Layer that displays a standard list menu. Data is provided using callbacks.
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.
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.
The destination graphics context
The layer of the cell to draw
If non-null, draws a title in larger text (24 points, bold Raster Gothic system font).
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.
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.
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.
The destination graphics context
The layer of the cell to draw
If non-null, draws a title in larger text (28 points, bold Raster Gothic system font).
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.
The destination graphics context
The layer of the cell to draw
If non-null, draws the title in small text (14 points, bold Raster Gothic system font).
Comparator function to determine the order of two MenuIndex values.
Pointer to the menu index of the first item
Pointer to the menu index of the second item
0 if A and B are equal, 1 if A has a higher section & row combination than B or else -1
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.
A pointer to the MenuLayer. NULL
if the MenuLayer could not be created
Destroys a MenuLayer previously created by menu_layer_create.
Sets the callbacks for the MenuLayer.
Pointer to the MenuLayer for which to set the callbacks and callback context.
The new callback context. This is passed into each of the callbacks and can be set to point to application provided data.
The new callbacks for the MenuLayer. The storage for this data structure must be long lived. Therefore, it cannot be stack-allocated.
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.
The MenuLayer that needs to receive click events.
The window for which to set the click configuration.
Selects the next or previous item, relative to the current selection.
If there is no next/previous item, this function is a no-op.
The MenuLayer for which to select the next item
Supply false
to select the next item in the list (downwards), or true
to select the previous item in the list (upwards).
The alignment of the new selection
Supply true
to animate changing the selection, or false
to change the selection instantly.
Selects the item with given MenuIndex.
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.
The MenuLayer for which to change the selection
The index of the item to select
The alignment of the new selection
Supply true
to animate changing the selection, or false
to change the selection instantly.
Gets the MenuIndex of the currently selected menu item.
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.
The MenuLayer for which to get the current selected index.
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.
The MenuLayer for which to reload the data.
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.
The Layers for the cell to check highlight status.
true if the given cell layer is highlighted in the menu.
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.
The MenuLayer for which to set the colors.
The color to be used for the background of the cell.
The color to be used for the foreground and text of the cell.
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.
The MenuLayer for which to set the colors.
The color to be used for the background of the cell.
The color to be used for the foreground and text of the cell.
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.
The menu layer for which to enable or disable the padding.
True = enable padding, False = disable padding.
True, if the MenuLayer generally scrolls such that the selected row is in the center.
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.
The menu layer for which to enable or disable the behavior.
true = enable the mode, false = disable it.
Returns whether or not the specified cell index is currently selected.
This function should not be used to determine whether a cell is highlighted or not. See menu_cell_layer_is_highlighted for more information.
Data structure containing all the callbacks of a MenuLayer.
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.
When NULL
, the number of sections defaults to 1.
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.
Must be set to a valid callback; NULL
causes undefined behavior.
Callback that gets called to get the height of a cell. This can get called at various moments throughout the life of a menu.
When NULL
, the default height of 44 pixels is used.
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.
When NULL
, the default height of 0 pixels is used. This disables section headers.
Callback that gets called to render a menu item. This gets called for each menu item, every time it needs to be re-rendered.
Must be set to a valid callback; NULL
causes undefined behavior.
Callback that gets called to render a section header. This gets called for each section header, every time it needs to be re-rendered.
Must be set to a valid callback, unless .get_header_height
is NULL
. Causes undefined behavior otherwise.
Callback that gets called when the user triggers a click with the SELECT button.
When NULL
, click events for the SELECT button are ignored.
Callback that gets called when the user triggers a long click with the SELECT button.
When NULL
, long click events for the SELECT button are ignored.
Callback that gets called whenever the selection changes.
When NULL
, selection change events are ignored.
Callback that gets called to get the height of a separator This can get called at various moments throughout the life of a menu.
When NULL
, the default height of 0 is used.
Callback that gets called to render a separator. This gets called for each separator, every time it needs to be re-rendered.
Must be set to a valid callback, unless .get_separator_height
is NULL
. Causes undefined behavior otherwise.
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,.
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.
Data structure containing all the callbacks of a MenuLayer.
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.
When NULL
, the number of sections defaults to 1.
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.
Must be set to a valid callback; NULL
causes undefined behavior.
Callback that gets called to get the height of a cell. This can get called at various moments throughout the life of a menu.
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.
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.
When NULL
, the default height of 0 pixels is used. This disables section headers.
Callback that gets called to render a menu item. This gets called for each menu item, every time it needs to be re-rendered.
Must be set to a valid callback; NULL
causes undefined behavior.
Callback that gets called to render a section header. This gets called for each section header, every time it needs to be re-rendered.
Must be set to a valid callback, unless .get_header_height
is NULL
. Causes undefined behavior otherwise.
Callback that gets called when the user triggers a click with the SELECT button.
When NULL
, click events for the SELECT button are ignored.
Callback that gets called when the user triggers a long click with the SELECT button.
When NULL
, long click events for the SELECT button are ignored.
Callback that gets called whenever the selection changes.
When NULL
, selection change events are ignored.
Callback that gets called to get the height of a separator This can get called at various moments throughout the life of a menu.
When NULL
, the default height of 0 is used.
Callback that gets called to render a separator. This gets called for each separator, every time it needs to be re-rendered.
Must be set to a valid callback, unless .get_separator_height
is NULL
. Causes undefined behavior otherwise.
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,.
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.
Values to specify how a (selected) row should be aligned relative to the visible area of the MenuLayer.
Don't align or update the scroll offset of the MenuLayer.
Scroll the contents of the MenuLayer in such way that the selected row is centered relative to the visible area.
Scroll the contents of the MenuLayer in such way that the selected row is at the top of the visible area.
Scroll the contents of the MenuLayer in such way that the selected row is at the bottom of the visible area.
Function signature for the callback to get the number of sections in a menu.
The MenuLayer for which the data is requested
The callback context
The number of sections in the menu
Function signature for the callback to get the number of rows in a given section in a menu.
The MenuLayer for which the data is requested
The index of the section of the menu for which the number of items it contains is requested
The callback context
The number of rows in the given section in the menu
Function signature for the callback to get the height of the menu cell at a given index.
The MenuLayer for which the data is requested
The MenuIndex for which the cell height is requested
The callback context
The height of the cell at the given MenuIndex
Function signature for the callback to get the height of the section header at a given section index.
The MenuLayer for which the data is requested
The index of the section for which the header height is requested
The callback context
The height of the section header at the given section index
Function signature for the callback to get the height of the separator at a given index.
The MenuLayer for which the data is requested
The MenuIndex for which the cell height is requested
The callback context
The height of the separator at the given MenuIndex
Function signature for the callback to render the menu cell at a given MenuIndex.
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.
The destination graphics context to draw into
The cell's layer, containing the geometry of the cell
The MenuIndex of the cell that needs to be drawn
The callback context
Function signature for the callback to render the section header at a given section index.
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.
The destination graphics context to draw into
The header cell's layer, containing the geometry of the header cell
The section index of the section header that needs to be drawn
The callback context
Function signature for the callback to render the separator at a given MenuIndex.
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.
The destination graphics context to draw into
The cell's layer, containing the geometry of the cell
The MenuIndex of the separator that needs to be drawn
The callback context
Function signature for the callback to handle the event that a user hits the SELECT button.
The MenuLayer for which the selection event occured
The MenuIndex of the cell that is selected
The callback context
Function signature for the callback to handle a change in the current selected item in the menu.
The MenuLayer for which the selection event occured
The MenuIndex of the new item that is selected now
The MenuIndex of the old item that was selected before
The 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.
menu_layer_set_selected_index will not trigger this callback when the selection changes, but menu_layer_set_selected_next will.
The MenuLayer for which the selection event that occured
Pointer to the index that the MenuLayer is going to change selection to.
The index that is being unselected.
The 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.
The destination graphics context to draw into.
The background's layer, containing the geometry of the background.
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.
Default section header height in pixels.
Macro to create a MenuIndex.
Constant value representing MenuLayer short cell height when this item is the selected item on a round display.
Constant value representing MenuLayer tall cell height when this item is the selected item on a round display.
Constant value representing MenuLayer short cell height when this item is not the selected item on a round display.
Do you have questions about the Pebble SDK?
Do you need some help understanding something on this page?
You can either take advantage of our awesome developer community and check out the SDK Help forums, or you can send us a message through the website!