objectbase.h

Go to the documentation of this file.

/**
 * \file objectbase.h <gre/objectbase.h>
 * \brief Define base GRE object class
 *
 * \if NODOC
 * $Id: objectbase.h_v 1.3 2003/09/15 13:48:59 fileserver!dwilliss Exp $
 *
 * $Log: objectbase.h_v $
 * Revision 1.3  2003/09/15 13:48:59  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.2  2003/07/30 15:33:20  mju
 * Ignore private sections.
 *
 * Revision 1.1  2003/06/16 19:40:04  mju
 * Initial revision
 *
 * \endif
**/

#ifndef  INC_GRE_OBJECTBASE_H
#define  INC_GRE_OBJECTBASE_H

#ifndef  INC_GRE_BASE_H
   #include <gre/base.h>
#endif

#ifndef  INC_GRE_MSG_H
   #include <gre/msg.h>
#endif

#ifndef  INC_MI32_MICON_H
   #include <mi32/micon.h>
#endif

#ifndef INC_STRING_H
   #include <string.h>
   #define INC_STRING_H
#endif


//! Base class for other GRE "spatial" objects.
class GRE_OBJECT {

   public:

      typedef void (*CBFUNC)(const GRE_CALLBACK_MSG*, void*);

      //! Allocate index into private pointer array to attach to.
      //! @see GetPrivPtr, SetPrivPtr
      //! It is often desirable for a process or library module to attach "private"
      //! data to one or more GRE objects.  This can be done using AllocPrivIndex()
      //! to allocate an entry into each object's private pointer array.  This method
      //! should only be called the first time the private index is needed.  It is
      //! the programmer's responsibility to retain this private index value.  Once
      //! a private index is allocated, use SetPrivPtr() to attach data to any GRE
      //! object and GetPrivPtr() to retrieve previously attached data.
      static int AllocPrivIndex (
         );

      //! Constructor
      explicit GRE_OBJECT (
         GRE_OBJTYPE type                       //!< Object type to construct
         );

      //! Destructor.
      virtual ~GRE_OBJECT (
         ) = 0;

      //! Request destruction of this object.
      //! @return true if destroyed, false if destruction deferred.
      //! If an object is dynamically created then unless the destruction occurs
      //! in the same function as creation the Destroy() method should be used 
      //! instead.  This is especially true if destruction is to be performed within
      //! a GRE callback.  Using delete on an object withing a callback may result
      //! in unpredictable behavior.
      bool Destroy (
         bool NotifyParent = true               //!< Notify parent of child's destruction if appropriate
         ) { return (v_Destroy(NotifyParent)); }

      //! Get icon for this object type.
      MICON GetIcon (
         ) const { return (v_GetIcon()); }

      //! Get name of this object type.
      //! @return Pointer to constant string.
      const char* GetTypeName (
         ) const { return (v_GetTypeName()); }

      //! Get name of this object type in string.
      //! @return Pointer to string provided.
      char* GetTypeName (
         char *string                           //!< String to fill in
         ) { strcpy(string,GetTypeName()); return (string); }

      //! Add callback function to object.
      //!
      //! The new callback function will be added to the head of the list.
      //!
      //! Callbacks may be added to any GRE object.  When a callback occurs for a particular object
      //! the message is sent to that object's callback list and any "ancestor" object's callback
      //! lists as well.  A callback will be called if the object type for the message was included in
      //! the object types specified when the callback was added.  This often eliminates the need to
      //! add callbacks to every GRE object which is created.  If a program creates a single group
      //! and needs information about the group and layers within it then a callback can be added
      //! to the group with GRE_OBJTYPE_Group and GRE_OBJTYPE_Layer specified.  Then within the
      //! callback itself a determination of the object type may be done.  Alternatively two callbacks
      //! might be used, one specifying GRE_OBJTYPE_Group and the other specifying GRE_OBJTYPE_Layer.
      //! Both callbacks would be added to the group, but no check of the object type would be needed
      //! within the callback since only one object type was specified when each callback was added.
      void CallbackAdd (
         CBFUNC cbfunc,                         //!< Callback function
         void *cbdata,                          //!< "Hook" data to pass to callback
         GRE_OBJTYPE objtypes                   //!< Object types for which messages are requested
         ) { m_CallbackList.Add(cbfunc,cbdata,objtypes); }

      //! Invoke callbacks on object and its ancestors.
      //! This method is generally only invoked from within the GRE library itself.
      void CallbackInvoke (
         GRE_CALLBACK_MSG::ACTION action,
         GRE_VIEW *view = 0,
         ELEMTYPE elemtype = ELEMTYPE_Empty
         ) { GRE_CALLBACK_MSG msg(action,this,view,elemtype); CallbackInvoke(msg); }
         
      //! Invoke callbacks on object and its ancestors.
      //! This method is generally only invoked from within the GRE library itself.
      void CallbackInvoke (
         GRE_CALLBACK_MSG::ACTION action,
         ELEMTYPE elemtype
         ) { GRE_CALLBACK_MSG msg(action,this,elemtype); CallbackInvoke(msg); }
         
      //! Invoke callbacks on object and its ancestors.
      //! This method is generally only invoked from within the GRE library itself.
      void CallbackInvoke (
         GRE_VIEW *view,
         GRE_CALLBACK_MSG::ACTION action
         ) { GRE_CALLBACK_MSG msg(action,this,view); CallbackInvoke(msg); }
         
      //! Invoke callbacks on object and its ancestors.
      //! This method is generally only invoked from within the GRE library itself.
      void CallbackInvoke (
         const GRE_CALLBACK_MSG& msg
         );
      
      //! Remove callback function.
      //! All callbacks are automatically removed when the object is destroyed.
      //! However, if the data specified when the callback was added is freed 
      //! before the object is destroyed, all callbacks referencing that data
      //! should be removed.  In this case, the cbfunc may be specified as NULL
      //! and the cbdata should be the pointer about to be freed.  This will
      //! remove all callbacks referencing that pointer in a single step.
      void CallbackRemove (
         CBFUNC cbfunc,                         //!< Callback function, matching CallbackAdd, or NULL to match all
         void *cbdata,                          //!< Callback data, matching CallbackAdd
         GRE_OBJTYPE objtypes = GRE_OBJTYPE_All //!< Object types
         ) { m_CallbackList.Remove(cbfunc,cbdata,objtypes); }

      //! Determine if destruction has been requested for this object.
      //! Sometimes a callback may be invoked on an object after destruction has been
      //! requested on that object.  This may occur if destruction occurs in a callback
      //! and more callbacks are in the list after the one destroying the object.  In
      //! order to avoid unwanted processing or errors it may be necessary to determine
      //! if an object has been requested to be destroyed.  This is only useful within
      //! a callback since once the callbacks are completed the destruction will finish
      //! and thus the object will no longer exist.
      bool DestroyRequested (
         ) const { return (m_DestroyRequested); }

      //! Get "private" pointer for this object.
      //! @see AllocPrivIndex, SetPrivPtr
      void *GetPrivPtr (
         int idx                                //!< Private index obtained from AllocPrivIndex()
         ) const { return (m_PrivData[idx]); }

      //! Get GRE object type
      GRE_OBJTYPE GetType (
         ) const { return (m_objtype); }

      //! Determine if object in process of being destroyed.
      //! Sometimes a callback may be invoked on an object after destruction has begun
      //! on that object. In order to avoid unwanted processing or errors it may be
      //! necessary to determine if an object is in the process of being destroyed.
      //! This is only useful within a callback since once the callbacks are completed
      //! the destruction will finish and thus the object will no longer exist.
      bool IsBeingDestroyed (
         ) const { return (m_BeingDestroyed); }

      //! Set "private" pointer for this object.
      //! When an object is destroyed, the private pointers are NOT freed by the GRE
      //! system.  Thus it is the programmers responsibility to see that allocated data
      //! attached to an object is freed at the appropriate time, usually by checking for
      //! ACTION_Destroy in the callback message.
      //! @see GetPrivPtr, AllocPrivIndex
      void SetPrivPtr (
         int idx,                               //!< Private index obtained from AllocPrivIndex()
         void *privptr                          //!< Pointer value to set.
         ) { m_PrivData[idx] = privptr; }

   protected:

      //! Determine if callbacks are currently being invoked on this object.
      bool CallbacksBeingInvoked (
         ) const { return (m_CallbackList.BeingInvoked()); }

      //! Notify object that is being destroyed, usually called by Destroy() method
      void SetBeingDestroyed (
         ) { m_BeingDestroyed = true; }

      //! Request destruction of object, usually called by Destroy() method
      void SetDestroyRequest (
         ) { m_DestroyRequested = true; }

   private:

      #ifndef GENERATING_DOXYGEN_OUTPUT

      // GRE_OBJECT::CBFUNCLIST
      //! Callback function list.
      class CBFUNCLIST {
         public:

            CBFUNCLIST (
               );

            ~CBFUNCLIST (
               );

            //! Add function to callback list
            void Add (
               CBFUNC cbfunc,                   //!< Function to add
               void *cbdata,                          //!< "Hook" data to pass to function
               GRE_OBJTYPE objtypes                   //!< Object type(s) for which messages are requested
               );

            //! Determine if callback list is currently being invoked.
            bool BeingInvoked (
               ) const { return (m_callcount > 0); }

            //! Invoke callbacks in list with specified message.
            void Invoke (
               const GRE_CALLBACK_MSG& msg            //!< Message
               );

            //! Remove function from callback list
            void Remove (
               CBFUNC cbfunc,                   //!< Function to remove, NULL to match all
               void *cbdata,                          //!< "Hook" data, must match value used in Add, or NULL to match all
               GRE_OBJTYPE objtypes = GRE_OBJTYPE_All //!< Object type(s) to match
               );

         private:
            // GRE_OBJECT::CBFUNCLIST::ITEM
            class ITEM {
               public:

                  ITEM (
                     CBFUNC cbfunc,
                     void *cbdata,
                     GRE_OBJTYPE objtypes
                     );

                  CBFUNC m_cbfunc;
                  void *m_cbdata;
                  GRE_OBJTYPE m_objtypes;
                  ITEM *m_next;
               };

            ITEM *m_first;
            UINT16 m_callcount;
            bool m_DidRemove;
         };

      static int s_PrivDataCount;            //!< Number of private data index entries used
      static int s_PrivDataAlloc;            //!< Number of private data index entries allocated

      const GRE_OBJTYPE m_objtype;           //!< Object type
      void **m_PrivData;                     //!< Private data for modules to attach stuff to
      CBFUNCLIST m_CallbackList;             //!< Callback list
      bool m_DestroyRequested;               //!< Destroy requested while in callback
      bool m_BeingDestroyed;                 //!< Object in process of being destroyed

      #endif //!< GENERATING_DOXYGEN_OUTPUT

      //! Overridables.
      virtual bool v_Destroy (bool NotifyParent) = 0;
      virtual MICON v_GetIcon () const = 0;
      virtual const char* v_GetTypeName () const = 0;
   };


#endif   //!< INC_GRE_OBJECTBASE_H

---