dali/devel-api/adaptor-framework/accessibility.h

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