dali/devel-api/adaptor-framework/accessibility-impl.h

   1 #ifndef DALI_INTERNAL_ATSPI_ACCESSIBILITY_IMPL_H
   2 #define DALI_INTERNAL_ATSPI_ACCESSIBILITY_IMPL_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
  21 // EXTERNAL INCLUDES
  22 #include <dali/public-api/actors/actor.h>
  23 #include <dali/public-api/math/rect.h>
  24 #include <dali/public-api/object/object-registry.h>
  25 #include <atomic>
  26 #include <bitset>
  27 #include <exception>
  28 #include <functional>
  29 #include <memory>
  30 #include <stdexcept>
  31 #include <string>
  32 #include <unordered_map>
  33 #include <unordered_set>
  34 #include <vector>
  35
  36 //INTERNAL INCLUDES
  37 #include <dali/devel-api/adaptor-framework/accessibility.h>
  38 #include <dali/integration-api/debug.h>
  39
  40 namespace Dali
  41 {
  42 namespace Accessibility
  43 {
  44 class DALI_ADAPTOR_API Accessible;
  45 class DALI_ADAPTOR_API Text;
  46 class DALI_ADAPTOR_API Value;
  47 class DALI_ADAPTOR_API Component;
  48 class DALI_ADAPTOR_API Collection;
  49 class DALI_ADAPTOR_API Action;
  50
  51 /**
  52  * @brief Base class for different accessibility bridges.
  53  *
  54  * Bridge is resposible for initializing and managing connection on accessibility bus.
  55  * Accessibility clients will not get any information about UI without initialized and upraised bridge.
  56  * Concrete implementation depends on the accessibility technology available on the platform.
  57  *
  58  * @note This class is singleton.
  59  */
  60 struct DALI_ADAPTOR_API Bridge
  61 {
  62   enum class ForceUpResult
  63   {
  64     JUST_STARTED,
  65     ALREADY_UP
  66   };
  67
  68   /**
  69    * @brief Destructor
  70    */
  71   virtual ~Bridge() = default;
  72
  73   /**
  74    * @brief Gets bus name which bridge is initialized on.
  75    */
  76   virtual const std::string& GetBusName() const = 0;
  77
  78   /**
  79    * @brief Registers top level window.
  80    *
  81    * Hierarchy of objects visible for accessibility clients is based on tree-like
  82    * structure created from Actors objects. This method allows to connect chosen
  83    * object as direct ancestor of application and therefore make it visible for
  84    * accessibility clients.
  85    *
  86    * @param[in] object The accessible object
  87    */
  88   virtual void AddTopLevelWindow(Accessible* object) = 0;
  89
  90   /**
  91    * @brief Removes top level window.
  92    *
  93    * Hierarchy of objects visible for accessibility clients is based on tree-like
  94    * structure created from Actors objects. This method removes previously added
  95    * window from visible accessibility objects.
  96    *
  97    * @param[in] object The accessible object
  98    */
  99   virtual void RemoveTopLevelWindow(Accessible* object) = 0;
 100
 101   /**
 102    * @brief Adds popup window.
 103    *
 104    * Hierarchy of objects visible for accessibility clients is based on tree-like
 105    * structure created from Actors objects. This method adds new popup to the tree.
 106    *
 107    * @param[in] object The accessible object
 108    */
 109   virtual void AddPopup(Accessible* object) = 0;
 110
 111   /**
 112    * @brief Removes popup window.
 113    *
 114    * Hierarchy of objects visible for accessibility clients is based on tree-like
 115    * structure created from Actors objects. This method removes previously added
 116    * popup window.
 117    *
 118    * @param[in] object The accessible object
 119    */
 120   virtual void RemovePopup(Accessible* object) = 0;
 121
 122   /**
 123    * @brief Sets name of current application which will be visible on accessibility bus.
 124    *
 125    * @param[in] name The application name
 126    */
 127   virtual void SetApplicationName(std::string name) = 0;
 128
 129   /**
 130    * @brief Gets object being root of accessibility tree.
 131    *
 132    * @return handler to accessibility object
 133    */
 134   virtual Accessible* GetApplication() const = 0;
 135
 136   /**
 137    * @brief Finds an object in accessibility tree.
 138    *
 139    * @param[in] path The path to object
 140    *
 141    * @return The handler to accessibility object
 142    */
 143   virtual Accessible* FindByPath(const std::string& path) const = 0;
 144
 145   /**
 146    * @brief Shows application on accessibility bus.
 147    */
 148   virtual void ApplicationShown() = 0;
 149
 150   /**
 151    * @brief Hides application on accessibility bus.
 152    */
 153   virtual void ApplicationHidden() = 0;
 154
 155   /**
 156    * @brief Initializes accessibility bus.
 157    */
 158   virtual void Initialize() = 0;
 159
 160   /**
 161    * @brief Terminates accessibility bus.
 162    */
 163   virtual void Terminate() = 0;
 164
 165   /**
 166    * @brief This method is called, when bridge is being activated.
 167    */
 168   virtual ForceUpResult ForceUp()
 169   {
 170     if(mData)
 171     {
 172       return ForceUpResult::ALREADY_UP;
 173     }
 174     mData = std::make_shared<Data>();
 175     mData->mBridge = this;
 176     return ForceUpResult::JUST_STARTED;
 177   }
 178
 179   /**
 180    * @brief This method is called, when bridge is being deactivated.
 181    */
 182   virtual void ForceDown() = 0;
 183
 184   /**
 185    * @brief Checks if bridge is activated or not.
 186    * @return True if brige is activated.
 187    */
 188   bool IsUp() const
 189   {
 190     return bool(mData);
 191   }
 192
 193   /**
 194    * @brief Emits cursor-moved event on at-spi bus.
 195    *
 196    * @param[in] obj The accessible object
 197    * @param[in] cursorPosition The new cursor position
 198    **/
 199   virtual void EmitCursorMoved(Accessible* obj, unsigned int cursorPosition) = 0;
 200
 201   /**
 202    * @brief Emits active-descendant-changed event on at-spi bus.
 203    *
 204    * @param[in] obj The accessible object
 205    * @param[in] child The child of the object
 206    **/
 207   virtual void EmitActiveDescendantChanged(Accessible* obj, Accessible* child) = 0;
 208
 209   /**
 210    * @brief Emits text-changed event on at-spi bus.
 211    *
 212    * @param[in] obj The accessible object
 213    * @param[in] state The changed state for text, such as Inserted or Deleted
 214    * @param[in] position The cursor position
 215    * @param[in] length The text length
 216    * @param[in] content The changed text
 217    **/
 218   virtual void EmitTextChanged(Accessible* obj, TextChangedState state, unsigned int position, unsigned int length, const std::string& content) = 0;
 219
 220   /**
 221    * @brief Emits state-changed event on at-spi bus.
 222    *
 223    * @param[in] obj The accessible object
 224    * @param[in] state The accessibility state (SHOWING, HIGHLIGHTED, etc)
 225    * @param[in] newValue Whether the state value is changed to new value or not.
 226    * @param[in] reserved Reserved. (Currently, this argument is not implemented in dali)
 227    **/
 228   virtual void EmitStateChanged(Accessible* obj, State state, int newValue, int reserved = 0) = 0;
 229
 230   /**
 231    * @brief Emits window event on at-spi bus.
 232    *
 233    * @param[in] obj The accessible object
 234    * @param[in] event The enumerated window event
 235    * @param[in] detail The additional parameter which interpretation depends on chosen event
 236    **/
 237   virtual void Emit(Accessible* obj, WindowEvent event, unsigned int detail = 0) = 0;
 238
 239   /**
 240    * @brief Emits property-changed event on at-spi bus.
 241    *
 242    * @param[in] obj The accessible object
 243    * @param[in] event Property changed event
 244    **/
 245   virtual void Emit(Accessible* obj, ObjectPropertyChangeEvent event) = 0;
 246
 247   /**
 248    * @brief Emits bounds-changed event on at-spi bus.
 249    *
 250    * @param[in] obj The accessible object
 251    * @param[in] rect The rectangle for changed bounds
 252    **/
 253   virtual void EmitBoundsChanged(Accessible* obj, Rect<> rect) = 0;
 254
 255   /**
 256    * @brief Emits key event on at-spi bus.
 257    *
 258    * Screen-reader might receive this event and reply, that given keycode is consumed. In that case
 259    * further processing of the keycode should be ignored.
 260    *
 261    * @param[in] type Key event type
 262    * @param[in] keyCode Key code
 263    * @param[in] keyName Key name
 264    * @param[in] timeStamp Time stamp
 265    * @param[in] isText Whether it's text or not
 266    * @return Whether this event is consumed or not
 267    **/
 268   virtual Consumed Emit(KeyEventType type, unsigned int keyCode, const std::string& keyName, unsigned int timeStamp, bool isText) = 0;
 269
 270   /**
 271    * @brief Reads given text by screen reader
 272    *
 273    * @param[in] text The text to read
 274    * @param[in] discardable If TRUE, reading can be discarded by subsequent reading requests,
 275    * if FALSE the reading must finish before next reading request can be started
 276    * @param[in] callback the callback function that is called on reading signals emitted
 277    * during processing of this reading request.
 278    * Callback can be one of the following signals:
 279    * ReadingCancelled, ReadingStopped, ReadingSkipped
 280    */
 281   virtual void Say(const std::string& text, bool discardable, std::function<void(std::string)> callback) = 0;
 282
 283   /**
 284    * @brief Force accessibility client to pause.
 285    */
 286   virtual void Pause() = 0;
 287
 288   /**
 289    * @brief Force accessibility client to resume.
 290    */
 291   virtual void Resume() = 0;
 292
 293   /**
 294    * @brief Cancels anything screen-reader is reading / has queued to read
 295    *
 296    * @param[in] alsoNonDiscardable whether to cancel non-discardable readings as well
 297    */
 298   virtual void StopReading(bool alsoNonDiscardable) = 0;
 299
 300   /**
 301    * @brief Suppresses reading of screen-reader
 302    *
 303    * @param[in] suppress whether to suppress reading of screen-reader
 304    */
 305   virtual void SuppressScreenReader(bool suppress) = 0;
 306
 307   /**
 308    * @brief Gets screen reader status.
 309    *
 310    * @return True if screen reader is enabled
 311    */
 312   virtual bool GetScreenReaderEnabled() = 0;
 313
 314   /**
 315    * @brief Gets ATSPI status.
 316    *
 317    * @return True if ATSPI is enabled
 318    */
 319   virtual bool IsEnabled() = 0;
 320
 321   /**
 322    * @brief Returns instance of bridge singleton object.
 323    *
 324    * @return The current bridge object
 325    **/
 326   static Bridge* GetCurrentBridge();
 327
 328   /**
 329    * @brief Blocks auto-initialization of AT-SPI bridge
 330    *
 331    * Use this only if your application starts before DBus does, and call it early in main()
 332    * (before GetCurrentBridge() is called by anyone). GetCurrentBridge() will then return an
 333    * instance of DummyBridge.
 334    *
 335    * When DBus is ready, call EnableAutoInit(). Please note that GetCurrentBridge() may still
 336    * return an instance of DummyBridge if AT-SPI was disabled at compile time or using an
 337    * environment variable, or if creating the real bridge failed.
 338    *
 339    * @see Dali::Accessibility::DummyBridge
 340    * @see Dali::Accessibility::Bridge::EnableAutoInit
 341    */
 342   static void DisableAutoInit();
 343
 344   /**
 345    * @brief Re-enables auto-initialization of AT-SPI bridge
 346    *
 347    * Normal applications do not have to call this function. GetCurrentBridge() tries to
 348    * initialize the AT-SPI bridge when it is called for the first time.
 349    *
 350    * @see Dali::Accessibility::Bridge::DisableAutoInit
 351    * @see Dali::Accessibility::Bridge::AddTopLevelWindow
 352    * @see Dali::Accessibility::Bridge::SetApplicationName
 353    */
 354   static void EnableAutoInit();
 355
 356 protected:
 357   struct Data
 358   {
 359     std::unordered_set<Accessible*> mKnownObjects;
 360     std::string                     mBusName;
 361     Bridge*                         mBridge = nullptr;
 362     Actor                           mHighlightActor;
 363     Actor                           mCurrentlyHighlightedActor;
 364   };
 365   std::shared_ptr<Data> mData;
 366   friend class Accessible;
 367
 368   enum class AutoInitState
 369   {
 370     DISABLED,
 371     ENABLED
 372   };
 373
 374   inline static AutoInitState autoInitState = AutoInitState::ENABLED;
 375
 376   /**
 377    * @brief Registers accessible object to be known in bridge object.
 378    *
 379    * Bridge must known about all currently alive accessible objects, as some requst
 380    * might come and object will be identified by number id (it's memory address).
 381    * To avoid memory corruption number id is checked against set of known objects.
 382    *
 383    * @param[in] object The accessible object
 384    **/
 385   void RegisterOnBridge(Accessible* object);
 386
 387   /**
 388    * @brief Tells bridge, that given object is considered root (doesn't have any parents).
 389    *
 390    * All root objects will have the same parent - application object. Application object
 391    * is controlled by bridge and private.
 392    *
 393    * @param[in] owner The accessible object
 394    **/
 395   void SetIsOnRootLevel(Accessible* owner);
 396 };
 397
 398 /**
 399  * @brief Checks if ATSPI is activated or not.
 400  * @return True if ATSPI is activated.
 401  */
 402 inline bool IsUp()
 403 {
 404   if(Bridge::GetCurrentBridge() == nullptr)
 405   {
 406     return false;
 407   }
 408
 409   if(Bridge::GetCurrentBridge()->IsEnabled() == false)
 410   {
 411     return false;
 412   }
 413
 414   return Bridge::GetCurrentBridge()->IsUp();
 415 }
 416
 417 /**
 418  * @brief Basic interface implemented by all accessibility objects.
 419  */
 420 class Accessible
 421 {
 422 public:
 423   virtual ~Accessible();
 424
 425   using utf8_t = unsigned char;
 426
 427   /**
 428    * @brief Calculates and finds word boundaries in given utf8 text.
 429    *
 430    * @param[in] string The source text to find
 431    * @param[in] length The length of text to find
 432    * @param[in] language The language to use
 433    * @param[out] breaks The word boundaries in given text
 434    *
 435    * @note Word boundaries are returned as non-zero values in table breaks, which must be of size at least length.
 436    */
 437   void FindWordSeparationsUtf8(const utf8_t* string, size_t length, const char* language, char* breaks);
 438
 439   /**
 440    * @brief Calculates and finds line boundaries in given utf8 text.
 441    *
 442    * @param[in] string The source text to find
 443    * @param[in] length The length of text to find
 444    * @param[in] language The language to use
 445    * @param[out] breaks The line boundaries in given text
 446    *
 447    * @note Line boundaries are returned as non-zero values in table breaks, which must be of size at least length.
 448    */
 449   void FindLineSeparationsUtf8(const utf8_t* string, size_t length, const char* language, char* breaks);
 450
 451   /**
 452    * @brief Helper function for emiting active-descendant-changed event.
 453    *
 454    * @param[in] obj The accessible object
 455    * @param[in] child The child of the object
 456    */
 457   void EmitActiveDescendantChanged(Accessible* obj, Accessible* child);
 458
 459   /**
 460    * @brief Helper function for emiting state-changed event.
 461    *
 462    * @param[in] state The accessibility state (SHOWING, HIGHLIGHTED, etc)
 463    * @param[in] newValue Whether the state value is changed to new value or not.
 464    * @param[in] reserved Reserved. (TODO : Currently, this argument is not implemented in dali)
 465    *
 466    * @note The second argument determines which value is depending on State.
 467    * For instance, if the state is PRESSED, newValue means isPressed or isSelected.
 468    * If the state is SHOWING, newValue means isShowing.
 469    */
 470   void EmitStateChanged(State state, int newValue, int reserved = 0);
 471
 472   /**
 473    * @brief Helper function for emiting bounds-changed event.
 474    *
 475    * @param rect The rectangle for changed bounds
 476    */
 477   void EmitBoundsChanged(Rect<> rect);
 478
 479   /**
 480    * @brief Emits "showing" event.
 481    * The method informs accessibility clients about "showing" state.
 482    *
 483    * @param[in] isShowing The flag pointing if object is showing
 484    */
 485   void EmitShowing(bool isShowing);
 486
 487   /**
 488    * @brief Emits "visible" event.
 489    * The method informs accessibility clients about "visible" state.
 490    *
 491    * @param[in] isVisible The flag pointing if object is visible
 492    */
 493   void EmitVisible(bool isVisible);
 494
 495   /**
 496    * @brief Emits "highlighted" event.
 497    * The method informs accessibility clients about "highlighted" state.
 498    *
 499    * @param[in] isHighlighted The flag pointing if object is highlighted
 500    */
 501   void EmitHighlighted(bool isHighlighted);
 502
 503   /**
 504    * @brief Emits "focused" event.
 505    * The method informs accessibility clients about "focused" state.
 506    *
 507    * @param[in] isFocused The flag pointing if object is focused
 508    */
 509   void EmitFocused(bool isFocused);
 510
 511   /**
 512    * @brief Emits "text inserted" event.
 513    *
 514    * @param[in] position The cursor position
 515    * @param[in] length The text length
 516    * @param[in] content The inserted text
 517    */
 518   void EmitTextInserted(unsigned int position, unsigned int length, const std::string& content);
 519
 520   /**
 521    * @brief Emits "text deleted" event.
 522    *
 523    * @param[in] position The cursor position
 524    * @param[in] length The text length
 525    * @param[in] content The deleted text
 526    */
 527   void EmitTextDeleted(unsigned int position, unsigned int length, const std::string& content);
 528
 529   /**
 530    * @brief Emits "cursor moved" event.
 531    *
 532    * @param[in] cursorPosition The new cursor position
 533    */
 534   void EmitTextCursorMoved(unsigned int cursorPosition);
 535
 536   /**
 537    * @brief Emits "highlighted" event.
 538    *
 539    * @param[in] event The enumerated window event
 540    * @param[in] detail The additional parameter which interpretation depends on chosen event
 541    */
 542   void Emit(WindowEvent event, unsigned int detail = 0);
 543
 544   /**
 545    * @brief Emits property-changed event.
 546    *
 547    * @param[in] event Property changed event
 548    **/
 549   void Emit(ObjectPropertyChangeEvent event);
 550
 551   /**
 552    * @brief Gets accessibility name.
 553    *
 554    * @return The string with name
 555    */
 556   virtual std::string GetName() = 0;
 557
 558   /**
 559    * @brief Gets accessibility description.
 560    *
 561    * @return The string with description
 562    */
 563   virtual std::string GetDescription() = 0;
 564
 565   /**
 566    * @brief Gets parent.
 567    *
 568    * @return The handler to accessibility object
 569    */
 570   virtual Accessible* GetParent() = 0;
 571
 572   /**
 573    * @brief Gets the number of children.
 574    *
 575    * @return The number of children
 576    */
 577   virtual size_t GetChildCount() = 0;
 578
 579   /**
 580    * @brief Gets collection with all children.
 581    *
 582    * @return The collection of accessibility objects
 583    */
 584   virtual std::vector<Accessible*> GetChildren();
 585
 586   /**
 587    * @brief Gets child of the index.
 588    *
 589    * @return The child object
 590    */
 591   virtual Accessible* GetChildAtIndex(size_t index) = 0;
 592
 593   /**
 594    * @brief Gets index that current object has in its parent's children collection.
 595    *
 596    * @return The index of the current object
 597    */
 598   virtual size_t GetIndexInParent() = 0;
 599
 600   /**
 601    * @brief Gets accessibility role.
 602    *
 603    * @return Role enumeration
 604    *
 605    * @see Dali::Accessibility::Role
 606    */
 607   virtual Role GetRole() = 0;
 608
 609   /**
 610    * @brief Gets name of accessibility role.
 611    *
 612    * @return The string with human readable role converted from enumeration
 613    *
 614    * @see Dali::Accessibility::Role
 615    * @see Accessibility::Accessible::GetRole
 616    */
 617   virtual std::string GetRoleName();
 618
 619   /**
 620    * @brief Gets localized name of accessibility role.
 621    *
 622    * @return The string with human readable role translated according to current
 623    * translation domain
 624    *
 625    * @see Dali::Accessibility::Role
 626    * @see Accessibility::Accessible::GetRole
 627    * @see Accessibility::Accessible::GetRoleName
 628    *
 629    * @note translation is not supported in this version
 630    */
 631   virtual std::string GetLocalizedRoleName();
 632
 633   /**
 634    * @brief Gets accessibility states.
 635    *
 636    * @return The collection of states
 637    *
 638    * @note States class is instatation of ArrayBitset template class
 639    *
 640    * @see Dali::Accessibility::State
 641    * @see Dali::Accessibility::ArrayBitset
 642    */
 643   virtual States GetStates() = 0;
 644
 645   /**
 646    * @brief Gets accessibility attributes.
 647    *
 648    * @return The map of attributes and their values
 649    */
 650   virtual Attributes GetAttributes() = 0;
 651
 652   /**
 653    * @brief Checks if this is proxy.
 654    *
 655    * @return True if this is proxy
 656    */
 657   virtual bool IsProxy();
 658
 659   /**
 660    * @brief Gets unique address on accessibility bus.
 661    *
 662    * @return The Address class containing address
 663    *
 664    * @see Dali::Accessibility::Address
 665    */
 666   virtual Address GetAddress();
 667
 668   /**
 669    * @brief Gets accessibility object, which is "default label" for this object.
 670    *
 671    * @return The Accessible object
 672    */
 673   virtual Accessible* GetDefaultLabel();
 674
 675   /**
 676    * @brief Deputes an object to perform provided gesture.
 677    *
 678    * @param[in] gestureInfo The structure describing the gesture
 679    *
 680    * @return true on success, false otherwise
 681    *
 682    * @see Dali::Accessibility::GestureInfo
 683    */
 684   virtual bool DoGesture(const GestureInfo& gestureInfo) = 0;
 685
 686   /**
 687    * @brief Re-emits selected states of an Accessibility Object.
 688    *
 689    * @param[in] states The chosen states to re-emit
 690    * @param[in] isRecursive If true, all children of the Accessibility object will also re-emit the states
 691    */
 692   void NotifyAccessibilityStateChange(Dali::Accessibility::States states, bool isRecursive);
 693
 694   /**
 695    * @brief Gets information about current object and all relations that connects
 696    * it with other accessibility objects.
 697    *
 698    * @return The iterable collection of Relation objects
 699    *
 700    * @see Dali::Accessibility::Relation
 701    */
 702   virtual std::vector<Relation> GetRelationSet() = 0;
 703
 704   /**
 705    * @brief Gets all implemented interfaces.
 706    *
 707    * @return The collection of strings with implemented interfaces
 708    */
 709   std::vector<std::string> GetInterfaces();
 710
 711   /**
 712    * @brief Checks if object is on root level.
 713    *
 714    * @return Whether object is on root level or not
 715    */
 716   bool IsOnRootLevel() const
 717   {
 718     return mIsOnRootLevel;
 719   }
 720
 721   /**
 722    * @brief The method registers functor resposible for converting Actor into Accessible.
 723    * @param functor The returning Accessible handle from Actor object
 724    */
 725   static void RegisterControlAccessibilityGetter(std::function<Accessible*(Dali::Actor)> functor);
 726
 727   /**
 728    * @brief Acquires Accessible object from Actor object.
 729    *
 730    * @param[in] actor Actor object
 731    * @param[in] isRoot True, if it's top level object (window)
 732    *
 733    * @return The handle to Accessible object
 734    */
 735   static Accessible* Get(Dali::Actor actor, bool isRoot = false);
 736
 737 protected:
 738   Accessible();
 739   Accessible(const Accessible&)         = delete;
 740   Accessible(Accessible&&)              = delete;
 741   Accessible&                   operator=(const Accessible&) = delete;
 742   Accessible&                   operator=(Accessible&&) = delete;
 743   std::shared_ptr<Bridge::Data> GetBridgeData();
 744
 745 public:
 746   /**
 747    * @brief Gets the highlight actor.
 748    *
 749    * This method is to get the highlight itself.
 750    * @return The highlight actor
 751    */
 752   static Dali::Actor GetHighlightActor();
 753
 754   /**
 755    * @brief Sets the highlight actor.
 756    *
 757    * This method is to set the highlight itself.
 758    * @param[in] actor The highlight actor
 759    */
 760   static void SetHighlightActor(Dali::Actor actor);
 761
 762   /**
 763    * @brief Gets the currently highlighted actor.
 764    *
 765    * @return The current highlighted actor
 766    */
 767   static Dali::Actor GetCurrentlyHighlightedActor();
 768
 769   /**
 770    * @brief Sets currently highlighted actor.
 771    *
 772    * @param[in] actor The highlight actor
 773    */
 774   static void SetCurrentlyHighlightedActor(Dali::Actor actor);
 775
 776   /**
 777    * @brief Sets ObjectRegistry.
 778    *
 779    * @param[in] registry ObjectRegistry instance
 780    */
 781   static void SetObjectRegistry(ObjectRegistry registry);
 782
 783 private:
 784   friend class Bridge;
 785
 786   std::weak_ptr<Bridge::Data> mBridgeData;
 787   bool                        mIsOnRootLevel = false;
 788 };
 789
 790 /**
 791  * @brief Interface enabling to perform provided actions.
 792  */
 793 class Action : public virtual Accessible
 794 {
 795 public:
 796   /**
 797    * @brief Gets name of action with given index.
 798    *
 799    * @param[in] index The index of action
 800    *
 801    * @return The string with name of action
 802    */
 803   virtual std::string GetActionName(size_t index) = 0;
 804
 805   /**
 806    * @brief Gets translated name of action with given index.
 807    *
 808    * @param[in] index The index of action
 809    *
 810    * @return The string with name of action translated according to current translation domain
 811    *
 812    * @note The translation is not supported in this version
 813    */
 814   virtual std::string GetLocalizedActionName(size_t index) = 0;
 815
 816   /**
 817    * @brief Gets description of action with given index.
 818    *
 819    * @param[in] index The index of action
 820    *
 821    * @return The string with description of action
 822    */
 823   virtual std::string GetActionDescription(size_t index) = 0;
 824
 825   /**
 826    * @brief Gets key code binded to action with given index.
 827    *
 828    * @param[in] index The index of action
 829    *
 830    * @return The string with key name
 831    */
 832   virtual std::string GetActionKeyBinding(size_t index) = 0;
 833
 834   /**
 835    * @brief Gets number of provided actions.
 836    *
 837    * @return The number of actions
 838    */
 839   virtual size_t GetActionCount() = 0;
 840
 841   /**
 842    * @brief Performs an action with given index.
 843    *
 844    * @param index The index of action
 845    *
 846    * @return true on success, false otherwise
 847    */
 848   virtual bool DoAction(size_t index) = 0;
 849
 850   /**
 851    * @brief Performs an action with given name.
 852    *
 853    * @param name The name of action
 854    *
 855    * @return true on success, false otherwise
 856    */
 857   virtual bool DoAction(const std::string& name) = 0;
 858 };
 859
 860 /**
 861  * @brief Interface enabling advanced quering of accessibility objects.
 862  *
 863  * @note since all mathods can be implemented inside bridge,
 864  * none methods have to be overrided
 865  */
 866 class Collection : public virtual Accessible
 867 {
 868 public:
 869 };
 870
 871 /**
 872  * @brief Interface representing objects having screen coordinates.
 873  */
 874 class Component : public virtual Accessible
 875 {
 876 public:
 877   /**
 878    * @brief Gets rectangle describing size.
 879    *
 880    * @param[in] type The enumeration with type of coordinate systems
 881    *
 882    * @return Rect<> object
 883    *
 884    * @see Dali::Rect
 885    */
 886   virtual Rect<> GetExtents(CoordinateType type) = 0;
 887
 888   /**
 889    * @brief Gets layer current object is localized on.
 890    *
 891    * @return The enumeration pointing layer
 892    *
 893    * @see Dali::Accessibility::ComponentLayer
 894    */
 895   virtual ComponentLayer GetLayer() = 0;
 896
 897   /**
 898    * @brief Gets value of z-order.
 899    *
 900    * @return The value of z-order
 901    * @remarks MDI means "Multi Document Interface" (https://en.wikipedia.org/wiki/Multiple-document_interface)
 902    * which in short means that many stacked windows can be displayed within a single application.
 903    * In such model, the concept of z-order of UI element became important to deal with element overlapping.
 904    */
 905   virtual int16_t GetMdiZOrder() = 0;
 906
 907   /**
 908    * @brief Sets current object as "focused".
 909    *
 910    * @return true on success, false otherwise
 911    */
 912   virtual bool GrabFocus() = 0;
 913
 914   /**
 915    * @brief Gets value of alpha channel.
 916    *
 917    * @return The alpha channel value in range [0.0, 1.0]
 918    */
 919   virtual double GetAlpha() = 0;
 920
 921   /**
 922    * @brief Sets current object as "highlighted".
 923    *
 924    * The method assings "highlighted" state, simultaneously removing it
 925    * from currently highlighted object.
 926    *
 927    * @return true on success, false otherwise
 928    */
 929   virtual bool GrabHighlight() = 0;
 930
 931   /**
 932    * @brief Sets current object as "unhighlighted".
 933    *
 934    * The method removes "highlighted" state from object.
 935    *
 936    * @return true on success, false otherwise
 937    *
 938    * @see Dali:Accessibility::State
 939    */
 940   virtual bool ClearHighlight() = 0;
 941
 942   /**
 943    * @brief Checks whether object can be scrolled.
 944    *
 945    * @return true if object is scrollable, false otherwise
 946    *
 947    * @see Dali:Accessibility::State
 948    */
 949   virtual bool IsScrollable();
 950
 951   /**
 952    * @brief Gets Accessible object containing given point.
 953    *
 954    * @param[in] point The two-dimensional point
 955    * @param[in] type The enumeration with type of coordinate system
 956    *
 957    * @return The handle to last child of current object which contains given point
 958    *
 959    * @see Dali::Accessibility::Point
 960    */
 961   virtual Accessible* GetAccessibleAtPoint(Point point, CoordinateType type);
 962
 963   /**
 964    * @brief Checks if current object contains given point.
 965    *
 966    * @param[in] point The two-dimensional point
 967    * @param[in] type The enumeration with type of coordinate system
 968    *
 969    * @return True if accessible contains in point, otherwise false.
 970    *
 971    * @remarks This method is `Contains` in DBus method.
 972    * @see Dali::Accessibility::Point
 973    */
 974   virtual bool IsAccessibleContainedAtPoint(Point point, CoordinateType type);
 975 };
 976
 977 /**
 978  * @brief Interface representing objects which can store numeric value.
 979  */
 980 class Value : public virtual Accessible
 981 {
 982 public:
 983   /**
 984    * @brief Gets the lowest possible value.
 985    *
 986    * @return The minimum value
 987   */
 988   virtual double GetMinimum() = 0;
 989
 990   /**
 991    * @brief Gets the current value.
 992    *
 993    * @return The current value
 994   */
 995   virtual double GetCurrent() = 0;
 996
 997   /**
 998    * @brief Gets the highest possible value.
 999    *
1000    * @return The highest value.
1001   */
1002   virtual double GetMaximum() = 0;
1003
1004   /**
1005    * @brief Sets the current value.
1006    *
1007    * @param[in] value The current value to set
1008    *
1009    * @return true if value could have been assigned, false otherwise
1010   */
1011   virtual bool SetCurrent(double value) = 0;
1012
1013   /**
1014    * @brief Gets the lowest increment that can be distinguished.
1015    *
1016    * @return The lowest increment
1017   */
1018   virtual double GetMinimumIncrement() = 0;
1019 };
1020
1021 /**
1022  * @brief Interface representing objects which can store immutable texts.
1023  *
1024  * @see Dali::Accessibility::EditableText
1025  */
1026 class DALI_ADAPTOR_API Text : public virtual Accessible
1027 {
1028 public:
1029   /**
1030    * @brief Gets stored text in given range.
1031    *
1032    * @param[in] startOffset The index of first character
1033    * @param[in] endOffset The index of first character after the last one expected
1034    *
1035    * @return The substring of stored text
1036    */
1037   virtual std::string GetText(size_t startOffset, size_t endOffset) = 0;
1038
1039   /**
1040    * @brief Gets number of all stored characters.
1041    *
1042    * @return The number of characters
1043    * @remarks This method is `CharacterCount` in DBus method.
1044    */
1045   virtual size_t GetCharacterCount() = 0;
1046
1047   /**
1048    * @brief Gets the cursor offset.
1049    *
1050    * @return Value of cursor offset
1051    * @remarks This method is `CaretOffset` in DBus method.
1052    */
1053   virtual size_t GetCursorOffset() = 0;
1054
1055   /**
1056    * @brief Sets the cursor offset.
1057    *
1058    * @param[in] offset Cursor offset
1059    *
1060    * @return True if successful
1061    * @remarks This method is `SetCaretOffset` in DBus method.
1062    */
1063   virtual bool SetCursorOffset(size_t offset) = 0;
1064
1065   /**
1066    * @brief Gets substring of stored text truncated in concrete gradation.
1067    *
1068    * @param[in] offset The position in stored text
1069    * @param[in] boundary The enumeration describing text gradation
1070    *
1071    * @return Range structure containing acquired text and offsets in original string
1072    *
1073    * @see Dali::Accessibility::Range
1074    */
1075   virtual Range GetTextAtOffset(size_t offset, TextBoundary boundary) = 0;
1076
1077   /**
1078    * @brief Gets selected text.
1079    *
1080    * @param[in] selectionIndex The selection index
1081    * @note Currently only one selection (i.e. with index = 0) is supported
1082    *
1083    * @return Range structure containing acquired text and offsets in original string
1084    *
1085    * @remarks This method is `GetSelection` in DBus method.
1086    * @see Dali::Accessibility::Range
1087    */
1088   virtual Range GetRangeOfSelection(size_t selectionIndex) = 0;
1089
1090   /**
1091    * @brief Removes the whole selection.
1092    *
1093    * @param[in] selectionIndex The selection index
1094    * @note Currently only one selection (i.e. with index = 0) is supported
1095    *
1096    * @return bool on success, false otherwise
1097    */
1098   virtual bool RemoveSelection(size_t selectionIndex) = 0;
1099
1100   /**
1101    * @brief Sets selected text.
1102    *
1103    * @param[in] selectionIndex The selection index
1104    * @param[in] startOffset The index of first character
1105    * @param[in] endOffset The index of first character after the last one expected
1106    *
1107    * @note Currently only one selection (i.e. with index = 0) is supported
1108    *
1109    * @return true on success, false otherwise
1110    * @remarks This method is `SetSelection` in DBus method.
1111    */
1112   virtual bool SetRangeOfSelection(size_t selectionIndex, size_t startOffset, size_t endOffset) = 0;
1113 };
1114
1115 /**
1116  * @brief Interface representing objects which can store editable texts.
1117  *
1118  * @note Paste method is entirely implemented inside bridge
1119  *
1120  * @see Dali::Accessibility::EditableText
1121  */
1122 class DALI_ADAPTOR_API EditableText : public virtual Accessible
1123 {
1124 public:
1125   /**
1126    * @brief Copies text in range to system clipboard.
1127    *
1128    * @param[in] startPosition The index of first character
1129    * @param[in] endPosition The index of first character after the last one expected
1130    *
1131    * @return true on success, false otherwise
1132    */
1133   virtual bool CopyText(size_t startPosition, size_t endPosition) = 0;
1134
1135   /**
1136    * @brief Cuts text in range to system clipboard.
1137    *
1138    * @param[in] startPosition The index of first character
1139    * @param[in] endPosition The index of first character after the last one expected
1140    *
1141    * @return true on success, false otherwise
1142    */
1143   virtual bool CutText(size_t startPosition, size_t endPosition) = 0;
1144
1145   /**
1146    * @brief Deletes text in range.
1147    *
1148    * @param[in] startPosition The index of first character
1149    * @param[in] endPosition The index of first character after the last one expected
1150    *
1151    * @return true on success, false otherwise
1152    */
1153   virtual bool DeleteText(size_t startPosition, size_t endPosition) = 0;
1154
1155   /**
1156    * @brief Inserts text at startPosition.
1157    *
1158    * @param[in] startPosition The index of first character
1159    * @param[in] text The text content
1160    *
1161    * @return true on success, false otherwise
1162    */
1163   virtual bool InsertText(size_t startPosition, std::string text) = 0;
1164
1165   /**
1166    * @brief Replaces text with content.
1167    *
1168    * @param[in] newContents The text content
1169    *
1170    * @return true on success, false otherwise
1171    */
1172   virtual bool SetTextContents(std::string newContents) = 0;
1173 };
1174
1175 /**
1176  * @brief Interface representing objects which can store a set of selected items.
1177  */
1178 class DALI_ADAPTOR_API Selection : public virtual Accessible
1179 {
1180 public:
1181   /**
1182    * @brief Gets the number of selected children.
1183    *
1184    * @return The number of selected children (zero if none)
1185    */
1186   virtual int GetSelectedChildrenCount() = 0;
1187
1188   /**
1189    * @brief Gets a specific selected child.
1190    *
1191    * @param selectedChildIndex The index of the selected child
1192    *
1193    * @note @p selectedChildIndex refers to the list of selected children,
1194    * not the list of all children
1195    *
1196    * @return The selected child or nullptr if index is invalid
1197    */
1198   virtual Accessible* GetSelectedChild(int selectedChildIndex) = 0;
1199
1200   /**
1201    * @brief Selects a child.
1202    *
1203    * @param childIndex The index of the child
1204    *
1205    * @return true on success, false otherwise
1206    */
1207   virtual bool SelectChild(int childIndex) = 0;
1208
1209   /**
1210    * @brief Deselects a selected child.
1211    *
1212    * @param selectedChildIndex The index of the selected child
1213    *
1214    * @note @p selectedChildIndex refers to the list of selected children,
1215    * not the list of all children
1216    *
1217    * @return true on success, false otherwise
1218    *
1219    * @see Dali::Accessibility::Selection::DeselectChild
1220    */
1221   virtual bool DeselectSelectedChild(int selectedChildIndex) = 0;
1222
1223   /**
1224    * @brief Checks whether a child is selected.
1225    *
1226    * @param childIndex The index of the child
1227    *
1228    * @return true if given child is selected, false otherwise
1229    */
1230   virtual bool IsChildSelected(int childIndex) = 0;
1231
1232   /**
1233    * @brief Selects all children.
1234    *
1235    * @return true on success, false otherwise
1236    */
1237   virtual bool SelectAll() = 0;
1238
1239   /**
1240    * @brief Deselects all children.
1241    *
1242    * @return true on success, false otherwise
1243    */
1244   virtual bool ClearSelection() = 0;
1245
1246   /**
1247    * @brief Deselects a child.
1248    *
1249    * @param childIndex The index of the child.
1250    *
1251    * @return true on success, false otherwise
1252    *
1253    * @see Dali::Accessibility::Selection::DeselectSelectedChild
1254    */
1255   virtual bool DeselectChild(int childIndex) = 0;
1256 };
1257
1258 /**
1259  * @brief The minimalistic, always empty Accessible object with settable address.
1260  *
1261  * For those situations, where you want to return address in different bridge
1262  * (embedding for example), but the object itself ain't planned to be used otherwise.
1263  * This object has null parent, no children, empty name and so on
1264  */
1265 class DALI_ADAPTOR_API EmptyAccessibleWithAddress : public virtual Accessible
1266 {
1267 public:
1268   EmptyAccessibleWithAddress() = default;
1269
1270   EmptyAccessibleWithAddress(Address address)
1271   : mAddress(std::move(address))
1272   {
1273   }
1274
1275   void SetAddress(Address address)
1276   {
1277     this->mAddress = std::move(address);
1278   }
1279
1280   std::string GetName() override
1281   {
1282     return "";
1283   }
1284
1285   std::string GetDescription() override
1286   {
1287     return "";
1288   }
1289
1290   Accessible* GetParent() override
1291   {
1292     return nullptr;
1293   }
1294
1295   size_t GetChildCount() override
1296   {
1297     return 0;
1298   }
1299
1300   std::vector<Accessible*> GetChildren() override
1301   {
1302     return {};
1303   }
1304
1305   Accessible* GetChildAtIndex(size_t index) override
1306   {
1307     throw std::domain_error{"out of bounds index (" + std::to_string(index) + ") - no children"};
1308   }
1309
1310   size_t GetIndexInParent() override
1311   {
1312     return static_cast<size_t>(-1);
1313   }
1314
1315   Role GetRole() override
1316   {
1317     return {};
1318   }
1319
1320   std::string GetRoleName() override;
1321
1322   States GetStates() override
1323   {
1324     return {};
1325   }
1326
1327   Attributes GetAttributes() override
1328   {
1329     return {};
1330   }
1331
1332   Address GetAddress() override
1333   {
1334     return mAddress;
1335   }
1336
1337   bool DoGesture(const GestureInfo& gestureInfo) override
1338   {
1339     return false;
1340   }
1341
1342   std::vector<Relation> GetRelationSet() override
1343   {
1344     return {};
1345   }
1346
1347 private:
1348   Address mAddress;
1349 };
1350
1351 } // namespace Accessibility
1352 } // namespace Dali
1353
1354 #endif // DALI_INTERNAL_ATSPI_ACCESSIBILITY_IMPL_H