src/cobalt/site/docs/reference/starboard/modules/10/event.md - cobalt.git - Git at Google

 ---
 layout: doc
 title: "Starboard Module Reference: event.h"
 ---

 Defines the event system that wraps the Starboard main loop and entry point.

 ## The Starboard Application Lifecycle ##

 ```
     ---------- *
    |           |
    |        Preload
    |           |
    |           V
  Start   [ PRELOADING ] ------------
    |           |                    |
    |         Start                  |
    |           |                    |
    |           V                    |
     ----> [ STARTED ] <----         |
                |           |        |
              Pause       Unpause    |
                |           |     Suspend
                V           |        |
     -----> [ PAUSED ] -----         |
    |           |                    |
 Resume      Suspend                 |
    |           |                    |
    |           V                    |
     ---- [ SUSPENDED ] <------------
                |
               Stop
                |
                V
           [ STOPPED ]

 ```

 The first event that a Starboard application receives is either `Start`
 (`kSbEventTypeStart`) or `Preload` (`kSbEventTypePreload`). `Start` puts the
 application in the `STARTED` state, whereas `Preload` puts the application in
 the `PRELOADING` state.

 `PRELOADING` can only happen as the first application state. In this state, the
 application should start and run as normal, but will not receive any input, and
 should not try to initialize graphics resources (via GL or `SbBlitter`). In
 `PRELOADING`, the application can receive `Start` or `Suspend` events. `Start`
 will receive the same data that was passed into `Preload`.

 In the `STARTED` state, the application is in the foreground and can expect to
 do all of the normal things it might want to do. Once in the `STARTED` state, it
 may receive a `Pause` event, putting the application into the `PAUSED` state.

 In the `PAUSED` state, the application is still visible, but has lost focus, or
 it is partially obscured by a modal dialog, or it is on its way to being shut
 down. The application should pause activity in this state. In this state, it can
 receive `Unpause` to be brought back to the foreground state (`STARTED`), or
 `Suspend` to be pushed further in the background to the `SUSPENDED` state.

 In the `SUSPENDED` state, the application is generally not visible. It should
 immediately release all graphics and video resources, and shut down all
 background activity (timers, rendering, etc). Additionally, the application
 should flush storage to ensure that if the application is killed, the storage
 will be up-to-date. The application may be killed at this point, but will
 ideally receive a `Stop` event for a more graceful shutdown.

 Note that the application is always expected to transition through `PAUSED` to
 `SUSPENDED` before receiving `Stop` or being killed.

 ## Enums ##

 ### SbEventType ###

 An enumeration of all possible event types dispatched directly by the system.
 Each event is accompanied by a void* data argument, and each event must define
 the type of the value pointed to by that data argument, if any.

 #### Values ####

 *   `kSbEventTypePreload`

     Applications should perform initialization and prepare to react to
     subsequent events, but must not initialize any graphics resources (through
     GL or SbBlitter). The intent of this event is to allow the application to do
     as much work as possible ahead of time, so that when the application is
     first brought to the foreground, it's as fast as a resume.

     The `kSbEventTypeStart` event may be sent at any time, regardless of
     initialization state. Input events will not be sent in the `PRELOADING`
     state. This event will only be sent once for a given process launch.
     SbEventStartData is passed as the data argument.

     The system may send `kSbEventTypeSuspend` in `PRELOADING` if it wants to
     push the app into a lower resource consumption state. Applications can alo
     call SbSystemRequestSuspend() when they are done preloading to request this.
 *   `kSbEventTypeStart`

     The first event that an application receives on startup when starting
     normally (i.e. not being preloaded). Applications should perform
     initialization, start running, and prepare to react to subsequent events.
     Applications that wish to run and then exit must call
     `SbSystemRequestStop()` to terminate. This event will only be sent once for
     a given process launch. `SbEventStartData` is passed as the data argument.
     In case of preload, the `SbEventStartData` will be the same as what was
     passed to `kSbEventTypePreload`.
 *   `kSbEventTypePause`

     A dialog will be raised or the application will otherwise be put into a
     background-but-visible or partially-obscured state (PAUSED). Graphics and
     video resources will still be available, but the application should pause
     foreground activity like animations and video playback. Can only be received
     after a Start event. The only events that should be dispatched after a Pause
     event are Unpause or Suspend. No data argument.
 *   `kSbEventTypeUnpause`

     The application is returning to the foreground (STARTED) after having been
     put in the PAUSED (e.g. partially-obscured) state. The application should
     unpause foreground activity like animations and video playback. Can only be
     received after a Pause or Resume event. No data argument.
 *   `kSbEventTypeSuspend`

     The operating system will put the application into a Suspended state after
     this event is handled. The application is expected to stop periodic
     background work, release ALL graphics and video resources, and flush any
     pending SbStorage writes. Some platforms will terminate the application if
     work is done or resources are retained after suspension. Can only be
     received after a Pause event. The only events that should be dispatched
     after a Suspend event are Resume or Stop. On some platforms, the process may
     also be killed after Suspend without a Stop event. No data argument.
 *   `kSbEventTypeResume`

     The operating system has restored the application to the PAUSED state from
     the SUSPENDED state. This is the first event the application will receive
     coming out of SUSPENDED, and it will only be received after a Suspend event.
     The application will now be in the PAUSED state. No data argument.
 *   `kSbEventTypeStop`

     The operating system will shut the application down entirely after this
     event is handled. Can only be recieved after a Suspend event, in the
     SUSPENDED state. No data argument.
 *   `kSbEventTypeInput`

     A user input event, including keyboard, mouse, gesture, or something else.
     SbInputData (from input.h) is passed as the data argument.
 *   `kSbEventTypeUser`

     A user change event, which means a new user signed-in or signed-out, or the
     current user changed. No data argument, call SbUserGetSignedIn() and
     SbUserGetCurrent() to get the latest changes.
 *   `kSbEventTypeLink`

     A navigational link has come from the system, and the application should
     consider handling it by navigating to the corresponding application
     location. The data argument is an application-specific, null-terminated
     string.
 *   `kSbEventTypeVerticalSync`

     The beginning of a vertical sync has been detected. This event is very
     timing-sensitive, so as little work as possible should be done on the main
     thread if the application wants to receive this event in a timely manner. No
     data argument.
 *   `kSbEventTypeNetworkDisconnect`

     The platform has detected a network disconnection. The platform should make
     a best effort to send an event of this type when the network disconnects,
     but there are likely to be cases where the platform cannot detect the
     disconnection (e.g. if the connection is via a powered hub which becomes
     disconnected), so the current network state cannot always be inferred from
     the sequence of Connect/Disconnect events.
 *   `kSbEventTypeNetworkConnect`

     The platform has detected a network connection. This event may be sent at
     application start-up, and should always be sent if the network reconnects
     since a disconnection event was sent.
 *   `kSbEventTypeScheduled`

     An event type reserved for scheduled callbacks. It will only be sent in
     response to an application call to SbEventSchedule(), and it will call the
     callback directly, so SbEventHandle should never receive this event
     directly. The data type is an internally-defined structure.
 *   `kSbEventTypeAccessiblitySettingsChanged`

     The platform's accessibility settings have changed. The application should
     query the accessibility settings using the appropriate APIs to get the new
     settings. Note this excludes captions settings changes, which causes
     kSbEventTypeAccessibilityCaptionSettingsChanged to fire.
 *   `kSbEventTypeLowMemory`

     An optional event that platforms may send to indicate that the application
     may soon be terminated (or crash) due to low memory availability. The
     application may respond by reducing memory consumption by running a Garbage
     Collection, flushing caches, or something similar. There is no requirement
     to respond to or handle this event, it is only advisory.
 *   `kSbEventTypeWindowSizeChanged`

     The size or position of a SbWindow has changed. The data is
     SbEventWindowSizeChangedData .
 *   `kSbEventTypeOnScreenKeyboardShown`

     The platform has shown the on screen keyboard. This event is triggered by
     the system or by the application's OnScreenKeyboard show method. The event
     has int data representing a ticket. The ticket is used by the application to
     mark individual calls to the show method as successfully completed. Events
     triggered by the application have tickets passed in via
     SbWindowShowOnScreenKeyboard. System-triggered events have ticket value
     kSbEventOnScreenKeyboardInvalidTicket.
 *   `kSbEventTypeOnScreenKeyboardHidden`

     The platform has hidden the on screen keyboard. This event is triggered by
     the system or by the application's OnScreenKeyboard hide method. The event
     has int data representing a ticket. The ticket is used by the application to
     mark individual calls to the hide method as successfully completed. Events
     triggered by the application have tickets passed in via
     SbWindowHideOnScreenKeyboard. System-triggered events have ticket value
     kSbEventOnScreenKeyboardInvalidTicket.
 *   `kSbEventTypeOnScreenKeyboardFocused`

     The platform has focused the on screen keyboard. This event is triggered by
     the system or by the application's OnScreenKeyboard focus method. The event
     has int data representing a ticket. The ticket is used by the application to
     mark individual calls to the focus method as successfully completed. Events
     triggered by the application have tickets passed in via
     SbWindowFocusOnScreenKeyboard. System-triggered events have ticket value
     kSbEventOnScreenKeyboardInvalidTicket.
 *   `kSbEventTypeOnScreenKeyboardBlurred`

     The platform has blurred the on screen keyboard. This event is triggered by
     the system or by the application's OnScreenKeyboard blur method. The event
     has int data representing a ticket. The ticket is used by the application to
     mark individual calls to the blur method as successfully completed. Events
     triggered by the application have tickets passed in via
     SbWindowBlurOnScreenKeyboard. System-triggered events have ticket value
     kSbEventOnScreenKeyboardInvalidTicket.
 *   `kSbEventTypeAccessibilityCaptionSettingsChanged`

     One or more of the fields returned by SbAccessibilityGetCaptionSettings has
     changed.

 ## Typedefs ##

 ### SbEventCallback ###

 A function that can be called back from the main Starboard event pump.

 #### Definition ####

 ```
 typedef void(* SbEventCallback) (void *context)
 ```

 ### SbEventDataDestructor ###

 A function that will cleanly destroy an event data instance of a specific type.

 #### Definition ####

 ```
 typedef void(* SbEventDataDestructor) (void *data)
 ```

 ### SbEventId ###

 An ID that can be used to refer to a scheduled event.

 #### Definition ####

 ```
 typedef uint32_t SbEventId
 ```

 ## Structs ##

 ### SbEvent ###

 Structure representing a Starboard event and its data.

 #### Members ####

 *   `SbEventType type`
 *   `void * data`

 ### SbEventStartData ###

 Event data for kSbEventTypeStart events.

 #### Members ####

 *   `char ** argument_values`

     The command-line argument values (argv).
 *   `int argument_count`

     The command-line argument count (argc).
 *   `const char * link`

     The startup link, if any.

 ### SbEventWindowSizeChangedData ###

 Event data for kSbEventTypeWindowSizeChanged events.

 #### Members ####

 *   `SbWindow window`
 *   `SbWindowSize size`

 ## Functions ##

 ### SbEventCancel ###

 Cancels the specified `event_id`. Note that this function is a no-op if the
 event already fired. This function can be safely called from any thread, but the
 only way to guarantee that the event does not run anyway is to call it from the
 main Starboard event loop thread.

 #### Declaration ####

 ```
 void SbEventCancel(SbEventId event_id)
 ```

 ### SbEventHandle ###

 The entry point that Starboard applications MUST implement. Any memory pointed
 at by `event` or the `data` field inside `event` is owned by the system, and
 that memory is reclaimed after this function returns, so the implementation must
 copy this data to extend its life. This behavior should also be assumed of all
 fields within the `data` object, unless otherwise explicitly specified.

 This function is only called from the main Starboard thread. There is no
 specification about what other work might happen on this thread, so the
 application should generally do as little work as possible on this thread, and
 just dispatch it over to another thread.

 #### Declaration ####

 ```
 SB_IMPORT void SbEventHandle(const SbEvent *event)
 ```

 ### SbEventIsIdValid ###

 Returns whether the given event handle is valid.

 #### Declaration ####

 ```
 static bool SbEventIsIdValid(SbEventId handle)
 ```

 ### SbEventSchedule ###

 Schedules an event `callback` into the main Starboard event loop. This function
 may be called from any thread, but `callback` is always called from the main
 Starboard thread, queued with other pending events.

 `callback`: The callback function to be called. `context`: The context that is
 passed to the `callback` function. `delay`: The minimum number of microseconds
 to wait before calling the `callback` function. Set `delay` to `0` to call the
 callback as soon as possible.

 #### Declaration ####

 ```
 SbEventId SbEventSchedule(SbEventCallback callback, void *context, SbTime delay)
 ```
	---
	layout: doc
	title: "Starboard Module Reference: event.h"
	---

	Defines the event system that wraps the Starboard main loop and entry point.

	## The Starboard Application Lifecycle ##

	```
	---------- *
	\| \|
	\| Preload
	\| \|
	\| V
	Start [ PRELOADING ] ------------
	\| \| \|
	\| Start \|
	\| \| \|
	\| V \|
	----> [ STARTED ] <---- \|
	\| \| \|
	Pause Unpause \|
	\| \| Suspend
	V \| \|
	-----> [ PAUSED ] ----- \|
	\| \| \|
	Resume Suspend \|
	\| \| \|
	\| V \|
	---- [ SUSPENDED ] <------------
	\|
	Stop
	\|
	V
	[ STOPPED ]

	```

	The first event that a Starboard application receives is either `Start`
	(`kSbEventTypeStart`) or `Preload` (`kSbEventTypePreload`). `Start` puts the
	application in the `STARTED` state, whereas `Preload` puts the application in
	the `PRELOADING` state.

	`PRELOADING` can only happen as the first application state. In this state, the
	application should start and run as normal, but will not receive any input, and
	should not try to initialize graphics resources (via GL or `SbBlitter`). In
	`PRELOADING`, the application can receive `Start` or `Suspend` events. `Start`
	will receive the same data that was passed into `Preload`.

	In the `STARTED` state, the application is in the foreground and can expect to
	do all of the normal things it might want to do. Once in the `STARTED` state, it
	may receive a `Pause` event, putting the application into the `PAUSED` state.

	In the `PAUSED` state, the application is still visible, but has lost focus, or
	it is partially obscured by a modal dialog, or it is on its way to being shut
	down. The application should pause activity in this state. In this state, it can
	receive `Unpause` to be brought back to the foreground state (`STARTED`), or
	`Suspend` to be pushed further in the background to the `SUSPENDED` state.

	In the `SUSPENDED` state, the application is generally not visible. It should
	immediately release all graphics and video resources, and shut down all
	background activity (timers, rendering, etc). Additionally, the application
	should flush storage to ensure that if the application is killed, the storage
	will be up-to-date. The application may be killed at this point, but will
	ideally receive a `Stop` event for a more graceful shutdown.

	Note that the application is always expected to transition through `PAUSED` to
	`SUSPENDED` before receiving `Stop` or being killed.

	## Enums ##

	### SbEventType ###

	An enumeration of all possible event types dispatched directly by the system.
	Each event is accompanied by a void* data argument, and each event must define
	the type of the value pointed to by that data argument, if any.

	#### Values ####

	* `kSbEventTypePreload`

	Applications should perform initialization and prepare to react to
	subsequent events, but must not initialize any graphics resources (through
	GL or SbBlitter). The intent of this event is to allow the application to do
	as much work as possible ahead of time, so that when the application is
	first brought to the foreground, it's as fast as a resume.

	The `kSbEventTypeStart` event may be sent at any time, regardless of
	initialization state. Input events will not be sent in the `PRELOADING`
	state. This event will only be sent once for a given process launch.
	SbEventStartData is passed as the data argument.

	The system may send `kSbEventTypeSuspend` in `PRELOADING` if it wants to
	push the app into a lower resource consumption state. Applications can alo
	call SbSystemRequestSuspend() when they are done preloading to request this.
	* `kSbEventTypeStart`

	The first event that an application receives on startup when starting
	normally (i.e. not being preloaded). Applications should perform
	initialization, start running, and prepare to react to subsequent events.
	Applications that wish to run and then exit must call
	`SbSystemRequestStop()` to terminate. This event will only be sent once for
	a given process launch. `SbEventStartData` is passed as the data argument.
	In case of preload, the `SbEventStartData` will be the same as what was
	passed to `kSbEventTypePreload`.
	* `kSbEventTypePause`

	A dialog will be raised or the application will otherwise be put into a
	background-but-visible or partially-obscured state (PAUSED). Graphics and
	video resources will still be available, but the application should pause
	foreground activity like animations and video playback. Can only be received
	after a Start event. The only events that should be dispatched after a Pause
	event are Unpause or Suspend. No data argument.
	* `kSbEventTypeUnpause`

	The application is returning to the foreground (STARTED) after having been
	put in the PAUSED (e.g. partially-obscured) state. The application should
	unpause foreground activity like animations and video playback. Can only be
	received after a Pause or Resume event. No data argument.
	* `kSbEventTypeSuspend`

	The operating system will put the application into a Suspended state after
	this event is handled. The application is expected to stop periodic
	background work, release ALL graphics and video resources, and flush any
	pending SbStorage writes. Some platforms will terminate the application if
	work is done or resources are retained after suspension. Can only be
	received after a Pause event. The only events that should be dispatched
	after a Suspend event are Resume or Stop. On some platforms, the process may
	also be killed after Suspend without a Stop event. No data argument.
	* `kSbEventTypeResume`

	The operating system has restored the application to the PAUSED state from
	the SUSPENDED state. This is the first event the application will receive
	coming out of SUSPENDED, and it will only be received after a Suspend event.
	The application will now be in the PAUSED state. No data argument.
	* `kSbEventTypeStop`

	The operating system will shut the application down entirely after this
	event is handled. Can only be recieved after a Suspend event, in the
	SUSPENDED state. No data argument.
	* `kSbEventTypeInput`

	A user input event, including keyboard, mouse, gesture, or something else.
	SbInputData (from input.h) is passed as the data argument.
	* `kSbEventTypeUser`

	A user change event, which means a new user signed-in or signed-out, or the
	current user changed. No data argument, call SbUserGetSignedIn() and
	SbUserGetCurrent() to get the latest changes.
	* `kSbEventTypeLink`

	A navigational link has come from the system, and the application should
	consider handling it by navigating to the corresponding application
	location. The data argument is an application-specific, null-terminated
	string.
	* `kSbEventTypeVerticalSync`

	The beginning of a vertical sync has been detected. This event is very
	timing-sensitive, so as little work as possible should be done on the main
	thread if the application wants to receive this event in a timely manner. No
	data argument.
	* `kSbEventTypeNetworkDisconnect`

	The platform has detected a network disconnection. The platform should make
	a best effort to send an event of this type when the network disconnects,
	but there are likely to be cases where the platform cannot detect the
	disconnection (e.g. if the connection is via a powered hub which becomes
	disconnected), so the current network state cannot always be inferred from
	the sequence of Connect/Disconnect events.
	* `kSbEventTypeNetworkConnect`

	The platform has detected a network connection. This event may be sent at
	application start-up, and should always be sent if the network reconnects
	since a disconnection event was sent.
	* `kSbEventTypeScheduled`

	An event type reserved for scheduled callbacks. It will only be sent in
	response to an application call to SbEventSchedule(), and it will call the
	callback directly, so SbEventHandle should never receive this event
	directly. The data type is an internally-defined structure.
	* `kSbEventTypeAccessiblitySettingsChanged`

	The platform's accessibility settings have changed. The application should
	query the accessibility settings using the appropriate APIs to get the new
	settings. Note this excludes captions settings changes, which causes
	kSbEventTypeAccessibilityCaptionSettingsChanged to fire.
	* `kSbEventTypeLowMemory`

	An optional event that platforms may send to indicate that the application
	may soon be terminated (or crash) due to low memory availability. The
	application may respond by reducing memory consumption by running a Garbage
	Collection, flushing caches, or something similar. There is no requirement
	to respond to or handle this event, it is only advisory.
	* `kSbEventTypeWindowSizeChanged`

	The size or position of a SbWindow has changed. The data is
	SbEventWindowSizeChangedData .
	* `kSbEventTypeOnScreenKeyboardShown`

	The platform has shown the on screen keyboard. This event is triggered by
	the system or by the application's OnScreenKeyboard show method. The event
	has int data representing a ticket. The ticket is used by the application to
	mark individual calls to the show method as successfully completed. Events
	triggered by the application have tickets passed in via
	SbWindowShowOnScreenKeyboard. System-triggered events have ticket value
	kSbEventOnScreenKeyboardInvalidTicket.
	* `kSbEventTypeOnScreenKeyboardHidden`

	The platform has hidden the on screen keyboard. This event is triggered by
	the system or by the application's OnScreenKeyboard hide method. The event
	has int data representing a ticket. The ticket is used by the application to
	mark individual calls to the hide method as successfully completed. Events
	triggered by the application have tickets passed in via
	SbWindowHideOnScreenKeyboard. System-triggered events have ticket value
	kSbEventOnScreenKeyboardInvalidTicket.
	* `kSbEventTypeOnScreenKeyboardFocused`

	The platform has focused the on screen keyboard. This event is triggered by
	the system or by the application's OnScreenKeyboard focus method. The event
	has int data representing a ticket. The ticket is used by the application to
	mark individual calls to the focus method as successfully completed. Events
	triggered by the application have tickets passed in via
	SbWindowFocusOnScreenKeyboard. System-triggered events have ticket value
	kSbEventOnScreenKeyboardInvalidTicket.
	* `kSbEventTypeOnScreenKeyboardBlurred`

	The platform has blurred the on screen keyboard. This event is triggered by
	the system or by the application's OnScreenKeyboard blur method. The event
	has int data representing a ticket. The ticket is used by the application to
	mark individual calls to the blur method as successfully completed. Events
	triggered by the application have tickets passed in via
	SbWindowBlurOnScreenKeyboard. System-triggered events have ticket value
	kSbEventOnScreenKeyboardInvalidTicket.
	* `kSbEventTypeAccessibilityCaptionSettingsChanged`

	One or more of the fields returned by SbAccessibilityGetCaptionSettings has
	changed.

	## Typedefs ##

	### SbEventCallback ###

	A function that can be called back from the main Starboard event pump.

	#### Definition ####

	```
	typedef void(* SbEventCallback) (void *context)
	```

	### SbEventDataDestructor ###

	A function that will cleanly destroy an event data instance of a specific type.

	#### Definition ####

	```
	typedef void(* SbEventDataDestructor) (void *data)
	```

	### SbEventId ###

	An ID that can be used to refer to a scheduled event.

	#### Definition ####

	```
	typedef uint32_t SbEventId
	```

	## Structs ##

	### SbEvent ###

	Structure representing a Starboard event and its data.

	#### Members ####

	* `SbEventType type`
	* `void * data`

	### SbEventStartData ###

	Event data for kSbEventTypeStart events.

	#### Members ####

	* `char ** argument_values`

	The command-line argument values (argv).
	* `int argument_count`

	The command-line argument count (argc).
	* `const char * link`

	The startup link, if any.

	### SbEventWindowSizeChangedData ###

	Event data for kSbEventTypeWindowSizeChanged events.

	#### Members ####

	* `SbWindow window`
	* `SbWindowSize size`

	## Functions ##

	### SbEventCancel ###

	Cancels the specified `event_id`. Note that this function is a no-op if the
	event already fired. This function can be safely called from any thread, but the
	only way to guarantee that the event does not run anyway is to call it from the
	main Starboard event loop thread.

	#### Declaration ####

	```
	void SbEventCancel(SbEventId event_id)
	```

	### SbEventHandle ###

	The entry point that Starboard applications MUST implement. Any memory pointed
	at by `event` or the `data` field inside `event` is owned by the system, and
	that memory is reclaimed after this function returns, so the implementation must
	copy this data to extend its life. This behavior should also be assumed of all
	fields within the `data` object, unless otherwise explicitly specified.

	This function is only called from the main Starboard thread. There is no
	specification about what other work might happen on this thread, so the
	application should generally do as little work as possible on this thread, and
	just dispatch it over to another thread.

	#### Declaration ####

	```
	SB_IMPORT void SbEventHandle(const SbEvent *event)
	```

	### SbEventIsIdValid ###

	Returns whether the given event handle is valid.

	#### Declaration ####

	```
	static bool SbEventIsIdValid(SbEventId handle)
	```

	### SbEventSchedule ###

	Schedules an event `callback` into the main Starboard event loop. This function
	may be called from any thread, but `callback` is always called from the main
	Starboard thread, queued with other pending events.

	`callback`: The callback function to be called. `context`: The context that is
	passed to the `callback` function. `delay`: The minimum number of microseconds
	to wait before calling the `callback` function. Set `delay` to `0` to call the
	callback as soon as possible.

	#### Declaration ####

	```
	SbEventId SbEventSchedule(SbEventCallback callback, void *context, SbTime delay)
	```