summaryrefslogtreecommitdiffstats
path: root/src/gui/accessible/qaccessible.cpp
diff options
context:
space:
mode:
Diffstat (limited to 'src/gui/accessible/qaccessible.cpp')
-rw-r--r--src/gui/accessible/qaccessible.cpp284
1 files changed, 224 insertions, 60 deletions
diff --git a/src/gui/accessible/qaccessible.cpp b/src/gui/accessible/qaccessible.cpp
index 954c8564f0..1d70598c39 100644
--- a/src/gui/accessible/qaccessible.cpp
+++ b/src/gui/accessible/qaccessible.cpp
@@ -97,6 +97,15 @@ QT_BEGIN_NAMESPACE
Accessibility, and the Unix/X11 AT-SPI standard. Other backends
can be supported using QAccessibleBridge.
+ In the Unix/X11 AT-SPI implementation, applications become accessible
+ when two conditions are met:
+ \list
+ \li org.a11y.Status.IsEnabled DBus property is true
+ \li org.a11y.Status.ScreenReaderEnabled DBus property is true
+ \endlist
+ An alternative to setting the DBus AT-SPI properties is to set
+ the QT_LINUX_ACCESSIBILITY_ALWAYS_ON environment variable.
+
In addition to QAccessible's static functions, Qt offers one
generic interface, QAccessibleInterface, that can be used to wrap
all widgets and objects (e.g., QPushButton). This single
@@ -167,7 +176,7 @@ QT_BEGIN_NAMESPACE
\value readOnly The object can usually be edited, but is explicitly set to read-only.
\value selectable The object is selectable.
\value selectableText The object has text which can be selected. This is different from selectable which refers to the object's children.
- \value selected The object is selected.
+ \value selected The object is selected, this is independent of text selection.
\value selfVoicing The object describes itself through speech or sound.
\value sizeable The object can be resized, e.g. top-level windows.
\value summaryElement The object summarizes the state of the window and should be treated with priority.
@@ -310,19 +319,24 @@ QT_BEGIN_NAMESPACE
\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.
\value Client The client area in a window.
\value Clock A clock displaying time.
+ \value ColorChooser A dialog that lets the user choose a color.
\value Column A column of cells, usually within a table.
\value ColumnHeader A header for a column of data.
\value ComboBox A list of choices that the user can select from.
+ \value ComplementaryContent A part of the document or web page that is complementary to the main content, usually a landmark (see WAI-ARIA).
\value Cursor An object that represents the mouse cursor.
\value Desktop The object represents the desktop or workspace.
\value Dial An object that represents a dial or knob.
\value Dialog A dialog box.
- \value Document A document window, usually in an MDI environment.
- \value EditableText Editable text
+ \value Document A document, for example in an office application.
+ \value EditableText Editable text such as a line or text edit.
\value Equation An object that represents a mathematical equation.
+ \value Footer A footer in a page (usually in documents).
+ \value Form A web form containing controls.
\value Graphic A graphic or picture, e.g. an icon.
\value Grip A grip that the user can drag to change the size of widgets.
\value Grouping An object that represents a logical grouping of other objects.
+ \value Heading A heading in a document.
\value HelpBalloon An object that displays help in a separate, short lived window.
\value HotkeyField A hotkey field that allows the user to enter a key sequence.
\value Indicator An indicator that represents a current value or item.
@@ -333,8 +347,10 @@ QT_BEGIN_NAMESPACE
\value MenuBar A menu bar from which menus are opened by the user.
\value MenuItem An item in a menu or menu bar.
\value NoRole The object has no role. This usually indicates an invalid object.
+ \value Note A section whose content is parenthetic or ancillary to the main content of the resource.
\value PageTab A page tab that the user can select to switch to a different page in a dialog.
\value PageTabList A list of page tabs.
+ \value Paragraph A paragraph of text (usually found in documents).
\value Pane A generic container.
\value PopupMenu A menu which lists options that the user can select to perform an action.
\value ProgressBar The object displays the progress of an operation in progress.
@@ -344,6 +360,7 @@ QT_BEGIN_NAMESPACE
\value Row A row of cells, usually within a table.
\value RowHeader A header for a row of data.
\value ScrollBar A scroll bar, which allows the user to scroll the visible area.
+ \value Section A section (in a document).
\value Separator A separator that divides space into logical areas.
\value Slider A slider that allows the user to select a value within a given range.
\value Sound An object that represents a sound.
@@ -359,6 +376,7 @@ QT_BEGIN_NAMESPACE
\value Tree A list of items in a tree structure.
\value TreeItem An item in a tree structure.
\value UserRole The first value to be used for user defined roles.
+ \value WebDocument HTML document, usually in a browser.
\value Whitespace Blank space between other objects.
\value Window A top level window.
*/
@@ -453,9 +471,11 @@ Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader,
#endif
#endif
+// FIXME turn this into one global static struct
Q_GLOBAL_STATIC(QList<QAccessible::InterfaceFactory>, qAccessibleFactories)
typedef QHash<QString, QAccessiblePlugin*> QAccessiblePluginsHash;
-Q_GLOBAL_STATIC(QAccessiblePluginsHash, qAccessiblePlugins);
+Q_GLOBAL_STATIC(QAccessiblePluginsHash, qAccessiblePlugins)
+Q_GLOBAL_STATIC(QList<QAccessible::ActivationObserver *>, qAccessibleActivationObservers)
QAccessible::UpdateHandler QAccessible::updateHandler = 0;
QAccessible::RootObjectHandler QAccessible::rootObjectHandler = 0;
@@ -492,6 +512,7 @@ void QAccessible::cleanup()
static void qAccessibleCleanup()
{
+ qAccessibleActivationObservers()->clear();
qAccessibleFactories()->clear();
}
@@ -592,6 +613,44 @@ QAccessible::RootObjectHandler QAccessible::installRootObjectHandler(RootObjectH
}
/*!
+ \class QAccessible::ActivationObserver
+ \internal
+
+ Interface to listen to activation or deactivation of the accessibility framework.
+ \sa installActivationObserver()
+*/
+
+/*!
+ \internal
+
+ Install \a observer to get notified of activation or deactivation (global accessibility has been enabled or disabled).
+*/
+void QAccessible::installActivationObserver(QAccessible::ActivationObserver *observer)
+{
+ if (!observer)
+ return;
+
+ if (!cleanupAdded) {
+ qAddPostRoutine(qAccessibleCleanup);
+ cleanupAdded = true;
+ }
+ if (qAccessibleActivationObservers()->contains(observer))
+ return;
+ qAccessibleActivationObservers()->append(observer);
+}
+
+/*!
+ \internal
+
+ Remove an \a observer to no longer get notified of state changes.
+ \sa installActivationObserver()
+*/
+void QAccessible::removeActivationObserver(ActivationObserver *observer)
+{
+ qAccessibleActivationObservers()->removeAll(observer);
+}
+
+/*!
If a QAccessibleInterface implementation exists for the given \a object,
this function returns a pointer to the implementation; otherwise it
returns 0.
@@ -744,6 +803,15 @@ bool QAccessible::isActive()
return false;
}
+/*!
+ \internal
+*/
+void QAccessible::setActive(bool active)
+{
+ for (int i = 0; i < qAccessibleActivationObservers()->count() ;++i)
+ qAccessibleActivationObservers()->at(i)->accessibilityActiveChanged(active);
+}
+
/*!
Sets the root object of the accessible objects of this application
@@ -793,16 +861,20 @@ void QAccessible::setRootObject(QObject *object)
*/
void QAccessible::updateAccessibility(QAccessibleEvent *event)
{
- if (!isActive())
+ // NOTE: Querying for the accessibleInterface below will result in
+ // resolving and caching the interface, which in some cases will
+ // cache the wrong information as updateAccessibility is called
+ // during construction of widgets. If you see cases where the
+ // cache seems wrong, this call is "to blame", but the code that
+ // caches dynamic data should be updated to handle change events.
+ if (!isActive() || !event->accessibleInterface())
return;
#ifndef QT_NO_ACCESSIBILITY
if (event->type() == QAccessible::TableModelChanged) {
- Q_ASSERT(event->object());
- if (QAccessibleInterface *iface = QAccessible::queryAccessibleInterface(event->object())) {
- if (iface->tableInterface())
- iface->tableInterface()->modelChange(static_cast<QAccessibleTableModelChangeEvent*>(event));
- }
+ QAccessibleInterface *iface = event->accessibleInterface();
+ if (iface && iface->tableInterface())
+ iface->tableInterface()->modelChange(static_cast<QAccessibleTableModelChangeEvent*>(event));
}
if (updateHandler) {
@@ -1845,24 +1917,68 @@ QDebug operator<<(QDebug d, const QAccessibleEvent &ev)
*/
/*!
+ \internal
+ Helper for finding line breaks in textBeforeOffset/textAtOffset/textAfterOffset.
+ \a beforeAtAfter is the line we look for. -1 for before, 0 for at and 1 for after.
+*/
+static QString textLineBoundary(int beforeAtAfter, const QString &text, int offset, int *startOffset, int *endOffset)
+{
+ Q_ASSERT(beforeAtAfter >= -1 && beforeAtAfter <= 1);
+ Q_ASSERT(*startOffset == -1 && *endOffset == -1);
+ int length = text.length();
+ Q_ASSERT(offset >= 0 && offset <= length);
+
+ // move offset into the right range (if asking for line before or after
+ if (beforeAtAfter == 1) {
+ offset = text.indexOf(QChar::LineFeed, qMin(offset, length - 1));
+ if (offset < 0)
+ return QString(); // after the last line comes nothing
+ ++offset; // move after the newline
+ } else if (beforeAtAfter == -1) {
+ offset = text.lastIndexOf(QChar::LineFeed, qMax(offset - 1, 0));
+ if (offset < 0)
+ return QString(); // before first line comes nothing
+ }
+
+ if (offset > 0)
+ *startOffset = text.lastIndexOf(QChar::LineFeed, offset - 1);
+ ++*startOffset; // move to the char after the newline (0 if lastIndexOf returned -1)
+
+ *endOffset = text.indexOf(QChar::LineFeed, qMin(offset, length - 1)) + 1; // include newline char
+ if (*endOffset <= 0 || *endOffset > length)
+ *endOffset = length; // if the text doesn't end with a newline it ends at length
+
+ return text.mid(*startOffset, *endOffset - *startOffset);
+}
+
+/*!
Returns the text item of type \a boundaryType that is close to offset \a offset
and sets \a startOffset and \a endOffset values to the start and end positions
of that item; returns an empty string if there is no such an item.
Sets \a startOffset and \a endOffset values to -1 on error.
+
+ This default implementation is provided for small text edits. A word processor or
+ text editor should provide their own efficient implementations. This function makes no
+ distinction between paragraphs and lines.
+
+ \note this function can not take the cursor position into account. By convention
+ an \a offset of -2 means that this function should use the cursor position as offset.
+ Thus an offset of -2 must be converted to the cursor position before calling this
+ function.
+ An offset of -1 is used for the text length and custom implementations of this function
+ have to return the result as if the length was passed in as offset.
*/
QString QAccessibleTextInterface::textBeforeOffset(int offset, QAccessible::TextBoundaryType boundaryType,
int *startOffset, int *endOffset) const
{
const QString txt = text(0, characterCount());
- if (txt.isEmpty() || offset < 0 || offset > txt.length()) {
- *startOffset = *endOffset = -1;
- return QString();
- }
- if (offset == 0) {
- *startOffset = *endOffset = offset;
+ if (offset == -1)
+ offset = txt.length();
+
+ *startOffset = *endOffset = -1;
+ if (txt.isEmpty() || offset <= 0 || offset > txt.length())
return QString();
- }
QTextBoundaryFinder::BoundaryType type;
switch (boundaryType) {
@@ -1875,11 +1991,13 @@ QString QAccessibleTextInterface::textBeforeOffset(int offset, QAccessible::Text
case QAccessible::SentenceBoundary:
type = QTextBoundaryFinder::Sentence;
break;
- default:
- // in any other case return the whole line
- *startOffset = 0;
- *endOffset = txt.length();
- return txt;
+ case QAccessible::LineBoundary:
+ case QAccessible::ParagraphBoundary:
+ // Lines can not use QTextBoundaryFinder since Line there means any potential line-break.
+ return textLineBoundary(-1, txt, offset, startOffset, endOffset);
+ case QAccessible::NoBoundary:
+ // return empty, this function currently only supports single lines, so there can be no line before
+ return QString();
}
// keep behavior in sync with QTextCursor::movePosition()!
@@ -1909,20 +2027,29 @@ QString QAccessibleTextInterface::textBeforeOffset(int offset, QAccessible::Text
and sets \a startOffset and \a endOffset values to the start and end positions
of that item; returns an empty string if there is no such an item.
Sets \a startOffset and \a endOffset values to -1 on error.
+
+ This default implementation is provided for small text edits. A word processor or
+ text editor should provide their own efficient implementations. This function makes no
+ distinction between paragraphs and lines.
+
+ \note this function can not take the cursor position into account. By convention
+ an \a offset of -2 means that this function should use the cursor position as offset.
+ Thus an offset of -2 must be converted to the cursor position before calling this
+ function.
+ An offset of -1 is used for the text length and custom implementations of this function
+ have to return the result as if the length was passed in as offset.
*/
QString QAccessibleTextInterface::textAfterOffset(int offset, QAccessible::TextBoundaryType boundaryType,
int *startOffset, int *endOffset) const
{
const QString txt = text(0, characterCount());
- if (txt.isEmpty() || offset < 0 || offset > txt.length()) {
- *startOffset = *endOffset = -1;
- return QString();
- }
- if (offset == txt.length()) {
- *startOffset = *endOffset = offset;
+ if (offset == -1)
+ offset = txt.length();
+
+ *startOffset = *endOffset = -1;
+ if (txt.isEmpty() || offset < 0 || offset >= txt.length())
return QString();
- }
QTextBoundaryFinder::BoundaryType type;
switch (boundaryType) {
@@ -1935,11 +2062,13 @@ QString QAccessibleTextInterface::textAfterOffset(int offset, QAccessible::TextB
case QAccessible::SentenceBoundary:
type = QTextBoundaryFinder::Sentence;
break;
- default:
- // in any other case return the whole line
- *startOffset = 0;
- *endOffset = txt.length();
- return txt;
+ case QAccessible::LineBoundary:
+ case QAccessible::ParagraphBoundary:
+ // Lines can not use QTextBoundaryFinder since Line there means any potential line-break.
+ return textLineBoundary(1, txt, offset, startOffset, endOffset);
+ case QAccessible::NoBoundary:
+ // return empty, this function currently only supports single lines, so there can be no line after
+ return QString();
}
// keep behavior in sync with QTextCursor::movePosition()!
@@ -1947,20 +2076,31 @@ QString QAccessibleTextInterface::textAfterOffset(int offset, QAccessible::TextB
QTextBoundaryFinder boundary(type, txt);
boundary.setPosition(offset);
- while (boundary.toNextBoundary() < txt.length()) {
+ while (true) {
+ int toNext = boundary.toNextBoundary();
if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem)))
break;
+ if (toNext < 0 || toNext >= txt.length())
+ break; // not found, the boundary might not exist
}
Q_ASSERT(boundary.position() <= txt.length());
*startOffset = boundary.position();
- while (boundary.toNextBoundary() < txt.length()) {
+ while (true) {
+ int toNext = boundary.toNextBoundary();
if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem)))
break;
+ if (toNext < 0 || toNext >= txt.length())
+ break; // not found, the boundary might not exist
}
Q_ASSERT(boundary.position() <= txt.length());
*endOffset = boundary.position();
+ if ((*startOffset == -1) || (*endOffset == -1) || (*startOffset == *endOffset)) {
+ *endOffset = -1;
+ *startOffset = -1;
+ }
+
return txt.mid(*startOffset, *endOffset - *startOffset);
}
@@ -1969,20 +2109,32 @@ QString QAccessibleTextInterface::textAfterOffset(int offset, QAccessible::TextB
and sets \a startOffset and \a endOffset values to the start and end positions
of that item; returns an empty string if there is no such an item.
Sets \a startOffset and \a endOffset values to -1 on error.
+
+ This default implementation is provided for small text edits. A word processor or
+ text editor should provide their own efficient implementations. This function makes no
+ distinction between paragraphs and lines.
+
+ \note this function can not take the cursor position into account. By convention
+ an \a offset of -2 means that this function should use the cursor position as offset.
+ Thus an offset of -2 must be converted to the cursor position before calling this
+ function.
+ An offset of -1 is used for the text length and custom implementations of this function
+ have to return the result as if the length was passed in as offset.
*/
QString QAccessibleTextInterface::textAtOffset(int offset, QAccessible::TextBoundaryType boundaryType,
int *startOffset, int *endOffset) const
{
const QString txt = text(0, characterCount());
- if (txt.isEmpty() || offset < 0 || offset > txt.length()) {
- *startOffset = *endOffset = -1;
+ if (offset == -1)
+ offset = txt.length();
+
+ *startOffset = *endOffset = -1;
+ if (txt.isEmpty() || offset < 0 || offset > txt.length())
return QString();
- }
- if (offset == txt.length()) {
- *startOffset = *endOffset = offset;
+
+ if (offset == txt.length() && boundaryType == QAccessible::CharBoundary)
return QString();
- }
QTextBoundaryFinder::BoundaryType type;
switch (boundaryType) {
@@ -1995,8 +2147,11 @@ QString QAccessibleTextInterface::textAtOffset(int offset, QAccessible::TextBoun
case QAccessible::SentenceBoundary:
type = QTextBoundaryFinder::Sentence;
break;
- default:
- // in any other case return the whole line
+ case QAccessible::LineBoundary:
+ case QAccessible::ParagraphBoundary:
+ // Lines can not use QTextBoundaryFinder since Line there means any potential line-break.
+ return textLineBoundary(0, txt, offset, startOffset, endOffset);
+ case QAccessible::NoBoundary:
*startOffset = 0;
*endOffset = txt.length();
return txt;
@@ -2060,7 +2215,6 @@ QString QAccessibleTextInterface::textAtOffset(int offset, QAccessible::TextBoun
\class QAccessibleEditableTextInterface
\ingroup accessibility
\inmodule QtGui
- \internal
\brief The QAccessibleEditableTextInterface class implements support for objects with editable text.
@@ -2478,6 +2632,23 @@ struct QAccessibleActionStrings
const QString showMenuAction;
const QString setFocusAction;
const QString toggleAction;
+
+ QString localizedDescription(const QString &actionName)
+ {
+ if (actionName == pressAction)
+ return QAccessibleActionInterface::tr("Triggers the action");
+ else if (actionName == increaseAction)
+ return QAccessibleActionInterface::tr("Increase the value");
+ else if (actionName == decreaseAction)
+ return QAccessibleActionInterface::tr("Decrease the value");
+ else if (actionName == showMenuAction)
+ return QAccessibleActionInterface::tr("Shows the menu");
+ else if (actionName == setFocusAction)
+ return QAccessibleActionInterface::tr("Sets the focus");
+ else if (actionName == toggleAction)
+ return QAccessibleActionInterface::tr("Toggles the state");
+ return QString();
+ }
};
Q_GLOBAL_STATIC(QAccessibleActionStrings, accessibleActionStrings)
@@ -2489,21 +2660,7 @@ QString QAccessibleActionInterface::localizedActionName(const QString &actionNam
QString QAccessibleActionInterface::localizedActionDescription(const QString &actionName) const
{
- const QAccessibleActionStrings *strings = accessibleActionStrings();
- if (actionName == strings->pressAction)
- return tr("Triggers the action");
- else if (actionName == strings->increaseAction)
- return tr("Increase the value");
- else if (actionName == strings->decreaseAction)
- return tr("Decrease the value");
- else if (actionName == strings->showMenuAction)
- return tr("Shows the menu");
- else if (actionName == strings->setFocusAction)
- return tr("Sets the focus");
- else if (actionName == strings->toggleAction)
- return tr("Toggles the state");
-
- return QString();
+ return accessibleActionStrings()->localizedDescription(actionName);
}
/*!
@@ -2560,6 +2717,13 @@ const QString &QAccessibleActionInterface::toggleAction()
return accessibleActionStrings()->toggleAction;
}
+/*! \internal */
+QString qAccessibleLocalizedActionDescription(const QString &actionName)
+{
+ return accessibleActionStrings()->localizedDescription(actionName);
+}
+
+
#endif
QT_END_NAMESPACE