/************************************************************************
filename: CEGUIEvent.h
created: Tue Feb 28 2006
author: Paul D Turner <paul@cegui.org.uk>
*************************************************************************/
/***************************************************************************
* Copyright (C) 2004 - 2006 Paul D Turner & The CEGUI Development Team
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files (the
* "Software"), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,
* distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so, subject to
* the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
* OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
***************************************************************************/
#ifndef _CEGUIEvent_h_
#define _CEGUIEvent_h_
#include "CEGUIString.h"
#include "CEGUIBoundSlot.h"
#include "CEGUISubscriberSlot.h"
#include "CEGUIRefCounted.h"
#include <map>
#if defined(_MSC_VER)
# pragma warning(push)
# pragma warning(disable : 4251)
#endif
// Start of CEGUI namespace section
namespace CEGUI
{
/*!
\brief
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:
\par
<em>bool function_name(const EventArgs& args);</em>
\note
An Event object may not be copied.
*/
class /*CEGUIEXPORT*/ Event
{
public:
/*!
\brief
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 RefCounted<BoundSlot> Connection;
/*!
\brief
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 CEGUI::SubscriberSlot Subscriber;
/*!
\brief
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.
*/
typedef unsigned int Group;
/*!
\brief
Event::Connection wrapper that automatically disconnects the connection
when the object is deleted (or goes out of scope).
*/
class ScopedConnection : public Connection
{
public:
ScopedConnection() {}
~ScopedConnection()
{ disconnect(); }
ScopedConnection(const Event::Connection& connection) :
d_connection(connection)
{}
ScopedConnection& operator=(const Event::Connection& connection)
{
d_connection = connection;
return *this;
}
bool connected() const
{ return d_connection.isValid() ? d_connection->connected() : false; }
void disconnect()
{ if (d_connection.isValid()) d_connection->disconnect(); }
private:
Event::Connection d_connection;
};
/*!
\brief
Constructs a new Event object with the specified name
*/
Event(const String& name);
/*!
\brief
Destructor for Event objects. Note that this is non-virtual and so you
should not sub-class Event.
*/
~Event();
/*!
\brief
Return the name given to this Event object when it was created.
\return
String object containing the name of the Event object.
*/
const String& getName(void) const
{ return d_name; }
/*!
\brief
Subscribes some function or object to the Event
\param subscriber
A 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.
\return
A Connection object which can be used to disconnect (unsubscribe) from
the Event, and also to check the connection state.
*/
Connection subscribe(const Subscriber& slot);
/*!
\brief
Subscribes some function or object to the Event
\param group
The 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.
\param subscriber
A 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.
\return
A Connection object which can be used to disconnect (unsubscribe) from
the Event, and also to check the connection state.
*/
Connection subscribe(Group group, const Subscriber& slot);
/*!
\brief
Fires the event. All event subscribers get called in the appropriate
sequence.
\param args
An 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.
\return
Nothing.
*/
void operator()(EventArgs& args);
private:
friend void CEGUI::BoundSlot::disconnect();
/*!
\brief
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.
*/
void unsubscribe(const BoundSlot& slot);
// Copy constructor and assignment are not allowed for events
Event(const Event&) {}
Event& operator=(const Event&) {return *this;}
typedef std::multimap<Group, Connection> SlotContainer;
SlotContainer d_slots; //!< Collection holding ref-counted bound slots
const String d_name; //!< Name of this event
};
} // End of CEGUI namespace section
#if defined(_MSC_VER)
# pragma warning(pop)
#endif
#endif // end of guard _CEGUIEvent_h_
subscribe函数是给 这个事件注册一个处理函数，operator（）当这个时间被激发后会被调用，这个函数是便利所有的处理类，并且调用该类的处理函数。unsubscribe函数取消一个处理类和这个事件的关联，BoundSlot的disconnect函数会调用她
Event::Connection Event::subscribe(Event::Group group, const Event::Subscriber& slot)
{
Event::Connection c(new BoundSlot(group, slot, *this));
d_slots.insert(std::pair<Group, Connection>(group, c));
return c;
}
void Event::operator()(EventArgs& args)
{
SlotContainer::iterator iter(d_slots.begin());
const SlotContainer::const_iterator end_iter(d_slots.end());
// execute all subscribers, updating the 'handled' state as we go
for (; iter != end_iter; ++iter)
if ((*iter->second->d_subscriber)(args))
++args.handled;
}
void Event::unsubscribe(const BoundSlot& slot)
{
// try to find the slot in our collection
SlotContainer::iterator curr =
std::find_if(d_slots.begin(),
d_slots.end(),
SubComp(slot));
// erase our reference to the slot, if we had one.
if (curr != d_slots.end())
d_slots.erase(curr);
}