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