Chapter 1. LibCXX overview



LibCXX Windows Library is built using the LibCXX library, a library of classes and templates based on reference-counted objects. Some existing familiarity with LibCXX will be helpful in understanding how to use LibCXXW's classes, but is not strictly necessary. A brief overview follows.

All LibCXXW classes and templates are defined in the x::w namespace.


It's important to understand the relationship between the various objects and classes. All classes and templates, like x::w::connection and x::w::screen are reference-counted objects, based on x::ref and x::ptr. x::w::connection, x::w::screen and others, are just reference handles, similar to std::shared_ptr.

The LibCXX Windows Library takes care of creating the actual, underlying objects, and when the last reference, last handle, to the underlying object goes out of scope, the underlying object gets destroyed. This includes both the explicit references, and the internal references the underlying objects have to each other.

Except as stated, the LibCXX Windows Library's internal references are generally as follows:

  • The LibCXX Windows Library does not maintain its own internal references to top level display elements, like x::w::main_window.

  • x::w::main_window holds a reference on its x::w::screen, which holds a reference on its x::w::connection.

  • A container holds a reference to its layout manager, and the layout manager holds reference to all elements in the container.

A main window is a container. Typically, an application creates its main window, and stores its x::w::main_window somewhere. The application procedes and creates the various display elements, putting them in their containers, which now hold a reference on them.

In this manner, all references end up being rooted in their main window object. When the application destroys its x::w::main_window handle, the cascading effect from that destroys all display elements and internal objects.

This works correctly as long as no other references to any display elements, or other related objects, exist. If the application has a reference to a display element, or some other LibCXX Windows Library object that's tied to the main application window, directly, or indirectly, this is going to prevent the main application window from getting properly destroyed.