GUI API documentation

Version: alpha

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

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

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

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

EXAMPLES

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

gui.cancel_spine()

gui.cancel_spine(node)

PARAMETERS

gui.clone()

gui.clone(node)

Make a clone instance of a node. This function does not clone the supplied node's children nodes. Use gui.clone_tree for that purpose.

PARAMETERS

RETURNS

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

RETURNS

gui.delete_node()

gui.delete_node(node)

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

PARAMETERS

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

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_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

RETURNS

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

RETURNS

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

RETURNS

gui.get_clipping_mode()

gui.get_clipping_mode(node)

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

PARAMETERS

RETURNS

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

RETURNS

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:

PARAMETERS

RETURNS

gui.get_fill_angle()

gui.get_fill_angle(node)

Returns the sector angle of a pie node.

PARAMETERS

RETURNS

gui.get_flipbook()

gui.get_flipbook(node)

Get node flipbook animation.

PARAMETERS

RETURNS

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

RETURNS

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

RETURNS

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

RETURNS

gui.get_height()

gui.get_height()

Returns the scene height.

PARAMETERS

RETURNS

gui.get_id()

gui.get_id(node)

Retrieves the id of the specified node.

PARAMETERS

RETURNS

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. 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

RETURNS

EXAMPLES

Compare the index order of two 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)

PARAMETERS

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

RETURNS

gui.get_layer()

gui.get_layer(node)

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

PARAMETERS

RETURNS

gui.get_layout()

gui.get_layout()

PARAMETERS

RETURNS

gui.get_leading()

gui.get_leading(node)

Returns the leading value for a text node.

PARAMETERS

RETURNS

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

RETURNS

gui.get_node()

gui.get_node(id)

Retrieves the node with the specified id.

PARAMETERS

RETURNS

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

RETURNS

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

RETURNS

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

RETURNS

gui.get_particlefx()

gui.get_particlefx(node)

Get the paricle fx for a gui node

PARAMETERS

RETURNS

gui.get_perimeter_vertices()

gui.get_perimeter_vertices(node)

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

PARAMETERS

RETURNS

gui.get_pivot()

gui.get_pivot(node)

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

PARAMETERS

RETURNS

gui.get_position()

gui.get_position(node)

Returns the position of the supplied node.

PARAMETERS

RETURNS

gui.get_rotation()

gui.get_rotation(node)

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

PARAMETERS

RETURNS

gui.get_scale()

gui.get_scale(node)

Returns the scale of the supplied node.

PARAMETERS

RETURNS

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

RETURNS

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

RETURNS

gui.get_size()

gui.get_size(node)

Returns the size of the supplied node.

PARAMETERS

RETURNS

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. Spine, Particle fx and Text nodes will ignore any size mode setting.

PARAMETERS

RETURNS

gui.get_slice9()

gui.get_slice9(node)

Returns the slice9 configuration values for the node.

PARAMETERS

RETURNS

gui.get_spine_animation()

gui.get_spine_animation(node)

Gets the playing animation on a spine node

PARAMETERS

RETURNS

gui.get_spine_bone()

gui.get_spine_bone(node,bone_id)

The returned node can be used for parenting and transform queries. This function has complexity O(n), where n is the number of bones in the spine model skeleton.

PARAMETERS

RETURNS

gui.get_spine_cursor()

gui.get_spine_cursor(node)

This is only useful for spine nodes. Gets the normalized cursor of the animation on a spine node.

PARAMETERS

RETURNS

gui.get_spine_playback_rate()

gui.get_spine_playback_rate(node)

This is only useful for spine nodes. Gets the playback rate of the animation on a spine node.

PARAMETERS

RETURNS

gui.get_spine_scene()

gui.get_spine_scene(node)

Returns the spine scene id of the supplied node. This is currently only useful for spine nodes. The returned spine scene must be mapped to the gui scene in the gui editor.

PARAMETERS

RETURNS

gui.get_spine_skin()

gui.get_spine_skin(node)

Gets the spine skin of a spine node

PARAMETERS

RETURNS

gui.get_text()

gui.get_text(node)

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

PARAMETERS

RETURNS

gui.get_text_metrics()

gui.get_text_metrics(font,text,width,line_break,leading,tracking)

Get text metrics given the provided font, text and parameters.

PARAMETERS

RETURNS

gui.get_text_metrics_from_node()

gui.get_text_metrics_from_node(node)

Get the text metrics from a text node.

PARAMETERS

RETURNS

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

RETURNS

gui.get_tracking()

gui.get_tracking(node)

Returns the tracking value of a text node.

PARAMETERS

RETURNS

gui.get_width()

gui.get_width()

Returns the scene width.

PARAMETERS

RETURNS

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

RETURNS

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

RETURNS

gui.hide_keyboard()

gui.hide_keyboard()

Hides the on-display touch keyboard on the device.

PARAMETERS

gui.is_enabled()

gui.is_enabled(node)

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

RETURNS

gui.move_above()

gui.move_above(node,node)

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

gui.move_below()

gui.move_below(node,node)

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

gui.new_box_node()

gui.new_box_node(pos,size)

Dynamically create a new box node.

PARAMETERS

RETURNS

gui.new_particlefx_node()

gui.new_particlefx_node(pos,particlefx)

Dynamically create a particle fx node.

PARAMETERS

RETURNS

gui.new_pie_node()

gui.new_pie_node(pos,size)

Dynamically create a new pie node.

PARAMETERS

RETURNS

gui.new_spine_node()

gui.new_spine_node(pos,spine_scene)

Dynamically create a new spine node.

PARAMETERS

RETURNS

gui.new_text_node()

gui.new_text_node(pos,text)

Dynamically create a new text node.

PARAMETERS

RETURNS

gui.new_texture()

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

Dynamically create a new texture.

PARAMETERS

RETURNS

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.
     if gui.new_texture("orange_tx", w, h, "rgb", string.rep(orange, w * h)) 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...
         ...
     end
end

gui.pick_node()

gui.pick_node(node,x,y)

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

PARAMETERS

RETURNS

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

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

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.play_spine_anim()

gui.play_spine_anim(node,animation_id,playback,[play_properties],[complete_function])

Starts a spine animation.

PARAMETERS

gui.reset_keyboard()

gui.reset_keyboard()

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

PARAMETERS

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

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

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

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

gui.set_clipping_mode()

gui.set_clipping_mode(node,clipping_mode)

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

PARAMETERS

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

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:

PARAMETERS

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

gui.set_fill_angle()

gui.set_fill_angle(node,angle)

Set the sector angle of a pie node.

PARAMETERS

gui.set_flipbook_cursor()

gui.set_flipbook_cursor(node,cursor)

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

PARAMETERS

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

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

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

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)

PARAMETERS

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

gui.set_layer()

gui.set_layer(node,layer)

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

PARAMETERS

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

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

gui.set_outer_bounds()

gui.set_outer_bounds(node,bounds_mode)

Sets the outer bounds mode for a pie node.

PARAMETERS

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

gui.set_parent()

gui.set_parent(node,parent,keep_scene_transform)

Sets the parent node of the specified node.

PARAMETERS

gui.set_particlefx()

gui.set_particlefx(node,particlefx)

Set the paricle fx for a gui node

PARAMETERS

gui.set_perimeter_vertices()

gui.set_perimeter_vertices(node,vertices)

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

PARAMETERS

gui.set_pivot()

gui.set_pivot(node,pivot)

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

PARAMETERS

gui.set_position()

gui.set_position(node,position)

Sets the position of the supplied node.

PARAMETERS

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

gui.set_rotation()

gui.set_rotation(node,rotation)

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

PARAMETERS

gui.set_scale()

gui.set_scale(node,scale)

Sets the scaling of the supplied node.

PARAMETERS

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

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

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. Spine, Particle fx and Text nodes will ignore any size mode setting.

PARAMETERS

gui.set_slice9()

gui.set_slice9(node,values)

Set the slice9 configuration values for the node.

PARAMETERS

gui.set_spine_cursor()

gui.set_spine_cursor(node,cursor)

This is only useful for spine nodes. The cursor is normalized.

PARAMETERS

gui.set_spine_playback_rate()

gui.set_spine_playback_rate(node,playback_rate)

This is only useful for spine nodes. Sets the playback rate of the animation on a spine node. Must be positive.

PARAMETERS

gui.set_spine_scene()

gui.set_spine_scene(node,spine_scene)

Set the spine scene on a spine node. The spine scene must be mapped to the gui scene in the gui editor.

PARAMETERS

gui.set_spine_skin()

gui.set_spine_skin(node,spine_skin,[spine_slot])

Sets the spine skin on a spine node.

PARAMETERS

EXAMPLES

Change skin of a Spine node

function init(self)
  gui.set_spine_skin(gui.get_node("spine_node"), "monster")
end

Change only part of the Spine to a different skin.

function monster_transform_arm(self)
  -- The player is transforming into a monster, begin with changing the arm.
  gui.set_spine_skin(gui.get_node("spine_node"), "monster", "left_arm_slot")
end

gui.set_text()

gui.set_text(node,text)

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

PARAMETERS

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

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

RETURNS

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

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

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

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

gui.stop_particlefx()

gui.stop_particlefx(node)

Stops the particle fx for a gui node

PARAMETERS

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

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:

Touch input table:

PARAMETERS

RETURNS

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

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

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

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

fit adjust mode

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

stretch adjust mode

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

zoom adjust mode

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.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_FILL_ANGLE

fill_angle property

gui.PROP_INNER_RADIUS

inner_radius 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.SIZE_MODE_AUTO

automatic size mode

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

gui.SIZE_MODE_MANUAL

manual size mode

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

Messages

layout_changed

reports a layout change

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

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

material

The material used when rendering the gui. The type of the property is hash.

hash gui material

EXAMPLES

How to set material using a script property (see resource.material)

go.property("my_material", resource.material("/material.material"))

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