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