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) 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 // 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.h>
  30 #include <dali/devel-api/adaptor-framework/accessibility-bridge.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   using utf8_t = unsigned char;
  43
  44   /**
  45    * @brief Calculates and finds word boundaries in given utf8 text.
  46    *
  47    * @param[in] string The source text to find
  48    * @param[in] length The length of text to find
  49    * @param[in] language The language to use
  50    * @param[out] breaks The word boundaries in given text
  51    *
  52    * @note Word boundaries are returned as non-zero values in table breaks, which must be of size at least length.
  53    */
  54   static void FindWordSeparationsUtf8(const utf8_t* string, std::size_t length, const char* language, char* breaks);
  55
  56   /**
  57    * @brief Calculates and finds line boundaries in given utf8 text.
  58    *
  59    * @param[in] string The source text to find
  60    * @param[in] length The length of text to find
  61    * @param[in] language The language to use
  62    * @param[out] breaks The line boundaries in given text
  63    *
  64    * @note Line boundaries are returned as non-zero values in table breaks, which must be of size at least length.
  65    */
  66   static void FindLineSeparationsUtf8(const utf8_t* string, std::size_t length, const char* language, char* breaks);
  67
  68   /**
  69    * @brief Helper function for emiting active-descendant-changed event.
  70    *
  71    * @param[in] obj The accessible object
  72    * @param[in] child The child of the object
  73    */
  74   void EmitActiveDescendantChanged(Accessible* obj, Accessible* child);
  75
  76   /**
  77    * @brief Helper function for emiting state-changed event.
  78    *
  79    * @param[in] state The accessibility state (SHOWING, HIGHLIGHTED, etc)
  80    * @param[in] newValue Whether the state value is changed to new value or not.
  81    * @param[in] reserved Reserved. (TODO : Currently, this argument is not implemented in dali)
  82    *
  83    * @note The second argument determines which value is depending on State.
  84    * For instance, if the state is PRESSED, newValue means isPressed or isSelected.
  85    * If the state is SHOWING, newValue means isShowing.
  86    */
  87   void EmitStateChanged(State state, int newValue, int reserved = 0);
  88
  89   /**
  90    * @brief Helper function for emiting bounds-changed event.
  91    *
  92    * @param rect The rectangle for changed bounds
  93    */
  94   void EmitBoundsChanged(Rect<> rect);
  95
  96   /**
  97    * @brief Emits "showing" event.
  98    * The method informs accessibility clients about "showing" state.
  99    *
 100    * @param[in] isShowing The flag pointing if object is showing
 101    */
 102   void EmitShowing(bool isShowing);
 103
 104   /**
 105    * @brief Emits "visible" event.
 106    * The method informs accessibility clients about "visible" state.
 107    *
 108    * @param[in] isVisible The flag pointing if object is visible
 109    */
 110   void EmitVisible(bool isVisible);
 111
 112   /**
 113    * @brief Emits "highlighted" event.
 114    * The method informs accessibility clients about "highlighted" state.
 115    *
 116    * @param[in] isHighlighted The flag pointing if object is highlighted
 117    */
 118   void EmitHighlighted(bool isHighlighted);
 119
 120   /**
 121    * @brief Emits "focused" event.
 122    * The method informs accessibility clients about "focused" state.
 123    *
 124    * @param[in] isFocused The flag pointing if object is focused
 125    */
 126   void EmitFocused(bool isFocused);
 127
 128   /**
 129    * @brief Emits "text inserted" event.
 130    *
 131    * @param[in] position The cursor position
 132    * @param[in] length The text length
 133    * @param[in] content The inserted text
 134    */
 135   void EmitTextInserted(unsigned int position, unsigned int length, const std::string& content);
 136
 137   /**
 138    * @brief Emits "text deleted" event.
 139    *
 140    * @param[in] position The cursor position
 141    * @param[in] length The text length
 142    * @param[in] content The deleted text
 143    */
 144   void EmitTextDeleted(unsigned int position, unsigned int length, const std::string& content);
 145
 146   /**
 147    * @brief Emits "cursor moved" event.
 148    *
 149    * @param[in] cursorPosition The new cursor position
 150    */
 151   void EmitTextCursorMoved(unsigned int cursorPosition);
 152
 153   /**
 154    * @brief Emits "MoveOuted" event.
 155    *
 156    * @param[in] type moved out of screen type
 157    */
 158   void EmitMovedOutOfScreen(ScreenRelativeMoveType type);
 159
 160   /**
 161    * @brief Emits "highlighted" event.
 162    *
 163    * @param[in] event The enumerated window event
 164    * @param[in] detail The additional parameter which interpretation depends on chosen event
 165    */
 166   void Emit(WindowEvent event, unsigned int detail = 0);
 167
 168   /**
 169    * @brief Emits property-changed event.
 170    *
 171    * @param[in] event Property changed event
 172    **/
 173   void Emit(ObjectPropertyChangeEvent event);
 174
 175   /**
 176    * @brief Gets accessibility name.
 177    *
 178    * @return The string with name
 179    */
 180   virtual std::string GetName() const = 0;
 181
 182   /**
 183    * @brief Gets accessibility description.
 184    *
 185    * @return The string with description
 186    */
 187   virtual std::string GetDescription() const = 0;
 188
 189   /**
 190    * @brief Gets parent.
 191    *
 192    * @return The handler to accessibility object
 193    */
 194   virtual Accessible* GetParent() = 0;
 195
 196   /**
 197    * @brief Gets the number of children.
 198    *
 199    * @return The number of children
 200    */
 201   virtual std::size_t GetChildCount() const = 0;
 202
 203   /**
 204    * @brief Gets collection with all children.
 205    *
 206    * @return The collection of accessibility objects
 207    */
 208   virtual std::vector<Accessible*> GetChildren() = 0;
 209
 210   /**
 211    * @brief Gets child of the index.
 212    *
 213    * @return The child object
 214    */
 215   virtual Accessible* GetChildAtIndex(std::size_t index) = 0;
 216
 217   /**
 218    * @brief Gets index that current object has in its parent's children collection.
 219    *
 220    * @return The index of the current object
 221    */
 222   virtual std::size_t GetIndexInParent() = 0;
 223
 224   /**
 225    * @brief Gets accessibility role.
 226    *
 227    * @return Role enumeration
 228    *
 229    * @see Dali::Accessibility::Role
 230    */
 231   virtual Role GetRole() const = 0;
 232
 233   /**
 234    * @brief Gets name of accessibility role.
 235    *
 236    * @return The string with human readable role converted from enumeration
 237    *
 238    * @see Dali::Accessibility::Role
 239    * @see Accessibility::Accessible::GetRole
 240    */
 241   virtual std::string GetRoleName() const;
 242
 243   /**
 244    * @brief Gets localized name of accessibility role.
 245    *
 246    * @return The string with human readable role translated according to current
 247    * translation domain
 248    *
 249    * @see Dali::Accessibility::Role
 250    * @see Accessibility::Accessible::GetRole
 251    * @see Accessibility::Accessible::GetRoleName
 252    *
 253    * @note translation is not supported in this version
 254    */
 255   virtual std::string GetLocalizedRoleName() const;
 256
 257   /**
 258    * @brief Gets accessibility states.
 259    *
 260    * @return The collection of states
 261    *
 262    * @note States class is instatation of ArrayBitset template class
 263    *
 264    * @see Dali::Accessibility::State
 265    * @see Dali::Accessibility::ArrayBitset
 266    */
 267   virtual States GetStates() = 0;
 268
 269   /**
 270    * @brief Gets accessibility attributes.
 271    *
 272    * @return The map of attributes and their values
 273    */
 274   virtual Attributes GetAttributes() const = 0;
 275
 276   /**
 277    * @brief Checks if this is hidden.
 278    *
 279    * @return True if this is hidden
 280    *
 281    * @note Hidden means not present in the AT-SPI tree.
 282    */
 283   virtual bool IsHidden() const;
 284
 285   /**
 286    * @brief Checks if this is proxy.
 287    *
 288    * @return True if this is proxy
 289    */
 290   virtual bool IsProxy() const;
 291
 292   /**
 293    * @brief Gets unique address on accessibility bus.
 294    *
 295    * @return The Address class containing address
 296    *
 297    * @see Dali::Accessibility::Address
 298    */
 299   virtual Address GetAddress() const;
 300
 301   /**
 302    * @brief Deputes an object to perform provided gesture.
 303    *
 304    * @param[in] gestureInfo The structure describing the gesture
 305    *
 306    * @return true on success, false otherwise
 307    *
 308    * @see Dali::Accessibility::GestureInfo
 309    */
 310   virtual bool DoGesture(const GestureInfo& gestureInfo) = 0;
 311
 312   /**
 313    * @brief Re-emits selected states of an Accessibility Object.
 314    *
 315    * @param[in] states The chosen states to re-emit
 316    * @param[in] isRecursive If true, all children of the Accessibility object will also re-emit the states
 317    */
 318   void NotifyAccessibilityStateChange(Dali::Accessibility::States states, bool isRecursive);
 319
 320   /**
 321    * @brief Gets information about current object and all relations that connects
 322    * it with other accessibility objects.
 323    *
 324    * @return The iterable collection of Relation objects
 325    *
 326    * @see Dali::Accessibility::Relation
 327    */
 328   virtual std::vector<Relation> GetRelationSet() = 0;
 329
 330   /**
 331    * @brief Gets internal Actor to be saved before.
 332    *
 333    * @return The internal Actor
 334    */
 335   virtual Dali::Actor GetInternalActor() = 0;
 336
 337   /**
 338    * @brief Gets all implemented interfaces.
 339    *
 340    * @return The collection of strings with implemented interfaces
 341    */
 342   std::vector<std::string> GetInterfaces() const;
 343
 344   /**
 345    * @brief Checks if object is on root level.
 346    *
 347    * @return Whether object is on root level or not
 348    */
 349   bool IsOnRootLevel() const
 350   {
 351     return mIsOnRootLevel;
 352   }
 353
 354 protected:
 355   Accessible();
 356   Accessible(const Accessible&)         = delete;
 357   Accessible(Accessible&&)              = delete;
 358   Accessible&                   operator=(const Accessible&) = delete;
 359   Accessible&                   operator=(Accessible&&) = delete;
 360   std::shared_ptr<Bridge::Data> GetBridgeData() const;
 361
 362 public:
 363   /**
 364    * @brief Gets the highlight actor.
 365    *
 366    * This method is to get the highlight itself.
 367    * @return The highlight actor
 368    */
 369   static Dali::Actor GetHighlightActor();
 370
 371   /**
 372    * @brief Sets the highlight actor.
 373    *
 374    * This method is to set the highlight itself.
 375    * @param[in] actor The highlight actor
 376    */
 377   static void SetHighlightActor(Dali::Actor actor);
 378
 379   /**
 380    * @brief Gets the currently highlighted actor.
 381    *
 382    * @return The current highlighted actor
 383    */
 384   static Dali::Actor GetCurrentlyHighlightedActor();
 385
 386   /**
 387    * @brief Sets currently highlighted actor.
 388    *
 389    * @param[in] actor The highlight actor
 390    */
 391   static void SetCurrentlyHighlightedActor(Dali::Actor actor);
 392
 393   /**
 394    * @brief Sets ObjectRegistry.
 395    *
 396    * @param[in] registry ObjectRegistry instance
 397    */
 398   static void SetObjectRegistry(ObjectRegistry registry);
 399
 400   /**
 401    * @brief The method registers functor resposible for converting Actor into Accessible.
 402    * @param functor The returning Accessible handle from Actor object
 403    */
 404   static void RegisterExternalAccessibleGetter(std::function<Accessible*(Dali::Actor)> functor);
 405
 406   /**
 407    * @brief Acquires Accessible object from Actor object.
 408    *
 409    * @param[in] actor Actor object
 410    * @param[in] isRoot True, if it's top level object (window)
 411    *
 412    * @return The handle to Accessible object
 413    */
 414   static Accessible* Get(Dali::Actor actor, bool isRoot = false);
 415
 416 private:
 417   friend class Bridge;
 418
 419   mutable std::weak_ptr<Bridge::Data> mBridgeData;
 420   bool                                mIsOnRootLevel = false;
 421
 422 }; // Accessible class
 423
 424 } // namespace Dali::Accessibility
 425
 426 #endif // DALI_ADAPTOR_ATSPI_ACCESSIBLE_H