Interface providing event signaling and handling. More...

Inherited by CEGUI::Element, CEGUI::Font, CEGUI::GlobalEventSet, CEGUI::MouseCursor, CEGUI::RenderingSurface, CEGUI::RenderTarget, CEGUI::ResourceEventSet, CEGUI::System, and CEGUI::WindowManager.

Public Types
typedef ConstMapIterator< EventMap >	EventIterator

Public Member Functions
	EventSet ()
	Constructor for EventSet objects.

virtual	~EventSet (void)
	Destructor for EventSet objects.

void	addEvent (const String &name)
	Creates a new Event object with the given name and adds it to the EventSet. More...

void	addEvent (Event &event)
	Adds the given Event object to the EventSet. Ownership of the object passes to EventSet and it will be deleted when it is removed from the EventSet - whether explicitly via removeEvent or when the EventSet is destroyed. More...

void	removeEvent (const String &name)
	Removes the Event with the given name. All connections to the event are disconnected, and the underlying Event object is destroyed. More...

void	removeEvent (Event &event)
	Removes the given event from the EventSet. All connections to the event are disconnected, and the event object is destroyed. More...

void	removeAllEvents (void)
	Remove all Event objects from the EventSet. Add connections will be disconnected, and all Event objects destroyed.

bool	isEventPresent (const String &name)
	Checks to see if an Event with the given name is present in this EventSet. More...

virtual Event::Connection	subscribeEvent (const String &name, Event::Subscriber subscriber)
	Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...

virtual Event::Connection	subscribeEvent (const String &name, Event::Group group, Event::Subscriber subscriber)
	Subscribes a handler to the specified group of the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...

template<typename Arg1 , typename Arg2 >
Event::Connection	subscribeEvent (const String &name, Arg1 arg1, Arg2 arg2)
	Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...

template<typename Arg1 , typename Arg2 >
Event::Connection	subscribeEvent (const String &name, Event::Group group, Arg1 arg1, Arg2 arg2)
	Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...

virtual Event::Connection	subscribeScriptedEvent (const String &name, const String &subscriber_name)
	Subscribes the named Event to a scripted funtion. More...

virtual Event::Connection	subscribeScriptedEvent (const String &name, Event::Group group, const String &subscriber_name)
	Subscribes the specified group of the named Event to a scripted funtion. More...

virtual void	fireEvent (const String &name, EventArgs &args, const String &eventNamespace="")
	Fires the named event passing the given EventArgs object. More...

bool	isMuted (void) const
	Return whether the EventSet is muted or not. More...

void	setMutedState (bool setting)
	Set the mute state for this EventSet. More...

Event *	getEventObject (const String &name, bool autoAdd=false)
	Return a pointer to the Event object with the given name, optionally adding such an Event object to the EventSet if it does not already exist. More...

EventIterator	getEventIterator (void) const
	Return a EventSet::EventIterator object to iterate over the events currently added to the EventSet.

Protected Types
typedef std::map< String, Event , StringFastLessCompare CEGUI_MAP_ALLOC(String, Event )>	EventMap

Protected Member Functions
void	fireEvent_impl (const String &name, EventArgs &args)
	Implementation event firing member.

ScriptModule *	getScriptModule () const
	Helper to return the script module pointer or throw.

	EventSet (EventSet &)

	EventSet (const EventSet &)

EventSet &	operator= (EventSet &)

EventSet &	operator= (const EventSet &)

Protected Attributes
EventMap	d_events

bool	d_muted
	true if events for this EventSet have been muted.

Detailed Description

Interface providing event signaling and handling.

The EventSet is a means for code to attach a handler function to some named event, and later, for that event to be fired and the subscribed handler(s) called.

Its purpose is similar to Qt's signal and slot system, you can think of Event name as the signal and the subscribed handler as the slot.

Each Event has a name and a set of handlers. Handlers can be free functions, class member functions or even functors. Whenever an Event is fired all of its handlers are invoked. You are most likely looking for a way to react to mouse clicks or other events fired internally by CEGUI.

The handlers have to have a very specific signature. They have to return bool and they have to take const EventArgs&. If this is not met you will encounter build errors!

Reacting to internal CEGUI events

bool handler(const EventArgs& args)
{
    std::cout << "Don't you dare click me again!" << std::endl;
    // returning true means we handled the Event and it doesn't need to be
    // propagated any further
    return true;
}
void example()
{
    CEGUI::Window* wnd = ...;
    wnd->subscribeEvent(CEGUI::Window::EventMouseClick, &handler);
}

A contrived example of various handler types

bool freeFunction(const EventArgs& args)
{
    // your handler code here
}
// nothing special about this class!
class CustomClass
{
    public:
        bool memberFunction(const EventArgs& args)
        {
            // your handler code here
        }
        static bool staticMemberFunction(const EventArgs& args)
        {
            // your handler code here
        }
        bool memberFunctionWithArg(const EventArgs& args, bool something)
        {
            // your handler code here
        }
};
class Functor
{
    public:
        bool operator()(const EventArgs& args)
        {
            // your handler code here
        }
}
void example()
{
    CustomClass instance;
    CEGUI::Window* wnd = ...;
    // creates "CustomEvent", subscribes freeFunction to it
    wnd->subscribeEvent("CustomEvent", &freeFunction);
    // subscribes memberFunction of "instance" to CustomEvent
    wnd->subscribeEvent("CustomEvent", &CustomClass::memberFunction, &instance);
    // subscribes staticMemberFunction of CustomClass to CustomEvent
    wnd->subscribeEvent("CustomEvent", &CustomClass::staticMemberFunction);
    // subscribes Functor to CustomEvent, Functor instance is owned by EventSet
    // after this call, it will be destroyed by EventSet
    wnd->subscribeEvent("CustomEvent", Functor());
    // Advanced subscribers using boost::bind follow:
    // subscribes memberFunctionWithArg of CustomClass to CustomEvent
    wnd->subscribeEvent("CustomEvent", boost::bind(&CustomClass::memberFunctionWithArg, _1, _2, true), &instance);
    // same as above, binding the instance itself as well
    wnd->subscribeEvent("CustomEvent", boost::bind(&CustomClass::memberFunctionWithArg, instance, _1, true));
    // the following line causes all subscribed handlers to be called
    wnd->fireEvent("CustomEvent");
}

EventSet works well with others: The EventSet can also subscribe boost::function, std::function, functors created by boost::bind and possibly others. This is not a feature of CEGUI per se, just a fortunate side effect of being able to call functors.

Events are automatically created on demand: As of CEGUI 0.5, the EventSet no longer needs to be filled with available events. Events are now added to the set as they are first used; that is, the first time a handler is subscribed to an event for a given EventSet, an Event object is created and added to the EventSet.

Instead of throwing an exception when firing an event that does not actually exist in the set, we now do nothing (if the Event does not exist, then it has no handlers subscribed, and therefore doing nothing is the correct course action).

Constructor & Destructor Documentation

CEGUI::EventSet::EventSet ( const EventSet & )

inlineprotected

Deprecated:

Member Function Documentation

void CEGUI::EventSet::addEvent ( const String & name )

Creates a new Event object with the given name and adds it to the EventSet.

Parameters

name	String object containing the name to give the new Event. The name must be unique for the EventSet.

Exceptions

AlreadyExistsException Thrown if an Event already exists named name.

void CEGUI::EventSet::addEvent ( Event & event )

Adds the given Event object to the EventSet. Ownership of the object passes to EventSet and it will be deleted when it is removed from the EventSet - whether explicitly via removeEvent or when the EventSet is destroyed.

Parameters

event Reference to an Event or Event based object that is to be added to the EventSaet

Exceptions

AlreadyExistsException Thrown if the EventSet already contains an Event with the same name as event. Note that event will be destroyed under this scenario.

virtual void CEGUI::EventSet::fireEvent	(	const String &	name,
		EventArgs &	args,
		const String &	eventNamespace = `""`
	)

virtual

Fires the named event passing the given EventArgs object.

Parameters

name	String object holding the name of the Event that is to be fired (triggered)
args	The EventArgs (or derived) object that is to be bassed to each subscriber of the Event. Once all subscribers have been called the 'handled' field of the event is updated appropriately.
eventNamespace	String object describing the global event namespace prefix for this event.

Reimplemented in CEGUI::GlobalEventSet.

Event* CEGUI::EventSet::getEventObject	(	const String &	name,
		bool	autoAdd = `false`
	)

Return a pointer to the Event object with the given name, optionally adding such an Event object to the EventSet if it does not already exist.

Parameters

name	String object holding the name of the Event to return.
autoAdd	true if an Event object named name should be added to the set if such an Event does not currently exist. false if no object should automatically be added to the set. In this case, if the Event does not already exist 0 will be returned.

Returns: Pointer to the Event object in this EventSet with the specifed name. Or 0 if such an Event does not exist and autoAdd was false.

bool CEGUI::EventSet::isEventPresent ( const String & name )

Checks to see if an Event with the given name is present in this EventSet.

Returns

true if an Event named name is defined for this EventSet.
false if no Event named name is defined for this EventSet.

bool CEGUI::EventSet::isMuted ( void ) const

Return whether the EventSet is muted or not.

Returns

true if the EventSet is muted. All requests to fire events will be ignored.
false if the EventSet is not muted. Requests to fire events are processed as normal.

EventSet& CEGUI::EventSet::operator= ( const EventSet & )

inlineprotected

Deprecated:

void CEGUI::EventSet::removeEvent ( const String & name )

Removes the Event with the given name. All connections to the event are disconnected, and the underlying Event object is destroyed.

Parameters

name	String object containing the name of the Event to remove. If no such Event exists, nothing happens.

void CEGUI::EventSet::removeEvent ( Event & event )

Removes the given event from the EventSet. All connections to the event are disconnected, and the event object is destroyed.

Parameters

event Reference to the Event or Event based object to be removed from the EventSet.

void CEGUI::EventSet::setMutedState ( bool setting )

Set the mute state for this EventSet.

Parameters

setting

true if the EventSet is to be muted (no further event firing requests will be honoured until EventSet is unmuted).
false if the EventSet is not to be muted and all events should fired as requested.

virtual Event::Connection CEGUI::EventSet::subscribeEvent	(	const String &	name,
		Event::Subscriber	subscriber
	)

virtual

Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added.

Parameters

name	String object containing the name of the Event to subscribe to.
subscriber	Function or object that is to be subscribed to the Event.

Returns: Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.

virtual Event::Connection CEGUI::EventSet::subscribeEvent	(	const String &	name,
		Event::Group	group,
		Event::Subscriber	subscriber
	)

virtual

Subscribes a handler to the specified group of the named Event. If the named Event is not yet present in the EventSet, it is created and added.

Parameters

name	String object containing the name of the Event to subscribe to.
group	Group which is to be subscribed to. Subscription groups are called in ascending order.
subscriber	Function or object that is to be subscribed to the Event.

Returns: Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.

template<typename Arg1 , typename Arg2 >

Event::Connection CEGUI::EventSet::subscribeEvent	(	const String &	name,
		Arg1	arg1,
		Arg2	arg2
	)

inline

Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added.

Parameters

name	String object containing the name of the Event to subscribe to.
subscriber	Function or object that is to be subscribed to the Event.

Returns: Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.

template<typename Arg1 , typename Arg2 >

Event::Connection CEGUI::EventSet::subscribeEvent	(	const String &	name,
		Event::Group	group,
		Arg1	arg1,
		Arg2	arg2
	)

inline

Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added.

Parameters

name	String object containing the name of the Event to subscribe to.
subscriber	Function or object that is to be subscribed to the Event.

Returns: Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.

virtual Event::Connection CEGUI::EventSet::subscribeScriptedEvent	(	const String &	name,
		const String &	subscriber_name
	)

virtual

Subscribes the named Event to a scripted funtion.

Parameters

name	String object containing the name of the Event to subscribe to.
subscriber_name	String object containing the name of the script funtion that is to be subscribed to the Event.

Returns: Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.

virtual Event::Connection CEGUI::EventSet::subscribeScriptedEvent	(	const String &	name,
		Event::Group	group,
		const String &	subscriber_name
	)

virtual

Subscribes the specified group of the named Event to a scripted funtion.

Parameters

name	String object containing the name of the Event to subscribe to.
group	Group which is to be subscribed to. Subscription groups are called in ascending order.
subscriber_name	String object containing the name of the script funtion that is to be subscribed to the Event.

Returns: Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation