Forgot to commit the header files and fixed documentation!

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

2 files changed, 209 insertions, 178 deletions

diff --git a/documentation/Fl_Input.html b/documentation/Fl_Input.html
index 0c65dc962..d6af54f69 100644
--- a/documentation/Fl_Input.html
+++ b/documentation/Fl_Input.html
@@ -27,16 +27,23 @@ will correctly display anything, using ^X notation for unprintable
 control characters and \nnn notation for unprintable characters with 
 the high bit set. It assummes the font can draw any characters in the 
 ISO8859-1 character set. 
+
+<p>
 <CENTER><TABLE border=1 WIDTH=90%>
-<TR><TD WIDTH=200><B>Mouse button 1</B></TD><TD>Moves the cursor to this point. 
- Drag selects characters.  Double click selects words.  Triple click 
-selects all text.  Shift+click extends the selection.</TD></TR>
-<TR><TD><B>Mouse button 2</B></TD><TD>Insert the current X selection at 
-the cursor (unlike Motif this does not move the insertion point to the 
-mouse).  If the widget does not have the input focus (and thus no 
-cursor) it puts the cursor where clicked and inserts the selection 
-there.</TD></TR>
+
+<TR><TD WIDTH=200><B>Mouse button 1</B></TD><TD>Moves the cursor to
+ this point. Drag selects characters.  Double click selects words.
+ Triple click selects all text.  Shift+click extends the selection.
+ When you select text it is automatically copied to the clipboard.
+</TD></TR>
+
+<TR><TD><B>Mouse button 2</B></TD><TD>Insert the clipboard at
+the point clicked.  You can also select a region to replace with the
+clipboard by selecting a region with mouse button 2.
+</TD></TR>
+
 <TR><TD><B>Mouse button 3</B></TD><TD>Currently acts like button 1.</TD></TR>
+
 <TR><TD><B>Backspace</B></TD><TD>Deletes one character to the left, or 
 deletes the selected region.</TD></TR>
 <TR><TD><B>Enter</B></TD><TD>May cause the callback, see when().</TD></TR>
@@ -44,9 +51,7 @@ deletes the selected region.</TD></TR>
 <TR><TD><B>^B or Left</B></TD><TD>Move left</TD></TR>
 <TR><TD><B>^C</B></TD><TD>Copy the selection to the clipboard</TD></TR>
 <TR><TD><B>^D or Delete</B></TD><TD>Deletes one character to the right 
-or deletes the selected region. <I>Due to silly historical X problems, 
-the Delete key will act like Backspace until you type a &quot;real&quot; 
-backspace.</I></TD></TR>
+or deletes the selected region.</TD></TR>
 <TR><TD><B>^E or End</B></TD><TD>Go to the end of line.</TD></TR>
 <TR><TD><B>^F or Right</B></TD><TD>Move right</TD></TR>
 <TR><TD><B>^K</B></TD><TD>Delete to the end of line (next \n character) 
@@ -56,11 +61,6 @@ into the clipboard.</TD></TR>
 only, otherwise it moves to the next input field).</TD></TR>
 <TR><TD><B>^P or Up</B></TD><TD>Move up (for Fl_Multiline_Input only, 
 otherwise it moves to the previous input field).</TD></TR>
-<TR><TD><B>^Q or
-<BR>RightCtrl or
-<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>
 <TR><TD><B>^V or ^Y</B></TD><TD>Paste the clipboard</TD></TR>
 <TR><TD><B>^X or ^W</B></TD><TD>Copy the region to the clipboard and 
@@ -71,6 +71,158 @@ into a single &quot;undo&quot;.  Often this will undo a lot more than you
 expected.</TD></TR>
 <TR><TD><B>Shift+move</B></TD><TD>Move the cursor but also extend the 
 selection.</TD></TR>
+
+<TR><TD><B>RightCtrl or
+<BR>Compose</B></TD><TD><a name=compose>
+Start a <A href="events.html#compose">compose-character</A>
+sequence.  The next one or two keys typed define the character to insert:
+
+<br><center><table border=1>
+<tr>
+	<th>Keys</th><th>Char</th>
+	<th>Keys</th><th>Char</th>
+	<th>Keys</th><th>Char</th>
+	<th>Keys</th><th>Char</th>
+	<th>Keys</th><th>Char</th>
+	<th>Keys</th><th>Char</th>
+
+</tr><tr>
+	<td align=center><small>space</small></td><td align=center><small>nbsp</small></td>
+	<td align=center><TT>*</tt></td><td align=center>°</td>
+	<td align=center><TT>`A</tt></td><td align=center>À</td>
+	<td align=center><TT>D-</tt></td><td align=center>Ð</td>
+	<td align=center><TT>`a</tt></td><td align=center>à</td>
+	<td align=center><TT>d-</tt></td><td align=center>ð
+</tr><tr>
+	<td align=center><TT>!</tt></td><td align=center>¡</td>
+	<td align=center><TT>+-</tt></td><td align=center>±</td>
+	<td align=center><TT>'A</tt></td><td align=center>Á</td>
+	<td align=center><TT>~N</tt></td><td align=center>Ñ</td>
+	<td align=center><TT>'a</tt></td><td align=center>á</td>
+	<td align=center><TT>~n</tt></td><td align=center>ñ
+</tr><tr>
+	<td align=center><TT>%</tt></td><td align=center>¢</td>
+	<td align=center><TT>2</tt></td><td align=center>²</td>
+	<td align=center><TT>A^</tt></td><td align=center>Â</td>
+	<td align=center><TT>`O</tt></td><td align=center>Ò</td>
+	<td align=center><TT>^a</tt></td><td align=center>â</td>
+	<td align=center><TT>`o</tt></td><td align=center>ò
+</tr><tr>
+	<td align=center><TT>#</tt></td><td align=center>£</td>
+	<td align=center><TT>3</tt></td><td align=center>³</td>
+	<td align=center><TT>~A</tt></td><td align=center>Ã</td>
+	<td align=center><TT>'O</tt></td><td align=center>Ó</td>
+	<td align=center><TT>~a</tt></td><td align=center>ã</td>
+	<td align=center><TT>'o</tt></td><td align=center>ó
+</tr><tr>
+	<td align=center><TT>$</tt></td><td align=center>¤</td>
+	<td align=center><TT>'</tt></td><td align=center>´</td>
+	<td align=center><TT>:A</tt></td><td align=center>Ä</td>
+	<td align=center><TT>^O</tt></td><td align=center>Ô</td>
+	<td align=center><TT>:a</tt></td><td align=center>ä</td>
+	<td align=center><TT>^o</tt></td><td align=center>ô
+</tr><tr>
+	<td align=center><TT>y=</tt></td><td align=center>¥</td>
+	<td align=center><TT>u</tt></td><td align=center>µ</td>
+	<td align=center><TT>*A</tt></td><td align=center>Å</td>
+	<td align=center><TT>~O</tt></td><td align=center>Õ</td>
+	<td align=center><TT>*a</tt></td><td align=center>å</td>
+	<td align=center><TT>~o</tt></td><td align=center>õ
+</tr><tr>
+	<td align=center><TT>|</tt></td><td align=center>¦</td>
+	<td align=center><TT>p</tt></td><td align=center>¶</td>
+	<td align=center><TT>AE</tt></td><td align=center>Æ</td>
+	<td align=center><TT>:O</tt></td><td align=center>Ö</td>
+	<td align=center><TT>ae</tt></td><td align=center>æ</td>
+	<td align=center><TT>:o</tt></td><td align=center>ö
+</tr><tr>
+	<td align=center><TT>&amp;</tt></td><td align=center>§</td>
+	<td align=center><TT>.</tt></td><td align=center>·</td>
+	<td align=center><TT>,C</tt></td><td align=center>Ç</td>
+	<td align=center><TT>x</tt></td><td align=center>×</td>
+	<td align=center><TT>,c</tt></td><td align=center>ç</td>
+	<td align=center><TT>-:</tt></td><td align=center>÷
+</tr><tr>
+	<td align=center><TT>:</tt></td><td align=center>¨</td>
+	<td align=center><TT>,</tt></td><td align=center>¸</td>
+	<td align=center><TT>E`</tt></td><td align=center>È</td>
+	<td align=center><TT>O/</tt></td><td align=center>Ø</td>
+	<td align=center><TT>`e</tt></td><td align=center>è</td>
+	<td align=center><TT>o/</tt></td><td align=center>ø
+</tr><tr>
+	<td align=center><TT>c</tt></td><td align=center>©</td>
+	<td align=center><TT>1</tt></td><td align=center>¹</td>
+	<td align=center><TT>'E</tt></td><td align=center>É</td>
+	<td align=center><TT>`U</tt></td><td align=center>Ù</td>
+	<td align=center><TT>'e</tt></td><td align=center>é</td>
+	<td align=center><TT>`u</tt></td><td align=center>ù
+</tr><tr>
+	<td align=center><TT>a</tt></td><td align=center>ª</td>
+	<td align=center><TT>o</tt></td><td align=center>º</td>
+	<td align=center><TT>^E</tt></td><td align=center>Ê</td>
+	<td align=center><TT>'U</tt></td><td align=center>Ú</td>
+	<td align=center><TT>^e</tt></td><td align=center>ê</td>
+	<td align=center><TT>'u</tt></td><td align=center>ú
+</tr><tr>
+	<td align=center><TT>&lt;&lt;</tt></td><td align=center>«</td>
+	<td align=center><TT>>></tt></td><td align=center>»</td>
+	<td align=center><TT>:E</tt></td><td align=center>Ë</td>
+	<td align=center><TT>^U</tt></td><td align=center>Û</td>
+	<td align=center><TT>:e</tt></td><td align=center>ë</td>
+	<td align=center><TT>^u</tt></td><td align=center>û
+</tr><tr>
+	<td align=center><TT>~</tt></td><td align=center>¬</td>
+	<td align=center><TT>14</tt></td><td align=center>¼</td>
+	<td align=center><TT>`I</tt></td><td align=center>Ì</td>
+	<td align=center><TT>:U</tt></td><td align=center>Ü</td>
+	<td align=center><TT>`i</tt></td><td align=center>ì</td>
+	<td align=center><TT>:u</tt></td><td align=center>ü
+</tr><tr>
+	<td align=center><TT>-</tt></td><td align=center>­</td>
+	<td align=center><TT>12</tt></td><td align=center>½</td>
+	<td align=center><TT>'I</tt></td><td align=center>Í</td>
+	<td align=center><TT>'Y</tt></td><td align=center>Ý</td>
+	<td align=center><TT>'i</tt></td><td align=center>í</td>
+	<td align=center><TT>'y</tt></td><td align=center>ý
+</tr><tr>
+	<td align=center><TT>r</tt></td><td align=center>®</td>
+	<td align=center><TT>34</tt></td><td align=center>¾</td>
+	<td align=center><TT>^I</tt></td><td align=center>Î</td>
+	<td align=center><TT>TH</tt></td><td align=center>Þ</td>
+	<td align=center><TT>^i</tt></td><td align=center>î</td>
+	<td align=center><TT>th</tt></td><td align=center>þ
+</tr><tr>
+	<td align=center><TT>_</tt></td><td align=center>¯</td>
+	<td align=center><TT>?</tt></td><td align=center>¿</td>
+	<td align=center><TT>:I</tt></td><td align=center>Ï</td>
+	<td align=center><TT>ss</tt></td><td align=center>ß</td>
+	<td align=center><TT>:i</tt></td><td align=center>ï</td>
+	<td align=center><TT>:y</tt></td><td align=center>ÿ
+</table></center>
+
+<p>For instance, to type "á" type [compose][a]['] or [compose]['][a].
+
+<P>The character "nbsp" (non-breaking space) is typed by using
+[compose][space].
+
+<P>The single-character sequences may be followed by a space if
+necessary to remove ambiguity.  For instance, if you really want to
+type "ª~" rather than "ã" you must type [compose][a][space][~].
+
+<p>The same key may be used to "quote" control characters into the
+text.  If you need a <tt>^Q</tt> character you can get one by typing
+[compose][Control+Q].
+
+<p>X may have a key on the keyboard
+defined as <tt>XK_Multi_key</tt>.  If so this key may be used as well
+as the right-hand control key.  You can set this up with the program
+<tt>xmodmap</tt>.
+
+<p>If your keyboard is set to support a foreign language you should
+also be able to type "dead key" prefix characters.  On X you will
+actually be able to see what dead key you typed, and if you then move
+the cursor without completing the sequence the accent will remain
+inserted.
 </TABLE></CENTER>
 <H3>Methods</H3>
 <CENTER>
diff --git a/documentation/events.html b/documentation/events.html
index 88ec9b9f3..502be762f 100644
--- a/documentation/events.html
+++ b/documentation/events.html
@@ -80,6 +80,10 @@ event.
 <P>To receive <CODE>FL_KEYBOARD</CODE> events you must also respond to the
 <CODE>FL_FOCUS</CODE> and <CODE>FL_UNFOCUS</CODE> events.
 
+<p>If you are writing a text-editing widget you may also want to call
+the <a href=#compose>Fl::compose()</a> function to translate
+individual keystrokes into foreign characters.
+
 <H3>FL_SHORTCUT</H3>
 If the <A href=functions.html#focus><TT>Fl::focus()</TT></A> widget is zero 
 or ignores an <TT>FL_KEYBOARD</TT> event then FLTK tries sending this 
@@ -102,7 +106,8 @@ active_r()</TT> to check this).
  This widget is now active, due to <A href=Fl_Widget.html#Fl_Widget.activate>
 <TT>activate()</TT></A> being called on it or one of its parents. 
 <H3>FL_HIDE</H3>
- This widget is no longer visible, due to <A #Fl_Widget.show" href="#Fl_Widget.hide><tt>hide()</tt></a> being called on it or one of its
+
+ This widget is no longer visible, due to <A href=Fl_Widget.html#Fl_Widget.hide><tt>hide()</tt></a> being called on it or one of its
 parents, or due to a parent window being minimized.  <tt>visible()</tt>
 may still be true after this, but the widget is visible only if
 <tt>visible()</tt> is true for it and all its parents (use
@@ -111,7 +116,7 @@ may still be true after this, but the widget is visible only if
 <h3>FL_SHOW</h3>
 
 This widget is visible again, due to <a
-href=">
+href=Fl_Widget.html#Fl_Widget.show>
 <TT>show()</TT></A> being called on it or one of its parents, or due to 
 a parent window being restored. <I>Child <TT>Fl_Window</TT>s respond to 
 this by actually creating the window if not done already, so if you 
@@ -128,7 +133,8 @@ Fl::event_length()</TT></A>.
  The <A href=functions.html#selection_owner>Fl::selection_owner()</A>
  will get this event before the selection is moved to another widget. 
  This indicates that some other widget or program has claimed the 
-selection. 
+selection.  Motif programs used this to clear the selection
+indication.  Most modern programs ignore this.
 <H2><A name=event_xxx>Fl::event_*() methods</A></H2>
  FLTK keeps the information about the most recent event in static 
 storage.  This information is good until the next event is processed. 
@@ -181,172 +187,45 @@ to leaf widgets.  These procedures control those leaf widgets: </P>
 
 <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>.
-
-<p><center><table border=1>
-<tr>
-	<th>Keys<th>Char<th>
-	<th>Keys<th>Char<th>
-	<th>Keys<th>Char<th>
-	<th>Keys<th>Char<th>
-	<th>Keys<th>Char<th>
-	<th>Keys<th>Char
-<tr>
-	<td align=center><small>space</small><td align=center><small>nbsp</small><td>
-	<td align=center><TT>*</TT><td align=center>°<td>
-	<td align=center><TT>A`</TT><td align=center>À<td>
-	<td align=center><TT>D-</TT><td align=center>Ð<td>
-	<td align=center><TT>a`</TT><td align=center>à<td>
-	<td align=center><TT>d-</TT><td align=center>ð
-<tr>
-	<td align=center><TT>!</TT><td align=center>¡<td>
-	<td align=center><TT>+-</TT><td align=center>±<td>
-	<td align=center><TT>A'</TT><td align=center>Á<td>
-	<td align=center><TT>N~</TT><td align=center>Ñ<td>
-	<td align=center><TT>a'</TT><td align=center>á<td>
-	<td align=center><TT>n~</TT><td align=center>ñ
-<tr>
-	<td align=center><TT>%</TT><td align=center>¢<td>
-	<td align=center><TT>2</TT><td align=center>²<td>
-	<td align=center><TT>A^</TT><td align=center>Â<td>
-	<td align=center><TT>O`</TT><td align=center>Ò<td>
-	<td align=center><TT>a^</TT><td align=center>â<td>
-	<td align=center><TT>o`</TT><td align=center>ò
-<tr>
-	<td align=center><TT>#</TT><td align=center>£<td>
-	<td align=center><TT>3</TT><td align=center>³<td>
-	<td align=center><TT>A~</TT><td align=center>Ã<td>
-	<td align=center><TT>O'</TT><td align=center>Ó<td>
-	<td align=center><TT>a~</TT><td align=center>ã<td>
-	<td align=center><TT>o'</TT><td align=center>ó
-<tr>
-	<td align=center><TT>$</TT><td align=center>¤<td>
-	<td align=center><TT>'</TT><td align=center>´<td>
-	<td align=center><TT>A:</TT><td align=center>Ä<td>
-	<td align=center><TT>O^</TT><td align=center>Ô<td>
-	<td align=center><TT>a:</TT><td align=center>ä<td>
-	<td align=center><TT>o^</TT><td align=center>ô
-<tr>
-	<td align=center><TT>y=</TT><td align=center>¥<td>
-	<td align=center><TT>u</TT><td align=center>µ<td>
-	<td align=center><TT>A*</TT><td align=center>Å<td>
-	<td align=center><TT>O~</TT><td align=center>Õ<td>
-	<td align=center><TT>a*</TT><td align=center>å<td>
-	<td align=center><TT>o~</TT><td align=center>õ
-<tr>
-	<td align=center><TT>|</TT><td align=center>¦<td>
-	<td align=center><TT>p</TT><td align=center>¶<td>
-	<td align=center><TT>AE</TT><td align=center>Æ<td>
-	<td align=center><TT>O:</TT><td align=center>Ö<td>
-	<td align=center><TT>ae</TT><td align=center>æ<td>
-	<td align=center><TT>o:</TT><td align=center>ö
-<tr>
-	<td align=center><TT>&amp;</TT><td align=center>§<td>
-	<td align=center><TT>.</TT><td align=center>·<td>
-	<td align=center><TT>C,</TT><td align=center>Ç<td>
-	<td align=center><TT>x</TT><td align=center>×<td>
-	<td align=center><TT>c,</TT><td align=center>ç<td>
-	<td align=center><TT>-:</TT><td align=center>÷
-<tr>
-	<td align=center><TT>:</TT><td align=center>¨<td>
-	<td align=center><TT>,</TT><td align=center>¸<td>
-	<td align=center><TT>E`</TT><td align=center>È<td>
-	<td align=center><TT>O/</TT><td align=center>Ø<td>
-	<td align=center><TT>e`</TT><td align=center>è<td>
-	<td align=center><TT>o/</TT><td align=center>ø
-<tr>
-	<td align=center><TT>c</TT><td align=center>©<td>
-	<td align=center><TT>1</TT><td align=center>¹<td>
-	<td align=center><TT>E'</TT><td align=center>É<td>
-	<td align=center><TT>U`</TT><td align=center>Ù<td>
-	<td align=center><TT>e'</TT><td align=center>é<td>
-	<td align=center><TT>u`</TT><td align=center>ù
-<tr>
-	<td align=center><TT>a</TT><td align=center>ª<td>
-	<td align=center><TT>o</TT><td align=center>º<td>
-	<td align=center><TT>E^</TT><td align=center>Ê<td>
-	<td align=center><TT>U'</TT><td align=center>Ú<td>
-	<td align=center><TT>e^</TT><td align=center>ê<td>
-	<td align=center><TT>u'</TT><td align=center>ú
-<tr>
-	<td align=center><TT>&lt;&lt;</TT><td align=center>«<td>
-	<td align=center><TT>>></TT><td align=center>»<td>
-	<td align=center><TT>E:</TT><td align=center>Ë<td>
-	<td align=center><TT>U^</TT><td align=center>Û<td>
-	<td align=center><TT>e:</TT><td align=center>ë<td>
-	<td align=center><TT>u^</TT><td align=center>û
-<tr>
-	<td align=center><TT>~</TT><td align=center>¬<td>
-	<td align=center><TT>14</TT><td align=center>¼<td>
-	<td align=center><TT>I`</TT><td align=center>Ì<td>
-	<td align=center><TT>U:</TT><td align=center>Ü<td>
-	<td align=center><TT>i`</TT><td align=center>ì<td>
-	<td align=center><TT>u:</TT><td align=center>ü
-<tr>
-	<td align=center><TT>-</TT><td align=center>­<td>
-	<td align=center><TT>12</TT><td align=center>½<td>
-	<td align=center><TT>I'</TT><td align=center>Í<td>
-	<td align=center><TT>Y'</TT><td align=center>Ý<td>
-	<td align=center><TT>i'</TT><td align=center>í<td>
-	<td align=center><TT>y'</TT><td align=center>ý
-<tr>
-	<td align=center><TT>r</TT><td align=center>®<td>
-	<td align=center><TT>34</TT><td align=center>¾<td>
-	<td align=center><TT>I^</TT><td align=center>Î<td>
-	<td align=center><TT>TH</TT><td align=center>Þ<td>
-	<td align=center><TT>i^</TT><td align=center>î<td>
-	<td align=center><TT>th</TT><td align=center>þ
-<tr>
-	<td align=center><TT>_</TT><td align=center>¯<td>
-	<td align=center><TT>?</TT><td align=center>¿<td>
-	<td align=center><TT>I:</TT><td align=center>Ï<td>
-	<td align=center><TT>ss</TT><td align=center>ß<td>
-	<td align=center><TT>i:</TT><td align=center>ï<td>
-	<td align=center><TT>y:</TT><td align=center>ÿ
-</table>
-</center>
-
-<p>For instance, to type "á" type [compose][a]['] or [compose]['][a].
-
-<P>The character "nbsp" (non-breaking space) is typed by using
-[compose][space].
+The foreign-letter compose processing done by the <A
+href=Fl_Input.html#compose><tt>Fl_Input</tt></a> widget is provided in
+a function that you can call if you are writing your own text editor
+widget.
 
-<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>Fltk uses it's own compose processing to allow "preview" of the
+partially composed sequence, which is impossible with the usual
+"dead key" processing.
 
-<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:
+<p>Although currently only characters in the ISO-8859-1 character set are
+handled, you should call this in case any enhancements to the
+processing are done in the future.  The interface has been designed to
+handle arbitrary UTF-8 encoded text.
 
-<h4><TT>int fl_compose(int state, char c, int &amp;del, char *buffer, int &amp;ins)</TT></h4>
+<h4><tt>int Fl::compose(int&amp; del)</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>Use of this function is very simple.  Any text editing widget should
+call this for each <tt>FL_KEYBOARD</tt> event.
 
-<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>If <i>true</i> is returned, then it has modified the
+Fl::event_text() and Fl::event_length() to a set of <i>bytes</i> to
+insert (it may be of zero length!).  In will also set the "del"
+parameter to the number of <i>bytes</i> to the left of the cursor to
+delete, this is used to delete the results of the previous call to
+Fl::compose().
 
-<P><tt>c</tt> is the ASCII character that the user typed.
+<p>If <i>false</i> is returned, the keys should be treated as function
+keys, and del is set to zero.  You could insert the text anyways, if
+you don't know what else to do.
 
-<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>Though the current implementation returns immediately, future
+versions may take quite awhile, as they may pop up a window or do
+other user-interface things to allow characters to be selected.
 
-<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).
+<h4><tt>int Fl::compose_reset()</tt></h4>
 
-<P><tt>ins</tt> will be the number of characters to insert.
+<p>If the user moves the cursor, be sure to call Fl::compose_reset().
+The next call to Fl::compose() will start out in an initial state.  In
+particular it will not set "del" to non-zero.  This call is very fast
+so it is ok to call it many times and in many places.
 
-</BODY></HTML>
+</body></html>