Add Page-UP/DOWN direction for KeyboardFocusManager

[platform/core/uifw/dali-toolkit.git] / dali-toolkit / public-api / controls / control.h

diff --git a/dali-toolkit/public-api/controls/control.h b/dali-toolkit/public-api/controls/control.h
index 3bada38..9ede92d 100644 (file)
--- a/dali-toolkit/public-api/controls/control.h
+++ b/dali-toolkit/public-api/controls/control.h
@@ -89,6 +89,10 @@ public:
    */
   struct Property
   {
+    /**
+     * @brief An enumeration of properties belonging to the Control class.
+     * @SINCE_1_0.0
+     */
     enum
     {
       /**
@@ -117,7 +121,7 @@ public:
        */
       KEY_INPUT_FOCUS,
       /**
-       * @brief name "background",       mutually exclusive with BACKGROUND_COLOR & BACKGROUND_IMAGE,                   type Map
+       * @brief name "background", mutually exclusive with BACKGROUND_COLOR & BACKGROUND_IMAGE, type Map or std::string for URL
        * @SINCE_1_1.3
        */
       BACKGROUND,
@@ -130,12 +134,18 @@ public:
    */
   struct KeyboardFocus
   {
+    /**
+     * @brief Keyboard focus direction
+     * @SINCE_1_0.0
+     */
     enum Direction
     {
       LEFT,   ///< Move keyboard focus towards the left direction @SINCE_1_0.0
       RIGHT,  ///< Move keyboard focus towards the right direction @SINCE_1_0.0
       UP,     ///< Move keyboard focus towards the up direction @SINCE_1_0.0
-      DOWN    ///< Move keyboard focus towards the down direction @SINCE_1_0.0
+      DOWN,    ///< Move keyboard focus towards the down direction @SINCE_1_0.0
+      PAGE_UP,     ///< Move keyboard focus towards the previous page direction @SINCE_1_2.14
+      PAGE_DOWN    ///< Move keyboard focus towards the next page direction @SINCE_1_2.14
     };
   };
 
@@ -169,14 +179,14 @@ public: // Creation & Destruction
   /**
    * @brief Copy constructor.
    *
-   * Creates another handle that points to the same real object
+   * Creates another handle that points to the same real object.
    * @SINCE_1_0.0
    * @param[in] uiControl Handle to copy
    */
   Control(const Control& uiControl);
 
   /**
-   * @brief Dali::Control is intended as a base class
+   * @brief Dali::Control is intended as a base class.
    *
    * This is non-virtual since derived Handle types must not contain data or virtual methods.
    * @SINCE_1_0.0
@@ -188,7 +198,7 @@ public: // operators
   /**
    * @brief Assignment operator.
    *
-   * Changes this handle to point to another real object
+   * Changes this handle to point to another real object.
    * @SINCE_1_0.0
    * @param[in] handle Object to assign this to
    * @return reference to this
@@ -198,14 +208,14 @@ public: // operators
 public:
 
   /**
-   * @brief Downcast an Object handle to Control.
+   * @brief Downcast a handle to Control handle.
    *
    * If handle points to a Control the downcast produces valid
    * handle. If not the returned handle is left uninitialized.
    *
    * @SINCE_1_0.0
    * @param[in] handle Handle to an object
-   * @return handle to a Control or an uninitialized handle
+   * @return A handle to a Control or an uninitialized handle
    */
   static Control DownCast( BaseHandle handle );
 
@@ -216,7 +226,6 @@ public:
    *
    * The key event can originate from a virtual or physical keyboard.
    * @SINCE_1_0.0
-   * @return True if the control has foucs, False otherwise.
    * @pre The Control has been initialized.
    * @pre The Control should be on the stage before setting keyboard focus.
    */
@@ -225,15 +234,15 @@ public:
   /**
    * @brief Quries whether the control has key input focus.
    *
-   * Note: The control can be set to have the focus and still not receive all the key events if another control has over ridden it.
-   * As the key input focus mechanism works like a stack, the top most control receives all the key events, and passes on the
-   * unhandled events to the controls below in the stack. A control in the stack will regain key input focus when there are no more
-   * controls above it in the focus stack.
-   * To query for the conrol which is on top of the focus stack use Dali::Toolkit::KeyInputFocusManager::GetCurrentKeyboardFocusActor()
    * @SINCE_1_0.0
    * @return true if this control has keyboard input focus
    * @pre The Control has been initialized.
    * @pre The Control should be on the stage before setting keyboard focus.
+   * @note The control can be set to have the focus and still not receive all the key events if another control has over ridden it.
+   * As the key input focus mechanism works like a stack, the top most control receives all the key events, and passes on the
+   * unhandled events to the controls below in the stack. A control in the stack will regain key input focus when there are no more
+   * controls above it in the focus stack.
+   * To query for the conrol which is on top of the focus stack use Dali::Toolkit::KeyInputFocusManager::GetCurrentKeyboardFocusActor().
    */
   bool HasKeyInputFocus();
 
@@ -323,15 +332,17 @@ public:
    * @SINCE_1_0.0
    * @return The background color of the control.
    */
-  Vector4 GetBackgroundColor() const;
+  Vector4 GetBackgroundColor() const DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_2_8, use Property::BACKGROUND instead
+   *
    * @brief Sets an image as the background of the control.
    *
    * @SINCE_1_0.0
    * @param[in] image The image to set as the background.
    */
-  void SetBackgroundImage( Image image );
+  void SetBackgroundImage( Image image ) DALI_DEPRECATED_API;
 
   /**
    * @brief Clears the background.
@@ -357,7 +368,7 @@ public:
   KeyEventSignalType& KeyEventSignal();
 
   /**
-   * @brief This signal is emitted when the control gets Key Input Focus
+   * @brief This signal is emitted when the control gets Key Input Focus.
    *
    * A callback of the following type may be connected:
    * @code