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

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

 API to allow applications to take advantage of the platform's native UI engine.
 This is mainly to drive the animation of visual elements and to signal which of
 those elements have focus. The implementation should not render any visual
 elements; instead, it will be used to guide the app in where these elements
 should be drawn.

 When the application creates the user interface, it will create SbUiNavItems for
 interactable elements. Additionally, the app must specify the position and size
 of these navigation items. As the app's user interface changes, it will create
 and destroy navigation items as appropriate.

 For each render frame, the app will query the local transform for each
 SbUiNavItem in case the native UI engine moves individual items in response to
 user interaction. If the navigation item is a container, then the content offset
 will also be queried to determine the placement of its content items.

 ## Macros ##

 ### kSbUiNavItemInvalid ###

 Well-defined value for an invalid navigation item.

 ## Enums ##

 ### SbUiNavItemType ###

 Navigation items may be one of the following types. This must be specified upon
 item creation and may not change during the item's lifespan.

 #### Values ####

 *   `kSbUiNavItemTypeFocus`

     This is a single focusable item.
 *   `kSbUiNavItemTypeContainer`

     This is a container of navigation items which can also be containers
     themselves or focusable items. Containers themselves cannot be focused.

 ## Typedefs ##

 ### SbUiNavItem ###

 An opaque handle to an implementation-private structure representing a
 navigation item.

 #### Definition ####

 ```
 typedef struct SbUiNavItemPrivate* SbUiNavItem
 ```

 ## Structs ##

 ### SbUiNavCallbacks ###

 This structure specifies all the callbacks which the platform UI engine should
 invoke for various interaction events on navigation items. These callbacks may
 be invoked from any thread at any frequency. The `callback_context` is the value
 that was passed on creation of the relevant SbUiNavItem.

 #### Members ####

 *   ` onblur`

     void (\*onblur)(SbUiNavItem item, void\* callback_context);

     Invoke when an item has lost focus. This is only used with focus items.
 *   ` onfocus`

     void (\*onfocus)(SbUiNavItem item, void\* callback_context);

     Invoke when an item has gained focus. This is only used with focus items.
 *   ` onscroll`

     void (\*onscroll)(SbUiNavItem item, void\* callback_context);

     Invoke when an item's content offset is changed. This is only used with
     container items.

 ### SbUiNavInterface ###

 This structure declares the interface to the UI navigation implementation. All
 function pointers must be specified if the platform supports UI navigation.

 #### Members ####

 *   ` create_item`

     SbUiNavItem (\*create_item)(SbUiNavItemType type, const SbUiNavCallbacks \*
     callbacks, void\* callback_context);

     Create a new navigation item. When the user interacts with this item the
     appropriate SbUiNavCallbacks function will be invoked with the provided
     `callback_context`. An item is not interactable until it is enabled.
 *   ` destroy_item`

     void (\*destroy_item)(SbUiNavItem item);

     Destroy the given navigation item. If this is a content of another item,
     then it will first be unregistered. Additionally, if this item contains
     other items, then those will be unregistered as well, but they will not be
     automatically destroyed.
 *   ` set_focus`

     void (\*set_focus)(SbUiNavItem item);

     This is used to manually force focus on a navigation item of type
     kSbUiNavItemTypeFocus. Any previously focused navigation item should receive
     the blur event. If the item is not transitively a content of the root item,
     then this does nothing.
 *   ` set_item_enabled`

     void (\*set_item_enabled)(SbUiNavItem item, bool enabled);

     This is used to enable or disable user interaction with the specified
     navigation item. All navigation items are disabled when created, and they
     must be explicitly enabled to allow user interaction. If a container is
     disabled, then all of its contents are not interactable even though they
     remain enabled. If `enabled` is false, it must be guaranteed that once this
     function returns, no callbacks associated with this item will be invoked
     until the item is re-enabled.
 *   ` set_item_dir`

     void (\*set_item_dir)(SbUiNavItem item, SbUiNavItemDir dir);

     This specifies directionality for container items. Containers within
     containers do not inherit directionality. Directionality must be specified
     for each container explicitly.
 *   ` set_item_size`

     void (\*set_item_size)(SbUiNavItem item, float width, float height);

     Set the interactable size of the specified navigation item. By default, an
     item's size is (0,0).
 *   ` set_item_transform`

     void (\*set_item_transform)(SbUiNavItem item, const SbUiNavMatrix2x3 \*
     transform);

     Set the transform for the navigation item and its contents if the item is a
     container. This specifies the placement of the item's center within its
     container. The transform origin is the center of the item. Distance is
     measured in pixels with the origin being the top-left of the item's
     container. By default, an item's transform is identity.
 *   ` get_item_focus_transform`

     bool (\*get_item_focus_transform)(SbUiNavItem item, SbUiNavMatrix4 \*
     out_transform);

     Retrieve the focus transform matrix for the navigation item. The UI engine
     may translate, rotate, and/or tilt focus items to reflect user interaction.
     This transform should be multiplied with the item's transform to get its
     position inside its container. The transform origin is the center of the
     item. Return false if the item position should not be changed (i.e. the
     transform should be treated as identity).
 *   ` get_item_focus_vector`

     bool (\*get_item_focus_vector)(SbUiNavItem item, float\* out_x, float\*
     out_y);

     Retrieve a vector representing the focus location within a focused item.
     This is used to provide feedback about user input that is too small to
     result in a focus change. If there is no focus vector for the navigation
     item, then return false and leave `out_x` and `out_y` unchanged. Otherwise,
     return true and set the output values in the range of [-1, +1] with (out_x,
     out_y) of (-1, -1) being the top-left corner of the navigation item and (0,
     0) being the center.
 *   ` set_item_container_window`

     void (\*set_item_container_window)(SbUiNavItem item, SbWindow window);

     This attaches the given navigation item (which must be a container) to the
     specified window. Navigation items are only interactable if they are
     transitively attached to a window.

     A navigation item may only have a SbUiNavItem or SbWindow as its direct
     container. The navigation item hierarchy is established using
     set_item_container_item() with the root container attached to a SbWindow
     using set_item_container_window() to enable interaction with all enabled
     items in the hierarchy.

     If `item` is already registered with a different window, then this will
     unregister it from that window then attach it to the given `window`. It is
     an error to register more than one navigation item with any given window. If
     `window` is kSbWindowInvalid, then this will unregister the `item` from its
     current window if any. Upon destruction of `item` or `window`, the `item` is
     automatically unregistered from the `window`.
 *   ` set_item_container_item`

     void (\*set_item_container_item)(SbUiNavItem item, SbUiNavItem container);

     A container navigation item may contain other navigation items. However, it
     is an error to have circular containment or for `container` to not be of
     type kSbUiNavItemTypeContainer. If `item` already has a different container,
     then this first severs that connection. If `container` is
     kSbUiNavItemInvalid, then this removes `item` from its current container.
     Upon destruction of `item` or `container`, the `item` is automatically
     removed from the `container`.

     The position of items within a container are specified relative to the
     container's position. The position of these content items are further
     modified by the container's "content offset".

     For example, consider item A with position (5,5) and content offset (0,0).
     Given item B with position (10,10) is registered as a content of item A.

     1) Item B should be drawn at position (15,15).

     2) If item A's content offset is changed to (10,0), then item B should be
     drawn at position (5,15).

     Essentially, content items should be drawn at: [container position] +
     [content position] - [container content offset]
 *   ` set_item_content_offset`

     void (\*set_item_content_offset)(SbUiNavItem item, float content_offset_x,
     float content_offset_y);

     Set the current content offset for the given container. This may be used to
     force scrolling to make certain content items visible. A container item's
     content offset helps determine where its content items should be drawn.
     Essentially, a content item should be drawn at: [container position] +
     [content position] - [container content offset] If `item` is not a
     container, then this does nothing. By default, the content offset is (0,0).
 *   ` get_item_content_offset`

     void (\*get_item_content_offset)(SbUiNavItem item, float\*
     out_content_offset_x, float\* out_content_offset_y);

     Retrieve the current content offset for the navigation item. If `item` is
     not a container, then the content offset is (0,0).

 ### SbUiNavItemDir ###

 Navigation items of type kSbUiNavItemTypeContainer have directionality. If
 directionality is not specified for a container, it should default to left-to-
 right and top-to-bottom.

 For left-to-right, content offset x = 0 shows the leftmost content. `< –
 Container Size-->` +----------------- – +----------------- – +-----------------
 – + ` Not selectable. ` Selectable. ` Selectable. ` ` Offscreen. ` Onscreen. `
 Offscreen. ` ` Negative position. ` Positive position. ` Positive position. `
 +----------------- – +----------------- – +----------------- – + ^ Content
 Offset X = 0.

 For right-to-left, content offset x = 0 shows the rightmost content. `< –
 Container Size-->` +----------------- – +----------------- – +-----------------
 – + ` Selectable. ` Selectable. ` Not selectable. ` ` Offscreen. ` Onscreen. `
 Offscreen. ` ` Negative position. ` Positive position. ` Positive position. `
 +----------------- – +----------------- – +----------------- – + ^ Content
 Offset X = 0.

 Top-to-bottom is similar to left-to-right, but for the Y position. Bottom-to-top
 is similar to right-to-left, but for the Y position.

 #### Members ####

 *   `bool is_left_to_right`
 *   `bool is_top_to_bottom`

 ### SbUiNavMatrix2x3 ###

 This represents a 2x3 transform matrix in row-major order. ` a b tx ` ` c d ty `

 #### Members ####

 *   `float m`

 ### SbUiNavMatrix4 ###

 This represents a 4x4 transform matrix in row-major order.

 #### Members ####

 *   `float m`

 ## Functions ##

 ### SbUiNavGetInterface ###

 Retrieve the platform's UI navigation implementation. If the platform does not
 provide one, then return false without modifying `out_interface`. Otherwise,
 initialize all members of `out_interface` and return true.

 #### Declaration ####

 ```
 bool SbUiNavGetInterface(SbUiNavInterface *out_interface)
 ```

 ### SbUiNavItemIsValid ###

 Returns whether the given navigation item handle is valid.

 #### Declaration ####

 ```
 static bool SbUiNavItemIsValid(SbUiNavItem item)
 ```
	---
	layout: doc
	title: "Starboard Module Reference: ui_navigation.h"
	---

	API to allow applications to take advantage of the platform's native UI engine.
	This is mainly to drive the animation of visual elements and to signal which of
	those elements have focus. The implementation should not render any visual
	elements; instead, it will be used to guide the app in where these elements
	should be drawn.

	When the application creates the user interface, it will create SbUiNavItems for
	interactable elements. Additionally, the app must specify the position and size
	of these navigation items. As the app's user interface changes, it will create
	and destroy navigation items as appropriate.

	For each render frame, the app will query the local transform for each
	SbUiNavItem in case the native UI engine moves individual items in response to
	user interaction. If the navigation item is a container, then the content offset
	will also be queried to determine the placement of its content items.

	## Macros ##

	### kSbUiNavItemInvalid ###

	Well-defined value for an invalid navigation item.

	## Enums ##

	### SbUiNavItemType ###

	Navigation items may be one of the following types. This must be specified upon
	item creation and may not change during the item's lifespan.

	#### Values ####

	* `kSbUiNavItemTypeFocus`

	This is a single focusable item.
	* `kSbUiNavItemTypeContainer`

	This is a container of navigation items which can also be containers
	themselves or focusable items. Containers themselves cannot be focused.

	## Typedefs ##

	### SbUiNavItem ###

	An opaque handle to an implementation-private structure representing a
	navigation item.

	#### Definition ####

	```
	typedef struct SbUiNavItemPrivate* SbUiNavItem
	```

	## Structs ##

	### SbUiNavCallbacks ###

	This structure specifies all the callbacks which the platform UI engine should
	invoke for various interaction events on navigation items. These callbacks may
	be invoked from any thread at any frequency. The `callback_context` is the value
	that was passed on creation of the relevant SbUiNavItem.

	#### Members ####

	* ` onblur`

	void (\onblur)(SbUiNavItem item, void\ callback_context);

	Invoke when an item has lost focus. This is only used with focus items.
	* ` onfocus`

	void (\onfocus)(SbUiNavItem item, void\ callback_context);

	Invoke when an item has gained focus. This is only used with focus items.
	* ` onscroll`

	void (\onscroll)(SbUiNavItem item, void\ callback_context);

	Invoke when an item's content offset is changed. This is only used with
	container items.

	### SbUiNavInterface ###

	This structure declares the interface to the UI navigation implementation. All
	function pointers must be specified if the platform supports UI navigation.

	#### Members ####

	* ` create_item`

	SbUiNavItem (\create_item)(SbUiNavItemType type, const SbUiNavCallbacks \
	callbacks, void\* callback_context);

	Create a new navigation item. When the user interacts with this item the
	appropriate SbUiNavCallbacks function will be invoked with the provided
	`callback_context`. An item is not interactable until it is enabled.
	* ` destroy_item`

	void (\*destroy_item)(SbUiNavItem item);

	Destroy the given navigation item. If this is a content of another item,
	then it will first be unregistered. Additionally, if this item contains
	other items, then those will be unregistered as well, but they will not be
	automatically destroyed.
	* ` set_focus`

	void (\*set_focus)(SbUiNavItem item);

	This is used to manually force focus on a navigation item of type
	kSbUiNavItemTypeFocus. Any previously focused navigation item should receive
	the blur event. If the item is not transitively a content of the root item,
	then this does nothing.
	* ` set_item_enabled`

	void (\*set_item_enabled)(SbUiNavItem item, bool enabled);

	This is used to enable or disable user interaction with the specified
	navigation item. All navigation items are disabled when created, and they
	must be explicitly enabled to allow user interaction. If a container is
	disabled, then all of its contents are not interactable even though they
	remain enabled. If `enabled` is false, it must be guaranteed that once this
	function returns, no callbacks associated with this item will be invoked
	until the item is re-enabled.
	* ` set_item_dir`

	void (\*set_item_dir)(SbUiNavItem item, SbUiNavItemDir dir);

	This specifies directionality for container items. Containers within
	containers do not inherit directionality. Directionality must be specified
	for each container explicitly.
	* ` set_item_size`

	void (\*set_item_size)(SbUiNavItem item, float width, float height);

	Set the interactable size of the specified navigation item. By default, an
	item's size is (0,0).
	* ` set_item_transform`

	void (\set_item_transform)(SbUiNavItem item, const SbUiNavMatrix2x3 \
	transform);

	Set the transform for the navigation item and its contents if the item is a
	container. This specifies the placement of the item's center within its
	container. The transform origin is the center of the item. Distance is
	measured in pixels with the origin being the top-left of the item's
	container. By default, an item's transform is identity.
	* ` get_item_focus_transform`

	bool (\get_item_focus_transform)(SbUiNavItem item, SbUiNavMatrix4 \
	out_transform);

	Retrieve the focus transform matrix for the navigation item. The UI engine
	may translate, rotate, and/or tilt focus items to reflect user interaction.
	This transform should be multiplied with the item's transform to get its
	position inside its container. The transform origin is the center of the
	item. Return false if the item position should not be changed (i.e. the
	transform should be treated as identity).
	* ` get_item_focus_vector`

	bool (\get_item_focus_vector)(SbUiNavItem item, float\ out_x, float\*
	out_y);

	Retrieve a vector representing the focus location within a focused item.
	This is used to provide feedback about user input that is too small to
	result in a focus change. If there is no focus vector for the navigation
	item, then return false and leave `out_x` and `out_y` unchanged. Otherwise,
	return true and set the output values in the range of [-1, +1] with (out_x,
	out_y) of (-1, -1) being the top-left corner of the navigation item and (0,
	0) being the center.
	* ` set_item_container_window`

	void (\*set_item_container_window)(SbUiNavItem item, SbWindow window);

	This attaches the given navigation item (which must be a container) to the
	specified window. Navigation items are only interactable if they are
	transitively attached to a window.

	A navigation item may only have a SbUiNavItem or SbWindow as its direct
	container. The navigation item hierarchy is established using
	set_item_container_item() with the root container attached to a SbWindow
	using set_item_container_window() to enable interaction with all enabled
	items in the hierarchy.

	If `item` is already registered with a different window, then this will
	unregister it from that window then attach it to the given `window`. It is
	an error to register more than one navigation item with any given window. If
	`window` is kSbWindowInvalid, then this will unregister the `item` from its
	current window if any. Upon destruction of `item` or `window`, the `item` is
	automatically unregistered from the `window`.
	* ` set_item_container_item`

	void (\*set_item_container_item)(SbUiNavItem item, SbUiNavItem container);

	A container navigation item may contain other navigation items. However, it
	is an error to have circular containment or for `container` to not be of
	type kSbUiNavItemTypeContainer. If `item` already has a different container,
	then this first severs that connection. If `container` is
	kSbUiNavItemInvalid, then this removes `item` from its current container.
	Upon destruction of `item` or `container`, the `item` is automatically
	removed from the `container`.

	The position of items within a container are specified relative to the
	container's position. The position of these content items are further
	modified by the container's "content offset".

	For example, consider item A with position (5,5) and content offset (0,0).
	Given item B with position (10,10) is registered as a content of item A.

	1) Item B should be drawn at position (15,15).

	2) If item A's content offset is changed to (10,0), then item B should be
	drawn at position (5,15).

	Essentially, content items should be drawn at: [container position] +
	[content position] - [container content offset]
	* ` set_item_content_offset`

	void (\*set_item_content_offset)(SbUiNavItem item, float content_offset_x,
	float content_offset_y);

	Set the current content offset for the given container. This may be used to
	force scrolling to make certain content items visible. A container item's
	content offset helps determine where its content items should be drawn.
	Essentially, a content item should be drawn at: [container position] +
	[content position] - [container content offset] If `item` is not a
	container, then this does nothing. By default, the content offset is (0,0).
	* ` get_item_content_offset`

	void (\get_item_content_offset)(SbUiNavItem item, float\
	out_content_offset_x, float\* out_content_offset_y);

	Retrieve the current content offset for the navigation item. If `item` is
	not a container, then the content offset is (0,0).

	### SbUiNavItemDir ###

	Navigation items of type kSbUiNavItemTypeContainer have directionality. If
	directionality is not specified for a container, it should default to left-to-
	right and top-to-bottom.

	For left-to-right, content offset x = 0 shows the leftmost content. `< –
	Container Size-->` +----------------- – +----------------- – +-----------------
	– + ` Not selectable. ` Selectable. ` Selectable. ` ` Offscreen. ` Onscreen. `
	Offscreen. ` ` Negative position. ` Positive position. ` Positive position. `
	+----------------- – +----------------- – +----------------- – + ^ Content
	Offset X = 0.

	For right-to-left, content offset x = 0 shows the rightmost content. `< –
	Container Size-->` +----------------- – +----------------- – +-----------------
	– + ` Selectable. ` Selectable. ` Not selectable. ` ` Offscreen. ` Onscreen. `
	Offscreen. ` ` Negative position. ` Positive position. ` Positive position. `
	+----------------- – +----------------- – +----------------- – + ^ Content
	Offset X = 0.

	Top-to-bottom is similar to left-to-right, but for the Y position. Bottom-to-top
	is similar to right-to-left, but for the Y position.

	#### Members ####

	* `bool is_left_to_right`
	* `bool is_top_to_bottom`

	### SbUiNavMatrix2x3 ###

	This represents a 2x3 transform matrix in row-major order. ` a b tx ` ` c d ty `

	#### Members ####

	* `float m`

	### SbUiNavMatrix4 ###

	This represents a 4x4 transform matrix in row-major order.

	#### Members ####

	* `float m`

	## Functions ##

	### SbUiNavGetInterface ###

	Retrieve the platform's UI navigation implementation. If the platform does not
	provide one, then return false without modifying `out_interface`. Otherwise,
	initialize all members of `out_interface` and return true.

	#### Declaration ####

	```
	bool SbUiNavGetInterface(SbUiNavInterface *out_interface)
	```

	### SbUiNavItemIsValid ###

	Returns whether the given navigation item handle is valid.

	#### Declaration ####

	```
	static bool SbUiNavItemIsValid(SbUiNavItem item)
	```