Qt Accessibility Client

accessibleobject.h
1 /*
2  SPDX-FileCopyrightText: 2012 Frederik Gladhorn <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5 */
6 
7 #ifndef QACCESSIBILITYCLIENT_ACCESSIBLEOBJECT_H
8 #define QACCESSIBILITYCLIENT_ACCESSIBLEOBJECT_H
9 
10 #include <QtGlobal>
11 
12 namespace QAccessibleClient {
13  class AccessibleObject;
14 }
15 
16 #include <QList>
17 #include <QSharedPointer>
18 #include <QAction>
19 
20 #include "qaccessibilityclient_export.h"
21 
22 namespace QAccessibleClient {
23 
24 class AccessibleObjectPrivate;
25 class RegistryPrivate;
26 
27 
28 #ifndef QT_NO_DEBUG_STREAM
29  QACCESSIBILITYCLIENT_EXPORT QDebug operator<<(QDebug, const AccessibleObject &);
30 #endif
31 
32 /**
33  This class represents an accessible object.
34 
35  An accessible object equals usually a visible widget or some kind
36  of other element the user can interact with but can also present
37  a not visible object that offers certain functionality like for
38  example actions which can be triggered.
39 
40  It is implicitly shared and only created by the library.
41 */
42 class QACCESSIBILITYCLIENT_EXPORT AccessibleObject
43 {
44 public:
45 
46  /**
47  This enum describes the different interfaces that an
48  AccessibleObject can implement.
49 
50  Each AccessibleObject must implement the AccessibleInterface, otherwise
51  it is invalid. All other interfaces are optional.
52 
53  If the ActionInterface is implement the object
54  will have a list of actions that can be invoked.
55  */
56  enum Interface {
57  NoInterface = 0x0,
58  AccessibleInterface = 0x1,
59  CacheInterface = 0x2,
60  ActionInterface = 0x4,
61  ApplicationInterface = 0x8,
62  CollectionInterface = 0x10,
63  ComponentInterface = 0x20,
64  DocumentInterface = 0x40,
65  EditableTextInterface = 0x80,
66  EventKeyboardInterface = 0x100,
67  EventMouseInterface = 0x200,
68  EventObjectInterface = 0x400,
69  HyperlinkInterface = 0x800,
70  HypertextInterface = 0x1000,
71  ImageInterface = 0x2000,
72  SelectionInterface = 0x4000,
73  TableInterface = 0x8000,
74  TextInterface = 0x10000,
75  ValueInterface = 0x20000,
76  SocketInterface = 0x40000,
77  EventWindowInterface = 0x80000,
78  EventFocusInterface = 0x100000,
79 
80  InvalidInterface = 0x80000000
81  };
82  Q_DECLARE_FLAGS(Interfaces, Interface)
83 
84  /**
85  The role indicates the type of UI element that an AccessibleObject
86  represents.
87  */
88  enum Role {
89  NoRole, /*!< The object is invalid and has no role set. This is generally a bug. */
90  CheckBox,
91  CheckableMenuItem,
92  ColumnHeader,
93  ComboBox,
94  DesktopFrame,
95  Dial,
96  Dialog,
97  Filler,
98  Frame,
99  Icon,
100  Label,
101  ListView,
102  ListItem,
103  Menu,
104  MenuBar,
105  MenuItem,
106  Tab,
107  TabContainer,
108  PasswordText,
109  PopupMenu,
110  ProgressBar,
111  Button,
112  RadioButton,
113  RadioMenuItem,
114  RowHeader,
115  ScrollBar,
116  ScrollArea,
117  Separator,
118  Slider,
119  SpinButton,
120  StatusBar,
121  TableView,
122  TableCell,
123  TableColumnHeader,
124  TableColumn,
125  TableRowHeader,
126  TableRow,
127  Terminal,
128  Text,
129  ToggleButton,
130  ToolBar,
131  ToolTip,
132  TreeView,
133  Window,
134  TreeItem
135 // Roles in Qt, I don't think we want those
136 // TitleBar = 0x00000001,
137 // Grip = 0x00000004,
138 // Sound = 0x00000005,
139 // Cursor = 0x00000006,
140 // Caret = 0x00000007,
141 // AlertMessage = 0x00000008,
142 // Client = 0x0000000A,
143 // Application = 0x0000000E,
144 // Document = 0x0000000F,
145 // Pane = 0x00000010,
146 // Chart = 0x00000011,
147 // Border = 0x00000013,
148 // Grouping = 0x00000014,
149 // Cell = 0x0000001D,
150 // Link = 0x0000001E,
151 // HelpBalloon = 0x0000001F,
152 // Assistant = 0x00000020,
153 // PageTab = 0x00000025,
154 // PropertyPage = 0x00000026,
155 // Indicator = 0x00000027,
156 // Graphic = 0x00000028,
157 // StaticText = 0x00000029,
158 // EditableText = 0x0000002A, // Editable, selectable, etc.
159 // HotkeyField = 0x00000032,
160 // SpinBox = 0x00000034,
161 // Canvas = 0x00000035,
162 // Animation = 0x00000036,
163 // Equation = 0x00000037,
164 // ButtonDropDown = 0x00000038,
165 // ButtonMenu = 0x00000039,
166 // ButtonDropGrid = 0x0000003A,
167 // Whitespace = 0x0000003B,
168 // PageTabList = 0x0000003C,
169 // Clock = 0x0000003D,
170 // Splitter = 0x0000003E,
171 // LayeredPane = 0x00000080,
172  };
173 
174  /**
175  \brief The TextBoundaries enum represents the different boundaries when
176  asking for text at a certain offset.
177  */
179  CharBoundary,
180  WordStartBoundary,
181  WordEndBoundary,
182  SentenceStartBoundary,
183  SentenceEndBoundary,
184  LineStartBoundary,
185  LineEndBoundary
186  };
187 
188  /**
189  \brief Construct an invalid AccessibleObject.
190  */
192 
193  /**
194  \brief Copy constructor.
195  */
196  AccessibleObject(const AccessibleObject &other);
197 
198  /**
199  Destroys the AccessibleObject
200  */
201  ~AccessibleObject();
202 
203  /**
204  Assignment operator
205  */
206  AccessibleObject &operator=(const AccessibleObject &other);
207  /**
208  Comparison operator
209  */
210  bool operator==(const AccessibleObject &other) const;
211  /**
212  Inequality operator
213  */
214  inline bool operator!=(const AccessibleObject &other) const {
215  return !operator==(other);
216  }
217 
218  /**
219  \brief Returns a unique identifier for the object.
220  */
221  QString id() const;
222 
223  /**
224  \brief Returns a QUrl that references the AccessibleObject.
225 
226  This can be used to serialize/unserialize an AccessibleObject
227  to pass it around as string and restore the AccessibleObject
228  by using Registry::accessibleFromUrl later on.
229 
230  The returned QUrl returns a scheme of "accessibleobject", the
231  dbus path as url path and the dbus service as url fragment.
232  */
233  QUrl url() const;
234 
235  /**
236  \brief Returns true if this object is valid.
237 
238  Invalid objects are for example returned when asking for the
239  parent of the top most item, or for a child that is out of range.
240  */
241  bool isValid() const;
242 
243  /**
244  \brief Returns this object's parent.
245  \return The parent AccessibleObject
246  */
247  AccessibleObject parent() const;
248 
249  /**
250  \brief Returns this accessible's index in it's parent's list of children.
251  \return index
252  */
253  int indexInParent() const;
254 
255  /**
256  \brief Returns this accessible's children in a list.
257  \return children
258  */
259  QList<AccessibleObject> children() const;
260 
261  /**
262  \brief Returns this accessible's children according to there roles.
263  \param roles The list of roles to query.
264  \return A vector that contains the children of this object according
265  to there roles. The number of vector-items equals to the number and
266  sorting of the roles items. Example code demonstrating usage:
267  \code
268  QList<Role> roles;
269  roles << Label << CheckBox;
270  QVector< QList<AccessibleObject> > c = children(roles);
271  Q_ASSERT(c.count() == roles.count());
272  Q_ASSERT(c[0].isEmpty() || c[0].first().role() == Label);
273  Q_ASSERT(c[1].isEmpty() || c[1].first().role() == CheckBox);
274  \endcode
275  */
276  QVector< QList<AccessibleObject> > children(const QList<Role> &roles) const;
277 
278  /**
279  \brief Returns the number of children for this accessible.
280  \return number of children
281  */
282  int childCount() const;
283 
284  /**
285  \brief Returns a specific child at position \a index.
286 
287  The list of children is 0-based.
288  \return number of children
289  */
290  AccessibleObject child(int index) const;
291 
292  /**
293  \brief Returns the accessible id of this accessible.
294 
295  This is an id which is stable over application development.
296  It may be empty.
297  */
298  QString accessibleId() const;
299 
300  /**
301  \brief Returns the name of this accessible.
302 
303  The name is a short descriptive one or two words.
304  It is localized.
305  */
306  QString name() const;
307 
308  /**
309  \brief Returns the description for this accessible.
310 
311  The description is more of an explanation than the name.
312  This can be a sentence. The string is localized.
313  */
314  QString description() const;
315 
316  /**
317  \brief Returns the role as integer value of this accessible.
318  */
319  Role role() const;
320 
321  /**
322  \brief Returns the name of the role of this accessible.
323 
324  This name is not localized to allow tools to work with the english string.
325  */
326  QString roleName() const;
327 
328  /**
329  \brief Returns the name of the role of this accessible.
330 
331  This name is localized and can be presented to the user.
332  */
333  QString localizedRoleName() const;
334 
335  /**
336  \brief The ComponentLayer in which this object resides.
337  */
338  int layer() const;
339 
340  /**
341  \brief Obtain the relative stacking order (i.e. 'Z' order) of an object.
342 
343  Larger values indicate that an object is on "top" of the stack, therefore
344  objects with smaller MDIZOrder may be obscured by objects with a larger
345  MDIZOrder, but not vice-versa.
346  */
347  int mdiZOrder() const;
348 
349  /**
350  \brief Obtain the alpha value of the component.
351 
352  An alpha value of 1.0 or greater indicates that the object is fully opaque,
353  and an alpha value of 0.0 indicates that the object is fully transparent.
354  Negative alpha values have no defined meaning at this time.
355 
356  Alpha values are used in conjunction with Z-order calculations to determine
357  whether an object wholly or partially obscures another object's visual
358  intersection, in the event that their bounds intersect.
359  */
360  double alpha() const;
361 
362  /**
363  \brief Returns a bounding rectangle for the accessible.
364 
365  It returns a QRect that bounds the accessible. This can be used to get the focus coordinates.
366 
367  \return QRect that bounds the accessible.
368  */
369  QRect boundingRect() const;
370 
371  /**
372  \brief Returns a bounding rectangle for the character at position \a offset.
373 
374  This function is only supported for accessibles that implement the text interface.
375  It will return an empty rectangle for invalid offsets or accessibles.
376 
377  \return QRect that bounds the character.
378  */
379  QRect characterRect(int offset) const;
380 
381  /**
382  \brief Returns List of interfaces supported by the accessible.
383 
384  This function provides a list of accessibile interfaces that are implemented
385  by an accessible object. This can be used to avoid calling functions that
386  are not supported by the accessible.
387 
388  \return QStringList that contains list of supported interfaces
389  */
390  Interfaces supportedInterfaces() const;
391 
392  /**
393  \brief Returns the offset of the caret from the beginning of the text.
394 
395  This function provides the current offset of the caret from the beginning of
396  the text in an accessible that implements org.a11y.atspi.Text.
397 
398  \return Caret Offset as an integer
399  */
400  int caretOffset() const;
401 
402  /**
403  \brief Returns the number of characters.
404 
405  \return Number of characters.
406  */
407  int characterCount() const;
408 
409  /**
410  \brief Returns a list of selections the text has.
411 
412  Code to demonstrate usage:
413  \code
414  QList< QPair<int,int> > sel = acc.textSelections();
415  int startOffset = sel[0].first;
416  int endOffset = sel[0].second;
417  QString allText = acc.text();
418  QString selText = allText.mid(startOffset, endOffset - startOffset);
419  \endcode
420 
421  \return The list of selections where every item in that list
422  is a pair of integers representing startOffset and endOffset
423  of the selection.
424  */
425  QList< QPair<int,int> > textSelections() const;
426 
427  /**
428  Set text \a selections, usually only one selection will be set,
429  use a list containing one QPair with the start and end offsets for that.
430  */
431  void setTextSelections(const QList< QPair<int,int> > &selections);
432 
433  /**
434  \brief Returns the text of the TextInterface.
435 
436  This function provides the current text as displayed by the
437  org.a11y.atspi.Text TextInterface component.
438 
439  \param startOffset The start caret offset to return the text from.
440  \param endOffset The end caret offset to return the text from. If -1
441  then the endOffset is the end of the string what means all characters
442  are included.
443  \return The text as displayed by the TextInterface.
444  */
445  QString text(int startOffset = 0, int endOffset = -1) const;
446 
447  /**
448  \brief Returns the text of the TextInterface by boundary.
449 
450  Especially for larger text fields it may be more performant and easier to
451  query the text at a certain position instead of the full text.
452 
453  For example the line where the cursor is currently can be retrieved with this function
454  in a convenient way.
455 
456  \param offset is the position of the requested text.
457  \param startOffset returns the beginning of the offset, for example the start of the line when
458  asking for line boundaries.
459  \param endOffset returns the end of the text section
460  \return the text at the offset.
461  */
462  QString textWithBoundary(int offset, TextBoundary boundary, int *startOffset = nullptr, int *endOffset = nullptr) const;
463 
464  /**
465  \brief Set the text of the EditableTextInterface.
466 
467  \param text The text to set.
468  \return true on success and false on error.
469  */
470  bool setText(const QString &text);
471 
472  /**
473  \brief Insert the text into the EditableTextInterface.
474 
475  \param text The text to insert.
476  \param position The caret position at which to insert the text.
477  \param length The length of the text to insert.
478  \return true on success and false on error.
479  */
480  bool insertText(const QString &text, int position = 0, int length = -1);
481 
482  /**
483  \brief Copy the text from the EditableTextInterface into the clipboard.
484 
485  \param startPos The caret position from which to start to copy the text from.
486  \param endPos The caret position from which to end to copy the text from.
487  \return true on success and false on error.
488  */
489  bool copyText(int startPos, int endPos);
490 
491  /**
492  \brief Cut the text from the EditableTextInterface into the clipboard.
493 
494  \param startPos The caret position from which to start to cut the text from.
495  \param endPos The caret position from which to end to cut the text from.
496  \return true on success and false on error.
497  */
498  bool cutText(int startPos, int endPos);
499 
500  /**
501  \brief Delete the text from the EditableTextInterface.
502 
503  \param startPos The caret position from which to start to delete the text.
504  \param endPos The caret position from which to end to delete the text.
505  \return true on success and false on error.
506  */
507  bool deleteText(int startPos, int endPos);
508 
509  /**
510  \brief Paste the text from the clipboard into the EditableTextInterface.
511 
512  \param position The caret position at which to insert the text into.
513  \return true on success and false on error.
514  */
515  bool pasteText(int position);
516 
517  /**
518  \brief Returns focus-point of the object
519 
520  \return The Focus Point of the object
521  */
522  QPoint focusPoint() const;
523 
524  /**
525  \brief Returns the application object.
526 
527  \return The top-level application object that expose an
528  org.a11y.atspi.Application accessibility interface.
529  */
530  AccessibleObject application() const;
531 
532  /**
533  \brief Returns the toolkit name.
534 
535  \return The tookit name. This can be for example "Qt"
536  or "gtk".
537  */
538  QString appToolkitName() const;
539 
540  /**
541  \brief Returns the toolkit version.
542 
543  \return The tookit version. This can be for example "4.8.3"
544  for Qt 4.8.3.
545  */
546  QString appVersion() const;
547 
548  /**
549  \brief Returns the unique application identifier.
550 
551  \return The app id. The identifier will not last over session
552  and everytime the app quits and restarts it gets another
553  identifier that persists as long as the application is running.
554  */
555  int appId() const;
556 
557  /**
558  The type of locale
559  */
560  enum LocaleType {
561  LocaleTypeMessages,
562  LocaleTypeCollate,
563  LocaleTypeCType,
564  LocaleTypeMonetary,
565  LocaleTypeNumeric,
566  LocaleTypeTime
567  };
568 
569  /**
570  \brief The application locale.
571 
572  \param lctype The \a LocaleType for which the locale is queried.
573  \return A string compliant with the POSIX standard for locale description.
574  */
575  QString appLocale(LocaleType lctype = LocaleTypeMessages) const;
576 
577  /**
578  \brief The application dbus address.
579  */
580  QString appBusAddress() const;
581 
582  /**
583  \brief The minimum value allowed by this valuator.
584 
585  If both, the \a minimumValue and \a maximumValue, are zero then
586  there is no minimum or maximum values. The \a currentValue has
587  no range restrictions.
588  */
589  double minimumValue() const;
590 
591  /**
592  \brief The maximum value allowed by this valuator.
593 
594  If both, the \a minimumValue and \a maximumValue, are zero then
595  there is no minimum or maximum values. The \a currentValue has
596  no range restrictions.
597  */
598  double maximumValue() const;
599 
600  /**
601  \brief The smallest incremental change which this valuator allows.
602 
603  This is a helper value to know in what steps the \a currentValue
604  is incremented or decremented.
605 
606  If 0, the incremental changes to the valuator are limited only by
607  the precision of a double precision value on the platform.
608  */
609  double minimumValueIncrement() const;
610 
611  /**
612  \brief The current value of the valuator.
613 
614  This is the value the org.a11y.atspi.Value accessibility interface has.
615  */
616  double currentValue() const;
617 
618  /**
619  \brief Set the value of the valuator.
620 
621  \param value the value to set.
622  \return true on success and false on error.
623  */
624  bool setCurrentValue(const double value);
625 
626  /**
627  \brief Returns the selection of accessible objects.
628  */
629  QList<AccessibleObject> selection() const;
630 
631  /**
632  \brief A description text of the image.
633 
634  It is recommended that imageDescription be the shorter of the available image
635  descriptions, for instance "alt text" in HTML images, and a longer description
636  be provided in Accessible::accessible-description, if available. A short, one
637  or two word label for the image should be provided in Accessible::accessible-name.
638 
639  \return A UTF-8 string providing a textual description of what is visually
640  depicted in the image.
641  */
642  QString imageDescription() const;
643 
644  /**
645  \brief The locale of the image.
646 
647  \return A string corresponding to the POSIX LC_MESSAGES locale used by the
648  imageDescription.
649  */
650  QString imageLocale() const;
651 
652  /**
653  \brief The image boundaries.
654 
655  Obtain a bounding box which entirely contains the image contents, as
656  displayed on screen.
657 
658  The bounds returned do not account for any viewport clipping or the fact that
659  the image may be partially or wholly obscured by other onscreen content.
660 
661  This method returns the bounds of the current onscreen view, and not the
662  nominal size of the source data in the event that the original image has
663  been rescaled.\
664 
665  \return A BoundingBox enclosing the image's onscreen representation.
666  */
667  QRect imageRect() const;
668 
669  /**
670  \brief Returns a list of actions supported by this accessible.
671 
672  Just trigger() the action to execute the underlying method at the accessible.
673  */
674  QVector< QSharedPointer<QAction> > actions() const;
675 
676  // states
677  /// Returns if the AccessibleObject is currently active
678  bool isActive() const;
679  /// Returns if the AccessibleObject is checkable (often indicates a check action)
680  bool isCheckable() const;
681  /// Returns if the AccessibleObject is currently checked
682  bool isChecked() const;
683  /// Returns if the AccessibleObject is defunct - that means it does not properly respont to requests
684  /// and should be ignored for accessibility purposes
685  bool isDefunct() const;
686  /// Returns if the AccessibleObject is an editable text
687  bool isEditable() const;
688  /// Returns if the AccessibleObject is currently enabled
689  bool isEnabled() const;
690  /// Returns if the AccessibleObject can be expanded to show more information
691  bool isExpandable() const;
692  /// Returns if the AccessibleObject is currently expanded
693  bool isExpanded() const;
694  /// Returns if the AccessibleObject is focusable
695  bool isFocusable() const;
696  /// Returns if the AccessibleObject is currently focused
697  bool isFocused() const;
698  /// Returns if the AccessibleObject is a multi line text edit
699  bool isMultiLine() const;
700  /// Returns if the AccessibleObject is selectable
701  bool isSelectable() const;
702  /// Returns if the AccessibleObject is currently selected
703  bool isSelected() const;
704  /// Returns if the AccessibleObject reacts to input events
705  bool isSensitive() const;
706  /// Returns if the AccessibleObject is a single line text edit
707  bool isSingleLine() const;
708 
709  /**
710  \brief Return a string representing states of this object.
711 
712  This is useful for debugging applications.
713  */
714  QString stateString() const;
715 
716  /*
717  * \internal
718  * \brief isTransient marks an object as being unreliable in that it can quickly disappear or change
719  *
720  * This is mostly a hint that the object should not be cached.
721  * \return true if the object is transient
722  */
723 // bool isTransient() const;
724 
725  /// Returns if the AccessibleObject is currently visible (it can still be off the screen,
726  /// but there is nothing preventing the user from seeing it in general)
727  bool isVisible() const;
728 
729  /*
730  * \internal
731  * \brief managesDescendants marks an object as being responsible for its children
732  *
733  * This is to notify that this object handles signals for it's children.
734  * The property is typically used for tables and lists or other collection objects.
735  * \return true if the object is transient
736  */
737 // bool managesDescendants() const;
738 // bool isRequired() const;
739 // bool isAnimated() const;
740 // bool isInvalidEntry() const;
741  /// Returns if the AccessibleObject is the default widget (e.g. a button in a dialog)
742  bool isDefault() const;
743 // bool isVisited() const;
744 
745  /// Returns if the AccessibleObject allows text selections
746  bool hasSelectableText() const;
747  /// Returns if the AccessibleObject has a tool tip
748  bool hasToolTip() const;
749  /// Returns if the AccessibleObject supports automatic text completion
750  bool supportsAutocompletion() const;
751 
752 private:
753  AccessibleObject(RegistryPrivate *reg, const QString &service, const QString &path);
756 
757  friend class Registry;
758  friend class RegistryPrivate;
759  friend class CacheWeakStrategy;
760  friend class CacheStrongStrategy;
761 #ifndef QT_NO_DEBUG_STREAM
762  friend QDebug QAccessibleClient::operator<<(QDebug, const AccessibleObject &);
763 #endif
764  friend uint qHash(const QAccessibleClient::AccessibleObject& object) {
765  return qHash(object.d);
766  }
767 };
768 
769 }
770 
771 Q_DECLARE_METATYPE(QAccessibleClient::AccessibleObject)
772 
773 #endif
Role
The role indicates the type of UI element that an AccessibleObject represents.
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
bool operator!=(const AccessibleObject &other) const
Inequality operator.
Interface
This enum describes the different interfaces that an AccessibleObject can implement.
KCALENDARCORE_EXPORT uint qHash(const KCalendarCore::Period &key)
This class represents an accessible object.
TextBoundary
The TextBoundaries enum represents the different boundaries when asking for text at a certain offset.
This class represents the global accessibility registry.
Definition: registry.h:29
Label
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Nov 28 2023 04:00:38 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.