pebble
Privacy
Cookies
Publish

Pebble C API

MenuLayer

Layer that displays a standard list menu. Data is provided using callbacks.

Key Points

  • The familiar list-style menu widget, as used throughout the Pebble user interface.

  • Built on top of ScrollLayer, inheriting all its goodness like animated scrolling, automatic "more content" shadow indicators, etc.

  • All data needed to render the menu is requested on-demand via callbacks, to avoid the need to keep a lot of data in memory.

  • Support for "sections". A section is a group of items, visually separated by a header with the name at the top of the section.

  • Variable heights: each menu item cell and each section header can have its own height. The heights are provided by callbacks.

  • Deviation from the Layer system for cell drawing: Each menu item does not have its own Layer (to minimize memory usage). Instead, a drawing callback is set onto the MenuLayer that is responsible for drawing each menu item. The MenuLayer will call this callback for each menu item that is visible and needs to be rendered.

  • Cell and header drawing can be customized by implementing a custom drawing callback.

  • A few "canned" menu cell drawing functions are provided for convenience, which support the default menu cell layout with a title, optional subtitle and icon.

For short, static list menus, consider using SimpleMenuLayer.

Function

void menu_cell_basic_draw(GContext * ctx, const Layer * cell_layer, const char * title, const char * subtitle, GBitmap * icon)

Section drawing function to draw a basic section cell with the title, subtitle, and icon of the section. Call this function inside the .draw_row callback implementation, see MenuLayerCallbacks. Note that if the size of cell_layer is too small to fit all of the cell items specified, not all of them may be drawn.

Parameters

ctx

The destination graphics context

cell_layer

The layer of the cell to draw

title

If non-null, draws a title in larger text (24 points, bold Raster Gothic system font).

subtitle

If non-null, draws a subtitle in smaller text (18 points, Raster Gothic system font). If NULL, the title will be centered vertically inside the menu cell.

icon

If non-null, draws an icon to the left of the text. If NULL, the icon will be omitted and the leftover space is used for the title and subtitle.

void menu_cell_title_draw(GContext * ctx, const Layer * cell_layer, const char * title)

Cell drawing function to draw a basic menu cell layout with title, subtitle Cell drawing function to draw a menu cell layout with only one big title. Call this function inside the .draw_row callback implementation, see MenuLayerCallbacks.

Parameters

ctx

The destination graphics context

cell_layer

The layer of the cell to draw

title

If non-null, draws a title in larger text (28 points, bold Raster Gothic system font).

void menu_cell_basic_header_draw(GContext * ctx, const Layer * cell_layer, const char * title)

Section header drawing function to draw a basic section header cell layout with the title of the section. Call this function inside the .draw_header callback implementation, see MenuLayerCallbacks.

Parameters

ctx

The destination graphics context

cell_layer

The layer of the cell to draw

title

If non-null, draws the title in small text (14 points, bold Raster Gothic system font).

int16_t menu_index_compare(const MenuIndex * a, const MenuIndex * b)

Comparator function to determine the order of two MenuIndex values.

Parameters

a

Pointer to the menu index of the first item

b

Pointer to the menu index of the second item

Returns

0 if A and B are equal, 1 if A has a higher section & row combination than B or else -1

MenuLayer * menu_layer_create(GRect frame)

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

  • Clips: true

  • Hidden: false

  • Content size: frame.size

  • Content offset: GPointZero

  • Callbacks: None (NULL for each one)

  • Callback context: NULL

  • After the relevant callbacks are called to populate the menu, the item at MenuIndex(0, 0) will be selected initially.

Returns

A pointer to the MenuLayer. NULL if the MenuLayer could not be created

void menu_layer_destroy(MenuLayer * menu_layer)

Destroys a MenuLayer previously created by menu_layer_create.

Layer * menu_layer_get_layer(const MenuLayer * menu_layer)

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

Parameters

menu_layer

Pointer to the MenuLayer for which to get the "root" Layer

Returns

The "root" Layer of the MenuLayer.

ScrollLayer * menu_layer_get_scroll_layer(const MenuLayer * menu_layer)

Gets the ScrollLayer of the MenuLayer, which is the layer responsible for the scrolling of the MenuLayer.

Parameters

menu_layer

Pointer to the MenuLayer for which to get the ScrollLayer

Returns

The ScrollLayer of the MenuLayer.

void menu_layer_set_callbacks(MenuLayer * menu_layer, void * callback_context, MenuLayerCallbacks callbacks)

Sets the callbacks for the MenuLayer.

Parameters

menu_layer

Pointer to the MenuLayer for which to set the callbacks and callback context.

callback_context

The new callback context. This is passed into each of the callbacks and can be set to point to application provided data.

callbacks

The new callbacks for the MenuLayer. The storage for this data structure must be long lived. Therefore, it cannot be stack-allocated.

See Also

MenuLayerCallbacks
void menu_layer_set_click_config_onto_window(MenuLayer * menu_layer, struct Window * window)

Convenience function to set the ClickConfigProvider callback on the given window to the MenuLayer internal click config provider. This internal click configuration provider, will set up the default UP & DOWN scrolling / menu item selection behavior. This function calls scroll_layer_set_click_config_onto_window to accomplish this.

Click and long click events for the SELECT button can be handled by installing the appropriate callbacks using menu_layer_set_callbacks(). This is a deviation from the usual click configuration provider pattern.

Parameters

menu_layer

The MenuLayer that needs to receive click events.

window

The window for which to set the click configuration.

See Also

Clicks
void menu_layer_set_selected_next(MenuLayer * menu_layer, bool up, MenuRowAlign scroll_align, bool animated)

Selects the next or previous item, relative to the current selection.

Note

If there is no next/previous item, this function is a no-op.

Parameters

menu_layer

The MenuLayer for which to select the next item

up

Supply false to select the next item in the list (downwards), or true to select the previous item in the list (upwards).

scroll_align

The alignment of the new selection

animated

Supply true to animate changing the selection, or false to change the selection instantly.

void menu_layer_set_selected_index(MenuLayer * menu_layer, MenuIndex index, MenuRowAlign scroll_align, bool animated)

Selects the item with given MenuIndex.

Note

If the section and/or row index exceeds the avaible number of sections or resp. rows, the exceeding index/indices will be capped, effectively selecting the last section and/or row, resp.

Parameters

menu_layer

The MenuLayer for which to change the selection

index

The index of the item to select

scroll_align

The alignment of the new selection

animated

Supply true to animate changing the selection, or false to change the selection instantly.

MenuIndex menu_layer_get_selected_index(const MenuLayer * menu_layer)

Gets the MenuIndex of the currently selected menu item.

Note

This function should not be used to determine whether a cell should be highlighted or not. See menu_cell_layer_is_highlighted for more information.

Parameters

menu_layer

The MenuLayer for which to get the current selected index.

See Also

menu_cell_layer_is_highlighted
void menu_layer_reload_data(MenuLayer * menu_layer)

Reloads the data of the menu. This causes the menu to re-request the menu item data, by calling the relevant callbacks. The current selection and scroll position will not be changed. See the note with menu_layer_set_selected_index() for the behavior if the old selection is no longer valid.

Parameters

menu_layer

The MenuLayer for which to reload the data.

bool menu_cell_layer_is_highlighted(const Layer * cell_layer)

Returns whether or not the given cell layer is highlighted. Using this for determining highlight behaviour is preferable to using menu_layer_get_selected_index. Row drawing callbacks may be invoked multiple times with a different highlight status on the same cell in order to handle partially highlighted cells during animation.

Parameters

cell_layer

The Layers for the cell to check highlight status.

Returns

true if the given cell layer is highlighted in the menu.

void menu_layer_set_normal_colors(MenuLayer * menu_layer, GColor background, GColor foreground)

Set the default colors to be used for cells when it is in a normal state (not highlighted). The GContext's text and fill colors will be set appropriately prior to calling the .draw_row callback. If this function is not explicitly called on a MenuLayer, it will default to white background with black foreground.

Parameters

menu_layer

The MenuLayer for which to set the colors.

background

The color to be used for the background of the cell.

foreground

The color to be used for the foreground and text of the cell.

See Also

menu_layer_set_highlight_colors
void menu_layer_set_highlight_colors(MenuLayer * menu_layer, GColor background, GColor foreground)

Set the default colors to be used for cells when it is in a highlighted state. The GContext's text and fill colors will be set appropriately prior to calling the .draw_row callback. If this function is not explicitly called on a MenuLayer, it will default to black background with white foreground.

Parameters

menu_layer

The MenuLayer for which to set the colors.

background

The color to be used for the background of the cell.

foreground

The color to be used for the foreground and text of the cell.

See Also

menu_layer_set_normal_colors
void menu_layer_pad_bottom_enable(MenuLayer * menu_layer, bool enable)

This enables or disables padding at the bottom of the MenuLayer. Padding at the bottom of the layer keeps the bottom item from being at the very bottom of the screen. Padding is turned on by default for all MenuLayers. The color of the padded area will be the background color set using menu_layer_set_normal_colors(). To color the padding a different color, use MenuLayerDrawBackgroundCallback.

Parameters

menu_layer

The menu layer for which to enable or disable the padding.

enable

True = enable padding, False = disable padding.

bool menu_layer_get_center_focused(MenuLayer * menu_layer)

True, if the MenuLayer generally scrolls such that the selected row is in the center.

See Also

menu_layer_set_center_focused
void menu_layer_set_center_focused(MenuLayer * menu_layer, bool center_focused)

Controls if the MenuLayer generally scrolls such that the selected row is in the center. For platforms with a round display (PBL_ROUND) the default is true, otherwise false is the default.

Parameters

menu_layer

The menu layer for which to enable or disable the behavior.

center_focused

true = enable the mode, false = disable it.

See Also

menu_layer_get_center_focused
bool menu_layer_is_index_selected(const MenuLayer * menu_layer, MenuIndex * index)

Returns whether or not the specified cell index is currently selected.

Note

This function should not be used to determine whether a cell is highlighted or not. See menu_cell_layer_is_highlighted for more information.

Parameters

menu_layer

The MenuLayer to use when determining if the index is selected.

index

The MenuIndex of the cell to check for selection.

Data Structure

struct MenuCellSpan

Data Fields

int16_t y
int16_t h
int16_t sep
MenuIndex index
struct MenuIndex

Data structure to represent an menu item's position in a menu, by specifying the section index and the row index within that section.

Data Fields

uint16_t section

The index of the section.

uint16_t row

The index of the row within the section with index .section

struct MenuLayerCallbacks

Data structure containing all the callbacks of a MenuLayer.

Data Fields

MenuLayerGetNumberOfSectionsCallback get_num_sections

Callback that gets called to get the number of sections in the menu. This can get called at various moments throughout the life of a menu.

Note

When NULL, the number of sections defaults to 1.

MenuLayerGetNumberOfRowsInSectionsCallback get_num_rows

Callback that gets called to get the number of rows in a section. This can get called at various moments throughout the life of a menu.

Note

Must be set to a valid callback; NULL causes undefined behavior.

MenuLayerGetCellHeightCallback get_cell_height

Callback that gets called to get the height of a cell. This can get called at various moments throughout the life of a menu.

Note

When NULL, the default height of 44 pixels is used.

MenuLayerGetHeaderHeightCallback get_header_height

Callback that gets called to get the height of a section header. This can get called at various moments throughout the life of a menu.

Note

When NULL, the default height of 0 pixels is used. This disables section headers.

MenuLayerDrawRowCallback draw_row

Callback that gets called to render a menu item. This gets called for each menu item, every time it needs to be re-rendered.

Note

Must be set to a valid callback; NULL causes undefined behavior.

MenuLayerDrawHeaderCallback draw_header

Callback that gets called to render a section header. This gets called for each section header, every time it needs to be re-rendered.

Note

Must be set to a valid callback, unless .get_header_height is NULL. Causes undefined behavior otherwise.

MenuLayerSelectCallback select_click

Callback that gets called when the user triggers a click with the SELECT button.

Note

When NULL, click events for the SELECT button are ignored.

MenuLayerSelectCallback select_long_click

Callback that gets called when the user triggers a long click with the SELECT button.

Note

When NULL, long click events for the SELECT button are ignored.

MenuLayerSelectionChangedCallback selection_changed

Callback that gets called whenever the selection changes.

Note

When NULL, selection change events are ignored.

MenuLayerGetSeparatorHeightCallback get_separator_height

Callback that gets called to get the height of a separator This can get called at various moments throughout the life of a menu.

Note

When NULL, the default height of 0 is used.

MenuLayerDrawSeparatorCallback draw_separator

Callback that gets called to render a separator. This gets called for each separator, every time it needs to be re-rendered.

Note

Must be set to a valid callback, unless .get_separator_height is NULL. Causes undefined behavior otherwise.

MenuLayerSelectionWillChangeCallback selection_will_change

Callback that gets called before the selected cell changes. This gets called before the selected item in the MenuLayer is changed, and will allow for the selected cell to be overridden. This allows for skipping cells in the menu, locking selection onto a given item,.

MenuLayerDrawBackgroundCallback draw_background

Callback that gets called before any cells are drawn. This supports two states, either highlighted or not highlighted. If highlighted is specified, it is expected to be colored in the same style as the menu's cells are. If this callback is not specified, it will default to the colors set with menu_layer_set_normal_colors and menu_layer_set_highlight_colors.

struct MenuLayerCallbacks

Data structure containing all the callbacks of a MenuLayer.

Data Fields

MenuLayerGetNumberOfSectionsCallback get_num_sections

Callback that gets called to get the number of sections in the menu. This can get called at various moments throughout the life of a menu.

Note

When NULL, the number of sections defaults to 1.

MenuLayerGetNumberOfRowsInSectionsCallback get_num_rows

Callback that gets called to get the number of rows in a section. This can get called at various moments throughout the life of a menu.

Note

Must be set to a valid callback; NULL causes undefined behavior.

MenuLayerGetCellHeightCallback get_cell_height

Callback that gets called to get the height of a cell. This can get called at various moments throughout the life of a menu.

Note

When NULL, the default height of MENU_CELL_BASIC_CELL_HEIGHT pixels is used. Developers may wish to use MENU_CELL_ROUND_FOCUSED_SHORT_CELL_HEIGHT and MENU_CELL_ROUND_UNFOCUSED_SHORT_CELL_HEIGHT on a round display to respect the system aesthetic.

MenuLayerGetHeaderHeightCallback get_header_height

Callback that gets called to get the height of a section header. This can get called at various moments throughout the life of a menu.

Note

When NULL, the default height of 0 pixels is used. This disables section headers.

MenuLayerDrawRowCallback draw_row

Callback that gets called to render a menu item. This gets called for each menu item, every time it needs to be re-rendered.

Note

Must be set to a valid callback; NULL causes undefined behavior.

MenuLayerDrawHeaderCallback draw_header

Callback that gets called to render a section header. This gets called for each section header, every time it needs to be re-rendered.

Note

Must be set to a valid callback, unless .get_header_height is NULL. Causes undefined behavior otherwise.

MenuLayerSelectCallback select_click

Callback that gets called when the user triggers a click with the SELECT button.

Note

When NULL, click events for the SELECT button are ignored.

MenuLayerSelectCallback select_long_click

Callback that gets called when the user triggers a long click with the SELECT button.

Note

When NULL, long click events for the SELECT button are ignored.

MenuLayerSelectionChangedCallback selection_changed

Callback that gets called whenever the selection changes.

Note

When NULL, selection change events are ignored.

MenuLayerGetSeparatorHeightCallback get_separator_height

Callback that gets called to get the height of a separator This can get called at various moments throughout the life of a menu.

Note

When NULL, the default height of 0 is used.

MenuLayerDrawSeparatorCallback draw_separator

Callback that gets called to render a separator. This gets called for each separator, every time it needs to be re-rendered.

Note

Must be set to a valid callback, unless .get_separator_height is NULL. Causes undefined behavior otherwise.

MenuLayerSelectionWillChangeCallback selection_will_change

Callback that gets called before the selected cell changes. This gets called before the selected item in the MenuLayer is changed, and will allow for the selected cell to be overridden. This allows for skipping cells in the menu, locking selection onto a given item,.

MenuLayerDrawBackgroundCallback draw_background

Callback that gets called before any cells are drawn. This supports two states, either highlighted or not highlighted. If highlighted is specified, it is expected to be colored in the same style as the menu's cells are. If this callback is not specified, it will default to the colors set with menu_layer_set_normal_colors and menu_layer_set_highlight_colors.

Enum

enum MenuRowAlign

Values to specify how a (selected) row should be aligned relative to the visible area of the MenuLayer.

Enumerators

MenuRowAlignNone

Don't align or update the scroll offset of the MenuLayer.

MenuRowAlignCenter

Scroll the contents of the MenuLayer in such way that the selected row is centered relative to the visible area.

MenuRowAlignTop

Scroll the contents of the MenuLayer in such way that the selected row is at the top of the visible area.

MenuRowAlignBottom

Scroll the contents of the MenuLayer in such way that the selected row is at the bottom of the visible area.

Typedef

typedef struct MenuLayer MenuLayer
typedef uint16_t(* MenuLayerGetNumberOfSectionsCallback)(struct MenuLayer *menu_layer, void *callback_context)

Function signature for the callback to get the number of sections in a menu.

Parameters

menu_layer

The MenuLayer for which the data is requested

callback_context

The callback context

Returns

The number of sections in the menu

See Also

menu_layer_set_callbacks()
typedef uint16_t(* MenuLayerGetNumberOfRowsInSectionsCallback)(struct MenuLayer *menu_layer, uint16_t section_index, void *callback_context)

Function signature for the callback to get the number of rows in a given section in a menu.

Parameters

menu_layer

The MenuLayer for which the data is requested

section_index

The index of the section of the menu for which the number of items it contains is requested

callback_context

The callback context

Returns

The number of rows in the given section in the menu

See Also

menu_layer_set_callbacks()
typedef int16_t(* MenuLayerGetCellHeightCallback)(struct MenuLayer *menu_layer, MenuIndex *cell_index, void *callback_context)

Function signature for the callback to get the height of the menu cell at a given index.

Parameters

menu_layer

The MenuLayer for which the data is requested

cell_index

The MenuIndex for which the cell height is requested

callback_context

The callback context

Returns

The height of the cell at the given MenuIndex

See Also

menu_layer_set_callbacks()
typedef int16_t(* MenuLayerGetHeaderHeightCallback)(struct MenuLayer *menu_layer, uint16_t section_index, void *callback_context)

Function signature for the callback to get the height of the section header at a given section index.

Parameters

menu_layer

The MenuLayer for which the data is requested

section_index

The index of the section for which the header height is requested

callback_context

The callback context

Returns

The height of the section header at the given section index

See Also

menu_layer_set_callbacks()
typedef int16_t(* MenuLayerGetSeparatorHeightCallback)(struct MenuLayer *menu_layer, MenuIndex *cell_index, void *callback_context)

Function signature for the callback to get the height of the separator at a given index.

Parameters

menu_layer

The MenuLayer for which the data is requested

cell_index

The MenuIndex for which the cell height is requested

callback_context

The callback context

Returns

The height of the separator at the given MenuIndex

See Also

menu_layer_set_callbacks()
typedef void(* MenuLayerDrawRowCallback)(GContext *ctx, const Layer *cell_layer, MenuIndex *cell_index, void *callback_context)

Function signature for the callback to render the menu cell at a given MenuIndex.

Note

The cell_layer argument is provided to make it easy to re-use an .update_proc implementation in this callback. Only the bounds and frame of the cell_layer are actually valid and other properties should be ignored.

Parameters

ctx

The destination graphics context to draw into

cell_layer

The cell's layer, containing the geometry of the cell

cell_index

The MenuIndex of the cell that needs to be drawn

callback_context

The callback context

See Also

menu_layer_set_callbacks()
typedef void(* MenuLayerDrawHeaderCallback)(GContext *ctx, const Layer *cell_layer, uint16_t section_index, void *callback_context)

Function signature for the callback to render the section header at a given section index.

Note

The cell_layer argument is provided to make it easy to re-use an .update_proc implementation in this callback. Only the bounds and frame of the cell_layer are actually valid and other properties should be ignored.

Parameters

ctx

The destination graphics context to draw into

cell_layer

The header cell's layer, containing the geometry of the header cell

section_index

The section index of the section header that needs to be drawn

callback_context

The callback context

See Also

menu_layer_set_callbacks()
typedef void(* MenuLayerDrawSeparatorCallback)(GContext *ctx, const Layer *cell_layer, MenuIndex *cell_index, void *callback_context)

Function signature for the callback to render the separator at a given MenuIndex.

Note

The cell_layer argument is provided to make it easy to re-use an .update_proc implementation in this callback. Only the bounds and frame of the cell_layer are actually valid and other properties should be ignored.

Parameters

ctx

The destination graphics context to draw into

cell_layer

The cell's layer, containing the geometry of the cell

cell_index

The MenuIndex of the separator that needs to be drawn

callback_context

The callback context

See Also

menu_layer_set_callbacks()
typedef void(* MenuLayerSelectCallback)(struct MenuLayer *menu_layer, MenuIndex *cell_index, void *callback_context)

Function signature for the callback to handle the event that a user hits the SELECT button.

Parameters

menu_layer

The MenuLayer for which the selection event occured

cell_index

The MenuIndex of the cell that is selected

callback_context

The callback context

See Also

menu_layer_set_callbacks()
typedef void(* MenuLayerSelectionChangedCallback)(struct MenuLayer *menu_layer, MenuIndex new_index, MenuIndex old_index, void *callback_context)

Function signature for the callback to handle a change in the current selected item in the menu.

Parameters

menu_layer

The MenuLayer for which the selection event occured

new_index

The MenuIndex of the new item that is selected now

old_index

The MenuIndex of the old item that was selected before

callback_context

The callback context

See Also

menu_layer_set_callbacks()
typedef void(* MenuLayerSelectionWillChangeCallback)(struct MenuLayer *menu_layer, MenuIndex *new_index, MenuIndex old_index, void *callback_context)

Function signature for the callback which allows or changes selection behavior of the menu. In order to change the cell that should be selected, modify the passed in new_index. Preventing the selection from changing, new_index can be assigned the value of old_index.

Note

menu_layer_set_selected_index will not trigger this callback when the selection changes, but menu_layer_set_selected_next will.

Parameters

menu_layer

The MenuLayer for which the selection event that occured

new_index

Pointer to the index that the MenuLayer is going to change selection to.

old_index

The index that is being unselected.

callback_context

The callback context

typedef void(* MenuLayerDrawBackgroundCallback)(GContext *ctx, const Layer *bg_layer, bool highlight, void *callback_context)

Function signature for the callback which draws the menu's background. The background is underneath the cells of the menu, and is visible in the padding below the bottom cell, or if a cell's background color is set to GColorClear.

Parameters

ctx

The destination graphics context to draw into.

bg_layer

The background's layer, containing the geometry of the background.

highlight

Whether this should be rendered as highlighted or not. Highlight style should match the highlight style of cells, since this color can be used for animating selection.

Macro Definition

#define MENU_CELL_BASIC_HEADER_HEIGHT ((const int16_t) 16)

Default section header height in pixels.

#define MENU_INDEX_NOT_FOUND ((const uint16_t) ~0)
#define MenuIndex ( section, row)

Macro to create a MenuIndex.

#define MENU_CELL_ROUND_FOCUSED_SHORT_CELL_HEIGHT ((const int16_t) 68)
#define MENU_CELL_ROUND_FOCUSED_SHORT_CELL_HEIGHT ((const int16_t) 68)

Constant value representing MenuLayer short cell height when this item is the selected item on a round display.

#define MENU_CELL_ROUND_FOCUSED_TALL_CELL_HEIGHT ((const int16_t) 84)
#define MENU_CELL_ROUND_FOCUSED_TALL_CELL_HEIGHT ((const int16_t) 84)

Constant value representing MenuLayer tall cell height when this item is the selected item on a round display.

#define MENU_CELL_ROUND_UNFOCUSED_SHORT_CELL_HEIGHT ((const int16_t) 24)
#define MENU_CELL_ROUND_UNFOCUSED_SHORT_CELL_HEIGHT ((const int16_t) 24)

Constant value representing MenuLayer short cell height when this item is not the selected item on a round display.

#define MENU_CELL_ROUND_UNFOCUSED_TALL_CELL_HEIGHT ((const int16_t) 32)
#define MENU_CELL_ROUND_UNFOCUSED_TALL_CELL_HEIGHT ((const int16_t) 32)

Constant value representing MenuLayer tall cell height when this item is not the selected item on a round display.