Refactor QAccessibleActionInterface.

Some refinements done by Jan-Arve Sæther.

Change-Id: I99195b3c7273316cfa9c46e451924bbcfddd11a9
Reviewed-by: Jan-Arve Sæther <jan-arve.saether@nokia.com>

6 files changed, 135 insertions, 138 deletions

diff --git a/src/gui/accessible/qaccessible.cpp b/src/gui/accessible/qaccessible.cpp
index 2785ff5db4..172bd7f8e3 100644
--- a/src/gui/accessible/qaccessible.cpp
+++ b/src/gui/accessible/qaccessible.cpp
@@ -1061,39 +1061,6 @@ QVector<QPair<QAccessibleInterface*, QAccessible::Relation> > QAccessibleInterfa
 */
 
 /*!
-    \fn int QAccessibleInterface::userActionCount(int child) const
-
-    Returns the number of custom actions of the object, or of the
-    object's child if \a child is not 0.
-
-    The \c Action type enumerates predefined actions: these
-    are not included in the returned value.
-
-    \sa actionText(), doAction()
-*/
-
-/*!
-    \fn QString QAccessibleInterface::actionText(int action, Text t, int child) const
-
-    Returns the text property \a t of the action \a action supported by
-    the object, or of the object's child if \a child is not 0.
-
-    \sa text(), userActionCount()
-*/
-
-/*!
-    \fn bool QAccessibleInterface::doAction(int action, int child, const QVariantList &params)
-
-    Asks the object, or the object's \a child if \a child is not 0, to
-    execute \a action using the parameters, \a params. Returns true if
-    the action could be executed; otherwise returns false.
-
-    \a action can be a predefined or a custom action.
-
-    \sa userActionCount(), actionText()
-*/
-
-/*!
     \fn QColor QAccessibleInterface::backgroundColor()
     \internal
 */
diff --git a/src/gui/accessible/qaccessible.h b/src/gui/accessible/qaccessible.h
index 2673765f6b..b0c334c90b 100644
--- a/src/gui/accessible/qaccessible.h
+++ b/src/gui/accessible/qaccessible.h
@@ -389,11 +389,6 @@ public:
     virtual Role role(int child = 0) const = 0;
     virtual State state(int child = 0) const = 0;
 
-    // action
-    virtual int userActionCount(int child = 0) const = 0;
-    virtual QString actionText(int action, Text t, int child = 0) const = 0;
-    virtual bool doAction(int action, int child = 0, const QVariantList &params = QVariantList()) = 0;
-
     virtual QVariant invokeMethod(Method method, int child = 0,
                           const QVariantList &params = QVariantList());
 
diff --git a/src/gui/accessible/qaccessible2.cpp b/src/gui/accessible/qaccessible2.cpp
index aef7e1af75..b33d9755c5 100644
--- a/src/gui/accessible/qaccessible2.cpp
+++ b/src/gui/accessible/qaccessible2.cpp
@@ -110,29 +110,142 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \class QAccessibleActionInterface
+    \class QAccessibleImageInterface
     \ingroup accessibility
     \internal
     \preliminary
 
-    \brief The QAccessibleActionInterface class implements support for
-    the IAccessibleAction interface.
+    \brief The QAccessibleImageInterface class implements support for
+    the IAccessibleImage interface.
 
     \link http://www.linux-foundation.org/en/Accessibility/IAccessible2 IAccessible2 Specification \endlink
 */
 
 /*!
-    \class QAccessibleImageInterface
+    \class QAccessibleActionInterface
     \ingroup accessibility
     \internal
     \preliminary
 
-    \brief The QAccessibleImageInterface class implements support for
-    the IAccessibleImage interface.
+    \brief The QAccessibleActionInterface class implements support for
+    invocable actions in the interface.
+
+    Each accessible should implement the action interface if it supports any actions.
+    The supported actions should adhere to the naming scheme inside the QAccessible2 namespace.
+    Custom actions can be added.
+
+    When subclassing QAccessibleActionInterface you need to provide a list of actionNames which
+    is the primary means to discover the available actions. Action names are never localized.
+    In order to present actions to the user there are two functions that need to return localized versions
+    of the name and give a description of the action.
+
+    In order to invoke the action, doAction is called with an action name.
+
+    Most widgets will simply implement the PressAction. This is what happens when the widget is activated by
+    being clicked on, space pressed or similar.
 
     \link http://www.linux-foundation.org/en/Accessibility/IAccessible2 IAccessible2 Specification \endlink
 */
 
+/*!
+    \fn QStringList QAccessibleActionInterface::actionNames() const
+
+    Returns a list of valid actions. The actions returned should be in preferred order,
+    i.e. the action that the user most likely wants to trigger should be returned first,
+    while the least likely action should be returned last.
+
+    The list does only contain actions that *can* be invoked. Therefore it,
+    won't return disabled actions, or actions associated with disabled UI
+    controls.
+
+    The list can also be empty.
+
+    \sa localizedActionName(), doAction()
+*/
+
+/*!
+    \fn QString QAccessibleActionInterface::localizedActionName(const QString &name) const
+
+    Returns a localized action name of \a name.
+
+    \sa actionNames(), localizedActionDescription()
+*/
+
+/*!
+    \fn QString QAccessibleActionInterface::localizedActionDescription(const QString &name) const
+
+    Returns a localized action description of \a name.
+
+    This is what should be presented to the user. The actionNames should always
+    be untranslated to make them consistent for screen readers.
+
+    \sa actionNames(), localizedActionName()
+*/
+
+/*!
+    \fn void QAccessibleActionInterface::doAction(const QString &actionName) const
+
+    Invokes the action specified by \a actionName
+
+    \sa actionNames()
+*/
+
+/*!
+    \fn QStringList QAccessibleActionInterface::keyBindingsForAction(const QString &actionName) const
+
+    Returns a list of the keyboard shortcuts available for invoking the action named \a actionName
+
+    \sa actionNames()
+*/
+
+const QString QAccessibleActionInterface::PressAction = QStringLiteral("Press");
+const QString QAccessibleActionInterface::IncreaseAction = QStringLiteral("Increase");
+const QString QAccessibleActionInterface::DecreaseAction = QStringLiteral("Decrease");
+const QString QAccessibleActionInterface::ShowMenuAction = QStringLiteral("ShowMenu");
+const QString QAccessibleActionInterface::SetFocusAction = QStringLiteral("SetFocus");
+const QString QAccessibleActionInterface::CheckAction = QStringLiteral("Check");
+const QString QAccessibleActionInterface::UncheckAction = QStringLiteral("Uncheck");
+
+QString QAccessibleActionInterface::localizedActionName(const QString &actionName) const
+{
+    if (actionName == PressAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "Press");
+    else if (actionName == IncreaseAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "Increase");
+    else if (actionName == DecreaseAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "Decrease");
+    else if (actionName == ShowMenuAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "ShowMenu");
+    else if (actionName == SetFocusAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "SetFocus");
+    else if (actionName == CheckAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "Check");
+    else if (actionName == UncheckAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "Uncheck");
+
+    return QString();
+}
+
+QString QAccessibleActionInterface::localizedActionDescription(const QString &actionName) const
+{
+    if (actionName == PressAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "Triggers the action");
+    else if (actionName == IncreaseAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "Increase the value");
+    else if (actionName == DecreaseAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "Decrease the value");
+    else if (actionName == ShowMenuAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "Shows the menu");
+    else if (actionName == SetFocusAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "Sets the focus");
+    else if (actionName == CheckAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "Checks the checkbox");
+    else if (actionName == UncheckAction)
+        return QCoreApplication::translate("QAccessibleActionInterface", "Unchecks the checkbox");
+
+    return QString();
+}
+
 
 /*!
   \internal
diff --git a/src/gui/accessible/qaccessible2.h b/src/gui/accessible/qaccessible2.h
index a609defdcc..d2a46a737c 100644
--- a/src/gui/accessible/qaccessible2.h
+++ b/src/gui/accessible/qaccessible2.h
@@ -326,17 +326,24 @@ friend class QAbstractItemView;
 friend class QAbstractItemViewPrivate;
 };
 
-class Q_GUI_EXPORT QAccessibleActionInterface : public QAccessible2Interface
+class Q_GUI_EXPORT QAccessibleActionInterface: public QAccessible2Interface
 {
 public:
     inline QAccessible2Interface *qAccessibleActionCastHelper() { return this; }
 
-    virtual int actionCount() = 0;
-    virtual void doAction(int actionIndex) = 0;
-    virtual QString localizedDescription(int actionIndex) = 0;
-    virtual QString name(int actionIndex) = 0;
-    virtual QString localizedName(int actionIndex) = 0;
-    virtual QStringList keyBindings(int actionIndex) = 0;
+    virtual QStringList actionNames() const = 0;
+    virtual QString localizedActionName(const QString &name) const;
+    virtual QString localizedActionDescription(const QString &name) const;
+    virtual void doAction(const QString &actionName) = 0;
+    virtual QStringList keyBindingsForAction(const QString &actionName) const = 0;
+
+    static const QString PressAction;
+    static const QString IncreaseAction;
+    static const QString DecreaseAction;
+    static const QString ShowMenuAction;
+    static const QString SetFocusAction;
+    static const QString CheckAction;
+    static const QString UncheckAction;
 };
 
 class Q_GUI_EXPORT QAccessibleImageInterface : public QAccessible2Interface
diff --git a/src/gui/accessible/qaccessibleobject.cpp b/src/gui/accessible/qaccessibleobject.cpp
index f7d6c3c72b..da68579809 100644
--- a/src/gui/accessible/qaccessibleobject.cpp
+++ b/src/gui/accessible/qaccessibleobject.cpp
@@ -154,44 +154,6 @@ void QAccessibleObject::setText(Text, int, const QString &)
 {
 }
 
-/*! \reimp */
-int QAccessibleObject::userActionCount(int) const
-{
-    return 0;
-}
-
-/*! \reimp */
-bool QAccessibleObject::doAction(int, int, const QVariantList &)
-{
-    return false;
-}
-
-static const char * const action_text[][5] =
-{
-    // Name, Description, Value, Help, Accelerator
-    { "Press", "", "", "", "Space" },
-    { "SetFocus", "Passes focus to this widget", "", "", "" },
-    { "Increase", "", "", "", "" },
-    { "Decrease", "", "", "", "" },
-    { "Accept", "", "", "", "" },
-    { "Cancel", "", "", "", "" },
-    { "Select", "", "", "", "" },
-    { "ClearSelection", "", "", "", "" },
-    { "RemoveSelection", "", "", "", "" },
-    { "ExtendSelection", "", "", "", "" },
-    { "AddToSelection", "", "", "", "" }
-};
-
-/*! \reimp */
-QString QAccessibleObject::actionText(int action, Text t, int child) const
-{
-    if (child || action > FirstStandardAction || action < LastStandardAction || t > Accelerator)
-        return QString();
-
-    return QString::fromLatin1(action_text[-(action - FirstStandardAction)][t]);
-}
-
-
 /*!
     \class QAccessibleApplication
     \brief The QAccessibleApplication class implements the QAccessibleInterface for QApplication.
@@ -353,45 +315,6 @@ QAccessible::State QAccessibleApplication::state(int) const
     return QGuiApplication::activeWindow() ? Focused : Normal;
 }
 
-/*! \reimp */
-int QAccessibleApplication::userActionCount(int) const
-{
-    return 1;
-}
-
-/*! \reimp */
-bool QAccessibleApplication::doAction(int action, int child, const QVariantList &param)
-{
-    //###Move to IA2 action interface at some point to get rid of the ambiguity.
-    /*  //### what is action == 0 and action == 1 ?????
-    if (action == 0 || action == 1) {
-        QWindow *w = 0;
-        w = QGuiApplication::activeWindow();
-        if (!w)
-            w = topLevelWindows().at(0);
-        if (!w)
-            return false;
-        w->requestActivateWindow();
-        return true;
-    }
-    */
-    return QAccessibleObject::doAction(action, child, param);
-}
-
-/*! \reimp */
-QString QAccessibleApplication::actionText(int action, Text text, int child) const
-{
-    QString str;
-    if ((action == 0 || action == 1) && !child) switch (text) {
-    case Name:
-        return QGuiApplication::tr("Activate");
-    case Description:
-        return QGuiApplication::tr("Activates the program's main window");
-    default:
-        break;
-    }
-    return QAccessibleObject::actionText(action, text, child);
-}
 
 QT_END_NAMESPACE
 
diff --git a/src/gui/accessible/qaccessibleobject.h b/src/gui/accessible/qaccessibleobject.h
index 0252a437c8..ded4e46563 100644
--- a/src/gui/accessible/qaccessibleobject.h
+++ b/src/gui/accessible/qaccessibleobject.h
@@ -43,6 +43,7 @@
 #define QACCESSIBLEOBJECT_H
 
 #include "qaccessible.h"
+#include "qaccessible2.h"
 
 QT_BEGIN_HEADER
 
@@ -67,11 +68,6 @@ public:
     QRect rect(int child = 0) const;
     void setText(Text t, int child, const QString &text);
 
-    // actions
-    int userActionCount(int child = 0) const;
-    bool doAction(int action, int child = 0, const QVariantList &params = QVariantList());
-    QString actionText(int action, Text t, int child = 0) const;
-
 protected:
     virtual ~QAccessibleObject();
 
@@ -82,6 +78,7 @@ private:
 
 class Q_GUI_EXPORT QAccessibleApplication : public QAccessibleObject
 {
+    Q_ACCESSIBLE_OBJECT
 public:
     QAccessibleApplication();
 
@@ -101,11 +98,6 @@ public:
     QString text(Text t, int child = 0) const;
     Role role(int child = 0) const;
     State state(int child = 0) const;
-
-    // actions
-    int userActionCount(int child = 0) const;
-    bool doAction(int action, int child = 0, const QVariantList &params = QVariantList());
-    QString actionText(int action, Text t, int child = 0) const;
 };
 
 #endif // QT_NO_ACCESSIBILITY