How To Use the Menu API

Headline

This document describes how to use the menu API in rockbox. This is for the core and for plugins (plugins remember to use rb-> ).

The API makes extensive use of the JdGordon-is-lazy-and-likes-macros macro system (TM)! apps/menu.h has all the macros needed to make a menu.

Macros

These are the important macros.

• MENUITEM_SETTING(name, var, callback)
• MENUITEM_SETTING_W_TEXT(name, var, str, callback )
• MENUITEM_STRINGLIST(name, str, callback, ... )
• MENUITEM_RETURNVALUE(name, str, val, callback, icon)
• MENUITEM_RETURNVALUE_DYNTEXT(name, val, callback, text_callback, text_cb_data, icon)
• MENUITEM_FUNCTION(name, flags, str, func, param, callback, icon)
• MENUITEM_FUNCTION_DYNTEXT(name, flags, func, param, text_callback, text_cb_data, callback, icon)
• MAKE_MENU( name, str, callback, icon, ... )

In all the above, name is the name of the menu item variable, callback is the function to call before the menu item is displayed, and at certain times while the menu is running (explained later). icon is the icon to use when the menu item is displayed (the enum list is in apps/gui/icons.h)

MENUITEM_SETTING

Usage

Use this macro when you want to add the setting screen for a setting. The setting MUST be configured in apps/settings_list.c.

Parameters

• var is the address of one of the settings.

MENUITEM_SETTING_W_TEXT

Usage

Same as above, except the text to display either is not set in settings_list.c or you want to show different text.

Parameters

• str is the text to display (can be ID2P?() or a literal string)

MENUITEM_STRINGLIST (Important for plugins)

Usage

This will create a menu which is a list of strings. do_menu() will return the index of the string which was selected (0 is the first one). Most do_menu() calls in plugins would use this macro to set up the menu.

Parameters

• str is the text to display (can be ID2P?() or a literal string)
• ... is the list of strings (or ID2P?()'s) to display

MENUITEM_RETURNVALUE

Usage

Similar to MENUITEM_STRINGLIST, except this creats a single menu item which when selected causes do_menu to return some value.

Parameters

• str is the text to display (can be ID2P?() or a literal string)
• val is the value to return when selected

MENUITEM_RETURNVALUE_DYNTEXT

Usage

As above, except the string to display is dynamic.

Parameters

• val is the value to return when selected
• text_callback is the function to call when the text to display is refreshed.
• text_cb_data is a pointer to data to pass to text_callback

MENUITEM_FUNCTION

Usage

Creates a menu item which when called will cause the function to be called.

Parameters

• flags - MENU_FUNC_USEPARAM and MENU_FUNC_CHECK_RETVAL. These can be OR-ed together (or set to 0)
  • MENU_FUNC_USEPARAM - param will be passed as a void* to the called function
  • MENU_FUNC_CHECK_RETVAL - if the called function returns 1, do_menu will exit
• str is the text to display (can be ID2P?() or a literal string)
• func is the function to call
• param is the parameter to pass to the function. NULL if MENU_FUNC_USEPARAM is not set

MENUITEM_FUNCTION_DYNTEXT

Usage

As above, except the string to display is dynamic.

Parameters

• text_callback is the function to call when the text to display is refreshed.
• text_cb_data is a pointer to data to pass to text_callback

MAKE_MENU (Most important macro)

Usage

This is used to create a menu with item of the above macros.

Parameters

• ... is the list of menu items which should be displayed in this menu. (Can include other MAKE_MENU() variables. Menu items are passed as &*menu name*.

Important Functions

int do_menu(const struct menu_item_ex *menu, int *start_selected); is the only function required to use the menu API.

• menu is a pointer to a menu variable which was created with either MAKE_MENU() or MENUITEM_STRINGLIST(). *start_selected is a pointer to a variable which keeps track of the last selection. the value should be set to 0 the first time the menu is entered. If set to NULL it wil be ignored and the first item will always be selected when the menu is entered.

Examples

Basic usage, typical plugin menu

MENUITEM_STRINGLIST(menu, "Edit What?", NULL, "Extension", "Color",);
switch (rb->do_menu(&menu, NULL))
{
    case 0: /* "Extension" */
        /* do something.... */
    break;
    case 1: /* "Color" */
        /* do something.... */
    break;
    default: /* user didnt select either item */
}

The above creates a small menu with 2 options, gives it the title "Edit What?" and runs the menu

Advanced usage

 (from lib/playback_control.c)
MENUITEM_FUNCTION(prevtrack_item, 0, "Previous Track",
                  prevtrack, NULL, NULL, Icon_NOICON);
MENUITEM_FUNCTION(playpause_item, 0, "Pause / Play",
                  play, NULL, NULL, Icon_NOICON);
MENUITEM_FUNCTION(stop_item, 0, "Stop Playback",
                  stop, NULL, NULL, Icon_NOICON);
MENUITEM_FUNCTION(nexttrack_item, 0, "Next Track",
                  nexttrack, NULL, NULL, Icon_NOICON);
MENUITEM_FUNCTION(volume_item, 0, "Change Volume",
                  volume, NULL, NULL, Icon_NOICON);
MENUITEM_FUNCTION(shuffle_item, 0, "Enable/Disable Shuffle",
                  shuffle, NULL, NULL, Icon_NOICON);
MENUITEM_FUNCTION(repeat_mode_item, 0, "Change Repeat Mode",
                  repeat_mode, NULL, NULL, Icon_NOICON);
MAKE_MENU(playback_control_menu, "Playback Control", NULL, Icon_NOICON,
            &prevtrack_item, &playpause_item, &stop_item, &nexttrack_item,
            &volume_item, &shuffle_item, &repeat_mode_item);
bool playback_control(struct plugin_api* newapi)
{
    api = newapi;
    return api->do_menu(&playback_control_menu, NULL) == MENU_ATTACHED_USB;
}