Introduction
------------
This library is a collection of classes which have been created by the FOX GUI user community
to extend the FOX GUI library, and is plainly called FOXEX (or FXEX), for FOX Extended.  It
is intended for this library to extend the base FOX implementation with functionality
not necessarily intended (or suitable) for a GUI library, as well as adding extra widgets
which are not really orthogonal to existing FOX widgets.

In particular, it specifically addresses some of the following issues:
- provides a location for ideas to be extended, so that others may contribute, which may or
  may not be applicable/suitable for the standard FOX library
- implements non-widget functionality (such as sockets/threads)
- provides more widgets
- provides adapter classes for connecting to other libraries

Note:
This library requires modifications to FOX before it can become useable, since it makes a
few minor assumptions about the base FOX library.


Compiling
---------
Before you start, you will need to apply a patch set to the existing FOX distribution.

1. Ensure that your existing FOX version has been 'configure'd correctly.
   It wont matter if it has already been installed.
2. You just need to run the following command, substituting your path to the 
   latest development version of FOX (1.1.27), from the directory this README is in.

   ./apply_patch.sh <path to fox-1.1.{latest}>

3. Now make (or re-make) FOX using:

   cd <path to fox-1.1.{latest}>
   make 
   make install

4. Now you are ready for FOXEX:

   cd <path to fxex-0.0.{latest}>
   ./configure
   make
   make install

   You can override certain build features; use the '--help' command line options of
   'configure' to see what can be adjusted.

Note:
1. FXEX is designed to apply against the latest FOX development release.  The FOX stable
   release is currently unsupported since, if you are using FXEX, it is more unstable than
   the FOX unstable releases...  :-)
2. Patches are currently provided individually, so as to make merging with Jereon's tree
   easier to understand.  They were created with the 'diff -c' command.


What this library provides
--------------------------
As with any free software, the best source of documentation is the source code.  Other than
that, the file 'ClassListing' may contain a brief listing of the classes available, until
I get the auto-documentation and some hand written docs available.

A brief summary:
- generic IO support, such as serial port, socket client/server, file IO (unix/win32)
- thread objects and functions, thread-safe variables, mutex/condition/barriers/atomics
- more widgets
- enhanced stream support
- dynamic library loader object
- database conectivity
- various other utility classes


Database support
----------------
Giancarlo Formicuccia is working on providing adapter classes to allow FOX applications to
connect to various backend databases.  A 'first round' implementation has been provided to
allow people to make suggestions.  The implementation / design is based on the Perl DBD/DBI
model.  This design seperates the 'data manipulation' part from the 'database access' part.
This allows generic functionality such as handling row-level data storage, handling and type
conversion, from the database specific access technique.

So far, there is support for ODBC using either MySQL or PostgreSQL as the database backend.
Native backends for each database source is still to be worked on, but at least ODBC allows
developers to connect to Win32 based SQL servers, with any luck.

There is still much work to do for database support.  We need a new 'browse' widget - something
similar to an FXTable but make FOX event calls, back into the FXDatabaseQuery object, to
request more data.

Also suggested is support for flat text files (either via ODBC using the unixODBC library) or
by using the FXFileIO class to support database style access for simple files.


Sockets & I/O
-------------
Socket support is currently tested for Unix, but I am hoping that my implementation
for sockets (and serial ports and files), will be easy to port to Win32.  The design
is based on an 'network events / IO events'.  The idea is that, just as you would get
a 'user event' such as a mouse click, you could also receive a network/IO event.  The
resultant application implementation would then just 'handle the event' just as it
would for any other FOX event.  The interesting point is that in this implementation,
it makes implementing socket / IO interfaces, next to trivial.

See the tests directory for a socket client and a corresponding socket server demo
applications.


Socket/IO Stream
----------------
Since we now have support for sockets, you can use the FXIOStream class to serialise /
de-serialise data over a socket.  To use it you will need to:

1. create an FXSocket object which FXIOStream can use as the I/O channel.
2. You may want to connect the socket to the destination, thus waiting for the SEL_OPENED
   socket event, so that you can correctly handle error conditions.
3. Create an FXIOStream object.
4. Open the stream, using the socket object as the IO channel.
5. Serialise / De-serialise the data over the socket, eg iostream << fox_object
6. Close the stream
7. Close the socket


Threading
---------
An implementation of threads for FOX is called the FXExThreads package.  FXExThread's includes
classes for mutex's, condition variables, semaphores, threads and thread events. It is based
on the freely available threads package called 'Omni Threads'.

I am not quite happy with the FXExThreads threading implementation, since it doesn't fully
utilise the existing FOX event mechanism.  Also, the public interface is not clean.

As such, I re-implemented thread support using some of the more useful parts of the
FXExThread package, plus some of my own implementation.  As such, you can use the FXThread
framework to communicate from your worker thread to the main thread, via FOX messages, or via
normal inter-thread communication mechanisms (eg: condition variables, atomic variables, etc).

Importantly, the FOX event mechanism is re-enterent safe for reads, so its just a matter
of serialising access to your own methods, to make your application thread-safe.  FXEX
provides thread serialisation and synchronisation mechanisms, to help simplify this
problem.


XML support
-----------
If you do some searching around the internet for XML parsers and any documentation, one
of the first things you will notice is that the libraries are based on two techniques.

The first is called 'DOM' (Document Object Model), which basically means that you read the
entire file to generate an in-memory version of the file.  The problem with this is that if
the file is huge (or possibly never-ending), the DOM technique can consume large amounts of
memory (for large files), even before we have an actual in-memory version of the document
tree.

The second is call 'SAX' (Simple API for XML).  This techniques overcomes the problem of
consuming large amounts of memory, since it works by having the file parser generate events
for each known <tag> (ie angle brace pairs).

You could probably guess as to which technique I am using; use the SAX technique - it fits
in very well with the FOX event mechanism.

So far I have implemented the stream reader (FXXmlReader), and the XML event generator
(FXXmlParser).  The FXXmlReader generates SEL_TAG events for each matching pair of angle
braces.  Since I keep no state of start-tag / stop-tag, this technique allows arbitrary
tag locations within the file.  The FXXmlParser generates the appropriate XML events
(eg SEL_BEGIN:ID_TAG, SEL_END:ID_DOCUMENT).  The intention is to next create a HTML
event generator (derived from FXXmlParser), which generates HTML events (such as
SEL_BEGIN:ID_HTML, SEL_END:ID_BODY, SEL_COMMAND:ID_IMG).  Note that this is a bit of a hack
at the moment; I will need to do some more on it one day...


Classes needed
--------------
If you would like to contribute classes, forward them to me so I can add them; make sure
to add some documentation to it...  Also, it makes the merge process a lot easier for me,
if the style follows the existing FOX style.

Examples of new classes which could be built:

FXProxy:
  This class receives messages (using a protocol/transfer mechanism yet to be defined, but
  could probably use the following FXFoxEvent class via a socket stream, or maybe
  an X/GDI based mechanism such as that used by XDND/DND), which it then forwards onto
  the target application in a similar way as FXApp forwards on display events such as 
  mouse clicks, repaints, etc.  Conversly, a message can be generated from the app and
  forwarded to the proxy, from which the proxy forwards it back upstream to the source 
  application.
    
FXFoxEvent:
  This could likely be a singleton which may create any other type of FOX event.

FXCommandLineParser:
  A dictionary which contains the command line arguments.
  It could be queried for set values; it could probably modify an FXSettings database.

FXRegistryMonitor - utility
  Monitors the registry for changes, generating an event when it changes.

FXMemoryDatabase
  Some form of in-memory database that can be serialised on application exit
  Possibly some form of database/cell fields - maybe that could be used for cells
  in an FXTable

FXDatabaseBrowse
  A database browse widget, is a widget that shows a viewable section of a database view.
  It would probably be derived from an FXScrollArea.  It would take an FXDatabase object
  which it uses to query, each time it needs to scroll.  It should also be able to have
  its view marked as dirty, if the contents of the database view changes.


Compilation Notes
-----------------
Sometimes people need to link apps to stdc++ when using the latest gcc, like this:

 -lsupc++  [or -lstdc++]  and  -lgcc_s



Mathew Robertson <mailto:mathew at users.sf.net>
Send your comments and suggestions in!

