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