Added two UTF-8 support headers which can not be used just yet. Added sample implementation of Doxygen documentation, including a Doxygen config file, two copied doc pages documentation/index.do and documentation/preface.dox, and sample headers fro Fl_Preferences and Fl_Clock.

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

4 files changed, 902 insertions, 6 deletions

diff --git a/FL/Fl_Clock.H b/FL/Fl_Clock.H
index 56962a2f5..da98bdcf8 100644
--- a/FL/Fl_Clock.H
+++ b/FL/Fl_Clock.H
@@ -25,6 +25,10 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \file
+ * Fl_Clock widget definitions for the Fast Light Tool Kit (FLTK).
+ */
+
 #ifndef Fl_Clock_H
 #define Fl_Clock_H
 
@@ -40,6 +44,15 @@
 
 // a Fl_Clock_Output can be used to display a program-supplied time:
 
+/**
+ * This widget can be used to display a program-supplied time.
+ * The time shown on the clock is not updated. 
+ * To display the current time, use <TT>Fl_Clock</A></TT> instead.
+ *
+ * \image html clock.gif 
+ *
+ * \image html round_clock.gif
+ */
 class FL_EXPORT Fl_Clock_Output : public Fl_Widget {
   int hour_, minute_, second_;
   ulong value_;
@@ -48,23 +61,101 @@ protected:
   void draw(int, int, int, int);
   void draw();
 public:
+  
+  /**
+   * Creates a new <tt>Fl_Clock_Output</tt> widget.
+   * Create an <tt>Fl_Clock_Output</tt> widget using the given position, 
+   * size, and label string. The default boxtype is <tt>FL_NO_BOX</tt>.
+   *
+   * \param[in] x, y, w, h position and size of the widget
+   * \param[in] label widget label, default is no label
+   */
   Fl_Clock_Output(int x,int y,int w,int h, const char *l = 0);
+
+  /**
+   * Set the displayed time.
+   * Set the time in seconds since the UNIX epoch (January 1, 1970).
+   * \see value()
+   */
   void value(ulong v);	// set to this Unix time
-  void value(int,int,int);	// set hour, minute, second
+  
+  /**
+   * Set the displayed time.
+   * Set the time in hours, minutes, and seconds.
+   * \param[in] hour, minute, second displayed time
+   * \see hour(), minute(), second()
+   */
+  void value(int hour, int minute, int second);
+  
+  /**
+   * Returns the displayed time.
+   * Returns the time in seconds since the UNIX epoch (January 1, 1970).
+   * \see value(ulong)
+   */
   ulong value() const {return value_;}
+
+  /**
+   * Returns the displayed time.
+   * Returns the displayed hour (0 to 23).
+   * \see value(), minute(), second()
+   */
   int hour() const {return hour_;}
+
+  /**
+   * Returns the displayed time.
+   * Returns the displayed minute (0 to 59).
+   * \see value(), hour(), second()
+   */
   int minute() const {return minute_;}
+
+  /**
+   * Returns the displayed time.
+   * Returns the displayed second (0 to 60, 60=leap second).
+   * \see value(), hour(), minute()
+   */
   int second() const {return second_;}
 };
 
 // a Fl_Clock displays the current time always by using a timeout:
 
+/**
+ * This widget provides a round analog clock display.
+ * <tt>Fl_Clock</tt> is provided for Forms compatibility. 
+ * It installs a 1-second timeout callback using <tt>Fl::add_timeout()</tt>.
+ *
+ * \image html clock.gif 
+ * 
+ * \image html round_clock.gif
+ */
 class FL_EXPORT Fl_Clock : public Fl_Clock_Output {
 public:
   int handle(int);
   void update();
+
+  /**
+   * Creates a new <tt>Fl_Clock</tt> widget.
+   * Create an <tt>Fl_Clock</tt> widget using the given position, 
+   * size, and label string. The default boxtype is <tt>FL_NO_BOX</tt>.
+   *
+   * \param[in] x, y, w, h position and size of the widget
+   * \param[in] label widget label, default is no label
+   */
   Fl_Clock(int x,int y,int w,int h, const char *l = 0);
+  
+  /**
+   * Creates a new <tt>Fl_Clock</tt> widget.
+   * Create an <tt>Fl_Clock</tt> widget using the given position, 
+   * size, and label string.
+   *
+   * \param[in] t boxtype
+   * \param[in] x, y, w, h position and size of the widget
+   * \param[in] label widget label, default is no label
+   */
   Fl_Clock(uchar t,int x,int y,int w,int h, const char *l);
+  
+  /**
+   * The destructor removes the clock.
+   */
   ~Fl_Clock();
 };
 
diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H
index b16a9f18b..1f7438a5f 100644
--- a/FL/Fl_Preferences.H
+++ b/FL/Fl_Preferences.H
@@ -25,6 +25,10 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \file
+ * Preferences definitions for the Fast Light Tool Kit (FLTK).
+ */
+
 #ifndef Fl_Preferences_H
 #  define Fl_Preferences_H
 
@@ -37,61 +41,421 @@
 
 
 /**
- * Preferences are a data tree containing a root, branches and leafs
+ * <tt>Fl_Preferences </tt>provides methods to store user
+ * setting between application starts. It is similar to the
+ * Registry on WIN32 and Preferences on MacOS, and provides a
+ * simple configuration mechanism for UNIX.
+ * 
+ * <tt>Fl_Preferences </tt>uses a hierarchy to store data. It
+ * bundles similar data into groups and manages entries into those
+ * groups as name/value pairs.
+ * 
+ * Preferences are stored in text files that can be edited
+ * manually. The file format is easy to read and relatively
+ * forgiving. Preferences files are the same on all platforms. User
+ * comments in preference files are preserved. Filenames are unique
+ * for each application by using a vendor/application naming
+ * scheme. The user must provide default values for all entries to
+ * ensure proper operation should preferences be corrupted or not
+ * yet exist.
+ * 
+ * Entries can be of any length. However, the size of each
+ * preferences file should be kept under 100k for performance
+ * reasons. One application can have multiple preferences files.
+ * Extensive binary data however should be stored in seperate
+ * files; see getUserdataPath()
  */
 class FL_EXPORT Fl_Preferences 
 {
 
 public:
 
-  enum Root { SYSTEM=0, USER };
+  /**
+   * Define the scope of the preferences.
+   */
+  enum Root { 
+    SYSTEM=0,   ///< Preferences are uses system-wide
+    USER        ///< Preferences apply only to the current user
+  };
   // enum Type { win32, macos, fltk };
 
+  /**
+   * The constructor creates a group that manages name/value pairs and
+   * child groups. Groups are ready for reading and writing at any time.
+   * The <tt>root</tt> argument is either <tt>Fl_Preferences::USER</tt>
+   * or <tt>Fl_Preferences::SYSTEM</tt>.
+   * 
+   * This constructor creates the <i>base</i> instance for all
+   * following entries and reads existing databases into memory. The
+   * <tt>vendor</tt> argument is a unique text string identifying the
+   * development team or vendor of an application.  A domain name or
+   * an EMail address are great unique names, e.g.
+   * "researchATmatthiasm.com" or "fltk.org". The
+   * <tt>application</tt> argument can be the working title or final
+   * name of your application. Both <tt>vendor</tt> and
+   * <tt>application</tt> must be valid relative UNIX pathnames and
+   * may contain '/'s to create deeper file structures.
+   *
+   * \param[in] root can be USER or SYSTEM for user specific or system wide preferences
+   * \param[in] vendor unique text describing the company or author of this file
+   * \param[in] application unique text describing application
+   */
   Fl_Preferences( Root root, const char *vendor, const char *application );
+
+  /**
+   * This constructor is used to create or read a preferences file at an
+   * arbitrary position in the file system. The file name is generated
+   * as <tt><i>path</i>/<i>application</i>.prefs</tt>. If <i>application</i>
+   * is 0, <i>path</i> must contain the full file name.
+   * 
+   * \param[in] path path to the directory that contains the preferences file
+   * \param[in] vendor unique text describing the company or author of this file
+   * \param[in] application unique text describing application
+   */
   Fl_Preferences( const char *path, const char *vendor, const char *application );
-  Fl_Preferences( Fl_Preferences&, const char *group );
+
+  /**
+   * This constructor generates a new group of preference entries
+   * inside the group or file <i>p</i>. The <tt>groupname</tt> argument 
+   * identifies a group of entries. It can contain '/'s to get quick 
+   * access to individual elements inside the hierarchy.
+   *
+   * \param[in] parent reference object for the new group
+   * \param[in] group name of the group to access (may contain '/'s)
+   */
+  Fl_Preferences( Fl_Preferences &parent, const char *group );
+
+  /**
+   * \see Fl_Preferences( Fl_Preferences&, const char *group )
+   */
   Fl_Preferences( Fl_Preferences*, const char *group );
+
+  /**
+   * The destructor removes allocated resources. When used on the
+   * <i>base</i> preferences group, the destructor flushes all
+   * changes to the preferences file and deletes all internal
+   * databases.
+   */
   ~Fl_Preferences();
 
+
+  /**
+   * Returns the number of groups that are contained within a
+   * group.
+   *
+   * \return 0 for no groups at all
+   */
   int groups();
-  const char *group( int );
+
+  /**
+   * Returns the name of the Nth group. There is no guaranteed
+   * order  of group names. The index must be within the range given
+   * by <tt>groups()</tt>.
+   * 
+   * \param[in] index number indexing the requested group
+   * \return cstring pointer to the group name
+   */
+  const char *group( int index );
+  
+  /**
+   * Returns non-zero if a group with this name exists.
+   * Groupnames are relative to the Preferences node and can contain a path.
+   * <tt>"."</tt> describes the current node, <tt>"./"</tt> describes the topmost node.
+   * By preceding a groupname with a <tt>"./"</tt>, its path becomes relative to the topmost node.
+   * 
+   * \param[in] group name of group that is searched for
+   * \return 0 if group was not found
+   */
   char groupExists( const char *group );
+
+  /**
+   * Deletes a group.
+   *
+   * \param[in] group name of the group to delete
+   * \return 0 if call failed
+   */
   char deleteGroup( const char *group );
 
+
+  /**
+   * Return the number of entries (name/value) pairs in a group.
+   *
+   * \return number of entries
+   */
   int entries();
-  const char *entry( int );
+
+  /**
+   * Returns the name of an entry. There is no guaranteed order of
+   * entry names. The index must be within the range given by
+   * <tt>entries()</tt>.
+   *
+   * \param[in] index number indexing the requested entry
+   * \return pointer to value cstring
+   */
+  const char *entry( int index );
+
+  /**
+   * Returns non-zero if an entry with this name exists.
+   * 
+   * \param[in] entry name of entry that is searched for
+   * \return 0 if entry was not found
+   */
   char entryExists( const char *entry );
+  
+  /**
+   * Removes a single entry (name/value pair).
+   *
+   * \param[in] entry name of entry to delete
+   * \return 0 if deleting the entry failed
+   */
   char deleteEntry( const char *entry );
 
+  /** 
+   * Sets an entry (name/value pair). The return value indicates if there
+   * was a problem storing the data in memory. However it does not
+   * reflect if the value was actually stored in the preferences
+   * file.
+   *
+   * \param[in] entry name of entry
+   * \param[in] value set this entry to \a value
+   * \return 0 if setting the value failed
+   */
   char set( const char *entry, int value );
+
+  /** 
+   * Sets an entry (name/value pair). The return value indicates if there
+   * was a problem storing the data in memory. However it does not
+   * reflect if the value was actually stored in the preferences
+   * file.
+   *
+   * \param[in] entry name of entry
+   * \param[in] value set this entry to \a value
+   * \return 0 if setting the value failed
+   */
   char set( const char *entry, float value );
+
+  /** 
+   * Sets an entry (name/value pair). The return value indicates if there
+   * was a problem storing the data in memory. However it does not
+   * reflect if the value was actually stored in the preferences
+   * file.
+   *
+   * \param[in] entry name of entry
+   * \param[in] value set this entry to \a value
+   * \param[in] precision number of decimal digits to represent value
+   * \return 0 if setting the value failed
+   */
   char set( const char *entry, float value, int precision );
+
+  /** 
+   * Sets an entry (name/value pair). The return value indicates if there
+   * was a problem storing the data in memory. However it does not
+   * reflect if the value was actually stored in the preferences
+   * file.
+   *
+   * \param[in] entry name of entry
+   * \param[in] value set this entry to \a value
+   * \return 0 if setting the value failed
+   */
   char set( const char *entry, double value );
+
+  /** 
+   * Sets an entry (name/value pair). The return value indicates if there
+   * was a problem storing the data in memory. However it does not
+   * reflect if the value was actually stored in the preferences
+   * file.
+   *
+   * \param[in] entry name of entry
+   * \param[in] value set this entry to \a value
+   * \param[in] precision number of decimal digits to represent value
+   * \return 0 if setting the value failed
+   */
   char set( const char *entry, double value, int precision );
+
+  /** 
+   * Sets an entry (name/value pair). The return value indicates if there
+   * was a problem storing the data in memory. However it does not
+   * reflect if the value was actually stored in the preferences
+   * file.
+   *
+   * \param[in] entry name of entry
+   * \param[in] value set this entry to \a value
+   * \return 0 if setting the value failed
+   */
   char set( const char *entry, const char *value );
+
+  /** 
+   * Sets an entry (name/value pair). The return value indicates if there
+   * was a problem storing the data in memory. However it does not
+   * reflect if the value was actually stored in the preferences
+   * file.
+   *
+   * \param[in] entry name of entry
+   * \param[in] value set this entry to \a value
+   * \param[in] size of data array
+   * \return 0 if setting the value failed
+   */
   char set( const char *entry, const void *value, int size ); 
 
+
+  /**
+   * Reads an entry from the group. A default value must be
+   * supplied. The return value indicates if the value was available
+   * (non-zero) or the default was used (0).
+   *
+   * \param[in] entry name of entry
+   * \param[out] value returned from preferences or default value if none was set
+   * \param[in] defaultValue default value to be used if no preference was set
+   * \return 0 if the default value was used 
+   */
   char get( const char *entry, int &value,    int defaultValue );
+
+  /**
+   * Reads an entry from the group. A default value must be
+   * supplied. The return value indicates if the value was available
+   * (non-zero) or the default was used (0). 
+   *
+   * \param[in] entry name of entry
+   * \param[out] value returned from preferences or default value if none was set
+   * \param[in] defaultValue default value to be used if no preference was set
+   * \return 0 if the default value was used 
+   */
   char get( const char *entry, float &value,  float defaultValue );
+
+  /**
+   * Reads an entry from the group. A default value must be
+   * supplied. The return value indicates if the value was available
+   * (non-zero) or the default was used (0). 
+   *
+   * \param[in] entry name of entry
+   * \param[out] value returned from preferences or default value if none was set
+   * \param[in] defaultValue default value to be used if no preference was set
+   * \return 0 if the default value was used 
+   */
   char get( const char *entry, double &value, double defaultValue );
+
+  /**
+   * Reads an entry from the group. A default value must be
+   * supplied. The return value indicates if the value was available
+   * (non-zero) or the default was used (0). get() allocates memory of
+   * sufficient size to hold the value. The buffer must be free'd by 
+   * the developer using '<tt>free(value)</tt>'. 
+   *
+   * \param[in] entry name of entry
+   * \param[out] value returned from preferences or default value if none was set
+   * \param[in] defaultValue default value to be used if no preference was set
+   * \return 0 if the default value was used 
+   */
   char get( const char *entry, char *&value,  const char *defaultValue );
+
+  /**
+   * Reads an entry from the group. A default value must be
+   * supplied. The return value indicates if the value was available
+   * (non-zero) or the default was used (0). 
+   * '<tt>maxSize</tt>' is the maximum length of text that will be read. 
+   * The text buffer must allow for one additional byte for a trailling zero.
+   *
+   * \param[in] entry name of entry
+   * \param[out] value returned from preferences or default value if none was set
+   * \param[in] defaultValue default value to be used if no preference was set
+   * \param[in] maxSize maximum length of value plus one byte for a trailing zero
+   * \return 0 if the default value was used 
+   */
   char get( const char *entry, char *value,   const char *defaultValue, int maxSize );
+
+  /**
+   * Reads an entry from the group. A default value must be
+   * supplied. The return value indicates if the value was available
+   * (non-zero) or the default was used (0). get() allocates memory of
+   * sufficient size to hold the value. The buffer must be free'd by 
+   * the developer using '<tt>free(value)</tt>'. 
+   *
+   * \param[in] entry name of entry
+   * \param[out] value returned from preferences or default value if none was set
+   * \param[in] defaultValue default value to be used if no preference was set
+   * \param[in] defaultSize size of default value array
+   * \return 0 if the default value was used 
+   */
   char get( const char *entry, void *&value,  const void *defaultValue, int defaultSize );
+
+  /**
+   * Reads an entry from the group. A default value must be
+   * supplied. The return value indicates if the value was available
+   * (non-zero) or the default was used (0). 
+   * '<tt>maxSize</tt>' is the maximum length of text that will be read. 
+   *
+   * \param[in] entry name of entry
+   * \param[out] value returned from preferences or default value if none was set
+   * \param[in] defaultValue default value to be used if no preference was set
+   * \param[in] defaultSize size of default value array
+   * \param[in] maxSize maximum length of value
+   * \return 0 if the default value was used 
+   *
+   * \todo maxSize should receive the number of bytes that were read.
+   */
   char get( const char *entry, void *value,   const void *defaultValue, int defaultSize, int maxSize );
+
+  /**
+   * Returns the size of the value part of an entry.
+   *
+   * \return size of value
+   */
   int size( const char *entry );
 
+
+  /**
+   * Creates a path that is related to the preferences file and
+   * that is usable for application data beyond what is covered by
+   * Fl_Preferences.
+   *
+   * \param[out] path buffer for user data path
+   * \param[in] pathlen size of path buffer
+   * \return 0 if path was not created or pathname can't fit into buffer
+   */
   char getUserdataPath( char *path, int pathlen );
 
+
+  /**
+   * Write all preferences to disk. This function works only with
+   * the base preference group. This function is rarely used as
+   * deleting the base preferences flushes automatically.
+   */
   void flush();
 
   // char export( const char *filename, Type fileFormat );
   // char import( const char *filename );
 
+  /**
+   * 'Name' provides a simple method to create numerical or more complex 
+   * procedural names for entries and groups on the fly.
+   * 
+   * Example: <tt>prefs.set(Fl_Preferences::Name("File%d",i),file[i]);</tt>. 
+   *
+   * See <tt>test/preferences.cxx</tt> as a sample for writing arrays into preferences.<p>
+   * 'Name' is actually implemented as a class inside Fl_Preferences. It casts
+   * into <tt>const char*</tt> and gets automatically destroyed after the enclosing call
+   * ends.
+   */
   class FL_EXPORT Name {
+
     char *data_;
+
   public:
+
+    /**
+     * Create a numerical name.
+     */
     Name( unsigned int n );
+
+    /**
+     * Create a name using 'printf' style formatting.
+     */
     Name( const char *format, ... );
+
+    /**
+     * Return the Name as a c-string.
+     * \internal
+     */
     operator const char *() { return data_; }
     ~Name();
   };
diff --git a/FL/Xutf8.h b/FL/Xutf8.h
new file mode 100644
index 000000000..2b79ede30
--- /dev/null
+++ b/FL/Xutf8.h
@@ -0,0 +1,193 @@
+/*
+ * "$Id:  $"
+ *
+ * X11 UTF-8 text drawing functions.
+ *
+ *      Copyright (c) 2000-2003, OksiD Software, Jean-Marc Lienher
+ *                      All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *      Redistributions of source code must retain the above copyright
+ *      notice, this list of conditions and the following disclaimer.
+ *
+ *      Redistributions in binary form must reproduce the above copyright
+ *      notice, this list of conditions and the following disclaimer in the
+ *      documentation and/or other materials provided with the distribution.
+ *
+ *      Neither the name of OksiD Software nor the names of its contributors
+ *      may be used to endorse or promote products derived from this software
+ *      without specific prior written permission.
+ *
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER 
+ * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ *
+ *  Author: Jean-Marc Lienher ( http://oksid.ch )
+ */
+
+
+#ifndef _Xutf8_h
+#define _Xutf8_h
+
+#  ifdef __cplusplus
+extern "C" {
+#  endif
+
+#include <X11/X.h>
+#include <X11/Xlib.h>
+#include <X11/Xlocale.h>
+#include <X11/Xutil.h>
+
+typedef struct {
+	int nb_font;
+	char **font_name_list;
+	int *encodings;
+	XFontStruct **fonts;
+	Font fid;
+	int ascent;
+	int descent;
+	int *ranges;
+} XUtf8FontStruct;
+
+XUtf8FontStruct *
+XCreateUtf8FontStruct (
+	Display         *dpy, 
+	const char      *base_font_name_list); 
+
+void
+XUtf8DrawString(
+        Display         	*display,
+        Drawable        	d,
+        XUtf8FontStruct  *font_set,
+        GC              	gc,
+        int             	x,
+        int             	y,
+        const char      	*string,
+        int             	num_bytes);
+
+void
+XUtf8DrawRtlString(
+        Display         	*display,
+        Drawable        	d,
+        XUtf8FontStruct  *font_set,
+        GC              	gc,
+        int             	x,
+        int             	y,
+        const char      	*string,
+        int             	num_bytes);
+
+void
+XUtf8DrawImageString(
+        Display         *display,
+        Drawable        d,
+        XUtf8FontStruct         *font_set,
+        GC              gc,
+        int             x,
+        int             y,
+        const char      *string,
+        int             num_bytes);
+
+int
+XUtf8TextWidth(
+        XUtf8FontStruct  *font_set,
+        const char      	*string,
+        int             	num_bytes);
+int 
+XUtf8UcsWidth(
+	XUtf8FontStruct  *font_set,
+	unsigned int            ucs);
+
+int
+XGetUtf8FontAndGlyph(
+        XUtf8FontStruct  *font_set,
+        unsigned int            ucs,
+        XFontStruct     **fnt,
+        unsigned short  *id);
+	
+void
+XFreeUtf8FontStruct(
+        Display         	*dpy,
+        XUtf8FontStruct 	*font_set);
+
+
+int 
+XConvertUtf8ToUcs( 
+	const unsigned char 	*buf, 
+	int 			len, 
+	unsigned int 		*ucs);
+
+int 
+XConvertUcsToUtf8(
+	unsigned int 		ucs, 
+	char 			*buf);
+
+int 
+XUtf8CharByteLen(
+	const unsigned char 	*buf, 
+	int 			len);
+
+int 
+XCountUtf8Char(
+	const unsigned char *buf, 
+	int len);
+
+int 
+XFastConvertUtf8ToUcs( 
+	const unsigned char 	*buf, 
+	int 			len, 
+	unsigned int 		*ucs);
+
+long 
+XKeysymToUcs(
+	KeySym 	keysym);
+
+int
+XUtf8LookupString(
+    XIC                 ic,
+    XKeyPressedEvent*   event,
+    char*               buffer_return,
+    int                 bytes_buffer,
+    KeySym*             keysym,
+    Status*             status_return);
+
+unsigned short 
+XUtf8IsNonSpacing(
+	unsigned int ucs);
+
+unsigned short
+XUtf8IsRightToLeft(
+        unsigned int ucs);
+
+
+int 
+XUtf8Tolower(
+        int ucs);
+
+int 
+XUtf8Toupper(
+        int ucs);
+
+
+#  ifdef __cplusplus
+}
+#  endif
+
+#endif
+
+/*
+ *  End of "$Id: $".
+ */ 
+
diff --git a/FL/fl_utf8.H b/FL/fl_utf8.H
new file mode 100644
index 000000000..7f93e1059
--- /dev/null
+++ b/FL/fl_utf8.H
@@ -0,0 +1,248 @@
+//
+// Copyright 1998-2005 by Bill Spitzak and others.
+//
+// This library is free software; you can redistribute it and/or
+// modify it under the terms of the GNU Library General Public
+// License as published by the Free Software Foundation; either
+// version 2 of the License, or (at your option) any later version
+// with exceptions that allow sub-classing and static linking in
+// non-LGPL compliant software. These exceptions are subject to
+// conditions, see the FLTK License for more details.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the FLTK
+// License for more details.
+//
+// You should have received a copy of the FLTK License along with
+// this library; if not, write to  OksiD Software, Jean-Marc Lienher,
+// Rue de la Cheminee 1, CH-2065 Savagnier, Switzerland.
+//
+// Please report all bugs and problems to "oksid@bluewin.ch".
+//
+
+// Merged in some functionality from the fltk-2 version. IMM.
+// The following code is an attempt to merge the functions incorporated in FLTK2
+// with the functions provided in OksiD's fltk-1.1.6-utf8 port
+
+/*** NOTE : all functions are LIMITED to 24 bits Unicode values !!! ***/
+
+#ifndef _HAVE_FL_UTF8_HDR_
+#  define _HAVE_FL_UTF8_HDR_
+#  include <stdio.h>
+#  include <string.h>
+#  include <stdlib.h>
+
+#  ifndef FL_EXPORT
+#    if defined(FL_DLL) && defined(_MSC_VER)
+#      ifdef FL_LIBRARY
+#        define FL_EXPORT   __declspec(dllexport)
+#      else
+#        define FL_EXPORT   __declspec(dllimport)
+#      endif /* FL_LIBRARY */
+#    else
+#      define FL_EXPORT
+#   endif /* FL_DLL && _MSC_VER */
+#  endif /* FL_EXPORT */
+
+
+
+#  if __APPLE__
+#    include <wchar.h>
+#    include <sys/stat.h>
+#  else
+#    include <sys/types.h>
+#    include <sys/stat.h>
+#    ifndef _WIN32
+#      include "Xutf8.h"
+#      include <X11/Xlocale.h>
+#      include <X11/Xlib.h>
+#    endif
+#    include <locale.h>
+#  endif
+
+
+
+#  if defined(WIN32)
+#    include <ctype.h>
+#    define xchar wchar_t
+#  else
+#   if __APPLE__
+#     define xchar wchar_t
+#   else
+#     define xchar unsigned short
+#   endif
+#  endif
+
+#  if defined(WIN32) && !defined(FL_DLL)
+#    undef strdup
+#    define strdup _strdup
+#    undef putenv
+#    define putenv _putenv
+#    undef stricmp
+#    define stricmp _stricmp
+#    undef strnicmp
+#    define strnicmp _strnicmp
+#    undef hypot
+#    define hypot _hypot
+#    undef chdir
+#    define chdir _chdir
+#  endif
+
+#  ifdef __cplusplus
+extern "C" {
+#  endif
+
+/* F2: comes from FLTK2 */
+/* OD: comes from OksiD */
+
+/* F2: How many bytes will be used to encode this wide character as UTF8? */
+FL_EXPORT int fl_utf8bytes(unsigned ucs);
+
+/* OD: returns the byte length of the first UTF-8 char sequence (returns -1 if not valid) */
+FL_EXPORT int fl_utf8len(char c);
+
+/* OD: returns the number of Unicode chars in the UTF-8 string */
+FL_EXPORT int fl_utf_nb_char(const unsigned char *buf, int len);
+
+/* F2: Convert the next UTF8 char-sequence into a Unicode value (and say how many bytes were used) */
+FL_EXPORT unsigned fl_utf8decode(const char* start, const char* end, int* len);
+
+/* F2: Encode a Unicode value into a UTF8 sequence, return the number of bytes used */
+FL_EXPORT int fl_utf8encode(unsigned ucs, char* buf);
+
+/* F2: Move forward to the next valid UTF8 sequence start betwen start and end */
+FL_EXPORT const char* fl_utf8fwd(const char* pos, const char* start, const char* end);
+
+/* F2: Move backward to the previous valid UTF8 sequence start */
+FL_EXPORT const char* fl_utf8back(const char* pos, const char* start, const char* end);
+
+/* F2: Convert a UTF8 string into UTF16 */
+FL_EXPORT unsigned fl_utf8toUtf16(const char* src, unsigned srclen, unsigned short* dst, unsigned dstlen);
+
+/* F2: Convert a UTF8 string into a wide character string - makes UTF16 on win32, "UCS4" elsewhere */
+FL_EXPORT unsigned fl_utf8towc(const char *src, unsigned srclen, wchar_t *dst, unsigned dstlen);
+
+/* F2: Convert a wide character string to UTF8 - takes in UTF16 on win32, "UCS4" elsewhere */
+FL_EXPORT unsigned fl_utf8fromwc(char *dst, unsigned dstlen, const wchar_t *src, unsigned srclen);
+
+/* F2: Convert a UTF8 string into ASCII, eliding untranslatable glyphs */
+FL_EXPORT unsigned fl_utf8toa (const char *src, unsigned srclen, char *dst, unsigned dstlen);
+/* OD: convert UTF-8 string to latin1 */
+//FL_EXPORT int fl_utf2latin1(const unsigned char *src, int srclen, char *dst);
+
+/* F2: Convert 8859-1 string to UTF8 */
+FL_EXPORT unsigned fl_utf8froma (char *dst, unsigned dstlen, const char *src, unsigned srclen);
+/* OD: convert latin1 str to UTF-8 */
+//FL_EXPORT int fl_latin12utf(const unsigned char *src, int srclen, char *dst);
+
+/* F2: Returns true if the current O/S locale is UTF8 */
+FL_EXPORT int fl_utf8locale();
+
+/* F2: Examine the first len characters of src, to determine if the input text is UTF8 or not
+ * NOTE: The value returned is not simply boolean - it contains information about the probable
+ * type of the src text. */
+FL_EXPORT int fl_utf8test(const char *src, unsigned len);
+
+/* OD: Return true if the character is non-spacing */
+FL_EXPORT unsigned int fl_nonspacing(unsigned int ucs);
+
+/* F2: Convert UTF8 to a local multi-byte encoding - mainly for win32? */
+FL_EXPORT unsigned fl_utf8to_mb(const char *src, unsigned srclen, char *dst, unsigned dstlen);
+/* OD: Convert UTF8 to a local multi-byte encoding */
+FL_EXPORT char* fl_utf2mbcs(const char *src);
+
+/* F2: Convert a local multi-byte encoding to UTF8 - mainly for win32? */
+FL_EXPORT unsigned fl_utf8from_mb(char *dst, unsigned dstlen, const char *src, unsigned srclen);
+/* OD: Convert a local multi-byte encoding to UTF8 */
+//FL_EXPORT char* fl_mbcs2utf(const char *src);
+
+/*****************************************************************************/
+#ifdef WIN32
+/* OD: Attempt to convert the UTF8 string to the current locale */
+FL_EXPORT char *fl_utf8_to_locale(const char *s, int len, unsigned int codepage);
+
+/* OD: Attempt to convert a string in the current locale to UTF8 */
+FL_EXPORT char *fl_locale_to_utf8(const char *s, int len, unsigned int codepage);
+#endif
+
+/*****************************************************************************/
+// The following functions are intended to provide portable, UTF8 aware
+// versions of standard functions
+
+/* OD: UTF8 aware strncasecmp - converts to lower case Unicode and tests */
+FL_EXPORT int fl_utf_strncasecmp(const char *s1, const char *s2, int n);
+
+/* OD: UTF8 aware strcasecmp - converts to Unicode and tests */
+FL_EXPORT int fl_utf_strcasecmp(const char *s1, const char *s2);
+
+/* OD: return the Unicode lower case value of ucs */
+FL_EXPORT int fl_tolower(unsigned int ucs);
+
+/* OD: return the Unicode upper case value of ucs */
+FL_EXPORT int fl_toupper(unsigned int ucs);
+
+/* OD: converts the UTF8 string to the lower case equivalent */
+FL_EXPORT int fl_utf_tolower(const unsigned char *str, int len, char *buf);
+
+/* OD: converts the UTF8 string to the upper case equivalent */
+FL_EXPORT int fl_utf_toupper(const unsigned char *str, int len, char *buf);
+
+/* OD: Portable UTF8 aware chmod wrapper */
+FL_EXPORT int fl_chmod(const char* f, int mode);
+
+/* OD: Portable UTF8 aware access wrapper */
+FL_EXPORT int fl_access(const char* f, int mode);
+
+/* OD: Portable UTF8 aware stat wrapper */
+FL_EXPORT int fl_stat( const char *path, struct stat *buffer );
+
+/* OD: Portable UTF8 aware getcwd wrapper */
+FL_EXPORT char* fl_getcwd( char *buf, int maxlen);
+
+/* OD: Portable UTF8 aware fopen wrapper */
+FL_EXPORT FILE *fl_fopen(const char *f, const char *mode);
+
+/* OD: Portable UTF8 aware system wrapper */
+FL_EXPORT int fl_system(const char* f);
+
+/* OD: Portable UTF8 aware execvp wrapper */
+FL_EXPORT int fl_execvp(const char *file, char *const *argv);
+
+/* OD: Portable UTF8 aware open wrapper */
+FL_EXPORT int fl_open(const char* f, int o, ...);
+
+/* OD: Portable UTF8 aware unlink wrapper */
+FL_EXPORT int fl_unlink(const char *f);
+
+/* OD: Portable UTF8 aware rmdir wrapper */
+FL_EXPORT int fl_rmdir(const char *f);
+
+/* OD: Portable UTF8 aware getenv wrapper */
+FL_EXPORT char* fl_getenv(const char *name);
+
+/* OD: Portable UTF8 aware execvp wrapper */
+FL_EXPORT int fl_mkdir(const char* f, int mode);
+
+/* OD: Portable UTF8 aware rename wrapper */
+FL_EXPORT int fl_rename(const char* f, const char *t);
+
+
+/* OD: Given a full pathname, this will create the directory path needed to hold the file named */
+FL_EXPORT void fl_make_path_for_file( const char *path );
+
+/* OD: recursively create a path in the file system */
+FL_EXPORT char fl_make_path( const char *path );
+
+/*****************************************************************************/
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+
+#endif // _HAVE_FL_UTF8_HDR_
+
+//
+// End of "$Id: $".
+//