CComponent

		GtkOL Reference Manual

CComponent

The CComponent definition reflects the GtkOL spine. There is no GUI handling at this definition level. All of the GUI requests are performed by the specific overloaded definitions of the CComponent API. This class maps the physical hierarchy of a GtkOL application.

XML serialization

Metaclass declaration

DECLARE_GENERIC_METACLASS ('cpnt', CComponent, CObject);

Hierarchy Definition

    [CClass]
        [CSerialized]
            [CMetaModule]
                [CObject]
                    CComponent

API description

#include "cobject.h"

#include <gtk/gtk.h>
#include <gdk/gdkkeysyms.h>

using namespace NServices; // using libgenerics namespace services

typedef TBuffer <CComponent     *> CComponents;        // gtkol components list
typedef TNode   <CComponent     > CComponentNode;   // gtkol component hierarchical node, internally used
typedef TBuffer <CComponentNode *> CComponentNodes;    // gtkol component hierarchical nodes list, internally used

class CComponent : public CObject
{
public :

CComponent            (CComponent *inOwner, const CObjectListener *inListener=NULL);
virtual ~CComponent   () =0;

public :

   UInt32                GetId            () const;
static CComponent *   GetComponent     (const UInt32 inId);

static CComponents    GetComponents   (const CMetaClass *inRequested=NULL, const CMetaClass *inRejected =NULL);

CComponents           GetChildren     (const CMetaClass *inRequested=NULL, const CMetaClass *inRejected =NULL) const;
CComponents           GetSubComponents (const CMetaClass *inRequested=NULL, const CMetaClass *inRejected =NULL) const;
CComponents           GetSiblings     (const CMetaClass *inRequested=NULL, const CMetaClass *inRejected =NULL) const;

Bool                HasSubComponent (const CComponent *inComponent) const;
Bool                  HasSibling       (const CComponent *inComponent) const;

static SInt16         GetInOwnerIndex (const CComponent *inOwner, const CComponent *inChild,
      const CMetaClass *inRequested=NULL, const CMetaClass *inRejected =NULL);
static SInt16         GetInOwnerOccurence (const CComponent *inOwner, const CComponent *inChild,
                                      const CMetaClass *inRequested=NULL, const CMetaClass *inRejected =NULL);

virtual Bool          CheckSetOwner       (const CComponent *inCandidate) const;
virtual Bool          SetOwner          (CComponent *inOwner, const SInt16 inIndex=-1);

CComponent *          GetOwner          (const CMetaClass *inRequested=NULL) const;

virtual CMetaClasses OwnerMustBe       () const;
virtual CMetaClasses ChildMustBe       () const;

virtual void        Serialize        (CXMLElementNode *&ioXMLElementNode, const int inMode) THROWABLE;
virtual void        Serialize       (CArchive &ioArchive) THROWABLE;

private :

static CComponentNode m_AbsoluteNode;

   CComponentNode *         m_ComponentNode;

   const UInt32               m_Id;
   static UInt32               m_IdInc;
   static TBuffer <UInt32> m_IdLost;

   friend class            CApplication;

SECTION_GENERIC_METACLASS;
};

API details

CComponent::CComponent (CComponent *inOwner, const CObjectListener *inListener=NULL);

The CComponent constructor. This level instanciates the internally used hierarchy tree nodes. It automatically calculates components execution identifiers too.

virtual CComponent::~CComponent () =0;

The CComponent destructor performs the application hierarchy deletion by freeing the children resources with a recursive algorithm. It flags the newly available lost execution identifiers to be reusable.

UInt32 CComponent::GetId () const;

Returns the component execution identifier. As identifiers are reaffected when the components instances are deleted, a given component identifier may differ from an application execution to another one, except for the CApplication one whose id is always 1 because beeing the first allocated.

static CComponent * CComponent::GetComponent (const UInt32 inId);

Retreives the component of specified identifier. NULL if none found.

static CComponents CComponent::GetComponents (const CMetaClass *inRequested=NULL, const CMetaClass *inRejected =NULL);

Returns the whole application hierarchy components list that match the potential given instances requested and rejected types. All of the components are returned if nothing special is requested or rejected.

As an example, you could request all of the application attached buttons instances but the radio ones with such a call :
CComponents inButtons (CComponent::GetComponents (__metaclass(CButton), __metaclass(CRadioButton)));

CComponents CComponent::GetChildren (const CMetaClass *inRequested=NULL, const CMetaClass *inRejected =NULL) const;

Returns the direct children list of the component caller that match the potential given instances requested and rejected types. All of the children are returned if nothing special is requested or rejected.

CComponents CComponent::GetSubComponents (const CMetaClass *inRequested=NULL, const CMetaClass *inRejected =NULL) const;

Returns all of the descent hierarchy list of the component caller in a prefixed order, component caller included, that match the potential given instances requested and rejected types. All of the descent hierarchy is returned if nothing special is requested or rejected.

CComponents CComponent::GetSiblings (const CMetaClass *inRequested=NULL, const CMetaClass *inRejected =NULL) const;

Returns all of the components siblings list of the component caller, component caller incuded, that match the potential given instances requested and rejected types. All of the siblings are returned if nothing special is requested or rejected.

Bool CComponent::HasSubComponent (const CComponent *inComponent) const;

Checks if the given inComponent argument is a subcomponent of the caller, without distinction between direct or indirect children.

Bool CComponent::HasSibling (const CComponent *inComponent) const;

Checks if the given inComponent argument is a sibling component of the caller.

static SInt16 CComponent::GetInOwnerIndex (const CComponent *inOwner, const CComponent *inChild,
const CMetaClass *inRequested=NULL,
const CMetaClass *inRejected =NULL);

Returns the direct inChild component inOwner index, counted on the potential given instances requested and rejected types. Returns -1 if not found.

static SInt16 CComponent::GetInOwnerOccurence (const CComponent *inOwner, const CComponent *inChild,
const CMetaClass *inRequested=NULL,
const CMetaClass *inRejected =NULL);

Returns the direct or indirect inChild component inOwner index from a prefixed tree walk through algorithm counted on the potential given instances requested and rejected types. Returns -1 if not found.

virtual Bool CComponent::CheckSetOwner (const CComponent *inCandidate) const;

Checks if the inCandidate component might be affected as the owner of the caller instance regarding to the inCandidate expected children types and the caller expected owner types. See the CComponent::OwnerMustBe and CComponent::ChildMustBe functions. This function might be overloaded by derived classes to add a check to the children number a component may handle.

virtual Bool CComponent::SetOwner (CComponent *inOwner, const SInt16 inIndex=-1);

Sets the caller component's owner by inserting the caller instance at the given owner child index, -1 to append the caller instance at the end of the current owner children list. This function first performs a call to the CComponent::CheckSetOwner function, then removes the potential previous owner of the caller and sets the specified new one. There is absolutly no GUI handling at this level. This function is currently overloaded to handle the GUI aspect of the owner affectation. It is the overloaded definition responsability to correctly handle the specified inIndex parameter.

CComponent * CComponent::GetOwner (const CMetaClass *inRequested=NULL) const;

Returns the current component's direct owner if no particular expected type is specified. Walks through the ascendant hierarchy to find the expected specified direct or indirect owner's type if specified.

As an example, you could request an indirect form owner of a button subcomponent by specifing the requested expected type :
CComponent *inForm = static_cast <CForm *> (aButton -> GetOwner (__metaclass(CForm)));

virtual CMetaClasses CComponent::OwnerMustBe () const;

Returns the potential owner types list of the caller component. This level defaults to __metaclasses(CComponent). Overloaded functions might return several expected types (for example, a tree view item might be contained into a tree view widget or into another tree view item). This function is called by CComponent::CheckSetOwner to check owner affectations possibilities.

virtual CMetaClasses CComponent::ChildMustBe () const;

Returns the potential children types list of the caller component. This level defaults to __metaclasses(CComponent). Overloaded functions might return several expected types. This function is called by CComponent::CheckSetOwner to check owner affectations possibilities.

virtual void CComponent::Serialize (CXMLElementNode *&ioXMLElementNode, const int inMode) THROWABLE;

This function serializes a component hierarchy. If a dump is requested by the inMode parameter, it writes the caller instance into the specified xml element node and calls the descent components hierarchy to do the same. If a load is requested, it requests the libgenerics services to launch the children serialization instanciation process and reload them from scratch.

virtual void CComponent::Serialize (CArchive &ioArchive) THROWABLE;

This version of the function, if called, returns an exception. The archive serialization of the libgenerics is not handled by GtkOL.