Chapter 1. LibCXX overview



LibCXX Widget Toolkit 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 Widget Toolkit 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 Widget Toolkit's internal references are generally as follows:

  • The LibCXX Widget Toolkit does not maintain its own internal references to top level widgets, 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 widgets, 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 widgets and internal objects.

This works correctly as long as no other references to any widgets, or other related objects, exist. If the application has a reference to a widget, or some other LibCXX Widget Toolkit 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.