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