Vertical, bar-shaped control widget on the right edge of the window. More...

Collaboration diagram for ActionBarLayer:

Classes
class	Pebble::ActionBarLayer
	Vertical, bar-shaped control widget on the right edge of the window. More...

Macros
#define	ACTION_BAR_WIDTH _ACTION_BAR_WIDTH(PBL_PLATFORM_TYPE_CURRENT)
	The width of the action bar in pixels.

#define	_ACTION_BAR_WIDTH(plat)
	The width of the action bar in pixels, for all platforms. More...

#define	NUM_ACTION_BAR_ITEMS 3
	The maximum number of action bar items.

Typedefs
typedef struct ActionBarLayer	ActionBarLayer

Enumerations
enum	ActionBarLayerIconPressAnimation { ActionBarLayerIconPressAnimationNone = 0, ActionBarLayerIconPressAnimationMoveLeft, ActionBarLayerIconPressAnimationMoveUp, ActionBarLayerIconPressAnimationMoveRight, ActionBarLayerIconPressAnimationMoveDown }

Functions
ActionBarLayer *	action_bar_layer_create (void)

void	action_bar_layer_destroy (ActionBarLayer *action_bar_layer)
	Destroys a ActionBarLayer previously created by action_bar_layer_create.

Layer *	action_bar_layer_get_layer (ActionBarLayer *action_bar_layer)

void	action_bar_layer_set_context (ActionBarLayer action_bar, void context)

void	action_bar_layer_set_click_config_provider (ActionBarLayer *action_bar, ClickConfigProvider click_config_provider)

void	action_bar_layer_set_icon (ActionBarLayer action_bar, ButtonId button_id, const GBitmap icon)

void	action_bar_layer_clear_icon (ActionBarLayer *action_bar, ButtonId button_id)

void	action_bar_layer_add_to_window (ActionBarLayer action_bar, struct Window window)

void	action_bar_layer_remove_from_window (ActionBarLayer *action_bar)

void	action_bar_layer_set_background_color (ActionBarLayer *action_bar, GColor background_color)

void	action_bar_layer_set_icon_animated (ActionBarLayer action_bar, ButtonId button_id, const GBitmap icon, bool animated)

void	action_bar_layer_set_icon_press_animation (ActionBarLayer *action_bar, ButtonId button_id, ActionBarLayerIconPressAnimation animation)

Detailed Description

Vertical, bar-shaped control widget on the right edge of the window.

ActionBarLayer is a Layer that displays a bar on the right edge of the window. The bar can contain up to 3 icons, each corresponding with one of the buttons on the right side of the watch. The purpose of each icon is to provide a hint (feed-forward) to what action a click on the respective button will cause.

The action bar is useful when there are a few (up to 3) main actions that are desirable to be able to take quickly, literally with one press of a button.

More actions

If there are more than 3 actions the user might want to take:

Try assigning the top and bottom icons of the action bar to the two most immediate actions and use the middle icon to push a Window with a MenuLayer with less immediate actions.
Secondary actions that are not vital, can be "hidden" under a long click. Try to group similar actions to one button. For example, in a Music app, a single click on the top button is tied to the action to jump to the previous track. Holding that same button means seek backwards.

Directionality mapping

When the top and bottom buttons are used to control navigating through a (potentially virtual, non-visible) list of items, follow this guideline:

Tie the top button to the action that goes to the previous item in the list, for example "jump to previous track" in a Music app.
Tie the bottom button to the action that goes to the next item in the list, for example "jump to next track" in a Music app.

Geometry

The action bar is 30 pixels wide. Use the ACTION_BAR_WIDTH define.
Icons should not be wider than 28 pixels, or taller than 18 pixels. It is recommended to use a size of around 15 x 15 pixels for the "visual core" of the icon, and extending or contracting where needed.
Example Code

The code example below shows how to do the initial setup of the action bar in a window's .load handler. Configuring the button actions is similar to the process when using window_set_click_config_provider(). See Clicks for more information.

ActionBarLayer *action_bar;
 
// The implementation of my_next_click_handler and my_previous_click_handler
// is omitted for the sake of brevity. See the Clicks reference docs.
 
void click_config_provider(void *context) {
  window_single_click_subscribe(BUTTON_ID_DOWN, (ClickHandler) my_next_click_handler);
  window_single_click_subscribe(BUTTON_ID_UP, (ClickHandler) my_previous_click_handler);
}
 
void window_load(Window *window) {
  ...
  // Initialize the action bar:
  action_bar = action_bar_layer_create();
  // Associate the action bar with the window:
  action_bar_layer_add_to_window(action_bar, window);
  // Set the click config provider:
  action_bar_layer_set_click_config_provider(action_bar,
                                             click_config_provider);
 
  // Set the icons:
  // The loading of the icons is omitted for brevity... See gbitmap_create_with_resource()
  action_bar_layer_set_icon_animated(action_bar, BUTTON_ID_UP, my_icon_previous, true);
  action_bar_layer_set_icon_animated(action_bar, BUTTON_ID_DOWN, my_icon_next, true);
}

Macro Definition Documentation

◆ _ACTION_BAR_WIDTH

#define _ACTION_BAR_WIDTH ( plat )

Value:

  PBL_PLATFORM_SWITCH(plat, \
  /*aplite*/ 30, \
  /*basalt*/ 30, \
  /*chalk*/ 40, \
  /*diorite*/ 30, \
  /*emery*/ 34)

The width of the action bar in pixels, for all platforms.

Function Documentation

◆ action_bar_layer_add_to_window()

void action_bar_layer_add_to_window	(	ActionBarLayer *	action_bar,
		struct Window *	window
	)

Adds the action bar's layer on top of the window's root layer. It also adjusts the layout of the action bar to match the geometry of the window it gets added to. Lastly, it calls window_set_click_config_provider_with_context() on the window to set it up to work with the internal callback and raw click handlers of the action bar, to enable the highlighting of the section of the action bar when the user presses a button.

Note: After this call, do not use window_set_click_config_provider_with_context() with the window that the action bar has been added to (this would de-associate the action bar's click config provider and context). Instead use action_bar_layer_set_click_config_provider() and action_bar_layer_set_context() to register the click configuration provider to configure the buttons actions.; It is advised to call this is in the window's .load or .appear handler. Make sure to call action_bar_layer_remove_from_window() in the window's .unload or .disappear handler.; Adding additional layers to the window's root layer after this calll can occlude the action bar.

Parameters

action_bar	The action bar to associate with the window
window	The window with which the action bar is to be associated

◆ action_bar_layer_clear_icon()

void action_bar_layer_clear_icon	(	ActionBarLayer *	action_bar,
		ButtonId	button_id
	)

Convenience function to clear out an existing icon. All it does is call action_bar_layer_set_icon(action_bar, button_id, NULL)

Parameters

action_bar	The action bar for which to clear an icon
button_id	The identifier of the button for which to clear the icon

See also: action_bar_layer_set_icon()

◆ action_bar_layer_create()

ActionBarLayer* action_bar_layer_create ( void )

Creates a new ActionBarLayer on the heap and initalizes it with the default values.

Background color: GColorBlack
No click configuration provider (NULL)
No icons
Not added to / associated with any window, thus not catching any button input yet.
Returns
A pointer to the ActionBarLayer. NULL if the ActionBarLayer could not be created

◆ action_bar_layer_get_layer()

Layer* action_bar_layer_get_layer ( ActionBarLayer * action_bar_layer )

Gets the "root" Layer of the action bar layer, which is the parent for the sub- layers used for its implementation.

Parameters

action_bar_layer Pointer to the ActionBarLayer for which to get the "root" Layer

Returns: The "root" Layer of the action bar layer.

◆ action_bar_layer_remove_from_window()

void action_bar_layer_remove_from_window ( ActionBarLayer * action_bar )

Removes the action bar from the window and unconfigures the window's click configuration provider. NULL is set as the window's new click config provider and also as its callback context. If it has not been added to a window before, this function is a no-op.

Parameters

action_bar The action bar to de-associate from its current window

◆ action_bar_layer_set_background_color()

void action_bar_layer_set_background_color	(	ActionBarLayer *	action_bar,
		GColor	background_color
	)

Sets the background color of the action bar. Defaults to GColorBlack. The action bar's layer is automatically marked dirty.

Parameters

action_bar	The action bar of which to set the background color
background_color	The new background color

◆ action_bar_layer_set_click_config_provider()

void action_bar_layer_set_click_config_provider	(	ActionBarLayer *	action_bar,
		ClickConfigProvider	click_config_provider
	)

Sets the click configuration provider callback of the action bar. In this callback your application can associate handlers to the different types of click events for each of the buttons, see Clicks.

Note: If the action bar had already been added to a window and the window is currently on-screen, the click configuration provider will be called before this function returns. Otherwise, it will be called by the system when the window becomes on-screen.; The .raw handlers cannot be used without breaking the automatic highlighting of the segment of the action bar that for which a button is

See also: action_bar_layer_set_icon()

Parameters

action_bar	The action bar for which to assign a new click configuration provider
click_config_provider	The new click configuration provider

◆ action_bar_layer_set_context()

void action_bar_layer_set_context	(	ActionBarLayer *	action_bar,
		void *	context
	)

Sets the context parameter, which will be passed in to ClickHandler callbacks and the ClickConfigProvider callback of the action bar.

Note: By default, a pointer to the action bar itself is passed in, if the context has not been set or if it has been set to NULL.

Parameters

action_bar	The action bar for which to assign the new context
context	The new context

See also: action_bar_layer_set_click_config_provider(); Clicks

◆ action_bar_layer_set_icon()

void action_bar_layer_set_icon	(	ActionBarLayer *	action_bar,
		ButtonId	button_id,
		const GBitmap *	icon
	)

Sets an action bar icon onto one of the 3 slots as identified by button_id. Only BUTTON_ID_UP, BUTTON_ID_SELECT and BUTTON_ID_DOWN can be used. The transition will not be animated. Whenever an icon is set, the click configuration provider will be called, to give the application the opportunity to reconfigure the button interaction.

Parameters

action_bar	The action bar for which to set the new icon
button_id	The identifier of the button for which to set the icon
icon	Pointer to the GBitmap icon

See also: action_bar_layer_set_icon_animated(); action_bar_layer_set_icon_press_animation(); action_bar_layer_set_click_config_provider()

◆ action_bar_layer_set_icon_animated()

void action_bar_layer_set_icon_animated	(	ActionBarLayer *	action_bar,
		ButtonId	button_id,
		const GBitmap *	icon,
		bool	animated
	)

Sets an action bar icon onto one of the 3 slots as identified by button_id. Only BUTTON_ID_UP, BUTTON_ID_SELECT and BUTTON_ID_DOWN can be used. Optionally, if animated is true, the transition will be animated. Whenever an icon is set, the click configuration provider will be called, to give the application the opportunity to reconfigure the button interaction.

Parameters

action_bar	The action bar for which to set the new icon
button_id	The identifier of the button for which to set the icon
icon	Pointer to the GBitmap icon
animated	True = animate the transition, False = do not animate the transition

See also: action_bar_layer_set_icon(); action_bar_layer_set_icon_press_animation(); action_bar_layer_set_click_config_provider()

◆ action_bar_layer_set_icon_press_animation()

void action_bar_layer_set_icon_press_animation	(	ActionBarLayer *	action_bar,
		ButtonId	button_id,
		ActionBarLayerIconPressAnimation	animation
	)

Sets the animation to use while a button is pressed on an ActionBarLayer. By default we use ActionBarLayerIconPressAnimationMoveLeft

Parameters

action_bar	The action bar for which to set the press animation
button_id	The button for which to set the press animation
animation	The animation to use.

See also: action_bar_layer_set_icon_animated(); action_bar_layer_set_click_config_provider()

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

More actions

Directionality mapping

Geometry

Example Code

Macro Definition Documentation

◆ _ACTION_BAR_WIDTH

Function Documentation

◆ action_bar_layer_add_to_window()

◆ action_bar_layer_clear_icon()

◆ action_bar_layer_create()

◆ action_bar_layer_get_layer()

◆ action_bar_layer_remove_from_window()

◆ action_bar_layer_set_background_color()

◆ action_bar_layer_set_click_config_provider()

◆ action_bar_layer_set_context()

◆ action_bar_layer_set_icon()

◆ action_bar_layer_set_icon_animated()

◆ action_bar_layer_set_icon_press_animation()