Appendix E. Standard Action Definitions

Table of Contents

Built-in Action Definitions
gra.screen
gra.screen.fade
gra.screen.hold
gra.screen.release
gra.sendevent
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.resource.dump_def
gra.playback
gra.capture
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.screen.glswitch
gra.screen.glrotate
gra.screen.glflip
gra.screen.gldoors
gra.screen.gltip
gra.screen.glcube
gra.screen.rotate
gra.screendump
gra.timer
gra.timer.stop
Media Actions

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

Send an event to the application's input event queue. This action is equivalent to injecting an event via Storyboard IO or using the Lua gre.send_event() API

The action arguments are:

event

The name of the event to send

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. If the control name is to be used instead of specific focus index value then this value should be set to -1 to avoid confusion about the intent of the action.

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 specified 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 -1 to have no minimum value

max

The maximum focus index to move to or -1 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 -1 to have no minimum value

max

The maximum focus index to move to or -1 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 -1 to have no minimum value

max

The maximum focus index to move to or -1 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.

Note

Only one table scroll animation can be run at a time. Storyboard Engine will cancel the currently running table scroll animation by snapping to the end of the animation and then it will trigger the new table scroll animation.

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. The option only ensures that the cell is visible and does not guarantee the cell will be at the top of the visible list.

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

gra.playback

This action is used to begin or to stop playback of a capture-playback file using the capture-playback plugin. The plugin currently only supports the playback of one file at a time.

The action arguments are:

Playback

True to begin playback

False to stop playback

Filename

The name of the file to playback

Loop

The number of times to loop playback

Quit

Send a quit message when finished

gra.capture

This action is used to begin or to stop capture of a capture-playback file using the capture-playback plugin. Only one capture-playback file may be captured at a time.

The action arguments are:

Capture

True to begin capture

False to stop capture

Filename

The name of the file to capture the events