converted more html to plain doxygen in {events,subclassing,opengl}.dox

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

1 files changed, 323 insertions, 228 deletions

diff --git a/documentation/subclassing.dox b/documentation/subclassing.dox
index 865f58cb8..4b9cf82d0 100644
--- a/documentation/subclassing.dox
+++ b/documentation/subclassing.dox
@@ -2,46 +2,63 @@
 
  \page	subclassing	7 - Adding and Extending Widgets
 
-<P>This chapter describes how to add your own widgets or extend existing
+
+This chapter describes how to add your own widgets or extend existing
 widgets in FLTK.
-<H2>Subclassing</H2>
- New widgets are created by <I>subclassing</I> an existing FLTK widget,
-typically <TT>Fl_Widget</TT> for controls and <TT>Fl_Group</TT> for
+
+\section subclassing_subclassing Subclassing
+
+New widgets are created by <I>subclassing</I> an existing FLTK widget,
+typically <tt>Fl_Widget</tt> for controls and <tt>Fl_Group</tt> for
 composite widgets.
-<P>A control widget typically interacts with the user to receive and/or
-display a value of some sort. </P>
-<P>A composite widget widget holds a list of child widgets and handles moving,
-sizing, showing, or hiding them as needed. <TT>Fl_Group</TT> is the
-main composite widget widget class in FLTK, and all of the other composite widgets (<TT>
-Fl_Pack</TT>, <TT>Fl_Scroll</TT>, <TT>Fl_Tabs</TT>, <TT>Fl_Tile</TT>,
-and <TT>Fl_Window</TT>) are subclasses of it. </P>
-<P>You can also subclass other existing widgets to provide a different
+
+A control widget typically interacts with the user to receive and/or
+display a value of some sort. 
+
+A composite widget widget holds a list of child widgets and handles moving,
+sizing, showing, or hiding them as needed. <tt>Fl_Group</tt> is the
+main composite widget widget class in FLTK, and all of the other composite
+widgets (<tt>Fl_Pack</tt>, <tt>Fl_Scroll</tt>, <tt>Fl_Tabs</tt>,
+<tt>Fl_Tile</tt>, and <tt>Fl_Window</tt>) are subclasses of it. 
+
+You can also subclass other existing widgets to provide a different
 look or user-interface. For example, the button widgets are all
-subclasses of <TT>Fl_Button</TT> since they all interact with the user
+subclasses of <tt>Fl_Button</tt> since they all interact with the user
 via a mouse button click.  The only difference is the code that draws
-the face of the button. </P>
-<H2>Making a Subclass of Fl_Widget</H2>
- Your subclasses can directly descend from <TT>Fl_Widget</TT> or any
-subclass of <TT>Fl_Widget</TT>. <TT>Fl_Widget</TT> has only four
+the face of the button. 
+
+\section subclassing_fl_widget Making a Subclass of Fl_Widget
+
+Your subclasses can directly descend from <tt>Fl_Widget</tt> or any
+subclass of <tt>Fl_Widget</tt>. <tt>Fl_Widget</tt> has only four
 virtual methods, and overriding some or all of these may be necessary.
-<H2>The Constructor</H2>
- The constructor should have the following arguments:
+
+\section subclassing_constructor The Constructor
+
+The constructor should have the following arguments:
+
 \code
 MyClass(int x, int y, int w, int h, const char *label = 0);
 \endcode
- This will allow the class to be used in <A href="fluid.html#FLUID">FLUID</A>
- without problems.
-<P>The constructor must call the constructor for the base class and
-pass the same arguments: </P>
+
+This will allow the class to be used in
+<A href="fluid.html#FLUID">FLUID</A>
+without problems.
+
+The constructor must call the constructor for the base class and
+pass the same arguments: 
+
 \code
 MyClass::MyClass(int x, int y, int w, int h, const char *label)
 : Fl_Widget(x, y, w, h, label) {
 // do initialization stuff...
 }
 \endcode
-<TT>Fl_Widget</TT>'s protected constructor sets <TT>x()</TT>, <TT>y()</TT>,
-<TT>w()</TT>, <TT>h()</TT>, and <TT>label()</TT> to the passed values
+
+<tt>Fl_Widget</tt>'s protected constructor sets <tt>x()</tt>, <tt>y()</tt>,
+<tt>w()</tt>, <tt>h()</tt>, and <tt>label()</tt> to the passed values
 and initializes the other instance variables to:
+
 \code
 type(0);
 box(FL_NO_BOX);
@@ -57,36 +74,47 @@ flags(ACTIVE|VISIBLE);
 image(0);
 deimage(0);
 \endcode
-<H2>Protected Methods of Fl_Widget</H2>
- The following methods are provided for subclasses to use:
-<UL>
-<LI><A href="#clear_visible"><TT>Fl_Widget::clear_visible</TT></A></LI>
-<LI><A href="#damage"><TT>Fl_Widget::damage</TT></A></LI>
-<LI><A href="#draw_box"><TT>Fl_Widget::draw_box</TT></A></LI>
-<LI><A href="#draw_focus"><TT>Fl_Widget::draw_focus</TT></A></LI>
-<LI><A href="#draw_label"><TT>Fl_Widget::draw_label</TT></A></LI>
-<LI><A href="#set_flag"><TT>Fl_Widget::set_flag</TT></A></LI>
-<LI><A href="#set_visible"><TT>Fl_Widget::set_visible</TT></A></LI>
-<LI><A href="#test_shortcut"><TT>Fl_Widget::test_shortcut</TT></A></LI>
-<LI><A href="#type"><TT>Fl_Widget::type</TT></A></LI>
-</UL>
-<H4><A name="damage">void Fl_Widget::damage(uchar mask)
-<BR> void Fl_Widget::damage(uchar mask, int x, int y, int w, int h)
-<BR> uchar Fl_Widget::damage()</A></H4>
+
+\section subclassing_protected Protected Methods of Fl_Widget
+
+The following methods are provided for subclasses to use:
+
+\li <A href="#clear_visible"><tt>Fl_Widget::clear_visible</tt></A>
+\li <A href="#damage"><tt>Fl_Widget::damage</tt></A>
+\li <A href="#draw_box"><tt>Fl_Widget::draw_box</tt></A>
+\li <A href="#draw_focus"><tt>Fl_Widget::draw_focus</tt></A>
+\li <A href="#draw_label"><tt>Fl_Widget::draw_label</tt></A>
+\li <A href="#set_flag"><tt>Fl_Widget::set_flag</tt></A>
+\li <A href="#set_visible"><tt>Fl_Widget::set_visible</tt></A>
+\li <A href="#test_shortcut"><tt>Fl_Widget::test_shortcut</tt></A>
+\li <A href="#type"><tt>Fl_Widget::type</tt></A>
+
+<A name="damage"></A> <!-- For old HTML links only ! -->
+void Fl_Widget::damage(uchar mask) <br>
+void Fl_Widget::damage(uchar mask, int x, int y, int w, int h) <br>
+uchar Fl_Widget::damage()
+
+\par
 The first form indicates that a partial update of the object is
-needed.  The bits in mask are OR'd into <TT>damage()</TT>.  Your <TT>
-draw()</TT> routine can examine these bits to limit what it is
-drawing.  The public method <TT>Fl_Widget::redraw()</TT> simply does
-<TT> Fl_Widget::damage(FL_DAMAGE_ALL)</TT>, but the  implementation of
-your widget can call the private <TT>damage(n)</TT>.
-<P>The second form indicates that a region is damaged.  If only these
-calls are done in a window (no calls to <TT>damage(n)</TT>) then FLTK
+needed.  The bits in mask are OR'd into <tt>damage()</tt>.  Your <tt>
+draw()</tt> routine can examine these bits to limit what it is
+drawing.  The public method <tt>Fl_Widget::redraw()</tt> simply does
+<tt> Fl_Widget::damage(FL_DAMAGE_ALL)</tt>, but the  implementation of
+your widget can call the private <tt>damage(n)</tt>.
+
+\par
+The second form indicates that a region is damaged.  If only these
+calls are done in a window (no calls to <tt>damage(n)</tt>) then FLTK
 will clip to the union of all these calls before drawing anything.
  This can greatly speed up incremental displays.  The mask bits are
-OR'd into <TT>damage()</TT> unless this is a <TT>Fl_Window</TT> widget. </P>
-<P>The third form returns the bitwise-OR of all <TT>damage(n)</TT>
-calls done since the last <TT>draw()</TT>.</P>
-<P><I>When redrawing your widgets you should look at the damage bits to
+OR'd into <tt>damage()</tt> unless this is a <tt>Fl_Window</tt> widget. 
+
+\par
+The third form returns the bitwise-OR of all <tt>damage(n)</tt>
+calls done since the last <tt>draw()</tt>.
+
+\par
+<I>When redrawing your widgets you should look at the damage bits to
 see what parts of your widget need redrawing.</I> The <tt>handle()</tt>
 method can then set individual damage bits to limit the amount of drawing
 that needs to be done:
@@ -108,90 +136,134 @@ MyClass::draw() {
   if (damage() &amp; (FL_DAMAGE_ALL | 4)) draw_part3();
 }
 \endcode
-<H4><A name="draw_box">void Fl_Widget::draw_box() const
-<BR></A>void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const</H4>
- The first form draws this widget's <TT>box()</TT>, using the
-dimensions of the widget.  The second form uses <TT>b</TT> as the box
-type and <TT>c</TT> as the color for the box.
 
-<H4><A name="draw_focus">void Fl_Widget::draw_focus() const
-<BR>void Fl_Widget::draw_focus(Fl_Boxtype b, int x, int y, int w, int h) const</A></H4>
+<A name="draw_box"></A> <!-- For old HTML links only ! -->
+void Fl_Widget::draw_box() const <br>
+void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const
+
+\par
+The first form draws this widget's <tt>box()</tt>, using the
+dimensions of the widget.  The second form uses <tt>b</tt> as the box
+type and <tt>c</tt> as the color for the box.
 
-<P>Draws a focus box inside the widgets bounding box. The second
+<A name="draw_focus"></A> <!-- For old HTML links only ! -->
+void Fl_Widget::draw_focus() const <br>
+void Fl_Widget::draw_focus(Fl_Boxtype b, int x, int y, int w, int h) const
+
+\par
+Draws a focus box inside the widgets bounding box. The second
 form allows you to specify a different bounding box.
 
-<H4><A name="draw_label">void Fl_Widget::draw_label() const
-<BR> void Fl_Widget::draw_label(int x, int y, int w, int h) const
-<BR> void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align
-align) const</A></H4>
- This is the usual function for a <TT>draw()</TT> method to call to
+<A name="draw_label"></A> <!-- For old HTML links only ! -->
+void Fl_Widget::draw_label() const <br>
+void Fl_Widget::draw_label(int x, int y, int w, int h) const <br>
+void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align align) const
+
+\par
+This is the usual function for a <tt>draw()</tt> method to call to
 draw the widget's label.  It does not draw the label if it is supposed
 to be outside the box (on the assumption that the enclosing group will
 draw those labels).
-<P>The second form uses the passed bounding box instead of the widget's
+
+\par
+The second form uses the passed bounding box instead of the widget's
 bounding box. This is useful so &quot;centered&quot; labels are aligned with some
-feature, like a moving slider. </P>
-<P>The third form draws the label anywhere. It acts as though <TT>
-FL_ALIGN_INSIDE</TT> has been forced on so the label will appear inside
+feature, like a moving slider. 
+
+\par
+The third form draws the label anywhere. It acts as though <tt>
+FL_ALIGN_INSIDE</tt> has been forced on so the label will appear inside
 the passed bounding box. This is designed for parent groups to draw
-labels with. </P>
-<H4><A name="set_flag">void Fl_Widget::set_flag(SHORTCUT_LABEL)</A></H4>
-Modifies <TT>draw_label()</TT> so that '&amp;' characters cause an underscore
+labels with. 
+
+<A name="set_flag"></A> <!-- For old HTML links only ! -->
+void Fl_Widget::set_flag(SHORTCUT_LABEL)
+
+\par
+Modifies <tt>draw_label()</tt> so that '&amp;' characters cause an underscore
 to be printed under the next letter.
-<H4><A name="set_visible">void Fl_Widget::set_visible()</A>
-<BR><A name="clear_visible">void Fl_Widget::clear_visible()</A></H4>
- Fast inline versions of <TT>Fl_Widget::hide()</TT> and <TT>
-Fl_Widget::show()</TT>. These do not send the <TT>FL_HIDE</TT> and <TT>
-FL_SHOW</TT> events to the widget.
-<H4><A name="test_shortcut">int Fl_Widget::test_shortcut() const
-<BR> static int Fl_Widget::test_shortcut(const char *s)</A></H4>
- The first version tests <TT>Fl_Widget::label()</TT> against the
-current event (which should be a <TT>FL_SHORTCUT</TT> event).  If the
+
+<A name="set_visible"></A> <!-- For old HTML links only ! -->
+<A name="clear_visible"></A> <!-- For old HTML links only ! -->
+void Fl_Widget::set_visible() <br>
+void Fl_Widget::clear_visible()
+
+\par
+Fast inline versions of <tt>Fl_Widget::hide()</tt> and <tt>
+Fl_Widget::show()</tt>. These do not send the <tt>FL_HIDE</tt> and <tt>
+FL_SHOW</tt> events to the widget.
+
+<A name="test_shortcut"></A> <!-- For old HTML links only ! -->
+int Fl_Widget::test_shortcut() const <br>
+static int Fl_Widget::test_shortcut(const char *s)
+
+\par
+The first version tests <tt>Fl_Widget::label()</tt> against the
+current event (which should be a <tt>FL_SHORTCUT</tt> event).  If the
 label contains a '&amp;' character and the character after it matches the key
-press, this returns true.  This returns false if the <TT>SHORTCUT_LABEL</TT>
-flag is off, if the label is <TT>NULL</TT> or does not have a
+press, this returns true.  This returns false if the <tt>SHORTCUT_LABEL</tt>
+flag is off, if the label is <tt>NULL</tt> or does not have a
 '&amp;' character in it, or if the keypress does not match the character.
-<P>The second version lets you do this test against an arbitrary
-string. </P>
-<H4><A name="type">uchar Fl_Widget::type() const
-<BR> void Fl_Widget::type(uchar t)</A></H4>
- The property <TT>Fl_Widget::type()</TT> can return an arbitrary 8-bit
-identifier, and can be set with the protected method <TT>type(uchar t)</TT>
-. This value had to be provided for Forms compatibility, but you can
+
+\par
+The second version lets you do this test against an arbitrary string. 
+
+<A name="type"></A> <!-- For old HTML links only ! -->
+uchar Fl_Widget::type() const <br>
+void Fl_Widget::type(uchar t)
+
+\par
+The property <tt>Fl_Widget::type()</tt> can return an arbitrary 8-bit
+identifier, and can be set with the protected method <tt>type(uchar t)</tt>.
+This value had to be provided for Forms compatibility, but you can
 use it for any purpose you want.  Try to keep the value less than 100
 to not interfere with reserved values.
-<P>FLTK does not use RTTI (Run Time Typing Infomation), to enhance
+
+\par
+FLTK does not use RTTI (Run Time Typing Infomation), to enhance
 portability.  But this may change in the near future if RTTI becomes
-standard everywhere. </P>
-<P>If you don't have RTTI you can use the clumsy FLTK mechanisim, by
-having <TT>type()</TT> use a unique value.  These unique values must
-be greater than the symbol <TT>FL_RESERVED_TYPE</TT> (which is 100).
-Look through the header files for <TT>FL_RESERVED_TYPE</TT> to find an
-unused number.  If you make a subclass of <TT>Fl_Window</TT>
-you must use <TT>FL_WINDOW + n</TT> (<TT>n</tt> must be in the
-range 1 to 7). </P>
-<H2><A NAME="handle">Handling Events</A></H2>
- The virtual method <TT>int Fl_Widget::handle(int event)</TT> is called
+standard everywhere. 
+
+\par
+If you don't have RTTI you can use the clumsy FLTK mechanisim, by
+having <tt>type()</tt> use a unique value.  These unique values must
+be greater than the symbol <tt>FL_RESERVED_TYPE</tt> (which is 100).
+Look through the header files for <tt>FL_RESERVED_TYPE</tt> to find an
+unused number.  If you make a subclass of <tt>Fl_Window</tt>
+you must use <tt>FL_WINDOW + n</tt> (<tt>n</tt> must be in the
+range 1 to 7). 
+
+<A NAME="handle"></A> <!-- For old HTML links only ! -->
+\section subclassing_events Handling Events
+
+The virtual method <tt>int Fl_Widget::handle(int event)</tt> is called
 to handle each event passed to the widget. It can:
-<UL>
-<LI>Change the state of the widget. </LI>
-<LI>Call <A href="Fl_Widget.html#Fl_Widget.redraw"><TT>Fl_Widget::redraw()</TT>
-</A> if the widget needs to be redisplayed. </LI>
-<LI>Call <A href="Fl_Widget.html#Fl_Widget.damage"><TT>
-Fl_Widget::damage(n)</TT></A> if  the widget needs a partial-update
-(assuming you provide  support for this in your <A href="#draw"><TT>Fl_Widget::draw()</TT></A>
- method). </LI>
-<LI>Call <A href="Fl_Widget.html#Fl_Widget.do_callback"><TT>
-Fl_Widget::do_callback()</TT></A> if a callback should be generated. </LI>
-<LI>Call <TT>Fl_Widget::handle()</TT> on child widgets. </LI>
-</UL>
- Events are identified by the integer argument.  Other information
+
+\li Change the state of the widget. 
+\li Call
+    <A href="Fl_Widget.html#Fl_Widget.redraw"><tt>Fl_Widget::redraw()</tt></A>
+    if the widget needs to be redisplayed. 
+\li Call
+    <A href="Fl_Widget.html#Fl_Widget.damage"><tt>Fl_Widget::damage(n)</tt></A>
+    if  the widget needs a partial-update (assuming you provide support for
+    this in your
+    <A href="#draw"><tt>Fl_Widget::draw()</tt></A>
+    method). 
+\li Call
+    <A href="Fl_Widget.html#Fl_Widget.do_callback"><tt>Fl_Widget::do_callback()</tt></A>
+    if a callback should be generated. 
+\li Call <tt>Fl_Widget::handle()</tt> on child widgets. 
+
+Events are identified by the integer argument.  Other information
 about the most recent event is stored in static locations and aquired
-by calling the <A href="events.html#events"><TT>Fl::event_*()</TT></A>
- functions. This information remains valid until another event is
+by calling the
+<A href="events.html#events"><tt>Fl::event_*()</tt></A>
+functions. This information remains valid until another event is
 handled.
-<P>Here is a sample <TT>handle()</TT> method for a widget that acts as
-a pushbutton and also accepts the keystroke 'x' to cause the callback: </P>
+
+Here is a sample <tt>handle()</tt> method for a widget that acts as
+a pushbutton and also accepts the keystroke 'x' to cause the callback: 
+
 \code
 int MyClass::handle(int event) {
   switch(event) {
@@ -228,52 +300,62 @@ int MyClass::handle(int event) {
 }
 \endcode
 
-<P>You must return non-zero if your <TT>handle()</TT> method
+You must return non-zero if your <tt>handle()</tt> method
 uses the event. If you return zero, the parent widget will try
 sending the event to another widget.
 
-<H2><A NAME="draw">Drawing the Widget</A></H2>
+<A NAME="draw"></A> <!-- For old HTML links only ! -->
+\section subclassing_drawing Drawing the Widget
 
-<P>The <TT>draw()</TT> virtual method is called when FLTK wants
+The <tt>draw()</tt> virtual method is called when FLTK wants
 you to redraw your widget. It will be called if and only if
-<TT>damage()</TT> is non-zero, and <TT>damage()</TT> will be
-cleared to zero after it returns. The <TT>draw()</TT> method
+<tt>damage()</tt> is non-zero, and <tt>damage()</tt> will be
+cleared to zero after it returns. The <tt>draw()</tt> method
 should be declared protected so that it can't be called from
 non-drawing code.
 
-<P>The <TT>damage()</TT> value contains the bitwise-OR of all
-the <TT>damage(n)</TT> calls to this widget since it was last
+The <tt>damage()</tt> value contains the bitwise-OR of all
+the <tt>damage(n)</tt> calls to this widget since it was last
 drawn. This can be used for minimal update, by only redrawing
 the parts whose bits are set. FLTK will turn on the
-<TT>FL_DAMAGE_ALL</TT> bit if it thinks the entire widget must
-be redrawn, e.g. for an expose event. </P>
+<tt>FL_DAMAGE_ALL</tt> bit if it thinks the entire widget must
+be redrawn, e.g. for an expose event. 
 
-<P>Expose events (and the above <TT>damage(b,x,y,w,h)</TT>) will cause <TT>
-draw()</TT> to be called with FLTK's <A href="drawing.html#clipping">
+Expose events (and the above <tt>damage(b,x,y,w,h)</tt>) will cause <tt>
+draw()</tt> to be called with FLTK's <A href="drawing.html#clipping">
 clipping</A> turned on.  You can greatly speed up redrawing in some
-cases by testing <TT>fl_not_clipped(x,y,w,h)</TT> or <TT>fl_clip_box(...)</TT> and
-skipping invisible parts. </P>
-<P>Besides the protected methods described above, FLTK provides a large
-number of basic drawing functions, which are described <A href="drawing.html#drawing">
-below</A>. </P>
-<H2>Resizing the Widget</H2>
- The <TT>resize(int x, int y, int w, int h)</TT> method is called when
+cases by testing <tt>fl_not_clipped(x,y,w,h)</tt> or <tt>fl_clip_box(...)</tt>
+and skipping invisible parts. 
+
+Besides the protected methods described above, FLTK provides a large
+number of basic drawing functions, which are described
+<A href="drawing.html#drawing">below</A>. 
+
+\section subclassing_resizing Resizing the Widget
+
+The <tt>resize(int x, int y, int w, int h)</tt> method is called when
 the widget is being resized or moved.  The arguments are the new
-position, width, and height. <TT>x()</TT>, <TT>y()</TT>, <TT>w()</TT>,
-and <TT>h()</TT> still remain the old size.  You must call <TT>resize()</TT>
- on your base class with the same arguments to get the widget size to
+position, width, and height. <tt>x()</tt>, <tt>y()</tt>, <tt>w()</tt>,
+and <tt>h()</tt> still remain the old size.  You must call <tt>resize()</tt>
+on your base class with the same arguments to get the widget size to
 actually change.
-<P>This should <I>not</I> call <TT>redraw()</TT>, at least if only the <TT>
-x()</TT> and <TT>y()</TT> change.  This is because composite widgets like <A href="Fl_Scroll.html#Fl_Scroll">
-<TT>Fl_Scroll</TT></A> may have a more efficient way of drawing the new
-position. </P>
-<H2>Making a Composite Widget</H2>
- A &quot;composite&quot; widget contains one or more &quot;child&quot; widgets.
- To make a composite widget you should subclass <A href="Fl_Group.html#Fl_Group"><TT>Fl_Group</TT></A>
-. It is possible to make a composite object that is not a subclass of <TT>
-Fl_Group</TT>, but you'll have to duplicate the code in <TT>Fl_Group</TT>
- anyways.
-<P>Instances of the child widgets may be included in the parent: </P>
+
+This should <I>not</I> call <tt>redraw()</tt>, at least if only the <tt>
+x()</tt> and <tt>y()</tt> change.  This is because composite widgets like
+<A href="Fl_Scroll.html#Fl_Scroll"><tt>Fl_Scroll</tt></A>
+may have a more efficient way of drawing the new position. 
+
+\section subclassing_composite Making a Composite Widget
+
+A &quot;composite&quot; widget contains one or more &quot;child&quot; widgets.
+To make a composite widget you should subclass
+<A href="Fl_Group.html#Fl_Group"><tt>Fl_Group</tt></A>.
+It is possible to make a composite object that is not a subclass of
+<tt>Fl_Group</tt>, but you'll have to duplicate the code in <tt>Fl_Group</tt>
+anyways.
+
+Instances of the child widgets may be included in the parent: 
+
 \code
 class MyClass : public Fl_Group {
   Fl_Button the_button;
@@ -281,9 +363,12 @@ class MyClass : public Fl_Group {
   ...
 };
 \endcode
- The constructor has to initialize these instances. They are automatically 
- <TT>add()</TT>ed to the group, since the Fl_Group constructor does Fl_Group::begin().
- <I>Don't forget to call Fl_Group::end() or use the Fl_End pseudo-class:</I>
+
+The constructor has to initialize these instances. They are automatically 
+<tt>add()</tt>ed to the group, since the Fl_Group constructor does
+Fl_Group::begin().
+<I>Don't forget to call Fl_Group::end() or use the Fl_End pseudo-class:</I>
+
 \code
 MyClass::MyClass(int x, int y, int w, int h) :
   Fl_Group(x, y, w, h),
@@ -294,10 +379,12 @@ MyClass::MyClass(int x, int y, int w, int h) :
   end(); // don't forget to do this!
 }
 \endcode
- The child widgets need callbacks.  These will be called with a pointer
-to the children, but the widget itself may be found in the <TT>parent()</TT>
- pointer of the child.  Usually these callbacks can be static private
+
+The child widgets need callbacks.  These will be called with a pointer
+to the children, but the widget itself may be found in the <tt>parent()</tt>
+pointer of the child.  Usually these callbacks can be static private
 methods, with a matching private method:
+
 \code
 void MyClass::static_slider_cb(Fl_Widget* v, void *) { // static method
   ((MyClass*)(v-&gt;parent())-&gt;slider_cb();
@@ -306,10 +393,12 @@ void MyClass::slider_cb() { // normal method
   use(the_slider-&gt;value());
 }
 \endcode
- If you make the <TT>handle()</TT> method, you can quickly pass all the
-events to the children using the <TT>Fl_Group::handle()</TT> method.
-You don't need to override <TT>handle()</TT> if your composite widget
+
+If you make the <tt>handle()</tt> method, you can quickly pass all the
+events to the children using the <tt>Fl_Group::handle()</tt> method.
+You don't need to override <tt>handle()</tt> if your composite widget
 does nothing other than pass events to the children:
+
 \code
 int MyClass::handle(int event) {
   if (Fl_Group::handle(event)) return 1;
@@ -317,10 +406,10 @@ int MyClass::handle(int event) {
 }
 \endcode
 
-<P>If you override <TT>draw()</TT> you need to draw all the
-children. If <TT>redraw()</TT> or <TT>damage()</TT> is called
-on a child, <TT>damage(FL_DAMAGE_CHILD)</TT> is done to the
-group, so this bit of <TT>damage()</TT> can be used to indicate
+If you override <tt>draw()</tt> you need to draw all the
+children. If <tt>redraw()</tt> or <tt>damage()</tt> is called
+on a child, <tt>damage(FL_DAMAGE_CHILD)</tt> is done to the
+group, so this bit of <tt>damage()</tt> can be used to indicate
 that a child needs to be drawn. It is fastest if you avoid
 drawing anything else in this case:
 
@@ -339,93 +428,99 @@ int MyClass::draw() {
   }
 }
 \endcode
-<TT>Fl_Group</TT> provides some protected methods to make drawing
+
+<tt>Fl_Group</tt> provides some protected methods to make drawing
 easier:
-<UL>
-<LI><A href="#draw_child">draw_child</A></LI>
-<LI><A href="#draw_outside_label">draw_outside_label</A></LI>
-<LI><A href="#update_child">update_child</A></LI>
-</UL>
-<H4><A name="draw_child">void Fl_Group::draw_child(Fl_Widget&amp;)</A></H4>
- This will force the child's <TT>damage()</TT> bits all to one and call <TT>
-draw()</TT> on it, then clear the <TT>damage()</TT>.  You should call
+
+\li <A href="#draw_child">draw_child</A>
+\li <A href="#draw_outside_label">draw_outside_label</A>
+\li <A href="#update_child">update_child</A>
+
+<A name="draw_child"></A> <!-- For old HTML links only ! -->
+void Fl_Group::draw_child(Fl_Widget&)
+
+\par
+This will force the child's <tt>damage()</tt> bits all to one and call <tt>
+draw()</tt> on it, then clear the <tt>damage()</tt>.  You should call
 this on all children if a total redraw of your widget is requested, or
 if you draw something (like a background box) that damages the child.
- Nothing is done if the child is not <TT>visible()</TT> or if it is
+Nothing is done if the child is not <tt>visible()</tt> or if it is
 clipped.
-<H4><A name="draw_outside_label">void
-Fl_Group::draw_outside_label(Fl_Widget&amp;) const</A></H4>
- Draw the labels that are <I>not</I> drawn by <A href="#draw_label"><TT>
-draw_label()</TT></A>.  If you want more control over the label
-positions you might want to call <TT>child-&gt;draw_label(x,y,w,h,a)</TT>.
-<H4><A name="update_child">void Fl_Group::update_child(Fl_Widget&amp;)</A></H4>
- Draws the child only if its <TT>damage()</TT> is non-zero.  You
+
+<A name="draw_outside_label"></A> <!-- For old HTML links only ! -->
+void Fl_Group::draw_outside_label(Fl_Widget&) const
+
+\par
+Draw the labels that are <I>not</I> drawn by <A href="#draw_label"><tt>
+draw_label()</tt></A>.  If you want more control over the label
+positions you might want to call <tt>child-&gt;draw_label(x,y,w,h,a)</tt>.
+
+<A name="update_child"></A> <!-- For old HTML links only ! -->
+void Fl_Group::update_child(Fl_Widget&)
+
+\par
+Draws the child only if its <tt>damage()</tt> is non-zero.  You
 should call this on all the children if your own damage is equal to
-FL_DAMAGE_CHILD.  Nothing is done if the child is not <TT>visible()</TT>
- or if it is clipped.
+FL_DAMAGE_CHILD.  Nothing is done if the child is not <tt>visible()</tt>
+or if it is clipped.
+
+\section subclassing_cutnpaste Cut and Paste Support
 
-<H2>Cut and Paste Support</H2>
 FLTK provides routines to cut and paste 8-bit text (in the future this
 may be UTF-8) between applications:
-<UL>
-<LI><A href="Fl.html#Fl.paste"><TT>Fl::paste</TT></A></LI>
-<LI><A href="Fl.html#Fl.selection"><TT>Fl::selection</TT></A></LI>
-<LI><A href="Fl.html#Fl.selection_owner"><TT>Fl::selection_owner</TT></A></LI>
-</UL>
-It may be possible to cut/paste non-text data by using <A href="osissues.html#add_handler">
-<TT>Fl::add_handler()</TT></A>.
 
-<H2>Drag And Drop Support</H2>
+\li <A href="Fl.html#Fl.paste"><tt>Fl::paste</tt></A>
+\li <A href="Fl.html#Fl.selection"><tt>Fl::selection</tt></A>
+\li <A href="Fl.html#Fl.selection_owner"><tt>Fl::selection_owner</tt></A>
+
+It may be possible to cut/paste non-text data by using
+<A href="osissues.html#add_handler"><tt>Fl::add_handler()</tt></A>.
+
+\section subclassing_dragndrop Drag And Drop Support
 
 FLTK provides routines to drag and drop 8-bit text between applications:
 
-<P>Drag'n'drop operations are are initiated by copying data to the 
+Drag'n'drop operations are are initiated by copying data to the 
 clipboard and calling the function
-<A href="Fl.html#Fl.dnd"><TT>Fl::dnd()</TT></A>.
-
-<P>Drop attempts are handled via <A href="events.html#dnd">events</A>:
-<UL>
-<LI><TT>FL_DND_ENTER</TT></LI>
-<LI><TT>FL_DND_DRAG</TT></LI>
-<LI><TT>FL_DND_LEAVE</TT></LI>
-<LI><TT>FL_DND_RELEASE</TT></LI>
-<LI><TT>FL_PASTE</TT></LI>
-</UL>
-
-<H2>Making a subclass of Fl_Window</H2>
-
-<P>You may want your widget to be a subclass of
-<TT>Fl_Window</TT>, <TT>Fl_Double_Window</TT>, or
-<TT>FL_Gl_Window</TT>. This can be useful if your widget wants
+<A href="Fl.html#Fl.dnd"><tt>Fl::dnd()</tt></A>.
+
+Drop attempts are handled via <A href="events.html#dnd">events</A>:
+
+\li <tt>FL_DND_ENTER</tt>
+\li <tt>FL_DND_DRAG</tt>
+\li <tt>FL_DND_LEAVE</tt>
+\li <tt>FL_DND_RELEASE</tt>
+\li <tt>FL_PASTE</tt>
+
+\section subclassing_fl_window Making a subclass of Fl_Window
+
+You may want your widget to be a subclass of
+<tt>Fl_Window</tt>, <tt>Fl_Double_Window</tt>, or
+<tt>FL_Gl_Window</tt>. This can be useful if your widget wants
 to occupy an entire window, and can also be used to take
 advantage of system-provided clipping, or to work with a library
 that expects a system window ID to indicate where to draw.
 
-<P>Subclassing <TT>Fl_Window</TT>is almost exactly like
-subclassing <TT>Fl_Group</TT>, and in fact you can easily
+Subclassing <tt>Fl_Window</tt>is almost exactly like
+subclassing <tt>Fl_Group</tt>, and in fact you can easily
 switch a subclass back and forth. Watch out for the following
-differences: </P>
-
-<OL>
-
-	<LI><TT>Fl_Window</TT> is a subclass of
-	<TT>Fl_Group</TT> so <I>make sure your constructor calls
-	<TT>end()</TT></I> unless you actually want children
-	added to your window.</LI>
+differences: 
 
-	<LI>When handling events and drawing, the upper-left
-	corner is at 0,0, not <TT>x(),y()</TT> as in other
-	<TT>Fl_Widget</TT>'s. For instance, to draw a box
-	around the widget, call <TT>draw_box(0, 0, w(),
-	h())</TT>, rather than <TT>draw_box(x(), y(), w(),
-	h())</TT>.</LI>
+-# <tt>Fl_Window</tt> is a subclass of <tt>Fl_Group</tt> so
+   <I>make sure your constructor calls <tt>end()</tt></I>
+   unless you actually want children added to your window.
 
-</OL>
+-# When handling events and drawing, the upper-left corner is at
+   0,0, not <tt>x(),y()</tt> as in other <tt>Fl_Widget</tt>'s.
+   For instance, to draw a box around the widget, call
+   <tt>draw_box(0, 0, w(), h())</tt>, rather than
+   <tt>draw_box(x(), y(), w(), h())</tt>.
 
-<P>You may also want to subclass <TT>Fl_Window</TT> in order to
+You may also want to subclass <tt>Fl_Window</tt> in order to
 get access to different visuals or to change other attributes of
-the windows. See <A href="osissues.html">"Appendix F - Operating
-System Issues"</A> for more information.
+the windows. See
+<A href="osissues.html">"Appendix F - Operating System Issues"</A>
+for more information.
 
 <hr>
 <a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;