From 16b13ce522a3f93504741803dc3c2df4cc5acec9 Mon Sep 17 00:00:00 2001 From: James Chen Date: Mon, 16 Sep 2013 14:43:57 +0800 Subject: [PATCH] issue #2087: [dispatcher] Updating some comments for new event dispatcher. --- cocos2dx/event_dispatcher/CCEvent.h | 25 ++++++++++-- .../event_dispatcher/CCEventDispatcher.cpp | 11 +++--- cocos2dx/event_dispatcher/CCEventDispatcher.h | 7 +++- cocos2dx/event_dispatcher/CCEventListener.h | 39 +++++++++++++++++-- 4 files changed, 70 insertions(+), 12 deletions(-) diff --git a/cocos2dx/event_dispatcher/CCEvent.h b/cocos2dx/event_dispatcher/CCEvent.h index 7482972821..151f288fb6 100644 --- a/cocos2dx/event_dispatcher/CCEvent.h +++ b/cocos2dx/event_dispatcher/CCEvent.h @@ -35,22 +35,41 @@ NS_CC_BEGIN class Node; +/** + * Base class of all kinds of events. + */ class Event { public: + /** Constructor */ Event(const std::string& type); + + /** Destructor */ virtual ~Event(); + /** Gets the event type */ const std::string& getType() const { return _type; }; + + /** Stops propagation for current event */ void stopPropagation() { _isStopped = true; }; + + /** Checks whether the event has been stopped */ bool isStopped() const { return _isStopped; }; + + /** @brief Gets current target of the event + * @return The target with which the event associates. + * @note It onlys be available when the event listener is associated with node. + * It returns 0 when the listener is associated with fixed priority. + */ Node* getCurrentTarget(); protected: + /** Sets current target */ void setCurrentTarget(Node* target); - std::string _type; - bool _isStopped; - Node* _currentTarget; + + std::string _type; /// Event type + bool _isStopped; /// whether the event has been stopped. + Node* _currentTarget; /// Current target friend class EventDispatcher; }; diff --git a/cocos2dx/event_dispatcher/CCEventDispatcher.cpp b/cocos2dx/event_dispatcher/CCEventDispatcher.cpp index 0954c0dbcd..9a4d8133da 100644 --- a/cocos2dx/event_dispatcher/CCEventDispatcher.cpp +++ b/cocos2dx/event_dispatcher/CCEventDispatcher.cpp @@ -104,7 +104,7 @@ void EventDispatcher::addEventListenerWithSceneGraphPriority(EventListener* list if (!listener->checkAvaiable()) return; - EventListenerItem* item = new EventListenerItem(); + auto item = new EventListenerItem(); item->node = node; item->fixedPriority = 0; item->listener = listener; @@ -124,7 +124,7 @@ void EventDispatcher::addEventListenerWithFixedPriority(EventListener* listener, if (!listener->checkAvaiable()) return; - EventListenerItem* item = new EventListenerItem(); + auto item = new EventListenerItem(); item->node = nullptr; item->fixedPriority = fixedPriority; item->listener = listener; @@ -244,11 +244,12 @@ void EventDispatcher::dispatchEvent(Event* event, bool toSortListeners) if (iter != _listeners->end()) { auto listenerList = iter->second; - for (auto listenerIter = listenerList->begin(); listenerIter != listenerList->end(); ++listenerIter) + for (auto& item : *listenerList) { - CCASSERT(*listenerIter, "listener is invalid."); + CCASSERT(item, "listener item is invalid."); - (*listenerIter)->listener->onEvent(event); + event->setCurrentTarget(item->node); + item->listener->onEvent(event); if (event->isStopped()) break; diff --git a/cocos2dx/event_dispatcher/CCEventDispatcher.h b/cocos2dx/event_dispatcher/CCEventDispatcher.h index 64d8f8c499..523211587d 100644 --- a/cocos2dx/event_dispatcher/CCEventDispatcher.h +++ b/cocos2dx/event_dispatcher/CCEventDispatcher.h @@ -58,16 +58,21 @@ public: /** Adds a event listener for a specified event with the priority of scene graph. * @param listener The listener of a specified event. * @param node The priority of the listener is based on the draw order of this node. + * @note The priority of scene graph will be fixed value 0. So the order of listener item + * in the vector will be ' <0, =0, scene graph, >0'. */ void addEventListenerWithSceneGraphPriority(EventListener* listener, Node* node); /** Adds a event listener for a specified event with the fixed priority. * @param listener The listener of a specified event. * @param fixedPriority The fixed priority of the listener. + * @note A lower priority will be called before the ones that have a higher value. */ void addEventListenerWithFixedPriority(EventListener* listener, int fixedPriority); - /** Remove a listener */ + /** Remove a listener + * @param listener The specified event listener which needs to be removed. + */ void removeEventListener(EventListener* listener); /** Removes all listeners with the same event type */ diff --git a/cocos2dx/event_dispatcher/CCEventListener.h b/cocos2dx/event_dispatcher/CCEventListener.h index 8971276d0f..b8bca5e336 100644 --- a/cocos2dx/event_dispatcher/CCEventListener.h +++ b/cocos2dx/event_dispatcher/CCEventListener.h @@ -36,22 +36,55 @@ NS_CC_BEGIN class Event; +/** + * The base class of event listener. + * If you need custom listener which with different callback, you need to inherit this class. + * For instance, you could refer to AccelerationEventListener, KeyboardEventListener or TouchEventListener. + * Usage: + * auto dispatcher = EventDispatcher::getInstance(); + * Adds a listener: + * + * auto callback = [](Event* event){ do_some_thing(); }; + * auto listener = EventListener::create("your_event_type", callback); + * dispatcher->addEventListenerWithSceneGraphPriority(listener, one_node); + * + * Dispatchs a custom event: + * + * Event event("your_event_type"); + * dispatcher->dispatchEvent(&event); + * + * Removes a listener + * + * dispatcher->removeListener(listener); + */ class EventListener : public Object { public: + /** Creates an event listener with type and callback. + * @param eventType The type of the event. + * @param callback The callback function when the specified event was emitted. + */ static EventListener* create(const std::string& eventType, std::function callback); protected: + /** Constructor */ EventListener(); + + /** Initializes event with type and callback function */ bool init(const std::string& t, std::functioncallback); public: + /** Destructor */ virtual ~EventListener(); + + /** Checks whether the listener is available. */ virtual bool checkAvaiable(); + + /** Clones the listener, its subclasses have to override this method. */ virtual EventListener* clone(); protected: - std::function onEvent; - std::string type; - bool _isRegistered; + std::function onEvent; /// Event callback function + std::string type; /// Event type + bool _isRegistered; /// Whether the listener has been added to dispatcher. friend class EventDispatcher; };