All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups
MenuLayer

Detailed Description

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

menu_layer.png

Key Points

For short, static list menus, consider using SimpleMenuLayer.

Function Documentation

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.

Parameters
ctxThe destination graphics context
cell_layerThe layer of the cell to draw
titleIf non-null, draws a title in larger text (24 points, bold Raster Gothic system font).
subtitleIf 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.
iconIf 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_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
ctxThe destination graphics context
cell_layerThe layer of the cell to draw
titleIf non-null, draws the title in small text (14 points, bold Raster Gothic system font).
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
ctxThe destination graphics context
cell_layerThe layer of the cell to draw
titleIf non-null, draws a title in larger text (28 points, bold Raster Gothic system font).
int16_t menu_index_compare ( MenuIndex a,
MenuIndex b 
)

Comparator function to determine the order of two MenuIndex values.

Parameters
aPointer to the menu index of the first item
bPointer 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 menu layer, which is the parent for the sub- layers used for its implementation.

Parameters
menu_layerPointer to the MenuLayer for which to get the "root" Layer
Returns
The "root" Layer of the menu layer.
ScrollLayer* menu_layer_get_scroll_layer ( const MenuLayer *  menu_layer)

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

Parameters
menu_layerPointer to the MenuLayer for which to get the ScrollLayer
Returns
The ScrollLayer of the menu layer.
MenuIndex menu_layer_get_selected_index ( const MenuLayer *  menu_layer)

Gets the MenuIndex of the currently selection menu item.

Parameters
menu_layerThe MenuLayer for which to get the current selected index.
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_layerThe MenuLayer for which to reload the data.
void menu_layer_set_callbacks ( MenuLayer *  menu_layer,
void *  callback_context,
MenuLayerCallbacks  callbacks 
)

Sets the callbacks for the MenuLayer.

Parameters
menu_layerPointer to the MenuLayer for which to set the callbacks and callback context.
callback_contextThe new callback context. This is passed into each of the callbacks and can be set to point to application provided data.
callbacksThe 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 menu layer's 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_layerThe MenuLayer that needs to receive click events.
windowThe window for which to set the click configuration.
See Also
Clicks
window_set_click_config_provider_with_context()
scroll_layer_set_click_config_onto_window()
void menu_layer_set_selected_index ( MenuLayer *  menu_layer,
MenuIndex  index,
MenuRowAlign  scroll_align,
bool  animated 
)

Selects the item with given MenuIndex.

Parameters
menu_layerThe MenuLayer for which to change the selection
indexThe index of the item to select
scroll_alignThe alignment of the new selection
animatedSupply true to animate changing the selection, or false to change the selection instantly.
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.
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.

Parameters
menu_layerThe MenuLayer for which to select the next item
upSupply false to select the next item in the list (downwards), or true to select the previous item in the list (upwards).
scroll_alignThe alignment of the new selection
animatedSupply true to animate changing the selection, or false to change the selection instantly.
Note
If there is no next/previous item, this function is a no-op.

Data Structure Documentation

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 row The index of the row within the section with index .section
uint16_t section The index of the section.
struct MenuLayerCallbacks

Data structure containing all the callbacks of a MenuLayer.

Data Fields
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.
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.
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.
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 defaults height of 0 pixels is used. This disables section headers.
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.
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.
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 1 is used.
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.

Typedef Documentation

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.

Parameters
ctxThe destination graphics context to draw into
cell_layerThe header cell's layer, containing the geometry of the header cell
section_indexThe section index of the section header that needs to be drawn
callback_contextThe callback context
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.
See Also
menu_layer_set_callbacks()
MenuLayerCallbacks
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.

Parameters
ctxThe destination graphics context to draw into
cell_layerThe cell's layer, containing the geometry of the cell
cell_indexThe MenuIndex of the cell that needs to be drawn
callback_contextThe callback context
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.
See Also
menu_layer_set_callbacks()
MenuLayerCallbacks
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.

Parameters
ctxThe destination graphics context to draw into
cell_layerThe cell's layer, containing the geometry of the cell
cell_indexThe MenuIndex of the separator that needs to be drawn
callback_contextThe callback context
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.
See Also
menu_layer_set_callbacks()
MenuLayerCallbacks
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_layerThe menu layer for which the data is requested
cell_indexThe MenuIndex for which the cell height is requested
callback_contextThe callback context
Returns
The height of the cell at the given MenuIndex
See Also
menu_layer_set_callbacks()
MenuLayerCallbacks
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_layerThe menu layer for which the data is requested
section_indexThe index of the section for which the header height is requested
callback_contextThe callback context
Returns
The height of the section header at the given section index
See Also
menu_layer_set_callbacks()
MenuLayerCallbacks
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_layerThe menu layer for which the data is requested
section_indexThe index of the section of the menu for which the number of items it contains is requested
callback_contextThe callback context
Returns
The number of rows in the given section in the menu
See Also
menu_layer_set_callbacks()
MenuLayerCallbacks
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_layerThe menu layer for which the data is requested
callback_contextThe callback context
Returns
The number of sections in the menu
See Also
menu_layer_set_callbacks()
MenuLayerCallbacks
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_layerThe menu layer for which the data is requested
cell_indexThe MenuIndex for which the cell height is requested
callback_contextThe callback context
Returns
The height of the separator at the given MenuIndex
See Also
menu_layer_set_callbacks()
MenuLayerCallbacks
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_layerThe menu layer for which the selection event occured
cell_indexThe MenuIndex of the cell that is selected
callback_contextThe callback context
See Also
menu_layer_set_callbacks()
MenuLayerCallbacks
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_layerThe menu layer for which the selection event occured
new_indexThe MenuIndex of the new item that is selected now
old_indexThe MenuIndex of the old item that was selected before
callback_contextThe callback context
See Also
menu_layer_set_callbacks()
MenuLayerCallbacks

Enumeration Type Documentation

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

Enumerator
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.

Macro Definition Documentation

#define MENU_CELL_BASIC_HEADER_HEIGHT   ((const int16_t) 16)

Default section header height in pixels.

#define MenuIndex (   section,
  row 
)    ((MenuIndex){ (section), (row) })

Macro to create a MenuIndex.