vos/metaobjects/property/propertylistener.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, 2002 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>
    Additions by Reed Hedges <reed@zerohour.net> marked with initials "rh" and date.
*/
#ifndef _PROPERTY_LISTENER_HH_
#define _PROPERTY_LISTENER_HH_


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

class Property;
class ExtrapolatedProperty;

/** @class PropertyEvent propertylistener.hh vos/metaobjects/property/propertylistener.hh
 *  PropertyEvents are passed to PropertyListener objectss to notify them of 
 *  changes to the properties they are listening to.
 */ 
class PROPERTY_API PropertyEvent : public RefCounted
{
public:
    typedef enum {PropertyWrite, PropertyReplace, PropertyRead} EventType;  

private:
    EventType event;
    string oldvalue;
    string newvalue;
    string olddatatype;
    string newdatatype;
    Vobject* initiator;
    Property* property;
    int offset;
    int length;
    bool isACcheck;
    
public:
    PropertyEvent(EventType et, Vobject& init, Property& property,
                  const string& value, 
                  const string& datatype,
                  bool isACcheck);
    PropertyEvent(EventType et, Vobject& init, Property& property,
                  const string& value, 
                  const string& datatype, 
                  const string& oldvalue,
                  const string& olddatatype, 
                  bool isACcheck);
    PropertyEvent(EventType et, Vobject& init, Property& property, 
                  int offset, 
                  int length, 
                  const string& value,
                  const string& datatype,
                  bool isACcheck);
    PropertyEvent(EventType et, Vobject& init, Property& property, 
                  int offset, 
                  int length, 
                  const string& value,
                  const string& datatype,
                  const string& oldvalue,
                  const string& olddatatype,
                  bool isACcheck);

    virtual ~PropertyEvent();

    /** @return What type of event this is. */
    EventType getEvent() const { 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() const { return initiator; }

    /** @return The property which is being accessed or changed.
        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!
     */
    Property* getProperty() const { return property; }

    /** @return The beginning of the changed section.  
        @note If you want to know what exactly section of the property
        changed on a write event, use
        @code
string section = e.getNewValue().substr(e.getOffset(), e.getLength());
        @endcode
    */
    unsigned int getOffset() const { return offset; }

    /** @return The size of the changed section. */
    unsigned int getLength() const { return length; }

    /** @return The previous value of this property, prior to a
        proposed change (for access control checks) or prior to the
        most recent change (for notify events). */
    const string& getOldValue() const { return oldvalue; }

    /** @return For an access control check, this is the proposed new
        value (it has not been commited yet).  For a notify event, the
        new value for this property.  */
    const string& getNewValue() const { return newvalue; }

    /** @return For an access control check, this is the old property
        value (the change has not been commited yet).  For a notify
        event it is the current value of the property.  */
    const string& getValue() const 
        { return (isACcheck ? oldvalue : newvalue); }

    /** Only to be used for access control checks.  This allows you to
        modify the proposed new value for this property.  
        @param v the new value to use */
    void setNewValue(const string& v) { newvalue = v; }

    /** @return The previous datatype of this property, prior to a
        proposed change (for access control checks) or prior to the
        most recent change (for notify events). */
    const string& getOldDataType() const { return olddatatype; }

    /** @return For an access control check, this is the proposed new
        datatype (it has not been commited yet).  For a notify event, the
        new datatype for this property.  */
    const string& getNewDataType() const { return newdatatype; }

    /** @return For an access control check, this is the old property
        datatype (the change has not been commited yet).  For a notify
        event it is the current datatype of the property.  */
    const string& getDataType() const
        { return (isACcheck ? olddatatype : newdatatype); }

    /** Only to be used for access control checks.  This allows you to
        modify the proposed new datatype for this property.  
        @param dt the new datatype to use */
    void setNewDataType(const string& dt) { newdatatype = dt; }
};
 
/** @class PropertyEvent propertylistener.hh vos/metaobjects/property/propertylistener.hh
 *  PropertyListener objects will be notified of all changes to Properties
 *  to which they are listening. Create a subclass and override 
 *  notifyPropertyChanged, create an instance, and then use 
 *  Property::addPropertyListener to register your listener with that
 *  property.
 */
class PROPERTY_API PropertyListener {
public:
    virtual ~PropertyListener();

    /** Notification interface that a property has been changed.
     * Override this method in your subclass.
     *  @param event Event describing what happened. Note the 'const' declaration.
     */
    virtual void notifyPropertyChange(const PropertyEvent& event) = 0;
};


/** @class ExtrapolatedPropertyEvent propertylistener.hh vos/metaobjects/property/propertylistener.hh
 *  Listener for ExtrapolatedProperty changes.
 */
class PROPERTY_API ExtrapolatedPropertyListener {
public:
    virtual void notifyBaseChange(ExtrapolatedProperty& ep,
                                      const vector<double>& position,
                                      const vector<double>& velocity,
                                      const vector<double>& acceleration,
                                      double t) = 0;
    virtual void notifyPositionChange(ExtrapolatedProperty& ep,
                                      const vector<double>& position,
                                      const vector<double>& velocity,
                                      const vector<double>& acceleration,
                                      double t) = 0;
};


/** @class DoNothingPropertyEvent propertylistener.hh vos/metaobjects/property/propertylistener.hh
 *  This is a PropertyListener that does nothing; however, it can be used
 *  to keep a RemoteProperty up to date with changes in a LocalProperty,
 *  speeding up reads of the RemoteProperty.
 */
class PROPERTY_API DoNothingPropertyListener : public virtual PropertyListener, public virtual ExtrapolatedPropertyListener
{
public:
    static DoNothingPropertyListener static_;

    virtual void notifyPropertyChange(const PropertyEvent& e) {};

    virtual void notifyPositionChange(ExtrapolatedProperty& , const vector<double>& , const vector<double>& ,
                                      const vector<double>& , double ) {};
    virtual void notifyBaseChange(ExtrapolatedProperty& , const vector<double>& , const vector<double>& ,
                                  const vector<double>& , double ) {};
};



/** Internal class used to sort of extend RemoteSite without actually
    touching RemoteSite.  Users don't need to worry about this.
    @internal
*/
class ExtrapolatedListenerSiteWrapper : public virtual ExtrapolatedPropertyListener
{
public:
    Site* site;
    ExtrapolatedListenerSiteWrapper(Site* s);
    virtual ~ExtrapolatedListenerSiteWrapper();
    virtual void notifyPositionChange(ExtrapolatedProperty& ep,
                                      const vector<double>& position,
                                      const vector<double>& velocity,
                                      const vector<double>& acceleration,
                                      double t);
    virtual void notifyBaseChange(ExtrapolatedProperty& ep,
                                      const vector<double>& position,
                                      const vector<double>& velocity,
                                      const vector<double>& acceleration,
                                      double t);
    class Cmp {
    public:
        inline bool operator()(const ExtrapolatedPropertyListener* p, const ExtrapolatedPropertyListener* q) const {
            const ExtrapolatedListenerSiteWrapper* pw;
            const ExtrapolatedListenerSiteWrapper* qw;
            if((pw = dynamic_cast<const ExtrapolatedListenerSiteWrapper*>(p))
               && (qw = dynamic_cast<const ExtrapolatedListenerSiteWrapper*>(q)))
            {
                return pw->site < qw->site;
            } else return (p < q);
        };
    };
};


/** Internal class used to sort of extend RemoteSite without actually
    touching RemoteSite.  Users don't need to worry about this.
    @internal
*/
class PropertyListenerSiteWrapper : public virtual PropertyListener
{
    string firstnonce;
public:
    Site* site;
    PropertyListenerSiteWrapper(Site* s, const string& firstnonce);
    PropertyListenerSiteWrapper(Site* s);
    virtual ~PropertyListenerSiteWrapper();
    virtual void notifyPropertyChange(const PropertyEvent& e);

    class Cmp {
    public:
        inline bool operator()(const PropertyListener* p, const PropertyListener* q) const {
            const PropertyListenerSiteWrapper* pw;
            const PropertyListenerSiteWrapper* qw;
            if((pw = dynamic_cast<const PropertyListenerSiteWrapper*>(p))
               && (qw = dynamic_cast<const PropertyListenerSiteWrapper*>(q)))
            {
                return pw->site < qw->site;
            } else return (p < q);
        };
    };
};



#endif

---