dali/internal/accessibility/bridge/bridge-accessible.h

   1 #ifndef DALI_INTERNAL_ACCESSIBILITY_BRIDGE_ACCESSIBLE_H
   2 #define DALI_INTERNAL_ACCESSIBILITY_BRIDGE_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
  21 // EXTERNAL INCLUDES
  22 #include <array>
  23 #include <string>
  24 #include <unordered_map>
  25 #include <vector>
  26
  27 // INTERNAL INCLUDES
  28 #include <dali/devel-api/atspi-interfaces/accessible.h>
  29 #include <dali/devel-api/atspi-interfaces/component.h>
  30 #include <dali/internal/accessibility/bridge/bridge-base.h>
  31
  32 /**
  33  * @brief The BridgeAccessible class is to correspond with Dali::Accessibility::Accessible.
  34  */
  35 class BridgeAccessible : public virtual BridgeBase
  36 {
  37 protected:
  38   /**
  39    * @brief Constructor.
  40    */
  41   BridgeAccessible();
  42
  43   /**
  44    * @brief Registers Accessible functions to dbus interfaces.
  45    */
  46   void RegisterInterfaces();
  47
  48   /**
  49    * @brief Returns the Accessible object of the currently executed DBus method call.
  50    *
  51    * @return The Accessible object
  52    */
  53   Dali::Accessibility::Accessible* FindSelf() const;
  54
  55 public:
  56   /**
  57    * @brief Enumeration for NeighborSearchMode.
  58    */
  59   enum class NeighborSearchMode
  60   {
  61     NORMAL                          = 0, ///< Normal
  62     RECURSE_FROM_ROOT               = 1, ///< Recurse from root
  63     CONTINUE_AFTER_FAILED_RECURSION = 2, ///< Continue after failed recursion
  64     RECURSE_TO_OUTSIDE              = 3, ///< Recurse to outside
  65   };
  66
  67   using ReadingMaterialType = DBus::ValueOrError<
  68     std::unordered_map<std::string, std::string>, // attributes
  69     std::string,                                  // name
  70     std::string,                                  // labeledByName
  71     std::string,                                  // textIfceName
  72     uint32_t,
  73     Dali::Accessibility::States,
  74     std::string,                      // localized name
  75     int32_t,                          // child count
  76     double,                           // current value
  77     std::string,                      // formatted current value
  78     double,                           // minimum increment
  79     double,                           // maximum value
  80     double,                           // minimum value
  81     std::string,                      // description
  82     int32_t,                          // index in parent
  83     bool,                             // isSelectedInParent
  84     bool,                             // hasCheckBoxChild
  85     int32_t,                          // listChildrenCount
  86     int32_t,                          // firstSelectedChildIndex
  87     Dali::Accessibility::Accessible*, // parent
  88     Dali::Accessibility::States,      // parentStateSet
  89     int32_t,                          // parentChildCount
  90     uint32_t,                         // parentRole
  91     int32_t,                          // selectedChildCount,
  92     Dali::Accessibility::Accessible*  // describedByObject
  93     >;
  94
  95   using NodeInfoType = DBus::ValueOrError<
  96     std::string,                                    // role name
  97     std::string,                                    // name
  98     std::string,                                    // toolkit name
  99     std::unordered_map<std::string, std::string>,   // attributes
 100     Dali::Accessibility::States,                    // states
 101     std::tuple<int32_t, int32_t, int32_t, int32_t>, // screen extents
 102     std::tuple<int32_t, int32_t, int32_t, int32_t>, // window extents
 103     double,                                         // current value
 104     double,                                         // minimum increment
 105     double,                                         // maximum value
 106     double                                          // minimum value
 107     >;
 108
 109   using Relation = std::tuple<uint32_t, std::vector<Dali::Accessibility::Accessible*>>;
 110
 111   /**
 112    * @copydoc Dali::Accessibility::Accessible::GetChildCount()
 113    */
 114   int GetChildCount();
 115
 116   /**
 117    * @copydoc Dali::Accessibility::Accessible::GetChildAtIndex()
 118    */
 119   DBus::ValueOrError<Dali::Accessibility::Accessible*> GetChildAtIndex(int index);
 120
 121   /**
 122    * @copydoc Dali::Accessibility::Accessible::GetParent()
 123    */
 124   Dali::Accessibility::Accessible* GetParent();
 125
 126   /**
 127    * @copydoc Dali::Accessibility::Accessible::GetChildren()
 128    */
 129   DBus::ValueOrError<std::vector<Dali::Accessibility::Accessible*>> GetChildren();
 130
 131   /**
 132    * @copydoc Dali::Accessibility::Accessible::GetName()
 133    */
 134   std::string GetName();
 135
 136   /**
 137    * @copydoc Dali::Accessibility::Accessible::GetDescription()
 138    */
 139   std::string GetDescription();
 140
 141   /**
 142    * @copydoc Dali::Accessibility::Accessible::GetRole()
 143    */
 144   DBus::ValueOrError<uint32_t> GetRole();
 145
 146   /**
 147    * @copydoc Dali::Accessibility::Accessible::GetRoleName()
 148    */
 149   DBus::ValueOrError<std::string> GetRoleName();
 150
 151   /**
 152    * @copydoc Dali::Accessibility::Accessible::GetLocalizedRoleName()
 153    */
 154   DBus::ValueOrError<std::string> GetLocalizedRoleName();
 155
 156   /**
 157    * @copydoc Dali::Accessibility::Accessible::GetIndexInParent()
 158    */
 159   DBus::ValueOrError<int32_t> GetIndexInParent();
 160
 161   /**
 162    * @copydoc Dali::Accessibility::Accessible::GetStates()
 163    */
 164   DBus::ValueOrError<std::array<uint32_t, 2>> GetStates();
 165
 166   /**
 167    * @copydoc Dali::Accessibility::Accessible::GetAttributes()
 168    */
 169   DBus::ValueOrError<std::unordered_map<std::string, std::string>> GetAttributes();
 170
 171   /**
 172    * @copydoc Dali::Accessibility::Accessible::GetInterfacesAsStrings()
 173    */
 174   DBus::ValueOrError<std::vector<std::string>> GetInterfacesAsStrings();
 175
 176   /**
 177    * @brief Gets Accessible object on which surface lies the point with given coordinates.
 178    *
 179    * @param[in] x X coordinate of a point
 180    * @param[in] y Y coordinate of a point
 181    * @param[in] coordinateType The coordinate type
 182    * @return The array containing the Accessible object, recursive status, and deputy Accessible
 183    */
 184   DBus::ValueOrError<Dali::Accessibility::Accessible*, uint8_t, Dali::Accessibility::Accessible*> GetNavigableAtPoint(int32_t x, int32_t y, uint32_t coordinateType);
 185
 186   /**
 187    * @brief Gets Accessible object that, dependently to the given direction parameter,
 188    * stands in navigation order immediately before/after the Accessible object being a target of this dbus call.
 189    *
 190    * The 'direction' parameter denotes if the neighbor object search is done forward or backward in UI elements navigation order.
 191    * @param[in] rootPath The path of root Accessible object
 192    * @param[in] direction 1 is forward, 0 is backward
 193    * @param[in] searchMode BridgeAccessible::NeighborSearchMode enum
 194    * @return The array containing the neighbor Accessible object and recursive status
 195    */
 196   DBus::ValueOrError<Dali::Accessibility::Accessible*, uint8_t> GetNeighbor(std::string rootPath, int32_t direction, int32_t searchMode);
 197
 198   /**
 199    * @brief Gets the default label information.
 200    *
 201    * The "Default label" is a text that could be read by screen-reader immediately
 202    * after the navigation context has changed (window activates, popup shows up, tab changes) and before first UI element is highlighted.
 203    * @return The array containing the Accessible object being a source of default label text, its role, and its attributes
 204    * @note This is a Tizen only feature not present in upstream ATSPI.
 205    * Feature can be enabled/disabled for particular context root object by setting value of its accessibility attribute "default_label".
 206    */
 207   DBus::ValueOrError<Dali::Accessibility::Accessible*, uint32_t, std::unordered_map<std::string, std::string>> GetDefaultLabelInfo();
 208
 209   /**
 210    * @brief Gets Reading material information of the self object.
 211    * @return Reading material information
 212    */
 213   ReadingMaterialType GetReadingMaterial();
 214
 215   /**
 216    * @copydoc Dali::Accessibility::Accessible::DoGesture()
 217    */
 218   DBus::ValueOrError<bool> DoGesture(Dali::Accessibility::Gesture type, int32_t startPositionX, int32_t startPositionY, int32_t endPositionX, int32_t endPositionY, Dali::Accessibility::GestureState state, uint32_t eventTime);
 219
 220   /**
 221    * @copydoc Dali::Accessibility::Accessible::GetRelationSet()
 222    */
 223   DBus::ValueOrError<std::vector<Relation>> GetRelationSet();
 224
 225   /**
 226    * @copydoc Dali::Accessibility::Accessible::SetListenPostRender()
 227    */
 228   DBus::ValueOrError<void> SetListenPostRender(bool enabled);
 229
 230   /**
 231    * @brief Gets Node information of the self object.
 232    * @return Node information
 233    */
 234   NodeInfoType GetNodeInfo();
 235
 236 private:
 237   /**
 238    * @brief Calculates Neighbor candidate object in root node.
 239    *
 240    * The DFS algorithm in the method is implemented in iterative way.
 241    * @param root The accessible root object
 242    * @param start The start node
 243    * @param forward If forward is 1, then it navigates forward, otherwise backward.
 244    * @param searchMode BridgeAccessible::NeighborSearchMode  enum
 245    * @return The neighbor Accessible object
 246    */
 247   Dali::Accessibility::Accessible* CalculateNeighbor(Dali::Accessibility::Accessible* root, Dali::Accessibility::Accessible* start, unsigned char forward, NeighborSearchMode searchMode);
 248
 249   /**
 250    * @brief Gets valid children accessible.
 251    *
 252    * @param[in] children Children accessible objects
 253    * @param start The start node
 254    * @return The valid children
 255    */
 256   std::vector<Dali::Accessibility::Component*> GetValidChildren(const std::vector<Dali::Accessibility::Accessible*>& children, Dali::Accessibility::Accessible* start);
 257
 258   /**
 259    * @brief Sorts children accessible based on the coordinates from top-left to bottom-right.
 260    *
 261    * @param[in,out] children Children accessible objects
 262    * @return The sorted children
 263    */
 264   void SortChildrenFromTopLeft(std::vector<Dali::Accessibility::Component*>& children);
 265
 266   /**
 267    * @brief Gets the currently highlighted accessible.
 268    *
 269    * @return The highlighted accessible
 270    * @remarks This is an experimental feature and might not be supported now.
 271    */
 272   Dali::Accessibility::Accessible* GetCurrentlyHighlighted();
 273
 274   /**
 275    * @brief Finds the non defunct sibling of the node.
 276    *
 277    * @param[out] areAllChildrenVisited True if all children are visited
 278    * @param[in] node The accessible object to find its non defunct sibling
 279    * @param[in] start The start node
 280    * @param[in] root The root node
 281    * @param[in] forward If forward is 1, then it navigates forward, otherwise backward.
 282    * @return The non defunct sibling accessible
 283    *
 284    * @note This function performs a Depth-First Search (DFS) on all children within the node.
 285    */
 286   Dali::Accessibility::Accessible* FindNonDefunctSibling(bool& areAllChildrenVisited, Dali::Accessibility::Accessible* node, Dali::Accessibility::Accessible* start, Dali::Accessibility::Accessible* root, unsigned char forward);
 287
 288   /**
 289    * @brief Gets the next non defunct sibling.
 290    *
 291    * @param obj The accessible object to find its non defunct sibling
 292    * @param start The start node
 293    * @param forward If forward is 1, then it navigates forward, otherwise backward.
 294    * @return The non defunct sibling accessible
 295    */
 296   Dali::Accessibility::Accessible* GetNextNonDefunctSibling(Dali::Accessibility::Accessible* obj, Dali::Accessibility::Accessible* start, unsigned char forward);
 297
 298   /**
 299    * @brief Gets Component object in relation.
 300    * @param obj The accessible object to find component in its address
 301    * @param relationType Accessibility::RelationType enum
 302    * @return The Component object
 303    */
 304   Dali::Accessibility::Component* GetObjectInRelation(Dali::Accessibility::Accessible* obj, Dali::Accessibility::RelationType relationType);
 305
 306   /**
 307    * @brief Calculates and gets Component object that can be navigable at given coordinates.
 308    *
 309    * This method calculates which Component should be addressed if user hits certain point in a screen.
 310    * @param root The root node
 311    * @param point The coordinate of a point
 312    * @param type This type says if the coordinates of a point refer to the device screen or current window.
 313    * @param maxRecursionDepth The maximum recursion depth count
 314    * @return The Component object
 315    */
 316   Dali::Accessibility::Component* CalculateNavigableAccessibleAtPoint(Dali::Accessibility::Accessible* root, Dali::Accessibility::Point point, Dali::Accessibility::CoordinateType type, unsigned int maxRecursionDepth);
 317 };
 318
 319 #endif // DALI_INTERNAL_ACCESSIBILITY_BRIDGE_ACCESSIBLE_H