FX::FXStream Class Reference

Detailed Description

File format helper (Qt compatible).

FXStream is a modified version of FOX's FXStream - it is mostly API compatible but admittedly reflects the biggest divergence of API between FOX and TnFOX at the time of writing. Both share the purpose of serialising and deserialising data to and from a stored format and indeed via loadObject() and saveObject() can transfer entire window trees to and from storage.

Most use is simple - set which QIODevice it should use, and then use the << and >> operators to store and load respectively. position() lets you set or read the current offset into the file. Most classes in TnFOX (as well as FOX) provide overloads for these operators, so your << and >> overloads merely need to call << and >> on each of your data members you wish to save. Use load() and save() for blocks of individual units for efficiency.

Previous to FOX v1.1.31, FOX used FXStream mostly for dumping application state and its FXStream was not designed for general purpose file i/o. TnFOX uses FXStream for IPC which can traverse networks and CPU types, so it needs FXStream to be fast and always generate data in a universally understood format. You can of course use swapBytes() based on a flag within your data structure to avoid unnecessary endian conversions (and indeed this is what TnFOX's IPC classes do based on endian types on each end of the communications channel).

Since FOX v1.1.31, FXStream incorporates buffering and more general purpose facilities. The buffering in particular is left out because that's for the i/o device classes to implement if they want to. More importantly, IPC just would not work if a write to a pipe was coalesced into a larger packet sent sometime later.

Endian translation is performed for you on big endian machines by default (simply because numerically more computers in the world are little endian, therefore we want to cost the least performance for the most people). Normal FOX always saves in native format and converts on load - and Qt is big endian by default.

Useful tip:

Look into QBuffer's ability to dump itself onto a stream. This lets you very conveniently prepare parts of an overall image into separate sections. I've personally found that if you keep your end file image in a set of ordered nested QPtrList's & QBuffer's, writing it out is as simple as:

QValueList invokes the << operator on each of its members and so it recurses down calling each in turn. All QTL thunks provided in TnFOX provide default stream operators which require a null constructor in the type to compile.