×
Namespaces

Variants
Actions
Revision as of 04:17, 11 October 2012 by hamishwillee (Talk | contribs)

Migrating from Avkon to QWidget: UI component comparison

From Nokia Developer Wiki
Jump to: navigation, search
Article Metadata
Article
Created: seppo_fn (11 Nov 2010)
Last edited: hamishwillee (11 Oct 2012)
Featured Article
21 Nov
2010

Contents

Introduction

This document is intended to be a reference guide for Symbian developers who are implementing user interfaces with Qt. The document lists the most-often-used Symbian Avkon UI components and their Qt counterparts (QWidgets). Source code will sometimes need to be customised for an optimal Symbian look and feel.

The illustrations used in this document depict Qt 4.6.3 on a Nokia N8 device based on Symbian^3.

CCoeControl vs. QWidget

Symbian and Qt have their own base classes for the UI: QWidget in Qt and CCoeControl in Symbian. Both classes can work as a container control or parent class for the other child components, and they have fairly similar features, for example

  • Handling mouse and key events, catching events, handling event flow between parent and child components.
  • When a component is created or window size is changed, the same kind of method is called to inform about the event: CCoeControl::SizeChanged() in Symbian and QWidget::resizeEvent() in Qt. In these methods it is necessary to define component position and size: CCoeControl::SetRect() in Symbian and QWidget::setGeometry() in Qt. There is, of course, a chance to use layouts in Qt, and it is even advisable.

Additional similarities include:

  • Dialogues have their own base classes: CAknDialog in Symbian and QDialog in Qt.
  • Applications have their own class that creates and sets the geometry of the main window: CAknApplication in Symbian and QApplication in Qt.

Switching between views

Qt does not support Symbian-style application view switching, where different applications can open each other’s views. Symbian views are described further in the View Server Tutorial and in Switching views on Symbian.

A Qt mobile application is usually built on QMainWindow, and it has one QWidget as the main central widget. Switching between different widgets can be implemented by, for example:

  • Using QStackedWidget as the central widget, which allows you to stack different QWidgets;
  • Opening QDialog on top of the central widget;
  • Using multiple QMainWindow instances where you open another QMainWindow on top of the first one. Define QMainWindow::setAttribute(Qt::WA_DeleteOnClose) for the opened windows, which are then deleted after close.

UI Scalability

All Symbian and Qt components scale dynamically. For a Qt application with multiple widgets in one view, use layouts to support automatic scaling. Sometimes Qt components need more space than is available in a mobile device. In that case, try using the SetNoConstraint flag in QLayout; for more information, see QLayout::setSizeConstraint(). This will allow components to be smaller than what has been defined as the Qt minimum.

Status pane and CBA buttons

CBA buttons and the status pane are visible automatically when running a Qt application on its maximised mode, QWidget::showMaximized().

CBA and status pane CBA but no status pane No CBA, no status pane

If you want to run a Qt application on full screen mode, QWidget::showFullScreen(), there is no status pane or CBA buttons visible.

On full screen mode it is possible to make CBA buttons visible by enabling the Qt::WindowSoftkeysVisibleHint flag into your window:

QWidget::setWindowFlags(windowFlags() | Qt::WindowSoftkeysVisibleHint);

Note that there is a slight difference in the placement of softkeys in Symbian^3 - they are in the bottom of the Avkon component. In QWidget they are in the CBA pane. This makes no difference when using the application, though.

Component Quick Reference

Qt UI component Symbian UI component
QWidget CCoeControl
QMenuBar, QMenu RESOURCE MENU_BAR, RESOURCE MENU_PANE
QAction RESOURCE MENU_ITEM
QDialog CAknDialog
QFormLayout CAknForm
QMessageBox CAknInformationNote, CAknConfirmationNote, CAknWarningNote, CAknErrorNote
QProgressDialog CAknProgressDialog
QProgressBar CEikProgressInfo
QColorDialog CAknColourSelectionGrid
QFileDialog AknCommonDialogsDynMem
QInputDialog CAknTextQueryDialog
QListWidget CAknSingleStyleListBox, CAknSingleGraphicStyleListBox, CAknDoubleStyleListBox
QGridLayout CAknGrid
QGroupBox
QSlider CAknSlider
QDial
QLineEdit CEikEdwin
QPushButton CAknButton
QRadioButton CAknRadioButtonSettingPage
QCheckBox CAknCheckBoxSettingPage
QLabel CEikLabel
QTextEdit CEikGlobalTextEditor
QTextBrowser CEikRichTextEditor
QTabWidget CAknTabGroup
QComboBox CAknChoiceList
QScrollBar CEikScrollBarFrame
QDateEdit CEikDateEditor
QTimeEdit CEikTimeEditor
QToolBar CAknToolbar, CAknButton

Layouts

Qt: QFormLayout S60: CAknForm
CcLayoutQt.png CcLayoutS60.png
Layout Management, QFormLayout Form API Specification

Qt has its own form layout class for building forms. Symbian has a different solution, where the form line is DLG_LINE in the DIALOG item in the application resource file.

Menu Bar

Qt: QMenuBar, QMenu, QAction S60: RESOURCE MENU_BAR, RESOURCE MENU_PANE, MENU_ITEM
CcMenuBarQt 01.png CcMenuBarS60 01.png
CcMenuBarQt 02.png CcMenuBarS60 02.png
QMenuBar, QAction Options Menu API

Symbian defines menus in application resource files, whereas QMenuBar and actions are created in the source code in Qt. In Qt, the Options menu can be defined in QMainWindow or QDialog.

In QMainWindow, the menu can be created in one line, such as:

menuBar()->addAction("Menu item", this, SLOT(someSlot()));

The menu in QDialog can be implemented using QMenu:

menu = new QMenu(this);
menu->addAction("Menu item", this, SLOT(someSlot()));

In QDialog, you have to define CBA buttons, too:

QAction *optionsAction = new QAction("Options", this);
optionsAction->setMenu(menu);
optionsAction->setSoftKeyRole(QAction::PositiveSoftKey);
addAction(optionsAction);
 
QAction *backSoftKeyAction = new QAction(QString("Back"), this);
backSoftKeyAction->setSoftKeyRole(QAction::NegativeSoftKey);
connect(backSoftKeyAction, SIGNAL(triggered()),this, SLOT(close()));
addAction(backSoftKeyAction);

Basic Components

Label, Date Editor, Time Editor, Text Editor

Qt: QLabel, QDateEdit, QTimeEdit, QTextEdit S60: CEikLabel, CEikDateEditor, CEikTimeEditor, CEikEdwin, CEikGlobalTextEditor
CcLabelDateTimeTextQt.png CcLabelDateTimeTextS60.png
QLabel, QDateEdit Editors API

Radio Button

Qt: QRadioButton S60: CAknRadioButtonSettingPage
CcRadioButtonQt.png CcRadioButtonS60.png
QRadioButton Setting Pages API

Symbian radio buttons can be used only in the setting page and are derived from CAknSettingPage. Qt QRadioButton can be used anywhere you want.

Check Box

Qt: QCheckBox S60: CAknCheckBoxSettingPage
CcCheckBoxQt.png CcCheckBoxS60.png
QCheckBox Setting Pages API

Symbian check boxes can be used only in the setting page and are derived from CAknSettingPage. Qt QCheckBox can be used anywhere you want.

Tabs

Qt: QTabWidget S60: CAknTabGroup
CcTabsQt 01.png CcTabsS60 01.png
CcTabsQt 02.png CcTabsS60 02.png
QTabWidget Tabs API

Users can define whether or not the scroll buttons are visible in tabs using the QTabWidget ::setUsesScrollButtons() method.

In Qt applications, tabs reside in the content area instead of being embedded into the status pane, as in Symbian. If you want to maximise the application window area when using QTabWidget as the main window, define the application to run this window in full screen mode:

int main(int argc, char *argv[]){
QApplication a(argc, argv);
MyTabWidget tabWidget;
tabWidget.showFullScreen();
return a.exec();
}

You may want to show CBA buttons also in full-screen mode. You can make them visible by setting the Qt::WindowSoftkeysVisibleHint flag into your window:

QWidget::setWindowFlags(windowFlags() | Qt::WindowSoftkeysVisibleHint);

Note that there are some usage problems when using tabs with a keyboard: when the focus is inside a tab, you cannot easily move to another tab but you first need to press 'Done' to move the focus to the tab row (unlike in Symbian, where pressing the left/right navigation key will always switch to another view).

Slider

Qt: QSlider S60: CAknSlider
CcSliderQt.png CcSliderS60.png
QSlider CAknSliderSettingItem

The Symbian slider can be used only in the setting page and is derived from CAknSettingPage. Qt QSlider can be used anywhere you want.

Button

Qt: QPushButton S60: CAknButton
CcButtonQt.png CcButtonS60.png
QPushButton Generic button API

Note: The default size of QPushButton is currently too narrow for easy finger touch use. The height of the button can, however, be defined.

Progress Indicator

Qt: QProgressBar S60: CEikProgressInfo
CcProgressBarQt.png CcProgressBarS60.png
QProgressBar Progress Bar Control Example, CEikProgressInfo
Qt: QProgressDialog S60: CAknProgressDialog
CcProgressDialogQt.png CcProgressDialogS60.png
QProgressDialog Notes API Specification

List

Qt: QListWidget S60: CAknSingleStyleListBox
CcListQt.png CcListS60.png
QListWidget Lists API

Symbian has many different UI classes for lists; Qt has only one, QListWidget. When using keyboard devices, there are some usage problems for selecting a row or moving between rows in the list in Qt.

Kinetic scrolling is not yet supported in Qt 4.6.3 in Symbian. It is possible to enable it by implementing the solution provided at labs.qt.nokia.com.

Enabling single tap

To use a Symbian^3 style single-tap interaction, listen to the QListWidget:: itemClicked(QListWidgetItem*) slot.

Enabling context menu

With single-tap interaction in use, item-specific commands cannot be used via the Options menu but rather by using a context menu that is launched with a long tap.

First, enable the context menu for the list:

listWidget->setContextMenuPolicy(Qt::CustomContextMenu);

Then start listening to a context menu signal from the list:

QObject::connect(listWidget, SIGNAL(customContextMenuRequested(const QPoint&)), this, SLOT(showContextMenu(const QPoint&)));

Now define the context menu:

m_contextMenu = new QMenu(this);
QAction* aMenuItem1 = menuBar()->addAction("Some item ", this, SLOT(someSlot()));
m_contextMenu->addAction(aMenuItem1);

Finally, implement a slot for the customContextMenuRequested() signal to execute the context menu that has been defined:

void QMyWidget::showContextMenu(const QPoint& pos) {
m_contextMenu->exec(pos);
}

Qt 4.6.3 in Symbian has a bug: When a widget has defined a context menu, an 'Actions' menu command appears in the Options menu that launches the context menu.

Combo Box

Qt: QComboBox S60: CAknChoiceList
CcComboBoxQt 01.png CcComboBoxS60 01.png
CcComboBoxQt 02.png CcComboBoxS60 02.png
QComboBox Choice list API

Qt 4.6.3 has invalid text colour in the QComboBox - it has white text on a white background. Open QComboBox has some kind of check box icons on each row in the list.

Grid

Qt: QGridLayout S60: CAknGrid
CcGridQt 01.png CcGridS60 01.png
CcGridQt 02.png
QGridLayout Grids API

Qt QGridLayout is only a layout for other UI components, whereas CAknGrid is a more versatile grid component (on the other hand, CAknGrid is more complicated than QGridLayout).

Rich Text Editor

Qt: QTextEdit S60: CEikRichTextEditor
CcRTEQt.png CcRTES60.png
QTextEdit Rich Text Editor Example, Editors API

QTextBrowser is derived from QTextEdit and can show HTML pages in Qt.

Toolbar

Qt: QToolBar S60: CAknToolbar
CcToolBarQt.png CcToolBarS60.png
QToolBar ToolBar API

Note that custom look and feel has been applied to the buttons in the example picture of the CAknToolbar.

By default QToolBar seems to be too big for mobile devices in Qt. Define a suitable size for the toolbar with this code:

QToolBar *tool = new QToolBar(this);
tool->setGeometry(0,0,200,20);

To learn more, see How to use QToolBar and QToolButton in Qt and Symbian C++ and Qt toolbar comparison.

Dialogs

Color Dialog

Qt: QColorDialog S60: CAknColourSelectionGrid
CcColorDialogQt.png CcColorDialogS60.png
Application Windows and Dialogs, QColorDialog Dialogs API

File Dialog

List Directories

Qt: QFileDialog S60: AknCommonDialogsDynMem
QFileDialog::getExistingDirectory()
Application Windows and Dialogs, QFileDialog Common File Dialogs API, AknCommonDialogsDynMem

QFileDialog::getExistingDirectory()

AknCommonDialogsDynMem does not have directory browsing functionality.

Open File

Qt: QFileDialog S60: AknCommonDialogsDynMem
QFileDialog::getOpenFileName() CcFileDialogS60 02.png
Application Windows and Dialogs, QFileDialog Common File Dialogs API, AknCommonDialogsDynMem

QFileDialog::getOpenFileName()

Save File

Qt: QFileDialog S60: AknCommonDialogsDynMem
QFileDialog::getSaveFileName() CcFileDialogS60 03.png
Application Windows and Dialogs, QFileDialog Common File Dialogs API, AknCommonDialogsDynMem

QFileDialog::getSaveFileName()

Define the destination path when saving a file. For example, the user's home directory is QDir::home().path().

Input Dialog

Text Query

Qt: QInputDialog S60: CAknTextQueryDialog
QInputDialog::getText() CcInputDialogS60 01.png
CcInputDialogQt 02.png CcInputDialogS60 02.png
Application Windows and Dialogs, QInputDialog Queries API

QInputDialog::getText()

List Query

Qt: QInputDialog S60: CAknListQueryDialog
QInputDialog::getItem() CcInputDialogS60 03.png
Application Windows and Dialogs, QInputDialog Queries API

QInputDialog::getItem()

Number Query

Qt: QInputDialog S60: CAknNumberQueryDialog
QInputDialog::getInt() CcInputDialogS60 04.png
Application Windows and Dialogs, QInputDialog Queries API

QInputDialog::getInt()

Message Dialog

Question Message

Qt: QMessageBox (QMessageBox::question()) S60: CAknQueryDialog (Confirmation Query)
QMessageBox::question() CcMessageDialogS60 01.png
QMessageBox Notes API, Showing Notes

Warning Message

Qt: QMessageBox (QMessageBox::warning()) S60: CAknWarningNote
QMessageBox::warning() CcMessageDialogS60 02.png
QMessageBox Notes API, Showing Notes

Information Message

Qt: QMessageBox (QMessageBox::information()) S60: CAknInformationNote
QMessageBox::information() CcMessageDialogS60 03.png
QMessageBox Notes API, Showing Notes

Confirmation Message

Qt: QMessageBox (QMessageBox::information()) S60: CAknConfirmationNote
QMessageBox::information() CcMessageDialogS60 04.png
QMessageBox Notes API, Showing Notes

Error Message

Qt: QMessageBox (QMessageBox::critical()) S60: CAknErrorNote
QMessageBox::critical() CcMessageDialogS60 05.png
QMessageBox Notes API, Showing Notes

References

Bold text

165 page views in the last 30 days.
×