From fdcfef214e67b0b1162ef4098ba960efd7049523 Mon Sep 17 00:00:00 2001
From: Fabien Costantini <fabien@onepost.net>
Date: Mon, 15 Sep 2008 00:27:28 +0000
Subject: Doxygen documentation WP7 Done. Fl_Menu_Item was a real pain to
 doxyfy.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6248 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
---
 src/Fl_Menu_add.cxx | 91 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 82 insertions(+), 9 deletions(-)

(limited to 'src/Fl_Menu_add.cxx')

diff --git a/src/Fl_Menu_add.cxx b/src/Fl_Menu_add.cxx
index ba5d0931d..7bc766948 100644
--- a/src/Fl_Menu_add.cxx
+++ b/src/Fl_Menu_add.cxx
@@ -24,7 +24,6 @@
 //
 //     http://www.fltk.org/str.php
 //
-
 // Methods to alter the menu in an Fl_Menu_ widget.
 
 // These are for Forms emulation and for dynamically changing the
@@ -97,9 +96,10 @@ static int compare(const char* a, const char* b) {
   }
 }
 
-// Add an item.  The text is split at '/' characters to automatically
-// produce submenus (actually a totally unnecessary feature as you can
-// now add submenu titles directly by setting SUBMENU in the flags):
+/** Adds an item.  The text is split at '/' characters to automatically
+   produce submenus (actually a totally unnecessary feature as you can
+   now add submenu titles directly by setting SUBMENU in the flags):
+*/
 int Fl_Menu_Item::add(
   const char *mytext,
   int sc,
@@ -175,7 +175,68 @@ int Fl_Menu_Item::add(
   if (array == local_array) local_array_size = msize;
   return m-array;
 }
-
+/**
+  Adds a new menu item, with a title string,  shortcut int (or string), 
+  callback, argument to the  callback, and flags.  
+  If the menu array was directly set with menu(x) then copy() is done 
+  to make a private array.
+  
+  <p>The characters "&", "/", "\", and "_" are treated as
+  special characters in the label string. The "&" character
+  specifies that the following character is an accelerator and
+  will be underlined. The "\" character is used to escape the next
+  character in the string. Labels starting with the "_" character
+  cause a divider to be placed after that menu item.</p>
+  
+  <p>A label of the form &quot;foo/bar/baz&quot; will create a
+  submenus called &quot;foo&quot; and &quot;bar&quot; with an
+  entry called &quot;baz&quot;. The "/" character is ignored if it
+  appears as the first character of the label string, e.g.
+  "/foo/bar/baz".</p>
+  
+  <p>The label string is copied to new memory and can be freed.
+  The other arguments (including the shortcut) are copied into the
+  menu item unchanged. </P>
+  
+  <P>If an item exists already with that name then it is replaced with
+  this new one.  Otherwise this new one is added to the end of the
+  correct menu or submenu.  The return value is the offset into the array
+  that the new entry was placed at.</P>
+  
+  <P>Shortcut can be 0L, or either a modifier/key combination (for example
+  FL_CTRL+'A') or a string describing the shortcut in one of two ways:</p>
+  
+  <pre>
+   [#+^]&lt;ascii_value&gt;    eg. "97", "^97", "+97", "#97"
+   [#+^]&lt;ascii_char&gt;     eg. "a", "^a", "+a", "#a"
+  </pre>
+  ..where &lt;ascii_value&gt; is a decimal value representing an
+  ascii character (eg. 97 is the ascii for 'a'), and the optional
+  prefixes enhance the value  that follows. Multiple prefixes must
+  appear in the above order.
+  <pre>
+   # - Alt
+   + - Shift
+   ^ - Control
+  </pre>
+  Text shortcuts are converted to integer shortcut by calling 
+  int fl_old_shortcut(const char*).
+  
+  <P>The return value is the index into the array that the entry was put. </P>
+  
+  <P>No items must be added to a menu during a callback to the same menu.</P>
+  
+  
+  <h4>int Fl_Menu_::add(const char *)</H4>
+  
+  <P>The passed string is split at any '|' characters and then
+  add(s,0,0,0,0) is done with each section. This is
+  often useful if you are just using the value, and is compatible
+  with Forms and other GL programs. The section strings use the
+  same special characters as described for the long version of add()</p>
+  
+  <P>No items must be added to a menu during a callback to the same menu.
+*/
 int Fl_Menu_::add(const char *t, int s, Fl_Callback *c,void *v,int f) {
   // make this widget own the local array:
   if (this != fl_menu_array_owner) {
@@ -218,9 +279,11 @@ int Fl_Menu_::add(const char *t, int s, Fl_Callback *c,void *v,int f) {
   return r;
 }
 
-// This is a Forms (and SGI GL library) compatable add function, it
-// adds many menu items, with '|' seperating the menu items, and tab
-// seperating the menu item names from an optional shortcut string.
+/**
+  This is a Forms (and SGI GL library) compatible add function, it
+  adds many menu items, with '|' seperating the menu items, and tab
+  separating the menu item names from an optional shortcut string.
+*/
 int Fl_Menu_::add(const char *str) {
   char buf[1024];
   int r = 0;
@@ -238,6 +301,11 @@ int Fl_Menu_::add(const char *str) {
   return r;
 }
 
+/**
+  Changes the text of item n.  This is the only way to get
+  slash into an add()'ed menu item.  If the menu array was directly set
+  with menu(x) then copy() is done to make a private array.
+*/
 void Fl_Menu_::replace(int i, const char *str) {
   if (i<0 || i>=size()) return;
   if (!alloc) copy(menu_);
@@ -247,7 +315,12 @@ void Fl_Menu_::replace(int i, const char *str) {
   }
   menu_[i].text = str;
 }
-
+/**
+  Deletes item n from the menu.  If the menu array was directly
+  set with menu(x) then copy() is done to make a private array.
+  
+  <P>No items must be removed from a menu during a callback to the same menu.
+*/
 void Fl_Menu_::remove(int i) {
   int n = size();
   if (i<0 || i>=n) return;
-- 
cgit v1.2.3