Simplify the soft key roles of QAction.

Previously there were many options here that were inherited from the
Qtopia implementation. It was not clear to developers which value
they actually should use. A good example was the  'Next' value. In
a typical wizard application, next would be on the right and
'Previous' would be on the left. However, it is also common to have
'Next' on the left and have 'Cancel' on the right.

Basically what people really wanted was a way to explicitly set the
right and left soft keys, but since this relies on form factor and
is wrong if the screen is rotated, we choose positive and negative
actions as the values for these such that they still make sense when
the screen is rotated. Also this helps people who don't know if a
particular action should be on the left or right, but they *do* know
if their action has destructive characterisitics (negative).

As a convenience for widgets in Qt that use softkeys, we create a
standard softkey enumeration. That maps the actions to the correct
role and has default text.

Reviewed-by: Alessandro Portale

12 files changed, 78 insertions, 107 deletions

diff --git a/src/gui/dialogs/qerrormessage.cpp b/src/gui/dialogs/qerrormessage.cpp
index 78b5529..436ef94 100644
--- a/src/gui/dialogs/qerrormessage.cpp
+++ b/src/gui/dialogs/qerrormessage.cpp
@@ -247,7 +247,7 @@ QErrorMessage::QErrorMessage(QWidget * parent)
     d->icon = new QLabel(this);
 #ifdef QT_SOFTKEYS_ENABLED
     d->okAction = new QAction(this);
-    d->okAction->setSoftKeyRole(QAction::OkSoftKey);
+    d->okAction->setSoftKeyRole(QAction::PositiveSoftKey);
     connect(d->okAction, SIGNAL(triggered()), this, SLOT(accept()));
     addAction(d->okAction);
 #endif
diff --git a/src/gui/dialogs/qprogressdialog.cpp b/src/gui/dialogs/qprogressdialog.cpp
index 292e950..5fb10bf 100644
--- a/src/gui/dialogs/qprogressdialog.cpp
+++ b/src/gui/dialogs/qprogressdialog.cpp
@@ -454,7 +454,7 @@ void QProgressDialog::setCancelButton(QPushButton *cancelButton)
 #else
     {
         d->cancelAction = new QAction(cancelButton->text(), this);
-        d->cancelAction->setSoftKeyRole(QAction::CancelSoftKey);
+        d->cancelAction->setSoftKeyRole(QAction::NegativeSoftKey);
         connect(d->cancelAction, SIGNAL(triggered()), this, SIGNAL(canceled()));
         addAction(d->cancelAction);
     }
diff --git a/src/gui/dialogs/qwizard.cpp b/src/gui/dialogs/qwizard.cpp
index 64588d2..0f6d353 100644
--- a/src/gui/dialogs/qwizard.cpp
+++ b/src/gui/dialogs/qwizard.cpp
@@ -1343,32 +1343,19 @@ bool QWizardPrivate::ensureButton(QWizard::WizardButton which) const
         QAction *softKey = new QAction(pushButton->text(), antiFlickerWidget);
         QAction::SoftKeyRole softKeyRole;
         switch(which) {
-        case QWizard::BackButton:
-            softKeyRole = QAction::PreviousSoftKey;
-            break;
         case QWizard::NextButton:
-            softKeyRole = QAction::NextSoftKey;
-            break;
-        case QWizard::CommitButton:
-            softKeyRole = QAction::EndEditSoftKey;
-            break;
         case QWizard::FinishButton:
-            softKeyRole = QAction::FinishSoftKey;
-            break;
         case QWizard::CancelButton:
-            softKeyRole = QAction::CancelSoftKey;
+            softKeyRole = QAction::NegativeSoftKey;
             break;
+        case QWizard::BackButton:
+        case QWizard::CommitButton:
         case QWizard::HelpButton:
-            softKeyRole = QAction::ViewSoftKey;
-            break;
         case QWizard::CustomButton1:
-            softKeyRole = QAction::SelectSoftKey;
-            break;
         case QWizard::CustomButton2:
-            softKeyRole = QAction::SelectSoftKey;
-            break;
         case QWizard::CustomButton3:
-            softKeyRole = QAction::SelectSoftKey;
+        default:
+            softKeyRole = QAction::PositiveSoftKey;
             break;
         }
         softKey->setSoftKeyRole(softKeyRole);
diff --git a/src/gui/itemviews/qabstractitemview.cpp b/src/gui/itemviews/qabstractitemview.cpp
index 715f92d..303f45b 100644
--- a/src/gui/itemviews/qabstractitemview.cpp
+++ b/src/gui/itemviews/qabstractitemview.cpp
@@ -133,7 +133,7 @@ void QAbstractItemViewPrivate::init()
     q->setAttribute(Qt::WA_InputMethodEnabled);
 
 #ifdef QT_SOFTKEYS_ENABLED
-    doneSoftKey = QSoftKeyManager::createKeyedAction(QAction::EndEditSoftKey, Qt::Key_Back, q);
+    doneSoftKey = QSoftKeyManager::createKeyedAction(QSoftKeyManager::DoneSoftKey, Qt::Key_Back, q);
 #endif
 }
 
diff --git a/src/gui/kernel/qaction.cpp b/src/gui/kernel/qaction.cpp
index 549d07c..6a6e549 100644
--- a/src/gui/kernel/qaction.cpp
+++ b/src/gui/kernel/qaction.cpp
@@ -269,24 +269,24 @@ void QActionPrivate::setShortcutEnabled(bool enable, QShortcutMap &map)
     MenuRole for the actions in that submenu have no effect. They will never be moved.
 */
 
-/*! \enum QAction::SoftKeyRole
-  \value OptionsSoftKey
-  \value SelectSoftKey
-  \value BackSoftKey
-  \value NextSoftKey
-  \value PreviousSoftKey
-  \value OkSoftKey
-  \value CancelSoftKey
-  \value EditSoftKey
-  \value ViewSoftKey
-  \value BackSpaceSoftKey
-  \value EndEditSoftKey
-  \value RevertEditSoftKey
-  \value DeselectSoftKey
-  \value FinishSoftKey
-  \value MenuSoftKey
-  \value ContextMenuSoftKey
-  \value ExitSoftKey
+/*! \since 4.6
+
+    \enum QAction::SoftKeyRole
+
+    This enum describes how an action should be placed in the softkey bar. Currently this enum only
+    has an effect on the Symbian platform.
+
+    \value NoSoftKey This action should be used as a softkey
+    \value PositiveSoftKey This action is used to describe a softkey with a positive or non-destructive
+           role such as Ok, Select, or Options.
+    \value NegativeSoftKey This action is used to describe a soft ey with a negative or destructive role
+           role such as Cancel, Discard, or Close.
+    \value SelectSoftKey This action is used to describe a role that selects a particular item or widget
+           in the application.
+
+    Actions with a softkey role defined are only visible in the softkey bar when the widget containing
+    the action has focus. If no widget currently has focus, the softkey framework will traverse up the
+    widget parent heirarchy looking for a widget containing softkey actions.
  */
 
 /*!
@@ -1437,8 +1437,9 @@ QAction::MenuRole QAction::menuRole() const
     \brief the action's softkey role
     \since 4.6
 
-    This indicates what softkey action this action is. Usually used on mobile
-    platforms to map QActions to hardware keys.
+    This indicates what type of role this action describes in the softkey framework
+    on platforms where such a framework is supported. Currently this is only
+    supported on the Symbian platform.
 
     The softkey role can be changed any time.
 */
diff --git a/src/gui/kernel/qaction.h b/src/gui/kernel/qaction.h
index df56d2c..bfc7491 100644
--- a/src/gui/kernel/qaction.h
+++ b/src/gui/kernel/qaction.h
@@ -94,10 +94,7 @@ public:
     enum MenuRole { NoRole, TextHeuristicRole, ApplicationSpecificRole, AboutQtRole,
                     AboutRole, PreferencesRole, QuitRole };
     enum SoftKeyRole {
-                    NoSoftKey, OptionsSoftKey, SelectSoftKey, BackSoftKey, NextSoftKey,
-                    PreviousSoftKey, OkSoftKey, CancelSoftKey, EditSoftKey, ViewSoftKey,
-                    BackSpaceSoftKey, EndEditSoftKey, RevertEditSoftKey, DeselectSoftKey,
-                    FinishSoftKey, MenuSoftKey, ContextMenuSoftKey, ExitSoftKey };
+                    NoSoftKey, PositiveSoftKey, NegativeSoftKey, SelectSoftKey };
     enum Priority { LowPriority = 0,
                     NormalPriority = 128,
                     HighPriority = 256};
diff --git a/src/gui/kernel/qsoftkeymanager.cpp b/src/gui/kernel/qsoftkeymanager.cpp
index b1ebd38..a7a5223 100644
--- a/src/gui/kernel/qsoftkeymanager.cpp
+++ b/src/gui/kernel/qsoftkeymanager.cpp
@@ -55,39 +55,24 @@ static const int s60CommandStart = 6000;
 QWidget *QSoftKeyManager::softKeySource = 0;
 QSoftKeyManager *QSoftKeyManager::self = 0;
 
-const char *QSoftKeyManager::standardSoftKeyText(QAction::SoftKeyRole role)
+const char *QSoftKeyManager::standardSoftKeyText(StandardSoftKey standardKey)
 {
     const char *softKeyText = 0;
-    switch (role) {
-    case QAction::OptionsSoftKey:
-        softKeyText = QT_TRANSLATE_NOOP("QSoftKeyManager", "Options");
+    switch (standardKey) {
+    case OkSoftKey:
+        softKeyText = QT_TRANSLATE_NOOP("QSoftKeyManager", "Ok");
         break;
-    case QAction::SelectSoftKey:
+    case SelectSoftKey:
         softKeyText = QT_TRANSLATE_NOOP("QSoftKeyManager", "Select");
         break;
-    case QAction::BackSoftKey:
-        softKeyText = QT_TRANSLATE_NOOP("QSoftKeyManager", "Back");
-        break;
-    case QAction::NextSoftKey:
-        softKeyText = QT_TRANSLATE_NOOP("QSoftKeyManager", "Next");
-        break;
-    case QAction::PreviousSoftKey:
-        softKeyText = QT_TRANSLATE_NOOP("QSoftKeyManager", "Previous");
-        break;
-    case QAction::OkSoftKey:
-        softKeyText = QT_TRANSLATE_NOOP("QSoftKeyManager", "Ok");
+    case DoneSoftKey:
+        softKeyText = QT_TRANSLATE_NOOP("QSoftKeyManager", "Done");
         break;
-    case QAction::CancelSoftKey:
+    case CancelSoftKey:
         softKeyText = QT_TRANSLATE_NOOP("QSoftKeyManager", "Cancel");
         break;
-    case QAction::EditSoftKey:
-        softKeyText = QT_TRANSLATE_NOOP("QSoftKeyManager", "Edit");
-        break;
-    case QAction::ViewSoftKey:
-        softKeyText = QT_TRANSLATE_NOOP("QSoftKeyManager", "View");
-        break;
     default:
-        ;
+        break;
     };
 
     return softKeyText;
@@ -105,10 +90,21 @@ QSoftKeyManager::QSoftKeyManager() : QObject()
 {
 }
 
-QAction *QSoftKeyManager::createAction(QAction::SoftKeyRole softKeyRole, QWidget *actionWidget)
+QAction *QSoftKeyManager::createAction(StandardSoftKey standardKey, QWidget *actionWidget)
 {
-    const char* text = standardSoftKeyText(softKeyRole);
+    const char* text = standardSoftKeyText(standardKey);
     QAction *action = new QAction(QSoftKeyManager::tr(text), actionWidget);
+    QAction::SoftKeyRole softKeyRole;
+    switch (standardKey) {
+    case OkSoftKey:
+    case SelectSoftKey:
+    case DoneSoftKey:
+        softKeyRole = QAction::PositiveSoftKey;
+        break;
+    case CancelSoftKey:
+        softKeyRole = QAction::NegativeSoftKey;
+        break;
+    }
     action->setSoftKeyRole(softKeyRole);
     return action;
 }
@@ -119,9 +115,9 @@ QAction *QSoftKeyManager::createAction(QAction::SoftKeyRole softKeyRole, QWidget
   \a actionWidget as a convenience.
 
 */
-QAction *QSoftKeyManager::createKeyedAction(QAction::SoftKeyRole softKeyRole, Qt::Key key, QWidget *actionWidget)
+QAction *QSoftKeyManager::createKeyedAction(StandardSoftKey standardKey, Qt::Key key, QWidget *actionWidget)
 {
-    QScopedPointer<QAction> action(createAction(softKeyRole, actionWidget));
+    QScopedPointer<QAction> action(createAction(standardKey, actionWidget));
 
     connect(action.data(), SIGNAL(triggered()), QSoftKeyManager::instance(), SLOT(sendKeyEvent()));
 
@@ -186,42 +182,23 @@ void QSoftKeyManager::updateSoftKeys_sys(const QList<QAction*> &softkeys)
         const QAction* softKeyAction = softkeys.at(index);
         switch (softKeyAction->softKeyRole()) {
         // Positive Actions go on LSK
-        case QAction::OptionsSoftKey:
-        case QAction::MenuSoftKey:
-        case QAction::ContextMenuSoftKey:
-            command = EAknSoftkeyOptions; //Calls DynInitMenuPane in AppUI
+        case QAction::PositiveSoftKey:
             position = 0;
             break;
         case QAction::SelectSoftKey:
-        case QAction::PreviousSoftKey:
-        case QAction::OkSoftKey:
-        case QAction::EditSoftKey:
-        case QAction::ViewSoftKey:
-        case QAction::EndEditSoftKey:
-        case QAction::FinishSoftKey:
-            command = s60CommandStart + index;
             position = 0;
             break;
         // Negative Actions on the RSK
-        case QAction::BackSoftKey:
-        case QAction::NextSoftKey:
-        case QAction::CancelSoftKey:
-        case QAction::BackSpaceSoftKey:
-        case QAction::RevertEditSoftKey:
-        case QAction::DeselectSoftKey:
+        case QAction::NegativeSoftKey:
             needsExitButton = false;
-            command = s60CommandStart + index;
-            position = 2;
-            break;
-        case QAction::ExitSoftKey:
-            needsExitButton = false;
-            command = EAknSoftkeyExit; //Calls HandleCommand in AppUI
             position = 2;
             break;
         default:
             break;
         }
 
+        command = s60CommandStart + index;
+
         if (position != -1) {
             TPtrC text = qt_QString2TPtrC(softKeyAction->text());
             QT_TRAP_THROWING(nativeContainer->SetCommandL(position, command, text));
diff --git a/src/gui/kernel/qsoftkeymanager_p.h b/src/gui/kernel/qsoftkeymanager_p.h
index 630dd9f..743b4d4 100644
--- a/src/gui/kernel/qsoftkeymanager_p.h
+++ b/src/gui/kernel/qsoftkeymanager_p.h
@@ -55,6 +55,7 @@
 
 #include <QtCore/qobject.h>
 #include "QtGui/qaction.h"
+
 QT_BEGIN_HEADER
 
 QT_BEGIN_NAMESPACE
@@ -64,9 +65,17 @@ class QSoftKeyManager : public QObject
     Q_OBJECT
 
 public:
+
+    enum StandardSoftKey {
+        OkSoftKey,
+        SelectSoftKey,
+        DoneSoftKey,
+        CancelSoftKey,
+    };
+
     static void updateSoftKeys(bool force = false);
-    static QAction *createAction(QAction::SoftKeyRole standardRole, QWidget *actionWidget);
-    static QAction *createKeyedAction(QAction::SoftKeyRole standardRole, Qt::Key key, QWidget *actionWidget);
+    static QAction *createAction(StandardSoftKey standardKey, QWidget *actionWidget);
+    static QAction *createKeyedAction(StandardSoftKey standardKey, Qt::Key key, QWidget *actionWidget);
 
 #ifdef Q_WS_S60
     static bool handleCommand(int);
@@ -75,7 +84,7 @@ public:
 private:
     QSoftKeyManager();
     static QSoftKeyManager *instance();
-    static const char *standardSoftKeyText(QAction::SoftKeyRole role);
+    static const char *standardSoftKeyText(StandardSoftKey standardKey);
     static void updateSoftKeys_sys(const QList<QAction*> &softKeys);
 
     static QSoftKeyManager *self;
diff --git a/src/gui/widgets/qcombobox.cpp b/src/gui/widgets/qcombobox.cpp
index 2f79600..61532b9 100644
--- a/src/gui/widgets/qcombobox.cpp
+++ b/src/gui/widgets/qcombobox.cpp
@@ -403,8 +403,8 @@ QComboBoxPrivateContainer::QComboBoxPrivateContainer(QAbstractItemView *itemView
     layout->setMargin(0);
 
 #ifdef QT_SOFTKEYS_ENABLED
-    selectAction = QSoftKeyManager::createKeyedAction(QAction::SelectSoftKey, Qt::Key_Select, itemView);
-    cancelAction = QSoftKeyManager::createKeyedAction(QAction::CancelSoftKey, Qt::Key_Escape, itemView);
+    selectAction = QSoftKeyManager::createKeyedAction(QSoftKeyManager::SelectSoftKey, Qt::Key_Select, itemView);
+    cancelAction = QSoftKeyManager::createKeyedAction(QSoftKeyManager::CancelSoftKey, Qt::Key_Escape, itemView);
     addAction(selectAction);
     addAction(cancelAction);
 #endif
diff --git a/src/gui/widgets/qdialogbuttonbox.cpp b/src/gui/widgets/qdialogbuttonbox.cpp
index 2ceeca7..39566ef 100644
--- a/src/gui/widgets/qdialogbuttonbox.cpp
+++ b/src/gui/widgets/qdialogbuttonbox.cpp
@@ -580,13 +580,13 @@ QAction* QDialogButtonBoxPrivate::createSoftKey(QAbstractButton *button, QDialog
     case YesRole:
     case ActionRole:
     case HelpRole:
-        softkeyRole = QAction::OkSoftKey;
+        softkeyRole = QAction::PositiveSoftKey;
         break;
     case RejectRole:
     case DestructiveRole:
     case NoRole:
     case ResetRole:
-        softkeyRole = QAction::CancelSoftKey;
+        softkeyRole = QAction::NegativeSoftKey;
         break;
     default:
         break;
diff --git a/src/gui/widgets/qmainwindow.cpp b/src/gui/widgets/qmainwindow.cpp
index 8a39a48..8bdbba7 100644
--- a/src/gui/widgets/qmainwindow.cpp
+++ b/src/gui/widgets/qmainwindow.cpp
@@ -118,7 +118,7 @@ void QMainWindowPrivate::init()
     iconSize = QSize(metric, metric);
     q->setAttribute(Qt::WA_Hover);
 #ifdef QT_SOFTKEYS_ENABLED
-    menuBarAction = QSoftKeyManager::createAction(QAction::MenuSoftKey, q);
+    menuBarAction = QSoftKeyManager::createAction(QSoftKeyManager::DoneSoftKey, q);
 #endif
 }
 
diff --git a/src/gui/widgets/qmenu.cpp b/src/gui/widgets/qmenu.cpp
index 5e51155..687e1bc 100644
--- a/src/gui/widgets/qmenu.cpp
+++ b/src/gui/widgets/qmenu.cpp
@@ -163,9 +163,9 @@ void QMenuPrivate::init()
         scroll->scrollFlags = QMenuPrivate::QMenuScroller::ScrollNone;
     }
 
-#ifdef QT_KEYPAD_NAVIGATION
-    selectAction = QSoftKeyManager::createKeyedAction(QAction::SelectSoftKey, Qt::Key_Select, q);
-    cancelAction = QSoftKeyManager::createKeyedAction(QAction::CancelSoftKey, Qt::Key_Back, q);
+#ifdef QT_SOFTKEYS_ENABLED
+    selectAction = QSoftKeyManager::createKeyedAction(QSoftKeyManager::SelectSoftKey, Qt::Key_Select, q);
+    cancelAction = QSoftKeyManager::createKeyedAction(QSoftKeyManager::CancelSoftKey, Qt::Key_Back, q);
     selectAction->setVisible(false); // Don't show these in the menu
     cancelAction->setVisible(false);
     q->addAction(selectAction);