Update some comments in menu.h to be hopefully more helpful.

Fix all the wrong usage of rb->do_menu() (my fault, sorry)


git-svn-id: svn://svn.rockbox.org/rockbox/trunk@13439 a1c6a512-1295-4272-9138-f99709370657

apps/menu.h

@@ -98,9 +98,26 @@ struct menu_item_ex {
 
 typedef int (*menu_callback_type)(int action,
                                   const struct menu_item_ex *this_item);
-int do_menu(const struct menu_item_ex *menu, int *start_selected);
 bool do_setting_from_menu(const struct menu_item_ex *temp);
 
+/* 
+   int do_menu(const struct menu_item_ex *menu, int *start_selected)
+    
+   Return value - usually one of the GO_TO_* values from root_menu.h,
+   however, some of the following defines can cause this to 
+   return a different value.
+   
+   *menu - The menu to run, can be a pointer to a MAKE_MENU() variable,
+            MENUITEM_STRINGLIST() or MENUITEM_RETURNVALUE() variable.
+            
+   *start_selected - the item to select when the menu is first run.
+                     When do_menu() returns, this will be set to the 
+                     index of the selected item at the time of the exit.
+                     This is always set, even if the menu was cancelled.
+                     If NULL it is ignored and the firs item starts selected
+*/
+int do_menu(const struct menu_item_ex *menu, int *start_selected);
+
 /* In all the following macros the argument names are as follows:
     - name: The name for the variable (so it can be used in a MAKE_MENU()
     - str:  the string to display for this menu item. use ID2P() for LANG_* id's
@@ -126,8 +143,9 @@ bool do_setting_from_menu(const struct menu_item_ex *temp);
             {.callback_and_desc = & name##__}};
 
 /*  Use this To create a list of Strings (or ID2P()'s )
-    When the user enters this list and selects one, the menu will exits
-    and its return value will be the index of the chosen item */
+    When the user enters this list and selects one, the menu will exit
+    and do_menu() will return value the index of the chosen item.
+    if the user cancels, GO_TO_PREVIOUS will be returned */
 #define MENUITEM_STRINGLIST(name, str, callback, ... )                  \
     static const char *name##_[] = {__VA_ARGS__};                       \
     static const struct menu_callback_with_desc name##__ =              \
@@ -138,7 +156,7 @@ bool do_setting_from_menu(const struct menu_item_ex *temp);
             { .strings = name##_},{.callback_and_desc = & name##__}};
 
             
-/* returns a value associated with the item */
+/* causes do_menu() to return a value associated with the item */
 #define MENUITEM_RETURNVALUE(name, str, val, cb, icon)                      \
      static const struct menu_callback_with_desc name##_ = {cb,str,icon};   \
      static const struct menu_item_ex name   =                              \

apps/plugins/chessbox/chessbox.c

@@ -528,8 +528,7 @@ static int cb_menu(void)
 
     while(!menu_quit)
     {
-        selection = rb->do_menu(&menu, &selection);
-        switch(selection)
+        switch(rb->do_menu(&menu, &selection))
         {
             case 0:
                 menu_quit = true;

apps/plugins/chopper.c

@@ -647,8 +647,7 @@ static int chopMenu(int menunum)
     rb->lcd_clear_display();
 
     while (!menu_quit) {
-        result=rb->do_menu(&menu,&result);
-        switch (result)
+        switch(rb->do_menu(&menu, &result))
         {
             case 0:     /* Start New Game */
                 menu_quit=true;

apps/plugins/dice.c

@@ -235,8 +235,7 @@ static bool dice_menu(int *num_dice, int *side_index) {
     };
                       
     while (!menu_quit) {
-        selection = rb->do_menu(&menu, &selection);
-        switch(selection)
+        switch(rb->do_menu(&menu, &selection))
         {
             case 0:
                 menu_quit = true;

apps/plugins/disktidy.c

@@ -355,8 +355,7 @@ int tidy_lcd_menu(void)
                       
     while (!menu_quit)
     {    
-        selection = rb->do_menu(&menu,&selection);
-        switch(selection)
+        switch(rb->do_menu(&menu, &selection))
         {
          
             case 0:

apps/plugins/minesweeper.c

@@ -410,8 +410,7 @@ enum minesweeper_status menu( void )
 #endif
 
     while (!menu_quit) {
-        selection=rb->do_menu(&menu,&selection);
-        switch(selection)
+        switch(rb->do_menu(&menu, &selection))
         {
             case 0:
                 result = MINESWEEPER_WIN; /* start playing */

apps/plugins/snake.c

@@ -342,8 +342,7 @@ void game_init(void) {
                         "Quit");
                                            
     while (!menu_quit) {
-        selection = rb->do_menu(&menu, &selection);
-        switch(selection)
+        switch(rb->do_menu(&menu, &selection))
         {
             case 0:
                 menu_quit = true; /* start playing */

apps/plugins/star.c

@@ -876,8 +876,7 @@ static int star_menu(void)
     
     while(!menu_quit)
     {
-        selection = rb->do_menu(&menu, &selection);
-        switch(selection)
+        switch(rb->do_menu(&menu, &selection))
         {
             case 0:
                 menu_quit = true;

apps/plugins/test_codec.c

@@ -452,7 +452,7 @@ enum plugin_status plugin_start(struct plugin_api* api, void* parameter)
     unsigned char* codec_stack_copy;
     size_t codec_stack_size;
     struct thread_entry* codecthread_id;
-    int result;
+    int result, selection = 0;
     char* ch;
     int line = 0;
 
@@ -529,7 +529,7 @@ enum plugin_status plugin_start(struct plugin_api* api, void* parameter)
 
     rb->lcd_clear_display();
 
-    result=rb->do_menu(&menu,&result);
+    result=rb->do_menu(&menu,&selection);
 
     if (result==0) {
         wavinfo.fd = -1;

apps/plugins/wavrecord.c

@@ -3717,9 +3717,8 @@ static int recording_menu(void)
                         "Set channels", "Set Source", "Start recording", "Quit");
 
     while (!done)
-    {   
-        rb->do_menu(&menu, &result);
-        switch (result)
+    {
+        switch (rb->do_menu(&menu, &result))
         {
             case 0: /* Set sample rate */
                 rb->set_option("Sample rate", &reccfg.samplerate, INT, freqs, 9, NULL);

apps/plugins/wormlet.c

@@ -2533,9 +2533,7 @@ enum plugin_status plugin_start(struct plugin_api* api, void* parameter)
     rb->button_clear_queue();
 
     while (!menu_quit) {
-        result = rb->do_menu(&menu, &result);
-
-        switch(result)
+        switch(rb->do_menu(&menu, &result))
         {
             case 0:
                 rb->lcd_setfont(FONT_SYSFIXED);