1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the QtGui module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qaccessible2.h"
43 #include <QtGui/QGuiApplication>
44 #include "qclipboard.h"
45 #include "qtextboundaryfinder.h"
47 #ifndef QT_NO_ACCESSIBILITY
52 \namespace QAccessible2
53 \ingroup accessibility
55 \brief The QAccessible2 namespace defines constants relating to
56 IAccessible2-based interfaces
58 \link http://www.linux-foundation.org/en/Accessibility/IAccessible2 IAccessible2 Specification \endlink
62 \class QAccessibleTextInterface
64 \ingroup accessibility
66 \brief The QAccessibleTextInterface class implements support for text handling.
68 This interface corresponds to the IAccessibleText interface.
69 It should be implemented for widgets that display more text than a plain label.
70 Labels should be represented by only \l QAccessibleInterface
71 and return their text as name (\l QAccessibleInterface::text() with \l QAccessible::Name as type).
72 The QAccessibleTextInterface is typically for text that a screen reader
73 might want to read line by line, and for widgets that support text selection and input.
74 This interface is, for example, implemented for QLineEdit.
76 Editable text objects should also implement \l QAccessibleEditableTextInterface.
77 \link http://www.linux-foundation.org/en/Accessibility/IAccessible2 IAccessible2 Specification \endlink
81 \fn QAccessibleTextInterface::~QAccessibleTextInterface()
86 \fn void QAccessibleTextInterface::addSelection(int startOffset, int endOffset)
87 Select the text from \a startOffset to \a endOffset.
88 The \a startOffset is the first character that will be selected.
89 The \a endOffset is the first character that will not be selected.
91 When the object supports multiple selections (e.g. in a word processor),
92 this adds a new selection, otherwise it replaces the previous selection.
94 The selection will be \a endOffset - \a startOffset characters long.
98 \fn QString QAccessibleTextInterface::attributes(int offset, int *startOffset, int *endOffset) const
102 \fn int QAccessibleTextInterface::cursorPosition() const
104 Returns the current cursor position.
108 \fn QRect QAccessibleTextInterface::characterRect(int offset, QAccessible2::CoordinateType coordType) const
112 \fn int QAccessibleTextInterface::selectionCount() const
114 Returns the number of selections in this text.
118 \fn int QAccessibleTextInterface::offsetAtPoint(const QPoint &point, QAccessible2::CoordinateType coordType) const
122 \fn void QAccessibleTextInterface::selection(int selectionIndex, int *startOffset, int *endOffset) const
126 \fn QString QAccessibleTextInterface::text(int startOffset, int endOffset) const
128 Returns the text from \a startOffset to \a endOffset.
129 The \a startOffset is the first character that will be returned.
130 The \a endOffset is the first character that will not be returned.
134 \fn QString QAccessibleTextInterface::textBeforeOffset (int offset, QAccessible2::BoundaryType boundaryType,
135 int *startOffset, int *endOffset) const
139 \fn QString QAccessibleTextInterface::textAfterOffset(int offset, QAccessible2::BoundaryType boundaryType,
140 int *startOffset, int *endOffset) const
144 \fn QString QAccessibleTextInterface::textAtOffset(int offset, QAccessible2::BoundaryType boundaryType,
145 int *startOffset, int *endOffset) const
149 \fn void QAccessibleTextInterface::removeSelection(int selectionIndex)
151 Clears the selection with \a index selectionIndex.
155 \fn void QAccessibleTextInterface::setCursorPosition(int position)
157 Moves the cursor to \a position.
161 \fn void QAccessibleTextInterface::setSelection(int selectionIndex, int startOffset, int endOffset)
163 Set the selection \a selectionIndex to the range from \a startOffset to \a endOffset.
165 \sa addSelection(), removeSelection()
169 \fn int QAccessibleTextInterface::characterCount() const
171 Returns the lenght of the text (total size including spaces).
175 \fn void QAccessibleTextInterface::scrollToSubstring(int startIndex, int endIndex)
177 Ensures that the text between \a startIndex and \a endIndex is visible.
181 \class QAccessibleEditableTextInterface
182 \ingroup accessibility
184 \brief The QAccessibleEditableTextInterface class implements support for objects with editable text.
186 When implementing this interface you will almost certainly also want to implement \l QAccessibleTextInterface.
188 Since this interface can be implemented by means of the normal \l QAccessibleTextInterface,
189 \l QAccessibleSimpleEditableTextInterface provides a convenience implementation of this interface.
190 Consider inheriting \l QAccessibleSimpleEditableTextInterface instead.
192 \sa QAccessibleInterface
194 \link http://www.linux-foundation.org/en/Accessibility/IAccessible2 IAccessible2 Specification \endlink
198 \fn QAccessibleEditableTextInterface::~QAccessibleEditableTextInterface()
204 \fn void QAccessibleEditableTextInterface::copyText(int startOffset, int endOffset) const
206 Copies the text from \a startOffset to \a endOffset to the system clip board.
207 The \a startOffset is the first character that will be copied.
208 The \a endOffset is the first character that will not be copied.
212 \fn void QAccessibleEditableTextInterface::deleteText(int startOffset, int endOffset)
214 Deletes the text from \a startOffset to \a endOffset.
218 \fn void QAccessibleEditableTextInterface::insertText(int offset, const QString &text)
220 Inserts \a text at position \a offset.
224 \fn void QAccessibleEditableTextInterface::cutText(int startOffset, int endOffset)
226 Removes the text from \a startOffset to \a endOffset and puts it in the system clip board.
230 \fn void QAccessibleEditableTextInterface::pasteText(int offset)
232 Pastes text from the system clip board at the position \a offset.
236 \fn void QAccessibleEditableTextInterface::replaceText(int startOffset, int endOffset, const QString &text)
238 Removes the text from \a startOffset to \a endOffset and instead inserts \a text.
242 \fn void QAccessibleEditableTextInterface::setAttributes(int startOffset, int endOffset, const QString &attributes)
244 \sa QAccessibleTextInterface::attributes()
248 \class QAccessibleSimpleEditableTextInterface
249 \ingroup accessibility
251 \brief The QAccessibleSimpleEditableTextInterface class is a convenience class for
252 text-based widgets. It can be inherited instead of \l QAccessibleEditableTextInterface.
254 \sa QAccessibleInterface, QAccessibleEditableTextInterface
256 \link http://www.linux-foundation.org/en/Accessibility/IAccessible2 IAccessible2 Specification \endlink
260 \class QAccessibleValueInterface
261 \ingroup accessibility
263 \brief The QAccessibleValueInterface class implements support for objects that manipulate a value.
265 This interface should be implemented by accessible objects that represent a value.
266 Examples are spinner, slider, dial and scroll bar.
268 Instead of forcing the user to deal with the individual parts of the widgets, this interface
269 gives an easier approach to the kind of widget it represents.
271 Usually this interface is implemented by classes that also implement \l QAccessibleInterface.
273 \link http://www.linux-foundation.org/en/Accessibility/IAccessible2 IAccessible2 Specification \endlink
277 \fn QAccessibleValueInterface::~QAccessibleValueInterface()
282 \fn QVariant QAccessibleValueInterface::currentValue() const
284 Returns the current value of the widget. This is usually a double or int.
285 \sa setCurrentValue()
289 \fn void QAccessibleValueInterface::setCurrentValue(const QVariant &value)
291 Sets the \a value. If the desired \a value is out of the range of permissible values,
292 this call will be ignored.
294 \sa currentValue(), minimumValue(), maximumValue()
298 \fn QVariant QAccessibleValueInterface::maximumValue() const
300 Returns the maximum value this object accepts.
301 \sa minimumValue(), currentValue()
305 \fn QVariant QAccessibleValueInterface::minimumValue() const
307 Returns the minimum value this object accepts.
308 \sa maximumValue(), currentValue()
312 \class QAccessibleImageInterface
313 \ingroup accessibility
317 \brief The QAccessibleImageInterface class implements support for
318 the IAccessibleImage interface.
320 \link http://www.linux-foundation.org/en/Accessibility/IAccessible2 IAccessible2 Specification \endlink
324 \class QAccessibleTableCellInterface
325 \ingroup accessibility
327 \brief The QAccessibleTableCellInterface class implements support for
328 the IAccessibleTable2 Cell interface.
330 \link http://www.linux-foundation.org/en/Accessibility/IAccessible2 IAccessible2 Specification \endlink
334 \class QAccessibleTableInterface
335 \ingroup accessibility
337 \brief The QAccessibleTableInterface class implements support for
338 the IAccessibleTable2 interface.
340 \link http://www.linux-foundation.org/en/Accessibility/IAccessible2 IAccessible2 Specification \endlink
345 \class QAccessibleActionInterface
346 \ingroup accessibility
348 \brief The QAccessibleActionInterface class implements support for
349 invocable actions in the interface.
351 Accessible objects should implement the action interface if they support user interaction.
352 Usually this interface is implemented by classes that also implement \l QAccessibleInterface.
354 The supported actions should use the predefined actions offered in this class unless they do not
355 fit a predefined action. In that case a custom action can be added.
357 When subclassing QAccessibleActionInterface you need to provide a list of actionNames which
358 is the primary means to discover the available actions. Action names are never localized.
359 In order to present actions to the user there are two functions that need to return localized versions
360 of the name and give a description of the action. For the predefined action names use
361 \l QAccessibleActionInterface::localizedActionName() and \l QAccessibleActionInterface::localizedActionDescription()
362 to return their localized counterparts.
364 In general you should use one of the predefined action names, unless describing an action that does not fit these:
366 \header \o Action name \o Description
367 \row \o \l checkAction() \o checks the item (checkbox, radio button, ...)
368 \row \o \l decreaseAction() \o decrease the value of the accessible (e.g. spinbox)
369 \row \o \l increaseAction() \o increase the value of the accessible (e.g. spinbox)
370 \row \o \l pressAction() \o press or click or activate the accessible (should correspont to clicking the object with the mouse)
371 \row \o \l setFocusAction() \o set the focus to this accessible
372 \row \o \l showMenuAction() \o show a context menu, corresponds to right-clicks
373 \row \o \l uncheckAction() \o uncheck the item (checkbox, radio button, ...)
376 In order to invoke the action, \l doAction() is called with an action name.
378 Most widgets will simply implement \l pressAction(). This is what happens when the widget is activated by
379 being clicked, space pressed or similar.
381 \link http://www.linux-foundation.org/en/Accessibility/IAccessible2 IAccessible2 Specification \endlink
385 \fn QStringList QAccessibleActionInterface::actionNames() const
387 Returns the list of actions supported by this accessible object.
388 The actions returned should be in preferred order,
389 i.e. the action that the user most likely wants to trigger should be returned first,
390 while the least likely action should be returned last.
392 The list does only contain actions that can be invoked.
393 It won't return disabled actions, or actions associated with disabled UI controls.
395 The list can be empty.
397 Note that this list is not localized. For a localized representation re-implement \l localizedActionName()
398 and \l localizedActionDescription()
400 \sa doAction(), localizedActionName(), localizedActionDescription()
404 \fn QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const
406 Returns a localized action name of \a actionName.
408 For custom actions this function has to be re-implemented.
409 When using one of the default names, you can call this function in QAccessibleActionInterface
410 to get the localized string.
412 \sa actionNames(), localizedActionDescription()
416 \fn QString QAccessibleActionInterface::localizedActionDescription(const QString &actionName) const
418 Returns a localized action description of the action \a actionName.
420 When using one of the default names, you can call this function in QAccessibleActionInterface
421 to get the localized string.
423 \sa actionNames(), localizedActionName()
427 \fn void QAccessibleActionInterface::doAction(const QString &actionName)
429 Invokes the action specified by \a actionName.
430 Note that \a actionName is the non-localized name as returned by \l actionNames()
431 This function is usually implemented by calling the same functions
432 that other user interaction, such as clicking the object, would trigger.
438 \fn QStringList QAccessibleActionInterface::keyBindingsForAction(const QString &actionName) const
440 Returns a list of the keyboard shortcuts available for invoking the action named \a actionName.
442 This is important to let users learn alternative ways of using the application by emphasizing the keyboard.
448 struct QAccessibleActionStrings
450 QAccessibleActionStrings() :
451 pressAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Press"))),
452 increaseAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Increase"))),
453 decreaseAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Decrease"))),
454 showMenuAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "ShowMenu"))),
455 setFocusAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "SetFocus"))),
456 checkAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Check"))),
457 uncheckAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Uncheck"))) {}
459 const QString pressAction;
460 const QString increaseAction;
461 const QString decreaseAction;
462 const QString showMenuAction;
463 const QString setFocusAction;
464 const QString checkAction;
465 const QString uncheckAction;
468 Q_GLOBAL_STATIC(QAccessibleActionStrings, accessibleActionStrings)
470 QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const
472 return QAccessibleActionInterface::tr(qPrintable(actionName));
475 QString QAccessibleActionInterface::localizedActionDescription(const QString &actionName) const
477 const QAccessibleActionStrings *strings = accessibleActionStrings();
478 if (actionName == strings->pressAction)
479 return tr("Triggers the action");
480 else if (actionName == strings->increaseAction)
481 return tr("Increase the value");
482 else if (actionName == strings->decreaseAction)
483 return tr("Decrease the value");
484 else if (actionName == strings->showMenuAction)
485 return tr("Shows the menu");
486 else if (actionName == strings->setFocusAction)
487 return tr("Sets the focus");
488 else if (actionName == strings->checkAction)
489 return tr("Checks the checkbox");
490 else if (actionName == strings->uncheckAction)
491 return tr("Unchecks the checkbox");
497 Returns the name of the press default action.
498 \sa actionNames(), localizedActionName()
500 const QString &QAccessibleActionInterface::pressAction()
502 return accessibleActionStrings()->pressAction;
506 Returns the name of the increase default action.
507 \sa actionNames(), localizedActionName()
509 const QString &QAccessibleActionInterface::increaseAction()
511 return accessibleActionStrings()->increaseAction;
515 Returns the name of the decrease default action.
516 \sa actionNames(), localizedActionName()
518 const QString &QAccessibleActionInterface::decreaseAction()
520 return accessibleActionStrings()->decreaseAction;
524 Returns the name of the show menu default action.
525 \sa actionNames(), localizedActionName()
527 const QString &QAccessibleActionInterface::showMenuAction()
529 return accessibleActionStrings()->showMenuAction;
533 Returns the name of the set focus default action.
534 \sa actionNames(), localizedActionName()
536 const QString &QAccessibleActionInterface::setFocusAction()
538 return accessibleActionStrings()->setFocusAction;
542 Returns the name of the check default action.
543 \sa actionNames(), localizedActionName()
545 const QString &QAccessibleActionInterface::checkAction()
547 return accessibleActionStrings()->checkAction;
551 Returns the name of the uncheck default action.
552 \sa actionNames(), localizedActionName()
554 const QString &QAccessibleActionInterface::uncheckAction()
556 return accessibleActionStrings()->uncheckAction;
562 QString Q_GUI_EXPORT qTextBeforeOffsetFromString(int offset, QAccessible2::BoundaryType boundaryType,
563 int *startOffset, int *endOffset, const QString& text)
565 QTextBoundaryFinder::BoundaryType type;
566 switch (boundaryType) {
567 case QAccessible2::CharBoundary:
568 type = QTextBoundaryFinder::Grapheme;
570 case QAccessible2::WordBoundary:
571 type = QTextBoundaryFinder::Word;
573 case QAccessible2::SentenceBoundary:
574 type = QTextBoundaryFinder::Sentence;
577 // in any other case return the whole line
579 *endOffset = text.length();
583 QTextBoundaryFinder boundary(type, text);
584 boundary.setPosition(offset);
586 if (!boundary.isAtBoundary()) {
587 boundary.toPreviousBoundary();
589 boundary.toPreviousBoundary();
590 *startOffset = boundary.position();
591 boundary.toNextBoundary();
592 *endOffset = boundary.position();
594 return text.mid(*startOffset, *endOffset - *startOffset);
600 QString Q_GUI_EXPORT qTextAfterOffsetFromString(int offset, QAccessible2::BoundaryType boundaryType,
601 int *startOffset, int *endOffset, const QString& text)
603 QTextBoundaryFinder::BoundaryType type;
604 switch (boundaryType) {
605 case QAccessible2::CharBoundary:
606 type = QTextBoundaryFinder::Grapheme;
608 case QAccessible2::WordBoundary:
609 type = QTextBoundaryFinder::Word;
611 case QAccessible2::SentenceBoundary:
612 type = QTextBoundaryFinder::Sentence;
615 // in any other case return the whole line
617 *endOffset = text.length();
621 QTextBoundaryFinder boundary(type, text);
622 boundary.setPosition(offset);
624 boundary.toNextBoundary();
625 *startOffset = boundary.position();
626 boundary.toNextBoundary();
627 *endOffset = boundary.position();
629 return text.mid(*startOffset, *endOffset - *startOffset);
635 QString Q_GUI_EXPORT qTextAtOffsetFromString(int offset, QAccessible2::BoundaryType boundaryType,
636 int *startOffset, int *endOffset, const QString& text)
638 QTextBoundaryFinder::BoundaryType type;
639 switch (boundaryType) {
640 case QAccessible2::CharBoundary:
641 type = QTextBoundaryFinder::Grapheme;
643 case QAccessible2::WordBoundary:
644 type = QTextBoundaryFinder::Word;
646 case QAccessible2::SentenceBoundary:
647 type = QTextBoundaryFinder::Sentence;
650 // in any other case return the whole line
652 *endOffset = text.length();
656 QTextBoundaryFinder boundary(type, text);
657 boundary.setPosition(offset);
659 if (!boundary.isAtBoundary()) {
660 boundary.toPreviousBoundary();
662 *startOffset = boundary.position();
663 boundary.toNextBoundary();
664 *endOffset = boundary.position();
666 return text.mid(*startOffset, *endOffset - *startOffset);
669 QAccessibleSimpleEditableTextInterface::QAccessibleSimpleEditableTextInterface(
670 QAccessibleInterface *accessibleInterface)
671 : iface(accessibleInterface)
676 #ifndef QT_NO_CLIPBOARD
677 static QString textForRange(QAccessibleInterface *iface, int startOffset, int endOffset)
679 return iface->text(QAccessible::Value).mid(startOffset, endOffset - startOffset);
684 void QAccessibleSimpleEditableTextInterface::copyText(int startOffset, int endOffset) const
686 #ifdef QT_NO_CLIPBOARD
687 Q_UNUSED(startOffset);
690 QGuiApplication::clipboard()->setText(textForRange(iface, startOffset, endOffset));
695 void QAccessibleSimpleEditableTextInterface::deleteText(int startOffset, int endOffset)
697 QString txt = iface->text(QAccessible::Value);
698 txt.remove(startOffset, endOffset - startOffset);
699 iface->setText(QAccessible::Value, txt);
703 void QAccessibleSimpleEditableTextInterface::insertText(int offset, const QString &text)
705 QString txt = iface->text(QAccessible::Value);
706 txt.insert(offset, text);
707 iface->setText(QAccessible::Value, txt);
711 void QAccessibleSimpleEditableTextInterface::cutText(int startOffset, int endOffset)
713 #ifdef QT_NO_CLIPBOARD
714 Q_UNUSED(startOffset);
717 QString sub = textForRange(iface, startOffset, endOffset);
718 deleteText(startOffset, endOffset);
719 QGuiApplication::clipboard()->setText(sub);
724 void QAccessibleSimpleEditableTextInterface::pasteText(int offset)
726 #ifdef QT_NO_CLIPBOARD
729 QString txt = iface->text(QAccessible::Value);
730 txt.insert(offset, QGuiApplication::clipboard()->text());
731 iface->setText(QAccessible::Value, txt);
736 void QAccessibleSimpleEditableTextInterface::replaceText(int startOffset, int endOffset, const QString &text)
738 QString txt = iface->text(QAccessible::Value);
739 txt.replace(startOffset, endOffset - startOffset, text);
740 iface->setText(QAccessible::Value, txt);
745 #endif // QT_NO_ACCESSIBILITY