b373cc77632cc497cc072b20390c00ac2b2f5b54
[platform/core/uifw/dali-adaptor.git] / dali / public-api / adaptor-framework / accessibility.h
1 #ifndef DALI_ACCESSIBILITY_H
2 #define DALI_ACCESSIBILITY_H
3
4 /*
5  * Copyright (c) 2019 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 <dali/public-api/actors/actor.h>
23 #include <dali/public-api/math/rect.h>
24
25 #include <atomic>
26 #include <bitset>
27 #include <exception>
28 #include <functional>
29 #include <memory>
30 #include <string>
31 #include <map>
32 #include <unordered_map>
33 #include <vector>
34 #include <list>
35 #include <cassert>
36 #include <sstream>
37 #include <string.h>
38
39 // INTERNAL INCLUDES
40 #include <dali/public-api/dali-adaptor-common.h>
41
42 namespace Dali
43 {
44 /**
45  * @addtogroup dali_adaptor_framework
46  * @{
47  */
48 class Actor;
49
50 namespace Accessibility
51 {
52
53 /**
54  * @brief Enumeration describing a relation between accessible objects
55  *
56  * 1 to 0..N relation model is supported. By default relation is not symmetrical.
57  * Symmetry must be explicitly maintained.
58  */
59 enum class RelationType : uint32_t
60 {
61   NULL_,
62   LABEL_FOR,
63   LABELLED_BY,
64   CONTROLLER_FOR,
65   CONTROLLED_BY,
66   MEMBER_OF,
67   TOOLTIP_FOR,
68   NODE_CHILD_OF,
69   NODE_PARENT_OF,
70   EXTENDED,
71   FLOWS_TO,
72   FLOWS_FROM,
73   SUBWINDOW_OF,
74   EMBEDS,
75   EMBEDDED_BY,
76   POPUP_FOR,
77   PARENT_WINDOW_OF,
78   DESCRIPTION_FOR,
79   DESCRIBED_BY,
80   DETAILS,
81   DETAILS_FOR,
82   ERROR_MESSAGE,
83   ERROR_FOR,
84   LAST_DEFINED
85 };
86
87 /**
88  * @brief Enumeration describing if coordinates are relative to screen or window
89  *
90  * @see Accessibility::Component::GetExtents
91  * @see Accessibility::Component::Contains
92  */
93 enum class CoordType
94 {
95   SCREEN,
96   WINDOW
97 };
98
99 /**
100  * @brief Enumeration indicating relative stacking order
101  *
102  * ComponentLayer allows to describe visibility of all parts of UI
103  * basing on the concrete stacking order
104  *
105  * @see Accessibility::Component::GetLayer
106  *
107  * @note currently only ComponentLayer::Window is supported
108  */
109 enum class ComponentLayer
110 {
111   INVALID,
112   BACKGROUND,
113   CANVAS,
114   WIDGET,
115   MDI,
116   POPUP,
117   OVERLAY,
118   WINDOW,
119   LAST_DEFINED,
120 };
121
122 /**
123  * @brief Enumeration describing role of the Accessibility object
124  *
125  * Object can be described by only one role.
126  *
127  * @see Accessibility::Accessible::GetRole
128  */
129 enum class Role : uint32_t
130 {
131   INVALID,
132   ACCELERATOR_LABEL,
133   ALERT,
134   ANIMATION,
135   ARROW,
136   CALENDAR,
137   CANVAS,
138   CHECK_BOX,
139   CHECK_MENU_ITEM,
140   COLOR_CHOOSER,
141   COLUMN_HEADER,
142   COMBO_BOX,
143   DATE_EDITOR,
144   DESKTOP_ICON,
145   DESKTOP_FRAME,
146   DIAL,
147   DIALOG,
148   DIRECTORY_PANE,
149   DRAWING_AREA,
150   FILE_CHOOSER,
151   FILLER,
152   FOCUS_TRAVERSABLE,
153   FONT_CHOOSER,
154   FRAME,
155   GLASS_PANE,
156   HTML_CONTAINER,
157   ICON,
158   IMAGE,
159   INTERNAL_FRAME,
160   LABEL,
161   LAYERED_PANE,
162   LIST,
163   LIST_ITEM,
164   MENU,
165   MENU_BAR,
166   MENU_ITEM,
167   OPTION_PANE,
168   PAGE_TAB,
169   PAGE_TAB_LIST,
170   PANEL,
171   PASSWORD_TEXT,
172   POPUP_MENU,
173   PROGRESS_BAR,
174   PUSH_BUTTON,
175   RADIO_BUTTON,
176   RADIO_MENU_ITEM,
177   ROOT_PANE,
178   ROW_HEADER,
179   SCROLL_BAR,
180   SCROLL_PANE,
181   SEPARATOR,
182   SLIDER,
183   SPIN_BUTTON,
184   SPLIT_PANE,
185   STATUS_BAR,
186   TABLE,
187   TABLE_CELL,
188   TABLE_COLUMN_HEADER,
189   TABLE_ROW_HEADER,
190   TEAROFF_MENU_ITEM,
191   TERMINAL,
192   TEXT,
193   TOGGLE_BUTTON,
194   TOOL_BAR,
195   TOOL_TIP,
196   TREE,
197   TREE_TABLE,
198   UNKNOWN,
199   VIEWPORT,
200   WINDOW,
201   EXTENDED,
202   HEADER,
203   FOOTER,
204   PARAGRAPH,
205   RULER,
206   APPLICATION,
207   AUTOCOMPLETE,
208   EDITBAR,
209   EMBEDDED,
210   ENTRY,
211   CHART,
212   CAPTION,
213   DOCUMENT_FRAME,
214   HEADING,
215   PAGE,
216   SECTION,
217   REDUNDANT_OBJECT,
218   FORM,
219   LINK,
220   INPUT_METHOD_WINDOW,
221   TABLE_ROW,
222   TREE_ITEM,
223   DOCUMENT_SPREADSHEET,
224   DOCUMENT_PRESENTATION,
225   DOCUMENT_TEXT,
226   DOCUMENT_WEB,
227   DOCUMENT_EMAIL,
228   COMMENT,
229   LIST_BOX,
230   GROUPING,
231   IMAGE_MAP,
232   NOTIFICATION,
233   INFO_BAR,
234   LEVEL_BAR,
235   TITLE_BAR,
236   BLOCK_QUOTE,
237   AUDIO,
238   VIDEO,
239   DEFINITION,
240   ARTICLE,
241   LANDMARK,
242   LOG,
243   MARQUEE,
244   MATH,
245   RATING,
246   TIMER,
247   STATIC,
248   MATH_FRACTION,
249   MATH_ROOT,
250   SUBSCRIPT,
251   SUPERSCRIPT,
252   _COUNT,
253 };
254
255 /**
256  * @brief Enumeration describing states of the Accessibility object
257  *
258  * Object can be in many states at the same time.
259  *
260  * @see Accessibility::Accessible::GetStates
261  */
262 enum class State : uint32_t
263 {
264   INVALID,
265   ACTIVE,
266   ARMED,
267   BUSY,
268   CHECKED,
269   COLLAPSED,
270   DEFUNCT,
271   EDITABLE,
272   ENABLED,
273   EXPANDABLE,
274   EXPANDED,
275   FOCUSABLE,
276   FOCUSED,
277   HAS_TOOLTIP,
278   HORIZONTAL,
279   ICONIFIED,
280   MODAL,
281   MULTI_LINE,
282   MULTI_SELECTABLE,
283   OPAQUE,
284   PRESSED,
285   RESIZEABLE,
286   SELECTABLE,
287   SELECTED,
288   SENSITIVE,
289   SHOWING,
290   SINGLE_LINE,
291   STALE,
292   TRANSIENT,
293   VERTICAL,
294   VISIBLE,
295   MANAGES_DESCENDANTS,
296   INDETERMINATE,
297   REQUIRED,
298   TRUNCATED,
299   ANIMATED,
300   INVALID_ENTRY,
301   SUPPORTS_AUTOCOMPLETION,
302   SELECTABLE_TEXT,
303   IS_DEFAULT,
304   VISITED,
305   CHECKABLE,
306   HAS_POPUP,
307   READ_ONLY,
308   HIGHLIGHTED,
309   HIGHLIGHTABLE,
310   _COUNT
311 };
312
313 /**
314  * @brief Enumeration describing change of text object
315  */
316 enum class TextChangedState : uint32_t
317 {
318   INSERT,
319   DELETE,
320   _COUNT
321 };
322
323 enum class ObjectPropertyChangeEvent {
324    NAME,
325    DESCRIPTION,
326    VALUE,
327    ROLE,
328    PARENT,
329 };
330
331 /**
332  * @brief Enumeration describing change of window object
333  *
334  * @see Accessibility::Accessible::Emit
335  */
336 enum class WindowEvent
337 {
338   PROPERTY_CHANGE,
339   MINIMIZE,
340   MAXIMIZE,
341   RESTORE,
342   CLOSE,
343   CREATE,
344   REPARENT,
345   DESKTOP_CREATE,
346   DESKTOP_DESTROY,
347   DESTROY,
348   ACTIVATE,
349   DEACTIVATE,
350   RAISE,
351   LOWER,
352   MOVE,
353   RESIZE,
354   SHADE,
355   UU_SHADE,
356   RESTYLE,
357 };
358
359 /**
360  * @brief Enumeration used to acquire bounded text from accessible object having textual content.
361  *
362  * @see Accessibility::Text::GetTextAtOffset
363  *
364  * @note Currently only TextBoundary::Character is supported
365  */
366 enum class TextBoundary : uint32_t
367 {
368   /**
369    * Only one character is acquired.
370    */
371   CHARACTER,
372
373   /**
374    * Not supported.
375    */
376   WORD,
377
378   /**
379    * Not supported.
380    */
381   SENTENCE,
382
383   /**
384    * Not supported.
385    */
386   LINE,
387
388   /**
389    * Not supported.
390    */
391   PARAGRAPH,
392   _COUNT
393 };
394
395 /**
396  * @brief Enumeration describing type of gesture
397  *
398  * @see Accessibility::Accessible::DoGesture
399  */
400 enum class Gesture : int32_t
401 {
402   ONE_FINGER_HOVER,
403   TWO_FINGER_HOVER,
404   THREE_FINGER_HOVER,
405   ONE_FINGER_FLICK_LEFT,
406   ONE_FINGER_FLICK_RIGHT,
407   ONE_FINGER_FLICK_UP,
408   ONE_FINGER_FLICK_DOWN,
409   TWO_FINGERS_FLICK_LEFT,
410   TWO_FINGERS_FLICK_RIGHT,
411   TWO_FINGERS_FLICK_UP,
412   TWO_FINGERS_FLICK_DOWN,
413   THREE_FINGERS_FLICK_LEFT,
414   THREE_FINGERS_FLICK_RIGHT,
415   THREE_FINGERS_FLICK_UP,
416   THREE_FINGERS_FLICK_DOWN,
417   ONE_FINGER_SINGLE_TAP,
418   ONE_FINGER_DOUBLE_TAP,
419   ONE_FINGER_TRIPLE_TAP,
420   TWO_FINGERS_SINGLE_TAP,
421   TWO_FINGERS_DOUBLE_TAP,
422   TWO_FINGERS_TRIPLE_TAP,
423   THREE_FINGERS_SINGLE_TAP,
424   THREE_FINGERS_DOUBLE_TAP,
425   THREE_FINGERS_TRIPLE_TAP,
426   ONE_FINGER_FLICK_LEFT_RETURN,
427   ONE_FINGER_FLICK_RIGHT_RETURN,
428   ONE_FINGER_FLICK_UP_RETURN,
429   ONE_FINGER_FLICK_DOWN_RETURN,
430   TWO_FINGERS_FLICK_LEFT_RETURN,
431   TWO_FINGERS_FLICK_RIGHT_RETURN,
432   TWO_FINGERS_FLICK_UP_RETURN,
433   TWO_FINGERS_FLICK_DOWN_RETURN,
434   THREE_FINGERS_FLICK_LEFT_RETURN,
435   THREE_FINGERS_FLICK_RIGHT_RETURN,
436   THREE_FINGERS_FLICK_UP_RETURN,
437   THREE_FINGERS_FLICK_DOWN_RETURN,
438   ONE_FINGER_DOUBLE_TAP_N_HOLD,
439   TWO_FINGERS_DOUBLE_TAP_N_HOLD,
440   THREE_FINGERS_DOUBLE_TAP_N_HOLD,
441   _COUNT
442 };
443
444 /**
445  * @brief Enumeration indicating current state of gesture
446  *
447  * @see Dali::Accessibility::GestureInfo
448  */
449 enum class GestureState : int32_t
450 {
451   BEGIN,
452   ONGOING,
453   ENDED,
454   ABORTED
455 };
456
457 enum class ReadingInfoType
458 {
459   NAME,
460   ROLE,
461   DESCRIPTION,
462   STATE
463 };
464
465 /**
466  * @brief Helper class for storing values treated as bit sets
467  *
468  * This class provides all bitset-like methods for bitset size larger, than long long int
469  *
470  * @see Dali::Accessibility::Accessible::GetStates
471  * @see Dali::Accessibility::Accessible::GetRoles
472  */
473 template < size_t I, typename S >
474 class BitSets
475 {
476   std::array< uint32_t, I > data;
477
478   void _set() { }
479   static constexpr bool _accepts() { return true; }
480   template < typename T > static constexpr bool _accepts()
481   {
482     return std::is_enum< T >::value;
483   }
484   template < typename T, typename T2, typename ... ARGS > static constexpr bool _accepts()
485   {
486     return std::is_enum< T >::value && _accepts< T2, ARGS... >();
487   }
488   template < typename T, typename ... ARGS > void _set( T t, ARGS ... args )
489   {
490     ( *this )[ t ] = true;
491     _set( args... );
492   }
493 public:
494   BitSets()
495   {
496     for( auto& u : data )
497       u = 0;
498   }
499   BitSets( const BitSets & ) = default;
500   BitSets( BitSets&& ) = default;
501   template < typename T, typename ... ARGS, typename std::enable_if< _accepts< T, ARGS... >() >::type* = nullptr >BitSets(T t, ARGS ... args) {
502     for(auto& u : data)
503       u = 0;
504     _set(t, args...);
505   }
506   explicit BitSets( std::array< uint32_t, I > d ) {
507     for( auto i = 0u; i < I; ++i )
508       data[ i ] = d[ i ];
509   }
510   explicit BitSets( std::array< int32_t, I > d ) {
511     for( auto i = 0u; i < I; ++i )
512       data[ i ] = static_cast< uint32_t >( d[ i ]);
513   }
514   BitSets &operator = ( const BitSets& ) = default;
515   BitSets &operator = ( BitSets&& ) = default;
516
517   struct reference
518   {
519     std::array< uint32_t, I >& data;
520     size_t pos;
521     reference &operator=( reference r )
522     {
523       ( *this ) = static_cast< bool >( r );
524       return *this;
525     }
526     reference &operator=( bool v )
527     {
528       if( v )
529         data[ pos / 32 ] |= 1 << ( pos & 31 );
530       else
531         data[ pos / 32 ] &= ~( 1 << ( pos & 31 ) );
532       return *this;
533     }
534     operator bool() const
535     {
536       auto i = static_cast< size_t >( pos );
537       return ( data[i / 32] & ( 1 << ( i & 31 ) ) ) != 0;
538     }
539   };
540   reference operator[]( S index ) { return {data, static_cast< size_t >( index )}; }
541   bool operator[]( S index ) const
542   {
543     auto i = static_cast< size_t >( index );
544     return ( data[i / 32] & ( 1 << ( i & 31 ) ) ) != 0;
545   }
546   std::array< uint32_t, I > GetRawData() const { return data; }
547
548   BitSets operator|( BitSets b ) const
549   {
550     BitSets r;
551     for( auto i = 0u; i < I; ++i )
552       r.data[i] = data[i] | b.data[i];
553     return r;
554   }
555   BitSets operator^( BitSets b ) const
556   {
557     BitSets r;
558     for( auto i = 0u; i < I; ++i )
559       r.data[i] = data[i] ^ b.data[i];
560     return r;
561   }
562   BitSets operator&( BitSets b ) const
563   {
564     BitSets r;
565     for( auto i = 0u; i < I; ++i )
566       r.data[i] = data[i] & b.data[i];
567     return r;
568   }
569   bool operator==( BitSets b ) const
570   {
571     for( auto i = 0u; i < I; ++i )
572       if( data[i] != b.data[i] )
573         return false;
574     return true;
575   }
576   bool operator!=( BitSets b ) const
577   {
578     return !((*this) == b);
579   }
580   explicit operator bool() const
581   {
582     for( auto& u : data )
583       if( u )
584         return true;
585     return false;
586   }
587   size_t size() const { return I; }
588 };
589
590 using ReadingInfoTypes = BitSets<1, ReadingInfoType>;
591 using States = BitSets< 2, State >;
592 using Attributes = std::unordered_map< std::string, std::string >;
593
594 /**
595  * @brief Class representing unique object address on accessibility bus
596  *
597  * @see Dali::Accessibility::Accessible::GetAddress
598  */
599 class DALI_ADAPTOR_API Address
600 {
601 public:
602   Address() = default;
603   Address( std::string bus, std::string path ) : bus( std::move( bus ) ), path( std::move( path ) ) {}
604
605   explicit operator bool() const { return !path.empty(); }
606   std::string ToString() const
607   {
608     return *this ? bus + ":" + path : "::null";
609   }
610   const std::string& GetBus() const;
611   const std::string& GetPath() const { return path; }
612
613   bool operator == (const Address &a) const {
614     return bus == a.bus && path == a.path;
615   }
616   bool operator != (const Address &a) const {
617     return !(*this == a);
618   }
619 private:
620   mutable std::string bus, path;
621 };
622
623 /**
624  * @brief Enumeration describing type of key event
625  *
626  * @see Adaptor::AccessibilityObserver::OnAccessibleKeyEvent
627  */
628 enum class KeyEventType
629 {
630   KEY_PRESSED,
631   KEY_RELEASED,
632 };
633
634 /**
635  * @brief Enumeration with human readable values describing state of event
636  *
637  * @see Dali::Accessibility::Bridge::Emit
638  */
639 enum class Consumed
640 {
641   NO,
642   YES
643 };
644
645 /**
646  * @brief Helper class representing two dimensional point with integer coordinates
647  */
648 struct DALI_ADAPTOR_API Point
649 {
650   int x = 0;
651   int y = 0;
652
653   Point() = default;
654   Point( int x, int y ) : x( x ), y( y ) {}
655
656   bool operator==( Point p ) const
657   {
658     return x == p.x && y == p.y;
659   }
660   bool operator!=( Point p ) const
661   {
662     return !( *this == p );
663   }
664 };
665
666 /**
667  * @brief Helper class representing size of rectangle object with usage of two integer values
668  */
669 struct DALI_ADAPTOR_API Size
670 {
671   int width = 0;
672   int height = 0;
673
674   Size() = default;
675   Size( int w, int h ) : width( w ), height( h ) {}
676
677   bool operator==( Size p ) const
678   {
679     return width == p.width && height == p.height;
680   }
681   bool operator!=( Size p ) const
682   {
683     return !( *this == p );
684   }
685 };
686
687 /**
688  * @brief Helper class used to store data related with Accessibility::Text interface
689  *
690  * @see Dali::Accessibility::Text::GetTextAtOffset
691  * @see Dali::Accessibility::Text::GetSelection
692  */
693 struct DALI_ADAPTOR_API Range
694 {
695   int startOffset = 0;
696   int endOffset = 0;
697   std::string content;
698
699   Range() = default;
700   Range( size_t start, size_t end ) : startOffset( start ), endOffset( end )
701   {
702   }
703   Range( size_t start, size_t end, std::string content ) : startOffset( start ), endOffset( end ), content( content )
704   {
705   }
706 };
707
708 /**
709  * @brief Structure containing all values needed to invoke Accessible::DoGesture
710  *
711  * type
712  *     enumerated gesture type
713  * xBeg, yBeg
714  *     point where gesture begins
715  * xEnd, yEnd
716  *     point where gesture ends
717  * state
718  *     enumerated state of gesture
719  * eventTime
720  *     time when event occured
721  *
722  * @see Dali::Accessibility::Accessible::DoGesture
723  */
724 struct DALI_ADAPTOR_API GestureInfo
725 {
726   GestureInfo() = default;
727   GestureInfo(Gesture type, int32_t xBeg, int32_t xEnd, int32_t yBeg, int32_t yEnd, GestureState state, uint32_t eventTime)
728     : type(type), xBeg(xBeg), xEnd(xEnd), yBeg(yBeg), yEnd(yEnd), state(state), eventTime(eventTime)
729   {}
730
731   Gesture type{};
732   int32_t xBeg{};
733   int32_t xEnd{};
734   int32_t yBeg{};
735   int32_t yEnd{};
736   GestureState state{};
737   uint32_t eventTime{};
738 };
739
740 class Accessible;
741
742 /**
743  * @brief Class representing accessibility relations
744  *
745  * Class connecting one source object with multiple target objects with usage
746  * of specific relation type.
747  *
748  * @note std::string representing source and targets are string values of Accessibility::Address
749  *
750  * @see Dali::Accessibility::Accessible::Address
751  * @see Dali::Accessibility::Accessible::RelationType
752  */
753 struct DALI_ADAPTOR_API Relation
754 {
755   Relation(RelationType relationType, std::vector<Address> targets)
756     : relationType(relationType), targets(targets)
757   {}
758   RelationType relationType;
759   std::vector<Address> targets;
760 };
761
762 /**
763  * @brief Reads given text by screen reader
764  *
765  * @param text The text to read
766  * @param discardable If TRUE, reading can be discarded by subsequent reading requests,
767  * if FALSE the reading must finish before next reading request can be started
768  * @param callback the callback function that is called on reading signals emitted
769  * during processing of this reading request.
770  * Callback can be one of the following signals:
771  * “ReadingCancelled”
772  * “ReadingStopped”
773  * “ReadingSkipped”
774  */
775 DALI_ADAPTOR_API void Say( const std::string &text, bool discardable, std::function<void(std::string)> callback );
776
777 /**
778  * @brief Force accessibility client to pause / resume.
779  *
780  * @param[in] pause true if you want to pause, false if you want to resume
781  */
782 DALI_ADAPTOR_API void PauseResume( bool pause );
783
784 /// \endcond
785 } // namespace Accessibility
786 /**
787  * @}
788  */
789 } // namespace Dali
790
791 namespace std
792 {
793 template <>
794 struct hash< Dali::Accessibility::Point >
795 {
796   size_t operator()( Dali::Accessibility::Point p )
797   {
798     return static_cast< size_t >( p.x ) ^ ( static_cast< size_t >( p.y ) * 11 );
799   }
800 };
801 template <>
802 struct hash< Dali::Accessibility::Size >
803 {
804   size_t operator()( Dali::Accessibility::Size p )
805   {
806     return static_cast< size_t >( p.width ) ^ ( static_cast< size_t >( p.height ) * 11 );
807   }
808 };
809 }
810
811 #endif // DALI_ACCESSIBILITY_H