Homepage Demos Overview Downloads Tutorials Reference
Credits

EventBase.h

Go to the documentation of this file.
00001 //-*-c++-*-
00002 #ifndef INCLUDED_EventBase_h
00003 #define INCLUDED_EventBase_h
00004 
00005 #include "Shared/get_time.h"
00006 #include "Shared/LoadSave.h"
00007 #include <string>
00008 
00009 //! The basis of events passed around the high level system
00010 /*! Contains the list of 'known' event generators in #EventGeneratorID_t
00011  *  and #EventGeneratorNames[].  If you want to make a new generator, all
00012  *  you have to do is add a new entry to the ID list (#EventGeneratorID_t)
00013  *  and then put its name in the #EventGeneratorNames[] array.
00014  *
00015  *  Alternatively, there is an 'unlicensed spectrum' available under
00016  *  the #unknownEGID.  You can send out events from that generator just
00017  *  like any other, but it should only be used for quick tests and hacking
00018  *  around...
00019  *
00020  *  The #sourceID (just an unsigned int) is generator specific.  A SID
00021  *  of @a i from the button generator (#buttonEGID) will refer to a
00022  *  particular button, whereas a SID from a vision detector (say
00023  *  #visObjEGID) refers to seeing a particular object.  These SIDs are
00024  *  usually defined in the generators themselves.
00025  *
00026  *  The #duration field is also generator specific - some may refer to
00027  *  the time since the last activation event (e.g. button events)
00028  *  where as others refer to time since last status (e.g. sensors
00029  *  updates)
00030  *
00031  *  The #EventGeneratorID_t list should contain links to the
00032  *  generators' documentation, or will directly give information about
00033  *  what to expect in events from that generator.
00034  */
00035 class EventBase : public LoadSave {
00036  public:
00037   //! Lists all possible event generator ids
00038   /*! An event generator is a abstract source of events, used for listening to and parsing certain classes of events
00039    *
00040    *  IF YOU ADD AN EVENT GENERATOR, DON'T FORGET TO NAME IT (EventBase::EventGeneratorNames, actual names are in EventBase.cc)*/
00041   enum EventGeneratorID_t {
00042     unknownEGID=0,    //!< default EGID, used if you forget to set it, probably not a good idea to use this for anything except errors or testing quick hacks
00043     aiEGID,           //!< not being used, yet (might use this when AI makes decisions?)
00044     audioEGID,        //!< Sends an event when a sound starts/ends playback, status events as chained sounds end; SID is SoundManager::Play_ID; duration is playtime
00045     buttonEGID,       //!< Sends activate event for button down, deactivate for button up.  Status events only for when pressure sensitive buttons' reading changes. (on sensorEGID updates); SIDs are from ButtonOffset_t in the namespace of the target model (e.g. ERS210Info::ButtonOffset_t); duration is button down time
00046     erouterEGID,      //!< Sends activate event on first listener, deactivate on last listener, and status on other listener changes.; SID is the generator ID affected (NOT IMPLEMENTED YET)
00047     estopEGID,        //!< Sends an event when the estop is turned on or off; SID is the MotionManager::MC_ID of the EmergencyStopMC; duration is length of estop activation
00048     locomotionEGID,   //!< Sends events regarding transportation in the world; you can/should assume these will all be LocomotionEvent classes; SID is MotionManager::MC_ID of posting MotionCommand; duration is the time since last velocity change of that MC. (You could generate these for things other than walking...)
00049     motmanEGID,       //!< Sends events when a MotionCommand is added or removed, SID is is the MotionManager::MC_ID, duration is always 0
00050     powerEGID,        //!< Sends events for low power warnings, temperature, etc. see PowerSourceID::PowerSourceID_t
00051     sensorEGID,       //!< Sends a status event when new sensor readings are available. see SensorSourceID::SensorSourceID_t
00052     stateMachineEGID, //!< Sends an event upon entering and leaving a StateNode; SID is pointer to the StateNode; duration is always 0
00053     textmsgEGID,      //!< Sends status events when a text msg is received on console; generated by the Controller, SID is always -1; durations is always 0 (see Controller for more information)
00054     timerEGID,        //!< Sends timer events; you set timers explicitly, you don't have to listen as well. (See EventRouter::addTimer()) There's no cross-talk, only the listener which requested the timer will receive it; SID is whatever you requested it to be; duration is the time (since boot, in ms) that the timer was supposed to go off; these are always status
00055     visOFbkEGID,      //!< Sends a DataEvent <OFbkImageVectorData> for every camera image received from the system; SID and duration are always 0 (This is generated by the MainObj instantiation of MMCombo)
00056     visRawCameraEGID, //!< Sends a FilterBankEvent when new raw camera images are available; SID is whatever value you gave during setup (typically in StartupBehavior_SetupVision.cc), duration is always 0
00057     visInterleaveEGID,//!< Sends a FilterBankEvent when new interleaved images are available; SID is whatever value you gave during setup (typically in StartupBehavior_SetupVision.cc), duration is always 0
00058     visJPEGEGID,      //!< Sends a FilterBankEvent when JPEG compressed images are available; SID is whatever value you gave during setup (typically in StartupBehavior_SetupVision.cc), duration is always 0
00059     visSegmentEGID,   //!< Sends a SegmentedColorFilterBankEvent when color segmentated images are available; SID is whatever value you gave during setup (typically in StartupBehavior_SetupVision.cc), duration is always 0
00060     visRLEEGID,       //!< Sends a SegmentedColorFilterBankEvent when RLE encoded color segmentated images are available; SID is whatever value you gave during setup (typically in StartupBehavior_SetupVision.cc), duration is always 0
00061     visRegionEGID,    //!< Sends a SegmentedColorFilterBankEvent when color regions are available; SID is whatever value you gave during setup (typically in StartupBehavior_SetupVision.cc), duration is always 0
00062     visObjEGID,       //!< Sends VisionObjectEvents for objects detected in camera images; SID is whatever value you gave during setup (typically in StartupBehavior_SetupVision.cc), duration is always 0
00063     wmVarEGID,        //!< Sends an event when a watched memory is changed; source id is pointer to WMEntry
00064     worldModelEGID,   //!< not being used, yet (for when objects are detected/lost?)
00065     numEGIDs          //!< the number of generators available
00066   };
00067 
00068   //! Holds string versions of each of the generator's names, handy for debugging so you can output the events as readable strings (you'll find this in EventBase.cc since it can't go in the header or we get multiply-defined errors during linking)
00069   static const char* const EventGeneratorNames[numEGIDs];
00070   
00071   //! an event type id is used to denote whether it's the first in a sequence (button down), in a sequence (button still down), or last (button up)
00072   enum EventTypeID_t {
00073     activateETID,   //!< Start of an event sequence, e.g. button down
00074     statusETID,     //!< Indicates a value has changed, e.g. new sensor readings
00075     deactivateETID, //!< Last of a series of events, e.g. button up
00076     numETIDs        //!< the number of different event types
00077   };
00078 
00079   /*! @name Constructors/Destructors */
00080   //! constructor
00081   /*! @see EventRouter::postEvent() */
00082   EventBase(); 
00083   EventBase(EventGeneratorID_t gid, unsigned int sid, EventTypeID_t tid, unsigned int dur=0);
00084   EventBase(EventGeneratorID_t gid, unsigned int sid, EventTypeID_t tid, unsigned int dur, const std::string& n, float mag);
00085   virtual ~EventBase() {} //!< destructor
00086   //@}
00087 
00088   /*! @name Methods */
00089   virtual const std::string& getName() const { return stim_id; } //!< gets the name of the event - useful for debugging, outputs
00090   virtual EventBase& setName(const std::string& n) { nameisgen=false; stim_id=n; return *this; } //!< sets name to a given string, prevents overwriting by generated names
00091 
00092   virtual float getMagnitude() const { return magnitude; } //!< gets "strength" of event - by default 1 for activate and status events, 0 for deactivate events
00093   virtual EventBase& setMagnitude(float m) { magnitude=m; return *this; }//!< sets "strength" of event - you may want to override the default values (see getMagnitude())
00094 
00095   virtual unsigned int getTimeStamp() const { return timestamp; } //!< time event was created
00096 
00097   virtual EventGeneratorID_t getGeneratorID() const { return genID; } /*!< @brief gets the generator ID for this event @see EventGeneratorID_t */
00098   virtual EventBase& setGeneratorID(EventGeneratorID_t gid) { genID=gid; genName(); return *this; } /*!< @brief sets the generator ID for this event @see EventGeneratorID_t */
00099   
00100   virtual unsigned int getSourceID() const { return sourceID; } /*!< @brief gets the source ID for this event @see sourceID */
00101   virtual EventBase& setSourceID(unsigned int sid) { sourceID=sid; genName(); return *this; } /*!< @brief sets the source ID for this event @see sourceID */
00102   
00103   virtual EventTypeID_t getTypeID() const { return typeID; } /*!< @brief gets the type ID @see EventTypeID_t */
00104   virtual EventBase& setTypeID(EventTypeID_t tid) { typeID=tid; genName(); return *this; } /*!< @brief sets the type ID @see EventTypeID_t */
00105 
00106   virtual unsigned int getDuration() const { return duration; } /*!< @brief gets the time since the beginning of this sequence (the timestamp of the activate event) @see duration */
00107   virtual EventBase& setDuration(unsigned int d) { duration = d; return *this; }/*!< @brief sets the time since the beginning of this sequence (the timestamp of the activate event) @see duration */
00108 
00109   virtual const std::string& resetName() { nameisgen=true; genName(); return stim_id; } //!< resets name to generated form, overwriting any previous name
00110   virtual bool isCustomName() const { return !nameisgen; } //!< returns true if not using the generated name
00111 
00112   inline bool operator<(const EventBase& e) const { return timestamp<e.timestamp; }
00113 
00114   //! is true if the genID, typeID, and sourceID's all match
00115   virtual bool operator==(const EventBase& eb) const {
00116     return (sourceID==eb.sourceID && genID==eb.genID && typeID==eb.typeID);
00117   }
00118   //!tests to see if events have the same generator and source IDs
00119   bool sameGenSource(const EventBase& eb) const { return genID==eb.genID && sourceID==eb.sourceID; }
00120   
00121   bool longerThan(const EventBase& eb) const { return duration>eb.duration && *this==eb; } //!< compares event duration and ensures same event generator, source, and type - useful for event masks
00122   bool shorterThan(const EventBase& eb) const { return duration<eb.duration && *this==eb; }//!< compares event duration and ensures same event generator, source, and type - useful for event masks
00123   bool equalOrLongerThan(const EventBase& eb) const { return duration>=eb.duration && *this==eb; }//!< compares event duration and ensures same event generator, source, and type - useful for event masks
00124   bool equalOrShorterThan(const EventBase& eb) const { return duration<=eb.duration && *this==eb; }//!< compares event duration and ensures same event generator, source, and type - useful for event masks
00125   //@}
00126 
00127   //! Useful for serializing events to send between processes
00128   /*! @name LoadSave interface */
00129   virtual unsigned int getBinSize() const;
00130   virtual unsigned int LoadBuffer(const char buf[], unsigned int len);
00131   virtual unsigned int SaveBuffer(char buf[], unsigned int len) const;
00132   //@}
00133  protected:
00134   std::string stim_id; //!< the name of the event, use the same name consistently or else will be seen as different stimuli
00135   float magnitude; //!< the current "strength" of the event/stimuli... MAKE SURE this gets set to ZERO IF event is DEACTIVATE
00136   unsigned int timestamp; //!< the time the event was created - set automatically by constructor
00137 
00138   bool nameisgen; //!< tracks whether the current name (stim_id) is generated or set
00139   virtual void genName(); //!< This does the actual generation of names based on genID, sourceID, and typeID
00140 
00141   EventGeneratorID_t genID; //!< generator ID, see EventGeneratorID_t
00142   EventTypeID_t typeID; //!< type ID, see EventTypeID_t
00143   unsigned int sourceID; /*!< @brief the source ID for this event
00144                           * Source IDs are defined by the generator that made it.  This should
00145                           * give authors flexibility to design their modules without having to
00146                           * worry about ID space collision */
00147   unsigned int duration; /*!< @brief the time since this sequence started (like, how long the
00148                           *   button has been pressed); not all generators will set this;
00149                           *   Typically, this would be 0 for activate,
00150                           *   (activate.timestamp-::get_time()) for status and deactivate */
00151 };
00152 
00153 /*! @file
00154  * @brief Describes EventBase, the basic class for sending events around the system
00155  * @author ejt (Creator)
00156  *
00157  * $Author: ejt $
00158  * $Name: tekkotsu-2_1 $
00159  * $Revision: 1.21 $
00160  * $State: Exp $
00161  * $Date: 2004/02/09 22:45:28 $
00162  */
00163 
00164 #endif

Tekkotsu v2.1
Generated Tue Mar 16 23:19:13 2004 by Doxygen 1.3.5