update event api

wbget · Mar 18, 2016 · 1e3a652 · 1e3a652
1 parent f8dcc9f
commit 1e3a652
Show file tree

Hide file tree

Showing 6 changed files with 127 additions and 108 deletions.
diff --git a/cocos2d/core/CCNode.js b/cocos2d/core/CCNode.js
@@ -42,15 +42,15 @@ var DontDestroy = Flags.DontDestroy;
 var EventType = cc.Enum({
     /**
      * !#en The event type for touch start event, you can use its value directly: 'touchstart'
-     * !#zh 开始触摸事件，可以直接使用它的值：“touchstart”。
+     * !#zh 当手指触摸到屏幕时。
      * @property TOUCH_START
      * @type {String}
      * @static
      */
     TOUCH_START: 'touchstart',
     /**
      * !#en The event type for touch move event, you can use its value directly: 'touchmove'
-     * !#zh 触摸后移动事件，可以直接使用它的值：“touchmove”。
+     * !#zh 当手指在屏幕上目标节点区域内移动时。
      * @property TOUCH_MOVE
      * @type {String}
      * @value 1
@@ -59,15 +59,15 @@ var EventType = cc.Enum({
     TOUCH_MOVE: 'touchmove',
     /**
      * !#en The event type for touch end event, you can use its value directly: 'touchend'
-     * !#zh 结束触摸事件，可以直接使用它的值：“touchend”。
+     * !#zh 当手指在目标节点区域内离开屏幕时。
      * @property TOUCH_END
      * @type {String}
      * @static
      */
     TOUCH_END: 'touchend',
     /**
      * !#en The event type for touch end event, you can use its value directly: 'touchcancel'
-     * !#zh 取消触摸事件，可以直接使用它的值：“touchcancel”。
+     * !#zh 当手指在目标节点区域外离开屏幕时。
      * @property TOUCH_CANCEL
      * @type {String}
      * @static
@@ -76,47 +76,47 @@ var EventType = cc.Enum({
 
     /**
      * !#en The event type for mouse down events, you can use its value directly: 'mousedown'
-     * !#zh 鼠标按下事件，可以直接使用它的值：“mousedown”。
+     * !#zh 当鼠标按下时触发一次。
      * @property MOUSE_DOWN
      * @type {String}
      * @static
      */
     MOUSE_DOWN: 'mousedown',
     /**
      * !#en The event type for mouse move events, you can use its value directly: 'mousemove'
-     * !#zh 鼠标按下后移动事件，可以直接使用它的值：“mousemove”。
+     * !#zh 当鼠标在目标节点在目标节点区域中移动时，不论是否按下。
      * @property MOUSE_MOVE
      * @type {String}
      * @static
      */
     MOUSE_MOVE: 'mousemove',
     /**
      * !#en The event type for mouse enter target events, you can use its value directly: 'mouseenter'
-     * !#zh 鼠标进入事件，可以直接使用它的值：“mouseenter”。
+     * !#zh 当鼠标移入目标节点区域时，不论是否按下。
      * @property MOUSE_ENTER
      * @type {String}
      * @static
      */
     MOUSE_ENTER: 'mouseenter',
     /**
      * !#en The event type for mouse leave target events, you can use its value directly: 'mouseleave'
-     * !#zh 鼠标移除事件，可以直接使用它的值：“mouseleave”。
+     * !#zh 当鼠标移出目标节点区域时，不论是否按下。
      * @property MOUSE_LEAVE
      * @type {String}
      * @static
      */
     MOUSE_LEAVE: 'mouseleave',
     /**
      * !#en The event type for mouse up events, you can use its value directly: 'mouseup'
-     * !#zh 鼠标释放事件，可以直接使用它的值：“mouseup”。
+     * !#zh 当鼠标从按下状态松开时触发一次。
      * @property MOUSE_UP
      * @type {String}
      * @static
      */
     MOUSE_UP: 'mouseup',
     /**
      * !#en The event type for mouse wheel events, you can use its value directly: 'mousewheel'
-     * !#zh 鼠标滚轮事件，可以直接使用它的值：“mousewheel”。
+     * !#zh 当鼠标滚轮滚动时。
      * @property MOUSE_WHEEL
      * @type {String}
      * @static

diff --git a/cocos2d/core/event-manager/CCEventListener.js b/cocos2d/core/event-manager/CCEventListener.js
@@ -31,7 +31,9 @@
  *      EventListenerTouchOneByOne, EventListenerCustom.
  * </p>
  *
- * !#zh 封装用户的事件处理逻辑。
+ * !#zh
+ * 封装用户的事件处理逻辑。
+ * 注意：这是一个抽象类，开发者不应该直接实例化这个类，请参考 cc.EventListener.create。
  *
  * @class EventListener
  * @param {Number} type
@@ -245,58 +247,57 @@ cc.EventListener = cc._Class.extend(/** @lends cc.EventListener# */{
 // event listener type
 /**
  * !#en The type code of unknown event listener.
- * !#zh 未知的事件监听器
+ * !#zh 未知的事件监听器类型。
  * @property EventListener.UNKNOWN
  * @constant
  * @type {Number}
  */
 cc.EventListener.UNKNOWN = 0;
 /*
  * !#en The type code of one by one touch event listener.
- * !#zh 单点触摸事件监听器
- *
+ * !#zh 触摸事件监听器类型，触点会一个一个得分开被派发。
  * @constant
  * @type {Number}
  */
 cc.EventListener.TOUCH_ONE_BY_ONE = 1;
 /*
  * !#en The type code of all at once touch event listener.
- * !#zh 多点触摸事件监听器
+ * !#zh 触摸事件监听器类型，触点会被一次性全部派发。
  * @constant
  * @type {Number}
  */
 cc.EventListener.TOUCH_ALL_AT_ONCE = 2;
 /**
  * !#en The type code of keyboard event listener.
- * !#zh 键盘事件监听器
+ * !#zh 键盘事件监听器类型。
  * @constant EventListener.KEYBOARD
  * @type {Number}
  */
 cc.EventListener.KEYBOARD = 3;
 /*
  * !#en The type code of mouse event listener.
- * !#zh 鼠标事件监听器
+ * !#zh 鼠标事件监听器类型。
  * @constant
  * @type {Number}
  */
 cc.EventListener.MOUSE = 4;
 /**
  * !#en The type code of focus event listener.
- * !#zh 加速器事件监听器
+ * !#zh 加速器事件监听器类型。
  * @constant EventListener.ACCELERATION
  * @type {Number}
  */
 cc.EventListener.ACCELERATION = 6;
 /*
  * !#en The type code of Focus change event listener.
- * !#zh 焦点事件监听器
+ * !#zh 焦点事件监听器类型。
  * @constant
  * @type {Number}
  */
 cc.EventListener.FOCUS = 7;
 /*
  * !#en The type code of custom event listener.
- * !#zh 自定义事件监听器
+ * !#zh 自定义事件监听器类型。
  * @constant
  * @type {Number}
  */
@@ -448,13 +449,16 @@ cc._EventListenerTouchAllAtOnce = cc.EventListener.extend({
 cc._EventListenerTouchAllAtOnce.LISTENER_ID = "__cc_touch_all_at_once";
 
 /**
- * !#en Create a EventListener object by json object
- * !#zh 通过 JSON 对象创建事件监听对象。
+ * !#en
+ * Create a EventListener object with configuration including the event type, handlers and other parameters.
+ * In handlers, this refer to the event listener object itself.
+ * You can also pass custom parameters in the configuration object,
+ * all custom parameters will be polyfilled into the event listener object and can be accessed in handlers.
+ * !#zh 通过指定不同的 Event 对象来设置想要创建的事件监听器。
  * @method create
  * @static
  * @param {Object} argObj a json object
  * @returns {EventListener}
- * todo: It should be the direct use new
  * @example {@link utils/api/engine/docs/cocos2d/core/event-manager/CCEventListener/create.js}
  */
 cc.EventListener.create = function(argObj){

diff --git a/cocos2d/core/event-manager/CCEventManager.js b/cocos2d/core/event-manager/CCEventManager.js
@@ -96,7 +96,11 @@ var __getListenerID = function (event) {
  *  The EventListener list is managed in such way so that event listeners can be added and removed          <br/>
  *  while events are being dispatched.
  * </p>
- * !#zh 管理用户注册的事件监听器，根据触发的事件类型分发给相应的事件监听器。
+ * !#zh
+ * 事件管理器，它主要管理事件监听器注册和派发系统事件。
+ * 原始设计中，它支持鼠标，触摸，键盘，陀螺仪和自定义事件。
+ * 在 Creator 的设计中，鼠标，触摸和自定义事件的监听和派发请参考 http://cocos.com/docs/creator/scripting/events.html。
+ *
  * @class eventManager
  * @example {@link utils/api/engine/docs/cocos2d/core/event-manager/CCEventManager/addListener.js}
  */
@@ -651,9 +655,10 @@ cc.eventManager = {
      * if the parameter "nodeOrPriority" is a Number,
      * it means to add a event listener for a specified event with the fixed priority.<br/>
      * </p>
-     * !#zh 向事件管理器添加一个监听器
-     * 如果参数 “nodeOrPriority” 是节点，优先级则由 node 决定。
-     * 如果参数 “nodeOrPriority” 是数字，优先级则固定为该参数的数值。
+     * !#zh
+     * 将事件监听器添加到事件管理器中。<br/>
+     * 如果参数 “nodeOrPriority” 是节点，优先级由 node 的渲染顺序决定，显示在上层的节点将优先收到事件。<br/>
+     * 如果参数 “nodeOrPriority” 是数字，优先级则固定为该参数的数值，数字越小，优先级越高。<br/>
      *
      * @method addListener
      * @param {EventListener|Object} listener - The listener of a specified event or a object of some event parameters.
@@ -700,7 +705,7 @@ cc.eventManager = {
         return listener;
     },
 
-    /**
+    /*
      * !#en Adds a Custom event listener. It will use a fixed priority of 1.
      * !#zh 向事件管理器添加一个自定义事件监听器。
      * @method addCustomListener
@@ -716,9 +721,10 @@ cc.eventManager = {
 
     /**
      * !#en Remove a listener.
-     * !#zh 移除一个事件监听器。
+     * !#zh 移除一个已添加的监听器。
      * @method removeListener
      * @param {EventListener} listener - an event listener or a registered node target
+     * @example {@link utils/api/engine/docs/cocos2d/core/event-manager/CCEventManager/removeListener.js}
      */
     removeListener: function (listener) {
         if (listener == null)
@@ -805,7 +811,18 @@ cc.eventManager = {
 
     /**
      * !#en Removes all listeners with the same event listener type or removes all listeners of a node.
-     * !#zh 移除某一类型或某一 node 对象相关的所有监听器。
+     * !#zh
+     * 移除注册到 eventManager 中指定类型的所有事件监听器。<br/>
+     * 1. 如果传入的第一个参数类型是 Node，那么事件管理器将移除与该对象相关的所有事件监听器。
+     * （如果第二参数 recursive 是 true 的话，就会连同该对象的子控件上所有的事件监听器也一并移除）<br/>
+     * 2. 如果传入的第一个参数类型是 Number（该类型 EventListener 中定义的事件类型），
+     * 那么事件管理器将移除该类型的所有事件监听器。<br/>
+     *
+     * 下列是目前存在监听器类型：       <br/>
+     * cc.EventListener.UNKNOWN       <br/>
+     * cc.EventListener.KEYBOARD      <br/>
+     * cc.EventListener.ACCELERATION，<br/>
+     *
      * @method removeListeners
      * @param {Number|Node} listenerType - listenerType or a node
      * @param {Boolean} recursive
@@ -862,7 +879,7 @@ cc.eventManager = {
         }
     },
 
-    /**
+    /*
      * !#en Removes all custom listeners with the same event name.
      * !#zh 移除同一事件名的自定义事件监听器。
      * @method removeCustomListeners
@@ -917,7 +934,7 @@ cc.eventManager = {
 
     /**
      * !#en Whether to enable dispatching events
-     * !#zh 是否允许分发事件。
+     * !#zh 启用或禁用事件管理器，禁用后不会分发任何事件。
      * @method setEnabled
      * @param {Boolean} enabled
      */
@@ -927,15 +944,15 @@ cc.eventManager = {
 
     /**
      * !#en Checks whether dispatching events is enabled
-     * !#zh 检测事件管理器是否分发事件。
+     * !#zh 检测事件管理器是否启用。
      * @method isEnabled
      * @returns {Boolean}
      */
     isEnabled: function () {
         return this._isEnabled;
     },
 
-    /**
+    /*
      * !#en Dispatches the event, also removes all EventListeners marked for deletion from the event dispatcher list.
      * !#zh 分发事件。
      * @method dispatchEvent
@@ -971,7 +988,7 @@ cc.eventManager = {
         return event.isStopped();
     },
 
-    /**
+    /*
      * !#en Dispatches a Custom Event with a event name an optional user data
      * !#zh 分发自定义事件。
      * @method dispatchCustomEvent