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

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