Revision as of 10:49, 12 July 2011

Under Construction: This article is under construction and it may have outstanding issues. If you have any comments please use the comments tab.

This article introduces some fundamental use cases that developers porting applications from iPhone and Android will need to implement, and discusses sample solutions. In general, Qt provides all modern classes and functionalities familiar from iPhone and Android. This makes it easy to keep the application logic close to the original when porting (see Snapshot of Qt classes).

Using Internet Services

Mobile applications are extremely likely to use the Internet — whether loading news stories from a server, using a remote service API such as Facebook or Twitter, or uploading photos to a photo-sharing service.

While protocols and service APIs vary considerably, it is very typical that the traffic happens on top of the HTTP protocol and is described as XML or JSON content.

The QNetworkAccessManager class[1] makes it easy to interact with remote services. The class handles common configuration and settings for the requests it sends, such as settings for proxies and caching. The API is asynchronous and uses signals to notify clients about events such as finished requests. QNetworkAccessManager supports HTTP(S) and FTP.

A simple example of retrieving data using an URL asynchronously: (replyFinished() slot is called upon completion)

    ...
    QUrl url("http://www.example.com/example.xml");
    QNetworkAccessManager *manager = new QNetworkAccessManager(this);
    connect(manager, SIGNAL(finished(QNetworkReply*)),
            this, SLOT(replyFinished(QNetworkReply*)));
    manager->get(QNetworkRequest(url);
    ...
 
myClass::replyFinished(QNetworkReply *reply) {
    QByteArray replyData(reply->readAll());
    // Process the reply data
}

See more info at http://doc.trolltech.com/main-snapshot/qnetworkaccessmanager.html

Web View

Qt has a WebView[2] QML element for displaying web content inside the application, like iPhone and Android. Thus, your existing server-side web content is directly reusable in Qt platforms.

Here is a short example of how to use a WebView element. A website can be loaded into the element by setting its url[3] property. Note that the QtWebKit import is also required.

import QtQuick 1.0
import QtWebKit 1.0
 
WebView {
    height: 640
    width: 480
    url: "http://www.developer.nokia.com/"
}

To get a scrolling webview, put the WebView element inside a Flickable[4] element:

import QtQuick 1.0
import QtWebKit 1.0
 
Flickable {
    id: flick
    width: 640
    height: 480
    contentWidth: web.width
    contentHeight: web.height
    WebView {
        id: web
        anchors.top: parent.top
        anchors.left: parent.left
        preferredWidth: flick.width
        preferredHeight: flick.height
        url: "http://www.developer.nokia.com"
    }
}

There are a few notable things about the above example: first, the WebView gets its preferredWidth and preferredHeight properties set to the size of the Flickable, which helps the WebView to try to resize the page in an intelligent way. Second, the Flickable needs to know the size of its contents to enable flicking: this is done using the contentWidth and contentHeight properties. Third, as the actual size of the WebView changes according to the loaded page, the WebView is anchored in the Flickable only by its top and left edges.

OpenGL ES Graphics using Qt GameEnabler

It is easy to integrate OpenGL ES graphics into Qt applications using Qt's OpenGL module. Qt GameEnabler takes the integration one step further by providing a simple starting point for game development, including not only graphics, but also audio playback and input event handling. By downloading a Qt GameEnabler release you get a project template that you can then start customizing and extending.

For a step-by-step introduction to Qt Game Enabler, see this guide.

Media Usage

Many application ideas and concepts can be realised thanks to the ease and convenience of the audio/video capabilities of Qt.

Qt provides a quick and simple way to display images and simple animations using the Image and AnimatedImage class:

AnimatedImage {
    source: "animations/fire.gif" 
}

Also, the common task of playing an audio file can be easily accomplished:

QSound::play("mysounds/bells.wav");

For more complex cases, Qt provides the [http://doc.trolltech.com/4.7-snapshot/phonon.html Phonon multimedia framework]. Phonon provides functionality for playback of the most common multimedia formats. The media can be read from files or streamed over a network, using a QURL to a file.

Music file playback can be constructed as follows:

Phonon::MediaObject *music =
Phonon::createPlayer(Phonon::MusicCategory,
Phonon::MediaSource("/path/song.mp3"));
music->play();

For video playback, the QtMultimediaKit module[5] provides the Video QML element[6].

import QtQuick 1.0
import QtMultimediaKit 1.1
 
Rectangle {
    width: 360
    height: 360
    Video {
        source: "movie.avi"
        anchors.fill: parent
    }
}

Application Data Storage

SQLite has changed the way you store and read data easily in mobile applications, and there's no reason to change it. Qt allows the application to use either the device's own SQLite database or include one inside Qt project.

In addition to features that are familiar from iPhone and Android, Qt also provides an offline storage API. With the offline storage API, you can use SQLite directly from QML code with an intuitive JavaScript interface.

Read more

Qt provides several different methods for storing data.

Simple data, such as application settings, is easily handled with QSettings [7]. All details are handled automatically:

QSettings settings("CompanyName", "ApplicationName");
settings.setValue("store/price", 13); 
...
int price = settings.value("store/price").toInt();

More complex data can be serialized into a binary form using QDataStream [8]. Serialization of C++'s basic data types, such as char, short, int and char*, is automatic. Serialization of more complex data is accomplished by breaking up the data into these primitive units. An XML format for data storage is available with QtXml [9], which provides a stream reader and writer for XML documents, and C++ implementations of SAX and DOM.

The most powerful data storage method is QtSql [10], which provides full SQL database functionalities. The following snippet creates a to-do list into a local database, inserts some data there, and reads it back selectively.

QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE");
db.setDatabaseName("myDataBase");
 
QSqlQuery query;
query.exec("CREATE TABLE items (id int primary key, item TEXT, description TEXT)");
query.exec("INSERT INTO items values(101, 'Shopping list', 'Milk')");
query.exec("INSERT INTO items values(102, 'Shopping list', 'Beer')");
 
query.exec("SELECT * FROM items WHERE description='Beer'");
 
while (query.next()) {
    QString list = query.value(1).toString();
    QString item = query.value(2).toString();
    qDebug() << list;
    qDebug() << item;
}

A temporary memory based database can be used by setting ':memory:' as the database name.

Useful features for porting

This section covers some of the most common features and examples for porting cases, grouped by typical applications. Application sketches on the left side of this document illustrate common application types on iPhone and Android devices. UI component images on the right show some of the most common Maemo/Nokia N900 elements used for building native-like user experiences.

QML ListView The ListView element provides a list or icon view onto a model. Read more QML Column The Column element provides a vertical layout for managing other QML elements. Read more Example: Dynamic linking Plug & Paint example demonstrates how to write Qt applications that can be extended through dynamically loaded plugins Open Example: Server Fortune Server example shows how to create a server in Qt for a simple network service Open Feature: State Framework State Machine framework provides an API and execution model that can be used to easily create UI functionality in Qt applications Read more Example: State transitions Event Transitions example shows how to use event transitions, a feature of The State Machine Framework Open

Common Maemo UI buttons and text elements

Maemo UI menu

Sample Maemo thumbnail list

Common Maemo UI portrait list and buttons

Maemo application dialog example

Maemo landscape list and buttons

Sample Maemo application view

Feature: View transform By applying a transformation to the view, you can easily add support for common navigation features such as zooming and rotating Read more Example: Drawing Basic Drawing example shows how to display basic graphics primitives in a variety of styles Open Example: Complex paths Painter Paths example shows how painter paths can be used to build complex shapes for rendering Open Feature: Draw path Draws the given painter path using the current pen for outline and the current brush for filling Read more Example: Path stroke Path Stroke example demonstrates various types of pens that can be used in Qt for paths Open Example: Advanced drawing Advanced Drawing example shows how to use advanced vector techniques to draw text using a QPainterPath Open

Example: XML with DOM QDomDocument enable developers to access the contents of XML files using a Document Object Model (DOM) API. Simple DOM Model example shows how to use it. Open Example: Image composition Image Composition example demonstrates the powerful image composition features supported in Qt. Open Example: Advanced composition Composition demo shows some of the more advanced composition modes supported by Qt Open Example: SVG viewer SVG Viewer example shows how to add SVG viewing support to applications for great scalable UIs and graphics. Open Example: State toggle Two-way button example shows how to use State Machine Framework to implement a logic that toggles state when a button is clicked Open Example: State animations Move Blocks example shows how to animate items in a QGraphicsScene using State Machine Framework with a custom transition. Open Example: State animations Application Chooser example shows how to use the Qt state machine and the animation framework. Open

Class: Syntax highlighting Syntax highlighters are often used when the user is entering text in a specific format and help the user to read the text. Read more Example: Auto completer Auto-complete makes forms easier to use in mobile environments. Completer example shows how to provide string-completion facilities for an input widget based on defined data. Open Example: Custom completer Custom Completer is an other example of how to provide string-completion facilities for an input widgetOpen Example: Google suggest Google Suggest example demonstrates how to use the QNetworkAccessManager class to obtain a list of suggestions from the Google search engine as the user types into a QLineEdit Open Example: HTTP Client Qt provides network-transparent features for many media and content classes, but HTTP interaction is still the very basic of modern development. HTTP example demonstrates a how to fetch files specified by URLs from remote hosts Open Example: Web view Web view is a powerful tool for easy content handling. DOM Traversal example shows how to use the QWebElement class to access the structure of web view's HTML page Open Example: Web view selector Simple Selector example shows how to use QWebElement to access the Document Object Model (DOM) in a Web page Open

QML GridView The GridView element allows displaying model data in a grid layout Read more Example: Sorting Custom Sort/Filter Model example illustrates how to perform advanced sorting and filtering in Qt Open Example: Localization Qt makes localization easy. Internationalization (I18N) example demonstrates Qt's support for translated text Open Example: Regexps Regular Expressions (RegExp) example shows how regular expressions in Qt are used with strings Open Example: SQL query Query Model example shows how to make customized versions of data obtained from a SQL query Open Example: SQL drill-down Drill Down example shows how to read data from a database as well as submit changes Open

Example: Audio output QAudioOutput class provides an interface for sending audio data to an audio output device. Audio output example demonstrates use of this class. Open Example: Music player Music Player Example shows how to use Phonon - the multimedia framework that comes with Qt - to create a simple music player. Open Example: Bearer management Bearer Cloud example shows how to use the Bearer Management API to monitor the connectivity state of the local device, i.e. for loading offline content only while WLAN is available Open

Example: Audio input Audio Input example shows how to use QAudioInput class, that provides an interface for receiving audio data from an audio input device. Open Example: Gradients Gradients Example show how the various types of gradients can be used in Qt. Open

Example: Drag'n'drop icons Drag'n'drop is the basic feature in modern user interfaces. Draggable Icons example shows how to drag and drop image data between widgets in Standard view Open Example: Drag'n'drop text Draggable Text example shows how to drag and drop textual data between widgets in Standard view Open Feature: Drag'n'drop Graphics View framework provides drag and drop support for the scene, and for each and every item Read more Example: Fetch more Fetch More example shows how two add items to an item view model on demand, commonly used by applications with a list view Open Example: FTP Client FTP Client example demonstrates how Qt can be used to list the available files on an FTP server and download them. Open Example: P2P chat Network Chat example demonstrates a stateful peer-to-peer Chat client that uses broadcasting with QUdpSocket and QNetworkInterface to discover its peers. Open

Example: Inline-SVG Text Object example shows how to reduce layout work and insert an SVG file (such as status icons, emoticons etc) into a QTextDocument Open Example: Undo framework Undo Framework example shows how to easily implement advanced undo/redo functionality with the Qt undo framework Open Feature: QtScript QtScript module provides classes for making Qt applications scriptable. Read more Example: Qt scripting Qt Scripting example demonstrates how to implement the functionality of a calculator widget Open

Example: Generated icons Qicon class in Qt creates automatically different button states from the given image object. Widget Icons example demonstrates how to use this great feature. Open Class: Grid layout QGraphicsGridLayout class provides a grid layout for managing widgets in Graphics View Read more Feature: Painter rotate Adjusting coordinate system on-the-fly makes drawing of custom layouts easier in some cases. QPainter's rotate functionality rotates the coordinate system the given angle clockwise. [11]

The sketches were created with [Balsamiq Mockups].

• See also Nokia Developer Design and User Experience Guide for ideas on how to achieve the best possible user experience when porting your application for Nokia devices.