Navigation

Work Environment Setup

If this is your first Qt Quick project, it makes sense to take a look at the tools you need, how a new project can be started and what are the most important needs of the daily development workflow.

Installing the tools

We recommend using the latest Qt libraries for working with this tutorial. You can download the libraries for your platform on www.qt-project.org/downloads. If you already have a working Qt development environment, make sure that you use Qt version Qt 4.7.4 or 4.8.x, which include QtQuick 1.1.

Creating Qt Quick applications

In this tutorial we will be using QtCreator [http://qt-project.org/wiki/Category:Tools::QtCreator] as an IDE. You can download the latest Qt Creator IDE and configure it to use the Qt 4.x libraries. For more information about configuring Qt Creator, refer to Adding Qt Versions <http://doc-snapshot.qt-project.org/qtcreator-2.6/creator-project-qmake.html>.

The wizard under the menu File ‣ New File or Project creates not only project files, but also some initial application code. The wizard provides two choices relevant to Qt Quick:

Qt Quick Application Qt Quick UI

The major difference between these two options is how the application code is executed. This difference reveals quite a few interesting facts of how Qt Quick works under the hood. Let’s create a project of each type and take a look at the files generated by the wizard.

Qt Quick UI* project type

If you select Qt Quick UI*, let’s name it hello_qt_quick_ui, you will get just one qml file and two project files in the project directory:

  • hello_qt_quick_ui.qml - application code you start with
  • hello_qt_quick_ui.qmlproject - the project file. You do not need to touch it for now
  • hello_qt_quick_ui.qmlproject.user - your project settings. Automatically generated and changed by Qt Creator. You need not edit this file, nor check it in into your version control system

hello_qt_quick_ui.qml looks like this:

import QtQuick 1.1

Rectangle {
    width: 360
    height: 360
    Text {
        anchors.centerIn: parent
        text: "Hello World"
    }
    MouseArea {
        anchors.fill: parent
        onClicked: {
            Qt.quit();
        }
    }
}

You can execute it by pressing CTRL-R or by selecting Build ‣ Run in Qt Creator. This shows the following on the screen:

../_images/hello_qt_quick_ui.png

But wait! There is no compilation step! How does the application run?

Qt Quick is script-based, just like Python or Perl. A script needs to be interpreted and executed by an engine. This engine in Qt Quick is called Qt Declarative UI Runtime [http://qt-project.org/doc/qt-4.8/qmlruntime.html]. Qt Quick applications can use this engine in two different ways:

  1. passing a qml file as a command-line option to the engine application, qmlviewer [http://qt-project.org/doc/qt-4.8/qmlviewer.html]
  2. integrating Qt Declarative UI Runtime [http://qt-project.org/doc/qt-4.8/qmlruntime.html] in C++ code and loading the qml files

Our hello_qt_quick_ui uses the first way. The qmlviewer [http://qt-project.org/doc/qt-4.8/qmlviewer.html] application located in the bin folder of the Qt installation. It contains code which uses Qt Declarative UI Runtime [http://qt-project.org/doc/qt-4.8/qmlruntime.html] to load the qml file specified on the command line. In the Qt Quick UI projects, Qt Creator automatically runs qmlviewer [http://qt-project.org/doc/qt-4.8/qmlviewer.html] to load the main qml file when you press CTRL-R or select Build ‣ Run. No compilation step is required.

The qmlviewer [http://qt-project.org/doc/qt-4.8/qmlviewer.html] application also provides debugging interfaces and many other cool goodies. Check its documentation page or call qmlviewer --help to see what is available.

This project type and the way it is integrated in Qt Creator is very simple and handy for discovering the functionality of Qt Quick. We use it most of the time. Nevertheless, in the next section we are going to learn about the Qt Quick Application project type to understand how you can use Qt Quick in a standard Qt application developed in C++.

Before we start with it, a short remark about the name Qt Quick UI given to a project type with qml files only. This underlines the major purpose of Qt Quick to serve as a script-based programming environment for application UI. Complex application logic and heavy processing should stay on the C++ side and expose its APIs to Qt Quick.

Qt Quick Application* project type

Another project type called Qt Quick Application allows you to unleash the power of Qt Quick. If you create a hello_qt_quick_app project in the wizard with this type, you get a Qt application in C++:

  • hello_qt_quick_app*.png and .svg - desktop icons for different platforms
  • hello_qt_quick_app*.desktop - desktop description files for different platforms
  • hello_qt_quick_app.pro - Qt project file. You need not touch it for now.
  • hello_qt_quick_app.pro.user - your local project settings. Automatically generated and changed by Qt Creator. You need not edit this file, nor check it in into your version control system
  • main.cpp - the main file of your application starting your own qmlviewer implemented using the QmlApplicationViewer C++ class
  • qml- a folder where the Hello World qml file resides. Add other qml files here
  • qmlapplicationviewer - a folder with implementation of the QmlApplicationViewer C++ class which initializes and starts Qt Declarative UI Runtime [http://qt-project.org/doc/qt-4.8/qmlruntime.html] with the main qml file

Your application now has its own qmlviewer-like module along with the same Hello World qml file. This is a Qt C++ application which provides the basic functionality of qmlviewer plus some additional code for integration on non-desktop platforms . If you run this project, Qt Creator compiles and builds your application like any other C++ application, and starts it. QmlApplicationViewer loads and executes Qt Quick code the same way as qmlviewer:

../_images/hello_qt_quick_app.png

Your new QmlApplicationViewer is another possible instance of Qt Declarative UI Runtime [http://qt-project.org/doc/qt-4.8/qmlruntime.html]. This way of handling Qt Quick applications opens many interesting possibilities for integrating Qt Quick code with classic C++ applications and even making C++ code available as new Qt Quick items. This is a more advanced technique beyond the scope of this tutorial. You can read more about this in Qt Declarative UI Runtime [http://qt-project.org/doc/qt-4.8/qmlruntime.html] documentation, as well as in the “Extending QML Functionality using C++” [http://qt-project.org/doc/qt-4.8/qml-extending.html] article in the Qt documentation.

Tracing what is going on

In the course of this tutorial you might want to trace what your application code does and might get interested to stop the application to inspect it at run-time. Let’s take a look at how debugging and tracing works in Qt Quick. Debugging is feature rich and is well documented in the Debugging Qt Quick Projects [http://qt-project.org/doc/qtcreator-2.6/creator-debugging-qml.html] article. When using it for the first time, you must set up the Debugging Helpers [http://qt-project.org/doc/qtcreator-2.6/creator-debugging-helpers.html].

In your first steps with Qt Quick, you will mostly use tracing as it is a simple and easy way to follow what happens in an application. You can add tracing statements by using the console.log(), console.debug() or just print() methods provided by JavaScript.

For example, if we choose to trace the place where our Hello World* application quits upon a mouse click, the code would look like this:

(helloqml/helloqml.qml in qt_quick_app_dev_intro_src.zip, see Downloads section)

/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** $QT_BEGIN_LICENSE:BSD$
** You may use this file under the terms of the BSD license as follows:
**
** "Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are
** met:
**   * Redistributions of source code must retain the above copyright
**     notice, this list of conditions and the following disclaimer.
**   * Redistributions in binary form must reproduce the above copyright
**     notice, this list of conditions and the following disclaimer in
**     the documentation and/or other materials provided with the
**     distribution.
**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
**     of its contributors may be used to endorse or promote products derived
**     from this software without specific prior written permission.
**
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
**
** $QT_END_LICENSE$
**
****************************************************************************/
import QtQuick 1.1

Rectangle {
    width: 360
    height: 360
    Text {
        anchors.centerIn: parent
        text: "Hello World"
    }
    MouseArea {
        anchors.fill: parent
        onClicked: {
            console.log("I was \"" + parent + "\"!")
            console.log("Bye for now!")
            Qt.quit();
        }
    }
}

This code produces the following in the QML Viewer tab in Qt Creator:

I was "QDeclarativeRectangle(0x23705d0)"!
Bye for now!

What’s Next?

By now you should have a working development environment and a simple project with a “Hello World” application which you can manipulate, run and inspect how it works. In the next chapter, we are going to discuss some of the core concepts of Qt Quick and take a look at what is available to do more than a simple Hello World example.

© Copyright (C) 2012 Digia. http://qt.digia.com.