Tutorial – UI

Genome2D offers a specific component and classes for UI rendering. This rendering pipeline is designed as a sub-component rendering tree and is not composed of nodes. This design decision is based on use-cases for UI rendering which are specific and need to be handled and optimized in a different way to nodes.

To start working with UI in Genome2D we need to explain classes that you are going to use so lets start.

GUI
com.genome2d.components.renderable.ui.GUI

This is the component that will handle all your UI rendering, it is attached to a specific node where the complete UI will be rendered. The node can be used to position the UI and keep in mind that there is no limit to having multiple nodes with different UIs. This component is not different from any other Genome2D component and can be created or attached to any GNode instance, UI however doesn’t support rotation so it will not inherit node rotation information either.

// Attach component to existing node
node.addComponent(GUI);

// Create a node with GUI component
var uiInstance:GUI = GNode.createWithComponent(GUI);

 

GUISkin
com.genome2d.ui.skin.GUISkin

GUISkin is a class you will probably not encounter at all, it is a super class for all UI skins inside Genome2D. Skins are used to specify rendering of UI elements. All skins need to have unique ID provided since they are always referenced by skin manager and can be looked up at any time (similarly to GTexture instances).

 

GUITextureSkin
com.genome2d.ui.skin.GUITextureSkin

GUITextureSkin class is used to render a texture within an element.

Constructor takes ID as a parameter as well as a texture instance used for the skin. There is an optional parameter autosize which tells the element if it can go below the actual size of the texture so if set to false (true by default) it will try to size the element to the be at minimum the size of the texture itself. Final argument in the constructor is option and used only internally (may be removed).

// Create GUITextureSkin instance
var textureSkin:GUITextureSkin = new GUITextureSkin("skinId", GTextureManager.getTexture("someTexture"), true);

There are additional properties that can be used to further modify the rendering of the skin.

red, green, blue, alpha
These are pretty self-explanatory as they are used within Genome2D on various other renderables and are used to multiply the actual color of the rendered object.

scaleX, scaleY
This is used to override the rendered texture scaling independently of the actual UI element.

rotation
Used to rotate the rendered texture, this is purely rendering override and will have no effect on the element sizing or layout itself.

tiled
Specifies the rendering of the texture during scaling which can either scale or tile the texture to the final size.

sliceLeft, sliceRight, sliceTop, sliceBottom
Specifies 9-slicing (or any kind of slicing actually) of the texture. These argumens will specify left/right and top/bottom bounds of the middle slice.

Example if we have a texture of the size 30 by 30 and specify sliceLeft 10 sliceRight 20 sliceTop 10 sliceBottom 20 it tells the renderer that the rectangle in the middle of size 10 by 10 will be the scaled one. Viz picture:
symbol_guides

However this approach offers other combinations as well, for example if you specify the slices in previous scenario using sliceLeft 10 sliceRight 20 sliceTop 0 sliceBottom 30 it will become just 3 slicing. Or sliceLeft 15 sliceRight 30 sliceTop 15 sliceBottom 30 it will become 4 slicing.

What you need to keep in mind is that the rectangle specified using the slice parameters will be the rectangle that will be scaled, the rectangle to the left/right will be scaled only vertically, the rectangles on top/bottom will be scaled only horizontally and finally the rectangles in the corners will not be scaled at all.

 

GUIFontSkin
com.genome2d.ui.skin.GUIFontSkin

GUIFontSkin class is used to render a text within an element.

Constructor takes ID as a parameter as well as font instance used for the skin. There is an optional parameter fontScale which can basically override size of the font as well as an optional autosize parameter which tells the element to size with the size of the text bound to it.Final argument in the constructor is option and used only internally (may be removed).

// Create GUIFontSkin instance
var fontSkin:GUIFontSkin = new GUIFontSkin("skinId", GFontManager.getTexture("someFont"), 1, true);

There are additional properties that can be used to further modify the rendering of the skin.

red, green, blue, alpha, color
These are pretty self-explanatory as they are used within Genome2D on various other renderables and are used to multiply the actual color of the rendered object.

vAlign,h Align
Specify vertical and horizontal aligning of the text.

format
Specify the formatting of the text, currently limited functionality but can be used for example to render multicolored text within single skin.

 

GUIElement
com.genome2d.ui.element.GUIElement

This is the bread and butter of UI rendering tree, the whole UI hierarchy is composed of GUIElement instances. Currently there are no other classes that can be added to the UI tree but nothing stops you from extending GUIElement and making for example compoud selfcontained elements. GUI component creates the root GUI element automatically so all your elements will be added to it.

GUIElement constructor takes skin as a parameter which tells the element what it actually renders, element can be used without skin for example if it is utilized just as a container.

// Create GUIElement instance
var element:GUIElement = new GUIElement(skinInstance);

There are additional properties that can be used to further modify the rendering of the element and layout.

anchorLeft, anchorRight, anchorTop, anchorBottom

Specifies the anchoring of the element, default values are 0.5.

If horizontal or vertical anchor values are different aka anchorLeft != anchorRight or anchorTop != anchorBottom this specifies scaling and you can anchor the sides of the element to the sides of the parent element. This is useful for fluid layouts and especially for multi resolution development where the UI will scale according to available screen space. Values are normalized 0-1 where 0 is left/top of the parent element and 1 is right/bottom of the parent element.

Lets say we want to specify that our element will always take 1/2 width of the parent element starting at 1/4 position and at the same take the whole height of the parent. We specify it accordingly:

anchorLeft = 0.25 – we start at 1/4 position of the horizontal space allocated by parent element
anchorRight = 0.75 – we want the element to take 1/2 of the horizotnal space so we added .5 to anchorLeft
anchorTop = 0 – we want the element to start at the absolute top
anchorBottom = 1 – again absolute bottom as our element needs to take the whole height of the parent

If anchor values are the same it will not specify scaling of the element but rather its positioning and different properties come to place. For example if we specify anchorLeft at 0.3 and anchorRight at 0.3 it will position the whole element at 30% of horizontal space.

left,right,top,bottom

These properties are used for absolute offseting of our anchored element, where anchorLeft/Right/Top/Bottom were normalized and relative values these are absolute values to fine tune the anchoring of the corners where absolute values are needed.

Lets say we want our element to take the whole width of the parent element but first 10 pixels of it. This would be hard to achieve using anchorLeft which is relative to the actual width of the parent. We can simply put the anchorLeft at 0 and then specify left as 10 this means the left side of our element will start at the beginning of the parent element and offseted by 10 pixels.

You can also use negative values if you want to size the element outside of the parent. This combination of relative anchoring and absolute offseting offers pretty much unlimited options for any layout you can encounter.

anchorX, anchorY

This only makes sense and may be used only when different anchoring is not in place aka when anchorLeft != anchorRight or anchorTop != anchorBottom. You can ofcourse anchor top/bottom and leave left/right unanchored or vice-versa.

These properties are used to offset the position of the element.

preferredWidth, preferredHeight

This only makes sense and may be used only when different anchoring is not in place aka when anchorLeft != anchorRight or anchorTop != anchorBottom. You can ofcourse anchor top/bottom and leave left/right unanchored or vice-versa.

This parameter is used to specify an actual width/height for an element, otherwise element may be sized according to skin autosize settings.

pivotX, pivotY

This only makes sense and may be used only when different anchoring is not in place aka when anchorLeft != anchorRight or anchorTop != anchorBottom. You can ofcourse anchor top/bottom and leave left/right unanchored or vice-versa.

Specifies the pivoting of the element.

setModel

This method is used to bind model to the element. The argument is dynamic as it may be handled in various different formats. The most common one is String. This then propagates to the skin and is handled accordingly, the most common usecase is for text rendering.

setAnchor

Helper method to specify the most common anchoring combinations in one single call. Integer value that ranges from 1 to 9 if you imagine the element as a defalt 9 slice the values represent the rectangles from left to right.

setAnchor(1) will specify the anchoring to top-left so anchorLeft 0 anchorRight 0 anchorTop 0 anchorBottom 0 whereas setAnchor(9) will specify the anchoring to bottom right anchorLeft 1 anchorRight 1 anchorTop 1 anchorBottom 1