- Select ref document -

Label API documentation

version 1.2.162

Functions to manipulate a label component.

Functions

label.get_text

label.get_text(url)

Gets the text from a label component

Parameters

url

string | hash | url the label to get the text from

url

string | hash | url the label to get the text from

Returns

metrics

string the label text

metrics

string the label text

Examples

function init(self)
    local text = label.get_text("#label")
    print(text)
end

label.get_text_metrics

label.get_text_metrics(url)

Gets the text metrics from a label component

Parameters

url

string | hash | url the label to get the (unscaled) metrics from

url

string | hash | url the label to get the (unscaled) metrics 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

Examples

function init(self)
    local metrics = label.get_text_metrics("#label")
    pprint(metrics)
end

label.set_text

label.set_text(url, text)

Sets the text of a label component

This method uses the message passing that means the value will be set after dispatch messages step. More information is available in the Application Lifecycle manual.

Parameters

url

string | hash | url the label that should have a constant set

text

string the text

url

string | hash | url the label that should have a constant set

text

string the text

Examples

function init(self)
    label.set_text("#label", "Hello World!")
end

Properties

color

The color of the label. The type of the property is vector4.

Examples

function init(self)
   -- Get the current color's y component
   local red_component = go.get("#label", "color.y")
   -- Animate the color
   go.animate("#label", "color", go.PLAYBACK_LOOP_PINGPONG, vmath.vector4(0,1,0,1), go.EASING_INOUTSINE, 1)
end

outline

The outline color of the label. The type of the property is vector4.

Examples

function init(self)
   -- Get the current outline color
   local outline = go.get("#label", "outline")
   -- Animate the property
   go.animate("#label", "outline", go.PLAYBACK_LOOP_PINGPONG, vmath.vector4(0,1,0,1), go.EASING_INOUTSINE, 1)
end

scale

The scale of the label. The type of the property is number (uniform) or vector3 (non uniform).

Examples

How to scale a label independently along the X and Y axis:

function init(self)
   -- Double the y-axis scaling on component "label"
   local yscale = go.get("#label", "scale.y")
   go.set("#label", "scale.y", yscale * 2)
   -- Set the new scale altogether
   go.set("#label", "scale", vmath.vector3(2,2,2))
   -- Animate the scale
   go.animate("#label", "scale", go.PLAYBACK_LOOP_PINGPONG, vmath.vector3(2,2,2), go.EASING_INOUTSINE, 1)
end

shadow

The shadow color of the label. The type of the property is vector4.

Examples

function init(self)
 -- Get the current shadow color
 local shadow = go.get("#label", "shadow")
 -- Animate the property
 go.animate("#label", "shadow", go.PLAYBACK_LOOP_PINGPONG, vmath.vector4(0,1,0,1), go.EASING_INOUTSINE, 1)
end

size

Returns the size of the label. The size will constrain the text if line break is enabled The type of the property is vector3.

Examples

How to query a label's size, either as a vector or selecting a specific dimension:

function init(self)
 -- get size from component "label"
 local size = go.get("#label", "size")
 local sizex = go.get("#label", "size.x")
 -- do something useful
 assert(size.x == sizex)
end