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

7 files changed, 391 insertions, 6 deletions

diff --git a/FL/Fl_Menu_.H b/FL/Fl_Menu_.H
index 04cd4519b..583f44440 100644
--- a/FL/Fl_Menu_.H
+++ b/FL/Fl_Menu_.H
@@ -33,6 +33,15 @@
 #endif
 #include "Fl_Menu_Item.H"
 
+/**
+  Base class of all widgets that have a menu in FLTK.
+  Currently FLTK provides you with 
+  Fl_Menu_Button, Fl_Menu_Bar, and Fl_Choice.
+  
+  <P>The class contains a pointer to an array of structures of type  Fl_Menu_Item.  The
+  array may either be supplied directly by the user program, or it may
+  be "private": a dynamically allocated array managed by the Fl_Menu_.
+*/
 class FL_EXPORT Fl_Menu_ : public Fl_Widget {
 
   Fl_Menu_Item *menu_;
@@ -57,41 +66,99 @@ public:
   const Fl_Menu_Item* test_shortcut() {return picked(menu()->test_shortcut());}
   void global();
 
+  /**
+    Returns a pointer to the array of Fl_Menu_Items.  This will either be
+    the value passed to menu(value) or the private copy.
+  */  
   const Fl_Menu_Item *menu() const {return menu_;}
   void menu(const Fl_Menu_Item *m);
   void copy(const Fl_Menu_Item *m, void* user_data = 0);
   int  add(const char*, int shortcut, Fl_Callback*, void* = 0, int = 0);
-  int  add(const char* a, const char* b, Fl_Callback* c,
-	  void* d = 0, int e = 0) {return add(a,fl_old_shortcut(b),c,d,e);}
+  /** See int Fl_Menu_::add(const char* label, int shortcut, Fl_Callback*, void *user_data=0, int flags=0)*/
+  int  add(const char* a, const char* b, Fl_Callback* c, void* d = 0, int e = 0) {
+      return add(a,fl_old_shortcut(b),c,d,e);}
+  int  add(const char *);
   int  size() const ;
   void size(int W, int H) { Fl_Widget::size(W, H); }
   void clear();
-  int  add(const char *);
   void replace(int,const char *);
   void remove(int);
+ /** Changes the shortcut of item i to n.  */
   void shortcut(int i, int s) {menu_[i].shortcut(s);}
+  /** Sets the flags of item i.  For a list of the flags, see Fl_Menu_Item.  */
   void mode(int i,int fl) {menu_[i].flags = fl;}
+  /** Gets the flags of item i.  For a list of the flags, see Fl_Menu_Item.  */
   int  mode(int i) const {return menu_[i].flags;}
 
+  /** Returns a pointer to the last menu item that was picked.  */
   const Fl_Menu_Item *mvalue() const {return value_;}
+  /** Returns the index into menu() of the last item chosen by the user.  It is zero initially. */
   int value() const {return value_ ? (int)(value_-menu_) : -1;}
   int value(const Fl_Menu_Item*);
+  /**
+    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 value(int i) {return value(menu_+i);}
+  /** Returns the title of the last item chosen, or of item i.  */
   const char *text() const {return value_ ? value_->text : 0;}
+  /** Returns the title of the last item chosen, or of item i.  */
   const char *text(int i) const {return menu_[i].text;}
 
+  /** Gets the current font of menu item labels.  */
   Fl_Font textfont() const {return textfont_;}
+  /**  Sets the current font of menu item labels.  */
   void textfont(Fl_Font c) {textfont_=c;}
+  /**  Gets the font size of menu item labels.  */
   Fl_Fontsize textsize() const {return textsize_;}
+  /**  Sets the font size of menu item labels.  */
   void textsize(Fl_Fontsize c) {textsize_=c;}
+  /** Get the current color of menu item labels.  */
   Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
+  /** Sets the current color of menu item labels. */
   void textcolor(unsigned c) {textcolor_=c;}
 
+  /**
+    This box type is used to surround the currently-selected items in the
+    menus.  If this is FL_NO_BOX then it acts like 
+    FL_THIN_UP_BOX and selection_color() acts like 
+    FL_WHITE, for back compatability.
+    
+    
+    <h4>const Fl_Menu_Item *Fl_Menu_::find_item(const char *name);</h4>
+    
+    <p>Returns a pointer to the menu item with the given (full)
+    pathname. If no matching menu item can be found, a NULL pointer
+    is returned. This function does not search submenus that are linked
+    via FL_SUBMENU_POINTER.</p>
+    
+    
+    <h4>int Fl_Menu_::item_pathname(char *name, int namelen ) const;<br>
+    int Fl_Menu_::item_pathname(char *name, int namelen, const Fl_Menu_Item *finditem) const;</h4>
+    
+    <p>Returns the 'menu pathname' (eg. "File/Quit") for the recently picked item in user supplied string 'name'. Useful in the callback function for a menu item, to determine the last picked item's 'menu pathname' string.
+    
+    <p>If finditem is specified, name will contain the 'menu pathname' for that item.
+    
+    <p>Returns:
+    
+    <ul>
+    	<li>0 - OK: 'name' has the pathname, guaranteed not longer than namelen
+    	<li>-1 - Failed: 'finditem' was not found in the menu
+    	<li>-2 - Failed: 'name' is not large enough to handle the menu names
+    </ul>
+    
+    <p>In the case of errors (-1 or -2), 'name' will be an empty string.
+  */
   Fl_Boxtype down_box() const {return (Fl_Boxtype)down_box_;}
+  /**    See Fl_Boxtype Fl_Menu_::down_box() const   */
   void down_box(Fl_Boxtype b) {down_box_ = b;}
 
-  // back compatability:
+  /** For back compatability, same as selection_color() */
   Fl_Color down_color() const {return selection_color();}
+  /** For back compatability, same as selection_color() */
   void down_color(unsigned c) {selection_color(c);}
 };
 
diff --git a/FL/Fl_Menu_Bar.H b/FL/Fl_Menu_Bar.H
index 42c7d2949..074821838 100644
--- a/FL/Fl_Menu_Bar.H
+++ b/FL/Fl_Menu_Bar.H
@@ -30,11 +30,50 @@
 
 #include "Fl_Menu_.H"
 
+/**
+  This widget provides a standard menubar interface.  Usually you will
+  put this widget along the top edge of your window.  The height of the
+  widget should be 30 for the menu titles to draw correctly with the
+  default font.
+  <P>The items on the bar and the menus they bring up are defined by a
+  single Fl_Menu_Item
+  array.  Because a Fl_Menu_Item array defines a hierarchy, the
+  top level menu defines the items in the menubar, while the submenus
+  define the pull-down menus. Sub-sub menus and lower pop up to the right
+  of the submenus. </P>
+  <P ALIGN=CENTER>\image html  src=</P>
+  <P>If there is an item in the top menu that is not a title of a
+  submenu, then it acts like a &quot;button&quot; in the menubar.  Clicking on it
+  will pick it. </P>
+  <P>When the user picks an item off the menu, the item's callback is
+  done with the menubar as the Fl_Widget* argument.  If the item
+  does not have a callback the menubar's callback is done instead. </P>
+  <P>Submenus will also pop up in response to shortcuts indicated by
+  putting a '&' character in the name field of the menu item. If you put a
+  '&' character in a top-level &quot;button&quot; then the shortcut picks it.  The
+  '&' character in submenus is ignored until the menu is popped up. </P>
+  <P>Typing the shortcut() of any of the menu items will cause
+  callbacks exactly the same as when you pick the item with the mouse.
+*/
 class FL_EXPORT Fl_Menu_Bar : public Fl_Menu_ {
 protected:
     void draw();
 public:
     int handle(int);
+  /**
+      Creates a new Fl_Menu_Bar 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. </P>
+    <P>labelsize(), labelfont(), and labelcolor()
+    are used to control how the menubar items are drawn.  They are
+    initialized from the Fl_Menu static variables, but you can
+    change them if desired. </P>
+    <P>label() is ignored unless you change align() to
+    put it outside the menubar.
+    <P>The destructor removes the Fl_Menu_Bar widget and all of its
+    menu items.
+  */
     Fl_Menu_Bar(int X, int Y, int W, int H,const char *l=0)
       : Fl_Menu_(X,Y,W,H,l) {}
 };
diff --git a/FL/Fl_Menu_Button.H b/FL/Fl_Menu_Button.H
index b0d669a05..7acebcef0 100644
--- a/FL/Fl_Menu_Button.H
+++ b/FL/Fl_Menu_Button.H
@@ -30,6 +30,26 @@
 
 #include "Fl_Menu_.H"
 
+/**
+  This is a button that when pushed pops up a menu (or hierarchy of
+  menus) defined by an array of 
+  Fl_Menu_Item objects.
+  <P ALIGN=CENTER>\image html  src=</P>
+  <P>Normally any mouse button will pop up a menu and it is lined up
+  below the button as shown in the picture.  However an Fl_Menu_Button
+  may also control a pop-up menu.  This is done by setting the type()
+  , see below. </P>
+  <P>The menu will also pop up in response to shortcuts indicated by
+  putting a '&' character in the label(). </P>
+  <P>Typing the shortcut() of any of the menu items will cause
+  callbacks exactly the same as when you pick the item with the mouse.
+  The '&' character in menu item names are only looked at when the menu is
+  popped up, however. </P>
+  <P>When the user picks an item off the menu, the item's callback is
+  done with the menu_button as the Fl_Widget* argument.  If the
+  item does not have a callback the menu_button's callback is done
+  instead.
+*/
 class FL_EXPORT Fl_Menu_Button : public Fl_Menu_ {
 protected:
   void draw();
diff --git a/FL/Fl_Menu_Item.H b/FL/Fl_Menu_Item.H
index a302a5446..6e4908951 100644
--- a/FL/Fl_Menu_Item.H
+++ b/FL/Fl_Menu_Item.H
@@ -51,6 +51,70 @@ extern FL_EXPORT int fl_old_shortcut(const char*);
 
 class Fl_Menu_;
 
+/**
+  The Fl_Menu_Item structure defines a single menu item that
+  is used by the Fl_Menu_ class.  
+  <UL>
+  <PRE>
+  struct Fl_Menu_Item {
+   const char*	        text; // label()
+   ulong		shortcut_;
+   Fl_Callback*	        callback_;
+   void*		user_data_;
+   int		        flags;
+   uchar		labeltype_;
+   uchar		labelfont_;
+   uchar		labelsize_;
+   uchar		labelcolor_;
+  };
+  
+  enum { // values for flags:
+   FL_MENU_INACTIVE	= 1,
+   FL_MENU_TOGGLE	= 2,
+   FL_MENU_VALUE	= 4,
+   FL_MENU_RADIO	= 8,
+   FL_MENU_INVISIBLE	= 0x10,
+   FL_SUBMENU_POINTER	= 0x20,
+   FL_SUBMENU		= 0x40,
+   FL_MENU_DIVIDER	= 0x80,
+   FL_MENU_HORIZONTAL	= 0x100
+  };
+  </PRE>
+  </UL>
+  Typically menu items are statically defined; for example:
+  <UL><PRE>
+  Fl_Menu_Item popup[] = {
+   {&quot;&alpha&quot;,   FL_ALT+'a', the_cb, (void*)1},
+   {&quot;&beta&quot;,    FL_ALT+'b', the_cb, (void*)2},
+   {&quot;gamma&quot;,    FL_ALT+'c', the_cb, (void*)3, FL_MENU_DIVIDER},
+   {&quot;&strange&quot;,  0,   strange_cb},
+   {&quot;&charm&quot;,    0,   charm_cb},
+   {&quot;&truth&quot;,    0,   truth_cb},
+   {&quot;b&eauty&quot;,   0,   beauty_cb},
+   {&quot;sub&menu&quot;,  0,   0, 0, FL_SUBMENU},
+   {&quot;one&quot;},
+   {&quot;two&quot;},
+   {&quot;three&quot;},
+   {0},
+   {&quot;inactive&quot;, FL_ALT+'i', 0, 0, FL_MENU_INACTIVE|FL_MENU_DIVIDER},
+   {&quot;invisible&quot;,FL_ALT+'i', 0, 0, FL_MENU_INVISIBLE},
+   {&quot;check&quot;,    FL_ALT+'i', 0, 0, FL_MENU_TOGGLE|FL_MENU_VALUE},
+   {&quot;box&quot;,      FL_ALT+'i', 0, 0, FL_MENU_TOGGLE},
+   {0}};
+  </PRE></UL>
+  produces:
+  <P ALIGN=CENTER>\image html  menu.gif </P>
+  
+  A submenu title is identified by the bit FL_SUBMENU in the 
+  flags field, and ends with a label() that is NULL.
+  You can nest menus to any depth.  A pointer to the first item in the
+  submenu can be treated as an Fl_Menu array itself.  It is also
+  possible to make seperate submenu arrays with FL_SUBMENU_POINTER
+  flags.
+  <P>You should use the method functions to access structure members and
+  not access them directly to avoid compatibility problems with future
+  releases of FLTK.
+*/
 struct FL_EXPORT Fl_Menu_Item {
   const char *text;	// label()
   int shortcut_;
@@ -64,51 +128,185 @@ struct FL_EXPORT Fl_Menu_Item {
 
   // advance N items, skipping submenus:
   const Fl_Menu_Item *next(int=1) 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.
+  */
   Fl_Menu_Item *next(int i=1) {
     return (Fl_Menu_Item*)(((const Fl_Menu_Item*)this)->next(i));}
+  /** Returns the first menu item, same as next(0). */
   const Fl_Menu_Item *first() const { return next(0); }
+  /** Returns the first menu item, same as next(0). */
   Fl_Menu_Item *first() { return next(0); }
 
   // methods on menu items:
+  /**
+    This is the title of the item.  A NULL here indicates the end
+    of the menu (or of a submenu).  A '&' in the item will print an
+    underscore under the next letter, and if the menu is popped up that
+    letter will be a &quot;shortcut&quot; to pick that item.  To get a
+    real '&' put two
+    in a row.
+  */
   const char* label() const {return text;}
+  /**    See const char* Fl_Menu_Item::label() const   */
   void label(const char* a) {text=a;}
+  /**    See const char* Fl_Menu_Item::label() const   */
   void label(Fl_Labeltype a,const char* b) {labeltype_ = a; text = b;}
+  /**
+    A labeltype identifies a routine that draws the label of the
+    widget.  This can be used for special effects such as emboss, or to use
+    the label() pointer as another form of data such as a bitmap.
+    The value FL_NORMAL_LABEL prints the label as text.
+  */
   Fl_Labeltype labeltype() const {return (Fl_Labeltype)labeltype_;}
+  /**
+    A labeltype identifies a routine that draws the label of the
+    widget.  This can be used for special effects such as emboss, or to use
+    the label() pointer as another form of data such as a bitmap.
+    The value FL_NORMAL_LABEL prints the label as text.
+  */
   void labeltype(Fl_Labeltype a) {labeltype_ = a;}
+  /**
+    This color is passed to the labeltype routine, and is typically the
+    color of the label text.  This defaults to FL_BLACK.  If this
+    color is not black fltk will <I>not</I> use overlay bitplanes to draw
+    the menu - this is so that images put in the menu draw correctly.
+  */
   Fl_Color labelcolor() const {return (Fl_Color)labelcolor_;}
+  /** See Fl_Color Fl_Menu_Item::labelcolor() const */
   void labelcolor(unsigned a) {labelcolor_ = a;}
+  /**
+    Fonts are identified by small 8-bit indexes into a table.  See the 
+    enumeration list for predefined fonts. The default value is a
+    Helvetica font.  The function 
+    Fl::set_font() can define new fonts.
+  */
   Fl_Font labelfont() const {return labelfont_;}
+  /**
+    Fonts are identified by small 8-bit indexes into a table.  See the 
+    enumeration list for predefined fonts. The default value is a
+    Helvetica font.  The function 
+    Fl::set_font() can define new fonts.
+  */
   void labelfont(Fl_Font a) {labelfont_ = a;}
+  /**    Gets or sets the label font pixel size/height.  */
+  /** Gets the label font pixel size/height.*/
   Fl_Fontsize labelsize() const {return labelsize_;}
+  /** Sets the label font pixel size/height.*/
   void labelsize(Fl_Fontsize a) {labelsize_ = a;}
+
+  /**
+     Each item has space for a callback function and an argument for that
+     function.  Due to back compatability, the Fl_Menu_Item itself
+     is not passed to the callback, instead you have to get it by calling 
+     ((Fl_Menu_*)w)-&gt;mvalue() where w is the widget argument.
+  */
   Fl_Callback_p callback() const {return callback_;}
+  /** See Fl_Callback_p Fl_MenuItem::callback() const */
   void callback(Fl_Callback* c, void* p) {callback_=c; user_data_=p;}
+  /** See Fl_Callback_p Fl_MenuItem::callback() const */
   void callback(Fl_Callback* c) {callback_=c;}
+  /** See Fl_Callback_p Fl_MenuItem::callback() const */
   void callback(Fl_Callback0*c) {callback_=(Fl_Callback*)c;}
+  /** See Fl_Callback_p Fl_MenuItem::callback() const */
   void callback(Fl_Callback1*c, long p=0) {callback_=(Fl_Callback*)c; user_data_=(void*)p;}
+  /**
+    Get or set the user_data argument that is sent to the
+    callback function.
+  */
   void* user_data() const {return user_data_;}
+  /**
+    Get or set the user_data argument that is sent to the
+    callback function.
+  */
   void user_data(void* v) {user_data_ = v;}
+  /**
+    For convenience you can also define the callback as taking a long
+    argument.  This is implemented by casting this to a Fl_Callback
+    and casting the long to a void* and may not be
+    portable to some machines.
+  */
   long argument() const {return (long)user_data_;}
+  /**
+    For convenience you can also define the callback as taking a long
+    argument.  This is implemented by casting this to a Fl_Callback
+    and casting the long to a void* and may not be
+    portable to some machines.
+  */
   void argument(long v) {user_data_ = (void*)v;}
+  /** Gets what key combination shortcut will trigger the menu item. */
   int shortcut() const {return shortcut_;}
+  /**
+    Sets exactly what key combination will trigger the menu item.  The
+    value is a logical 'or' of a key and a set of shift flags, for instance 
+    FL_ALT+'a' or FL_ALT+FL_F+10 or just 'a'.  A value of
+    zero disables the shortcut.
+    <P>The key can be any value returned by 
+    Fl::event_key(), but will usually be an ASCII letter.  Use
+    a lower-case letter unless you require the shift key to be held down. </P>
+    <P>The shift flags can be any set of values accepted by 
+    Fl::event_state().  If the bit is on that shift key must
+    be pushed.  Meta, Alt, Ctrl, and Shift must be off if they are not in
+    the shift flags (zero for the other bits indicates a &quot;don't care&quot;
+    setting).
+  */
   void shortcut(int s) {shortcut_ = s;}
+  /**
+    Returns true if either FL_SUBMENU or FL_SUBMENU_POINTER
+    is on in the flags. FL_SUBMENU indicates an embedded submenu
+    that goes from the next item through the next one with a NULL
+    label(). FL_SUBMENU_POINTER indicates that user_data()
+    is a pointer to another menu array.
+  */
   int submenu() const {return flags&(FL_SUBMENU|FL_SUBMENU_POINTER);}
+  /**
+    Returns true if a checkbox will be drawn next to this item.  This is
+    true if FL_MENU_TOGGLE or FL_MENU_RADIO is set in the
+    flags.
+  */
   int checkbox() const {return flags&FL_MENU_TOGGLE;}
+  /**
+    Returns true if this item is a radio item.  When a radio button is
+    selected all &quot;adjacent&quot; radio buttons are turned off.  A set of radio
+    items is delimited by an item that has radio() false, or by an
+    item with FL_MENU_DIVIDER turned on.
+  */
   int radio() const {return flags&FL_MENU_RADIO;}
+  /**    Returns the current value of the check or radio item.  */
   int value() const {return flags&FL_MENU_VALUE;}
+  /**
+    Turns the check or radio item &quot;on&quot; for the menu item. Note that this
+    does not turn off any adjacent radio items like set_only()
+    does.
+  */
   void set() {flags |= FL_MENU_VALUE;}
+  /**    Turns the check or radio item &quot;off&quot; for the menu item.  */
   void clear() {flags &= ~FL_MENU_VALUE;}
   void setonly();
+  /**    Gets the visibility of an item.  */
   int visible() const {return !(flags&FL_MENU_INVISIBLE);}
+  /**    Makes an item visible in the menu.  */
   void show() {flags &= ~FL_MENU_INVISIBLE;}
+  /**    Hides an item in the menu.  */
   void hide() {flags |= FL_MENU_INVISIBLE;}
+  /**    Get whether or not the item can be picked.  */
   int active() const {return !(flags&FL_MENU_INACTIVE);}
+  /**    Allows a menu item to be picked.  */
   void activate() {flags &= ~FL_MENU_INACTIVE;}
+  /**
+    Prevents a menu item from being picked. Note that this will also cause
+    the menu item to appear grayed-out.
+  */
   void deactivate() {flags |= FL_MENU_INACTIVE;}
-  int activevisible() const {return !(flags&0x11);}
+  /** Returns non 0 if FL_INACTIVE and FL_INVISIBLE are cleared, 0 otherwise. */
+  int activevisible() const {return !(flags & (FL_MENU_INACTIVE|FL_MENU_INVISIBLE));}
 
   // compatibility for FLUID so it can set the image of a menu item...
+  /** compatibility api for FLUID, same as a->label(this) */
   void image(Fl_Image* a) {a->label(this);}
+  /** compatibility api for FLUID, same as a.label(this) */
   void image(Fl_Image& a) {a.label(this);}
 
   // used by menubar:
@@ -130,15 +328,37 @@ struct FL_EXPORT Fl_Menu_Item {
   const Fl_Menu_Item* test_shortcut() const;
   const Fl_Menu_Item* find_shortcut(int *ip=0) const;
 
+  /**
+    Call the Fl_Menu_Item item's callback, and provide the 
+    Fl_Widget argument (and optionally override the user_data()
+    argument).  You must first check that callback() is non-zero
+    before calling this.
+  */
   void do_callback(Fl_Widget* o) const {callback_(o, user_data_);}
+  /**
+    Call the Fl_Menu_Item item's callback, and provide the 
+    Fl_Widget argument (and optionally override the user_data()
+    argument).  You must first check that callback() is non-zero
+    before calling this.
+  */
   void do_callback(Fl_Widget* o,void* arg) const {callback_(o, arg);}
+  /**
+    Call the Fl_Menu_Item item's callback, and provide the 
+    Fl_Widget argument (and optionally override the user_data()
+    argument).  You must first check that callback() is non-zero
+    before calling this.
+  */
   void do_callback(Fl_Widget* o,long arg) const {callback_(o, (void*)arg);}
 
   // back-compatability, do not use:
+  /** back compatibility only \deprecated. */
   int checked() const {return flags&FL_MENU_VALUE;}
+  /** back compatibility only \deprecated. */
   void check() {flags |= FL_MENU_VALUE;}
+  /** back compatibility only \deprecated. */
   void uncheck() {flags &= ~FL_MENU_VALUE;}
   int add(const char*, int shortcut, Fl_Callback*, void* =0, int = 0);
+  /** See int add(const char*, int shortcut, Fl_Callback*, void*, int) */
   int add(const char*a, const char* b, Fl_Callback* c,
 	  void* d = 0, int e = 0) {
     return add(a,fl_old_shortcut(b),c,d,e);}
diff --git a/FL/Fl_Menu_Window.H b/FL/Fl_Menu_Window.H
index b2fea05d0..7337ac1d2 100644
--- a/FL/Fl_Menu_Window.H
+++ b/FL/Fl_Menu_Window.H
@@ -30,6 +30,12 @@
 
 #include "Fl_Single_Window.H"
 
+/**
+  The Fl_Menu_Window widget is a window type used for menus. By
+  default the window is drawn in the hardware overlay planes if they are
+  available so that the menu don't force the rest of the window to
+  redraw.
+*/
 class FL_EXPORT Fl_Menu_Window : public Fl_Single_Window {
   enum {NO_OVERLAY = 128};
 public:
@@ -37,12 +43,18 @@ public:
   void erase();
   void flush();
   void hide();
+  /** Tells if hardware overlay mode is set */
   int overlay() {return !(flags()&NO_OVERLAY);}
+  /** Tells FLTK to use hardware overlay planes if they are available.  */
   void set_overlay() {clear_flag(NO_OVERLAY);}
+  /** Tells FLTK to use normal drawing planes instead of overlay planes.
+      This is usually necessary if your menu contains multi-color pixmaps. */
   void clear_overlay() {set_flag(NO_OVERLAY);}
   ~Fl_Menu_Window();
+  /** Creates a new Fl_Menu_Window widget using the given size, and label string. */
   Fl_Menu_Window(int W, int H, const char *l = 0)
     : Fl_Single_Window(W,H,l) { image(0); }
+  /** Creates a new Fl_Menu_Window widget using the given position, size, and label string. */
   Fl_Menu_Window(int X, int Y, int W, int H, const char *l = 0)
     : Fl_Single_Window(X,Y,W,H,l) { image(0); }
 };
diff --git a/FL/Fl_Progress.H b/FL/Fl_Progress.H
index 6f5819a2b..12ccf09c6 100644
--- a/FL/Fl_Progress.H
+++ b/FL/Fl_Progress.H
@@ -38,7 +38,9 @@
 //
 // Progress class...
 //
-
+/**
+    Displays a progress bar for the user.
+*/
 class FL_EXPORT Fl_Progress : public Fl_Widget
 {
   float	value_,
@@ -53,13 +55,19 @@ class FL_EXPORT Fl_Progress : public Fl_Widget
 
   Fl_Progress(int x, int y, int w, int h, const char *l = 0);
 
+  /** Sets the maximum value in the progress widget.  */
   void	maximum(float v) { maximum_ = v; redraw(); }
+  /** Gets the maximum value in the progress widget.  */
   float	maximum() const { return (maximum_); }
 
+  /** Sets the minimum value in the progress widget.  */
   void	minimum(float v) { minimum_ = v; redraw(); }
+  /** Gets the minimum value in the progress widget.  */
   float	minimum() const { return (minimum_); }
 
+  /** Sets the current value in the progress widget.  */
   void	value(float v) { value_ = v; redraw(); }
+  /** Gets the current value in the progress widget.  */
   float	value() const { return (value_); }
 };
 
diff --git a/FL/Fl_Timer.H b/FL/Fl_Timer.H
index 6c9e28067..4f3dada40 100644
--- a/FL/Fl_Timer.H
+++ b/FL/Fl_Timer.H
@@ -37,6 +37,13 @@
 #define FL_VALUE_TIMER		1
 #define FL_HIDDEN_TIMER		2
 
+/**
+  This is provided only to emulate the Forms Timer widget.  It works by
+  making a timeout callback every 1/5 second.  This is wasteful and
+  inaccurate if you just want something to happen a fixed time in the
+  future.  You should directly call 
+  Fl::add_timeout() instead.
+*/
 class FL_EXPORT Fl_Timer : public Fl_Widget {
   static void stepcb(void *);
   void step();
@@ -50,9 +57,21 @@ public:
   Fl_Timer(uchar t,int x,int y,int w,int h, const char *l);
   ~Fl_Timer();
   void value(double);
+  /** See void Fl_Timer::value(double)  */
   double value() const {return delay>0.0?delay:0.0;}
+  /**
+    Gets or sets the direction of the timer.  If the direction is zero
+    then the timer will count up, otherwise it will count down from the
+    initial value().
+  */
   char direction() const {return direction_;}
+  /**
+    Gets or sets the direction of the timer.  If the direction is zero
+    then the timer will count up, otherwise it will count down from the
+    initial value().
+  */
   void direction(char d) {direction_ = d;}
+  /**    Gets or sets whether the timer is suspended.  */
   char suspended() const {return !on;}
   void suspended(char d);
 };