GtkOL applications are windows widgets containing other widgets such as buttons, menus, text entries and many more... Those widgets or GUI components are instanciated one under each others. Widgets owning other widgets are called containers. Such widgets may be GUI visible controls or just layouts i.e. non visible widgets instanciated only to arrange a descent hierarchy of widgets. GTK+ offers two kinds of containers, the ones that can handle multiple children instances and others, called bin structures, that can handle only one child instance.

    GtkOL implements an abstract CComponent class that maps a given application hierarchy state. All of the GUI components derives the abstract GtkOL CComponent definition. This class implements a set of functions that enables the developper to go through the application hierarchy by getting component instances owner and children while requesting potential expected types... It implements a logical set of affectations rules too i.e. when components are able to be owned by some other ones respecting owner expected children types and numbers and children expected owner types. The CComponent definition reflects the GtkOL spine. It uses the libgenerics TNode template services to do so.  The CApplication instance is always the GtkOL's absolute CComponent node.

    2.1.1. Component owner affectation

    There are two maners to specify a GUI component's owner. The first one is while instanciating it under a given owner component. The second one is by specifying it with a later call to the virtual bool CComponent::SetOwner (CComponent *inOwner, const size_t inIndex=-1) function.

// let's consider we declare a GtkOL application instance CApplication Application (argc, argv); // instanciate a form under the application instance, the form's owner is the application component CForm *aForm = new CForm (&Application); // instanciate a button without specifying its owner CButton *aButton = new CButton (); // instanciate a vertical box layout, the layout's owner is the form instance CVBoxLayout *aVBoxLayout = new CVBoxLayout (aForm); // assign the button's owner : it will be contained into the vertical box layout aButton -> SetOwner (aVBoxLayout);

    Because there is only one simple function call to assign a component's owner, special components such as layouts that organize the children components GUI aspect have to be set before inserting children instances if their default behaviour does not correspond to the need. Please see specificities for each of them.

    2.1.2. Components hierarchy walk through

    As all of the GtkOL GUI instances are CComponent derived, you can use the CComponent API to walk through the hierarchy GUI instances. Let's keep on considering the previous instanciated hierarchy.

// get the button's direct owner : the vertical layout CComponent *inOwner = aButton -> GetOwner (); // get the form direct children : the vertical layout CComponents inChildren = aForm -> GetChildren (); // get the button indirect owner from specified requested instance type : the form inOwner = aButton -> GetOwner (__metaclass(CForm)); // get the form whole descent hierarchy, form instance included i.e. the form, the vertical layout and the button inChildren = aForm -> GetSubComponents (); // get the button sibling instances if any CComponents inSiblings = aButton -> GetSiblings ();

    And so on... please refer to the CComponent API for a complete detailed set of functions.

    2.1.3. Resource freeing

    GtkOL widgets instances have lifetimes and scopes just like classical C++ classes. To avoid code scope implicit restrictions, the new and delete C++ operator should be used when allocating and freeing GtkOL instances, as much as excepted but for the CApplication one until it is explictly deleted at the end of the GtkOL application execution. Anyway, all of the GtkOL components hierarchy is deleted, if not explictly done before, with a recursive algorithm that will go through the children components of a given one before deleting it. So, if the application execution entry point declares a CApplication instance that is automatically freed when done with the events loop, the whole attached components hierarchy will be deleted at the end of the execution without any care for the developper about the resources freeing sequence. In the given sample code, when the main events loop ends, the Application instance destructor is called; it then performs the deletion of the button, the vertical layout, the form and the Application itself.