Version: stable
FUNCTION | |
---|---|
gui.get_node() | gets the node with the specified id |
gui.get_id() | gets the id of the specified node |
gui.set_id() | sets the id of the specified node |
gui.get_index() | gets the index of the specified node |
gui.delete_node() | deletes a node |
gui.animate() | animates a node property |
gui.cancel_animation() | cancels an ongoing animation |
gui.new_box_node() | creates a new box node |
gui.new_text_node() | creates a new text node |
gui.new_pie_node() | creates a new pie node |
gui.get_text() | gets the node text |
gui.set_text() | sets the node text |
gui.get_line_break() | get line-break mode |
gui.set_line_break() | set line-break mode |
gui.get_blend_mode() | gets the node blend mode |
gui.set_blend_mode() | sets node blend mode |
gui.get_texture() | gets node texture |
gui.set_texture() | sets the node texture |
gui.get_flipbook() | gets the node flipbook animation |
gui.play_flipbook() | play node flipbook animation |
gui.cancel_flipbook() | cancel a node flipbook animation |
gui.new_texture() | create new texture |
gui.delete_texture() | delete texture |
gui.set_texture_data() | set the buffer data for a texture |
gui.get_material() | gets the assigned node material |
gui.set_material() | sets the node material |
gui.reset_material() | resets the node material |
gui.get_font() | gets the node font |
gui.get_font_resource() | gets the node font resource |
gui.set_font() | sets the node font |
gui.get_layer() | gets the node layer |
gui.set_layer() | sets the node layer |
gui.get_layout() | gets the scene current layout |
gui.get_clipping_mode() | gets the node clipping mode |
gui.set_clipping_mode() | sets node clipping mode state |
gui.get_clipping_visible() | gets node clipping visibility state |
gui.set_clipping_visible() | sets node clipping visibility |
gui.get_clipping_inverted() | gets node clipping inverted state |
gui.set_clipping_inverted() | sets node clipping inversion |
gui.get_xanchor() | gets the x-anchor of a node |
gui.set_xanchor() | sets the x-anchor of a node |
gui.get_yanchor() | gets the y-anchor of a node |
gui.set_yanchor() | sets the y-anchor of a node |
gui.get_pivot() | gets the pivot of a node |
gui.set_pivot() | sets the pivot of a node |
gui.get_width() | gets the scene width |
gui.get_height() | gets the scene height |
gui.set_slice9() | set the slice9 configuration for the node |
gui.get_slice9() | get the slice9 values for the node |
gui.set_perimeter_vertices() | sets the number of generated vertices around the perimeter |
gui.get_perimeter_vertices() | gets the number of generated vertices around the perimeter |
gui.set_fill_angle() | sets the angle for the filled pie sector |
gui.get_fill_angle() | gets the angle for the filled pie sector |
gui.set_inner_radius() | sets the pie inner radius |
gui.get_inner_radius() | gets the pie inner radius |
gui.set_outer_bounds() | sets the pie node outer bounds mode |
gui.get_outer_bounds() | gets the pie outer bounds mode |
gui.set_leading() | sets the leading of the text node |
gui.get_leading() | gets the leading of the text node |
gui.set_tracking() | sets the tracking of the text node |
gui.get_tracking() | gets the tracking of the text node |
gui.pick_node() | determines if the node is pickable by the supplied coordinates |
gui.is_enabled() | returns if a node is enabled or not |
gui.set_enabled() | enables/disables a node |
gui.get_visible() | returns if a node is visible or not |
gui.set_visible() | set visibility for a node |
gui.get_adjust_mode() | gets the node adjust mode |
gui.set_adjust_mode() | sets node adjust mode |
gui.get_size_mode() | gets the node size mode |
gui.set_size_mode() | sets node size mode |
gui.move_above() | moves the first node above the second |
gui.move_below() | moves the first node below the second |
gui.get_parent() | gets the parent of the specified node |
gui.set_parent() | sets the parent of the node |
gui.clone() | clone a node |
gui.clone_tree() | clone a node including its children |
gui.get_tree() | get a node including its children |
gui.reset_nodes() | resets all nodes to initial state |
gui.set_render_order() | sets the render ordering for the current GUI scene |
gui.show_keyboard() | shows the on-display keyboard if available |
gui.hide_keyboard() | hides on-display keyboard if available |
gui.reset_keyboard() | resets on-display keyboard if available |
gui.get_position() | gets the node position |
gui.set_position() | sets the node position |
gui.get_rotation() | gets the node rotation |
gui.set_rotation() | sets the node rotation |
gui.get_scale() | gets the node scale |
gui.set_scale() | sets the node scale |
gui.get_color() | gets the node color |
gui.set_color() | sets the node color |
gui.get_outline() | gets the node outline color |
gui.set_outline() | sets the node outline color |
gui.get_shadow() | gets the node shadow color |
gui.set_shadow() | sets the node shadow color |
gui.set_size() | sets the node size |
gui.get_size() | gets the node size |
gui.get_screen_position() | gets the node screen position |
gui.set_screen_position() | sets screen position to the node |
gui.screen_to_local() | convert screen position to the local node position |
gui.get_flipbook_cursor() | gets the normalized cursor of the animation on a node with flipbook animation |
gui.set_flipbook_cursor() | sets the normalized cursor of the animation on a node with flipbook animation |
gui.get_flipbook_playback_rate() | gets the playback rate of the flipbook animation on a node |
gui.set_flipbook_playback_rate() | sets the playback rate of the flipbook animation on a node |
gui.new_particlefx_node() | creates a new particle fx node |
gui.play_particlefx() | Plays a particle fx |
gui.stop_particlefx() | Stops a particle fx |
gui.set_particlefx() | Sets a particle fx |
gui.get_particlefx() | Gets a particle fx |
gui.get_inherit_alpha() | gets the node inherit alpha state |
gui.set_inherit_alpha() | sets the node inherit alpha state |
gui.get_alpha() | gets the node alpha |
gui.set_alpha() | sets the node alpha |
init() | called when a gui component is initialized |
final() | called when a gui component is finalized |
update() | called every frame to update the gui component |
on_message() | called when a message has been sent to the gui component |
on_input() | called when user input is received |
on_reload() | called when the gui script is reloaded |
MESSAGE | |
---|---|
layout_changed | reports a layout change |
PROPERTIES | |
---|---|
material | hash gui material |
materials | hash gui materials |
textures | hash gui textures |
fonts | hash gui fonts |
gui.get_node(id)
Retrieves the node with the specified id.
PARAMETERS
id |
string, hash |
id of the node to retrieve |
RETURNS
instance |
node | a new node instance |
EXAMPLES
Gets a node by id and change its color:local node = gui.get_node("my_node")
local red = vmath.vector4(1.0, 0.0, 0.0, 1.0)
gui.set_color(node, red)
gui.get_id(node)
Retrieves the id of the specified node.
PARAMETERS
node |
node |
the node to retrieve the id from |
RETURNS
id |
hash | the id of the node |
EXAMPLES
Gets the id of a node:local node = gui.get_node("my_node")
local id = gui.get_id(node)
print(id) --> hash: [my_node]
gui.set_id(node,id)
Set the id of the specicied node to a new value. Nodes created with the gui.new_*_node() functions get an empty id. This function allows you to give dynamically created nodes an id. No checking is done on the uniqueness of supplied ids. It is up to you to make sure you use unique ids.
PARAMETERS
node |
node |
node to set the id for |
id |
string, hash |
id to set |
EXAMPLES
Create a new node and set its id:local pos = vmath.vector3(100, 100, 0)
local size = vmath.vector3(100, 100, 0)
local node = gui.new_box_node(pos, size)
gui.set_id(node, "my_new_node")
gui.get_index(node)
Retrieve the index of the specified node among its siblings. The index defines the order in which a node appear in a GUI scene. Higher index means the node is drawn on top of lower indexed nodes.
PARAMETERS
node |
node |
the node to retrieve the id from |
RETURNS
index |
number | the index of the node |
EXAMPLES
Compare the index order of two sibling nodes:local node1 = gui.get_node("my_node_1")
local node2 = gui.get_node("my_node_2")
if gui.get_index(node1) < gui.get_index(node2) then
-- node1 is drawn below node2
else
-- node2 is drawn below node1
end
gui.delete_node(node)
Deletes the specified node. Any child nodes of the specified node will be recursively deleted.
PARAMETERS
node |
node |
node to delete |
EXAMPLES
Delete a particular node and any child nodes it might have:local node = gui.get_node("my_node")
gui.delete_node(node)
gui.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
|
to |
number, vector3, vector4, quaternion |
target property value |
easing |
constant, vector |
easing to use during animation.
Either specify one of the gui.EASING_* constants or provide a
vector with a custom curve. See the animation guide for more information. |
duration |
number |
duration of the animation in seconds. |
[delay] |
number |
delay before the animation starts in seconds. |
[complete_function] |
function(self, node) |
function to call when the animation has completed |
[playback] |
constant |
playback mode
|
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
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
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(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
|
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.new_box_node(pos,size)
Dynamically create a new box node.
PARAMETERS
pos |
vector3, vector4 |
node position |
size |
vector3 |
node size |
RETURNS
node |
node | new box node |
gui.new_text_node(pos,text)
Dynamically create a new text node.
PARAMETERS
pos |
vector3, vector4 |
node position |
text |
string |
node text |
RETURNS
node |
node | new text node |
gui.new_pie_node(pos,size)
Dynamically create a new pie node.
PARAMETERS
pos |
vector3, vector4 |
node position |
size |
vector3 |
node size |
RETURNS
node |
node | new pie node |
gui.get_text(node)
Returns the text value of a text node. This is only useful for text nodes.
PARAMETERS
node |
node |
node from which to get the text |
RETURNS
text |
string | text value |
gui.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 |
gui.get_line_break(node)
Returns whether a text node is in line-break mode or not. This is only useful for text nodes.
PARAMETERS
node |
node |
node from which to get the line-break for |
RETURNS
line_break |
boolean | true or false |
gui.set_line_break(node,line_break)
Sets the line-break mode on a text node. This is only useful for text nodes.
PARAMETERS
node |
node |
node to set line-break for |
line_break |
boolean |
true or false |
gui.get_blend_mode(node)
Returns the blend mode of a node. Blend mode defines how the node will be blended with the background.
PARAMETERS
node |
node |
node from which to get the blend mode |
RETURNS
blend_mode |
constant | blend mode
|
gui.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.get_texture(node)
Returns the texture of a node. This is currently only useful for box or pie nodes. The texture must be mapped to the gui scene in the gui editor.
PARAMETERS
node |
node |
node to get texture from |
RETURNS
texture |
hash | texture id |
gui.set_texture(node,texture)
Set the texture on a box or pie node. The texture must be mapped to
the gui scene in the gui editor. The function points out which texture
the node should render from. If the texture is an atlas, further
information is needed to select which image/animation in the atlas
to render. In such cases, use gui.play_flipbook()
in
addition to this function.
PARAMETERS
node |
node |
node to set texture for |
texture |
string, hash |
texture id |
EXAMPLES
To set a texture (or animation) from an atlas:local node = gui.get_node("box_node")
gui.set_texture(node, "my_atlas")
gui.play_flipbook(node, "image")
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.get_flipbook(node)
Get node flipbook animation.
PARAMETERS
node |
node |
node to get flipbook animation from |
RETURNS
animation |
hash | animation id |
gui.play_flipbook(node,animation,[complete_function],[play_properties])
Play flipbook animation on a box or pie node. The current node texture must contain the animation. Use this function to set one-frame still images on the node.
PARAMETERS
node |
node |
node to set animation for |
animation |
string, hash |
animation id |
[complete_function] |
function(self, node) |
optional function to call when the animation has completed
|
[play_properties] |
table |
optional table with properties
|
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
-- 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.cancel_flipbook(node)
Cancels any running flipbook animation on the specified node.
PARAMETERS
node |
node |
node cancel flipbook animation for |
EXAMPLES
local node = gui.get_node("anim_node")
gui.cancel_flipbook(node)
gui.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
|
buffer |
string |
texture data |
flip |
boolean |
flip texture vertically |
RETURNS
success |
boolean | texture creation was successful |
code |
number | one of the gui.RESULT_* codes if unsuccessful |
EXAMPLES
How to create a texture and apply it to a new box node:function init(self)
local w = 200
local h = 300
-- A nice orange. String with the RGB values.
local orange = string.char(0xff) .. string.char(0x80) .. string.char(0x10)
-- Create the texture. Repeat the color string for each pixel.
local ok, reason = gui.new_texture("orange_tx", w, h, "rgb", string.rep(orange, w * h))
if ok then
-- Create a box node and apply the texture to it.
local n = gui.new_box_node(vmath.vector3(200, 200, 0), vmath.vector3(w, h, 0))
gui.set_texture(n, "orange_tx")
else
-- Could not create texture for some reason...
if reason == gui.RESULT_TEXTURE_ALREADY_EXISTS then
...
else
...
end
end
end
gui.delete_texture(texture)
Delete a dynamically created texture.
PARAMETERS
texture |
string, hash |
texture id |
EXAMPLES
function init(self)
-- Create a texture.
if gui.new_texture("temp_tx", 10, 10, "rgb", string.rep('\0', 10 * 10 * 3)) then
-- Do something with the texture.
...
-- Delete the texture
gui.delete_texture("temp_tx")
end
end
gui.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
|
buffer |
string |
texture data |
flip |
boolean |
flip texture vertically |
RETURNS
success |
boolean | setting the data was successful |
EXAMPLES
function init(self)
local w = 200
local h = 300
-- Create a dynamic texture, all white.
if gui.new_texture("dynamic_tx", w, h, "rgb", string.rep(string.char(0xff), w * h * 3)) then
-- Create a box node and apply the texture to it.
local n = gui.new_box_node(vmath.vector3(200, 200, 0), vmath.vector3(w, h, 0))
gui.set_texture(n, "dynamic_tx")
...
-- Change the data in the texture to a nice orange.
local orange = string.char(0xff) .. string.char(0x80) .. string.char(0x10)
if gui.set_texture_data("dynamic_tx", w, h, "rgb", string.rep(orange, w * h)) then
-- Go on and to more stuff
...
end
else
-- Something went wrong
...
end
end
gui.get_material(node)
Returns the material of a node. The material must be mapped to the gui scene in the gui editor.
PARAMETERS
node |
node |
node to get the material for |
EXAMPLES
Getting the material for a node, and assign it to another node:local node1 = gui.get_node("my_node")
local node2 = gui.get_node("other_node")
local node1_material = gui.get_material(node1)
gui.set_material(node2, node1_material)
gui.set_material(node,material)
Set the material on a node. The material must be mapped to the gui scene in the gui editor,
and assigning a material is supported for all node types. To set the default material that
is assigned to the gui scene node, use gui.reset_material(node_id)
instead.
PARAMETERS
node |
node |
node to set material for |
material |
string, hash |
material id |
EXAMPLES
Assign an existing material to a node:local node = gui.get_node("my_node")
gui.set_material(node, "my_material")
gui.reset_material(node)
Resets the node material to the material assigned in the gui scene.
PARAMETERS
node |
node |
node to reset the material for |
EXAMPLES
Resetting the material for a node:local node = gui.get_node("my_node")
gui.reset_material(node)
gui.get_font(node)
This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.
PARAMETERS
node |
node |
node from which to get the font |
RETURNS
font |
hash | font id |
gui.get_font_resource(font_name)
This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.
PARAMETERS
font_name |
hash, string |
font of which to get the path hash |
RETURNS
hash |
hash | path hash to resource |
EXAMPLES
Get the text metrics for a textfunction init(self)
local node = gui.get_node("name")
local font_name = gui.get_font(node)
local font = gui.get_font_resource(font_name)
local metrics = resource.get_text_metrics(font, "The quick brown fox\n jumps over the lazy dog")
end
gui.set_font(node,font)
This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.
PARAMETERS
node |
node |
node for which to set the font |
font |
string, hash |
font id |
gui.get_layer(node)
The layer must be mapped to the gui scene in the gui editor.
PARAMETERS
node |
node |
node from which to get the layer |
RETURNS
layer |
hash | layer id |
gui.set_layer(node,layer)
The layer must be mapped to the gui scene in the gui editor.
PARAMETERS
node |
node |
node for which to set the layer |
layer |
string, hash |
layer id |
gui.get_layout()
gets the scene current layout
PARAMETERS
None
RETURNS
layout |
hash | layout id |
gui.get_clipping_mode(node)
Clipping mode defines how the node will clip it's children nodes
PARAMETERS
node |
node |
node from which to get the clipping mode |
RETURNS
clipping_mode |
constant | clipping mode
|
gui.set_clipping_mode(node,clipping_mode)
Clipping mode defines how the node will clip it's children nodes
PARAMETERS
node |
node |
node to set clipping mode for |
clipping_mode |
constant |
clipping mode to set
|
gui.get_clipping_visible(node)
If node is set as visible clipping node, it will be shown as well as clipping. Otherwise, it will only clip but not show visually.
PARAMETERS
node |
node |
node from which to get the clipping visibility state |
RETURNS
visible |
boolean | true or false |
gui.set_clipping_visible(node,visible)
If node is set as an visible clipping node, it will be shown as well as clipping. Otherwise, it will only clip but not show visually.
PARAMETERS
node |
node |
node to set clipping visibility for |
visible |
boolean |
true or false |
gui.get_clipping_inverted(node)
If node is set as an inverted clipping node, it will clip anything inside as opposed to outside.
PARAMETERS
node |
node |
node from which to get the clipping inverted state |
RETURNS
inverted |
boolean | true or false |
gui.set_clipping_inverted(node,inverted)
If node is set as an inverted clipping node, it will clip anything inside as opposed to outside.
PARAMETERS
node |
node |
node to set clipping inverted state for |
inverted |
boolean |
true or false |
gui.get_xanchor(node)
The x-anchor specifies how the node is moved when the game is run in a different resolution.
PARAMETERS
node |
node |
node to get x-anchor from |
RETURNS
anchor |
constant | anchor constant
|
gui.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.get_yanchor(node)
The y-anchor specifies how the node is moved when the game is run in a different resolution.
PARAMETERS
node |
node |
node to get y-anchor from |
RETURNS
anchor |
constant | anchor constant
|
gui.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.get_pivot(node)
The pivot specifies how the node is drawn and rotated from its position.
PARAMETERS
node |
node |
node to get pivot from |
RETURNS
pivot |
constant | pivot constant
|
gui.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.get_width()
Returns the scene width.
PARAMETERS
None
RETURNS
width |
number | scene width |
gui.get_height()
Returns the scene height.
PARAMETERS
None
RETURNS
height |
number | scene height |
gui.set_slice9(node,values)
Set the slice9 configuration values for the node.
PARAMETERS
node |
node |
node to manipulate |
values |
vector4 |
new values |
gui.get_slice9(node)
Returns the slice9 configuration values for the node.
PARAMETERS
node |
node |
node to manipulate |
RETURNS
values |
vector4 | configuration values |
gui.set_perimeter_vertices(node,vertices)
Sets the number of generated vertices around the perimeter of a pie node.
PARAMETERS
node |
node |
pie node |
vertices |
number |
vertex count |
gui.get_perimeter_vertices(node)
Returns the number of generated vertices around the perimeter of a pie node.
PARAMETERS
node |
node |
pie node |
RETURNS
vertices |
number | vertex count |
gui.set_fill_angle(node,angle)
Set the sector angle of a pie node.
PARAMETERS
node |
node |
node to set the fill angle for |
angle |
number |
sector angle |
gui.get_fill_angle(node)
Returns the sector angle of a pie node.
PARAMETERS
node |
node |
node from which to get the fill angle |
RETURNS
angle |
number | sector angle |
gui.set_inner_radius(node,radius)
Sets the inner radius of a pie node. The radius is defined along the x-axis.
PARAMETERS
node |
node |
node to set the inner radius for |
radius |
number |
inner radius |
gui.get_inner_radius(node)
Returns the inner radius of a pie node. The radius is defined along the x-axis.
PARAMETERS
node |
node |
node from where to get the inner radius |
RETURNS
radius |
number | inner radius |
gui.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.get_outer_bounds(node)
Returns the outer bounds mode for a pie node.
PARAMETERS
node |
node |
node from where to get the outer bounds mode |
RETURNS
bounds_mode |
constant | the outer bounds mode of the pie node:
|
gui.set_leading(node,leading)
Sets the leading value for a text node. This value is used to scale the line spacing of text.
PARAMETERS
node |
node |
node for which to set the leading |
leading |
number |
a scaling value for the line spacing (default=1) |
gui.get_leading(node)
Returns the leading value for a text node.
PARAMETERS
node |
node |
node from where to get the leading |
RETURNS
leading |
number | leading scaling value (default=1) |
gui.set_tracking(node,tracking)
Sets the tracking value of a text node. This value is used to adjust the vertical spacing of characters in the text.
PARAMETERS
node |
node |
node for which to set the tracking |
tracking |
number |
a scaling number for the letter spacing (default=0) |
gui.get_tracking(node)
Returns the tracking value of a text node.
PARAMETERS
node |
node |
node from where to get the tracking |
RETURNS
tracking |
number | tracking scaling number (default=0) |
gui.pick_node(node,x,y)
Tests whether a coordinate is within the bounding box of a node.
PARAMETERS
node |
node |
node to be tested for picking |
x |
number |
x-coordinate (see on_input ) |
y |
number |
y-coordinate (see on_input ) |
RETURNS
pickable |
boolean | pick result |
gui.is_enabled(node,recursive)
Returns true
if a node is enabled and false
if it's not.
Disabled nodes are not rendered and animations acting on them are not evaluated.
PARAMETERS
node |
node |
node to query |
recursive |
boolean |
check hierarchy recursively |
RETURNS
enabled |
boolean | whether the node is enabled or not |
gui.set_enabled(node,enabled)
Sets a node to the disabled or enabled state. Disabled nodes are not rendered and animations acting on them are not evaluated.
PARAMETERS
node |
node |
node to be enabled/disabled |
enabled |
boolean |
whether the node should be enabled or not |
gui.get_visible(node)
Returns true
if a node is visible and false
if it's not.
Invisible nodes are not rendered.
PARAMETERS
node |
node |
node to query |
RETURNS
visible |
boolean | whether the node is visible or not |
gui.set_visible(node,visible)
Set if a node should be visible or not. Only visible nodes are rendered.
PARAMETERS
node |
node |
node to be visible or not |
visible |
boolean |
whether the node should be visible or not |
gui.get_adjust_mode(node)
Returns the adjust mode of a node. The adjust mode defines how the node will adjust itself to screen resolutions that differs from the one in the project settings.
PARAMETERS
node |
node |
node from which to get the adjust mode (node) |
RETURNS
adjust_mode |
constant | the current adjust mode
|
gui.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.get_size_mode(node)
Returns the size of a node. The size mode defines how the node will adjust itself in size. Automatic size mode alters the node size based on the node's content. Automatic size mode works for Box nodes and Pie nodes which will both adjust their size to match the assigned image. Particle fx and Text nodes will ignore any size mode setting.
PARAMETERS
node |
node |
node from which to get the size mode (node) |
RETURNS
size_mode |
constant | the current size mode
|
gui.set_size_mode(node,size_mode)
Sets the size mode of a node. The size mode defines how the node will adjust itself in size. Automatic size mode alters the node size based on the node's content. Automatic size mode works for Box nodes and Pie nodes which will both adjust their size to match the assigned image. Particle fx and Text nodes will ignore any size mode setting.
PARAMETERS
node |
node |
node to set size mode for |
size_mode |
constant |
size mode to set
|
gui.move_above(node,reference)
Alters the ordering of the two supplied nodes by moving the first node
above the second.
If the second argument is nil
the first node is moved to the top.
PARAMETERS
node |
node |
to move |
reference |
node, nil |
reference node above which the first node should be moved |
gui.move_below(node,reference)
Alters the ordering of the two supplied nodes by moving the first node
below the second.
If the second argument is nil
the first node is moved to the bottom.
PARAMETERS
node |
node |
to move |
reference |
node, nil |
reference node below which the first node should be moved |
gui.get_parent(node)
Returns the parent node of the specified node.
If the supplied node does not have a parent, nil
is returned.
PARAMETERS
node |
node |
the node from which to retrieve its parent |
RETURNS
parent |
node, nil | parent instance or nil |
gui.set_parent(node,parent,keep_scene_transform)
Sets the parent node of the specified node.
PARAMETERS
node |
node |
node for which to set its parent |
parent |
node |
parent node to set |
keep_scene_transform |
boolean |
optional flag to make the scene position being perserved |
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 |
RETURNS
clone |
node | the cloned node |
gui.clone_tree(node)
Make a clone instance of a node and all its children. Use gui.clone to clone a node excluding its children.
PARAMETERS
node |
node |
root node to clone |
RETURNS
clones |
table | a table mapping node ids to the corresponding cloned nodes |
gui.get_tree(node)
Get a node and all its children as a Lua table.
PARAMETERS
node |
node |
root node to get node tree from |
RETURNS
clones |
table | a table mapping node ids to the corresponding nodes |
gui.reset_nodes()
Resets all nodes in the current GUI scene to their initial state. The reset only applies to static node loaded from the scene. Nodes that are created dynamically from script are not affected.
PARAMETERS
None
gui.set_render_order(order)
Set the order number for the current GUI scene. The number dictates the sorting of the "gui" render predicate, in other words in which order the scene will be rendered in relation to other currently rendered GUI scenes. The number must be in the range 0 to 15.
PARAMETERS
order |
number |
rendering order (0-15) |
gui.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
|
autoclose |
boolean |
if the keyboard should automatically close when clicking outside |
gui.hide_keyboard()
Hides the on-display touch keyboard on the device.
PARAMETERS
None
gui.reset_keyboard()
Resets the input context of keyboard. This will clear marked text.
PARAMETERS
None
gui.get_position(node)
Returns the position of the supplied node.
PARAMETERS
node |
node |
node to get the position from |
RETURNS
position |
vector3 | node position |
gui.set_position(node,position)
Sets the position of the supplied node.
PARAMETERS
node |
node |
node to set the position for |
position |
vector3, vector4 |
new position |
gui.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 |
RETURNS
rotation |
vector3 | node 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 |
gui.get_scale(node)
Returns the scale of the supplied node.
PARAMETERS
node |
node |
node to get the scale from |
RETURNS
scale |
vector3 | node scale |
gui.set_scale(node,scale)
Sets the scaling of the supplied node.
PARAMETERS
node |
node |
node to set the scale for |
scale |
vector3, vector4 |
new scale |
gui.get_color(node)
Returns the color of the supplied node. The components of the returned vector4 contains the color channel values:
Component | Color value |
---|---|
x | Red value |
y | Green value |
z | Blue value |
w | Alpha value |
PARAMETERS
node |
node |
node to get the color from |
RETURNS
color |
vector4 | node color |
gui.set_color(node,color)
Sets the color of the supplied node. The components of the supplied vector3 or vector4 should contain the color channel values:
Component | Color value |
---|---|
x | Red value |
y | Green value |
z | Blue value |
w vector4 | Alpha value |
PARAMETERS
node |
node |
node to set the color for |
color |
vector3, vector4 |
new color |
gui.get_outline(node)
Returns the outline color of the supplied node. See gui.get_color for info how vectors encode color values.
PARAMETERS
node |
node |
node to get the outline color from |
RETURNS
color |
vector4 | outline color |
gui.set_outline(node,color)
Sets the outline color of the supplied node. See gui.set_color for info how vectors encode color values.
PARAMETERS
node |
node |
node to set the outline color for |
color |
vector3, vector4 |
new outline color |
gui.get_shadow(node)
Returns the shadow color of the supplied node. See gui.get_color for info how vectors encode color values.
PARAMETERS
node |
node |
node to get the shadow color from |
RETURNS
color |
vector4 | node shadow color |
gui.set_shadow(node,color)
Sets the shadow color of the supplied node. See gui.set_color for info how vectors encode color values.
PARAMETERS
node |
node |
node to set the shadow color for |
color |
vector3, vector4 |
new shadow color |
gui.set_size(node,size)
Sets the size of the supplied node. You can only set size on nodes with size mode set to SIZE_MODE_MANUAL
PARAMETERS
node |
node |
node to set the size for |
size |
vector3, vector4 |
new size |
gui.get_size(node)
Returns the size of the supplied node.
PARAMETERS
node |
node |
node to get the size from |
RETURNS
size |
vector3 | node size |
gui.get_screen_position(node)
Returns the screen position of the supplied node. This function returns the calculated transformed position of the node, taking into account any parent node transforms.
PARAMETERS
node |
node |
node to get the screen position from |
RETURNS
position |
vector3 | node screen position |
gui.set_screen_position(node,screen_position)
Set the screen position to the supplied node
PARAMETERS
node |
node |
node to set the screen position to |
screen_position |
vector3 |
screen position |
gui.screen_to_local(node,screen_position)
Convert the screen position to the local position of supplied node
PARAMETERS
node |
node |
node used for getting local transformation matrix |
screen_position |
vector3 |
screen position |
RETURNS
local_position |
vector3 | local position |
gui.get_flipbook_cursor(node)
This is only useful nodes with flipbook animations. Gets the normalized cursor of the flipbook animation on a node.
PARAMETERS
node |
node |
node to get the cursor for (node) |
RETURNS
cursor |
number | cursor value |
gui.set_flipbook_cursor(node,cursor)
This is only useful nodes with flipbook animations. The cursor is normalized.
PARAMETERS
node |
node |
node to set the cursor for |
cursor |
number |
cursor value |
gui.get_flipbook_playback_rate(node)
This is only useful nodes with flipbook animations. Gets the playback rate of the flipbook animation on a node.
PARAMETERS
node |
node |
node to set the cursor for |
RETURNS
rate |
number | playback rate |
gui.set_flipbook_playback_rate(node,playback_rate)
This is only useful nodes with flipbook animations. Sets the playback rate of the flipbook animation on a node. Must be positive.
PARAMETERS
node |
node |
node to set the cursor for |
playback_rate |
number |
playback rate |
gui.new_particlefx_node(pos,particlefx)
Dynamically create a particle fx node.
PARAMETERS
pos |
vector3, vector4 |
node position |
particlefx |
hash, string |
particle fx resource name |
RETURNS
node |
node | new particle fx node |
gui.play_particlefx(node,[emitter_state_function])
Plays the paricle fx for a gui node
PARAMETERS
node |
node |
node to play particle fx for |
[emitter_state_function] |
function(self, node, emitter, state) |
optional callback function that will be called when an emitter attached to this particlefx changes state.
|
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.stop_particlefx(node,options)
Stops the particle fx for a gui node
PARAMETERS
node |
node |
node to stop particle fx for |
options |
table |
options when stopping the particle fx. Supported options:
|
gui.set_particlefx(node,particlefx)
Set the paricle fx for a gui node
PARAMETERS
node |
node |
node to set particle fx for |
particlefx |
hash, string |
particle fx id |
gui.get_particlefx(node)
Get the paricle fx for a gui node
PARAMETERS
node |
node |
node to get particle fx for |
RETURNS
particlefx |
hash | particle fx id |
gui.get_inherit_alpha(node)
gets the node inherit alpha state
PARAMETERS
node |
node |
node from which to get the inherit alpha state |
gui.set_inherit_alpha(node,inherit_alpha)
sets the node inherit alpha state
PARAMETERS
node |
node |
node from which to set the inherit alpha state |
inherit_alpha |
boolean |
true or false |
gui.get_alpha(node)
gets the node alpha
PARAMETERS
node |
node |
node from which to get alpha |
gui.set_alpha(node,alpha)
sets the node alpha
PARAMETERS
node |
node |
node for which to set alpha |
alpha |
number |
0..1 alpha color |
init(self)
This is a callback-function, which is called by the engine when a gui component is initialized. It can be used to set the initial state of the script and gui scene.
PARAMETERS
self |
object |
reference to the script state to be used for storing data |
EXAMPLES
function init(self)
-- set up useful data
self.my_value = 1
end
final(self)
This is a callback-function, which is called by the engine when a gui component is finalized (destroyed). It can
be used to e.g. take some last action, report the finalization to other game object instances
or release user input focus (see release_input_focus
). There is no use in starting any animations or similar
from this function since the gui component is about to be destroyed.
PARAMETERS
self |
object |
reference to the script state to be used for storing data |
EXAMPLES
function final(self)
-- report finalization
msg.post("my_friend_instance", "im_dead", {my_stats = self.some_value})
end
update(self,dt)
This is a callback-function, which is called by the engine every frame to update the state of a gui component. It can be used to perform any kind of gui related tasks, e.g. animating nodes.
PARAMETERS
self |
object |
reference to the script state to be used for storing data |
dt |
number |
the time-step of the frame update |
EXAMPLES
This example demonstrates how to update a text node that displays game score in a counting fashion. It is assumed that the gui component receives messages from the game when a new score is to be shown.function init(self)
-- fetch the score text node for later use (assumes it is called "score")
self.score_node = gui.get_node("score")
-- keep track of the current score counted up so far
self.current_score = 0
-- keep track of the target score we should count up to
self.target_score = 0
-- how fast we will update the score, in score/second
self.score_update_speed = 1
end
function update(self, dt)
-- check if target score is more than current score
if self.current_score < self.target_score
-- increment current score according to the speed
self.current_score = self.current_score + dt * self.score_update_speed
-- check if we went past the target score, clamp current score in that case
if self.current_score > self.target_score then
self.current_score = self.target_score
end
-- update the score text node
gui.set_text(self.score_node, "" .. math.floor(self.current_score))
end
end
function on_message(self, message_id, message, sender)
-- check the message
if message_id == hash("set_score") then
self.target_score = message.score
end
end
on_message(self,message_id,message)
This is a callback-function, which is called by the engine whenever a message has been sent to the gui component.
It can be used to take action on the message, e.g. update the gui or send a response back to the sender of the message.
The message
parameter is a table containing the message data. If the message is sent from the engine, the
documentation of the message specifies which data is supplied.
See the update function for examples on how to use this callback-function.
PARAMETERS
self |
object |
reference to the script state to be used for storing data |
message_id |
hash |
id of the received message |
message |
table |
a table containing the message data |
on_input(self,action_id,action)
This is a callback-function, which is called by the engine when user input is sent to the instance of the gui component.
It can be used to take action on the input, e.g. modify the gui according to the input.
For an instance to obtain user input, it must first acquire input
focus through the message acquire_input_focus
.
Any instance that has obtained input will be put on top of an
input stack. Input is sent to all listeners on the stack until the
end of stack is reached, or a listener returns true
to signal that it wants input to be consumed.
See the documentation of acquire_input_focus for more
information.
The action
parameter is a table containing data about the input mapped to the
action_id
.
For mapped actions it specifies the value of the input and if it was just pressed or released.
Actions are mapped to input in an input_binding-file.
Mouse movement is specifically handled and uses nil
as its action_id
.
The action
only contains positional parameters in this case, such as x and y of the pointer.
Here is a brief description of the available table fields:
Field | Description |
---|---|
value |
The amount of input given by the user. This is usually 1 for buttons and 0-1 for analogue inputs. This is not present for mouse movement. |
pressed |
If the input was pressed this frame. This is not present for mouse movement. |
released |
If the input was released this frame. This is not present for mouse movement. |
repeated |
If the input was repeated this frame. This is similar to how a key on a keyboard is repeated when you hold it down. This is not present for mouse movement. |
x |
The x value of a pointer device, if present. |
y |
The y value of a pointer device, if present. |
screen_x |
The screen space x value of a pointer device, if present. |
screen_y |
The screen space y value of a pointer device, if present. |
dx |
The change in x value of a pointer device, if present. |
dy |
The change in y value of a pointer device, if present. |
screen_dx |
The change in screen space x value of a pointer device, if present. |
screen_dy |
The change in screen space y value of a pointer device, if present. |
gamepad |
The index of the gamepad device that provided the input. |
touch |
List of touch input, one element per finger, if present. See table below about touch input |
Field | Description |
---|---|
id |
A number identifying the touch input during its duration. |
pressed |
True if the finger was pressed this frame. |
released |
True if the finger was released this frame. |
tap_count |
Number of taps, one for single, two for double-tap, etc |
x |
The x touch location. |
y |
The y touch location. |
dx |
The change in x value. |
dy |
The change in y value. |
acc_x |
Accelerometer x value (if present). |
acc_y |
Accelerometer y value (if present). |
acc_z |
Accelerometer z value (if present). |
PARAMETERS
self |
object |
reference to the script state to be used for storing data |
action_id |
hash |
id of the received input action, as mapped in the input_binding-file |
action |
table |
a table containing the input data, see above for a description |
RETURNS
consume |
boolean, nil | optional boolean to signal if the input should be consumed (not passed on to others) or not, default is false |
EXAMPLES
function on_input(self, action_id, action)
-- check for input
if action_id == hash("my_action") then
-- take appropritate action
self.my_value = action.value
end
-- consume input
return true
end
on_reload(self)
This is a callback-function, which is called by the engine when the gui script is reloaded, e.g. from the editor. It can be used for live development, e.g. to tweak constants or set up the state properly for the script.
PARAMETERS
self |
object |
reference to the script state to be used for storing data |
EXAMPLES
function on_reload(self)
-- restore some color (or similar)
gui.set_color(gui.get_node("my_node"), self.my_original_color)
end
once forward
once backward
once forward and then backward
loop forward
loop backward
ping pong loop
linear interpolation
in-quadratic
out-quadratic
in-out-quadratic
out-in-quadratic
in-cubic
out-cubic
in-out-cubic
out-in-cubic
in-quartic
out-quartic
in-out-quartic
out-in-quartic
in-quintic
out-quintic
in-out-quintic
out-in-quintic
in-sine
out-sine
in-out-sine
out-in-sine
in-exponential
out-exponential
in-out-exponential
out-in-exponential
in-circlic
out-circlic
in-out-circlic
out-in-circlic
in-elastic
out-elastic
in-out-elastic
out-in-elastic
in-back
out-back
in-out-back
out-in-back
in-bounce
out-bounce
in-out-bounce
out-in-bounce
default keyboard
number input keyboard
email keyboard
password keyboard
position property
rotation property
scale property
color property
outline color property
shadow color property
size property
fill_angle property
inner_radius property
slice9 property
alpha blending
additive blending
additive alpha blending
multiply blending
clipping mode none
clipping mode stencil
left x-anchor
right x-anchor
top y-anchor
bottom y-anchor
no anchor
center pivot
north pivot
north-east pivot
east pivot
south-east pivot
south pivot
south-west pivot
west pivot
north-west pivot
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.
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.
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.
elliptical pie node bounds
rectangular pie node bounds
The size of the node is determined by the size set in the editor, the constructor or by gui.set_size()
The size of the node is determined by the currently assigned texture.
The texture id already exists when trying to use gui.new_texture().
The system is out of resources, for instance when trying to create a new texture using gui.new_texture().
The provided data is not in the expected format or is in some other way incorrect, for instance the image data provided to gui.new_texture().
This message is broadcast to every GUI component when a layout change has been initiated on device.
id |
hash |
the id of the layout the engine is changing to |
previous_id |
hash |
the id of the layout the engine is changing from |
EXAMPLES
function on_message(self, message_id, message, sender)
if message_id == hash("layout_changed") and message.id == hash("Landscape") then
-- switching layout to "Landscape"...
...
end
end
The main material (the default material assigned to a GUI) used when rendering the gui. The type of the property is hash.
EXAMPLES
How to set material using a script property (see resource.material)go.property("desaturate_material", resource.material("/desaturate.material"))
function init(self)
go.set("#gui", "material", self.desaturate_material)
end
The materials used when rendering the gui. The type of the property is hash. Key must be specified in options table.
EXAMPLES
How to change a named material resource using a script property from a scriptgo.property("my_material", resource.material("/my_material.material"))
function init(self)
-- this will update the "my_gui_material" entry in the GUI to use the material
-- specified in the "my_material" script property.
go.set("#gui", "materials", self.my_material, { key = "my_gui_material" })
end
The textures used in the gui. The type of the property is hash. Key must be specified in options table.
EXAMPLES
How to set texture using a script property (see resource.atlas)go.property("cards_red", resource.atlas("/cards_red.atlas"))
go.property("cards_blue", resource.atlas("/cards_blue.atlas"))
function init(self)
go.set("#gui", "textures", self.cards_red, {key = "cards"})
end
The fonts used in the gui. The type of the property is hash. Key must be specified in options table.
EXAMPLES
How to set font using a script property (see resource.font)go.property("title_latin", resource.font("/open_sans.font"))
go.property("title_cyrillic", resource.font("/open_sans_cyrillic.font"))
function init(self)
go.set("#gui", "fonts", self.title_cyrillic, {key = "title"})
end