dali/devel-api/atspi-interfaces/accessible.h

   1 #ifndef DALI_ADAPTOR_ATSPI_ACCESSIBLE_H
   2 #define DALI_ADAPTOR_ATSPI_ACCESSIBLE_H
   3
   4 /*
   5  * Copyright (c) 2023 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 // EXTERNAL INCLUDES
  21 #include <dali/public-api/actors/actor.h>
  22 #include <dali/public-api/math/rect.h>
  23 #include <dali/public-api/object/object-registry.h>
  24 #include <cstdint>
  25 #include <string>
  26 #include <vector>
  27
  28 // INTERNAL INCLUDES
  29 #include <dali/devel-api/adaptor-framework/accessibility-bridge.h>
  30 #include <dali/devel-api/adaptor-framework/accessibility.h>
  31
  32 namespace Dali::Accessibility
  33 {
  34 /**
  35  * @brief Basic interface implemented by all accessibility objects.
  36  */
  37 class DALI_ADAPTOR_API Accessible
  38 {
  39 public:
  40   virtual ~Accessible() noexcept;
  41
  42   /**
  43    * @brief Helper function for emiting active-descendant-changed event.
  44    *
  45    * @param[in] child The child of the object
  46    */
  47   void EmitActiveDescendantChanged(Accessible* child);
  48
  49   /**
  50    * @brief Helper function for emiting state-changed event.
  51    *
  52    * @param[in] state The accessibility state (SHOWING, HIGHLIGHTED, etc)
  53    * @param[in] newValue Whether the state value is changed to new value or not.
  54    * @param[in] reserved Reserved. (TODO : Currently, this argument is not implemented in dali)
  55    *
  56    * @note The second argument determines which value is depending on State.
  57    * For instance, if the state is PRESSED, newValue means isPressed or isSelected.
  58    * If the state is SHOWING, newValue means isShowing.
  59    */
  60   void EmitStateChanged(State state, int newValue, int reserved = 0);
  61
  62   /**
  63    * @brief Helper function for emiting bounds-changed event.
  64    *
  65    * @param rect The rectangle for changed bounds
  66    */
  67   void EmitBoundsChanged(Rect<> rect);
  68
  69   /**
  70    * @brief Emits "showing" event.
  71    * The method informs accessibility clients about "showing" state.
  72    *
  73    * @param[in] isShowing The flag pointing if object is showing
  74    */
  75   void EmitShowing(bool isShowing);
  76
  77   /**
  78    * @brief Emits "visible" event.
  79    * The method informs accessibility clients about "visible" state.
  80    *
  81    * @param[in] isVisible The flag pointing if object is visible
  82    */
  83   void EmitVisible(bool isVisible);
  84
  85   /**
  86    * @brief Emits "highlighted" event.
  87    * The method informs accessibility clients about "highlighted" state.
  88    *
  89    * @param[in] isHighlighted The flag pointing if object is highlighted
  90    */
  91   void EmitHighlighted(bool isHighlighted);
  92
  93   /**
  94    * @brief Emits "focused" event.
  95    * The method informs accessibility clients about "focused" state.
  96    *
  97    * @param[in] isFocused The flag pointing if object is focused
  98    */
  99   void EmitFocused(bool isFocused);
 100
 101   /**
 102    * @brief Emits "text inserted" event.
 103    *
 104    * @param[in] position The cursor position
 105    * @param[in] length The text length
 106    * @param[in] content The inserted text
 107    */
 108   void EmitTextInserted(unsigned int position, unsigned int length, const std::string& content);
 109
 110   /**
 111    * @brief Emits "text deleted" event.
 112    *
 113    * @param[in] position The cursor position
 114    * @param[in] length The text length
 115    * @param[in] content The deleted text
 116    */
 117   void EmitTextDeleted(unsigned int position, unsigned int length, const std::string& content);
 118
 119   /**
 120    * @brief Emits "cursor moved" event.
 121    *
 122    * @param[in] cursorPosition The new cursor position
 123    */
 124   void EmitTextCursorMoved(unsigned int cursorPosition);
 125
 126   /**
 127    * @brief Emits "MoveOuted" event.
 128    *
 129    * @param[in] type moved out of screen type
 130    */
 131   void EmitMovedOutOfScreen(ScreenRelativeMoveType type);
 132
 133   /**
 134    * @brief Emits "org.a11y.atspi.Socket.Available" signal.
 135    */
 136   // This belongs to Dali::Accessibility::Socket. However, all Emit*() helpers
 137   // are here in Accessible, regardless of what interface they belong to (perhaps
 138   // to spare a dynamic_cast if used like this: Accessible::Get()->Emit*(...)).
 139   void EmitSocketAvailable();
 140
 141   /**
 142    * @brief Emits "highlighted" event.
 143    *
 144    * @param[in] event The enumerated window event
 145    * @param[in] detail The additional parameter which interpretation depends on chosen event
 146    */
 147   void Emit(WindowEvent event, unsigned int detail = 0);
 148
 149   /**
 150    * @brief Emits property-changed event.
 151    *
 152    * @param[in] event Property changed event
 153    **/
 154   void Emit(ObjectPropertyChangeEvent event);
 155
 156   /**
 157    * @brief Gets accessibility name.
 158    *
 159    * @return The string with name
 160    */
 161   virtual std::string GetName() const = 0;
 162
 163   /**
 164    * @brief Gets accessibility description.
 165    *
 166    * @return The string with description
 167    */
 168   virtual std::string GetDescription() const = 0;
 169
 170   /**
 171    * @brief Gets parent.
 172    *
 173    * @return The handler to accessibility object
 174    */
 175   virtual Accessible* GetParent() = 0;
 176
 177   /**
 178    * @brief Gets the number of children.
 179    *
 180    * @return The number of children
 181    */
 182   virtual std::size_t GetChildCount() const = 0;
 183
 184   /**
 185    * @brief Gets collection with all children.
 186    *
 187    * @return The collection of accessibility objects
 188    */
 189   virtual std::vector<Accessible*> GetChildren() = 0;
 190
 191   /**
 192    * @brief Gets child of the index.
 193    *
 194    * @return The child object
 195    */
 196   virtual Accessible* GetChildAtIndex(std::size_t index) = 0;
 197
 198   /**
 199    * @brief Gets index that current object has in its parent's children collection.
 200    *
 201    * @return The index of the current object
 202    */
 203   virtual std::size_t GetIndexInParent() = 0;
 204
 205   /**
 206    * @brief Gets accessibility role.
 207    *
 208    * @return Role enumeration
 209    *
 210    * @see Dali::Accessibility::Role
 211    */
 212   virtual Role GetRole() const = 0;
 213
 214   /**
 215    * @brief Gets name of accessibility role.
 216    *
 217    * @return The string with human readable role converted from enumeration
 218    *
 219    * @see Dali::Accessibility::Role
 220    * @see Accessibility::Accessible::GetRole
 221    */
 222   virtual std::string GetRoleName() const;
 223
 224   /**
 225    * @brief Gets localized name of accessibility role.
 226    *
 227    * @return The string with human readable role translated according to current
 228    * translation domain
 229    *
 230    * @see Dali::Accessibility::Role
 231    * @see Accessibility::Accessible::GetRole
 232    * @see Accessibility::Accessible::GetRoleName
 233    *
 234    * @note translation is not supported in this version
 235    */
 236   virtual std::string GetLocalizedRoleName() const;
 237
 238   /**
 239    * @brief Gets accessibility states.
 240    *
 241    * @return The collection of states
 242    *
 243    * @note States class is instatation of ArrayBitset template class
 244    *
 245    * @see Dali::Accessibility::State
 246    * @see Dali::Accessibility::ArrayBitset
 247    */
 248   virtual States GetStates() = 0;
 249
 250   /**
 251    * @brief Gets accessibility attributes.
 252    *
 253    * Attributes are key-value string pairs which can be used to transfer arbitrary
 254    * information from the application to a client such as a screen reader or an
 255    * automation framework.
 256    *
 257    * Typically, attributes are used when the data does not fit any other category
 258    * with a dedicated API (name, description, states etc.).
 259    *
 260    * @see Accessible::SetAttribute()
 261    * @see Accessible::UnsetAttribute()
 262    * @see Accessible::ClearAttributes()
 263    * @see Accessible::UpdateAttributes()
 264    *
 265    * @return The map of attributes and their values
 266    */
 267   const Attributes& GetAttributes() const;
 268
 269   /**
 270    * @brief Sets an attribute
 271    *
 272    * The key will be created if necessary and the old attribute value (if any) will be replaced.
 273    *
 274    * @param[in] key Attribute key
 275    * @param[in] value Attribute value
 276    *
 277    * @return True if the key was created, false otherwise (only value was updated)
 278    */
 279   bool SetAttribute(const std::string& key, const std::string& value);
 280
 281   /**
 282    * @brief Unsets an attribute
 283    *
 284    * The key-value pair is removed from the attribute collection.
 285    *
 286    * @param[in] key Attribute key
 287    *
 288    * @return True if there was such a key, false otherwise
 289    */
 290   bool UnsetAttribute(const std::string& key);
 291
 292   /**
 293    * @brief Unsets all attributes
 294    *
 295    * @see Accessible::UnsetAttribute()
 296    */
 297   void ClearAttributes();
 298
 299   /**
 300    * @brief Gets the reading info types
 301    *
 302    * @return Reading info types bitmask
 303    * @see Accessible::SetReadingInfoTypes()
 304    */
 305   ReadingInfoTypes GetReadingInfoTypes() const;
 306
 307   /**
 308    * @brief Sets the reading info types
 309    *
 310    * The reading info types are individual pieces of information (name, role etc.)
 311    * that can be read by the screen reader. This method can be used to enable and
 312    * disable reading specific pieces.
 313    *
 314    * @param[in] types Reading info types bitmask
 315    *
 316    * @note The types will appear in GetAttributes() under the "reading_info_type" key.
 317    * @see Accessible::GetAttributes()
 318    */
 319   void SetReadingInfoTypes(ReadingInfoTypes types);
 320
 321   /**
 322    * @brief Checks if this is hidden.
 323    *
 324    * @return True if this is hidden
 325    *
 326    * @note Hidden means not present in the AT-SPI tree.
 327    */
 328   virtual bool IsHidden() const;
 329
 330   /**
 331    * @brief Checks if this is proxy.
 332    *
 333    * @return True if this is proxy
 334    */
 335   virtual bool IsProxy() const;
 336
 337   /**
 338    * @brief Gets unique address on accessibility bus.
 339    *
 340    * @return The Address class containing address
 341    *
 342    * @see Dali::Accessibility::Address
 343    */
 344   virtual Address GetAddress() const;
 345
 346   /**
 347    * @brief Deputes an object to perform provided gesture.
 348    *
 349    * @param[in] gestureInfo The structure describing the gesture
 350    *
 351    * @return true on success, false otherwise
 352    *
 353    * @see Dali::Accessibility::GestureInfo
 354    */
 355   virtual bool DoGesture(const GestureInfo& gestureInfo) = 0;
 356
 357   /**
 358    * @brief Re-emits selected states of an Accessibility Object.
 359    *
 360    * @param[in] states The chosen states to re-emit
 361    * @param[in] isRecursive If true, all children of the Accessibility object will also re-emit the states
 362    */
 363   void NotifyAccessibilityStateChange(Dali::Accessibility::States states, bool isRecursive);
 364
 365   /**
 366    * @brief Gets information about current object and all relations that connects
 367    * it with other accessibility objects.
 368    *
 369    * @return The iterable collection of Relation objects
 370    *
 371    * @see Dali::Accessibility::Relation
 372    */
 373   virtual std::vector<Relation> GetRelationSet() = 0;
 374
 375   /**
 376    * @brief Gets the Actor associated with this Accessible (if there is one).
 377    *
 378    * @return The internal Actor
 379    */
 380   virtual Dali::Actor GetInternalActor() = 0;
 381
 382   /**
 383    * @brief Sets whether to listen for post render callback.
 384    *
 385    * @param[in] enabled If ture, registration post render callback, false otherwise
 386    */
 387   virtual void SetListenPostRender(bool enabled);
 388
 389   /**
 390    * @brief Gets all implemented interfaces.
 391    *
 392    * Override DoGetInterfaces() to customize the return value of this method.
 393    *
 394    * @return The collection of implemented interfaces
 395    *
 396    * @see DoGetInterfaces()
 397    */
 398   AtspiInterfaces GetInterfaces() const;
 399
 400   /**
 401    * @brief Gets all implemented interfaces.
 402    *
 403    * Converts all interfaces returned by GetInterfaces() to their DBus names
 404    * using GetInterfaceName().
 405    *
 406    * @return The collection of names of implemented interfaces
 407    *
 408    * @see GetInterfaces()
 409    * @see GetInterfaceName()
 410    */
 411   std::vector<std::string> GetInterfacesAsStrings() const;
 412
 413   /**
 414    * @brief Checks if object is on root level.
 415    *
 416    * @return Whether object is on root level or not
 417    */
 418   bool IsOnRootLevel() const
 419   {
 420     return mIsOnRootLevel;
 421   }
 422
 423   /**
 424    * @brief Gets all suppressed events.
 425    *
 426    * @return All suppressed events
 427    */
 428   AtspiEvents GetSuppressedEvents() const
 429   {
 430     return mSuppressedEvents;
 431   }
 432
 433   /**
 434    * @brief Gets all suppressed events.
 435    *
 436    * @return All suppressed events
 437    */
 438   AtspiEvents& GetSuppressedEvents()
 439   {
 440     return mSuppressedEvents;
 441   }
 442
 443 protected:
 444   Accessible();
 445   Accessible(const Accessible&)         = delete;
 446   Accessible(Accessible&&)              = delete;
 447   Accessible&                   operator=(const Accessible&) = delete;
 448   Accessible&                   operator=(Accessible&&) = delete;
 449   std::shared_ptr<Bridge::Data> GetBridgeData() const;
 450
 451   /**
 452    * @brief Returns the collection of AT-SPI interfaces implemented by this Accessible.
 453    *
 454    * This method is called only once and its return value is cached. The default implementation
 455    * uses dynamic_cast to determine which interfaces are implemented. Override this if you
 456    * conceptually provide fewer interfaces than dynamic_cast can see.
 457    *
 458    * @return The collection of implemented interfaces
 459    *
 460    * @see GetInterfaces()
 461    * @see GetInterfaceName()
 462    */
 463   virtual AtspiInterfaces DoGetInterfaces() const;
 464
 465   /**
 466    * @brief Updates the attribute collection
 467    *
 468    * This method, which is always called by GetAttributes(), can be overriden to
 469    * provide lazily-calculated or dynamically-calculated (i.e. non-constant)
 470    * attributes. When overriding, make sure to call the base class implementation
 471    * first.
 472    *
 473    * @note The attribute collection is non-empty on entry
 474    * @see Accessible::GetAttributes()
 475    *
 476    * @param[inout] attributes The attribute collection to update
 477    */
 478   virtual void UpdateAttributes(Attributes& attributes) const;
 479
 480 public:
 481   /**
 482    * @brief Gets the highlight actor.
 483    *
 484    * This method is to get the highlight itself.
 485    * @return The highlight actor
 486    */
 487   static Dali::Actor GetHighlightActor();
 488
 489   /**
 490    * @brief Sets the highlight actor.
 491    *
 492    * This method is to set the highlight itself.
 493    * @param[in] actor The highlight actor
 494    */
 495   static void SetHighlightActor(Dali::Actor actor);
 496
 497   /**
 498    * @brief Gets the currently highlighted actor.
 499    *
 500    * @return The current highlighted actor
 501    */
 502   static Dali::Actor GetCurrentlyHighlightedActor();
 503
 504   /**
 505    * @brief Sets currently highlighted actor.
 506    *
 507    * @param[in] actor The highlight actor
 508    */
 509   static void SetCurrentlyHighlightedActor(Dali::Actor actor);
 510
 511   /**
 512    * @brief Sets ObjectRegistry.
 513    *
 514    * @param[in] registry ObjectRegistry instance
 515    */
 516   static void SetObjectRegistry(ObjectRegistry registry);
 517
 518   /**
 519    * @brief The method registers functor resposible for converting Actor into Accessible.
 520    * @param functor The returning Accessible handle from Actor object
 521    */
 522   static void RegisterExternalAccessibleGetter(std::function<Accessible*(Dali::Actor)> functor);
 523
 524   /**
 525    * @brief Acquires Accessible object from Actor object.
 526    *
 527    * @param[in] actor Actor object
 528    *
 529    * @return The handle to Accessible object
 530    */
 531   static Accessible* Get(Dali::Actor actor);
 532
 533   /**
 534    * @brief Obtains the DBus interface name for the specified AT-SPI interface.
 535    *
 536    * @param interface AT-SPI interface identifier (e.g. AtspiInterface::ACCESSIBLE)
 537    * @return AT-SPI interface name (e.g. "org.a11y.atspi.Accessible")
 538    */
 539   static std::string GetInterfaceName(AtspiInterface interface);
 540
 541   /**
 542    * @brief Downcasts an Accessible pointer to an AT-SPI interface pointer.
 543    *
 544    * @tparam I Desired AT-SPI interface
 545    *
 546    * @param obj Object to cast.
 547    *
 548    * @return Pointer to an AT-SPI interface or null if the interface is not implemented.
 549    */
 550   template<AtspiInterface I>
 551   static AtspiInterfaceType<I>* DownCast(Accessible* obj)
 552   {
 553     if(!obj || !obj->GetInterfaces()[I])
 554     {
 555       return nullptr;
 556     }
 557
 558     return dynamic_cast<AtspiInterfaceType<I>*>(obj);
 559   }
 560
 561 private:
 562   friend class Bridge;
 563
 564   mutable std::weak_ptr<Bridge::Data> mBridgeData;
 565   mutable AtspiInterfaces             mInterfaces;
 566   mutable Attributes                  mAttributes;
 567   ReadingInfoTypes                    mReadingInfoTypes = ~ReadingInfoTypes(); // all set
 568   AtspiEvents                         mSuppressedEvents;
 569   bool                                mIsOnRootLevel = false;
 570 }; // Accessible class
 571
 572 namespace Internal
 573 {
 574 template<>
 575 struct AtspiInterfaceTypeHelper<AtspiInterface::ACCESSIBLE>
 576 {
 577   using Type = Accessible;
 578 };
 579 } // namespace Internal
 580
 581 } // namespace Dali::Accessibility
 582
 583 #endif // DALI_ADAPTOR_ATSPI_ACCESSIBLE_H