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

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,
+  /** See int Fl_Menu_::add(const char* label, int shortcut, Fl_Callback*, void *user_data=0, int flags=0)*/
-	  void* d = 0, int e = 0) {return add(a,fl_old_shortcut(b),c,d,e);}
+  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);}
 };
 

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) {}
 };

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();

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);}

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); }
 };

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_); }
 };
 

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);
 };

documentation/todo_filelist_doc.txt

@@ -15,7 +15,7 @@ In Progress Work List (add your WP and name here):
   - WP4  (Fabien) DONE
   - WP5  (Fabien) DONE
   - WP6  (Fabien) DONE
-  - WP7  (Fabien)
+  - WP7  (Fabien) DONE
   - WP8  (Fabien)
   - WP9
   - WP10
@@ -194,19 +194,6 @@ Fl_Input_.cxx
 Fl_Input_Choice.H
 Fl_Int_Input.H
 Fl_Line_Dial.H
-Fl_Menu.H
-Fl_Menu.cxx
-Fl_Menu_.H
-Fl_Menu_.cxx
-Fl_Menu_Bar.H
-Fl_Menu_Bar.cxx
-Fl_Menu_Button.H
-Fl_Menu_Button.cxx
-Fl_Menu_Item.H
-Fl_Menu_Window.H
-Fl_Menu_Window.cxx
-Fl_Menu_add.cxx
-Fl_Menu_global.cxx
 Fl_Multi_Browser.H
 Fl_Multi_Label.H
 Fl_Multi_Label.cxx
@@ -215,8 +202,6 @@ Fl_Multiline_Output.H
 Fl_Nice_Slider.H
 Fl_Object.H
 Fl_Output.H
-Fl_Progress.H
-Fl_Progress.cxx
 Fl_Radio_Button.H
 Fl_Radio_Light_Button.H
 Fl_Radio_Round_Button.H
@@ -251,7 +236,6 @@ Fl_Text_Editor.H
 Fl_Text_Editor.cxx
 Fl_Tiled_Image.H
 Fl_Tiled_Image.cxx
-Fl_Timer.H
 Fl_Toggle_Button.H
 Fl_Toggle_Light_Button.H
 Fl_Toggle_Round_Button.H
@@ -354,7 +338,6 @@ forms_bitmap.cxx
 forms_compatability.cxx
 forms_fselect.cxx
 forms_pixmap.cxx
-forms_timer.cxx
 freeglut_geometry.cxx
 freeglut_stroke_mono_roman.cxx
 freeglut_stroke_roman.cxx

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;

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
+#define SAFE_STRCAT(s) { len += strlen(s); if ( len >= namelen ) { *name='\0'; return(-2); } else strcat(name,(s)); }
-//    If finditem==NULL, mvalue() is used (the most recently picked menuitem)
+
-//    Returns:
+/** Set 'pathname' of specified menuitem
-//       0 : OK
+    If finditem==NULL, mvalue() is used (the most recently picked menuitem)
-//      -1 : item not found (name="")
+    Returns:
-//      -2 : 'name' not large enough (name="")
+    -   0 : OK
-//
+    -  -1 : item not found (name="")
-#define SAFE_STRCAT(s) \
+    -  -2 : 'name' not large enough (name="")
-    { len += strlen(s); if ( len >= namelen ) { *name='\0'; return(-2); } else strcat(name,(s)); }
+*/
 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"
+  Find menu item index, given menu pathname
-//     Will also return submenus, eg. "Edit"
+     eg. "Edit/Copy"
-//     Returns NULL if not found.
+     Will also return submenus, eg. "Edit"
-//
+     Returns NULL if not found.
-const Fl_Menu_Item *
+*/
-Fl_Menu_::find_item(const char *name)
+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
+ When user picks a menu item, call this.  It will do the callback.
-// was necessary so non-checkbox menus can really be declared const...
+ 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--;)

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);

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();
 }

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
+/** Adds an item.  The text is split at '/' characters to automatically
-// produce submenus (actually a totally unnecessary feature as you can
+   produce submenus (actually a totally unnecessary feature as you can
-// now add submenu titles directly by setting SUBMENU in the flags):
+   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
+  This is a Forms (and SGI GL library) compatible add function, it
-// seperating the menu item names from an optional shortcut string.
+  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;

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;

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);

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;