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