Doxygen documentation WP9 Done.

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

FL/Fl_File_Input.H

@@ -51,7 +51,9 @@ public:
   virtual int handle(int);
   virtual void draw();
 
+  /**    Gets or sets the box type to use for the navigation bar.  */
   Fl_Boxtype	down_box() const { return (Fl_Boxtype)down_box_; }
+  /**    Gets or sets the box type to use for the navigation bar.  */
   void		down_box(Fl_Boxtype b) { down_box_ = b; }
   Fl_Color	errorcolor() const { return errorcolor_; }
   void		errorcolor(Fl_Color c) { errorcolor_ = c; }

FL/Fl_Float_Input.H

@@ -25,15 +25,26 @@
 //     http://www.fltk.org/str.php
 //
 
+
 #ifndef Fl_Float_Input_H
 #define Fl_Float_Input_H
 
 #include "Fl_Input.H"
 
+/**
+  The Fl_Float_Input class is a subclass of Fl_Input
+  that only allows the user to type floating point numbers (sign,
+  digits, decimal point, more digits, 'E' or 'e', sign, digits).
+*/
 class Fl_Float_Input : public Fl_Input {
 public:
-    Fl_Float_Input(int X,int Y,int W,int H,const char *l = 0)
+  /**
-	: Fl_Input(X,Y,W,H,l) {type(FL_FLOAT_INPUT);}
+      Creates a new Fl_Float_Input widget using the given position,
+    size, and label string. The default boxtype is FL_DOWN_BOX.
+  <P> Inherited destructor destroys the widget and any value associated with it
+  */
+  Fl_Float_Input(int X,int Y,int W,int H,const char *l = 0)
+    : Fl_Input(X,Y,W,H,l) {type(FL_FLOAT_INPUT);}
 };
 
 #endif

FL/Fl_Input.H

@@ -30,6 +30,215 @@
 
 #include "Fl_Input_.H"
 
+/**
+  This is the FLTK text input widget. It displays a single line
+  of text and lets the user edit it. Normally it is drawn with an
+  inset box and a white background. The text may contain any
+  characters (even 0), and will correctly display anything, using
+  ^X notation for unprintable control characters and \nnn notation
+  for unprintable characters with the high bit set. It assumes the
+  font can draw any characters in the ISO-8859-1 character set.</P>
+  
+  <CENTER><TABLE border=1 WIDTH=90% summary="Fl_Input keyboard and mouse bindings.">
+  
+  <TR><TD WIDTH=200><B>Mouse button 1</B></TD><TD>Moves the cursor to
+  this point. Drag selects characters.  Double click selects words.
+  Triple click selects all text.  Shift+click extends the selection.
+  When you select text it is automatically copied to the clipboard.
+  </TD></TR>
+  
+  <TR><TD><B>Mouse button 2</B></TD><TD>Insert the clipboard at
+  the point clicked.  You can also select a region and replace it with the
+  clipboard by selecting the region with mouse button 2.
+  </TD></TR>
+  
+  <TR><TD><B>Mouse button 3</B></TD><TD>Currently acts like button 1.</TD></TR>
+  
+  <TR><TD><B>Backspace</B></TD><TD>Deletes one character to the left, or
+  deletes the selected region.</TD></TR>
+  <TR><TD><B>Enter</B></TD><TD>May cause the callback, see when().</TD></TR>
+  <TR><TD><B>^A or Home</B></TD><TD>Go to start of line.</TD></TR>
+  <TR><TD><B>^B or Left</B></TD><TD>Move left</TD></TR>
+  <TR><TD><B>^C</B></TD><TD>Copy the selection to the clipboard</TD></TR>
+  <TR><TD><B>^D or Delete</B></TD><TD>Deletes one character to the right
+  or deletes the selected region.</TD></TR>
+  <TR><TD><B>^E or End</B></TD><TD>Go to the end of line.</TD></TR>
+  <TR><TD><B>^F or Right</B></TD><TD>Move right</TD></TR>
+  <TR><TD><B>^K</B></TD><TD>Delete to the end of line (next \n character)
+  or deletes a single \n character.  These deletions are all concatenated
+  into the clipboard.</TD></TR>
+  <TR><TD><B>^N or Down</B></TD><TD>Move down (for Fl_Multiline_Input
+  only, otherwise it moves to the next input field).</TD></TR>
+  <TR><TD><B>^P or Up</B></TD><TD>Move up (for Fl_Multiline_Input only,
+  otherwise it moves to the previous input field).</TD></TR>
+  <TR><TD><B>^U</B></TD><TD>Delete everything.</TD></TR>
+  <TR><TD><B>^V or ^Y</B></TD><TD>Paste the clipboard</TD></TR>
+  <TR><TD><B>^X or ^W</B></TD><TD>Copy the region to the clipboard and
+  delete it.</TD></TR>
+  <TR><TD><B>^Z or ^_</B></TD><TD>Undo.  This is a single-level undo
+  mechanism, but all adjacent deletions and insertions are concatenated
+  into a single &quot;undo&quot;.  Often this will undo a lot more than you
+  expected.</TD></TR>
+  <TR><TD><B>Shift+move</B></TD><TD>Move the cursor but also extend the
+  selection.</TD></TR>
+  
+  <TR><TD><B>RightCtrl or
+  <BR>Compose</B></TD><TD>Start
+  a compose-character
+  sequence.  The next one or two keys typed define the character to
+  insert (see table that follows.)
+  
+  <p>For instance, to type "á" type [compose][a]['] or [compose]['][a].
+  
+  <P>The character "nbsp" (non-breaking space) is typed by using
+  [compose][space].
+  
+  <P>The single-character sequences may be followed by a space if
+  necessary to remove ambiguity.  For instance, if you really want to
+  type "ª~" rather than "ã" you must type [compose][a][space][~].
+  
+  <p>The same key may be used to "quote" control characters into the
+  text.  If you need a ^Q character you can get one by typing
+  [compose][Control+Q].
+  
+  <p>X may have a key on the keyboard
+  defined as XK_Multi_key.  If so this key may be used as well
+  as the right-hand control key.  You can set this up with the program
+  xmodmap.
+  
+  <p>If your keyboard is set to support a foreign language you should
+  also be able to type "dead key" prefix characters.  On X you will
+  actually be able to see what dead key you typed, and if you then move
+  the cursor without completing the sequence the accent will remain
+  inserted.</TD></TR>
+  </TABLE></CENTER>
+  
+  <!-- NEW PAGE -->
+  <center><table border=1 summary="Character Composition Table">
+  <caption align="top">Character Composition Table</caption>
+  <tr>
+  	<th>Keys</th><th>Char</th>
+  	<th>Keys</th><th>Char</th>
+  	<th>Keys</th><th>Char</th>
+  	<th>Keys</th><th>Char</th>
+  	<th>Keys</th><th>Char</th>
+  	<th>Keys</th><th>Char</th>
+  
+  </tr><tr>
+  	<td align=center>sp</td><td align=center><small>nbsp</small></td>
+  	<td align=center>*</td><td align=center>°</td>
+  	<td align=center>` A</td><td align=center>À</td>
+  	<td align=center>D -</td><td align=center>Ð</td>
+  	<td align=center>` a</td><td align=center>à</td>
+  	<td align=center>d -</td><td align=center>ð</td>
+  </tr><tr>
+  	<td align=center>!</td><td align=center>¡</td>
+  	<td align=center>+ -</td><td align=center>±</td>
+  	<td align=center>' A</td><td align=center>Á</td>
+  	<td align=center>~ N</td><td align=center>Ñ</td>
+  	<td align=center>' a</td><td align=center>á</td>
+  	<td align=center>~ n</td><td align=center>ñ</td>
+  </tr><tr>
+  	<td align=center>%</td><td align=center>¢</td>
+  	<td align=center>2</td><td align=center>²</td>
+  	<td align=center>A ^</td><td align=center>Â</td>
+  	<td align=center>` O</td><td align=center>Ò</td>
+  	<td align=center>^ a</td><td align=center>â</td>
+  	<td align=center>` o</td><td align=center>ò</td>
+  </tr><tr>
+  	<td align=center>#</td><td align=center>£</td>
+  	<td align=center>3</td><td align=center>³</td>
+  	<td align=center>~ A</td><td align=center>Ã</td>
+  	<td align=center>' O</td><td align=center>Ó</td>
+  	<td align=center>~ a</td><td align=center>ã</td>
+  	<td align=center>' o</td><td align=center>ó</td>
+  </tr><tr>
+  	<td align=center>$</td><td align=center>¤</td>
+  	<td align=center>'</td><td align=center>´</td>
+  	<td align=center>: A</td><td align=center>Ä</td>
+  	<td align=center>^ O</td><td align=center>Ô</td>
+  	<td align=center>: a</td><td align=center>ä</td>
+  	<td align=center>^ o</td><td align=center>ô</td>
+  </tr><tr>
+  	<td align=center>y =</td><td align=center>¥</td>
+  	<td align=center>u</td><td align=center>µ</td>
+  	<td align=center>* A</td><td align=center>Å</td>
+  	<td align=center>~ O</td><td align=center>Õ</td>
+  	<td align=center>* a</td><td align=center>å</td>
+  	<td align=center>~ o</td><td align=center>õ</td>
+  </tr><tr>
+  	<td align=center>|</td><td align=center>¦</td>
+  	<td align=center>p</td><td align=center>¶</td>
+  	<td align=center>A E</td><td align=center>Æ</td>
+  	<td align=center>: O</td><td align=center>Ö</td>
+  	<td align=center>a e</td><td align=center>æ</td>
+  	<td align=center>: o</td><td align=center>ö</td>
+  </tr><tr>
+  	<td align=center>&</td><td align=center>§</td>
+  	<td align=center>.</td><td align=center>·</td>
+  	<td align=center>, C</td><td align=center>Ç</td>
+  	<td align=center>x</td><td align=center>×</td>
+  	<td align=center>, c</td><td align=center>ç</td>
+  	<td align=center>- :</td><td align=center>÷</td>
+  </tr><tr>
+  	<td align=center>:</td><td align=center>¨</td>
+  	<td align=center>,</td><td align=center>¸</td>
+  	<td align=center>E `</td><td align=center>È</td>
+  	<td align=center>O /</td><td align=center>Ø</td>
+  	<td align=center>` e</td><td align=center>è</td>
+  	<td align=center>o /</td><td align=center>ø</td>
+  </tr><tr>
+  	<td align=center>c</td><td align=center>©</td>
+  	<td align=center>1</td><td align=center>¹</td>
+  	<td align=center>' E</td><td align=center>É</td>
+  	<td align=center>` U</td><td align=center>Ù</td>
+  	<td align=center>' e</td><td align=center>é</td>
+  	<td align=center>` u</td><td align=center>ù</td>
+  </tr><tr>
+  	<td align=center>a</td><td align=center>ª</td>
+  	<td align=center>o</td><td align=center>º</td>
+  	<td align=center>^ E</td><td align=center>Ê</td>
+  	<td align=center>' U</td><td align=center>Ú</td>
+  	<td align=center>^ e</td><td align=center>ê</td>
+  	<td align=center>' u</td><td align=center>ú</td>
+  </tr><tr>
+  	<td align=center>&lt; &lt;</td><td align=center>«</td>
+  	<td align=center>&gt; &gt;</td><td align=center>»</td>
+  	<td align=center>: E</td><td align=center>Ë</td>
+  	<td align=center>^ U</td><td align=center>Û</td>
+  	<td align=center>: e</td><td align=center>ë</td>
+  	<td align=center>^ u</td><td align=center>û</td>
+  </tr><tr>
+  	<td align=center>~</td><td align=center>¬</td>
+  	<td align=center>1 4</td><td align=center>¼</td>
+  	<td align=center>` I</td><td align=center>Ì</td>
+  	<td align=center>: U</td><td align=center>Ü</td>
+  	<td align=center>` i</td><td align=center>ì</td>
+  	<td align=center>: u</td><td align=center>ü</td>
+  </tr><tr>
+  	<td align=center>-</td><td align=center>­</td>
+  	<td align=center>1 2</td><td align=center>½</td>
+  	<td align=center>' I</td><td align=center>Í</td>
+  	<td align=center>' Y</td><td align=center>Ý</td>
+  	<td align=center>' i</td><td align=center>í</td>
+  	<td align=center>' y</td><td align=center>ý</td>
+  </tr><tr>
+  	<td align=center>r</td><td align=center>®</td>
+  	<td align=center>3 4</td><td align=center>¾</td>
+  	<td align=center>^ I</td><td align=center>Î</td>
+  	<td align=center>T H</td><td align=center>Þ</td>
+  	<td align=center>^ i</td><td align=center>î</td>
+  	<td align=center>t h</td><td align=center>þ</td>
+  </tr><tr>
+  	<td align=center>_</td><td align=center>¯</td>
+  	<td align=center>?</td><td align=center>¿</td>
+  	<td align=center>: I</td><td align=center>Ï</td>
+  	<td align=center>s s</td><td align=center>ß</td>
+  	<td align=center>: i</td><td align=center>ï</td>
+  	<td align=center>: y</td><td align=center>ÿ</td>
+  </tr>
+  </table></center>
+*/
 class FL_EXPORT Fl_Input : public Fl_Input_ {
   int handle_key();
   int shift_position(int p);

FL/Fl_Input_.H

@@ -46,6 +46,31 @@
 #define FL_MULTILINE_INPUT_WRAP	(FL_MULTILINE_INPUT | FL_INPUT_WRAP)
 #define FL_MULTILINE_OUTPUT_WRAP (FL_MULTILINE_INPUT | FL_INPUT_READONLY | FL_INPUT_WRAP)
 
+/**
+  This is a virtual base class below Fl_Input. It has all
+  the same interfaces, but lacks the handle() and
+  draw() method. You may want to subclass it if you are
+  one of those people who likes to change how the editing keys
+  work.
+  
+  <P>This can act like any of the subclasses of Fl_Input, by
+  setting type() to one of the following values:</P>
+  
+  \code
+  #define FL_NORMAL_INPUT	   0
+  #define FL_FLOAT_INPUT	   1
+  #define FL_INT_INPUT		   2
+  #define FL_MULTILINE_INPUT	   4
+  #define FL_SECRET_INPUT	   5
+  #define FL_INPUT_TYPE		   7
+  #define FL_INPUT_READONLY	   8
+  #define FL_NORMAL_OUTPUT	   (FL_NORMAL_INPUT | FL_INPUT_READONLY)
+  #define FL_MULTILINE_OUTPUT	   (FL_MULTILINE_INPUT | FL_INPUT_READONLY)
+  #define FL_INPUT_WRAP		   16
+  #define FL_MULTILINE_INPUT_WRAP  (FL_MULTILINE_INPUT | FL_INPUT_WRAP)
+  #define FL_MULTILINE_OUTPUT_WRAP (FL_MULTILINE_INPUT | FL_INPUT_READONLY | FL_INPUT_WRAP)
+  \endcode
+*/
 class FL_EXPORT Fl_Input_ : public Fl_Widget {
 
   const char* value_;
@@ -99,45 +124,142 @@ public:
   int value(const char*, int);
   int static_value(const char*);
   int static_value(const char*, int);
+  /**
+      The first form returns the current value, which is a pointer
+      to the internal buffer and is valid only until the next event is
+      handled.
+      
+      <P>The second two forms change the text and set the mark and the
+      point to the end of it. The string is copied to the internal
+      buffer. Passing NULL is the same as &quot;&quot;. 
+      This returns non-zero if the new value is different than the
+      current one.  You can use the second version to directly set the
+      length if you know it already or want to put nul's in the
+      text.
+  */
   const char* value() const {return value_;}
-  char index(int i) const {return value_[i];}
+  /**
+      Same as value()[n], but may be faster in plausible
+      implementations. No bounds checking is done. 
+  */
+char index(int i) const {return value_[i];}
+  /**
+      Returns the number of characters in value(). This
+      may be greater than strlen(value()) if there are nul
+      characters in it.
+  */
   int size() const {return size_;}
   void size(int W, int H) { Fl_Widget::size(W, H); }
+  /** Gets the maximum length of the input field.  */
   int maximum_size() const {return maximum_size_;}
+  /** Sets the maximum length of the input field.  */
   void maximum_size(int m) {maximum_size_ = m;}
-
+  /**
+    The input widget maintains two pointers into the string. The
+    &quot;position&quot; is where the cursor is. The
+    &quot;mark&quot; is the other end of the selected text. If they
+    are equal then there is no selection. Changing this does not
+    affect the clipboard (use copy() to do that).
+    
+    <P>Changing these values causes a redraw(). The new
+    values are bounds checked. The return value is non-zero if the
+    new position is different than the old one. position(n)
+    is the same as position(n,n). mark(n) is the
+    same as position(position(),n).
+  */
   int position() const {return position_;}
+  /** Gets the current selection mark. mark(n) is  the same as position(position(),n).*/
   int mark() const {return mark_;}
   int position(int p, int m);
+   /**  See int Fl_Input_::position() const */
   int position(int p) {return position(p, p);}
+  /** Sets the current selection mark. mark(n) is  the same as position(position(),n).*/
   int mark(int m) {return position(position(), m);}
   int replace(int, int, const char*, int=0);
+  /**
+    Deletes the current selection.
+    cut(n) deletes n characters after the
+    position(). cut(-n) deletes n
+    characters before the position(). cut(a,b)
+    deletes the characters between offsets a and
+    b. A, b, and n are all
+    clamped to the size of the string. The mark and point are left
+    where the deleted text was.
+    
+    <P>If you want the data to go into the clipboard, do
+    Fl_Input_::copy() before calling
+    Fl_Input_::cut(), or do Fl_Input_::copy_cuts()
+    afterwards.
+  */
   int cut() {return replace(position(), mark(), 0);}
+  /**    See int Fl_Input_::cut()   */
   int cut(int n) {return replace(position(), position()+n, 0);}
+  /**    See int Fl_Input_::cut()   */
   int cut(int a, int b) {return replace(a, b, 0);}
+  /**
+    Insert the string t at the current position, and
+    leave the mark and position after it. If l is not zero
+    then it is assumed to be strlen(t).
+  */
   int insert(const char* t, int l=0){return replace(position_, mark_, t, l);}
   int copy(int clipboard);
   int undo();
   int copy_cuts();
 
+  /**
+    The first form returns the current shortcut key for the Input.
+    <P>The second form sets the shortcut key to key. Setting this
+    overrides the use of '&' in the label().  The value is a bitwise
+    OR of a key and a set of shift flags, for example FL_ALT | 'a'
+    , FL_ALT | (FL_F + 10), or just 'a'.  A value
+    of 0 disables the shortcut. </P>
+    <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).
+  */
   int shortcut() const {return shortcut_;}
+  /** See int shortcut() const */
   void shortcut(int s) {shortcut_ = s;}
 
+  /** Gets the font of the text in the input field.*/
   Fl_Font textfont() const {return textfont_;}
+  /** Sets the font of the text in the input field.*/
   void textfont(Fl_Font s) {textfont_ = s;}
+  /** Gets the size of the text in the input field.*/
   Fl_Fontsize textsize() const {return textsize_;}
+  /** Sets the size of the text in the input field.*/
   void textsize(Fl_Fontsize s) {textsize_ = s;}
+  /** Gets the color of the text in the input field.*/
   Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
+  /** Sets the color of the text in the input field.*/
   void textcolor(unsigned n) {textcolor_ = n;}
+  /** Gets the color of the cursor.  This is black by default.*/
   Fl_Color cursor_color() const {return (Fl_Color)cursor_color_;}
+  /** Sets the color of the cursor.  This is black by default.*/
   void cursor_color(unsigned n) {cursor_color_ = n;}
-
+  /** Gets the input field type. */
   int input_type() const {return type() & FL_INPUT_TYPE; }
+  /** Sets the input field type. */
   void input_type(int t) { type((uchar)(t | readonly())); }
+  /** Gets the read-only state of the input field.  */
   int readonly() const { return type() & FL_INPUT_READONLY; }
+  /** Sets the read-only state of the input field.  */
   void readonly(int b) { if (b) type((uchar)(type() | FL_INPUT_READONLY));
                          else type((uchar)(type() & ~FL_INPUT_READONLY)); }
+  /**
+    Gets  the word wrapping state of the input field. Word
+    wrap is only functional with multi-line input fields.
+  */
   int wrap() const { return type() & FL_INPUT_WRAP; }
+  /**
+    Sets the word wrapping state of the input field. Word
+    wrap is only functional with multi-line input fields.
+  */
   void wrap(int b) { if (b) type((uchar)(type() | FL_INPUT_WRAP));
                          else type((uchar)(type() & ~FL_INPUT_WRAP)); }
 };

FL/Fl_Input_Choice.H

@@ -30,6 +30,8 @@
 //     http://www.fltk.org/str.php
 //
 
+
+
 #ifndef Fl_Input_Choice_H
 #define Fl_Input_Choice_H
 
@@ -40,6 +42,17 @@
 #include <FL/fl_draw.H>
 #include <string.h>
 
+/**
+  A combination of the input widget and a menu button.
+  The user can either type into the input area, or use the
+  menu button chooser on the right, which loads the input area
+  with predefined text.  Normally it is drawn with an inset box 
+  and a white background. 
+  <P>
+  The application can directly access both the input and menu
+  widgets directly, using the menubutton()
+  and input() accessor methods.
+*/
 class Fl_Input_Choice : public Fl_Group {
   // Private class to handle slightly 'special' behavior of menu button
   class InputMenuButton : public Fl_Menu_Button {
@@ -112,6 +125,11 @@ class Fl_Input_Choice : public Fl_Group {
   inline int menu_h() { return(h() - Fl::box_dh(box())); }
 
 public:
+  /**
+    Creates a new Fl_Input_Choice widget using the given position, size,
+    and label string.
+  <P> Inherited destructor Destroys the widget and any value associated with it.
+  */
   Fl_Input_Choice (int x,int y,int w,int h,const char*l=0) : Fl_Group(x,y,w,h,l) {
     Fl_Group::box(FL_DOWN_BOX);
     align(FL_ALIGN_LEFT);				// default like Fl_Input
@@ -126,12 +144,10 @@ public:
     menu_->box(FL_FLAT_BOX);				// cosmetic
     end();
   }
-  void add(const char *s) {
+  
-    menu_->add(s);
+  /** Adds an item to the menu.*/
-  }
+  void add(const char *s) { menu_->add(s);  }
-  int changed() const { 
+  int changed() const { return inp_->changed() | Fl_Widget::changed();}
-    return inp_->changed() | Fl_Widget::changed();
-  }
   void clear_changed() { 
     inp_->clear_changed();
     Fl_Widget::clear_changed();
@@ -140,55 +156,53 @@ public:
     inp_->set_changed();
     // no need to call Fl_Widget::set_changed()
   }
-  void clear() {
+  /** Removes all items from the menu. */
-    menu_->clear();
+  void clear() { menu_->clear(); }
-  }
+  /** Gets the box type of the menu button */
-  Fl_Boxtype down_box() const {
+  Fl_Boxtype down_box() const { return (menu_->down_box()); }
-    return (menu_->down_box());
+  /** Sets the box type of the menu button */
-  }
+  void down_box(Fl_Boxtype b) { menu_->down_box(b); }
-  void down_box(Fl_Boxtype b) {
+  /** Gets the Fl_Menu_Item array used for the menu. */
-    menu_->down_box(b);
+  const Fl_Menu_Item *menu() { return (menu_->menu()); }
-  }
+  /** Sets the Fl_Menu_Item array used for the menu. */
-  const Fl_Menu_Item *menu() {
+  void menu(const Fl_Menu_Item *m) { menu_->menu(m); }
-    return (menu_->menu());
-  }
-  void menu(const Fl_Menu_Item *m) {
-    menu_->menu(m);
-  }
   void resize(int X, int Y, int W, int H) {
     Fl_Group::resize(X,Y,W,H);
     inp_->resize(inp_x(), inp_y(), inp_w(), inp_h());
     menu_->resize(menu_x(), menu_y(), menu_w(), menu_h());
   }
-  Fl_Color textcolor() const {
+  /** Gets the encapsulated input text color attributes */
-    return (inp_->textcolor());
+  Fl_Color textcolor() const { return (inp_->textcolor());}
-  }
+  /** Sets the encapsulated input text color attributes */
-  void textcolor(Fl_Color c) {
+  void textcolor(Fl_Color c) { inp_->textcolor(c);}
-    inp_->textcolor(c);
+  /** Gets the encapsulated input text font  attributes */
-  }
+  Fl_Font textfont() const { return (inp_->textfont());}
-  Fl_Font textfont() const {
+  /** Sets the encapsulated input text font attributes */
-    return (inp_->textfont());
+  void textfont(Fl_Font f) { inp_->textfont(f);}
-  }
+  /** Gets the encapsulated input size attributes */
-  void textfont(Fl_Font f) {
+  Fl_Fontsize textsize() const { return (inp_->textsize()); }
-    inp_->textfont(f);
+  /** Sets the encapsulated input size attributes */
-  }
+  void textsize(Fl_Fontsize s) { inp_->textsize(s); }
-  Fl_Fontsize textsize() const {
+  /** See void Fl_Input_Choice::value(const char *s)  */
-    return (inp_->textsize());
+  const char* value() const { return (inp_->value()); }
-  }
+  /**
-  void textsize(Fl_Fontsize s) {
+    Sets or returns the input widget's current contents. The
-    inp_->textsize(s);
+    second form sets the contents using the index into the menu
-  }
+    which you can set as an integer.  Setting the value effectively
-  const char* value() const {
+    'chooses' this menu item, and sets it as the new input text,
-    return (inp_->value());
+    deleting the previous text.
-  }
+  */
-  void value(const char *val) {
+  void value(const char *val) { inp_->value(val); }
-    inp_->value(val);
+  /**    See void Fl_Input_Choice::value(const char *s)  */
-  }
   void value(int val) {
     menu_->value(val);
     inp_->value(menu_->text(val));
   }
+  /**    Returns a reference to the internal Fl_Menu_Button widget.  */
   Fl_Menu_Button *menubutton() { return menu_; }
+  /**
+    Returns a reference to the internal Fl_Input widget.</p>
+  */
   Fl_Input *input() { return inp_; }
 };
 

FL/Fl_Int_Input.H

@@ -30,10 +30,19 @@
 
 #include "Fl_Input.H"
 
+/**
+  The Fl_Int_Input class is a subclass of Fl_Input
+  that only allows the user to type decimal digits (or hex numbers of the form 0xaef).
+*/
 class Fl_Int_Input : public Fl_Input {
 public:
-    Fl_Int_Input(int X,int Y,int W,int H,const char *l = 0)
+  /**
-	: Fl_Input(X,Y,W,H,l) {type(FL_INT_INPUT);}
+    Creates a new Fl_Int_Input widget using the given position,
+    size, and label string. The default boxtype is FL_DOWN_BOX.
+    <P>Inherited destructor Destroys the widget and any value associated with it.
+  */
+  Fl_Int_Input(int X,int Y,int W,int H,const char *l = 0)
+      : Fl_Input(X,Y,W,H,l) {type(FL_INT_INPUT);}
 };
 
 #endif

FL/Fl_Multiline_Input.H

@@ -25,15 +25,31 @@
 //     http://www.fltk.org/str.php
 //
 
+
 #ifndef Fl_Multiline_Input_H
 #define Fl_Multiline_Input_H
 
 #include "Fl_Input.H"
 
+/**
+  This input field displays '\n' characters as new lines rather than ^J,
+  and accepts the Return, Tab, and up and down arrow keys.  This is for
+  editing multiline text.
+  <P>This is far from the nirvana of text editors, and is probably only
+  good for small bits of text, 10 lines at most.  I think FLTK can be
+  used to write a powerful text editor, but it is not going to be a
+  built-in feature.  Powerful text editors in a toolkit are a big source
+  of bloat.
+*/
 class Fl_Multiline_Input : public Fl_Input {
 public:
-    Fl_Multiline_Input(int X,int Y,int W,int H,const char *l = 0)
+  /**
-	: Fl_Input(X,Y,W,H,l) {type(FL_MULTILINE_INPUT);}
+    Creates a new Fl_Multiline_Input widget using the given
+    position, size, and label string. The default boxtype is FL_DOWN_BOX.
+    <P>Inherited destructor destroys the widget and any value associated with it.
+  */
+  Fl_Multiline_Input(int X,int Y,int W,int H,const char *l = 0)
+    : Fl_Input(X,Y,W,H,l) {type(FL_MULTILINE_INPUT);}
 };
 
 #endif

FL/Fl_Secret_Input.H

@@ -25,15 +25,26 @@
 //     http://www.fltk.org/str.php
 //
 
+
 #ifndef Fl_Secret_Input_H
 #define Fl_Secret_Input_H
 
 #include "Fl_Input.H"
 
+/**
+  The Fl_Secret_Input class is a subclass of Fl_Input
+  that displays its input as a string of asterisks.  This subclass is
+  usually used to receive passwords and other "secret" information.
+*/
 class Fl_Secret_Input : public Fl_Input {
 public:
-    Fl_Secret_Input(int X,int Y,int W,int H,const char *l = 0)
+  /**
-	: Fl_Input(X,Y,W,H,l) {type(FL_SECRET_INPUT);}
+    Creates a new Fl_Secret_Input widget using the given
+    position, size, and label string. The default boxtype is FL_DOWN_BOX.
+    <P>Inherited destructor destroys the widget and any value associated with it.
+  */
+  Fl_Secret_Input(int X,int Y,int W,int H,const char *l = 0)
+    : Fl_Input(X,Y,W,H,l) {type(FL_SECRET_INPUT);}
 };
 
 #endif

FL/Fl_Widget.H

@@ -532,8 +532,43 @@ public:
    */
   void argument(long v) {user_data_ = (void*)v;}
 
-  /** Return the conditions under which the callback is called.
+  /**
-   *  \return set of flags
+     Controls when callbacks are done. The following values are useful,
+     the default value is FL_WHEN_RELEASE:
+  
+  <UL>
+  
+  	<LI>0: The callback is not done, but
+  	changed() is turned on.</LI>
+  
+  	<LI>FL_WHEN_CHANGED: The callback is done each
+  	time the text is changed by the user.</LI>
+  
+  	<LI>FL_WHEN_RELEASE: The callback will be done
+  	when this widget loses the focus, including when the
+  	window is unmapped. This is a useful value for text
+  	fields in a panel where doing the callback on every
+  	change is wasteful. However the callback will also
+  	happen if the mouse is moved out of the window, which
+  	means it should not do anything visible (like pop up an
+  	error message). You might do better setting this to
+  	zero, and scanning all the items for changed()
+  	when the OK button on a panel is pressed.</LI>
+  
+  	<LI>FL_WHEN_ENTER_KEY: If the user types the
+  	Enter key, the entire text is selected, and the callback
+  	is done if the text has changed. Normally the Enter key
+  	will navigate to the next field (or insert a newline for
+  	a Fl_Mulitline_Input), this changes the
+  	behavior.</LI>
+  
+  	<LI>FL_WHEN_ENTER_KEY|FL_WHEN_NOT_CHANGED: The
+  	Enter key will do the callback even if the text has not
+  	changed. Useful for command fields.</LI>
+  
+  </UL>
+	Return the conditions under which the callback is called.
+        \return set of flags
    */
   Fl_When when() const {return (Fl_When)when_;}
 

documentation/todo_filelist_doc.txt

@@ -17,7 +17,7 @@ In Progress Work List (add your WP and name here):
   - WP6  (Fabien) DONE
   - WP7  (Fabien) DONE
   - WP8  (Fabien) DONE
-  - WP9  (Fabien)
+  - WP9  (Fabien) DONE
   - WP10 (Fabien)
   - WP11
   - WP12 (Albrecht) work in progress
@@ -171,11 +171,8 @@ Fl_Color_Chooser.cxx
 Fl_Counter.H
 Fl_Counter.cxx
 Fl_Export.H
-Fl_File_Input.H
-Fl_File_Input.cxx
 Fl_Fill_Dial.H
 Fl_Fill_Slider.H
-Fl_Float_Input.H
 Fl_Font.H
 Fl_FormsBitmap.H
 Fl_FormsPixmap.H
@@ -185,18 +182,10 @@ Fl_Hor_Fill_Slider.H
 Fl_Hor_Nice_Slider.H
 Fl_Hor_Slider.H
 Fl_Hor_Value_Slider.H
-Fl_Input.H
-Fl_Input.cxx
-Fl_Input_.H
-Fl_Input_.cxx
-Fl_Input_Choice.H
-Fl_Int_Input.H
 Fl_Line_Dial.H
 Fl_Multi_Browser.H
 Fl_Multi_Label.H
 Fl_Multi_Label.cxx
-Fl_Multiline_Input.H
-Fl_Multiline_Output.H
 Fl_Nice_Slider.H
 Fl_Object.H
 Fl_Output.H
@@ -206,7 +195,6 @@ Fl_Radio_Round_Button.H
 Fl_Roller.H
 Fl_Roller.cxx
 Fl_Round_Clock.H
-Fl_Secret_Input.H
 Fl_Select_Browser.H
 Fl_Simple_Counter.H
 Fl_Slider.H

src/Fl_File_Input.cxx

@@ -48,10 +48,10 @@
 #define FL_DAMAGE_BAR	0x10
 
 
-//
+/**
-// 'Fl_File_Input::Fl_File_Input()' - Create a Fl_File_Input widget.
+  Creates a new Fl_File_Input widget using the given position,
-//
+  size, and label string. The default boxtype is FL_DOWN_BOX.
-
+*/
 Fl_File_Input::Fl_File_Input(int X, int Y, int W, int H, const char *l)
   : Fl_Input(X, Y, W, H, l) {
   buttons_[0] = 0;
@@ -62,12 +62,8 @@ Fl_File_Input::Fl_File_Input(int X, int Y, int W, int H, const char *l)
   down_box(FL_UP_BOX);
 }
 
-//
+/** Draw directory buttons. */
-// 'Fl_File_Input::draw_buttons()' - Draw directory buttons.
+void Fl_File_Input::draw_buttons() {
-//
-
-void
-Fl_File_Input::draw_buttons() {
   int	i,					// Looping var
 	X;					// Current X position
 
@@ -101,12 +97,8 @@ Fl_File_Input::draw_buttons() {
   }
 }
 
-//
+/** Update the sizes of the directory buttons.*/
-// 'Fl_File_Input::update_buttons()' - Update the sizes of the directory buttons.
+void Fl_File_Input::update_buttons() {
-//
-
-void
-Fl_File_Input::update_buttons() {
   int		i;				// Looping var
   const char	*start,				// Start of path component
 		*end;				// End of path component
@@ -141,9 +133,7 @@ Fl_File_Input::update_buttons() {
 
 
 //
-// 'Fl_File_Input::value()' - Set the value of the widget...
+/** Sets the value of the widget given a new string value and its length, Returns non 0 on success */
-//
-
 int						// O - TRUE on success
 Fl_File_Input::value(const char *str,		// I - New string value
                      int        len) {		// I - Length of value
@@ -152,6 +142,7 @@ Fl_File_Input::value(const char *str,		// I - New string value
 }
 
 
+/** Sets the value of the widget given a new string value, Returns non 0 on success  */
 int						// O - TRUE on success
 Fl_File_Input::value(const char *str) {		// I - New string value
   damage(FL_DAMAGE_BAR);
@@ -159,12 +150,8 @@ Fl_File_Input::value(const char *str) {		// I - New string value
 }
 
 
-//
+/** Draws the file input widget */
-// 'Fl_File_Input::draw()' - Draw the file input widget...
+void Fl_File_Input::draw() {
-//
-
-void
-Fl_File_Input::draw() {
   Fl_Boxtype b = box();
   if (damage() & (FL_DAMAGE_BAR | FL_DAMAGE_ALL)) draw_buttons();
   // this flag keeps Fl_Input_::drawtext from drawing a bogus box!
@@ -178,10 +165,8 @@ Fl_File_Input::draw() {
 }
 
 
-//
-// 'Fl_File_Input::handle()' - Handle events in the widget...
-//
 
+/** Handle events in the widget, return non zero if event is handled */
 int						// O - TRUE if we handled event
 Fl_File_Input::handle(int event) 		// I - Event
 {
@@ -215,10 +200,8 @@ Fl_File_Input::handle(int event) 		// I - Event
 }
 
 
-//
-// 'Fl_File_Input::handle_button()' - Handle button events in the widget...
-//
 
+/** Handles button events in the widget , return non zero if event is handled */
 int						// O - TRUE if we handled event
 Fl_File_Input::handle_button(int event)		// I - Event
 {

src/Fl_Input.cxx

@@ -465,6 +465,10 @@ int Fl_Input::handle(int event) {
 	w()-Fl::box_dw(b), h()-Fl::box_dh(b));
 }
 
+/**
+  Creates a new Fl_Input widget using the given position, size,
+  and label string. The default boxtype is FL_DOWN_BOX.
+*/
 Fl_Input::Fl_Input(int X, int Y, int W, int H, const char *l)
 : Fl_Input_(X, Y, W, H, l) {
 }

src/Fl_Input_.cxx

@@ -25,6 +25,14 @@
 //     http://www.fltk.org/str.php
 //
 
+/** FIXME DOX: APIs not found
+ fn int Fl_Input_::wordboundary(int i) const
+  Returns true if position i is at the start or end of a word.
+
+ fn int Fl_Input_::lineboundary(int i) const
+  Returns true if position i is at the start or end of a line.
+
+*/
 // This is the base class for Fl_Input.  You can use it directly
 // if you are one of those people who like to define their own
 // set of editing keys.  It may also be useful for adding scrollbars
@@ -165,6 +173,12 @@ void Fl_Input_::setfont() const {
  fl_font(textfont(), textsize());
 }
 
+/**
+  Draw the text in the passed bounding box.  If damage()
+  & FL_DAMAGE_ALL is true, this assumes the area has
+  already been erased to color(). Otherwise it does
+  minimal update and erases the area itself.
+*/
 void Fl_Input_::drawtext(int X, int Y, int W, int H) {
   int do_mu = !(damage()&FL_DAMAGE_ALL);
 
@@ -472,6 +486,7 @@ void Fl_Input_::handle_mouse(int X, int Y, int /*W*/, int /*H*/, int drag) {
   position(newpos, newmark);
 }
 
+/**  See int Fl_Input_::position() const */
 int Fl_Input_::position(int p, int m) {
   int is_same = 0;
   was_up_down = 0;
@@ -520,6 +535,12 @@ int Fl_Input_::position(int p, int m) {
   return 1;
 }
 
+/**
+  Do the correct thing for arrow keys. Sets the position (and
+  mark if <I>keepmark</I> is zero) to somewhere in the same line
+  as <I>i</I>, such that pressing the arrows repeatedly will cause
+  the point to move up and down.
+*/
 int Fl_Input_::up_down_position(int i, int keepmark) {
   // unlike before, i must be at the start of the line already!
 
@@ -539,6 +560,13 @@ int Fl_Input_::up_down_position(int i, int keepmark) {
   return j;
 }
 
+/**
+  Put the current selection between mark() and
+  position() into the specified clipboard.  Does not
+  replace the old clipboard contents if position() and
+  mark() are equal. Clipboard 0 maps to the current text
+  selection and clipboard 1 maps to the cut/paste clipboard.
+*/
 int Fl_Input_::copy(int clipboard) {
   int b = position();
   int e = mark();
@@ -574,6 +602,29 @@ static void undobuffersize(int n) {
 }
 
 // all changes go through here, delete characters b-e and insert text:
+/**
+  This call does all editing of the text. It deletes the region
+  between a and b (either one may be less or
+  equal to the other), and then inserts the string insert
+  at that point and leaves the mark() and
+  position() after the insertion. Does the callback if
+  when() & FL_WHEN_CHANGED and there is a change.
+  
+  <P>Set start and end equal to not delete
+  anything. Set insert to NULL to not insert
+  anything.</P>
+  
+  <P>length must be zero or strlen(insert), this
+  saves a tiny bit of time if you happen to already know the
+  length of the insertion, or can be used to insert a portion of a
+  string or a string containing nul's.</P>
+  
+  <P>a and b are clamped to the
+  0..size() range, so it is safe to pass any values.</P>
+  
+  <P>cut() and insert() are just inline
+  functions that call replace().
+*/
 int Fl_Input_::replace(int b, int e, const char* text, int ilen) {
   int ul, om, op;
   was_up_down = 0;
@@ -669,6 +720,10 @@ int Fl_Input_::replace(int b, int e, const char* text, int ilen) {
   return 1;
 }
 
+/**
+  Does undo of several previous calls to replace().
+  Returns non-zero if any change was made.
+*/
 int Fl_Input_::undo() {
   was_up_down = 0;
   if (undowidget != this || !undocut && !undoinsert) return 0;
@@ -709,6 +764,10 @@ int Fl_Input_::undo() {
   return 1;
 }
 
+/**
+  Copy all the previous contiguous cuts from the undo
+  information to the clipboard. This is used to make ^K work.
+*/
 int Fl_Input_::copy_cuts() {
   // put the yank buffer into the X clipboard
   if (!yankcut || input_type()==FL_SECRET_INPUT) return 0;
@@ -839,6 +898,11 @@ int Fl_Input_::handletext(int event, int X, int Y, int W, int H) {
 
 /*------------------------------*/
 
+/**
+  Creates a new Fl_Input_ widget using the given
+  position, size, and label string. The default boxtype is
+  FL_DOWN_BOX.
+*/
 Fl_Input_::Fl_Input_(int X, int Y, int W, int H, const char* l)
 : Fl_Widget(X, Y, W, H, l) {
   box(FL_DOWN_BOX);
@@ -892,7 +956,7 @@ void Fl_Input_::put_in_buffer(int len) {
   memmove(buffer, value_, size_); buffer[size_] = 0;
   value_ = buffer;
 }
-
+/** See int Fl_Input::static_value(const char*) */
 int Fl_Input_::static_value(const char* str, int len) {
   clear_changed();
   if (undowidget == this) undowidget = 0;
@@ -923,16 +987,27 @@ int Fl_Input_::static_value(const char* str, int len) {
   return 1;
 }
 
+/**
+  Change the text and set the mark and the point to the end of
+  it. The string is <I>not</I> copied. If the user edits the
+  string it is copied to the internal buffer then. This can save a
+  great deal of time and memory if your program is rapidly
+  changing the values of text fields, but this will only work if
+  the passed string remains unchanged until either the
+  Fl_Input is destroyed or value() is called
+  again.
+*/
 int Fl_Input_::static_value(const char* str) {
   return static_value(str, str ? strlen(str) : 0);
 }
-
+/** See const char *Fl_Input_::value() const */
 int Fl_Input_::value(const char* str, int len) {
   int r = static_value(str, len);
   if (len) put_in_buffer(len);
   return r;
 }
 
+/** See const char *Fl_Input_::value() const */
 int Fl_Input_::value(const char* str) {
   return value(str, str ? strlen(str) : 0);
 }

src/Fl_Menu_add.cxx

@@ -175,6 +175,7 @@ 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.  
@@ -227,16 +228,7 @@ int Fl_Menu_Item::add(
   <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) {
@@ -283,6 +275,14 @@ int Fl_Menu_::add(const char *t, int s, Fl_Callback *c,void *v,int f) {
   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.
+
+  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 *str) {
   char buf[1024];