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
25QT_BEGIN_NAMESPACE
26
27using namespace Qt::StringLiterals;
28
29Q_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*/
508QAccessibleInterface::~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 */
520Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, acLoader,
521 (QAccessibleFactoryInterface_iid, "/accessible"_L1))
522typedef QHash<QString, QAccessiblePlugin*> QAccessiblePluginsHash;
523Q_GLOBAL_STATIC(QAccessiblePluginsHash, qAccessiblePlugins)
524
525// FIXME turn this into one global static struct
526Q_GLOBAL_STATIC(QList<QAccessible::InterfaceFactory>, qAccessibleFactories)
527Q_GLOBAL_STATIC(QList<QAccessible::ActivationObserver *>, qAccessibleActivationObservers)
528
529QAccessible::UpdateHandler QAccessible::updateHandler = nullptr;
530QAccessible::RootObjectHandler QAccessible::rootObjectHandler = nullptr;
531
532static bool cleanupAdded = false;
533
534static 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*/
552void QAccessible::cleanup()
553{
554 if (QPlatformAccessibility *pfAccessibility = platformAccessibility())
555 pfAccessibility->cleanup();
556}
557
558static 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*/
611void 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*/
628void 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*/
640QAccessible::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*/
653QAccessible::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
668QAccessible::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*/
677void 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*/
697void 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*/
720QAccessibleInterface *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 */
810QAccessible::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*/
821void QAccessible::deleteAccessibleInterface(Id id)
822{
823 QAccessibleCache::instance()->deleteInterface(id);
824}
825
826/*!
827 Returns the unique ID for the QAccessibleInterface \a iface.
828*/
829QAccessible::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*/
842QAccessibleInterface *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*/
859bool QAccessible::isActive()
860{
861 if (QPlatformAccessibility *pfAccessibility = platformAccessibility())
862 return pfAccessibility->isActive();
863 return false;
864}
865
866/*!
867 \internal
868*/
869void 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*/
890void 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*/
920void 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*/
952QPair< 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*/
1160QList<QPair<QAccessibleInterface*, QAccessible::Relation>>
1161QAccessibleInterface::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*/
1172QAccessibleInterface *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*/
1318QColor 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*/
1328QColor 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*/
1405QAccessibleEvent::~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*/
1432QAccessible::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*/
1484QAccessibleValueChangeEvent::~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*/
1527QAccessibleStateChangeEvent::~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*/
1606QAccessibleTableModelChangeEvent::~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*/
1634QAccessibleTextCursorEvent::~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*/
1674QAccessibleTextInsertEvent::~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*/
1716QAccessibleTextRemoveEvent::~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*/
1777QAccessibleTextUpdateEvent::~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*/
1811QAccessibleTextSelectionEvent::~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*/
1864QAccessibleAnnouncementEvent::~QAccessibleAnnouncementEvent()
1865{
1866}
1867
1868/*!
1869 Returns the QAccessibleInterface associated with the event.
1870*/
1871QAccessibleInterface *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 */
1904QWindow *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*/
1917void 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 */
1938const 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 */
1947const 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 */
1955Q_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 */
1997QDebug 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*/
2080QAccessibleTextInterface::~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*/
2151static 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*/
2198QString 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*/
2272QString 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*/
2357QString 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*/
2468QAccessibleEditableTextInterface::~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*/
2512QAccessibleValueInterface::~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*/
2575QAccessibleImageInterface::~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*/
2594QAccessibleTableCellInterface::~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*/
2662QAccessibleTableInterface::~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*/
2838QAccessibleActionInterface::~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
2906struct 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 showMenuAction;
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
2968Q_GLOBAL_STATIC(QAccessibleActionStrings, accessibleActionStrings)
2969
2970QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const
2971{
2972 return QAccessibleActionInterface::tr(qPrintable(actionName));
2973}
2974
2975QString 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 */
2984const 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 */
2993const 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 */
3002const 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 */
3011const QString &QAccessibleActionInterface::showMenuAction()
3012{
3013 return accessibleActionStrings()->showMenuAction;
3014}
3015
3016/*!
3017 Returns the name of the set focus default action.
3018 \sa actionNames(), localizedActionName()
3019 */
3020const 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 */
3029const 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 */
3038QString 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 */
3047QString 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 */
3056QString 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 */
3065QString 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 */
3074QString 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 */
3083QString 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*/
3108QAccessibleSelectionInterface::~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*/
3137QAccessibleInterface* 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*/
3154bool 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*/
3223QAccessibleAttributesInterface::~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 */
3247QString 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
3285QAccessibleHyperlinkInterface::~QAccessibleHyperlinkInterface()
3286{
3287
3288}
3289
3290#endif // QT_CONFIG(accessibility)
3291
3292QT_END_NAMESPACE
3293
3294#include "moc_qaccessible_base.cpp"
3295

source code of qtbase/src/gui/accessible/qaccessible.cpp