Welcome!

You are just one step away from creating awesome games!

Sign up with Google

You need a Google account to use Defold

- Select ref document -

GUI API documentation

version 1.2.107

GUI core hooks, functions, messages, properties and constants for creation and manipulation of GUI nodes. The "gui" namespace is accessible only from gui scripts.

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

cancel a spine 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_adjust_mode

gets the node adjust mode

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_fill_angle

gets the angle for the filled pie sector

gui.get_flipbook

gets the node flipbook animation

gui.get_font

gets the node font

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

gets the number of generarted 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_spine_bone

retrieve the GUI node corresponding to a spine skeleton bone

gui.get_spine_cursor

gets the normalized cursor of the animation on a spine node

gui.get_spine_playback_rate

gets the playback rate of the animation on a spine node

gui.get_spine_scene

gets the spine scene of a node

gui.get_spine_skin

gets the skin of a spine node

gui.get_text

gets the node text

gui.get_text_metrics

get text metrics

gui.get_text_metrics_from_node

get text metrics from node

gui.get_texture

gets node texture

gui.get_tracking

gets the tracking of the text node

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_pie_node

creates a new pie node

gui.new_spine_node

creates a new spine 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_spine_anim

play a spine animation

gui.reset_keyboard

resets on-display keyboard if available

gui.reset_nodes

resets all nodes to initial state

gui.set_adjust_mode

sets node adjust mode

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_fill_angle

sets the angle for the filled pie sector

gui.set_font

sets the node font

gui.set_id

sets the id of the specified node

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

sets the normalized cursor of the animation on a spine node

gui.set_spine_playback_rate

sets the playback rate of the animation on a spine node

gui.set_spine_scene

sets the spine scene of a node

gui.set_spine_skin

sets the spine skin

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

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

Messages

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

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

gui.SIZE_MODE_MANUAL

manual size mode

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

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"
  • "scale"
  • "color"
  • "outline"
  • "shadow"
  • "size"
  • "fill_angle" (pie)
  • "inner_radius" (pie)
  • "slice9" (slice9)

The following property constants are defined equaling the corresponding property string names.

  • gui.PROP_POSITION
  • gui.PROP_ROTATION
  • 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_SLICE9
to

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

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
node

node node to animate

property

string | constant property to animate

  • "position"
  • "rotation"
  • "scale"
  • "color"
  • "outline"
  • "shadow"
  • "size"
  • "fill_angle" (pie)
  • "inner_radius" (pie)
  • "slice9" (slice9)

The following property constants are defined equaling the corresponding property string names.

  • gui.PROP_POSITION
  • gui.PROP_ROTATION
  • 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_SLICE9
to

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

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"
  • "scale"
  • "color"
  • "outline"
  • "shadow"
  • "size"
  • "fill_angle" (pie)
  • "inner_radius" (pie)
  • "slice9" (slice9)
node

node node that should have its animation canceled

property

string | constant property for which the animation should be canceled

  • "position"
  • "rotation"
  • "scale"
  • "color"
  • "outline"
  • "shadow"
  • "size"
  • "fill_angle" (pie)
  • "inner_radius" (pie)
  • "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

node

node node cancel flipbook animation for

Examples

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

gui.cancel_spine

gui.cancel_spine(node)

Parameters

node

node spine node that should cancel its animation

node

node spine node that should cancel its animation

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

node

node node to clone

node

node node to clone

Returns

clone

node the cloned node

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

node

node root node to clone

Returns

clones

table a table mapping node ids to the corresponding cloned nodes

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

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

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

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
adjust_mode

constant the current adjust mode

  • gui.ADJUST_FIT
  • gui.ADJUST_ZOOM
  • gui.ADJUST_STRETCH

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

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
blend_mode

constant blend mode

  • gui.BLEND_ALPHA
  • gui.BLEND_ADD
  • gui.BLEND_ADD_ALPHA
  • gui.BLEND_MULT

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

node

node node from which to get the clipping inverted state

Returns

inverted

boolean true or false

inverted

boolean true or false

gui.get_clipping_mode

gui.get_clipping_mode(node)

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

Parameters

node

node node from which to get the clipping mode

node

node node from which to get the clipping mode

Returns

clipping_mode

constant clipping mode

  • gui.CLIPPING_MODE_NONE
  • gui.CLIPPING_MODE_STENCIL

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

node

node node from which to get the clipping visibility state

Returns

visible

boolean true or false

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

node

node node to get the color from

Returns

color

vector4 node color

color

vector4 node color

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

node

node node from which to get the fill angle

Returns

angle

number sector angle

angle

number sector angle

gui.get_flipbook

gui.get_flipbook(node)

Get node flipbook animation.

Parameters

node

node node to get flipbook animation from

node

node node to get flipbook animation from

Returns

animation

hash animation id

animation

hash animation id

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

node

node node from which to get the font

Returns

font

hash font id

font

hash font id

gui.get_height

gui.get_height()

Returns the scene height.

Returns

height

number scene height

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

node

node the node to retrieve the id from

Returns

id

hash the id of the node

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

node

node the node to retrieve the id from

Returns

index

number the index of the node

index

number the index of the node

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

node

node node from where to get the inner radius

Returns

radius

number inner radius

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

node

node node from which to get the layer

Returns

layer

hash layer id

layer

hash layer id

gui.get_layout

gui.get_layout()

Returns

layout

hash layout id

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

node

node node from where to get the leading

Returns

leading

number leading scaling value (default=1)

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

node

node node from which to get the line-break for

Returns

line-break

boolean true or false

line-break

boolean true or false

gui.get_node

gui.get_node(id)

Retrieves the node with the specified id.

Parameters

id

string | hash id of the node to retrieve

id

string | hash id of the node to retrieve

Returns

instance

node a new node instance

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

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

node

node node to get the outline color from

Returns

color

vector4 outline color

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

node

node the node from which to retrieve its parent

Returns

parent

node parent instance or nil

parent

node parent instance or nil

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

node

node pie node

Returns

vertices

number vertex count

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

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

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

node

node node to get the position from

Returns

position

vector3 node position

position

vector3 node position

gui.get_rotation

gui.get_rotation(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

node

node node to get the rotation from

Returns

rotation

vector3 node rotation

rotation

vector3 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

node

node node to get the scale from

Returns

scale

vector3 node scale

scale

vector3 node scale

gui.get_screen_position

gui.get_screen_position(node)

Returns the screen position of the supplied node.

Parameters

node

node node to get the screen position from

node

node node to get the screen position from

Returns

position

vector3 node screen position

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

node

node node to get the shadow color from

Returns

color

vector4 node shadow color

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

node

node node to get the size from

Returns

size

vector3 node size

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.

Parameters

node

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

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

node

node node to manipulate

Returns

values

vector4 configuration values

values

vector4 configuration values

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

node

node spine node to query for bone node

bone_id

string | hash id of the corresponding bone

node

node spine node to query for bone node

bone_id

string | hash id of the corresponding bone

Returns

bone

node node corresponding to the spine bone

bone

node node corresponding to the spine bone

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

node

spine node to set the cursor for (node)

node

spine node to set the cursor for (node)

Returns

cursor

value (number)

cursor

value (number)

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

node

node spine node to set the cursor for

node

node spine node to set the cursor for

Returns

rate

number playback rate

rate

number playback rate

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

node

node node to get texture from

node

node node to get texture from

Returns

spine_scene

hash spine scene id

spine_scene

hash spine scene id

gui.get_spine_skin

gui.get_spine_skin(node)

Gets the spine skin of a spine node

Parameters

node

node node to get spine skin from

node

node node to get spine skin from

Returns

id

hash spine skin id, 0 if no explicit skin is set

id

hash spine skin id, 0 if no explicit skin is set

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

node

node node from which to get the text

Returns

text

string text value

text

string text value

gui.get_text_metrics

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

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

Parameters

font

string | hash font id

text

string text to measure

width

number max-width. Use for line-breaks (default=FLT_MAX)

line_breaks

boolean true to break lines accordingly to width (default=false)

leading

number scale value for line spacing (default=1)

tracking

number scale value for letter spacing (default=0)

font

string | hash font id

text

string text to measure

width

number max-width. Use for line-breaks (default=FLT_MAX)

line_breaks

boolean true to break lines accordingly to width (default=false)

leading

number scale value for line spacing (default=1)

tracking

number scale value for letter spacing (default=0)

Returns

metrics

table a table with the following fields:

  • width
  • height
  • max_ascent
  • max_descent
metrics

table a table with the following fields:

  • width
  • height
  • max_ascent
  • max_descent

gui.get_text_metrics_from_node

gui.get_text_metrics_from_node(node)

Get the text metrics from a text node.

Parameters

node

node text node to measure text from

node

node text node to measure text from

Returns

metrics

table a table with the following fields:

  • width
  • height
  • max_ascent
  • max_descent
metrics

table a table with the following fields:

  • width
  • height
  • max_ascent
  • max_descent

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

node

node node to get texture from

Returns

texture

hash texture id

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

node

node node from where to get the tracking

Returns

tracking

number tracking scaling number (default=0)

tracking

number tracking scaling number (default=0)

gui.get_width

gui.get_width()

Returns the scene width.

Returns

width

number scene width

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

node

node node to get x-anchor from

Returns

anchor

constant anchor constant

  • gui.ANCHOR_NONE
  • gui.ANCHOR_LEFT
  • gui.ANCHOR_RIGHT
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

node

node node to get y-anchor from

Returns

anchor

constant anchor constant

  • gui.ANCHOR_NONE
  • gui.ANCHOR_TOP
  • gui.ANCHOR_BOTTOM
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.

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

node

node node to query

node

node node to query

Returns

enabled

boolean whether the node is enabled or not

enabled

boolean whether the node is enabled or not

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

node

node to move

node

node | nil reference node above which the first node should be moved

node

node to move

node

node | nil reference node above which the first node should be moved

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

node

node to move

node

node | nil reference node below which the first node should be moved

node

node to move

node

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

pos

vector3 | vector4 node position

size

vector3 node size

Returns

node

node new box node

node

node new box 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

pos

vector3 | vector4 node position

size

vector3 node size

Returns

node

node new box node

node

node new box node

gui.new_spine_node

gui.new_spine_node(pos, spine_scene)

Dynamically create a new spine node.

Parameters

pos

vector3 | vector4 node position

spine_scene

string | hash spine scene id

pos

vector3 | vector4 node position

spine_scene

string | hash spine scene id

Returns

node

node new spine node

node

node new spine 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

pos

vector3 | vector4 node position

text

string node text

Returns

node

node new text node

node

node new text node

gui.new_texture

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

Dynamically create a new 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

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 texture creation was successful

success

boolean texture creation was successful

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

node

node node to be tested for picking

x

number x-coordinate (see on_input )

y

number y-coordinate (see on_input )

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

pickable

boolean pick result

gui.play_flipbook

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

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.

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.

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_spine_anim

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

Starts a spine animation.

Parameters

node

node spine node that should play the animation

animation_id

string | hash id of the animation to play

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
[play_properties]

table optional table with properties

blend_duration
number The duration of a linear blend between the current and new animation
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
[complete_function]

function(self, node) function to call when the animation has completed

node

node spine node that should play the animation

animation_id

string | hash id of the animation to play

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
[play_properties]

table optional table with properties

blend_duration
number The duration of a linear blend between the current and new animation
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
[complete_function]

function(self, node) function to call when the animation has completed

gui.reset_keyboard

gui.reset_keyboard()

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

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.

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

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

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

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

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

node

node node to be enabled/disabled

enabled

boolean whether the node should be enabled or not

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

node

node node to set the fill angle for

angle

number sector angle

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

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

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

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

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)

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 of false

node

node node to set line-break for

line-break

boolean true of false

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

node

node node to set the outline color for

color

vector3 | vector4 new outline color

gui.set_parent

gui.set_parent(node, parent)

Sets the parent node of the specified node.

Parameters

node

node node for which to set its parent

parent

node parent node to set

node

node node for which to set its parent

parent

node parent node to set

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

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

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

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)

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 in degree Euler angles.

Parameters

node

node node to set the rotation for

rotation

vector3 | vector4 new rotation

node

node node to set the rotation for

rotation

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

node

node node to set the scale for

scale

vector3 | vector4 new scale

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

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

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.

Parameters

node

node node to set size mode for

size_mode

constant size mode to set

  • gui.SIZE_MODE_MANUAL
  • gui.SIZE_MODE_AUTO
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

node

node node to manipulate

values

vector4 new values

gui.set_spine_cursor

gui.set_spine_cursor(node, cursor)

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

Parameters

node

node spine node to set the cursor for

cursor

number cursor value

node

node spine node to set the cursor for

cursor

number cursor value

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

node

node spine node to set the cursor for

playback_rate

number playback rate

node

node spine node to set the cursor for

playback_rate

number playback rate

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

node

node node to set spine scene for

spine_scene

string | hash spine scene id

node

node node to set spine scene for

spine_scene

string | hash spine scene id

gui.set_spine_skin

gui.set_spine_skin(node, spine_skin)

Sets the spine skin on a spine node.

Parameters

node

node node to set the spine skin on

spine_skin

string | hash spine skin id

node

node node to set the spine skin on

spine_skin

string | hash spine skin id

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 text to set

node

node node to set text for

text

string 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

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

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

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)

node

node node for which to set the tracking

tracking

number a scaling number for the letter spacing (default=0)

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

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

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

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, 0 for false and 1 for true. This is not present for mouse movement.
released If the input was released this frame, 0 for false and 1 for true. This is not present for mouse movement.
repeated If the input was repeated this frame, 0 for false and 1 for true. 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
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

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 optional boolean to signal if the input should be consumed (not passed on to others) or not, default is false

[consume]

boolean 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

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

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

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

Messages

layout_changed

"layout_changed", { id=…, previous_id=… }

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

Fields

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

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

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

gui.ANCHOR_LEFT

gui.ANCHOR_RIGHT

gui.ANCHOR_TOP

gui.BLEND_ADD

gui.BLEND_ADD_ALPHA

gui.BLEND_ALPHA

gui.BLEND_MULT

gui.CLIPPING_MODE_NONE

gui.CLIPPING_MODE_STENCIL

gui.EASING_INBACK

gui.EASING_INBOUNCE

gui.EASING_INCIRC

gui.EASING_INCUBIC

gui.EASING_INELASTIC

gui.EASING_INEXPO

gui.EASING_INOUTBACK

gui.EASING_INOUTBOUNCE

gui.EASING_INOUTCIRC

gui.EASING_INOUTCUBIC

gui.EASING_INOUTELASTIC

gui.EASING_INOUTEXPO

gui.EASING_INOUTQUAD

gui.EASING_INOUTQUART

gui.EASING_INOUTQUINT

gui.EASING_INOUTSINE

gui.EASING_INQUAD

gui.EASING_INQUART

gui.EASING_INQUINT

gui.EASING_INSINE

gui.EASING_LINEAR

gui.EASING_OUTBACK

gui.EASING_OUTBOUNCE

gui.EASING_OUTCIRC

gui.EASING_OUTCUBIC

gui.EASING_OUTELASTIC

gui.EASING_OUTEXPO

gui.EASING_OUTINBACK

gui.EASING_OUTINBOUNCE

gui.EASING_OUTINCIRC

gui.EASING_OUTINCUBIC

gui.EASING_OUTINELASTIC

gui.EASING_OUTINEXPO

gui.EASING_OUTINQUAD

gui.EASING_OUTINQUART

gui.EASING_OUTINQUINT

gui.EASING_OUTINSINE

gui.EASING_OUTQUAD

gui.EASING_OUTQUART

gui.EASING_OUTQUINT

gui.EASING_OUTSINE

gui.KEYBOARD_TYPE_DEFAULT

gui.KEYBOARD_TYPE_EMAIL

gui.KEYBOARD_TYPE_NUMBER_PAD

gui.KEYBOARD_TYPE_PASSWORD

gui.PIEBOUNDS_ELLIPSE

gui.PIEBOUNDS_RECTANGLE

gui.PIVOT_CENTER

gui.PIVOT_E

gui.PIVOT_N

gui.PIVOT_NE

gui.PIVOT_NW

gui.PIVOT_S

gui.PIVOT_SE

gui.PIVOT_SW

gui.PIVOT_W

gui.PLAYBACK_LOOP_BACKWARD

gui.PLAYBACK_LOOP_FORWARD

gui.PLAYBACK_LOOP_PINGPONG

gui.PLAYBACK_ONCE_BACKWARD

gui.PLAYBACK_ONCE_FORWARD

gui.PLAYBACK_ONCE_PINGPONG

gui.PROP_COLOR

gui.PROP_FILL_ANGLE

gui.PROP_INNER_RADIUS

gui.PROP_OUTLINE

gui.PROP_POSITION

gui.PROP_ROTATION

gui.PROP_SCALE

gui.PROP_SHADOW

gui.PROP_SIZE

gui.PROP_SLICE9

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


I want to report anonymously.