UsingTheMenuAPI < Main

Downloads
release
dev builds
extras
themes
Documentation
manual
wiki
device status
Support
forums
mailing lists
IRC
Development
bugs
patches
dev guide
Donate
Wiki > Main > DocsIndex > DevelopmentGuide > UsingTheMenuAPI
---+!! How To Use the Menu API

%TOC%

---++ 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-> ).

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.

---++ The callback paramater
Each menu item as a callback parameter (some have two) which are used to:
   * change the action when a user presses a button
   * tell the menu items parent menu to not display the item
   * tell the menu items parent menu what to display for it (only the _DYNTEXT macros)
---+++ the action callback.
Firstly, the callback is of type <verbatim>int (*menu_callback)(int action, const struct menu_item_ex *this_item);</verbatim>.
The *this_item* parameter is a pointer to the menu item which is being called on, this is needed so many items can share the callback function (so remember to check this value if you are sharing callbacks.)

if the callback is not NULL, the first time it is called the action will be ACTION_REQUEST_MENUITEM which means it is being checked if it should be displayed. returning anything other than ACTION_EXIT_MENUITEM will mean the item is being shown. (returning ACTION_EXIT_MENUITEM will hide the item). This actually happens when the items parent is setting up.

For actual menu's (created by the MAKE_MENU() and MAKE_STRINGLIST() macros) the callback will be called whenever an action happens. the return value will become the new action the list will process. Returning ACTION_REDRAW will cause the list to do a full redraw. returning ACTION_EXIT_AFTER_THIS_MENUITEM will cause the menu to exit do_menu() instead of going back to the previous menu when this menu is back-ed out of. (i.e menu1 -> menu2-> menu3. The callback in menu3 returns ACTION_EXIT_AFTER_THIS_MENUITEM.. when ACTION_STD_CANCEL next occurs the user will be returned to the funciton which called do_menu(menu1,...); instead of being in menu2. )

after ACTION_STD_CANCEL occurs, the callback also gets ACTION_EXIT_MENUITEM which should be used if it needs to do any post-processing....

after ACTION_STD_OK on a new menu item, the new item's callback will get ACTION_ENTER_MENUITEM. returning ACTION_EXIT_MENUITEM will stop the user entering the item., all other return values are ignored.
Finally, when the new subitem returns (unless it was a real menu) the subitems callback will get ACTION_EXIT_MENUITEM. the return value is ignored.

---+++ The text callback.
The text callback is used when a subitem has dynamic text. it is used the same as any text callback for the list widget.


---++ Examples
---+++ Basic usage, typical plugin menu
<verbatim>
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 */
}
</verbatim>
The above creates a small menu with 2 options, gives it the title "Edit What?" and runs the menu

---+++ Advanced usage
<verbatim> (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;
}
</verbatim>
r4 - 02 Aug 2007 - 10:30:13 - JonathanGordon
Parents: DocsIndex > DevelopmentGuide