CONTROL is the class for Lua objects that represent Storyboard control model objects. CONTROL extends DOMOBJECT so objects of this type can also invoke all the functions of DOMOBJECT. In Lua, this class is called gredom#control.
As of Storyboard 9.0, GREDOM Controls have direct member access for grd_ attributes. Direct access allows for both reading and writing of these properties through common Lua variable access/assignment.
-
x- The fixed component of a controls x-position. [grd_x] -
y- The fixed component of a controls y-position. [grd_y] -
w(orwidth) - The fixed component of a control's width. [grd_width] -
h(orheight- The fixed component control's height. [grd_height] -
sx- The scaled component of a control's x-position, a factor of the parent's width inherited by this control. [grd_sx] -
sy- The scaled component of a control's y-position, a factor of the parent's height inherited by this control. [grd_sy] -
sw- The scaled component of a control's width, a factor of the parent's width inherited by this control. [grd_sw] -
sh- The scaled component of a control's height, a factor of the parent's height inherited by this control. [grd_sh] -
ax- The control's horizontal anchor (gre.LEFT, gre.CENTER, gre.RIGHT). Determines how a control's x-position is interpreted, defining which point of the control is anchored to the specified x coordinate. [grd_ax]-
gre.LEFT- The x-position specifies the location of the left-most edge of the control. -
gre.CENTER- The x-position specifies the location of the horizontal center of the control. -
gre.RIGHT- The x-position specifies the location of the right-most edge of the control.
-
-
ay- The control's vertical anchor (gre.TOP, gre.CENTER, gre.BOTTOM). Determines how a control's y-position is interpreted, defining which point of the control is anchored to the specified y coordinate. [grd_ay]-
gre.TOP- The y-position specifies the location of the top-most edge of the control. -
gre.CENTER- The y-position specifies the location of the vertical center of the control. -
gre.BOTTOM- The y-position specifies the location of the bottom-most edge of the control.
-
-
pl- The control's left padding, used to determine the client area for children of this control. [grd_pl] -
pt- The control's top padding, used to determine the client area for children of this control. [grd_pt] -
pr- The control's right padding, used to determine the client area for children of this control. [grd_pr] -
pb- The control's bottom padding, used to determine the client area for children of this control. [grd_pb] -
active- A control is active by default, when false this control will not receive targeted events such as press/release/motion/touch events. [grd_active] -
hidden- The control's hidden state, when true a control will not be visible. [grd_hidden] -
clip_disabled- Enable/disable clipping for children of the control, default is false. [grd_clip_disabled] -
mask_enabled- Enable/disable the control's mask render extension, default is false. [grd_mask_enabled] -
opaque- Event opacity, when opaque, a control will not allow press/release/motion/touch events to propagate to objects behind it on-screen. [grd_opaque] -
findex- A control's focus index, used for focus-driven control navigation. [grd_findex] -
zindex- A control's z-index value which determines it's order among it's peers on its parent. [grd_zindex]
Direct access allows for both reading and writing of these properties through common Lua variable access/assignment.
Example:
local control = gredom.get_control("MyLayer.MyControl")
print("Old width", control.w)
control.w = 150
print("New width", control.w)
All of the above listed member variables have an equivalent get_ and set_ function available, should it be required. For convenience, any property in the above list can be accessed through a getter and setter method.
CONTROL:get_bounds()
Get the value of grd_x, grd_y, grd_width and grd_height for this control.
Returns: The grd_x value of this control The grd_y value of this control The grd_width value of this control The grd_height value of this control
CONTROL:get_layer()
Get the layer containing this control.
Returns:
gredom#layer The layer containing this control
CONTROL:get_layer_bounds()
Computes the layer-relative bounds for this control. Does not take layer scrolling offset into account. Layer relative bounds are the resolved bounds of each parent-control accumulated.
CONTROL:get_parent()
Get the parent object for this control.
Returns:
gredom#domobject The parent of this control, either a gredom#layer, gredom#group or gredom#control.
CONTROL:get_parent_bounds()
Computes the parent-relative bounds for this control. Parent relative bounds are equivalent to the resolved bounds of this control with the parent's padding applied.
CONTROL:get_position()
Get the value of grd_x and grd_y for this control.
Returns: The grd_x value of this control The grd_y value of this control
CONTROL:get_resolved_bounds()
Computes the resolved bounds for this control. The resolved bounds are the bounds of this control in the parent's coordinate system.
This is a combination of the fixed-position, fixed-size, scaled-position and scaled-size properties as follows:
-
The parent size is the resolved size of the parent, reduced by the parent's padding. The bounds for each parent are computed top-down in order to compute the resolved bounds.
resolved_x = x + (sx * parent_width)
resolved_y = y + (sy * parent_height)
resolved_width = w + (sw * parent_width)
resolved_height = h + (sh * parent_height)
-
Anchors define how the resolved position is adjusted according to the control’s bounds.
-
gre.LEFT and gre.TOP anchors will not affect the x/y position.
-
gre.CENTER anchors will adjust the x/y position by half the resolved width/height.
-
gre.RIGHT and gre.BOTTOM anchors will adjust the x/y position by the resolved width/height.
-
CONTROL:get_screen_bounds()
Computes the screen-relative bounds for this control. Screen relative bounds are equivalent to the layer-relative bounds with layer translation and layer scrolling offsets applied.
CONTROL:get_size()
Get the value of grd_width and grd_height for this control.
Returns: The grd_width value of this control The grd_height value of this control
CONTROL:set_bounds(
x,
y,
width,
height
)
Set the value of grd_x, grd_y, grd_width and grd_height for this control to the provided values.
Parameters: x An integer value to set to grd_x of this control y An integer value to set to grd_y of this control width An integer value to set to grd_width of this control height An integer value to set to grd_height of this control
CONTROL:set_position(
x,
y
)
Set the value of grd_x and grd_y for this control to the provided values.
Parameters: x An integer value to set to grd_x of this control y An integer value to set to grd_y of this control
CONTROL:set_size(
width,
height
)
Set the value of grd_width and grd_height for this control to the provided values.
Parameters: width An integer value to set to grd_width of this control height An integer value to set to grd_height of this control
CONTROL:clone(
new_object_name,
parent_name,
data
)
Create a new control (new_object_name), within an existing parent layer or group (parent_name) by copying all of the properties of this control. This new object will have all of the same actions, variables and it's current state will match the state of this control.
-
Controls and tables can be cloned into either layer or group parents as long as no name conflict exists.
The data argument is a table of properties that match the properties for that type of object as described in the gre.set_control_attrs or gre.set_table_attrs functions as applicable.
Parameters: new_object_name The name for the new object, this must be a unique name in the parents namespace parent_name The name of the layer or group to place this object within, this object must exist data Optional: A table containing control attribute tags as the keys with new values to be applied. Returns: A CONTROL object representing the newly created control.
CONTROL:delete()
Delete this control. This function only works on controls that were created as clones of other controls.
CONTROL:set_property(
index,
name,
value
)
Updates a render extension argument at runtime.
Multiple calls to CONTROL:set_property will trigger a single redraw event. The greconst Lua table contains constants for valid render extension argument names and should be used when passing the name parameter. These constants correspond to the argument names defined in the GAPP file XML.
Historically, render extension arguments could only be modified at runtime if they were bound to a Storyboard variable. This function removes that limitation by allowing arguments to be changed dynamically through Lua.
Because render extension arguments participate in Storyboard’s rendering pipeline, there is a trade-off between convenience and performance when using dynamically bound values.
Understanding how Storyboard determines when a screen becomes “dirty” helps clarify this trade-off.
CONTROL:set_property can be used to bind a render extension argument to a Storyboard Variable by passing a Storyboard data key as the value.
Any valid data key may be used including:
-
${app:key}
-
${screen:key}
-
${layer:key}
-
${parent:key}
-
${control:key}
If an argument is already bound to a variable, calling CONTROL:set_property with a literal value will unbind the variable and set the argument to that static value.
There is no CONTROL:get_property function. Render extension arguments are read-only, so any code that requires access to their current value must track it explicity in Lua.
Static render extension arguments incur no data resolution cost. Storyboard does not need to consult the Data Manager to determine whether their values have changed.
Dynamically bound arguments require additional processing:
-
The data key is resolved:
(e.g. ${control:alpha} → PopupLayer.WarningPopup.alpha).
-
The Data Manager is queried for the current value.
-
The value is compared against the previously cached value.
-
If the value has changed, the control is marked dirty and updatedBecause of this, dynamically bound arguments are more flexible but carry a higher runtime cost.
Because of this, dynamically bound arguments are more flexible but carry a higher runtime cost.
Parameters: index The render extension index, 0 to apply this change to all render extensions. Index 1 is furthest back. name The name of the render extension argument to modify. value The value to set the render exension argument to.