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:

2. 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

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

Extended documentation:

• Breaking changes between v1.4.x and v1.6.x based versions of TnFOX
• Frequently Asked Questions about TnFOX
• TnFOX's Python language bindings
• How to use TnFOX's tool CppMunge.py
• How to provide human-language translations for TnFOX applications
• Facilities for writing fully exception-aware code
• Facilities for writing secure code
• Structural differences between TnFOX and Qt
• Porting from FOX to TnFOX
• Generic programming tools provided by TnFOX
• Debugging facilities in TnFOX
• Modular building of TnFOX
• C++0x Support in TnFOX

• Apple MacOS X specific notes
• Windows-specific notes
• Unix-specific notes

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?

• TnFOX is a very modern C++ library. When I say "modern", I mean that it uses many of the very most cutting edge techniques in C++ known and this does make a lot of programmers uncomfortable. Probably the hardest thing for most typical programmers to adjust to is writing fully exception aware code and unfortunately due to how extensively TnFOX uses exceptions, there isn't any choice in the matter. Summary: If you don't like exceptions, don't use TnFOX.

• Ancillory to the above, TnFOX needs a modern compiler. While written almost entirely in ISO C++, many compilers don't fully support all the constructs TnFOX uses - hence TnFOX supports two primary compilers: (i) MSVC v7.1 or later on Windows and (ii) GCC v3.2 or later on POSIX (note that other compilers do work and have build system support eg; Intel's). If you don't use those compilers on those platforms, expect to do some minor porting work (noting that I will never support using GCC for building Windows binaries until it becomes properly compatible with the PE binary format - hence, there is no mingw or cygwin support).

• Also ancillory to the above, TnFOX is not as "lightweight" as FOX - but then TnFOX is a solution framework (primarily it's Tn's portability layer) whereas FOX still remains mostly a GUI toolkit. All the metaprogramming adds a fair bit of extra bulk to generated binaries. As of v0.87, TnFOX can be built with optional components left out - see Modular building of TnFOX

Who should use TnFOX?

• Heavy multithreaded applications. TnFOX's multithreading support is second to none and is heavily optimised for speed, probably more so than any other C++ toolkit out there.

• Mission-critical applications. TnFOX works around or patches unhelpful features of C++ to ensure that no matter what goes wrong in your application, your code can respond (eg; deleting all secret data). Using TnFOX's facilities, your C++ application can be as robust as any C++ application can be as all host OS errors are detected and thrown as an exception.

• Very secure applications. There is strong encryption support, Secure Sockets Layer (SSL), data shredding and full host OS security support to Access Control List (ACL) level.

• Anyone interested in compile-time programming (metaprogramming) the C++ compiler will find good facilities in TnFOX. Unlike the Boost library (http://www.boost.org/), we don't have to work around compiler limitations which means we can greatly simplify implementation and avoid most usage of macros.

• Anyone wishing to have one or more processes communicate with one another, including over a network will find TnFOX's lightweight inter-process communication system extremely interesting as it happily outperforms CORBA and is very flexible and easy to use whilst remaining endian-safe.

• Anyone interested in performance. Both device i/o and SQL Database support are far faster than their comprehensive API's would suggest and the whole of TnFOX is regularly profiled and tuned after every major addition of new code. A lot of the code uses dynamically adjusted O(1) hash containers for excellent scaling and compile-time optimised sort algorithms. Full & portable access is provided to hardware-optimised vector facilities on the host computer.

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.