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