Updated documentation with changes from Bill.

Added new image files for buttons.


git-svn-id: file:///fltk/svn/fltk/trunk@237 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

16 files changed, 320 insertions, 105 deletions

diff --git a/documentation/Fl_Adjuster.html b/documentation/Fl_Adjuster.html
index bb51e26c1..e3336f8c5 100644
--- a/documentation/Fl_Adjuster.html
+++ b/documentation/Fl_Adjuster.html
@@ -17,14 +17,15 @@
 </PRE>
 </UL>
 <H3>Description</H3>
- The <TT>Fl_Adjuster</TT> widget was stolen from Prisms, and has proven 
-to be very useful for values that need a large dynamic range.  When you 
-press a button and drag to the right the value increases. When you drag 
-to the left it decreases.  The largest button adjusts by <TT>100 * 
-step()</TT>, the next by <TT>10 * step()</TT> and that smallest button 
-by <TT>step()</TT>.  Clicking on the buttons increments by 10 times the 
-amount dragging by a pixel does. Shift + click decrements by 10 times 
-the amount. 
+The <TT>Fl_Adjuster</TT> widget was stolen from Prisms, and has proven 
+to be very useful for values that need a large dynamic range.
+<P ALIGN=CENTER><IMG SRC="adjuster1.gif"></P>
+<P>When you  press a button and drag to the right the value increases.
+When you drag  to the left it decreases.  The largest button adjusts by
+<TT>100 *  step()</TT>, the next by <TT>10 * step()</TT> and that
+smallest button  by <TT>step()</TT>.  Clicking on the buttons
+increments by 10 times the  amount dragging by a pixel does. Shift +
+click decrements by 10 times  the amount. 
 <H3>Methods</H3>
 <UL>
 <LI><A href=#Fl_Adjuster.Fl_Adjuster>Fl_Adjuster</A></LI>
@@ -44,4 +45,5 @@ times the other.
  If &quot;soft&quot; is turned on, the user is allowed to drag the value outside 
 the range.  If they drag the value to one of the ends, let go, then 
 grab again and continue to drag, they can get to any value.  Default is 
-one. </BODY></HTML>
\ No newline at end of file
+one.
+</BODY></HTML>
diff --git a/documentation/Fl_Check_Button.html b/documentation/Fl_Check_Button.html
index 9b013ea2a..475a8c9f6 100644
--- a/documentation/Fl_Check_Button.html
+++ b/documentation/Fl_Check_Button.html
@@ -17,9 +17,10 @@
 </PRE>
 </UL>
 <H3>Description</H3>
- Buttons generate callbacks when they are clicked by the user.  You 
+Buttons generate callbacks when they are clicked by the user.  You 
 control exactly when and how by changing the values for <TT>type()</TT>
- and <TT>when()</TT>. 
+and <TT>when()</TT>.
+<P ALIGN=CENTER><IMG SRC="Fl_Check_Button.gif"></P>
 <P>The <TT>Fl_Check_Button</TT> subclass display the &quot;on&quot; state by 
 turning on a light, rather than drawing pushed in.  The shape of the 
 &quot;light&quot; is initially set to FL_DIAMOND_DOWN_BOX.  The color of the 
@@ -37,4 +38,4 @@ Fl_Check_Button::Fl_Check_Button(int x, int y, int w, int h, const char
 position, size, and label string. 
 <H4><A name=Fl_Check_Button.~Fl_Check_Button>
 Fl_Check_Button::~Fl_Check_Button()</A></H4>
- The destructor deletes the check button. </BODY></HTML>
\ No newline at end of file
+ The destructor deletes the check button. </BODY></HTML>
diff --git a/documentation/Fl_Input.html b/documentation/Fl_Input.html
index 8e4317022..0c65dc962 100644
--- a/documentation/Fl_Input.html
+++ b/documentation/Fl_Input.html
@@ -58,7 +58,7 @@ only, otherwise it moves to the next input field).</TD></TR>
 otherwise it moves to the previous input field).</TD></TR>
 <TR><TD><B>^Q or
 <BR>RightCtrl or
-<BR>Compose</B></TD><TD>Start a <A href=compose.html>compose-character</A>
+<BR>Compose</B></TD><TD>Start a <A href="events.html#compose">compose-character</A>
  sequence.  The next one or two keys typed define the character to 
 insert.  This also can be used to &quot;quote&quot; control characters.</TD></TR>
 <TR><TD><B>^U</B></TD><TD>Delete everything.</TD></TR>
@@ -176,4 +176,6 @@ fields. </LI>
 <H4><A name=Fl_Input.cursor_color>Fl_Color Fl_Input::cursor_color() 
 const
 <BR> void Fl_Input::cursor_color(Fl_Color)</A></H4>
- Get or set the color of the cursor.  This is black by default. </BODY></HTML>
+ Get or set the color of the cursor.  This is black by default.
+
+</BODY></HTML>
diff --git a/documentation/Fl_Int_Input.html b/documentation/Fl_Int_Input.html
index 78382ebc2..9cdfaa650 100644
--- a/documentation/Fl_Int_Input.html
+++ b/documentation/Fl_Int_Input.html
@@ -5,7 +5,7 @@
 <H3>Class Hierarchy</H3>
 <UL>
 <PRE>
-<A href=functions.html#Fl_Input>Fl_Input</A>
+<A href=Fl_Input.html#Fl_Input>Fl_Input</A>
    |
    +----<B>Fl_Int_Input</B>
 </PRE>
@@ -31,4 +31,4 @@ int y, int w, int h, const char *label = 0)</A></H4>
 size, and label string. The default boxtype is <TT>FL_DOWN_BOX</TT>. 
 <H4><A name=Fl_Int_Input.~Fl_Int_Input>virtual 
 Fl_Int_Input::~Fl_Int_Input()</A></H4>
- Destroys the widget and any value associated with it. </BODY></HTML>
\ No newline at end of file
+ Destroys the widget and any value associated with it. </BODY></HTML>
diff --git a/documentation/Fl_Light_Button.html b/documentation/Fl_Light_Button.html
index 658e24b1a..fc8820c5f 100644
--- a/documentation/Fl_Light_Button.html
+++ b/documentation/Fl_Light_Button.html
@@ -17,9 +17,10 @@
 </PRE>
 </UL>
 <H3>Description</H3>
- Buttons generate callbacks when they are clicked by the user.  You 
+Buttons generate callbacks when they are clicked by the user.  You 
 control exactly when and how by changing the values for <TT>type()</TT>
- and <TT>when()</TT>. 
+and <TT>when()</TT>. 
+<P ALIGN=CENTER><IMG SRC="Fl_Light_Button.gif"></P>
 <P>The <TT>Fl_Light_Button</TT> subclass display the &quot;on&quot; state by 
 turning on a light, rather than drawing pushed in.  The shape of the 
 &quot;light&quot; is initially set to FL_DOWN_BOX.  The color of the light when 
@@ -37,4 +38,4 @@ Fl_Light_Button::Fl_Light_Button(int x, int y, int w, int h, const char
 position, size, and label string. 
 <H4><A name=Fl_Light_Button.~Fl_Light_Button>
 Fl_Light_Button::~Fl_Light_Button()</A></H4>
- The destructor deletes the check button. </BODY></HTML>
\ No newline at end of file
+ The destructor deletes the check button. </BODY></HTML>
diff --git a/documentation/Fl_Return_Button.html b/documentation/Fl_Return_Button.html
index a6a740ea9..7d5653480 100644
--- a/documentation/Fl_Return_Button.html
+++ b/documentation/Fl_Return_Button.html
@@ -14,9 +14,10 @@
 <PRE>#include &lt;FL/Fl_Return_Button.H&gt;</PRE>
 </UL>
 <H3>Description</H3>
- The <TT>Fl_Return_Button</TT> is a subclass of <TT>Fl_Button</TT> that 
+The <TT>Fl_Return_Button</TT> is a subclass of <TT>Fl_Button</TT> that 
 generates a callback when it is pressed or when the user presses the 
 Enter key.  A carriage-return symbol is drawn next to the button label. 
+<P ALIGN=CENTER><IMG SRC="Fl_Return_Button.gif"></P>
 <H3>Methods</H3>
 <UL>
 <LI><A href=#Fl_Return_Button.Fl_Return_Button>Fl_Return_Button</A></LI>
@@ -30,4 +31,4 @@ position, size, and label string. The default boxtype is <TT>FL_UP_BOX</TT>
 . 
 <H4><A name=Fl_Return_Button.~Fl_Return_Button>virtual 
 Fl_Return_Button::~Fl_Return_Button()</A></H4>
- Deletes the button. </BODY></HTML>
\ No newline at end of file
+ Deletes the button. </BODY></HTML>
diff --git a/documentation/Fl_Round_Button.html b/documentation/Fl_Round_Button.html
index 2c7ea9d3a..a103d9f7c 100644
--- a/documentation/Fl_Round_Button.html
+++ b/documentation/Fl_Round_Button.html
@@ -17,9 +17,10 @@
 </PRE>
 </UL>
 <H3>Description</H3>
- Buttons generate callbacks when they are clicked by the user.  You 
+Buttons generate callbacks when they are clicked by the user.  You 
 control exactly when and how by changing the values for <TT>type()</TT>
- and <TT>when()</TT>. 
+and <TT>when()</TT>. 
+<P ALIGN=CENTER><IMG SRC="Fl_Round_Button.gif"></P>
 <P>The <TT>Fl_Round_Button</TT> subclass display the &quot;on&quot; state by 
 turning on a light, rather than drawing pushed in.  The shape of the 
 &quot;light&quot; is initially set to FL_ROUND_DOWN_BOX.  The color of the light 
@@ -37,4 +38,4 @@ Fl_Round_Button::Fl_Round_Button(int x, int y, int w, int h, const char
 position, size, and label string. 
 <H4><A name=Fl_Round_Button.~Fl_Round_Button>
 Fl_Round_Button::~Fl_Round_Button()</A></H4>
- The destructor deletes the check button. </BODY></HTML>
\ No newline at end of file
+ The destructor deletes the check button. </BODY></HTML>
diff --git a/documentation/Fl_Value_Input.html b/documentation/Fl_Value_Input.html
index 9dfd5d9df..00b24c7f6 100644
--- a/documentation/Fl_Value_Input.html
+++ b/documentation/Fl_Value_Input.html
@@ -19,7 +19,7 @@
 <H3>Description</H3>
  The <TT>Fl_Value_Input</TT> widget displays a floating point value. 
 The user can click in the text field and edit it (there is in fact a 
-hidden <A href=#Fl_Value_Input><TT>Fl_Value_Input</TT></A> widget with <TT>
+hidden <A href=#Fl_Input><TT>Fl_Input</TT></A> widget with <TT>
 type(FL_FLOAT_INPUT)</TT> in there), and when they hit return or tab 
 the value updates to what they typed and the callback is done. 
 <P>If <TT>step()</TT> is not zero, the user can also drag the mouse 
@@ -68,4 +68,4 @@ const
 <H4><A name=Fl_Value_Input.textsize>uchar Fl_Value_Input::textsize() 
 const
 <BR> void Fl_Value_Input::textsize(uchar)</A></H4>
- Gets or sets the size of the text in the value box. </BODY></HTML>
\ No newline at end of file
+ Gets or sets the size of the text in the value box. </BODY></HTML>
diff --git a/documentation/Fl_Widget.html b/documentation/Fl_Widget.html
index 708b061a5..63c534fe6 100644
--- a/documentation/Fl_Widget.html
+++ b/documentation/Fl_Widget.html
@@ -21,7 +21,7 @@
 <H3>Description</H3>
 <TT>Fl_Widget</TT> is the base class for all widgets in FLTK. You can't 
 create one of these because the constructor is not public.  However you 
-can <A href=#subclassing">subclass</A> it. 
+can <A href="#subclassing">subclass</A> it. 
 <P>All &quot;property&quot; accessing methods, such as <TT>color()</TT>, <TT>
 parent()</TT>, or <TT>argument()</TT> are implemented as trivial inline 
 functions and thus are as fast and small as accessing fields in a 
@@ -38,14 +38,15 @@ to call <TT>redraw()</TT> after these. </P>
 <LI><A href=#Fl_Widget.~Fl_Widget>~Fl_Widget</A></LI>
 <LI><A href=#Fl_Widget.activate>activate</A></LI>
 <LI><A href=#Fl_Widget.active>active</A></LI>
+<LI><A href=#Fl_Widget.active_r>active_r</A></LI>
 <LI><A href=#Fl_Widget.activevisible>activevisible</A></LI>
 <LI><A href=#Fl_Widget.align>align</A></LI>
 <LI><A href=#Fl_Widget.argument>argument</A></LI>
 <LI><A href=#Fl_Widget.box>box</A></LI>
-<LI><A href=#Fl_Widget.callback>callback</A></LI>
 </UL>
 </TD><TD align=left valign=top>
 <UL>
+<LI><A href=#Fl_Widget.callback>callback</A></LI>
 <LI><A href=#Fl_Widget.changed>changed</A></LI>
 <LI><A href=#Fl_Widget.clear_changed>clear_changed</A></LI>
 <LI><A href=#Fl_Widget.color>color</A></LI>
@@ -54,10 +55,10 @@ to call <TT>redraw()</TT> after these. </P>
 <LI><A href=#Fl_Widget.deactivate>deactivate</A></LI>
 <LI><A href=#Fl_Widget.default_callback>default_callback</A></LI>
 <LI><A href=#Fl_Widget.do_callback>do_callback</A></LI>
-<LI><A href=#Fl_Widget.h>h</A></LI>
 </UL>
 </TD><TD align=left valign=top>
 <UL>
+<LI><A href=#Fl_Widget.h>h</A></LI>
 <LI><A href=#Fl_Widget.hide>hide</A></LI>
 <LI><A href=#Fl_Widget.inside>inside</A></LI>
 <LI><A href=#Fl_Widget.label>label</A></LI>
@@ -77,12 +78,13 @@ to call <TT>redraw()</TT> after these. </P>
 <LI><A href=#Fl_Widget.show>show</A></LI>
 <LI><A href=#Fl_Widget.size>size</A></LI>
 <LI><A href=#Fl_Widget.take_focus>take_focus</A></LI>
+<LI><A href=#Fl_Widget.type>type</A></LI>
 </UL>
 </TD><TD align=left valign=top>
 <UL>
-<LI><A href=#Fl_Widget.type>type</A></LI>
 <LI><A href=#Fl_Widget.user_data>user_data</A></LI>
 <LI><A href=#Fl_Widget.visible>visible</A></LI>
+<LI><A href=#Fl_Widget.visible_r>visible_r</A></LI>
 <LI><A href=#Fl_Widget.w>w</A></LI>
 <LI><A href=#Fl_Widget.when>when</A></LI>
 <LI><A href=#Fl_Widget.window>window</A></LI>
@@ -115,7 +117,7 @@ Fl_Widget::resize(int,int,int,int)</A>
 <BR><A name=Fl_Widget.position>void Fl_Widget::position(short x,short y)</A>
 <BR><A name=Fl_Widget.size>void Fl_Widget::size(short w,short h)</A></H4>
  Change the size or position of the widget.  This is a virtual function 
-so the widget may implement it's own handling of resizing.  The default 
+so the widget may implement its own handling of resizing.  The default 
 version does <I>not</I> do redraw(), that is the parent widget's 
 responsibility (this is because the parent may know a faster way to 
 update the display, such as scrolling from the old position). 
@@ -126,7 +128,7 @@ update the display, such as scrolling from the old position).
  Return a pointer to the <A href=Fl_Window.html#Fl_Window><TT>Fl_Window</TT>
 </A> that this widget is in (it will skip any and all parent widgets 
 between this and the window).  Returns <TT>NULL</TT> if none.  Note: 
-for an <TT>Fl_Window</TT>, this returns it's <I>parent</I> window (if 
+for an <TT>Fl_Window</TT>, this returns its <I>parent</I> window (if 
 any), not <I>this</I> window. 
 <H4><A name=Fl_Widget.box>Fl_Boxtype Fl_Widget::box() const
 <BR> void Fl_Widget::box(Fl_Boxtype)</A></H4>
@@ -241,27 +243,31 @@ Fl_Widget::default_callback(Fl_Widget*, void*)</A></H4>
  The default callback, which puts a pointer to the widget on the queue 
 returned by <A href=functions.html#readqueue><TT>Fl::readqueue()</TT></A>
 .  You may want to call this from your own callback. 
-<H4><A name=Fl_Widget.visible>int Fl_Widget::visible() const</A>
-<BR><A name=Fl_Widget.show>void Fl_Widget::show()</A>
-<BR><A name=Fl_Widget.hide>void Fl_Widget::hide()</A></H4>
- An invisible widget never gets redrawn and does not get events.  An 
-widget is really visible if <TT>visible()</TT> is true on it <I>and all 
-it's parents</I>.  Changing it will send <TT>FL_SHOW</TT> or <TT>FL_HIDE</TT>
- events to the widget. <I>Do not change it if the parent is not 
+<H4><A name=Fl_Widget.visible>int Fl_Widget::visible() const</A><BR>
+<A name=Fl_Widget.visible_r>int Fl_Widget::visible_r() const</A><BR>
+<A name=Fl_Widget.show>void Fl_Widget::show()</A><BR>
+<A name=Fl_Widget.hide>void Fl_Widget::hide()</A></H4>
+An invisible widget never gets redrawn and does not get events.  The
+<TT>visible()</TT> method returns true if the widget is set to be
+visible.The <TT>visible_r()</TT> method returns true if the widget and
+all of its parents are visible. A widget is only visible if
+<TT>visible()</TT> is true on it <I>and all of its parents</I>.  
+<P>Changing it will send <TT>FL_SHOW</TT> or <TT>FL_HIDE</TT>
+events to the widget. <I>Do not change it if the parent is not 
 visible, as this will send false <TT>FL_SHOW</TT> or <TT>FL_HIDE</TT>
  events to the widget</I>. <TT>redraw()</TT> is called if necessary on 
 this or the parent. 
-<H4><A name=Fl_Widget.active>int Fl_Widget::active() const</A>
-<BR><A name=Fl_Widget.activate>void Fl_Widget::activate()</A>
-<BR><A name=Fl_Widget.deactivate>void Fl_Widget::deactivate()</A>
-<BR></H4>
-<TT>Fl_Widget::active()</TT> returns whether the widget is active.  An 
-inactive widget does not get any events, but it does get redrawn.  A 
-widget is active if <TT>active()</TT> is true on it <I>and all it's 
-parents</I>. Changing this value will send <TT>FL_ACTIVATE</TT> or <TT>
-FL_DEACTIVATE</TT> to the widget. <I>Do not change it if the parent is 
-not active, as this will send false <TT>FL_ACTIVATE</TT> or <TT>
-FL_DEACTIVATE</TT> events to the widget</I>. 
+<H4><A name=Fl_Widget.active>int Fl_Widget::active() const</A><BR>
+<A name=Fl_Widget.active_r>int Fl_Widget::active_r() const</A></BR>
+<A name=Fl_Widget.activate>void Fl_Widget::activate()</A></BR>
+<A name=Fl_Widget.deactivate>void Fl_Widget::deactivate()</A></H4>
+<TT>Fl_Widget::active()</TT> returns whether the widget is active.
+<TT>Fl_Widget::active_r()</TT> returns whether the widget and all of
+its parents are active.  An inactive widget does not get any events,
+but it does get redrawn.  A widget is only active if <TT>active()</TT> is
+true on it <I>and all of its parents</I>.
+<P>Changing this value will send <TT>FL_ACTIVATE</TT> or <TT>
+FL_DEACTIVATE</TT> to the widget if <tt>active_r()</tt> is true.
 <P>Currently you cannot deactivate <TT>Fl_Window</TT> widgets. </P>
 <H4><A name=Fl_Widget.activevisible>int Fl_Widget::activevisible() const</A>
 </H4>
@@ -273,8 +279,10 @@ FL_DEACTIVATE</TT> events to the widget</I>.
 bit field that the widget subclass can use to figure out what parts to 
 draw. 
 <H4><A name=Fl_Widget.parent>Fl_Widget *Fl_Widget::parent() const</A></H4>
- Returns a pointer to the parent widget.  Usually this is a <A href=Fl_Group.html#Fl_Group>
-<TT>Fl_Group</TT></A> or <A Fl_Widget.contains" href="Fl_Window><tt>Fl_Window</tt></a>.  Returns <tt>NULL</tt> if none.
+Returns a pointer to the parent widget.  Usually this is a <A
+href=Fl_Group.html#Fl_Group> <TT>Fl_Group</TT></A> or <A
+HREF="Fl_Window.html#Fl_Window"><tt>Fl_Window</tt></a>.  Returns
+<tt>NULL</tt> if none.
 
 <h4><a name="Fl_Widget.contains">int Fl_Widget::contains(Fl_Widget* b) const</A></H4>
 Returns true if <TT>b</TT> is a child of this widget, or is equal to
diff --git a/documentation/Fl_Window.html b/documentation/Fl_Window.html
index bfd8a828a..f78fee9f3 100644
--- a/documentation/Fl_Window.html
+++ b/documentation/Fl_Window.html
@@ -81,23 +81,31 @@ exit(0)</TT> if this is the last top-level window. </P>
 </TD></TR>
 </TABLE>
 </CENTER>
-<H4><A name=Fl_Window.Fl_Window>Fl_Window::Fl_Window(int x, int y, int 
-w, int h, const char *title = 0)
-<BR> Fl_Window::Fl_Window(int w, int h, const char *title = 0)</A></H4>
- The first constructor takes 4 int arguments to create the window with 
-a preset position and size.  The second constructor with 2 arguments 
-will create the window with a preset size, but the window manager will 
-choose the position according to it's own whims. 
+<H4><A name=Fl_Window.Fl_Window>Fl_Window::Fl_Window(int w, int h, const char *title = 0)<BR>
+Fl_Window::Fl_Window(int x, int y, int w, int h, const char *title = 0)</A></H4>
+
+The first form of the constructor should be used for a "top-level" window
+(that is, one that is not inside another window).  It correctly sets
+<tt>visible()</tt> to false and <tt>parent()</tt> to <tt>NULL</tt>.
+By not specifying the position of the window, the window system will pick a
+place to show the window or allow the user to pick a location.  If you want to
+force a position you should call <tt>position(x,y)</tt> or <tt>hotspot()</tt>
+before calling <tt>show()</tt>.
+
+<P>The second form of the constructor is for creating child windows.  It
+leaves <tt>visible()</tt> set to true.
+
 <P><TT>Fl_Widget::box()</TT> is set to <TT>FL_FLAT_BOX</TT>.  If you 
 plan to completely fill the window with children widgets you should 
 change this to <TT>FL_NO_BOX</TT>. If you turn the window border off 
 you may want to change this to <TT>FL_UP_BOX</TT>. </P>
+
 <H4><A name=Fl_Window.~Fl_Window>virtual Fl_Window::~Fl_Window()</A></H4>
  The destructor <I>also deletes all the children</I>. This allows a 
 whole tree to be deleted at once, without having to keep a pointer to 
 all the children in the user code. A kludge has been done so the <TT>
 Fl_Window</TT> and all of it's children can be automatic (local) 
-variables, but you must declare the <TT>Fl_Window</TT><I>first</I>, so 
+variables, but you must declare the <TT>Fl_Window</TT> <I>first</I> so 
 that it is destroyed last. 
 <H4><A name=Fl_Window.size_range>void Fl_Window::size_range(int minw, 
 int minh, int maxw=0, int maxh=0, int dw=0, int dh=0, int aspect=0)</A></H4>
@@ -146,8 +154,7 @@ top.  This is really convenient because your program can call <TT>show()</TT>
 show()</TT> serves the purpose of <TT>raise()</TT> in other toolkits. </P>
 <H4><A name=Fl_Window.hide>virtual void Fl_Window::hide()</A></H4>
  Remove the window from the screen.  If the window is already hidden or 
-has not been shown then this does nothing (and is harmless). <I>Under 
-the X Window System this actually destroys the xid</I>. 
+has not been shown then this does nothing and is harmless.
 <H4><A name=Fl_Window.shown>int Fl_Window::shown() const</A></H4>
  Returns non-zero if <TT>show()</TT> has been called (but not <TT>hide()</TT>
 ). You can tell if a window is iconified with <TT>(w-&gt;shown() 
@@ -254,4 +261,4 @@ debug and maintain!</B>
 <P>This method only works for the <TT>Fl_Window</TT> and <TT>
 Fl_Gl_Window</TT> classes. </P>
 <H4><A name=Fl_Window.current>static Fl_Window* Fl_Window::current()</A></H4>
- Returns the last window that was made current. </BODY></HTML>
\ No newline at end of file
+ Returns the last window that was made current. </BODY></HTML>
diff --git a/documentation/basics.html b/documentation/basics.html
index 4de221c41..4b78f840b 100644
--- a/documentation/basics.html
+++ b/documentation/basics.html
@@ -121,7 +121,7 @@ program by closing the window or pressing the ESCape key.
 arguments to the constructors are usually one of the following: 
 <UL>
 <PRE>
-Fl_Widget(boxtype, x, y, width, height)
+Fl_Widget(boxtype, x, y, width, height, label)
 Fl_Widget(x, y, width, height)
 Fl_Widget(width, height)
 </PRE>
@@ -139,6 +139,11 @@ pixels. </P>
 <P>The <TT>width</TT> and <TT>height</TT> parameters determine the size 
 of the widget or window in pixels.  The maximum widget size is 
 typically governed by the underlying window system or hardware. </P>
+<p><tt>label</tt> is a pointer to a character string to label the
+widget with or <tt>NULL</tt>. If not specified the label defaults to
+<tt>NULL</tt>.  The label string must be in static storage (such as a
+string constant) because FLTK does not make a copy of it (it just uses
+the pointer).
 <H3>Labels</H3>
  All widgets support labels.  In the case of window widgets, the label 
 is used for the label in the title bar. Our example program calls the <A href=Fl_Widget.html#Fl_Widget.labelfont>
diff --git a/documentation/common.html b/documentation/common.html
index 97284b7d5..4fa974e75 100644
--- a/documentation/common.html
+++ b/documentation/common.html
@@ -60,6 +60,8 @@ Fl_Input *input = new Fl_Input(x, y, width, height, &quot;label&quot;);
 input-&gt;value(&quot;Now is the time for all good men...&quot;);
 </PRE>
 </UL>
+<p>The string is copied to the widget's own storage when you set the
+<tt>value()<tt> of the widget.
 <H2>Valuators</H2>
  Unlike text widgets, valuators keep track of numbers instead of 
 strings. FLTK provides the following valuators: 
@@ -75,7 +77,7 @@ strings. FLTK provides the following valuators:
  The <A href=Fl_Valuator.html#Fl_Valuator.value><TT>value()</TT></A>
  method gets and sets the current value of the widget.  The <A href=Fl_Valuator.html#Fl_Valuator.minimum>
 <TT>minimum()</TT></A> and <A href=Fl_Valuator.html#Fl_Valuator.maximum><TT>
-maximum</TT></A> methods set the range of values that are reported by 
+maximum()</TT></A> methods set the range of values that are reported by 
 the widget. 
 <H2>Groups</H2>
  The <TT>Fl_Group</TT> widget class is used as a general purpose 
@@ -92,9 +94,11 @@ any widgets together. </LI>
 <LI><TT>Fl_Window</TT> - A window on the screen. </LI>
 </UL>
 <H2>Setting the Size and Position of Widgets</H2>
- The size and position of widgets is usually set when you create them. 
- You can change this at any time using the <TT>position</TT>, <TT>
-resize()</TT>, and <TT>size</TT> methods: 
+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.
+<p>You can change the size and position by using the <TT>position()</TT>, <TT>
+resize()</TT>, and <TT>size()</TT> methods: 
 <UL>
 <PRE>
 button-&gt;position(x, y);
@@ -102,21 +106,23 @@ group-&gt;resize(x, y, width, height);
 window-&gt;size(width, height);
 </PRE>
 </UL>
- Changing the size or position of a widget will cause a redraw of that 
-widget and its children. 
+If you change a widget's size or position after it is displayed you
+will have to call <tt>redraw()</tt> on the widget's parent.
 <H2><A NAME=colors>Colors</A></H2>
- FLTK manages a virtual color palette of &quot;standard&quot; colors.  The 
-standard colors are: 
+FLTK stores the colors of widgets as an 8-bit number that is an index
+into a color palette of 256 colors. This is <i>not</i> the X or WIN32
+colormap, but instead is an internal table with fixed contents.
+<p>There are symbols for naming some of the more common colors:
 <UL>
-<LI><TT>FL_BLACK</TT></LI>
+<LI><TT>FL_BLACK</TT> (this is the default label color)</LI>
 <LI><TT>FL_RED</TT></LI>
 <LI><TT>FL_GREEN</TT></LI>
 <LI><TT>FL_YELLOW</TT></LI>
 <LI><TT>FL_BLUE</TT></LI>
 <LI><TT>FL_MAGENTA</TT></LI>
 <LI><TT>FL_CYAN</TT></LI>
-<LI><TT>FL_WHITE</TT></LI>
-<LI><TT>FL_GRAY</TT></LI>
+<LI><TT>FL_WHITE</TT> (this is the default background color of text widgets)</LI>
+<LI><TT>FL_GRAY</TT> (this is the default background color of most widgets)</LI>
 </UL>
  The widget color can be set using the <TT>color()</TT> method: 
 <UL>
@@ -135,7 +141,7 @@ button-&gt;labelcolor(FL_WHITE);
 <P>The type <TT>Fl_Boxtype</TT> stored and returned in <A href=Fl_Widget.html#Fl_Widget.box>
 <TT>Fl_Widget::box()</TT></A> is an enumeration defined in <A href=enumerations.html#enumerations>
 <TT>&lt;Enumerations.H&gt;</TT></A>: 
-<P ALIGN=CENTER><IMG src=./boxtypes.gif width=80%></P>
+<P ALIGN=CENTER><IMG src="boxtypes.gif"></P>
 <P><TT>FL_NO_BOX</TT> 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 center unchanged.  In the above diagram 
@@ -188,7 +194,7 @@ label. For the <TT>FL_SYMBOL_LABEL</TT> and image label types the
 string contains the actual symbol or image data. 
 <H3>align()</H3>
  The <TT>align()</TT> method positions the label.  The following 
-constants are defined: 
+constants are defined (they may be OR'd together as needed): 
 <UL>
 <LI><TT>FL_ALIGN_CENTER</TT> - center the label in the widget. </LI>
 <LI><TT>FL_ALIGN_TOP</TT> - align the label at the top of the widget. </LI>
@@ -322,7 +328,7 @@ button-&gt;when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED);
 </UL>
 <H2>Shortcuts</H2>
  Shortcuts are key sequences that activate widgets (usually buttons or 
-menu items).  The <TT>shortcut()</TT> method registers a shortcut for a 
+menu items).  The <TT>shortcut()</TT> method sets the shortcut for a 
 widget: 
 <UL>
 <PRE>
@@ -331,8 +337,11 @@ button-&gt;shortcut(FL_SHIFT + 'b');
 button-&gt;shortcut(FL_CTRL + 'b');
 button-&gt;shortcut(FL_ALT + 'b');
 button-&gt;shortcut(FL_CTRL + FL_ALT + 'b');
+button-&gt;shortcut(0); // no shortcut
 </PRE>
 </UL>
- The shortcut value is the key event value (the ASCII value or one of 
-the special keys like <TT>FL_Enter</TT>) combined with any modifiers 
-(like shift, alt, and control). </BODY></HTML>
+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 shift, alt, and control).
+</BODY></HTML>
diff --git a/documentation/enumerations.html b/documentation/enumerations.html
index 10283643b..2bb19ce69 100644
--- a/documentation/enumerations.html
+++ b/documentation/enumerations.html
@@ -56,7 +56,7 @@ is released and the value changes. </LI>
 <LI><TT>FL_WHEN_ENTER_KEY_ALWAYS</TT> - Do the callback when the user 
  presses the ENTER key, even if the value doesn't change. </LI>
 </UL>
-<H2>Fl::event_key() Values</H2>
+<H2><A NAME="key_values">Fl::event_key() Values</A></H2>
  The following constants define the non-ASCII keys on the keyboard for <TT>
 FL_KEYBOARD</TT> and <TT>FL_SHORTCUT</TT> events: 
 <UL>
diff --git a/documentation/events.html b/documentation/events.html
index 3b62864b5..8a5286d01 100644
--- a/documentation/events.html
+++ b/documentation/events.html
@@ -166,4 +166,184 @@ to leaf widgets.  These procedures control those leaf widgets: </P>
 <LI><A href=Fl_Widget.html#Fl_Widget.take_focus>Fl_Widget::take_focus</A>
 </LI>
 </UL>
-</BODY></HTML>
\ No newline at end of file
+
+<H2><A name=compose>FLTK Compose-Character Sequences</A></H2>
+
+The <A href="#Fl_Input"><tt>Fl_Input</tt></a> widget lets you type all the
+characters in the standard ISO-8859-1 character set.  Most fonts will
+display these characters correctly.
+
+<P>To insert them, type the [compose] key and then one or two
+characters.  The two characters can be in either order.  The [compose]
+key is any of: Ctrl+Q, the righthand control key, or any key your X server
+calls <TT>XK_Multi_key</TT>.
+
+<center><table border=1>
+<tr>
+	<td><TT>sp</TT>nbsp</td>
+	<td><TT>*</TT>°</td>
+	<td><TT>A`</TT>À</td>
+	<td><TT>D-</TT>Ð</td>
+	<td><TT>a`</TT>à</td>
+	<td><TT>d-</TT>ð</td>
+</tr>
+<tr>
+	<td><TT>!</TT>¡</td>
+	<td><TT>+-</TT>±</td>
+	<td><TT>A'</TT>Á</td>
+	<td><TT>N~</TT>Ñ</td>
+	<td><TT>a'</TT>á</td>
+	<td><TT>n~</TT>ñ</td>
+</tr>
+<tr>
+	<td><TT>%</TT>¢</td>
+	<td><TT>2</TT>²</td>
+	<td><TT>A^</TT>Â</td>
+	<td><TT>O`</TT>Ò</td>
+	<td><TT>a^</TT>â</td>
+	<td><TT>o`</TT>ò</td>
+</tr>
+<tr>
+	<td><TT>#</TT>£</td>
+	<td><TT>3</TT>³</td>
+	<td><TT>A~</TT>Ã</td>
+	<td><TT>O'</TT>Ó</td>
+	<td><TT>a~</TT>ã</td>
+	<td><TT>o'</TT>ó</td>
+</tr>
+<tr>
+	<td><TT>$</TT>¤</td>
+	<td><TT>'</TT>´</td>
+	<td><TT>A:</TT>Ä</td>
+	<td><TT>O^</TT>Ô</td>
+	<td><TT>a:</TT>ä</td>
+	<td><TT>o^</TT>ô</td>
+</tr>
+<tr>
+	<td><TT>y=</TT>¥</td>
+	<td><TT>u</TT>µ</td>
+	<td><TT>A*</TT>Å</td>
+	<td><TT>O~</TT>Õ</td>
+	<td><TT>a*</TT>å</td>
+	<td><TT>o~</TT>õ</td>
+</tr>
+<tr>
+	<td><TT>|</TT>¦</td>
+	<td><TT>p</TT>¶</td>
+	<td><TT>AE</TT>Æ</td>
+	<td><TT>O:</TT>Ö</td>
+	<td><TT>ae</TT>æ</td>
+	<td><TT>o:</TT>ö</td>
+</tr>
+<tr>
+	<td><TT>&</TT>§</td>
+	<td><TT>.</TT>·</td>
+	<td><TT>C,</TT>Ç</td>
+	<td><TT>x</TT>×</td>
+	<td><TT>c,</TT>ç</td>
+	<td><TT>-:</TT>÷</td>
+</tr>
+<tr>
+	<td><TT>:</TT>¨</td>
+	<td><TT>,</TT>¸</td>
+	<td><TT>E`</TT>È</td>
+	<td><TT>O/</TT>Ø</td>
+	<td><TT>e`</TT>è</td>
+	<td><TT>o/</TT>ø</td>
+</tr>
+<tr>
+	<td><TT>c</TT>©</td>
+	<td><TT>1</TT>¹</td>
+	<td><TT>E'</TT>É</td>
+	<td><TT>U`</TT>Ù</td>
+	<td><TT>e'</TT>é</td>
+	<td><TT>u`</TT>ù</td>
+</tr>
+<tr>
+	<td><TT>a</TT>ª</td>
+	<td><TT>o</TT>º</td>
+	<td><TT>E^</TT>Ê</td>
+	<td><TT>U'</TT>Ú</td>
+	<td><TT>e^</TT>ê</td>
+	<td><TT>u'</TT>ú</td>
+</tr>
+<tr>
+	<td><TT>&lt;&lt;</TT>«</td>
+	<td><TT>>></TT>»</td>
+	<td><TT>E:</TT>Ë</td>
+	<td><TT>U^</TT>Û</td>
+	<td><TT>e:</TT>ë</td>
+	<td><TT>u^</TT>û</td>
+</tr>
+<tr>
+	<td><TT>~</TT>¬</td>
+	<td><TT>14</TT>¼</td>
+	<td><TT>I`</TT>Ì</td>
+	<td><TT>U:</TT>Ü</td>
+	<td><TT>i`</TT>ì</td>
+	<td><TT>u:</TT>ü</td>
+</tr>
+<tr>
+	<td><TT>-</TT>­</td>
+	<td><TT>12</TT>½</td>
+	<td><TT>I'</TT>Í</td>
+	<td><TT>Y'</TT>Ý</td>
+	<td><TT>i'</TT>í</td>
+	<td><TT>y'</TT>ý</td>
+</tr>
+<tr>
+	<td><TT>r</TT>®</td>
+	<td><TT>34</TT>¾</td>
+	<td><TT>I^</TT>Î</td>
+	<td><TT>DD</TT>Þ</td>
+	<td><TT>i^</TT>î</td>
+	<td><TT>dd</TT>þ</td>
+</tr>
+<tr>
+	<td><TT>_</TT>¯</td>
+	<td><TT>?</TT>¿</td>
+	<td><TT>I:</TT>Ï</td>
+	<td><TT>ss</TT>ß</td>
+	<td><TT>i:</TT>ï</td>
+	<td><TT>y:</TT>ÿ</td>
+</tr>
+</table>
+</center>
+
+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>If you wish to use the compose function in your own code, your
+widget's <tt>handle()</tt> method must call <tt>fl_compose()</tt>
+in response to <tt>FL_KEYPRESS</tt> events:
+
+<h4><TT>int fl_compose(int state, char c, int &amp;del, char *buffer, int &amp;ins)</TT></h4>
+
+Starts or adds a single ASCII character to a compose sequence.  This
+will return the number of old bytes to delete and a set of new bytes to
+insert, and a new <tt>state</tt> value.  If this returns zero you can
+ignore the result (which just says to insert the character unchanged)
+and handle the keystroke yourself.
+
+<P><tt>state</tt> must either be the return value of the last call to
+<tt>fl_compose()</tt> or zero to start a new compose sequence.  Be sure to reset
+to zero if the user ever moves the cursor.
+
+<P><tt>c</tt> is the ASCII character that the user typed.
+
+<P><tt>del</tt> is set to the number of bytes to delete backwards.  This
+will always be less or equal to the <tt>ins</tt> from the last call to
+<tt>fl_compose()</tt>, and will be zero if <tt>state</tt> is zero.
+
+<P><tt>buffer</tt> will have the first <tt>ins</tt> bytes set to the data
+to insert and display (it is <I>not</I> nul-terminated).
+
+<P><tt>ins</tt> will be the number of characters to insert.
+
+</BODY></HTML>
diff --git a/documentation/preface.html b/documentation/preface.html
index 63781160d..8726c158c 100644
--- a/documentation/preface.html
+++ b/documentation/preface.html
@@ -55,7 +55,7 @@ Reference</A></LI>
 <H2>Copyrights and Trademarks</H2>
  FLTK is Copyright 1998-1999 by Bill Spitzak and others.  Use and 
 distribution of FLTK is governed by the GNU Library General Public 
-License, located in <A HREF=license.html#license>Appendix D</A>. 
+License, located in <A HREF=license.html#license>Appendix G</A>. 
 <P>UNIX is a registered trademark of the X Open Group, Inc.  Microsoft 
 and Windows are registered trademarks of Microsoft Corporation. OpenGL 
 is a registered trademark of Silicon Graphics, Inc. </P>
diff --git a/documentation/subclassing.html b/documentation/subclassing.html
index d15f691e2..5951f0305 100644
--- a/documentation/subclassing.html
+++ b/documentation/subclassing.html
@@ -74,20 +74,19 @@ flags(ACTIVE|VISIBLE);
 <H3><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></H3>
- The first form indicates that a partial update of the object is 
+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>. 
+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>.  The public method <TT>
-redraw()</TT> does <TT>damage(FL_DAMAGE_ALL)</TT>, but the 
-implementation of your widget can call the private <TT>damage(n)</TT>. </P>
+calls done since the last <TT>draw()</TT>.</P>
 <H3><A name=draw_box>void Fl_Widget::draw_box() const
 <BR></A>void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const</H3>
  The first form draws this widget's <TT>box()</TT>, using the 
@@ -110,7 +109,7 @@ the passed bounding box. This is designed for parent groups to draw
 labels with. </P>
 <H3><A name=set_flag>void Fl_Widget::set_flag(SHORTCUT_LABEL)</A></H3>
  If your constructor calls this it modifies <TT>draw_label()</TT> so 
-that ''characters cause an underscore to be printed under the next 
+that '&amp;' characters cause an underscore to be printed under the next 
 letter. 
 <H3><A name=set_visible>void Fl_Widget::set_visible()</A>
 <BR><A name=clear_visible>void Fl_Widget::clear_visible()</A></H3>
@@ -121,10 +120,10 @@ FL_SHOW</TT> events to the widget.
 <BR> static int Fl_Widget::test_shortcut(const char *s)</A></H3>
  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 ''character and the character after it matches the key 
+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 
-''character in it, or if the keypress does not match the character. 
+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>
 <H3><A name=type>uchar Fl_Widget::type() const
@@ -140,11 +139,10 @@ standard everywhere. </P>
 <P>If you don't have RTTI you can use the clumsy FLTK mechanisim, by 
 having <TT>type()</TT> have 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_Group</TT> you must 
-use <TT>FL_GROUP + n</TT>, and if you make a subclass of <TT>Fl_Window<TT>
-you must use <TT>FL_WINDOW + n</TT> (in both cases <TT>n is in the 
-range 1 to 7). </TT></TT></TT></P>
+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>Handling Events</H2>
  The virtual method <TT>int Fl_Widget::handle(int event)</TT> is called 
 to handle each event passed to the widget. It can: 
@@ -216,8 +214,8 @@ be called from non-drawing code.
 <P><TT>damage()</TT> 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 <I>all</I> the bits on if it thinks the entire widget must be 
-redrawn (for instance due to an expose event). </P>
+will turn on the <TT>FL_DAMAGE_ALL</TT> bit if it thinks the entire widget
+must be redrawn (for instance due to 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 
@@ -285,8 +283,8 @@ void MyClass::slider_cb() { // normal method
 </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. 
-Note that you don't need to override <TT>handle()</TT> if your 
-composite widget does nothing other than pass events to the children: 
+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) {
@@ -373,4 +371,4 @@ rather than <TT>draw_box( x(), y(), w(), h())</TT>. </LI>
  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#osissues>Appendix F - Operating 
-System Issues</A> for more information. </BODY></HTML>
\ No newline at end of file
+System Issues</A> for more information. </BODY></HTML>