jem::util::Delegate< Args > Class Template Reference

Represents a call-back function that will be invoked by an event. More...

#include <jem/util/event/Delegate.h>

Inheritance diagram for jem::util::Delegate< Args >:

Public Types
typedef Args	Arguments
	A struct that bundles the arguments of an event. More...

Public Member Functions
virtual void	call (const Arguments &args)=0
	Invokes the call-back represented by this object. More...
virtual bool	isConnected () const =0
	Tests whether the call-back represented by this object still exists. More...
Public Member Functions inherited from jem::util::AbstractDelegate
virtual bool	equals (AbstractDelegate *rhs) const =0
	Tests whether this delegate is equal to another delegate. More...

Protected Member Functions
virtual	~Delegate ()
	Protected destructor. More...
Protected Member Functions inherited from jem::util::AbstractDelegate
virtual	~AbstractDelegate ()
	Protected destructor. More...

Detailed Description

template<class Args>
class jem::util::Delegate< Args >

The Delegate class represents a call-back function that is invoked by an Event object. The template parameter Args is a class that bundles the arguments of an event. This parameter equals the Arguments type defined by the event to which a Delegate is connected.

The Delegate class essentially provides two public functions: call() and isConnected(). The first is called when the emit() function is invoked on the event to which a delegate has been connected. The second is called by an Event to test whether a Delegate is still useable. If this function returns false, the Delegate will be deleted.

If you want to implement your own delegate type, you should take the following steps: define a class that is derived from the Delegate class; implement the call() and isConnected() member functions; and implement a non-member function that creates an instance of your class and that connects this instance to an event. The following example illustrates these steps for a delegate type that encapsulates a call-back function with a single argument.

template <class Args, class Func>
  class MyDelegate : public Delegate
{
 public:

  explicit MyDelegate ( Func func ) : func_ ( func )
  {}

  virtual bool isConnected () const
  {
    return true;  // Since a function is never deleted.
  }

  virtual void call ( const Args& args )
  {
    func_ ( args.first );
  }


 private:

  Func func_;
};

template <class E, class F>
  void myConnect ( E& event, F func )
{
  event.connectTo (
    new MyDelegate< typename E::Arguments, F > ( func )
  );
}

See also

Event

Member Typedef Documentation

template<class Args >

typedef Args jem::util::Delegate< Args >::Arguments

The Arguments type is a simple struct that bundles the arguments of an event. It is an alias for the template parameter Args, that equals the Arguments type defined by the event to which this Delegate has been connected.

See also

call()

Constructor & Destructor Documentation

template<class Args >

virtual jem::util::Delegate< Args >::~Delegate ( )

protectedvirtual

The destructor of the Delegate class is declared protected because only an Event should be able to delete an instance of the Delegate class. This is to avoid situations in which an Delegate is deleted more than once.

Classes derived from the Delegate class should also declare their destructor protected.

Member Function Documentation

template<class Args >

virtual void jem::util::Delegate< Args >::call ( const Arguments &  args )

pure virtual

Invokes the call-back function represented by this Delegate object. The call member function by the emit member function of the Event class. The argument args is a simple struct that bundles the arguments of the emit function. This struct has the following members:

• ARGUMENT_COUNT - a static member of type const int that equals the number of arguments that were passed to the emit function.

• first - a copy of the first argument passed to the emit function. This member only exists when emit was called with one or more arguments.

• second - a copy of the second argument passed to the emit function. This member only exists when emit was called with two or more arguments.

• third - a copy of the third argument passed to the emit function. This member only exists when emit was called with three arguments.

Note that you do not have to test explicitly whether the members first, second and third exist; the compiler will emit an error if you try to use a non-existing member.

Parameters

args	- a struct bundling the arguments of the emit function of the Event class.

template<class Args >

virtual bool jem::util::Delegate< Args >::isConnected ( ) const

pure virtual

Tests whether the call-back function represented by this Delegate object still exists. If, for instance, this Delegate represents a non-static member function of some object, then this function should return false if that object has been deleted, and true otherwise.

This function is called by an Event to test whether a Delegate is still useable. If this function returns false, then the Delegate will be deleted.

Returns

true if the call-back represented by this object still exists, and false otherwise.

Implements jem::util::AbstractDelegate.