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