Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries over the next few weeks. Thanks for all your past and future contributions.

Archived:Handling softkeys in Qt for Symbian

From Wiki
Jump to: navigation, search

Archived.pngArchived: This article is archived because it is not considered relevant for third-party developers creating commercial solutions today. If you think this article is still relevant, let us know by adding the template {{ReviewForRemovalFromArchive|user=~~~~|write your reason here}}.

Qt Quick should be used for all UI development on mobile devices. The approach described in this article (based on QWidget) is deprecated.

Article Metadata
Tested with
Devices(s): All (S60)
Platform(s): S60 3rd Edition, FP1
S60 3rd Edition, FP2
S60 5th Edition
S60 5th Edition
S60 3rd Edition FP2
S60 3rd Edition FP1
Keywords: setSoftKeyRole, QAction
Created: User:Kbwiki (14 Dec 2009)
Last edited: hamishwillee (11 Oct 2012)


Softkeys will be visible in the control pane of a Qt application, if a focused widget has actions (QAction) with a softkey role defined. This article discusses how softkeys are implemented and how to dynamically change the softkey actions in Qt on Symbian.

Detailed description

QAction::setSoftKeyRole() can be used for specifying the type (role) of a softkey for an action:

QAction::NoSoftKey Action is not used as a softkey
QAction::PositiveSoftKey Softkey with a positive or non-destructive role such as Ok, Select, or Options.
QAction::NegativeSoftKey Softkey with a negative or destructive role role such as Cancel, Discard, or Close.
QAction::SelectSoftKey Softkey that selects a particular item or widget in the application.

When the application is in portrait mode, locations for positive and negative softkeys are at the left-hand and right-hand side of the screen, respectively. In landscape mode, the positive softkey is at the bottom and the negative softkey on top.

Softkeys will be set according to the actions of the currently focused widget. By default, the top-level widget has Options and Exit softkeys. If a focused child widget has no defined softkeys, the framework will traverse up the widget parent hierarchy looking for a widget containing softkey actions.

Traversal through the widget hierarchy stops once at least one softkey action is found. This has some implications for widgets that want to modify a single softkey; for example, consider the following code used for defining a Back softkey in a child widget:

 QAction* backAction = new QAction( tr("Back"), this );
backAction->setSoftKeyRole( QAction::NegativeSoftKey );
connect(backAction, SIGNAL(triggered()), this, SLOT(back()));
addAction( backAction );

If the application has other actions located in the Options menu, accessing the menu is not possible as the Options softkey is not visible as the focused widget has defined only a single (negative) softkey.


Managing the softkeys should be done in the implementation of a top-level parent widget (QWidget) or the main window (QMainWindow).

For example, to toggle between Exit and Back actions as the negative softkey, use the following code:

  MainWindow::MainWindow(QWidget *parent) :
m_backAction = new QAction( tr("Back"), this );
m_backAction->setSoftKeyRole( QAction::NegativeSoftKey );
void MainWindow::toggleRightSoftKey( bool back, QWidget* focusWidget )
if( back ) {
connect(m_backAction, SIGNAL(triggered()), focusWidget, SLOT(back()));
addAction( m_backAction );
} else {
disconnect( m_backAction );
removeAction( m_backAction );

After this, a child widget can replace the default Exit right softkey with Back by calling toggleRightSoftKey(true, this) on the MainWindow object. Note that the code assumes the widget has a back() slot implemented.

This page was last modified on 11 October 2012, at 01:14.
70 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.


Thank you!

We appreciate your feedback.