Phx::BaseListener< Notifier, Listener > Class Template Reference

The base listener class used for a notifier that allows a single listener. More...

#include <PhxListeners.h>

Inheritance diagram for Phx::BaseListener< Notifier, Listener >:

List of all members.

Public Member Functions
	BaseListener (void)
	Constructs a base listener that has no notifier.
virtual	~BaseListener (void)
	Destructs the listener.
Protected Member Functions
Notifier *	notifier (void)
	Acquires a pointer to the notifier that this listener is installed in.
Friends
class	Manager
Classes
class	Manager
	This Manager class does the work of maintaining a listener object. More...

---

Detailed Description

template<class Notifier, class Listener>
class Phx::BaseListener< Notifier, Listener >

The base listener class used for a notifier that allows a single listener.

This class is meant to aid implementors in providing standardized listeners with minimal code investment for each use. To make use of this class, the "notifier" class (which is providing the listener interface to a client), defines a listener subclass within its own scope, deriving from this template class. The name of the notifier's class is the first template parameter, and the name of the embedded listener class is the second parameter.

In addition to defining a base class for the listener object, this class also includes a manager object that takes care of the logistics of installing and uninstalling listeners for you. See BaseListener::Manager for its API, or continue on to see the salient points in the example below.

Below is an example of a notifier class and its accompanying listener object. This notifier defers to the BaseListener::Manager for all of its operations. Take note of the syntax used to invoke a listener that is held by the manager. Constructing a notifier and listener boils down to a few simple steps, each labeled in the example (not in a particular order).

 class MyNotifier : public LockedPtrInterface<MyNotifier> {
 public:
    // Step 1.  Define our listener class with our notification methods.
    // It derives from BaseListener with the template parameters being
    // the name of our notifier class, and the name of this listener class.
    class MyListener : public BaseListener<MyNotifier, MyListener> {
        virtual void onMyNotification(void);
        virtual void onMyOtherNotification(uint32_t parameter);
    };

    // Step 2.  The constructor must give a pointer to "this" to the manager.
    MyNotifier() : mListenerManager(this) {}

    // Step 3.  Give the client a way to install a listener, and just bounce
    // this call to the manager that's in charge of that listener type.
    void listener(MyListener* listener) {
       // The notifier just defers to the manager to store the listener
       mListenerManager.listener(listener);
    }

    // Step 4.  Here's how you invoke the listener.  You would normally make this
    // a private method in the implementation which was called when the listener
    // needed to be notified.
    void notifyMyListener(void) {
       // This is how the notifier invokes the listener
       MyListener* listener = mListenerManager.listener();
       if (listener) listener->onMyNotification();
    }

 private:
   // Step 5.  Define the manager object that takes care of the listener
   // objects for us.
   MyListener::Manager mListenerManager;
 };

See also:

BaseListener::Manager

---

Member Function Documentation

template<class Notifier, class Listener> Notifier* Phx::BaseListener< Notifier, Listener >::notifier (  void   )  [inline, protected]

Acquires a pointer to the notifier that this listener is installed in. Note that the value to which this method refers changes when the notifier's listener is changed (that is, when this listener is installed or uninstalled from a notifier). Thus, any access to these must not occur when this listener is being installed or uninstalled (which includes times when the notifier is being deleted). The Notifier will not uninstall the listener while it is being called, hence this attribute may not be changed during the listener callback and the listener may assume that it is safe to access this attribute. At all other times, no such guarantee is made. For this reason, this attribute should not be accessed except during the callback -- it is declared protected to encourage this. Returns: A pointer to the notifier that this listener was installed into.

---

The documentation for this class was generated from the following file:

• PhxListeners.h

---