|
|
How To Use the Menu APIHeadlineThis 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.MacrosThese are the important macros.
MENUITEM_SETTINGUsageUse this macro when you want to add the setting screen for a setting. The setting MUST be configured in apps/settings_list.c.Parameters
MENUITEM_SETTING_W_TEXTUsageSame as above, except the text to display either is not set in settings_list.c or you want to show different text.Parameters
MENUITEM_STRINGLIST (Important for plugins)UsageThis 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
MENUITEM_RETURNVALUEUsageSimilar to MENUITEM_STRINGLIST, except this creats a single menu item which when selected causes do_menu to return some value.Parameters
MENUITEM_RETURNVALUE_DYNTEXTUsageAs above, except the string to display is dynamic.Parameters
MENUITEM_FUNCTIONUsageCreates a menu item which when called will cause the function to be called.Parameters
MENUITEM_FUNCTION_DYNTEXTUsageAs above, except the string to display is dynamic.Parameters
MAKE_MENU (Most important macro)UsageThis is used to create a menu with item of the above macros.Parameters
Important Functionsint do_menu(const struct menu_item_ex *menu, int *start_selected); is the only function required to use the menu API.
The callback paramaterEach menu item as a callback parameter (some have two) which are used to:
the action callback.Firstly, the callback is of typeint (*menu_callback)(int action, const struct menu_item_ex *this_item);. 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.ExamplesBasic usage, typical plugin menuMENUITEM_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; } r5 - 02 Apr 2021 - 20:46:07 - UnknownUser
Copyright © by the contributing authors.
|