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