File indexing completed on 2023-12-03 11:41:02
0001 /* 0002 SPDX-FileCopyrightText: 2012 Frederik Gladhorn <gladhorn@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL 0005 */ 0006 0007 #ifndef QACCESSIBILITYCLIENT_ACCESSIBLEOBJECT_H 0008 #define QACCESSIBILITYCLIENT_ACCESSIBLEOBJECT_H 0009 0010 #include <QtGlobal> 0011 0012 namespace QAccessibleClient { 0013 class AccessibleObject; 0014 } 0015 0016 #include <QList> 0017 #include <QSharedPointer> 0018 #include <QAction> 0019 0020 #include "qaccessibilityclient_export.h" 0021 0022 namespace QAccessibleClient { 0023 0024 class AccessibleObjectPrivate; 0025 class RegistryPrivate; 0026 0027 0028 #ifndef QT_NO_DEBUG_STREAM 0029 QACCESSIBILITYCLIENT_EXPORT QDebug operator<<(QDebug, const AccessibleObject &); 0030 #endif 0031 0032 /** 0033 This class represents an accessible object. 0034 0035 An accessible object equals usually a visible widget or some kind 0036 of other element the user can interact with but can also present 0037 a not visible object that offers certain functionality like for 0038 example actions which can be triggered. 0039 0040 It is implicitly shared and only created by the library. 0041 */ 0042 class QACCESSIBILITYCLIENT_EXPORT AccessibleObject 0043 { 0044 public: 0045 0046 /** 0047 This enum describes the different interfaces that an 0048 AccessibleObject can implement. 0049 0050 Each AccessibleObject must implement the AccessibleInterface, otherwise 0051 it is invalid. All other interfaces are optional. 0052 0053 If the ActionInterface is implement the object 0054 will have a list of actions that can be invoked. 0055 */ 0056 enum Interface { 0057 NoInterface = 0x0, 0058 AccessibleInterface = 0x1, 0059 CacheInterface = 0x2, 0060 ActionInterface = 0x4, 0061 ApplicationInterface = 0x8, 0062 CollectionInterface = 0x10, 0063 ComponentInterface = 0x20, 0064 DocumentInterface = 0x40, 0065 EditableTextInterface = 0x80, 0066 EventKeyboardInterface = 0x100, 0067 EventMouseInterface = 0x200, 0068 EventObjectInterface = 0x400, 0069 HyperlinkInterface = 0x800, 0070 HypertextInterface = 0x1000, 0071 ImageInterface = 0x2000, 0072 SelectionInterface = 0x4000, 0073 TableInterface = 0x8000, 0074 TextInterface = 0x10000, 0075 ValueInterface = 0x20000, 0076 SocketInterface = 0x40000, 0077 EventWindowInterface = 0x80000, 0078 EventFocusInterface = 0x100000, 0079 0080 InvalidInterface = 0x80000000 0081 }; 0082 Q_DECLARE_FLAGS(Interfaces, Interface) 0083 0084 /** 0085 The role indicates the type of UI element that an AccessibleObject 0086 represents. 0087 */ 0088 enum Role { 0089 NoRole, /*!< The object is invalid and has no role set. This is generally a bug. */ 0090 CheckBox, 0091 CheckableMenuItem, 0092 ColumnHeader, 0093 ComboBox, 0094 DesktopFrame, 0095 Dial, 0096 Dialog, 0097 Filler, 0098 Frame, 0099 Icon, 0100 Label, 0101 ListView, 0102 ListItem, 0103 Menu, 0104 MenuBar, 0105 MenuItem, 0106 Tab, 0107 TabContainer, 0108 PasswordText, 0109 PopupMenu, 0110 ProgressBar, 0111 Button, 0112 RadioButton, 0113 RadioMenuItem, 0114 RowHeader, 0115 ScrollBar, 0116 ScrollArea, 0117 Separator, 0118 Slider, 0119 SpinButton, 0120 StatusBar, 0121 TableView, 0122 TableCell, 0123 TableColumnHeader, 0124 TableColumn, 0125 TableRowHeader, 0126 TableRow, 0127 Terminal, 0128 Text, 0129 ToggleButton, 0130 ToolBar, 0131 ToolTip, 0132 TreeView, 0133 Window, 0134 TreeItem 0135 // Roles in Qt, I don't think we want those 0136 // TitleBar = 0x00000001, 0137 // Grip = 0x00000004, 0138 // Sound = 0x00000005, 0139 // Cursor = 0x00000006, 0140 // Caret = 0x00000007, 0141 // AlertMessage = 0x00000008, 0142 // Client = 0x0000000A, 0143 // Application = 0x0000000E, 0144 // Document = 0x0000000F, 0145 // Pane = 0x00000010, 0146 // Chart = 0x00000011, 0147 // Border = 0x00000013, 0148 // Grouping = 0x00000014, 0149 // Cell = 0x0000001D, 0150 // Link = 0x0000001E, 0151 // HelpBalloon = 0x0000001F, 0152 // Assistant = 0x00000020, 0153 // PageTab = 0x00000025, 0154 // PropertyPage = 0x00000026, 0155 // Indicator = 0x00000027, 0156 // Graphic = 0x00000028, 0157 // StaticText = 0x00000029, 0158 // EditableText = 0x0000002A, // Editable, selectable, etc. 0159 // HotkeyField = 0x00000032, 0160 // SpinBox = 0x00000034, 0161 // Canvas = 0x00000035, 0162 // Animation = 0x00000036, 0163 // Equation = 0x00000037, 0164 // ButtonDropDown = 0x00000038, 0165 // ButtonMenu = 0x00000039, 0166 // ButtonDropGrid = 0x0000003A, 0167 // Whitespace = 0x0000003B, 0168 // PageTabList = 0x0000003C, 0169 // Clock = 0x0000003D, 0170 // Splitter = 0x0000003E, 0171 // LayeredPane = 0x00000080, 0172 }; 0173 0174 /** 0175 \brief The TextBoundaries enum represents the different boundaries when 0176 asking for text at a certain offset. 0177 */ 0178 enum TextBoundary { 0179 CharBoundary, 0180 WordStartBoundary, 0181 WordEndBoundary, 0182 SentenceStartBoundary, 0183 SentenceEndBoundary, 0184 LineStartBoundary, 0185 LineEndBoundary 0186 }; 0187 0188 /** 0189 \brief Construct an invalid AccessibleObject. 0190 */ 0191 AccessibleObject(); 0192 0193 /** 0194 \brief Copy constructor. 0195 */ 0196 AccessibleObject(const AccessibleObject &other); 0197 0198 /** 0199 Destroys the AccessibleObject 0200 */ 0201 ~AccessibleObject(); 0202 0203 /** 0204 Assignment operator 0205 */ 0206 AccessibleObject &operator=(const AccessibleObject &other); 0207 /** 0208 Comparison operator 0209 */ 0210 bool operator==(const AccessibleObject &other) const; 0211 /** 0212 Inequality operator 0213 */ 0214 inline bool operator!=(const AccessibleObject &other) const { 0215 return !operator==(other); 0216 } 0217 0218 /** 0219 \brief Returns a unique identifier for the object. 0220 */ 0221 QString id() const; 0222 0223 /** 0224 \brief Returns a QUrl that references the AccessibleObject. 0225 0226 This can be used to serialize/unserialize an AccessibleObject 0227 to pass it around as string and restore the AccessibleObject 0228 by using Registry::accessibleFromUrl later on. 0229 0230 The returned QUrl returns a scheme of "accessibleobject", the 0231 dbus path as url path and the dbus service as url fragment. 0232 */ 0233 QUrl url() const; 0234 0235 /** 0236 \brief Returns true if this object is valid. 0237 0238 Invalid objects are for example returned when asking for the 0239 parent of the top most item, or for a child that is out of range. 0240 */ 0241 bool isValid() const; 0242 0243 /** 0244 \brief Returns this object's parent. 0245 \return The parent AccessibleObject 0246 */ 0247 AccessibleObject parent() const; 0248 0249 /** 0250 \brief Returns this accessible's index in it's parent's list of children. 0251 \return index 0252 */ 0253 int indexInParent() const; 0254 0255 /** 0256 \brief Returns this accessible's children in a list. 0257 \return children 0258 */ 0259 QList<AccessibleObject> children() const; 0260 0261 /** 0262 \brief Returns this accessible's children according to there roles. 0263 \param roles The list of roles to query. 0264 \return A vector that contains the children of this object according 0265 to there roles. The number of vector-items equals to the number and 0266 sorting of the roles items. Example code demonstrating usage: 0267 \code 0268 QList<Role> roles; 0269 roles << Label << CheckBox; 0270 QVector< QList<AccessibleObject> > c = children(roles); 0271 Q_ASSERT(c.count() == roles.count()); 0272 Q_ASSERT(c[0].isEmpty() || c[0].first().role() == Label); 0273 Q_ASSERT(c[1].isEmpty() || c[1].first().role() == CheckBox); 0274 \endcode 0275 */ 0276 QVector< QList<AccessibleObject> > children(const QList<Role> &roles) const; 0277 0278 /** 0279 \brief Returns the number of children for this accessible. 0280 \return number of children 0281 */ 0282 int childCount() const; 0283 0284 /** 0285 \brief Returns a specific child at position \a index. 0286 0287 The list of children is 0-based. 0288 \return number of children 0289 */ 0290 AccessibleObject child(int index) const; 0291 0292 /** 0293 \brief Returns the accessible id of this accessible. 0294 0295 This is an id which is stable over application development. 0296 It may be empty. 0297 */ 0298 QString accessibleId() const; 0299 0300 /** 0301 \brief Returns the name of this accessible. 0302 0303 The name is a short descriptive one or two words. 0304 It is localized. 0305 */ 0306 QString name() const; 0307 0308 /** 0309 \brief Returns the description for this accessible. 0310 0311 The description is more of an explanation than the name. 0312 This can be a sentence. The string is localized. 0313 */ 0314 QString description() const; 0315 0316 /** 0317 \brief Returns the role as integer value of this accessible. 0318 */ 0319 Role role() const; 0320 0321 /** 0322 \brief Returns the name of the role of this accessible. 0323 0324 This name is not localized to allow tools to work with the english string. 0325 */ 0326 QString roleName() const; 0327 0328 /** 0329 \brief Returns the name of the role of this accessible. 0330 0331 This name is localized and can be presented to the user. 0332 */ 0333 QString localizedRoleName() const; 0334 0335 /** 0336 \brief The ComponentLayer in which this object resides. 0337 */ 0338 int layer() const; 0339 0340 /** 0341 \brief Obtain the relative stacking order (i.e. 'Z' order) of an object. 0342 0343 Larger values indicate that an object is on "top" of the stack, therefore 0344 objects with smaller MDIZOrder may be obscured by objects with a larger 0345 MDIZOrder, but not vice-versa. 0346 */ 0347 int mdiZOrder() const; 0348 0349 /** 0350 \brief Obtain the alpha value of the component. 0351 0352 An alpha value of 1.0 or greater indicates that the object is fully opaque, 0353 and an alpha value of 0.0 indicates that the object is fully transparent. 0354 Negative alpha values have no defined meaning at this time. 0355 0356 Alpha values are used in conjunction with Z-order calculations to determine 0357 whether an object wholly or partially obscures another object's visual 0358 intersection, in the event that their bounds intersect. 0359 */ 0360 double alpha() const; 0361 0362 /** 0363 \brief Returns a bounding rectangle for the accessible. 0364 0365 It returns a QRect that bounds the accessible. This can be used to get the focus coordinates. 0366 0367 \return QRect that bounds the accessible. 0368 */ 0369 QRect boundingRect() const; 0370 0371 /** 0372 \brief Returns a bounding rectangle for the character at position \a offset. 0373 0374 This function is only supported for accessibles that implement the text interface. 0375 It will return an empty rectangle for invalid offsets or accessibles. 0376 0377 \return QRect that bounds the character. 0378 */ 0379 QRect characterRect(int offset) const; 0380 0381 /** 0382 \brief Returns List of interfaces supported by the accessible. 0383 0384 This function provides a list of accessibile interfaces that are implemented 0385 by an accessible object. This can be used to avoid calling functions that 0386 are not supported by the accessible. 0387 0388 \return QStringList that contains list of supported interfaces 0389 */ 0390 Interfaces supportedInterfaces() const; 0391 0392 /** 0393 \brief Returns the offset of the caret from the beginning of the text. 0394 0395 This function provides the current offset of the caret from the beginning of 0396 the text in an accessible that implements org.a11y.atspi.Text. 0397 0398 \return Caret Offset as an integer 0399 */ 0400 int caretOffset() const; 0401 0402 /** 0403 \brief Returns the number of characters. 0404 0405 \return Number of characters. 0406 */ 0407 int characterCount() const; 0408 0409 /** 0410 \brief Returns a list of selections the text has. 0411 0412 Code to demonstrate usage: 0413 \code 0414 QList< QPair<int,int> > sel = acc.textSelections(); 0415 int startOffset = sel[0].first; 0416 int endOffset = sel[0].second; 0417 QString allText = acc.text(); 0418 QString selText = allText.mid(startOffset, endOffset - startOffset); 0419 \endcode 0420 0421 \return The list of selections where every item in that list 0422 is a pair of integers representing startOffset and endOffset 0423 of the selection. 0424 */ 0425 QList< QPair<int,int> > textSelections() const; 0426 0427 /** 0428 Set text \a selections, usually only one selection will be set, 0429 use a list containing one QPair with the start and end offsets for that. 0430 */ 0431 void setTextSelections(const QList< QPair<int,int> > &selections); 0432 0433 /** 0434 \brief Returns the text of the TextInterface. 0435 0436 This function provides the current text as displayed by the 0437 org.a11y.atspi.Text TextInterface component. 0438 0439 \param startOffset The start caret offset to return the text from. 0440 \param endOffset The end caret offset to return the text from. If -1 0441 then the endOffset is the end of the string what means all characters 0442 are included. 0443 \return The text as displayed by the TextInterface. 0444 */ 0445 QString text(int startOffset = 0, int endOffset = -1) const; 0446 0447 /** 0448 \brief Returns the text of the TextInterface by boundary. 0449 0450 Especially for larger text fields it may be more performant and easier to 0451 query the text at a certain position instead of the full text. 0452 0453 For example the line where the cursor is currently can be retrieved with this function 0454 in a convenient way. 0455 0456 \param offset is the position of the requested text. 0457 \param startOffset returns the beginning of the offset, for example the start of the line when 0458 asking for line boundaries. 0459 \param endOffset returns the end of the text section 0460 \return the text at the offset. 0461 */ 0462 QString textWithBoundary(int offset, TextBoundary boundary, int *startOffset = nullptr, int *endOffset = nullptr) const; 0463 0464 /** 0465 \brief Set the text of the EditableTextInterface. 0466 0467 \param text The text to set. 0468 \return true on success and false on error. 0469 */ 0470 bool setText(const QString &text); 0471 0472 /** 0473 \brief Insert the text into the EditableTextInterface. 0474 0475 \param text The text to insert. 0476 \param position The caret position at which to insert the text. 0477 \param length The length of the text to insert. 0478 \return true on success and false on error. 0479 */ 0480 bool insertText(const QString &text, int position = 0, int length = -1); 0481 0482 /** 0483 \brief Copy the text from the EditableTextInterface into the clipboard. 0484 0485 \param startPos The caret position from which to start to copy the text from. 0486 \param endPos The caret position from which to end to copy the text from. 0487 \return true on success and false on error. 0488 */ 0489 bool copyText(int startPos, int endPos); 0490 0491 /** 0492 \brief Cut the text from the EditableTextInterface into the clipboard. 0493 0494 \param startPos The caret position from which to start to cut the text from. 0495 \param endPos The caret position from which to end to cut the text from. 0496 \return true on success and false on error. 0497 */ 0498 bool cutText(int startPos, int endPos); 0499 0500 /** 0501 \brief Delete the text from the EditableTextInterface. 0502 0503 \param startPos The caret position from which to start to delete the text. 0504 \param endPos The caret position from which to end to delete the text. 0505 \return true on success and false on error. 0506 */ 0507 bool deleteText(int startPos, int endPos); 0508 0509 /** 0510 \brief Paste the text from the clipboard into the EditableTextInterface. 0511 0512 \param position The caret position at which to insert the text into. 0513 \return true on success and false on error. 0514 */ 0515 bool pasteText(int position); 0516 0517 /** 0518 \brief Returns focus-point of the object 0519 0520 \return The Focus Point of the object 0521 */ 0522 QPoint focusPoint() const; 0523 0524 /** 0525 \brief Returns the application object. 0526 0527 \return The top-level application object that expose an 0528 org.a11y.atspi.Application accessibility interface. 0529 */ 0530 AccessibleObject application() const; 0531 0532 /** 0533 \brief Returns the toolkit name. 0534 0535 \return The tookit name. This can be for example "Qt" 0536 or "gtk". 0537 */ 0538 QString appToolkitName() const; 0539 0540 /** 0541 \brief Returns the toolkit version. 0542 0543 \return The tookit version. This can be for example "4.8.3" 0544 for Qt 4.8.3. 0545 */ 0546 QString appVersion() const; 0547 0548 /** 0549 \brief Returns the unique application identifier. 0550 0551 \return The app id. The identifier will not last over session 0552 and everytime the app quits and restarts it gets another 0553 identifier that persists as long as the application is running. 0554 */ 0555 int appId() const; 0556 0557 /** 0558 The type of locale 0559 */ 0560 enum LocaleType { 0561 LocaleTypeMessages, 0562 LocaleTypeCollate, 0563 LocaleTypeCType, 0564 LocaleTypeMonetary, 0565 LocaleTypeNumeric, 0566 LocaleTypeTime 0567 }; 0568 0569 /** 0570 \brief The application locale. 0571 0572 \param lctype The \a LocaleType for which the locale is queried. 0573 \return A string compliant with the POSIX standard for locale description. 0574 */ 0575 QString appLocale(LocaleType lctype = LocaleTypeMessages) const; 0576 0577 /** 0578 \brief The application dbus address. 0579 */ 0580 QString appBusAddress() const; 0581 0582 /** 0583 \brief The minimum value allowed by this valuator. 0584 0585 If both, the \a minimumValue and \a maximumValue, are zero then 0586 there is no minimum or maximum values. The \a currentValue has 0587 no range restrictions. 0588 */ 0589 double minimumValue() const; 0590 0591 /** 0592 \brief The maximum value allowed by this valuator. 0593 0594 If both, the \a minimumValue and \a maximumValue, are zero then 0595 there is no minimum or maximum values. The \a currentValue has 0596 no range restrictions. 0597 */ 0598 double maximumValue() const; 0599 0600 /** 0601 \brief The smallest incremental change which this valuator allows. 0602 0603 This is a helper value to know in what steps the \a currentValue 0604 is incremented or decremented. 0605 0606 If 0, the incremental changes to the valuator are limited only by 0607 the precision of a double precision value on the platform. 0608 */ 0609 double minimumValueIncrement() const; 0610 0611 /** 0612 \brief The current value of the valuator. 0613 0614 This is the value the org.a11y.atspi.Value accessibility interface has. 0615 */ 0616 double currentValue() const; 0617 0618 /** 0619 \brief Set the value of the valuator. 0620 0621 \param value the value to set. 0622 \return true on success and false on error. 0623 */ 0624 bool setCurrentValue(const double value); 0625 0626 /** 0627 \brief Returns the selection of accessible objects. 0628 */ 0629 QList<AccessibleObject> selection() const; 0630 0631 /** 0632 \brief A description text of the image. 0633 0634 It is recommended that imageDescription be the shorter of the available image 0635 descriptions, for instance "alt text" in HTML images, and a longer description 0636 be provided in Accessible::accessible-description, if available. A short, one 0637 or two word label for the image should be provided in Accessible::accessible-name. 0638 0639 \return A UTF-8 string providing a textual description of what is visually 0640 depicted in the image. 0641 */ 0642 QString imageDescription() const; 0643 0644 /** 0645 \brief The locale of the image. 0646 0647 \return A string corresponding to the POSIX LC_MESSAGES locale used by the 0648 imageDescription. 0649 */ 0650 QString imageLocale() const; 0651 0652 /** 0653 \brief The image boundaries. 0654 0655 Obtain a bounding box which entirely contains the image contents, as 0656 displayed on screen. 0657 0658 The bounds returned do not account for any viewport clipping or the fact that 0659 the image may be partially or wholly obscured by other onscreen content. 0660 0661 This method returns the bounds of the current onscreen view, and not the 0662 nominal size of the source data in the event that the original image has 0663 been rescaled.\ 0664 0665 \return A BoundingBox enclosing the image's onscreen representation. 0666 */ 0667 QRect imageRect() const; 0668 0669 /** 0670 \brief Returns a list of actions supported by this accessible. 0671 0672 Just trigger() the action to execute the underlying method at the accessible. 0673 */ 0674 QVector< QSharedPointer<QAction> > actions() const; 0675 0676 // states 0677 /// Returns if the AccessibleObject is currently active 0678 bool isActive() const; 0679 /// Returns if the AccessibleObject is checkable (often indicates a check action) 0680 bool isCheckable() const; 0681 /// Returns if the AccessibleObject is currently checked 0682 bool isChecked() const; 0683 /// Returns if the AccessibleObject is defunct - that means it does not properly respont to requests 0684 /// and should be ignored for accessibility purposes 0685 bool isDefunct() const; 0686 /// Returns if the AccessibleObject is an editable text 0687 bool isEditable() const; 0688 /// Returns if the AccessibleObject is currently enabled 0689 bool isEnabled() const; 0690 /// Returns if the AccessibleObject can be expanded to show more information 0691 bool isExpandable() const; 0692 /// Returns if the AccessibleObject is currently expanded 0693 bool isExpanded() const; 0694 /// Returns if the AccessibleObject is focusable 0695 bool isFocusable() const; 0696 /// Returns if the AccessibleObject is currently focused 0697 bool isFocused() const; 0698 /// Returns if the AccessibleObject is a multi line text edit 0699 bool isMultiLine() const; 0700 /// Returns if the AccessibleObject is selectable 0701 bool isSelectable() const; 0702 /// Returns if the AccessibleObject is currently selected 0703 bool isSelected() const; 0704 /// Returns if the AccessibleObject reacts to input events 0705 bool isSensitive() const; 0706 /// Returns if the AccessibleObject is a single line text edit 0707 bool isSingleLine() const; 0708 0709 /** 0710 \brief Return a string representing states of this object. 0711 0712 This is useful for debugging applications. 0713 */ 0714 QString stateString() const; 0715 0716 /* 0717 * \internal 0718 * \brief isTransient marks an object as being unreliable in that it can quickly disappear or change 0719 * 0720 * This is mostly a hint that the object should not be cached. 0721 * \return true if the object is transient 0722 */ 0723 // bool isTransient() const; 0724 0725 /// Returns if the AccessibleObject is currently visible (it can still be off the screen, 0726 /// but there is nothing preventing the user from seeing it in general) 0727 bool isVisible() const; 0728 0729 /* 0730 * \internal 0731 * \brief managesDescendants marks an object as being responsible for its children 0732 * 0733 * This is to notify that this object handles signals for it's children. 0734 * The property is typically used for tables and lists or other collection objects. 0735 * \return true if the object is transient 0736 */ 0737 // bool managesDescendants() const; 0738 // bool isRequired() const; 0739 // bool isAnimated() const; 0740 // bool isInvalidEntry() const; 0741 /// Returns if the AccessibleObject is the default widget (e.g. a button in a dialog) 0742 bool isDefault() const; 0743 // bool isVisited() const; 0744 0745 /// Returns if the AccessibleObject allows text selections 0746 bool hasSelectableText() const; 0747 /// Returns if the AccessibleObject has a tool tip 0748 bool hasToolTip() const; 0749 /// Returns if the AccessibleObject supports automatic text completion 0750 bool supportsAutocompletion() const; 0751 0752 private: 0753 AccessibleObject(RegistryPrivate *reg, const QString &service, const QString &path); 0754 AccessibleObject(const QSharedPointer<AccessibleObjectPrivate> &dd); 0755 QSharedPointer<AccessibleObjectPrivate> d; 0756 0757 friend class Registry; 0758 friend class RegistryPrivate; 0759 friend class CacheWeakStrategy; 0760 friend class CacheStrongStrategy; 0761 #ifndef QT_NO_DEBUG_STREAM 0762 friend QDebug QAccessibleClient::operator<<(QDebug, const AccessibleObject &); 0763 #endif 0764 friend uint qHash(const QAccessibleClient::AccessibleObject& object) { 0765 return qHash(object.d); 0766 } 0767 }; 0768 0769 } 0770 0771 Q_DECLARE_METATYPE(QAccessibleClient::AccessibleObject) 0772 0773 #endif