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