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

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