Crazy Eddie's GUI System  0.8.7
CEGUI::Event Class Reference

Defines an 'event' which can be subscribed to by interested parties. More...

+ Inheritance diagram for CEGUI::Event:
+ Collaboration diagram for CEGUI::Event:

Classes

class  ScopedConnection
 Event::Connection wrapper that automatically disconnects the connection when the object is deleted (or goes out of scope). More...
 

Public Types

typedef RefCounted< BoundSlotConnection
 Connection object. This is a thin 'smart pointer' wrapper around the actual BoundSlot that represents the connection. You can use this object to inspect the current connection state and also to disconnect from the event.
 
typedef CEGUI::SubscriberSlot Subscriber
 Subscriber object type. This is now just a typedef to SubscriberSlot, the use of the name Event::Subscriber is maintained for hostorical and compatability reasons.
 
typedef unsigned int Group
 Type for a subscriber group. You can use the subscriber group to order calls to multiple subscribers. Groups are called in ascending order, with subscribers with no group called last.
 

Public Member Functions

 Event (const String &name)
 Constructs a new Event object with the specified name.
 
virtual ~Event ()
 Destructor for Event objects. Note that this is non-virtual and so you should not sub-class Event.
 
const StringgetName (void) const
 Return the name given to this Event object when it was created. More...
 
Connection subscribe (const Subscriber &slot)
 Subscribes some function or object to the Event. More...
 
Connection subscribe (Group group, const Subscriber &slot)
 Subscribes some function or object to the Event. More...
 
void operator() (EventArgs &args)
 Fires the event. All event subscribers get called in the appropriate sequence. More...
 

Protected Types

typedef std::multimap< Group, Connection, std::less< Group > CEGUI_MULTIMAP_ALLOC(Group, Connection)> SlotContainer
 

Protected Member Functions

void unsubscribe (const BoundSlot &slot)
 Disconnects and removes the given BoundSlot from the collection of bound slots attached to this Event, thus 'unsubscribing' it. More...
 
 Event (const Event &)
 
Eventoperator= (const Event &)
 

Protected Attributes

SlotContainer d_slots
 Collection holding ref-counted bound slots.
 
const String d_name
 Name of this event.
 

Friends

void CEGUI::BoundSlot::disconnect ()
 

Detailed Description

Defines an 'event' which can be subscribed to by interested parties.

An Event can be subscribed by a function, a member function, or a function object. Whichever option is taken, the function signature needs to be as follows:

bool function_name(const EventArgs& args);
Note
An Event object may not be copied.

Member Function Documentation

const String& CEGUI::Event::getName ( void  ) const
inline

Return the name given to this Event object when it was created.

Returns
String object containing the name of the Event object.
void CEGUI::Event::operator() ( EventArgs args)

Fires the event. All event subscribers get called in the appropriate sequence.

Parameters
argsAn object derived from EventArgs to be passed to each event subscriber. The 'handled' field will be set to true if any of the called subscribers return that they handled the event.
Returns
Nothing.
Connection CEGUI::Event::subscribe ( const Subscriber slot)

Subscribes some function or object to the Event.

Parameters
subscriberA function, static member function, or function object, with the signature void function_name(const EventArgs& args). To subscribe a member function you should explicitly create an Event::Subscriber as this parameter.
Returns
A Connection object which can be used to disconnect (unsubscribe) from the Event, and also to check the connection state.
Connection CEGUI::Event::subscribe ( Group  group,
const Subscriber slot 
)

Subscribes some function or object to the Event.

Parameters
groupThe Event group to subscribe to, subscription groups are called in ascending order, followed by subscriptions with no group. Note that calling order of connections to the same group is unspecified.
subscriberA function, static member function, or function object, with the signature void function_name(const EventArgs& args). To subscribe a member function you should explicitly create an Event::Subscriber as this parameter.
Returns
A Connection object which can be used to disconnect (unsubscribe) from the Event, and also to check the connection state.
void CEGUI::Event::unsubscribe ( const BoundSlot slot)
protected

Disconnects and removes the given BoundSlot from the collection of bound slots attached to this Event, thus 'unsubscribing' it.

Note
This is an implementation member, and is not available to client code. In order to detach / unsubscribe from an Event you should be using the Connection object(s) returned when you initially subscribed.