UI Submodule API

Cave Engine provides, in the editor only, the cave.ui submodule for you to create your own custom tools.

Be aware that it will not work if you attempt to use this in game!

ui.DebugTab

In order to use the UI Submodule API, you first need to create your own custom Tab by making a class that inherits and implements the ui.DebugTab. I've written a detailed documentation on how to do it at Editor Only API > Writting your own Tools, so consider reading it first.

Variables

The DebugTab only have one variable: the active. If True, the Tab will be rendered and displayed to the user. If not, it will be hidden and the engine user will have to enable it back by using the Tools menu in the top left corner of the Editor.

active : bool

Methods

Just like the variables, the DebugTab only have one method: the draw(). It's a virtual method intended for you to overwrite in order to draw your own UI to the Editor's screen.

draw()

---

UI Functions

After creating your own ui.DebugTab, everything you'll do regarding UI will be using one of those functions below.

ui.prop(...)

In order to display variables in the UI, you'll need to use the cave.ui.prop function. It receives the prop name and also its current value and returns the updated one. Example on how to use it:

self.myProp = cave.ui.prop("My Prop", self.myProp)

And here is the API for reference:

cave.ui.prop(name: str, value: int) -> int
cave.ui.prop(name: str, value: float) -> float
cave.ui.prop(name: str, value: bool) -> bool
cave.ui.prop(name: str, value: cave.Vector2) -> cave.Vector2
cave.ui.prop(name: str, value: cave.Vector3) -> cave.Vector3
cave.ui.prop(name: str, value: str) -> str

ui.propSlider(...)

Just like the cave.ui.prop, you can use the cave.ui.propSlider if you want to display the property with a slider, ranging from [valueMin to valueMax]. Here is the API for reference:

cave.ui.propSlider(name: str, value: int, valueMin: float, valueMax: float) -> int
cave.ui.propSlider(name: str, value: float, valueMin: float, valueMax: float) -> float
cave.ui.propSlider(name: str, value: cave.Vector2, valueMin: float, valueMax: float) -> cave.Vector2
cave.ui.propSlider(name: str, value: cave.Vector3, valueMin: float, valueMax: float) -> cave.Vector3

ui.button(...)

If you want you can also add buttons to your UI. They are simple and straight forward and will return True if the user clicks in it. Example:

if cave.ui.button("Click Me!"):
    print("Thank you for clicking me!")

And here is the API for reference:

cave.ui.button(name: str) -> bool

Tree Nodes

You can also create a Tree Node structure in your UI. If the node is open, the treeNodeStart will return True. In this case (and only in this case), you must call the treeNodeEnd. Tree Nodes can be nested. Here is an usage example:

if cave.ui.treeNodeStart("Node Example"):
    cave.ui.text("Hello, world!")

    # Must be called:
    cave.ui.treeNodeEnd()

And here is the API for reference:

cave.ui.treeNodeStart(name: str) -> bool
cave.ui.treeNodeEnd()

---

Various UI Functions

The cave.ui.header works just like the Tree Node, except that you don't need to end this one.

cave.ui.header(name: str) -> bool

The cave.ui.separator() will add a horizontal separator line in your UI. Good for organization.

cave.ui.separator()

If you need to display some raw texts in the UI, you can do it by calling this funciton:

cave.ui.text(name: str)