1	// Copyright (C) 2020 The Qt Company Ltd.
2	// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4	#include "qaccessible.h"
5
6	#include "qaccessiblecache_p.h"
7	#include "qaccessibleplugin.h"
8	#include "qaccessibleobject.h"
9	#include "qaccessiblebridge.h"
10	#include <QtCore/qtextboundaryfinder.h>
11	#include <QtGui/qclipboard.h>
12	#include <QtGui/qguiapplication.h>
13	#include <QtGui/qtextcursor.h>
14	#include <private/qguiapplication_p.h>
15	#include <qpa/qplatformaccessibility.h>
16	#include <qpa/qplatformintegration.h>
17
18	#include <QtCore/qdebug.h>
19	#include <QtCore/qloggingcategory.h>
20	#include <QtCore/qmetaobject.h>
21	#include <QtCore/private/qmetaobject_p.h>
22	#include <QtCore/qhash.h>
23	#include <private/qfactoryloader_p.h>
24
25	QT_BEGIN_NAMESPACE
26
27	using namespace Qt::StringLiterals;
28
29	Q_LOGGING_CATEGORY(lcAccessibilityCore, "qt.accessibility.core");
30
31	/*!
32	\class QAccessible
33	\brief The QAccessible class provides enums and static functions
34	related to accessibility.
35
36	\ingroup accessibility
37	\inmodule QtGui
38
39	This class is part of \l {Accessibility for QWidget Applications}.
40
41	Accessible applications can be used by people who are not able to
42	use applications by conventional means.
43
44	The functions in this class are used for communication between
45	accessible applications (also called AT Servers) and
46	accessibility tools (AT Clients), such as screen readers and
47	braille displays. Clients and servers communicate in the following way:
48
49	\list
50	\li \e{AT Servers} notify the clients about events through calls to the
51	updateAccessibility() function.
52
53	\li \e{AT Clients} request information about the objects in the server.
54	The QAccessibleInterface class is the core interface, and encapsulates
55	this information in a pure virtual API. Implementations of the interface
56	are provided by Qt through the queryAccessibleInterface() API.
57	\endlist
58
59	The communication between servers and clients is initialized by
60	the setRootObject() function. Function pointers can be installed
61	to replace or extend the default behavior of the static functions
62	in QAccessible.
63
64	Qt supports Microsoft Active Accessibility (MSAA), \macos
65	Accessibility, and the Unix/X11 AT-SPI standard. Other backends
66	can be supported using QAccessibleBridge.
67
68	In the Unix/X11 AT-SPI implementation, applications become accessible
69	when two conditions are met:
70	\list
71	\li org.a11y.Status.IsEnabled DBus property is true
72	\li org.a11y.Status.ScreenReaderEnabled DBus property is true
73	\endlist
74	An alternative to setting the DBus AT-SPI properties is to set
75	the QT_LINUX_ACCESSIBILITY_ALWAYS_ON environment variable.
76
77	In addition to QAccessible's static functions, Qt offers one
78	generic interface, QAccessibleInterface, that can be used to wrap
79	all widgets and objects (e.g., QPushButton). This single
80	interface provides all the metadata necessary for the assistive
81	technologies. Qt provides implementations of this interface for
82	its built-in widgets as plugins.
83
84	When you develop custom widgets, you can create custom subclasses
85	of QAccessibleInterface and distribute them as plugins (using
86	QAccessiblePlugin) or compile them into the application.
87	Likewise, Qt's predefined accessibility support can be built as
88	plugin (the default) or directly into the Qt library. The main
89	advantage of using plugins is that the accessibility classes are
90	only loaded into memory if they are actually used; they don't
91	slow down the common case where no assistive technology is being
92	used.
93
94	Qt also includes two convenience classes, QAccessibleObject and
95	QAccessibleWidget, that inherit from QAccessibleInterface and
96	provide the lowest common denominator of metadata (e.g., widget
97	geometry, window title, basic help text). You can use them as
98	base classes when wrapping your custom QObject or QWidget
99	subclasses.
100
101	\sa QAccessibleInterface
102	*/
103
104
105	/*!
106	\class QAccessible::State
107
108	\inmodule QtGui
109
110	This structure defines bit flags that indicate
111	the state of an accessible object. The values are:
112
113	\value active The object is the active window or the active sub-element in a container (that would get focus when focusing the container).
114	\value adjustable The object represents an adjustable value, e.g. sliders.
115	\value animated The object's appearance changes frequently.
116	\value busy The object cannot accept input at the moment.
117	\value checkable The object is checkable.
118	\value checked The object's check box is checked.
119	\value checkStateMixed The third state of checkboxes (half checked in tri-state check boxes).
120	\value collapsed The object is collapsed, e.g. a closed listview item, or an iconified window.
121	\value defaultButton The object represents the default button in a dialog.
122	\value defunct The object no longer exists.
123	\value editable The object has a text carret (and often implements the text interface).
124	\value expandable The object is expandable, mostly used for cells in a tree view.
125	\value expanded The object is expanded, currently its children are visible.
126	\value extSelectable The object supports extended selection.
127	\value focusable The object can receive focus. Only objects in the active window can receive focus.
128	\value focused The object has keyboard focus.
129	\value hasPopup The object opens a popup.
130	\value hotTracked The object's appearance is sensitive to the mouse cursor position.
131	\value invalid The object is no longer valid (because it has been deleted).
132	\value invisible The object is not visible to the user.
133	\value linked The object is linked to another object, e.g. a hyperlink.
134	\value marqueed The object displays scrolling contents, e.g. a log view.
135	\value modal The object blocks input from other objects.
136	\value movable The object can be moved.
137	\value multiLine The object has multiple lines of text (word wrap), as opposed to a single line.
138	\value multiSelectable The object supports multiple selected items.
139	\value offscreen The object is clipped by the visible area. Objects that are off screen are also invisible.
140	\value passwordEdit The object is a password field, e.g. a line edit for entering a Password.
141	\value playsSound The object produces sound when interacted with.
142	\value pressed The object is pressed.
143	\value readOnly The object can usually be edited, but is explicitly set to read-only.
144	\value searchEdit The object is a line edit that is the input for search queries.
145	\value selectable The object is selectable.
146	\value selectableText The object has text which can be selected. This is different from selectable which refers to the object's children.
147	\value selected The object is selected, this is independent of text selection.
148	\value selfVoicing The object describes itself through speech or sound.
149	\value sizeable The object can be resized, e.g. top-level windows.
150	\value summaryElement The object summarizes the state of the window and should be treated with priority.
151	\value supportsAutoCompletion The object has auto-completion, for example in line edits or combo boxes.
152	\value traversed The object is linked and has been visited.
153	\value updatesFrequently The object changes frequently and needs to be refreshed when accessing it.
154	\value disabled The object is unavailable to the user, e.g. a disabled widget.
155
156	Implementations of QAccessibleInterface::state() return a combination
157	of these flags.
158	*/
159
160	/*!
161	\fn QAccessible::State::State()
162
163	Constructs a new QAccessible::State with all states set to false.
164	*/
165
166	/*!
167	\enum QAccessible::Event
168
169	This enum type defines accessible event types.
170
171	\omitvalue InvalidEvent \omit Internal: Used when creating subclasses of QAccessibleEvent. \endomit
172	\value AcceleratorChanged The keyboard accelerator for an action has been changed.
173	\value ActionChanged An action has been changed.
174	\value ActiveDescendantChanged
175	\value Alert A system alert (e.g., a message from a QMessageBox)
176	\value 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	*/
443	QAccessibleInterface::~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 */
455	Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, acLoader,
456	(QAccessibleFactoryInterface_iid, "/accessible"_L1))
457	typedef QHash<QString, QAccessiblePlugin*> QAccessiblePluginsHash;
458	Q_GLOBAL_STATIC(QAccessiblePluginsHash, qAccessiblePlugins)
459
460	// FIXME turn this into one global static struct
461	Q_GLOBAL_STATIC(QList<QAccessible::InterfaceFactory>, qAccessibleFactories)
462	Q_GLOBAL_STATIC(QList<QAccessible::ActivationObserver *>, qAccessibleActivationObservers)
463
464	QAccessible::UpdateHandler QAccessible::updateHandler = nullptr;
465	QAccessible::RootObjectHandler QAccessible::rootObjectHandler = nullptr;
466
467	static bool cleanupAdded = false;
468
469	static 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	*/
487	void QAccessible::cleanup()
488	{
489	if (QPlatformAccessibility *pfAccessibility = platformAccessibility())
490	pfAccessibility->cleanup();
491	}
492
493	static 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	*/
546	void 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	*/
563	void 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	*/
575	QAccessible::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	*/
588	QAccessible::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
603	QAccessible::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	*/
612	void 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	*/
632	void 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	*/
655	QAccessibleInterface *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	*/
745	QAccessible::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	*/
756	void QAccessible::deleteAccessibleInterface(Id id)
757	{
758	QAccessibleCache::instance()->deleteInterface(id);
759	}
760
761	/*!
762	Returns the unique ID for the QAccessibleInterface \a iface.
763	*/
764	QAccessible::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	*/
777	QAccessibleInterface *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	*/
794	bool QAccessible::isActive()
795	{
796	if (QPlatformAccessibility *pfAccessibility = platformAccessibility())
797	return pfAccessibility->isActive();
798	return false;
799	}
800
801	/*!
802	\internal
803	*/
804	void 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	*/
825	void 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	*/
855	void 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	*/
887	QPair< 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	*/
1095	QList<QPair<QAccessibleInterface*, QAccessible::Relation>>
1096	QAccessibleInterface::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	*/
1107	QAccessibleInterface *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	*/
1246	QColor 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	*/
1256	QColor 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	*/
1333	QAccessibleEvent::~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	*/
1360	QAccessible::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	*/
1412	QAccessibleValueChangeEvent::~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	*/
1455	QAccessibleStateChangeEvent::~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	*/
1534	QAccessibleTableModelChangeEvent::~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	*/
1562	QAccessibleTextCursorEvent::~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	*/
1602	QAccessibleTextInsertEvent::~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	*/
1644	QAccessibleTextRemoveEvent::~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	*/
1705	QAccessibleTextUpdateEvent::~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	*/
1739	QAccessibleTextSelectionEvent::~QAccessibleTextSelectionEvent()
1740	{
1741	}
1742
1743
1744
1745	/*!
1746	Returns the QAccessibleInterface associated with the event.
1747	*/
1748	QAccessibleInterface *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	*/
1781	QWindow *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	*/
1794	void 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 */
1815	const 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 */
1824	const 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 */
1832	Q_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 */
1874	QDebug 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	*/
1957	QAccessibleTextInterface::~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	*/
2028	static 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	*/
2075	QString 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	*/
2149	QString 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	*/
2234	QString 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	*/
2345	QAccessibleEditableTextInterface::~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	*/
2389	QAccessibleValueInterface::~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	*/
2452	QAccessibleImageInterface::~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	*/
2471	QAccessibleTableCellInterface::~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	*/
2539	QAccessibleTableInterface::~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	*/
2715	QAccessibleActionInterface::~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
2783	struct 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
2845	Q_GLOBAL_STATIC(QAccessibleActionStrings, accessibleActionStrings)
2846
2847	QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const
2848	{
2849	return QAccessibleActionInterface::tr(qPrintable(actionName));
2850	}
2851
2852	QString 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	*/
2861	const 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	*/
2870	const 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	*/
2879	const 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	*/
2888	const 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	*/
2897	const 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	*/
2906	const 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	*/
2915	QString 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	*/
2924	QString 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	*/
2933	QString 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	*/
2942	QString 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	*/
2951	QString 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	*/
2960	QString 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	*/
2986	QAccessibleSelectionInterface::~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	*/
3015	QAccessibleInterface* 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	*/
3032	bool 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 */
3074	QString 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
3112	QAccessibleHyperlinkInterface::~QAccessibleHyperlinkInterface()
3113	{
3114
3115	}
3116
3117	#endif // QT_CONFIG(accessibility)
3118
3119	QT_END_NAMESPACE
3120
3121	#include "moc_qaccessible_base.cpp"
3122