doxygen comments for fl_box(), fl_down(), fl_frame() and converted html tags

FL/Enumerations.H: doxygen comments for fl_box(), fl_down(), fl_frame()
documentation/src/common.dox: converted html tags to doxyge commands
documentation/src/preface.dox: corrected footer link
documentation/src/index.dox: corrected footer link



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

4 files changed, 126 insertions, 128 deletions

diff --git a/FL/Enumerations.H b/FL/Enumerations.H
index 7faa77b37..7059d6d85 100644
--- a/FL/Enumerations.H
+++ b/FL/Enumerations.H
@@ -529,12 +529,27 @@ extern FL_EXPORT Fl_Boxtype fl_define_FL_GTK_UP_BOX();
 #define FL_GTK_ROUND_DOWN_BOX (Fl_Boxtype)(fl_define_FL_GTK_UP_BOX()+9)
 
 // conversions of box types to other boxtypes:
+/**
+  Get the filled version of a frame.
+  If no filled version of a given frame exists, the behavior of this function
+  is undefined and some random box or frame is returned,
+  */
 inline Fl_Boxtype fl_box(Fl_Boxtype b) {
   return (Fl_Boxtype)((b<FL_UP_BOX||b%4>1)?b:(b-2));
 }
+/**
+  Get the "pressed" or "down" version of a box.
+  If no "down" version of a given box exists, the behavior of this function
+  is undefined and some random box or frame is returned,
+  */
 inline Fl_Boxtype fl_down(Fl_Boxtype b) {
   return (Fl_Boxtype)((b<FL_UP_BOX)?b:(b|1));
 }
+/**
+  Get the unfilled, frame only version of a box.
+  If no frame version of a given box exists, the behavior of this function
+  is undefined and some random box or frame is returned,
+  */
 inline Fl_Boxtype fl_frame(Fl_Boxtype b) {
   return (Fl_Boxtype)((b%4<2)?b:(b+2));
 }
diff --git a/documentation/src/common.dox b/documentation/src/common.dox
index 119976856..ab0e43c98 100644
--- a/documentation/src/common.dox
+++ b/documentation/src/common.dox
@@ -19,12 +19,13 @@ FLTK provides many types of buttons:
 \li Fl_Repeat_Button - A push button that repeats when held.
 
 \li Fl_Return_Button - A push button that is activated by the
-    <KBD>Enter</KBD> key.
+    \c Enter key.
 
 \li Fl_Round_Button - A button with a radio circle.
 
 \image html buttons.gif "Figure 3-1: FLTK Button Widgets"
 \image latex buttons.eps "FLTK Button Widgets" width=10cm
+
 All of these buttons just need the corresponding
 <tt><FL/Fl_xyz_Button.H></tt> header file. The constructor
 takes the bounding box of the button and optionally a label
@@ -36,7 +37,7 @@ Fl_Light_Button *lbutton = new Fl_Light_Button(x, y, width, height);
 Fl_Round_Button *rbutton = new Fl_Round_Button(x, y, width, height, "label");
 \endcode
 
-Each button has an associated <tt>type()</tt> which allows
+Each button has an associated \c type() which allows
 it to behave as a push button, toggle button, or radio button:
 
 \code
@@ -45,11 +46,11 @@ lbutton->type(FL_TOGGLE_BUTTON);
 rbutton->type(FL_RADIO_BUTTON);
 \endcode
 
-For toggle and radio buttons, the value() method returns 
-the current button state (0 = off, 1 = on). The set() and
-clear() methods can be used on toggle buttons to turn a 
+For toggle and radio buttons, the \c value() method returns 
+the current button state (0 = off, 1 = on). The \c set() and
+\c clear() methods can be used on toggle buttons to turn a 
 toggle button on or off, respectively. 
-Radio buttons can be turned on with the setonly()
+Radio buttons can be turned on with the \c setonly()
 method; this will also turn off other radio buttons in the same
 group.
 
@@ -71,11 +72,11 @@ FLTK provides several text widgets for displaying and receiving text:
 
 \li Fl_Help_View - A HTML text display widget.
 
-The <tt>Fl_Output</tt> and <tt>Fl_Multiline_Output</tt>
+The Fl_Output and Fl_Multiline_Output
 widgets allow the user to copy text from the output field but
 not change it.
 
-The <tt>value()</tt> method is used to get or set the 
+The \c value() method is used to get or set the 
 string that is displayed:
 
 \code
@@ -84,10 +85,10 @@ input->value("Now is the time for all good men...");
 \endcode
 
 The string is copied to the widget's own storage when you set
-the <tt>value()</tt> of the widget.
+the \c value() of the widget.
 
-The <tt>Fl_Text_Display</tt> and <tt>Fl_Text_Editor</tt>
-widgets use an associated <tt>Fl_Text_Buffer</tt> class for the
+The Fl_Text_Display and Fl_Text_Editor
+widgets use an associated Fl_Text_Buffer class for the
 value, instead of a simple string.
 
 <!-- NEED 4in -->
@@ -111,8 +112,9 @@ strings. FLTK provides the following valuators:
 
 \image html valuators.gif "Figure 3-2: FLTK valuator widgets"
 \image latex valuators.eps "FLTK valuator widgets" width=10cm
-The <tt>value()</tt> method gets and sets the current value 
-of the widget. The <tt>minimum()</tt> and <tt>maximum()</tt>
+
+The \c value() method gets and sets the current value 
+of the widget. The \c minimum() and \c maximum()
 methods set the range of values that are reported by the
 widget.
 
@@ -120,7 +122,7 @@ widget.
 
 \section common_groups Groups
 
-The <tt>Fl_Group</tt> widget class is used as a general
+The Fl_Group widget class is used as a general
 purpose "container" widget. Besides grouping radio
 buttons, the groups are used to encapsulate windows, tabs, and
 scrolled windows. The following group classes are available
@@ -147,13 +149,12 @@ with FLTK:
 
 \section common_sizeposition Setting the Size and Position of Widgets
 
-The size and position of widgets is usually set when you
-create them. You can access them with the <tt>x()</tt>,
-<tt>y()</tt>, <tt>w()</tt>, and <tt>h()</tt> methods.
+The size and position of widgets is usually set when you create them.
+You can access them with the \c x(), \c y(), \c w(), and \c h()
+methods.
 
-You can change the size and position by using the
-<tt>position()</tt>, <tt> resize()</tt>, and <tt>size()</tt>
-methods:
+You can change the size and position by using the \c position(),
+\c resize(), and \c size() methods:
 
 \code
 button->position(x, y);
@@ -162,7 +163,7 @@ window->size(width, height);
 \endcode
 
 If you change a widget's size or position after it is
-displayed you will have to call <tt>redraw()</tt> on the
+displayed you will have to call \c redraw() on the
 widget's parent.
 
 <A NAME="colors"></A> <!-- For old HTML links only ! -->
@@ -170,56 +171,44 @@ widget's parent.
 
 FLTK stores the colors of widgets as an 32-bit unsigned
 number that is either an index into a color palette of 256
-colors or a 24-bit RGB color. The color palette is <i>not</i>
+colors or a 24-bit RGB color. The color palette is \e not
 the X or WIN32 colormap, but instead is an internal table with
 fixed contents.
 
 There are symbols for naming some of the more common colors:
 
-\li <tt>FL_BLACK</tt>
-
-\li <tt>FL_RED</tt>
-
-\li <tt>FL_GREEN</tt>
-
-\li <tt>FL_YELLOW</tt>
-
-\li <tt>FL_BLUE</tt>
-
-\li <tt>FL_MAGENTA</tt>
-
-\li <tt>FL_CYAN</tt>
-
-\li <tt>FL_WHITE</tt>
-
-\li FL_WHITE
+\li \c FL_BLACK
+\li \c FL_RED
+\li \c FL_GREEN
+\li \c FL_YELLOW
+\li \c FL_BLUE
+\li \c FL_MAGENTA
+\li \c FL_CYAN
+\li \c FL_WHITE
+\li \c FL_WHITE
 
 These symbols are the default colors for all FLTK widgets. They are
 explained in more detail in the chapter 
 <A HREF="enumerations.html#colors">Enumerations</A>
 
-\li <tt>FL_FOREGROUND_COLOR</tt> 
-
-\li <tt>FL_BACKGROUND_COLOR</tt> 
-
-\li <tt>FL_INACTIVE_COLOR</tt> 
+\li \c FL_FOREGROUND_COLOR
+\li \c FL_BACKGROUND_COLOR
+\li \c FL_INACTIVE_COLOR
+\li \c FL_SELECTION_COLOR
 
-\li <tt>FL_SELECTION_COLOR</tt> 
-
-RGB colors can be set using the <tt>fl_rgb_color()</tt> function:
+RGB colors can be set using the \c fl_rgb_color() function:
 
 \code
 Fl_Color c = fl_rgb_color(85, 170, 255);
 \endcode
 
-The widget color is set using the <tt>color()</tt> method:
+The widget color is set using the \c color() method:
 
 \code
 button->color(FL_RED);
 \endcode
 
-Similarly, the label color is set using the <tt>labelcolor()</tt>
-method:
+Similarly, the label color is set using the \c labelcolor() method:
 
 \code
 button->labelcolor(FL_WHITE);
@@ -228,14 +217,15 @@ button->labelcolor(FL_WHITE);
 <A NAME="boxtypes"></A> <!-- For old HTML links only ! -->
 \section common_boxtypes Box Types
 
-The type <tt>Fl_Boxtype</tt> stored and returned in Fl_Widget::box()
+The type Fl_Boxtype stored and returned in Fl_Widget::box()
 is an enumeration defined in Enumerations.H.
 
 Figure 3-3 shows the standard box types included with FLTK.
 
 \image html boxtypes.gif "Figure 3-3: FLTK box types"
 \image latex boxtypes.eps "FLTK box types" width=12cm
-<tt>FL_NO_BOX</tt> means nothing is drawn at all, so whatever is
+
+\c FL_NO_BOX means nothing is drawn at all, so whatever is
 already on the screen remains. The <tt>FL_..._FRAME</tt> types only
 draw their edges, leaving the interior unchanged. The blue color in
 Figure 3-3 is the area that is not drawn by the frame types.
@@ -279,46 +269,50 @@ void xyz_draw(int x, int y, int w, int h, Fl_Color c) {
 \endcode
 
 <A name="fl_down"></A>  <!-- For old HTML links only ! -->
-\par Fl_Boxtype fl_down(Fl_Boxtype)
+\anchor common_fl_down
+Fl_Boxtype fl_down(Fl_Boxtype b)
 
-<tt>fl_down</tt> returns the "pressed" or "down" version of a box.
+fl_down() returns the "pressed" or "down" version of a box.
 If no "down" version of a given box exists, the behavior of this function
 is undefined and some random box or frame is returned.
 See also: <A HREF="drawing.html#fl_frame">fl_frame drawing</A>.
 
 <A name="fl_frame"></A>  <!-- For old HTML links only ! -->
-\par Fl_Boxtype fl_frame(Fl_Boxtype)
+\anchor common_fl_frame
+Fl_Boxtype fl_frame(Fl_Boxtype b)
 
-<tt>fl_frame</tt> returns the unfilled, frame-only version of a box.
+fl_frame() returns the unfilled, frame-only version of a box.
 If no frame version of a given box exists, the behavior of this function
 is undefined and some random box or frame is returned.
 See also: <A HREF="drawing.html#fl_frame">fl_frame drawing</A>.
 
 <A name="fl_box"></A> <!-- For old HTML links only ! -->
-\par Fl_Boxtype fl_box(Fl_Boxtype)
+\anchor common_fl_box
+Fl_Boxtype fl_box(Fl_Boxtype b)
 
-<tt>fl_box</tt> returns the filled version of a frame.
+fl_box() returns the filled version of a frame.
 If no filled version of a given frame exists, the behavior of this function
 is undefined and some random box or frame is returned.
 See also: <tt><A HREF="#fl_frame">fl_frame</A></tt>.
 
 \par Adding Your Box Type
 
-The <tt>Fl::set_boxtype()</tt> method adds or replaces the specified box type:
+The Fl::set_boxtype() method adds or replaces the specified box type:
 
 \code
 #define XYZ_BOX FL_FREE_BOXTYPE
 
 Fl::set_boxtype(XYZ_BOX, xyz_draw, 1, 1, 2, 2);
 \endcode
-The last 4 arguments to <tt>Fl::set_boxtype()</tt> are the
+The last 4 arguments to Fl::set_boxtype() are the
 offsets for the x, y, width, and height values that should be
 subtracted when drawing the label inside the box.
 
 A complete box design contains four box types in this order: 
-a filled, neutral box (<tt>UP_BOX</tt>), a filled, depressed box 
-(<tt>DOWN_BOX</tt>), and the same as outlines only (<tt>UP_FRAME</tt> 
-and <tt>DOWN_FRAME</tt>). The function 
+a filled, neutral box (<tt>UP_BOX</tt>),
+a filled, depressed box (<tt>DOWN_BOX</tt>),
+and the same as outlines only (<tt>UP_FRAME</tt> and <tt>DOWN_FRAME</tt>).
+The function
 <tt><A HREF="#fl_down">fl_down(Fl_Boxtype)</A></tt> 
 expects the neutral design on a boxtype with a numerical 
 value evenly divideable by two. 
@@ -328,13 +322,15 @@ expects the <tt>UP_BOX</tt> design at a value divideable by four.
 <A NAME="labels"></A> <!-- For old HTML links only ! -->
 \section common_labels Labels and Label Types
 
-The <tt>label()</tt>, <tt>align()</tt>, <tt>labelfont()</tt>,
-<tt>labelsize()</tt>, <tt>labeltype()</tt>, <tt>image()</tt>, and
-<tt>deimage()</tt> methods control the labeling of widgets.
+\todo correct signatures for label() and friends to produce links in common.dox
+
+The \c label(), \c align(), \c labelfont(), \c labelsize(),
+\c labeltype(), \c image(), and \c deimage() methods control the
+labeling of widgets.
 
 \par label()
 
-The <tt>label()</tt> method sets the string that is displayed
+The \c label() method sets the string that is displayed
 for the label. Symbols can be included with the label string by
 escaping them using the "@" symbol - "@@" displays a single at
 sign. Figure 3-4 shows the available symbols.
@@ -362,55 +358,38 @@ label string "@+92->".
 
 \par align()
 
-The <tt>align()</tt> method positions the label. The following
+The \c align() method positions the label. The following
 constants are defined and may be OR'd together as needed:
 
-\li <tt>FL_ALIGN_CENTER</tt> - center the label in the widget.
-
-\li <tt>FL_ALIGN_TOP</tt> - align the label at the top of the widget.
-
-\li <tt>FL_ALIGN_BOTTOM</tt> - align the label at the bottom of the
-	widget.
-
-\li <tt>FL_ALIGN_LEFT</tt> - align the label to the left of the widget.
-
-\li <tt>FL_ALIGN_RIGHT</tt> - align the label to the right of the
-	widget.
-
-\li <tt>FL_ALIGN_INSIDE</tt> - align the label inside the widget.
-
-\li <tt>FL_ALIGN_CLIP</tt> - clip the label to the widget's bounding
-	box.
-
-\li <tt>FL_ALIGN_WRAP</tt> - wrap the label text as needed.
-
-\li <tt>FL_TEXT_OVER_IMAGE</tt> - show the label text over the image.
-
-\li <tt>FL_IMAGE_OVER_TEXT</tt> - show the label image over the text (default).
+\li \c FL_ALIGN_CENTER - center the label in the widget.
+\li \c FL_ALIGN_TOP - align the label at the top of the widget.
+\li \c FL_ALIGN_BOTTOM - align the label at the bottom of the widget.
+\li \c FL_ALIGN_LEFT - align the label to the left of the widget.
+\li \c FL_ALIGN_RIGHT - align the label to the right of the widget.
+\li \c FL_ALIGN_INSIDE - align the label inside the widget.
+\li \c FL_ALIGN_CLIP - clip the label to the widget's bounding box.
+\li \c FL_ALIGN_WRAP - wrap the label text as needed.
+\li \c FL_TEXT_OVER_IMAGE - show the label text over the image.
+\li \c FL_IMAGE_OVER_TEXT - show the label image over the text (default).
 
 <A NAME="labeltypes"></A> <!-- For old HTML links only ! -->
 \par labeltype()
 
-The <tt>labeltype()</tt> method sets the type of the label.  The
+The \c labeltype() method sets the type of the label.  The
 following standard label types are included:
 
-\li <tt>FL_NORMAL_LABEL</tt> - draws the text.
-
-\li <tt>FL_NO_LABEL</tt> - does nothing.
-
-\li <tt>FL_SHADOW_LABEL</tt> - draws a drop shadow under the text.
-
-\li <tt>FL_ENGRAVED_LABEL</tt> - draws edges as though the text is engraved.
-
-\li <tt>FL_EMBOSSED_LABEL</tt> - draws edges as thought the text is raised.
-
-\li <tt>FL_ICON_LABEL</tt> - draws the icon associated with the text.
+\li \c FL_NORMAL_LABEL - draws the text.
+\li \c FL_NO_LABEL - does nothing.
+\li \c FL_SHADOW_LABEL - draws a drop shadow under the text.
+\li \c FL_ENGRAVED_LABEL - draws edges as though the text is engraved.
+\li \c FL_EMBOSSED_LABEL - draws edges as thought the text is raised.
+\li \c FL_ICON_LABEL - draws the icon associated with the text.
 
 \par image() and deimage()
 
-The <tt>image()</tt> and <tt>deimage()</tt> methods set an image that
-will be displayed with the widget. The <tt>deimage()</tt> method sets the
-image that is shown when the widget is inactive, while the <tt>image()</tt>
+The \c image() and \c deimage() methods set an image that
+will be displayed with the widget. The \c deimage() method sets the
+image that is shown when the widget is inactive, while the \c image()
 method sets the image that is shown when the widget is active.
 
 To make an image you use a subclass of
@@ -421,7 +400,7 @@ To make an image you use a subclass of
 Label types are actually indexes into a table of functions
 that draw them. The primary purpose of this is to use this to
 draw the labels in ways inaccessible through the
-<tt>fl_font</tt> mechanisim (e.g. <tt>FL_ENGRAVED_LABEL</tt>) or
+fl_font() mechanisim (e.g. <tt>FL_ENGRAVED_LABEL</tt>) or
 with program-generated letters or symbology.
 
 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
@@ -436,7 +415,7 @@ with program-generated letters or symbology.
 
 To setup your own label type you will need to write two
 functions: one to draw and one to measure the label. The draw
-function is called with a pointer to a <tt>Fl_Label</tt>
+function is called with a pointer to a Fl_Label
 structure containing the label information, the bounding box for
 the label, and the label alignment:
 
@@ -446,12 +425,12 @@ void xyz_draw(const Fl_Label *label, int x, int y, int w, int h, Fl_Align align)
 }
 \endcode
 
-The label should be drawn <I>inside</I> this bounding box,
-even if <tt>FL_ALIGN_INSIDE</tt> is not enabled. The function
-is not called if the label value is <tt>NULL</tt>.
+The label should be drawn \e inside this bounding box,
+even if \c FL_ALIGN_INSIDE is not enabled. The function
+is not called if the label value is \c NULL.
 
 The measure function is called with a pointer to a
-<tt>Fl_Label</tt> structure and references to the width and
+Fl_Label structure and references to the width and
 height:
 
 \code
@@ -461,11 +440,11 @@ void xyz_measure(const Fl_Label *label, int &w, int &h) {
 \endcode
 
 The function should measure the size of the label and set
-<tt>w</tt> and <tt>h</tt> to the size it will occupy.
+\c w and \c h to the size it will occupy.
 
 \par Adding Your Label Type
 
-The <tt>Fl::set_labeltype</tt> method creates a label type
+The Fl::set_labeltype method creates a label type
 using your draw and measure functions:
 
 \code
@@ -474,13 +453,13 @@ using your draw and measure functions:
 Fl::set_labeltype(XYZ_LABEL, xyz_draw, xyz_measure);
 \endcode
 
-The label type number <tt>n</tt> can be any integer value
-starting at the constant <tt>FL_FREE_LABELTYPE</tt>. Once you
-have added the label type you can use the <tt>labeltype()</tt>
+The label type number \c n can be any integer value
+starting at the constant \c FL_FREE_LABELTYPE. Once you
+have added the label type you can use the \c labeltype()
 method to select your label type.
 
-The <tt>Fl::set_labeltype</tt> method can also be used to overload
-an existing label type such as <tt>FL_NORMAL_LABEL</tt>.
+The Fl::set_labeltype method can also be used to overload
+an existing label type such as \c FL_NORMAL_LABEL.
 
 <A NAME="add_symbol"></A> <!-- For old HTML links only ! -->
 \par Making your own symbols
@@ -494,13 +473,13 @@ To create a new symbol, you implement a drawing function
 <a href="drawing.html#complex">complex drawing functions</a>
 to generate a vector shape inside a two-by-two units sized box
 around the origin. This function is then linked into the symbols
-table using <tt>fl_add_symbol</tt>:
+table using fl_add_symbol():
 
 \code
 int fl_add_symbol(const char *name, void (*drawit)(Fl_Color), int scalable)
 \endcode
 
-<i>name</i> is the name of the symbol without the "@"; <i>scalable</I>
+\c name is the name of the symbol without the "@"; \c scalable
 must be set to 1 if the symbol is generated using scalable vector drawing
 functions.
 
@@ -513,7 +492,7 @@ This function draws a named symbol fitting the given rectangle.
 \section common_callbacks Callbacks
 
 Callbacks are functions that are called when the value of a
-widget changes. A callback function is sent a <tt>Fl_Widget</tt>
+widget changes. A callback function is sent a Fl_Widget
 pointer of the widget that changed and a pointer to data that
 you provide:
 
@@ -523,7 +502,7 @@ void xyz_callback(Fl_Widget *w, void *data) {
 }
 \endcode
 
-The <tt>callback()</tt> method sets the callback function for a
+The \c callback() method sets the callback function for a
 widget. You can optionally pass a pointer to some data needed for the
 callback:
 
@@ -569,7 +548,7 @@ button->when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED);
 	in your class that accepts a pointer to the class, and
 	then have the static method call the class method(s) as
 	needed. The data pointer you provide to the
-	<tt>callback()</tt> method of the widget can be a
+	\c callback() method of the widget can be a
 	pointer to the instance of your class.
 
 \code
@@ -590,7 +569,7 @@ w->callback(my_static_callback, (void *)this);
 \section common_shortcuts Shortcuts
 
 Shortcuts are key sequences that activate widgets such as
-buttons or menu items. The <tt>shortcut()</tt> method sets the
+buttons or menu items. The \c shortcut() method sets the
 shortcut for a widget:
 
 \code
@@ -605,8 +584,7 @@ button->shortcut(0); // no shortcut
 The shortcut value is the key event value - the ASCII value
 or one of the special keys like
 <a href="enumerations.html#key_values"><tt>FL_Enter</tt></a> -
-combined with any modifiers like <KBD>Shift</KBD>,
-<KBD>Alt</KBD>, and <KBD>Control</KBD>.
+combined with any modifiers like \c Shift , \c Alt , and \c Control .
 
 \htmlonly
 <hr>
diff --git a/documentation/src/index.dox b/documentation/src/index.dox
index 7f219e369..a2ae84ece 100644
--- a/documentation/src/index.dox
+++ b/documentation/src/index.dox
@@ -93,4 +93,10 @@
 </TR>
 </TABLE>
 
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="preface.html">[Next]&nbsp; Preface</a>&nbsp;
+\endhtmlonly
+
 */
diff --git a/documentation/src/preface.dox b/documentation/src/preface.dox
index 39c865592..b3b17a3df 100644
--- a/documentation/src/preface.dox
+++ b/documentation/src/preface.dox
@@ -78,8 +78,7 @@ registered trademarks of Apple Computer, Inc.
 \htmlonly
 <hr>
 <a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
-<a class="el" href="intro.html">[Next]</a>&nbsp;
-     \ref intro
+<a class="el" href="intro.html">[Next]&nbsp; 1 - Introduction to FLTK</a>
 
 \endhtmlonly
 */