Doxygen documentation - WP12 and WP13 - first step.

Converted the descriptive chapters of the html docs to doxygen format
and modified index.dox accordingly.

This checkin includes only trivial reformatting, no major rewriting.

Added a chapter "Migrating Code from FLTK 1.1 to 1.3".

All links on the main page are working now.

Todo:
  - Check doxygen error messages, rewrite pages (html tags, contents).
  - Fill the new "Migrating..." chapter.


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

1 files changed, 431 insertions, 0 deletions

diff --git a/documentation/subclassing.dox b/documentation/subclassing.dox
new file mode 100644
index 000000000..cb4763be2
--- /dev/null
+++ b/documentation/subclassing.dox
@@ -0,0 +1,431 @@
+/**
+
+ \page	subclassing	7 - Adding and Extending Widgets
+
+<P>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
+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
+look or user-interface. For example, the button widgets are all
+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
+virtual methods, and overriding some or all of these may be necessary.
+<H2>The Constructor</H2>
+ The constructor should have the following arguments:
+<UL><PRE>
+MyClass(int x, int y, int w, int h, const char *label = 0);
+</PRE></UL>
+ 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>
+<UL><PRE>
+MyClass::MyClass(int x, int y, int w, int h, const char *label)
+: Fl_Widget(x, y, w, h, label) {
+// do initialization stuff...
+}
+</PRE></UL>
+<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:
+<UL><PRE>
+type(0);
+box(FL_NO_BOX);
+color(FL_BACKGROUND_COLOR);
+selection_color(FL_BACKGROUND_COLOR);
+labeltype(FL_NORMAL_LABEL);
+labelstyle(FL_NORMAL_STYLE);
+labelsize(FL_NORMAL_SIZE);
+labelcolor(FL_FOREGROUND_COLOR);
+align(FL_ALIGN_CENTER);
+callback(default_callback,0);
+flags(ACTIVE|VISIBLE);
+image(0);
+deimage(0);
+</PRE></UL>
+<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>
+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
+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
+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:
+<UL><PRE>
+MyClass::handle(int event) {
+  ...
+  if (change_to_part1) damage(1);
+  if (change_to_part2) damage(2);
+  if (change_to_part3) damage(4);
+}
+
+MyClass::draw() {
+  if (damage() &amp; FL_DAMAGE_ALL) {
+    ... draw frame/box and other static stuff ...
+  }
+
+  if (damage() &amp; (FL_DAMAGE_ALL | 1)) draw_part1();
+  if (damage() &amp; (FL_DAMAGE_ALL | 2)) draw_part2();
+  if (damage() &amp; (FL_DAMAGE_ALL | 4)) draw_part3();
+}
+</PRE></UL>
+<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>
+
+<P>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
+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
+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
+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
+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
+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
+'&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
+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
+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
+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
+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
+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>
+<UL><PRE>
+int MyClass::handle(int event) {
+  switch(event) {
+    case FL_PUSH:
+      highlight = 1;
+      redraw();
+      return 1;
+    case FL_DRAG: {
+        int t = Fl::event_inside(this);
+        if (t != highlight) {
+          highlight = t;
+	  redraw();
+	}
+      }
+      return 1;
+    case FL_RELEASE:
+      if (highlight) {
+	highlight = 0;
+	redraw();
+        do_callback();
+	// never do anything after a callback, as the callback
+	// may delete the widget!
+      }
+      return 1;
+    case FL_SHORTCUT:
+      if (Fl::event_key() == 'x') {
+        do_callback();
+	return 1;
+      }
+      return 0;
+    default:
+      return Fl_Widget::handle(event);
+  }
+}
+</PRE></UL>
+
+<P>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>
+
+<P>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
+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
+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>
+
+<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>
+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
+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
+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>
+<UL><PRE>
+class MyClass : public Fl_Group {
+  Fl_Button the_button;
+  Fl_Slider the_slider;
+  ...
+};
+</PRE></UL>
+ The constructor has to initialize these instances.  They are
+automatically <TT>add()</TT>ed to the group, since the <TT>Fl_Group</TT>
+ constructor does <TT>begin()</TT>. <I>Don't forget to call <TT>end()</TT>
+ or use the <A href=Fl_End.html#Fl_End><TT>Fl_End</TT></A> pseudo-class:</I>
+<UL><PRE>
+MyClass::MyClass(int x, int y, int w, int h) :
+  Fl_Group(x, y, w, h),
+  the_button(x + 5, y + 5, 100, 20),
+  the_slider(x, y + 50, w, 20)
+{
+  ...(you could add dynamically created child widgets here)...
+  end(); // don't forget to do this!
+}
+</PRE></UL>
+ 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:
+<UL><PRE>
+void MyClass::static_slider_cb(Fl_Widget* v, void *) { // static method
+  ((MyClass*)(v-&gt;parent())-&gt;slider_cb();
+}
+void MyClass::slider_cb() { // normal method
+  use(the_slider-&gt;value());
+}
+</PRE></UL>
+ 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:
+<UL><PRE>
+int MyClass::handle(int event) {
+  if (Fl_Group::handle(event)) return 1;
+  ... handle events that children don't want ...
+}
+</PRE></UL>
+
+<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
+that a child needs to be drawn. It is fastest if you avoid
+drawing anything else in this case:
+
+<UL><PRE>
+int MyClass::draw() {
+  Fl_Widget *const*a = array();
+  if (damage() == FL_DAMAGE_CHILD) { // only redraw some children
+    for (int i = children(); i --; a ++) update_child(**a);
+  } else { // total redraw
+    ... draw background graphics ...
+    // now draw all the children atop the background:
+    for (int i = children_; i --; a ++) {
+      draw_child(**a);
+      draw_outside_label(**a); // you may not need to do this
+    }
+  }
+}
+</PRE></UL>
+<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
+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
+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
+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.
+
+<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>
+
+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 
+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
+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
+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>
+
+	<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>
+
+</OL>
+
+<P>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.
+
+*/