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

8 files changed, 244 insertions, 48 deletions

diff --git a/src/Fl_Menu.cxx b/src/Fl_Menu.cxx
index eeda1bcc2..a7af493df 100644
--- a/src/Fl_Menu.cxx
+++ b/src/Fl_Menu.cxx
@@ -41,7 +41,7 @@
 #ifdef __APPLE__
 #  include <Carbon/Carbon.h>
 #endif
-
+/** Size of the menu starting from this menu item */
 int Fl_Menu_Item::size() const {
   const Fl_Menu_Item* m = this;
   int nest = 0;
@@ -56,6 +56,11 @@ int Fl_Menu_Item::size() const {
   }
 }
 
+/**
+  Advance a pointer by n items through a menu array, skipping
+  the contents of submenus and invisible items.  There are two calls so
+  that you can advance through const and non-const data.
+*/
 const Fl_Menu_Item* Fl_Menu_Item::next(int n) const {
   if (n < 0) return 0; // this is so selected==-1 returns NULL
   const Fl_Menu_Item* m = this;
@@ -118,7 +123,10 @@ public:
 
 extern char fl_draw_shortcut;
 
-// width of label, including effect of & characters:
+/** 
+  Measures width of label, including effect of & characters. 
+  Optionally, can get height if hp is not NULL. 
+*/
 int Fl_Menu_Item::measure(int* hp, const Fl_Menu_* m) const {
   Fl_Label l;
   l.value   = text;
@@ -136,6 +144,7 @@ int Fl_Menu_Item::measure(int* hp, const Fl_Menu_* m) const {
   return w;
 }
 
+/** Draws the menu item in bounding box x,y,w,h, optionally selects the item. */
 void Fl_Menu_Item::draw(int x, int y, int w, int h, const Fl_Menu_* m,
 			int selected) const {
   Fl_Label l;
@@ -745,13 +754,22 @@ int menuwindow::early_hide_handle(int e) {
   return Fl_Window::handle(e);
 }
 
+/**
+  Pulldown() is similar to popup(), but a rectangle is
+  provided to position the menu.  The menu is made at least W
+  wide, and the picked item is centered over the rectangle
+  (like Fl_Choice uses).  If picked is zero or not
+  found, the menu is aligned just below the rectangle (like a pulldown
+  menu).
+  <P>The title and menubar arguments are used
+  internally by the Fl_Menu_Bar widget.
+*/
 const Fl_Menu_Item* Fl_Menu_Item::pulldown(
     int X, int Y, int W, int H,
     const Fl_Menu_Item* initial_item,
     const Fl_Menu_* pbutton,
     const Fl_Menu_Item* t,
-    int menubar) const
-{
+    int menubar) const {
   Fl_Group::current(0); // fix possible user error...
 
   button = pbutton;
@@ -894,21 +912,39 @@ const Fl_Menu_Item* Fl_Menu_Item::pulldown(
   return m;
 }
 
-const Fl_Menu_Item*
-Fl_Menu_Item::popup(
+/**
+  This method is called by widgets that want to display menus.  The menu
+  stays up until the user picks an item or dismisses it.  The selected
+  item (or NULL if none) is returned. <I>This does not do the
+  callbacks or change the state of check or radio items.</I>
+  <P>X,Y is the position of the mouse cursor, relative to the
+  window that got the most recent event (usually you can pass 
+  Fl::event_x() and Fl::event_y() unchanged here). </P>
+  <P>title is a character string title for the menu.  If
+  non-zero a small box appears above the menu with the title in it. </P>
+  <P>The menu is positioned so the cursor is centered over the item 
+  picked.  This will work even if picked is in a submenu.
+  If picked is zero or not in the menu item table the menu is
+  positioned with the cursor in the top-left corner. </P>
+  <P>button is a pointer to an 
+  Fl_Menu_ from which the color and boxtypes for the menu are
+  pulled.  If NULL then defaults are used.
+*/
+const Fl_Menu_Item* Fl_Menu_Item::popup(
   int X, int Y,
   const char* title,
   const Fl_Menu_Item* picked,
   const Fl_Menu_* but
-  ) const
-{
+  ) const {
   static Fl_Menu_Item dummy; // static so it is all zeros
   dummy.text = title;
   return pulldown(X, Y, 0, 0, picked, but, title ? &dummy : 0);
 }
 
-// Search only the top level menu for a shortcut.  Either &x in the
-// label or the shortcut fields are used:
+/**
+  Search only the top level menu for a shortcut.  
+  Either &x in the label or the shortcut fields are used. 
+*/
 const Fl_Menu_Item* Fl_Menu_Item::find_shortcut(int* ip) const {
   const Fl_Menu_Item* m = first();
   if (m) for (int ii = 0; m->text; m = m->next(), ii++) {
@@ -925,6 +961,14 @@ const Fl_Menu_Item* Fl_Menu_Item::find_shortcut(int* ip) const {
 
 // Recursive search of all submenus for anything with this key as a
 // shortcut.  Only uses the shortcut field, ignores &x in the labels:
+/**
+  This is designed to be called by a widgets handle() method in
+  response to a FL_SHORTCUT event.  If the current event matches
+  one of the items shortcut, that item is returned.  If the keystroke
+  does not match any shortcuts then NULL is returned.  This only
+  matches the shortcut() fields, not the letters in the title
+  preceeded by '
+*/
 const Fl_Menu_Item* Fl_Menu_Item::test_shortcut() const {
   const Fl_Menu_Item* m = first();
   const Fl_Menu_Item* ret = 0;
diff --git a/src/Fl_Menu_.cxx b/src/Fl_Menu_.cxx
index 1a8e12691..c875a6688 100644
--- a/src/Fl_Menu_.cxx
+++ b/src/Fl_Menu_.cxx
@@ -24,7 +24,6 @@
 //
 //     http://www.fltk.org/str.php
 //
-
 // This is a base class for all items that have a menu:
 //	Fl_Menu_Bar, Fl_Menu_Button, Fl_Choice
 // This provides storage for a menu item, functions to add/modify/delete
@@ -38,15 +37,15 @@
 #include <stdio.h>
 #include <stdlib.h>
 
-// Set 'pathname' of specified menuitem
-//    If finditem==NULL, mvalue() is used (the most recently picked menuitem)
-//    Returns:
-//       0 : OK
-//      -1 : item not found (name="")
-//      -2 : 'name' not large enough (name="")
-//
-#define SAFE_STRCAT(s) \
-    { len += strlen(s); if ( len >= namelen ) { *name='\0'; return(-2); } else strcat(name,(s)); }
+#define SAFE_STRCAT(s) { len += strlen(s); if ( len >= namelen ) { *name='\0'; return(-2); } else strcat(name,(s)); }
+
+/** Set 'pathname' of specified menuitem
+    If finditem==NULL, mvalue() is used (the most recently picked menuitem)
+    Returns:
+    -   0 : OK
+    -  -1 : item not found (name="")
+    -  -2 : 'name' not large enough (name="")
+*/
 int Fl_Menu_::item_pathname(char *name, int namelen, const Fl_Menu_Item *finditem) const {
     int len = 0;
     finditem = finditem ? finditem : mvalue();    
@@ -75,14 +74,13 @@ int Fl_Menu_::item_pathname(char *name, int namelen, const Fl_Menu_Item *findite
     return(-1);						// item not found
 }
 
-// FIND MENU ITEM INDEX, GIVEN MENU PATHNAME
-//     eg. "Edit/Copy"
-//     Will also return submenus, eg. "Edit"
-//     Returns NULL if not found.
-//
-const Fl_Menu_Item *
-Fl_Menu_::find_item(const char *name)
-{
+/**
+  Find menu item index, given menu pathname
+     eg. "Edit/Copy"
+     Will also return submenus, eg. "Edit"
+     Returns NULL if not found.
+*/
+const Fl_Menu_Item * Fl_Menu_::find_item(const char *name) {
   char menupath[1024] = "";	// File/Export
 
   for ( int t=0; t < size(); t++ ) {
@@ -115,15 +113,23 @@ Fl_Menu_::find_item(const char *name)
   return (const Fl_Menu_Item *)0;
 }
 
+/**
+  The value is the index into menu() of the last item chosen by
+  the user.  It is zero initially.  You can set it as an integer, or set
+  it with a pointer to a menu item.  The set routines return non-zero if
+  the new value is different than the old one.
+*/
 int Fl_Menu_::value(const Fl_Menu_Item* m) {
   clear_changed();
   if (value_ != m) {value_ = m; return 1;}
   return 0;
 }
 
-// When user picks a menu item, call this.  It will do the callback.
-// Unfortunatly this also casts away const for the checkboxes, but this
-// was necessary so non-checkbox menus can really be declared const...
+/** 
+ When user picks a menu item, call this.  It will do the callback.
+ Unfortunatly this also casts away const for the checkboxes, but this
+ was necessary so non-checkbox menus can really be declared const...
+*/
 const Fl_Menu_Item* Fl_Menu_::picked(const Fl_Menu_Item* v) {
   if (v) {
     if (v->radio()) {
@@ -150,7 +156,7 @@ const Fl_Menu_Item* Fl_Menu_::picked(const Fl_Menu_Item* v) {
   return v;
 }
 
-// turn on one of a set of radio buttons
+/** Turns the radio item &quot;on&quot; for the menu item and turns off adjacent radio items set. */
 void Fl_Menu_Item::setonly() {
   flags |= FL_MENU_RADIO | FL_MENU_VALUE;
   Fl_Menu_Item* j;
@@ -167,6 +173,10 @@ void Fl_Menu_Item::setonly() {
 }
 
 Fl_Menu_::Fl_Menu_(int X,int Y,int W,int H,const char* l)
+/**
+  Creates a new Fl_Menu_ widget using the given position, size,
+  and label string.  menu() is initialized to null.
+*/
 : Fl_Widget(X,Y,W,H,l) {
   set_flag(SHORTCUT_LABEL);
   box(FL_UP_BOX);
@@ -180,11 +190,24 @@ Fl_Menu_::Fl_Menu_(int X,int Y,int W,int H,const char* l)
   down_box(FL_NO_BOX);
 }
 
+/**
+  This returns the number of Fl_Menu_Item structures that make up the
+  menu, correctly counting submenus.  This includes the "terminator"
+  item at the end.  To copy a menu array you need to copy
+  size()*sizeof(Fl_Menu_Item) bytes.  If the menu is
+  NULL this returns zero (an empty menu will return 1).
+*/
 int Fl_Menu_::size() const {
   if (!menu_) return 0;
   return menu_->size();
 }
 
+/**
+    Sets the menu array pointer directly.  If the old menu is private it is
+    deleted.  NULL is allowed and acts the same as a zero-length
+    menu.  If you try to modify the array (with add(), replace(), or
+    delete()) a private copy is automatically done.
+*/
 void Fl_Menu_::menu(const Fl_Menu_Item* m) {
   clear();
   value_ = menu_ = (Fl_Menu_Item*)m;
@@ -192,6 +215,11 @@ void Fl_Menu_::menu(const Fl_Menu_Item* m) {
 
 // this version is ok with new Fl_Menu_add code with fl_menu_array_owner:
 
+/** 
+  Sets the menu array pointer with a copy of m that will be automatically deleted. 
+  If ud is not NULL, then all user data pointers are changed in the menus as well.
+  See void Fl_Menu_::menu(const Fl_Menu_Item* m). 
+*/
 void Fl_Menu_::copy(const Fl_Menu_Item* m, void* ud) {
   int n = m->size();
   Fl_Menu_Item* newMenu = new Fl_Menu_Item[n];
@@ -213,6 +241,12 @@ Fl_Menu_::~Fl_Menu_() {
 // expanding array.  We must not free this array:
 Fl_Menu_* fl_menu_array_owner = 0;
 
+/**
+  Same as menu(NULL), set the array pointer to null, indicating
+  a zero-length menu.
+  
+  <P>Menus must no be cleared during a callback to the same menu.
+*/
 void Fl_Menu_::clear() {
   if (alloc) {
     if (alloc>1) for (int i = size(); i--;)
diff --git a/src/Fl_Menu_Button.cxx b/src/Fl_Menu_Button.cxx
index a3c13a829..5474cbaaf 100644
--- a/src/Fl_Menu_Button.cxx
+++ b/src/Fl_Menu_Button.cxx
@@ -47,6 +47,13 @@ void Fl_Menu_Button::draw() {
   fl_line(X+H, Y, X+H/2, Y+H);
 }
 
+/**
+  Act exactly as though the user clicked the button or typed the
+  shortcut key.  The menu appears, it waits for the user to pick an item,
+  and if they pick one it sets value() and does the callback or
+  sets changed() as described above.  The menu item is returned
+  or NULL if the user dismisses the menu.
+*/
 const Fl_Menu_Item* Fl_Menu_Button::popup() {
   const Fl_Menu_Item* m;
   pressed_menu_button_ = this;
@@ -101,6 +108,12 @@ int Fl_Menu_Button::handle(int e) {
   }
 }
 
+/**
+  Creates a new Fl_Menu_Button widget using the given position,
+  size, and label string. The default boxtype is FL_UP_BOX.
+  <P>The constructor sets menu() to NULL.  See 
+  Fl_Menu_ for the methods to set or change the menu.
+*/
 Fl_Menu_Button::Fl_Menu_Button(int X,int Y,int W,int H,const char *l)
 : Fl_Menu_(X,Y,W,H,l) {
   down_box(FL_NO_BOX);
diff --git a/src/Fl_Menu_Window.cxx b/src/Fl_Menu_Window.cxx
index ece82ce30..2b463f3bc 100644
--- a/src/Fl_Menu_Window.cxx
+++ b/src/Fl_Menu_Window.cxx
@@ -78,6 +78,7 @@ void Fl_Menu_Window::flush() {
 #endif
 }
 
+/** Erases the window, does nothing if HAVE_OVERLAY is not defined config.h */
 void Fl_Menu_Window::erase() {
 #if HAVE_OVERLAY
   if (!gc || !shown()) return;
@@ -94,6 +95,7 @@ void Fl_Menu_Window::hide() {
   Fl_Single_Window::hide();
 }
 
+/**  Destroys the window and all of its children.*/
 Fl_Menu_Window::~Fl_Menu_Window() {
   hide();
 }
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;
diff --git a/src/Fl_Menu_global.cxx b/src/Fl_Menu_global.cxx
index b7cba6faf..ebfb7965e 100644
--- a/src/Fl_Menu_global.cxx
+++ b/src/Fl_Menu_global.cxx
@@ -40,6 +40,16 @@ static int handler(int e) {
   return the_widget->handle(e);
 }
 
+/**
+  Make the shortcuts for this menu work no matter what window has the
+  focus when you type it.  This is done by using 
+  Fl::add_handler().  This Fl_Menu_ widget does not
+  have to be visible (ie the window it is in can be hidden, or it does
+  not have to be put in a window at all).
+  <P>Currently there can be only one global()menu.  Setting a new
+  one will replace the old one.  There is no way to remove the 
+  global() setting (so don't destroy the widget!)
+*/
 void Fl_Menu_::global() {
   if (!the_widget) Fl::add_handler(handler);
   the_widget = this;
diff --git a/src/Fl_Progress.cxx b/src/Fl_Progress.cxx
index 69e76492c..ee311a326 100644
--- a/src/Fl_Progress.cxx
+++ b/src/Fl_Progress.cxx
@@ -25,6 +25,7 @@
 //     http://www.fltk.org/str.php
 //
 // Contents:
+
 //
 //   Fl_Progress::draw()        - Draw the check button.
 //   Fl_Progress::Fl_Progress() - Construct a Fl_Progress widget.
@@ -49,6 +50,7 @@
 // 'Fl_Progress::draw()' - Draw the check button.
 //
 
+/** Draws the check button. */
 void Fl_Progress::draw()
 {
   int	progress;	// Size of progress bar...
@@ -96,13 +98,13 @@ void Fl_Progress::draw()
 }
 
 
-//
-// 'Fl_Progress::Fl_Progress()' - Construct a Fl_Progress widget.
-//
-
+/**  
+    The constructor creates the progress bar using the position,
+    size, and label.
+    <P> The inherited destructor removes the progress bar.
+*/
 Fl_Progress::Fl_Progress(int X, int Y, int W, int H, const char* l)
-: Fl_Widget(X, Y, W, H, l)
-{
+: Fl_Widget(X, Y, W, H, l) {
   align(FL_ALIGN_INSIDE);
   box(FL_DOWN_BOX);
   color(FL_BACKGROUND2_COLOR, FL_YELLOW);
diff --git a/src/forms_timer.cxx b/src/forms_timer.cxx
index 031d67f27..33627761d 100644
--- a/src/forms_timer.cxx
+++ b/src/forms_timer.cxx
@@ -126,11 +126,28 @@ int Fl_Timer::handle(int event) {
   return 0;
 }
 
+/**
+ Destroys the timer and removes the timeout.
+*/
 Fl_Timer::~Fl_Timer() {
   Fl::remove_timeout(stepcb, this);
 }
 
+/**
+  Creates a new Fl_Timer widget using the given type, position,
+  size, and label string. The type parameter can be any of the
+  following symbolic constants:
+  <UL>
+  <LI>FL_NORMAL_TIMER - The timer just does the callback  and
+  displays the string &quot;Timer&quot; in the widget. </LI>
+  <LI>FL_VALUE_TIMER - The timer does the callback and  displays
+  the current timer value in the widget. </LI>
+  <LI>FL_HIDDEN_TIMER - The timer just does the callback  and
+  does not display anything. </LI>
+  </UL>
+*/
 Fl_Timer::Fl_Timer(uchar t, int X, int Y, int W, int H, const char* l)
+
 : Fl_Widget(X, Y, W, H, l) {
   box(FL_DOWN_BOX);
   selection_color(FL_RED);
@@ -141,7 +158,7 @@ Fl_Timer::Fl_Timer(uchar t, int X, int Y, int W, int H, const char* l)
   if (t == FL_HIDDEN_TIMER) clear_visible();
   if (t == FL_VALUE_TIMER) align(FL_ALIGN_LEFT);
 }
-
+/** Sets the current timer value */
 void Fl_Timer::value(double d) {
   delay = total = d;
   on = (d > 0.0);
@@ -151,6 +168,7 @@ void Fl_Timer::value(double d) {
   if (on) Fl::add_timeout(FL_TIMER_BLINKRATE, stepcb, this);
 }
 
+/** Gets or sets whether the timer is suspended.*/
 void Fl_Timer::suspended(char d) {
   if (!d) {
     if (on) return;