Bringing over fix [r11786] from 1.3 current to the porting branch.

 
Some small Fl_Sys_Menu_Bar related doc mods as per STR#3317.
WIP -- more to come; just checking in what I have for now..
 
 	1) rank -> index
 	2) Added docs for index \return values for some methods 
 	3) Some clarification in the internal docs about rank vs. index
 	4) Enabled Fl_Menu_Item's enum flags to be able to be links (added @file
 	   to Fl_Menu_Item.H) so references to e.g. "::FL_MENU_TOGGLE" will show
 	   up as links in doxygen docs.



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3-porting@11825 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

3 files changed, 30 insertions, 13 deletions

diff --git a/FL/Fl_Menu_Item.H b/FL/Fl_Menu_Item.H
index ebff23ae2..55f953db6 100644
--- a/FL/Fl_Menu_Item.H
+++ b/FL/Fl_Menu_Item.H
@@ -23,6 +23,9 @@
 #  include "Fl_Image.H"
 #  include <FL/platform_types.h> // for FL_COMMAND and FL_CONTROL
 
+// doxygen needs the following line to enable e.g. ::FL_MENU_TOGGLE to link to the enums
+/// @file
+
 enum { // values for flags:
   FL_MENU_INACTIVE = 1,		///< Deactivate menu item (gray out)
   FL_MENU_TOGGLE= 2,		///< Item is a checkbox toggle (shows checkbox for on/off state)
diff --git a/FL/Fl_Sys_Menu_Bar.H b/FL/Fl_Sys_Menu_Bar.H
index c866c083d..61d97fe52 100644
--- a/FL/Fl_Sys_Menu_Bar.H
+++ b/FL/Fl_Sys_Menu_Bar.H
@@ -70,7 +70,7 @@ public:
     return insert(index, label, fl_old_shortcut(shortcut), cb, user_data, flags);
     }
   void remove(int n);
-  void replace(int rank, const char *name);
+  void replace(int index, const char *name);
   /** Set the Fl_Menu_Item array pointer to null, indicating a zero-length menu. 
    \see Fl_Menu_::clear()
    */
diff --git a/src/Fl_Sys_Menu_Bar.mm b/src/Fl_Sys_Menu_Bar.mm
index 65141ffd8..a44039b5f 100644
--- a/src/Fl_Sys_Menu_Bar.mm
+++ b/src/Fl_Sys_Menu_Bar.mm
@@ -56,8 +56,12 @@ extern void (*fl_unlock_function)();
 
 /*  Each MacOS system menu item contains a pointer to a record of type sys_menu_item defined below.
     The purpose of these records is to associate each MacOS system menu item with a relevant Fl_Menu_Item.
+
+    Note: in the below, 'rank' is similar to an FLTK menu() 'index'.
+    Let's avoid exposing Mac internal terminology like 'rank' to FLTK users; stick with 'index'.
+
     If use_rank is YES, the "rank" field is used, and fl_sys_menu_bar->menu() + rank is the address 
-	of the relevant Fl_Menu_Item;
+    of the relevant Fl_Menu_Item;
     Otherwise, the "item" field points to the relevant Fl_Menu_Item.
     This allows the MacOS system menu to use the same Fl_Menu_Item's as those used by FLTK menus, 
     the address of which can be relocated by the FLTK menu logic.
@@ -185,7 +189,7 @@ const char *Fl_Mac_App_Menu::quit = "Quit %@";
 						action:selector
 					 keyEquivalent:@""];
   sys_menu_item smi;
-  // ≥ 0 if mitem is in the menu items of fl_sys_menu_bar, -1 if not
+  // >= 0 if mitem is in the menu items of fl_sys_menu_bar, -1 if not
   smi.rank = (fl_sys_menu_bar ? fl_sys_menu_bar->find_index(mitem) : -1);
   smi.use_rank = (smi.rank >= 0);
   if (!smi.use_rank) smi.item = mitem;
@@ -363,11 +367,19 @@ void Fl_Sys_Menu_Bar::menu(const Fl_Menu_Item *m)
 
 
 /**
- * @brief add to the system menu bar a new menu item
+ * @brief Add a new menu item to the system menu bar.
  *
- * add to the system menu bar a new menu item, with a title string, shortcut int,
+ * Add to the system menu bar a new menu item, with a title string, shortcut int,
  * callback, argument to the callback, and flags.
  *
+ * @param label     - new menu item's label
+ * @param shortcut  - new menu item's integer shortcut (can be 0 for none, or e.g. FL_ALT+'x')
+ * @param cb        - callback to be invoked when item selected (can be 0 for none, in which case the menubar's callback() can be used instead)
+ * @param user_data - argument to the callback
+ * @param flags     - item's flags, e.g. ::FL_MENU_TOGGLE, etc.
+ *
+ * \returns the index into the menu() array, where the entry was added
+ *
  * @see Fl_Menu_::add(const char* label, int shortcut, Fl_Callback *cb, void *user_data, int flags) 
  */
 int Fl_Sys_Menu_Bar::add(const char* label, int shortcut, Fl_Callback *cb, void *user_data, int flags)
@@ -380,7 +392,8 @@ int Fl_Sys_Menu_Bar::add(const char* label, int shortcut, Fl_Callback *cb, void
 
 /**
  * Forms-compatible procedure to add items to the system menu bar
-*
+ *
+ * \returns the index into the menu() array, where the entry was added
  * @see Fl_Menu_::add(const char* str) 
  */
 int Fl_Sys_Menu_Bar::add(const char* str)
@@ -394,9 +407,10 @@ int Fl_Sys_Menu_Bar::add(const char* str)
 /**
  * @brief insert in the system menu bar a new menu item
  *
- * insert in the system menu bar a new menu item, with a title string, shortcut int,
+ * Insert in the system menu bar a new menu item, with a title string, shortcut int,
  * callback, argument to the callback, and flags.
  *
+ * \returns the index into the menu() array, where the entry was inserted
  * @see Fl_Menu_::insert(int index, const char* label, int shortcut, Fl_Callback *cb, void *user_data, int flags) 
  */
 int Fl_Sys_Menu_Bar::insert(int index, const char* label, int shortcut, Fl_Callback *cb, void *user_data, int flags)
@@ -423,11 +437,11 @@ int Fl_Sys_Menu_Bar::clear_submenu(int index)
 /**
  * @brief remove an item from the system menu bar
  *
- * @param rank		the rank of the item to remove
+ * @param index		the index of the item to remove
  */
-void Fl_Sys_Menu_Bar::remove(int rank)
+void Fl_Sys_Menu_Bar::remove(int index)
 {
-  Fl_Menu_::remove(rank);
+  Fl_Menu_::remove(index);
   update();
 }
 
@@ -435,12 +449,12 @@ void Fl_Sys_Menu_Bar::remove(int rank)
 /**
  * @brief rename an item from the system menu bar
  *
- * @param rank		the rank of the item to rename
+ * @param index		the index of the item to rename
  * @param name		the new item name as a UTF8 string
  */
-void Fl_Sys_Menu_Bar::replace(int rank, const char *name)
+void Fl_Sys_Menu_Bar::replace(int index, const char *name)
 {
-  Fl_Menu_::replace(rank, name);
+  Fl_Menu_::replace(index, name);	// index
   update();
 }