Chapter 5. Event Definitions

Table of Contents

Standard Event Definitions
System Events
Pointer Events
Keyboard Events
Screen Manager Events
Focus Events
Table Events
Table Scroll Events
Layer Scroll Events
Mobile Events (Android and iOS)
Android Events
Windows Embedded Compact 2013 (WEC2013) Events
Plugin Specific Event Definitions
gre.gesture.up
gre.gesture.down
gre.gesture.left
gre.gesture.right
gre.screendump.complete
timer.[name] Timer Events
gre.animate.complete.[name] Animation Events
gre.rendermgr.error

Standard Event Definitions

Storyboard supports a list of standard events.  These events are all prefixed with gre. and can be used by your application.  

System Events

gre.init

The system has been initialized and is ready.  This is the first event set in the system.

Data:

        No data payload

gre.quit

The system is being shutdown.

Data:

        No data payload

gre.redraw

An area of the screen has been damaged (visible data has changed). A redraw event may not cause actual screen drawing if the control which has changed is hidden or offscreen.

Data:

int32_t   x
int32_t   y
int32_t   width
int32_t   height
                    

If the values are all 0 then the entire screen has been damaged

Pointer Events

The following events are generated in response to a device such as a mouse or a touchscreen.  These events are targeted at specific controls based upon the controls location and sensitivity.

gre.press

A mouse/touchscreen has been pressed.

Data

uint32_t    button
uint32_t    timestamp
int16_t     subtype
int16_t     x
int16_t     y
int16_t     z
int16_t		id
int16_t		spare
                    

Where:

button
GR_EVENT_BTN_LEFT - 0x0001: if this is a touchscreen then the button is always left
GR_EVENT_BTN_MIDDLE - 0x0002
GR_EVENT_BTN_RIGHT - 0x0004
timestamp

This is an event timestamp in milliseconds since application start

subtype
GR_EVENT_RELEASE_IN
GR_EVENT_RELEASE_OUT
z

This parameter is dependent on the availability of z- co-ordinate information

id

This parameter is used to track multi-touch presses as they come in

spare

This is padding and should be 0

gre.release

A mouse/touchscreen has been released.

Data

uint32_t    button
uint32_t    timestamp
int16_t     subtype
int16_t     x
int16_t     y
int16_t     z
int16_t		id
int16_t		spare
                    

Where:

button
GR_EVENT_BTN_LEFT - 0x0001: if this is a touchscreen then the button is always left
GR_EVENT_BTN_MIDDLE - 0x0002
GR_EVENT_BTN_RIGHT - 0x0004
timestamp

This is an event timestamp in milliseconds since application start

subtype
GR_EVENT_RELEASE_IN
GR_EVENT_RELEASE_OUT
z

This parameter is dependent on the availability of z- co-ordinate information

id

This parameter is used to track multi-touch presses as they come in

spare

This is padding and should be 0

gre.touch

If a mouse/touchscreen presses and then releases on the same control then a touch event will be generated.  This is useful for activating button style elements.  If the release is found to intersect a different control then a touch event is not generated.

Note

This event is synthetically generated by the framework based on incoming gre.press and gre.release events. Event redirectors should generally not include this event in their list of redirection events.

Data

uint32_t    button
uint32_t    timestamp
int16_t     subtype
int16_t     x
int16_t     y
int16_t     z
int16_t		id
int16_t		spare
                    

Where:

button
GR_EVENT_BTN_LEFT - 0x0001: if this is a touchscreen then the button is always left
GR_EVENT_BTN_MIDDLE - 0x0002
GR_EVENT_BTN_RIGHT - 0x0004
timestamp

This is an event timestamp in milliseconds since application start

subtype
GR_EVENT_RELEASE_IN
GR_EVENT_RELEASE_OUT
z

This parameter is dependent on the availability of z- co-ordinate information

id

This parameter is used to track multi-touch presses as they come in

spare

This is padding and should be 0

gre.mtpress

A touchscreen has been pressed. This event is emitted where are two or more contact points.

Data

uint32_t    button
uint32_t    timestamp
int16_t     subtype
int16_t     x
int16_t     y
int16_t     z
int16_t		id
int16_t		spare
                    

Where:

button
GR_EVENT_BTN_LEFT - 0x0001: if this is a touchscreen then the button is always left
GR_EVENT_BTN_MIDDLE - 0x0002
GR_EVENT_BTN_RIGHT - 0x0004
timestamp

This is an event timestamp in milliseconds since application start

subtype
GR_EVENT_RELEASE_IN
GR_EVENT_RELEASE_OUT
z

This parameter is dependent on the availability of z- co-ordinate information

id

This parameter is used to track multi-touch presses as they come in

spare

This is padding and should be 0

gre.mtrelease

A touchscreen has been released. This event is emitted when there are two or more contact points.

Data

uint32_t    button
uint32_t    timestamp
int16_t     subtype
int16_t     x
int16_t     y
int16_t     z
int16_t		id
int16_t		spare
                    

Where:

button
GR_EVENT_BTN_LEFT - 0x0001: if this is a touchscreen then the button is always left
GR_EVENT_BTN_MIDDLE - 0x0002
GR_EVENT_BTN_RIGHT - 0x0004
timestamp

This is an event timestamp in milliseconds since application start

subtype
GR_EVENT_RELEASE_IN
GR_EVENT_RELEASE_OUT
z

This parameter is dependent on the availability of z- co-ordinate information

id

This parameter is used to track multi-touch presses as they come in

spare

This is padding and should be 0

gre.inbound

A mouse/touchscreen has entered a control (if dragging a pointer or finger).  This event is generated once the coordinates enter a control boundary.  If mouse motion events are disabled in the render manager then this event will not be generated.

Note

Control groups can not receive inbound events.

Data

uint32_t    button
uint32_t    timestamp
int16_t     subtype
int16_t     x
int16_t     y
int16_t     z
int16_t		id
int16_t		spare
                    

Where:

button
GR_EVENT_BTN_LEFT - 0x0001: if this is a touchscreen then the button is always left
GR_EVENT_BTN_MIDDLE - 0x0002
GR_EVENT_BTN_RIGHT - 0x0004
timestamp

This is an event timestamp in milliseconds since application start

subtype
GR_EVENT_RELEASE_IN
GR_EVENT_RELEASE_OUT
z

This parameter is dependent on the availability of z- co-ordinate information

id

This parameter is used to track multi-touch presses as they come in

spare

This is padding and should be 0

gre.outbound

A mouse/touchscreen has left a control (if dragging a pointer or finger).  This event is generated once the coordinates leave a control boundary.  If mouse motion events are disabled in the render manager then this event will not be generated.

Note

Control groups can not receive outbound events.

Data

uint32_t    button
uint32_t    timestamp
int16_t     subtype
int16_t     x
int16_t     y
int16_t     z
int16_t		id
int16_t		spare
                    

Where:

button
GR_EVENT_BTN_LEFT - 0x0001: if this is a touchscreen then the button is always left
GR_EVENT_BTN_MIDDLE - 0x0002
GR_EVENT_BTN_RIGHT - 0x0004
timestamp

This is an event timestamp in milliseconds since application start

subtype
GR_EVENT_RELEASE_IN
GR_EVENT_RELEASE_OUT
z

This parameter is dependent on the availability of z- co-ordinate information

id

This parameter is used to track multi-touch presses as they come in

spare

This is padding and should be 0

Keyboard Events

The following events are generated if a keyboard is present and supported by the render manager.

gre.keydown

A key is in the pressed state

Data

uint32_t    code
uint32_t    modifiers
                    

Where:

code

This is the UTF-8 key value

modifiers

A set of modifiers applied to the key

GR_EVENT_KEYMOD_ALT
GR_EVENT_KEYMOD_CTRL
GR_EVENT_KEYMOD_SHIFT

gre.keyup

A key which was previously pressed has been released

Data

uint32_t    code
uint32_t    modifiers
                    

Where:

code

This is the UTF-8 key value

modifiers

A set of modifiers applied to the key

GR_EVENT_KEYMOD_ALT
GR_EVENT_KEYMOD_CTRL
GR_EVENT_KEYMOD_SHIFT

Screen Manager Events

The following events are generated by the Screen Manager during screen transitions.  These events are generated in the following order:

gre.screenshow.pre delivered to target (end) screen
gre.screenhide.pre delivered to source (start) screen
gre.screenshow.post delivered to target (end) screen
gre.screenhide.post delivered to source (start) screen

gre.screenshow.pre

A screen is being shown.  This event is triggered before the screen is shown and signifies that a transition may be starting

Data:

char *name

The name of the screen which is being shown

gre.screenshow.post

A screen has been shown.  This event is triggered after the screen is shown and signifies that a transition has ended.

Data:

char *name

The name of the screen which has been shown

gre.screenhide.pre

A screen is being hidden.  This event is triggered before the screen is hidden and signifies that a transition may be starting.

Data:

char *name

The name of the screen which is being hidden

gre.screenhide.post

A screen has been hidden.  This event is triggered after the screen is hidden and signifies that a transition has ended.

Data:

char *name

The name of the screen which has been hidden

Focus Events

The following events are generated on a change of control focus.  If there is no focusable control on the current screen then these events will not be generated.  These events are targeted at the currently or last focused control.  When focus shifts from one control to another the lost focus event is sent first followed by the got focus event.

gre.gotfocus

A control has received focus, delivered to the control that received the focus.

No data payload.

gre.lostfocus

A control has lost focus, delivered to the control that has lost the focus.

No data payload.

Table Events

The following events are generated by a Table control.  If no table control is present then these events will not be generated.

gre.table.viewport

A table has been resized via the table resize action.  This event notifies the system of the new table size and visible area.

Data:

uint32_t    top_row
uint32_t    left_col
uint32_t    bot_row;
uint32_t    right_col;
char        *table
                    

Where:

top_row

The top row that is visible

left_col

The left column that is visible

bot_row

The bottom row that is visible

right_col

The right column that is visible

table

The name of the table whose viewport changed to cause this event

gre.cell.gotfocus

A table cell has received focus and is the currently active cell. This is delivered to the control template with the cell focus information.

Data:

uint32_t    row;
uint32_t    col;
char *table
                    

Where:

row

The row that received focus

col

The column that received focus

table

The name of the table where the cell focus changed

gre.cell.lostfocus

A table cell has lost focus and is no longer the active cell. This is delivered to the control template with the cell focus information

Data:

uint32_t    row;
uint32_t    col;
char *table
                    

Where:

row

The row that received focus

col

The column that received focus

table

The name of the table where the cell focus changed

Table Scroll Events

The following events are only generated when the "Enable list scrolling behaviour" option is checked in the Table properties.

gre.table.drag_start

This event is generated when a user begins dragging a scrolling table.

Data:

        No data payload

gre.table.drag_stop

This event is generated when a user stops dragging a scrolling table.

Data:

        No data payload

gre.table.scroll_start

This event is generated when the scroll animation begins.

Data:

        No data payload

gre.table.scroll_stop

This event is generated when the scroll animation completes.

Data:

        No data payload

gre.table.scroll_cancel

This event is generated when the scroll animation is interrupted.

Data:

        No data payload

Layer Scroll Events

The following events are only generated when the "Enable layer scrolling behaviour" option is checked in the Layer Scrolling properties.

gre.drag.start

This event is generated when a user begins dragging a scrolling layer.

Data:

        The name of the object being scrolled

gre.drag.stop

This event is generated when a user stops dragging a scrolling layer.

Data:

        The name of the object being scrolled

gre.scroll.start

This event is generated when the scroll animation begins.

Data:

        The name of the object being scrolled

gre.scroll.stop

This event is generated when the scroll animation completes.

Data:

        The name of the object being scrolled

gre.scroll.cancel

This event is generated when the scroll animation is interrupted.

Data:

        The name of the object being scrolled

Mobile Events (Android and iOS)

The following events are only generated when running on Android and iOS.

gre.mobile.on_pause

The application has become inactive. The application will not be rendering to the screen after this event is received.

Data:

        No data payload

gre.mobile.on_resume

The application has become active. The application will be rendering to the screen after this event is received.

Data:

        No data payload

gre.mobile.on_background

The application has lost focus.

Data:

        No data payload

Android Events

The following event is only generated when running on Android.

android.onBack

The back button on the Android application has been pressed.

Data:

        No data payload

Windows Embedded Compact 2013 (WEC2013) Events

Limited gestures support has been added to the winevent plugin for the Windows Embedded Compact 2013 platform. This support has been added via the Storyboard Engine winevent plugin (libgre-plugin-winevent.dll) and this plugin must be included in Storyboard Engine distribution.

The gesture support is designed to make visible the internal Windows gesture events and payloads that are generated from the underlying system as described in this document: https://msdn.microsoft.com/en-us/library/ee503599.aspx

As of the Storyboard 4.2 release, only the GID_PAN and GID_SCROLL sub-category of WM_GESTURE gesture events are translated into corresponding Storyboard events. These events will only be generated on WEC2013 hardware platforms where the BSP has been configured with gesture event support and the touchscreen driver configured to enable such event generation.

In order to add application support for receiving these win.gesture events, the events must be added to the Storyboard Designer application. The events can be added in the same manner as any other user defined events are added at the point where they are used to trigger an action within the "New Action" dialog.

win.gesture.pinch

This event is generated in response to the Windows MW_GESTURE:GID_PAN event. The event data is taken directly from the Windows event.

Data: (4s1 x 4s1 y 4s1 spread)

int32_t x
int32_t y
int32_t spread
                        

win.gesture.[up|down|left|right|unknown]

This event is generated in response to the Windows MW_GESTURE:GID_SCROLL event. The event data is taken directly from the Windows event.

Data: (4s1 velocity 4s1 angle)

int32_t velocity
int32_t angle