issue #2087: [dispatcher] Updating some comments for new event dispatcher.

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;
 };

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;

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 */

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<void(Event*)> callback);
     
 protected:
+    /** Constructor */
     EventListener();
+    
+    /** Initializes event with type and callback function */
     bool init(const std::string& t, std::function<void(Event*)>callback);
 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<void(Event*)> onEvent;
-    std::string type;
-    bool _isRegistered;
+    std::function<void(Event*)> onEvent;   /// Event callback function
+    std::string type;                      /// Event type
+    bool _isRegistered;                    /// Whether the listener has been added to dispatcher.
     
     friend class EventDispatcher;
 };