diff --git a/cocos/base/CCEvent.h b/cocos/base/CCEvent.h index 08f1cbd01f..ccd49010c2 100644 --- a/cocos/base/CCEvent.h +++ b/cocos/base/CCEvent.h @@ -33,12 +33,13 @@ NS_CC_BEGIN class Node; -/** - * Base class of all kinds of events. +/** @class Event + * @brief Base class of all kinds of events. */ class CC_DLL Event : public Ref { public: + /** Type Event type.*/ enum class Type { TOUCH, @@ -54,21 +55,29 @@ CC_CONSTRUCTOR_ACCESS: /** Constructor */ Event(Type type); public: - /** Destructor */ + /** Destructor. + */ virtual ~Event(); - /** Gets the event type */ + /** Gets the event type. + * + * @return The event type. + */ inline Type getType() const { return _type; }; - /** Stops propagation for current event */ + /** Stops propagation for current event. + */ inline void stopPropagation() { _isStopped = true; }; - /** Checks whether the event has been stopped */ + /** Checks whether the event has been stopped. + * + * @return True if the event has been stopped. + */ inline 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. + /** 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. */ inline Node* getCurrentTarget() { return _currentTarget; }; diff --git a/cocos/base/CCEventAcceleration.h b/cocos/base/CCEventAcceleration.h index 8aa7ecd589..1b6013f572 100644 --- a/cocos/base/CCEventAcceleration.h +++ b/cocos/base/CCEventAcceleration.h @@ -30,9 +30,16 @@ NS_CC_BEGIN +/** @class EventAcceleration + * @brief Accelerometer event. + */ class CC_DLL EventAcceleration : public Event { public: + /** Constructor. + * + * @param acc A given Acceleration. + */ EventAcceleration(const Acceleration& acc); private: diff --git a/cocos/base/CCEventCustom.h b/cocos/base/CCEventCustom.h index 8699d8cf62..94602b7c43 100644 --- a/cocos/base/CCEventCustom.h +++ b/cocos/base/CCEventCustom.h @@ -30,19 +30,34 @@ NS_CC_BEGIN +/** @class EventCustom + * @brief Custom event. + */ class CC_DLL EventCustom : public Event { public: - /** Constructor */ + /** Constructor. + * + * @param eventName A given name of the custom event. + */ EventCustom(const std::string& eventName); - /** Sets user data */ + /** Sets user data. + * + * @param data The user data pointer, it's a void*. + */ inline void setUserData(void* data) { _userData = data; }; - /** Gets user data */ + /** Gets user data. + * + * @return The user data pointer, it's a void*. + */ inline void* getUserData() const { return _userData; }; - /** Gets event name */ + /** Gets event name. + * + * @return The name of the event. + */ inline const std::string& getEventName() const { return _eventName; }; protected: void* _userData; ///< User data diff --git a/cocos/base/CCEventDispatcher.h b/cocos/base/CCEventDispatcher.h index 1f3349e101..0016c6f910 100644 --- a/cocos/base/CCEventDispatcher.h +++ b/cocos/base/CCEventDispatcher.h @@ -44,8 +44,8 @@ class Node; class EventCustom; class EventListenerCustom; -/** -This class manages event listener subscriptions +/** @class EventDispatcher +* @brief This class manages event listener subscriptions and event dispatching. The EventListener list is managed in such a way that @@ -56,7 +56,7 @@ dispatched. class CC_DLL EventDispatcher : public Ref { public: - // Adds event listener + // Adds event listener. /** Adds a event listener for a specified event with the priority of scene graph. * @param listener The listener of a specified event. @@ -76,7 +76,9 @@ public: /** Adds a Custom event listener. It will use a fixed priority of 1. - @return the generated event. Needed in order to remove the event from the dispather + * @param eventName A given name of the event. + * @param callback A given callback method that associated the event name. + * @return the generated event. Needed in order to remove the event from the dispather */ EventListenerCustom* addCustomEventListener(const std::string &eventName, const std::function& callback); @@ -84,60 +86,98 @@ public: // Removes event listener - /** 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 listener type */ + /** Removes all listeners with the same event listener type. + * + * @param listenerType A given event listener type which needs to be removed. + */ void removeEventListenersForType(EventListener::Type listenerType); - /** Removes all listeners which are associated with the specified target. */ + /** Removes all listeners which are associated with the specified target. + * + * @param target A given target node. + * @param recursive True if remove recursively, the default value is false. + */ void removeEventListenersForTarget(Node* target, bool recursive = false); - /** Removes all custom listeners with the same event name */ + /** Removes all custom listeners with the same event name. + * + * @param customEventName A given event listener name which needs to be removed. + */ void removeCustomEventListeners(const std::string& customEventName); - /** Removes all listeners */ + /** Removes all listeners. + */ void removeAllEventListeners(); ///////////////////////////////////////////// // Pauses / Resumes event listener - /** Pauses all listeners which are associated the specified target. */ + /** Pauses all listeners which are associated the specified target. + * + * @param target A given target node. + * @param recursive True if pause recursively, the default value is false. + */ void pauseEventListenersForTarget(Node* target, bool recursive = false); - /** Resumes all listeners which are associated the specified target. */ + /** Resumes all listeners which are associated the specified target. + * + * @param target A given target node. + * @param recursive True if resume recursively, the default value is false. + */ void resumeEventListenersForTarget(Node* target, bool recursive = false); ///////////////////////////////////////////// - /** Sets listener's priority with fixed value. */ + /** Sets listener's priority with fixed value. + * + * @param listener A given listener. + * @param fixedPriority The fixed priority value. + */ void setPriority(EventListener* listener, int fixedPriority); - /** Whether to enable dispatching events */ + /** Whether to enable dispatching events. + * + * @param isEnabled True if enable dispatching events. + */ void setEnabled(bool isEnabled); - /** Checks whether dispatching events is enabled */ + /** Checks whether dispatching events is enabled. + * + * @return True if dispatching events is enabled. + */ bool isEnabled() const; ///////////////////////////////////////////// - /** Dispatches the event + /** Dispatches the event. * Also removes all EventListeners marked for deletion from the * event dispatcher list. + * + * @param event The event needs to be dispatched. */ void dispatchEvent(Event* event); - /** Dispatches a Custom Event with a event name an optional user data */ + /** Dispatches a Custom Event with a event name an optional user data. + * + * @param eventName The name of the event which needs to be dispatched. + * @param optionalUserData The optional user data, it's a void*, the default value is nullptr. + */ void dispatchCustomEvent(const std::string &eventName, void *optionalUserData = nullptr); ///////////////////////////////////////////// - /** Constructor of EventDispatcher */ + /** Constructor of EventDispatcher. + */ EventDispatcher(); - /** Destructor of EventDispatcher */ + /** Destructor of EventDispatcher. + */ ~EventDispatcher(); #if CC_NODE_DEBUG_VERIFY_EVENT_LISTENERS && COCOS2D_DEBUG > 0 diff --git a/cocos/base/CCEventFocus.h b/cocos/base/CCEventFocus.h index 100b207cbd..e63ee3669c 100644 --- a/cocos/base/CCEventFocus.h +++ b/cocos/base/CCEventFocus.h @@ -35,9 +35,17 @@ namespace ui { class Widget; } +/** @class EventFocus + * @brief Focus event. + */ class CC_DLL EventFocus : public Event { public: + /** Constructor. + * + * @param widgetLoseFocus The widget which lose focus. + * @param widgetGetFocus The widget which get focus. + */ EventFocus(ui::Widget* widgetLoseFocus, ui::Widget* widgetGetFocus); private: diff --git a/cocos/base/CCEventKeyboard.h b/cocos/base/CCEventKeyboard.h index d06594d6d9..78999f0fe5 100644 --- a/cocos/base/CCEventKeyboard.h +++ b/cocos/base/CCEventKeyboard.h @@ -30,11 +30,14 @@ NS_CC_BEGIN +/** @class EventKeyboard + * @brief Keyboard event. + */ class CC_DLL EventKeyboard : public Event { public: /** - * The key (code). + * KeyCode The key (code). */ enum class KeyCode { @@ -210,6 +213,11 @@ public: KEY_PLAY }; + /** Constructor. + * + * @param keyCode A given keycode. + * @param isPressed True if the key is pressed. + */ EventKeyboard(KeyCode keyCode, bool isPressed); private: diff --git a/cocos/base/CCEventListener.h b/cocos/base/CCEventListener.h index aecfd92a8d..aa0f276f48 100644 --- a/cocos/base/CCEventListener.h +++ b/cocos/base/CCEventListener.h @@ -37,14 +37,15 @@ NS_CC_BEGIN class Event; class Node; -/** - * The base class of event listener. +/** @class EventListener + * @brief 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 EventListenerAcceleration, EventListenerKeyboard, EventListenerTouchOneByOne, EventListenerCustom. */ class CC_DLL EventListener : public Ref { public: + /** Type Event type.*/ enum class Type { UNKNOWN, @@ -67,24 +68,34 @@ CC_CONSTRUCTOR_ACCESS: /** Initializes event with type and callback function */ bool init(Type t, const ListenerID& listenerID, const std::function& callback); public: - /** Destructor */ + /** Destructor. + */ virtual ~EventListener(); - /** Checks whether the listener is available. */ + /** Checks whether the listener is available. + * + * @return True if the listener is available. + */ virtual bool checkAvailable() = 0; - /** Clones the listener, its subclasses have to override this method. */ + /** Clones the listener, its subclasses have to override this method. + */ virtual EventListener* clone() = 0; - /** Enables or disables the listener - * @note Only listeners with `enabled` state will be able to receive events. + /** Enables or disables the listener. + * @note Only listeners with `enabled` state will be able to receive events. * When an listener was initialized, it's enabled by default. * An event listener can receive events when it is enabled and is not paused. * paused state is always false when it is a fixed priority listener. + * + * @param enabled True if enables the listener. */ inline void setEnabled(bool enabled) { _isEnabled = enabled; }; - /** Checks whether the listener is enabled */ + /** Checks whether the listener is enabled. + * + * @return True if the listenrt is enabled. + */ inline bool isEnabled() const { return _isEnabled; }; protected: diff --git a/cocos/base/CCEventListenerAcceleration.h b/cocos/base/CCEventListenerAcceleration.h index ea339770ca..c9f226d8cb 100644 --- a/cocos/base/CCEventListenerAcceleration.h +++ b/cocos/base/CCEventListenerAcceleration.h @@ -30,12 +30,23 @@ NS_CC_BEGIN +/** @class EventListenerAcceleration + * @brief Acceleration event listener. + */ class CC_DLL EventListenerAcceleration : public EventListener { public: static const std::string LISTENER_ID; + /** Create a acceleration EventListener. + * + * @param callback The acceleration callback method. + * @return An autoreleased EventListenerAcceleration object. + */ static EventListenerAcceleration* create(const std::function& callback); + + /** Destructor. + */ virtual ~EventListenerAcceleration(); /// Overrides diff --git a/cocos/base/CCEventListenerController.h b/cocos/base/CCEventListenerController.h index cdcefd023a..c6e1032489 100644 --- a/cocos/base/CCEventListenerController.h +++ b/cocos/base/CCEventListenerController.h @@ -34,11 +34,18 @@ NS_CC_BEGIN class Event; class Controller; +/** @class EventListenerController + * @param Controller event listener. + */ class EventListenerController : public EventListener { public: static const std::string LISTENER_ID; + /** Create a controller event listener. + * + * @return An autoreleased EventListenerController object. + */ static EventListenerController* create(); /// Overrides diff --git a/cocos/base/CCEventListenerCustom.h b/cocos/base/CCEventListenerCustom.h index c602d626b5..6cdb17df4c 100644 --- a/cocos/base/CCEventListenerCustom.h +++ b/cocos/base/CCEventListenerCustom.h @@ -31,8 +31,9 @@ NS_CC_BEGIN class EventCustom; -/** - * Usage: +/** @class EventListenerCustom + * @brief Custom event listener. + * @code Usage: * auto dispatcher = Director::getInstance()->getEventDispatcher(); * Adds a listener: * @@ -53,8 +54,9 @@ class CC_DLL EventListenerCustom : public EventListener { 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. + * @param eventType The type of the event. + * @param callback The callback function when the specified event was emitted. + * @return An autoreleased EventListenerCustom object. */ static EventListenerCustom* create(const std::string& eventName, const std::function& callback); diff --git a/cocos/base/CCEventListenerFocus.h b/cocos/base/CCEventListenerFocus.h index 00c78bb22d..e2486c1db9 100644 --- a/cocos/base/CCEventListenerFocus.h +++ b/cocos/base/CCEventListenerFocus.h @@ -35,12 +35,22 @@ namespace ui { class Widget; } +/** @class EventListenerFocus + * @brief Focus event listener. + */ class CC_DLL EventListenerFocus : public EventListener { public: static const std::string LISTENER_ID; + + /** Create a focus event listener. + * + * @return An autoreleased EventListenerFocus object. + */ static EventListenerFocus* create(); + /** Destructor. + */ virtual ~EventListenerFocus(); /// Overrides diff --git a/cocos/base/CCEventListenerKeyboard.h b/cocos/base/CCEventListenerKeyboard.h index 283a0ed41e..7a63529f88 100644 --- a/cocos/base/CCEventListenerKeyboard.h +++ b/cocos/base/CCEventListenerKeyboard.h @@ -33,11 +33,18 @@ NS_CC_BEGIN class Event; +/** @class EventListenerKeyboard + * @brief Keyboard event listener. + */ class CC_DLL EventListenerKeyboard : public EventListener { public: static const std::string LISTENER_ID; + /** Create a keyboard event listener. + * + * @return An autoreleased EventListenerKeyboard object. + */ static EventListenerKeyboard* create(); /// Overrides diff --git a/cocos/base/CCEventListenerMouse.h b/cocos/base/CCEventListenerMouse.h index c5141444b7..b1e0a83c67 100644 --- a/cocos/base/CCEventListenerMouse.h +++ b/cocos/base/CCEventListenerMouse.h @@ -33,11 +33,18 @@ NS_CC_BEGIN class Event; +/** @class EventListenerMouse + * @brief Mouse event listener. + */ class CC_DLL EventListenerMouse : public EventListener { public: static const std::string LISTENER_ID; + /** Create a mouse event listener. + * + * @return An autoreleased EventListenerMouse object. + */ static EventListenerMouse* create(); /// Overrides diff --git a/cocos/base/CCEventListenerTouch.h b/cocos/base/CCEventListenerTouch.h index 603160b1e9..33b662609d 100644 --- a/cocos/base/CCEventListenerTouch.h +++ b/cocos/base/CCEventListenerTouch.h @@ -34,16 +34,30 @@ NS_CC_BEGIN class Touch; +/** @class EventListenerTouchOneByOne + * @brief Single touch event listener. + */ class CC_DLL EventListenerTouchOneByOne : public EventListener { public: static const std::string LISTENER_ID; + /** Create a one by one touch event listener. + */ static EventListenerTouchOneByOne* create(); + /** Destructor. */ virtual ~EventListenerTouchOneByOne(); + /** Whether or not to swall touches. + * + * @param needSwallow True if needs to swall touches. + */ void setSwallowTouches(bool needSwallow); + /** Is swall touches or not. + * + * @return True if needs to swall touches. + */ bool isSwallowTouches(); /// Overrides @@ -72,13 +86,21 @@ private: friend class EventDispatcher; }; - +/** @class EventListenerTouchAllAtOnce + * @brief Multiple touches event listener. + */ class CC_DLL EventListenerTouchAllAtOnce : public EventListener { public: static const std::string LISTENER_ID; + /** Create a all at once event listener. + * + * @return An autoreleased EventListenerTouchAllAtOnce object. + */ static EventListenerTouchAllAtOnce* create(); + /** Destructor. + */ virtual ~EventListenerTouchAllAtOnce(); /// Overrides diff --git a/cocos/base/CCEventMouse.h b/cocos/base/CCEventMouse.h index 1c5af7eb22..a1f4fc39a3 100644 --- a/cocos/base/CCEventMouse.h +++ b/cocos/base/CCEventMouse.h @@ -40,11 +40,14 @@ NS_CC_BEGIN +/** @class EventMouse + * @brief The mouse event. + */ class CC_DLL EventMouse : public Event { public: /** - * Different types of MouseEvent + * MouseEventType Different types of MouseEvent. */ enum class MouseEventType { @@ -55,13 +58,34 @@ public: MOUSE_SCROLL, }; + /** Constructor. + * + * @param mouseEventCode A given mouse event type. + */ EventMouse(MouseEventType mouseEventCode); - /** Set mouse scroll data */ + /** Set mouse scroll data. + * + * @param scrollX The scroll data of x axis. + * @param scrollY The scroll data of y axis. + */ inline void setScrollData(float scrollX, float scrollY) { _scrollX = scrollX; _scrollY = scrollY; }; + /** Get mouse scroll data of x axis. + * + * @return The scroll data of x axis. + */ inline float getScrollX() { return _scrollX; }; + /** Get mouse scroll data of y axis. + * + * @return The scroll data of y axis. + */ inline float getScrollY() { return _scrollY; }; + /** Set the cursor position. + * + * @param x The x coordinate of cursor position. + * @param y The y coordinate of cursor position. + */ inline void setCursorPosition(float x, float y) { _x = x; _y = y; @@ -75,24 +99,61 @@ public: } } + /** Set mouse button. + * + * @param button a given mouse button. + */ inline void setMouseButton(int button) { _mouseButton = button; }; + /** Get mouse button. + * + * @return The mouse button. + */ inline int getMouseButton() { return _mouseButton; }; + /** Get the cursor position of x axis. + * + * @return The x coordinate of cursor position. + */ inline float getCursorX() { return _x; }; + /** Get the cursor position of y axis. + * + * @return The y coordinate of cursor position. + */ inline float getCursorY() { return _y; }; - /** returns the current touch location in OpenGL coordinates */ + /** Returns the current touch location in OpenGL coordinates. + * + * @return The current touch location in OpenGL coordinates. + */ Vec2 getLocation() const; - /** returns the previous touch location in OpenGL coordinates */ + /** Returns the previous touch location in OpenGL coordinates. + * + * @return The previous touch location in OpenGL coordinates. + */ Vec2 getPreviousLocation() const; - /** returns the start touch location in OpenGL coordinates */ + /** Returns the start touch location in OpenGL coordinates. + * + * @return The start touch location in OpenGL coordinates. + */ Vec2 getStartLocation() const; - /** returns the delta of 2 current touches locations in screen coordinates */ + /** Returns the delta of 2 current touches locations in screen coordinates. + * + * @return The delta of 2 current touches locations in screen coordinates. + */ Vec2 getDelta() const; - /** returns the current touch location in screen coordinates */ + /** Returns the current touch location in screen coordinates. + * + * @return The current touch location in screen coordinates. + */ Vec2 getLocationInView() const; - /** returns the previous touch location in screen coordinates */ + /** Returns the previous touch location in screen coordinates. + * + * @return The previous touch location in screen coordinates. + */ Vec2 getPreviousLocationInView() const; - /** returns the start touch location in screen coordinates */ + /** Returns the start touch location in screen coordinates. + * + * @return The start touch location in screen coordinates. + */ Vec2 getStartLocationInView() const; diff --git a/cocos/base/CCEventTouch.h b/cocos/base/CCEventTouch.h index d4d5d9625b..50292fe547 100644 --- a/cocos/base/CCEventTouch.h +++ b/cocos/base/CCEventTouch.h @@ -34,11 +34,15 @@ class Touch; #define TOUCH_PERF_DEBUG 1 +/** @class EventTouch + * @brief Touch event. + */ class CC_DLL EventTouch : public Event { public: static const int MAX_TOUCHES = 15; + /** EventCode Touch event code.*/ enum class EventCode { BEGAN, @@ -47,13 +51,31 @@ public: CANCELLED }; + /** Constructor.*/ EventTouch(); + /** Get event code. + * + * @return The code of the event. + */ inline EventCode getEventCode() const { return _eventCode; }; + + /** Get the touches. + * + * @return The touches of the event. + */ inline const std::vector& getTouches() const { return _touches; }; #if TOUCH_PERF_DEBUG + /** Set the event code. + * + * @param eventCode A given EventCode. + */ void setEventCode(EventCode eventCode) { _eventCode = eventCode; }; + /** Set the touches + * + * @param touches A given touches vector. + */ void setTouches(const std::vector& touches) { _touches = touches; }; #endif