vos/corelibs/vos/listener.hh

Go to the documentation of this file.

/*
    This file is part of the Virtual Object System of
    the Interreality project (http://interreality.org).

    Copyright (C) 2001-2003 Peter Amstutz

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

    Peter Amstutz <tetron@interreality.org>
*/
#ifndef _LISTENER_HH_
#define _LISTENER_HH_

/** @file
    Defines ChildChangeListener, ParentChangeListener, and TypeChangeListener.
*/

#include <vos/corelibs/vos/vosdefs.hh>
#include <vos/corelibs/vos/refcount.hh>

#include <string>

namespace VOS
{
    class Vobject;

/** @class VobjectEvent listener.hh vos/corelibs/vos/vobject.hh
 *
 * This class describes an event changing the state of a Vobject.
    This event has either been requested to happen or has already
    happened, depending respectively on whether it is supplied as part
    of an access control callback or a listener notification callback.
    @note A VobjectEvent is a reference counted object.  This means
    that you may keep a reference to an event which has been passed to
    you if you increment its count with acquire().
 */
class VOS_API VobjectEvent : public RefCounted
{
public:
    typedef enum {TypeInsert, TypeRemove, ParentInsert, ParentRemove,
                  ChildInsert, ChildReplace, ChildRemove,
                  ReadChild, ReadParent, ReadType,
                  ChildrenListen, ParentListen} EventType;
private:
    EventType event;
    Vobject* initiator;
    Vobject* from;
    int position;
    string newstring; // used for both contextual name and new type events
    Vobject* newchild;
    Vobject* oldchild;
public:
    /** Construct a ReadChild, ReadParent, ChildInserted,
        ChildRemoved, ParentInserted or ParentRemoved event.

        @param et The type of event that occured
        @param init The object which caused this event to occur
        @param fromobj The parent object involved
        @param pos The position of the child object in question
        @param contextname The contextual name of the child object in question
        @param childobj The child object involved
     */
    VobjectEvent(EventType et, Vobject& init,
                 Vobject& fromobj, int pos, const string& contextname,
                 Vobject& childobj);

    /** Construct a ChildReplaced event.
        @param et The type of event that occured
        @param init The object which caused this event to occur
        @param fromobj The parent object
        @param pos The position of the child object in question
        @param contextname The contextual name of the child object in question
        @param newobject The new child at this position
        @param oldobj The old child at this position
     */
    VobjectEvent(EventType et, Vobject& init,
                 Vobject& fromobj, int pos, const string& contextname,
                 Vobject& newobj, Vobject& oldobj);

    /** Construct a ReadType, TypeInserted or TypeRemoved event.
        @param et The type of event that occured
        @param init The object which caused this event to occur
        @param fromobj The parent object of this child change event
        @param type The newly added type string
    */
    VobjectEvent(EventType et, Vobject& init, Vobject& fromobject, const string& type);

    /** Construct a ChildrenListen or ParentListen event
        @param et The type of event that occured
        @param requester The object which wants to start listening
        @param fromobj The object that will be listened to
    */
    VobjectEvent(EventType et, Vobject& requester, Vobject& fromobject);

    virtual ~VobjectEvent();

    /** @return What type of event this is. */
    EventType getEvent() { return event; }

    /** @return The object which requested or initiated this event.
        Always valid.  For access control checks, this is the object
        which is requesting access.  Note that unlike most parts of
        the API the reference count on the returned object is NOT
        increased (acquire is NOT called) so if you plan on keeping a
        reference to it past the lifetime of the callback, you must
        call acquire yourself!  This also means you should NOT assign
        the returned value to a vRef!
     */
    Vobject* getInitiator() { return initiator; }

    /** @return The parent Vobject being changed.  Always a vaild
        object. Note that unlike most parts of the API the reference
        count on the returned object is NOT increased (acquire is NOT
        called) so if you plan on keeping a reference to it past the
        lifetime of the callback, you must call acquire yourself!
        This also means you should NOT assign the returned value to a
        vRef! */
    Vobject* getParent() { return from; }

    /** @return The Vobject which is changing state. Always a valid
        object. Note that unlike most parts of the API the reference
        count on the returned object is NOT increased (acquire is NOT
        called) so if you plan on keeping a reference to it past the
        lifetime of the callback, you must call acquire yourself!
        This also means you should NOT assign the returned value to a
        vRef!
    */
    Vobject* getAffectedObject() { return from; }

    /** @return The child Vobject which was affected on a ParentInsert
        or ParentRemove event, or the requested object to read on a
        ReadChild event.  Will be NULL for TypeInsert, TypeRemove and
        all Listen events. Note that unlike most parts of the API the
        reference count on the returned object is NOT increased
        (acquire is NOT called) so if you plan on keeping a reference
        to it past the lifetime of the callback, you must call acquire
        yourself!  This also means you should NOT assign the returned
        value to a vRef! */
    Vobject* getChild() { return newchild; }

    /** @return The child Vobject which was newly added on a
        ChildInsert or ChildReplace event.  Will be NULL for
        ChildRemove, TypeInsert, TypeRemove and all Read and Listen
        events. Note that unlike most parts of the API the reference
        count on the returned object is NOT increased (acquire is NOT
        called) so if you plan on keeping a reference to it past the
        lifetime of the callback, you must call acquire yourself!
        This also means you should NOT assign the returned value to a
        vRef! */
    Vobject* getNewChild() { return newchild; }

    /** @return The previous Vobject occupying this position.  Only
        valid for ChildRemove and ChildReplace events, NULL otherwise.
        Note that unlike most parts of the API the reference count on
        the returned object is NOT increased (acquire is NOT called)
        so if you plan on keeping a reference to it past the lifetime
        of the callback, you must call acquire yourself!  This also
        means you should NOT assign the returned value to a vRef!
    */
    Vobject* getOldChild() { return oldchild; }

    /** @return The absolute position of the child Vobject in parent, or -1 if this is a
        TypeInserted or TypeRemoved event.*/
    int getPosition() { return position; }

    /** @return The contextual name of the child Vobject. */
    const string& getContextualName() { return newstring; }

    /** @return The added or removed type for type change events. */
    const string& getNewType() { return newstring; }
};


/** @class ChildChangeListener listener.hh vos/corelibs/vos/vobject.hh
 *
 * Interface to be called when a listened-to object has some
 *  change to its child list.
*/
class VOS_API ChildChangeListener
{
public:
    /** Called when a child has been inserted into the listened-to children list */
    virtual void notifyChildInserted(VobjectEvent& e) = 0;

    /** Called when a child has replaced another child in the listened-to children list */
    virtual void notifyChildReplaced(VobjectEvent& e) = 0;

    /** Called when a child has been deleted in the listened-to children list */
    virtual void notifyChildRemoved(VobjectEvent& e) = 0;
};

/** @class ParentChangeListener listener.hh vos/corelibs/vos/vobject.hh
 * Interface to be called when a listened-to object has some
    change to its parent set.
*/
class VOS_API ParentChangeListener
{
public:
    /** Called when an object has aquired a new parent. */
    virtual void notifyParentInserted(VobjectEvent& e) = 0;

    /** Called when an object has lost a parent. */
    virtual void notifyParentRemoved(VobjectEvent& e) = 0;
};

/** @class TypeChangeListener listener.hh vos/corelibs/vos/vobject.hh
 * Interface to be called when a listened-to object has some
    change to its type set.
*/
class VOS_API TypeChangeListener
{
public:
    /** Called when an object has gained a type. */
    virtual void notifyTypeInserted(VobjectEvent& e) = 0;

    /** Called when an object has lost a type. */
    virtual void notifyTypeRemoved(VobjectEvent& e) = 0;
};

/** @class DoNothingListener listener.hh vos/corelibs/vos/vobject.hh
 * Trivial listener implementation that does nothing. 
 * It can be useful, however, to keep a local cache of remote objects up to
 * date.  
 */ 
class VOS_API DoNothingListener : public ChildChangeListener,
                          public ParentChangeListener,
                          public TypeChangeListener
{
public:
    static DoNothingListener static_;

    virtual void notifyChildInserted(VobjectEvent& /*e*/) { }
    virtual void notifyChildReplaced(VobjectEvent& /*e*/) { }
    virtual void notifyChildRemoved(VobjectEvent& /*e*/) { }
    virtual void notifyParentInserted(VobjectEvent& /*e*/) { }
    virtual void notifyParentRemoved(VobjectEvent& /*e*/) { }
    virtual void notifyTypeInserted(VobjectEvent& /*e*/) { }
    virtual void notifyTypeRemoved(VobjectEvent& /*e*/) { }
};
}

#endif

---