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

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();
 };
 

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();
   };

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: $".
+ */ 
+

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: $".
+//

documentation/index.dox

@@ -0,0 +1,101 @@
+/**
+
+\mainpage FLTK Programming Manual
+
+<TABLE BGCOLOR="#9f9f9f" CELLPADDING="8" CELLSPACING="0" SUMMARY="TITLE BAR" WIDTH="700">
+<TR>
+	<TD VALIGN="MIDDLE">
+  \image html FL200.gif
+	<TD ALIGN="CENTER" VALIGN="MIDDLE">
+	<H1>FLTK 1.3.0 Programming Manual</H1>
+	<P>Revision 8 by Michael Sweet, Craig P. Earls,<br>Matthias Melcher, and Bill Spitzak<BR>
+	Copyright 1998-2008 by Bill Spitzak and others.</P>
+	</TD>
+</TR>
+<TR>
+	<TH COLSPAN=2>This software and manual are provided under the terms of the GNU Library General Public License. Permission is granted to reproduce this manual or any portion for any purpose, provided this copyright and permission notice are preserved.</TH>
+</TR>
+</TABLE>
+
+<TABLE BGCOLOR="#9f9fef" CELLPADDING="8" CELLSPACING="0" SUMMARY="Table of Contents" WIDTH="700">
+<TR>
+	<TD ALIGN="LEFT" VALIGN="TOP"><B>
+ \subpage preface
+        </B>
+	<BR>
+	<BR>
+	<B><A HREF="intro.html#intro">1 - Introduction to FLTK</A></B>
+	<BR>
+	<BR>
+	<B><A HREF="basics.html#basics">2 - FLTK Basics</A></B>
+	<BR>
+	<BR>
+	<B><A HREF="common.html#common">3 - Common Widgets and Attributes</A></B>
+	<UL>
+	<LI><A HREF="drawing.html#colors">Colors</A></LI>
+	<LI><A HREF="common.html#boxtypes">Box Types</A></LI>
+	<LI><A HREF="common.html#labels">Labels and Label Types</A></LI>
+	<LI><A HREF="drawing.html#images">Images</A></LI>
+	<LI><A HREF="Fl_Pixmap.html#Fl_Pixmap">class Fl_Pixmap</A></LI>
+	</UL>
+	<B><A HREF="editor.html#editor">4 - Designing a Simple Text Editor</A></B>
+	<BR>
+	<BR>
+	<B><A HREF="drawing.html#drawing">5 - Drawing Things in FLTK</A></B>
+	<BR>
+	<BR>
+	<B><A HREF="events.html#events">6 - Handling Events</A></B>
+	<UL>
+	<LI><A HREF="events.html#event_xxx">Fl::event_*() methods</A></LI>
+	<LI><A HREF="events.html#propagation">Event Propagation</A></LI>
+	</UL>
+	<B><A HREF="subclassing.html#subclassing">7 - Adding and Extending
+	Widgets</A></B>
+	<BR>
+	<BR>
+	<B><A HREF="opengl.html#opengl">8 - Using OpenGL</A></B>
+	</TD>
+	<TD ALIGN=LEFT VALIGN=TOP>
+	<B><A HREF="fluid.html#FLUID">9 - Programming with FLUID</A></B>
+	<UL>
+	<LI><A HREF="fluid.html#widget_attributes">Widget Attributes</A></LI>
+	<LI><A HREF="fluid.html#widget_attributes">Selecting Moving Widgets</A></LI>
+	<LI><A HREF="fluid.html#images">Image Labels</A></LI>
+	</UL>
+	<B><A HREF="advanced.html#advanced">10 - Advanced FLTK</A></B>
+	<BR>
+	<BR>
+	<B><A HREF="classes.html">A - Class Reference</A></B>
+	<BR>
+	<BR>
+	<B><A HREF="globals_func.html">B - Function Reference</A></B>
+	<BR>
+	<BR>
+	<B><A HREF="enumerations.html#Enumerations">C - FLTK Enumerations.H</A>
+	</B>
+	<BR>
+	<BR>
+	<B><A HREF="glut.html#glut">D - GLUT Compatibility</A></B>
+	<UL>
+	<LI><A HREF="glut.html#Fl_Glut_Window">class Fl_Glut_Window</A></LI>
+	</UL>
+	<B><A HREF="forms.html#forms">E - Forms Compatibility</A></B>
+	<BR>
+	<BR>
+	<B><A HREF="osissues.html#osissues">F - Operating System Issues</A></B>
+	<BR>
+	<BR>
+	<B><A HREF="migration.html">G - Migrating Code from FLTK 1.0.x</A></B>
+	<BR>
+	<BR>
+	<B><A HREF="license.html#license">H - Software License</A></B>
+	<BR>
+	<BR>
+	<B><A HREF="examples.html#examples">I - Example Source Code</A></B>
+	</TD>
+</TR>
+</TABLE>
+
+*/
+
+

documentation/preface.dox

@@ -0,0 +1,108 @@
+/**
+
+ \page preface Preface
+
+<P>This manual describes the Fast Light Tool Kit (&quot;FLTK&quot;)
+version 1.1.8, a C++ Graphical User Interface
+(&quot;GUI&quot;) toolkit for UNIX, Microsoft Windows and MacOS. Each
+of the chapters in this manual is designed as a tutorial for
+using FLTK, while the appendices provide a convenient reference
+for all FLTK widgets, functions, and operating system
+interfaces.</P>
+
+<P><B>This manual may be printed, modified, and/or used under
+the terms of the FLTK license provided in <A
+HREF="license.html">Appendix A</A>.</B>
+
+<H2>Organization</H2>
+
+<P>This manual is organized into the following chapters and appendices:</P>
+
+<UL>
+
+	<LI><A HREF="intro.html#intro">Chapter 1 - Introduction to FLTK</A></LI>
+
+	<LI><A HREF="basics.html#basics">Chapter 2 - FLTK Basics</A></LI>
+
+	<LI><A HREF="common.html#common">Chapter 3 - Common Widgets and Attributes</A></LI>
+
+	<LI><A HREF="editor.html#editor">Chapter 4 - Designing a Simple Text
+	Editor</A></LI>
+
+	<LI><A HREF="drawing.html#drawing">Chapter 5 - Drawing Things in FLTK</A></LI>
+
+	<LI><A HREF="events.html#events">Chapter 6 - Handling Events</A></LI>
+
+	<LI><A HREF="subclassing.html#subclassing">Chapter 7 - Extending and
+	Adding Widgets</A></LI>
+
+	<LI><A HREF="opengl.html#opengl">Chapter 8 - Using OpenGL</A></LI>
+
+	<LI><A HREF="fluid.html#FLUID">Chapter 9 - Programming With FLUID</A></LI>
+
+	<LI><A HREF="widgets.html#widgets">Appendix A - Class Reference</A></LI>
+
+	<LI><A HREF="functions.html#functions">Appendix B - Function Reference</A></LI>
+
+	<LI><A HREF="enumerations.html#Enumerations">Appendix C - Enumeration
+	Reference</A></LI>
+
+	<LI><A HREF="glut.html#glut">Appendix D - GLUT Compatibility</A></LI>
+
+	<LI><A HREF="forms.html#forms">Appendix E - Forms Compatibility</A></LI>
+
+	<LI><A HREF="osissues.html#osissues">Appendix F - Operating System Issues</A></LI>
+
+	<LI><A HREF="migration.html">Appendix G - Migrating from FLTK 1.0.x to FLTK 1.1.x</A></LI>
+
+	<LI><A HREF="license.html#license">Appendix H - Software License</A></LI>
+
+	<LI><A HREF="examples.html#examples">Appendix I - Example Source Code</A></LI>
+
+</UL>
+
+<H2>Conventions</H2>
+
+<P>The following typeface conventions are used in this manual:</P>
+
+<UL>
+	<LI>Function and constant names are shown in <B><TT>bold courier type</TT></B></LI>
+
+	<LI>Code samples and commands are shown in <TT>regular courier type</TT></LI>
+
+</UL>
+
+<H2>Abbreviations</H2>
+
+<P>The following abbreviations are used in this manual:</P>
+
+<DL>
+
+	<DT>X11</DT>
+	<DD>The X Window System version 11.</DD>
+
+	<DT>Xlib</DT>
+	<DD>The X Window System interface library.</DD>
+
+	<DT>WIN32</DT>
+	<DD>The Microsoft Windows 32-bit Application Programmer's Interface.</DD>
+
+	<DT>MacOS</DT>
+	<DD>The Apple Macintosh OS 8.6 and later, including OS X.</DD>
+
+</DL>
+
+<H2>Copyrights and Trademarks</H2>
+
+<P>FLTK is Copyright 1998-2006 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 H</A>.</P>
+
+<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. Apple, Macintosh, MacOS, and Mac OS X are
+registered trademarks of Apple Computer, Inc.</P>
+
+*/
+