observer.h

Go to the documentation of this file.

/******************************************************************************
 *
 * \file observer.h <mi32/observer.h>
 * \brief Observer Pattern Class definition
 *
 * Currently, this only implements the Client/Server type of Observer Pattern.
 * That is, one in which you have a SUBJECT class which hangs around and is
 * a source of events, and multiple clients or OBSERVERs which come and go and
 * want to recieve messages from the SUBJECT.
 *
 * The other form of Observer Pattern is the Big Brother approach.  That is,
 * You have one OBSERVER which monitors the coming and going of SUBJECTS.
 * This is a bit more complicated because in the generic case, your SUBJECTs
 * could be in multiple threads.  This isn't implemented yet.
 *
 * \if NODOC
 * $Id: observer.h_v 1.19 2003/09/15 15:37:51 dwilliss Exp $
 *
 * $Log: observer.h_v $
 * Revision 1.19  2003/09/15 15:37:51  dwilliss
 * More mismatched #ifdefs
 *
 * Revision 1.18  2003/09/15 15:28:13  dwilliss
 * Fixed doxygen cleanup errors. Unbalanced ifdefs
 *
 * Revision 1.17  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.16  2003/09/11 20:15:24  dwilliss
 * Added typename keyword to avoid g++ compiler warnings
 *
 * Revision 1.15  2003/04/09 19:20:28  dwilliss
 * Don't use _T in templates.  Mac's ctype.h defines a global _T.  Thanks Apple!
 *
 * Revision 1.14  2003/01/24 14:22:55  mju
 * Attempt to fix Unix warnings with typedef of OBSERVERLIST_ITERATOR.
 *
 * Revision 1.13  2002/09/13 20:50:24  dwilliss
 * Nope!  MS VC++ acccepted that, but gcc changed the warning to an error!
 *
 * Revision 1.12  2002/09/13 20:28:12  dwilliss
 * Try to fix a "typename is implicitly defined" warning from gcc 3.1
 *
 * Revision 1.11  2002/08/26 14:46:44  dwilliss
 * Clear up some warnings from new gcc 3.1 (I hope)
 *
 * Revision 1.10  2000/10/16 15:05:13  dwilliss
 * Internal iterator constructor should take const reference, not by value
 *
 * Revision 1.9  2000/10/13 16:20:07  dwilliss
 * Be more specific about who our friends are
 *
 * Revision 1.8  2000/10/13 16:04:16  dwilliss
 * Mac doesn't like typedef of MILIST<_CT*> OBSERVERLIST
 *
 * Revision 1.7  2000/10/13 14:59:40  dwilliss
 * Must use "friend class NAME", not "friend NAME"
 *
 * Revision 1.6  2000/10/12 16:15:52  mju
 * Keep sample code out of Genitor docs.
 *
 * Revision 1.5  2000/08/24 14:13:54  dwilliss
 * Changed ITERATOR's operator-> to hopefully compile on Mac
 *
 * Revision 1.4  2000/08/23 14:13:16  dwilliss
 * Fixed a Unix compile problem
 *
 * Revision 1.3  2000/08/23 13:53:44  dwilliss
 * Trying to fix weird Mac-only compile error involving const.
 *
 * Revision 1.2  2000/08/21 21:26:52  dwilliss
 * *** empty log message ***
 *
 * Revision 1.1  2000/08/01 17:30:58  dwilliss
 * Initial revision
 *
 * \endif
 *****************************************************************************/

#ifndef INC_MI32_OBSERVER_H
#define INC_MI32_OBSERVER_H

#ifndef INC_MI32_MILIST_H
#include <mi32/milist.h>
#endif

#ifndef GENERATING_DOXYGEN_OUTPUT
class OBSERVER_BASE;

//! Don't derive from this class directly.  It's the base class for
//! SUBJECT<>
class SUBJECTBASE {
   public:

      SUBJECTBASE (
         ) {
         }

      virtual ~SUBJECTBASE (
         ) {
         }

   private:
      //! The following virtual methods are private.  Only the friend
      //! class OBSERVER_BASE may call them
      virtual void AddObserver (
         OBSERVER_BASE* observer
         ) = 0;

      virtual void RemoveObserver (
         OBSERVER_BASE* observer
         ) = 0;

      friend class OBSERVER_BASE;
   };
#endif //!< GENERATING_DOXYGEN_OUTPUT


//! Base class for the SUBJECT of the OBSERVER (the observed).
//! For an example of how to use this, see the end of this include file.
template <class _CT = class OBSERVER_BASE> class SUBJECT : public SUBJECTBASE {
   public:

      typedef MILIST<_CT*> OBSERVERLIST;
      typedef typename OBSERVERLIST::ITERATOR OBSERVERLIST_ITERATOR;

      class ITERATOR {
         public:
            //! Default constructor
            ITERATOR (
               ) {}

            //No copy constructor?  Hmmm.. MILIST<>ITERATOR didn't have one
            // and that's what I used as a reference for this.

            //! Dereference operator - returns ref to item
            _CT*& operator* ( 
               ) const {
               return (*m_it);
               }

            //! Dereference operator ptr to item
            _CT* operator-> ( 
               ) {
               return (*m_it);
               }

            //! Pre-increment operator
            ITERATOR& operator++ (
               ) {
               m_it = m_next;
               ++m_next;
               return (*this);
               }

            bool operator== (
               const ITERATOR& rhs
               ) const {
               return (m_it == rhs.m_it);
               }

            bool operator!= (
               const ITERATOR& rhs
               ) const {
               return (m_it != rhs.m_it);
               }

         private:
            #ifndef GENERATING_DOXYGEN_OUTPUT
            friend class SUBJECT<_CT>;
            OBSERVERLIST_ITERATOR m_it;
            OBSERVERLIST_ITERATOR m_next;

            //! Internal constructor
            ITERATOR (
               const OBSERVERLIST_ITERATOR& it
               ) {
               m_it = it;
               m_next = it;
               ++m_next;
               }

            //! Used internally by SUBJECT<>::RemoveItem()
            OBSERVERLIST_ITERATOR& GetIterator (
               ) {
               return (m_it);
               }
            #endif //!< GENERATING_DOXYGEN_OUTPUT

         };

      //! Default constructor. (nothing to do).
      SUBJECT (
         ) {
         }

      //! Destructor.
      //! Iterates through the list of OBSERVERs and calls their OnSubjectDestroy methods.
      virtual ~SUBJECT (
         ) {
         for (ITERATOR it = ObserverBegin() ; it != ObserverEnd() ; ++it) {

            (*it)->OnSubjectDestroy();
            }
         }

      //! Call the OnNotify method of all the observers.
      //! If other event handlers are needed, they would be implemented as
      //! virtual methods in the OBSERVER-derived class, and the SUBJECT-
      //! derived class would be given methods to call them.
      void NotifyObservers (
         ) {
         for (ITERATOR it = ObserverBegin() ; it != ObserverEnd() ; ++it) {

            (*it)->OnNotify();
            }
         return;
         }

   protected:

      //! Return an iterator to the first Observer.
      //! Note: Named ObserverBegin() to avoid possible conflict if derived
      //! class wants a Begin() method.
      ITERATOR ObserverBegin (
         ) {
         return (ITERATOR(m_Observers.Begin()));
         }

      //! Return an iterator to the end of the Observer list
      //! Note: Named ObserverBegin() to avoid possible conflict if derived
      //! class wants a Begin() method.
      ITERATOR ObserverEnd (
         ) {
         return (ITERATOR(m_Observers.End()));
         }

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      MILIST<_CT*> m_Observers;

      //! Add an observer.  
      void AddObserver (
         OBSERVER_BASE* observer
         ) {
         m_Observers.PushFront(static_cast<_CT*>(observer));
         }

      //! Remove an observer.  
      //! Called by OBSERVER's destructor. Only OBSERVER should be able to to 
      //! call this, so it's private and OBSERVER is a friend class.
      void RemoveObserver (
         OBSERVER_BASE* observer
         ) {
         for (ITERATOR it = ObserverBegin() ; it != ObserverEnd() ; ++it) {
            if ((*it) == static_cast<_CT*>(observer)) {
               m_Observers.Remove(it.GetIterator());
               break;
               }
            }  
         return;
         }
      #endif //!< GENERATING_DOXYGEN_OUTPUT

   };


//! Base class for an Observer.
//!
//! For simple cases, there is a virtual method Notify() which the
//! SUBJECT can call.  For more complicated usage, see the example
//! at the end of this include file.
//!
class OBSERVER_BASE {
   public:

      //! Constructor taking a SUBJECT reference.
      //! Will arrange to be notified when subject 
      //! changes anything
      OBSERVER_BASE (
         SUBJECTBASE& subject
         ) :
         m_subject(&subject),
         m_bAttached(false)      //! Attach will set this to true
         {
         Attach();
         }
         
      //! Copy constructor
      OBSERVER_BASE (
         const OBSERVER_BASE& rhs
         ) :
         m_subject(rhs.m_subject),
         m_bAttached(false)      //! Attach will set this to true
         {
         Attach();
         }
         
      //! Destructor
      virtual ~OBSERVER_BASE (
         ) {
         //! Remove ourselves from the SUBJECT's observer list.  
         //! SUBJECT's destructor will call our OnSubjectDestroy method, which will set 
         //! m_subject to NULL so that we won't try to remove ourselves from 
         //! a subject that no longer exists.
         Detach();
         }

            //! Assignment operator.
      OBSERVER_BASE& operator= (
         const OBSERVER_BASE& rhs
         ) {
         //! Don't bother doing anything unless rhs points to a different SUBJECT
         if (&rhs != this && rhs.m_subject != m_subject) {
            if (m_subject != 0) m_subject->RemoveObserver(this);
            m_subject = rhs.m_subject;
            if (m_subject != 0) m_subject->AddObserver(this);
            }
         return (*this);
         }


      void Attach (
         ) {
         if (m_subject == 0 || m_bAttached) return;
         m_subject->AddObserver(this);
         m_bAttached = true;
         return;
         }

      void Detach (
         ) {
         if (m_subject == 0 || !m_bAttached) return;
         m_subject->RemoveObserver(this);
         m_bAttached = false;
         return;
         }

      bool IsAttached (
         ) const {
         return (m_bAttached);
         }

      //! Called by m_subject's destructor to tell us it's going away.
      //! (Could be made private if we made SUBJECT a friend)
      void OnSubjectDestroy (
         ) {
         m_subject = 0;
         }

      //! Virtual method which the SUBJECT will call when it's NotifyObservers()
      //! method is called.
      //! If other event handlers are needed, they would be implemented as
      //! virtual methods in the OBSERVER-derived class, and the SUBJECT-
      //! derived class would be given methods to call them.
      virtual void OnNotify (
         ) {
         }

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      SUBJECTBASE* m_subject;
      bool m_bAttached;
      #endif //!< GENERATING_DOXYGEN_OUTPUT

   };



#ifndef GENERATING_DOXYGEN_OUTPUT
#if 0
//! Example Code

#ifndef INC_MI32_RECT_H
#include <mi32/rect.h>
#endif

class THINGY;

//! Example of a derived SUBJECT which knows about the event handling
//! methods of a class derived from OBSERVER_BASE.
//! When declaring the derived class, you have to also specify which
//! OBSERVER_BASE-derived class you want this to be the subject of.
class EVENTPUMP : public SUBJECT<THINGY> {
   public:

      //! Method to call THINGY::OnRedraw().
      //! Actual method can't be defined inline.  We can't reference things
      //! in THINGY until we've defined EVENTPUMP.  And we can't define
      //! THINGY until we've defined EVENTPUMP.  I tried forward declaring
      //! class EVENTPUMP : public SUBJECT<THINGY> but that won't compile.
      void CallOnRedraw (
         const DRECT2D& rect
         );
      };

//! Example of an OBSERVER-derived class.  
//! This class adds the additional event handler OnDraw().
class THINGY : public OBSERVER_BASE {
   public:
      THINGY (
         EVENTPUMP& pump
         ) :
         OBSERVER_BASE(pump)
         {
         }

      virtual ~THINGY (
         ) {
         }
         
      //! Example of adding a new event handler to the derived class       
      //! New handler can take anything you want, but the SUBJECT-derived
      //! class has to know to call it.
      virtual void OnRedraw (
         const DRECT2D& rect
         );
   };


void EVENTPUMP::CallOnRedraw (
   const DRECT2D& rect
   ) {
   for (ITERATOR it = ObserverBegin() ; it != ObserverEnd() ; ++it) {

      (*it)->OnRedraw(rect);
      }
   return;
   }

#endif      //!< End of example code
#endif //!< GENERATING_DOXYGEN_OUTPUT

#endif      //!< INC_MI32_OBSERVER_H

---