A formatter of an object is any implementation of IXMLSerialize that is meant to XML serialize that object. Most of our formatters also can (optionally) dynamically create an instance of the associated class type while loading an XML document.

You can use our built-in formatters for MFC collection classes and GDI objects in your own applications.

The XML Formatter Factory is a behind-the-scenes global singleton used by the Stingray XML persistence framework to mimic the CObject-based polymorphic serialization provided by MFC. The factory object is used by the formatters, provided with the SEC XML framework, for the MFC collection classes such as CObArray and CObList that have native support for serializing CObject-based classes. The Formatter Factory is implemented by the SECXMLFormatterFactory class; building the Stingray Foundation Library with the XML Serialization option selected in the SFL Build Wizard will define a global instance of the factory object.

Formatters for the MFC CObject-derived classes that are a part of the serialization routine have to be first registered with the factory before any of the XML persistence functions can be invoked. During an XML file save operation, if a collection of CObject-derived classes is encountered, the collection formatter will:

This sequence is reversed during a file open operation. The collection formatter first reads the tag descriptor for an element and then queries the factory for the formatter associated with this type. Failing to register formatters with the factory will preclude this type look-up, resulting in a breakdown of the serialization attempt.

Formatter registration is performed using the set of XMLFORMATTERMAP() macros; the macros can be placed within the formatters themselves or can be used within a higher-level class, such as the document, that possesses knowledge of the persisted types and performs a collective registration of all the formatters.

Usage of the formatter map macros for registering formatter classes is shown below:

Once the formatters and the accompanying registration macros are in place, the Formatter Factory has to be initialized. This can be done as part of the application's start-up code in the CWinApp::InitInstance() override.

The Stingray XML framework includes formatters for the commonly used MFC collection classes (arrays, lists, maps, etc.). The collection class formatters observe all the semantics of any other XML formatter and, therefore, their usage is virtually identical. These formatters implement the IXMLSerialize interface and accept a reference to a pointer as a constructor argument. While serializing a collection class, within the XMLSerialize() override, create an equivalent formatter for the collection and pass this to the SECXMLArchive::Read() or Write() function. The following code snippet demonstrates using some of the simpler collection classes,

Providing the formatters for collections of native types is straightforward. More complex collections— such as CPtrArray, CObArray, CPtrList, CObList, CList (template) and typed collections— require formatters to be provided for the serialized objects as well.

You will have noticed, undoubtedly, that the Stingray XML framework’s built-in serialization support provided for the pointer collection classes is over and above what is provided in MFC. A restriction here, however, is that the serialization support for pointers (as well as for the simple template-based collections) is limited to one specific type. The polymorphic serialization behavior exhibited by the CObject collections and their equivalent formatters is not available. The collection formatter is updated directly by the underlying class formatter during template instantiation. Usage of the pointer and simple template-based collections is shown in the code below,

The XML formatter specification for serializable CObject-based classes is done through the Formatter Factory. As mentioned in “The XML Formatter Factory”, it is important that the registration macros be an integral part of either the formatter or an encompassing class. Once all formatters have been registered with the Formatter Factory, using the CObject-based collection classes is straightforward and much like using the native type collections. The following excerpt demonstrates this:

CBrushFTR, CPenFTR, CFontFTR, CRectFTR and CPointFTR are other built-in formatters for some MFC classes. Their names imply their functions.

To create a custom formatter, derive a class from IXMLSerialize or CXMLSerializeImp and override XMLSerialize. Our additional recommendations include:

Objective Grid and Objective Chart use this XML Serialization architecture to optionally serialize their data in XML format. For more information, take a look at the User’s Guide for each of these products.