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 Get 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   virtual void AddTopLevelWindow(Accessible*) = 0;
  87
  88   /**
  89    * @brief Removes top level window
  90    *
  91    * Hierarchy of objects visible for accessibility clients is based on tree-like
  92    * structure created from Actors objects. This method removes previously added
  93    * window from visible accessibility objects.
  94    */
  95   virtual void RemoveTopLevelWindow(Accessible*) = 0;
  96
  97   /**
  98    * @brief Adds popup window
  99    *
 100    * Hierarchy of objects visible for accessibility clients is based on tree-like
 101    * structure created from Actors objects. This method adds new popup to the tree.
 102    */
 103   virtual void AddPopup(Accessible*) = 0;
 104
 105   /**
 106    * @brief Removes popup window
 107    *
 108    * Hierarchy of objects visible for accessibility clients is based on tree-like
 109    * structure created from Actors objects. This method removes previously added
 110    * popup window.
 111    */
 112   virtual void RemovePopup(Accessible*) = 0;
 113
 114   /**
 115    * @brief Set name of current application which will be visible on accessibility bus
 116    */
 117   virtual void SetApplicationName(std::string) = 0;
 118
 119   /**
 120    * @brief Get object being root of accessibility tree
 121    *
 122    * @return handler to accessibility object
 123    */
 124   virtual Accessible* GetApplication() const = 0;
 125
 126   /**
 127    * @brief Find an object in accessibility tree
 128    *
 129    * @param[in] s path to object
 130    *
 131    * @return handler to accessibility object
 132    */
 133   virtual Accessible* FindByPath(const std::string& s) const = 0;
 134
 135   /**
 136    * @brief Show application on accessibility bus
 137    */
 138   virtual void ApplicationShown() = 0;
 139
 140   /**
 141    * @brief Hide application on accessibility bus
 142    */
 143   virtual void ApplicationHidden() = 0;
 144
 145   /**
 146    * @brief Initialize accessibility bus
 147    */
 148   virtual void Initialize() = 0;
 149
 150   /**
 151    * @brief Terminate accessibility bus
 152    */
 153   virtual void Terminate() = 0;
 154
 155   /**
 156    * @brief This method is called, when bridge is being activated.
 157    */
 158   virtual ForceUpResult ForceUp()
 159   {
 160     if(data)
 161     {
 162       return ForceUpResult::ALREADY_UP;
 163     }
 164     data         = std::make_shared<Data>();
 165     data->bridge = this;
 166     return ForceUpResult::JUST_STARTED;
 167   }
 168
 169   /**
 170    * @brief This method is called, when bridge is being deactivated.
 171    */
 172   virtual void ForceDown() = 0;
 173
 174   /**
 175    * @brief Check if bridge is activated or not.
 176    * @return True if brige is activated.
 177    */
 178   bool IsUp() const
 179   {
 180     return bool(data);
 181   }
 182
 183   /**
 184    * @brief Emits caret-moved event on at-spi bus.
 185    **/
 186   virtual void EmitCaretMoved(Accessible* obj, unsigned int cursorPosition) = 0;
 187
 188   /**
 189    * @brief Emits active-descendant-changed event on at-spi bus.
 190    **/
 191   virtual void EmitActiveDescendantChanged(Accessible* obj, Accessible* child) = 0;
 192
 193   /**
 194    * @brief Emits text-changed event on at-spi bus.
 195    **/
 196   virtual void EmitTextChanged(Accessible* obj, TextChangedState state, unsigned int position, unsigned int length, const std::string& content) = 0;
 197
 198   /**
 199    * @brief Emits state-changed event on at-spi bus.
 200    **/
 201   virtual void EmitStateChanged(Accessible* obj, State state, int val1, int val2 = 0) = 0;
 202
 203   /**
 204    * @brief Emits window event on at-spi bus.
 205    **/
 206   virtual void Emit(Accessible* obj, WindowEvent we, unsigned int detail1 = 0) = 0;
 207
 208   /**
 209    * @brief Emits property-changed event on at-spi bus.
 210    **/
 211   virtual void Emit(Accessible* obj, ObjectPropertyChangeEvent event) = 0;
 212
 213   /**
 214    * @brief Emits bounds-changed event on at-spi bus.
 215    **/
 216   virtual void EmitBoundsChanged(Accessible* obj, Rect<> rect) = 0;
 217
 218   /**
 219    * @brief Emits key event on at-spi bus.
 220    *
 221    * Screen-reader might receive this event and reply, that given keycode is consumed. In that case
 222    * further processing of the keycode should be ignored.
 223    **/
 224   virtual Consumed Emit(KeyEventType type, unsigned int keyCode, const std::string& keyName, unsigned int timeStamp, bool isText) = 0;
 225
 226   /**
 227    * @brief Reads given text by screen reader
 228    *
 229    * @param text The text to read
 230    * @param discardable If TRUE, reading can be discarded by subsequent reading requests,
 231    * if FALSE the reading must finish before next reading request can be started
 232    * @param callback the callback function that is called on reading signals emitted
 233    * during processing of this reading request.
 234    * Callback can be one of the following signals:
 235    * ReadingCancelled, ReadingStopped, ReadingSkipped
 236    */
 237   virtual void Say(const std::string& text, bool discardable, std::function<void(std::string)> callback) = 0;
 238
 239   /**
 240    * @brief Force accessibility client to pause.
 241    */
 242   virtual void Pause() = 0;
 243
 244   /**
 245    * @brief Force accessibility client to resume.
 246    */
 247   virtual void Resume() = 0;
 248
 249   /**
 250    * @brief Cancels anything screen-reader is reading / has queued to read
 251    *
 252    * @param alsoNonDiscardable whether to cancel non-discardable readings as well
 253    */
 254   virtual void StopReading(bool alsoNonDiscardable) = 0;
 255
 256   /**
 257    * @brief Get screen reader status.
 258    */
 259   virtual bool GetScreenReaderEnabled() = 0;
 260
 261   /**
 262    * @brief Get ATSPI status.
 263    */
 264   virtual bool GetIsEnabled() = 0;
 265
 266   /**
 267    * @brief Returns instance of bridge singleton object.
 268    **/
 269   static Bridge* GetCurrentBridge();
 270
 271   /**
 272    * @brief Blocks auto-initialization of AT-SPI bridge
 273    *
 274    * Use this only if your application starts before DBus does, and call it early in main()
 275    * (before GetCurrentBridge() is called by anyone). GetCurrentBridge() will then return an
 276    * instance of DummyBridge.
 277    *
 278    * When DBus is ready, call EnableAutoInit(). Please note that GetCurrentBridge() may still
 279    * return an instance of DummyBridge if AT-SPI was disabled at compile time or using an
 280    * environment variable, or if creating the real bridge failed.
 281    *
 282    * @see Dali::Accessibility::DummyBridge
 283    * @see Dali::Accessibility::Bridge::EnableAutoInit
 284    */
 285   static void DisableAutoInit();
 286
 287   /**
 288    * @brief Re-enables auto-initialization of AT-SPI bridge
 289    *
 290    * @param topLevelWindow Accessible object for Scene::GetRootLayer()
 291    * @param applicationName Application name
 292    *
 293    * Normal applications do not have to call this function. GetCurrentBridge() tries to
 294    * initialize the AT-SPI bridge when it is called for the first time.
 295    *
 296    * @see Dali::Accessibility::Bridge::DisableAutoInit
 297    * @see Dali::Accessibility::Bridge::AddTopLevelWindow
 298    * @see Dali::Accessibility::Bridge::SetApplicationName
 299    */
 300   static void EnableAutoInit(Accessible* topLevelWindow, const std::string& applicationName);
 301
 302 protected:
 303   struct Data
 304   {
 305     std::unordered_set<Accessible*> knownObjects;
 306     std::string                     busName;
 307     Bridge*                         bridge = nullptr;
 308     Actor                           highlightActor, currentlyHighlightedActor;
 309   };
 310   std::shared_ptr<Data> data;
 311   friend class Accessible;
 312
 313   enum class AutoInitState
 314   {
 315     DISABLED,
 316     ENABLED
 317   };
 318   inline static AutoInitState autoInitState = AutoInitState::ENABLED;
 319
 320   /**
 321    * @brief Registers accessible object to be known in bridge object
 322    *
 323    * Bridge must known about all currently alive accessible objects, as some requst
 324    * might come and object will be identified by number id (it's memory address).
 325    * To avoid memory corruption number id is checked against set of known objects.
 326    **/
 327   void RegisterOnBridge(Accessible*);
 328
 329   /**
 330    * @brief Tells bridge, that given object is considered root (doesn't have any parents).
 331    *
 332    * All root objects will have the same parent - application object. Application object
 333    * is controlled by bridge and private.
 334    **/
 335   void SetIsOnRootLevel(Accessible*);
 336 };
 337
 338 /**
 339  * @brief Check if ATSPI is activated or not.
 340  * @return True if ATSPI is activated.
 341  */
 342 inline bool IsUp()
 343 {
 344   if(Bridge::GetCurrentBridge() == nullptr)
 345   {
 346     return false;
 347   }
 348   if(Bridge::GetCurrentBridge()->GetIsEnabled() == false)
 349   {
 350     return false;
 351   }
 352   return Bridge::GetCurrentBridge()->IsUp();
 353 }
 354
 355 /**
 356  * @brief Basic interface implemented by all accessibility objects
 357  */
 358 class Accessible
 359 {
 360 public:
 361   virtual ~Accessible();
 362
 363   using utf8_t = unsigned char;
 364
 365   /**
 366    * @brief Calculaties word boundaries in given utf8 text.
 367    *
 368    * s and length represents source text pointer and it's length respectively. langauge represents
 369    * language to use. Word boundaries are returned as non-zero values in table breaks, which
 370    * must be of size at least length.
 371    **/
 372   void FindWordSeparationsUtf8(const utf8_t* s, size_t length, const char* language, char* breaks);
 373
 374   /**
 375    * @brief Calculaties line boundaries in given utf8 text.
 376    *
 377    * s and length represents source text pointer and it's length respectively. langauge represents
 378    * language to use. Line boundaries are returned as non-zero values in table breaks, which
 379    * must be of size at least length.
 380    **/
 381   void FindLineSeparationsUtf8(const utf8_t* s, size_t length, const char* language, char* breaks);
 382
 383   /**
 384    * @brief Helper function for emiting active-descendant-changed event
 385    **/
 386   void EmitActiveDescendantChanged(Accessible* obj, Accessible* child);
 387
 388   /**
 389    * @brief Helper function for emiting state-changed event
 390    **/
 391   void EmitStateChanged(State state, int newValue1, int newValue2 = 0);
 392
 393   /**
 394    * @brief Helper function for emiting bounds-changed event
 395    **/
 396   void EmitBoundsChanged(Rect<> rect);
 397
 398   /**
 399    * @brief Emit "showing" event.
 400    * The method inform accessibility clients about "showing" state
 401    *
 402    * @param[in] showing flag pointing if object is showing
 403    */
 404   void EmitShowing(bool showing);
 405
 406   /**
 407    * @brief Emit "visible" event.
 408    * The method inform accessibility clients about "visible" state
 409    *
 410    * @param[in] visible flag pointing if object is visible
 411    */
 412   void EmitVisible(bool visible);
 413
 414   /**
 415    * @brief Emit "highlighted" event.
 416    * The method inform accessibility clients about "highlighted" state
 417    *
 418    * @param[in] set flag pointing if object is highlighted
 419    */
 420   void EmitHighlighted(bool set);
 421
 422   /**
 423    * @brief Emit "focused" event.
 424    * The method inform accessibility clients about "focused" state
 425    *
 426    * @param[in] set flag pointing if object is focused
 427    */
 428   void EmitFocused(bool set);
 429
 430   /**
 431    * @brief Emit "text inserted" event
 432    *
 433    * @param[in] position caret position
 434    * @param[in] length text length
 435    * @param[in] content inserted text
 436    */
 437   void EmitTextInserted(unsigned int position, unsigned int length, const std::string& content);
 438
 439   /**
 440    * @brief Emit "text deleted" event
 441    *
 442    * @param[in] position caret position
 443    * @param[in] length text length
 444    * @param[in] content deleted text
 445    */
 446   void EmitTextDeleted(unsigned int position, unsigned int length, const std::string& content);
 447
 448   /**
 449    * @brief Emit "caret moved" event
 450    *
 451    * @param[in] cursorPosition new caret position
 452    */
 453   void EmitTextCaretMoved(unsigned int cursorPosition);
 454
 455   /**
 456    * @brief Emit "highlighted" event
 457    *
 458    * @param[in] we enumerated window event
 459    * @param[in] detail1 additional parameter which interpretation depends on chosen event
 460    */
 461   void Emit(WindowEvent we, unsigned int detail1 = 0);
 462
 463   /**
 464    * @brief Emits property-changed event
 465    * @param[in] event Property changed event
 466    **/
 467   void Emit(ObjectPropertyChangeEvent event);
 468
 469   /**
 470    * @brief Get accessibility name
 471    *
 472    * @return string with name
 473    */
 474   virtual std::string GetName() = 0;
 475
 476   /**
 477    * @brief Get accessibility description
 478    *
 479    * @return string with description
 480    */
 481   virtual std::string GetDescription() = 0;
 482
 483   /**
 484    * @brief Get parent
 485    *
 486    * @return handler to accessibility object
 487    */
 488   virtual Accessible* GetParent() = 0;
 489
 490   /**
 491    * @brief Get count of children
 492    *
 493    * @return unsigned integer value
 494    */
 495   virtual size_t GetChildCount() = 0;
 496
 497   /**
 498    * @brief Get collection with all children
 499    *
 500    * @return collection of accessibility objects
 501    */
 502   virtual std::vector<Accessible*> GetChildren();
 503
 504   /**
 505    * @brief Get nth child
 506    *
 507    * @return accessibility object
 508    */
 509   virtual Accessible* GetChildAtIndex(size_t index) = 0;
 510
 511   /**
 512    * @brief Get index that current object has in its parent's children collection
 513    *
 514    * @return unsigned integer index
 515    */
 516   virtual size_t GetIndexInParent() = 0;
 517
 518   /**
 519    * @brief Get accessibility role
 520    *
 521    * @return Role enumeration
 522    *
 523    * @see Dali::Accessibility::Role
 524    */
 525   virtual Role GetRole() = 0;
 526
 527   /**
 528    * @brief Get name of accessibility role
 529    *
 530    * @return string with human readable role converted from enumeration
 531    *
 532    * @see Dali::Accessibility::Role
 533    * @see Accessibility::Accessible::GetRole
 534    */
 535   virtual std::string GetRoleName();
 536
 537   /**
 538    * @brief Get localized name of accessibility role
 539    *
 540    * @return string with human readable role translated according to current
 541    * translation domain
 542    *
 543    * @see Dali::Accessibility::Role
 544    * @see Accessibility::Accessible::GetRole
 545    * @see Accessibility::Accessible::GetRoleName
 546    *
 547    * @note translation is not supported in this version
 548    */
 549   virtual std::string GetLocalizedRoleName();
 550
 551   /**
 552    * @brief Get accessibility states
 553    *
 554    * @return collection of states
 555    *
 556    * @note States class is instatation of ArrayBitset template class
 557    *
 558    * @see Dali::Accessibility::State
 559    * @see Dali::Accessibility::ArrayBitset
 560    */
 561   virtual States GetStates() = 0;
 562
 563   /**
 564    * @brief Get accessibility attributes
 565    *
 566    * @return map of attributes and their values
 567    */
 568   virtual Attributes GetAttributes() = 0;
 569
 570   /**
 571    * @brief Check if this is proxy
 572    *
 573    * @return True if this is proxy
 574    */
 575   virtual bool IsProxy();
 576
 577   /**
 578    * @brief Get unique address on accessibility bus
 579    *
 580    * @return class containing address
 581    *
 582    * @see Dali::Accessibility::Address
 583    */
 584   virtual Address GetAddress();
 585
 586   /**
 587    * @brief Get accessibility object, which is "default label" for this object
 588    */
 589   virtual Accessible* GetDefaultLabel();
 590
 591   /**
 592    * @brief Depute an object to perform provided gesture
 593    *
 594    * @param[in] gestureInfo structure describing the gesture
 595    *
 596    * @return true on success, false otherwise
 597    *
 598    * @see Dali::Accessibility::GestureInfo
 599    */
 600   virtual bool DoGesture(const GestureInfo& gestureInfo) = 0;
 601
 602   /**
 603    * @brief Re-emits selected states of an Accessibility Object
 604    *
 605    * @param[in] states chosen states to re-emit
 606    * @param[in] doRecursive if true all children of the Accessibility Object will also re-emit the states
 607    */
 608   void NotifyAccessibilityStateChange(Dali::Accessibility::States states, bool doRecursive);
 609
 610   /**
 611    * @brief Get information about current object and all relations that connects
 612    * it with other accessibility objects
 613    *
 614    * @return iterable collection of Relation objects
 615    *
 616    * @see Dali::Accessibility::Relation
 617    */
 618   virtual std::vector<Relation> GetRelationSet() = 0;
 619
 620   /**
 621    * @brief Get all implemented interfaces
 622    *
 623    * @return collection of strings with implemented interfaces
 624    */
 625   std::vector<std::string> GetInterfaces();
 626
 627   /**
 628    * @brief Check if object is on root level
 629    */
 630   bool GetIsOnRootLevel() const
 631   {
 632     return isOnRootLevel;
 633   }
 634
 635   /**
 636    * @brief The method registers functor resposible for converting Actor into Accessible
 637    * @param functor returning Accessible handle from Actor object
 638    */
 639   static void RegisterControlAccessibilityGetter(std::function<Accessible*(Dali::Actor)> functor);
 640
 641   /**
 642    * @brief Acquire Accessible object from Actor object
 643    *
 644    * @param[in] actor Actor object
 645    * @param[in] root true, if it's top level object (window)
 646    *
 647    * @return handle to Accessible object
 648    */
 649   static Accessible* Get(Dali::Actor actor, bool root = false);
 650
 651 protected:
 652   Accessible();
 653   Accessible(const Accessible&)         = delete;
 654   Accessible(Accessible&&)              = delete;
 655   Accessible&                   operator=(const Accessible&) = delete;
 656   Accessible&                   operator=(Accessible&&) = delete;
 657   std::shared_ptr<Bridge::Data> GetBridgeData();
 658
 659 public:
 660   static Dali::Actor GetHighlightActor();
 661   static void        SetHighlightActor(Dali::Actor actor);
 662   static Dali::Actor GetCurrentlyHighlightedActor();
 663   static void        SetCurrentlyHighlightedActor(Dali::Actor);
 664   static void        SetObjectRegistry(ObjectRegistry registry);
 665
 666 private:
 667   friend class Bridge;
 668
 669   std::weak_ptr<Bridge::Data> bridgeData;
 670   bool                        isOnRootLevel = false;
 671 };
 672
 673 /**
 674  * @brief Interface enabling to perform provided actions
 675  */
 676 class Action : public virtual Accessible
 677 {
 678 public:
 679   /**
 680    * @brief Get name of action with given index
 681    *
 682    * @param[in] index index of action
 683    *
 684    * @return string with name of action
 685    */
 686   virtual std::string GetActionName(size_t index) = 0;
 687
 688   /**
 689    * @brief Get translated name of action with given index
 690    *
 691    * @param[in] index index of action
 692    *
 693    * @return string with name of action translated according to current translation domain
 694    *
 695    * @note translation is not supported in this version
 696    */
 697   virtual std::string GetLocalizedActionName(size_t index) = 0;
 698
 699   /**
 700    * @brief Get description of action with given index
 701    *
 702    * @param[in] index index of action
 703    *
 704    * @return string with description of action
 705    */
 706   virtual std::string GetActionDescription(size_t index) = 0;
 707
 708   /**
 709    * @brief Get key code binded to action with given index
 710    *
 711    * @param[in] index index of action
 712    *
 713    * @return string with key name
 714    */
 715   virtual std::string GetActionKeyBinding(size_t index) = 0;
 716
 717   /**
 718    * @brief Get number of provided actions
 719    *
 720    * @return unsigned integer with number of actions
 721    */
 722   virtual size_t GetActionCount() = 0;
 723
 724   /**
 725    * @brief Perform an action with given index
 726    *
 727    * @param index index of action
 728    *
 729    * @return true on success, false otherwise
 730    */
 731   virtual bool DoAction(size_t index) = 0;
 732
 733   /**
 734    * @brief Perform an action with given name
 735    *
 736    * @param name name of action
 737    *
 738    * @return true on success, false otherwise
 739    */
 740   virtual bool DoAction(const std::string& name) = 0;
 741 };
 742
 743 /**
 744  * @brief Interface enabling advanced quering of accessibility objects
 745  *
 746  * @note since all mathods can be implemented inside bridge,
 747  * none methods have to be overrided
 748  */
 749 class Collection : public virtual Accessible
 750 {
 751 public:
 752 };
 753
 754 /**
 755  * @brief Interface representing objects having screen coordinates
 756  */
 757 class Component : public virtual Accessible
 758 {
 759 public:
 760   /**
 761    * @brief Get rectangle describing size
 762    *
 763    * @param[in] ctype enumeration with type of coordinate systems
 764    *
 765    * @return Rect<> object
 766    *
 767    * @see Dali::Rect
 768    */
 769   virtual Rect<> GetExtents(CoordType ctype) = 0;
 770
 771   /**
 772    * @brief Get layer current object is localized on
 773    *
 774    * @return enumeration pointing layer
 775    *
 776    * @see Dali::Accessibility::ComponentLayer
 777    */
 778   virtual ComponentLayer GetLayer() = 0;
 779
 780   /**
 781    * @brief Get value of z-order
 782    *
 783    * @return value of z-order
 784    */
 785   virtual int16_t GetMdiZOrder() = 0;
 786
 787   /**
 788    * @brief Set current object as "focused"
 789    *
 790    * @return true on success, false otherwise
 791    */
 792   virtual bool GrabFocus() = 0;
 793
 794   /**
 795    * @brief Get value of alpha channel
 796    *
 797    * @return alpha channel value in range [0.0, 1.0]
 798    */
 799   virtual double GetAlpha() = 0;
 800
 801   /**
 802    * @brief Set current object as "highlighted"
 803    *
 804    * The method assings "highlighted" state, simultaneously removing it
 805    * from currently highlighted object.
 806    *
 807    * @return true on success, false otherwise
 808    */
 809   virtual bool GrabHighlight() = 0;
 810
 811   /**
 812    * @brief Set current object as "unhighlighted"
 813    *
 814    * The method removes "highlighted" state from object.
 815    *
 816    * @return true on success, false otherwise
 817    *
 818    * @see Dali:Accessibility::State
 819    */
 820   virtual bool ClearHighlight() = 0;
 821
 822   /**
 823    * @brief Check whether object can be scrolled
 824    *
 825    * @return true if object is scrollable, false otherwise
 826    *
 827    * @see Dali:Accessibility::State
 828    */
 829   virtual bool IsScrollable();
 830
 831   /**
 832    * @brief Get Accessible object containing given point
 833    *
 834    * @param[in] p two-dimensional point
 835    * @param[in] ctype enumeration with type of coordinate system
 836    *
 837    * @return handle to last child of current object which contains given point
 838    *
 839    * @see Dali::Accessibility::Point
 840    */
 841   virtual Accessible* GetAccessibleAtPoint(Point p, CoordType ctype);
 842
 843   /**
 844    * @brief Check if current object contains given point
 845    *
 846    * @param[in] p two-dimensional point
 847    * @param[in] ctype enumeration with type of coordinate system
 848    *
 849    * @return handle to Accessible object
 850    *
 851    * @see Dali::Accessibility::Point
 852    */
 853   virtual bool Contains(Point p, CoordType ctype);
 854 };
 855
 856 /**
 857  * @brief Interface representing objects which can store numeric value
 858  */
 859 class Value : public virtual Accessible
 860 {
 861 public:
 862   /**
 863    * @brief Get the lowest possible value
 864    *
 865    * @return double value
 866   */
 867   virtual double GetMinimum() = 0;
 868
 869   /**
 870    * @brief Get current value
 871    *
 872    * @return double value
 873   */
 874   virtual double GetCurrent() = 0;
 875
 876   /**
 877    * @brief Get the highest possible value
 878    *
 879    * @return double value
 880   */
 881   virtual double GetMaximum() = 0;
 882
 883   /**
 884    * @brief Set value
 885    *
 886    * @param[in] val double value
 887    *
 888    * @return true if value could have been assigned, false otherwise
 889   */
 890   virtual bool SetCurrent(double val) = 0;
 891
 892   /**
 893    * @brief Get the lowest increment that can be distinguished
 894    *
 895    * @return double value
 896   */
 897   virtual double GetMinimumIncrement() = 0;
 898 };
 899
 900 /**
 901  * @brief Interface representing objects which can store immutable texts
 902  *
 903  * @see Dali::Accessibility::EditableText
 904  */
 905 class DALI_ADAPTOR_API Text : public virtual Accessible
 906 {
 907 public:
 908   /**
 909    * @brief Get stored text in given range
 910    *
 911    * @param[in] startOffset index of first character
 912    * @param[in] endOffset index of first character after the last one expected
 913    *
 914    * @return substring of stored text
 915    */
 916   virtual std::string GetText(size_t startOffset, size_t endOffset) = 0;
 917
 918   /**
 919    * @brief Get number of all stored characters
 920    *
 921    * @return number of characters
 922    */
 923   virtual size_t GetCharacterCount() = 0;
 924
 925   /**
 926    * @brief Get caret offset
 927    *
 928    * @return Value of caret offset
 929    */
 930   virtual size_t GetCaretOffset() = 0;
 931
 932   /**
 933    * @brief Set caret offset
 934    *
 935    * @param[in] offset Caret offset
 936    *
 937    * @return True if successful
 938    */
 939   virtual bool SetCaretOffset(size_t offset) = 0;
 940
 941   /**
 942    * @brief Get substring of stored text truncated in concrete gradation
 943    *
 944    * @param[in] offset position in stored text
 945    * @param[in] boundary enumeration describing text gradation
 946    *
 947    * @return Range structure containing acquired text and offsets in original string
 948    *
 949    * @see Dali::Accessibility::Range
 950    */
 951   virtual Range GetTextAtOffset(size_t offset, TextBoundary boundary) = 0;
 952
 953   /**
 954    * @brief Get selected text
 955    *
 956    * @param[in] selectionNum selection index
 957    * @note Currently only one selection (i.e. with index = 0) is supported
 958    *
 959    * @return Range structure containing acquired text and offsets in original string
 960    *
 961    * @see Dali::Accessibility::Range
 962    */
 963   virtual Range GetSelection(size_t selectionNum) = 0;
 964
 965   /**
 966    * @brief Remove selection
 967    *
 968    * @param[in] selectionNum selection index
 969    * @note Currently only one selection (i.e. with index = 0) is supported
 970    *
 971    * @return bool on success, false otherwise
 972    */
 973   virtual bool RemoveSelection(size_t selectionNum) = 0;
 974
 975   /**
 976    * @brief Get selected text
 977    *
 978    * @param[in] selectionNum selection index
 979    * @param[in] startOffset index of first character
 980    * @param[in] endOffset index of first character after the last one expected
 981    *
 982    * @note Currently only one selection (i.e. with index = 0) is supported
 983    *
 984    * @return true on success, false otherwise
 985    */
 986   virtual bool SetSelection(size_t selectionNum, size_t startOffset, size_t endOffset) = 0;
 987 };
 988
 989 /**
 990  * @brief Interface representing objects which can store editable texts
 991  *
 992  * @note Paste method is entirely implemented inside bridge
 993  *
 994  * @see Dali::Accessibility::EditableText
 995  */
 996 class DALI_ADAPTOR_API EditableText : public virtual Accessible
 997 {
 998 public:
 999   /**
1000    * @brief Copy text in range to system clipboard
1001    *
1002    * @param[in] startPosition index of first character
1003    * @param[in] endPosition index of first character after the last one expected
1004    *
1005    * @return true on success, false otherwise
1006    */
1007   virtual bool CopyText(size_t startPosition, size_t endPosition) = 0;
1008
1009   /**
1010    * @brief Cut text in range to system clipboard
1011    *
1012    * @param[in] startPosition index of first character
1013    * @param[in] endPosition index of first character after the last one expected
1014    *
1015    * @return true on success, false otherwise
1016    */
1017   virtual bool CutText(size_t startPosition, size_t endPosition) = 0;
1018 };
1019
1020 /**
1021  * @brief minimalistic, always empty Accessible object with settable address
1022  *
1023  * For those situations, where you want to return address in different bridge
1024  * (embedding for example), but the object itself ain't planned to be used otherwise.
1025  * This object has null parent, no children, empty name and so on
1026  */
1027 class DALI_ADAPTOR_API EmptyAccessibleWithAddress : public virtual Accessible
1028 {
1029 public:
1030   EmptyAccessibleWithAddress() = default;
1031   EmptyAccessibleWithAddress(Address address)
1032   : address(std::move(address))
1033   {
1034   }
1035
1036   void SetAddress(Address address)
1037   {
1038     this->address = std::move(address);
1039   }
1040
1041   std::string GetName() override
1042   {
1043     return "";
1044   }
1045   std::string GetDescription() override
1046   {
1047     return "";
1048   }
1049   Accessible* GetParent() override
1050   {
1051     return nullptr;
1052   }
1053   size_t GetChildCount() override
1054   {
1055     return 0;
1056   }
1057   std::vector<Accessible*> GetChildren() override
1058   {
1059     return {};
1060   }
1061   Accessible* GetChildAtIndex(size_t index) override
1062   {
1063     throw std::domain_error{"out of bounds index (" + std::to_string(index) + ") - no children"};
1064   }
1065   size_t GetIndexInParent() override
1066   {
1067     return static_cast<size_t>(-1);
1068   }
1069   Role GetRole() override
1070   {
1071     return {};
1072   }
1073   std::string GetRoleName() override;
1074   States      GetStates() override
1075   {
1076     return {};
1077   }
1078   Attributes GetAttributes() override
1079   {
1080     return {};
1081   }
1082   Address GetAddress() override
1083   {
1084     return address;
1085   }
1086   bool DoGesture(const GestureInfo& gestureInfo) override
1087   {
1088     return false;
1089   }
1090   std::vector<Relation> GetRelationSet() override
1091   {
1092     return {};
1093   }
1094
1095 private:
1096   Address address;
1097 };
1098
1099 } // namespace Accessibility
1100 } // namespace Dali
1101
1102 #endif // DALI_INTERNAL_ATSPI_ACCESSIBILITY_IMPL_H