Attaching application data to display elements

All display elements, including the main application window, have an opaque appdata member that LibCXX Windows Library does not use itself. appdata is an opaque x::ptr<x::obj> object, a reference-counted object. See LibCXX's documentation for more information.

appdata provides convenient means for an application to attach its own data to a display element, by deriving from x::obj, and saving a x::ref to it in appdata.

With application windows having complicated layouts, and a large number of display elements, it's more convenient to stash away a direct reference to a particular display element, rather than having to drill down and find it, each time. As explained in the section called “Containers own references to the elements in the container”, LibCXX Windows Library's containers own references to their elements, and in order for application windows and their elements to be properly destroyed and terminated the application must release its own references to them. With LibCXX Windows Library built on top of LibCXX's reference-counted object framework, a lingering reference from an application to some display element will prevent proper destruction of display elements.

The appdata provides one convenient way to compile a list of all display elements in one place, safely:

The earlier example in this chapter gives an example of this approach. inputfieldsandbuttons.C creates a window containing, amongst other things, two x::w::input_field. Besides being placed into the window, they're also placed into an object that's attached to the main window's appdata. When the window gets closed the application retrieves the main window's appdata, retrieves the two input fields, and prints their contents.

#include <xrefptr_traits.H>
#include "inputfields.inc.H"

class appdataObj : virtual public x::obj, public inputfields {
public:

	using inputfields::inputfields;
};

typedef x::ref<appdataObj> appdata_t;

The sample program uses some supporting framework from the LibCXX base classes and templates library. The Makefile in the examples directory runs a stylesheet to process inputfields.xml, a simplistic list of fields and their types. This generates a header file that declares two classes. The first one has a list of x::ptrs for all fields. The declared x::ptrs are convenient to have when creating them, piecemeal.

The second class is inputfields, with the final collection of the listed fields, as their natural x::refs. This is multiply-inherited with x::obj to produce a reference-counted object, an appdata_t. This gets create()d and attached as the x::w::main_window's appdata.

Before exiting, the sample program retrieves the main window's appdata, and shows the contents of the input fields.

Every display element has an available appdata. The application can use this to attach an object to any display element; but it is important to understand that the display element owns a reference to its appdata so this object should not have its own reference to the display element or to any of its parent container elements (see the section called “Containers own references to the elements in the container” for more information). Otherwise this creates a problematic circular reference. With some care, it's possible to use weak pointers, though.

See Chapter 15, The book layout manager for another example of using appdata. See the section called “Using singleton objects” for a different approach to conveniently compiling a collection of all objects in a manner that's compatible with LibCXX Windows Library's rules for reference-counted objects.