1 | // Copyright (C) 2020 The Qt Company Ltd. |
2 | // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only |
3 | |
4 | #include "qaccessible.h" |
5 | |
6 | #include "qaccessiblecache_p.h" |
7 | #include "qaccessibleplugin.h" |
8 | #include "qaccessibleobject.h" |
9 | #include "qaccessiblebridge.h" |
10 | #include <QtCore/qtextboundaryfinder.h> |
11 | #include <QtGui/qclipboard.h> |
12 | #include <QtGui/qguiapplication.h> |
13 | #include <QtGui/qtextcursor.h> |
14 | #include <private/qguiapplication_p.h> |
15 | #include <qpa/qplatformaccessibility.h> |
16 | #include <qpa/qplatformintegration.h> |
17 | |
18 | #include <QtCore/qdebug.h> |
19 | #include <QtCore/qloggingcategory.h> |
20 | #include <QtCore/qmetaobject.h> |
21 | #include <QtCore/private/qmetaobject_p.h> |
22 | #include <QtCore/qhash.h> |
23 | #include <private/qfactoryloader_p.h> |
24 | |
25 | QT_BEGIN_NAMESPACE |
26 | |
27 | using namespace Qt::StringLiterals; |
28 | |
29 | Q_LOGGING_CATEGORY(lcAccessibilityCore, "qt.accessibility.core" ); |
30 | |
31 | /*! |
32 | \class QAccessible |
33 | \brief The QAccessible class provides enums and static functions |
34 | related to accessibility. |
35 | |
36 | \ingroup accessibility |
37 | \inmodule QtGui |
38 | |
39 | This class is part of \l {Accessibility for QWidget Applications}. |
40 | |
41 | Accessible applications can be used by people who are not able to |
42 | use applications by conventional means. |
43 | |
44 | The functions in this class are used for communication between |
45 | accessible applications (also called AT Servers) and |
46 | accessibility tools (AT Clients), such as screen readers and |
47 | braille displays. Clients and servers communicate in the following way: |
48 | |
49 | \list |
50 | \li \e{AT Servers} notify the clients about events through calls to the |
51 | updateAccessibility() function. |
52 | |
53 | \li \e{AT Clients} request information about the objects in the server. |
54 | The QAccessibleInterface class is the core interface, and encapsulates |
55 | this information in a pure virtual API. Implementations of the interface |
56 | are provided by Qt through the queryAccessibleInterface() API. |
57 | \endlist |
58 | |
59 | The communication between servers and clients is initialized by |
60 | the setRootObject() function. Function pointers can be installed |
61 | to replace or extend the default behavior of the static functions |
62 | in QAccessible. |
63 | |
64 | Qt supports Microsoft Active Accessibility (MSAA), \macos |
65 | Accessibility, and the Unix/X11 AT-SPI standard. Other backends |
66 | can be supported using QAccessibleBridge. |
67 | |
68 | In the Unix/X11 AT-SPI implementation, applications become accessible |
69 | when two conditions are met: |
70 | \list |
71 | \li org.a11y.Status.IsEnabled DBus property is true |
72 | \li org.a11y.Status.ScreenReaderEnabled DBus property is true |
73 | \endlist |
74 | An alternative to setting the DBus AT-SPI properties is to set |
75 | the QT_LINUX_ACCESSIBILITY_ALWAYS_ON environment variable. |
76 | |
77 | In addition to QAccessible's static functions, Qt offers one |
78 | generic interface, QAccessibleInterface, that can be used to wrap |
79 | all widgets and objects (e.g., QPushButton). This single |
80 | interface provides all the metadata necessary for the assistive |
81 | technologies. Qt provides implementations of this interface for |
82 | its built-in widgets as plugins. |
83 | |
84 | When you develop custom widgets, you can create custom subclasses |
85 | of QAccessibleInterface and distribute them as plugins (using |
86 | QAccessiblePlugin) or compile them into the application. |
87 | Likewise, Qt's predefined accessibility support can be built as |
88 | plugin (the default) or directly into the Qt library. The main |
89 | advantage of using plugins is that the accessibility classes are |
90 | only loaded into memory if they are actually used; they don't |
91 | slow down the common case where no assistive technology is being |
92 | used. |
93 | |
94 | Qt also includes two convenience classes, QAccessibleObject and |
95 | QAccessibleWidget, that inherit from QAccessibleInterface and |
96 | provide the lowest common denominator of metadata (e.g., widget |
97 | geometry, window title, basic help text). You can use them as |
98 | base classes when wrapping your custom QObject or QWidget |
99 | subclasses. |
100 | |
101 | \sa QAccessibleInterface |
102 | */ |
103 | |
104 | |
105 | /*! |
106 | \class QAccessible::State |
107 | |
108 | \inmodule QtGui |
109 | |
110 | This structure defines bit flags that indicate |
111 | the state of an accessible object. The values are: |
112 | |
113 | \value active The object is the active window or the active sub-element in a container (that would get focus when focusing the container). |
114 | \value adjustable The object represents an adjustable value, e.g. sliders. |
115 | \value animated The object's appearance changes frequently. |
116 | \value busy The object cannot accept input at the moment. |
117 | \value checkable The object is checkable. |
118 | \value checked The object's check box is checked. |
119 | \value checkStateMixed The third state of checkboxes (half checked in tri-state check boxes). |
120 | \value collapsed The object is collapsed, e.g. a closed listview item, or an iconified window. |
121 | \value defaultButton The object represents the default button in a dialog. |
122 | \value defunct The object no longer exists. |
123 | \value editable The object has a text carret (and often implements the text interface). |
124 | \value expandable The object is expandable, mostly used for cells in a tree view. |
125 | \value expanded The object is expanded, currently its children are visible. |
126 | \value extSelectable The object supports extended selection. |
127 | \value focusable The object can receive focus. Only objects in the active window can receive focus. |
128 | \value focused The object has keyboard focus. |
129 | \value hasPopup The object opens a popup. |
130 | \value hotTracked The object's appearance is sensitive to the mouse cursor position. |
131 | \value invalid The object is no longer valid (because it has been deleted). |
132 | \value invisible The object is not visible to the user. |
133 | \value linked The object is linked to another object, e.g. a hyperlink. |
134 | \value marqueed The object displays scrolling contents, e.g. a log view. |
135 | \value modal The object blocks input from other objects. |
136 | \value movable The object can be moved. |
137 | \value multiLine The object has multiple lines of text (word wrap), as opposed to a single line. |
138 | \value multiSelectable The object supports multiple selected items. |
139 | \value offscreen The object is clipped by the visible area. Objects that are off screen are also invisible. |
140 | \value passwordEdit The object is a password field, e.g. a line edit for entering a Password. |
141 | \value playsSound The object produces sound when interacted with. |
142 | \value pressed The object is pressed. |
143 | \value readOnly The object can usually be edited, but is explicitly set to read-only. |
144 | \value searchEdit The object is a line edit that is the input for search queries. |
145 | \value selectable The object is selectable. |
146 | \value selectableText The object has text which can be selected. This is different from selectable which refers to the object's children. |
147 | \value selected The object is selected, this is independent of text selection. |
148 | \value selfVoicing The object describes itself through speech or sound. |
149 | \value sizeable The object can be resized, e.g. top-level windows. |
150 | \value summaryElement The object summarizes the state of the window and should be treated with priority. |
151 | \value supportsAutoCompletion The object has auto-completion, for example in line edits or combo boxes. |
152 | \value traversed The object is linked and has been visited. |
153 | \value updatesFrequently The object changes frequently and needs to be refreshed when accessing it. |
154 | \value disabled The object is unavailable to the user, e.g. a disabled widget. |
155 | |
156 | Implementations of QAccessibleInterface::state() return a combination |
157 | of these flags. |
158 | */ |
159 | |
160 | /*! |
161 | \fn QAccessible::State::State() |
162 | |
163 | Constructs a new QAccessible::State with all states set to false. |
164 | */ |
165 | |
166 | /*! |
167 | \enum QAccessible::Event |
168 | |
169 | This enum type defines accessible event types. |
170 | |
171 | \omitvalue InvalidEvent \omit Internal: Used when creating subclasses of QAccessibleEvent. \endomit |
172 | \value AcceleratorChanged The keyboard accelerator for an action has been changed. |
173 | \value ActionChanged An action has been changed. |
174 | \value ActiveDescendantChanged |
175 | \value Alert A system alert (e.g., a message from a QMessageBox) |
176 | \value [since 6.8] Announcement The announcement of a message is requested. |
177 | \value AttributeChanged |
178 | \value ContextHelpEnd Context help (QWhatsThis) for an object is finished. |
179 | \value ContextHelpStart Context help (QWhatsThis) for an object is initiated. |
180 | \value DefaultActionChanged The default QAccessible::Action for the accessible |
181 | object has changed. |
182 | \value DescriptionChanged The object's QAccessible::Description changed. |
183 | \value DialogEnd A dialog (QDialog) has been hidden |
184 | \value DialogStart A dialog (QDialog) has been set visible. |
185 | \value DocumentContentChanged The contents of a text document have changed. |
186 | \value DocumentLoadComplete A document has been loaded. |
187 | \value DocumentLoadStopped A document load has been stopped. |
188 | \value DocumentReload A document reload has been initiated. |
189 | \value DragDropEnd A drag and drop operation is about to finished. |
190 | \value DragDropStart A drag and drop operation is about to be initiated. |
191 | \value Focus An object has gained keyboard focus. |
192 | \value ForegroundChanged A window has been activated (i.e., a new window has |
193 | gained focus on the desktop). |
194 | \value HelpChanged The QAccessible::Help text property of an object has |
195 | changed. |
196 | \value HyperlinkEndIndexChanged The end position of the display text for a hypertext |
197 | link has changed. |
198 | \value HyperlinkNumberOfAnchorsChanged The number of anchors in a hypertext link has changed, |
199 | perhaps because the display text has been split to |
200 | provide more than one link. |
201 | \value HyperlinkSelectedLinkChanged The link for the selected hypertext link has changed. |
202 | \value HyperlinkStartIndexChanged The start position of the display text for a hypertext |
203 | link has changed. |
204 | \value HypertextChanged The display text for a hypertext link has changed. |
205 | \value HypertextLinkActivated A hypertext link has been activated, perhaps by being |
206 | clicked or via a key press. |
207 | \value HypertextLinkSelected A hypertext link has been selected. |
208 | \value HypertextNLinksChanged |
209 | \value [since 6.8] IdentifierChanged The identifier of an object has changed. |
210 | \value LocationChanged An object's location on the screen has changed. |
211 | \value MenuCommand A menu item is triggered. |
212 | \value MenuEnd A menu has been closed (Qt uses PopupMenuEnd for all |
213 | menus). |
214 | \value MenuStart A menu has been opened on the menubar (Qt uses |
215 | PopupMenuStart for all menus). |
216 | \value NameChanged The QAccessible::Name property of an object has changed. |
217 | \value ObjectAttributeChanged |
218 | \value ObjectCreated A new object is created. |
219 | \value ObjectDestroyed An object is deleted. |
220 | \value ObjectHide An object is hidden; for example, with QWidget::hide(). |
221 | Any children the object that is hidden has do not send |
222 | this event. It is not sent when an object is hidden as |
223 | it is being obscured by others. |
224 | \value ObjectReorder A layout or item view has added, removed, or moved an |
225 | object (Qt does not use this event). |
226 | \value ObjectShow An object is displayed; for example, with |
227 | QWidget::show(). |
228 | \value PageChanged |
229 | \value ParentChanged An object's parent object changed. |
230 | \value PopupMenuEnd A pop-up menu has closed. |
231 | \value PopupMenuStart A pop-up menu has opened. |
232 | \value ScrollingEnd A scrollbar scroll operation has ended (the mouse has |
233 | released the slider handle). |
234 | \value ScrollingStart A scrollbar scroll operation is about to start; this may |
235 | be caused by a mouse press on the slider handle, for |
236 | example. |
237 | \value SectionChanged |
238 | \value SelectionAdd An item has been added to the selection in an item view. |
239 | \value SelectionRemove An item has been removed from an item view selection. |
240 | \value Selection The selection has changed in a menu or item view. |
241 | \value SelectionWithin Several changes to a selection has occurred in an item |
242 | view. |
243 | \value SoundPlayed A sound has been played by an object |
244 | \omitvalue StateChanged \omit The QAccessible::State of an object has changed. |
245 | This value is used internally for the QAccessibleStateChangeEvent. \endomit |
246 | \value TableCaptionChanged A table caption has been changed. |
247 | \value TableColumnDescriptionChanged The description of a table column, typically found in |
248 | the column's header, has been changed. |
249 | \value TableColumnHeaderChanged A table column header has been changed. |
250 | \omitvalue TableModelChanged \omit The model providing data for a table has been changed. \endomit |
251 | \value TableRowDescriptionChanged The description of a table row, typically found in the |
252 | row's header, has been changed. |
253 | \value TableRowHeaderChanged A table row header has been changed. |
254 | \value TableSummaryChanged The summary of a table has been changed. |
255 | \omitvalue TextAttributeChanged |
256 | \omitvalue TextCaretMoved \omit The caret has moved in an editable widget. |
257 | The caret represents the cursor position in an editable |
258 | widget with the input focus. \endomit |
259 | \value TextColumnChanged A text column has been changed. |
260 | \omitvalue TextInserted \omit Text has been inserted into an editable widget. \endomit |
261 | \omitvalue TextRemoved \omit Text has been removed from an editable widget. \endomit |
262 | \omitvalue TextSelectionChanged \omit The selected text has changed in an editable widget. \endomit |
263 | \omitvalue TextUpdated \omit The text has been update in an editable widget. \endomit |
264 | \omitvalue ValueChanged \omit The QAccessible::Value of an object has changed. \endomit |
265 | \value VisibleDataChanged |
266 | |
267 | The values for this enum are defined to be the same as those defined in the |
268 | \l{AccessibleEventID.idl File Reference}{IAccessible2} and |
269 | \l{Microsoft Active Accessibility Event Constants}{MSAA} specifications. |
270 | */ |
271 | |
272 | /*! |
273 | \enum QAccessible::Role |
274 | |
275 | This enum defines the role of an accessible object. The roles are: |
276 | |
277 | \value AlertMessage An object that is used to alert the user. |
278 | \value Animation An object that displays an animation. |
279 | \value Application The application's main window. |
280 | \value Assistant An object that provides interactive help. |
281 | \value Border An object that represents a border. |
282 | \value ButtonDropDown A button that drops down a list of items. |
283 | \value ButtonDropGrid A button that drops down a grid. |
284 | \value ButtonMenu A button that drops down a menu. |
285 | \value Canvas An object that displays graphics that the user can interact with. |
286 | \value Caret An object that represents the system caret (text cursor). |
287 | \value Cell A cell in a table. |
288 | \value Chart An object that displays a graphical representation of data. |
289 | \value CheckBox An object that represents an option that can be checked or unchecked. Some options provide a "mixed" state, e.g. neither checked nor unchecked. |
290 | \value Client The client area in a window. |
291 | \value Clock A clock displaying time. |
292 | \value ColorChooser A dialog that lets the user choose a color. |
293 | \value Column A column of cells, usually within a table. |
294 | \value ColumnHeader A header for a column of data. |
295 | \value ComboBox A list of choices that the user can select from. |
296 | \value ComplementaryContent A part of the document or web page that is complementary to the main content, usually a landmark (see WAI-ARIA). |
297 | \value Cursor An object that represents the mouse cursor. |
298 | \value Desktop The object represents the desktop or workspace. |
299 | \value Dial An object that represents a dial or knob. |
300 | \value Dialog A dialog box. |
301 | \value Document A document, for example in an office application. |
302 | \value EditableText Editable text such as a line or text edit. |
303 | \value Equation An object that represents a mathematical equation. |
304 | \value Footer A footer in a page (usually in documents). |
305 | \value Form A web form containing controls. |
306 | \value Graphic A graphic or picture, e.g. an icon. |
307 | \value Grip A grip that the user can drag to change the size of widgets. |
308 | \value Grouping An object that represents a logical grouping of other objects. |
309 | \value Heading A heading in a document. |
310 | \value HelpBalloon An object that displays help in a separate, short lived window. |
311 | \value HotkeyField A hotkey field that allows the user to enter a key sequence. |
312 | \value Indicator An indicator that represents a current value or item. |
313 | \value LayeredPane An object that can contain layered children, e.g. in a stack. |
314 | \value Link A link to something else. |
315 | \value List A list of items, from which the user can select one or more items. |
316 | \value ListItem An item in a list of items. |
317 | \value MenuBar A menu bar from which menus are opened by the user. |
318 | \value MenuItem An item in a menu or menu bar. |
319 | \value NoRole The object has no role. This usually indicates an invalid object. |
320 | \value Note A section whose content is parenthetic or ancillary to the main content of the resource. |
321 | \value Notification An object that represents a notification (e.g. in the system tray). This role only has an effect on Linux. |
322 | \value PageTab A page tab that the user can select to switch to a different page in a dialog. |
323 | \value PageTabList A list of page tabs. |
324 | \value Paragraph A paragraph of text (usually found in documents). |
325 | \value Pane A generic container. |
326 | \value PopupMenu A menu which lists options that the user can select to perform an action. |
327 | \value ProgressBar The object displays the progress of an operation in progress. |
328 | \value PropertyPage A property page where the user can change options and settings. |
329 | \value Button A button. |
330 | \value RadioButton An object that represents an option that is mutually exclusive with other options. |
331 | \value Row A row of cells, usually within a table. |
332 | \value RowHeader A header for a row of data. |
333 | \value ScrollBar A scroll bar, which allows the user to scroll the visible area. |
334 | \value Section A section (in a document). |
335 | \value Separator A separator that divides space into logical areas. |
336 | \value Slider A slider that allows the user to select a value within a given range. |
337 | \value Sound An object that represents a sound. |
338 | \value SpinBox A spin box widget that allows the user to enter a value within a given range. |
339 | \value Splitter A splitter distributing available space between its child widgets. |
340 | \value StaticText Static text, such as labels for other widgets. |
341 | \value StatusBar A status bar. |
342 | \value Table A table representing data in a grid of rows and columns. |
343 | \value Terminal A terminal or command line interface. |
344 | \value TitleBar The title bar caption of a window. |
345 | \value ToolBar A tool bar, which groups widgets that the user accesses frequently. |
346 | \value ToolTip A tool tip which provides information about other objects. |
347 | \value Tree A list of items in a tree structure. |
348 | \value TreeItem An item in a tree structure. |
349 | \value UserRole The first value to be used for user defined roles. |
350 | \value WebDocument HTML document, usually in a browser. |
351 | \value Whitespace Blank space between other objects. |
352 | \value Window A top level window. |
353 | */ |
354 | |
355 | /*! |
356 | \enum QAccessible::RelationFlag |
357 | |
358 | This enum type defines bit flags that can be combined to indicate |
359 | the relationship between two accessible objects. It is used by |
360 | the relations() function, which returns a list of all the related |
361 | interfaces of the calling object, together with the relations |
362 | for each object. |
363 | |
364 | Each entry in the list is a QPair where the \c second member stores |
365 | the relation type(s) between the \c returned object represented by the |
366 | \c first member and the \c origin (the caller) interface/object. |
367 | |
368 | In the table below, the \c returned object refers to the object in |
369 | the returned list, and the \c origin object is the one represented |
370 | by the calling interface. |
371 | |
372 | \value Label The \c returned object is the label for the \c origin object. |
373 | \value Labelled The \c returned object is labelled by the \c origin object. |
374 | \value Controller The \c returned object controls the \c origin object. |
375 | \value Controlled The \c returned object is controlled by the \c origin object. |
376 | \value [since 6.6] DescriptionFor The \c returned object provides a description for the \c origin object. |
377 | \value [since 6.6] Described The \c returned object is described by the \c origin object. |
378 | \value [since 6.6] FlowsFrom Content logically flows from the \c returned object to the \c origin object. |
379 | \value [since 6.6] FlowsTo Content logically flows to the \c returned object from the \c origin object. |
380 | \value AllRelations Used as a mask to specify that we are interesting in information |
381 | about all relations |
382 | |
383 | Implementations of relations() return a combination of these flags. |
384 | Some values are mutually exclusive. |
385 | */ |
386 | |
387 | /*! |
388 | \enum QAccessible::Text |
389 | |
390 | This enum specifies string information that an accessible object |
391 | returns. |
392 | |
393 | \value Name The name of the object. This can be used both |
394 | as an identifier or a short description by |
395 | accessible clients. |
396 | \value Description A short text describing the object. |
397 | \value Value The value of the object. |
398 | \value Help A longer text giving information about how to use the object. |
399 | \value Accelerator The keyboard shortcut that executes the object's default action. |
400 | \value UserText The first value to be used for user defined text. |
401 | \value [since 6.8] Identifier An identifier for the object for e.g. UI tests. |
402 | \omitvalue DebugDescription |
403 | */ |
404 | |
405 | /*! \enum QAccessible::TextBoundaryType |
406 | This enum describes different types of text boundaries. It follows the IAccessible2 API and is used in the \l QAccessibleTextInterface. |
407 | |
408 | \value CharBoundary Use individual characters as boundary. |
409 | \value WordBoundary Use words as boundaries. |
410 | \value SentenceBoundary Use sentences as boundary. |
411 | \value ParagraphBoundary Use paragraphs as boundary. |
412 | \value LineBoundary Use newlines as boundary. |
413 | \value NoBoundary No boundary (use the whole text). |
414 | |
415 | \sa QAccessibleTextInterface |
416 | */ |
417 | |
418 | /*! \enum QAccessible::Attribute |
419 | This enum describes different types of attributes used by the |
420 | \l QAccessibleAttributesInterface. |
421 | \since 6.8 |
422 | |
423 | These attributes are comparable to the concept of properties/(object) |
424 | attributes found in ARIA, AT-SPI2, IAccessible, UIA and NSAccessibility |
425 | and are mapped to their platform counterpart where applicable. |
426 | |
427 | Each attribute is handled as a key-value pair, with the values of this |
428 | enumeration being used as keys. |
429 | |
430 | Attribute values are represented in a \l QVariant. The type of the value |
431 | stored in the \l QVariant is fixed and specified below for each of the |
432 | attribute types. |
433 | |
434 | \value Custom value type: \a QHash<QString, QString> |
435 | The \a Custom attribute is special in that |
436 | it can effectively represent multiple attributes at |
437 | once, since it itself is a \l QHash used to represent |
438 | key-value pairs. |
439 | For platforms supporting custom key-value pairs for |
440 | attributes, those set in the \a Custom attribute |
441 | are bridged to the platform layer without applying any |
442 | translation to platform-specific attributes. In general, |
443 | the other, more strongly typed attributes should be used. |
444 | This attribute can e.g. be used for prototyping |
445 | before officially adding an official new enumeration value |
446 | for a specific feature. |
447 | \value Level value type: \a int |
448 | Defines the hierarchical level of an element within a structure, |
449 | e.g. the heading level of a heading. This attribute conceptually |
450 | matches the "aria-level" property in ARIA. |
451 | |
452 | \sa QAccessibleAttributesInterface |
453 | */ |
454 | |
455 | /*! \enum QAccessible::AnnouncementPoliteness |
456 | This enum describes the priority for announcements used by the |
457 | \l QAccessibleAnnouncementEvent. |
458 | \since 6.8 |
459 | |
460 | With \a QAccessible::AnouncementPoliteness::Polite, assistive technologies |
461 | should announce the message at the next graceful opportunity such as at the |
462 | end of speaking the current sentence or when the user pauses typing. |
463 | |
464 | When specifying \a QAccessible::AnouncementPoliteness::Assertive, assistive |
465 | technologies should notify the user immediately. |
466 | |
467 | Because an interruption might disorient users or cause them to not complete |
468 | their current task, \a QAccessible::AnouncementPoliteness::Assertive should |
469 | not be used unless the interruption is imperative. |
470 | |
471 | \value Polite The announcement has normal priority. |
472 | \value Assertive The announcement has high priority and should notify |
473 | the user immediately, even if that means interrupting the user's |
474 | current task. |
475 | |
476 | \sa QAccessibleAnnouncementEvent |
477 | */ |
478 | |
479 | |
480 | /*! |
481 | \enum QAccessible::InterfaceType |
482 | |
483 | \l QAccessibleInterface supports several sub interfaces. |
484 | In order to provide more information about some objects, their accessible |
485 | representation should implement one or more of these interfaces. |
486 | |
487 | \note When subclassing one of these interfaces, \l QAccessibleInterface::interface_cast() needs to be implemented. |
488 | |
489 | \value TextInterface For text that supports selections or is more than one line. Simple labels do not need to implement this interface. |
490 | \omitvalue EditableTextInterface \omit For text that can be edited by the user. \endomit |
491 | \value ValueInterface For objects that are used to manipulate a value, for example slider or scroll bar. |
492 | \value ActionInterface For interactive objects that allow the user to trigger an action. Basically everything that allows for example mouse interaction. |
493 | \omitvalue ImageInterface \omit For objects that represent an image. This interface is generally less important. \endomit |
494 | \value TableInterface For lists, tables and trees. |
495 | \value TableCellInterface For cells in a TableInterface object. |
496 | \value HyperlinkInterface For hyperlink nodes (usually embedded as children of text nodes) |
497 | \value [since 6.5] SelectionInterface For non-text objects that support selection of child objects. |
498 | \value [since 6.8] AttributesInterface For objects that support object-specific attributes. |
499 | |
500 | \sa QAccessibleInterface::interface_cast(), QAccessibleTextInterface, QAccessibleValueInterface, QAccessibleActionInterface, QAccessibleTableInterface, QAccessibleTableCellInterface, QAccessibleSelectionInterface, QAccessibleAttributesInterface |
501 | */ |
502 | |
503 | #if QT_CONFIG(accessibility) |
504 | |
505 | /*! |
506 | Destroys the QAccessibleInterface. |
507 | */ |
508 | QAccessibleInterface::~QAccessibleInterface() |
509 | { |
510 | } |
511 | |
512 | /*! |
513 | \typedef QAccessible::Id |
514 | |
515 | Synonym for unsigned, used by the QAccessibleInterface cache. |
516 | */ |
517 | |
518 | |
519 | /* accessible widgets plugin discovery stuff */ |
520 | Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, acLoader, |
521 | (QAccessibleFactoryInterface_iid, "/accessible"_L1 )) |
522 | typedef QHash<QString, QAccessiblePlugin*> QAccessiblePluginsHash; |
523 | Q_GLOBAL_STATIC(QAccessiblePluginsHash, qAccessiblePlugins) |
524 | |
525 | // FIXME turn this into one global static struct |
526 | Q_GLOBAL_STATIC(QList<QAccessible::InterfaceFactory>, qAccessibleFactories) |
527 | Q_GLOBAL_STATIC(QList<QAccessible::ActivationObserver *>, qAccessibleActivationObservers) |
528 | |
529 | QAccessible::UpdateHandler QAccessible::updateHandler = nullptr; |
530 | QAccessible::RootObjectHandler QAccessible::rootObjectHandler = nullptr; |
531 | |
532 | static bool cleanupAdded = false; |
533 | |
534 | static QPlatformAccessibility *platformAccessibility() |
535 | { |
536 | QPlatformIntegration *pfIntegration = QGuiApplicationPrivate::platformIntegration(); |
537 | return pfIntegration ? pfIntegration->accessibility() : nullptr; |
538 | } |
539 | |
540 | /*! |
541 | \fn QAccessible::QAccessible() |
542 | \internal |
543 | |
544 | This class is purely a collection of enums and static functions, |
545 | it is not supposed to be instantiated. |
546 | */ |
547 | |
548 | |
549 | /*! |
550 | \internal |
551 | */ |
552 | void QAccessible::cleanup() |
553 | { |
554 | if (QPlatformAccessibility *pfAccessibility = platformAccessibility()) |
555 | pfAccessibility->cleanup(); |
556 | } |
557 | |
558 | static void qAccessibleCleanup() |
559 | { |
560 | qAccessibleActivationObservers()->clear(); |
561 | qAccessibleFactories()->clear(); |
562 | } |
563 | |
564 | /*! |
565 | \typedef QAccessible::InterfaceFactory |
566 | |
567 | This is a typedef for a pointer to a function with the following |
568 | signature: |
569 | |
570 | \snippet code/src_gui_accessible_qaccessible.cpp 1 |
571 | |
572 | The function receives a QString and a QObject pointer, where the |
573 | QString is the key identifying the interface. The QObject is used |
574 | to pass on to the QAccessibleInterface so that it can hold a reference |
575 | to it. |
576 | |
577 | If the key and the QObject does not have a corresponding |
578 | QAccessibleInterface, \nullptr will be returned. |
579 | |
580 | Installed factories are called by queryAccessibilityInterface() until |
581 | one provides an interface. |
582 | */ |
583 | |
584 | /*! |
585 | \typedef QAccessible::UpdateHandler |
586 | |
587 | \internal |
588 | |
589 | A function pointer type. Use a function with this prototype to install |
590 | your own update function. |
591 | |
592 | The function is called by updateAccessibility(). |
593 | */ |
594 | |
595 | /*! |
596 | \typedef QAccessible::RootObjectHandler |
597 | |
598 | \internal |
599 | |
600 | A function pointer type. Use a function with this prototype to install |
601 | your own root object handler. |
602 | |
603 | The function is called by setRootObject(). |
604 | */ |
605 | |
606 | |
607 | /*! |
608 | Installs the InterfaceFactory \a factory. The last factory added |
609 | is the first one used by queryAccessibleInterface(). |
610 | */ |
611 | void QAccessible::installFactory(InterfaceFactory factory) |
612 | { |
613 | if (!factory) |
614 | return; |
615 | |
616 | if (!cleanupAdded) { |
617 | qAddPostRoutine(qAccessibleCleanup); |
618 | cleanupAdded = true; |
619 | } |
620 | if (qAccessibleFactories()->contains(t: factory)) |
621 | return; |
622 | qAccessibleFactories()->append(t: factory); |
623 | } |
624 | |
625 | /*! |
626 | Removes \a factory from the list of installed InterfaceFactories. |
627 | */ |
628 | void QAccessible::removeFactory(InterfaceFactory factory) |
629 | { |
630 | qAccessibleFactories()->removeAll(t: factory); |
631 | } |
632 | |
633 | /*! |
634 | \internal |
635 | |
636 | Installs the given \a handler as the function to be used by |
637 | updateAccessibility(), and returns the previously installed |
638 | handler. |
639 | */ |
640 | QAccessible::UpdateHandler QAccessible::installUpdateHandler(UpdateHandler handler) |
641 | { |
642 | UpdateHandler old = updateHandler; |
643 | updateHandler = handler; |
644 | return old; |
645 | } |
646 | |
647 | /*! |
648 | \internal |
649 | |
650 | Installs the given \a handler as the function to be used by setRootObject(), |
651 | and returns the previously installed handler. |
652 | */ |
653 | QAccessible::RootObjectHandler QAccessible::installRootObjectHandler(RootObjectHandler handler) |
654 | { |
655 | RootObjectHandler old = rootObjectHandler; |
656 | rootObjectHandler = handler; |
657 | return old; |
658 | } |
659 | |
660 | /*! |
661 | \class QAccessible::ActivationObserver |
662 | \internal |
663 | |
664 | Interface to listen to activation or deactivation of the accessibility framework. |
665 | \sa installActivationObserver() |
666 | */ |
667 | |
668 | QAccessible::ActivationObserver::~ActivationObserver() |
669 | { |
670 | } |
671 | |
672 | /*! |
673 | \internal |
674 | |
675 | Install \a observer to get notified of activation or deactivation (global accessibility has been enabled or disabled). |
676 | */ |
677 | void QAccessible::installActivationObserver(QAccessible::ActivationObserver *observer) |
678 | { |
679 | if (!observer) |
680 | return; |
681 | |
682 | if (!cleanupAdded) { |
683 | qAddPostRoutine(qAccessibleCleanup); |
684 | cleanupAdded = true; |
685 | } |
686 | if (qAccessibleActivationObservers()->contains(t: observer)) |
687 | return; |
688 | qAccessibleActivationObservers()->append(t: observer); |
689 | } |
690 | |
691 | /*! |
692 | \internal |
693 | |
694 | Remove an \a observer to no longer get notified of state changes. |
695 | \sa installActivationObserver() |
696 | */ |
697 | void QAccessible::removeActivationObserver(ActivationObserver *observer) |
698 | { |
699 | qAccessibleActivationObservers()->removeAll(t: observer); |
700 | } |
701 | |
702 | /*! |
703 | If a QAccessibleInterface implementation exists for the given \a object, |
704 | this function returns a pointer to the implementation; otherwise it |
705 | returns \nullptr. |
706 | |
707 | The function calls all installed factory functions (from most |
708 | recently installed to least recently installed) until one is found |
709 | that provides an interface for the class of \a object. If no |
710 | factory can provide an accessibility implementation for the class |
711 | the function loads installed accessibility plugins, and tests if |
712 | any of the plugins can provide the implementation. |
713 | |
714 | If no implementation for the object's class is available, the |
715 | function tries to find an implementation for the object's parent |
716 | class, using the above strategy. |
717 | |
718 | All interfaces are managed by an internal cache and should not be deleted. |
719 | */ |
720 | QAccessibleInterface *QAccessible::queryAccessibleInterface(QObject *object) |
721 | { |
722 | if (!object) |
723 | return nullptr; |
724 | |
725 | if (Id id = QAccessibleCache::instance()->idForObject(obj: object)) |
726 | return QAccessibleCache::instance()->interfaceForId(id); |
727 | |
728 | // Create a QAccessibleInterface for the object class. Start by the most |
729 | // derived class and walk up the class hierarchy. |
730 | const QMetaObject *mo = object->metaObject(); |
731 | const auto *objectPriv = QObjectPrivate::get(o: object); |
732 | /* |
733 | We do not want to cache each and every QML metaobject (Button_QMLTYPE_124, |
734 | Button_QMLTYPE_125, etc.). Those dynamic metaobjects shouldn't have an |
735 | accessible interface in any case. Instead, we start the whole checking |
736 | with the first non-dynamic meta-object. To avoid potential regressions |
737 | in other areas of Qt that also use dynamic metaobjects, we only do this |
738 | for objects that are QML-related (approximated by checking whether they |
739 | have ddata set). |
740 | */ |
741 | const bool qmlRelated = !objectPriv->isDeletingChildren && |
742 | objectPriv->declarativeData; |
743 | while (qmlRelated && mo) { |
744 | auto mop = QMetaObjectPrivate::get(metaobject: mo); |
745 | if (!mop || !(mop->flags & DynamicMetaObject)) |
746 | break; |
747 | |
748 | mo = mo->superClass(); |
749 | }; |
750 | while (mo) { |
751 | const QString cn = QLatin1StringView(mo->className()); |
752 | |
753 | // Check if the class has a InterfaceFactory installed. |
754 | for (int i = qAccessibleFactories()->size(); i > 0; --i) { |
755 | InterfaceFactory factory = qAccessibleFactories()->at(i: i - 1); |
756 | if (QAccessibleInterface *iface = factory(cn, object)) { |
757 | QAccessibleCache::instance()->insert(object, iface); |
758 | Q_ASSERT(QAccessibleCache::instance()->containsObject(object)); |
759 | return iface; |
760 | } |
761 | } |
762 | // Find a QAccessiblePlugin (factory) for the class name. If there's |
763 | // no entry in the cache try to create it using the plugin loader. |
764 | if (!qAccessiblePlugins()->contains(key: cn)) { |
765 | QAccessiblePlugin *factory = nullptr; // 0 means "no plugin found". This is cached as well. |
766 | const int index = acLoader()->indexOf(needle: cn); |
767 | if (index != -1) |
768 | factory = qobject_cast<QAccessiblePlugin *>(object: acLoader()->instance(index)); |
769 | qAccessiblePlugins()->insert(key: cn, value: factory); |
770 | } |
771 | |
772 | // At this point the cache should contain a valid factory pointer or 0: |
773 | Q_ASSERT(qAccessiblePlugins()->contains(cn)); |
774 | QAccessiblePlugin *factory = qAccessiblePlugins()->value(key: cn); |
775 | if (factory) { |
776 | QAccessibleInterface *result = factory->create(key: cn, object); |
777 | if (result) { |
778 | QAccessibleCache::instance()->insert(object, iface: result); |
779 | Q_ASSERT(QAccessibleCache::instance()->containsObject(object)); |
780 | } |
781 | return result; |
782 | } |
783 | mo = mo->superClass(); |
784 | } |
785 | |
786 | if (object == qApp) { |
787 | QAccessibleInterface *appInterface = new QAccessibleApplication; |
788 | QAccessibleCache::instance()->insert(object, iface: appInterface); |
789 | Q_ASSERT(QAccessibleCache::instance()->containsObject(qApp)); |
790 | return appInterface; |
791 | } |
792 | |
793 | return nullptr; |
794 | } |
795 | |
796 | /*! |
797 | \brief Call this function to ensure that manually created interfaces |
798 | are properly memory managed. |
799 | |
800 | Must only be called exactly once per interface \a iface. |
801 | This is implicitly called when calling queryAccessibleInterface, |
802 | calling this function is only required when QAccessibleInterfaces |
803 | are instantiated with the "new" operator. This is not recommended, |
804 | whenever possible use the default functions and let \l queryAccessibleInterface() |
805 | take care of this. |
806 | |
807 | When it is necessary to reimplement the QAccessibleInterface::child() function |
808 | and returning the child after constructing it, this function needs to be called. |
809 | */ |
810 | QAccessible::Id QAccessible::registerAccessibleInterface(QAccessibleInterface *iface) |
811 | { |
812 | Q_ASSERT(iface); |
813 | return QAccessibleCache::instance()->insert(object: iface->object(), iface); |
814 | } |
815 | |
816 | /*! |
817 | Removes the interface belonging to this \a id from the cache and |
818 | deletes it. The id becomes invalid an may be re-used by the |
819 | cache. |
820 | */ |
821 | void QAccessible::deleteAccessibleInterface(Id id) |
822 | { |
823 | QAccessibleCache::instance()->deleteInterface(id); |
824 | } |
825 | |
826 | /*! |
827 | Returns the unique ID for the QAccessibleInterface \a iface. |
828 | */ |
829 | QAccessible::Id QAccessible::uniqueId(QAccessibleInterface *iface) |
830 | { |
831 | Id id = QAccessibleCache::instance()->idForInterface(iface); |
832 | if (!id) |
833 | id = registerAccessibleInterface(iface); |
834 | return id; |
835 | } |
836 | |
837 | /*! |
838 | Returns the QAccessibleInterface belonging to the \a id. |
839 | |
840 | Returns \nullptr if the id is invalid. |
841 | */ |
842 | QAccessibleInterface *QAccessible::accessibleInterface(Id id) |
843 | { |
844 | return QAccessibleCache::instance()->interfaceForId(id); |
845 | } |
846 | |
847 | |
848 | /*! |
849 | Returns \c true if the platform requested accessibility information. |
850 | |
851 | This function will return false until a tool such as a screen reader |
852 | accessed the accessibility framework. It is still possible to use |
853 | \l QAccessible::queryAccessibleInterface() even if accessibility is not |
854 | active. But there will be no notifications sent to the platform. |
855 | |
856 | It is recommended to use this function to prevent expensive notifications |
857 | via updateAccessibility() when they are not needed. |
858 | */ |
859 | bool QAccessible::isActive() |
860 | { |
861 | if (QPlatformAccessibility *pfAccessibility = platformAccessibility()) |
862 | return pfAccessibility->isActive(); |
863 | return false; |
864 | } |
865 | |
866 | /*! |
867 | \internal |
868 | */ |
869 | void QAccessible::setActive(bool active) |
870 | { |
871 | for (int i = 0; i < qAccessibleActivationObservers()->size() ;++i) |
872 | qAccessibleActivationObservers()->at(i)->accessibilityActiveChanged(active); |
873 | } |
874 | |
875 | |
876 | /*! |
877 | Sets the root object of the accessible objects of this application |
878 | to \a object. All other accessible objects are reachable using object |
879 | navigation from the root object. |
880 | |
881 | Normally, it isn't necessary to call this function, because Qt sets |
882 | the QApplication object as the root object immediately before the |
883 | event loop is entered in QApplication::exec(). |
884 | |
885 | Use QAccessible::installRootObjectHandler() to redirect the function |
886 | call to a customized handler function. |
887 | |
888 | \sa queryAccessibleInterface() |
889 | */ |
890 | void QAccessible::setRootObject(QObject *object) |
891 | { |
892 | if (rootObjectHandler) { |
893 | rootObjectHandler(object); |
894 | return; |
895 | } |
896 | |
897 | if (QPlatformAccessibility *pfAccessibility = platformAccessibility()) |
898 | pfAccessibility->setRootObject(object); |
899 | } |
900 | |
901 | /*! |
902 | Notifies about a change that might be relevant for accessibility clients. |
903 | |
904 | \a event provides details about the change. These include the source |
905 | of the change and the nature of the change. The \a event should |
906 | contain enough information give meaningful notifications. |
907 | |
908 | For example, the type \c ValueChange indicates that the position of |
909 | a slider has been changed. |
910 | |
911 | Call this function whenever the state of your accessible object or |
912 | one of its sub-elements has been changed either programmatically |
913 | (e.g. by calling QLabel::setText()) or by user interaction. |
914 | |
915 | If there are no accessibility tools listening to this event, the |
916 | performance penalty for calling this function is small, but if |
917 | determining the parameters of the call is expensive you can test |
918 | QAccessible::isActive() to avoid unnecessary computation. |
919 | */ |
920 | void QAccessible::updateAccessibility(QAccessibleEvent *event) |
921 | { |
922 | // NOTE: Querying for the accessibleInterface below will result in |
923 | // resolving and caching the interface, which in some cases will |
924 | // cache the wrong information as updateAccessibility is called |
925 | // during construction of widgets. If you see cases where the |
926 | // cache seems wrong, this call is "to blame", but the code that |
927 | // caches dynamic data should be updated to handle change events. |
928 | QAccessibleInterface *iface = event->accessibleInterface(); |
929 | if (isActive() && iface) { |
930 | if (event->type() == QAccessible::TableModelChanged) { |
931 | if (iface->tableInterface()) |
932 | iface->tableInterface()->modelChange(event: static_cast<QAccessibleTableModelChangeEvent*>(event)); |
933 | } |
934 | } |
935 | |
936 | if (updateHandler) { |
937 | updateHandler(event); |
938 | return; |
939 | } |
940 | |
941 | if (QPlatformAccessibility *pfAccessibility = platformAccessibility()) |
942 | pfAccessibility->notifyAccessibilityUpdate(event); |
943 | } |
944 | |
945 | /*! |
946 | \internal |
947 | \brief getBoundaries is a helper function to find the accessible text boundaries for QTextCursor based documents. |
948 | \param documentCursor a valid cursor bound to the document (not null). It needs to ba at the position to look for the boundary |
949 | \param boundaryType the type of boundary to find |
950 | \return the boundaries as pair |
951 | */ |
952 | QPair< int, int > QAccessible::qAccessibleTextBoundaryHelper(const QTextCursor &offsetCursor, TextBoundaryType boundaryType) |
953 | { |
954 | Q_ASSERT(!offsetCursor.isNull()); |
955 | |
956 | QTextCursor endCursor = offsetCursor; |
957 | endCursor.movePosition(op: QTextCursor::End); |
958 | int characterCount = endCursor.position(); |
959 | |
960 | QPair<int, int> result; |
961 | QTextCursor cursor = offsetCursor; |
962 | switch (boundaryType) { |
963 | case CharBoundary: |
964 | result.first = cursor.position(); |
965 | cursor.movePosition(op: QTextCursor::NextCharacter, QTextCursor::KeepAnchor); |
966 | result.second = cursor.position(); |
967 | break; |
968 | case WordBoundary: |
969 | cursor.movePosition(op: QTextCursor::StartOfWord, QTextCursor::MoveAnchor); |
970 | result.first = cursor.position(); |
971 | cursor.movePosition(op: QTextCursor::EndOfWord, QTextCursor::KeepAnchor); |
972 | result.second = cursor.position(); |
973 | break; |
974 | case SentenceBoundary: { |
975 | // QCursor does not provide functionality to move to next sentence. |
976 | // We therefore find the current block, then go through the block using |
977 | // QTextBoundaryFinder and find the sentence the \offset represents |
978 | cursor.movePosition(op: QTextCursor::StartOfBlock, QTextCursor::MoveAnchor); |
979 | result.first = cursor.position(); |
980 | cursor.movePosition(op: QTextCursor::EndOfBlock, QTextCursor::KeepAnchor); |
981 | result.second = cursor.position(); |
982 | QString blockText = cursor.selectedText(); |
983 | const int offsetWithinBlockText = offsetCursor.position() - result.first; |
984 | QTextBoundaryFinder sentenceFinder(QTextBoundaryFinder::Sentence, blockText); |
985 | sentenceFinder.setPosition(offsetWithinBlockText); |
986 | int prevBoundary = offsetWithinBlockText; |
987 | int nextBoundary = offsetWithinBlockText; |
988 | if (!(sentenceFinder.boundaryReasons() & QTextBoundaryFinder::StartOfItem)) |
989 | prevBoundary = sentenceFinder.toPreviousBoundary(); |
990 | nextBoundary = sentenceFinder.toNextBoundary(); |
991 | if (nextBoundary != -1) |
992 | result.second = result.first + nextBoundary; |
993 | if (prevBoundary != -1) |
994 | result.first += prevBoundary; |
995 | break; } |
996 | case LineBoundary: |
997 | cursor.movePosition(op: QTextCursor::StartOfLine, QTextCursor::MoveAnchor); |
998 | result.first = cursor.position(); |
999 | cursor.movePosition(op: QTextCursor::EndOfLine, QTextCursor::KeepAnchor); |
1000 | result.second = cursor.position(); |
1001 | break; |
1002 | case ParagraphBoundary: |
1003 | cursor.movePosition(op: QTextCursor::StartOfBlock, QTextCursor::MoveAnchor); |
1004 | result.first = cursor.position(); |
1005 | cursor.movePosition(op: QTextCursor::EndOfBlock, QTextCursor::KeepAnchor); |
1006 | result.second = cursor.position(); |
1007 | break; |
1008 | case NoBoundary: |
1009 | result.first = 0; |
1010 | result.second = characterCount; |
1011 | break; |
1012 | } |
1013 | return result; |
1014 | } |
1015 | |
1016 | /*! |
1017 | \class QAccessibleInterface |
1018 | \brief The QAccessibleInterface class defines an interface that exposes information |
1019 | about accessible objects. |
1020 | |
1021 | \ingroup accessibility |
1022 | \inmodule QtGui |
1023 | |
1024 | This class is part of \l {Accessibility for QWidget Applications}. |
1025 | |
1026 | Accessibility tools (also called AT Clients), such as screen readers |
1027 | or braille displays, require high-level information about |
1028 | accessible objects in an application. Accessible objects provide |
1029 | specialized input and output methods, making it possible for users |
1030 | to use accessibility tools with enabled applications (AT Servers). |
1031 | |
1032 | Every element that the user needs to interact with or react to is |
1033 | an accessible object, and should provide this information. These |
1034 | are mainly visual objects, such as widgets and widget elements, but |
1035 | can also be content, such as sounds. |
1036 | |
1037 | The AT client uses three basic concepts to acquire information |
1038 | about any accessible object in an application: |
1039 | \list |
1040 | \li \e Properties The client can read information about |
1041 | accessible objects. In some cases the client can also modify these |
1042 | properties; such as text in a line edit. |
1043 | \li \e Actions The client can invoke actions like pressing a button |
1044 | or . |
1045 | \li \e{Relationships and Navigation} The client can traverse from one |
1046 | accessible object to another, using the relationships between objects. |
1047 | \endlist |
1048 | |
1049 | The QAccessibleInterface defines the API for these three concepts. |
1050 | |
1051 | \section1 Relationships and Navigation |
1052 | |
1053 | The functions childCount() and indexOfChild() return the number of |
1054 | children of an accessible object and the index a child object has |
1055 | in its parent. The childAt() function returns a child QAccessibleInterface |
1056 | that is found at a position. The child does not have to be a direct |
1057 | child. This allows bypassing intermediate layers when the parent already knows the |
1058 | top-most child. childAt() is used for hit testing (finding the object |
1059 | under the mouse). |
1060 | |
1061 | The relations() function provides information about the relations an |
1062 | object has to other objects, and parent() and child() allows |
1063 | traversing from one object to another object. |
1064 | |
1065 | \section1 Properties |
1066 | |
1067 | The central property of an accessible objects is what role() it |
1068 | has. Different objects can have the same role, e.g. both the "Add |
1069 | line" element in a scroll bar and the \c OK button in a dialog have |
1070 | the same role, "button". The role implies what kind of |
1071 | interaction the user can perform with the user interface element. |
1072 | |
1073 | An object's state() property is a combination of different state |
1074 | flags and can describe both how the object's state differs from a |
1075 | "normal" state, e.g. it might be unavailable, and also how it |
1076 | behaves, e.g. it might be selectable. |
1077 | |
1078 | The text() property provides textual information about the object. |
1079 | An object usually has a name, but can provide extended information |
1080 | such as a description, help text, or information about any |
1081 | keyboard accelerators it provides. Some objects allow changing the |
1082 | text() property through the setText() function, but this |
1083 | information is in most cases read-only. |
1084 | |
1085 | The rect() property provides information about the geometry of an |
1086 | accessible object. This information is usually only available for |
1087 | visual objects. |
1088 | |
1089 | \section1 Interfaces |
1090 | |
1091 | To enable the user to interact with an accessible object the |
1092 | object must implement QAccessibleActionInterface in addition to |
1093 | QAccessibleInterface. |
1094 | Objects that support selections can define actions to change the selection. |
1095 | |
1096 | There are several other interfaces that should be implemented as required. |
1097 | QAccessibleTextInterface should be used for bigger texts edits such as document views. |
1098 | This interface should not be implemented for labels/single line edits. |
1099 | |
1100 | For sliders, scrollbars and other numerical value selectors QAccessibleValueInterface |
1101 | should be implemented. |
1102 | |
1103 | Lists, tables and trees should implement QAccessibleTableInterface. |
1104 | |
1105 | \sa QAccessible, QAccessibleActionInterface, QAccessibleTextInterface, QAccessibleValueInterface, QAccessibleTableInterface |
1106 | */ |
1107 | |
1108 | /*! |
1109 | \fn bool QAccessibleInterface::isValid() const |
1110 | |
1111 | Returns \c true if all the data necessary to use this interface |
1112 | implementation is valid (e.g. all pointers are non-null); |
1113 | otherwise returns \c false. |
1114 | |
1115 | \sa object() |
1116 | */ |
1117 | |
1118 | /*! |
1119 | \fn QObject *QAccessibleInterface::object() const |
1120 | |
1121 | Returns a pointer to the QObject this interface implementation provides |
1122 | information for. |
1123 | |
1124 | \sa isValid() |
1125 | */ |
1126 | |
1127 | /*! |
1128 | \fn int QAccessibleInterface::childCount() const |
1129 | |
1130 | Returns the number of children that belong to this object. A child |
1131 | can provide accessibility information on its own (e.g. a child |
1132 | widget), or be a sub-element of this accessible object. |
1133 | |
1134 | All objects provide this information. |
1135 | |
1136 | \sa indexOfChild() |
1137 | */ |
1138 | |
1139 | /*! |
1140 | \fn int QAccessibleInterface::indexOfChild(const QAccessibleInterface *child) const |
1141 | |
1142 | Returns the 0-based index of the object \a child in this object's |
1143 | children list, or -1 if \a child is not a child of this object. |
1144 | |
1145 | All objects provide this information about their children. |
1146 | |
1147 | \sa childCount() |
1148 | */ |
1149 | |
1150 | /*! |
1151 | Returns the meaningful relations to other widgets. Usually this will not return parent/child |
1152 | relations, unless they are handled in a specific way such as in tree views. |
1153 | It will typically return the labelled-by and label relations. |
1154 | |
1155 | It is possible to filter the relations by using the optional parameter \a match. |
1156 | It should never return itself. |
1157 | |
1158 | \sa parent(), child() |
1159 | */ |
1160 | QList<QPair<QAccessibleInterface*, QAccessible::Relation>> |
1161 | QAccessibleInterface::relations(QAccessible::Relation match) const |
1162 | { |
1163 | Q_UNUSED(match); |
1164 | return { }; |
1165 | } |
1166 | |
1167 | /*! |
1168 | Returns the object that has the keyboard focus. |
1169 | |
1170 | The object returned can be any descendant, including itself. |
1171 | */ |
1172 | QAccessibleInterface *QAccessibleInterface::focusChild() const |
1173 | { |
1174 | return nullptr; |
1175 | } |
1176 | |
1177 | /*! |
1178 | \fn QAccessibleInterface *QAccessibleInterface::childAt(int x, int y) const |
1179 | |
1180 | Returns the QAccessibleInterface of a child that contains the screen coordinates (\a x, \a y). |
1181 | If there are no children at this position this function returns \nullptr. |
1182 | The returned accessible must be a child, but not necessarily a direct child. |
1183 | |
1184 | This function is only reliable for visible objects (invisible |
1185 | object might not be laid out correctly). |
1186 | |
1187 | All visual objects provide this information. |
1188 | |
1189 | A default implementation is provided for objects inheriting QAccessibleObject. This will iterate |
1190 | over all children. If the widget manages its children (e.g. a table) it will be more efficient |
1191 | to write a specialized implementation. |
1192 | |
1193 | \sa rect() |
1194 | */ |
1195 | |
1196 | /*! |
1197 | \fn QAccessibleInterface* QAccessibleInterface::parent() const |
1198 | |
1199 | Returns the QAccessibleInterface of the parent in the accessible object hierarchy. |
1200 | |
1201 | Returns \nullptr if no parent exists (e.g. for the top level application object). |
1202 | |
1203 | \sa child() |
1204 | */ |
1205 | |
1206 | /*! |
1207 | \fn QAccessibleInterface* QAccessibleInterface::child(int index) const |
1208 | |
1209 | Returns the accessible child with index \a index. |
1210 | 0-based index. The number of children of an object can be checked with childCount. |
1211 | |
1212 | Returns \nullptr when asking for an invalid child (e.g. when the child became invalid in the meantime). |
1213 | |
1214 | \sa childCount(), parent() |
1215 | */ |
1216 | |
1217 | /*! |
1218 | \fn QString QAccessibleInterface::text(QAccessible::Text t) const |
1219 | |
1220 | Returns the value of the text property \a t of the object. |
1221 | |
1222 | The \l QAccessible::Name is a string used by clients to identify, find, or |
1223 | announce an accessible object for the user. All objects must have |
1224 | a name that is unique within their container. The name can be |
1225 | used differently by clients, so the name should both give a |
1226 | short description of the object and be unique. |
1227 | |
1228 | An accessible object's \l QAccessible::Description provides textual information |
1229 | about an object's visual appearance. The description is primarily |
1230 | used to provide greater context for vision-impaired users, but is |
1231 | also used for context searching or other applications. Not all |
1232 | objects have a description. An "OK" button would not need a |
1233 | description, but a tool button that shows a picture of a smiley |
1234 | would. |
1235 | |
1236 | The \l QAccessible::Value of an accessible object represents visual information |
1237 | contained by the object, e.g. the text in a line edit. Usually, |
1238 | the value can be modified by the user. Not all objects have a |
1239 | value, e.g. static text labels don't, and some objects have a |
1240 | state that already is the value, e.g. toggle buttons. |
1241 | |
1242 | The \l QAccessible::Help text provides information about the function and |
1243 | usage of an accessible object. Not all objects provide this |
1244 | information. |
1245 | |
1246 | The \l QAccessible::Accelerator is a keyboard shortcut that activates the |
1247 | object's default action. A keyboard shortcut is the underlined |
1248 | character in the text of a menu, menu item or widget, and is |
1249 | either the character itself, or a combination of this character |
1250 | and a modifier key like Alt, Ctrl or Shift. Command controls like |
1251 | tool buttons also have shortcut keys and usually display them in |
1252 | their tooltip. |
1253 | |
1254 | The \l QAccessible::Identifier can be explicitly set to provide an |
1255 | ID to assistive technologies. This can be especially useful for UI tests. |
1256 | If no identifier has been explicitly set, the identifier is set by the |
1257 | respective interface to an ID based on \l QObject::objectName or its |
1258 | class name and \l QObject::objectName or class name of the parents |
1259 | in its parents chain. |
1260 | |
1261 | All objects provide a string for \l QAccessible::Name. |
1262 | |
1263 | \sa role(), state() |
1264 | */ |
1265 | |
1266 | /*! |
1267 | \fn void QAccessibleInterface::setText(QAccessible::Text t, const QString &text) |
1268 | |
1269 | Sets the text property \a t of the object to \a text. |
1270 | |
1271 | Note that the text properties of most objects are read-only |
1272 | so calling this function might have no effect. |
1273 | |
1274 | \sa text() |
1275 | */ |
1276 | |
1277 | /*! |
1278 | \fn QRect QAccessibleInterface::rect() const |
1279 | |
1280 | Returns the geometry of the object. The geometry is in screen coordinates. |
1281 | |
1282 | This function is only reliable for visible objects (invisible |
1283 | objects might not be laid out correctly). |
1284 | |
1285 | All visual objects provide this information. |
1286 | |
1287 | \sa childAt() |
1288 | */ |
1289 | |
1290 | /*! |
1291 | \fn QAccessible::Role QAccessibleInterface::role() const |
1292 | |
1293 | Returns the role of the object. |
1294 | The role of an object is usually static. |
1295 | |
1296 | All accessible objects have a role. |
1297 | |
1298 | \sa text(), state() |
1299 | */ |
1300 | |
1301 | /*! |
1302 | \fn QAccessible::State QAccessibleInterface::state() const |
1303 | |
1304 | Returns the current state of the object. |
1305 | The returned value is a combination of the flags in |
1306 | the QAccessible::StateFlag enumeration. |
1307 | |
1308 | All accessible objects have a state. |
1309 | |
1310 | \sa text(), role() |
1311 | */ |
1312 | |
1313 | /*! |
1314 | Returns the accessible's foreground color if applicable or an invalid QColor. |
1315 | |
1316 | \sa backgroundColor() |
1317 | */ |
1318 | QColor QAccessibleInterface::foregroundColor() const |
1319 | { |
1320 | return QColor(); |
1321 | } |
1322 | |
1323 | /*! |
1324 | Returns the accessible's background color if applicable or an invalid QColor. |
1325 | |
1326 | \sa foregroundColor() |
1327 | */ |
1328 | QColor QAccessibleInterface::backgroundColor() const |
1329 | { |
1330 | return QColor(); |
1331 | } |
1332 | |
1333 | /*! |
1334 | \fn QAccessibleTextInterface *QAccessibleInterface::textInterface() |
1335 | */ |
1336 | |
1337 | /*! |
1338 | \fn QAccessibleTextInterface *QAccessibleInterface::editableTextInterface() |
1339 | \internal |
1340 | */ |
1341 | |
1342 | /*! |
1343 | \fn QAccessibleValueInterface *QAccessibleInterface::valueInterface() |
1344 | */ |
1345 | |
1346 | /*! |
1347 | \fn QAccessibleTableInterface *QAccessibleInterface::tableInterface() |
1348 | */ |
1349 | |
1350 | /*! |
1351 | \fn QAccessibleTableCellInterface *QAccessibleInterface::tableCellInterface() |
1352 | */ |
1353 | |
1354 | /*! |
1355 | \fn QAccessibleActionInterface *QAccessibleInterface::actionInterface() |
1356 | */ |
1357 | |
1358 | /*! |
1359 | \fn QAccessibleImageInterface *QAccessibleInterface::imageInterface() |
1360 | \internal |
1361 | */ |
1362 | |
1363 | /*! |
1364 | \fn QAccessibleSelectionInterface *QAccessibleInterface::selectionInterface() |
1365 | \since 6.5 |
1366 | */ |
1367 | |
1368 | /*! |
1369 | \class QAccessibleEvent |
1370 | \ingroup accessibility |
1371 | \inmodule QtGui |
1372 | |
1373 | \brief The QAccessibleEvent class is the base class for accessibility notifications. |
1374 | |
1375 | This class is used with \l QAccessible::updateAccessibility(). |
1376 | |
1377 | The event type is one of the values of \l QAccessible::Event. |
1378 | There are a number of subclasses that should be used to provide more details about the |
1379 | event. |
1380 | |
1381 | For example to notify about a focus change when re-implementing QWidget::setFocus, |
1382 | the event could be used as follows: |
1383 | \snippet code/src_gui_accessible_qaccessible.cpp 2 |
1384 | |
1385 | To enable in process screen readers, all events must be sent after the change has happened. |
1386 | */ |
1387 | |
1388 | /*! \fn QAccessibleEvent::QAccessibleEvent(QObject *object, QAccessible::Event type) |
1389 | |
1390 | Constructs a QAccessibleEvent to notify that \a object has changed. |
1391 | The event \a type describes what changed. |
1392 | */ |
1393 | |
1394 | /*! \fn QAccessibleEvent::QAccessibleEvent(QAccessibleInterface *interface, QAccessible::Event type) |
1395 | |
1396 | Constructs a QAccessibleEvent to notify that \a interface has changed. |
1397 | The event \a type describes what changed. |
1398 | Use this function if you already have a QAccessibleInterface or no QObject, otherwise consider |
1399 | the overload taking a \l QObject parameter as it might be cheaper. |
1400 | */ |
1401 | |
1402 | /*! |
1403 | Destroys the event. |
1404 | */ |
1405 | QAccessibleEvent::~QAccessibleEvent() |
1406 | { |
1407 | } |
1408 | |
1409 | /*! \fn QAccessible::Event QAccessibleEvent::type() const |
1410 | Returns the event type. |
1411 | */ |
1412 | |
1413 | /*! \fn QObject* QAccessibleEvent::object() const |
1414 | Returns the event object. |
1415 | */ |
1416 | |
1417 | /*! \fn void QAccessibleEvent::setChild(int child) |
1418 | Sets the child index to \a child. |
1419 | */ |
1420 | |
1421 | /*! \fn int QAccessibleEvent::child() const |
1422 | Returns the child index. |
1423 | */ |
1424 | |
1425 | /*! |
1426 | \internal |
1427 | Returns the uniqueId of the QAccessibleInterface represented by this event. |
1428 | |
1429 | In case the object() function returns \nullptr, this is the only way to access the |
1430 | interface. |
1431 | */ |
1432 | QAccessible::Id QAccessibleEvent::uniqueId() const |
1433 | { |
1434 | if (!m_object) |
1435 | return m_uniqueId; |
1436 | QAccessibleInterface *iface = QAccessible::queryAccessibleInterface(object: m_object); |
1437 | if (!iface) |
1438 | return 0; |
1439 | if (m_child != -1) { |
1440 | iface = iface->child(index: m_child); |
1441 | if (Q_UNLIKELY(!iface)) { |
1442 | qCWarning(lcAccessibilityCore) << "Invalid child in QAccessibleEvent:" << m_object << "child:" << m_child; |
1443 | return 0; |
1444 | } |
1445 | } |
1446 | return QAccessible::uniqueId(iface); |
1447 | } |
1448 | |
1449 | /*! |
1450 | \class QAccessibleValueChangeEvent |
1451 | \ingroup accessibility |
1452 | \inmodule QtGui |
1453 | |
1454 | \brief The QAccessibleValueChangeEvent describes a change in value for an accessible object. |
1455 | |
1456 | It contains the new value. |
1457 | |
1458 | This class is used with \l QAccessible::updateAccessibility(). |
1459 | */ |
1460 | |
1461 | /*! \fn QAccessibleValueChangeEvent::QAccessibleValueChangeEvent(QObject *object, const QVariant &value) |
1462 | |
1463 | Constructs a new QAccessibleValueChangeEvent for \a object. |
1464 | The event contains the new \a value. |
1465 | */ |
1466 | /*! \fn QAccessibleValueChangeEvent::QAccessibleValueChangeEvent(QAccessibleInterface *iface, const QVariant &val) |
1467 | |
1468 | Constructs a new QAccessibleValueChangeEvent for \a iface. |
1469 | The event contains the new value \a val. |
1470 | */ |
1471 | |
1472 | /*! \fn void QAccessibleValueChangeEvent::setValue(const QVariant & value) |
1473 | |
1474 | Sets the new \a value for this event. |
1475 | */ |
1476 | /*! |
1477 | \fn QVariant QAccessibleValueChangeEvent::value() const |
1478 | |
1479 | Returns the new value of the accessible object of this event. |
1480 | */ |
1481 | /*! |
1482 | \internal |
1483 | */ |
1484 | QAccessibleValueChangeEvent::~QAccessibleValueChangeEvent() |
1485 | { |
1486 | } |
1487 | |
1488 | /*! |
1489 | \class QAccessibleStateChangeEvent |
1490 | \ingroup accessibility |
1491 | \inmodule QtGui |
1492 | |
1493 | \brief The QAccessibleStateChangeEvent notfies the accessibility framework |
1494 | that the state of an object has changed. |
1495 | |
1496 | This class is used with \l QAccessible::updateAccessibility(). |
1497 | |
1498 | \sa QAccessibleInterface::state() |
1499 | */ |
1500 | /*! \fn QAccessibleStateChangeEvent::QAccessibleStateChangeEvent(QObject *object, QAccessible::State state) |
1501 | |
1502 | Constructs a new QAccessibleStateChangeEvent for \a object. |
1503 | The difference to the object's previous state is in \a state. |
1504 | */ |
1505 | /*! |
1506 | \fn QAccessibleStateChangeEvent::QAccessibleStateChangeEvent(QAccessibleInterface *iface, QAccessible::State state) |
1507 | |
1508 | Constructs a new QAccessibleStateChangeEvent. |
1509 | \a iface is the interface associated with the event |
1510 | \a state is the state of the accessible object. |
1511 | */ |
1512 | /*! |
1513 | \fn QAccessible::State QAccessibleStateChangeEvent::changedStates() const |
1514 | \brief Returns the states that have been changed. |
1515 | |
1516 | Keep in mind that the returned states are the ones that have changed. |
1517 | To find out about the state of an object, use QAccessibleInterface::state(). |
1518 | |
1519 | For example, if an object used to have the focus but loses it, |
1520 | the object's state will have focused set to \c false. This event on the |
1521 | other hand tells about the change and has focused set to \c true since |
1522 | the focus state is changed from \c true to \c false. |
1523 | */ |
1524 | /*! |
1525 | \internal |
1526 | */ |
1527 | QAccessibleStateChangeEvent::~QAccessibleStateChangeEvent() |
1528 | { |
1529 | } |
1530 | |
1531 | /*! |
1532 | \class QAccessibleTableModelChangeEvent |
1533 | \ingroup accessibility |
1534 | \inmodule QtGui |
1535 | |
1536 | \brief The QAccessibleTableModelChangeEvent signifies a change in a table, list, or tree where cells |
1537 | are added or removed. |
1538 | If the change affected a number of rows, firstColumn and lastColumn will return -1. |
1539 | Likewise for columns, the row functions may return -1. |
1540 | |
1541 | This class is used with \l QAccessible::updateAccessibility(). |
1542 | */ |
1543 | |
1544 | /*! \enum QAccessibleTableModelChangeEvent::ModelChangeType |
1545 | This enum describes the different types of changes in the table model. |
1546 | \value ModelReset The model has been reset, all previous knowledge about the model is now invalid. |
1547 | \value DataChanged No cells have been added or removed, but the data of the specified cell range is invalid. |
1548 | \value RowsInserted New rows have been inserted. |
1549 | \value ColumnsInserted New columns have been inserted. |
1550 | \value RowsRemoved Rows have been removed. |
1551 | \value ColumnsRemoved Columns have been removed. |
1552 | */ |
1553 | /*! \fn QAccessibleTableModelChangeEvent::QAccessibleTableModelChangeEvent(QObject *object, ModelChangeType changeType) |
1554 | |
1555 | Constructs a new QAccessibleTableModelChangeEvent for \a object of with \a changeType. |
1556 | */ |
1557 | /*! \fn int QAccessibleTableModelChangeEvent::firstColumn() const |
1558 | |
1559 | Returns the first changed column. |
1560 | */ |
1561 | /*! \fn int QAccessibleTableModelChangeEvent::firstRow() const |
1562 | |
1563 | Returns the first changed row. |
1564 | */ |
1565 | /*! \fn int QAccessibleTableModelChangeEvent::lastColumn() const |
1566 | |
1567 | Returns the last changed column. |
1568 | */ |
1569 | /*! \fn int QAccessibleTableModelChangeEvent::lastRow() const |
1570 | |
1571 | Returns the last changed row. |
1572 | */ |
1573 | /*! \fn QAccessibleTableModelChangeEvent::ModelChangeType QAccessibleTableModelChangeEvent::modelChangeType() const |
1574 | |
1575 | Returns the type of change. |
1576 | */ |
1577 | /*! \fn void QAccessibleTableModelChangeEvent::setFirstColumn(int column) |
1578 | |
1579 | Sets the first changed \a column. |
1580 | */ |
1581 | /*! \fn void QAccessibleTableModelChangeEvent::setFirstRow(int row) |
1582 | |
1583 | Sets the first changed \a row. |
1584 | */ |
1585 | /*! \fn void QAccessibleTableModelChangeEvent::setLastColumn(int column) |
1586 | |
1587 | Sets the last changed \a column. |
1588 | */ |
1589 | /*! \fn void QAccessibleTableModelChangeEvent::setLastRow(int row) |
1590 | |
1591 | Sets the last changed \a row. |
1592 | */ |
1593 | /*! \fn void QAccessibleTableModelChangeEvent::setModelChangeType(ModelChangeType changeType) |
1594 | |
1595 | Sets the type of change to \a changeType. |
1596 | */ |
1597 | /*! |
1598 | \fn QAccessibleTableModelChangeEvent::QAccessibleTableModelChangeEvent(QAccessibleInterface *iface, ModelChangeType changeType) |
1599 | |
1600 | Constructs a new QAccessibleTableModelChangeEvent for interface \a iface with a model |
1601 | change type \a changeType. |
1602 | */ |
1603 | /*! |
1604 | \internal |
1605 | */ |
1606 | QAccessibleTableModelChangeEvent::~QAccessibleTableModelChangeEvent() |
1607 | { |
1608 | } |
1609 | /*! |
1610 | \class QAccessibleTextCursorEvent |
1611 | \ingroup accessibility |
1612 | \inmodule QtGui |
1613 | |
1614 | \brief The QAccessibleTextCursorEvent class notifies of cursor movements. |
1615 | |
1616 | This class is used with \l QAccessible::updateAccessibility(). |
1617 | */ |
1618 | /*! \fn QAccessibleTextCursorEvent::QAccessibleTextCursorEvent(QObject *object, int cursorPos) |
1619 | |
1620 | Create a new QAccessibleTextCursorEvent for \a object. |
1621 | The \a cursorPos is the new cursor position. |
1622 | */ |
1623 | /*! \fn int QAccessibleTextCursorEvent::cursorPosition() const |
1624 | |
1625 | Returns the cursor position. |
1626 | */ |
1627 | /*! \fn void QAccessibleTextCursorEvent::setCursorPosition(int position) |
1628 | |
1629 | Sets the cursor \a position for this event. |
1630 | */ |
1631 | /*! |
1632 | \internal |
1633 | */ |
1634 | QAccessibleTextCursorEvent::~QAccessibleTextCursorEvent() |
1635 | { |
1636 | } |
1637 | |
1638 | |
1639 | /*! |
1640 | \fn QAccessibleTextCursorEvent::QAccessibleTextCursorEvent(QAccessibleInterface *iface, int cursorPos) |
1641 | |
1642 | Create a new QAccessibleTextCursorEvent for \a iface, |
1643 | The \a cursorPos is the new cursor position. |
1644 | */ |
1645 | |
1646 | /*! |
1647 | \class QAccessibleTextInsertEvent |
1648 | \ingroup accessibility |
1649 | \inmodule QtGui |
1650 | |
1651 | \brief The QAccessibleTextInsertEvent class notifies of text being inserted. |
1652 | |
1653 | This class is used with \l QAccessible::updateAccessibility(). |
1654 | */ |
1655 | /*! \fn QAccessibleTextInsertEvent::QAccessibleTextInsertEvent(QObject *object, int position, const QString &text) |
1656 | |
1657 | Constructs a new QAccessibleTextInsertEvent event for \a object. |
1658 | The \a text has been inserted at \a position. |
1659 | By default, it is assumed that the cursor has moved to the end |
1660 | of the selection. If that is not the case, one needs to manually |
1661 | set it with \l QAccessibleTextCursorEvent::setCursorPosition() for this event. |
1662 | */ |
1663 | /*! \fn int QAccessibleTextInsertEvent::changePosition() const |
1664 | |
1665 | Returns the position where the text was inserted. |
1666 | */ |
1667 | /*! \fn QString QAccessibleTextInsertEvent::textInserted() const |
1668 | |
1669 | Returns the text that has been inserted. |
1670 | */ |
1671 | /*! |
1672 | \internal |
1673 | */ |
1674 | QAccessibleTextInsertEvent::~QAccessibleTextInsertEvent() |
1675 | { |
1676 | } |
1677 | |
1678 | |
1679 | /*! |
1680 | \class QAccessibleTextRemoveEvent |
1681 | \ingroup accessibility |
1682 | \inmodule QtGui |
1683 | |
1684 | \brief The QAccessibleTextRemoveEvent class notifies of text being deleted. |
1685 | |
1686 | This class is used with \l QAccessible::updateAccessibility(). |
1687 | */ |
1688 | /*! \fn QAccessibleTextRemoveEvent::QAccessibleTextRemoveEvent(QObject *object, int position, const QString &text) |
1689 | |
1690 | Constructs a new QAccessibleTextRemoveEvent event for \a object. |
1691 | The \a text has been removed at \a position. |
1692 | By default it is assumed that the cursor has moved to \a position. |
1693 | If that is not the case, one needs to manually |
1694 | set it with \l QAccessibleTextCursorEvent::setCursorPosition() for this event. |
1695 | */ |
1696 | /*! \fn QAccessibleTextRemoveEvent::QAccessibleTextRemoveEvent(QAccessibleInterface *iface, int position, const QString &text) |
1697 | |
1698 | Constructs a new QAccessibleTextRemoveEvent event for \a iface. |
1699 | The \a text has been removed at \a position. |
1700 | By default it is assumed that the cursor has moved to \a position. |
1701 | If that is not the case, one needs to manually |
1702 | set it with \l QAccessibleTextCursorEvent::setCursorPosition() for this event. |
1703 | */ |
1704 | |
1705 | /*! \fn int QAccessibleTextRemoveEvent::changePosition() const |
1706 | |
1707 | Returns the position where the text was removed. |
1708 | */ |
1709 | /*! \fn QString QAccessibleTextRemoveEvent::textRemoved() const |
1710 | |
1711 | Returns the text that has been removed. |
1712 | */ |
1713 | /*! |
1714 | \internal |
1715 | */ |
1716 | QAccessibleTextRemoveEvent::~QAccessibleTextRemoveEvent() |
1717 | { |
1718 | } |
1719 | |
1720 | /*! |
1721 | \fn QAccessibleTextSelectionEvent::QAccessibleTextSelectionEvent(QAccessibleInterface *iface, int start, int end) |
1722 | |
1723 | Constructs a new QAccessibleTextSelectionEvent for \a iface. The new selection this |
1724 | event notifies about is from position \a start to \a end. |
1725 | */ |
1726 | |
1727 | /*! |
1728 | \fn QAccessibleTextInsertEvent::QAccessibleTextInsertEvent(QAccessibleInterface *iface, int position, const QString &text) |
1729 | |
1730 | Constructs a new QAccessibleTextInsertEvent event for \a iface. The \a text has been inserted |
1731 | at \a position. |
1732 | */ |
1733 | |
1734 | /*! |
1735 | \fn inline QAccessibleTextUpdateEvent::QAccessibleTextUpdateEvent(QAccessibleInterface *iface, int position, const QString &oldText, |
1736 | const QString &text) |
1737 | |
1738 | Constructs a new QAccessibleTextUpdateEvent for \a iface. The text change takes place at |
1739 | \a position where the \a oldText was removed and \a text inserted instead. |
1740 | |
1741 | */ |
1742 | |
1743 | |
1744 | |
1745 | /*! |
1746 | \class QAccessibleTextUpdateEvent |
1747 | \ingroup accessibility |
1748 | \inmodule QtGui |
1749 | |
1750 | \brief The QAccessibleTextUpdateEvent class notifies about text changes. |
1751 | This is for accessibles that support editable text such as line edits. |
1752 | This event occurs for example when a portion of selected text |
1753 | gets replaced by pasting a new text or in override mode of editors. |
1754 | |
1755 | This class is used with \l QAccessible::updateAccessibility(). |
1756 | */ |
1757 | /*! \fn QAccessibleTextUpdateEvent::QAccessibleTextUpdateEvent(QObject *object, int position, const QString &oldText, const QString &text) |
1758 | |
1759 | Constructs a new QAccessibleTextUpdateEvent for \a object. |
1760 | The text change takes place at \a position where the \a oldText was removed and \a text inserted instead. |
1761 | */ |
1762 | /*! \fn int QAccessibleTextUpdateEvent::changePosition() const |
1763 | |
1764 | Returns where the change took place. |
1765 | */ |
1766 | /*! \fn QString QAccessibleTextUpdateEvent::textInserted() const |
1767 | |
1768 | Returns the inserted text. |
1769 | */ |
1770 | /*! \fn QString QAccessibleTextUpdateEvent::textRemoved() const |
1771 | |
1772 | Returns the removed text. |
1773 | */ |
1774 | /*! |
1775 | \internal |
1776 | */ |
1777 | QAccessibleTextUpdateEvent::~QAccessibleTextUpdateEvent() |
1778 | { |
1779 | } |
1780 | |
1781 | |
1782 | /*! |
1783 | \class QAccessibleTextSelectionEvent |
1784 | \ingroup accessibility |
1785 | \inmodule QtGui |
1786 | |
1787 | \brief QAccessibleTextSelectionEvent signals a change in the text selection of an object. |
1788 | |
1789 | This class is used with \l QAccessible::updateAccessibility(). |
1790 | */ |
1791 | /*! \fn QAccessibleTextSelectionEvent::QAccessibleTextSelectionEvent(QObject *object, int start, int end) |
1792 | |
1793 | Constructs a new QAccessibleTextSelectionEvent for \a object. |
1794 | The new selection this event notifies about is from position \a start to \a end. |
1795 | */ |
1796 | /*! \fn int QAccessibleTextSelectionEvent::selectionEnd() const |
1797 | |
1798 | Returns the position of the last selected character. |
1799 | */ |
1800 | /*! \fn int QAccessibleTextSelectionEvent::selectionStart() const |
1801 | |
1802 | Returns the position of the first selected character. |
1803 | */ |
1804 | /*! \fn void QAccessibleTextSelectionEvent::setSelection(int start, int end) |
1805 | |
1806 | Sets the selection for this event from position \a start to \a end. |
1807 | */ |
1808 | /*! |
1809 | \internal |
1810 | */ |
1811 | QAccessibleTextSelectionEvent::~QAccessibleTextSelectionEvent() |
1812 | { |
1813 | } |
1814 | |
1815 | /*! |
1816 | \since 6.8 |
1817 | \class QAccessibleAnnouncementEvent |
1818 | \ingroup accessibility |
1819 | \inmodule QtGui |
1820 | |
1821 | \brief The QAccessibleAnnouncementEvent is used to request the announcement |
1822 | of a given message by assistive technologies. |
1823 | |
1824 | This class is used with \l QAccessible::updateAccessibility(). |
1825 | */ |
1826 | |
1827 | /*! \fn QAccessibleAnnouncementEvent::QAccessibleAnnouncementEvent(QObject *object, const QString &message) |
1828 | |
1829 | Constructs a new QAccessibleAnnouncementEvent event for \a object |
1830 | to request the announcement of \a message with politeness |
1831 | \l QAccessible::AnnouncementPoliteness::Polite. |
1832 | |
1833 | \l QAccessibleAnnouncementEvent::setPoliteness can be used to adjust the politeness. |
1834 | */ |
1835 | |
1836 | /*! \fn QAccessibleAnnouncementEvent::QAccessibleAnnouncementEvent(QAccessibleInterface *iface, const QString &message) |
1837 | |
1838 | Constructs a new QAccessibleAnnouncementEvent event for \a iface |
1839 | to request the announcement of \a message with politeness |
1840 | \l QAccessible::AnnouncementPoliteness::Polite. |
1841 | |
1842 | \l QAccessibleAnnouncementEvent::setPoliteness can be used to adjust the politeness. |
1843 | */ |
1844 | |
1845 | /*! \fn QString QAccessibleAnnouncementEvent::message() const |
1846 | |
1847 | Returns the message. |
1848 | */ |
1849 | |
1850 | /*! \fn QAccessible::AnnouncementPoliteness QAccessibleAnnouncementEvent::politeness() const |
1851 | |
1852 | Returns the politeness. |
1853 | */ |
1854 | |
1855 | /*! \fn void QAccessibleAnnouncementEvent::setPoliteness(QAccessible::AnnouncementPoliteness politeness) |
1856 | |
1857 | Sets the politeness with which the announcement will be requested to \a politeness. |
1858 | */ |
1859 | |
1860 | |
1861 | /*! |
1862 | \internal |
1863 | */ |
1864 | QAccessibleAnnouncementEvent::~QAccessibleAnnouncementEvent() |
1865 | { |
1866 | } |
1867 | |
1868 | /*! |
1869 | Returns the QAccessibleInterface associated with the event. |
1870 | */ |
1871 | QAccessibleInterface *QAccessibleEvent::accessibleInterface() const |
1872 | { |
1873 | if (m_object == nullptr) |
1874 | return QAccessible::accessibleInterface(id: m_uniqueId); |
1875 | |
1876 | QAccessibleInterface *iface = QAccessible::queryAccessibleInterface(object: m_object); |
1877 | if (!iface || !iface->isValid()) |
1878 | return nullptr; |
1879 | |
1880 | if (m_child >= 0) { |
1881 | QAccessibleInterface *child = iface->child(index: m_child); |
1882 | if (child) { |
1883 | iface = child; |
1884 | } else { |
1885 | qCWarning(lcAccessibilityCore) << "Cannot create accessible child interface for object: " << m_object << " index: " << m_child; |
1886 | } |
1887 | } |
1888 | return iface; |
1889 | } |
1890 | |
1891 | /*! |
1892 | Returns the window associated with the underlying object. |
1893 | For instance, QAccessibleWidget reimplements this and returns |
1894 | the windowHandle() of the QWidget. |
1895 | |
1896 | It is used on some platforms to be able to notify the AT client about |
1897 | state changes. |
1898 | The backend will traverse up all ancestors until it finds a window. |
1899 | (This means that at least one interface among the ancestors should |
1900 | return a valid QWindow pointer). |
1901 | |
1902 | The default implementation returns \nullptr. |
1903 | */ |
1904 | QWindow *QAccessibleInterface::window() const |
1905 | { |
1906 | return nullptr; |
1907 | } |
1908 | |
1909 | /*! |
1910 | \internal |
1911 | Method to allow extending this class without breaking binary compatibility. |
1912 | The actual behavior and format of \a data depends on \a id argument |
1913 | which must be defined if the class is to be extended with another virtual |
1914 | function. |
1915 | Currently, this is unused. |
1916 | */ |
1917 | void QAccessibleInterface::virtual_hook(int /*id*/, void * /*data*/) |
1918 | { |
1919 | } |
1920 | |
1921 | /*! |
1922 | \fn void *QAccessibleInterface::interface_cast(QAccessible::InterfaceType type) |
1923 | |
1924 | Returns a specialized accessibility interface \a type from the |
1925 | generic QAccessibleInterface. |
1926 | |
1927 | This function must be reimplemented when providing more |
1928 | information about a widget or object through the specialized |
1929 | interfaces. For example a line edit should implement the |
1930 | QAccessibleTextInterface. |
1931 | |
1932 | \sa QAccessible::InterfaceType, QAccessibleTextInterface, |
1933 | QAccessibleValueInterface, QAccessibleActionInterface, |
1934 | QAccessibleTableInterface, QAccessibleTableCellInterface |
1935 | */ |
1936 | |
1937 | /*! \internal */ |
1938 | const char *qAccessibleRoleString(QAccessible::Role role) |
1939 | { |
1940 | if (role >= QAccessible::UserRole) |
1941 | role = QAccessible::UserRole; |
1942 | static int roleEnum = QAccessible::staticMetaObject.indexOfEnumerator(name: "Role" ); |
1943 | return QAccessible::staticMetaObject.enumerator(index: roleEnum).valueToKey(value: role); |
1944 | } |
1945 | |
1946 | /*! \internal */ |
1947 | const char *qAccessibleEventString(QAccessible::Event event) |
1948 | { |
1949 | static int eventEnum = QAccessible::staticMetaObject.indexOfEnumerator(name: "Event" ); |
1950 | return QAccessible::staticMetaObject.enumerator(index: eventEnum).valueToKey(value: event); |
1951 | } |
1952 | |
1953 | #ifndef QT_NO_DEBUG_STREAM |
1954 | /*! \internal */ |
1955 | Q_GUI_EXPORT QDebug operator<<(QDebug d, const QAccessibleInterface *iface) |
1956 | { |
1957 | QDebugStateSaver saver(d); |
1958 | if (!iface) { |
1959 | d << "QAccessibleInterface(null)" ; |
1960 | return d; |
1961 | } |
1962 | d.nospace(); |
1963 | d << "QAccessibleInterface(" << Qt::hex << (const void *) iface << Qt::dec; |
1964 | if (iface->isValid()) { |
1965 | d << " name=" << iface->text(t: QAccessible::Name) << ' '; |
1966 | d << "role=" << qAccessibleRoleString(role: iface->role()) << ' '; |
1967 | if (iface->childCount()) |
1968 | d << "childc=" << iface->childCount() << ' '; |
1969 | if (iface->object()) { |
1970 | d << "obj=" << iface->object(); |
1971 | } |
1972 | QStringList stateStrings; |
1973 | QAccessible::State st = iface->state(); |
1974 | if (st.focusable) |
1975 | stateStrings << u"focusable"_s ; |
1976 | if (st.focused) |
1977 | stateStrings << u"focused"_s ; |
1978 | if (st.selected) |
1979 | stateStrings << u"selected"_s ; |
1980 | if (st.invisible) |
1981 | stateStrings << u"invisible"_s ; |
1982 | |
1983 | if (!stateStrings.isEmpty()) |
1984 | d << stateStrings.join(sep: u'|'); |
1985 | |
1986 | if (!st.invisible) |
1987 | d << "rect=" << iface->rect(); |
1988 | |
1989 | } else { |
1990 | d << " invalid" ; |
1991 | } |
1992 | d << ')'; |
1993 | return d; |
1994 | } |
1995 | |
1996 | /*! \internal */ |
1997 | QDebug operator<<(QDebug d, const QAccessibleEvent &ev) |
1998 | { |
1999 | QDebugStateSaver saver(d); |
2000 | d.nospace() << "QAccessibleEvent(" ; |
2001 | if (ev.object()) { |
2002 | d.nospace() << "object=" << Qt::hex << ev.object() << Qt::dec; |
2003 | d.nospace() << "child=" << ev.child(); |
2004 | } else { |
2005 | d.nospace() << "no object, uniqueId=" << ev.uniqueId(); |
2006 | } |
2007 | d << " event=" << qAccessibleEventString(event: ev.type()); |
2008 | if (ev.type() == QAccessible::StateChanged) { |
2009 | QAccessible::State changed = static_cast<const QAccessibleStateChangeEvent*>(&ev)->changedStates(); |
2010 | d << "State changed:" ; |
2011 | if (changed.disabled) d << "disabled" ; |
2012 | if (changed.selected) d << "selected" ; |
2013 | if (changed.focusable) d << "focusable" ; |
2014 | if (changed.focused) d << "focused" ; |
2015 | if (changed.pressed) d << "pressed" ; |
2016 | if (changed.checkable) d << "checkable" ; |
2017 | if (changed.checked) d << "checked" ; |
2018 | if (changed.checkStateMixed) d << "checkStateMixed" ; |
2019 | if (changed.readOnly) d << "readOnly" ; |
2020 | if (changed.hotTracked) d << "hotTracked" ; |
2021 | if (changed.defaultButton) d << "defaultButton" ; |
2022 | if (changed.expanded) d << "expanded" ; |
2023 | if (changed.collapsed) d << "collapsed" ; |
2024 | if (changed.busy) d << "busy" ; |
2025 | if (changed.expandable) d << "expandable" ; |
2026 | if (changed.marqueed) d << "marqueed" ; |
2027 | if (changed.animated) d << "animated" ; |
2028 | if (changed.invisible) d << "invisible" ; |
2029 | if (changed.offscreen) d << "offscreen" ; |
2030 | if (changed.sizeable) d << "sizeable" ; |
2031 | if (changed.movable) d << "movable" ; |
2032 | if (changed.selfVoicing) d << "selfVoicing" ; |
2033 | if (changed.selectable) d << "selectable" ; |
2034 | if (changed.linked) d << "linked" ; |
2035 | if (changed.traversed) d << "traversed" ; |
2036 | if (changed.multiSelectable) d << "multiSelectable" ; |
2037 | if (changed.extSelectable) d << "extSelectable" ; |
2038 | if (changed.passwordEdit) d << "passwordEdit" ; // used to be Protected |
2039 | if (changed.hasPopup) d << "hasPopup" ; |
2040 | if (changed.modal) d << "modal" ; |
2041 | |
2042 | // IA2 - we chose to not add some IA2 states for now |
2043 | // Below the ones that seem helpful |
2044 | if (changed.active) d << "active" ; |
2045 | if (changed.invalid) d << "invalid" ; // = defunct |
2046 | if (changed.editable) d << "editable" ; |
2047 | if (changed.multiLine) d << "multiLine" ; |
2048 | if (changed.selectableText) d << "selectableText" ; |
2049 | if (changed.supportsAutoCompletion) d << "supportsAutoCompletion" ; |
2050 | |
2051 | } |
2052 | d << ')'; |
2053 | return d; |
2054 | } |
2055 | #endif // QT_NO_DEBUGSTREAM |
2056 | |
2057 | /*! |
2058 | \class QAccessibleTextInterface |
2059 | \inmodule QtGui |
2060 | |
2061 | \ingroup accessibility |
2062 | |
2063 | \brief The QAccessibleTextInterface class implements support for text handling. |
2064 | |
2065 | This interface corresponds to the IAccessibleText interface. |
2066 | It should be implemented for widgets that display more text than a plain label. |
2067 | Labels should be represented by only \l QAccessibleInterface |
2068 | and return their text as name (\l QAccessibleInterface::text() with \l QAccessible::Name as type). |
2069 | The QAccessibleTextInterface is typically for text that a screen reader |
2070 | might want to read line by line, and for widgets that support text selection and input. |
2071 | This interface is, for example, implemented for QLineEdit. |
2072 | |
2073 | \l{IAccessible2 Specification} |
2074 | */ |
2075 | |
2076 | /*! |
2077 | |
2078 | Destroys the QAccessibleTextInterface. |
2079 | */ |
2080 | QAccessibleTextInterface::~QAccessibleTextInterface() |
2081 | { |
2082 | } |
2083 | |
2084 | /*! |
2085 | \fn void QAccessibleTextInterface::addSelection(int startOffset, int endOffset) |
2086 | |
2087 | Select the text from \a startOffset to \a endOffset. |
2088 | The \a startOffset is the first character that will be selected. |
2089 | The \a endOffset is the first character that will not be selected. |
2090 | |
2091 | When the object supports multiple selections (e.g. in a word processor), |
2092 | this adds a new selection, otherwise it replaces the previous selection. |
2093 | |
2094 | The selection will be \a endOffset - \a startOffset characters long. |
2095 | */ |
2096 | |
2097 | /*! |
2098 | \fn QString QAccessibleTextInterface::attributes(int offset, int *startOffset, int *endOffset) const |
2099 | |
2100 | Returns the text attributes at the position \a offset. |
2101 | In addition the range of the attributes is returned in \a startOffset and \a endOffset. |
2102 | */ |
2103 | |
2104 | /*! |
2105 | \fn int QAccessibleTextInterface::cursorPosition() const |
2106 | |
2107 | Returns the current cursor position. |
2108 | */ |
2109 | |
2110 | /*! |
2111 | \fn QRect QAccessibleTextInterface::characterRect(int offset) const |
2112 | |
2113 | Returns the position and size of the character at position \a offset in screen coordinates. |
2114 | */ |
2115 | |
2116 | /*! |
2117 | \fn int QAccessibleTextInterface::selectionCount() const |
2118 | |
2119 | Returns the number of selections in this text. |
2120 | */ |
2121 | |
2122 | /*! |
2123 | \fn int QAccessibleTextInterface::offsetAtPoint(const QPoint &point) const |
2124 | |
2125 | Returns the offset of the character at the \a point in screen coordinates. |
2126 | */ |
2127 | |
2128 | /*! |
2129 | \fn void QAccessibleTextInterface::selection(int selectionIndex, int *startOffset, int *endOffset) const |
2130 | |
2131 | Returns a selection. The size of the selection is returned in \a startOffset and \a endOffset. |
2132 | If there is no selection both \a startOffset and \a endOffset are \nullptr. |
2133 | |
2134 | The accessibility APIs support multiple selections. For most widgets though, only one selection |
2135 | is supported with \a selectionIndex equal to 0. |
2136 | */ |
2137 | |
2138 | /*! |
2139 | \fn QString QAccessibleTextInterface::text(int startOffset, int endOffset) const |
2140 | |
2141 | Returns the text from \a startOffset to \a endOffset. |
2142 | The \a startOffset is the first character that will be returned. |
2143 | The \a endOffset is the first character that will not be returned. |
2144 | */ |
2145 | |
2146 | /*! |
2147 | \internal |
2148 | Helper for finding line breaks in textBeforeOffset/textAtOffset/textAfterOffset. |
2149 | \a beforeAtAfter is the line we look for. -1 for before, 0 for at and 1 for after. |
2150 | */ |
2151 | static QString textLineBoundary(int beforeAtAfter, const QString &text, int offset, int *startOffset, int *endOffset) |
2152 | { |
2153 | Q_ASSERT(beforeAtAfter >= -1 && beforeAtAfter <= 1); |
2154 | Q_ASSERT(*startOffset == -1 && *endOffset == -1); |
2155 | int length = text.size(); |
2156 | Q_ASSERT(offset >= 0 && offset <= length); |
2157 | |
2158 | // move offset into the right range (if asking for line before or after |
2159 | if (beforeAtAfter == 1) { |
2160 | offset = text.indexOf(ch: QChar::LineFeed, from: qMin(a: offset, b: length - 1)); |
2161 | if (offset < 0) |
2162 | return QString(); // after the last line comes nothing |
2163 | ++offset; // move after the newline |
2164 | } else if (beforeAtAfter == -1) { |
2165 | offset = text.lastIndexOf(ch: QChar::LineFeed, from: qMax(a: offset - 1, b: 0)); |
2166 | if (offset < 0) |
2167 | return QString(); // before first line comes nothing |
2168 | } |
2169 | |
2170 | if (offset > 0) |
2171 | *startOffset = text.lastIndexOf(ch: QChar::LineFeed, from: offset - 1); |
2172 | ++*startOffset; // move to the char after the newline (0 if lastIndexOf returned -1) |
2173 | |
2174 | *endOffset = text.indexOf(ch: QChar::LineFeed, from: qMin(a: offset, b: length - 1)) + 1; // include newline char |
2175 | if (*endOffset <= 0 || *endOffset > length) |
2176 | *endOffset = length; // if the text doesn't end with a newline it ends at length |
2177 | |
2178 | return text.mid(position: *startOffset, n: *endOffset - *startOffset); |
2179 | } |
2180 | |
2181 | /*! |
2182 | Returns the text item of type \a boundaryType that is close to offset \a offset |
2183 | and sets \a startOffset and \a endOffset values to the start and end positions |
2184 | of that item; returns an empty string if there is no such an item. |
2185 | Sets \a startOffset and \a endOffset values to -1 on error. |
2186 | |
2187 | This default implementation is provided for small text edits. A word processor or |
2188 | text editor should provide their own efficient implementations. This function makes no |
2189 | distinction between paragraphs and lines. |
2190 | |
2191 | \note this function can not take the cursor position into account. By convention |
2192 | an \a offset of -2 means that this function should use the cursor position as offset. |
2193 | Thus an offset of -2 must be converted to the cursor position before calling this |
2194 | function. |
2195 | An offset of -1 is used for the text length and custom implementations of this function |
2196 | have to return the result as if the length was passed in as offset. |
2197 | */ |
2198 | QString QAccessibleTextInterface::textBeforeOffset(int offset, QAccessible::TextBoundaryType boundaryType, |
2199 | int *startOffset, int *endOffset) const |
2200 | { |
2201 | const QString txt = text(startOffset: 0, endOffset: characterCount()); |
2202 | |
2203 | if (offset == -1) |
2204 | offset = txt.size(); |
2205 | |
2206 | *startOffset = *endOffset = -1; |
2207 | if (txt.isEmpty() || offset <= 0 || offset > txt.size()) |
2208 | return QString(); |
2209 | |
2210 | // type initialized just to silence a compiler warning [-Werror=maybe-uninitialized] |
2211 | QTextBoundaryFinder::BoundaryType type = QTextBoundaryFinder::Grapheme; |
2212 | switch (boundaryType) { |
2213 | case QAccessible::CharBoundary: |
2214 | type = QTextBoundaryFinder::Grapheme; |
2215 | break; |
2216 | case QAccessible::WordBoundary: |
2217 | type = QTextBoundaryFinder::Word; |
2218 | break; |
2219 | case QAccessible::SentenceBoundary: |
2220 | type = QTextBoundaryFinder::Sentence; |
2221 | break; |
2222 | case QAccessible::LineBoundary: |
2223 | case QAccessible::ParagraphBoundary: |
2224 | // Lines can not use QTextBoundaryFinder since Line there means any potential line-break. |
2225 | return textLineBoundary(beforeAtAfter: -1, text: txt, offset, startOffset, endOffset); |
2226 | case QAccessible::NoBoundary: |
2227 | // return empty, this function currently only supports single lines, so there can be no line before |
2228 | return QString(); |
2229 | default: |
2230 | Q_UNREACHABLE(); |
2231 | } |
2232 | |
2233 | // keep behavior in sync with QTextCursor::movePosition()! |
2234 | |
2235 | QTextBoundaryFinder boundary(type, txt); |
2236 | boundary.setPosition(offset); |
2237 | |
2238 | do { |
2239 | if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem))) |
2240 | break; |
2241 | } while (boundary.toPreviousBoundary() > 0); |
2242 | Q_ASSERT(boundary.position() >= 0); |
2243 | *endOffset = boundary.position(); |
2244 | |
2245 | while (boundary.toPreviousBoundary() > 0) { |
2246 | if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem))) |
2247 | break; |
2248 | } |
2249 | Q_ASSERT(boundary.position() >= 0); |
2250 | *startOffset = boundary.position(); |
2251 | |
2252 | return txt.mid(position: *startOffset, n: *endOffset - *startOffset); |
2253 | } |
2254 | |
2255 | /*! |
2256 | Returns the text item of type \a boundaryType that is right after offset \a offset |
2257 | and sets \a startOffset and \a endOffset values to the start and end positions |
2258 | of that item; returns an empty string if there is no such an item. |
2259 | Sets \a startOffset and \a endOffset values to -1 on error. |
2260 | |
2261 | This default implementation is provided for small text edits. A word processor or |
2262 | text editor should provide their own efficient implementations. This function makes no |
2263 | distinction between paragraphs and lines. |
2264 | |
2265 | \note this function can not take the cursor position into account. By convention |
2266 | an \a offset of -2 means that this function should use the cursor position as offset. |
2267 | Thus an offset of -2 must be converted to the cursor position before calling this |
2268 | function. |
2269 | An offset of -1 is used for the text length and custom implementations of this function |
2270 | have to return the result as if the length was passed in as offset. |
2271 | */ |
2272 | QString QAccessibleTextInterface::textAfterOffset(int offset, QAccessible::TextBoundaryType boundaryType, |
2273 | int *startOffset, int *endOffset) const |
2274 | { |
2275 | const QString txt = text(startOffset: 0, endOffset: characterCount()); |
2276 | |
2277 | if (offset == -1) |
2278 | offset = txt.size(); |
2279 | |
2280 | *startOffset = *endOffset = -1; |
2281 | if (txt.isEmpty() || offset < 0 || offset >= txt.size()) |
2282 | return QString(); |
2283 | |
2284 | // type initialized just to silence a compiler warning [-Werror=maybe-uninitialized] |
2285 | QTextBoundaryFinder::BoundaryType type = QTextBoundaryFinder::Grapheme; |
2286 | switch (boundaryType) { |
2287 | case QAccessible::CharBoundary: |
2288 | type = QTextBoundaryFinder::Grapheme; |
2289 | break; |
2290 | case QAccessible::WordBoundary: |
2291 | type = QTextBoundaryFinder::Word; |
2292 | break; |
2293 | case QAccessible::SentenceBoundary: |
2294 | type = QTextBoundaryFinder::Sentence; |
2295 | break; |
2296 | case QAccessible::LineBoundary: |
2297 | case QAccessible::ParagraphBoundary: |
2298 | // Lines can not use QTextBoundaryFinder since Line there means any potential line-break. |
2299 | return textLineBoundary(beforeAtAfter: 1, text: txt, offset, startOffset, endOffset); |
2300 | case QAccessible::NoBoundary: |
2301 | // return empty, this function currently only supports single lines, so there can be no line after |
2302 | return QString(); |
2303 | default: |
2304 | Q_UNREACHABLE(); |
2305 | } |
2306 | |
2307 | // keep behavior in sync with QTextCursor::movePosition()! |
2308 | |
2309 | QTextBoundaryFinder boundary(type, txt); |
2310 | boundary.setPosition(offset); |
2311 | |
2312 | while (true) { |
2313 | int toNext = boundary.toNextBoundary(); |
2314 | if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem))) |
2315 | break; |
2316 | if (toNext < 0 || toNext >= txt.size()) |
2317 | break; // not found, the boundary might not exist |
2318 | } |
2319 | Q_ASSERT(boundary.position() <= txt.size()); |
2320 | *startOffset = boundary.position(); |
2321 | |
2322 | while (true) { |
2323 | int toNext = boundary.toNextBoundary(); |
2324 | if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem))) |
2325 | break; |
2326 | if (toNext < 0 || toNext >= txt.size()) |
2327 | break; // not found, the boundary might not exist |
2328 | } |
2329 | Q_ASSERT(boundary.position() <= txt.size()); |
2330 | *endOffset = boundary.position(); |
2331 | |
2332 | if ((*startOffset == -1) || (*endOffset == -1) || (*startOffset == *endOffset)) { |
2333 | *endOffset = -1; |
2334 | *startOffset = -1; |
2335 | } |
2336 | |
2337 | return txt.mid(position: *startOffset, n: *endOffset - *startOffset); |
2338 | } |
2339 | |
2340 | /*! |
2341 | Returns the text item of type \a boundaryType at offset \a offset |
2342 | and sets \a startOffset and \a endOffset values to the start and end positions |
2343 | of that item; returns an empty string if there is no such an item. |
2344 | Sets \a startOffset and \a endOffset values to -1 on error. |
2345 | |
2346 | This default implementation is provided for small text edits. A word processor or |
2347 | text editor should provide their own efficient implementations. This function makes no |
2348 | distinction between paragraphs and lines. |
2349 | |
2350 | \note this function can not take the cursor position into account. By convention |
2351 | an \a offset of -2 means that this function should use the cursor position as offset. |
2352 | Thus an offset of -2 must be converted to the cursor position before calling this |
2353 | function. |
2354 | An offset of -1 is used for the text length and custom implementations of this function |
2355 | have to return the result as if the length was passed in as offset. |
2356 | */ |
2357 | QString QAccessibleTextInterface::textAtOffset(int offset, QAccessible::TextBoundaryType boundaryType, |
2358 | int *startOffset, int *endOffset) const |
2359 | { |
2360 | const QString txt = text(startOffset: 0, endOffset: characterCount()); |
2361 | |
2362 | if (offset == -1) |
2363 | offset = txt.size(); |
2364 | |
2365 | *startOffset = *endOffset = -1; |
2366 | if (txt.isEmpty() || offset < 0 || offset > txt.size()) |
2367 | return QString(); |
2368 | |
2369 | if (offset == txt.size() && boundaryType == QAccessible::CharBoundary) |
2370 | return QString(); |
2371 | |
2372 | // type initialized just to silence a compiler warning [-Werror=maybe-uninitialized] |
2373 | QTextBoundaryFinder::BoundaryType type = QTextBoundaryFinder::Grapheme; |
2374 | switch (boundaryType) { |
2375 | case QAccessible::CharBoundary: |
2376 | type = QTextBoundaryFinder::Grapheme; |
2377 | break; |
2378 | case QAccessible::WordBoundary: |
2379 | type = QTextBoundaryFinder::Word; |
2380 | break; |
2381 | case QAccessible::SentenceBoundary: |
2382 | type = QTextBoundaryFinder::Sentence; |
2383 | break; |
2384 | case QAccessible::LineBoundary: |
2385 | case QAccessible::ParagraphBoundary: |
2386 | // Lines can not use QTextBoundaryFinder since Line there means any potential line-break. |
2387 | return textLineBoundary(beforeAtAfter: 0, text: txt, offset, startOffset, endOffset); |
2388 | case QAccessible::NoBoundary: |
2389 | *startOffset = 0; |
2390 | *endOffset = txt.size(); |
2391 | return txt; |
2392 | default: |
2393 | Q_UNREACHABLE(); |
2394 | } |
2395 | |
2396 | // keep behavior in sync with QTextCursor::movePosition()! |
2397 | |
2398 | QTextBoundaryFinder boundary(type, txt); |
2399 | boundary.setPosition(offset); |
2400 | |
2401 | do { |
2402 | if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem))) |
2403 | break; |
2404 | } while (boundary.toPreviousBoundary() > 0); |
2405 | Q_ASSERT(boundary.position() >= 0); |
2406 | *startOffset = boundary.position(); |
2407 | |
2408 | while (boundary.toNextBoundary() < txt.size()) { |
2409 | if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem))) |
2410 | break; |
2411 | } |
2412 | Q_ASSERT(boundary.position() <= txt.size()); |
2413 | *endOffset = boundary.position(); |
2414 | |
2415 | return txt.mid(position: *startOffset, n: *endOffset - *startOffset); |
2416 | } |
2417 | |
2418 | /*! |
2419 | \fn void QAccessibleTextInterface::removeSelection(int selectionIndex) |
2420 | |
2421 | Clears the selection with index \a selectionIndex. |
2422 | */ |
2423 | |
2424 | /*! |
2425 | \fn void QAccessibleTextInterface::setCursorPosition(int position) |
2426 | |
2427 | Moves the cursor to \a position. |
2428 | */ |
2429 | |
2430 | /*! |
2431 | \fn void QAccessibleTextInterface::setSelection(int selectionIndex, int startOffset, int endOffset) |
2432 | |
2433 | Set the selection \a selectionIndex to the range from \a startOffset to \a endOffset. |
2434 | |
2435 | \sa addSelection(), removeSelection() |
2436 | */ |
2437 | |
2438 | /*! |
2439 | \fn int QAccessibleTextInterface::characterCount() const |
2440 | |
2441 | Returns the length of the text (total size including spaces). |
2442 | */ |
2443 | |
2444 | /*! |
2445 | \fn void QAccessibleTextInterface::scrollToSubstring(int startIndex, int endIndex) |
2446 | |
2447 | Ensures that the text between \a startIndex and \a endIndex is visible. |
2448 | */ |
2449 | |
2450 | /*! |
2451 | \class QAccessibleEditableTextInterface |
2452 | \ingroup accessibility |
2453 | \inmodule QtGui |
2454 | |
2455 | \brief The QAccessibleEditableTextInterface class implements support for objects with editable text. |
2456 | |
2457 | When implementing this interface you will almost certainly also want to implement \l QAccessibleTextInterface. |
2458 | |
2459 | \sa QAccessibleInterface |
2460 | |
2461 | \l{IAccessible2 Specification} |
2462 | */ |
2463 | |
2464 | /*! |
2465 | |
2466 | Destroys the QAccessibleEditableTextInterface. |
2467 | */ |
2468 | QAccessibleEditableTextInterface::~QAccessibleEditableTextInterface() |
2469 | { |
2470 | } |
2471 | |
2472 | /*! |
2473 | \fn void QAccessibleEditableTextInterface::deleteText(int startOffset, int endOffset) |
2474 | |
2475 | Deletes the text from \a startOffset to \a endOffset. |
2476 | */ |
2477 | |
2478 | /*! |
2479 | \fn void QAccessibleEditableTextInterface::insertText(int offset, const QString &text) |
2480 | |
2481 | Inserts \a text at position \a offset. |
2482 | */ |
2483 | |
2484 | /*! |
2485 | \fn void QAccessibleEditableTextInterface::replaceText(int startOffset, int endOffset, const QString &text) |
2486 | |
2487 | Removes the text from \a startOffset to \a endOffset and instead inserts \a text. |
2488 | */ |
2489 | |
2490 | /*! |
2491 | \class QAccessibleValueInterface |
2492 | \inmodule QtGui |
2493 | \ingroup accessibility |
2494 | |
2495 | \brief The QAccessibleValueInterface class implements support for objects that manipulate a value. |
2496 | |
2497 | This interface should be implemented by accessible objects that represent a value. |
2498 | Examples are spinner, slider, dial and scroll bar. |
2499 | |
2500 | Instead of forcing the user to deal with the individual parts of the widgets, this interface |
2501 | gives an easier approach to the kind of widget it represents. |
2502 | |
2503 | Usually this interface is implemented by classes that also implement \l QAccessibleInterface. |
2504 | |
2505 | \l{IAccessible2 Specification} |
2506 | */ |
2507 | |
2508 | /*! |
2509 | Destroys the QAccessibleValueInterface. |
2510 | |
2511 | */ |
2512 | QAccessibleValueInterface::~QAccessibleValueInterface() |
2513 | { |
2514 | } |
2515 | |
2516 | /*! |
2517 | \fn QVariant QAccessibleValueInterface::currentValue() const |
2518 | |
2519 | Returns the current value of the widget. This is usually a double or int. |
2520 | \sa setCurrentValue() |
2521 | */ |
2522 | |
2523 | /*! |
2524 | \fn void QAccessibleValueInterface::setCurrentValue(const QVariant &value) |
2525 | |
2526 | Sets the \a value. If the desired \a value is out of the range of permissible values, |
2527 | this call will be ignored. |
2528 | |
2529 | \sa currentValue(), minimumValue(), maximumValue() |
2530 | */ |
2531 | |
2532 | /*! |
2533 | \fn QVariant QAccessibleValueInterface::maximumValue() const |
2534 | |
2535 | Returns the maximum value this object accepts. |
2536 | \sa minimumValue(), currentValue() |
2537 | */ |
2538 | |
2539 | /*! |
2540 | \fn QVariant QAccessibleValueInterface::minimumValue() const |
2541 | |
2542 | Returns the minimum value this object accepts. |
2543 | \sa maximumValue(), currentValue() |
2544 | */ |
2545 | |
2546 | /*! |
2547 | \fn QVariant QAccessibleValueInterface::minimumStepSize() const |
2548 | |
2549 | Returns the minimum step size for the accessible. |
2550 | This is the smallest increment that makes sense when changing the value. |
2551 | When programmatically changing the value it should always be a multiple |
2552 | of the minimum step size. |
2553 | |
2554 | Some tools use this value even when the setCurrentValue does not |
2555 | perform any action. Progress bars for example are read-only but |
2556 | should return their range divided by 100. |
2557 | */ |
2558 | |
2559 | /*! |
2560 | \class QAccessibleImageInterface |
2561 | \inmodule QtGui |
2562 | \ingroup accessibility |
2563 | \internal |
2564 | \preliminary |
2565 | |
2566 | \brief The QAccessibleImageInterface class implements support for |
2567 | the IAccessibleImage interface. |
2568 | |
2569 | \l{IAccessible2 Specification} |
2570 | */ |
2571 | |
2572 | /*! |
2573 | Destroys the QAccessibleImageInterface. |
2574 | */ |
2575 | QAccessibleImageInterface::~QAccessibleImageInterface() |
2576 | { |
2577 | } |
2578 | |
2579 | /*! |
2580 | \class QAccessibleTableCellInterface |
2581 | \inmodule QtGui |
2582 | \ingroup accessibility |
2583 | |
2584 | \brief The QAccessibleTableCellInterface class implements support for |
2585 | the IAccessibleTable2 Cell interface. |
2586 | |
2587 | \l{IAccessible2 Specification} |
2588 | */ |
2589 | |
2590 | /*! |
2591 | |
2592 | Destroys the QAccessibleTableCellInterface. |
2593 | */ |
2594 | QAccessibleTableCellInterface::~QAccessibleTableCellInterface() |
2595 | { |
2596 | } |
2597 | |
2598 | /*! |
2599 | \fn virtual int QAccessibleTableCellInterface::columnExtent() const |
2600 | |
2601 | Returns the number of columns occupied by this cell accessible. |
2602 | */ |
2603 | |
2604 | /*! |
2605 | \fn virtual QList<QAccessibleInterface*> QAccessibleTableCellInterface::columnHeaderCells() const |
2606 | |
2607 | Returns the column headers as an array of cell accessibles. |
2608 | */ |
2609 | |
2610 | /*! |
2611 | \fn virtual int QAccessibleTableCellInterface::columnIndex() const |
2612 | |
2613 | Translates this cell accessible into the corresponding column index. |
2614 | */ |
2615 | |
2616 | /*! |
2617 | \fn virtual int QAccessibleTableCellInterface::rowExtent() const |
2618 | |
2619 | Returns the number of rows occupied by this cell accessible. |
2620 | */ |
2621 | |
2622 | /*! |
2623 | \fn virtual QList<QAccessibleInterface*> QAccessibleTableCellInterface::rowHeaderCells() const |
2624 | |
2625 | Returns the row headers as an array of cell accessibles. |
2626 | */ |
2627 | |
2628 | /*! |
2629 | \fn virtual int QAccessibleTableCellInterface::rowIndex() const |
2630 | |
2631 | Translates this cell accessible into the corresponding row index. |
2632 | */ |
2633 | |
2634 | /*! |
2635 | \fn virtual bool QAccessibleTableCellInterface::isSelected() const |
2636 | |
2637 | Returns a boolean value indicating whether this cell is selected. |
2638 | */ |
2639 | |
2640 | /*! |
2641 | \fn virtual QAccessibleInterface *QAccessibleTableCellInterface::table() const |
2642 | |
2643 | Returns the QAccessibleInterface of the table containing this cell. |
2644 | */ |
2645 | |
2646 | |
2647 | /*! |
2648 | \class QAccessibleTableInterface |
2649 | \inmodule QtGui |
2650 | \ingroup accessibility |
2651 | |
2652 | \brief The QAccessibleTableInterface class implements support for |
2653 | the IAccessibleTable2 interface. |
2654 | |
2655 | \l{IAccessible2 Specification} |
2656 | */ |
2657 | |
2658 | /*! |
2659 | |
2660 | Destroys the QAccessibleTableInterface. |
2661 | */ |
2662 | QAccessibleTableInterface::~QAccessibleTableInterface() |
2663 | { |
2664 | } |
2665 | |
2666 | /*! |
2667 | \fn virtual QAccessibleInterface *QAccessibleTableInterface::cellAt(int row, int column) const |
2668 | |
2669 | Returns the cell at the specified \a row and \a column in the table. |
2670 | */ |
2671 | |
2672 | /*! |
2673 | \fn virtual QAccessibleInterface *QAccessibleTableInterface::caption() const |
2674 | |
2675 | Returns the caption for the table. |
2676 | */ |
2677 | |
2678 | /*! |
2679 | \fn virtual QString QAccessibleTableInterface::columnDescription(int column) const |
2680 | |
2681 | Returns the description text of the specified \a column in the table. |
2682 | */ |
2683 | |
2684 | /*! |
2685 | \fn virtual int QAccessibleTableInterface::columnCount() const |
2686 | |
2687 | Returns the total number of columns in table. |
2688 | */ |
2689 | |
2690 | /*! |
2691 | \fn virtual int QAccessibleTableInterface::rowCount() const |
2692 | |
2693 | Returns the total number of rows in table. |
2694 | */ |
2695 | |
2696 | /*! |
2697 | \fn virtual int QAccessibleTableInterface::selectedCellCount() const |
2698 | |
2699 | Returns the total number of selected cells. |
2700 | */ |
2701 | |
2702 | /*! |
2703 | \fn virtual int QAccessibleTableInterface::selectedColumnCount() const |
2704 | |
2705 | Returns the total number of selected columns. |
2706 | */ |
2707 | |
2708 | /*! |
2709 | \fn virtual int QAccessibleTableInterface::selectedRowCount() const |
2710 | |
2711 | Returns the total number of selected rows. |
2712 | */ |
2713 | |
2714 | /*! |
2715 | \fn virtual QString QAccessibleTableInterface::rowDescription(int row) const |
2716 | |
2717 | Returns the description text of the specified \a row in the table. |
2718 | */ |
2719 | |
2720 | /*! |
2721 | \fn virtual QList<int> QAccessibleTableInterface::selectedCells() const |
2722 | |
2723 | Returns the list of selected cell (by their index as \l QAccessibleInterface::child() accepts). |
2724 | */ |
2725 | |
2726 | /*! |
2727 | \fn virtual QList<int> QAccessibleTableInterface::selectedColumns() const |
2728 | |
2729 | Returns the list of currently selected columns. |
2730 | */ |
2731 | |
2732 | /*! |
2733 | \fn virtual QList<int> QAccessibleTableInterface::selectedRows() const |
2734 | |
2735 | Returns the list of currently selected rows. |
2736 | */ |
2737 | |
2738 | /*! |
2739 | \fn virtual QAccessibleInterface *QAccessibleTableInterface::summary() const |
2740 | |
2741 | Returns a QAccessibleInterface that represents a summary of the table. |
2742 | This function may return 0 if no such interface exists. |
2743 | */ |
2744 | |
2745 | /*! |
2746 | \fn virtual bool QAccessibleTableInterface::isColumnSelected(int column) const |
2747 | |
2748 | Returns a boolean value indicating whether the specified \a column is completely selected. |
2749 | */ |
2750 | |
2751 | /*! |
2752 | \fn virtual bool QAccessibleTableInterface::isRowSelected(int row) const |
2753 | |
2754 | Returns a boolean value indicating whether the specified \a row is completely selected. |
2755 | */ |
2756 | |
2757 | /*! |
2758 | \fn virtual bool QAccessibleTableInterface::selectRow(int row) |
2759 | |
2760 | Selects \a row. This function might unselect all previously selected rows. |
2761 | Returns \c true if the selection was successful. |
2762 | */ |
2763 | |
2764 | /*! |
2765 | \fn virtual bool QAccessibleTableInterface::selectColumn(int column) |
2766 | |
2767 | Selects \a column. This function might unselect all previously selected columns. |
2768 | Returns \c true if the selection was successful. |
2769 | */ |
2770 | |
2771 | /*! |
2772 | \fn virtual bool QAccessibleTableInterface::unselectRow(int row) |
2773 | |
2774 | Unselects \a row, leaving other selected rows selected (if any). |
2775 | Returns \c true if the selection was successful. |
2776 | */ |
2777 | |
2778 | /*! |
2779 | \fn virtual bool QAccessibleTableInterface::unselectColumn(int column) |
2780 | |
2781 | Unselects \a column, leaving other selected columns selected (if any). |
2782 | Returns \c true if the selection was successful. |
2783 | */ |
2784 | |
2785 | /*! |
2786 | \fn virtual void QAccessibleTableInterface::modelChange(QAccessibleTableModelChangeEvent *event) |
2787 | |
2788 | Informs about a change in the model's layout. |
2789 | The \a event contains the details. |
2790 | \sa QAccessibleTableModelChangeEvent |
2791 | */ |
2792 | |
2793 | |
2794 | /*! |
2795 | \class QAccessibleActionInterface |
2796 | \inmodule QtGui |
2797 | \ingroup accessibility |
2798 | |
2799 | \brief The QAccessibleActionInterface class implements support for |
2800 | invocable actions in the interface. |
2801 | |
2802 | Accessible objects should implement the action interface if they support user interaction. |
2803 | Usually this interface is implemented by classes that also implement \l QAccessibleInterface. |
2804 | |
2805 | The supported actions should use the predefined actions offered in this class unless they do not |
2806 | fit a predefined action. In that case a custom action can be added. |
2807 | |
2808 | When subclassing QAccessibleActionInterface you need to provide a list of actionNames which |
2809 | is the primary means to discover the available actions. Action names are never localized. |
2810 | In order to present actions to the user there are two functions that need to return localized versions |
2811 | of the name and give a description of the action. For the predefined action names use |
2812 | \l QAccessibleActionInterface::localizedActionName() and \l QAccessibleActionInterface::localizedActionDescription() |
2813 | to return their localized counterparts. |
2814 | |
2815 | In general you should use one of the predefined action names, unless describing an action that does not fit these: |
2816 | \table |
2817 | \header \li Action name \li Description |
2818 | \row \li \l toggleAction() \li toggles the item (checkbox, radio button, switch, ...) |
2819 | \row \li \l decreaseAction() \li decrease the value of the accessible (e.g. spinbox) |
2820 | \row \li \l increaseAction() \li increase the value of the accessible (e.g. spinbox) |
2821 | \row \li \l pressAction() \li press or click or activate the accessible (should correspond to clicking the object with the mouse) |
2822 | \row \li \l setFocusAction() \li set the focus to this accessible |
2823 | \row \li \l showMenuAction() \li show a context menu, corresponds to right-clicks |
2824 | \endtable |
2825 | |
2826 | In order to invoke the action, \l doAction() is called with an action name. |
2827 | |
2828 | Most widgets will simply implement \l pressAction(). This is what happens when the widget is activated by |
2829 | being clicked, space pressed or similar. |
2830 | |
2831 | \l{IAccessible2 Specification} |
2832 | */ |
2833 | |
2834 | /*! |
2835 | |
2836 | Destroys the QAccessibleActionInterface. |
2837 | */ |
2838 | QAccessibleActionInterface::~QAccessibleActionInterface() |
2839 | { |
2840 | } |
2841 | |
2842 | /*! |
2843 | \fn QStringList QAccessibleActionInterface::actionNames() const |
2844 | |
2845 | Returns the list of actions supported by this accessible object. |
2846 | The actions returned should be in preferred order, |
2847 | i.e. the action that the user most likely wants to trigger should be returned first, |
2848 | while the least likely action should be returned last. |
2849 | |
2850 | The list does only contain actions that can be invoked. |
2851 | It won't return disabled actions, or actions associated with disabled UI controls. |
2852 | |
2853 | The list can be empty. |
2854 | |
2855 | Note that this list is not localized. For a localized representation re-implement \l localizedActionName() |
2856 | and \l localizedActionDescription() |
2857 | |
2858 | \sa doAction(), localizedActionName(), localizedActionDescription() |
2859 | */ |
2860 | |
2861 | /*! |
2862 | \fn QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const |
2863 | |
2864 | Returns a localized action name of \a actionName. |
2865 | |
2866 | For custom actions this function has to be re-implemented. |
2867 | When using one of the default names, you can call this function in QAccessibleActionInterface |
2868 | to get the localized string. |
2869 | |
2870 | \sa actionNames(), localizedActionDescription() |
2871 | */ |
2872 | |
2873 | /*! |
2874 | \fn QString QAccessibleActionInterface::localizedActionDescription(const QString &actionName) const |
2875 | |
2876 | Returns a localized action description of the action \a actionName. |
2877 | |
2878 | When using one of the default names, you can call this function in QAccessibleActionInterface |
2879 | to get the localized string. |
2880 | |
2881 | \sa actionNames(), localizedActionName() |
2882 | */ |
2883 | |
2884 | /*! |
2885 | \fn void QAccessibleActionInterface::doAction(const QString &actionName) |
2886 | |
2887 | Invokes the action specified by \a actionName. |
2888 | Note that \a actionName is the non-localized name as returned by \l actionNames() |
2889 | This function is usually implemented by calling the same functions |
2890 | that other user interaction, such as clicking the object, would trigger. |
2891 | |
2892 | \sa actionNames() |
2893 | */ |
2894 | |
2895 | /*! |
2896 | \fn QStringList QAccessibleActionInterface::keyBindingsForAction(const QString &actionName) const |
2897 | |
2898 | Returns a list of the keyboard shortcuts available for invoking the action named \a actionName. |
2899 | |
2900 | This is important to let users learn alternative ways of using the application by emphasizing the keyboard. |
2901 | |
2902 | \sa actionNames() |
2903 | */ |
2904 | |
2905 | |
2906 | struct QAccessibleActionStrings |
2907 | { |
2908 | QAccessibleActionStrings() : |
2909 | pressAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface" , "Press" ))), |
2910 | increaseAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface" , "Increase" ))), |
2911 | decreaseAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface" , "Decrease" ))), |
2912 | showMenuAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface" , "ShowMenu" ))), |
2913 | setFocusAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface" , "SetFocus" ))), |
2914 | toggleAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface" , "Toggle" ))), |
2915 | scrollLeftAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface" , "Scroll Left" ))), |
2916 | scrollRightAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface" , "Scroll Right" ))), |
2917 | scrollUpAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface" , "Scroll Up" ))), |
2918 | scrollDownAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface" , "Scroll Down" ))), |
2919 | previousPageAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface" , "Previous Page" ))), |
2920 | nextPageAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface" , "Next Page" ))) |
2921 | {} |
2922 | |
2923 | const QString pressAction; |
2924 | const QString increaseAction; |
2925 | const QString decreaseAction; |
2926 | const QString ; |
2927 | const QString setFocusAction; |
2928 | const QString toggleAction; |
2929 | const QString scrollLeftAction; |
2930 | const QString scrollRightAction; |
2931 | const QString scrollUpAction; |
2932 | const QString scrollDownAction; |
2933 | const QString previousPageAction; |
2934 | const QString nextPageAction; |
2935 | |
2936 | QString localizedDescription(const QString &actionName) |
2937 | { |
2938 | if (actionName == pressAction) |
2939 | return QAccessibleActionInterface::tr(sourceText: "Triggers the action" ); |
2940 | else if (actionName == increaseAction) |
2941 | return QAccessibleActionInterface::tr(sourceText: "Increase the value" ); |
2942 | else if (actionName == decreaseAction) |
2943 | return QAccessibleActionInterface::tr(sourceText: "Decrease the value" ); |
2944 | else if (actionName == showMenuAction) |
2945 | return QAccessibleActionInterface::tr(sourceText: "Shows the menu" ); |
2946 | else if (actionName == setFocusAction) |
2947 | return QAccessibleActionInterface::tr(sourceText: "Sets the focus" ); |
2948 | else if (actionName == toggleAction) |
2949 | return QAccessibleActionInterface::tr(sourceText: "Toggles the state" ); |
2950 | else if (actionName == scrollLeftAction) |
2951 | return QAccessibleActionInterface::tr(sourceText: "Scrolls to the left" ); |
2952 | else if (actionName == scrollRightAction) |
2953 | return QAccessibleActionInterface::tr(sourceText: "Scrolls to the right" ); |
2954 | else if (actionName == scrollUpAction) |
2955 | return QAccessibleActionInterface::tr(sourceText: "Scrolls up" ); |
2956 | else if (actionName == scrollDownAction) |
2957 | return QAccessibleActionInterface::tr(sourceText: "Scrolls down" ); |
2958 | else if (actionName == previousPageAction) |
2959 | return QAccessibleActionInterface::tr(sourceText: "Goes back a page" ); |
2960 | else if (actionName == nextPageAction) |
2961 | return QAccessibleActionInterface::tr(sourceText: "Goes to the next page" ); |
2962 | |
2963 | |
2964 | return QString(); |
2965 | } |
2966 | }; |
2967 | |
2968 | Q_GLOBAL_STATIC(QAccessibleActionStrings, accessibleActionStrings) |
2969 | |
2970 | QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const |
2971 | { |
2972 | return QAccessibleActionInterface::tr(qPrintable(actionName)); |
2973 | } |
2974 | |
2975 | QString QAccessibleActionInterface::localizedActionDescription(const QString &actionName) const |
2976 | { |
2977 | return accessibleActionStrings()->localizedDescription(actionName); |
2978 | } |
2979 | |
2980 | /*! |
2981 | Returns the name of the press default action. |
2982 | \sa actionNames(), localizedActionName() |
2983 | */ |
2984 | const QString &QAccessibleActionInterface::pressAction() |
2985 | { |
2986 | return accessibleActionStrings()->pressAction; |
2987 | } |
2988 | |
2989 | /*! |
2990 | Returns the name of the increase default action. |
2991 | \sa actionNames(), localizedActionName() |
2992 | */ |
2993 | const QString &QAccessibleActionInterface::increaseAction() |
2994 | { |
2995 | return accessibleActionStrings()->increaseAction; |
2996 | } |
2997 | |
2998 | /*! |
2999 | Returns the name of the decrease default action. |
3000 | \sa actionNames(), localizedActionName() |
3001 | */ |
3002 | const QString &QAccessibleActionInterface::decreaseAction() |
3003 | { |
3004 | return accessibleActionStrings()->decreaseAction; |
3005 | } |
3006 | |
3007 | /*! |
3008 | Returns the name of the show menu default action. |
3009 | \sa actionNames(), localizedActionName() |
3010 | */ |
3011 | const QString &QAccessibleActionInterface::() |
3012 | { |
3013 | return accessibleActionStrings()->showMenuAction; |
3014 | } |
3015 | |
3016 | /*! |
3017 | Returns the name of the set focus default action. |
3018 | \sa actionNames(), localizedActionName() |
3019 | */ |
3020 | const QString &QAccessibleActionInterface::setFocusAction() |
3021 | { |
3022 | return accessibleActionStrings()->setFocusAction; |
3023 | } |
3024 | |
3025 | /*! |
3026 | Returns the name of the toggle default action. |
3027 | \sa actionNames(), localizedActionName() |
3028 | */ |
3029 | const QString &QAccessibleActionInterface::toggleAction() |
3030 | { |
3031 | return accessibleActionStrings()->toggleAction; |
3032 | } |
3033 | |
3034 | /*! |
3035 | Returns the name of the scroll left default action. |
3036 | \sa actionNames(), localizedActionName() |
3037 | */ |
3038 | QString QAccessibleActionInterface::scrollLeftAction() |
3039 | { |
3040 | return accessibleActionStrings()->scrollLeftAction; |
3041 | } |
3042 | |
3043 | /*! |
3044 | Returns the name of the scroll right default action. |
3045 | \sa actionNames(), localizedActionName() |
3046 | */ |
3047 | QString QAccessibleActionInterface::scrollRightAction() |
3048 | { |
3049 | return accessibleActionStrings()->scrollRightAction; |
3050 | } |
3051 | |
3052 | /*! |
3053 | Returns the name of the scroll up default action. |
3054 | \sa actionNames(), localizedActionName() |
3055 | */ |
3056 | QString QAccessibleActionInterface::scrollUpAction() |
3057 | { |
3058 | return accessibleActionStrings()->scrollUpAction; |
3059 | } |
3060 | |
3061 | /*! |
3062 | Returns the name of the scroll down default action. |
3063 | \sa actionNames(), localizedActionName() |
3064 | */ |
3065 | QString QAccessibleActionInterface::scrollDownAction() |
3066 | { |
3067 | return accessibleActionStrings()->scrollDownAction; |
3068 | } |
3069 | |
3070 | /*! |
3071 | Returns the name of the previous page default action. |
3072 | \sa actionNames(), localizedActionName() |
3073 | */ |
3074 | QString QAccessibleActionInterface::previousPageAction() |
3075 | { |
3076 | return accessibleActionStrings()->previousPageAction; |
3077 | } |
3078 | |
3079 | /*! |
3080 | Returns the name of the next page default action. |
3081 | \sa actionNames(), localizedActionName() |
3082 | */ |
3083 | QString QAccessibleActionInterface::nextPageAction() |
3084 | { |
3085 | return accessibleActionStrings()->nextPageAction; |
3086 | } |
3087 | |
3088 | |
3089 | /*! |
3090 | \since 6.5 |
3091 | \class QAccessibleSelectionInterface |
3092 | \inmodule QtGui |
3093 | \ingroup accessibility |
3094 | |
3095 | \brief The QAccessibleSelectionInterface class implements support for |
3096 | selection handling. |
3097 | |
3098 | It provides methods for both, retrieving the current selection |
3099 | as well as modifying the selection. |
3100 | |
3101 | Only selections of direct children are supported. |
3102 | */ |
3103 | |
3104 | /*! |
3105 | |
3106 | Destroys the QAccessibleSelectionInterface. |
3107 | */ |
3108 | QAccessibleSelectionInterface::~QAccessibleSelectionInterface() |
3109 | { |
3110 | } |
3111 | |
3112 | /*! |
3113 | \fn virtual int QAccessibleSelectionInterface::selectedItemCount() const |
3114 | |
3115 | Returns the total number of selected accessible items. |
3116 | */ |
3117 | |
3118 | /*! |
3119 | \fn virtual QList<QAccessibleInterface *> QAccessibleSelectionInterface::selectedItems() const |
3120 | |
3121 | Returns the list of selected accessible items. |
3122 | */ |
3123 | |
3124 | /*! |
3125 | Returns the selected accessible item at index \a selectionIndex in the selection. |
3126 | |
3127 | Note that the index refers to the n-th selected accessible item (i.e. the index in the current selection), |
3128 | which generally differs from the index that would be passed to \l QAccessibleInterface::child() |
3129 | in order to retrieve the same item. |
3130 | |
3131 | The default implementation uses \a selectionIndex to retrieve the item from the list |
3132 | of selected items retrieved by \l QAccessibleSelectionInterface::selectedItems(). |
3133 | |
3134 | In particular for implementations dealing with many selected items, reimplementing |
3135 | this method in a more efficient way may be desirable for performance reasons. |
3136 | */ |
3137 | QAccessibleInterface* QAccessibleSelectionInterface::selectedItem(int selectionIndex) const |
3138 | { |
3139 | QList<QAccessibleInterface*> items = selectedItems(); |
3140 | if (selectionIndex < 0 || selectionIndex > items.length() -1) { |
3141 | qCWarning(lcAccessibilityCore) << "Selection index" << selectionIndex << "out of range." ; |
3142 | return nullptr; |
3143 | } |
3144 | |
3145 | return items.at(i: selectionIndex); |
3146 | } |
3147 | |
3148 | /*! |
3149 | Returns whether \a childItem is part of the current selection. |
3150 | |
3151 | The default implementation checks whether \a childItem is contained |
3152 | in the list of items retrieved by \l QAccessibleSelectionInterface::selectedItems. |
3153 | */ |
3154 | bool QAccessibleSelectionInterface::isSelected(QAccessibleInterface *childItem) const |
3155 | { |
3156 | return selectedItems().contains(t: childItem); |
3157 | } |
3158 | |
3159 | /*! |
3160 | \fn virtual bool QAccessibleSelectionInterface::select(QAccessibleInterface *childItem) |
3161 | |
3162 | Adds \a childItem to the selection. |
3163 | Returns whether \a childItem has actually been added to the selection. |
3164 | |
3165 | For implementations that only allow single selections, |
3166 | this may replace the current selection. |
3167 | */ |
3168 | |
3169 | /*! |
3170 | \fn virtual bool QAccessibleSelectionInterface::unselect(QAccessibleInterface *childItem) |
3171 | |
3172 | Removes \a childItem from the selection. |
3173 | |
3174 | Returns whether the accessible item has actually been removed from the selection. |
3175 | */ |
3176 | |
3177 | /*! |
3178 | \fn virtual bool QAccessibleSelectionInterface::selectAll() |
3179 | |
3180 | Selects all accessible child items. |
3181 | |
3182 | Returns whether all accessible child items have actually been added to the selection. |
3183 | */ |
3184 | |
3185 | /*! |
3186 | \fn virtual bool QAccessibleSelectionInterface::clear() |
3187 | |
3188 | Unselects all accessible child items. |
3189 | |
3190 | Returns whether all accessible child items have actually been removed from the selection, |
3191 | i.e. whether the selection is empty after this method has been called. |
3192 | */ |
3193 | |
3194 | |
3195 | /*! |
3196 | \since 6.8 |
3197 | \class QAccessibleAttributesInterface |
3198 | \inmodule QtGui |
3199 | \ingroup accessibility |
3200 | |
3201 | \brief The QAccessibleAttributesInterface class implements support for |
3202 | reporting attributes for an accessible object. |
3203 | |
3204 | Attributes are key-value pairs. Values are stored in \l QVariant. |
3205 | |
3206 | The \l QAccessible::Attribute enumeration describes the available keys and |
3207 | documents which type to use for the value of each key. |
3208 | |
3209 | While the text-specific attributes handled by \l QAccessibleTextInterface::attributes |
3210 | are specific to objects implementing text and are specific to a specific text |
3211 | position/offset, the attributes handled by the \l QAccessibleAttributesInterface |
3212 | can be used for objects of any role and apply for the whole object. |
3213 | |
3214 | Classes already implementing \l QAccessibleTextInterface for text-specific attrtibutes |
3215 | may want to implement \l QAccessibleAttributesInterface in addition for object-specific |
3216 | attributes. |
3217 | */ |
3218 | |
3219 | /*! |
3220 | |
3221 | Destroys the QAccessibleAttributesInterface. |
3222 | */ |
3223 | QAccessibleAttributesInterface::~QAccessibleAttributesInterface() |
3224 | { |
3225 | } |
3226 | |
3227 | /*! |
3228 | \fn QList<QAccessible::Attribute> QAccessibleAttributesInterface::attributeKeys() const |
3229 | |
3230 | Returns the keys of all attributes the object supports. The \l QAccessible::Attribute |
3231 | enumeration describes available keys. |
3232 | */ |
3233 | |
3234 | /*! |
3235 | \fn QVariant QAccessibleAttributesInterface::attributeValue(QAccessible::Attribute key) const |
3236 | |
3237 | Returns the value of the attribute \a key of this object. |
3238 | |
3239 | If the attribute is set for this object, a value of the type documented for the |
3240 | given key in the documentation of the \l QAccessible::Attribute enumeration is |
3241 | returned in the \l QVariant. |
3242 | |
3243 | Otherwise, an invalid \l QVariant is returned. |
3244 | */ |
3245 | |
3246 | /*! \internal */ |
3247 | QString qAccessibleLocalizedActionDescription(const QString &actionName) |
3248 | { |
3249 | return accessibleActionStrings()->localizedDescription(actionName); |
3250 | } |
3251 | |
3252 | /*! |
3253 | \internal |
3254 | \fn QString QAccessibleHyperlinkInterface::anchor() const |
3255 | |
3256 | The logical/human readable name of the hyperlink |
3257 | */ |
3258 | |
3259 | /*! |
3260 | \internal |
3261 | \fn QString QAccessibleHyperlinkInterface::anchorTarget() const |
3262 | |
3263 | The target url of the hyperlink |
3264 | */ |
3265 | |
3266 | /*! |
3267 | \internal |
3268 | \fn int QAccessibleHyperlinkInterface::startIndex() const |
3269 | |
3270 | Returns the start index that will refer to the first character in the text where the hyperlink |
3271 | begins. The index corresponds to the index that the QAccessibleTextInterface needs in order |
3272 | to find the start of the hyperlink. |
3273 | |
3274 | */ |
3275 | |
3276 | /*! |
3277 | \internal |
3278 | \fn int QAccessibleHyperlinkInterface::endIndex() const |
3279 | |
3280 | Returns the end index that will refer to the first character in the text where the hyperlink |
3281 | begins. The index corresponds to the index that the QAccessibleTextInterface needs in order |
3282 | to find the end of the hyperlink. |
3283 | */ |
3284 | |
3285 | QAccessibleHyperlinkInterface::~QAccessibleHyperlinkInterface() |
3286 | { |
3287 | |
3288 | } |
3289 | |
3290 | #endif // QT_CONFIG(accessibility) |
3291 | |
3292 | QT_END_NAMESPACE |
3293 | |
3294 | #include "moc_qaccessible_base.cpp" |
3295 | |