How to help with the settings recode work

This is a work in progress , so for the time being just ignore me... I've just realised it will be too difficult to commit and manage this effort without a bit more work.

What This Is

This page willl briefly explain how to help convert the ~200 settings and menus in rockbox to using the new system. The idea being that once this is finished it will be much easier to add/remove/edit settings, and hopefully there will be a drop in the binary size.

Important source files

• settings_list.c - every setting in global_settings should be in here and setup correctly, this is where most of the work will be done
• settings_list.h - hopefully this wont need editing. Important reference (if you need it) for the .c
• menu.h - reference for the next lot of files
• apps/*_menu.c - we want to eventually delete these files
• apps/menus/*.c - the menus from the above files will be moved to here in a neat manner. (1 .c for each major submenu)

Where we are now

• the main menu (in menus/main_menu.c) will be fully setup for the new system, each item will be a MENUITEM_FUNCTION() type to call the current menu functions (this will make sense soon)
• NO settings will be converted yet.

How to help

There are 2 parts to each setting that ends up in the menu. The first part is its "definition" in settings_list.c which will be made up of one of the following macros

• SOUND_SETTING() - used for settings which currently call set_sound() to configure it (these are mostly done)
• OFFON_SETTING() - settings which use "Enabled" "Disabled" in the setting screen and save to "off" "on" in the cfg (must be type bool)
• BOOL_SETTING() - type bool which can use any string in the cfg and any LANG_ id in the setting windows for the options.
• SYSTEM_SETTING() - "settings" which the user doesnt touch, no more should be added, but just in case...
• FILENAME_SETTING() - settings which store a filename
• CHOICE_SETTING() - settings which used to call set_option()
• INT_SETTING() - settings which used to call set_int()

add an actuall explanation of each macro if its needed

The 2nd part of the setting is its position in one of the apps/menus/ files. Ideally these will be one .c for each major sub menu (one for playback menu, one for display, etc) but if they become too messy we can split them more. The macros in menu.h

• MENUITEM_SETTING() - points to a setting in settings_list.c, if this is called the user will be put in the setting screen for that option
• MAKE_MENU() - is an array containing pointers to any of these macros
• MENUITEM_STRINGLIST() - will be used by plugins mostly, alows a menu to be created from a list of strings, each string being an item, and the menu returning the index of the chosen string.
• MENUITEM_FUNCTION() - if the user selects an item in the menu of this type the function it points to will be called.
• MENUITEM_FUNCTION_WPARAM() - same as above, but a void* can be passed to the function.

Now, at the time of commit, each of these submenus will just be a MAKE_FUNCTION_CALL() type pointing back into apps/*_menu.c. What needs to be done is each of these needs to be converted to used.

Really what needs to be done

To actually help, you need to choose an item in any of the not completed menus to work through. The "easiest" ones are ones which only have settings or function calls as items. For example, the debug menu.

If the sub menu you choose is big enough for its own file create it in apps/menus and make sure you add a pointer to the "main menu" of the file in apps/menus/exported_menus.h. (Use the MAKE_MENU() macro to create the actual menu, example in menus/main_menu.c).

Now you need to use one of the 2nd set of macros above for each of this menus items. The easiest is the MAKE_SETTING_OPT() which requires a name (so the struct can be included in the menu), a pointer to the item in settings_list.c (using the variables * as the link), and a callback (see below). Now each time you use this macro you willl need to edit settings_list.c to complete the setting "definition" in that array (by using one of the first set of macros above)

Now once your menu is ready, you need to tell the current menu to run it. Either add the & to the menu you want it put into, or if there are submenus between the current bottom of the menu and your menu you will need to change your parent menu to do_menu(&my_menu);

e.g

You changed the crossfeed menu to the new system, but the sound menu (crossfeed is a sub menu of sound menu) still uses the old system, So all you need to do is change static bool crossfeed_menu(void) to look like

MAKE_MENU(crossfeed_menu_item, ... );
static bool crossfeed_menu(void)
{
   return (bool)do_menu(&crossfeed_menu_item);
}

Then submit a patch, have it commited and move on to the next bit

Order of calls to the menu callback functions

1. Before a MAKE_MENU() type is entered, each of its items recieves the ACTION_REQUEST_MENUITEM action
   1. If the item returns ACTION_EXIT_MENUITEM it will not be displayed
   2. anthing else and it will be displayed
2. every time the user presses a key the menu will recieve the action before it is acted on by the menu code, you can change the key by returning a different action, (e.g ACTION_STD_OK will signal the user is enetring a subitem)
   1. the subitem will then get ACTION_ENTER_MENUITEM to its callback, returnning ACTION_EXIT_MENUITEM will back out
      1. if the sub item is a menu, goto the start of this table.
   2. when the subitem exits, its callback will get the ACTION_EXIT_MENUITEM action and its return value is ignored.
      1. If the sub item was a menu, the parent menu will send ACTION_REQUEST_MENUITEM to each of its items again to decide which to display.

Questions and comments