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