GUI API documentation

Version: alpha

FUNCTIONS
final() called when a gui component is finalized
gui.animate() animates a node property
gui.cancel_animation() cancels an ongoing animation
gui.cancel_flipbook() cancel a node flipbook animation
gui.clone() clone a node
gui.clone_tree() clone a node including its children
gui.delete_node() deletes a node
gui.delete_texture() delete texture
gui.get() gets the named property of a specified gui node
gui.get_adjust_mode() gets the node adjust mode
gui.get_alpha() gets the node alpha
gui.get_blend_mode() gets the node blend mode
gui.get_clipping_inverted() gets node clipping inverted state
gui.get_clipping_mode() gets the node clipping mode
gui.get_clipping_visible() gets node clipping visibility state
gui.get_color() gets the node color
gui.get_euler() gets the node rotation
gui.get_fill_angle() gets the angle for the filled pie sector
gui.get_flipbook() gets the node flipbook animation
gui.get_flipbook_cursor() gets the normalized cursor of the animation on a node with flipbook animation
gui.get_flipbook_playback_rate() gets the playback rate of the flipbook animation on a node
gui.get_font() gets the node font
gui.get_font_resource() gets the node font resource
gui.get_height() gets the scene height
gui.get_id() gets the id of the specified node
gui.get_index() gets the index of the specified node
gui.get_inherit_alpha() gets the node inherit alpha state
gui.get_inner_radius() gets the pie inner radius
gui.get_layer() gets the node layer
gui.get_layout() gets the scene current layout
gui.get_leading() gets the leading of the text node
gui.get_line_break() get line-break mode
gui.get_material() gets the assigned node material
gui.get_node() gets the node with the specified id
gui.get_outer_bounds() gets the pie outer bounds mode
gui.get_outline() gets the node outline color
gui.get_parent() gets the parent of the specified node
gui.get_particlefx() Gets a particle fx
gui.get_perimeter_vertices() gets the number of generated vertices around the perimeter
gui.get_pivot() gets the pivot of a node
gui.get_position() gets the node position
gui.get_rotation() gets the node rotation
gui.get_scale() gets the node scale
gui.get_screen_position() gets the node screen position
gui.get_shadow() gets the node shadow color
gui.get_size() gets the node size
gui.get_size_mode() gets the node size mode
gui.get_slice9() get the slice9 values for the node
gui.get_text() gets the node text
gui.get_texture() gets node texture
gui.get_tracking() gets the tracking of the text node
gui.get_tree() get a node including its children
gui.get_visible() returns if a node is visible or not
gui.get_width() gets the scene width
gui.get_xanchor() gets the x-anchor of a node
gui.get_yanchor() gets the y-anchor of a node
gui.hide_keyboard() hides on-display keyboard if available
gui.is_enabled() returns if a node is enabled or not
gui.move_above() moves the first node above the second
gui.move_below() moves the first node below the second
gui.new_box_node() creates a new box node
gui.new_particlefx_node() creates a new particle fx node
gui.new_pie_node() creates a new pie node
gui.new_text_node() creates a new text node
gui.new_texture() create new texture
gui.pick_node() determines if the node is pickable by the supplied coordinates
gui.play_flipbook() play node flipbook animation
gui.play_particlefx() Plays a particle fx
gui.reset_keyboard() resets on-display keyboard if available
gui.reset_material() resets the node material
gui.reset_nodes() resets all nodes to initial state
gui.screen_to_local() convert screen position to the local node position
gui.set() sets the named property of a specified gui node
gui.set_adjust_mode() sets node adjust mode
gui.set_alpha() sets the node alpha
gui.set_blend_mode() sets node blend mode
gui.set_clipping_inverted() sets node clipping inversion
gui.set_clipping_mode() sets node clipping mode state
gui.set_clipping_visible() sets node clipping visibility
gui.set_color() sets the node color
gui.set_enabled() enables/disables a node
gui.set_euler() sets the node rotation
gui.set_fill_angle() sets the angle for the filled pie sector
gui.set_flipbook_cursor() sets the normalized cursor of the animation on a node with flipbook animation
gui.set_flipbook_playback_rate() sets the playback rate of the flipbook animation on a node
gui.set_font() sets the node font
gui.set_id() sets the id of the specified node
gui.set_inherit_alpha() sets the node inherit alpha state
gui.set_inner_radius() sets the pie inner radius
gui.set_layer() sets the node layer
gui.set_leading() sets the leading of the text node
gui.set_line_break() set line-break mode
gui.set_material() sets the node material
gui.set_outer_bounds() sets the pie node outer bounds mode
gui.set_outline() sets the node outline color
gui.set_parent() sets the parent of the node
gui.set_particlefx() Sets a particle fx
gui.set_perimeter_vertices() sets the number of generated vertices around the perimeter
gui.set_pivot() sets the pivot of a node
gui.set_position() sets the node position
gui.set_render_order() sets the render ordering for the current GUI scene
gui.set_rotation() sets the node rotation
gui.set_scale() sets the node scale
gui.set_screen_position() sets screen position to the node
gui.set_shadow() sets the node shadow color
gui.set_size() sets the node size
gui.set_size_mode() sets node size mode
gui.set_slice9() set the slice9 configuration for the node
gui.set_text() sets the node text
gui.set_texture() sets the node texture
gui.set_texture_data() set the buffer data for a texture
gui.set_tracking() sets the tracking of the text node
gui.set_visible() set visibility for a node
gui.set_xanchor() sets the x-anchor of a node
gui.set_yanchor() sets the y-anchor of a node
gui.show_keyboard() shows the on-display keyboard if available
gui.stop_particlefx() Stops a particle fx
init() called when a gui component is initialized
on_input() called when user input is received
on_message() called when a message has been sent to the gui component
on_reload() called when the gui script is reloaded
update() called every frame to update the gui component
CONSTANTS
gui.ADJUST_FIT fit adjust mode
gui.ADJUST_STRETCH stretch adjust mode
gui.ADJUST_ZOOM zoom adjust mode
gui.ANCHOR_BOTTOM bottom y-anchor
gui.ANCHOR_LEFT left x-anchor
gui.ANCHOR_NONE no anchor
gui.ANCHOR_RIGHT right x-anchor
gui.ANCHOR_TOP top y-anchor
gui.BLEND_ADD additive blending
gui.BLEND_ADD_ALPHA additive alpha blending
gui.BLEND_ALPHA alpha blending
gui.BLEND_MULT multiply blending
gui.BLEND_SCREEN screen blending
gui.CLIPPING_MODE_NONE clipping mode none
gui.CLIPPING_MODE_STENCIL clipping mode stencil
gui.EASING_INBACK in-back
gui.EASING_INBOUNCE in-bounce
gui.EASING_INCIRC in-circlic
gui.EASING_INCUBIC in-cubic
gui.EASING_INELASTIC in-elastic
gui.EASING_INEXPO in-exponential
gui.EASING_INOUTBACK in-out-back
gui.EASING_INOUTBOUNCE in-out-bounce
gui.EASING_INOUTCIRC in-out-circlic
gui.EASING_INOUTCUBIC in-out-cubic
gui.EASING_INOUTELASTIC in-out-elastic
gui.EASING_INOUTEXPO in-out-exponential
gui.EASING_INOUTQUAD in-out-quadratic
gui.EASING_INOUTQUART in-out-quartic
gui.EASING_INOUTQUINT in-out-quintic
gui.EASING_INOUTSINE in-out-sine
gui.EASING_INQUAD in-quadratic
gui.EASING_INQUART in-quartic
gui.EASING_INQUINT in-quintic
gui.EASING_INSINE in-sine
gui.EASING_LINEAR linear interpolation
gui.EASING_OUTBACK out-back
gui.EASING_OUTBOUNCE out-bounce
gui.EASING_OUTCIRC out-circlic
gui.EASING_OUTCUBIC out-cubic
gui.EASING_OUTELASTIC out-elastic
gui.EASING_OUTEXPO out-exponential
gui.EASING_OUTINBACK out-in-back
gui.EASING_OUTINBOUNCE out-in-bounce
gui.EASING_OUTINCIRC out-in-circlic
gui.EASING_OUTINCUBIC out-in-cubic
gui.EASING_OUTINELASTIC out-in-elastic
gui.EASING_OUTINEXPO out-in-exponential
gui.EASING_OUTINQUAD out-in-quadratic
gui.EASING_OUTINQUART out-in-quartic
gui.EASING_OUTINQUINT out-in-quintic
gui.EASING_OUTINSINE out-in-sine
gui.EASING_OUTQUAD out-quadratic
gui.EASING_OUTQUART out-quartic
gui.EASING_OUTQUINT out-quintic
gui.EASING_OUTSINE out-sine
gui.KEYBOARD_TYPE_DEFAULT default keyboard
gui.KEYBOARD_TYPE_EMAIL email keyboard
gui.KEYBOARD_TYPE_NUMBER_PAD number input keyboard
gui.KEYBOARD_TYPE_PASSWORD password keyboard
gui.PIEBOUNDS_ELLIPSE elliptical pie node bounds
gui.PIEBOUNDS_RECTANGLE rectangular pie node bounds
gui.PIVOT_CENTER center pivot
gui.PIVOT_E east pivot
gui.PIVOT_N north pivot
gui.PIVOT_NE north-east pivot
gui.PIVOT_NW north-west pivot
gui.PIVOT_S south pivot
gui.PIVOT_SE south-east pivot
gui.PIVOT_SW south-west pivot
gui.PIVOT_W west pivot
gui.PLAYBACK_LOOP_BACKWARD loop backward
gui.PLAYBACK_LOOP_FORWARD loop forward
gui.PLAYBACK_LOOP_PINGPONG ping pong loop
gui.PLAYBACK_ONCE_BACKWARD once backward
gui.PLAYBACK_ONCE_FORWARD once forward
gui.PLAYBACK_ONCE_PINGPONG once forward and then backward
gui.PROP_COLOR color property
gui.PROP_EULER euler property
gui.PROP_FILL_ANGLE fill_angle property
gui.PROP_INNER_RADIUS inner_radius property
gui.PROP_LEADING leading property
gui.PROP_OUTLINE outline color property
gui.PROP_POSITION position property
gui.PROP_ROTATION rotation property
gui.PROP_SCALE scale property
gui.PROP_SHADOW shadow color property
gui.PROP_SIZE size property
gui.PROP_SLICE9 slice9 property
gui.PROP_TRACKING tracking property
gui.RESULT_DATA_ERROR data error
gui.RESULT_OUT_OF_RESOURCES out of resource
gui.RESULT_TEXTURE_ALREADY_EXISTS texture already exists
gui.SIZE_MODE_AUTO automatic size mode
gui.SIZE_MODE_MANUAL manual size mode
MESSAGES
layout_changed reports a layout change
PROPERTIES
fonts hash gui fonts
material hash gui material
materials hash gui materials
textures hash gui textures

Functions

final()

final(self)

This is a callback-function, which is called by the engine when a gui component is finalized (destroyed). It can be used to e.g. take some last action, report the finalization to other game object instances or release user input focus (see release_input_focus). There is no use in starting any animations or similar from this function since the gui component is about to be destroyed.

PARAMETERS

self object reference to the script state to be used for storing data

EXAMPLES

function final(self)
    -- report finalization
    msg.post("my_friend_instance", "im_dead", {my_stats = self.some_value})
end

gui.animate()

gui.animate(node,property,to,easing,duration,[delay],[complete_function],[playback])

This starts an animation of a node property according to the specified parameters. If the node property is already being animated, that animation will be canceled and replaced by the new one. Note however that several different node properties can be animated simultaneously. Use gui.cancel_animation to stop the animation before it has completed. Composite properties of type vector3, vector4 or quaternion also expose their sub-components (x, y, z and w). You can address the components individually by suffixing the name with a dot '.' and the name of the component. For instance, "position.x" (the position x coordinate) or "color.w" (the color alpha value). If a complete_function (Lua function) is specified, that function will be called when the animation has completed. By starting a new animation in that function, several animations can be sequenced together. See the examples below for more information.

PARAMETERS

node node node to animate
property string, constant property to animate
  • "position"
  • "rotation"
  • "euler"
  • "scale"
  • "color"
  • "outline"
  • "shadow"
  • "size"
  • "fill_angle" (pie)
  • "inner_radius" (pie)
  • "leading" (text)
  • "tracking" (text)
  • "slice9" (slice9)
The following property constants are defined equaling the corresponding property string names.
  • gui.PROP_POSITION
  • gui.PROP_ROTATION
  • gui.PROP_EULER
  • gui.PROP_SCALE
  • gui.PROP_COLOR
  • gui.PROP_OUTLINE
  • gui.PROP_SHADOW
  • gui.PROP_SIZE
  • gui.PROP_FILL_ANGLE
  • gui.PROP_INNER_RADIUS
  • gui.PROP_LEADING
  • gui.PROP_TRACKING
  • gui.PROP_SLICE9
to number, vector3, vector4, quaternion target property value
easing constant, vector easing to use during animation. Either specify one of the gui.EASING_* constants or provide a vector with a custom curve. See the animation guide for more information.
duration number duration of the animation in seconds.
[delay] number delay before the animation starts in seconds.
[complete_function] function(self, node) function to call when the animation has completed
[playback] constant playback mode
  • gui.PLAYBACK_ONCE_FORWARD
  • gui.PLAYBACK_ONCE_BACKWARD
  • gui.PLAYBACK_ONCE_PINGPONG
  • gui.PLAYBACK_LOOP_FORWARD
  • gui.PLAYBACK_LOOP_BACKWARD
  • gui.PLAYBACK_LOOP_PINGPONG

EXAMPLES

How to start a simple color animation, where the node fades in to white during 0.5 seconds:
gui.set_color(node, vmath.vector4(0, 0, 0, 0)) -- node is fully transparent
gui.animate(node, gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), gui.EASING_INOUTQUAD, 0.5) -- start animation
How to start a sequenced animation where the node fades in to white during 0.5 seconds, stays visible for 2 seconds and then fades out:
local function on_animation_done(self, node)
    -- fade out node, but wait 2 seconds before the animation starts
    gui.animate(node, gui.PROP_COLOR, vmath.vector4(0, 0, 0, 0), gui.EASING_OUTQUAD, 0.5, 2.0)
end

function init(self)
    -- fetch the node we want to animate
    local my_node = gui.get_node("my_node")
    -- node is initially set to fully transparent
    gui.set_color(my_node, vmath.vector4(0, 0, 0, 0))
    -- animate the node immediately and call on_animation_done when the animation has completed
    gui.animate(my_node, gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), gui.EASING_INOUTQUAD, 0.5, 0.0, on_animation_done)
end
How to animate a node's y position using a crazy custom easing curve:
function init(self)
    local values = { 0, 0, 0, 0, 0, 0, 0, 0,
                     1, 1, 1, 1, 1, 1, 1, 1,
                     0, 0, 0, 0, 0, 0, 0, 0,
                     1, 1, 1, 1, 1, 1, 1, 1,
                     0, 0, 0, 0, 0, 0, 0, 0,
                     1, 1, 1, 1, 1, 1, 1, 1,
                     0, 0, 0, 0, 0, 0, 0, 0,
                     1, 1, 1, 1, 1, 1, 1, 1 }
    local vec = vmath.vector(values)
    local node = gui.get_node("box")
    gui.animate(node, "position.y", 100, vec, 4.0, 0, nil, gui.PLAYBACK_LOOP_PINGPONG)
end

gui.cancel_animation()

gui.cancel_animation(node,property)

If an animation of the specified node is currently running (started by gui.animate), it will immediately be canceled.

PARAMETERS

node node node that should have its animation canceled
property string, constant property for which the animation should be canceled
  • "position"
  • "rotation"
  • "euler"
  • "scale"
  • "color"
  • "outline"
  • "shadow"
  • "size"
  • "fill_angle" (pie)
  • "inner_radius" (pie)
  • "leading" (text)
  • "tracking" (text)
  • "slice9" (slice9)

EXAMPLES

Start an animation of the position property of a node, then cancel parts of the animation:
local node = gui.get_node("my_node")
-- animate to new position
local pos = vmath.vector3(100, 100, 0)
gui.animate(node, "position", pos, go.EASING_LINEAR, 2)
...
-- cancel animation of the x component.
gui.cancel_animation(node, "position.x")

gui.cancel_flipbook()

gui.cancel_flipbook(node)

Cancels any running flipbook animation on the specified node.

PARAMETERS

node node node cancel flipbook animation for

EXAMPLES

local node = gui.get_node("anim_node")
gui.cancel_flipbook(node)

gui.clone()

gui.clone(node)

Make a clone instance of a node. The cloned node will be identical to the original node, except the id which is generated as the string "node" plus a sequential unsigned integer value. This function does not clone the supplied node's children nodes. Use gui.clone_tree for that purpose.

PARAMETERS

node node node to clone

RETURNS

clone node the cloned node

gui.clone_tree()

gui.clone_tree(node)

Make a clone instance of a node and all its children. Use gui.clone to clone a node excluding its children.

PARAMETERS

node node root node to clone

RETURNS

clones table a table mapping node ids to the corresponding cloned nodes

gui.delete_node()

gui.delete_node(node)

Deletes the specified node. Any child nodes of the specified node will be recursively deleted.

PARAMETERS

node node node to delete

EXAMPLES

Delete a particular node and any child nodes it might have:
local node = gui.get_node("my_node")
gui.delete_node(node)

gui.delete_texture()

gui.delete_texture(texture)

Delete a dynamically created texture.

PARAMETERS

texture string, hash texture id

EXAMPLES

function init(self)
     -- Create a texture.
     if gui.new_texture("temp_tx", 10, 10, "rgb", string.rep('\0', 10 * 10 * 3)) then
         -- Do something with the texture.
         ...

         -- Delete the texture
         gui.delete_texture("temp_tx")
     end
end

gui.get()

gui.get(node,property,[options])

Instead of using specific getters such as gui.get_position or gui.get_scale, you can use gui.get instead and supply the property as a string or a hash. While this function is similar to go.get, there are a few more restrictions when operating in the gui namespace. Most notably, only these explicitly named properties are supported:

  • "position"
  • "rotation"
  • "euler"
  • "scale"
  • "color"
  • "outline"
  • "shadow"
  • "size"
  • "fill_angle" (pie)
  • "inner_radius" (pie)
  • "leading" (text)
  • "tracking" (text)
  • "slice9" (slice9)
The value returned will either be a vmath.vector4 or a single number, i.e getting the "position" property will return a vec4 while getting the "position.x" property will return a single value. You can also use this function to get material constants.

PARAMETERS

node node node to get the property for
property string, hash, constant the property to retrieve
[options] table optional options table (only applicable for material constants) - index integer index into array property (1 based)

EXAMPLES

Get properties on existing nodes:
local node = gui.get_node("my_box_node")
local node_position = gui.get(node, "position")

gui.get_adjust_mode()

gui.get_adjust_mode(node)

Returns the adjust mode of a node. The adjust mode defines how the node will adjust itself to screen resolutions that differs from the one in the project settings.

PARAMETERS

node node node from which to get the adjust mode (node)

RETURNS

adjust_mode constant the current adjust mode
  • gui.ADJUST_FIT
  • gui.ADJUST_ZOOM
  • gui.ADJUST_STRETCH

gui.get_alpha()

gui.get_alpha(node)

gets the node alpha

PARAMETERS

node node node from which to get alpha

RETURNS

alpha number alpha

gui.get_blend_mode()

gui.get_blend_mode(node)

Returns the blend mode of a node. Blend mode defines how the node will be blended with the background.

PARAMETERS

node node node from which to get the blend mode

RETURNS

blend_mode constant blend mode
  • gui.BLEND_ALPHA
  • gui.BLEND_ADD
  • gui.BLEND_ADD_ALPHA
  • gui.BLEND_MULT
  • gui.BLEND_SCREEN

gui.get_clipping_inverted()

gui.get_clipping_inverted(node)

If node is set as an inverted clipping node, it will clip anything inside as opposed to outside.

PARAMETERS

node node node from which to get the clipping inverted state

RETURNS

inverted boolean true or false

gui.get_clipping_mode()

gui.get_clipping_mode(node)

Clipping mode defines how the node will clip it's children nodes

PARAMETERS

node node node from which to get the clipping mode

RETURNS

clipping_mode constant clipping mode
  • gui.CLIPPING_MODE_NONE
  • gui.CLIPPING_MODE_STENCIL

gui.get_clipping_visible()

gui.get_clipping_visible(node)

If node is set as visible clipping node, it will be shown as well as clipping. Otherwise, it will only clip but not show visually.

PARAMETERS

node node node from which to get the clipping visibility state

RETURNS

visible boolean true or false

gui.get_color()

gui.get_color(node)

Returns the color of the supplied node. The components of the returned vector4 contains the color channel values:

Component Color value
x Red value
y Green value
z Blue value
w Alpha value

PARAMETERS

node node node to get the color from

RETURNS

color vector4 node color

gui.get_euler()

gui.get_euler(node)

Returns the rotation of the supplied node. The rotation is expressed in degree Euler angles.

PARAMETERS

node node node to get the rotation from

RETURNS

rotation vector3 node rotation

gui.get_fill_angle()

gui.get_fill_angle(node)

Returns the sector angle of a pie node.

PARAMETERS

node node node from which to get the fill angle

RETURNS

angle number sector angle

gui.get_flipbook()

gui.get_flipbook(node)

Get node flipbook animation.

PARAMETERS

node node node to get flipbook animation from

RETURNS

animation hash animation id

gui.get_flipbook_cursor()

gui.get_flipbook_cursor(node)

This is only useful nodes with flipbook animations. Gets the normalized cursor of the flipbook animation on a node.

PARAMETERS

node node node to get the cursor for (node)

RETURNS

cursor number cursor value

gui.get_flipbook_playback_rate()

gui.get_flipbook_playback_rate(node)

This is only useful nodes with flipbook animations. Gets the playback rate of the flipbook animation on a node.

PARAMETERS

node node node to set the cursor for

RETURNS

rate number playback rate

gui.get_font()

gui.get_font(node)

This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.

PARAMETERS

node node node from which to get the font

RETURNS

font hash font id

gui.get_font_resource()

gui.get_font_resource(font_name)

This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.

PARAMETERS

font_name hash, string font of which to get the path hash

RETURNS

hash hash path hash to resource

EXAMPLES

Get the text metrics for a text
function init(self)
  local node = gui.get_node("name")
  local font_name = gui.get_font(node)
  local font = gui.get_font_resource(font_name)
  local metrics = resource.get_text_metrics(font, "The quick brown fox\n jumps over the lazy dog")
end

gui.get_height()

gui.get_height()

Returns the scene height.

PARAMETERS

None

RETURNS

height number scene height

gui.get_id()

gui.get_id(node)

Retrieves the id of the specified node.

PARAMETERS

node node the node to retrieve the id from

RETURNS

id hash the id of the node

EXAMPLES

Gets the id of a node:
local node = gui.get_node("my_node")

local id = gui.get_id(node)
print(id) --> hash: [my_node]

gui.get_index()

gui.get_index(node)

Retrieve the index of the specified node among its siblings. The index defines the order in which a node appear in a GUI scene. Higher index means the node is drawn on top of lower indexed nodes.

PARAMETERS

node node the node to retrieve the id from

RETURNS

index number the index of the node

EXAMPLES

Compare the index order of two sibling nodes:
local node1 = gui.get_node("my_node_1")
local node2 = gui.get_node("my_node_2")

if gui.get_index(node1) < gui.get_index(node2) then
    -- node1 is drawn below node2
else
    -- node2 is drawn below node1
end

gui.get_inherit_alpha()

gui.get_inherit_alpha(node)

gets the node inherit alpha state

PARAMETERS

node node node from which to get the inherit alpha state

RETURNS

inherit_alpha boolean true or false

gui.get_inner_radius()

gui.get_inner_radius(node)

Returns the inner radius of a pie node. The radius is defined along the x-axis.

PARAMETERS

node node node from where to get the inner radius

RETURNS

radius number inner radius

gui.get_layer()

gui.get_layer(node)

The layer must be mapped to the gui scene in the gui editor.

PARAMETERS

node node node from which to get the layer

RETURNS

layer hash layer id

gui.get_layout()

gui.get_layout()

gets the scene current layout

PARAMETERS

None

RETURNS

layout hash layout id

gui.get_leading()

gui.get_leading(node)

Returns the leading value for a text node.

PARAMETERS

node node node from where to get the leading

RETURNS

leading number leading scaling value (default=1)

gui.get_line_break()

gui.get_line_break(node)

Returns whether a text node is in line-break mode or not. This is only useful for text nodes.

PARAMETERS

node node node from which to get the line-break for

RETURNS

line_break boolean true or false

gui.get_material()

gui.get_material(node)

Returns the material of a node. The material must be mapped to the gui scene in the gui editor.

PARAMETERS

node node node to get the material for

RETURNS

materal hash material id

EXAMPLES

Getting the material for a node, and assign it to another node:
local node1 = gui.get_node("my_node")
local node2 = gui.get_node("other_node")
local node1_material = gui.get_material(node1)
gui.set_material(node2, node1_material)

gui.get_node()

gui.get_node(id)

Retrieves the node with the specified id.

PARAMETERS

id string, hash id of the node to retrieve

RETURNS

instance node a new node instance

EXAMPLES

Gets a node by id and change its color:
local node = gui.get_node("my_node")
local red = vmath.vector4(1.0, 0.0, 0.0, 1.0)
gui.set_color(node, red)

gui.get_outer_bounds()

gui.get_outer_bounds(node)

Returns the outer bounds mode for a pie node.

PARAMETERS

node node node from where to get the outer bounds mode

RETURNS

bounds_mode constant the outer bounds mode of the pie node:
  • gui.PIEBOUNDS_RECTANGLE
  • gui.PIEBOUNDS_ELLIPSE

gui.get_outline()

gui.get_outline(node)

Returns the outline color of the supplied node. See gui.get_color for info how vectors encode color values.

PARAMETERS

node node node to get the outline color from

RETURNS

color vector4 outline color

gui.get_parent()

gui.get_parent(node)

Returns the parent node of the specified node. If the supplied node does not have a parent, nil is returned.

PARAMETERS

node node the node from which to retrieve its parent

RETURNS

parent node, nil parent instance or nil

gui.get_particlefx()

gui.get_particlefx(node)

Get the paricle fx for a gui node

PARAMETERS

node node node to get particle fx for

RETURNS

particlefx hash particle fx id

gui.get_perimeter_vertices()

gui.get_perimeter_vertices(node)

Returns the number of generated vertices around the perimeter of a pie node.

PARAMETERS

node node pie node

RETURNS

vertices number vertex count

gui.get_pivot()

gui.get_pivot(node)

The pivot specifies how the node is drawn and rotated from its position.

PARAMETERS

node node node to get pivot from

RETURNS

pivot constant pivot constant
  • gui.PIVOT_CENTER
  • gui.PIVOT_N
  • gui.PIVOT_NE
  • gui.PIVOT_E
  • gui.PIVOT_SE
  • gui.PIVOT_S
  • gui.PIVOT_SW
  • gui.PIVOT_W
  • gui.PIVOT_NW

gui.get_position()

gui.get_position(node)

Returns the position of the supplied node.

PARAMETERS

node node node to get the position from

RETURNS

position vector3 node position

gui.get_rotation()

gui.get_rotation(node)

Returns the rotation of the supplied node. The rotation is expressed as a quaternion

PARAMETERS

node node node to get the rotation from

RETURNS

rotation quaternion node rotation

gui.get_scale()

gui.get_scale(node)

Returns the scale of the supplied node.

PARAMETERS

node node node to get the scale from

RETURNS

scale vector3 node scale

gui.get_screen_position()

gui.get_screen_position(node)

Returns the screen position of the supplied node. This function returns the calculated transformed position of the node, taking into account any parent node transforms.

PARAMETERS

node node node to get the screen position from

RETURNS

position vector3 node screen position

gui.get_shadow()

gui.get_shadow(node)

Returns the shadow color of the supplied node. See gui.get_color for info how vectors encode color values.

PARAMETERS

node node node to get the shadow color from

RETURNS

color vector4 node shadow color

gui.get_size()

gui.get_size(node)

Returns the size of the supplied node.

PARAMETERS

node node node to get the size from

RETURNS

size vector3 node size

gui.get_size_mode()

gui.get_size_mode(node)

Returns the size of a node. The size mode defines how the node will adjust itself in size. Automatic size mode alters the node size based on the node's content. Automatic size mode works for Box nodes and Pie nodes which will both adjust their size to match the assigned image. Particle fx and Text nodes will ignore any size mode setting.

PARAMETERS

node node node from which to get the size mode (node)

RETURNS

size_mode constant the current size mode
  • gui.SIZE_MODE_MANUAL
  • gui.SIZE_MODE_AUTO

gui.get_slice9()

gui.get_slice9(node)

Returns the slice9 configuration values for the node.

PARAMETERS

node node node to manipulate

RETURNS

values vector4 configuration values

gui.get_text()

gui.get_text(node)

Returns the text value of a text node. This is only useful for text nodes.

PARAMETERS

node node node from which to get the text

RETURNS

text string text value

gui.get_texture()

gui.get_texture(node)

Returns the texture of a node. This is currently only useful for box or pie nodes. The texture must be mapped to the gui scene in the gui editor.

PARAMETERS

node node node to get texture from

RETURNS

texture hash texture id

gui.get_tracking()

gui.get_tracking(node)

Returns the tracking value of a text node.

PARAMETERS

node node node from where to get the tracking

RETURNS

tracking number tracking scaling number (default=0)

gui.get_tree()

gui.get_tree(node)

Get a node and all its children as a Lua table.

PARAMETERS

node node root node to get node tree from

RETURNS

clones table a table mapping node ids to the corresponding nodes

gui.get_visible()

gui.get_visible(node)

Returns true if a node is visible and false if it's not. Invisible nodes are not rendered.

PARAMETERS

node node node to query

RETURNS

visible boolean whether the node is visible or not

gui.get_width()

gui.get_width()

Returns the scene width.

PARAMETERS

None

RETURNS

width number scene width

gui.get_xanchor()

gui.get_xanchor(node)

The x-anchor specifies how the node is moved when the game is run in a different resolution.

PARAMETERS

node node node to get x-anchor from

RETURNS

anchor constant anchor constant
  • gui.ANCHOR_NONE
  • gui.ANCHOR_LEFT
  • gui.ANCHOR_RIGHT

gui.get_yanchor()

gui.get_yanchor(node)

The y-anchor specifies how the node is moved when the game is run in a different resolution.

PARAMETERS

node node node to get y-anchor from

RETURNS

anchor constant anchor constant
  • gui.ANCHOR_NONE
  • gui.ANCHOR_TOP
  • gui.ANCHOR_BOTTOM

gui.hide_keyboard()

gui.hide_keyboard()

Hides the on-display touch keyboard on the device.

PARAMETERS

None


gui.is_enabled()

gui.is_enabled(node,[recursive])

Returns true if a node is enabled and false if it's not. Disabled nodes are not rendered and animations acting on them are not evaluated.

PARAMETERS

node node node to query
[recursive] boolean check hierarchy recursively

RETURNS

enabled boolean whether the node is enabled or not

gui.move_above()

gui.move_above(node,reference)

Alters the ordering of the two supplied nodes by moving the first node above the second. If the second argument is nil the first node is moved to the top.

PARAMETERS

node node to move
reference node, nil reference node above which the first node should be moved

gui.move_below()

gui.move_below(node,reference)

Alters the ordering of the two supplied nodes by moving the first node below the second. If the second argument is nil the first node is moved to the bottom.

PARAMETERS

node node to move
reference node, nil reference node below which the first node should be moved

gui.new_box_node()

gui.new_box_node(pos,size)

Dynamically create a new box node.

PARAMETERS

pos vector3, vector4 node position
size vector3 node size

RETURNS

node node new box node

gui.new_particlefx_node()

gui.new_particlefx_node(pos,particlefx)

Dynamically create a particle fx node.

PARAMETERS

pos vector3, vector4 node position
particlefx hash, string particle fx resource name

RETURNS

node node new particle fx node

gui.new_pie_node()

gui.new_pie_node(pos,size)

Dynamically create a new pie node.

PARAMETERS

pos vector3, vector4 node position
size vector3 node size

RETURNS

node node new pie node

gui.new_text_node()

gui.new_text_node(pos,text)

Dynamically create a new text node.

PARAMETERS

pos vector3, vector4 node position
text string node text

RETURNS

node node new text node

gui.new_texture()

gui.new_texture(texture_id,width,height,type,buffer,flip)

Dynamically create a new texture.

PARAMETERS

texture_id string, hash texture id
width number texture width
height number texture height
type string, constant texture type
  • "rgb" - RGB
  • "rgba" - RGBA
  • "l" - LUMINANCE
buffer string texture data
flip boolean flip texture vertically

RETURNS

success boolean texture creation was successful
code number one of the gui.RESULT_* codes if unsuccessful

EXAMPLES

How to create a texture and apply it to a new box node:
function init(self)
     local w = 200
     local h = 300

     -- A nice orange. String with the RGB values.
     local orange = string.char(0xff) .. string.char(0x80) .. string.char(0x10)

     -- Create the texture. Repeat the color string for each pixel.
     local ok, reason = gui.new_texture("orange_tx", w, h, "rgb", string.rep(orange, w * h))
     if ok then
         -- Create a box node and apply the texture to it.
         local n = gui.new_box_node(vmath.vector3(200, 200, 0), vmath.vector3(w, h, 0))
         gui.set_texture(n, "orange_tx")
     else
         -- Could not create texture for some reason...
         if reason == gui.RESULT_TEXTURE_ALREADY_EXISTS then
             ...
         else
             ...
         end
     end
end

gui.pick_node()

gui.pick_node(node,x,y)

Tests whether a coordinate is within the bounding box of a node.

PARAMETERS

node node node to be tested for picking
x number x-coordinate (see on_input )
y number y-coordinate (see on_input )

RETURNS

pickable boolean pick result

gui.play_flipbook()

gui.play_flipbook(node,animation,[complete_function],[play_properties])

Play flipbook animation on a box or pie node. The current node texture must contain the animation. Use this function to set one-frame still images on the node.

PARAMETERS

node node node to set animation for
animation string, hash animation id
[complete_function] function(self, node) optional function to call when the animation has completed
self
object The current object.
node
node The node that is animated.
[play_properties] table optional table with properties
offset
number The normalized initial value of the animation cursor when the animation starts playing
playback_rate
number The rate with which the animation will be played. Must be positive

EXAMPLES

Set the texture of a node to a flipbook animation from an atlas:
local function anim_callback(self, node)
    -- Take action after animation has played.
end

function init(self)
    -- Create a new node and set the texture to a flipbook animation
    local node = gui.get_node("button_node")
    gui.set_texture(node, "gui_sprites")
    gui.play_flipbook(node, "animated_button")
end
Set the texture of a node to an image from an atlas:
-- Create a new node and set the texture to a "button.png" from atlas
local node = gui.get_node("button_node")
gui.set_texture(node, "gui_sprites")
gui.play_flipbook(node, "button")

gui.play_particlefx()

gui.play_particlefx(node,[emitter_state_function])

Plays the paricle fx for a gui node

PARAMETERS

node node node to play particle fx for
[emitter_state_function] function(self, node, emitter, state) optional callback function that will be called when an emitter attached to this particlefx changes state.
self
object The current object
node
hash The particle fx node, or nil if the node was deleted
emitter
hash The id of the emitter
state
constant the new state of the emitter:
  • particlefx.EMITTER_STATE_SLEEPING
  • particlefx.EMITTER_STATE_PRESPAWN
  • particlefx.EMITTER_STATE_SPAWNING
  • particlefx.EMITTER_STATE_POSTSPAWN

EXAMPLES

How to play a particle fx when a gui node is created. The callback receives the gui node, the hash of the id of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
local function emitter_state_change(self, node, emitter, state)
  if emitter == hash("exhaust") and state == particlefx.EMITTER_STATE_POSTSPAWN then
    -- exhaust is done spawning particles...
  end
end

function init(self)
    gui.play_particlefx(gui.get_node("particlefx"), emitter_state_change)
end

gui.reset_keyboard()

gui.reset_keyboard()

Resets the input context of keyboard. This will clear marked text.

PARAMETERS

None


gui.reset_material()

gui.reset_material(node)

Resets the node material to the material assigned in the gui scene.

PARAMETERS

node node node to reset the material for

EXAMPLES

Resetting the material for a node:
local node = gui.get_node("my_node")
gui.reset_material(node)

gui.reset_nodes()

gui.reset_nodes()

Resets all nodes in the current GUI scene to their initial state. The reset only applies to static node loaded from the scene. Nodes that are created dynamically from script are not affected.

PARAMETERS

None


gui.screen_to_local()

gui.screen_to_local(node,screen_position)

Convert the screen position to the local position of supplied node

PARAMETERS

node node node used for getting local transformation matrix
screen_position vector3 screen position

RETURNS

local_position vector3 local position

gui.set()

gui.set(node,property,value,[options])

Instead of using specific setteres such as gui.set_position or gui.set_scale, you can use gui.set instead and supply the property as a string or a hash. While this function is similar to go.get and go.set, there are a few more restrictions when operating in the gui namespace. Most notably, only these named properties identifiers are supported:

  • "position"
  • "rotation"
  • "euler"
  • "scale"
  • "color"
  • "outline"
  • "shadow"
  • "size"
  • "fill_angle" (pie)
  • "inner_radius" (pie)
  • "leading" (text)
  • "tracking" (text)
  • "slice9" (slice9)
The value to set must either be a vmath.vector4, vmath.vector3, vmath.quat or a single number and depends on the property name you want to set. I.e when setting the "position" property, you need to use a vmath.vector4 and when setting a single component of the property, such as "position.x", you need to use a single value. Note: When setting the rotation using the "rotation" property, you need to pass in a vmath.quat. This behaviour is different than from the gui.set_rotation function, the intention is to move new functionality closer to go namespace so that migrating between gui and go is easier. To set the rotation using degrees instead, use the "euler" property instead. The rotation and euler properties are linked, changing one of them will change the backing data of the other. Similar to go.set, you can also use gui.set for setting material constant values on a node. E.g if a material has specified a constant called tint in the .material file, you can use gui.set to set the value of that constant by calling gui.set(node, "tint", vmath.vec4(1,0,0,1)), or gui.set(node, "matrix", vmath.matrix4()) if the constant is a matrix. Arrays are also supported by gui.set - to set an array constant, you need to pass in an options table with the 'index' key set. If the material has a constant array called 'tint_array' specified in the material, you can use gui.set(node, "tint_array", vmath.vec4(1,0,0,1), { index = 4}) to set the fourth array element to a different value.

PARAMETERS

node node node to set the property for
property string, hash, constant the property to set
value number, vector4, vector3, quat the property to set
[options] table optional options table (only applicable for material constants) - index integer index into array property (1 based)

EXAMPLES

Updates the position property on an existing node:
local node = gui.get_node("my_box_node")
local node_position = gui.get(node, "position")
gui.set(node, "position.x", node_position.x + 128)
Updates the rotation property on an existing node:
local node = gui.get_node("my_box_node")
gui.set(node, "rotation", vmath.quat_rotation_z(math.rad(45)))
-- this is equivalent to:
gui.set(node, "euler.z", 45)
-- or using the entire vector:
gui.set(node, "euler", vmath.vector3(0,0,45))
-- or using the set_rotation
gui.set_rotation(node, vmath.vector3(0,0,45))
Sets various material constants for a node:
local node = gui.get_node("my_box_node")
gui.set(node, "tint", vmath.vector4(1,0,0,1))
-- matrix4 is also supported
gui.set(node, "light_matrix", vmath.matrix4())
-- update a constant in an array at position 4. the array is specified in the shader as:
-- uniform vec4 tint_array[4]; // lua is 1 based, shader is 0 based
gui.set(node, "tint_array", vmath.vector4(1,0,0,1), { index = 4 })
-- update a matrix constant in an array at position 4. the array is specified in the shader as:
-- uniform mat4 light_matrix_array[4];
gui.set(node, "light_matrix_array", vmath.matrix4(), { index = 4 })
-- update a sub-element in a constant
gui.set(node, "tint.x", 1)
-- update a sub-element in an array constant at position 4
gui.set(node, "tint_array.x", 1, {index = 4})

gui.set_adjust_mode()

gui.set_adjust_mode(node,adjust_mode)

Sets the adjust mode on a node. The adjust mode defines how the node will adjust itself to screen resolutions that differs from the one in the project settings.

PARAMETERS

node node node to set adjust mode for
adjust_mode constant adjust mode to set
  • gui.ADJUST_FIT
  • gui.ADJUST_ZOOM
  • gui.ADJUST_STRETCH

gui.set_alpha()

gui.set_alpha(node,alpha)

sets the node alpha

PARAMETERS

node node node for which to set alpha
alpha number 0..1 alpha color

gui.set_blend_mode()

gui.set_blend_mode(node,blend_mode)

Set the blend mode of a node. Blend mode defines how the node will be blended with the background.

PARAMETERS

node node node to set blend mode for
blend_mode constant blend mode to set
  • gui.BLEND_ALPHA
  • gui.BLEND_ADD
  • gui.BLEND_ADD_ALPHA
  • gui.BLEND_MULT
  • gui.BLEND_SCREEN

gui.set_clipping_inverted()

gui.set_clipping_inverted(node,inverted)

If node is set as an inverted clipping node, it will clip anything inside as opposed to outside.

PARAMETERS

node node node to set clipping inverted state for
inverted boolean true or false

gui.set_clipping_mode()

gui.set_clipping_mode(node,clipping_mode)

Clipping mode defines how the node will clip it's children nodes

PARAMETERS

node node node to set clipping mode for
clipping_mode constant clipping mode to set
  • gui.CLIPPING_MODE_NONE
  • gui.CLIPPING_MODE_STENCIL

gui.set_clipping_visible()

gui.set_clipping_visible(node,visible)

If node is set as an visible clipping node, it will be shown as well as clipping. Otherwise, it will only clip but not show visually.

PARAMETERS

node node node to set clipping visibility for
visible boolean true or false

gui.set_color()

gui.set_color(node,color)

Sets the color of the supplied node. The components of the supplied vector3 or vector4 should contain the color channel values:

Component Color value
x Red value
y Green value
z Blue value
w vector4 Alpha value

PARAMETERS

node node node to set the color for
color vector3, vector4 new color

gui.set_enabled()

gui.set_enabled(node,enabled)

Sets a node to the disabled or enabled state. Disabled nodes are not rendered and animations acting on them are not evaluated.

PARAMETERS

node node node to be enabled/disabled
enabled boolean whether the node should be enabled or not

gui.set_euler()

gui.set_euler(node,rotation)

Sets the rotation of the supplied node. The rotation is expressed in degree Euler angles.

PARAMETERS

node node node to set the rotation for
rotation vector3, vector4 new rotation

gui.set_fill_angle()

gui.set_fill_angle(node,angle)

Set the sector angle of a pie node.

PARAMETERS

node node node to set the fill angle for
angle number sector angle

gui.set_flipbook_cursor()

gui.set_flipbook_cursor(node,cursor)

This is only useful nodes with flipbook animations. The cursor is normalized.

PARAMETERS

node node node to set the cursor for
cursor number cursor value

gui.set_flipbook_playback_rate()

gui.set_flipbook_playback_rate(node,playback_rate)

This is only useful nodes with flipbook animations. Sets the playback rate of the flipbook animation on a node. Must be positive.

PARAMETERS

node node node to set the cursor for
playback_rate number playback rate

gui.set_font()

gui.set_font(node,font)

This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.

PARAMETERS

node node node for which to set the font
font string, hash font id

gui.set_id()

gui.set_id(node,id)

Set the id of the specicied node to a new value. Nodes created with the gui.new_*_node() functions get an empty id. This function allows you to give dynamically created nodes an id. No checking is done on the uniqueness of supplied ids. It is up to you to make sure you use unique ids.

PARAMETERS

node node node to set the id for
id string, hash id to set

EXAMPLES

Create a new node and set its id:
local pos = vmath.vector3(100, 100, 0)
local size = vmath.vector3(100, 100, 0)
local node = gui.new_box_node(pos, size)
gui.set_id(node, "my_new_node")

gui.set_inherit_alpha()

gui.set_inherit_alpha(node,inherit_alpha)

sets the node inherit alpha state

PARAMETERS

node node node from which to set the inherit alpha state
inherit_alpha boolean true or false

gui.set_inner_radius()

gui.set_inner_radius(node,radius)

Sets the inner radius of a pie node. The radius is defined along the x-axis.

PARAMETERS

node node node to set the inner radius for
radius number inner radius

gui.set_layer()

gui.set_layer(node,layer)

The layer must be mapped to the gui scene in the gui editor.

PARAMETERS

node node node for which to set the layer
layer string, hash layer id

gui.set_leading()

gui.set_leading(node,leading)

Sets the leading value for a text node. This value is used to scale the line spacing of text.

PARAMETERS

node node node for which to set the leading
leading number a scaling value for the line spacing (default=1)

gui.set_line_break()

gui.set_line_break(node,line_break)

Sets the line-break mode on a text node. This is only useful for text nodes.

PARAMETERS

node node node to set line-break for
line_break boolean true or false

gui.set_material()

gui.set_material(node,material)

Set the material on a node. The material must be mapped to the gui scene in the gui editor, and assigning a material is supported for all node types. To set the default material that is assigned to the gui scene node, use gui.reset_material(node_id) instead.

PARAMETERS

node node node to set material for
material string, hash material id

EXAMPLES

Assign an existing material to a node:
local node = gui.get_node("my_node")
gui.set_material(node, "my_material")

gui.set_outer_bounds()

gui.set_outer_bounds(node,bounds_mode)

Sets the outer bounds mode for a pie node.

PARAMETERS

node node node for which to set the outer bounds mode
bounds_mode constant the outer bounds mode of the pie node:
  • gui.PIEBOUNDS_RECTANGLE
  • gui.PIEBOUNDS_ELLIPSE

gui.set_outline()

gui.set_outline(node,color)

Sets the outline color of the supplied node. See gui.set_color for info how vectors encode color values.

PARAMETERS

node node node to set the outline color for
color vector3, vector4 new outline color

gui.set_parent()

gui.set_parent(node,[parent],[keep_scene_transform])

Sets the parent node of the specified node.

PARAMETERS

node node node for which to set its parent
[parent] node parent node to set, pass nil to remove parent
[keep_scene_transform] boolean optional flag to make the scene position being perserved

gui.set_particlefx()

gui.set_particlefx(node,particlefx)

Set the paricle fx for a gui node

PARAMETERS

node node node to set particle fx for
particlefx hash, string particle fx id

gui.set_perimeter_vertices()

gui.set_perimeter_vertices(node,vertices)

Sets the number of generated vertices around the perimeter of a pie node.

PARAMETERS

node node pie node
vertices number vertex count

gui.set_pivot()

gui.set_pivot(node,pivot)

The pivot specifies how the node is drawn and rotated from its position.

PARAMETERS

node node node to set pivot for
pivot constant pivot constant
  • gui.PIVOT_CENTER
  • gui.PIVOT_N
  • gui.PIVOT_NE
  • gui.PIVOT_E
  • gui.PIVOT_SE
  • gui.PIVOT_S
  • gui.PIVOT_SW
  • gui.PIVOT_W
  • gui.PIVOT_NW

gui.set_position()

gui.set_position(node,position)

Sets the position of the supplied node.

PARAMETERS

node node node to set the position for
position vector3, vector4 new position

gui.set_render_order()

gui.set_render_order(order)

Set the order number for the current GUI scene. The number dictates the sorting of the "gui" render predicate, in other words in which order the scene will be rendered in relation to other currently rendered GUI scenes. The number must be in the range 0 to 15.

PARAMETERS

order number rendering order (0-15)

gui.set_rotation()

gui.set_rotation(node,rotation)

Sets the rotation of the supplied node. The rotation is expressed as a quaternion

PARAMETERS

node node node to set the rotation for
rotation quaternion, vector4 new rotation

gui.set_scale()

gui.set_scale(node,scale)

Sets the scaling of the supplied node.

PARAMETERS

node node node to set the scale for
scale vector3, vector4 new scale

gui.set_screen_position()

gui.set_screen_position(node,screen_position)

Set the screen position to the supplied node

PARAMETERS

node node node to set the screen position to
screen_position vector3 screen position

gui.set_shadow()

gui.set_shadow(node,color)

Sets the shadow color of the supplied node. See gui.set_color for info how vectors encode color values.

PARAMETERS

node node node to set the shadow color for
color vector3, vector4 new shadow color

gui.set_size()

gui.set_size(node,size)

Sets the size of the supplied node. You can only set size on nodes with size mode set to SIZE_MODE_MANUAL

PARAMETERS

node node node to set the size for
size vector3, vector4 new size

gui.set_size_mode()

gui.set_size_mode(node,size_mode)

Sets the size mode of a node. The size mode defines how the node will adjust itself in size. Automatic size mode alters the node size based on the node's content. Automatic size mode works for Box nodes and Pie nodes which will both adjust their size to match the assigned image. Particle fx and Text nodes will ignore any size mode setting.

PARAMETERS

node node node to set size mode for
size_mode constant size mode to set
  • gui.SIZE_MODE_MANUAL
  • gui.SIZE_MODE_AUTO

gui.set_slice9()

gui.set_slice9(node,values)

Set the slice9 configuration values for the node.

PARAMETERS

node node node to manipulate
values vector4 new values

gui.set_text()

gui.set_text(node,text)

Set the text value of a text node. This is only useful for text nodes.

PARAMETERS

node node node to set text for
text string, number text to set

gui.set_texture()

gui.set_texture(node,texture)

Set the texture on a box or pie node. The texture must be mapped to the gui scene in the gui editor. The function points out which texture the node should render from. If the texture is an atlas, further information is needed to select which image/animation in the atlas to render. In such cases, use gui.play_flipbook() in addition to this function.

PARAMETERS

node node node to set texture for
texture string, hash texture id

EXAMPLES

To set a texture (or animation) from an atlas:
local node = gui.get_node("box_node")
gui.set_texture(node, "my_atlas")
gui.play_flipbook(node, "image")
Set a dynamically created texture to a node. Note that there is only one texture image in this case so gui.set_texture() is sufficient.
local w = 200
local h = 300
-- A nice orange. String with the RGB values.
local orange = string.char(0xff) .. string.char(0x80) .. string.char(0x10)
-- Create the texture. Repeat the color string for each pixel.
if gui.new_texture("orange_tx", w, h, "rgb", string.rep(orange, w * h)) then
    local node = gui.get_node("box_node")
    gui.set_texture(node, "orange_tx")
end

gui.set_texture_data()

gui.set_texture_data(texture,width,height,type,buffer,flip)

Set the texture buffer data for a dynamically created texture.

PARAMETERS

texture string, hash texture id
width number texture width
height number texture height
type string, constant texture type
  • "rgb" - RGB
  • "rgba" - RGBA
  • "l" - LUMINANCE
buffer string texture data
flip boolean flip texture vertically

RETURNS

success boolean setting the data was successful

EXAMPLES

function init(self)
     local w = 200
     local h = 300

     -- Create a dynamic texture, all white.
     if gui.new_texture("dynamic_tx", w, h, "rgb", string.rep(string.char(0xff), w * h * 3)) then
         -- Create a box node and apply the texture to it.
         local n = gui.new_box_node(vmath.vector3(200, 200, 0), vmath.vector3(w, h, 0))
         gui.set_texture(n, "dynamic_tx")

         ...

         -- Change the data in the texture to a nice orange.
         local orange = string.char(0xff) .. string.char(0x80) .. string.char(0x10)
         if gui.set_texture_data("dynamic_tx", w, h, "rgb", string.rep(orange, w * h)) then
             -- Go on and to more stuff
             ...
         end
     else
         -- Something went wrong
         ...
     end
end

gui.set_tracking()

gui.set_tracking(node,tracking)

Sets the tracking value of a text node. This value is used to adjust the vertical spacing of characters in the text.

PARAMETERS

node node node for which to set the tracking
tracking number a scaling number for the letter spacing (default=0)

gui.set_visible()

gui.set_visible(node,visible)

Set if a node should be visible or not. Only visible nodes are rendered.

PARAMETERS

node node node to be visible or not
visible boolean whether the node should be visible or not

gui.set_xanchor()

gui.set_xanchor(node,anchor)

The x-anchor specifies how the node is moved when the game is run in a different resolution.

PARAMETERS

node node node to set x-anchor for
anchor constant anchor constant
  • gui.ANCHOR_NONE
  • gui.ANCHOR_LEFT
  • gui.ANCHOR_RIGHT

gui.set_yanchor()

gui.set_yanchor(node,anchor)

The y-anchor specifies how the node is moved when the game is run in a different resolution.

PARAMETERS

node node node to set y-anchor for
anchor constant anchor constant
  • gui.ANCHOR_NONE
  • gui.ANCHOR_TOP
  • gui.ANCHOR_BOTTOM

gui.show_keyboard()

gui.show_keyboard(type,autoclose)

Shows the on-display touch keyboard. The specified type of keyboard is displayed if it is available on the device. This function is only available on iOS and Android. .

PARAMETERS

type constant keyboard type
  • gui.KEYBOARD_TYPE_DEFAULT
  • gui.KEYBOARD_TYPE_EMAIL
  • gui.KEYBOARD_TYPE_NUMBER_PAD
  • gui.KEYBOARD_TYPE_PASSWORD
autoclose boolean if the keyboard should automatically close when clicking outside

gui.stop_particlefx()

gui.stop_particlefx(node,[options])

Stops the particle fx for a gui node

PARAMETERS

node node node to stop particle fx for
[options] table options when stopping the particle fx. Supported options:
  • boolean clear: instantly clear spawned particles

init()

init(self)

This is a callback-function, which is called by the engine when a gui component is initialized. It can be used to set the initial state of the script and gui scene.

PARAMETERS

self object reference to the script state to be used for storing data

EXAMPLES

function init(self)
    -- set up useful data
    self.my_value = 1
end

on_input()

on_input(self,action_id,action)

This is a callback-function, which is called by the engine when user input is sent to the instance of the gui component. It can be used to take action on the input, e.g. modify the gui according to the input. For an instance to obtain user input, it must first acquire input focus through the message acquire_input_focus. Any instance that has obtained input will be put on top of an input stack. Input is sent to all listeners on the stack until the end of stack is reached, or a listener returns true to signal that it wants input to be consumed. See the documentation of acquire_input_focus for more information. The action parameter is a table containing data about the input mapped to the action_id. For mapped actions it specifies the value of the input and if it was just pressed or released. Actions are mapped to input in an input_binding-file. Mouse movement is specifically handled and uses nil as its action_id. The action only contains positional parameters in this case, such as x and y of the pointer. Here is a brief description of the available table fields:

Field Description
value The amount of input given by the user. This is usually 1 for buttons and 0-1 for analogue inputs. This is not present for mouse movement.
pressed If the input was pressed this frame. This is not present for mouse movement.
released If the input was released this frame. This is not present for mouse movement.
repeated If the input was repeated this frame. This is similar to how a key on a keyboard is repeated when you hold it down. This is not present for mouse movement.
x The x value of a pointer device, if present.
y The y value of a pointer device, if present.
screen_x The screen space x value of a pointer device, if present.
screen_y The screen space y value of a pointer device, if present.
dx The change in x value of a pointer device, if present.
dy The change in y value of a pointer device, if present.
screen_dx The change in screen space x value of a pointer device, if present.
screen_dy The change in screen space y value of a pointer device, if present.
gamepad The index of the gamepad device that provided the input.
touch List of touch input, one element per finger, if present. See table below about touch input
Touch input table:
Field Description
id A number identifying the touch input during its duration.
pressed True if the finger was pressed this frame.
released True if the finger was released this frame.
tap_count Number of taps, one for single, two for double-tap, etc
x The x touch location.
y The y touch location.
dx The change in x value.
dy The change in y value.
acc_x Accelerometer x value (if present).
acc_y Accelerometer y value (if present).
acc_z Accelerometer z value (if present).

PARAMETERS

self object reference to the script state to be used for storing data
action_id hash id of the received input action, as mapped in the input_binding-file
action table a table containing the input data, see above for a description

RETURNS

consume boolean, nil optional boolean to signal if the input should be consumed (not passed on to others) or not, default is false

EXAMPLES

function on_input(self, action_id, action)
    -- check for input
    if action_id == hash("my_action") then
        -- take appropritate action
        self.my_value = action.value
    end
    -- consume input
    return true
end

on_message()

on_message(self,message_id,message)

This is a callback-function, which is called by the engine whenever a message has been sent to the gui component. It can be used to take action on the message, e.g. update the gui or send a response back to the sender of the message. The message parameter is a table containing the message data. If the message is sent from the engine, the documentation of the message specifies which data is supplied. See the update function for examples on how to use this callback-function.

PARAMETERS

self object reference to the script state to be used for storing data
message_id hash id of the received message
message table a table containing the message data

on_reload()

on_reload(self)

This is a callback-function, which is called by the engine when the gui script is reloaded, e.g. from the editor. It can be used for live development, e.g. to tweak constants or set up the state properly for the script.

PARAMETERS

self object reference to the script state to be used for storing data

EXAMPLES

function on_reload(self)
    -- restore some color (or similar)
    gui.set_color(gui.get_node("my_node"), self.my_original_color)
end

update()

update(self,dt)

This is a callback-function, which is called by the engine every frame to update the state of a gui component. It can be used to perform any kind of gui related tasks, e.g. animating nodes.

PARAMETERS

self object reference to the script state to be used for storing data
dt number the time-step of the frame update

EXAMPLES

This example demonstrates how to update a text node that displays game score in a counting fashion. It is assumed that the gui component receives messages from the game when a new score is to be shown.
function init(self)
    -- fetch the score text node for later use (assumes it is called "score")
    self.score_node = gui.get_node("score")
    -- keep track of the current score counted up so far
    self.current_score = 0
    -- keep track of the target score we should count up to
    self.target_score = 0
    -- how fast we will update the score, in score/second
    self.score_update_speed = 1
end

function update(self, dt)
    -- check if target score is more than current score
    if self.current_score < self.target_score
        -- increment current score according to the speed
        self.current_score = self.current_score + dt * self.score_update_speed
        -- check if we went past the target score, clamp current score in that case
        if self.current_score > self.target_score then
            self.current_score = self.target_score
        end
        -- update the score text node
        gui.set_text(self.score_node, "" .. math.floor(self.current_score))
    end
end

function on_message(self, message_id, message, sender)
    -- check the message
    if message_id == hash("set_score") then
        self.target_score = message.score
    end
end

Constants

gui.ADJUST_FIT

Adjust mode is used when the screen resolution differs from the project settings. The fit mode ensures that the entire node is visible in the adjusted gui scene.


gui.ADJUST_STRETCH

Adjust mode is used when the screen resolution differs from the project settings. The stretch mode ensures that the node is displayed as is in the adjusted gui scene, which might scale it non-uniformally.


gui.ADJUST_ZOOM

Adjust mode is used when the screen resolution differs from the project settings. The zoom mode ensures that the node fills its entire area and might make the node exceed it.


gui.ANCHOR_BOTTOM

bottom y-anchor


gui.ANCHOR_LEFT

left x-anchor


gui.ANCHOR_NONE

no anchor


gui.ANCHOR_RIGHT

right x-anchor


gui.ANCHOR_TOP

top y-anchor


gui.BLEND_ADD

additive blending


gui.BLEND_ADD_ALPHA

additive alpha blending


gui.BLEND_ALPHA

alpha blending


gui.BLEND_MULT

multiply blending


gui.BLEND_SCREEN

screen blending


gui.CLIPPING_MODE_NONE

clipping mode none


gui.CLIPPING_MODE_STENCIL

clipping mode stencil


gui.EASING_INBACK

in-back


gui.EASING_INBOUNCE

in-bounce


gui.EASING_INCIRC

in-circlic


gui.EASING_INCUBIC

in-cubic


gui.EASING_INELASTIC

in-elastic


gui.EASING_INEXPO

in-exponential


gui.EASING_INOUTBACK

in-out-back


gui.EASING_INOUTBOUNCE

in-out-bounce


gui.EASING_INOUTCIRC

in-out-circlic


gui.EASING_INOUTCUBIC

in-out-cubic


gui.EASING_INOUTELASTIC

in-out-elastic


gui.EASING_INOUTEXPO

in-out-exponential


gui.EASING_INOUTQUAD

in-out-quadratic


gui.EASING_INOUTQUART

in-out-quartic


gui.EASING_INOUTQUINT

in-out-quintic


gui.EASING_INOUTSINE

in-out-sine


gui.EASING_INQUAD

in-quadratic


gui.EASING_INQUART

in-quartic


gui.EASING_INQUINT

in-quintic


gui.EASING_INSINE

in-sine


gui.EASING_LINEAR

linear interpolation


gui.EASING_OUTBACK

out-back


gui.EASING_OUTBOUNCE

out-bounce


gui.EASING_OUTCIRC

out-circlic


gui.EASING_OUTCUBIC

out-cubic


gui.EASING_OUTELASTIC

out-elastic


gui.EASING_OUTEXPO

out-exponential


gui.EASING_OUTINBACK

out-in-back


gui.EASING_OUTINBOUNCE

out-in-bounce


gui.EASING_OUTINCIRC

out-in-circlic


gui.EASING_OUTINCUBIC

out-in-cubic


gui.EASING_OUTINELASTIC

out-in-elastic


gui.EASING_OUTINEXPO

out-in-exponential


gui.EASING_OUTINQUAD

out-in-quadratic


gui.EASING_OUTINQUART

out-in-quartic


gui.EASING_OUTINQUINT

out-in-quintic


gui.EASING_OUTINSINE

out-in-sine


gui.EASING_OUTQUAD

out-quadratic


gui.EASING_OUTQUART

out-quartic


gui.EASING_OUTQUINT

out-quintic


gui.EASING_OUTSINE

out-sine


gui.KEYBOARD_TYPE_DEFAULT

default keyboard


gui.KEYBOARD_TYPE_EMAIL

email keyboard


gui.KEYBOARD_TYPE_NUMBER_PAD

number input keyboard


gui.KEYBOARD_TYPE_PASSWORD

password keyboard


gui.PIEBOUNDS_ELLIPSE

elliptical pie node bounds


gui.PIEBOUNDS_RECTANGLE

rectangular pie node bounds


gui.PIVOT_CENTER

center pivot


gui.PIVOT_E

east pivot


gui.PIVOT_N

north pivot


gui.PIVOT_NE

north-east pivot


gui.PIVOT_NW

north-west pivot


gui.PIVOT_S

south pivot


gui.PIVOT_SE

south-east pivot


gui.PIVOT_SW

south-west pivot


gui.PIVOT_W

west pivot


gui.PLAYBACK_LOOP_BACKWARD

loop backward


gui.PLAYBACK_LOOP_FORWARD

loop forward


gui.PLAYBACK_LOOP_PINGPONG

ping pong loop


gui.PLAYBACK_ONCE_BACKWARD

once backward


gui.PLAYBACK_ONCE_FORWARD

once forward


gui.PLAYBACK_ONCE_PINGPONG

once forward and then backward


gui.PROP_COLOR

color property


gui.PROP_EULER

euler property


gui.PROP_FILL_ANGLE

fill_angle property


gui.PROP_INNER_RADIUS

inner_radius property


gui.PROP_LEADING

leading property


gui.PROP_OUTLINE

outline color property


gui.PROP_POSITION

position property


gui.PROP_ROTATION

rotation property


gui.PROP_SCALE

scale property


gui.PROP_SHADOW

shadow color property


gui.PROP_SIZE

size property


gui.PROP_SLICE9

slice9 property


gui.PROP_TRACKING

tracking property


gui.RESULT_DATA_ERROR

The provided data is not in the expected format or is in some other way incorrect, for instance the image data provided to gui.new_texture().


gui.RESULT_OUT_OF_RESOURCES

The system is out of resources, for instance when trying to create a new texture using gui.new_texture().


gui.RESULT_TEXTURE_ALREADY_EXISTS

The texture id already exists when trying to use gui.new_texture().


gui.SIZE_MODE_AUTO

The size of the node is determined by the currently assigned texture.


gui.SIZE_MODE_MANUAL

The size of the node is determined by the size set in the editor, the constructor or by gui.set_size()


Messages

layout_changed

This message is broadcast to every GUI component when a layout change has been initiated on device.

id hash the id of the layout the engine is changing to
previous_id hash the id of the layout the engine is changing from

EXAMPLES

function on_message(self, message_id, message, sender)
   if message_id == hash("layout_changed") and message.id == hash("Landscape") then
       -- switching layout to "Landscape"...
       ...
   end
end

Properties

fonts

The fonts used in the gui. The type of the property is hash. Key must be specified in options table.

EXAMPLES

How to set font using a script property (see resource.font)
go.property("title_latin", resource.font("/open_sans.font"))
go.property("title_cyrillic", resource.font("/open_sans_cyrillic.font"))

function init(self)
  go.set("#gui", "fonts", self.title_cyrillic, {key = "title"})
end

material

The main material (the default material assigned to a GUI) used when rendering the gui. The type of the property is hash.

EXAMPLES

How to set material using a script property (see resource.material)
go.property("desaturate_material", resource.material("/desaturate.material"))

function init(self)
  go.set("#gui", "material", self.desaturate_material)
end

materials

The materials used when rendering the gui. The type of the property is hash. Key must be specified in options table.

EXAMPLES

How to change a named material resource using a script property from a script
go.property("my_material", resource.material("/my_material.material"))

function init(self)
  -- this will update the "my_gui_material" entry in the GUI to use the material
  -- specified in the "my_material" script property.
  go.set("#gui", "materials", self.my_material, { key = "my_gui_material" })
end

textures

The textures used in the gui. The type of the property is hash. Key must be specified in options table.

EXAMPLES

How to set texture using a script property (see resource.atlas)
go.property("cards_red", resource.atlas("/cards_red.atlas"))
go.property("cards_blue", resource.atlas("/cards_blue.atlas"))

function init(self)
  go.set("#gui", "textures", self.cards_red, {key = "cards"})
end