Chapter 5. Action Definitions

Table of Contents

Built-in Action Definitions
gra.screen
gra.screen.fade
gra.screen.hold
gra.screen.release
gra.datachange
gra.screen.focus.set
gra.screen.focus.next
gra.screen.focus.prev
gra.screen.focus.direction
gra.table.scroll
gra.table.resize
gra.table.navigate
gra.log
gra.control.zorder
gra.resource.dump_def
Plugin Action Definitions
gra.lua
gra.animate
gra.animate.stop
gra.audio
gra.greio
gra.perf_state
gra.redirect
gra.screen.path
gra.screen.scale
gra.screendump
gra.timer

Built-in Action Definitions

Storyboard supports a number of standard actions which are built-in to the framework.   These actions are all prefixed with gra. and can be incorporated into your application design without any plugin dependency.

gra.screen

Cause a screen transition to occur by replacing the current screen with the new one.

The action arguments are:

screen

The name of the screen to transition to.

gra.screen.fade

Causes a screen transition to occur by fading the old screen into the new one.

The action arguments are:

screen

The name of the screen to transition to.

rate

Defines how the alpha value will change over the transition:

linear
easein
easeout
easeinout
bounce

fps

The frames per second to use for the transition

duration

The duration of the transition in milliseconds

gra.screen.hold

Hold all screen updates.  While held a screen will not redraw.

gra.screen.release

Release a held screen.  If a screen was damaged during the period of time that the screen was being held, then a redraw action will be triggered.

gra.datachange

Change or create a variable value in the data manager.

The action arguments are key/value pairs such that the key is the fully qualified model path for the variable and the value is the new value to assign to that variable. For more information on creating the model paths, see the Data Variables section of this document.

gra.screen.focus.set

Set the focus to a specific control.

The action arguments are:

index

The focus index to set the focus to.

control

The name of a control to set the focus to.

Only one of either the index or the control need to be provided for this action. If both arguments are set, then the index value will be used.

In order for this action to complete successfully, the control sepecified must be set as focusable. For more information about making controls focusable and the focus operation in Storyboard, refer to the Focus section in the Execution Pipeline part of this document.

gra.screen.focus.next

Move the current focus to the next focusable control.

The action arguments are:

min

The minimum focus index to move to or 0 to have no minimum value

max

The maximum focus index to move to or 0 to have no maximum value

In order for this action to complete successfully, there must be a control whose focus index lies between the min and max values. For more information about making controls focusable and the focus operation in Storyboard, refer to the Focus section in the Execution Pipeline part of this document.

gra.screen.focus.prev

Move the current focus to the previous focusable control.

The action arguments are:

min

The minimum focus index to move to or 0 to have no minimum value

max

The maximum focus index to move to or 0 to have no maximum value

In order for this action to complete successfully, there must be a control whose focus index lies between the min and max values. For more information about making controls focusable and the focus operation in Storyboard, refer to the Focus section in the Execution Pipeline part of this document.

gra.screen.focus.direction

Move the current focus to the next control in a direction.

The action arguments are:

min

The minimum focus index to move to or 0 to have no minimum value

max

The maximum focus index to move to or 0 to have no maximum value

direction

The direction to search for the next focusable control

up
down
left
right

In order for this action to complete successfully, there must be a control whose focus index lies between the min and max values. For more information about making controls focusable and the focus operation in Storyboard, refer to the Focus section in the Execution Pipeline part of this document.

gra.table.scroll

Scroll the content of one or more tables.

The action arguments are:

control

The name of the table control to scroll. May be a comma separated list if multiple tables are specified.

row

The absolute 1 based row to start the scroll from. The default, 0, indicates that scrolling should start from the current row

col

The absolute 1 based column to start the scroll from. The default, 0, indicates that scrolling should start from the current column

delta_row

The number of rows to move. A positive value moves the table down a negative value moves the table up

delta_col

The number of columns to move. A positive value moves the table right a negative value moves the table left

fps

The frames per second rate at which to scroll the table.

duration

The duration in milliseconds to run the scroll over.

gra.table.resize

Set the number of rows and columns for a table. This action does not resize the control, simply the number of cells contained within the virtual table.

The action arguments are:

control

The name of the table control to resize.

rows

The number of rows for the table. Specifying 0 will leave the current number of rows unchanged.

columns

The number of columns for the table. Specifying 0 will leave the current number of columns unchanged.

When the table is resized, a gre.table.resize event will be emitted.

gra.table.navigate

Navigates the cells of a table, sets the active cell which in turn generates the cell focus events.  If the new active cell is not visible the table will be scrolled in order to show this cell.

The action arguments are:

control

The name of the table control to scroll. May be a comma separated list if multiple tables are specified.

fps

The frames per second rate at which to scroll the table, 0 performs an immediate scroll.

duration

The duration in milliseconds to run the scroll over, 0 scrolls it immediately.

direction

The type of navigation to perform

set

Sets the active row and column to what is specified in the row/col parameters

next

Move to the next cell, scroll by column then by row

prev

Move to the previous cell, scroll by column then by row

up

Move to the cell above the current one

down

Move to the cell below the current one

left

Move to the cell to the left of the current one

right

Move to the cell to the right of the current one

home

Move to the first cell in the table at row,column 1,1

end

Move to the last cell in the table

row

The row to navigate to. This is only used if direction is assigned set

col

The column to navigate to. This is only used if direction is assigned set

gra.log

Use the GRE logging mechanism to output a message.

The action argument is the string message that should be output.

gra.control.zorder

Move a control forward or back in the control z-order heiarchy within its layer. If the direction is backward or forward then the control moves in that direction one level. If the direction is toback or tofront then the control moves relative to the reference control

The action arguments are:

control

The name of the control whose z-order is to be changed.

reference

The name of a reference control. Used only when direction is tofront or toback.

direction

The z-order direction to move the control.

tofront

Move in front of reference control, if no reference control is specified then move to front of all other controls on the control's layer

toback

Move in back of reference control, if no reference control then move to back of all other controls

forward

Move one control forward towards the top of the z-order

backward

Move one control backward towards the back of the z-order

gra.resource.dump_def

Remove a resource which is managed by the resource manager.

The action arguments are:

pool

The pool name containing the resource to dump

ref

The name of the resource to dump

The currently defined resource pools are image containing all of the images and font containing all of the fonts associated with the Storybard application.