Softkeys are programmable buttons that can be used to perform different functions based on the current context. Symbian applications use softkeys in order to access and select menu options, for acknowledging or canceling prompts and dialogs, and for closing the whole application.
This article provides an overview of how softkeys are used in QWidget based applications on Symbian, and is intended to be complement to the generic Qt examples and documentation:
Softkeys provide access to the standard application menu, and are used to provide a consistent location for users to invoke positive (OK, Open, Select) and negative (Close, Cancel, Exit) actions. On non-touch Symbian devices, they are simply labels that correspond to hardware buttons on the device (located adjacent/below them in portrait mode). On touch screen devices the softkey label is itself a pressable button and no hardware key is required. In landscape mode the buttons are located in the same location, but rotated 90 degrees to make them readable.
Qt apps define softkeys as QActions with a enum QAction::SoftKeyRole indicating whether they are positive, negative, or for selection. These positive and negative softkeys map to left and right softkeys on Symbian platform devices.
Applications main windows get an "Exit" softkey by default, and an "Options" softkey if the application has a menu. New softkeys can be added added or removed from any widget (if no softkey is defined for a widget, those of its parents are used). The text on softkeys can be changed and images can be used instead of text. Note that it is not possible to style the softkey text or button because softkeys are implemented using Symbian platform libraries which do not support this functionality.
The following sections demonstrate how to work with softkeys on the Symbian platform.
The Softkey example code demonstrates most aspects of using softkeys. Figure 1 shows the application as it is displayed on start up on a Nokia 5800, with an "Options" softkey for launching its menu, and "Exit" for closing it.
The remaining UI widgets are used to demonstrate other softkey uses:
- "Custom" button changes the softkey text to "OK" and "Cancel" (Figure 2)
- "File Dialog" launches a standard file dialog with its "Open" and "Cancel" softkeys (Figure 3)
- The selection list (initial value "Selection 1") launches a selection dialog with keys "Select" and "Cancel" (Figure 4)
- "Loop SK window type" button loops the window size (Figures 5, 6, 7)
How to ensure the softkeys are visible
- Setting the window maximised using QWidget::showMaximized(); this sizes the window to fit between the softkeys at the bottom of the screen and the status up the top. Figure 5 shows this approach.
int main(int argc, char *argv)
QApplication app(argc, argv);
- Setting the window to full screen using QWidget::showFullScreen() but providing the window hint Qt::WindowSoftkeysVisibleHint that the softkeys be made visible. Figure 6 shows this approach.
In theory you can also have the sofkeys hidden and still respond to softkey events; however at time of writing this does not work - see QTBUG-10259
The softkey example demonstrates all three approaches, as shown in the screenshots below:
Adding your own softkey
To add your own softkey:
- Create a QAction with the softkey text
- Specify a softkey role of QAction::PositiveSoftKey for positive actions (menu, select, OK) or QAction::NegativeSoftKey for negative actions (close, cancel, exit)
- Add it to a widget
The following code fragment adds a positive softkey "My Action" to the current widget (e.g. the main window). Note that you can add the softkey to any widget and it will be used when the widget has focus. If a widget doesn't have a softkey the softkey of its parent is used:
How to use softkey icons
Applications that have softkey icons can be more intuitive to use and easier to translate than those that use text - particularly when the icons are commonly understood in many countries. For example, the screenshot below shows the softkey example using icons "thumbs up" (25 by 25 pixels) and "off button" (40 by 40 pixels) for the softkeys instead of "OK" and "Cancel".
To use an icon, simply call QAction::setIcon() on the softkey action - this will be used instead of any existing text. The code fragment below shows the addition of icons to the softkey example for the custom OK and "cancel" buttions:
ok = new QAction(tr("Ok"), this);
ok->setIcon(QPixmap(":/icons/icons/thumbs_up.png")); //add icon for "OK"
connect(ok, SIGNAL(triggered()), this, SLOT(okPressed()));
cancel = new QAction(tr("Cancel"), this);
cancel->setIcon(QPixmap(":/icons/icons/exit.png")); //add icon for "Exit"
Note that the images are displayed to the extreme left and right of the softkeys in portrait mode, and centred in landscape (this difference in behaviour may be a bug, see QTBUG-14662).
How do I change the softkey text
Softkey text can be changed by changing the value held in its associated QAction.
The only issue is when its difficult to get hold of the softkey action - for example, the "Options" softkey associated with the menu is internal. In this case you can simply define a new softkey (and menu), as discussed in Qt Menus
Note that the default text is often translated on your behalf by manufacturers - changing it may not be in your interest.
Qt Creator/Designer for softkeys
The Qt UI designer does not have any specific support for creating and working with softkeys.
Softkeys provide access to the Symbian menu, and are the primary mechanism for user interaction on non-touch devices. This article showed how to create and customise softkeys in Qt on Symbian applications.