Generics Reference Manual

|-- CSerialized
     |-- CMetaModule
          |-- CObject
          |-- CObjectListener

Listener Abstraction

    Listeners are classes dedicated to specific objects events handling. For example, a form class definition could be associated to a form listener class in order to give developpers and users the ability to intercept and manage special events such as maximization, close requests and many others. There is no message queue handling in those objects, the main purpose is just a user friendly front end API presentation.

    Listeners are not static functions, they are classes definitions and so inherits from the c++ polymorphic mechanism. The listeners functions will generally be declared as virtual ones to give the developpers the ability to handle all or part of the objects events with their own overloaded definitions.

    This concept is introduced in generics with two simple classes : CObject and CObjectListener. Both derive the CMetaModule definition in order to give developpers the possibility of defining such objects in dynamic linked modules and to deal with the CMetaModuleImporter API. Because they derive the CMetaModule definition, they inherits the serialization process too.

class CObjectListener : public CMetaModule
    // instanciation section
    public :

        CObjectListener                      ();
        virtual ~CObjectListener             () =0;

    // listener section
    public :

        // called when CObject constructor is executed on inSender (except when CObject is instanciated from serialization process
        // because in such cases the cobject would already be allocated when the listener would be attached)
        virtual void                         OnConstruct        (CObject *inSender)    { }

        // called when CObject destructor is executed on inSender, don't forget that only CObject's memory stack is available at
        //this point !
        virtual void                         OnDestruct          (CObject *inSender)    { }

    // private section
    private :

        // listener callers
        CObjects                             m_Owners;

        // friend object class
        friend class                         CObject;

        // generic metaclass association

// metaclass and class tag declarations
DECLARE_GENERIC_METACLASS ('_obj', CObjectListener, CMetaModule);

class CObject : public CMetaModule
    // instanciation section
    public :

        CObject                            (const CObjectListener *inListener =NULL);
        virtual ~CObject                   () =0;

    // protected definition
    protected :

        // object expected listener type
        virtual CMetaClass *               ListenerMustBe          () const;

    // specific functions
    public :

        // listener affectation, reader and removal (do not force class type caller on AssignListener : to increase performance,
        // types may be checked only while assignation in overwritten functions, not before calling specific listener functions;
        // if you force, you could generate segmentation faults not on this call but later on the listener exploitation)
        Bool                               AssignListener          (const CObjectListener *inListener);
        CObjectListener *                  RemoveListener          ();
        CObjectListener *                  GetListener             () const;

    // serialization redefinition
    public :

        // object serialization, stores or instanciates associated listener if any
        virtual void                       Serialize               (CXMLElementNode *&ioXMLElementNode, const int inMode);

    // protected attributes
    protected :
        // the object listener
        CObjectListener *                  m_Listener;

        // friend object listener class
        friend class                       CObjectListener;

        // generic metaclass specifications

// generic metaclass and class tag declarations
DECLARE_GENERIC_METACLASS ('objt', CObject, CMetaModule);