adaptors/public-api/adaptor-framework/accessibility-manager.h

   1 #ifndef __DALI_ACCESSIBILITY_MANAGER_H__
   2 #define __DALI_ACCESSIBILITY_MANAGER_H__
   3
   4 /*
   5  * Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21
  22 // EXTERNAL INCLUDES
  23 #include <dali/public-api/events/touch-event.h>
  24 #include <dali/public-api/object/base-handle.h>
  25 #include <dali/public-api/signals/dali-signal.h>
  26
  27 namespace Dali
  28 {
  29
  30 namespace Internal DALI_INTERNAL
  31 {
  32 namespace Adaptor
  33 {
  34 class AccessibilityManager;
  35 }
  36 }
  37
  38 class AccessibilityActionHandler;
  39 class AccessibilityGestureHandler;
  40 class TouchPoint;
  41
  42 /**
  43  * @brief The AccessibilityManager provides signals when accessibility & screen reader feature turned on in device.
  44  */
  45 class DALI_IMPORT_API AccessibilityManager : public BaseHandle
  46 {
  47 public:
  48
  49   // Typedefs
  50
  51   /**
  52    * @brief Accessibility Action Signal.
  53    *
  54    * Signal connected callback should return the result
  55    */
  56   typedef Signal< bool ( AccessibilityManager& ) > AccessibilityActionSignalType; ///< Generic signal type
  57   typedef Signal< bool (AccessibilityManager&, const Dali::TouchEvent&)> AccessibilityActionScrollSignalType; ///< Scroll signal type
  58
  59   /**
  60    * @brief Create an uninitialized handle.
  61    *
  62    * This can be initialized by calling getting the manager from Dali::Adaptor.
  63    */
  64   AccessibilityManager();
  65
  66   /**
  67    * @brief Retrieve a handle to the AccessibilityManager.
  68    *
  69    * @return A handle to the AccessibilityManager.
  70    */
  71   static AccessibilityManager Get();
  72
  73   /**
  74    * @brief Destructor
  75    *
  76    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  77    */
  78   ~AccessibilityManager();
  79
  80   /**
  81    * @brief Returns the current position of the read action.
  82    * @return The current event position.
  83    */
  84   Vector2 GetReadPosition() const;
  85
  86   /**
  87    * @brief Query whether the accessibility(screen-reader) is enabled.
  88    *
  89    * The accessibility will be enabled by system setting.
  90    * @return True if the accessibility(screen-reader) is enabled.
  91    */
  92   bool IsEnabled() const;
  93
  94   /**
  95    * @brief Set the handler to handle accessibility actions.
  96    *
  97    * @param[in] handler The Accessibility action handler.
  98    * @note Handlers should remove themselves when they are destroyed.
  99    */
 100   void SetActionHandler(AccessibilityActionHandler& handler);
 101
 102   /**
 103    * @brief Set the handler to handle accessibility gestures.
 104    *
 105    * @param[in] handler The Accessibility gesture handler.
 106    * @note Handlers should remove themselves when they are destroyed.
 107    */
 108   void SetGestureHandler(AccessibilityGestureHandler& handler);
 109
 110   /**
 111    * @brief Handle the accessibility action to move focus to the next focusable actor
 112    * (by one finger flick down).
 113    *
 114    * @param allowEndFeedback true if end of list feedback should be played when the focus is alread reached to the end
 115    * @return Whether the action is performed successfully or not.
 116    */
 117   bool HandleActionNextEvent(bool allowEndFeedback = true);
 118
 119   /**
 120    * @brief Handle the accessibility action to move focus to the previous focusable actor
 121    * (by one finger flick up).
 122    *
 123    * @param allowEndFeedback true if end of list feedback should be played when the focus is alread reached to the end
 124    * @return Whether the action is performed successfully or not.
 125    */
 126   bool HandleActionPreviousEvent(bool allowEndFeedback = true);
 127
 128   /**
 129    * @brief Handle the accessibility action to activate the current focused actor (by one
 130    * finger double tap)
 131    *
 132    * @return Whether the action is performed successfully or not.
 133    */
 134   bool HandleActionActivateEvent();
 135
 136   /**
 137    * @brief Handle the accessibility action to focus and read the actor (by one finger tap or move).
 138    *
 139    * @param x x position of event
 140    * @param y y position of event
 141    * @param allowReadAgain true if the action read again the same object (i.e. read action)
 142    *                       false if the action just read when the focus object is changed (i.e. over action)
 143    * @return Whether the action is performed successfully or not.
 144    */
 145   bool HandleActionReadEvent(unsigned int x, unsigned int y, bool allowReadAgain);
 146
 147   /**
 148    * @brief Handle the accessibility action to move focus to the next focusable actor
 149    * (by one finger flick right).
 150    *
 151    * @param allowEndFeedback true if end of list feedback should be played when the focus is alread reached to the end
 152    * @return Whether the action is performed successfully or not.
 153    */
 154   bool HandleActionReadNextEvent(bool allowEndFeedback = true);
 155
 156   /**
 157    * @brief Handle the accessibility action to move focus to the previous focusable actor
 158    * (by one finger flick up).
 159    *
 160    * @param allowEndFeedback true if end of list feedback should be played when the focus is alread reached to the front
 161    * @return Whether the action is performed successfully or not.
 162    */
 163   bool HandleActionReadPreviousEvent(bool allowEndFeedback = true);
 164
 165   /**
 166    * @brief Handle the accessibility action to change the value when the current focused
 167    * actor is a slider (by double finger down and move up and right).
 168    *
 169    * @return Whether the action is performed successfully or not.
 170    */
 171   bool HandleActionUpEvent();
 172
 173   /**
 174    * @brief Handle the accessibility action to change the value when the current focused
 175    * actor is a slider (by double finger down and move down and left).
 176    *
 177    * @return Whether the action is performed successfully or not.
 178    */
 179   bool HandleActionDownEvent();
 180
 181   /**
 182    * @brief Handle the accessibility action to clear the focus from the current focused
 183    * actor if any, so that no actor is focused in the focus chain.
 184    *
 185    * @return Whether the action is performed successfully or not.
 186    */
 187   bool HandleActionClearFocusEvent();
 188
 189   /**
 190    * @brief Handle the accessibility action to scroll when there is a scroller on the touched position
 191    * (by 2 finger touch & move, 2 finger flick).
 192    *
 193    * @param[in]  point      The touch point information.
 194    * @param[in]  timeStamp  The time the touch occurred.
 195    * @return Whether the action is performed successfully or not.
 196    */
 197   bool HandleActionScrollEvent(const TouchPoint& point, unsigned long timeStamp);
 198
 199   /**
 200    * @brief Handle the accessibility action to move for the current focused actor
 201    * (by 1 finger tap & hold and move).
 202    *
 203    * @param[in]  point      The touch point information.
 204    * @param[in]  timeStamp  The time the touch occurred.
 205    * @return Whether the action is performed successfully or not.
 206    */
 207   bool HandleActionTouchEvent(const TouchPoint& point, unsigned long timeStamp);
 208
 209   /**
 210    * @brief Handle the accessibility action to navigate back (by two fingers circle draw).
 211    * @return Whether the action is performed successfully or not.
 212    */
 213   bool HandleActionBackEvent();
 214
 215   /**
 216    * @brief Handle the accessibility action to enable the feature.
 217    */
 218   void HandleActionEnableEvent();
 219
 220   /**
 221    * @brief Handle the accessibility action to disable the feature.
 222    */
 223   void HandleActionDisableEvent();
 224
 225 public:  // Signals
 226
 227   /**
 228    * @brief This is emitted when accessibility(screen-reader) feature turned on or off.
 229    *
 230    * A callback of the following type may be connected:
 231    * @code
 232    *   bool YourCallback( AccessibilityManager& manager );
 233    * @endcode
 234    * @return The signal to connect to.
 235    */
 236   AccessibilityActionSignalType& StatusChangedSignal();
 237
 238   /**
 239    * @brief This is emitted when accessibility action is received to move focus to the next
 240    * focusable actor (by one finger flick down).
 241    *
 242    * A callback of the following type may be connected:
 243    * @code
 244    *   bool YourCallback( AccessibilityManager& manager );
 245    * @endcode
 246    * @return The signal to connect to.
 247    */
 248   AccessibilityActionSignalType& ActionNextSignal();
 249
 250   /**
 251    * @brief This is emitted when accessibility action is received to move focus to the previous
 252    * focusable actor (by one finger flick up).
 253    *
 254    * A callback of the following type may be connected:
 255    * @code
 256    *   bool YourCallback( AccessibilityManager& manager );
 257    * @endcode
 258    * @return The signal to connect to.
 259    */
 260   AccessibilityActionSignalType& ActionPreviousSignal();
 261
 262   /**
 263    * @brief This is emitted when accessibility action is received to activate the current focused
 264    * actor (by one finger double tap).
 265    *
 266    * A callback of the following type may be connected:
 267    * @code
 268    *   bool YourCallback( AccessibilityManager& manager );
 269    * @endcode
 270    * @return The signal to connect to.
 271    */
 272   AccessibilityActionSignalType& ActionActivateSignal();
 273
 274   /**
 275    * @brief This is emitted when accessibility action is received to focus and read the actor
 276    * (by one finger tap).
 277    *
 278    * A callback of the following type may be connected:
 279    * @code
 280    *   bool YourCallback( AccessibilityManager& manager );
 281    * @endcode
 282    * @return The signal to connect to.
 283    */
 284   AccessibilityActionSignalType& ActionReadSignal();
 285
 286   /**
 287    * @brief This is emitted when accessibility action is received to focus and read the actor
 288    * (by one finger move).
 289    *
 290    * A callback of the following type may be connected:
 291    * @code
 292    *   bool YourCallback( AccessibilityManager& manager );
 293    * @endcode
 294    * @return The signal to connect to.
 295    */
 296   AccessibilityActionSignalType& ActionOverSignal();
 297
 298   /**
 299    * @brief This is emitted when accessibility action is received to move focus to the next
 300    * focusable actor (by one finger flick right).
 301    *
 302    * A callback of the following type may be connected:
 303    * @code
 304    *   bool YourCallback( AccessibilityManager& manager );
 305    * @endcode
 306    * @return The signal to connect to.
 307    */
 308   AccessibilityActionSignalType& ActionReadNextSignal();
 309
 310   /**
 311    * @brief This is emitted when accessibility action is received to move focus to the previous
 312    * focusable actor (by one finger flick left).
 313    *
 314    * A callback of the following type may be connected:
 315    * @code
 316    *   bool YourCallback( AccessibilityManager& manager );
 317    * @endcode
 318    * @return The signal to connect to.
 319    */
 320   AccessibilityActionSignalType& ActionReadPreviousSignal();
 321
 322   /**
 323    * @brief This is emitted when accessibility action is received to change the value when the
 324    * current focused actor is a slider (by double finger down and move up and right).
 325    *
 326    * A callback of the following type may be connected:
 327    * @code
 328    *   bool YourCallback( AccessibilityManager& manager );
 329    * @endcode
 330    * @return The signal to connect to.
 331    */
 332   AccessibilityActionSignalType& ActionUpSignal();
 333
 334   /**
 335    * @brief This is emitted when accessibility action is received to change the value when the
 336    * current focused actor is a slider (by double finger down and move down and left).
 337    *
 338    * A callback of the following type may be connected:
 339    * @code
 340    *   bool YourCallback( AccessibilityManager& manager );
 341    * @endcode
 342    * @return The signal to connect to.
 343    */
 344   AccessibilityActionSignalType& ActionDownSignal();
 345
 346   /**
 347    * @brief This is emitted when accessibility action is received to clear the focus from the
 348    * current focused actor if any, so that no actor is focused in the focus chain.
 349    *
 350    * A callback of the following type may be connected:
 351    * @code
 352    *   bool YourCallback( AccessibilityManager& manager );
 353    * @endcode
 354    * @return The signal to connect to.
 355    */
 356   AccessibilityActionSignalType& ActionClearFocusSignal();
 357
 358   /**
 359    * @brief This is emitted when accessibility action is received to navigate back (by two
 360    * fingers circle draw).
 361    *
 362    * A callback of the following type may be connected:
 363    * @code
 364    *   bool YourCallback( AccessibilityManager& manager );
 365    * @endcode
 366    * @return The signal to connect to.
 367    */
 368   AccessibilityActionSignalType& ActionBackSignal();
 369
 370   /**
 371    * @brief This is emitted when accessibility action is received to handle scroll event (by two
 372    * fingers drag).
 373    *
 374    * A callback of the following type may be connected:
 375    * @code
 376    *   bool YourCallback( AccessibilityManager& manager, const TouchEvent& event );
 377    * @endcode
 378    * @return The signal to connect to.
 379    */
 380   AccessibilityActionScrollSignalType& ActionScrollSignal();
 381
 382 public: // Not intended for application developers
 383
 384   /**
 385    * @brief Creates a handle using the Adaptor::Internal implementation.
 386    *
 387    * @param[in] manager The AccessibilityManager implementation.
 388    */
 389   DALI_INTERNAL AccessibilityManager( Internal::Adaptor::AccessibilityManager& manager );
 390
 391   /**
 392    * @brief This constructor is used by AccessibilityManager::Get().
 393    *
 394    * @param[in] manager A pointer to the accessibility manager.
 395    */
 396   explicit DALI_INTERNAL AccessibilityManager( Internal::Adaptor::AccessibilityManager* manager );
 397 };
 398
 399 } // namespace Dali
 400
 401 #endif // __DALI_ACCESSIBILITY_MANAGER_H__