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