dali-toolkit/devel-api/controls/control-devel.h

   1 #ifndef DALI_TOOLKIT_CONTROL_DEVEL_H
   2 #define DALI_TOOLKIT_CONTROL_DEVEL_H
   3
   4 /*
   5  * Copyright (c) 2021 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 // EXTERNAL INCLUDES
  21 #include <dali/devel-api/adaptor-framework/accessibility-impl.h>
  22 #include <dali/devel-api/adaptor-framework/input-method-context.h>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali-toolkit/devel-api/controls/accessible-impl.h>
  26 #include <dali-toolkit/devel-api/visual-factory/visual-base.h>
  27 #include <dali-toolkit/public-api/controls/control.h>
  28
  29 namespace Dali
  30 {
  31 namespace Toolkit
  32 {
  33 class TransitionData;
  34
  35 namespace Visual
  36 {
  37 class Base;
  38 }
  39
  40 namespace DevelControl
  41 {
  42 /// @brief AccessibilityActivate signal type.
  43 typedef Signal<void()> AccessibilityActivateSignalType;
  44
  45 /// @brief AccessibilityReadingSkipped signal type.
  46 typedef Signal<void()> AccessibilityReadingSkippedSignalType;
  47
  48 /// @brief AccessibilityReadingPaused signal type.
  49 typedef Signal<void()> AccessibilityReadingPausedSignalType;
  50
  51 /// @brief AccessibilityReadingResumed signal type.
  52 typedef Signal<void()> AccessibilityReadingResumedSignalType;
  53
  54 /// @brief AccessibilityReadingCancelled signal type.
  55 typedef Signal<void()> AccessibilityReadingCancelledSignalType;
  56
  57 /// @brief AccessibilityReadingStopped signal type.
  58 typedef Signal<void()> AccessibilityReadingStoppedSignalType;
  59
  60 /// @brief AccessibilityGetName signal type.
  61 typedef Signal<void(std::string&)> AccessibilityGetNameSignalType;
  62
  63 /// @brief AccessibilityGetDescription signal type.
  64 typedef Signal<void(std::string&)> AccessibilityGetDescriptionSignalType;
  65
  66 /// @brief AccessibilityDoGesture signal type.
  67 typedef Signal<void(std::pair<Dali::Accessibility::GestureInfo, bool>&)> AccessibilityDoGestureSignalType;
  68
  69 enum State
  70 {
  71   NORMAL,
  72   FOCUSED,
  73   DISABLED
  74 };
  75
  76 namespace Property
  77 {
  78 enum
  79 {
  80   STYLE_NAME      = Control::Property::STYLE_NAME,
  81   KEY_INPUT_FOCUS = Control::Property::KEY_INPUT_FOCUS,
  82   BACKGROUND      = Control::Property::BACKGROUND,
  83   MARGIN          = Control::Property::MARGIN,
  84   PADDING         = Control::Property::PADDING,
  85
  86   /**
  87    * @brief Displays a tooltip when the control is hovered over.
  88    * @details Name "tooltip", type Property::STRING, Property::ARRAY or Property::MAP.
  89    *          If Property::STRING, then the style specified in the stylesheet is used.
  90    *          If Property::ARRAY of Visuals then all are displayed in one row.
  91    *          If Property::MAP, then it should be a map of Tooltip properties.
  92    * @note The tooltip is only activated if display content is received, i.e. a string (text) or visual to show.
  93    *       The rest is used to just build up the style of the tooltip (i.e. background, text color/point-size etc.)
  94    * @note When retrieved, a Property::MAP is returned.
  95    * @see Toolkit::Tooltip
  96    */
  97   TOOLTIP = PADDING + 1,
  98
  99   /**
 100    * @brief The current state of the control.
 101    * @details Name "state", type DevelControl::State ( Property::INTEGER ) or Property::STRING
 102    *
 103    * @see DevelControl::State
 104    */
 105   STATE = PADDING + 2,
 106
 107   /**
 108    * @brief The current sub state of the control.
 109    * @details Name "subState", type Property::INTEGER or Property::STRING. The enumeration used is dependent on the derived control.
 110    *
 111    * @see DevelControl::State
 112    */
 113   SUB_STATE = PADDING + 3,
 114
 115   /**
 116    * @brief The actor ID of the left focusable control.
 117    * @details Name "leftFocusableActorId", type Property::INTEGER.
 118    *
 119    */
 120   LEFT_FOCUSABLE_ACTOR_ID = PADDING + 4,
 121
 122   /**
 123    * @brief The actor ID of the right focusable control.
 124    * @details Name "rightFocusableActorId", type Property::INTEGER.
 125    *
 126    */
 127   RIGHT_FOCUSABLE_ACTOR_ID = PADDING + 5,
 128
 129   /**
 130    * @brief The actor ID of the up focusable control.
 131    * @details Name "upFocusableActorId", type Property::INTEGER.
 132    *
 133    */
 134   UP_FOCUSABLE_ACTOR_ID = PADDING + 6,
 135
 136   /**
 137    * @brief The actor ID of the down focusable control.
 138    * @details Name "downFocusableActorId", type Property::INTEGER.
 139    *
 140    */
 141   DOWN_FOCUSABLE_ACTOR_ID = PADDING + 7,
 142
 143   /**
 144    * @brief The shadow of the control.
 145    * @details Name "shadow", type Property::MAP.
 146    */
 147   SHADOW = PADDING + 8,
 148
 149   /**
 150    * @brief The name of object visible in accessibility tree.
 151    * @details Name "accessibilityName", type Property::STRING.
 152    */
 153   ACCESSIBILITY_NAME,
 154
 155   /**
 156    * @brief The description of object visible in accessibility tree.
 157    * @details Name "accessibilityDescription", type Property::STRING.
 158    */
 159   ACCESSIBILITY_DESCRIPTION,
 160
 161   /**
 162    * @brief Current translation domain for accessibility clients.
 163    * @details Name "accessibilityTranslationDomain", type Property::STRING.
 164    */
 165   ACCESSIBILITY_TRANSLATION_DOMAIN,
 166
 167   /**
 168    * @brief Role being performed in accessibility hierarchy.
 169    * @details Name "accessibilityRole", type Property::INTEGER.
 170    * @note Property is stored as INTEGER, however its interpretaton
 171    * depend on enumeration Dali::Accessibility::Role and should be read and written
 172    * with usage of enumerated values.
 173    * @see Dali::Accessibility::Role
 174    */
 175   ACCESSIBILITY_ROLE,
 176   /**
 177    * @brief Mark of able to highlight object.
 178    * @details Name "accessibilityHighlightable", type Property::BOOLEAN.
 179    */
 180   ACCESSIBILITY_HIGHLIGHTABLE,
 181   /**
 182    * @brief Set of accessibility attributes describing object in accessibility hierarchy
 183    * @details Name "accessibilityAttributes", type Property::MAP
 184    */
 185   ACCESSIBILITY_ATTRIBUTES,
 186
 187   /**
 188    * @brief Boolean flag describing object as animated
 189    * @details Name "accessibilityAnimated", type Property::BOOLEAN
 190    * @note Flag set to true will prevent BoundChanged accessibility signal from emiting
 191    */
 192   ACCESSIBILITY_ANIMATED
 193 };
 194
 195 } // namespace Property
 196
 197 /**
 198  * @brief Register a visual by Property Index.
 199  *
 200  * @param[in] control The control
 201  * @param[in] index The Property index of the visual, used to reference visual
 202  * @param[in] visual The visual to register
 203  *
 204  * @note Derived class should not call visual.SetOnScene(actor). It is the responsibility of the base class to connect/disconnect registered visual to stage.
 205  *       Use below API with enabled set to false if derived class wishes to control when visual is staged.
 206  * @note If the depth-index is not set on the visual, then it is set to be above the currently registered visuals.
 207  * @note If replacing a visual, then the depth-index of the visual being replaced is used for the visual.
 208  */
 209 DALI_TOOLKIT_API void RegisterVisual(Internal::Control& control, Dali::Property::Index index, Toolkit::Visual::Base& visual);
 210
 211 /**
 212  * @brief Register a visual by Property Index with a depth index.
 213  *
 214  * @param[in] control The control
 215  * @param[in] index The Property index of the visual, used to reference visual
 216  * @param[in] visual The visual to register
 217  * @param[in] depthIndex The visual's depth-index is set to this
 218  *
 219  * @note Derived class should not call visual.SetOnScene(actor). It is the responsibility of the base class to connect/disconnect registered visual to stage.
 220  *       Use below API with enabled set to false if derived class wishes to control when visual is staged.
 221  *
 222  * @see Visual::Base::GetDepthIndex()
 223  * @see Visual::Base::SetDepthIndex()
 224  */
 225 DALI_TOOLKIT_API void RegisterVisual(Internal::Control& control, Dali::Property::Index index, Toolkit::Visual::Base& visual, int depthIndex);
 226
 227 /**
 228  * @brief Register a visual by Property Index with the option of enabling/disabling it.
 229  *
 230  * @param[in] control The control
 231  * @param[in] index The Property index of the visual, used to reference visual
 232  * @param[in] visual The visual to register
 233  * @param[in] enabled false if derived class wants to control when visual is set on stage.
 234  *
 235  * @note If the depth-index is not set on the visual, then it is set to be above the currently registered visuals.
 236  * @note If replacing a visual, then the depth-index of the visual being replaced is used for the visual.
 237  *
 238  * @see EnableVisual()
 239  */
 240 DALI_TOOLKIT_API void RegisterVisual(Internal::Control& control, Dali::Property::Index index, Toolkit::Visual::Base& visual, bool enabled);
 241
 242 /**
 243  * @brief Register a visual by Property Index with a depth index with the option of enabling/disabling it.
 244  *
 245  * @param[in] control The control
 246  * @param[in] index The Property index of the visual, used to reference visual
 247  * @param[in] visual The visual to register
 248  * @param[in] enabled false if derived class wants to control when visual is set on stage.
 249  * @param[in] depthIndex The visual's depth-index is set to this
 250  *
 251  * @see EnableVisual()
 252  * @see Visual::Base::GetDepthIndex()
 253  * @see Visual::Base::SetDepthIndex()
 254  */
 255 DALI_TOOLKIT_API void RegisterVisual(Internal::Control& control, Dali::Property::Index index, Toolkit::Visual::Base& visual, bool enabled, int depthIndex);
 256
 257 /**
 258  * @brief Erase the entry matching the given index from the list of registered visuals
 259  *
 260  * @param[in] control The control
 261  * @param[in] index The Property index of the visual, used to reference visual
 262  */
 263 DALI_TOOLKIT_API void UnregisterVisual(Internal::Control& control, Dali::Property::Index index);
 264
 265 /**
 266  * @brief Retrieve the visual associated with the given property index.
 267  *
 268  * @param[in] control The control
 269  * @param[in] index The Property index of the visual.
 270  * @return The registered visual if exist, otherwise empty handle.
 271  * @note For managing object life-cycle, do not store the returned visual as a member which increments its reference count.
 272  */
 273 DALI_TOOLKIT_API Toolkit::Visual::Base GetVisual(const Internal::Control& control, Dali::Property::Index index);
 274
 275 /**
 276  * @brief Sets the given visual to be displayed or not when parent staged.
 277  *
 278  * @param[in] control The control
 279  * @param[in] index The Property index of the visual
 280  * @param[in] enable flag to set enabled or disabled.
 281  */
 282 DALI_TOOLKIT_API void EnableVisual(Internal::Control& control, Dali::Property::Index index, bool enable);
 283
 284 /**
 285  * @brief Queries if the given visual is to be displayed when parent staged.
 286  *
 287  * @param[in] control The control
 288  * @param[in] index The Property index of the visual
 289  * @return bool whether visual is enabled or not
 290  */
 291 DALI_TOOLKIT_API bool IsVisualEnabled(const Internal::Control& control, Dali::Property::Index index);
 292
 293 /**
 294  * @brief Add a transition effect on the control to the given animation
 295  *
 296  * Only generates an animator if the properties described in the transition
 297  * data are staged (e.g. the visual is Enabled and the control is on stage).
 298  * Otherwise the target values are stored, and will get set onto the properties
 299  * when the visual is next staged.
 300  *
 301  * @param[in] control The control
 302  * @param[in] animation The Animation to add valid transitions to
 303  * @param[in] transitionData The transition data describing the effect to create
 304  */
 305 DALI_TOOLKIT_API void AddTransitions(Internal::Control&             control,
 306                                      Dali::Animation                animation,
 307                                      const Toolkit::TransitionData& transitionData);
 308
 309 /**
 310  * @brief Create a transition effect on the control.
 311  *
 312  * Only generates an animation if the properties described in the transition
 313  * data are staged (e.g. the visual is Enabled and the control is on stage).
 314  * Otherwise the target values are stored, and will get set onto the properties
 315  * when the visual is next staged.
 316  *
 317  * @param[in] control The control
 318  * @param[in] transitionData The transition data describing the effect to create
 319  * @return A handle to an animation defined with the given effect, or an empty
 320  * handle if no properties match.
 321  */
 322 DALI_TOOLKIT_API Dali::Animation CreateTransition(Internal::Control&             control,
 323                                                   const Toolkit::TransitionData& transitionData);
 324
 325 /**
 326  * @brief Perform an action on a visual registered to this control.
 327  *
 328  * Visuals will have actions, this API is used to perform one of these actions with the given attributes.
 329  *
 330  * @param[in] control The control.
 331  * @param[in] visualIndex The Property index of the visual.
 332  * @param[in] actionId The action to perform.  See Visual to find supported actions.
 333  * @param[in] attributes Optional attributes for the action.
 334  */
 335 DALI_TOOLKIT_API void DoAction(Control& control, Dali::Property::Index visualIndex, Dali::Property::Index actionId, const Dali::Property::Value attributes);
 336
 337 /**
 338  * @brief Set input method context.
 339  *
 340  * @param[in] control The control.
 341  * @param[in] inputMethodContext The input method context.
 342  */
 343 DALI_TOOLKIT_API void SetInputMethodContext(Internal::Control& control, InputMethodContext& inputMethodContext);
 344
 345 /**
 346  * @brief Visual Event signal type
 347  */
 348 using VisualEventSignalType = Signal<void(Control, Dali::Property::Index, Dali::Property::Index)>;
 349
 350 /**
 351  * @brief This signal is emitted when a visual has an event to notify.
 352  *
 353  * A callback of the following type may be connected:
 354  * @code
 355  *   void YourCallbackName( Control control, Dali::Property::Index visualIndex, Dali::Property::Index signalId );
 356  * @endcode
 357  * @return The signal to connect to
 358  */
 359 DALI_TOOLKIT_API VisualEventSignalType& VisualEventSignal(Control control);
 360
 361 /**
 362  * @brief Retrieve the property object associated with the given property index and the visual property key.
 363  *
 364  * @param[in] control The control
 365  * @param[in] index The Property index of the visual.
 366  * @param[in] visualPropertyKey The key of the visual's property.
 367  * @return The Property object
 368  */
 369 DALI_TOOLKIT_API Dali::Property GetVisualProperty(Control control, Dali::Property::Index index, Dali::Property::Key visualPropertyKey);
 370
 371 /**
 372  * @brief The signal is emmited as a succession of "activate" signal send by accessibility client.
 373  * @return The signal to connect to
 374  */
 375 DALI_TOOLKIT_API AccessibilityActivateSignalType& AccessibilityActivateSignal(Toolkit::Control control);
 376
 377 /**
 378  * @brief The signal is emmited when text send via Dali::Accessibility::Bridge::Say
 379  * was placed in TTS queue but other text with higher priority prevented it from being read.
 380  *
 381  * @return The signal to connect to
 382  */
 383 DALI_TOOLKIT_API AccessibilityReadingSkippedSignalType& AccessibilityReadingSkippedSignal(Toolkit::Control control);
 384
 385 /**
 386  * @brief
 387  *
 388  * @return The signal to connect to
 389  */
 390 DALI_TOOLKIT_API AccessibilityReadingPausedSignalType& AccessibilityReadingPausedSignal(Toolkit::Control control);
 391
 392 /**
 393  * @brief
 394  *
 395  * @return The signal to connect to
 396  */
 397 DALI_TOOLKIT_API AccessibilityReadingResumedSignalType& AccessibilityReadingResumedSignal(Toolkit::Control control);
 398
 399 /**
 400  * @brief The signal is emmited when text send via Dali::Accessibility::Bridge::Say
 401  * was placed in TTS queue and reading was started but other text with higher priority cancelled it.
 402  *
 403  * @return The signal to connect to
 404  */
 405 DALI_TOOLKIT_API AccessibilityReadingCancelledSignalType& AccessibilityReadingCancelledSignal(Toolkit::Control control);
 406
 407 /**
 408  * @brief The signal is emmited when text send via Dali::Accessibility::Bridge::Say
 409  * was fully read by TTS module.
 410  *
 411  * @return The signal to connect to
 412  */
 413 DALI_TOOLKIT_API AccessibilityReadingStoppedSignalType& AccessibilityReadingStoppedSignal(Toolkit::Control control);
 414
 415 /**
 416  * @brief The signal is emmited when accessibility client asks for object's name.
 417  *
 418  * Connected callback should assign name to std::string call parameter.
 419  * Accessibility name can be stored in two ways:
 420  *     this signal,
 421  *     ACCESSIBILITY_NAME property,
 422  * Priority is as above. If none is used, default implementation is provided.
 423  * @return [description]
 424  */
 425 DALI_TOOLKIT_API AccessibilityGetNameSignalType& AccessibilityGetNameSignal(Toolkit::Control control);
 426
 427 /**
 428  * @brief The signal is emmited when accessibility client asks for object's description.
 429  *
 430  * Connected callback should assign description to std::string call parameter.
 431  * Accessibility description can be stored in two ways:
 432  *     this signal,
 433  *     ACCESSIBILITY_DESCRIPTION property,
 434  * Priority is as above. If none is used, default implementation is provided.
 435  * @return signal handler
 436  */
 437 DALI_TOOLKIT_API AccessibilityGetDescriptionSignalType& AccessibilityGetDescriptionSignal(Toolkit::Control control);
 438
 439 /**
 440  * @brief The signal is emitted when accessibility client call "DoGesture" method via IPC mechanism.
 441  *
 442  * This signal allows developers to serve incoming gesture in specific way.
 443  * @return signal handler
 444  */
 445 DALI_TOOLKIT_API AccessibilityDoGestureSignalType& AccessibilityDoGestureSignal(Toolkit::Control control);
 446
 447 /**
 448  * @brief The method allows connection with other actor with usage of concrete accessibility relation type.
 449  *
 450  * @param control object to append attribute to
 451  * @param destination Actor object
 452  * @param relation    enumerated value describing relation
 453  */
 454 DALI_TOOLKIT_API void AppendAccessibilityRelation(Dali::Actor control, Actor destination, Dali::Accessibility::RelationType relation);
 455
 456 /**
 457  * @brief The method allows removing relation
 458  *
 459  * @param control object to append attribute to
 460  * @param destination Actor object
 461  * @param relation    enumerated value describing relation
 462  */
 463 DALI_TOOLKIT_API void RemoveAccessibilityRelation(Dali::Actor control, Actor destination, Dali::Accessibility::RelationType relation);
 464
 465 /**
 466  * @brief The method returns collection accessibility addresses representing objects connected with current object
 467  *
 468  * @param control object to append attribute to
 469  * @return std::vector, where index is casted value of Accessibility::RelationType and value is std::vector of type Accessibility::Address
 470  */
 471 DALI_TOOLKIT_API std::vector<std::vector<Accessibility::Address>> GetAccessibilityRelations(Dali::Actor control);
 472
 473 /**
 474  * @brief The method removes all previously appended relations
 475  *
 476  * @param control object to append attribute to
 477  */
 478 DALI_TOOLKIT_API void ClearAccessibilityRelations(Dali::Actor control);
 479
 480 /**
 481  * @brief The method allows to add or modify value matched with given key.
 482  * Modification take place if key was previously set.
 483  *
 484  * @param control object to append attribute to
 485  * @param key   std::string value
 486  * @param value std::string value
 487  */
 488 DALI_TOOLKIT_API void AppendAccessibilityAttribute(Dali::Actor control, const std::string& key, const std::string value);
 489
 490 /**
 491  * @brief The method erases key with its value from accessibility attributes
 492  * @param control object to append attribute to
 493  * @param key std::string value
 494  */
 495 DALI_TOOLKIT_API void RemoveAccessibilityAttribute(Dali::Actor control, const std::string& key);
 496
 497 /**
 498  * @brief The method clears accessibility attributes
 499  *
 500  * @param control object to append attribute to
 501  */
 502 DALI_TOOLKIT_API void ClearAccessibilityAttributes(Dali::Actor control);
 503
 504 /**
 505  * @brief The method inserts reading information of an accessible object into attributes
 506  *
 507  * @param control object to append attribute to
 508  * @param types Reading information types
 509  */
 510 DALI_TOOLKIT_API void SetAccessibilityReadingInfoType(Dali::Actor control, const Dali::Accessibility::ReadingInfoTypes types);
 511
 512 /**
 513  * @brief The method returns reading information of an accessible object
 514  *
 515  * @param control object to append attribute to
 516  * @return Reading information types
 517  */
 518 DALI_TOOLKIT_API Dali::Accessibility::ReadingInfoTypes GetAccessibilityReadingInfoType(Dali::Actor control);
 519
 520 /**
 521  * @brief The method erases highlight.
 522  *
 523  * @param control object to append attribute to
 524  * @return bool value, false when it is not possible or something went wrong, at the other way true.
 525  */
 526 DALI_TOOLKIT_API bool ClearAccessibilityHighlight(Dali::Actor control);
 527
 528 /**
 529  * @brief The method grabs highlight.
 530  *
 531  * @param control object to append attribute to
 532  * @return bool value, false when it is not possible or something went wrong, at the other way true.
 533  */
 534 DALI_TOOLKIT_API bool GrabAccessibilityHighlight(Dali::Actor control);
 535
 536 /**
 537  * @brief The metod presents bitset of control's states.
 538  *
 539  * @param control object to append attribute to
 540  * @return Dali::Accessibility::States is vector of enumerated State.
 541  */
 542 DALI_TOOLKIT_API Dali::Accessibility::States GetAccessibilityStates(Dali::Actor control);
 543
 544 /**
 545  * @brief The method force sending notifications about current states to accessibility clients
 546  *
 547  * @param control object to append attribute to
 548  * @param states      mask with states expected to broadcast
 549  * @param doRecursive flag pointing if notifications of children's state would be sent
 550  */
 551 DALI_TOOLKIT_API void NotifyAccessibilityStateChange(Dali::Actor control, Dali::Accessibility::States states, bool doRecursive);
 552
 553 /**
 554  * The method allows to set specific constructor for creating accessibility structure
 555  *
 556  * Thank to this method hierarchy of accessibility objects can be based on internal hierarchy of Actors.
 557  * It prevents from necessity of keeping two trees synchronized.
 558  * The method should be called inside OnInitialize method of all classes inheriting from Control.
 559  *
 560  * Possible usage can be as follows:
 561  * @code
 562  *   SetAccessibilityConstructor( []( Dali::Actor actor ) {
 563        return std::unique_ptr< Dali::Accessibility::Accessible >(
 564        new AccessibleImpl( actor, Dali::Accessibility::Role::DIALOG, true ) );
 565       } );
 566   * @endcode
 567   *
 568   * param constructor callback creating Accessible object
 569   */
 570 DALI_TOOLKIT_API void SetAccessibilityConstructor(Dali::Actor control, std::function<std::unique_ptr<Dali::Accessibility::Accessible>(Dali::Actor)> constructor);
 571
 572 /**
 573  * Returns accessibility object bound to actor, if any
 574  *
 575  * This method won't bound new accessibility object. Use Dali::Accessibility::Accessible::Get in that case.
 576  */
 577 DALI_TOOLKIT_API Dali::Accessibility::Accessible* GetBoundAccessibilityObject(Dali::Actor control);
 578
 579 } // namespace DevelControl
 580
 581 } // namespace Toolkit
 582
 583 } // namespace Dali
 584
 585 #endif // DALI_TOOLKIT_CONTROL_DEVEL_H