qaccessible.cpp

Absolute File Name:

/home/qt/qt5_coco/qt5/qtbase/src/gui/accessible/qaccessible.cpp

Source code

Switch to Preprocessed file

Line Source Count

1 /**************************************************************************** -

2 ** -

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/qmetaobject.h> -

56 #include <QtCore/qhash.h> -

57 #include <private/qfactoryloader_p.h> -

58 -

59 QT_BEGIN_NAMESPACE -

60 -

61 /*! -

62 \class QAccessible -

63 \brief The QAccessible class provides enums and static functions -

64 related to accessibility. -

65 -

66 \ingroup accessibility -

67 \inmodule QtGui -

68 -

69 This class is part of \l {Accessibility for QWidget Applications}. -

70 -

71 Accessible applications can be used by people who are not able to -

72 use applications by conventional means. -

73 -

74 The functions in this class are used for communication between -

75 accessible applications (also called AT Servers) and -

76 accessibility tools (AT Clients), such as screen readers and -

77 braille displays. Clients and servers communicate in the following way: -

78 -

79 \list -

80 \li \e{AT Servers} notify the clients about events through calls to the -

81 updateAccessibility() function. -

82 -

83 \li \e{AT Clients} request information about the objects in the server. -

84 The QAccessibleInterface class is the core interface, and encapsulates -

85 this information in a pure virtual API. Implementations of the interface -

86 are provided by Qt through the queryAccessibleInterface() API. -

87 \endlist -

88 -

89 The communication between servers and clients is initialized by -

90 the setRootObject() function. Function pointers can be installed -

91 to replace or extend the default behavior of the static functions -

92 in QAccessible. -

93 -

94 Qt supports Microsoft Active Accessibility (MSAA), \macos -

95 Accessibility, and the Unix/X11 AT-SPI standard. Other backends -

96 can be supported using QAccessibleBridge. -

97 -

98 In the Unix/X11 AT-SPI implementation, applications become accessible -

99 when two conditions are met: -

100 \list -

101 \li org.a11y.Status.IsEnabled DBus property is true -

102 \li org.a11y.Status.ScreenReaderEnabled DBus property is true -

103 \endlist -

104 An alternative to setting the DBus AT-SPI properties is to set -

105 the QT_LINUX_ACCESSIBILITY_ALWAYS_ON environment variable. -

106 -

107 In addition to QAccessible's static functions, Qt offers one -

108 generic interface, QAccessibleInterface, that can be used to wrap -

109 all widgets and objects (e.g., QPushButton). This single -

110 interface provides all the metadata necessary for the assistive -

111 technologies. Qt provides implementations of this interface for -

112 its built-in widgets as plugins. -

113 -

114 When you develop custom widgets, you can create custom subclasses -

115 of QAccessibleInterface and distribute them as plugins (using -

116 QAccessiblePlugin) or compile them into the application. -

117 Likewise, Qt's predefined accessibility support can be built as -

118 plugin (the default) or directly into the Qt library. The main -

119 advantage of using plugins is that the accessibility classes are -

120 only loaded into memory if they are actually used; they don't -

121 slow down the common case where no assistive technology is being -

122 used. -

123 -

124 Qt also includes two convenience classes, QAccessibleObject and -

125 QAccessibleWidget, that inherit from QAccessibleInterface and -

126 provide the lowest common denominator of metadata (e.g., widget -

127 geometry, window title, basic help text). You can use them as -

128 base classes when wrapping your custom QObject or QWidget -

129 subclasses. -

130 -

131 \sa QAccessibleInterface -

132 */ -

133 -

134 -

135 /*! -

136 \class QAccessible::State -

137 -

138 \inmodule QtGui -

139 -

140 This structure defines bit flags that indicate -

141 the state of an accessible object. The values are: -

142 -

143 \value active The object is the active window or the active sub-element in a container (that would get focus when focusing the container). -

144 \value adjustable The object represents an adjustable value, e.g. sliders. -

145 \value animated The object's appearance changes frequently. -

146 \value busy The object cannot accept input at the moment. -

147 \value checkable The object is checkable. -

148 \value checked The object's check box is checked. -

149 \value checkStateMixed The third state of checkboxes (half checked in tri-state check boxes). -

150 \value collapsed The object is collapsed, e.g. a closed listview item, or an iconified window. -

151 \value defaultButton The object represents the default button in a dialog. -

152 \value defunct The object no longer exists. -

153 \value editable The object has a text carret (and often implements the text interface). -

154 \value expandable The object is expandable, mostly used for cells in a tree view. -

155 \value expanded The object is expanded, currently its children are visible. -

156 \value extSelectable The object supports extended selection. -

157 \value focusable The object can receive focus. Only objects in the active window can receive focus. -

158 \value focused The object has keyboard focus. -

159 \value hasPopup The object opens a popup. -

160 \value hotTracked The object's appearance is sensitive to the mouse cursor position. -

161 \value invalid The object is no longer valid (because it has been deleted). -

162 \value invalidEntry Input validation current input invalid. -

163 \value invisible The object is not visible to the user. -

164 \value linked The object is linked to another object, e.g. a hyperlink. -

165 \value marqueed The object displays scrolling contents, e.g. a log view. -

166 \value modal The object blocks input from other objects. -

167 \value movable The object can be moved. -

168 \value multiLine The object has multiple lines of text (word wrap), as opposed to a single line. -

169 \value multiSelectable The object supports multiple selected items. -

170 \value offscreen The object is clipped by the visible area. Objects that are off screen are also invisible. -

171 \value passwordEdit The object is a password field, e.g. a line edit for entering a Password. -

172 \value playsSound The object produces sound when interacted with. -

173 \value pressed The object is pressed. -

174 \value readOnly The object can usually be edited, but is explicitly set to read-only. -

175 \value searchEdit The object is a line edit that is the input for search queries. -

176 \value selectable The object is selectable. -

177 \value selectableText The object has text which can be selected. This is different from selectable which refers to the object's children. -

178 \value selected The object is selected, this is independent of text selection. -

179 \value selfVoicing The object describes itself through speech or sound. -

180 \value sizeable The object can be resized, e.g. top-level windows. -

181 \value summaryElement The object summarizes the state of the window and should be treated with priority. -

182 \value supportsAutoCompletion The object has auto-completion, for example in line edits or combo boxes. -

183 \value traversed The object is linked and has been visited. -

184 \value updatesFrequently The object changes frequently and needs to be refreshed when accessing it. -

185 \value disabled The object is unavailable to the user, e.g. a disabled widget. -

186 -

187 Implementations of QAccessibleInterface::state() return a combination -

188 of these flags. -

189 */ -

190 -

191 /*! -

192 \fn QAccessible::State::State() -

193 -

194 Constructs a new QAccessible::State with all states set to false. -

195 */ -

196 -

197 /*! -

198 \enum QAccessible::Event -

199 -

200 This enum type defines accessible event types. -

201 -

202 \omitvalue InvalidEvent Internal: Used when creating subclasses of QAccessibleEvent. -

203 \value AcceleratorChanged The keyboard accelerator for an action has been changed. -

204 \value ActionChanged An action has been changed. -

205 \value ActiveDescendantChanged -

206 \value Alert A system alert (e.g., a message from a QMessageBox) -

207 \value AttributeChanged -

208 \value ContextHelpEnd Context help (QWhatsThis) for an object is finished. -

209 \value ContextHelpStart Context help (QWhatsThis) for an object is initiated. -

210 \value DefaultActionChanged The default QAccessible::Action for the accessible -

211 object has changed. -

212 \value DescriptionChanged The object's QAccessible::Description changed. -

213 \value DialogEnd A dialog (QDialog) has been hidden -

214 \value DialogStart A dialog (QDialog) has been set visible. -

215 \value DocumentContentChanged The contents of a text document have changed. -

216 \value DocumentLoadComplete A document has been loaded. -

217 \value DocumentLoadStopped A document load has been stopped. -

218 \value DocumentReload A document reload has been initiated. -

219 \value DragDropEnd A drag and drop operation is about to finished. -

220 \value DragDropStart A drag and drop operation is about to be initiated. -

221 \value Focus An object has gained keyboard focus. -

222 \value ForegroundChanged A window has been activated (i.e., a new window has -

223 gained focus on the desktop). -

224 \value HelpChanged The QAccessible::Help text property of an object has -

225 changed. -

226 \value HyperlinkEndIndexChanged The end position of the display text for a hypertext -

227 link has changed. -

228 \value HyperlinkNumberOfAnchorsChanged The number of anchors in a hypertext link has changed, -

229 perhaps because the display text has been split to -

230 provide more than one link. -

231 \value HyperlinkSelectedLinkChanged The link for the selected hypertext link has changed. -

232 \value HyperlinkStartIndexChanged The start position of the display text for a hypertext -

233 link has changed. -

234 \value HypertextChanged The display text for a hypertext link has changed. -

235 \value HypertextLinkActivated A hypertext link has been activated, perhaps by being -

236 clicked or via a key press. -

237 \value HypertextLinkSelected A hypertext link has been selected. -

238 \value HypertextNLinksChanged -

239 \value LocationChanged An object's location on the screen has changed. -

240 \value MenuCommand A menu item is triggered. -

241 \value MenuEnd A menu has been closed (Qt uses PopupMenuEnd for all -

242 menus). -

243 \value MenuStart A menu has been opened on the menubar (Qt uses -

244 PopupMenuStart for all menus). -

245 \value NameChanged The QAccessible::Name property of an object has changed. -

246 \value ObjectAttributeChanged -

247 \value ObjectCreated A new object is created. -

248 \value ObjectDestroyed An object is deleted. -

249 \value ObjectHide An object is hidden; for example, with QWidget::hide(). -

250 Any children the object that is hidden has do not send -

251 this event. It is not sent when an object is hidden as -

252 it is being obcured by others. -

253 \value ObjectReorder A layout or item view has added, removed, or moved an -

254 object (Qt does not use this event). -

255 \value ObjectShow An object is displayed; for example, with -

256 QWidget::show(). -

257 \value PageChanged -

258 \value ParentChanged An object's parent object changed. -

259 \value PopupMenuEnd A pop-up menu has closed. -

260 \value PopupMenuStart A pop-up menu has opened. -

261 \value ScrollingEnd A scrollbar scroll operation has ended (the mouse has -

262 released the slider handle). -

263 \value ScrollingStart A scrollbar scroll operation is about to start; this may -

264 be caused by a mouse press on the slider handle, for -

265 example. -

266 \value SectionChanged -

267 \value SelectionAdd An item has been added to the selection in an item view. -

268 \value SelectionRemove An item has been removed from an item view selection. -

269 \value Selection The selection has changed in a menu or item view. -

270 \value SelectionWithin Several changes to a selection has occurred in an item -

271 view. -

272 \value SoundPlayed A sound has been played by an object -

273 \omitvalue StateChanged The QAccessible::State of an object has changed. -

274 This value is used internally for the QAccessibleStateChangeEvent. -

275 \value TableCaptionChanged A table caption has been changed. -

276 \value TableColumnDescriptionChanged The description of a table column, typically found in -

277 the column's header, has been changed. -

278 \value TableColumnHeaderChanged A table column header has been changed. -

279 \omitvalue TableModelChanged The model providing data for a table has been changed. -

280 \value TableRowDescriptionChanged The description of a table row, typically found in the -

281 row's header, has been changed. -

282 \value TableRowHeaderChanged A table row header has been changed. -

283 \value TableSummaryChanged The summary of a table has been changed. -

284 \omitvalue TextAttributeChanged -

285 \omitvalue TextCaretMoved The caret has moved in an editable widget. -

286 The caret represents the cursor position in an editable -

287 widget with the input focus. -

288 \value TextColumnChanged A text column has been changed. -

289 \omitvalue TextInserted Text has been inserted into an editable widget. -

290 \omitvalue TextRemoved Text has been removed from an editable widget. -

291 \omitvalue TextSelectionChanged The selected text has changed in an editable widget. -

292 \omitvalue TextUpdated The text has been update in an editable widget. -

293 \omitvalue ValueChanged The QAccessible::Value of an object has changed. -

294 \value VisibleDataChanged -

295 -

296 The values for this enum are defined to be the same as those defined in the -

297 \l{AccessibleEventID.idl File Reference}{IAccessible2} and -

298 \l{Microsoft Active Accessibility Event Constants}{MSAA} specifications. -

299 */ -

300 -

301 /*! -

302 \enum QAccessible::Role -

303 -

304 This enum defines the role of an accessible object. The roles are: -

305 -

306 \value AlertMessage An object that is used to alert the user. -

307 \value Animation An object that displays an animation. -

308 \value Application The application's main window. -

309 \value Assistant An object that provids interactive help. -

310 \value Border An object that represents a border. -

311 \value ButtonDropDown A button that drops down a list of items. -

312 \value ButtonDropGrid A button that drops down a grid. -

313 \value ButtonMenu A button that drops down a menu. -

314 \value Canvas An object that displays graphics that the user can interact with. -

315 \value Caret An object that represents the system caret (text cursor). -

316 \value Cell A cell in a table. -

317 \value Chart An object that displays a graphical representation of data. -

318 \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. -

319 \value Client The client area in a window. -

320 \value Clock A clock displaying time. -

321 \value ColorChooser A dialog that lets the user choose a color. -

322 \value Column A column of cells, usually within a table. -

323 \value ColumnHeader A header for a column of data. -

324 \value ComboBox A list of choices that the user can select from. -

325 \value ComplementaryContent A part of the document or web page that is complementary to the main content, usually a landmark (see WAI-ARIA). -

326 \value Cursor An object that represents the mouse cursor. -

327 \value Desktop The object represents the desktop or workspace. -

328 \value Dial An object that represents a dial or knob. -

329 \value Dialog A dialog box. -

330 \value Document A document, for example in an office application. -

331 \value EditableText Editable text such as a line or text edit. -

332 \value Equation An object that represents a mathematical equation. -

333 \value Footer A footer in a page (usually in documents). -

334 \value Form A web form containing controls. -

335 \value Graphic A graphic or picture, e.g. an icon. -

336 \value Grip A grip that the user can drag to change the size of widgets. -

337 \value Grouping An object that represents a logical grouping of other objects. -

338 \value Heading A heading in a document. -

339 \value HelpBalloon An object that displays help in a separate, short lived window. -

340 \value HotkeyField A hotkey field that allows the user to enter a key sequence. -

341 \value Indicator An indicator that represents a current value or item. -

342 \value LayeredPane An object that can contain layered children, e.g. in a stack. -

343 \value Link A link to something else. -

344 \value List A list of items, from which the user can select one or more items. -

345 \value ListItem An item in a list of items. -

346 \value MenuBar A menu bar from which menus are opened by the user. -

347 \value MenuItem An item in a menu or menu bar. -

348 \value NoRole The object has no role. This usually indicates an invalid object. -

349 \value Note A section whose content is parenthetic or ancillary to the main content of the resource. -

350 \value PageTab A page tab that the user can select to switch to a different page in a dialog. -

351 \value PageTabList A list of page tabs. -

352 \value Paragraph A paragraph of text (usually found in documents). -

353 \value Pane A generic container. -

354 \value PopupMenu A menu which lists options that the user can select to perform an action. -

355 \value ProgressBar The object displays the progress of an operation in progress. -

356 \value PropertyPage A property page where the user can change options and settings. -

357 \value Button A button. -

358 \value RadioButton An object that represents an option that is mutually exclusive with other options. -

359 \value Row A row of cells, usually within a table. -

360 \value RowHeader A header for a row of data. -

361 \value ScrollBar A scroll bar, which allows the user to scroll the visible area. -

362 \value Section A section (in a document). -

363 \value Separator A separator that divides space into logical areas. -

364 \value Slider A slider that allows the user to select a value within a given range. -

365 \value Sound An object that represents a sound. -

366 \value SpinBox A spin box widget that allows the user to enter a value within a given range. -

367 \value Splitter A splitter distributing available space between its child widgets. -

368 \value StaticText Static text, such as labels for other widgets. -

369 \value StatusBar A status bar. -

370 \value Table A table representing data in a grid of rows and columns. -

371 \value Terminal A terminal or command line interface. -

372 \value TitleBar The title bar caption of a window. -

373 \value ToolBar A tool bar, which groups widgets that the user accesses frequently. -

374 \value ToolTip A tool tip which provides information about other objects. -

375 \value Tree A list of items in a tree structure. -

376 \value TreeItem An item in a tree structure. -

377 \value UserRole The first value to be used for user defined roles. -

378 \value WebDocument HTML document, usually in a browser. -

379 \value Whitespace Blank space between other objects. -

380 \value Window A top level window. -

381 */ -

382 -

383 /*! -

384 \enum QAccessible::RelationFlag -

385 -

386 This enum type defines bit flags that can be combined to indicate -

387 the relationship between two accessible objects. -

388 -

389 \value Label The first object is the label of the second object. -

390 \value Labelled The first object is labelled by the second object. -

391 \value Controller The first object controls the second object. -

392 \value Controlled The first object is controlled by the second object. -

393 \value AllRelations Used as a mask to specify that we are interesting in information -

394 about all relations -

395 -

396 Implementations of relations() return a combination of these flags. -

397 Some values are mutually exclusive. -

398 */ -

399 -

400 /*! -

401 \enum QAccessible::Text -

402 -

403 This enum specifies string information that an accessible object -

404 returns. -

405 -

406 \value Name The name of the object. This can be used both -

407 as an identifier or a short description by -

408 accessible clients. -

409 \value Description A short text describing the object. -

410 \value Value The value of the object. -

411 \value Help A longer text giving information about how to use the object. -

412 \value Accelerator The keyboard shortcut that executes the object's default action. -

413 \value UserText The first value to be used for user defined text. -

414 \omitvalue DebugDescription -

415 */ -

416 -

417 /*! \enum QAccessible::TextBoundaryType -

418 This enum describes different types of text boundaries. It follows the IAccessible2 API and is used in the \l QAccessibleTextInterface. -

419 -

420 \value CharBoundary Use individual characters as boundary. -

421 \value WordBoundary Use words as boundaries. -

422 \value SentenceBoundary Use sentences as boundary. -

423 \value ParagraphBoundary Use paragraphs as boundary. -

424 \value LineBoundary Use newlines as boundary. -

425 \value NoBoundary No boundary (use the whole text). -

426 -

427 \sa QAccessibleTextInterface -

428 */ -

429 -

430 -

431 /*! -

432 \enum QAccessible::InterfaceType -

433 -

434 \l QAccessibleInterface supports several sub interfaces. -

435 In order to provide more information about some objects, their accessible -

436 representation should implement one or more of these interfaces. -

437 -

438 \note When subclassing one of these interfaces, \l QAccessibleInterface::interface_cast() needs to be implemented. -

439 -

440 \value TextInterface For text that supports selections or is more than one line. Simple labels do not need to implement this interface. -

441 \omitvalue EditableTextInterface For text that can be edited by the user. -

442 \value ValueInterface For objects that are used to manipulate a value, for example slider or scroll bar. -

443 \value ActionInterface For interactive objects that allow the user to trigger an action. Basically everything that allows for example mouse interaction. -

444 \omitvalue ImageInterface For objects that represent an image. This interface is generally less important. -

445 \value TableInterface For lists, tables and trees. -

446 \value TableCellInterface For cells in a TableInterface object. -

447 -

448 \sa QAccessibleInterface::interface_cast(), QAccessibleTextInterface, QAccessibleValueInterface, QAccessibleActionInterface, QAccessibleTableInterface, QAccessibleTableCellInterface -

449 */ -

450 -

451 #ifndef QT_NO_ACCESSIBILITY -

452 -

453 /*! -

454 Destroys the QAccessibleInterface. -

455 */ -

456 QAccessibleInterface::~QAccessibleInterface() -

457 { -

458 } -

459 -

460 /*! -

461 \typedef QAccessible::Id -

462 -

463 Synonym for unsigned, used by the QAccessibleInterface cache. -

464 */ -

465 -

466 -

#ifndef QT_NO_ACCESSIBILITY/* accessible widgets plugin discovery stuff */

#ifndef QT_NO_LIBRARYQ_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader,

469 (QAccessibleFactoryInterface_iid, QLatin1String("/accessible"))) -

470 typedef QHash<QString, QAccessiblePlugin*> QAccessiblePluginsHash; -

471 Q_GLOBAL_STATIC(QAccessiblePluginsHash, qAccessiblePlugins) -

472 -

#endif// FIXME turn this into one global static struct

474 Q_GLOBAL_STATIC(QList<QAccessible::InterfaceFactory>, qAccessibleFactories) -

475 Q_GLOBAL_STATIC(QList<QAccessible::ActivationObserver *>, qAccessibleActivationObservers) -

476 -

477 QAccessible::UpdateHandler QAccessible::updateHandler = 0; -

478 QAccessible::RootObjectHandler QAccessible::rootObjectHandler = 0; -

479 -

480 static bool cleanupAdded = false; -

481 -

482 static QPlatformAccessibility *platformAccessibility() -

483 { -

484 QPlatformIntegration *pfIntegration = QGuiApplicationPrivate::platformIntegration(); -

485 return pfIntegration ? pfIntegration->accessibility() : 0; -

486 } -

487 -

488 /*! -

489 \fn QAccessible::QAccessible() -

490 \internal -

491 -

492 This class is purely a collection of enums and static functions, -

493 it is not supposed to be instantiated. -

494 */ -

495 -

496 -

497 /*! -

498 \internal -

499 */ -

500 void QAccessible::cleanup() -

501 { -

502 if (QPlatformAccessibility *pfAccessibility = platformAccessibility()) -

503 pfAccessibility->cleanup(); -

504 } -

505 -

506 static void qAccessibleCleanup() -

507 { -

508 qAccessibleActivationObservers()->clear(); -

509 qAccessibleFactories()->clear(); -

510 } -

511 -

512 /*! -

513 \typedef QAccessible::InterfaceFactory -

514 -

515 This is a typedef for a pointer to a function with the following -

516 signature: -

517 -

518 \snippet code/src_gui_accessible_qaccessible.cpp 1 -

519 -

520 The function receives a QString and a QObject pointer, where the -

521 QString is the key identifying the interface. The QObject is used -

522 to pass on to the QAccessibleInterface so that it can hold a reference -

523 to it. -

524 -

525 If the key and the QObject does not have a corresponding -

526 QAccessibleInterface, a null-pointer will be returned. -

527 -

528 Installed factories are called by queryAccessibilityInterface() until -

529 one provides an interface. -

530 */ -

531 -

532 /*! -

533 \typedef QAccessible::UpdateHandler -

534 -

535 \internal -

536 -

537 A function pointer type. Use a function with this prototype to install -

538 your own update function. -

539 -

540 The function is called by updateAccessibility(). -

541 */ -

542 -

543 /*! -

544 \typedef QAccessible::RootObjectHandler -

545 -

546 \internal -

547 -

548 A function pointer type. Use a function with this prototype to install -

549 your own root object handler. -

550 -

551 The function is called by setRootObject(). -

552 */ -

553 -

554 -

555 /*! -

556 Installs the InterfaceFactory \a factory. The last factory added -

557 is the first one used by queryAccessibleInterface(). -

558 */ -

559 void QAccessible::installFactory(InterfaceFactory factory) -

560 { -

561 if (!factory) -

562 return; -

563 -

564 if (!cleanupAdded) { -

565 qAddPostRoutine(qAccessibleCleanup); -

566 cleanupAdded = true; -

567 } -

568 if (qAccessibleFactories()->contains(factory)) -

569 return; -

570 qAccessibleFactories()->append(factory); -

571 } -

572 -

573 /*! -

574 Removes \a factory from the list of installed InterfaceFactories. -

575 */ -

576 void QAccessible::removeFactory(InterfaceFactory factory) -

577 { -

578 qAccessibleFactories()->removeAll(factory); -

579 } -

580 -

581 /*! -

582 \internal -

583 -

584 Installs the given \a handler as the function to be used by -

585 updateAccessibility(), and returns the previously installed -

586 handler. -

587 */ -

588 QAccessible::UpdateHandler QAccessible::installUpdateHandler(UpdateHandler handler) -

589 { -

590 UpdateHandler old = updateHandler; -

591 updateHandler = handler; -

592 return old; -

593 } -

594 -

595 /*! -

596 \internal -

597 -

598 Installs the given \a handler as the function to be used by setRootObject(), -

599 and returns the previously installed handler. -

600 */ -

601 QAccessible::RootObjectHandler QAccessible::installRootObjectHandler(RootObjectHandler handler) -

602 { -

603 RootObjectHandler old = rootObjectHandler; -

604 rootObjectHandler = handler; -

605 return old; -

606 } -

607 -

608 /*! -

609 \class QAccessible::ActivationObserver -

610 \internal -

611 -

612 Interface to listen to activation or deactivation of the accessibility framework. -

613 \sa installActivationObserver() -

614 */ -

615 -

616 QAccessible::ActivationObserver::~ActivationObserver() -

617 { -

618 // must be empty until ### Qt 6 -

619 } -

620 -

621 /*! -

622 \internal -

623 -

624 Install \a observer to get notified of activation or deactivation (global accessibility has been enabled or disabled). -

625 */ -

626 void QAccessible::installActivationObserver(QAccessible::ActivationObserver *observer) -

627 { -

628 if (!observer) -

629 return; -

630 -

631 if (!cleanupAdded) { -

632 qAddPostRoutine(qAccessibleCleanup); -

633 cleanupAdded = true; -

634 } -

635 if (qAccessibleActivationObservers()->contains(observer)) -

636 return; -

637 qAccessibleActivationObservers()->append(observer); -

638 } -

639 -

640 /*! -

641 \internal -

642 -

643 Remove an \a observer to no longer get notified of state changes. -

644 \sa installActivationObserver() -

645 */ -

646 void QAccessible::removeActivationObserver(ActivationObserver *observer) -

647 { -

648 qAccessibleActivationObservers()->removeAll(observer); -

649 } -

650 -

651 /*! -

652 If a QAccessibleInterface implementation exists for the given \a object, -

653 this function returns a pointer to the implementation; otherwise it -

654 returns 0. -

655 -

656 The function calls all installed factory functions (from most -

657 recently installed to least recently installed) until one is found -

658 that provides an interface for the class of \a object. If no -

659 factory can provide an accessibility implementation for the class -

660 the function loads installed accessibility plugins, and tests if -

661 any of the plugins can provide the implementation. -

662 -

663 If no implementation for the object's class is available, the -

664 function tries to find an implementation for the object's parent -

665 class, using the above strategy. -

666 -

667 All interfaces are managed by an internal cache and should not be deleted. -

668 */ -

669 QAccessibleInterface *QAccessible::queryAccessibleInterface(QObject *object) -

670 { -

671

if (!object)

!object	Description
TRUE	never evaluated
FALSE	never evaluated

672

return 0;

never executed: return 0;

673 -

674

if (Id id = QAccessibleCache::instance()->objectToId.value(object))

Id id = QAcces....value(object)	Description
TRUE	never evaluated
FALSE	never evaluated

675

return QAccessibleCache::instance()->interfaceForId(id);

never executed: return QAccessibleCache::instance()->interfaceForId(id);

676 -

677 // Create a QAccessibleInterface for the object class. Start by the most -

678 // derived class and walk up the class hierarchy. -

679 const QMetaObject *mo = object->metaObject(); -

680

while (mo) {

mo	Description
TRUE	never evaluated
FALSE	never evaluated

681 const QString cn = QLatin1String(mo->className()); -

682 -

683 // Check if the class has a InterfaceFactory installed. -

684

for (int i = qAccessibleFactories()->count(); i > 0; --i) {

i > 0	Description
TRUE	never evaluated
FALSE	never evaluated

685 InterfaceFactory factory = qAccessibleFactories()->at(i - 1); -

686

if (QAccessibleInterface *iface = factory(cn, object)) {

QAccessibleInt...ry(cn, object)	Description
TRUE	never evaluated
FALSE	never evaluated

687 QAccessibleCache::instance()->insert(object, iface); -

688 Q_ASSERT(QAccessibleCache::instance()->objectToId.contains(object)); -

689

return iface;

never executed: return iface;

690 } -

691

}

never executed: end of block

692 #ifndef QT_NO_LIBRARY// Find a QAccessiblePlugin (factory) for the class name. If there's -

693 // no entry in the cache try to create it using the plugin loader. -

694

if (!qAccessiblePlugins()->contains(cn)) {

!qAccessiblePl...->contains(cn)	Description
TRUE	never evaluated
FALSE	never evaluated

695 QAccessiblePlugin *factory = 0; // 0 means "no plugin found". This is cached as well. -

696 const int index = loader()->indexOf(cn); -

697

if (index != -1)

index != -1	Description
TRUE	never evaluated
FALSE	never evaluated

698

factory = qobject_cast<QAccessiblePlugin *>(loader()->instance(index));

never executed: factory = qobject_cast<QAccessiblePlugin *>(loader()->instance(index));

699 qAccessiblePlugins()->insert(cn, factory); -

700

}

never executed: end of block

701 -

702 // At this point the cache should contain a valid factory pointer or 0: -

703 Q_ASSERT(qAccessiblePlugins()->contains(cn)); -

704 QAccessiblePlugin *factory = qAccessiblePlugins()->value(cn); -

705

if (factory) {

factory	Description
TRUE	never evaluated
FALSE	never evaluated

706 QAccessibleInterface *result = factory->create(cn, object); -

707

if (result) { // Need this condition because of QDesktopScreenWidget

result	Description
TRUE	never evaluated
FALSE	never evaluated

708 QAccessibleCache::instance()->insert(object, result); -

709 Q_ASSERT(QAccessibleCache::instance()->objectToId.contains(object)); -

710

}

never executed: end of block

711

return result;

never executed: return result;

712 }#endif -

713 mo = mo->superClass(); -

714

}

never executed: end of block

715 -

716

if (object == qApp) {

object == (sta...::instance()))	Description
TRUE	never evaluated
FALSE	never evaluated

717 QAccessibleInterface *appInterface = new QAccessibleApplication; -

718 QAccessibleCache::instance()->insert(object, appInterface); -

719 Q_ASSERT(QAccessibleCache::instance()->objectToId.contains(qApp)); -

720

return appInterface;

never executed: return appInterface;

721 } -

722 -

723

return 0;

never executed: return 0;

724 } -

725 -

726 /*! -

727 \brief Call this function to ensure that manually created interfaces -

728 are properly memory managed. -

729 -

730 Must only be called exactly once per interface \a iface. -

731 This is implicitly called when calling queryAccessibleInterface, -

732 calling this function is only required when QAccessibleInterfaces -

733 are instantiated with the "new" operator. This is not recommended, -

734 whenever possible use the default functions and let \l queryAccessibleInterface() -

735 take care of this. -

736 -

737 When it is necessary to reimplement the QAccessibleInterface::child() function -

738 and returning the child after constructing it, this function needs to be called. -

739 */ -

740 QAccessible::Id QAccessible::registerAccessibleInterface(QAccessibleInterface *iface) -

741 { -

742 Q_ASSERT(iface); -

743 return QAccessibleCache::instance()->insert(iface->object(), iface); -

744 } -

745 -

746 /*! -

747 Removes the interface belonging to this \a id from the cache and -

748 deletes it. The id becomes invalid an may be re-used by the -

749 cache. -

750 */ -

751 void QAccessible::deleteAccessibleInterface(Id id) -

752 { -

753 QAccessibleCache::instance()->deleteInterface(id); -

754 } -

755 -

756 /*! -

757 Returns the unique ID for the QAccessibleInterface \a iface. -

758 */ -

759 QAccessible::Id QAccessible::uniqueId(QAccessibleInterface *iface) -

760 { -

761 Id id = QAccessibleCache::instance()->idForInterface(iface); -

762 if (!id) -

763 id = registerAccessibleInterface(iface); -

764 return id; -

765 } -

766 -

767 /*! -

768 Returns the QAccessibleInterface belonging to the \a id. -

769 -

770 Returns 0 if the id is invalid. -

771 */ -

772 QAccessibleInterface *QAccessible::accessibleInterface(Id id) -

773 { -

774 return QAccessibleCache::instance()->interfaceForId(id); -

775 } -

776 -

777 -

778 /*! -

779 Returns \c true if the platform requested accessibility information. -

780 -

781 This function will return false until a tool such as a screen reader -

782 accessed the accessibility framework. It is still possible to use -

783 \l QAccessible::queryAccessibleInterface() even if accessibility is not -

784 active. But there will be no notifications sent to the platform. -

785 -

786 It is recommended to use this function to prevent expensive notifications -

787 via updateAccessibility() when they are not needed. -

788 */ -

789 bool QAccessible::isActive() -

790 { -

791 if (QPlatformAccessibility *pfAccessibility = platformAccessibility()) -

792 return pfAccessibility->isActive(); -

793 return false; -

794 } -

795 -

796 /*! -

797 \internal -

798 */ -

799 void QAccessible::setActive(bool active) -

800 { -

801 for (int i = 0; i < qAccessibleActivationObservers()->count() ;++i) -

802 qAccessibleActivationObservers()->at(i)->accessibilityActiveChanged(active); -

803 } -

804 -

805 -

806 /*! -

807 Sets the root object of the accessible objects of this application -

808 to \a object. All other accessible objects are reachable using object -

809 navigation from the root object. -

810 -

811 Normally, it isn't necessary to call this function, because Qt sets -

812 the QApplication object as the root object immediately before the -

813 event loop is entered in QApplication::exec(). -

814 -

815 Use QAccessible::installRootObjectHandler() to redirect the function -

816 call to a customized handler function. -

817 -

818 \sa queryAccessibleInterface() -

819 */ -

820 void QAccessible::setRootObject(QObject *object) -

821 { -

822 if (rootObjectHandler) { -

823 rootObjectHandler(object); -

824 return; -

825 } -

826 -

827 if (QPlatformAccessibility *pfAccessibility = platformAccessibility()) -

828 pfAccessibility->setRootObject(object); -

829 } -

830 -

831 /*! -

832 Notifies about a change that might be relevant for accessibility clients. -

833 -

834 \a event provides details about the change. These include the source -

835 of the change and the nature of the change. The \a event should -

836 contain enough information give meaningful notifications. -

837 -

838 For example, the type \c ValueChange indicates that the position of -

839 a slider has been changed. -

840 -

841 Call this function whenever the state of your accessible object or -

842 one of its sub-elements has been changed either programmatically -

843 (e.g. by calling QLabel::setText()) or by user interaction. -

844 -

845 If there are no accessibility tools listening to this event, the -

846 performance penalty for calling this function is small, but if -

847 determining the parameters of the call is expensive you can test -

848 QAccessible::isActive() to avoid unnecessary computation. -

849 */ -

850 void QAccessible::updateAccessibility(QAccessibleEvent *event) -

851 { -

852 // NOTE: Querying for the accessibleInterface below will result in -

853 // resolving and caching the interface, which in some cases will -

854 // cache the wrong information as updateAccessibility is called -

855 // during construction of widgets. If you see cases where the -

856 // cache seems wrong, this call is "to blame", but the code that -

857 // caches dynamic data should be updated to handle change events. -

858 QAccessibleInterface *iface = event->accessibleInterface(); -

859 if (isActive() && iface) { -

860 if (event->type() == QAccessible::TableModelChanged) { -

861 if (iface->tableInterface()) -

862 iface->tableInterface()->modelChange(static_cast<QAccessibleTableModelChangeEvent*>(event)); -

863 } -

864 -

865 if (updateHandler) { -

866 updateHandler(event); -

867 return; -

868 } -

869 } -

870 -

871 if (QPlatformAccessibility *pfAccessibility = platformAccessibility()) -

872 pfAccessibility->notifyAccessibilityUpdate(event); -

873 } -

874 -

875 #if QT_DEPRECATED_SINCE(5, 0) -

876 /*! -

877 \obsolete -

878 \fn void QAccessible::updateAccessibility(QObject *object, int child, Event reason); -

879 -

880 \brief Use QAccessible::updateAccessibility(QAccessibleEvent*) instead. -

881 */ -

882 #endif -

883 -

884 /*! -

885 \internal -

886 \brief getBoundaries is a helper function to find the accessible text boundaries for QTextCursor based documents. -

887 \param documentCursor a valid cursor bound to the document (not null). It needs to ba at the position to look for the boundary -

888 \param boundaryType the type of boundary to find -

889 \return the boundaries as pair -

890 */ -

891 QPair< int, int > QAccessible::qAccessibleTextBoundaryHelper(const QTextCursor &offsetCursor, TextBoundaryType boundaryType) -

892 { -

893 Q_ASSERT(!offsetCursor.isNull()); -

894 -

895 QTextCursor endCursor = offsetCursor; -

896 endCursor.movePosition(QTextCursor::End); -

897 int characterCount = endCursor.position(); -

898 -

899 QPair<int, int> result; -

900 QTextCursor cursor = offsetCursor; -

901 switch (boundaryType) { -

902 case CharBoundary: -

903 result.first = cursor.position(); -

904 cursor.movePosition(QTextCursor::NextCharacter, QTextCursor::KeepAnchor); -

905 result.second = cursor.position(); -

906 break; -

907 case WordBoundary: -

908 cursor.movePosition(QTextCursor::StartOfWord, QTextCursor::MoveAnchor); -

909 result.first = cursor.position(); -

910 cursor.movePosition(QTextCursor::EndOfWord, QTextCursor::KeepAnchor); -

911 result.second = cursor.position(); -

912 break; -

913 case SentenceBoundary: { -

914 // QCursor does not provide functionality to move to next sentence. -

915 // We therefore find the current block, then go through the block using -

916 // QTextBoundaryFinder and find the sentence the \offset represents -

917 cursor.movePosition(QTextCursor::StartOfBlock, QTextCursor::MoveAnchor); -

918 result.first = cursor.position(); -

919 cursor.movePosition(QTextCursor::EndOfBlock, QTextCursor::KeepAnchor); -

920 result.second = cursor.position(); -

921 QString blockText = cursor.selectedText(); -

922 const int offsetWithinBlockText = offsetCursor.position() - result.first; -

923 QTextBoundaryFinder sentenceFinder(QTextBoundaryFinder::Sentence, blockText); -

924 sentenceFinder.setPosition(offsetWithinBlockText); -

925 int prevBoundary = offsetWithinBlockText; -

926 int nextBoundary = offsetWithinBlockText; -

927 if (!(sentenceFinder.boundaryReasons() & QTextBoundaryFinder::StartOfItem)) -

928 prevBoundary = sentenceFinder.toPreviousBoundary(); -

929 nextBoundary = sentenceFinder.toNextBoundary(); -

930 if (nextBoundary != -1) -

931 result.second = result.first + nextBoundary; -

932 if (prevBoundary != -1) -

933 result.first += prevBoundary; -

934 break; } -

935 case LineBoundary: -

936 cursor.movePosition(QTextCursor::StartOfLine, QTextCursor::MoveAnchor); -

937 result.first = cursor.position(); -

938 cursor.movePosition(QTextCursor::EndOfLine, QTextCursor::KeepAnchor); -

939 result.second = cursor.position(); -

940 break; -

941 case ParagraphBoundary: -

942 cursor.movePosition(QTextCursor::StartOfBlock, QTextCursor::MoveAnchor); -

943 result.first = cursor.position(); -

944 cursor.movePosition(QTextCursor::EndOfBlock, QTextCursor::KeepAnchor); -

945 result.second = cursor.position(); -

946 break; -

947 case NoBoundary: -

948 result.first = 0; -

949 result.second = characterCount; -

950 break; -

951 } -

952 return result; -

953 } -

954 -

955 /*! -

956 \class QAccessibleInterface -

957 \brief The QAccessibleInterface class defines an interface that exposes information -

958 about accessible objects. -

959 -

960 \ingroup accessibility -

961 \inmodule QtGui -

962 -

963 This class is part of \l {Accessibility for QWidget Applications}. -

964 -

965 Accessibility tools (also called AT Clients), such as screen readers -

966 or braille displays, require high-level information about -

967 accessible objects in an application. Accessible objects provide -

968 specialized input and output methods, making it possible for users -

969 to use accessibility tools with enabled applications (AT Servers). -

970 -

971 Every element that the user needs to interact with or react to is -

972 an accessible object, and should provide this information. These -

973 are mainly visual objects, such as widgets and widget elements, but -

974 can also be content, such as sounds. -

975 -

976 The AT client uses three basic concepts to acquire information -

977 about any accessible object in an application: -

978 \list -

979 \li \e Properties The client can read information about -

980 accessible objects. In some cases the client can also modify these -

981 properties; such as text in a line edit. -

982 \li \e Actions The client can invoke actions like pressing a button -

983 or . -

984 \li \e{Relationships and Navigation} The client can traverse from one -

985 accessible object to another, using the relationships between objects. -

986 \endlist -

987 -

988 The QAccessibleInterface defines the API for these three concepts. -

989 -

990 \section1 Relationships and Navigation -

991 -

992 The functions childCount() and indexOfChild() return the number of -

993 children of an accessible object and the index a child object has -

994 in its parent. The childAt() function returns a child QAccessibleInterface -

995 that is found at a position. The child does not have to be a direct -

996 child. This allows bypassing intermediate layers when the parent already knows the -

997 top-most child. childAt() is used for hit testing (finding the object -

998 under the mouse). -

999 -

1000 The relations() function provides information about the relations an -

1001 object has to other objects, and parent() and child() allows -

1002 traversing from one object to another object. -

1003 -

1004 \section1 Properties -

1005 -

1006 The central property of an accessible objects is what role() it -

1007 has. Different objects can have the same role, e.g. both the "Add -

1008 line" element in a scroll bar and the \c OK button in a dialog have -

1009 the same role, "button". The role implies what kind of -

1010 interaction the user can perform with the user interface element. -

1011 -

1012 An object's state() property is a combination of different state -

1013 flags and can describe both how the object's state differs from a -

1014 "normal" state, e.g. it might be unavailable, and also how it -

1015 behaves, e.g. it might be selectable. -

1016 -

1017 The text() property provides textual information about the object. -

1018 An object usually has a name, but can provide extended information -

1019 such as a description, help text, or information about any -

1020 keyboard accelerators it provides. Some objects allow changing the -

1021 text() property through the setText() function, but this -

1022 information is in most cases read-only. -

1023 -

1024 The rect() property provides information about the geometry of an -

1025 accessible object. This information is usually only available for -

1026 visual objects. -

1027 -

1028 \section1 Interfaces -

1029 -

1030 To enable the user to interact with an accessible object the -

1031 object must implement QAccessibleActionInterface in addition to -

1032 QAccessibleInterface. -

1033 Objects that support selections can define actions to change the selection. -

1034 -

1035 There are several other interfaces that should be implemented as required. -

1036 QAccessibleTextInterface should be used for bigger texts edits such as document views. -

1037 This interface should not be implemented for labels/single line edits. -

1038 -

1039 For sliders, scrollbars and other numerical value selectors QAccessibleValueInterface -

1040 should be implemented. -

1041 -

1042 Lists, tables and trees should implement QAccessibleTableInterface. -

1043 -

1044 \sa QAccessible, QAccessibleActionInterface, QAccessibleTextInterface, QAccessibleValueInterface, QAccessibleTableInterface -

1045 */ -

1046 -

1047 /*! -

1048 \fn bool QAccessibleInterface::isValid() const -

1049 -

1050 Returns \c true if all the data necessary to use this interface -

1051 implementation is valid (e.g. all pointers are non-null); -

1052 otherwise returns \c false. -

1053 -

1054 \sa object() -

1055 */ -

1056 -

1057 /*! -

1058 \fn QObject *QAccessibleInterface::object() const -

1059 -

1060 Returns a pointer to the QObject this interface implementation provides -

1061 information for. -

1062 -

1063 \sa isValid() -

1064 */ -

1065 -

1066 /*! -

1067 \fn int QAccessibleInterface::childCount() const -

1068 -

1069 Returns the number of children that belong to this object. A child -

1070 can provide accessibility information on its own (e.g. a child -

1071 widget), or be a sub-element of this accessible object. -

1072 -

1073 All objects provide this information. -

1074 -

1075 \sa indexOfChild() -

1076 */ -

1077 -

1078 /*! -

1079 \fn int QAccessibleInterface::indexOfChild(const QAccessibleInterface *child) const -

1080 -

1081 Returns the 0-based index of the object \a child in this object's -

1082 children list, or -1 if \a child is not a child of this object. -

1083 -

1084 All objects provide this information about their children. -

1085 -

1086 \sa childCount() -

1087 */ -

1088 -

1089 /*! -

1090 Returns the meaningful relations to other widgets. Usually this will not return parent/child -

1091 relations, unless they are handled in a specific way such as in tree views. -

1092 It will typically return the labelled-by and label relations. -

1093 -

1094 It is possible to filter the relations by using \a match. -

1095 It should never return itself. -

1096 -

1097 \sa parent(), child() -

1098 */ -

1099 QVector<QPair<QAccessibleInterface*, QAccessible::Relation> > -

1100 QAccessibleInterface::relations(QAccessible::Relation /*match = QAccessible::AllRelations*/) const -

1101 { -

1102 return QVector<QPair<QAccessibleInterface*, QAccessible::Relation> >(); -

1103 } -

1104 -

1105 /*! -

1106 Returns the object that has the keyboard focus. -

1107 -

1108 The object returned can be any descendant, including itself. -

1109 */ -

1110 QAccessibleInterface *QAccessibleInterface::focusChild() const -

1111 { -

1112 return 0; -

1113 } -

1114 -

1115 /*! -

1116 \fn QAccessibleInterface *QAccessibleInterface::childAt(int x, int y) const -

1117 -

1118 Returns the QAccessibleInterface of a child that contains the screen coordinates (\a x, \a y). -

1119 If there are no children at this position this function returns 0. -

1120 The returned accessible must be a child, but not necessarily a direct child. -

1121 -

1122 This function is only relyable for visible objects (invisible -

1123 object might not be laid out correctly). -

1124 -

1125 All visual objects provide this information. -

1126 -

1127 A default implementation is provided for objects inheriting QAccessibleObject. This will iterate -

1128 over all children. If the widget manages its children (e.g. a table) it will be more efficient -

1129 to write a specialized implementation. -

1130 -

1131 \sa rect() -

1132 */ -

1133 -

1134 /*! -

1135 \fn QAccessibleInterface* QAccessibleInterface::parent() const -

1136 -

1137 Returns the QAccessibleInterface of the parent in the accessible object hierarchy. -

1138 -

1139 Returns 0 if no parent exists (e.g. for the top level application object). -

1140 -

1141 \sa child() -

1142 */ -

1143 -

1144 /*! -

1145 \fn QAccessibleInterface* QAccessibleInterface::child(int index) const -

1146 -

1147 Returns the accessible child with index \a index. -

1148 0-based index. The number of children of an object can be checked with childCount. -

1149 -

1150 Returns 0 when asking for an invalid child (e.g. when the child became invalid in the meantime). -

1151 -

1152 \sa childCount(), parent() -

1153 */ -

1154 -

1155 /*! -

1156 \fn QString QAccessibleInterface::text(QAccessible::Text t) const -

1157 -

1158 Returns the value of the text property \a t of the object. -

1159 -

1160 The \l QAccessible::Name is a string used by clients to identify, find, or -

1161 announce an accessible object for the user. All objects must have -

1162 a name that is unique within their container. The name can be -

1163 used differently by clients, so the name should both give a -

1164 short description of the object and be unique. -

1165 -

1166 An accessible object's \l QAccessible::Description provides textual information -

1167 about an object's visual appearance. The description is primarily -

1168 used to provide greater context for vision-impaired users, but is -

1169 also used for context searching or other applications. Not all -

1170 objects have a description. An "OK" button would not need a -

1171 description, but a tool button that shows a picture of a smiley -

1172 would. -

1173 -

1174 The \l QAccessible::Value of an accessible object represents visual information -

1175 contained by the object, e.g. the text in a line edit. Usually, -

1176 the value can be modified by the user. Not all objects have a -

1177 value, e.g. static text labels don't, and some objects have a -

1178 state that already is the value, e.g. toggle buttons. -

1179 -

1180 The \l QAccessible::Help text provides information about the function and -

1181 usage of an accessible object. Not all objects provide this -

1182 information. -

1183 -

1184 The \l QAccessible::Accelerator is a keyboard shortcut that activates the -

1185 object's default action. A keyboard shortcut is the underlined -

1186 character in the text of a menu, menu item or widget, and is -

1187 either the character itself, or a combination of this character -

1188 and a modifier key like Alt, Ctrl or Shift. Command controls like -

1189 tool buttons also have shortcut keys and usually display them in -

1190 their tooltip. -

1191 -

1192 All objects provide a string for \l QAccessible::Name. -

1193 -

1194 \sa role(), state() -

1195 */ -

1196 -

1197 /*! -

1198 \fn void QAccessibleInterface::setText(QAccessible::Text t, const QString &text) -

1199 -

1200 Sets the text property \a t of the object to \a text. -

1201 -

1202 Note that the text properties of most objects are read-only -

1203 so calling this function might have no effect. -

1204 -

1205 \sa text() -

1206 */ -

1207 -

1208 /*! -

1209 \fn QRect QAccessibleInterface::rect() const -

1210 -

1211 Returns the geometry of the object. The geometry is in screen coordinates. -

1212 -

1213 This function is only reliable for visible objects (invisible -

1214 objects might not be laid out correctly). -

1215 -

1216 All visual objects provide this information. -

1217 -

1218 \sa childAt() -

1219 */ -

1220 -

1221 /*! -

1222 \fn QAccessible::Role QAccessibleInterface::role() const -

1223 -

1224 Returns the role of the object. -

1225 The role of an object is usually static. -

1226 -

1227 All accessible objects have a role. -

1228 -

1229 \sa text(), state() -

1230 */ -

1231 -

1232 /*! -

1233 \fn QAccessible::State QAccessibleInterface::state() const -

1234 -

1235 Returns the current state of the object. -

1236 The returned value is a combination of the flags in -

1237 the QAccessible::StateFlag enumeration. -

1238 -

1239 All accessible objects have a state. -

1240 -

1241 \sa text(), role() -

1242 */ -

1243 -

1244 /*! -

1245 Returns the accessible's foreground color if applicable or an invalid QColor. -

1246 -

1247 \sa backgroundColor() -

1248 */ -

1249 QColor QAccessibleInterface::foregroundColor() const -

1250 { -

1251 return QColor(); -

1252 } -

1253 -

1254 /*! -

1255 Returns the accessible's background color if applicable or an invalid QColor. -

1256 -

1257 \sa foregroundColor() -

1258 */ -

1259 QColor QAccessibleInterface::backgroundColor() const -

1260 { -

1261 return QColor(); -

1262 } -

1263 -

1264 /*! -

1265 \fn QAccessibleTextInterface *QAccessibleInterface::textInterface() -

1266 */ -

1267 -

1268 /*! -

1269 \fn QAccessibleTextInterface *QAccessibleInterface::editableTextInterface() -

1270 \internal -

1271 */ -

1272 -

1273 /*! -

1274 \fn QAccessibleValueInterface *QAccessibleInterface::valueInterface() -

1275 */ -

1276 -

1277 /*! -

1278 \fn QAccessibleTableInterface *QAccessibleInterface::tableInterface() -

1279 */ -

1280 -

1281 /*! -

1282 \fn QAccessibleTableCellInterface *QAccessibleInterface::tableCellInterface() -

1283 */ -

1284 -

1285 /*! -

1286 \fn QAccessibleActionInterface *QAccessibleInterface::actionInterface() -

1287 */ -

1288 -

1289 /*! -

1290 \fn QAccessibleImageInterface *QAccessibleInterface::imageInterface() -

1291 \internal -

1292 */ -

1293 -

1294 /*! -

1295 \class QAccessibleEvent -

1296 \ingroup accessibility -

1297 \inmodule QtGui -

1298 -

1299 \brief The QAccessibleEvent class is the base class for accessibility notifications. -

1300 -

1301 This class is used with \l QAccessible::updateAccessibility(). -

1302 -

1303 The event type is one of the values of \l QAccessible::Event. -

1304 There are a number of subclasses that should be used to provide more details about the -

1305 event. -

1306 -

1307 For example to notify about a focus change when re-implementing QWidget::setFocus, -

1308 the event could be used as follows: -

1309 \code -

1310 void MyWidget::setFocus(Qt::FocusReason reason) -

1311 { -

1312 // handle custom focus setting... -

1313 QAccessibleEvent event(f, QAccessible::Focus); -

1314 QAccessible::updateAccessibility(&event); -

1315 } -

1316 \endcode -

1317 -

1318 To enable in process screen readers, all events must be sent after the change has happened. -

1319 */ -

1320 -

1321 /*! \fn QAccessibleEvent::QAccessibleEvent(QObject *object, QAccessible::Event type) -

1322 -

1323 Constructs a QAccessibleEvent to notify that \a object has changed. -

1324 The event \a type describes what changed. -

1325 */ -

1326 -

1327 /*! \fn QAccessibleEvent::QAccessibleEvent(QAccessibleInterface *interface, QAccessible::Event type) -

1328 -

1329 Constructs a QAccessibleEvent to notify that \a interface has changed. -

1330 The event \a type describes what changed. -

1331 Use this function if you already have a QAccessibleInterface or no QObject, otherwise consider -

1332 the overload taking a \l QObject parameter as it might be cheaper. -

1333 */ -

1334 -

1335 /*! -

1336 Destroys the event. -

1337 */ -

1338 QAccessibleEvent::~QAccessibleEvent() -

1339 { -

1340 // must be empty until ### Qt 6 -

1341 } -

1342 -

1343 /*! \fn QAccessible::Event QAccessibleEvent::type() const -

1344 Returns the event type. -

1345 */ -

1346 -

1347 /*! \fn QObject* QAccessibleEvent::object() const -

1348 Returns the event object. -

1349 */ -

1350 -

1351 /*! \fn void QAccessibleEvent::setChild(int child) -

1352 Sets the child index to \a child. -

1353 */ -

1354 -

1355 /*! \fn int QAccessibleEvent::child() const -

1356 Returns the child index. -

1357 */ -

1358 -

1359 /*! -

1360 \internal -

1361 Returns the uniqueId of the QAccessibleInterface represented by this event. -

1362 -

1363 In case the object() function returns 0 this is the only way to access the -

1364 interface. -

1365 */ -

1366 QAccessible::Id QAccessibleEvent::uniqueId() const -

1367 { -

1368 if (!m_object) -

1369 return m_uniqueId; -

1370 QAccessibleInterface *iface = QAccessible::queryAccessibleInterface(m_object); -

1371 if (!iface) -

1372 return 0; -

1373 if (m_child != -1) -

1374 iface = iface->child(m_child); -

1375 return QAccessible::uniqueId(iface); -

1376 } -

1377 -

1378 /*! -

1379 \class QAccessibleValueChangeEvent -

1380 \ingroup accessibility -

1381 \inmodule QtGui -

1382 -

1383 \brief The QAccessibleValueChangeEvent describes a change in value for an accessible object. -

1384 -

1385 It contains the new value. -

1386 -

1387 This class is used with \l QAccessible::updateAccessibility(). -

1388 */ -

1389 -

1390 /*! \fn QAccessibleValueChangeEvent::QAccessibleValueChangeEvent(QObject *object, const QVariant &value) -

1391 -

1392 Constructs a new QAccessibleValueChangeEvent for \a object. -

1393 The event contains the new \a value. -

1394 */ -

1395 /*! \fn QAccessibleValueChangeEvent::QAccessibleValueChangeEvent(QAccessibleInterface *iface, const QVariant &val) -

1396 -

1397 Constructs a new QAccessibleValueChangeEvent for \a iface. -

1398 The event contains the new value \a val. -

1399 */ -

1400 -

1401 /*! \fn void QAccessibleValueChangeEvent::setValue(const QVariant & value) -

1402 -

1403 Sets the new \a value for this event. -

1404 */ -

1405 /*! -

1406 \fn QVariant QAccessibleValueChangeEvent::value() const -

1407 -

1408 Returns the new value of the accessible object of this event. -

1409 */ -

1410 /*! -

1411 \internal -

1412 */ -

1413 QAccessibleValueChangeEvent::~QAccessibleValueChangeEvent() -

1414 { -

1415 // must be empty until ### Qt 6 -

1416 } -

1417 -

1418 /*! -

1419 \class QAccessibleStateChangeEvent -

1420 \ingroup accessibility -

1421 \inmodule QtGui -

1422 -

1423 \brief The QAccessibleStateChangeEvent notfies the accessibility framework -

1424 that the state of an object has changed. -

1425 -

1426 This class is used with \l QAccessible::updateAccessibility(). -

1427 -

1428 \sa QAccessibleInterface::state() -

1429 */ -

1430 /*! \fn QAccessibleStateChangeEvent::QAccessibleStateChangeEvent(QObject *object, QAccessible::State state) -

1431 -

1432 Constructs a new QAccessibleStateChangeEvent for \a object. -

1433 The difference to the object's previous state is in \a state. -

1434 */ -

1435 /*! -

1436 \fn QAccessibleStateChangeEvent::QAccessibleStateChangeEvent(QAccessibleInterface *iface, QAccessible::State state) -

1437 -

1438 Constructs a new QAccessibleStateChangeEvent. -

1439 \a iface is the interface associated with the event -

1440 \a state is the state of the accessible object. -

1441 */ -

1442 /*! -

1443 \fn QAccessible::State QAccessibleStateChangeEvent::changedStates() const -

1444 \brief Returns the states that have been changed. -

1445 -

1446 Keep in mind that the returned states are the ones that have changed. -

1447 To find out about the state of an object, use QAccessibleInterface::state(). -

1448 -

1449 For example, if an object used to have the focus but loses it, -

1450 the object's state will have focused set to \c false. This event on the -

1451 other hand tells about the change and has focused set to \c true since -

1452 the focus state is changed from \c true to \c false. -

1453 */ -

1454 /*! -

1455 \internal -

1456 */ -

1457 QAccessibleStateChangeEvent::~QAccessibleStateChangeEvent() -

1458 { -

1459 // must be empty until ### Qt 6 -

1460 } -

1461 -

1462 /*! -

1463 \class QAccessibleTableModelChangeEvent -

1464 \ingroup accessibility -

1465 \inmodule QtGui -

1466 -

1467 \brief The QAccessibleTableModelChangeEvent signifies a change in a table, list, or tree where cells -

1468 are added or removed. -

1469 If the change affected a number of rows, firstColumn and lastColumn will return -1. -

1470 Likewise for columns, the row functions may return -1. -

1471 -

1472 This class is used with \l QAccessible::updateAccessibility(). -

1473 */ -

1474 -

1475 /*! \enum QAccessibleTableModelChangeEvent::ModelChangeType -

1476 This enum describes the different types of changes in the table model. -

1477 \value ModelReset The model has been reset, all previous knowledge about the model is now invalid. -

1478 \value DataChanged No cells have been added or removed, but the data of the specified cell range is invalid. -

1479 \value RowsInserted New rows have been inserted. -

1480 \value ColumnsInserted New columns have been inserted. -

1481 \value RowsRemoved Rows have been removed. -

1482 \value ColumnsRemoved Columns have been removed. -

1483 */ -

1484 /*! \fn QAccessibleTableModelChangeEvent::QAccessibleTableModelChangeEvent(QObject *object, ModelChangeType changeType) -

1485 -

1486 Constructs a new QAccessibleTableModelChangeEvent for \a object of with \a changeType. -

1487 */ -

1488 /*! \fn int QAccessibleTableModelChangeEvent::firstColumn() const -

1489 -

1490 Returns the first changed column. -

1491 */ -

1492 /*! \fn int QAccessibleTableModelChangeEvent::firstRow() const -

1493 -

1494 Returns the first changed row. -

1495 */ -

1496 /*! \fn int QAccessibleTableModelChangeEvent::lastColumn() const -

1497 -

1498 Returns the last changed column. -

1499 */ -

1500 /*! \fn int QAccessibleTableModelChangeEvent::lastRow() const -

1501 -

1502 Returns the last changed row. -

1503 */ -

1504 /*! \fn QAccessibleTableModelChangeEvent::ModelChangeType QAccessibleTableModelChangeEvent::modelChangeType() const -

1505 -

1506 Returns the type of change. -

1507 */ -

1508 /*! \fn void QAccessibleTableModelChangeEvent::setFirstColumn(int column) -

1509 -

1510 Sets the first changed \a column. -

1511 */ -

1512 /*! \fn void QAccessibleTableModelChangeEvent::setFirstRow(int row) -

1513 -

1514 Sets the first changed \a row. -

1515 */ -

1516 /*! \fn void QAccessibleTableModelChangeEvent::setLastColumn(int column) -

1517 -

1518 Sets the last changed \a column. -

1519 */ -

1520 /*! \fn void QAccessibleTableModelChangeEvent::setLastRow(int row) -

1521 -

1522 Sets the last changed \a row. -

1523 */ -

1524 /*! \fn void QAccessibleTableModelChangeEvent::setModelChangeType(ModelChangeType changeType) -

1525 -

1526 Sets the type of change to \a changeType. -

1527 */ -

1528 /*! -

1529 \fn QAccessibleTableModelChangeEvent::QAccessibleTableModelChangeEvent(QAccessibleInterface *iface, ModelChangeType changeType) -

1530 -

1531 Constructs a new QAccessibleTableModelChangeEvent for interface \a iface with a model -

1532 change type \a changeType. -

1533 */ -

1534 /*! -

1535 \internal -

1536 */ -

1537 QAccessibleTableModelChangeEvent::~QAccessibleTableModelChangeEvent() -

1538 { -

1539 // must be empty until ### Qt 6 -

1540 } -

1541 /*! -

1542 \class QAccessibleTextCursorEvent -

1543 \ingroup accessibility -

1544 \inmodule QtGui -

1545 -

1546 \brief The QAccessibleTextCursorEvent class notifies of cursor movements. -

1547 -

1548 This class is used with \l QAccessible::updateAccessibility(). -

1549 */ -

1550 /*! \fn QAccessibleTextCursorEvent::QAccessibleTextCursorEvent(QObject *object, int cursorPos) -

1551 -

1552 Create a new QAccessibleTextCursorEvent for \a object. -

1553 The \a cursorPos is the new cursor position. -

1554 */ -

1555 /*! \fn int QAccessibleTextCursorEvent::cursorPosition() const -

1556 -

1557 Returns the cursor position. -

1558 */ -

1559 /*! \fn void QAccessibleTextCursorEvent::setCursorPosition(int position) -

1560 -

1561 Sets the cursor \a position for this event. -

1562 */ -

1563 /*! -

1564 \internal -

1565 */ -

1566 QAccessibleTextCursorEvent::~QAccessibleTextCursorEvent() -

1567 { -

1568 // must be empty until ### Qt 6 -

1569 } -

1570 -

1571 -

1572 /*! -

1573 \fn QAccessibleTextCursorEvent(QAccessibleInterface *iface, int cursorPos) -

1574 -

1575 Create a new QAccessibleTextCursorEvent for \a iface, -

1576 The \a cursorPos is the new cursor position. -

1577 */ -

1578 -

1579 /*! -

1580 \class QAccessibleTextInsertEvent -

1581 \ingroup accessibility -

1582 \inmodule QtGui -

1583 -

1584 \brief The QAccessibleTextInsertEvent class notifies of text being inserted. -

1585 -

1586 This class is used with \l QAccessible::updateAccessibility(). -

1587 */ -

1588 /*! \fn QAccessibleTextInsertEvent::QAccessibleTextInsertEvent(QObject *object, int position, const QString &text) -

1589 -

1590 Constructs a new QAccessibleTextInsertEvent event for \a object. -

1591 The \a text has been inserted at \a position. -

1592 By default, it is assumed that the cursor has moved to the end -

1593 of the selection. If that is not the case, one needs to manually -

1594 set it with \l QAccessibleTextCursorEvent::setCursorPosition() for this event. -

1595 */ -

1596 /*! \fn int QAccessibleTextInsertEvent::changePosition() const -

1597 -

1598 Returns the position where the text was inserted. -

1599 */ -

1600 /*! \fn QString QAccessibleTextInsertEvent::textInserted() const -

1601 -

1602 Returns the text that has been inserted. -

1603 */ -

1604 /*! -

1605 \internal -

1606 */ -

1607 QAccessibleTextInsertEvent::~QAccessibleTextInsertEvent() -

1608 { -

1609 // must be empty until ### Qt 6 -

1610 } -

1611 -

1612 -

1613 /*! -

1614 \class QAccessibleTextRemoveEvent -

1615 \ingroup accessibility -

1616 \inmodule QtGui -

1617 -

1618 \brief The QAccessibleTextRemoveEvent class notifies of text being deleted. -

1619 -

1620 This class is used with \l QAccessible::updateAccessibility(). -

1621 */ -

1622 /*! \fn QAccessibleTextRemoveEvent::QAccessibleTextRemoveEvent(QObject *object, int position, const QString &text) -

1623 -

1624 Constructs a new QAccessibleTextRemoveEvent event for \a object. -

1625 The \a text has been removed at \a position. -

1626 By default it is assumed that the cursor has moved to \a position. -

1627 If that is not the case, one needs to manually -

1628 set it with \l QAccessibleTextCursorEvent::setCursorPosition() for this event. -

1629 */ -

1630 /*! \fn QAccessibleTextRemoveEvent::QAccessibleTextRemoveEvent(QAccessibleInterface *iface, int position, const QString &text) -

1631 -

1632 Constructs a new QAccessibleTextRemoveEvent event for \a iface. -

1633 The \a text has been removed at \a position. -

1634 By default it is assumed that the cursor has moved to \a position. -

1635 If that is not the case, one needs to manually -

1636 set it with \l QAccessibleTextCursorEvent::setCursorPosition() for this event. -

1637 */ -

1638 -

1639 /*! \fn int QAccessibleTextRemoveEvent::changePosition() const -

1640 -

1641 Returns the position where the text was removed. -

1642 */ -

1643 /*! \fn QString QAccessibleTextRemoveEvent::textRemoved() const -

1644 -

1645 Returns the text that has been removed. -

1646 */ -

1647 /*! -

1648 \internal -

1649 */ -

1650 QAccessibleTextRemoveEvent::~QAccessibleTextRemoveEvent() -

1651 { -

1652 // must be empty until ### Qt 6 -

1653 } -

1654 -

1655 /*! -

1656 \fn QAccessibleTextSelectionEvent::QAccessibleTextSelectionEvent(QAccessibleInterface *iface, int start, int end) -

1657 -

1658 Constructs a new QAccessibleTextSelectionEvent for \a iface. The new selection this -

1659 event notifies about is from position \a start to \a end. -

1660 */ -

1661 -

1662 /*! -

1663 \fn QAccessibleTextInsertEvent::QAccessibleTextInsertEvent(QAccessibleInterface *iface, int position, const QString &text) -

1664 -

1665 Constructs a new QAccessibleTextInsertEvent event for \a iface. The text has been inserted at -

1666 \a position. -

1667 */ -

1668 -

1669 /*! -

1670 \fn inline QAccessibleTextUpdateEvent::QAccessibleTextUpdateEvent(QAccessibleInterface *iface, int position, const QString &oldText, -

1671 const QString &text) -

1672 -

1673 Constructs a new QAccessibleTextUpdateEvent for \a iface. The text change takes place at -

1674 \a position where the \a oldText was removed and \a text inserted instead. -

1675 -

1676 */ -

1677 -

1678 -

1679 -

1680 /*! -

1681 \class QAccessibleTextUpdateEvent -

1682 \ingroup accessibility -

1683 \inmodule QtGui -

1684 -

1685 \brief The QAccessibleTextUpdateEvent class notifies about text changes. -

1686 This is for accessibles that support editable text such as line edits. -

1687 This event occurs for example when a portion of selected text -

1688 gets replaced by pasting a new text or in override mode of editors. -

1689 -

1690 This class is used with \l QAccessible::updateAccessibility(). -

1691 */ -

1692 /*! \fn QAccessibleTextUpdateEvent::QAccessibleTextUpdateEvent(QObject *object, int position, const QString &oldText, const QString &text) -

1693 -

1694 Constructs a new QAccessibleTextUpdateEvent for \a object. -

1695 The text change takes place at \a position where the \a oldText was removed and \a text inserted instead. -

1696 */ -

1697 /*! \fn int QAccessibleTextUpdateEvent::changePosition() const -

1698 -

1699 Returns where the change took place. -

1700 */ -

1701 /*! \fn QString QAccessibleTextUpdateEvent::textInserted() const -

1702 -

1703 Returns the inserted text. -

1704 */ -

1705 /*! \fn QString QAccessibleTextUpdateEvent::textRemoved() const -

1706 -

1707 Returns the removed text. -

1708 */ -

1709 /*! -

1710 \internal -

1711 */ -

1712 QAccessibleTextUpdateEvent::~QAccessibleTextUpdateEvent() -

1713 { -

1714 // must be empty until ### Qt 6 -

1715 } -

1716 -

1717 -

1718 /*! -

1719 \class QAccessibleTextSelectionEvent -

1720 \ingroup accessibility -

1721 \inmodule QtGui -

1722 -

1723 \brief QAccessibleTextSelectionEvent signals a change in the text selection of an object. -

1724 -

1725 This class is used with \l QAccessible::updateAccessibility(). -

1726 */ -

1727 /*! \fn QAccessibleTextSelectionEvent::QAccessibleTextSelectionEvent(QObject *object, int start, int end) -

1728 -

1729 Constructs a new QAccessibleTextSelectionEvent for \a object. -

1730 The new selection this event notifies about is from position \a start to \a end. -

1731 */ -

1732 /*! \fn int QAccessibleTextSelectionEvent::selectionEnd() const -

1733 -

1734 Returns the position of the last selected character. -

1735 */ -

1736 /*! \fn int QAccessibleTextSelectionEvent::selectionStart() const -

1737 -

1738 Returns the position of the first selected character. -

1739 */ -

1740 /*! \fn void QAccessibleTextSelectionEvent::setSelection(int start, int end) -

1741 -

1742 Sets the selection for this event from position \a start to \a end. -

1743 */ -

1744 /*! -

1745 \internal -

1746 */ -

1747 QAccessibleTextSelectionEvent::~QAccessibleTextSelectionEvent() -

1748 { -

1749 // must be empty until ### Qt 6 -

1750 } -

1751 -

1752 -

1753 -

1754 /*! -

1755 Returns the QAccessibleInterface associated with the event. -

1756 The caller of this function takes ownership of the returned interface. -

1757 */ -

1758 QAccessibleInterface *QAccessibleEvent::accessibleInterface() const -

1759 { -

1760 if (m_object == 0) -

1761 return QAccessible::accessibleInterface(m_uniqueId); -

1762 -

1763 QAccessibleInterface *iface = QAccessible::queryAccessibleInterface(m_object); -

1764 if (!iface || !iface->isValid()) -

1765 return 0; -

1766 -

1767 if (m_child >= 0) { -

1768 QAccessibleInterface *child = iface->child(m_child); -

1769 if (child) { -

1770 iface = child; -

1771 } else { -

1772 qWarning() << "Cannot creat accessible child interface for object: " << m_object << " index: " << m_child; -

1773 } -

1774 } -

1775 return iface; -

1776 } -

1777 -

1778 /*! -

1779 Returns the window associated with the underlying object. -

1780 For instance, QAccessibleWidget reimplements this and returns -

1781 the windowHandle() of the QWidget. -

1782 -

1783 It is used on some platforms to be able to notify the AT client about -

1784 state changes. -

1785 The backend will traverse up all ancestors until it finds a window. -

1786 (This means that at least one interface among the ancestors should -

1787 return a valid QWindow pointer). -

1788 -

1789 The default implementation returns 0. -

1790 */ -

1791 QWindow *QAccessibleInterface::window() const -

1792 { -

1793 return 0; -

1794 } -

1795 -

1796 /*! -

1797 \internal -

1798 Method to allow extending this class without breaking binary compatibility. -

1799 The actual behavior and format of \a data depends on \a id argument -

1800 which must be defined if the class is to be extended with another virtual -

1801 function. -

1802 Currently, this is unused. -

1803 */ -

1804 void QAccessibleInterface::virtual_hook(int /*id*/, void * /*data*/) -

1805 { -

1806 } -

1807 -

1808 /*! -

1809 \fn void *QAccessibleInterface::interface_cast(QAccessible::InterfaceType type) -

1810 -

1811 Returns a specialized accessibility interface \a type from the -

1812 generic QAccessibleInterface. -

1813 -

1814 This function must be reimplemented when providing more -

1815 information about a widget or object through the specialized -

1816 interfaces. For example a line edit should implement the -

1817 QAccessibleTextInterface. -

1818 -

1819 Qt's QLineEdit for example has its accessibility support -

1820 implemented in QAccessibleLineEdit. -

1821 -

1822 \code -

1823 void *QAccessibleLineEdit::interface_cast(QAccessible::InterfaceType t) -

1824 { -

1825 if (t == QAccessible::TextInterface) -

1826 return static_cast<QAccessibleTextInterface*>(this); -

1827 return QAccessibleWidget::interface_cast(t); -

1828 } -

1829 \endcode -

1830 -

1831 \sa QAccessible::InterfaceType, QAccessibleTextInterface, -

1832 QAccessibleValueInterface, QAccessibleActionInterface, -

1833 QAccessibleTableInterface, QAccessibleTableCellInterface -

1834 */ -

1835 -

1836 /*! \internal */ -

1837 const char *qAccessibleRoleString(QAccessible::Role role) -

1838 { -

1839 if (role >= QAccessible::UserRole) -

1840 role = QAccessible::UserRole; -

1841 static int roleEnum = QAccessible::staticMetaObject.indexOfEnumerator("Role"); -

1842 return QAccessible::staticMetaObject.enumerator(roleEnum).valueToKey(role); -

1843 } -

1844 -

1845 /*! \internal */ -

1846 const char *qAccessibleEventString(QAccessible::Event event) -

1847 { -

1848 static int eventEnum = QAccessible::staticMetaObject.indexOfEnumerator("Event"); -

1849 return QAccessible::staticMetaObject.enumerator(eventEnum).valueToKey(event); -

1850 } -

1851 -

1852 /*! \internal */ -

1853 bool operator==(const QAccessible::State &first, const QAccessible::State &second) -

1854 { -

1855 return memcmp(&first, &second, sizeof(QAccessible::State)) == 0; -

1856 } -

1857 -

1858 #ifndef QT_NO_DEBUG_STREAM -

1859 /*! \internal */ -

1860 Q_GUI_EXPORT QDebug operator<<(QDebug d, const QAccessibleInterface *iface) -

1861 { -

1862 QDebugStateSaver saver(d); -

1863 if (!iface) { -

1864 d << "QAccessibleInterface(null)"; -

1865 return d; -

1866 } -

1867 d.nospace(); -

1868 d << "QAccessibleInterface(" << hex << (const void *) iface << dec; -

1869 if (iface->isValid()) { -

1870 d << " name=" << iface->text(QAccessible::Name) << ' '; -

1871 d << "role=" << qAccessibleRoleString(iface->role()) << ' '; -

1872 if (iface->childCount()) -

1873 d << "childc=" << iface->childCount() << ' '; -

1874 if (iface->object()) { -

1875 d << "obj=" << iface->object(); -

1876 } -

1877 QStringList stateStrings; -

1878 QAccessible::State st = iface->state(); -

1879 if (st.focusable) -

1880 stateStrings << QLatin1String("focusable"); -

1881 if (st.focused) -

1882 stateStrings << QLatin1String("focused"); -

1883 if (st.selected) -

1884 stateStrings << QLatin1String("selected"); -

1885 if (st.invisible) -

1886 stateStrings << QLatin1String("invisible"); -

1887 -

1888 if (!stateStrings.isEmpty()) -

1889 d << stateStrings.join(QLatin1Char('|')); -

1890 -

1891 if (!st.invisible) -

1892 d << "rect=" << iface->rect(); -

1893 -

1894 } else { -

1895 d << " invalid"; -

1896 } -

1897 d << ')'; -

1898 return d; -

1899 } -

1900 -

1901 /*! \internal */ -

1902 QDebug operator<<(QDebug d, const QAccessibleEvent &ev) -

1903 { -

1904 QDebugStateSaver saver(d); -

1905 d.nospace() << "QAccessibleEvent("; -

1906 if (ev.object()) { -

1907 d.nospace() << "object=" << hex << ev.object() << dec; -

1908 d.nospace() << "child=" << ev.child(); -

1909 } else { -

1910 d.nospace() << "no object, uniqueId=" << ev.uniqueId(); -

1911 } -

1912 d << " event=" << qAccessibleEventString(ev.type()); -

1913 if (ev.type() == QAccessible::StateChanged) { -

1914 QAccessible::State changed = static_cast<const QAccessibleStateChangeEvent*>(&ev)->changedStates(); -

1915 d << "State changed:"; -

1916 if (changed.disabled) d << "disabled"; -

1917 if (changed.selected) d << "selected"; -

1918 if (changed.focusable) d << "focusable"; -

1919 if (changed.focused) d << "focused"; -

1920 if (changed.pressed) d << "pressed"; -

1921 if (changed.checkable) d << "checkable"; -

1922 if (changed.checked) d << "checked"; -

1923 if (changed.checkStateMixed) d << "checkStateMixed"; -

1924 if (changed.readOnly) d << "readOnly"; -

1925 if (changed.hotTracked) d << "hotTracked"; -

1926 if (changed.defaultButton) d << "defaultButton"; -

1927 if (changed.expanded) d << "expanded"; -

1928 if (changed.collapsed) d << "collapsed"; -

1929 if (changed.busy) d << "busy"; -

1930 if (changed.expandable) d << "expandable"; -

1931 if (changed.marqueed) d << "marqueed"; -

1932 if (changed.animated) d << "animated"; -

1933 if (changed.invisible) d << "invisible"; -

1934 if (changed.offscreen) d << "offscreen"; -

1935 if (changed.sizeable) d << "sizeable"; -

1936 if (changed.movable) d << "movable"; -

1937 if (changed.selfVoicing) d << "selfVoicing"; -

1938 if (changed.selectable) d << "selectable"; -

1939 if (changed.linked) d << "linked"; -

1940 if (changed.traversed) d << "traversed"; -

1941 if (changed.multiSelectable) d << "multiSelectable"; -

1942 if (changed.extSelectable) d << "extSelectable"; -

1943 if (changed.passwordEdit) d << "passwordEdit"; // used to be Protected -

1944 if (changed.hasPopup) d << "hasPopup"; -

1945 if (changed.modal) d << "modal"; -

1946 -

1947 // IA2 - we chose to not add some IA2 states for now -

1948 // Below the ones that seem helpful -

1949 if (changed.active) d << "active"; -

1950 if (changed.invalid) d << "invalid"; // = defunct -

1951 if (changed.editable) d << "editable"; -

1952 if (changed.multiLine) d << "multiLine"; -

1953 if (changed.selectableText) d << "selectableText"; -

1954 if (changed.supportsAutoCompletion) d << "supportsAutoCompletion"; -

1955 -

1956 } -

1957 d << ')'; -

1958 return d; -

1959 } -

1960 #endif // QT_NO_DEBUGSTREAM -

1961 -

1962 /*! -

1963 \class QAccessibleTextInterface -

1964 \inmodule QtGui -

1965 -

1966 \ingroup accessibility -

1967 -

1968 \brief The QAccessibleTextInterface class implements support for text handling. -

1969 -

1970 This interface corresponds to the IAccessibleText interface. -

1971 It should be implemented for widgets that display more text than a plain label. -

1972 Labels should be represented by only \l QAccessibleInterface -

1973 and return their text as name (\l QAccessibleInterface::text() with \l QAccessible::Name as type). -

1974 The QAccessibleTextInterface is typically for text that a screen reader -

1975 might want to read line by line, and for widgets that support text selection and input. -

1976 This interface is, for example, implemented for QLineEdit. -

1977 -

1978 \l{IAccessible2 Specification} -

1979 */ -

1980 -

1981 /*! -

1982 -

1983 Destroys the QAccessibleTextInterface. -

1984 */ -

1985 QAccessibleTextInterface::~QAccessibleTextInterface() -

1986 { -

1987 // must be empty until ### Qt 6 -

1988 } -

1989 -

1990 /*! -

1991 \fn void QAccessibleTextInterface::addSelection(int startOffset, int endOffset) -

1992 -

1993 Select the text from \a startOffset to \a endOffset. -

1994 The \a startOffset is the first character that will be selected. -

1995 The \a endOffset is the first character that will not be selected. -

1996 -

1997 When the object supports multiple selections (e.g. in a word processor), -

1998 this adds a new selection, otherwise it replaces the previous selection. -

1999 -

2000 The selection will be \a endOffset - \a startOffset characters long. -

2001 */ -

2002 -

2003 /*! -

2004 \fn QString QAccessibleTextInterface::attributes(int offset, int *startOffset, int *endOffset) const -

2005 -

2006 Returns the text attributes at the position \a offset. -

2007 In addition the range of the attributes is returned in \a startOffset and \a endOffset. -

2008 */ -

2009 -

2010 /*! -

2011 \fn int QAccessibleTextInterface::cursorPosition() const -

2012 -

2013 Returns the current cursor position. -

2014 */ -

2015 -

2016 /*! -

2017 \fn QRect QAccessibleTextInterface::characterRect(int offset) const -

2018 -

2019 Returns the position and size of the character at position \a offset in screen coordinates. -

2020 */ -

2021 -

2022 /*! -

2023 \fn int QAccessibleTextInterface::selectionCount() const -

2024 -

2025 Returns the number of selections in this text. -

2026 */ -

2027 -

2028 /*! -

2029 \fn int QAccessibleTextInterface::offsetAtPoint(const QPoint &point) const -

2030 -

2031 Returns the offset of the character at the \a point in screen coordinates. -

2032 */ -

2033 -

2034 /*! -

2035 \fn void QAccessibleTextInterface::selection(int selectionIndex, int *startOffset, int *endOffset) const -

2036 -

2037 Returns a selection. The size of the selection is returned in \a startOffset and \a endOffset. -

2038 If there is no selection both \a startOffset and \a endOffset are 0. -

2039 -

2040 The accessibility APIs support multiple selections. For most widgets though, only one selection -

2041 is supported with \a selectionIndex equal to 0. -

2042 */ -

2043 -

2044 /*! -

2045 \fn QString QAccessibleTextInterface::text(int startOffset, int endOffset) const -

2046 -

2047 Returns the text from \a startOffset to \a endOffset. -

2048 The \a startOffset is the first character that will be returned. -

2049 The \a endOffset is the first character that will not be returned. -

2050 */ -

2051 -

2052 /*! -

2053 \internal -

2054 Helper for finding line breaks in textBeforeOffset/textAtOffset/textAfterOffset. -

2055 \a beforeAtAfter is the line we look for. -1 for before, 0 for at and 1 for after. -

2056 */ -

2057 static QString textLineBoundary(int beforeAtAfter, const QString &text, int offset, int *startOffset, int *endOffset) -

2058 { -

2059 Q_ASSERT(beforeAtAfter >= -1 && beforeAtAfter <= 1); -

2060 Q_ASSERT(*startOffset == -1 && *endOffset == -1); -

2061 int length = text.length(); -

2062 Q_ASSERT(offset >= 0 && offset <= length); -

2063 -

2064 // move offset into the right range (if asking for line before or after -

2065 if (beforeAtAfter == 1) { -

2066 offset = text.indexOf(QChar::LineFeed, qMin(offset, length - 1)); -

2067 if (offset < 0) -

2068 return QString(); // after the last line comes nothing -

2069 ++offset; // move after the newline -

2070 } else if (beforeAtAfter == -1) { -

2071 offset = text.lastIndexOf(QChar::LineFeed, qMax(offset - 1, 0)); -

2072 if (offset < 0) -

2073 return QString(); // before first line comes nothing -

2074 } -

2075 -

2076 if (offset > 0) -

2077 *startOffset = text.lastIndexOf(QChar::LineFeed, offset - 1); -

2078 ++*startOffset; // move to the char after the newline (0 if lastIndexOf returned -1) -

2079 -

2080 *endOffset = text.indexOf(QChar::LineFeed, qMin(offset, length - 1)) + 1; // include newline char -

2081 if (*endOffset <= 0 || *endOffset > length) -

2082 *endOffset = length; // if the text doesn't end with a newline it ends at length -

2083 -

2084 return text.mid(*startOffset, *endOffset - *startOffset); -

2085 } -

2086 -

2087 /*! -

2088 Returns the text item of type \a boundaryType that is close to offset \a offset -

2089 and sets \a startOffset and \a endOffset values to the start and end positions -

2090 of that item; returns an empty string if there is no such an item. -

2091 Sets \a startOffset and \a endOffset values to -1 on error. -

2092 -

2093 This default implementation is provided for small text edits. A word processor or -

2094 text editor should provide their own efficient implementations. This function makes no -

2095 distinction between paragraphs and lines. -

2096 -

2097 \note this function can not take the cursor position into account. By convention -

2098 an \a offset of -2 means that this function should use the cursor position as offset. -

2099 Thus an offset of -2 must be converted to the cursor position before calling this -

2100 function. -

2101 An offset of -1 is used for the text length and custom implementations of this function -

2102 have to return the result as if the length was passed in as offset. -

2103 */ -

2104 QString QAccessibleTextInterface::textBeforeOffset(int offset, QAccessible::TextBoundaryType boundaryType, -

2105 int *startOffset, int *endOffset) const -

2106 { -

2107 const QString txt = text(0, characterCount()); -

2108 -

2109 if (offset == -1) -

2110 offset = txt.length(); -

2111 -

2112 *startOffset = *endOffset = -1; -

2113 if (txt.isEmpty() || offset <= 0 || offset > txt.length()) -

2114 return QString(); -

2115 -

2116 // type initialized just to silence a compiler warning [-Werror=maybe-uninitialized] -

2117 QTextBoundaryFinder::BoundaryType type = QTextBoundaryFinder::Grapheme; -

2118 switch (boundaryType) { -

2119 case QAccessible::CharBoundary: -

2120 type = QTextBoundaryFinder::Grapheme; -

2121 break; -

2122 case QAccessible::WordBoundary: -

2123 type = QTextBoundaryFinder::Word; -

2124 break; -

2125 case QAccessible::SentenceBoundary: -

2126 type = QTextBoundaryFinder::Sentence; -

2127 break; -

2128 case QAccessible::LineBoundary: -

2129 case QAccessible::ParagraphBoundary: -

2130 // Lines can not use QTextBoundaryFinder since Line there means any potential line-break. -

2131 return textLineBoundary(-1, txt, offset, startOffset, endOffset); -

2132 case QAccessible::NoBoundary: -

2133 // return empty, this function currently only supports single lines, so there can be no line before -

2134 return QString(); -

2135 default: -

2136 Q_UNREACHABLE(); -

2137 } -

2138 -

2139 // keep behavior in sync with QTextCursor::movePosition()! -

2140 -

2141 QTextBoundaryFinder boundary(type, txt); -

2142 boundary.setPosition(offset); -

2143 -

2144 do { -

2145 if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem))) -

2146 break; -

2147 } while (boundary.toPreviousBoundary() > 0); -

2148 Q_ASSERT(boundary.position() >= 0); -

2149 *endOffset = boundary.position(); -

2150 -

2151 while (boundary.toPreviousBoundary() > 0) { -

2152 if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem))) -

2153 break; -

2154 } -

2155 Q_ASSERT(boundary.position() >= 0); -

2156 *startOffset = boundary.position(); -

2157 -

2158 return txt.mid(*startOffset, *endOffset - *startOffset); -

2159 } -

2160 -

2161 /*! -

2162 Returns the text item of type \a boundaryType that is right after offset \a offset -

2163 and sets \a startOffset and \a endOffset values to the start and end positions -

2164 of that item; returns an empty string if there is no such an item. -

2165 Sets \a startOffset and \a endOffset values to -1 on error. -

2166 -

2167 This default implementation is provided for small text edits. A word processor or -

2168 text editor should provide their own efficient implementations. This function makes no -

2169 distinction between paragraphs and lines. -

2170 -

2171 \note this function can not take the cursor position into account. By convention -

2172 an \a offset of -2 means that this function should use the cursor position as offset. -

2173 Thus an offset of -2 must be converted to the cursor position before calling this -

2174 function. -

2175 An offset of -1 is used for the text length and custom implementations of this function -

2176 have to return the result as if the length was passed in as offset. -

2177 */ -

2178 QString QAccessibleTextInterface::textAfterOffset(int offset, QAccessible::TextBoundaryType boundaryType, -

2179 int *startOffset, int *endOffset) const -

2180 { -

2181 const QString txt = text(0, characterCount()); -

2182 -

2183 if (offset == -1) -

2184 offset = txt.length(); -

2185 -

2186 *startOffset = *endOffset = -1; -

2187 if (txt.isEmpty() || offset < 0 || offset >= txt.length()) -

2188 return QString(); -

2189 -

2190 // type initialized just to silence a compiler warning [-Werror=maybe-uninitialized] -

2191 QTextBoundaryFinder::BoundaryType type = QTextBoundaryFinder::Grapheme; -

2192 switch (boundaryType) { -

2193 case QAccessible::CharBoundary: -

2194 type = QTextBoundaryFinder::Grapheme; -

2195 break; -

2196 case QAccessible::WordBoundary: -

2197 type = QTextBoundaryFinder::Word; -

2198 break; -

2199 case QAccessible::SentenceBoundary: -

2200 type = QTextBoundaryFinder::Sentence; -

2201 break; -

2202 case QAccessible::LineBoundary: -

2203 case QAccessible::ParagraphBoundary: -

2204 // Lines can not use QTextBoundaryFinder since Line there means any potential line-break. -

2205 return textLineBoundary(1, txt, offset, startOffset, endOffset); -

2206 case QAccessible::NoBoundary: -

2207 // return empty, this function currently only supports single lines, so there can be no line after -

2208 return QString(); -

2209 default: -

2210 Q_UNREACHABLE(); -

2211 } -

2212 -

2213 // keep behavior in sync with QTextCursor::movePosition()! -

2214 -

2215 QTextBoundaryFinder boundary(type, txt); -

2216 boundary.setPosition(offset); -

2217 -

2218 while (true) { -

2219 int toNext = boundary.toNextBoundary(); -

2220 if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem))) -

2221 break; -

2222 if (toNext < 0 || toNext >= txt.length()) -

2223 break; // not found, the boundary might not exist -

2224 } -

2225 Q_ASSERT(boundary.position() <= txt.length()); -

2226 *startOffset = boundary.position(); -

2227 -

2228 while (true) { -

2229 int toNext = boundary.toNextBoundary(); -

2230 if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem))) -

2231 break; -

2232 if (toNext < 0 || toNext >= txt.length()) -

2233 break; // not found, the boundary might not exist -

2234 } -

2235 Q_ASSERT(boundary.position() <= txt.length()); -

2236 *endOffset = boundary.position(); -

2237 -

2238 if ((*startOffset == -1) || (*endOffset == -1) || (*startOffset == *endOffset)) { -

2239 *endOffset = -1; -

2240 *startOffset = -1; -

2241 } -

2242 -

2243 return txt.mid(*startOffset, *endOffset - *startOffset); -

2244 } -

2245 -

2246 /*! -

2247 Returns the text item of type \a boundaryType at offset \a offset -

2248 and sets \a startOffset and \a endOffset values to the start and end positions -

2249 of that item; returns an empty string if there is no such an item. -

2250 Sets \a startOffset and \a endOffset values to -1 on error. -

2251 -

2252 This default implementation is provided for small text edits. A word processor or -

2253 text editor should provide their own efficient implementations. This function makes no -

2254 distinction between paragraphs and lines. -

2255 -

2256 \note this function can not take the cursor position into account. By convention -

2257 an \a offset of -2 means that this function should use the cursor position as offset. -

2258 Thus an offset of -2 must be converted to the cursor position before calling this -

2259 function. -

2260 An offset of -1 is used for the text length and custom implementations of this function -

2261 have to return the result as if the length was passed in as offset. -

2262 */ -

2263 QString QAccessibleTextInterface::textAtOffset(int offset, QAccessible::TextBoundaryType boundaryType, -

2264 int *startOffset, int *endOffset) const -

2265 { -

2266 const QString txt = text(0, characterCount()); -

2267 -

2268 if (offset == -1) -

2269 offset = txt.length(); -

2270 -

2271 *startOffset = *endOffset = -1; -

2272 if (txt.isEmpty() || offset < 0 || offset > txt.length()) -

2273 return QString(); -

2274 -

2275 if (offset == txt.length() && boundaryType == QAccessible::CharBoundary) -

2276 return QString(); -

2277 -

2278 // type initialized just to silence a compiler warning [-Werror=maybe-uninitialized] -

2279 QTextBoundaryFinder::BoundaryType type = QTextBoundaryFinder::Grapheme; -

2280 switch (boundaryType) { -

2281 case QAccessible::CharBoundary: -

2282 type = QTextBoundaryFinder::Grapheme; -

2283 break; -

2284 case QAccessible::WordBoundary: -

2285 type = QTextBoundaryFinder::Word; -

2286 break; -

2287 case QAccessible::SentenceBoundary: -

2288 type = QTextBoundaryFinder::Sentence; -

2289 break; -

2290 case QAccessible::LineBoundary: -

2291 case QAccessible::ParagraphBoundary: -

2292 // Lines can not use QTextBoundaryFinder since Line there means any potential line-break. -

2293 return textLineBoundary(0, txt, offset, startOffset, endOffset); -

2294 case QAccessible::NoBoundary: -

2295 *startOffset = 0; -

2296 *endOffset = txt.length(); -

2297 return txt; -

2298 default: -

2299 Q_UNREACHABLE(); -

2300 } -

2301 -

2302 // keep behavior in sync with QTextCursor::movePosition()! -

2303 -

2304 QTextBoundaryFinder boundary(type, txt); -

2305 boundary.setPosition(offset); -

2306 -

2307 do { -

2308 if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem))) -

2309 break; -

2310 } while (boundary.toPreviousBoundary() > 0); -

2311 Q_ASSERT(boundary.position() >= 0); -

2312 *startOffset = boundary.position(); -

2313 -

2314 while (boundary.toNextBoundary() < txt.length()) { -

2315 if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem))) -

2316 break; -

2317 } -

2318 Q_ASSERT(boundary.position() <= txt.length()); -

2319 *endOffset = boundary.position(); -

2320 -

2321 return txt.mid(*startOffset, *endOffset - *startOffset); -

2322 } -

2323 -

2324 /*! -

2325 \fn void QAccessibleTextInterface::removeSelection(int selectionIndex) -

2326 -

2327 Clears the selection with index \a selectionIndex. -

2328 */ -

2329 -

2330 /*! -

2331 \fn void QAccessibleTextInterface::setCursorPosition(int position) -

2332 -

2333 Moves the cursor to \a position. -

2334 */ -

2335 -

2336 /*! -

2337 \fn void QAccessibleTextInterface::setSelection(int selectionIndex, int startOffset, int endOffset) -

2338 -

2339 Set the selection \a selectionIndex to the range from \a startOffset to \a endOffset. -

2340 -

2341 \sa addSelection(), removeSelection() -

2342 */ -

2343 -

2344 /*! -

2345 \fn int QAccessibleTextInterface::characterCount() const -

2346 -

2347 Returns the length of the text (total size including spaces). -

2348 */ -

2349 -

2350 /*! -

2351 \fn void QAccessibleTextInterface::scrollToSubstring(int startIndex, int endIndex) -

2352 -

2353 Ensures that the text between \a startIndex and \a endIndex is visible. -

2354 */ -

2355 -

2356 /*! -

2357 \class QAccessibleEditableTextInterface -

2358 \ingroup accessibility -

2359 \inmodule QtGui -

2360 -

2361 \brief The QAccessibleEditableTextInterface class implements support for objects with editable text. -

2362 -

2363 When implementing this interface you will almost certainly also want to implement \l QAccessibleTextInterface. -

2364 -

2365 \sa QAccessibleInterface -

2366 -

2367 \l{IAccessible2 Specification} -

2368 */ -

2369 -

2370 /*! -

2371 -

2372 Destroys the QAccessibleEditableTextInterface. -

2373 */ -

2374 QAccessibleEditableTextInterface::~QAccessibleEditableTextInterface() -

2375 { -

2376 // must be empty until ### Qt 6 -

2377 } -

2378 -

2379 /*! -

2380 \fn void QAccessibleEditableTextInterface::deleteText(int startOffset, int endOffset) -

2381 -

2382 Deletes the text from \a startOffset to \a endOffset. -

2383 */ -

2384 -

2385 /*! -

2386 \fn void QAccessibleEditableTextInterface::insertText(int offset, const QString &text) -

2387 -

2388 Inserts \a text at position \a offset. -

2389 */ -

2390 -

2391 /*! -

2392 \fn void QAccessibleEditableTextInterface::replaceText(int startOffset, int endOffset, const QString &text) -

2393 -

2394 Removes the text from \a startOffset to \a endOffset and instead inserts \a text. -

2395 */ -

2396 -

2397 /*! -

2398 \class QAccessibleValueInterface -

2399 \inmodule QtGui -

2400 \ingroup accessibility -

2401 -

2402 \brief The QAccessibleValueInterface class implements support for objects that manipulate a value. -

2403 -

2404 This interface should be implemented by accessible objects that represent a value. -

2405 Examples are spinner, slider, dial and scroll bar. -

2406 -

2407 Instead of forcing the user to deal with the individual parts of the widgets, this interface -

2408 gives an easier approach to the kind of widget it represents. -

2409 -

2410 Usually this interface is implemented by classes that also implement \l QAccessibleInterface. -

2411 -

2412 \l{IAccessible2 Specification} -

2413 */ -

2414 -

2415 /*! -

2416 Destroys the QAccessibleValueInterface. -

2417 -

2418 */ -

2419 QAccessibleValueInterface::~QAccessibleValueInterface() -

2420 { -

2421 // must be empty until ### Qt 6 -

2422 } -

2423 -

2424 /*! -

2425 \fn QVariant QAccessibleValueInterface::currentValue() const -

2426 -

2427 Returns the current value of the widget. This is usually a double or int. -

2428 \sa setCurrentValue() -

2429 */ -

2430 -

2431 /*! -

2432 \fn void QAccessibleValueInterface::setCurrentValue(const QVariant &value) -

2433 -

2434 Sets the \a value. If the desired \a value is out of the range of permissible values, -

2435 this call will be ignored. -

2436 -

2437 \sa currentValue(), minimumValue(), maximumValue() -

2438 */ -

2439 -

2440 /*! -

2441 \fn QVariant QAccessibleValueInterface::maximumValue() const -

2442 -

2443 Returns the maximum value this object accepts. -

2444 \sa minimumValue(), currentValue() -

2445 */ -

2446 -

2447 /*! -

2448 \fn QVariant QAccessibleValueInterface::minimumValue() const -

2449 -

2450 Returns the minimum value this object accepts. -

2451 \sa maximumValue(), currentValue() -

2452 */ -

2453 -

2454 /*! -

2455 \fn QVariant QAccessibleValueInterface::minimumStepSize() const -

2456 -

2457 Returns the minimum step size for the accessible. -

2458 This is the smalles increment that makes sense when changing the value. -

2459 When programatically changing the value it should always be a multiple -

2460 of the minimum step size. -

2461 -

2462 Some tools use this value even when the setCurrentValue does not -

2463 perform any action. Progress bars for example are read-only but -

2464 should return their range divided by 100. -

2465 */ -

2466 -

2467 /*! -

2468 \class QAccessibleImageInterface -

2469 \inmodule QtGui -

2470 \ingroup accessibility -

2471 \internal -

2472 \preliminary -

2473 -

2474 \brief The QAccessibleImageInterface class implements support for -

2475 the IAccessibleImage interface. -

2476 -

2477 \l{IAccessible2 Specification} -

2478 */ -

2479 -

2480 /*! -

2481 Destroys the QAccessibleImageInterface. -

2482 */ -

2483 QAccessibleImageInterface::~QAccessibleImageInterface() -

2484 { -

2485 // must be empty until ### Qt 6 -

2486 } -

2487 -

2488 /*! -

2489 \class QAccessibleTableCellInterface -

2490 \inmodule QtGui -

2491 \ingroup accessibility -

2492 -

2493 \brief The QAccessibleTableCellInterface class implements support for -

2494 the IAccessibleTable2 Cell interface. -

2495 -

2496 \l{IAccessible2 Specification} -

2497 */ -

2498 -

2499 /*! -

2500 -

2501 Destroys the QAccessibleTableCellInterface. -

2502 */ -

2503 QAccessibleTableCellInterface::~QAccessibleTableCellInterface() -

2504 { -

2505 // must be empty until ### Qt 6 -

2506 } -

2507 -

2508 /*! -

2509 \fn virtual int QAccessibleTableCellInterface::columnExtent() const -

2510 -

2511 Returns the number of columns occupied by this cell accessible. -

2512 */ -

2513 -

2514 /*! -

2515 \fn virtual QList<QAccessibleInterface*> QAccessibleTableCellInterface::columnHeaderCells() const -

2516 -

2517 Returns the column headers as an array of cell accessibles. -

2518 */ -

2519 -

2520 /*! -

2521 \fn virtual int QAccessibleTableCellInterface::columnIndex() const -

2522 -

2523 Translates this cell accessible into the corresponding column index. -

2524 */ -

2525 -

2526 /*! -

2527 \fn virtual int QAccessibleTableCellInterface::rowExtent() const -

2528 -

2529 Returns the number of rows occupied by this cell accessible. -

2530 */ -

2531 -

2532 /*! -

2533 \fn virtual QList<QAccessibleInterface*> QAccessibleTableCellInterface::rowHeaderCells() const -

2534 -

2535 Returns the row headers as an array of cell accessibles. -

2536 */ -

2537 -

2538 /*! -

2539 \fn virtual int QAccessibleTableCellInterface::rowIndex() const -

2540 -

2541 Translates this cell accessible into the corresponding row index. -

2542 */ -

2543 -

2544 /*! -

2545 \fn virtual bool QAccessibleTableCellInterface::isSelected() const -

2546 -

2547 Returns a boolean value indicating whether this cell is selected. -

2548 */ -

2549 -

2550 /*! -

2551 \fn virtual QAccessibleInterface *QAccessibleTableCellInterface::table() const -

2552 -

2553 Returns the QAccessibleInterface of the table containing this cell. -

2554 */ -

2555 -

2556 -

2557 /*! -

2558 \class QAccessibleTableInterface -

2559 \ingroup accessibility -

2560 -

2561 \brief The QAccessibleTableInterface class implements support for -

2562 the IAccessibleTable2 interface. -

2563 -

2564 \l{IAccessible2 Specification} -

2565 */ -

2566 -

2567 /*! -

2568 -

2569 Destroys the QAccessibleTableInterface. -

2570 */ -

2571 QAccessibleTableInterface::~QAccessibleTableInterface() -

2572 { -

2573 // must be empty until ### Qt 6 -

2574 } -

2575 -

2576 /*! -

2577 \fn virtual QAccessibleInterface *QAccessibleTableInterface::cellAt(int row, int column) const -

2578 -

2579 Returns the cell at the specified \a row and \a column in the table. -

2580 */ -

2581 -

2582 /*! -

2583 \fn virtual QAccessibleInterface *QAccessibleTableInterface::caption() const -

2584 -

2585 Returns the caption for the table. -

2586 */ -

2587 -

2588 /*! -

2589 \fn virtual QString QAccessibleTableInterface::columnDescription(int column) const -

2590 -

2591 Returns the description text of the specified \a column in the table. -

2592 */ -

2593 -

2594 /*! -

2595 \fn virtual int QAccessibleTableInterface::columnCount() const -

2596 -

2597 Returns the total number of columns in table. -

2598 */ -

2599 -

2600 /*! -

2601 \fn virtual int QAccessibleTableInterface::rowCount() const -

2602 -

2603 Returns the total number of rows in table. -

2604 */ -

2605 -

2606 /*! -

2607 \fn virtual int QAccessibleTableInterface::selectedCellCount() const -

2608 -

2609 Returns the total number of selected cells. -

2610 */ -

2611 -

2612 /*! -

2613 \fn virtual int QAccessibleTableInterface::selectedColumnCount() const -

2614 -

2615 Returns the total number of selected columns. -

2616 */ -

2617 -

2618 /*! -

2619 \fn virtual int QAccessibleTableInterface::selectedRowCount() const -

2620 -

2621 Returns the total number of selected rows. -

2622 */ -

2623 -

2624 /*! -

2625 \fn virtual QString QAccessibleTableInterface::rowDescription(int row) const -

2626 -

2627 Returns the description text of the specified \a row in the table. -

2628 */ -

2629 -

2630 /*! -

2631 \fn virtual QList<int> QAccessibleTableInterface::selectedCells() const -

2632 -

2633 Returns the list of selected cell (by their index as \l QAccessibleInterface::child() accepts). -

2634 */ -

2635 -

2636 /*! -

2637 \fn virtual QList<int> QAccessibleTableInterface::selectedColumns() const -

2638 -

2639 Returns the list of currently selected columns. -

2640 */ -

2641 -

2642 /*! -

2643 \fn virtual QList<int> QAccessibleTableInterface::selectedRows() const -

2644 -

2645 Returns the list of currently selected columns. -

2646 */ -

2647 -

2648 /*! -

2649 \fn virtual QAccessibleInterface *QAccessibleTableInterface::summary() const -

2650 -

2651 Returns a QAccessibleInterface that represents a summary of the table. -

2652 This function may return 0 if no such interface exists. -

2653 */ -

2654 -

2655 /*! -

2656 \fn virtual bool QAccessibleTableInterface::isColumnSelected(int column) const -

2657 -

2658 Returns a boolean value indicating whether the specified \a column is completely selected. -

2659 */ -

2660 -

2661 /*! -

2662 \fn virtual bool QAccessibleTableInterface::isRowSelected(int row) const -

2663 -

2664 Returns a boolean value indicating whether the specified \a row is completely selected. -

2665 */ -

2666 -

2667 /*! -

2668 \fn virtual bool QAccessibleTableInterface::selectRow(int row) -

2669 -

2670 Selects \a row. This function might unselect all previously selected rows. -

2671 Returns \c true if the selection was successful. -

2672 */ -

2673 -

2674 /*! -

2675 \fn virtual bool QAccessibleTableInterface::selectColumn(int column) -

2676 -

2677 Selects \a column. This function might unselect all previously selected columns. -

2678 Returns \c true if the selection was successful. -

2679 */ -

2680 -

2681 /*! -

2682 \fn virtual bool QAccessibleTableInterface::unselectRow(int row) -

2683 -

2684 Unselects \a row, leaving other selected rows selected (if any). -

2685 Returns \c true if the selection was successful. -

2686 */ -

2687 -

2688 /*! -

2689 \fn virtual bool QAccessibleTableInterface::unselectColumn(int column) -

2690 -

2691 Unselects \a column, leaving other selected columns selected (if any). -

2692 Returns \c true if the selection was successful. -

2693 */ -

2694 -

2695 /*! -

2696 \fn virtual void QAccessibleTableInterface::modelChange(QAccessibleTableModelChangeEvent *event) -

2697 -

2698 Informs about a change in the model's layout. -

2699 The \a event contains the details. -

2700 \sa QAccessibleTableModelChangeEvent -

2701 */ -

2702 -

2703 -

2704 /*! -

2705 \class QAccessibleActionInterface -

2706 \ingroup accessibility -

2707 -

2708 \brief The QAccessibleActionInterface class implements support for -

2709 invocable actions in the interface. -

2710 -

2711 Accessible objects should implement the action interface if they support user interaction. -

2712 Usually this interface is implemented by classes that also implement \l QAccessibleInterface. -

2713 -

2714 The supported actions should use the predefined actions offered in this class unless they do not -

2715 fit a predefined action. In that case a custom action can be added. -

2716 -

2717 When subclassing QAccessibleActionInterface you need to provide a list of actionNames which -

2718 is the primary means to discover the available actions. Action names are never localized. -

2719 In order to present actions to the user there are two functions that need to return localized versions -

2720 of the name and give a description of the action. For the predefined action names use -

2721 \l QAccessibleActionInterface::localizedActionName() and \l QAccessibleActionInterface::localizedActionDescription() -

2722 to return their localized counterparts. -

2723 -

2724 In general you should use one of the predefined action names, unless describing an action that does not fit these: -

2725 \table -

2726 \header \li Action name \li Description -

2727 \row \li \l toggleAction() \li toggles the item (checkbox, radio button, switch, ...) -

2728 \row \li \l decreaseAction() \li decrease the value of the accessible (e.g. spinbox) -

2729 \row \li \l increaseAction() \li increase the value of the accessible (e.g. spinbox) -

2730 \row \li \l pressAction() \li press or click or activate the accessible (should correspont to clicking the object with the mouse) -

2731 \row \li \l setFocusAction() \li set the focus to this accessible -

2732 \row \li \l showMenuAction() \li show a context menu, corresponds to right-clicks -

2733 \endtable -

2734 -

2735 In order to invoke the action, \l doAction() is called with an action name. -

2736 -

2737 Most widgets will simply implement \l pressAction(). This is what happens when the widget is activated by -

2738 being clicked, space pressed or similar. -

2739 -

2740 \l{IAccessible2 Specification} -

2741 */ -

2742 -

2743 /*! -

2744 -

2745 Destroys the QAccessibleActionInterface. -

2746 */ -

2747 QAccessibleActionInterface::~QAccessibleActionInterface() -

2748 { -

2749 // must be empty until ### Qt 6 -

2750 } -

2751 -

2752 /*! -

2753 \fn QStringList QAccessibleActionInterface::actionNames() const -

2754 -

2755 Returns the list of actions supported by this accessible object. -

2756 The actions returned should be in preferred order, -

2757 i.e. the action that the user most likely wants to trigger should be returned first, -

2758 while the least likely action should be returned last. -

2759 -

2760 The list does only contain actions that can be invoked. -

2761 It won't return disabled actions, or actions associated with disabled UI controls. -

2762 -

2763 The list can be empty. -

2764 -

2765 Note that this list is not localized. For a localized representation re-implement \l localizedActionName() -

2766 and \l localizedActionDescription() -

2767 -

2768 \sa doAction(), localizedActionName(), localizedActionDescription() -

2769 */ -

2770 -

2771 /*! -

2772 \fn QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const -

2773 -

2774 Returns a localized action name of \a actionName. -

2775 -

2776 For custom actions this function has to be re-implemented. -

2777 When using one of the default names, you can call this function in QAccessibleActionInterface -

2778 to get the localized string. -

2779 -

2780 \sa actionNames(), localizedActionDescription() -

2781 */ -

2782 -

2783 /*! -

2784 \fn QString QAccessibleActionInterface::localizedActionDescription(const QString &actionName) const -

2785 -

2786 Returns a localized action description of the action \a actionName. -

2787 -

2788 When using one of the default names, you can call this function in QAccessibleActionInterface -

2789 to get the localized string. -

2790 -

2791 \sa actionNames(), localizedActionName() -

2792 */ -

2793 -

2794 /*! -

2795 \fn void QAccessibleActionInterface::doAction(const QString &actionName) -

2796 -

2797 Invokes the action specified by \a actionName. -

2798 Note that \a actionName is the non-localized name as returned by \l actionNames() -

2799 This function is usually implemented by calling the same functions -

2800 that other user interaction, such as clicking the object, would trigger. -

2801 -

2802 \sa actionNames() -

2803 */ -

2804 -

2805 /*! -

2806 \fn QStringList QAccessibleActionInterface::keyBindingsForAction(const QString &actionName) const -

2807 -

2808 Returns a list of the keyboard shortcuts available for invoking the action named \a actionName. -

2809 -

2810 This is important to let users learn alternative ways of using the application by emphasizing the keyboard. -

2811 -

2812 \sa actionNames() -

2813 */ -

2814 -

2815 -

2816 struct QAccessibleActionStrings -

2817 { -

2818 QAccessibleActionStrings() : -

2819 pressAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Press"))), -

2820 increaseAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Increase"))), -

2821 decreaseAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Decrease"))), -

2822 showMenuAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "ShowMenu"))), -

2823 setFocusAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "SetFocus"))), -

2824 toggleAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Toggle"))), -

2825 scrollLeftAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Scroll Left"))), -

2826 scrollRightAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Scroll Right"))), -

2827 scrollUpAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Scroll Up"))), -

2828 scrollDownAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Scroll Down"))), -

2829 previousPageAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Previous Page"))), -

2830 nextPageAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Next Page"))) -

2831 {} -

2832 -

2833 const QString pressAction; -

2834 const QString increaseAction; -

2835 const QString decreaseAction; -

2836 const QString showMenuAction; -

2837 const QString setFocusAction; -

2838 const QString toggleAction; -

2839 const QString scrollLeftAction; -

2840 const QString scrollRightAction; -

2841 const QString scrollUpAction; -

2842 const QString scrollDownAction; -

2843 const QString previousPageAction; -

2844 const QString nextPageAction; -

2845 -

2846 QString localizedDescription(const QString &actionName) -

2847 { -

2848 if (actionName == pressAction) -

2849 return QAccessibleActionInterface::tr("Triggers the action"); -

2850 else if (actionName == increaseAction) -

2851 return QAccessibleActionInterface::tr("Increase the value"); -

2852 else if (actionName == decreaseAction) -

2853 return QAccessibleActionInterface::tr("Decrease the value"); -

2854 else if (actionName == showMenuAction) -

2855 return QAccessibleActionInterface::tr("Shows the menu"); -

2856 else if (actionName == setFocusAction) -

2857 return QAccessibleActionInterface::tr("Sets the focus"); -

2858 else if (actionName == toggleAction) -

2859 return QAccessibleActionInterface::tr("Toggles the state"); -

2860 else if (actionName == scrollLeftAction) -

2861 return QAccessibleActionInterface::tr("Scrolls to the left"); -

2862 else if (actionName == scrollRightAction) -

2863 return QAccessibleActionInterface::tr("Scrolls to the right"); -

2864 else if (actionName == scrollUpAction) -

2865 return QAccessibleActionInterface::tr("Scrolls up"); -

2866 else if (actionName == scrollDownAction) -

2867 return QAccessibleActionInterface::tr("Scrolls down"); -

2868 else if (actionName == previousPageAction) -

2869 return QAccessibleActionInterface::tr("Goes back a page"); -

2870 else if (actionName == nextPageAction) -

2871 return QAccessibleActionInterface::tr("Goes to the next page"); -

2872 -

2873 -

2874 return QString(); -

2875 } -

2876 }; -

2877 -

2878 Q_GLOBAL_STATIC(QAccessibleActionStrings, accessibleActionStrings) -

2879 -

2880 QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const -

2881 { -

2882 return QAccessibleActionInterface::tr(qPrintable(actionName)); -

2883 } -

2884 -

2885 QString QAccessibleActionInterface::localizedActionDescription(const QString &actionName) const -

2886 { -

2887 return accessibleActionStrings()->localizedDescription(actionName); -

2888 } -

2889 -

2890 /*! -

2891 Returns the name of the press default action. -

2892 \sa actionNames(), localizedActionName() -

2893 */ -

2894 const QString &QAccessibleActionInterface::pressAction() -

2895 { -

2896 return accessibleActionStrings()->pressAction; -

2897 } -

2898 -

2899 /*! -

2900 Returns the name of the increase default action. -

2901 \sa actionNames(), localizedActionName() -

2902 */ -

2903 const QString &QAccessibleActionInterface::increaseAction() -

2904 { -

2905 return accessibleActionStrings()->increaseAction; -

2906 } -

2907 -

2908 /*! -

2909 Returns the name of the decrease default action. -

2910 \sa actionNames(), localizedActionName() -

2911 */ -

2912 const QString &QAccessibleActionInterface::decreaseAction() -

2913 { -

2914 return accessibleActionStrings()->decreaseAction; -

2915 } -

2916 -

2917 /*! -

2918 Returns the name of the show menu default action. -

2919 \sa actionNames(), localizedActionName() -

2920 */ -

2921 const QString &QAccessibleActionInterface::showMenuAction() -

2922 { -

2923 return accessibleActionStrings()->showMenuAction; -

2924 } -

2925 -

2926 /*! -

2927 Returns the name of the set focus default action. -

2928 \sa actionNames(), localizedActionName() -

2929 */ -

2930 const QString &QAccessibleActionInterface::setFocusAction() -

2931 { -

2932 return accessibleActionStrings()->setFocusAction; -

2933 } -

2934 -

2935 /*! -

2936 Returns the name of the toggle default action. -

2937 \sa actionNames(), localizedActionName() -

2938 */ -

2939 const QString &QAccessibleActionInterface::toggleAction() -

2940 { -

2941 return accessibleActionStrings()->toggleAction; -

2942 } -

2943 -

2944 /*! -

2945 Returns the name of the scroll left default action. -

2946 \sa actionNames(), localizedActionName() -

2947 */ -

2948 QString QAccessibleActionInterface::scrollLeftAction() -

2949 { -

2950 return accessibleActionStrings()->scrollLeftAction; -

2951 } -

2952 -

2953 /*! -

2954 Returns the name of the scroll right default action. -

2955 \sa actionNames(), localizedActionName() -

2956 */ -

2957 QString QAccessibleActionInterface::scrollRightAction() -

2958 { -

2959 return accessibleActionStrings()->scrollRightAction; -

2960 } -

2961 -

2962 /*! -

2963 Returns the name of the scroll up default action. -

2964 \sa actionNames(), localizedActionName() -

2965 */ -

2966 QString QAccessibleActionInterface::scrollUpAction() -

2967 { -

2968 return accessibleActionStrings()->scrollUpAction; -

2969 } -

2970 -

2971 /*! -

2972 Returns the name of the scroll down default action. -

2973 \sa actionNames(), localizedActionName() -

2974 */ -

2975 QString QAccessibleActionInterface::scrollDownAction() -

2976 { -

2977 return accessibleActionStrings()->scrollDownAction; -

2978 } -

2979 -

2980 /*! -

2981 Returns the name of the previous page default action. -

2982 \sa actionNames(), localizedActionName() -

2983 */ -

2984 QString QAccessibleActionInterface::previousPageAction() -

2985 { -

2986 return accessibleActionStrings()->previousPageAction; -

2987 } -

2988 -

2989 /*! -

2990 Returns the name of the next page default action. -

2991 \sa actionNames(), localizedActionName() -

2992 */ -

2993 QString QAccessibleActionInterface::nextPageAction() -

2994 { -

2995 return accessibleActionStrings()->nextPageAction; -

2996 } -

2997 -

2998 /*! \internal */ -

2999 QString qAccessibleLocalizedActionDescription(const QString &actionName) -

3000 { -

3001 return accessibleActionStrings()->localizedDescription(actionName); -

3002 } -

3003 -

3004 #endif // QT_NO_ACCESSIBILITY -

3005 -

3006 QT_END_NAMESPACE -

3007 -

Source code

Switch to Preprocessed file

Generated by Squish Coco Non-Commercial 4.3.0-BETA-master-30-08-2018-4cb69e9