From 92809e6c4f454188f8a694871f045b93f6cb6e1b Mon Sep 17 00:00:00 2001 From: Seoyeon Kim Date: Tue, 2 Feb 2016 10:47:50 +0900 Subject: [PATCH] Update Events' public header comments Change-Id: I5bfe89ed6d8f25a41966d8ed595753446f3a8868 --- dali/public-api/events/gesture-detector.h | 14 ++++++++------ dali/public-api/events/gesture.h | 3 +++ dali/public-api/events/key-event.h | 13 +++++++++---- dali/public-api/events/long-press-gesture-detector.h | 10 +++++----- dali/public-api/events/long-press-gesture.h | 9 ++++++--- dali/public-api/events/pan-gesture-detector.h | 14 +++++++------- dali/public-api/events/pan-gesture.h | 11 +++++++---- dali/public-api/events/pinch-gesture-detector.h | 10 +++++----- dali/public-api/events/pinch-gesture.h | 11 +++++++---- dali/public-api/events/tap-gesture-detector.h | 20 ++++++++++---------- dali/public-api/events/tap-gesture.h | 3 +++ dali/public-api/events/touch-event.h | 2 +- dali/public-api/events/wheel-event.h | 8 ++++---- 13 files changed, 75 insertions(+), 53 deletions(-) diff --git a/dali/public-api/events/gesture-detector.h b/dali/public-api/events/gesture-detector.h index 18a7cff..c6cc8fd 100644 --- a/dali/public-api/events/gesture-detector.h +++ b/dali/public-api/events/gesture-detector.h @@ -53,21 +53,23 @@ class DALI_IMPORT_API GestureDetector : public Handle public: // Creation & Destruction /** - * @brief Create an uninitialized GestureDetector; this can be initialized with one of the derived gestures' New() methods. + * @brief Create an uninitialized GestureDetector. * - * Calling member functions with an uninitialized Dali::Object is not allowed. + * This can be initialized with one of the derived gesture detectors' New() methods. For example, PanGestureDetector::New(). + * + * Calling member functions with an uninitialized Dali::GestureDetector handle is not allowed. * @SINCE_1_0.0 */ GestureDetector(); /** - * @brief Downcast an Object handle to GestureDetector handle. + * @brief Downcast a handle to GestureDetector handle. * * If handle points to a GestureDetector object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @SINCE_1_0.0 - * @param[in] handle to An object - * @return handle to a GestureDetector object or an uninitialized handle + * @param[in] handle Handle to an object + * @return Handle to a GestureDetector object or an uninitialized handle */ static GestureDetector DownCast( BaseHandle handle ); @@ -150,7 +152,7 @@ public: // Actor related protected: /** - * @brief This constructor is used by Dali New() methods of derived classes. + * @brief This constructor is used by New() methods of derived classes (For example, PanGestureDetector::New()). * * @SINCE_1_0.0 * @param [in] internal A pointer to a newly allocated Dali resource. diff --git a/dali/public-api/events/gesture.h b/dali/public-api/events/gesture.h index d16adc7..ea67cd1 100644 --- a/dali/public-api/events/gesture.h +++ b/dali/public-api/events/gesture.h @@ -48,12 +48,15 @@ struct DALI_IMPORT_API Gesture /** * @brief Copy constructor. * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle */ Gesture( const Gesture& rhs ); /** * @brief Assignment operator. * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle + * @return A reference to this */ Gesture& operator=( const Gesture& rhs ); diff --git a/dali/public-api/events/key-event.h b/dali/public-api/events/key-event.h index 7e8bd72..a6b0c5b 100644 --- a/dali/public-api/events/key-event.h +++ b/dali/public-api/events/key-event.h @@ -42,7 +42,7 @@ namespace Dali * pressed. * * Currently KeyEvent is also being used to relay messages from the - * IMF keyboard to Core. In future IMF may communicate via its own + * IMF(Input Method Framework) keyboard to the internal core. In future IMF may communicate via its own * module. * @SINCE_1_0.0 */ @@ -90,7 +90,7 @@ struct DALI_IMPORT_API KeyEvent * @brief Check to see if Shift key modifier has been supplied. * * @SINCE_1_0.0 - * @return bool true if shift modifier + * @return True if shift modifier */ bool IsShiftModifier() const; @@ -98,7 +98,7 @@ struct DALI_IMPORT_API KeyEvent * @brief Check to see if Ctrl (control) key modifier has been supplied. * * @SINCE_1_0.0 - * @return bool true if ctrl modifier + * @return True if ctrl modifier */ bool IsCtrlModifier() const; @@ -106,7 +106,7 @@ struct DALI_IMPORT_API KeyEvent * @brief Check to see if Alt key modifier has been supplied. * * @SINCE_1_0.0 - * @return bool true if alt modifier + * @return True if alt modifier */ bool IsAltModifier() const; @@ -124,6 +124,11 @@ struct DALI_IMPORT_API KeyEvent /** * @brief Keycode for the key pressed. + * + * @remarks We recommend not to use this key code value + * directly because its meaning might be changed in the future. Currently, it means a + * platform-specific key code. You need to use IsKey() to know what a key event means + * instead of direct comparison of key code value. */ int keyCode; diff --git a/dali/public-api/events/long-press-gesture-detector.h b/dali/public-api/events/long-press-gesture-detector.h index 9d383be..4a9c849 100644 --- a/dali/public-api/events/long-press-gesture-detector.h +++ b/dali/public-api/events/long-press-gesture-detector.h @@ -70,7 +70,7 @@ public: // Creation & Destruction /** * @brief Create an uninitialized LongPressGestureDetector; this can be initialized with LongPressGestureDetector::New(). * - * Calling member functions with an uninitialized Dali::Object is not allowed. + * Calling member functions with an uninitialized LongPressGestureDetector handle is not allowed. * @SINCE_1_0.0 */ LongPressGestureDetector(); @@ -108,13 +108,13 @@ public: // Creation & Destruction static LongPressGestureDetector New(unsigned int minTouches, unsigned int maxTouches); /** - * @brief Downcast an Object handle to LongPressGestureDetector handle. + * @brief Downcast a handle to LongPressGestureDetector handle. * * If handle points to a LongPressGestureDetector object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @SINCE_1_0.0 - * @param[in] handle to An object - * @return handle to a LongPressGestureDetector object or an uninitialized handle + * @param[in] handle Handle to an object + * @return Handle to a LongPressGestureDetector object or an uninitialized handle */ static LongPressGestureDetector DownCast( BaseHandle handle ); @@ -211,7 +211,7 @@ public: // Signals public: // Not intended for Application developers /** - * @brief This constructor is used by Dali New() methods. + * @brief This constructor is used by LongPressGestureDetector::New() methods. * * @SINCE_1_0.0 * @param [in] internal A pointer to a newly allocated Dali resource. diff --git a/dali/public-api/events/long-press-gesture.h b/dali/public-api/events/long-press-gesture.h index 6ae3f86..a71df01 100644 --- a/dali/public-api/events/long-press-gesture.h +++ b/dali/public-api/events/long-press-gesture.h @@ -32,8 +32,8 @@ namespace Dali /** * @brief A LongPressGesture is emitted when the user touches and holds the screen with the stated number of fingers. * - * This gesture can be in one of two states, when the long-press gesture is first detected: "Started"; - * and when the long-press gesture ends: "Finished". + * This gesture can be in one of two states, when the long-press gesture is first detected: Gesture::Started + * and when the long-press gesture ends: Gesture::Finished. * * Long press gesture finishes when all touches have been released. * @@ -48,19 +48,22 @@ struct DALI_IMPORT_API LongPressGesture : public Gesture * @brief Constructor * * @SINCE_1_0.0 - * @param[in] state The state of the gesture + * @param[in] state The state of the gesture */ LongPressGesture(Gesture::State state); /** * @brief Copy constructor * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle */ LongPressGesture( const LongPressGesture& rhs ); /** * @brief Assignment operator * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle + * @return A reference to this */ LongPressGesture& operator=( const LongPressGesture& rhs ); diff --git a/dali/public-api/events/pan-gesture-detector.h b/dali/public-api/events/pan-gesture-detector.h index 75b1677..72f688e 100644 --- a/dali/public-api/events/pan-gesture-detector.h +++ b/dali/public-api/events/pan-gesture-detector.h @@ -105,7 +105,7 @@ public: // Creation & Destruction /** * @brief Create an uninitialized PanGestureDetector; this can be initialized with PanGestureDetector::New(). * - * Calling member functions with an uninitialized Dali::Object is not allowed. + * Calling member functions with an uninitialized PanGestureDetector handle is not allowed. * @SINCE_1_0.0 */ PanGestureDetector(); @@ -119,13 +119,13 @@ public: // Creation & Destruction static PanGestureDetector New(); /** - * @brief Downcast an Object handle to PanGestureDetector handle. + * @brief Downcast a handle to PanGestureDetector handle. * * If handle points to a PanGestureDetector object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @SINCE_1_0.0 - * @param[in] handle to An object - * @return handle to a PanGestureDetector object or an uninitialized handle + * @param[in] handle Handle to an object + * @return Handle to a PanGestureDetector object or an uninitialized handle */ static PanGestureDetector DownCast( BaseHandle handle ); @@ -268,7 +268,7 @@ public: // Directional Panning * @brief Returns the angle by index that this pan gesture detector emits a signal. * * @SINCE_1_0.0 - * @return an angle threshold pair, or a zero valued angle pair when index is invalid. + * @return An angle threshold pair, or a zero valued angle pair when index is invalid. * @pre The gesture detector has been initialized. * @pre The index is less than GetAngleCount() */ @@ -336,10 +336,10 @@ public: // Pan Properties Setters public: // Not intended for Application developers /** - * @brief This constructor is used by Dali New() methods. + * @brief This constructor is used by PanGestureDetector::New() methods. * * @SINCE_1_0.0 - * @param [in] internal A pointer to a newly allocated Dali resource. + * @param [in] internal A pointer to a newly allocated Dali resource. */ explicit DALI_INTERNAL PanGestureDetector(Internal::PanGestureDetector* internal); diff --git a/dali/public-api/events/pan-gesture.h b/dali/public-api/events/pan-gesture.h index 61ee338..18acedc 100644 --- a/dali/public-api/events/pan-gesture.h +++ b/dali/public-api/events/pan-gesture.h @@ -32,9 +32,9 @@ namespace Dali /** * @brief A PanGesture is emitted when the user moves one or more fingers in a particular direction. * - * This gesture can be in one of three states, when the pan gesture is first detected: "Started"; - * when the pan gesture is continuing: "Continuing"; and finally, when the pan gesture ends: - * "Finished". + * This gesture can be in one of three states, when the pan gesture is first detected: Gesture::Started + * when the pan gesture is continuing: Gesture::Continuing and finally, when the pan gesture ends: + * Gesture::Finished. * * A pan gesture will end in the following ways: * - User releases the primary finger (the first touch). @@ -59,19 +59,22 @@ struct DALI_IMPORT_API PanGesture: public Gesture * @brief Constructor. * * @SINCE_1_0.0 - * @param[in] state The state of the gesture + * @param[in] state The state of the gesture */ PanGesture(Gesture::State state); /** * @brief Copy constructor. * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle */ PanGesture( const PanGesture& rhs ); /** * @brief Assignment operator. * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle + * @return A reference to this */ PanGesture& operator=( const PanGesture& rhs ); diff --git a/dali/public-api/events/pinch-gesture-detector.h b/dali/public-api/events/pinch-gesture-detector.h index 3cda2fc..37eb16a 100644 --- a/dali/public-api/events/pinch-gesture-detector.h +++ b/dali/public-api/events/pinch-gesture-detector.h @@ -73,7 +73,7 @@ public: // Creation & Destruction /** * @brief Create an uninitialized PinchGestureDetector; this can be initialized with PinchGestureDetector::New(). * - * Calling member functions with an uninitialized Dali::Object is not allowed. + * Calling member functions with an uninitialized PinchGestureDetector handle is not allowed. * @SINCE_1_0.0 */ PinchGestureDetector(); @@ -87,13 +87,13 @@ public: // Creation & Destruction static PinchGestureDetector New(); /** - * @brief Downcast an Object handle to PinchGestureDetector handle. + * @brief Downcast a handle to PinchGestureDetector handle. * * If handle points to a PinchGestureDetector object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @SINCE_1_0.0 - * @param[in] handle to An object - * @return handle to a PinchGestureDetector object or an uninitialized handle + * @param[in] handle Handle to an object + * @return Handle to a PinchGestureDetector object or an uninitialized handle */ static PinchGestureDetector DownCast( BaseHandle handle ); @@ -140,7 +140,7 @@ public: // Signals public: // Not intended for Application developers /** - * @brief This constructor is used by Dali New() methods. + * @brief This constructor is used by PinchGestureDetector::New() methods. * * @SINCE_1_0.0 * @param [in] internal A pointer to a newly allocated Dali resource. diff --git a/dali/public-api/events/pinch-gesture.h b/dali/public-api/events/pinch-gesture.h index 0f35ee4..9d67203 100644 --- a/dali/public-api/events/pinch-gesture.h +++ b/dali/public-api/events/pinch-gesture.h @@ -33,9 +33,9 @@ namespace Dali * @brief A PinchGesture is emitted when the user moves two fingers towards or away from each other. * * This gesture can be in one of three states; when the pinch gesture is first detected, its - * state is set to "Started". After this, if there is change in the gesture, the state will - * be "Continuing". Finally, when the gesture ends, the state of the gesture changes to - * "Finished". + * state is set to Gesture::Started. After this, if there is change in the gesture, the state will + * be Gesture::Continuing. Finally, when the gesture ends, the state of the gesture changes to + * Gesture::Finished. * * A pinch gesture will continue to be sent to the actor under the center point of the pinch * until the pinch ends. @@ -49,19 +49,22 @@ struct DALI_IMPORT_API PinchGesture: public Gesture * @brief Default Constructor. * * @SINCE_1_0.0 - * @param[in] state The state of the gesture + * @param[in] state The state of the gesture */ PinchGesture(Gesture::State state); /** * @brief Copy constructor. * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle */ PinchGesture( const PinchGesture& rhs ); /** * @brief Assignment operator. * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle + * @return A reference to this */ PinchGesture& operator=( const PinchGesture& rhs ); diff --git a/dali/public-api/events/tap-gesture-detector.h b/dali/public-api/events/tap-gesture-detector.h index 3f6b002..3f322d1 100644 --- a/dali/public-api/events/tap-gesture-detector.h +++ b/dali/public-api/events/tap-gesture-detector.h @@ -40,9 +40,9 @@ struct TapGesture; * @brief This class emits a signal when a tap gesture occurs that meets the requirements set by the * application. * - * See TapGestureDetector::SetTapsRequired + * See @ref TapGestureDetector::SetTapsRequired * - * A Tap Gesture is a discrete gesture, which means it does not have any state information attached + * A TapGesture is a discrete gesture, which means it does not have any state information attached * to it. Please see TapGesture for more information. * * The application programmer can use this gesture detector as follows: @@ -53,7 +53,7 @@ struct TapGesture; * @endcode * * @SINCE_1_0.0 - * @note Multi-touch taps are not currently supported. However, multiple taps (double & triple tap etc.) ARE supported. + * @note Multi-touch taps are not currently supported. However, multiple taps (double & triple tap etc.) are supported. * * Signals * | %Signal Name | Method | @@ -77,7 +77,7 @@ public: // Creation & Destruction /** * @brief Create an uninitialized TapGestureDetector; this can be initialized with TapGestureDetector::New(). * - * Calling member functions with an uninitialized Dali::Object is not allowed. + * Calling member functions with an uninitialized TapGestureDetector handle is not allowed. * @SINCE_1_0.0 */ TapGestureDetector(); @@ -95,19 +95,19 @@ public: // Creation & Destruction * @brief Create an initialized TapGestureDetector with the specified parameters. * * @SINCE_1_0.0 - * @param[in] tapsRequired The minimum & maximum number of taps required. + * @param[in] tapsRequired The minimum & maximum number of taps required. * @return A handle to a newly allocated Dali resource. */ static TapGestureDetector New( unsigned int tapsRequired ); /** - * @brief Downcast an Object handle to TapGestureDetector handle. + * @brief Downcast a handle to TapGestureDetector handle. * * If handle points to a TapGestureDetector object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @SINCE_1_0.0 - * @param[in] handle to An object - * @return handle to a TapGestureDetector object or an uninitialized handle + * @param[in] handle Handle to an object + * @return Handle to a TapGestureDetector object or an uninitialized handle */ static TapGestureDetector DownCast( BaseHandle handle ); @@ -198,10 +198,10 @@ public: // Signals public: // Not intended for Application developers /** - * @brief This constructor is used by Dali New() methods. + * @brief This constructor is used by TapGestureDetector::New() methods. * * @SINCE_1_0.0 - * @param [in] internal A pointer to a newly allocated Dali resource. + * @param [in] internal A pointer to a newly allocated Dali resource. */ explicit DALI_INTERNAL TapGestureDetector(Internal::TapGestureDetector* internal); }; diff --git a/dali/public-api/events/tap-gesture.h b/dali/public-api/events/tap-gesture.h index 0aa32fb..0f8645d 100644 --- a/dali/public-api/events/tap-gesture.h +++ b/dali/public-api/events/tap-gesture.h @@ -49,12 +49,15 @@ struct DALI_IMPORT_API TapGesture : public Gesture /** * @brief Copy constructor * @SINCE_1_0.0 + * @param rhs A reference to the copied handle */ TapGesture( const TapGesture& rhs ); /** * @brief Assignment operator * @SINCE_1_0.0 + * @param rhs A reference to the copied handle + * @return A reference to this */ TapGesture& operator=( const TapGesture& rhs ); diff --git a/dali/public-api/events/touch-event.h b/dali/public-api/events/touch-event.h index 0d76880..3fc4463 100644 --- a/dali/public-api/events/touch-event.h +++ b/dali/public-api/events/touch-event.h @@ -49,7 +49,7 @@ struct DALI_IMPORT_API TouchEvent /** * @brief Constructor * @SINCE_1_0.0 - * @param[in] time The time the event occurred + * @param[in] time The time the event occurred */ TouchEvent(unsigned long time); diff --git a/dali/public-api/events/wheel-event.h b/dali/public-api/events/wheel-event.h index 47351c6..ab4c442 100644 --- a/dali/public-api/events/wheel-event.h +++ b/dali/public-api/events/wheel-event.h @@ -67,7 +67,7 @@ struct DALI_IMPORT_API WheelEvent * @SINCE_1_0.0 * @param[in] type The type of the wheel event * @param[in] direction The direction of wheel rolling (0 = default vertical wheel, 1 = horizontal wheel) - * @param[in] modifiers modifier keys pressed during the event (such as shift, alt and control) + * @param[in] modifiers Modifier keys pressed during the event (such as shift, alt and control) * @param[in] point The co-ordinates of the cursor relative to the top-left of the screen. * @param[in] z The offset of rolling (positive value means roll down or clockwise, and negative value means roll up or counter-clockwise) * @param[in] timeStamp The time the wheel is being rolled. @@ -84,7 +84,7 @@ struct DALI_IMPORT_API WheelEvent * @brief Check to see if Shift key modifier has been supplied. * * @SINCE_1_0.0 - * @return bool true if shift modifier + * @return True if shift modifier */ bool IsShiftModifier() const; @@ -92,7 +92,7 @@ struct DALI_IMPORT_API WheelEvent * @brief Check to see if Ctrl (control) key modifier has been supplied. * * @SINCE_1_0.0 - * @return bool true if ctrl modifier + * @return True if ctrl modifier */ bool IsCtrlModifier() const; @@ -100,7 +100,7 @@ struct DALI_IMPORT_API WheelEvent * @brief Check to see if Alt key modifier has been supplied. * * @SINCE_1_0.0 - * @return bool true if alt modifier + * @return True if alt modifier */ bool IsAltModifier() const; -- 2.7.4