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