dali/devel-api/adaptor-framework/accessibility.h

   1 #ifndef DALI_ATSPI_ACCESSIBILITY_H\r
   2 #define DALI_ATSPI_ACCESSIBILITY_H\r
   3 /*\r
   4  * Copyright (c) 2021 Samsung Electronics Co., Ltd.\r
   5  *\r
   6  * Licensed under the Apache License, Version 2.0 (the "License");\r
   7  * you may not use this file except in compliance with the License.\r
   8  * You may obtain a copy of the License at\r
   9  *\r
  10  * http://www.apache.org/licenses/LICENSE-2.0\r
  11  *\r
  12  * Unless required by applicable law or agreed to in writing, software\r
  13  * distributed under the License is distributed on an "AS IS" BASIS,\r
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  15  * See the License for the specific language governing permissions and\r
  16  * limitations under the License.\r
  17  *\r
  18  */\r
  19 \r
  20 // EXTERNAL INCLUDES\r
  21 #include <string>\r
  22 #include <unordered_map>\r
  23 #include <vector>\r
  24 \r
  25 // INTERNAL INCLUDES\r
  26 #include <dali/devel-api/adaptor-framework/accessibility-bitset.h>\r
  27 #include <dali/public-api/dali-adaptor-common.h>\r
  28 \r
  29 namespace Dali\r
  30 {\r
  31 namespace Accessibility\r
  32 {\r
  33 /**\r
  34  * @brief Enumeration describing type of object move relative to the screen. Only outgoing moves are signalled to AT-clients.\r
  35  */\r
  36 enum class ScreenRelativeMoveType\r
  37 {\r
  38   OUTSIDE               = 0, ///< Object moves outside of the screen\r
  39   OUTGOING_TOP_LEFT     = 1, ///< Object moves out through the top(or left) side of the screen. Maps to: ATSPI_MOVE_OUTED_TOP_LEFT\r
  40   OUTGOING_BOTTOM_RIGHT = 2, ///< Object moves out through the bottom(or right) side of the screen. Maps to: ATSPI_MOVE_OUTED_BOTTOM_RIGHT\r
  41   INSIDE                     ///< Object moves into the screen or moves inside the screen\r
  42 };\r
  43 \r
  44 /**\r
  45  * @brief Enumeration describing a relation between accessible objects\r
  46  * 1 to 0..N relation model is supported. By default relation is not symmetrical.\r
  47  * Symmetry must be explicitly maintained.\r
  48  */\r
  49 enum class RelationType : uint32_t\r
  50 {\r
  51   NULL_OF,          ///< Null Relation.\r
  52   LABEL_FOR,        ///< Label For.\r
  53   LABELLED_BY,      ///< Labelled By.\r
  54   CONTROLLER_FOR,   ///< Controller For.\r
  55   CONTROLLED_BY,    ///< Controlled By.\r
  56   MEMBER_OF,        ///< Member Of.\r
  57   TOOLTIP_FOR,      ///< ToolTip For.\r
  58   NODE_CHILD_OF,    ///< Node Child Of.\r
  59   NODE_PARENT_OF,   ///< Node Parent Of.\r
  60   EXTENDED,         ///< Extended.\r
  61   FLOWS_TO,         ///< Flows To.\r
  62   FLOWS_FROM,       ///< Flows From.\r
  63   SUBWINDOW_OF,     ///< Sub Window Of.\r
  64   EMBEDS,           ///< Embeds.\r
  65   EMBEDDED_BY,      ///< Embedded By.\r
  66   POPUP_FOR,        ///< Popup For\r
  67   PARENT_WINDOW_OF, ///< Parent Window Of.\r
  68   DESCRIPTION_FOR,  ///< Description For.\r
  69   DESCRIBED_BY,     ///< Described By.\r
  70   DETAILS,          ///< Details.\r
  71   DETAILS_FOR,      ///< Details For.\r
  72   ERROR_MESSAGE,    ///< Error Message.\r
  73   ERROR_FOR,        ///< Error For.\r
  74   MAX_COUNT\r
  75 };\r
  76 \r
  77 /**\r
  78  * @brief Enumeration describing if coordinates are relative to screen or window\r
  79  * @see Accessibility::Component::GetExtents\r
  80  * @see Accessibility::Component::IsAccessibleContainingPoint\r
  81  */\r
  82 enum class CoordinateType\r
  83 {\r
  84   SCREEN, ///< Screen.\r
  85   WINDOW  ///< Window.\r
  86 };\r
  87 \r
  88 /**\r
  89  * @brief Enumeration indicating relative stacking order\r
  90  * ComponentLayer allows to describe visibility of all parts of UI\r
  91  * basing on the concrete stacking order\r
  92  * @see Accessibility::Component::GetLayer\r
  93  * @note currently only ComponentLayer::Window is supported\r
  94  */\r
  95 enum class ComponentLayer\r
  96 {\r
  97   INVALID,    ///< Invalid.\r
  98   BACKGROUND, ///< Background.\r
  99   CANVAS,     ///< Canvas.\r
 100   WIDGET,     ///< Widget.\r
 101   MDI,        ///< MDI.\r
 102   POPUP,      ///< Popup.\r
 103   OVERLAY,    ///< Overlay.\r
 104   WINDOW,     ///< Window.\r
 105   MAX_COUNT\r
 106 };\r
 107 \r
 108 /**\r
 109  * @brief Enumeration describing role of the Accessibility object\r
 110  * Object can be described by only one role.\r
 111  * @see Accessibility::Accessible::GetRole\r
 112  */\r
 113 enum class Role : uint32_t\r
 114 {\r
 115   INVALID,\r
 116   ACCELERATOR_LABEL,\r
 117   ALERT,\r
 118   ANIMATION,\r
 119   ARROW,\r
 120   CALENDAR,\r
 121   CANVAS,\r
 122   CHECK_BOX,\r
 123   CHECK_MENU_ITEM,\r
 124   COLOR_CHOOSER,\r
 125   COLUMN_HEADER,\r
 126   COMBO_BOX,\r
 127   DATE_EDITOR,\r
 128   DESKTOP_ICON,\r
 129   DESKTOP_FRAME,\r
 130   DIAL,\r
 131   DIALOG,\r
 132   DIRECTORY_PANE,\r
 133   DRAWING_AREA,\r
 134   FILE_CHOOSER,\r
 135   FILLER,\r
 136   FOCUS_TRAVERSABLE,\r
 137   FONT_CHOOSER,\r
 138   FRAME,\r
 139   GLASS_PANE,\r
 140   HTML_CONTAINER,\r
 141   ICON,\r
 142   IMAGE,\r
 143   INTERNAL_FRAME,\r
 144   LABEL,\r
 145   LAYERED_PANE,\r
 146   LIST,\r
 147   LIST_ITEM,\r
 148   MENU,\r
 149   MENU_BAR,\r
 150   MENU_ITEM,\r
 151   OPTION_PANE,\r
 152   PAGE_TAB,\r
 153   PAGE_TAB_LIST,\r
 154   PANEL,\r
 155   PASSWORD_TEXT,\r
 156   POPUP_MENU,\r
 157   PROGRESS_BAR,\r
 158   PUSH_BUTTON,\r
 159   RADIO_BUTTON,\r
 160   RADIO_MENU_ITEM,\r
 161   ROOT_PANE,\r
 162   ROW_HEADER,\r
 163   SCROLL_BAR,\r
 164   SCROLL_PANE,\r
 165   SEPARATOR,\r
 166   SLIDER,\r
 167   SPIN_BUTTON,\r
 168   SPLIT_PANE,\r
 169   STATUS_BAR,\r
 170   TABLE,\r
 171   TABLE_CELL,\r
 172   TABLE_COLUMN_HEADER,\r
 173   TABLE_ROW_HEADER,\r
 174   TEAROFF_MENU_ITEM,\r
 175   TERMINAL,\r
 176   TEXT,\r
 177   TOGGLE_BUTTON,\r
 178   TOOL_BAR,\r
 179   TOOL_TIP,\r
 180   TREE,\r
 181   TREE_TABLE,\r
 182   UNKNOWN,\r
 183   VIEWPORT,\r
 184   WINDOW,\r
 185   EXTENDED,\r
 186   HEADER,\r
 187   FOOTER,\r
 188   PARAGRAPH,\r
 189   RULER,\r
 190   APPLICATION,\r
 191   AUTOCOMPLETE,\r
 192   EDITBAR,\r
 193   EMBEDDED,\r
 194   ENTRY,\r
 195   CHART,\r
 196   CAPTION,\r
 197   DOCUMENT_FRAME,\r
 198   HEADING,\r
 199   PAGE,\r
 200   SECTION,\r
 201   REDUNDANT_OBJECT,\r
 202   FORM,\r
 203   LINK,\r
 204   INPUT_METHOD_WINDOW,\r
 205   TABLE_ROW,\r
 206   TREE_ITEM,\r
 207   DOCUMENT_SPREADSHEET,\r
 208   DOCUMENT_PRESENTATION,\r
 209   DOCUMENT_TEXT,\r
 210   DOCUMENT_WEB,\r
 211   DOCUMENT_EMAIL,\r
 212   COMMENT,\r
 213   LIST_BOX,\r
 214   GROUPING,\r
 215   IMAGE_MAP,\r
 216   NOTIFICATION,\r
 217   INFO_BAR,\r
 218   LEVEL_BAR,\r
 219   TITLE_BAR,\r
 220   BLOCK_QUOTE,\r
 221   AUDIO,\r
 222   VIDEO,\r
 223   DEFINITION,\r
 224   ARTICLE,\r
 225   LANDMARK,\r
 226   LOG,\r
 227   MARQUEE,\r
 228   MATH,\r
 229   RATING,\r
 230   TIMER,\r
 231   STATIC,\r
 232   MATH_FRACTION,\r
 233   MATH_ROOT,\r
 234   SUBSCRIPT,\r
 235   SUPERSCRIPT,\r
 236   MAX_COUNT\r
 237 };\r
 238 \r
 239 /**\r
 240  * @brief Enumeration describing states of the Accessibility object\r
 241  * Object can be in many states at the same time.\r
 242  * @see Accessibility::Accessible::GetStates\r
 243  */\r
 244 enum class State : uint32_t\r
 245 {\r
 246   INVALID,\r
 247   ACTIVE,\r
 248   ARMED,\r
 249   BUSY,\r
 250   CHECKED,\r
 251   COLLAPSED,\r
 252   DEFUNCT,\r
 253   EDITABLE,\r
 254   ENABLED,\r
 255   EXPANDABLE,\r
 256   EXPANDED,\r
 257   FOCUSABLE,\r
 258   FOCUSED,\r
 259   HAS_TOOLTIP,\r
 260   HORIZONTAL,\r
 261   ICONIFIED,\r
 262   MODAL,\r
 263   MULTI_LINE,\r
 264   MULTI_SELECTABLE,\r
 265   OPAQUE,\r
 266   PRESSED,\r
 267   RESIZEABLE,\r
 268   SELECTABLE,\r
 269   SELECTED,\r
 270   SENSITIVE,\r
 271   SHOWING,\r
 272   SINGLE_LINE,\r
 273   STALE,\r
 274   TRANSIENT,\r
 275   VERTICAL,\r
 276   VISIBLE,\r
 277   MANAGES_DESCENDANTS,\r
 278   INDETERMINATE,\r
 279   REQUIRED,\r
 280   TRUNCATED,\r
 281   ANIMATED,\r
 282   INVALID_ENTRY,\r
 283   SUPPORTS_AUTOCOMPLETION,\r
 284   SELECTABLE_TEXT,\r
 285   IS_DEFAULT,\r
 286   VISITED,\r
 287   CHECKABLE,\r
 288   HAS_POPUP,\r
 289   READ_ONLY,\r
 290   HIGHLIGHTED,\r
 291   HIGHLIGHTABLE,\r
 292   MAX_COUNT\r
 293 };\r
 294 \r
 295 /**\r
 296  * @brief Enumeration describing change of text object\r
 297  */\r
 298 enum class TextChangedState : uint32_t\r
 299 {\r
 300   INSERTED,\r
 301   DELETED,\r
 302   MAX_COUNT\r
 303 };\r
 304 \r
 305 /**\r
 306  * @brief Enumeration describing change of object property\r
 307  */\r
 308 enum class ObjectPropertyChangeEvent\r
 309 {\r
 310   NAME,\r
 311   DESCRIPTION,\r
 312   VALUE,\r
 313   ROLE,\r
 314   PARENT,\r
 315 };\r
 316 \r
 317 /**\r
 318  * @brief Enumeration describing change of window object\r
 319  * @see Accessibility::Accessible::Emit\r
 320  */\r
 321 enum class WindowEvent\r
 322 {\r
 323   PROPERTY_CHANGE,\r
 324   MINIMIZE,\r
 325   MAXIMIZE,\r
 326   RESTORE,\r
 327   CLOSE,\r
 328   CREATE,\r
 329   REPARENT,\r
 330   DESKTOP_CREATE,\r
 331   DESKTOP_DESTROY,\r
 332   DESTROY,\r
 333   ACTIVATE,\r
 334   DEACTIVATE,\r
 335   RAISE,\r
 336   LOWER,\r
 337   MOVE,\r
 338   RESIZE,\r
 339   SHADE,\r
 340   UU_SHADE,\r
 341   RESTYLE,\r
 342 };\r
 343 \r
 344 /**\r
 345  * @brief Enumeration used to acquire bounded text from accessible object having textual content.\r
 346  * @see Accessibility::Text::GetTextAtOffset\r
 347  * @note Currently only TextBoundary::Character is supported\r
 348  */\r
 349 enum class TextBoundary : uint32_t\r
 350 {\r
 351   CHARACTER, ///> Only one character is acquired.\r
 352   WORD,      ///> Not supported.\r
 353   SENTENCE,  ///> Not supported.\r
 354   LINE,      ///> Not supported.\r
 355   PARAGRAPH, ///> Not supported.\r
 356   MAX_COUNT\r
 357 };\r
 358 \r
 359 /**\r
 360  * @brief Enumeration describing type of gesture\r
 361  * @see Accessibility::Accessible::DoGesture\r
 362  */\r
 363 enum class Gesture : int32_t\r
 364 {\r
 365   ONE_FINGER_HOVER,\r
 366   TWO_FINGER_HOVER,\r
 367   THREE_FINGER_HOVER,\r
 368   ONE_FINGER_FLICK_LEFT,\r
 369   ONE_FINGER_FLICK_RIGHT,\r
 370   ONE_FINGER_FLICK_UP,\r
 371   ONE_FINGER_FLICK_DOWN,\r
 372   TWO_FINGERS_FLICK_LEFT,\r
 373   TWO_FINGERS_FLICK_RIGHT,\r
 374   TWO_FINGERS_FLICK_UP,\r
 375   TWO_FINGERS_FLICK_DOWN,\r
 376   THREE_FINGERS_FLICK_LEFT,\r
 377   THREE_FINGERS_FLICK_RIGHT,\r
 378   THREE_FINGERS_FLICK_UP,\r
 379   THREE_FINGERS_FLICK_DOWN,\r
 380   ONE_FINGER_SINGLE_TAP,\r
 381   ONE_FINGER_DOUBLE_TAP,\r
 382   ONE_FINGER_TRIPLE_TAP,\r
 383   TWO_FINGERS_SINGLE_TAP,\r
 384   TWO_FINGERS_DOUBLE_TAP,\r
 385   TWO_FINGERS_TRIPLE_TAP,\r
 386   THREE_FINGERS_SINGLE_TAP,\r
 387   THREE_FINGERS_DOUBLE_TAP,\r
 388   THREE_FINGERS_TRIPLE_TAP,\r
 389   ONE_FINGER_FLICK_LEFT_RETURN,\r
 390   ONE_FINGER_FLICK_RIGHT_RETURN,\r
 391   ONE_FINGER_FLICK_UP_RETURN,\r
 392   ONE_FINGER_FLICK_DOWN_RETURN,\r
 393   TWO_FINGERS_FLICK_LEFT_RETURN,\r
 394   TWO_FINGERS_FLICK_RIGHT_RETURN,\r
 395   TWO_FINGERS_FLICK_UP_RETURN,\r
 396   TWO_FINGERS_FLICK_DOWN_RETURN,\r
 397   THREE_FINGERS_FLICK_LEFT_RETURN,\r
 398   THREE_FINGERS_FLICK_RIGHT_RETURN,\r
 399   THREE_FINGERS_FLICK_UP_RETURN,\r
 400   THREE_FINGERS_FLICK_DOWN_RETURN,\r
 401   ONE_FINGER_DOUBLE_TAP_N_HOLD,\r
 402   TWO_FINGERS_DOUBLE_TAP_N_HOLD,\r
 403   THREE_FINGERS_DOUBLE_TAP_N_HOLD,\r
 404   MAX_COUNT\r
 405 };\r
 406 \r
 407 /**\r
 408  * @brief Enumeration indicating current state of gesture\r
 409  * @see Dali::Accessibility::GestureInfo\r
 410  */\r
 411 enum class GestureState : int32_t\r
 412 {\r
 413   BEGIN,\r
 414   ONGOING,\r
 415   ENDED,\r
 416   ABORTED\r
 417 };\r
 418 \r
 419 /**\r
 420  * @brief Enumeration of ReadingInfoType\r
 421  */\r
 422 enum class ReadingInfoType\r
 423 {\r
 424   NAME,\r
 425   ROLE,\r
 426   DESCRIPTION,\r
 427   STATE,\r
 428   MAX_COUNT\r
 429 };\r
 430 \r
 431 using ReadingInfoTypes = EnumBitSet<ReadingInfoType, ReadingInfoType::MAX_COUNT>;\r
 432 using States           = EnumBitSet<State, State::MAX_COUNT>;\r
 433 using Attributes       = std::unordered_map<std::string, std::string>;\r
 434 \r
 435 /**\r
 436  * @brief Class representing unique object address on accessibility bus\r
 437  * @see Dali::Accessibility::Accessible::GetAddress\r
 438  */\r
 439 class DALI_ADAPTOR_API Address\r
 440 {\r
 441 public:\r
 442   Address() = default;\r
 443 \r
 444   Address(std::string bus, std::string path)\r
 445   : mBus(std::move(bus)),\r
 446     mPath(std::move(path))\r
 447   {\r
 448   }\r
 449 \r
 450   explicit operator bool() const\r
 451   {\r
 452     return !mPath.empty();\r
 453   }\r
 454 \r
 455   std::string ToString() const\r
 456   {\r
 457     return *this ? mBus + ":" + mPath : "::null";\r
 458   }\r
 459 \r
 460   const std::string& GetBus() const;\r
 461 \r
 462   const std::string& GetPath() const\r
 463   {\r
 464     return mPath;\r
 465   }\r
 466 \r
 467   bool operator==(const Address& a) const\r
 468   {\r
 469     return mBus == a.mBus && mPath == a.mPath;\r
 470   }\r
 471 \r
 472   bool operator!=(const Address& a) const\r
 473   {\r
 474     return !(*this == a);\r
 475   }\r
 476 \r
 477 private:\r
 478   mutable std::string mBus, mPath;\r
 479 };\r
 480 \r
 481 /**\r
 482  * @brief Enumeration describing type of key event\r
 483  * @see Adaptor::AccessibilityObserver::OnAccessibleKeyEvent\r
 484  */\r
 485 enum class KeyEventType\r
 486 {\r
 487   KEY_PRESSED,\r
 488   KEY_RELEASED,\r
 489 };\r
 490 \r
 491 /**\r
 492  * @brief Enumeration with human readable values describing state of event\r
 493  * @see Dali::Accessibility::Bridge::Emit\r
 494  */\r
 495 enum class Consumed\r
 496 {\r
 497   NO,\r
 498   YES\r
 499 };\r
 500 \r
 501 /**\r
 502  * @brief Helper class representing two dimensional point with integer coordinates\r
 503  */\r
 504 struct DALI_ADAPTOR_API Point\r
 505 {\r
 506   int x = 0;\r
 507   int y = 0;\r
 508 \r
 509   Point() = default;\r
 510 \r
 511   Point(int x, int y)\r
 512   : x(x),\r
 513     y(y)\r
 514   {\r
 515   }\r
 516 \r
 517   bool operator==(Point p) const\r
 518   {\r
 519     return x == p.x && y == p.y;\r
 520   }\r
 521   bool operator!=(Point p) const\r
 522   {\r
 523     return !(*this == p);\r
 524   }\r
 525 };\r
 526 \r
 527 /**\r
 528 * @brief Helper class representing size of rectangle object with usage of two integer values\r
 529 */\r
 530 struct DALI_ADAPTOR_API Size\r
 531 {\r
 532   int width  = 0;\r
 533   int height = 0;\r
 534 \r
 535   Size() = default;\r
 536 \r
 537   Size(int w, int h)\r
 538   : width(w),\r
 539     height(h)\r
 540   {\r
 541   }\r
 542 \r
 543   bool operator==(Size p) const\r
 544   {\r
 545     return width == p.width && height == p.height;\r
 546   }\r
 547 \r
 548   bool operator!=(Size p) const\r
 549   {\r
 550     return !(*this == p);\r
 551   }\r
 552 };\r
 553 \r
 554 /**\r
 555  * @brief Helper class used to store data related with Accessibility::Text interface\r
 556  * @see Dali::Accessibility::Text::GetTextAtOffset\r
 557  * @see Dali::Accessibility::Text::GetRangeOfSelection\r
 558  */\r
 559 struct DALI_ADAPTOR_API Range\r
 560 {\r
 561   int32_t     startOffset = 0;\r
 562   int32_t     endOffset   = 0;\r
 563   std::string content;\r
 564 \r
 565   Range() = default;\r
 566 \r
 567   Range(size_t start, size_t end)\r
 568   : startOffset(start),\r
 569     endOffset(end)\r
 570   {\r
 571   }\r
 572 \r
 573   Range(size_t start, size_t end, std::string content)\r
 574   : startOffset(start),\r
 575     endOffset(end),\r
 576     content(content)\r
 577   {\r
 578   }\r
 579 };\r
 580 \r
 581 /**\r
 582  * @brief Structure containing all values needed to invoke Accessible::DoGesture\r
 583  * type : numerated gesture type\r
 584  * startPositionX, startPositionY : point where gesture begins\r
 585  * endPositionX, endPositionY : point where gesture ends\r
 586  * state : enumerated state of gesture\r
 587  * eventTime : time when event occured\r
 588  * @see Dali::Accessibility::Accessible::DoGesture\r
 589  */\r
 590 struct DALI_ADAPTOR_API GestureInfo\r
 591 {\r
 592   GestureInfo() = default;\r
 593   GestureInfo(Gesture type, int32_t startPositionX, int32_t endPositionX, int32_t startPositionY, int32_t endPositionY, GestureState state, uint32_t eventTime)\r
 594   : type(type),\r
 595     startPointX(startPositionX),\r
 596     endPointX(endPositionX),\r
 597     startPointY(startPositionY),\r
 598     endPointY(endPositionY),\r
 599     state(state),\r
 600     eventTime(eventTime)\r
 601   {\r
 602   }\r
 603 \r
 604   Gesture      type{};\r
 605   int32_t      startPointX{};\r
 606   int32_t      endPointX{};\r
 607   int32_t      startPointY{};\r
 608   int32_t      endPointY{};\r
 609   GestureState state{};\r
 610   uint32_t     eventTime{};\r
 611 };\r
 612 \r
 613 /**\r
 614  * @brief Class representing accessibility relations\r
 615  * Class connecting one source object with multiple target objects with usage\r
 616  * of specific relation type.\r
 617  * @note std::string representing source and targets are string values of Accessibility::Address\r
 618  * @see Dali::Accessibility::Accessible::Address\r
 619  * @see Dali::Accessibility::Accessible::RelationType\r
 620  */\r
 621 struct DALI_ADAPTOR_API Relation\r
 622 {\r
 623   Relation(RelationType relationType, std::vector<Address> targets)\r
 624   : relationType(relationType),\r
 625     targets(targets)\r
 626   {\r
 627   }\r
 628 \r
 629   RelationType         relationType;\r
 630   std::vector<Address> targets;\r
 631 };\r
 632 \r
 633 } // namespace Accessibility\r
 634 } // namespace Dali\r
 635 \r
 636 #endif // DALI_ATSPI_ACCESSIBILITY_H\r