Running helloworld.C again should open its window in the same position with most window managers. This uses LibCXX's application identifier-based configuration directory. LibCXX Widget Toolkit automatically saves window positions in the windows file in the application's configuration directory.

On display servers with multiple screens the main windows get opened on the same screen as before. This flag can be turned off by calling x::w::preserve_screen_number or setting an application property of the same name.

helloworld.C creates an x::w::main_window, an object that represents the main application window. x::w::main_window is a smart pointer. LibCXXW does not use C++ library's std::shared_ptr, but LibCXX's own x::ref (non-nullptr smart pointer), x::const_ref (a ref to a constant object), x::ptr (a nullable smart pointer), and x::const_ptr (a constant ptr) , which work in similar ways (but have additional features). This documentation uses the term “reference” to refer to LibCXX's x::ref family of smart pointers.

The application does not need to take an explicit step to destroy the main window, or any other display object. When its x::ref goes out of scope and gets destroyed the widget gets destroyed and removed.

x::w::main_window is a container, a widget that contains other widgets. All widgets are either individual elements, like buttons and input fields, or they are containers with their own widgets; and each container is, itself, a widget.

Naturally, containers hold references on the widgets in the container. Removing an widget from the container gets rid of the container's reference on the widget. Normally, no other references remain and all resources used by the widget get released.

The application creates all widgets. Each factory method that creates a widget returns a reference to the new widget. The application should generally avoid storing references to widgets in static or dynamic objects, the safest thing to do is to hold it in a local variable, in automatic scope, so that the reference gets destroyed at the end of the scope. This is because it is critical that no other references to a widget remain when it gets removed from its container; or when any of its parent containers get removed from their respective container. Otherwise the LibCXXW will not be able to properly clean up all resources, and handle its internal book-keeping.

Since x::w::main_window is a top-level application window, nothing else holds a reference to it. helloworld.C creates an x::w::main_window in its testlabel() function. There are no other references to it, and when it returns the last reference to the main window goes out of scope, it gets destroyed and removed from the display.

helloworld.C's create_label() creates a label widget in the main window, but testlabel() does not store this reference itself, leaving the only reference to the label in its main window container. When testlabel() returns, the last reference to the main window goes away and the underlying object gets destroyed. Since that object held the only reference to the label widget object, the label widget object gets destroyed as well.

In this manner, removing a container recursively removes and destroyes everything in the container, recursively. However if the application retained its own reference to the label object, this would prevent everything from getting destroyed properly, and all resources released.

Attaching a reference to a widget in some way (via a callback) is generally safe as long as the reference is to a widget that's not an immediate parent or child of the widget to which the reference gets attached to. If necessary, it is safe to store or capture weak pointer references and recover strong references when needed.

LibCXX Widget Toolkit starts an internal execution thread that manages the connection to the X server. Unlike other X toolkits, LibCXX Widget Toolkit does not force the application into an event-driven design pattern. LibCXX Widget Toolkit takes care of automatically starting the internal execution thread, and stopping it after the last top level window object gets destroyed.

In helloworld.C, returning from testlabel() destroys the x::w::main_window, which stops the execution thread. However the execution thread does not get stopped immediately, and it continues to perform some final cleanup duties, while main() wraps up its own responsibilities.

helloworld.C shows an example of waiting until the connection thread terminates and the connection to the X server gets closed. This uses various classes from the LibCXX parent library:

A callback is a lambda or a callable object that LibCXXW executes in response to an event of some kind.

helloworld.C, installs two callbacks: the on_disconnect() lambda gets invoked if the connection to the X server was unexpectedly disconnected; and x::w::main_window's on_delete() lambda gets invoked when the main window's “Close” button gets clicked.

on_delete() callback's first parameter, “ONLY IN_THREAD”. indicates it gets invoked from the connection-thread, as explained in Chapter 46, Connection threads and callbacks. Although on_disconnect()'s callback also gets invoked from the connection-thread its invocation indicates that the connection-thread is no longer functional, so it does not get the “ONLY IN_THREAD” parameter.

In all cases, callbacks, in general, should not engage in lengthy, time-consuming tasks. The internal connection thread does not process any additional X protocol messages until the callback returns. Callbacks should be limited to simple tasks, such as sending messages to the main application thread, to execute the actual task at hand.

To effectively do this in a thread safe manner, the recommended approach is:

x::w::main_window is an example of a container. A container is a widget which contains other widgets. Each container has a layout manager that controls the position and the behavior of the elemnts in the container. helloworld.C creates a x::w::main_window that has a label widget.

x::w::main_window's create() static method returns a new x::w::main_window. Other containers get created in various other ways.

Creator lambdas initialize the contents of a new widget, including containers. For containers, a lambda gets passed as a parameter to a function or a method that creates a new container, like a factory's create_container() or create_focusable_container(). A creator also gets passed to a x::w::main_window's create(). In general, a creator lambda gets called just before the function or the method returns the new container:

The creator lambda gets the new widget as its parameter. This is the same object that's going to be returned from the function or a method that's creating the container. The creator lambda gets invoked just before that function or method returns.

The purpose of the creator lambda is to initialize the new container. helloworld.C initializes the main window, in the creator, by adding a new label to it.

Observe that helloworld.C's window gets automatically sized for its label. The creator lambda is an optimization. The size of a new container gets computed after the creator lambda returns, but before the newly-created container itself gets returned to the application.

helloworld.C could do nothing in its creator lambda, and then add the label to the x::w::main_window itself. However, this will be less efficient. Initially the main window's size gets calculated as empty, there's nothing in it. After the label gets added the size of the main window must be recalculated again.

Populating the container in its creator lambda avoids doing this extra recalculation, and is more efficient.

There are some isolated exceptions. The peephole layout manager does not use creator lambdas. Peepholes always contain a single widget in the peephole (but the widget itself can be a container with many other widgets). The peepholed's creator gets specified separately, as a constructor to the new layout manager specification parameter. However, an empty creator lambda must still be provided, to create_container() or create_focusable_container(), which typically does nothing; but it can be repurposed for some other use.

A container is a widget that contains other widgets. The main application window is a container. Each container has a “layout manager”. The layout manager arranges the widgets in the container. A container's get_layoutmanager() method returns a x::w::layoutmanager, which is just a reference to a base layout manager class. There are several layout managers that get derived from an x::w::layoutmanager's base class:

The actual layout manager gets specified when creating the container, and the return value of get_layoutmanager() gets converted accordingly. helloworld.C explicitly specifies the grid layout manager for its main window, so its get_layoutmanager() returns a x::w::gridlayoutmanager.

For convenience, methods named after each layout manager invoke get_layoutmanager() and convert the result to the appropriate layout manager type. gridlayout() calls get_layoutmanager() and returns a x::w::gridlayoutmanager; borderlayout() calls get_layoutmanager() and returns a x::w::borderlayoutmanager; and so on. An exception gets thrown if the container uses a different layout manager.

An x::w::factory creates new widgets. The factory comes from the layout manager, and the process for obtaining a factory is specific to each layout manager (except for the bare list layout manager, which is an impostor). helloworld.C calls its grid layout manager's append_row() method, which returns a factory that places the new widget in a new row in the grid.

Some layout managers provide factories with additional functionality. Grid layout manager's methods return an x::w::gridfactory with additional methods that set each new widget's borders, padding and alignment.

Fatal errors in the LibCXX Widget Toolkit get reported by throwing an x::exception LibCXX object. helloworld.C shows the basic approach of catching the exception, and reporting it.