Add implementations of QAIM::sibling in public APIs.
[profile/ivi/qtbase.git] / src / gui / accessible / qaccessible2.cpp
1 /****************************************************************************
2 **
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
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 Digia.  For licensing terms and
14 ** conditions see http://qt.digia.com/licensing.  For further information
15 ** use the contact form at http://qt.digia.com/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 2.1 as published by the Free Software
20 ** Foundation and appearing in the file LICENSE.LGPL included in the
21 ** packaging of this file.  Please review the following information to
22 ** ensure the GNU Lesser General Public License version 2.1 requirements
23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24 **
25 ** In addition, as a special exception, Digia gives you certain additional
26 ** rights.  These rights are described in the Digia Qt LGPL Exception
27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28 **
29 ** GNU General Public License Usage
30 ** Alternatively, this file may be used under the terms of the GNU
31 ** General Public License version 3.0 as published by the Free Software
32 ** Foundation and appearing in the file LICENSE.GPL included in the
33 ** packaging of this file.  Please review the following information to
34 ** ensure the GNU General Public License version 3.0 requirements will be
35 ** met: http://www.gnu.org/copyleft/gpl.html.
36 **
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41
42 #include "qaccessible2.h"
43 #include <QtGui/QGuiApplication>
44 #include "qclipboard.h"
45 #include "qtextboundaryfinder.h"
46
47 #ifndef QT_NO_ACCESSIBILITY
48
49 QT_BEGIN_NAMESPACE
50
51 /*!
52     \namespace QAccessible2
53     \ingroup accessibility
54     \internal
55
56     \brief The QAccessible2 namespace defines constants relating to
57     IAccessible2-based interfaces
58
59     \l{IAccessible2 Specification}
60 */
61
62 /*!
63     \class QAccessibleTextInterface
64     \internal
65     \inmodule QtGui
66
67     \ingroup accessibility
68
69     \brief The QAccessibleTextInterface class implements support for text handling.
70
71     This interface corresponds to the IAccessibleText interface.
72     It should be implemented for widgets that display more text than a plain label.
73     Labels should be represented by only \l QAccessibleInterface
74     and return their text as name (\l QAccessibleInterface::text() with \l QAccessible::Name as type).
75     The QAccessibleTextInterface is typically for text that a screen reader
76     might want to read line by line, and for widgets that support text selection and input.
77     This interface is, for example, implemented for QLineEdit.
78
79     Editable text objects should also implement \l QAccessibleEditableTextInterface.
80     \l{IAccessible2 Specification}
81 */
82
83 /*!
84     \fn QAccessibleTextInterface::~QAccessibleTextInterface()
85     Destructor.
86 */
87
88 /*!
89     \fn void QAccessibleTextInterface::addSelection(int startOffset, int endOffset)
90     Select the text from \a startOffset to \a endOffset.
91     The \a startOffset is the first character that will be selected.
92     The \a endOffset is the first character that will not be selected.
93
94     When the object supports multiple selections (e.g. in a word processor),
95     this adds a new selection, otherwise it replaces the previous selection.
96
97     The selection will be \a endOffset - \a startOffset characters long.
98 */
99
100 /*!
101     \fn QString QAccessibleTextInterface::attributes(int offset, int *startOffset, int *endOffset) const
102 */
103
104 /*!
105     \fn int QAccessibleTextInterface::cursorPosition() const
106
107     Returns the current cursor position.
108 */
109
110 /*!
111     \fn QRect QAccessibleTextInterface::characterRect(int offset) const
112 */
113
114 /*!
115     \fn int QAccessibleTextInterface::selectionCount() const
116
117     Returns the number of selections in this text.
118 */
119
120 /*!
121     \fn int QAccessibleTextInterface::offsetAtPoint(const QPoint &point) const
122 */
123
124 /*!
125     \fn void QAccessibleTextInterface::selection(int selectionIndex, int *startOffset, int *endOffset) const
126 */
127
128 /*!
129     \fn QString QAccessibleTextInterface::text(int startOffset, int endOffset) const
130
131     Returns the text from \a startOffset to \a endOffset.
132     The \a startOffset is the first character that will be returned.
133     The \a endOffset is the first character that will not be returned.
134 */
135
136 /*!
137     Returns the text item of type \a boundaryType that is close to offset \a offset
138     and sets \a startOffset and \a endOffset values to the start and end positions
139     of that item; returns an empty string if there is no such an item.
140     Sets \a startOffset and \a endOffset values to -1 on error.
141 */
142 QString QAccessibleTextInterface::textBeforeOffset(int offset, QAccessible2::BoundaryType boundaryType,
143                                                    int *startOffset, int *endOffset) const
144 {
145     const QString txt = text(0, characterCount());
146
147     if (txt.isEmpty() || offset < 0 || offset > txt.length()) {
148         *startOffset = *endOffset = -1;
149         return QString();
150     }
151     if (offset == 0) {
152         *startOffset = *endOffset = offset;
153         return QString();
154     }
155
156     QTextBoundaryFinder::BoundaryType type;
157     switch (boundaryType) {
158     case QAccessible2::CharBoundary:
159         type = QTextBoundaryFinder::Grapheme;
160         break;
161     case QAccessible2::WordBoundary:
162         type = QTextBoundaryFinder::Word;
163         break;
164     case QAccessible2::SentenceBoundary:
165         type = QTextBoundaryFinder::Sentence;
166         break;
167     default:
168         // in any other case return the whole line
169         *startOffset = 0;
170         *endOffset = txt.length();
171         return txt;
172     }
173
174     // keep behavior in sync with QTextCursor::movePosition()!
175
176     QTextBoundaryFinder boundary(type, txt);
177     boundary.setPosition(offset);
178
179     do {
180         if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem)))
181             break;
182     } while (boundary.toPreviousBoundary() > 0);
183     Q_ASSERT(boundary.position() >= 0);
184     *endOffset = boundary.position();
185
186     while (boundary.toPreviousBoundary() > 0) {
187         if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem)))
188             break;
189     }
190     Q_ASSERT(boundary.position() >= 0);
191     *startOffset = boundary.position();
192
193     return txt.mid(*startOffset, *endOffset - *startOffset);
194 }
195
196 /*!
197     Returns the text item of type \a boundaryType that is right after offset \a offset
198     and sets \a startOffset and \a endOffset values to the start and end positions
199     of that item; returns an empty string if there is no such an item.
200     Sets \a startOffset and \a endOffset values to -1 on error.
201 */
202 QString QAccessibleTextInterface::textAfterOffset(int offset, QAccessible2::BoundaryType boundaryType,
203                                                   int *startOffset, int *endOffset) const
204 {
205     const QString txt = text(0, characterCount());
206
207     if (txt.isEmpty() || offset < 0 || offset > txt.length()) {
208         *startOffset = *endOffset = -1;
209         return QString();
210     }
211     if (offset == txt.length()) {
212         *startOffset = *endOffset = offset;
213         return QString();
214     }
215
216     QTextBoundaryFinder::BoundaryType type;
217     switch (boundaryType) {
218     case QAccessible2::CharBoundary:
219         type = QTextBoundaryFinder::Grapheme;
220         break;
221     case QAccessible2::WordBoundary:
222         type = QTextBoundaryFinder::Word;
223         break;
224     case QAccessible2::SentenceBoundary:
225         type = QTextBoundaryFinder::Sentence;
226         break;
227     default:
228         // in any other case return the whole line
229         *startOffset = 0;
230         *endOffset = txt.length();
231         return txt;
232     }
233
234     // keep behavior in sync with QTextCursor::movePosition()!
235
236     QTextBoundaryFinder boundary(type, txt);
237     boundary.setPosition(offset);
238
239     while (boundary.toNextBoundary() < txt.length()) {
240         if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem)))
241             break;
242     }
243     Q_ASSERT(boundary.position() <= txt.length());
244     *startOffset = boundary.position();
245
246     while (boundary.toNextBoundary() < txt.length()) {
247         if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem)))
248             break;
249     }
250     Q_ASSERT(boundary.position() <= txt.length());
251     *endOffset = boundary.position();
252
253     return txt.mid(*startOffset, *endOffset - *startOffset);
254 }
255
256 /*!
257     Returns the text item of type \a boundaryType at offset \a offset
258     and sets \a startOffset and \a endOffset values to the start and end positions
259     of that item; returns an empty string if there is no such an item.
260     Sets \a startOffset and \a endOffset values to -1 on error.
261 */
262 QString QAccessibleTextInterface::textAtOffset(int offset, QAccessible2::BoundaryType boundaryType,
263                                                int *startOffset, int *endOffset) const
264 {
265     const QString txt = text(0, characterCount());
266
267     if (txt.isEmpty() || offset < 0 || offset > txt.length()) {
268         *startOffset = *endOffset = -1;
269         return QString();
270     }
271     if (offset == txt.length()) {
272         *startOffset = *endOffset = offset;
273         return QString();
274     }
275
276     QTextBoundaryFinder::BoundaryType type;
277     switch (boundaryType) {
278     case QAccessible2::CharBoundary:
279         type = QTextBoundaryFinder::Grapheme;
280         break;
281     case QAccessible2::WordBoundary:
282         type = QTextBoundaryFinder::Word;
283         break;
284     case QAccessible2::SentenceBoundary:
285         type = QTextBoundaryFinder::Sentence;
286         break;
287     default:
288         // in any other case return the whole line
289         *startOffset = 0;
290         *endOffset = txt.length();
291         return txt;
292     }
293
294     // keep behavior in sync with QTextCursor::movePosition()!
295
296     QTextBoundaryFinder boundary(type, txt);
297     boundary.setPosition(offset);
298
299     do {
300         if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem)))
301             break;
302     } while (boundary.toPreviousBoundary() > 0);
303     Q_ASSERT(boundary.position() >= 0);
304     *startOffset = boundary.position();
305
306     while (boundary.toNextBoundary() < txt.length()) {
307         if ((boundary.boundaryReasons() & (QTextBoundaryFinder::StartOfItem | QTextBoundaryFinder::EndOfItem)))
308             break;
309     }
310     Q_ASSERT(boundary.position() <= txt.length());
311     *endOffset = boundary.position();
312
313     return txt.mid(*startOffset, *endOffset - *startOffset);
314 }
315
316 /*!
317     \fn void QAccessibleTextInterface::removeSelection(int selectionIndex)
318
319     Clears the selection with \a index selectionIndex.
320 */
321
322 /*!
323     \fn void QAccessibleTextInterface::setCursorPosition(int position)
324
325     Moves the cursor to \a position.
326 */
327
328 /*!
329     \fn void QAccessibleTextInterface::setSelection(int selectionIndex, int startOffset, int endOffset)
330
331     Set the selection \a selectionIndex to the range from \a startOffset to \a endOffset.
332
333     \sa addSelection(), removeSelection()
334 */
335
336 /*!
337     \fn int QAccessibleTextInterface::characterCount() const
338
339     Returns the length of the text (total size including spaces).
340 */
341
342 /*!
343     \fn void QAccessibleTextInterface::scrollToSubstring(int startIndex, int endIndex)
344
345     Ensures that the text between \a startIndex and \a endIndex is visible.
346 */
347
348 /*!
349     \class QAccessibleEditableTextInterface
350     \ingroup accessibility
351     \inmodule QtGui
352     \internal
353
354     \brief The QAccessibleEditableTextInterface class implements support for objects with editable text.
355
356     When implementing this interface you will almost certainly also want to implement \l QAccessibleTextInterface.
357
358     \sa QAccessibleInterface
359
360     \l{IAccessible2 Specification}
361 */
362
363 /*!
364     \fn QAccessibleEditableTextInterface::~QAccessibleEditableTextInterface()
365
366
367 */
368
369 /*!
370     \fn void QAccessibleEditableTextInterface::deleteText(int startOffset, int endOffset)
371
372     Deletes the text from \a startOffset to \a endOffset.
373 */
374
375 /*!
376     \fn void QAccessibleEditableTextInterface::insertText(int offset, const QString &text)
377
378     Inserts \a text at position \a offset.
379 */
380
381 /*!
382     \fn void QAccessibleEditableTextInterface::replaceText(int startOffset, int endOffset, const QString &text)
383
384     Removes the text from \a startOffset to \a endOffset and instead inserts \a text.
385 */
386
387 /*!
388     \class QAccessibleValueInterface
389     \inmodule QtGui
390     \ingroup accessibility
391     \internal
392
393     \brief The QAccessibleValueInterface class implements support for objects that manipulate a value.
394
395     This interface should be implemented by accessible objects that represent a value.
396     Examples are spinner, slider, dial and scroll bar.
397
398     Instead of forcing the user to deal with the individual parts of the widgets, this interface
399     gives an easier approach to the kind of widget it represents.
400
401     Usually this interface is implemented by classes that also implement \l QAccessibleInterface.
402
403     \l{IAccessible2 Specification}
404 */
405
406 /*!
407     \fn QAccessibleValueInterface::~QAccessibleValueInterface()
408     Destructor.
409 */
410
411 /*!
412     \fn QVariant QAccessibleValueInterface::currentValue() const
413
414     Returns the current value of the widget. This is usually a double or int.
415     \sa setCurrentValue()
416 */
417
418 /*!
419     \fn void QAccessibleValueInterface::setCurrentValue(const QVariant &value)
420
421     Sets the \a value. If the desired \a value is out of the range of permissible values,
422     this call will be ignored.
423
424     \sa currentValue(), minimumValue(), maximumValue()
425 */
426
427 /*!
428     \fn QVariant QAccessibleValueInterface::maximumValue() const
429
430     Returns the maximum value this object accepts.
431     \sa minimumValue(), currentValue()
432 */
433
434 /*!
435     \fn QVariant QAccessibleValueInterface::minimumValue() const
436
437     Returns the minimum value this object accepts.
438     \sa maximumValue(), currentValue()
439 */
440
441 /*!
442     \class QAccessibleImageInterface
443     \inmodule QtGui
444     \ingroup accessibility
445     \internal
446     \preliminary
447
448     \brief The QAccessibleImageInterface class implements support for
449     the IAccessibleImage interface.
450
451     \l{IAccessible2 Specification}
452 */
453
454 /*!
455     \class QAccessibleTableCellInterface
456     \inmodule QtGui
457     \ingroup accessibility
458     \internal
459
460     \brief The QAccessibleTableCellInterface class implements support for
461     the IAccessibleTable2 Cell interface.
462
463     \l{IAccessible2 Specification}
464 */
465
466 /*!
467     \class QAccessibleTableInterface
468     \ingroup accessibility
469     \internal
470
471     \brief The QAccessibleTableInterface class implements support for
472     the IAccessibleTable2 interface.
473
474     \l{IAccessible2 Specification}
475 */
476
477
478 /*!
479     \class QAccessibleActionInterface
480     \ingroup accessibility
481     \internal
482
483     \brief The QAccessibleActionInterface class implements support for
484     invocable actions in the interface.
485
486     Accessible objects should implement the action interface if they support user interaction.
487     Usually this interface is implemented by classes that also implement \l QAccessibleInterface.
488
489     The supported actions should use the predefined actions offered in this class unless they do not
490     fit a predefined action. In that case a custom action can be added.
491
492     When subclassing QAccessibleActionInterface you need to provide a list of actionNames which
493     is the primary means to discover the available actions. Action names are never localized.
494     In order to present actions to the user there are two functions that need to return localized versions
495     of the name and give a description of the action. For the predefined action names use
496     \l QAccessibleActionInterface::localizedActionName() and \l QAccessibleActionInterface::localizedActionDescription()
497     to return their localized counterparts.
498
499     In general you should use one of the predefined action names, unless describing an action that does not fit these:
500     \table
501     \header \li Action name         \li Description
502     \row    \li \l toggleAction()   \li toggles the item (checkbox, radio button, switch, ...)
503     \row    \li \l decreaseAction() \li decrease the value of the accessible (e.g. spinbox)
504     \row    \li \l increaseAction() \li increase the value of the accessible (e.g. spinbox)
505     \row    \li \l pressAction()    \li press or click or activate the accessible (should correspont to clicking the object with the mouse)
506     \row    \li \l setFocusAction() \li set the focus to this accessible
507     \row    \li \l showMenuAction() \li show a context menu, corresponds to right-clicks
508     \endtable
509
510     In order to invoke the action, \l doAction() is called with an action name.
511
512     Most widgets will simply implement \l pressAction(). This is what happens when the widget is activated by
513     being clicked, space pressed or similar.
514
515     \l{IAccessible2 Specification}
516 */
517
518 /*!
519     \fn QStringList QAccessibleActionInterface::actionNames() const
520
521     Returns the list of actions supported by this accessible object.
522     The actions returned should be in preferred order,
523     i.e. the action that the user most likely wants to trigger should be returned first,
524     while the least likely action should be returned last.
525
526     The list does only contain actions that can be invoked.
527     It won't return disabled actions, or actions associated with disabled UI controls.
528
529     The list can be empty.
530
531     Note that this list is not localized. For a localized representation re-implement \l localizedActionName()
532     and \l localizedActionDescription()
533
534     \sa doAction(), localizedActionName(), localizedActionDescription()
535 */
536
537 /*!
538     \fn QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const
539
540     Returns a localized action name of \a actionName.
541
542     For custom actions this function has to be re-implemented.
543     When using one of the default names, you can call this function in QAccessibleActionInterface
544     to get the localized string.
545
546     \sa actionNames(), localizedActionDescription()
547 */
548
549 /*!
550     \fn QString QAccessibleActionInterface::localizedActionDescription(const QString &actionName) const
551
552     Returns a localized action description of the action \a actionName.
553
554     When using one of the default names, you can call this function in QAccessibleActionInterface
555     to get the localized string.
556
557     \sa actionNames(), localizedActionName()
558 */
559
560 /*!
561     \fn void QAccessibleActionInterface::doAction(const QString &actionName)
562
563     Invokes the action specified by \a actionName.
564     Note that \a actionName is the non-localized name as returned by \l actionNames()
565     This function is usually implemented by calling the same functions
566     that other user interaction, such as clicking the object, would trigger.
567
568     \sa actionNames()
569 */
570
571 /*!
572     \fn QStringList QAccessibleActionInterface::keyBindingsForAction(const QString &actionName) const
573
574     Returns a list of the keyboard shortcuts available for invoking the action named \a actionName.
575
576     This is important to let users learn alternative ways of using the application by emphasizing the keyboard.
577
578     \sa actionNames()
579 */
580
581
582 struct QAccessibleActionStrings
583 {
584     QAccessibleActionStrings() :
585         pressAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Press"))),
586         increaseAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Increase"))),
587         decreaseAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Decrease"))),
588         showMenuAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "ShowMenu"))),
589         setFocusAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "SetFocus"))),
590         toggleAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Toggle"))) {}
591
592     const QString pressAction;
593     const QString increaseAction;
594     const QString decreaseAction;
595     const QString showMenuAction;
596     const QString setFocusAction;
597     const QString toggleAction;
598 };
599
600 Q_GLOBAL_STATIC(QAccessibleActionStrings, accessibleActionStrings)
601
602 QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const
603 {
604     return QAccessibleActionInterface::tr(qPrintable(actionName));
605 }
606
607 QString QAccessibleActionInterface::localizedActionDescription(const QString &actionName) const
608 {
609     const QAccessibleActionStrings *strings = accessibleActionStrings();
610     if (actionName == strings->pressAction)
611         return tr("Triggers the action");
612     else if (actionName == strings->increaseAction)
613         return tr("Increase the value");
614     else if (actionName == strings->decreaseAction)
615         return tr("Decrease the value");
616     else if (actionName == strings->showMenuAction)
617         return tr("Shows the menu");
618     else if (actionName == strings->setFocusAction)
619         return tr("Sets the focus");
620     else if (actionName == strings->toggleAction)
621         return tr("Toggles the state");
622
623     return QString();
624 }
625
626 /*!
627     Returns the name of the press default action.
628     \sa actionNames(), localizedActionName()
629   */
630 const QString &QAccessibleActionInterface::pressAction()
631 {
632     return accessibleActionStrings()->pressAction;
633 }
634
635 /*!
636     Returns the name of the increase default action.
637     \sa actionNames(), localizedActionName()
638   */
639 const QString &QAccessibleActionInterface::increaseAction()
640 {
641     return accessibleActionStrings()->increaseAction;
642 }
643
644 /*!
645     Returns the name of the decrease default action.
646     \sa actionNames(), localizedActionName()
647   */
648 const QString &QAccessibleActionInterface::decreaseAction()
649 {
650     return accessibleActionStrings()->decreaseAction;
651 }
652
653 /*!
654     Returns the name of the show menu default action.
655     \sa actionNames(), localizedActionName()
656   */
657 const QString &QAccessibleActionInterface::showMenuAction()
658 {
659     return accessibleActionStrings()->showMenuAction;
660 }
661
662 /*!
663     Returns the name of the set focus default action.
664     \sa actionNames(), localizedActionName()
665   */
666 const QString &QAccessibleActionInterface::setFocusAction()
667 {
668     return accessibleActionStrings()->setFocusAction;
669 }
670
671 /*!
672     Returns the name of the toggle default action.
673     \sa actionNames(), localizedActionName()
674   */
675 const QString &QAccessibleActionInterface::toggleAction()
676 {
677     return accessibleActionStrings()->toggleAction;
678 }
679
680 QT_END_NAMESPACE
681
682 #endif // QT_NO_ACCESSIBILITY