TnFOX documentation

v0.88

Welcome to TnFOX! TnFOX is an extension of the FOX portable GUI toolkit and it provides enhanced facilities and features mainly for the upcoming Tn library. It is greatly hoped that others will find use of TnFOX outside its remit within Tn.

TnFOX could not exist without the efforts of those who wrote FOX, and my thanks go especially to Jeroen van der Zijp who owns copyright of the lion's share of the code. You can find the original FOX toolkit at http://www.fox-toolkit.org/ plus the full list of authors in the AUTHORS file. You can find TnFOX-specific acknowledgements here

TnFOX absorbs the latest improvements to the core FOX library on a regular basis (this version is derived from v1.6.33), and the extensions listed below are designed to not interfere with that process where possible (hence some functionality has not been folded into FOX where it otherwise would). All extension code is (C) 2001-2008 Niall Douglas and all code rests under the same licence as FOX but with one extra restriction - I do not permit any code copyrighted to me to be "promoted" to the GPL so therefore section 3 of the LGPL does not apply to code (C) Niall Douglas. If you want to know more about the licensing implications of the FOX licence, see Jeroen's useful comments about the matter in the LICENCE-ADDENDUM.txt file and you can find out more about mine in the LICENCE-ADDENDUM2.txt

To get you started, here are a list of common start points:

  1. All classes in TnFOX and Non-class entities. By category:
    GUI classes Layout classes Resource classes Operational classes
    Convenience classes Container classes Qt Template Library OpenGL classes
    File type i/o devices Synchronous i/o devices

  2. A list of files in TnFOX. The ones with descriptions are entirely written by me.
  3. All class methods individually in TnFOX (long) and All non-class items individually (long)
  4. A list of all deprecated facilities
  5. Go to the TnFOX homepage [external]

Extended documentation:

All extensions to FOX are fully documented under doxygen (http://www.doxygen.net/). You will find a test framework of the extensions (which also serve as code examples) in the TestSuite directory.

Who should NOT use TnFOX?

Who should use TnFOX?

Detailed list of enhancements

  1. Qt-like automated human language translation
    When combined with FX::QTrans, human-language translation is now easy as pie! Simply wrap all of your user-visible string literals with tr(), extract into a text file using the provided utility CppMunge.py and add your translations. You can then choose to embed the file, or place it next to the executable. You can even place translations within DLL's and arbitrarily load and unload them!

  2. FX::FXStream now works with a FX::QIODevice & 64 bit file i/o is now used throughout
    A FXfval now holds a file pointer or size, ready for the transition to 128 bit disc i/o around 2025. The i/o structure is now based around a Qt-compatible QIODevice which is much much more flexible than the old FOX structure and for backwards compatibility FOX's FX::FXFileStream, FX::FXMemoryStream & FX::FXGZStream have been rewritten to use FX::QFile + FX::FXStream, FX::QBuffer + FX::FXStream & FX::QGZipDevice + FX::FXStream combinations respectively (note that their use in new code is deprecated).

  3. Enhanced i/o facilities
    FX::QPipe provides a feature-rich portable named pipe across all platforms and FX::QLocalPipe provides an intra-process pipe. FX::QBlkSocket and FX::QHostAddress provide Qt-compatible network access including full IPv4 and IPv6 support. FX::QGZipDevice provides a transparent gzip format compressor and decompressor which uses LZW compression to substantially decrease data size. FX::QBZip2Device provides a transparent bzip2 format compressor and decompressor which decreases data size even further.

  4. Improved Time facilities
    FX::FXTime provides an enhanced portable, microsecond granularity date & time system from the 1st January year 0 until the 20th February, year 584,556 with knowledge of local time zones. This support extends throughout the file system support on operating systems with better than one second granularity (Windows, FreeBSD). FX::FXProcess provides portable millisecond and nanosecond counters for extremely accurate timing.

  5. Improved User Interface facilities
    TnFOX understands the user's handedness (reported via FX::FXProcess::userHandedness()) as do TnFOX's GUI extension classes. FX::FXPrimaryButton is a primary button in a dialog which orientates itself towards the user's handedness and bottom plus dispatches TnFOX's apply/reset protocol which lets compliant widgets apply themselves to their data or restore the correct representation. FX::FXHandedInterfaceI implements an interface with a handed primary button well and further automates the apply/reset protocol. Small screens are better supported with dynamic layout spacing via FX::FXWindow::defaultPadding() and FX::FXWindow::defaultSpacing() plus extra command line arguments such as -fxscreenscale and -fxscreensize. There are a number of convenient implementations of handed interfaces such as FX::FXExceptionDialog, FX::FXHandedDialog, FX::FXHandedPopup and FX::FXHandedMsgBox.

  6. Full strength encryption facilities
    FX::QSSLDevice is built upon the excellent OpenSSL library and provides integrated full strength encryption facilities which can work with any of the other i/o devices in TnFOX. Both communications and file data may be encrypted with any supported cipher and key length. File data can be encrypted by AES or Blowfish symmetric encryption and also by RSA public key asymmetric encryption. FX::FXSSLKey is a container for symmetric keys and FX::FXSSLPKey is a container for asymmetric keys and both can be loaded and saved plus compatibility facilities with other programs through X509/PEM file support. Furthermore, TnFOX provides a cross-platform entropy gatherer (FX::Secure::Randomness) which ensures up to 8192 bits of randomness is available plus a number of cryptographically useful routines such as FX::QIODevice::shredData().

  7. Superior provision of host OS facilities portably
    FX::FXACL and FX::FXACLEntity provide a portable method of setting detailed access control list based security on those platforms which support it and a reasonable emulation for everything else. FX::QDir and FX::QFileInfo are mostly Qt compatible classes which permit easy enumeration and traversal of directories as well as obtaining detailed information about files. FX::FXFSMonitor permits portable monitoring of directories for changes. FX::FXProcess contains a wide variety of miscellaneous useful functions, and FX::FXWinShellLink + FX::FXWinJunctionPoint provide support for all possible forms of file shortcuts available on Windows (with full POSIX emulation!).

    A self-optimising metaprogramming implementation of hardware-assisted math operations is provided in the FX::Maths namespace. These make full use of any parallel mathematics hardware.

  8. QList, QPtrList, QPtrListIterator, QValueList, QDict, QDictIterator, QIntDict, QIntDictIterator, QPtrDict, QPtrDictIterator, QPtrVector, QPtrVectorIterator, QMemArray, QByteArray, QStringList, QFileInfoList
    All implemented as thunks to the STL. I've personally continued to use these in new code as the pointer holding classes have auto-deletion, something I find very useful. There is also the Qt-compatible totally generic Least Recently Used (LRU) cache class FX::FXLRUCache with specialisations for FX::QCache and FX::QIntCache.

  9. Ordered static initialisation
    Make static data initialisation order problems disappear! With FX::FXProcess' facilities for declaring dependencies between static data, you always guarantee objects will exist when you need them! FX::FXProcess can be initialised without FX::FXApp, so if you write a command-line based program using TnFOX then you can make use of all its facilities without invoking GUI code
    Note:
    You must always initialise a FXProcess first thing in your main() - failure to do this causes many of the extensions to fail
  10. Exception Handling
    With support for nested exceptions, automatic error code extraction, automatic failed operation retries, extra debug information and a host of useful error checking & input validation macros, FX::FXException provides facilities for superior robustness and stress-testing. FX::FXExceptionDialog provides a useful standard window with which to report an error to the user. Writing fully exception aware code is made much easier with classes such as FX::FXPtrHold and transaction rollbacks . Memory leak detection is made much easier on Microsoft compilers with FXMemDbg.h, integrated support for MSVC's CRT debug library's memory leak checking.

  11. Multithreading
    FX::FXAtomicInt, FX::QWaitCondition, FX::QMutex, FX::QShrdMemMutex, FX::QRWMutex, FX::QMtxHold and FX::FXZeroedWait all are written for the optimum in efficiency and features. FX::QThreadLocalStorage provides a portable and C++ friendly interface to host OS TLS facilities. Even on platforms without POSIX threads support, they can be compiled into placeholder functionality so that the rest of the library remains useful. FX::QThread provides a wealth of features, including cleanup handlers, self-destruction, names, parent-child relationships, portable priority, exit codes and per-thread atexit() handlers. FX::QThreadPool provides pools of worker threads capable of accepting jobs (FX::Generic::BoundFunctor) whether for immediate execution or for delayed (timed) execution.

  12. Generic programming support
    In case you didn't already know, the C++ compiler can be programmed to write code for you (which obviously is useful). TnFOX in a number of places uses policies (which let you configure the code generation) and traits (where TnFOX configures itself). Furthermore facilities are provided for extremely generic code writing such as typelists and compile-time introspection of code. While TnFOX doesn't go as far as Boost or Loki, it does provide the most useful compile-time programming support tools and has borrowed ideas from both. For more information, see the page about generic tools

  13. Inter Process Communication (IPC)
    Inter-process communications become easy with TnFOX's powerful but lightweight IPC framework which combines with arbitrary i/o device's which provide socket, named pipe and encrypted data transport. Automatic endian conversion, optional compression and modular extensibility also feature. The core of TnFOX's IPC is FX::FXIPCMsgRegistry which provides a messaging namespace of FX::FXIPCMsg subclasses, ensuring that old and new binaries work together seamlessly. FX::FXIPCChannel is a base class implementing almost everything you need to get started immediately. For more information, see the page about Inter Process Communication For running traditional command line programs such as compilers whilst redirecting standard input and output, FX::QChildProcess is provided.

  14. SQL Database support
    FX::TnFXSQLDB is the primary class for accessing SQL databases but unlike other implementations, it has transparent BLOB support for storing & retrieving arbitrary C++ object instances via metaprogramming. It is easy to write your own driver, and prewritten drivers come for SQLite3 (of which there is a customised copy built into TnFOX) and using an IPC connection to remotely work with another database via FX::TnFXSQLDBServer.

  15. Threads can now run their own event loops
    Through a small implementational change to FX::FXApp, threads can now run their own event loops permitting per-thread window trees to be run (a window tree is any hierarchy of parent & child windows which has no relation to any other hierarchy ie; hierarchies may not span threads) if that application created a FX::TnFXApp as its primary application object. This is particularly useful for reporting errors by directly opening a dialog box instead of having to request the GUI thread to do it for you and can substantially decrease the complexity of worker threads performing simple interactions with the user.

  16. Custom memory pools
    Through FX::FXMemoryPool, TnFOX allows your code to create as many separate memory pools as your heart desires! Based upon dlmalloc, one of the fastest and least fragmentary general purpose dynamic memory allocators known, you can realise all the benefits of custom memory pools with ease: additional speed, security and robustness. On Win32, the core process allocator is replaced with nedmalloc (a dlmalloc derivative) yielding a typical 6x speed improvement for heavily multithreaded code!

To do list:

See the file Todo.txt.

(C) 2002-2008 Niall Douglas. Some parts (C) to assorted authors.
Generated on Thu Jun 12 16:07:25 2008 for TnFOX by doxygen v1.5.6