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