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

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