Qt Softkeys

Comments

(no comments yet)

Log in or Join to leave comments.

Article Metadata

---

Article

Created: hamishwillee (17 Dec 2010)

Last edited: hamishwillee (30 Apr 2013)

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:

• Softkey example code
• class QWidget softkey information
• enum QAction::SoftKeyRole

Overview

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.

Example code

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.

Figure 1: Options and Exit

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)

• 

  Figure 2: Custom buttons

• 

  Figure 3: File Dialog

• 

  Figure 4: Selection list

The example omits only one important topic - adding images to softkey items (QTBUG-14627). The How to use softkey icons section below shows how to replace softkey text with an image.

How to ensure the softkeys are visible

Qt applications that want to use softkeys (and the menu) must ensure that the QMainWindow does not cover the softkey area. Applications typically do this by:

• 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);
      MainWindow window;
  #if defined(Q_OS_SYMBIAN)
      window.showMaximized();
  #else
      window.show();
  #endif
      return app.exec();
  }

• 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.

  Qt::WindowFlags flags = windowFlags();
  flags |= Qt::WindowSoftkeysVisibleHint;
  showFullScreen();

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:

• 

  Figure 5: Maximised

• 

  Figure 6: Full screen with softkeys

• 

  Figure 7: Full screen

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:

QAction* myAction= new QAction(tr("My Action"), this);
myAction->setSoftKeyRole(QAction::PositiveSoftKey);
addAction(myAction);

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".

Using images for the softkey buttons

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->setSoftKeyRole(QAction::PositiveSoftKey);
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->setSoftKeyRole(QAction::NegativeSoftKey);  
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.

QAction* myAction =  new QAction (tr("Oldtext"),this);
myAction ->setText (tr("New text") );

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.

Summary

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.