GUI and GUIEX – ShiVa Engine


All ShiVa editor modules are open source. If you want to create your own modules, you are welcome to look through our own code and base your own work on ours. But wait! Our modules are written using an in-house (yet) undocumented API called GUIEX (GUI Extended) which is based on the public GUI API, but comes with a number of important differences you need to know about.

Common library

The GUIEX library can be found at and imported from the Common package at ShiVa Editor\Modules\com.shiva.editor.common. It consists of several XML and Lua scripts, but it’s easiest if you just include the main XML:

<!-- COMMON -->
<depend module="com.shiva.editor.common" />
<include file="/com.shiva.editor.common/guiexAPI.xml"/>

The Lua scripts automatically included through this XML extend the GUI API with lots of common shorthands, editor controls, file system functions and a lot more. It also changes how some established mechanisms work compared to the pure GUI API, like sending signals from XML components to Lua event handlers, but more on that later.


Among other things, GUIEX offers a function library for common ShiVa workflows that Lua by default does not include. For instance, lots of number controls come in pairs: scale x/y, position x/y, offset x/y, and so forth, so it makes sense to implement a Vector2 function that reads these two values directly from a component:

local x, y = guiex.getVector2Value ( gui.getComponentFromView ( hView, "section.selection.component.single.background.uvoffset", "Vector2" ) )

The equivalent GUI-only call would make you:
– get the resource from the view
– validate the resource
– get the component for X
– get the component for Y
– get the value for X
– get the value for Y
Merging everything into a single line makes the code more robust and easier to handle.


The standard GUI API asks you to create every UI component as an object, like this checkbox:

<checkBox id="optionCheckManual" textAlignment="left|vCenter" hSizePolicy="fixed" fixedWidth="50"/>

By contrast, every UI object in GUIEX is already defined and only needs to be instatiated from a template in the common library:

<instantiate id="optionCheckInstantiate" template="PropertyControlCheckBox" library="com.shiva.editor.common.lib" />

The full list of controls that can be instantiated can be found under com.shiva.editor.common\library.xml.

Event sending

GUIEX als changes the way events are sent. You already know that a standard forward call for the checkbox to optionCheckManual looks like this:

<connect sender="optionCheckManual" event="kEventCheckBoxStateChanged" handler="onOptionCheckChangedManual" />

However, the equivalent GUIEX call requires an extra parameter, like so:

<connect sender="optionCheckInstantiate, CheckBox" event="kEventCheckBoxStateChanged" handler="onOptionCheckChangedInstantiate" />


It is very tempting to just look at our own ShiVa modules, copy chunks of the code and use it as a basis for your own work. And while you are allowed to do that, you must know that GUIEX is a private API which, at the time of writing, is still evolving and not frozen. That means your modules that work with one release of ShiVa might not work with a newer or older one.
Furthermore, GUIEX is not documented (yet) sine it changes all the time. To understand what every function does, how the instantiated UI elements work and how event handling is changed, you would need to read through the library files in the Common library.
We recommend sticking to the official and documented GUI API if you plan on redistributing or selling your own Editor Modules. It is the only API that guarantees stability from one release to another.

Need more answers?

  • slackBanner