[Home]	[About]
[Screenshots]	[Download]
[News]	[Community]
[Documentation]	[Manual]
[Bugs & Requests]	[Wiki]

/home/tetron/hack/vos/libs/vos/vos/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 
    Additions by Reed Hedges  marked with initials "rh" and date.
*/
#ifndef _PROPERTY_LISTENER_HH_
#define _PROPERTY_LISTENER_HH_

#include <vos/vos/vos.hh>
#include <vos/vutil/refcount.hh>
#include <vos/vos/property.hh>

namespace VOS {
    class Property;
//    class ExtrapolatedProperty;
    class PropertyEvent;

/** @class PropertyListener propertylistener.hh vos/metaobjects/property/propertylistener.hh
  * @ingroup libmetaobject_property
 *  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 VOS_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 PropertyEvent propertylistener.hh vos/metaobjects/property/propertylistener.hh
  * @ingroup libmetaobject_property
 *  PropertyEvents are passed to PropertyListener objectss to notify them of
 *  changes to the properties they are listening to.
 */
    class VOS_API PropertyEvent : public VUtil::RefCounted
{
public:
    typedef enum {PropertyWrite, PropertyReplace, PropertyRead} EventType;

private:
    EventType event;
    std::string oldvalue;
    std::string newvalue;
    std::string olddatatype;
    std::string newdatatype;
    Vobject* initiator;
    Property* property;
    int offset;
    int length;
    bool isACcheck;

public:
    PropertyEvent(EventType et, Vobject* init, Property& property,
                  const std::string& value,
                  const std::string& datatype,
                  bool isACcheck);
    PropertyEvent(EventType et, Vobject* init, Property& property,
                  const std::string& value,
                  const std::string& datatype,
                  const std::string& oldvalue,
                  const std::string& olddatatype,
                  bool isACcheck);
    PropertyEvent(EventType et, Vobject* init, Property& property,
                  int offset,
                  int length,
                  const std::string& value,
                  const std::string& datatype,
                  bool isACcheck);
    PropertyEvent(EventType et, Vobject* init, Property& property,
                  int offset,
                  int length,
                  const std::string& value,
                  const std::string& datatype,
                  const std::string& oldvalue,
                  const std::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.
     */
    VUtil::vRef<Vobject> getInitiator() const { return VUtil::vRef<Vobject>(initiator, true); }

    /** @return The property which is being accessed or changed.
        Always valid.  For access control checks, this is the object
        which is requesting access.
     */
    VUtil::vRef<Property> getProperty() const;

    /** @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 std::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 std::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 std::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 std::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 std::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 std::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 std::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 std::string& dt) { newdatatype = dt; }

    void deliverTo(PropertyListener* pl) { pl->notifyPropertyChange(*this); };
};

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


/** @class DoNothingPropertyListener propertylistener.hh vos/metaobjects/property/propertylistener.hh
 *  @ingroup libmetaobject_property
 *  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 VOS_API DoNothingPropertyListener : public virtual PropertyListener
//, public virtual ExtrapolatedPropertyListener
{
public:
    static DoNothingPropertyListener static_;

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

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


    class VOS_API RemotePropertyListener :  public MetaObject, public PropertyListener
    {
    public:
        RemotePropertyListener(VobjectBase* superobject);
        virtual ~RemotePropertyListener() { }

        virtual void notifyPropertyChange(const PropertyEvent& event);
    };

}

#endif