Update spec to build Qt 5.0
[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     \fn QVariant QAccessibleValueInterface::minimumStepSize() const
443
444     Returns the minimum step size for the accessible.
445     This is the smalles increment that makes sense when changing the value.
446     When programatically changing the value it should always be a multiple
447     of the minimum step size.
448
449     Some tools use this value even when the setCurrentValue does not
450     perform any action. Progress bars for example are read-only but
451     should return their range divided by 100.
452 */
453
454 /*!
455     \class QAccessibleImageInterface
456     \inmodule QtGui
457     \ingroup accessibility
458     \internal
459     \preliminary
460
461     \brief The QAccessibleImageInterface class implements support for
462     the IAccessibleImage interface.
463
464     \l{IAccessible2 Specification}
465 */
466
467 /*!
468     \class QAccessibleTableCellInterface
469     \inmodule QtGui
470     \ingroup accessibility
471     \internal
472
473     \brief The QAccessibleTableCellInterface class implements support for
474     the IAccessibleTable2 Cell interface.
475
476     \l{IAccessible2 Specification}
477 */
478
479 /*!
480     \class QAccessibleTableInterface
481     \ingroup accessibility
482     \internal
483
484     \brief The QAccessibleTableInterface class implements support for
485     the IAccessibleTable2 interface.
486
487     \l{IAccessible2 Specification}
488 */
489
490
491 /*!
492     \class QAccessibleActionInterface
493     \ingroup accessibility
494     \internal
495
496     \brief The QAccessibleActionInterface class implements support for
497     invocable actions in the interface.
498
499     Accessible objects should implement the action interface if they support user interaction.
500     Usually this interface is implemented by classes that also implement \l QAccessibleInterface.
501
502     The supported actions should use the predefined actions offered in this class unless they do not
503     fit a predefined action. In that case a custom action can be added.
504
505     When subclassing QAccessibleActionInterface you need to provide a list of actionNames which
506     is the primary means to discover the available actions. Action names are never localized.
507     In order to present actions to the user there are two functions that need to return localized versions
508     of the name and give a description of the action. For the predefined action names use
509     \l QAccessibleActionInterface::localizedActionName() and \l QAccessibleActionInterface::localizedActionDescription()
510     to return their localized counterparts.
511
512     In general you should use one of the predefined action names, unless describing an action that does not fit these:
513     \table
514     \header \li Action name         \li Description
515     \row    \li \l toggleAction()   \li toggles the item (checkbox, radio button, switch, ...)
516     \row    \li \l decreaseAction() \li decrease the value of the accessible (e.g. spinbox)
517     \row    \li \l increaseAction() \li increase the value of the accessible (e.g. spinbox)
518     \row    \li \l pressAction()    \li press or click or activate the accessible (should correspont to clicking the object with the mouse)
519     \row    \li \l setFocusAction() \li set the focus to this accessible
520     \row    \li \l showMenuAction() \li show a context menu, corresponds to right-clicks
521     \endtable
522
523     In order to invoke the action, \l doAction() is called with an action name.
524
525     Most widgets will simply implement \l pressAction(). This is what happens when the widget is activated by
526     being clicked, space pressed or similar.
527
528     \l{IAccessible2 Specification}
529 */
530
531 /*!
532     \fn QStringList QAccessibleActionInterface::actionNames() const
533
534     Returns the list of actions supported by this accessible object.
535     The actions returned should be in preferred order,
536     i.e. the action that the user most likely wants to trigger should be returned first,
537     while the least likely action should be returned last.
538
539     The list does only contain actions that can be invoked.
540     It won't return disabled actions, or actions associated with disabled UI controls.
541
542     The list can be empty.
543
544     Note that this list is not localized. For a localized representation re-implement \l localizedActionName()
545     and \l localizedActionDescription()
546
547     \sa doAction(), localizedActionName(), localizedActionDescription()
548 */
549
550 /*!
551     \fn QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const
552
553     Returns a localized action name of \a actionName.
554
555     For custom actions this function has to be re-implemented.
556     When using one of the default names, you can call this function in QAccessibleActionInterface
557     to get the localized string.
558
559     \sa actionNames(), localizedActionDescription()
560 */
561
562 /*!
563     \fn QString QAccessibleActionInterface::localizedActionDescription(const QString &actionName) const
564
565     Returns a localized action description of the action \a actionName.
566
567     When using one of the default names, you can call this function in QAccessibleActionInterface
568     to get the localized string.
569
570     \sa actionNames(), localizedActionName()
571 */
572
573 /*!
574     \fn void QAccessibleActionInterface::doAction(const QString &actionName)
575
576     Invokes the action specified by \a actionName.
577     Note that \a actionName is the non-localized name as returned by \l actionNames()
578     This function is usually implemented by calling the same functions
579     that other user interaction, such as clicking the object, would trigger.
580
581     \sa actionNames()
582 */
583
584 /*!
585     \fn QStringList QAccessibleActionInterface::keyBindingsForAction(const QString &actionName) const
586
587     Returns a list of the keyboard shortcuts available for invoking the action named \a actionName.
588
589     This is important to let users learn alternative ways of using the application by emphasizing the keyboard.
590
591     \sa actionNames()
592 */
593
594
595 struct QAccessibleActionStrings
596 {
597     QAccessibleActionStrings() :
598         pressAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Press"))),
599         increaseAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Increase"))),
600         decreaseAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Decrease"))),
601         showMenuAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "ShowMenu"))),
602         setFocusAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "SetFocus"))),
603         toggleAction(QStringLiteral(QT_TRANSLATE_NOOP("QAccessibleActionInterface", "Toggle"))) {}
604
605     const QString pressAction;
606     const QString increaseAction;
607     const QString decreaseAction;
608     const QString showMenuAction;
609     const QString setFocusAction;
610     const QString toggleAction;
611 };
612
613 Q_GLOBAL_STATIC(QAccessibleActionStrings, accessibleActionStrings)
614
615 QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const
616 {
617     return QAccessibleActionInterface::tr(qPrintable(actionName));
618 }
619
620 QString QAccessibleActionInterface::localizedActionDescription(const QString &actionName) const
621 {
622     const QAccessibleActionStrings *strings = accessibleActionStrings();
623     if (actionName == strings->pressAction)
624         return tr("Triggers the action");
625     else if (actionName == strings->increaseAction)
626         return tr("Increase the value");
627     else if (actionName == strings->decreaseAction)
628         return tr("Decrease the value");
629     else if (actionName == strings->showMenuAction)
630         return tr("Shows the menu");
631     else if (actionName == strings->setFocusAction)
632         return tr("Sets the focus");
633     else if (actionName == strings->toggleAction)
634         return tr("Toggles the state");
635
636     return QString();
637 }
638
639 /*!
640     Returns the name of the press default action.
641     \sa actionNames(), localizedActionName()
642   */
643 const QString &QAccessibleActionInterface::pressAction()
644 {
645     return accessibleActionStrings()->pressAction;
646 }
647
648 /*!
649     Returns the name of the increase default action.
650     \sa actionNames(), localizedActionName()
651   */
652 const QString &QAccessibleActionInterface::increaseAction()
653 {
654     return accessibleActionStrings()->increaseAction;
655 }
656
657 /*!
658     Returns the name of the decrease default action.
659     \sa actionNames(), localizedActionName()
660   */
661 const QString &QAccessibleActionInterface::decreaseAction()
662 {
663     return accessibleActionStrings()->decreaseAction;
664 }
665
666 /*!
667     Returns the name of the show menu default action.
668     \sa actionNames(), localizedActionName()
669   */
670 const QString &QAccessibleActionInterface::showMenuAction()
671 {
672     return accessibleActionStrings()->showMenuAction;
673 }
674
675 /*!
676     Returns the name of the set focus default action.
677     \sa actionNames(), localizedActionName()
678   */
679 const QString &QAccessibleActionInterface::setFocusAction()
680 {
681     return accessibleActionStrings()->setFocusAction;
682 }
683
684 /*!
685     Returns the name of the toggle default action.
686     \sa actionNames(), localizedActionName()
687   */
688 const QString &QAccessibleActionInterface::toggleAction()
689 {
690     return accessibleActionStrings()->toggleAction;
691 }
692
693 QT_END_NAMESPACE
694
695 #endif // QT_NO_ACCESSIBILITY