Table of Content

• Qt 5.0 Roadmap
  • Mission of release
  • Platforms
  • Modules
    • Qt Essentials
    • Qt Add-Ons
  • Timelines

Qt 5.0 Roadmap

NOTE: this page is work in progress, needs review.

Mission of release

Qt 5.0 will be the foundation for a new way of developing applications, where Qt Quick is in the center of Qt. Qt 5 continues to offer all of the power of native Qt C++, and we don’t want Qt 5 to be disruptive for existing code developed for Qt 4.

Qt 5 enables highly sophisticated user experiences, offering applications the full capabilities of OpenGL/OpenGL ES graphics acceleration. In this respect, Qt 5.0 is a feature-driven release with time-to-market requirements especially for embedded environments. This implies that we should keep the scope of Qt 5.0 limited to the essential, and add more features and add-on modules in the upcoming minor releases.

• Product Definition from QtCS/11 [developer.qt.nokia.com]

Platforms

We are targeting to have the following platform configurations as reference platforms for Qt 5.0, targeting to run them on the Continuous Integration system. On all platforms, Open GL (ES) 2.0 is required.

In addition to the reference platform configurations, we would like to support the following configurations on Tier 1 level.

Modules

Qt Essentials

The Qt Essentials for Qt 5.0 are listed here.

Qt Add-Ons

The following table documents the Qt Add-On modules and their platform support in Qt 5.0.

Phonon will be maintained upstream by KDE.

Open: Add Qt Quick components modules

Open: whether Qt 5.0 will include the Qt Document Gallery add-on module.
Open: whether Qt 5.0 will include the Qt Local connectivity add-on
Open: whether Qt 5.0 will include the Qt Messaging add-on

Timelines

Target schedule for Qt 5.0 release: 1st half of 2012

Building Qt 5 from Git

Introduction

This article will try to give some hints for checking out the modularized Qt5 from git and getting it built. Please feel free to update this article as things change during development. Raise issues related to the article on http://developer.qt.nokia.com/forums/viewthread/7018 .

System Requirements

You need obviously git (>= 1.6.x) to get the packages. To properly configure and build Qt 5 from source you also need Perl and Python, as well as a working compiler.

Linux/X11

Libxcb is now the default window-system backend for platforms based on X11/Xorg, and you should therefore install libxcb and its accompanying packages. Qt5 should build with whatever libxcb version is available in your distro’s packages (but you may optionally wish to use v1.8 or higher to have threaded rendering support).

For example:

on Ubuntu/Debian:

on Ubuntu/Oneiric:

1. sudo apt-get install libxcb.* libglu1-mesa-dev

on Fedora:

1. su - -c "yum install libxcb libxcb-devel xcb-util xcb-util-devel gperf"

on ArchLinux:

1. sudo pacman -S libxcb xcb-proto xcb-util xcb-util-image xcb-util-wm

For QML2 a graphics driver with native OpenGL 2.0 support is highly recommended.

Mac OS X

XCode and git should be enough.

Windows

The commonly used compiler is Visual Studio (2008, 2010). MinGW (with gcc 4.6) might work too …

For QML2 to work, you need an OpenGL driver (NVidia,etc) for your graphics card. The Windows default driver provides only OpenGL 1.1, which is not sufficient.

You’ll also need both Python (e.g. Active Python 2.7 or higher) and Perl (e.g. Active State Perl 5.10 or higher) in the %PATH%.

• Hint: Check that Activate State Perl is found in the path before any outdated binaries, e.g. the ones that ship with msys-git.

Getting the source code

First clone the top-level qt5 git repository:

or (if you’re behind a firewall and want to use the http protocol):

Following the README file we initialize the repository. This clones the various sub-modules of Qt5:

If you plan to contribute to Qt, you should specify your codereview username so that the git remotes are properly set up:

• Hint 1a: If you’re having problems downloading the webkit repository (which is quite big), you can pass —no-webkit. This module also takes a long time to compile and if often a source of compile errors, so it is recommend to only download it if you intend to use it.
• Hint 1b: You can run init-repository again with -f later to setup webkit if you need it, and have previously deselected it.
• Hint 2: If you’re behind a firewall, pass —http.
• Hint 3: You can sign up for a user name here: https://bugreports.qt.nokia.com/

Configuring and building

Setup your path so that we pick up the Qt5 tools rather than any old Qt4 ones that may be present on your system:

For Linux:

For Windows:

Now configure the build (from top level dir). Disabling tests and examples will greatly speed up compilation:

The -developer-build options export more symbols than in a traditional Qt build in order to allow more classes and functions to be unit tested. It also defaults to a ‘debug’ build, and installs the binaries in the current directory, avoiding the need for ‘make install’. ‘-opensource’ set’s the license to be LGPL 2.1. The -nomake examples and -nomake tests parameters make sure examples and tests aren’t compiled by default. You can always decide to compile them later by hand.

• Hint1: On Linux you should also pass -no-gtkstyle. This is because on a number of systems (at least SUSE and Gentoo) `pkg-config —cflags gtk+-2.0` actually returns paths that include the system Qt4.x include directories.

• Hint2: You can add -confirm-license to get rid of the question whether you agree to the license.

Now make it as per usual (adjust -j option to suit number of cores + 1):

Or just make a specific module, e.g. declarative, and modules it depends on:

Installing

• Note: Installation is only needed if you haven’t used the configure options -developer-build or -prefix “.”. Otherwise you can just use Qt from the build directory.

To install, simply run

But if you’re installing into a non-standard path for testing qt5, you’ll need to set your path to include the installation directory’s bin directory. You should either make sure you don’t have QTDIR set in your environment, or set QTDIR to the installation path before running make install. For example, if installing into /opt/qt5 (this assumes you are using bash; for csh-derived shells you’ll need to run setenv equivalents first):

Cleaning

To really get a clean tree use:

since make confclean no longer works from the top-level of the repo.

Getting updates

To update both the qt5.git repo as well as the submodules to the list of revisions that are known to work, run

• Warning: git submodule update does a hard reset on submodules, potentially getting rid of any local commits you’ve done! If the latter happened to you (and you haven’t been working with branches anyhow), git reflog is your friend ….

Using master branches in the submodules

By default the checkout will not contain the latest master branches of each individual submodule repository, but a combination of versions that are known to work together. If you want to get the absolute latest stuff you can do so on a per-module basis, e.g.

or use qt5_tool to update all repositories to master:

However, there’s a good chance that compilation will fail due to incompatible versions of submodules! You might want to ask other persons actively working on a module how to resolve these incompatibilities.

Issues

configure fails with “No QPA platform plugin enabled!”

You should install the libxcb and it’s accompanying packages, see ‘Build Requirements’.

qmlscene segfaults “Cannot create platform GL context, none of GLX, EGL, DRI2 is enabled”

Try installing the libx11-xcb-dev package:

afterwards you have to re-run configure and force qtbase/src/plugins/platforms/xcb to recompile.

qdeclarative doesn’t compile because of missing v8.lib (Windows)

Compiling v8 in qtbase requires Python. Make sure you have a python.exe in your %PATH%, go to qtjsbackend, run qmake && nmake.

WebKit doesn’t compile, missing ICU

Currently there is no configure time check for ICU, so install it through the package manager through

Or build it without webkit support by passing -no-webkit

Debugging OpenGL issues (Windows)

Set the environment variable QT_LIGHTHOUSE_WINDOWS_VERBOSE=gl:1 and run the application with DebugView installed. The log will show the requested vs obtained OpenGL version. If the log tells you that it only has OpenGL 1.1, QML2 will not work. Note that qmlscene will not report errors about unsupported OpenGL versions.

Questions & Comments

Please raise questions & comments about this article in the forum : http://developer.qt.nokia.com/forums/viewthread/7018

How to Locally Disable QRC in QML

By default, when you load any file in QML using QRC (Qt Resource System [developer.qt.nokia.com]), all files down the hierarchy tree are loaded using resource system, too. This is nice and handy for most use cases, because it allows you to switch to QRC without big changes to the source code.

But what if you are using resources, and suddenly need to load a non-qrc file? For example, in an app you are developing, a certain module, or game’s save file, can be provided by user at runtime, using relative path. Currently, QML will not allow that – once you’ve started using resources, the declarative engine loads all files using QRC scheme.

I faced the same problem and found a pretty nice and easy solution: QRC can be locally disabled. It will not break anything – in fact, after turning the QRC scheme off, you can still load a file from resource system, and the QML engine will automatically reapply the scheme.

Here’s what needs to be done (to make the example simple, I assume we need to disable QRC in a Loader element):

1. In C++, define a signal to be emitted before the new file is to be loaded, and a slot to receive the signal. Connect them together, and add as context properties to your QML [developer.qt.nokia.com]. In this case, I’ll use “void disableQrcSignal(QObject *object);” as signal, and “void disableQrcSlot(QObject *object);” as slot
2. Before you change “source” property of your Loader, send “disableQrcSignal(loaderId)” signal.

Here’s a snippet (I’m using a global property, fileToLoad, to store the path):

In your disableQrcSlot() body, use this code:

And that’s it! Now you can use this signal in any place in your code to temporarily disable QRC loading.

Table of Content

• Extend Qt Creator
• Contributing plugins
• Qt Creator Plug-in Gallery
  • Class browser
  • Doxygen generator
  • CppHelper
  • Macros
  • Emacs keys
  • autotools (MERGED)
  • UML tool
  • Remote Compiler
  • Profiling plugin
  • compile errors inline
  • display todo / fixme etc. comments
  • TODO plugin
  • AStyle plugin
  • WebRunTime Plugin
  • Bazaar plugin
  • OpenPilot
  • Mylyn Plugin
  • CruiseControl Monitor Plugin
  • XmlTree Plugin
  • Static Code Quality Plugin
  • CodeBlocks Project Manager Plugin
  • Google Native Client Toolchain Plugin
  • Premake Project Manager Plugin
• External documentation

Extend Qt Creator

Even though Qt Creator and Eclipse are different tools written in different programming languages, they still share the approach of adding all the functionality by plugins. So, from that point of view Qt Creator and Eclipse can be seen more as plugin frameworks instead of IDEs.

A plugin implements certain extension points but at the same time can also define new extension points. And that’s where Qt Creator and Eclipse differentiate.

In Eclipse, the extension points are usually defined as soon as the plugin is implemented meaning that those interfaces are often best guesses based on one example extension if at all. This may easily result in unnecessary extension in the first place or too inflexible or limited interfaces for more real world use cases.

Qt Creator takes another approach. In most cases plugins do not define extension points immediately, so it’s always treated as a leave. For the first use case which requires an extension we still recommend to put the new functionality into the existing plugin implementation. Once a second or third use case comes up we start refactoring the original plugin and define the extension points. Obviously, this is not a 100% guarantee that those interfaces are perfect and cover all future needs, but it’s definitely better than basing the extension point on only one example or even pure guesses.

Contributing plugins

Please check Qt Creator Plug in Contribution Guide when considering contributing a plugin to Qt Creator.

Qt Creator Plug-in Gallery

Class browser

site [cppblog.com]

Doxygen generator

generates doxygen comments from source code
site [dev.kofee.org]

CppHelper

generates implementation-stubs (discontinued, replaced by refactoring action in Qt Creator 2.1)
site [gitorious.org]

Macros

record action-sequence and playback status (merged, first version shipping it is Qt Creator 2.2)
site [gitorious.org]

Emacs keys

Emacs-style keybindings, alike “FakeVim”
site [github.com]

autotools (MERGED)

Autotool support for Creator
site [gitorious.org]”

Was merged into Qt Creator 2.4.

UML tool

doc [vakken.groept.be]

Remote Compiler

forum.nokia available in Nokia Qt SDK

Profiling plugin

(oprofile / linux based)
site [qt.gitorious.org]

compile errors inline

display compile warnings and errors (tasks) inline
announcement [lists.qt.nokia.com], screenshot [lists.qt.nokia.com]

display todo / fixme etc. comments

Display comments in the form of //todo bla bla in the build issues tab.
The keywords that introduce the comments are configurable.
announcement [lists.qt.nokia.com], screenshot [lists.qt.nokia.com]

TODO plugin

This plugin add pane with list all TODO, FIXME, etc.
In current version available:

• Plugin settings
• Task window or Todo pane output selector
• Scanning all file in project or only current file selector
• Keywords editor
• Locale support

Download source [gitorious.org]
Screenshot [dl.yarlug.org]

AStyle plugin

Full featured code pretty printer plugin using astyle
site [astyleplugin.berlios.de]

WebRunTime Plugin

Support for developing web based applications. Only a video of the plugin in action.
Status: unknown
video [youtube.com]

Bazaar plugin

A plugin adding support for the bazaar version control system. Status: merged (first version shipping it is Qt Creator 2.2)
site [blueprints.launchpad.net]

OpenPilot

A plugin using Qt Creator as a plugin manager only, embedding a map.
Status: unknown
site [openpilot.org]

Mylyn Plugin

Mylyn is a application lifecycle management plugin, inspired by an eclipse plugin of the same name. Status: unknown, no changes for a couple of month now.
site [github.com]

CruiseControl Monitor Plugin

A simple plugin for monitoring a CruiseControl continuous integration server
site [code.google.com]

XmlTree Plugin

A plugin for reading and editing xml files as tree.
site [gitorious.org]

Static Code Quality Plugin

A plugin for performing static code quality tests. Based on Krazy and making use of Qt Script and the cpp parser that comes with Qt Creator. Currently in a development state and not completely ready for use.
site [gitorious.org]

CodeBlocks Project Manager Plugin

This plugin can read Codeblocks .workspace project files. It reads the projects hierarchy and parses the individual .cbp project files to extract the source and header files and the build targets. Using commandline Codeblocks it allows you to (re)build your workspace. Also the build output is parsed(gcc and msvc supported).
site [gitorious.org]

Google Native Client Toolchain Plugin

Adds the Chrome browser as a target. For use with the NaCl port of Qt.
site [developer.qt.nokia.com]

Premake Project Manager Plugin

This plugin adds support of Premake [industriousone.com] build configuration tool into Qt Creator.
site [gitorious.org]

External documentation

You can display external documentation in the Qt Creator Help mode. For more information, see the Qt Creator Manual [doc.qt.nokia.com].

See Qt Creator Documentation Gallery [developer.qt.nokia.com] for a list of them.

QML Dynamic Objects

Introduction

QML has a very reach set of techniques for visualization control like visual objects appearing/disappearing on the scene. We mean dynamic effects which could be controlled programmatically. These techniques could be classified in three groups. The techniques from the first group control a QML object property to hide and/or render a visual object. For example, opacity property is very often used by developers and as you know it serves as a mirror to visual state of an item. Another useful properties are visible, z, color:transparent. The second group mechanisms apply some transformations to objects – moving of an object off the screen (assign negative values to x,y coordinates), transforming geometrical object shape. For instance, we may control object visualization through width and height properties. Have a look at the techniques groups illustrations bellow:
First and second group

Third group

The next snippet illustrates how width and height properties could be used to control visibility:

dynamicWidth.qml

You guessed already that top rectangle is constructed when QML file is loaded, but not visualized. It is because its width and height properties are not defined. We determine them later in MouseArea script block.

The techniques of the first and second groups do not manage computer memory at all – the hidden objects are kept stored in memory. This could be considered as a plus because the hidden objects are easily accessible through their IDs.

The third group includes mechanisms based on dynamic loading of QML objects. These are QML constructs Loader and dynamic creation of objects. This article discusses dynamic creation of objects [doc.qt.nokia.com]. More information about Loader utilization is here [developer.qt.nokia.com].

Creation of Dynamic QML Objects

The process of dynamic creating of QML objects consists of two steps. Firstly, an object is created and secondly newly created object is loaded. The process is performed in a JavaScript context only. In other words, we have some JavaScript methods, which could be invoked in a script block.

The dynamic object is normally formatted as a QML computer file or we want to get it as a string. Our considerations are limited to the second case. For this case steps of creating and loading are combined in one step. The signature of the respective JavaScript method is as follows [doc.qt.nokia.com]:

The first argument in the method invocation is a string formatted as a QML file, for example:

We use single quotes for the QML string to avoid conflict with double quotes in color property definition.

The second argument is the ID of QML item in which context the new object is created and loaded. That means that newly created object has as parent this context item. In invocation the context item ID is supplied as a variable name (no quotes are needed).

The third argument is a string used as a file name in error reporting in Qt IDE. For example if an error is encountered in loaded QML string it is reported as one in the file with filename name. In invocation filename as a string has to be surrounded in double quotes.

The function createQmlObject() is a method of the global QML Qt object [doc.qt.nokia.com].

Formally it is described as:

If you are tempted to use a Loader element from the QML string it will probably not work. It is because loading of an external file needs some time, but the method createQmlObject() returns not waiting for such operations. Here is a complete example of createQmlObject() method utilization:

dynamicObject.qml

Practically it is inconvenient to supply a long QML string in createQmlObject() call. We could define a string property and assign to it QML string as property value. This is demonstrated in the following example:

dynamicObjectTop.qml

Communication with Dynamic Objects

The dynamically created QML object is not accessible through its ID. We need other mechanisms for communication with dynamic objects and these are signals and QML signal objects connect () method. By communication we mean exchange of information between the caller (main QML file) and the callee (dynamically created QML file) and in both directions.

The next snippet shows that a property defined at the caller top level is visible (directly accessible) in the QML dynamic object:

dynamicObjectProperty.qml

In case we want to pass some information from QML string to the main file we define a signal, then connect it to a JavaScript method defined in the main QML file and finally emit the signal (in QML string):

dynamicObjectConnect.qml

In the QML string we define the signal send, which invokes function fun1() defined in main QML. A parameter is passed also. And vice versa: in the main QML the signal forward is defined and emitted. It calls function fun2() defined in QML string.

Dynamic Objects Behavior – Nested Objects

Let us create an application with the following functionality:
1. The user enters some text in a QML TextInput element;
2. The entered text is displayed in a window;
3. The user is asked to confirm the entered text in a dialog window;

The new point here is that from a dynamic object we want to create and load a next dynamic object.

dynamicUseCase.qml

Some fragments of the above code need more explanation as they implement several rules of QML dynamic objects. In the first place, a dynamic QML object (rectangle abc) could contain a nested QML string – rectangle nested. As you see, the nested objects are in the same name space and this is used when we design the application layout – it is applied bounding of properties values. Moreover, the nested objects are executed in the context of the main QML file and they use properties from the main application space.

To invoke the first dynamic object (rectangle abc) we use onAccepted signal generated after you enter the text in the QML TextInput field and hit <Enter>. The entered text is displayed in the rectangle abc. When you click on this rectangle, following onClicked signal, the nested object (rectangle nested) is rendered.

Destroying Dynamic Objects

Analyzing the above code samples you probably asked yourself already how one could close dynamically created QML objects. To release (delete) a dynamically created QML object you could use destroy() method from within a JavaScript context. The method is called as member of newly created dynamic object. For example, considering our last code snippet, we call: dynamicObject.destroy(). The destroy() method has a parameter that supplies the time delay before the dynamic object will be destroyed. It is measured in milliseconds with a default value of zero.
In the file dynamicUseCase.qml you have an commented section (at the file bottom) that experiments with destroy() method. Uncomment this section and call to release() function in onAccepted script block.

Notes:
1. The .qml files used in the discussions above could be downloaded here [sugarsync.com].
2. The code samples were tested in a desktop environment – Windows 7, Qt Creator 2.4.1 (based on Qt 4.7.4).

Table of Content

• Threads, Events and QObjects
  • Warning: Beta Version
• Introduction
  • Prerequisites
• Events and the event loop
  • What requires a running event loop?
  • Blocking the event loop
  • Forcing event dispatching
• Qt thread classes
  • QThread
  • QRunnable and QThreadPool
  • QtConcurrent
  • Feature comparison
• Threads and QObjects
  • Per-thread event loop
  • Signals and slots across threads
  • DOs and DON'Ts
• When should I use threads?
  • When you have to use a blocking API
  • When you want to scale with the number of CPUs
  • When you don't want to be possibly blocked by others
• When shouldn't I use threads?
  • Timers
  • Networking / state machines
  • Jobs splittable in chunks
• Some examples
  • MD5 hash
• References

English Русский 中文

Threads, Events and QObjects

Warning: Beta Version

The article is almost done, but it needs a bit of polishing and some good examples. Any review or contribution is welcome! Discussion about this article happens in this thread [developer.qt.nokia.com] .

Introduction

You’re doing it wrong. — Bradley T. Hughes

One of the most popular topics on the #qt IRC channel [irc.freenode.net] is threading: many people join the channel and ask how they should solve their problem with some code running in a different thread.

Nine times out of ten, a quick inspection of their code shows that the biggest problem is the very fact they’re using threads in the first place, and they’re falling in one of the endless pitfalls of parallel programming.

The ease of creating and running threads in Qt, combined with some lack of knowledge about programming styles (especially asynchronous network programming, combined with Qt’s signals and slots architecture) and/or habits developed when using other tookits or languages, usually leads to people shooting themselves in the foot. Moreover, threading support in Qt is a double-edged sword: while it makes it very simple for you to do multithread programming, it adds a certain number of features (especially when it comes to interaction with QObjects) you must be aware of.

The purpose of this document is not to teach you how to use threads, do proper locking, exploit parallelism, nor write scalable programs; there are many good books about these topics; for instance, take a look to the recommended reading list on this page [doc.qt.nokia.com]. Instead, this small article is meant to be a guide to introduce users to threading in Qt 4, in order to avoid the most common pitfalls and help them to develop code that is at the same time more robust and with a better structure.

Prerequisites

Think of it this way: threads are like salt, not like pasta.
You like salt, I like salt, we all like salt. But we eat more pasta.
— Larry McVoy

Not being a general-purpose introduction to (threads) programming, we expect you to have some previous knowledge about:

• C++ basics (though most suggestions do apply to other languages as well);
• Qt basics: QObjects, signals and slots, event handling;
• what a thread is and what the relationships are between threads, processes and the operating system;
• how to start and stop a thread, and wait for it to finish, under (at least) one major operating system;
• how to use mutexes, semaphores and wait conditions to create thread-safe/reentrant functions, data structures, classes.

In this document we’ll follow the Qt naming conventions [doc.qt.nokia.com], which are:

• Reentrant A class is reentrant if it’s safe to use its instances from more than one thread, provided that at most one thread is accessing the same instance at the same time. A function is reentrant if it’s safe to invoke it from more than one thread at the same, provided that each invocation references unique data. In other words, this means that users of that class/function must serialize all accesses to instances/shared data by means of some external locking mechanism.
• Thread-safe A class is thread-safe if it’s safe to use its instances from more than one thread at the same time. A function is thread-safe if it’s safe to invoke it from more than one thread at the same time even if the invocations reference shared data.

Events and the event loop

Being an event-driven toolkit, events and event delivery play a central role in Qt architecture. In this article we’ll not give a comprehensive coverage about this topic; we’ll instead focus on some thread-related key concepts (see here [doc.qt.nokia.com] and here [doc.qt.nokia.com] for more information about the Qt event system).

An event in Qt is an object which represents something interesting that happened; the main difference between an event and a signal is that events are targeted to a specific object in our application (which decides what to do with that event), while signals are emitted “in the wild”. From a code point of view, all events are instances of some subclass of QEvent [doc.qt.nokia.com], and all QObject-derived classes can override the QObject::event() virtual method in order to handle events targeted to their instances.

Events can be generated from both inside and outside the application; for instance:

• QKeyEvent and QMouseEvent objects represent some kind of keyboard and mouse interaction, and they come from the window manager;
• QTimerEvent objects are sent to a QObject when one of its timers fires, and they (usually) come from the operating system;
• QChildEvent objects are sent to a QObject when a child is added or removed, and they come from inside your Qt application.

The important thing about events is that they’re not delivered as soon as they’re generated; they’re instead queued up in an event queue and sent sometime later. The dispatcher itself loops around the event queue and sends queued events to their target objects, and therefore it is called the event loop. Conceptually, this is how an event loop looks (see the Qt Quarterly article linked above):

We enter Qt’s main event loop by running QCoreApplication::exec(); this call blocks until QCoreApplication::exit() or QCoreApplication::quit() are called, terminating the loop.

The “wait_for_more_events()” function blocks (that is, it’s not a busy wait) until some event is generated. If we think about it, all that can generate events at that point is some external source (dispatching for all internal events is now complete and there were no more pending events in the event queue to delivery). Therefore, the event loop can be woken up by:

• window manager activity (key/mouse presses, interaction with the windows, etc.);
• sockets activity (there’s some data available to read, or a socket is writable without blocking, there’s a new incoming connection, etc.);
• timers (i.e. a timer fired);
• events posted from other threads (see later).

In a UNIX-like system, window manager activity (i.e. X11) is notified to applications via sockets (Unix Domain or TCP/IP), since clients use them to communicate with the X server. If we decide to implement cross-thread event posting with an internal socketpair(2), all that is left is being woken up by activity on:

• sockets;
• timers;

which is exactly what the select(2) system call does: it watches over a set of descriptors for activity and it times out (with a configurable timeout) if there’s no activity for a certain while. All Qt needs to do is converting what select returns into an object of the right QEvent subclass and queue it up in the event queue. Now you know what’s inside an event loop :)

What requires a running event loop?

This isn’t an exhaustive list, but if you have the overall picture, you should be able to guess which classes require a running event loop.

• Widgets painting and interaction: QWidget::paintEvent() will be called when delivering QPaintEvent objects, which are generated both by calling QWidget::update() (i.e. internally) or by the window manager (for instance, because a hidden window was shown). The same thing holds for all kinds of interaction (keyboard, mouse, etc.): the corresponding events will require an event loop to be dispatched.
• Timers: long story short, they’re fired when select(2) or similar calls time out, therefore you need to let Qt do those calls for you by returning to the event loop.
• Networking: all low-level Qt networking classes (QTcpSocket, QUdpSocket, QTcpServer, etc.) are asynchronous by design. When you call read(), they just return already available data; when you call write(), they schedule the writing for later. It’s only when you return to the event loop the actual reading/writing takes place. Notice that they do offer synchronous methods (the waitFor* family of methods), but their use is discouraged because they block the event loop while waiting. High-level classes, like QNetworkAccessManager, simply do not offer any synchronous API and require an event loop.

Blocking the event loop

Before discussing why you should never ever block the event loop, let’s try to figure out what this “blocking” means. Suppose you have a Button widget which emits a signal when clicked; connected to this signal there’s a slot of our Worker object, which does a lot of work. After you click the button, the stack trace will look like this (the stack grows downwards):

1. main(int, char **)
2. QApplication::exec()
3. […]
4. QWidget::event(QEvent *)
5. Button::mousePressEvent(QMouseEvent *)
6. Button::clicked()
7. […]
8. Worker::doWork()

In main() we started the event loop, as usual, by calling QApplication::exec() (line 2). The window manager sent us the mouse click, which was picked up by the Qt kernel, converted in a QMouseEvent and sent to our widget’s event() method (line 4) by QApplication::notify() (not shown here). Since Button didn’t override event(), the base class implementation (QWidget) is called. QWidget::event() detects the event is actually a mouse click and calls the specialized event handler, that is, Button::mousePressEvent() (line 5). We overrode this method to emit the Button::clicked() signal (line 6), which invokes the Worker::doWork slot of our worker object (line 7).

While the worker is busy working, what’s the event loop doing? You should’ve guessed it: nothing! It dispatched the mouse press event and it’s blocked waiting for the event handler to return. We managed to block the event loop, which means that no event is sent any more, until we return from the doWork() slot, up the stack, to the event loop, and let it process pending events.

With the event delivery stuck, widgets won’t update themselves (QPaintEvent objects will sit in the queue), no further interaction with widgets is possible (for the same reason), timers won’t fire and networking communications will slow down and stop. Moreover, many window managers will detect that your application is not handling events any more and tell the user that your application isn’t responding. That’s why is so important to quickly react to events and return to the event loop as soon as possible!

Forcing event dispatching

So, what do we do if we have a long task to run and don’t want to block the event loop? One possible answer is to move the task into another thread: in the next sections we’ll see how to do that. We also have the option to manually force the event loop to run, by (repeatedly) calling QCoreApplication::processEvents() inside our blocking task. QCoreApplication::processEvents() will process all the events in the event queue and return to the caller.

Another available option we can use to forcibly reenter the event loop is the QEventLoop [doc.qt.nokia.com] class. By calling QEventLoop::exec() we reenter the event loop, and we can connect signals to the QEventLoop::quit() slot to make it quit. For instance:

QNetworkReply doesn’t offer a blocking API and requires an event loop to be running. We enter a local QEventLoop, and when the reply has finished, the local event loop quits.

Be very careful when reentering the event loop “by other paths”: it can lead to unwanted recursions! Let’s go back to the Button example. If we call QCoreApplication::processEvents() inside the doWork() slot, and the user clicks again on the button, the doWork() slot will be invoked again:

1. main(int, char **)
2. QApplication::exec()
3. […]
4. QWidget::event(QEvent *)
5. Button::mousePressEvent(QMouseEvent *)
6. Button::clicked()
7. […]
8. Worker::doWork() // first, inner invocation
9. QCoreApplication::processEvents() // we manually dispatch events and…
10. […]
11. QWidget::event(QEvent * ) // another mouse click is sent to the Button…
12. Button::mousePressEvent(QMouseEvent *)
13. Button::clicked() // which emits clicked() again…
14. […]
15. Worker::doWork() // DANG! we’ve recursed into our slot.

A quick and easy workaround for this is passing QEventLoop::ExcludeUserInputEvents to QCoreApplication::processEvents(), which tells the event loop to not dispatch any user input event (the events will simply stay in the queue).

Luckily, the same thing does not apply to deletion events (the ones posted in the event queue by QObject::deleteLater()). In fact, they are handled in a special way by Qt, and are processed only if the running event loop has a smaller degree of “nesting” (w.r.t. event loops) than the one where deleteLater was called. For instance:

will not make object a dangling pointer (the event loop entered by QDialog::exec() is more nested than the deleteLater call). The same thing applies to local event loops started with QEventLoop. The only notable exception I’ve found to this rule (as of Qt 4.7.3) is that if deleteLater is called when NO event loop is running, then the first event loop entered will pick up the event and delete the object. This is pretty much reasonable, since Qt does not know about any “outer” loop that will eventually perform the deletion, and therefore deletes the object immediately.

.

Qt thread classes

A computer is a state machine. Threads are for people who can’t program state machines.
— Alan Cox

Qt has had thread support for many years (Qt 2.2, released on 22 Sept 2000, introduced the QThread class.), and with the 4.0 release thread support is enabled by default on all supported platforms (although it can be turned off, see here [doc.qt.nokia.com] for more details). Qt now offers several classes for dealing with threads; let’s start with an overview.

QThread

QThread [doc.qt.nokia.com] is the central, low-level class for thread support in Qt. A QThread object represents one thread of execution. Due to the cross-platform nature of Qt, QThread manages to hide all the platform-specific code that is needed to use threads on different operating systems.

In order to use a QThread to run some code in a thread, we can subclass it and override the QThread::run() method:

Then we can use

to actually start the new thread. Note that since Qt 4.4 QThread is no longer an abstract class; now the virtual method QThread::run() instead simply calls QThread::exec();, which starts the thread’s event loop (more info on this later).

QRunnable and QThreadPool

QRunnable [doc.qt.nokia.com] is a lightweight abstract class that can be used to start a task in another thread in a “run and forget” fashion. In order to do so, all we have to do is subclass QRunnable and implement its run() pure virtual method:

To actually run a QRunnable object we use the QThreadPool [doc.qt.nokia.com] class, which manages a pool of threads. By calling QThreadPool::start(runnable) we put a QRunnable in a QThreadPool’s runqueue; as soon as a thread becomes available, the QRunnable will be picked up and run into that thread. All Qt applications have a global thread pool available by calling QThreadPool::globalInstance(), but one can always create a private QThreadPool instance and manage it explicitely.

Notice that, not being a QObject, QRunnable has no built-in means of explicitely communicating something to other components; you have to code that by hand, using low-level threading primitives (like a mutex-guarded queue for collecting results, etc.).

QtConcurrent

QtConcurrent [doc.qt.nokia.com] is a higher-level API, built on top of QThreadPool, useful to deal with the most common parallel computation patterns: map [en.wikipedia.org]), reduce [en.wikipedia.org]), and filter [en.wikipedia.org]) ; it also offers a QtConcurrent::run() method that can be used to easily run a function in another thread.

Unlike QThread and QRunnable, QtConcurrent does not require us to use low-level synchronization primitives: all QtConcurrent methods instead return a QFuture [doc.qt.nokia.com] object, which can be used to query the computation status (its progress), to pause/resume/cancel the computation, and that also contains its results. The QFutureWatcher [doc.qt.nokia.com] class can be used to monitor a QFuture progress and interact with it by means of signals and slots (notice that QFuture, being a value-based class, doesn’t inherit QObject).

Feature comparison

¹ Except QtConcurrent::run, which is implemented using QRunnable and therefore shares its pros and cons.

Threads and QObjects

Per-thread event loop

So far we’ve always talked about “the event loop”, taking somehow per granted that there’s only one event loop in a Qt application. This is not the case: QThread objects can start thread-local event loops running in the threads they represent. Therefore, we say that the main event loop is the one created by the thread which invoked main(), and started with QCoreApplication::exec() (which must be called from that thread). This is also called the GUI thread, because it’s the only thread in which GUI-related operations are allowed. A QThread local event loop can be started instead by calling QThread::exec() (inside its run() method):

As we mentioned before, since Qt 4.4 QThread::run() is no longer a pure virtual method; instead, it calls QThread::exec(). Exactly like QCoreApplication, QThread has also the QThread::quit() and QThread::exit() methods to stop the event loop.

A thread event loop delivers events for all QObjects that are living in that thread; this includes, by default, all objects that are created into that thread, or that were moved to that thread (more info about this later). We also say that the thread affinity of a QObject is a certain thread, meaning that the object is living in that thread. This applies to objects which are built in the constructor of a QThread object:

What’s the thread affinity of obj, otherObj, yetAnotherObj after we create a MyThread object? We must look at the thread that created them: it’s the thread that ran the MyThread constructor. Therefore, all three objects are not living in the MyThread thread, but in the thread that created the MyThread instance (which, by the way, is where the instance is living as well).

We can query anytime the thread affinity of a QObject by calling QObject::thread(). Notice that QObjects created before a QCoreApplication object have no thread affinity, and therefore no event dispatching will be done for them (in other words, QCoreApplication builds up the QThread object that represents the main thread).

We can use the thread-safe QCoreApplication::postEvent() method for posting an event for a certain object. This will enqueue the event in the event loop of the thread the object is living in; therefore, the event will not be dispatched unless that thread has a running event loop.

It is very important to understand that QObject and all of its subclasses are not thread-safe (although they can be reentrant); therefore, you can not access a QObject from more than one thread at the same time, unless you serialize all accesses to the object’s internal data (for instance, by protecting it with a mutex). Remember that the object may be handling events dispatched by the event loop of the thread it is living in while you’re accessing it from another thread! For the same reason, you can’t delete a QObject from another thread, but you must use QObject::deleteLater(), which will post an event that will ultimately cause its deletion by the thread the object is living in.

Moreover, QWidget and all of its subclasses, along with other GUI-related classes (even not QObject-based, like QPixmap) are not reentrant either: they can be used exclusively from the GUI thread.

We can change a QObject’s affinity by calling QObject::moveToThread(); this will change the affinity of the object and of its children. Since QObject is not thread-safe, we must use it from the thread the object is living in; that is, you can only push objects from the thread they’re living in to other threads, and not pull them or move them around from other threads. Moreover, Qt requires that the child of a QObject must live in the same thread where the parent is living. This implies that:

• you can’t use QObject::moveToThread() on a object which has a parent;
• you must not create objects in a QThread using the QThread object itself as their parent:

This is because the QThread object is living in another thread, namely, the one in which it was created.

Qt also requires that all objects living in a thread are deleted before the QThread object that represents the thread is destroyed; this can be easily done by creating all the objects living in that thread on the QThread::run() method’s stack.

Signals and slots across threads

Given these premises, how do we call methods on QObjects living in other threads? Qt offers a very nice and clean solution: we post an event in that thread’s event queue, and the handling of that event will consist in invoking the method we’re interested in (this of course requires that the thread has a running event loop). This facility is built around the method introspection provided by moc: therefore, only signals, slots and methods marked with the Q_INVOKABLE macro are invokable from other threads.

The QMetaObject::invokeMethod() static method does all the work for us:

Notice that since the arguments need to be copied in the event which is built behind the scenes, their types need to provide a public constructor, a public destructor and a public copy constructor, and must be registered within Qt type system by using the qRegisterMetaType() function.

Signals and slots across threads work in a similar way. When we connect a signal to a slot, the fifth argument of QObject::connect is used to specify the connection type:

• a direct connection means that the slot is always invoked directly by the thread the signal is emitted from;
• a queued connection means that an event is posted in the event queue of the thread the receiver is living in, which will be picked up by the event loop and will cause the slot invocation sometime later;
• a blocking queued connection is like a queued connection, but the sender thread blocks until the event is picked up by the event loop of the thread the receiver is living in, the slot is invoked, and it returns;
• an automatic connection (the default) means that if the thread the receiver is living in is the same as the current thread, a direct connection is used; otherwise, a queued connection is used.

In every case, keep in mind the thread the emitting object is living in has no importance at all! In case of an automatic connection, Qt looks at the thread that invoked the signal and compares it with the thread the receiver is living in to determine which connection type it has to use. In particular, the current Qt documentation [doc.qt.nokia.com] (4.7.1) is simply wrong when it states:

Auto Connection (default) The behavior is the same as the Direct Connection, if the emitter and receiver are in the same thread. The behavior is the same as the Queued Connection, if the emitter and receiver are in different threads.

because the emitter object’s thread affinity does not matter. For instance:

The signal aSignal() will be emitted by the new thread (represented by the Thread object); since it is not the thread the Object object is living in (which, by the way, is the same thread the Thread object is living in, just to stress that the sender’s thread affinity doesn’t matter), a queued connection will be used.

Another common pitfall is the following one:

When “obj” emits its aSignal() signal, which kind of connection will be used? You should’ve guessed it: a direct connection. That’s because the Thread object is living in the thread that emits the signal. In the aSlot() slot we could then access some Thread’s member variable while they’re being accessed by the run() method, which is running concurrently: this is the perfect recipe for disaster.

Yet another example, probably the most important one:

In this case a queued connection is used, therefore you’re required to run an event loop in the thread the Thread object is living in.

A solution you’ll often found in forums, blog posts etc. is to add a moveToThread(this) to the Thread constructor:

which indeed will work (because now the affinity of the Thread object changed), but it’s a very bad design. What’s wrong here is that we’re misunderstanding the purpose of a thread object (the QThread subclass): QThread objects are not threads; they’re control objects around a thread, therefore meant to be used from another thread (usually, the one they’re living in).

A good way to achieve the same result is splitting the “working” part from the “controller” part, that is, writing a QObject subclass and using QObject::moveToThread() to change its affinity:

DOs and DON’Ts

You can…

• … add signals to a QThread subclass. It’s perfectly safe and they’ll do the “right thing” (see above; the sender’s thread affinity does not matter).

You shouldn’t …

• … use moveToThread(this).
• … force the connection type: this usually means that you’re doing something wrong, like mixing the control interface of QThread with the program logic (which should stay in a separate object which lives in that thread).
• … add slots to a QThread subclass: they’ll be invoked from the “wrong” thread, that is, not the one the QThread object is managing, but the one that object is living in, forcing you to specify a direct connection and/or to use moveToThread(this).
• … use QThread::terminate.

You must not…

• … quit your program when threads are still running. Use QThread::wait to wait for their termination.
• … destroy a QThread while the thread that it’s managing is still running. If you want some kind of “self-destruction”, you can connect the finished() signal with the deleteLater() slot.

When should I use threads?

When you have to use a blocking API

If you need to use a library or other code that doesn’t offer a non-blocking API (by means of signals and slots, or events, or callbacks, etc.), then the only viable solution in order to avoid freezing the event loop is to spawn a process or a thread. Since creating a new worker process, having it doing the job and communicating back the results is definetely harder and more expensive than just starting a thread, the latter is the most common choice.

A good example of such an API is address resolution (just to show you that we’re not talking about 3rd-party crappy API. This is something included in every C library out there), which is the process of taking an host name and converting it into an address. This process involves a query to a (usually remote) system — the Domain Name System, or DNS. While, usually, the response is almost instantaneous, the remote servers might fail, some packet might get lost, the network connection might break, and so on; in short, it might take dozens of seconds before we get a reply from our query.

The only standard API available on UNIX systems is blocking (not only the old-fashioned gethostbyname(3), but also the newer and better getservbyname(3) and getaddrinfo(3)). QHostInfo [doc.qt.nokia.com], the Qt class that handles host name lookups, uses a QThreadPool to enable the queries to run in the background (see here [qt.gitorious.com] ; if thread support is turned off, it switches back to a blocking API).

Other simple examples are image loading and scaling. QImageReader [doc.qt.nokia.com] and QImage [doc.qt.nokia.com] only offer blocking methods to read an image from a device, or to scale an image to a different resolution. If you’re dealing with very large images, these processes can take up to (tens of) seconds.

When you want to scale with the number of CPUs

Threads allow your program to take advantage from multiprocessor systems. Since each thread is scheduled independently by the operating system, if your application is running on such a machine the scheduler is likely to run each thread on a different processor at the same time.

For instance, consider an application that generates thumbnails from a set of images. A thread farm of n threads (that is, a thread pool with a fixed number of threads), one per each CPU available in the system (see also QThread::idealThreadCount() ), can spread the work of scaling down the images into thumbnails on all the threads, effectively gaining an almost linear speedup with the number of the processors (for simplicity’s sake, we consider the CPU being the bottleneck).

When you don’t want to be possibly blocked by others

MEH. BETTER START WITH AN EXAMPLE.

This is quite an advanced topic, so feel free to skip it for now. A nice example of this use case comes from QNetworkAccessManager usage inside WebKit. WebKit is a modern browser engine, that is, a set of classes to lay out and display web pages. The Qt widget that uses WebKit is QWebView.

QNetworkAccessManager is a Qt class that deals with HTTP requests and responses for all purposes, we can consider it to be the networking engine of a web browser. Its current design does not make use of any worker threads; all networking is handled in the same thread QNetworkAccessManager and its QNetworkReplys are living in.

While not using threads for networking is a very good idea, it has also a major drawback: if you don’t read data from the socket as soon as possible, the kernel buffers will fill up, packets will begin to be dropped, and the transfer speed will decrease considerably.

Socket activity (i.e., availability of some data to read from a socket) is managed by Qt’s event loop. Blocking the event loop will therefore lead to a loss of transfer performance, because nobody will be notified that there are data to read (and thus nobody will read them).

But what could block the event loop? The sad answer is: WebKit itself! As soon as some data are received, WebKit uses them to start laying out the web page. Unfortunately, the layout process is quite complicated and expensive, therefore it blocks the event loop for a (short) while, enough to impact on ongoing transfers (broadband connections play their role here, filling up kernel buffers in a small fraction of second).

To sum it up, what happens is something like this:

• WebKit issues a request;
• some data from the reply begin to arrive;
• WebKit starts to lay out the web page using the incoming data, blocking the event loop;
• without a running event loop, data are received by the OS, but not read from QNetworkAccessManager sockets;
• kernel buffers will fill up, and the transfer will slow down.

The overall page loading time is therefore worsened by this self-induced transfer slowness.

Notice that since QNetworkAccessManagers and QNetworkReplys are QObjects, they’re not thread-safe, therefore you can’t just move them to another thread and continue using them from your thread, because they may be accessed at the same time by two threads: yours and the one they’re living in, due to events that will be dispatched to them by the latter thread’s event loop.

As of Qt 4.8, QNetworkAccessManager now handles HTTP requests in a separate thread by default, so the result of unresponsive GUI and OS buffers filling up too quickly should be cured.

When shouldn’t I use threads?

If you think you need threads then your processes are too fat.
— Rob Pike

Timers

This is perhaps the worst form of thread abuse. If we have to invoke a method repeatedly (for instance, every second), many people end up with something like this:

Then they figure out that this is blocking the event loop, therefore decide to bring in threads:

A much better and simpler way of achieving the same result is simply using timers, i.e. a QTimer [doc.qt.nokia.com] object with a 1s timeout, and make the doWork() method a slot:

All we need is a running event loop, then the doWork() method will be invoked each second.

Networking / state machines

A very common design pattern when dealing with network operations is the following one:

Needless to say, the various waitFor*() calls block the caller without returning to the event loop, freezing the UI and so on. Notice that the above snippet does not take into account any error handling, otherwise it would have been even more cumbersome. What is very wrong in this design is that we’re forgetting that networking is asynchronous by design, and if we build a synchronous processing around we’re shooting ourselves in the foot. To solve this problem, many people simple move this code into a different thread.

Another more abstract example:

Which has more or less the same pitfalls of the networking example.

Let’s take a step back and consider from an higher point of view what we’re building here: we want to create a state machine that reacts on inputs of some sort and acts consequently. For instance, with the networking example, we might want to build something like this:

• Idle → Connecting (when calling connectToHost());
• Connecting → Connected (when connected() is emitted);
• Connected → LoginDataSent (when we send the login data to the server);
• LoginDataSent → LoggedIn (the server replied with an ACK)
• LoginDataSent → LoginError (the server replied with a NACK)

and so forth.

Now, there are several ways to build a state machine (and Qt even offers a class for that: QStateMachine [doc.qt.nokia.com] ), the simplest one being an enum (i.e. an integer) used to remember the current state. We can rewrite the above snippets like this:

What the “source” object and its “ready()” signal are? Exactly what we want them to be: for instance, in the networking example, we might want to connect the socket’s QAbstractSocket::connected() and the QIODevice::readyRead() signals to our slot. Of course, we can also easily add more slots if that suits better in our case (like a slot to manage error situations, which are notified by the QAbstractSocket::error() signal). This is a true asynchronous, signal-driven design!

Jobs splittable in chunks

Suppose that we have a long computation which can’t be easily moved to another thread (or that it can’t be moved at all, because for instance it must run in the GUI thread). If we can split the computation in small chunks, we can return to the event loop, let it dispatch events, and make it invoke the method that processes the next chunk. This can be easily done if we remember how queued connections are implemented: an event is posted in the event loop of the thread the receiver object is living in; when the event is delivered, the corresponding slot is invoked.

We can use QMetaObject::invokeMethod() to achieve the same result by specifying Qt::QueuedConnection as the type of the invocation; this just requires the method to be invokable, therefore it must be either a slot or marked with the Q_INVOKABLE macro. If we also want to pass parameters to the method, they need to be registered within the Qt metatype system using qRegisterMetaType(). The following snippet shows this pattern:

Since there are no threads involved, it’s easy to pause/resume/cancel such a computation and collect the results back.

Some examples

MD5 hash

References

• Bradley T. Hughes: You’re doing it wrong… [labs.qt.nokia.com], Qt Labs blogs, 2010-06-17
• Bradley T. Hughes: Threading without the headache [labs.qt.nokia.com], Qt Labs blogs, 2006-12-04

Написано от: Girish Ramakrishnan, ForwardBias Technologies

API-та за таймери

Qt предоставя две API-та за работа с таймери.

• QObject::startTimer [doc.qt.nokia.com] – Създава повтарящ се таймер за употреба от всеки подклас на QObject и връща идентификатор на таймера. Когато таймера изтече, обекта получава QEvent::Timer, който може да се обработи като се предефинира функцията QObject::timerEvent(QTimerEvent *). Аргумента на QTimerEvent съдържа идентификатора на таймера, с цел да може да се проверява кой таймер е свършил, ако QObject използва няколко. QObject::killTimer(id) може да се използва за спиране на таймера.

• QTimer [doc.qt.nokia.com] – QTimer е QObject, който излъчва сигнала elapsed(), когато таймера изтече. Той просто използва QObject::startTimer() и при обработката на QObject::timerEvent(), излъчва сигнала elapsed().

QAbstractEventDispatcher

QtEventProcessing [developer.qt.nokia.com] предоставя обобщен преглед на това как Qt обработва събитията от операционната система.

QAbstractEventDispatcher [doc.qt.nokia.com] е интерфейсът за изпомпване на събития/съобщения. За всяка нишка, създадена от Qt, съществува по един диспечер на събитията. Той изисква функциите registerTimer [doc.qt.nokia.com] и unregisterTimer [doc.qt.nokia.com] да бъдат имплементирани, за да може да поддържа таймери.

Има два варианта на registerTimer (един виртуален и не виртуален). И двата приемат за аргумент QObject-а, който ще използва таймера. Не виртуалният registerTimer (cross-platform) заделя уникален идентификатор и извиква виртуалния registerTimer за реалното регистриране/създаване по специфичен за платформата(ОС) начин. С този подход, платформения диспечер на събитията поддържа списък с таймерите, асоциирани с даден QObject. QAbstractEventDispatcher::registeredTimers [doc.qt.nokia.com] може да се използва за взимане на лист с таймерите, свързани с QObject.

На ниско ниво, след като веднъж е създаден таймер, неговият интервал не може да се сменя и поради трябва да се счита за неизменяем. API-то от високо ниво трябва да създаде нов таймер, за да промени интервала. Също така, таймерите продължават да работят, докато не бъдат убити и няма концепция за единични таймери в интерфейса на диспечера на събитията. API-тата от високо ниво трябва да симулират единични таймери като спират регистрацията си за таймер след като мине първия интервал.

Алгоритъм за заделяне на идентификатори за таймери

Алгоритъма за заделяне на идентификатори за таймери е свободен и може да се разгледа в блога на Брад [labs.trolltech.com].

Важно е да се отбележи, че идентификаторите на таймерите трябва да са уникални, даже и при употреба в различни нишки. Това е така, защото когато QObject [developer.qt.nokia.com] бъде преместен от нишка в друга нишка, таймерите му се преместват също (т.е сигналите и събитията вече се доставят през цикъла на събитията в новата нишка). Преместването на таймер е просто – премахва се регистрацията му от диспечера в старата нишка и се регистрира в този на новата. Ако идентификаторите на таймерите не бяха уникални, можеха да се препокрият със вече съществуващи в новата нишка. Ако нови идентификатори се генерираха при QObject::moveToThread, то приложението трябваше да бъде уведомено за промяната, а това е неудобно за разработчиците на приложения.

Unix (без glib)

В Unix, QEventDispatcherUNIX имплементира диспечера на събитията. Той поддържа списък с таймери, сортирани по времето им на изтичане. Когато се регистрира таймер, неговото време на изтичане се пресмята като се добави периода към монотонния часовник (clock_gettime). На системи, които не поддържат такъв часовник, се използва gettimeofday.

Диспечера разчита на select(), за да чака за събития от всички файлови дескриптори (връзки от X, сокети). При влизане в processEvents(), диспечера първо обновява периода на изтичане на всички регистрирани таймери. После предоставя времето на изтичане на системното извикване select() като интервал в първият таймер в листа. След завръщането си от select, диспечера “активира” изтеклите таймери като изпраща на съответните QObject-и QEvent::Timer.

Забележете, че Qt не използва POSIX API-то за таймери – timerfd_create (Защо? Преносимост?).

Unix (с glib)

Qt може да се компилира така, че да използва цикъла на събитията на glib (по подразбиране), което помага за по-добрата интеграция с Gtk. Документация на цикъла в Glib [developer.symbian.org]” предоставя допълнителна информация за това как той е реализиран.

Точно като QEventDispatcherUNIX, QEventDispatcherGlib управлява таймерите като сортиран по време на изтичане лист. Той създава нов GSource за таймери. Функциите за подготовка, проверката и изпращане на този GSource работят по очевидния начин.

Windows

Както е отбелязано в QtEventProcessing [developer.qt.nokia.com], Qt създава скрит прозорец с указател към функция(callback), за да обработва събития. Когато се регистрира таймер, QEventDispatcherWin създава вграден Windows таймер, базирайки се на интервала.

• Ако интервалът е по-голям от 20 милисекунди, се използва SetTimer (с идентификатор, създаден чрез QAbstractEventDispatcher::registerTimer). SetTimer изпраща съобщение WM_TIMER към подадената функция, което се препраща като QEvent::Timer към QObject.

• Ако интервалът е по-малък от 20 милисекунди, Qt се опитва да използва мултимедийните (известни също като “бързи”) таймери чрез timeSetEvent. timeSetEvent приема указател към функция, която се извиква при изтичане и това става в отделна нишка. В Qt обаче, таймерите работят в същата нишка, в която е и QObject. За това функцията, подадена на timeSetEventlback, пуска съобщение към диспечера, което той прихваща и предава като QEvent::Timer.

• Ако интервалът е 0, диспечера създава специално съобщение към себе си (QEvent::ZeroTimerEvent) при регистрация на таймера. После той обработва това събитие като изпраща QEvent::Timer към съответния QObject и ZeroTimerEvent към себе си.

Реализация на API-то

QObject::startTimer регистрира нов таймер в диспечера на събитията. Това е приблизително еквивалентно на, QAbstractEventDispatcher::instance(object->thread())->registerTimer(интервал, обект).

QTimer е QObject. Всичко, което прави е да извика QObject::startTimer(). Той излъчва сигнала activated() в своя timerEvent().

QBasicTimer

QTimer изглежда тежък, тъй като е QObject и често се избягва в Qt код. В същото време, използването на QObject::startTimer() API-то предразполага към грешки.

1. Когато спирате таймер, трябва да направите идентификатора му невалиден (примерно да го приравните на -1) след QObject::killTimer(m_timerId). Това се изисква, тъй като положителна стойност на m_timerId ще индикира, че таймера е активен.

1. За да рестартирате таймер, трябва да запомните, че първо трябва да спрете предишния таймер, ако m_timerId е различно от -1.

QBasicTimer решава горният проблем и е просто подобрен интерфейс около “идентификатора на таймера”. QBasicTimer::start(int msec, QObject *) спира всички съществуващи таймери към този обект и създава нов, използвайки object->startTimer(msec). QBasicTimer::stop() спира таймера и слага идентификатора му на невалидна стойност. QBasicTimer::timerId() предоставя идентификатора.

Още материали

• Безкрайната борба [labs.trolltech.com] – Алгоритъм за заделяне на идентификатори за таймери

Written By : Girish Ramakrishnan, ForwardBias Technologies

The timer APIs

Qt provides two APIs to work with timer.

• QObject::startTimer [doc.qt.nokia.com] – Creates a recurring timer for use by any QObject subclass and returns the timer id. When the timer expires it receives a QEvent::Timer that can be handled by overriding QObject::timerEvent(QTimerEvent *). The QTimerEvent argument contains the timer id which can be matched against if the QObject uses multiple timers. QObject::killTimer(id) can be used to stop and disarm the timer.

• QTimer [doc.qt.nokia.com] – QTimer is a QObject which emits the elapsed() signal when the timer expires. It simply uses QObject::startTimer() and in the QObject::timerEvent() event handler, it emits the elapsed() signal.

QAbstractEventDispatcher

QtEventProcessing [developer.qt.nokia.com] provides an overview of how platform events are processed by Qt.

QAbstractEventDispatcher [doc.qt.nokia.com] is the interface for the event/message pump. An event dispatcher exists for each thread created using Qt. It requires registerTimer [doc.qt.nokia.com] and unregisterTimer [doc.qt.nokia.com] to be implemented for timers.

There are two versions of the registerTimer (one virtual and one non-virtual). Both versions take an argument to QObject that the timer is to be associated with. The non-virtual registerTimer (cross-platform) allocates a unique timer id and calls the virtual registerTimer for actually registering/creating the timer in a platform-specific way. With this approach, the platform event dispatcher maintains the list of timers associated with a QObject. QAbstractEventDispatcher::registeredTimers [doc.qt.nokia.com] can be used to query the list of timers associated with a QObject.

At the low level, once you register a timer, its interval cannot be changed and should be considered as immutable. A high-level API has to create a new timer to change the interval. Also, timers keep firing (i.e recurring) until killed and there is no concept of a “single shot” in the event dispatcher interface. High level APIs have to emulate a single shot timer by unregistering the timer after the first interval expires.

Timer id allocation algorithm

The algorithm for timer id allocation is lock-free and can be studied from Brad’s blog [labs.trolltech.com].

An important fact is that timer ids are required to be unique even across threads. This is because when a QObject moves from one thread to another, its timers also move along with it (i.e signals and events are now delivered through the new thread’s event loop). Moving the timer is simply a matter of unregistering the timer from the old thread’s dispatcher and registering in the new thread’s dispatcher. If the timer ids were not unique, the timer ids might clash with existing timers in the new thread. If fresh timer ids were to be regenerated on a QObject::moveToThread, then the application needs to be notified about the id changes and this is a hassle for the application programmer.

Unix (without glib)

On Unix, QEventDispatcherUNIX implements the event dispatcher. It maintains a list of timers sorted by their expiry time. When a timer is registered, it’s expiry time is computed by adding the timeout value to monotonic clock (clock_gettime). On systems that do not support monotonic clock, gettimeofday is used. The timer is then inserted into a list sorted based on its expiry interval (first item expires first).

The dispatcher relies on select() to wait for events on all fds (the X connection, sockets). It first updates the expiry interval for all the registered timers when processEvents() is entered. It then provides the timeout to the select() system call as the interval in the first item of the timer list. After returning from select, the dispatcher “activates” expired timers by sending the associated QObjects a QEvent::Timer.

Note that Qt does not use the POSIX timer API – timerfd_create (Why? Portability?).

Unix (with glib)

Qt can be compiled to use the glib event loop (the default) which helps it integrate better with Gtk. Glib loop documentation [developer.symbian.org]” provides an introduction to how glib loops are written.

Just like QEventDispatcherUNIX, QEventDispatcherGlib manages timers in a list sorted on expiry time. It creates a new GSource for timers. The prepare, check and dispatch functions of this custom GSource work on the timer list in the obvious way.

Windows

As noted in QtEventProcessing [developer.qt.nokia.com], Qt creates a hidden window with a callback function to process events. When a timer is registered, QEventDispatcherWin creates a native Windows timer based on the timer interval.

• If the interval is greater than 20 msecs, it uses SetTimer (with the id that was generated by QAbstractEventDispatcher::registerTimer). SetTimer sends a WM_TIMER message to the callback function that gets sent as QEvent::Timer to the QObject.

• If the interval is less than 20 msecs, Qt tries to use multimedia (aka fast) timers using timeSetEvent. timeSetEvent takes a callback function that is called on expiry and will be called from a separate thread. In Qt, timers fire in the same thread as that of the QObject. So the timeSetEvent’s callback function posts a message to the dispatcher which the dispatcher picks up and sends as QEvent::Timer.

• If the interval is 0, the dispatcher posts a special message to itself (QEvent::ZeroTimerEvent) on registration. The dispatcher processes this event by sending a QEvent::Timer to the corresponding QObject and posts a ZeroTimerEvent to itself.

API implementation

QObject::startTimer registers a new timer with event dispatcher. This is roughly the equivalent of, QAbstractEventDispatcher::instance(object->thread())->registerTimer(interval, object).

QTimer is a QObject. All it does is call QObject::startTimer(). It emits activated() signal in it’s timerEvent().

QBasicTimer

QTimer feels heavy since it’s a QObject and in general Qt code tries to avoid it. At the same time, using the QObject::startTimer() API is a bit error-prone.

1. When stopping a timer, you have to invalidate the timer id (say to -1) after QObject::killTimer(m_timerId). This is required since a positive value for m_timerId will indicate to your code that the timer is active.

1. To restart a timer, one needs to remember to kill the old timer if m_timerId is not -1.

QBasicTimer solves the above and is just a glorified interface to the integer “timer id”. QBasicTimer::start(int msec, QObject *) kills any existing timer and create a new one using object->startTimer(msec). QBasicTimer::stop() will kill the timer and invalidate the id. QBasicTimer::timerId() provides the timer id.

Further reading

• A never-ending struggle [labs.trolltech.com] – Timer id allocation algorithm

What’s needed to port Shiboken to Python 3

Note: The Python3 support related ideas were moved to PySide_Python_3_Support!

• Python 3 C API doesn’t have PyInt _ * functions, just PyLong _ [docs.python.org]. The code used to handle type conversions recognizes the use of PyInt and PyLong. The proper code for conversion is executed depending on the scenario.
  • Possible fix: Create PyInt _ * aliases to PyLong _ * functions.
  • Severity: Low
• Python 3 module initialization is completely different from Python 2, support both types of initialization would be trick¹.
  • Possible fix: Change the generator to generate different initialization routines for different Python versions or pollute the generated module initialization routine with #ifdef’s.
  • Severity: Medium
• PyTypeObject layout changed in Python 3 [python.org] . As many PyType objects are defined in libshiboken this implies in some ugly changes to libshiboken to get the source code supporting both Python versions.
  • Possible fix: Do an “#ifdef festival” on libshiboken and on code generated by the generator to handle the differences between Python versions.
  • Severity: High
• Python libraries will be ABI version tagged from 3.2 on [python.org]
  • Possible fix: Support it in CMakeLists.txt.
  • Severity: Medium
• Can’t access PyObject attributes from a PyTypeObject without cast it to PyObject beforehand.
  • Possible fix: Cast it!
  • Severity: Low
• Removal of PyString, addition of PyByte.
  • Possible fix: Create some aliases to the respective PyUnicode functions or add #ifdefs when the aliasing solution isn’t possible.
  • Severity: Medium
• CMake knows nothing about Python 3.
  • Possible fix: Write our own findPython3 function to detect Python 3 on the underlying system.
  • Severity: Medium

Summarizing, porting shiboken to Python 3 isn’t going to be a trivial task and support both versions will be even harder but not impossible.

Table of Content

• Chicken Wranglers - Showcase app
  • Game Development
    • The Mobile as a Remote control
    • Connectivity
    • UI and Animation
    • Making Smart Chickens
    • Porting and Optimizations
  • Conclusion
  • Controls
  • Binaries
  • Source

Chicken Wranglers – Showcase app

Listen to the INdT team in Brazil about how they used Qt to make a multiplayer and cross-device game using mobiles devices as the controllers.

The original premise of this project was the development of an application to showcase how Qt and QML can support interoperability between different platforms and devices.

The idea started to shape as a cross-device game, where several players could use their mobiles as remote controls and a big screen as a main game board.

After several proposals being considered, the designers presented a quite charming and funny game concept: farmers trying to capture chickens on their hencoops, using laser walls to trap them.

The challenge ahead: how to implement this concept with a small team (with zero previous experience in QML and no gaming development experience as well) in a really tight schedule?

If successful, this could be the perfect scenario to prove how was the QML learning curve and how productive it could be.

Game Development

It was clear that some components would be required for assembling a multiplayer networked game, so the team decided to start implementing modules that could be used independently of how the idea would evolve. The demands at this stage were interoperability and client devices acting as remote controllers.

The Mobile as a Remote control

The first module to be developed was the game controller. For input the team decided to use the accelerometer sensor for moving the characters. Qt Mobility features a sensors module that provides access to the device accelerometers.

Character movements were quite simple (up, down, right, left, stop), being just a matter of capturing accelerometer data and converting to discrete directions. The main challenge here was to fine tune those values such that it wouldn’t be hard for the user to guide his character through the battlefield.

It required some degree of experimentation to achieve good thresholds for handling common commands. Some parameters were used to aid the calculations:

• The minimum angle the device needs to be rotated to trigger a direction change.
• A threshold between two directions in the same axis (e.g. up and stopped) so the controller does not keep oscillating between them.
• Direction changing timeout, to check if the time spent in a given direction is not too short. This avoids undesired direction changes.

Connectivity

Before working on the connectivity itself, it was defined a communication protocol (messages and states to be exchanged between the devices), targeting to support both WLAN and bluetooth. Qt has great networking support, so it was relatively easy to implement connectivity via local network (therefore WLAN).

Qt Mobility 1.2 offers bluetooth classes for device management (discovering, pairing, etc) and message interchanging. It maps closely to the networking classes, enabling the initial WLAN code to be later translated to be used for bluetooth connections.

To support both WLAN and Bluetooth connectivity it a common abstraction was created for representing a network connection (QBluetoothSocket and QTcpSocket don’t share the same immediate parent class), thus signals diverge in type signature besides being quite similar. This allowed the application to switch the type of connectivity used at run time.

UI and Animation

One major concern was on the visual aspects of the game: how to make rich user interface screens, fancy transitions and animations to look beautiful and run smoothly.

That is where QML (Qt Modeling Language) came to the rescue. The team was formed by proficient programmers in C++/Qt/Linux but, as explained earlier, no previous experience with QML.

It turned out to be a pleasant surprise how easy and intuitive was to implement animations and effects while building the user interface in a declarative way. The possibilities of integration between C++ and the declarative language were seamless, enabling logic coded in native code to easily plug into Javascript based QML.

This way, we could keep the performance sensitive code paths in the native side (e.g. the chickens’ artificial intelligence, collision detection and connectivity, to name a few) and let only the visual implementation on the declarative side.

Making Smart Chickens

To make the chickens look like they are smart, it a module was created to add some intelligence to them. It basically changes the position of the chickens based on the proximity of the farmers or of hencoops. This logic enables the chickens to avoid wranglers and coops whenever possible and features a pseudo random criteria of avoidance, enriching the gaming experience.

The game elements (wranglers, hencoop, chickens, lasers) are logically represented on a matrix, in order to help the module to detect collisions and calculate the runaway logic.

Porting and Optimizations

The next step to fulfill the original vision of being truly cross-platform was a port to Symbian. The possibility of a port was only made possible starting with Qt Mobility 1.2 beta being made available (this is required to support bluetooth connectivity).

The first step was to change the buildsystem to couple with Symbian idiosyncrasies. While the initial buildsystem allowed to build different components as shared libraries (thus helping in debugging), to adapt to Symbian the application buildsystem was changed to build its submodules as a single project.

The app successfully launched in Symbian, but its memory footprint was above the maximum heapsize, as also the default stack size. These memory problems required some optimizations like using smaller image assets, installable character models (instead of using Qt resources for everything) and lazy loading of some screens.

Next, the screens got to be made more scalable (the game targeted the resolution of Nokia N900, which is bigger than Symbian devices like Nokia N8). The next step was to dynamically load assets depending on the environment and fine tune parameters animations (i.e. the feathers animation will use different number of feathers depending on the environment). This together with some reordering and refactoring of screen elements brought some benefits for CW in both environments, like faster app startup and better framerates. The end result was a reduction of memory usage from above 80MB to just 15MB of RAM.

Finally, much improved frame rates were achieved by simply using a QGLWidget thus unleashing OpenGL hardware acceleration for free. At end, we even got host mode to run successfully in the mobile (hosting up to 4 players at same time) with pretty good CPU usage (load around 65%) and framerates.

Conclusion

Qt technologies made possible to write from scratch a game for mobile devices in a short schedule with a small team, enabling quick implementation of designer’s mockups into real code.

It features support for everything needed to turn ideas into a running application: networking, bluetooth, accelerometer and graphics. The fact that it is possible to use C++ for more complex code paths, brings a huge advantage while coding games.

Add a declarative way for UI development in the mix and you achieve a winning combination for rapid application development.
How to Play

Chicken Wranglers is a 2-4 players game, where each player is a farmer whose goal is to capture as much chickens as he can while a timer is running. The chickens walk freely across a bi-dimensional grid, always trying to escape from the farmers and their chicken coops.

In order to push chickens to his coop, the farmer can activate lasers in the grid to build mazes that should restrain the chickens’ path and guide them to the coop. The lasers can be placed at any edge of a cell (up, down, left or right) where the farmer is currently located. Although active lasers are supposed to help a farmer, the other farmers can deactivate any laser at any time. This enables a farmer to have his maze broken by his opponents.

Note that neither chickens nor farmers are allowed to cross a laser wall before it is deactivated.
Score

Each time a chicken cross a farmer’s coop, the corresponding player scores 1 point. After the timer expires, the player with the highest score wins.

Ashley Walker holds the Chicken Wrangler title with wrangling all 40 chickens into the hen house before the clock ran out. She was undefeated at the MeeGo Conference this spring. Do you have what it takes to steal the CW title?

Controls

Movement – A player controls his character direction via device accelerometer. The characters moves in four directions: up, down, left and right according to device tilting on any of those directions. If the device is tilted diagonally (e.g. up and left), the predominant direction will be the most tilted one.

Lasers – Tapping on screen toggles a laser on the corresponding direction of the player character’s position. For instance, if the player taps on the top of the screen, the laser is activated/deactivated above the character’s position.

Binaries

Harmattan (N9 / N950): http://get.qt.nokia.com/demos/chicken-wranglers/chicken-wranglers_0.1-0_harmattan_armel.deb

Fremantle (N900): http://get.qt.nokia.com/demos/chicken-wranglers/chicken-wranglers_0.1-0_fremantle_armel.deb

Ubuntu 11.04: http://get.qt.nokia.com/demos/chicken-wranglers/chicken-wranglers_0.1-0_i386.deb

Source

http://qt.gitorious.org/qt-labs/mobile-demos/trees/master/chicken-wranglers

KD Soap is a web service access package for Qt applications.

KD SOAP is a tool for creating client applications for web services and also provides the means to create web services without the need for any further component such as a dedicated web server. It makes it possible to interact with applications which have APIs that can be exported as SOAP objects. The web service then provides a machine-accessible interface to its functionality via HTTP.

Code generators for the client and the server side make it really easy to write SOAP clients and servers in Qt.

Table of Content

• Overview
  • Preparation
  • Modify your project

Overview

gSOAP is a portable development toolkit for C and C++ XML Web services and XML data bindings. Supports XML auto-serialization of C/C++ data. Includes WSDL/XSD schema binding tools, stub/skeleton compiler, Web server, SOAP/XML/MIME streaming, XML-RPC. Here is how to use it to build a web service client in Qt.

Preparation

• Download and unzip gSOAP package [sourceforge.net].

gSOAP package contains pre-built tools in the gsoap/bin directory.

• wsdl2h schema importer
• soap2cpp stub/skeleton generator.

You require .wsdl and .xsd files of web service to generate c++ stub.

Modify your project

• First use wsdl2h on .wsdl file it will generate .h file, then use soapcpp2 on generated .h file, this will generate .h and .cpp files to be included in Qt project.

• Before using wsdl2h you have to modify “typemap.dat” file, this file is present in ‘gsoap/ws’ directory. Add a line in this file defining namespace of your webservice. Give any name to namespace and copy string from your .wsdl file following the tag.

Add this line to “typemap.dat” file:

• Now run wsdl2h on .wsdl and .xsd files (from command prompt)

(note .xsd file should be in same directory as .wsdl file)

• Then use soapcpp2 on generated .h file (we assume that name of generated file is chatapp.h)

this will generate multiple files

and an xml file for each method in defined in .wsdl file.

• now add

as headers in to your qt project and then add

as source

• add include path of yor generated file in .pro file of your qt project or simply copy all of generated files to your project directory. Also add path of “libws2_32.a” in your .pro file I my case it is as under

• also add stdsoap2.h and stdsoap2.cpp from gsoap directory as header and source in your project.

• now include chatapp.nsmap and chatappProxy.h in your main.cpp.

• make an object of chatappProxy and use it to communicate with webservice.

above method worked for me while using gsoap with NokiaQtSDk on windows xp.

Building Qt Documentation

For information about writing documentation for Qt, see the Writing Qt Documentation page.

For help on troubleshooting documentation builds, see the Troubleshooting_Qt_DocumentationTroubleshooting Qt Documentation page.

For information about building documentation in the modularized Qt repositories, see the Building Qt 5 Documentation page.

Building Qt4 Documentation

Build Qt as normal.

Define environment variables for QT_SOURCE_TREE and for QT_BUILD_TREE appropriately. Make sure the PATH environment variable points to the bin directory containing the qdoc3 executable.

For the online docs it may be necessary to use

for later versions of Qt.

For Windows™ use the nmake utility instead of make. Some Linux systems will require gmake instead of make.

If you already have Qt compiled (from the SDK, for example) and want to build some special flavour of the doc, you can call directly qdoc3 (QT_SOURCE_TREE, QT_BUILD_TREE, and QTDIR must be set appropriately), here for DITA output:

Building Qt5 Documentation

Building qdoc3

qdoc3 is built during a normal build of Qt because it is needed to generate the Qt documentation. This means that, for many developers, qdoc3 is installed alongside the other Qt tools.

Copy over the qdoc3 executable from qt5/qtbase/bin to qt5/qtdoc/tools/qdoc3/ because that is where the Makefile expects it to be.

Running qdoc3

There are two ways to build Qt documentation.

Using The Qt Build System

At the command line, enter the root directory of the build tree and invoke the docs build rule.

You will first need to go to the qtdoc directory located under qt5.

For example, on Linux/Unix platforms to make Creator style documentation:

or for the online style:

On Windows, you may be using the native nmake tool:

Running qdoc3 Directly

Under construction.

Adding Modules to the Documentation

Here we will add a module, in this case QtLocation, to the Qt5 documentation. We will use the default name of the repository ‘qt5’ in the example.

There should already be an entry in qt5/qtdoc/doc/doc.pri in the MODULES list for your module, if not it is easily added.

In the directory qt5/qtdoc/doc/config there is a directory ‘modules’. There should be a qdocconf file for each module.

The location one is qtlocation.qdocconf. This is just a list of specifications on the locations of header, source, example and image directories. It is a simple task to copy, paste and edit one to your own needs.

The environment variable that is used to identify the location of the module source, eg QT_LOCATION_SOURCES is constructed in the qtdoc tree from the location specified in the module’s source tree. These environment variables are then hardcoded into the qdocconf files in qt5/qtdoc/doc/config/modules, which explains the contents of qtlocation.qdocconf.

For QtLocation, the above is simply background since location is in the list of modules and a qtlocation.qdocconf file has been written.

To add documentation source to location we have to add the files location.qdoc and qlandmarks.qdoc to qt5/qtlocation/doc/src. Also we need to create and populate the ‘examples’, ‘plugins’ and ‘snippets’ directories which will contain the location specific examples, plugin docs and snippet files.

Also copy across the related examples to the ‘examples’ qt5/qtlocation/examples directory. These will be the examples that contain snippets used in the documentation.

Next we add our Location classes to the Modules page (this does not link the overview however, only a link to the classes in the module).

In qt5/qtdoc/doc/src/modules.qdoc add the following to the table

To link the module overview we have to simply add

to the location.qdoc and qlandmarks.qdoc, this will mean that the module link will appear in the Technology APIs page accessible via the sidebar or the front page (the latter has an incorrect link which I will fix).

Points of caution.

qdoc3 does not understand two pages with the same title and html output page correctly. When adding documentation one should therefore be careful to not call the index page for the add-on module index.html when it should be part of the complete Qt documentation, since this might overwrite the index page for the whole of the documentation (qdoc3 overwrites entriers already in its internal list of pages, therefore the last page found will be the displayed one)

PySide/QtQuick Tutorials

In this wiki page, we have sorted out some tutorials structured by rough experience levels. So we have tutorials for absolute beginners, for intermediate PySide developers and for the more advanced ones who are just searching for simple solutions for their complex problems.

Beginner tutorials

• An Hello World with PySide and Qt Quick
• PySide_and_QML_Playground

Intermediate tutorials

• SuperHybrids part 2, now Qt + PySide [lynxline.com]
  • I am not sure is this belongs in QtQuick section as it has nothing to do with QML.
  • Wayback Machine Formatted Mirror [web.archive.org]
  • Google Text-Only Mirror [webcache.googleusercontent.com]

Advanced tutorials

• Selectable list of Python objects in QML
• Multi selection lists in Python with QML
• Defining and using constants from PySide in QML
• Using QtWebKit and QML with PySide
• Updating QML content from Python threads
• Utilizing Qt Quick Colibri in PySide
• Filling and reading QML UI forms from Python
• Auto generating QObject from template in PySide
• Using QtMobility sensors and QML from PySide

Написано от : Girish Ramakrishnan, ForwardBias Technologies

Общ преглед

Qt Resources предоставя платформено независим механизъм за вкарване на произволни бинарни данни, включително изображения и звуци, като част от изпълнимият файл на приложението. Вижте документацията на ресурсите [doc.qt.nokia.com] за по-подробна информация.

По отношение на имплементацията, ресурсите в Qt нямат нищо общо с RES файловете [msdn.microsoft.com] на Windows или resource forks [en.wikipedia.org] on Mac OS X.

Как работи

Ресурсните файлове (i.e .qrc files) са XML-и, които описват кои файлове трябва да се пакетират в крайният бинарен файл. Ресурсният компилатор rcc обхожда XML-а и генерира C/C++ код. Този генериран код съдържа C структура, която съдържа суровите данни на файловете, който се намират в .qrc. След това тези C-структури се събират в друга C-структура, за да формират дървовидна структура, така че файловете да могат да се наредят в йерархии. Детайлите за тази структура сами по себе си не са много интересни, за това и не са описани тук. С опцията -_compressed_ на rcc, данните в структурите се компресират със zlib (по подразбиране, компресирането е изключено).

C-структурите трябва да се регистрират в Qt, за да може то да знае за тях. Номера е, че в края на всеки генериран от rcc C++ файл, rcc слага извикване на qRegisterResourceData(), което регистрира C структурата в системата за ресурси на Qt. Чрез използването на подхода за конструктурна функция, qRegisterResourceData() се извиква преди main(). Подхода за конструктурната функция е използването на глобална статична променлива, която се инициализира като се извиква функция.

В края на генерирания от rcc C++ файл, съдържа нещо подобно на:

Тъй като статичните променливи се инициализират преди извикаването на main(), всички ресурси автоматично се регистрират преди същинската програма да стартира.

Q_INIT_RESOURCE

Трикът с конструкторната функция работи само ако генерирания C++ файл е компилиран и вързан за приложението директно. Ако ресурсите се използват в статична библиотека и тя е свързана с приложението, конструкторната функция никога няма да се извика. Това е в природата на C/C++ свръзването – функциите и променливите в библиотеките, които не се използват/извикват от крайната програма се премахват от крайният бинарен код ( оптимизират се). Ако ресурсите са в споделена библиотека, тогава конструкторната функция се извиква. Обаче, повечето платформи зареждат споделените библиотеки при нужда и конструктурната функция се извиква само когато библиотеката се зарежда. Последствието от това е, че всички ресурси в плъгини, които се използват в главната програма, няма да бъдат намерени от Qt, докато плъгина не бъде зареден – това не е проблем, ако ресурсиоте от споделената библиотека се изпозлват само в нея. Обърнете внимание на това, че достъпването на ресурси от споделената библиотека в главното приложение не предизвиква зареждането и, тъй като никакви символи не се експортират от QRC системата.

Решението на този проблем е да се използва генерирана променлива( от AFUNC ## init_variable по-горе) или да се извика генерираната функция qInitResource_images(). Макросът Q_INIT_RESOURCE съществува с тази цел и се изисква, когато имате ресурси в статична или споделена библиотека.

Макроса по-горе обикновено се слага в началото на main() за всеки qrc файл.

Достъпване на ресурси

QFile, QDir, QPixmap и т.н. могат да достъпват qrc файлове. Целият достъп до файлове в Qt минава през QAbstractFileEngine [doc.trolltech.com]. QResource регистрира подклас на QAbstractFileSystemEngine при стартиране, който предоставя валидна система за достъп до файлове (през QAbstractFileEngine::create), когато името на файла започва с “:”.

Именни пространства за ресурси

Когато използвате ресурси в плъгини, ресурсните пътища трябва да бъдат именовани. Използването на името на плъгина за именоване на ресурсното пространство е добра техника. За пример, e. Ако съществуващ път до ресурси е регистриран втори път с различни данни, той се игнорира и се запазва първия.

Written By : Girish Ramakrishnan, ForwardBias Technologies

This page explains the purpose of various QString related classes.

QLatin1String : Avoid hidden mallocs in operator “==”

Creating a QString from a C-string may involve a malloc. For example, there is possibly a hidden-malloc cost in the following code.

QString provides a QString::operator==(const char *) overload for comparison with C-strings. As explained in QtString [developer.qt.nokia.com], the encoding of C-strings is determined using QTextCodec::setCodecForCStrings(). When no special encoding is set, Qt performs the above comparison by providing a specialized function that compares a Unicode string (fruit) and the Latin-1 string (‘apple’). This comparison is fast and requires no mallocs.

However, when QTextCodec::setCodecForCString is set, “apple” gets converted into a QString using QString::fromAscii(). This means that QString will allocate memory for the string “apple” and creates a deep copy of the C-style string before performing the comparison!

Application developers set QTextCodec::setCodecForCString() in main() without realizing that this has the side-effect of a malloc for every single C-style string comparison.

Since comparisons with Latin-1 C-strings are very common in programs, Qt provides a special class called QLatin1String that just holds a pointer to a Latin-1 encoded C-string. In addition, QString provides a QString::operator==(const QLatin1String &) overload that calls the specialized function that compares the Unicode string and Latin1-string. We can make the above code assuredly fast by writing it instead as,

In Qt’s own code, all C-strings comparisons use QLatin1String since the application can choose an arbitrary codec for C-strings.

QStringRef : String manipulation without the malloc

QString has various methods for string manipulations like mid(), left(), right(). All of them create a new QString and hence a malloc/deep copy of data in an existing QString. Instead, QString::midRef(), QString::leftRef() and QString::rightRef() can be used to obtain a QStringRef. A QStringRef is a reference of a portion of a QString. QString also provides many overloads like QString::operator==(const QStringRef &) for optimal use with QStringRef.

QString::reserve and QString::squeeze

It’s better to call QString::reserve to allocate extra memory in advance so that every call to QString::append() does not result in a malloc. Extra memory can be reclaimed using QString::squeeze.

QStringBuilder : Fast QString concatenation

The code below requires atleast 2 mallocs. First a malloc to store the result of “(” + type. And then another malloc for appending the “)”. The number of mallocs increases with each addition of “+” operator.

The additional mallocs can be avoided if the length of the final QString is known in advance. Qt 4.6 introduces an internal class called QStringBuilder that “reserves” memory for a concatenation chain in a single shot. It does so by having each of the + operations above return a different class (not QString anymore). This class keeps track of the string’s that are being appended and the required memory at each step. At the final step, when the concatenation operation gets converted into a QString it allocates memory in a single shot and copies all the strings in the chain one after another. This feature can be enabled by including <QtCore/QStringBuilder>. and using use the operator ‘%’ instead of ‘+’. One would now write,

‘+’ can be used instead of ‘%’ by defining QT_USE_QSTRINGBUILDER. See Fast concatenation [developer.qt.nokia.com] for more details

QStringMatcher : Fast string matching

QStringMatcher can be used to look for a string repetitively in many strings or in the same string many times. It uses “Boyer-Moore string search algorithm”:http://en.wikipedia.org/wiki/Boyer–Moore_string_search_algorithm to perform fast searches.

QML Application Structuring Approaches

Introduction

A common approach to deal with a complex application is to decompose it in several smaller units. This leads to better structuring of application and more productive development process as a whole. QML offers two constructs that service this approach – Component and Loader elements. Roughly speaking, the both elements bring similar functionality. But the ways they do this are different. We may refer to the Component approach as static one and the Loader approach as dynamic one. We first re-call Component and Loader definitions, than compare the two approaches and in the main part of this article describe several Loader element use cases. There are two other approaches to structure a QML application also – dynamic creation of objects and module importing. They are beyond the scope of this article.

Component Element Definition

A QML component is a separate, autonomous unit that contains other QML elements. It could be defined in two modes – as an inline unit in a QML file or as a separate QML file. The main point with QML component is that it could be reused many times trough its very convenient interface. For more details about Component syntax and interface consult the documentation. [doc.qt.nokia.com]

How does the Component element support application code structuring and particularly its decomposition? In case of component file it is obvious – the application is split in several components. They are included in the main file and instantiated via their interfaces, for example like this:

QML File

Including of the component means that we get an instance of the component viewed as a template. The basic component is used to generate instances only and they do not depend anymore on it. We may have several instances and they behavior independently, treated like basic QML elements. Note that Component interface allows to re-define component properties – predefined ones as well as defining new ones. This is the case of the color property in the snippet above. We could even just instantiate the component and not alter any property.

We may have many instances of Banner component provided that they have different id.

By now we are considering properties defined at the top level of the component file. What about siblings’/children’ properties in a component file? Let us consider the following case:

ExampleOne.qml – Component file

componentScope.qml – It is using component ExampleOne

As you see if we want to re-define the property color of nameText child we have to make it visible at the top level. To get this we define an alias of the nameText at the top level. This alias is re-defined in componentScope.qml file.

Could we develop more complex structures with components? For instance, could we have nested components? By nested components we mean that a component contains another component. Structures like these are acceptable:

nestedComponents.qml – Main file

Comp1.qml – First level component file

Comp2.qml – Second level component file

The inline definition syntax of the component element is very similar to this one of other QML elements. It starts with a key word Component followed by element block (represented by { } pair). Within the block you may define and nest other QML elements – refer to Nokia documentation [doc.qt.nokia.com].

On the other hand, inline Component offers other kind of structuring. It encapsulates a piece of QML code that could be assigned as a property value of other QML elements. Particularly this mechanism is used in the definition of the Loader element – see the next section. This kind of structuring is sometimes referred as aggregation. An example how inline Component could be utilized is demonstrated in section Loader and Inline Component.

Loader Element Definition

Loader element serves as a handler, which loads dynamically a QML unit formed as a separate QML file or inline component. Dynamically means that the QML unit to be loaded is determined at run-time, for example if a mouse button is clicked. The loaded unit is described as value of source or sourceComponent property of the Loader. The source value is a URL value – the path to QML file to be loaded. The sourceComponent value is id name of an inline component. Where can we bind values to these properties? The rule is: at places where the Loader id name is visible. In the following sections you see many examples of implementation of this rule. For more information on Loader see documentation [doc.qt.nokia.com].

One interesting point is how the loaded QML unit could be accessed. The Loader element has a default property item. It is read-only and has Item type. In other words, loaded QML unit is a QML Item element. We recall that it is not visible and serves to group other QML elements. An illustrating snippet on item property follows:

LoaderItem.qml

Page.qml

We could set up source or sourceComponent properties in the Loader definition. Now the Loader element is processed like any other QML element and its target will be rendered. In this case the behavior is similar to the one of component element. But note that we may change programmatically properties values of source or sourceComponent at a later time.

Component Element vs. Loader Element

Now we are going to compare component file and Loader element. They both offer similar functionality, but differ in ways they are applied.

In case of a component file we have the following process. We declare the component (rather its interface) in a fixed way in the main file for example. QML parser immediately checks if a component file with the name as in component declaration exists. The parser searches in the directory where is placed the file.

The Loader acts a bit differently. When a QML file containing a Loader element is parsed, the Loader constructs itself like any other QML element. The Loader could define the source destination of the file to be loaded or not. In the first case the file is loaded. In the second case this is postponed to the moment we define the source destination of the file in a script element for example. Note that in case of source property we may point to a file located anywhere on our local computer or on the Internet. If we have many QML entities that are not needed permanently, there is no need to keep them in memory – rather load them as they are necessary. This leads to a better structuring of the application and more efficient computer memory management. Be aware that any consequent activation of a Loader destroys the previously loaded items. If we set an empty string as source property value or undefined value to sourceComponent property, the memory used by the Loader is released.

Because the file to be loaded by a Loader could be determined in run-time, the Loader approach is referred to as dynamic one. The component approach is called static one.

Combining loaders, components and other QML elements it is important to understand the hierarchy of elements and how they overlap each other. Let us create a demo example, which will illustrate QML elements rendering hierarchy. We are considering a QML main file that has two Loaders, one component and other standard QML elements. We re-define the z property of elements to control their overlapping.

elementHierarchy.qml – main file

firstLoader.qml – file loaded by newLoad Loader

secondComp.qml – loaded by loadSecond Loader

CompNew.qml – component file

The next picture illustrates how QML elements are displayed and overlapping. As a rule elements are rendered in the order they are defined in the main file. In the snippets above z property is changed for text element textInner (z=3) and for rectangle element second (z=2) and they are rendered at the top element hierarchy.

You may experiment changing z property.

Loader Element Use Cases

Simple Wizard Template

Our application consists of several pages (3 in the snippet bellow), each of them formatted as a separate QML file. These files could be located in different directories, but for simplicity we suppose they reside in the directory where is located our main file. Each page has its own Loader element and when a Click me button is pressed the Loader loads a next wizard page.

wizardSimple.qml – main file

Page1.qml – first wizard page

Page2.qml – second wizard page

Page3.qml – last wizard page

The above wizard implementation is very simple, but suffers of some drawbacks:
• When a new page is loaded the previously loaded page stays unnecessary into memory.
• We use similar loaders for each page – their IDs are different only.
• The order of pages loading is fixed one – the source property values are set in advance.
• There is no mechanism for exchange of information between the caller and the called page and vise-verse.

More Complex Navigation

Now we will try to release the restrictions of the loading scheme from the previous section. Firstly, following the Simon Judge idea [mobilephonedevelopment.com], we will apply a common Loader for all pages. Secondly, we suppose that the next page to be loaded is not known in advance – it is determined after a condition is evaluated. And finally, we will use signals to pass information between pages and demonstrate how multi-window screens could be constructed.

A common approach to trigger some actions after an event is fired is to define an own signal like that (for more information here [doc.qt.nokia.com]):

where signal is QML keyword, MySignal is the name of newly defined signal, message is a parameter of type string and trigger is another parameter. The parameters could be of different QML types. For our purposes we want to pass a string that is the name of wizard page to be loaded and an index to identify the application state.

The main idea is as follows:

• When we want to load a page we emit our own signal.
• This signal is caught by a Loader defined somewhere.
• Our signal has a parameter to which we bound the name of the page to be loaded – as an URL value.

Use Case: We will consider an application that consists of a main page (Page1) and two other pages (Page2, Page3). The pages should be loaded sequentially and construct a wizard this way. Some of pages could be loaded checking for a logical condition creating the wizard branches.

Objectives: To demonstrate how a flexible wizard could be implemented based on QML Loader element. Additionally we may complicate the wizard constructing some multi-windows screens.

Design: Pages are loaded one by one. The application starts loading automatically Page1. To load the next page we should click the left mouse button. For Page1 we have two wizard branches depending on a logical value. We introduce a current index for pages (an integer) around which the application logic is build.

Development: For each page we define the same own signal:

To activate this signal (emit the signal) we have to invoke it as a method in a script block. A MouseArea onClicked script block is used. In invocation the name of the page to be loaded is passed as parameter. Emitted signal is attached (automatically) to the signal handler onHandlerLoader, which in turn is connected to a target pageLoader.item. The connection is carried out by a QML Connections element in the QML file flexibleLoader.qml. The target pageLoader.item is in fact the object loaded by the Loader (id:pageLoader) defined in the file flexibleLoader.qml. Note that the target property of the Connections element is of type Object. When Page2 is loaded we want a second window (NewWindow.qml) to be loaded into the same screen. This is done by a second Loader (id:window), which is defined in the file flexibleLoader.qml. The decision to load this second window is taken in onHandlerLoader block on the base of returned value of trigger parameter. Note that the Loader destroys previously loaded entities when loading new items.

Code:

flexibleLoader.qml – application main file

Page1.qml – page 1

Files Page2.qml and Page3.qml are similar to Page1.qml.

Download Package: Necessary files: flexibleLoader.qml, Page1.qml, Page2.qml, Page3.qml, Help.qml, NewWindow.qml. Get them from here [sugarsync.com].

Loader and Component Together

Use Case: Assume the page we are loading uses an external component (component file) and from this component we want to load a next page. What is new in this use case comparing with the previous one? The call to the
Loader is not located at the top level now. It is nested in a component. When the Loader is defined in the main application the pages are loaded in its context. This requires the Loader source property to be determined at the top level also. To solve this problem we use cascading definitions of properties. Firstly, have a look at a diagram illustrating the use case:

Design: It follows the diagram above. The main file componentLoader.qml loads Page1.qml, which in turn loads Page2.qml. The Page2.qml file instantiates a component – Inserted.qml. From within Inserted.qml the Loader in componentLoader.qml is invoked.

Development: The issue here is that the signal handlerLoader has to be activated at the top level of the file Page2.qml. When instantiating component Inserted we define an alias to the top level id: property alias next1:pop. The signal is invoked in Inserted.qml through a qualified name – next1.handlerLoader(“Page3.qml”,0).

Code: Main file componentLoader.qml and files Page1.qml and Page3.qml are similar to these ones of the previous section.

Page2.qml – this file instantiates component file Insert.qml

Inserted.qml – this is component file

Download Package: Necessary files: componentLoader.qml, Page1.qml, Page2.qml, Page3.qml, Inserted.qml. Get them from here [sugarsync.com].

Loader and Inline Component

Use case: We want to implement an advertising banner composed from images and texts. We have several images combined with explanatory texts and these pairs are displayed cyclically. Additionally a button is needed to be bound to each displayed pair – for example to get more information on advertised topic. Have a look at some screenshots.

Objectives: To demonstrate how a loader and an inline component could be used together. Moreover nested components and QML Timer element are highlighted.

Design: Bellow you have a diagram illustrating what and how QML elements are employed.

Development: The cycling is implemented through a QML Timer element. Each time the Timer generates an onTriggered signal, the sourceComponent property of the Loader (id:test) is changed to load the next pair image-text. Images are arranged in a JavaScript array – defined in JavaScript function act(). The texts are placed in the JavaScript array externalArray – defined in a separate file arrayExt.js – just to show how this approach works. The pairs image-text are modeled with a inline component – id:varText – which is loaded sequentially by the loader. The necessary button is implemented as an external component – file Button.qml – and which is nested in the component varText. The handler, connected to this button, is illustrated with console.log() function output.

Code: Each cycle forms a state. The states are indentified via the property loop, which gets int values and is used as arrays current index.

bannerComponent.qml

Button.qml

arrayExt.js

Download Package: Necessary files: bannerComponent.qml, Button.qml, arrayExt.js, fall1.jpg, fall2.jpg, fall3.jpg, fall4.jpg. Get them from here [sugarsync.com].

Note: The download package is organized in subdirectories corresponding to respective sections:
• Component Element Definition – Component
• Loader Element Definition – Loader
• Component Element vs. Loader Element – ComponentvsLoader
• Simple Wizard Template – SimpleWizard
• More Complex Navigation – ComplexNavigation
• Loader and Component Together – LoaderandComponent
• Loader and Inline Component – LoaderInline

Download Package [sugarsync.com].

Squish

Squish is a tool developed by Froglogic [froglogic.com] used for automatic testing of Qt applications.

Guidelines

• The recommended way of working with Squish
• Working with long test cases
• Load testing

Tips and Tricks

• Verifying the value of a QLabel
• Verifying the existence of a menu item
• Finding list items that ends in a given string
• Robust selection of items in a tree or list view with variable text
• Iterating through a table
• Custom settings for test runs
• Waiting for input from the test operator
• Hooking into slow launching subprocesses on Windows
• Waiting for a progress bar or progress dialog
• Navigating a QDateEdit
• Using Squish and custom properties
• Generating test data
• Calculating checksums
• Clicking link in label

Training

Need help or training [kdab.com] with Squish: feel free to contact KDAB.

Similar tools

• Testability Driver [projects.forum.nokia.com] – A generic driver which provides access to Qt software for test automation harnesses.

Clicking link in label

As is commonly known, you can put in hyper text links in a regular QLabel in Qt, by using simple HTML syntax. Then of course, you want to be able to click this link in your Squish tests. However, Squish does not have a clickLink() function, as it does for e.g. clickButton() or clickTab(), so what happens during recording is that you will get code similar to:

That is, hard coded coordinates for where the link is. So if the position of the link would change for whatever reason (different platform, new text added, different font) the test will break.

In Squish 4.1, a new function named installSignalHandler() was added. This lets your test script react to signals emitted from the application code. We can use this function combined with the fact that a signal is emitted from a QLabel whenever a link is hovered. This will let us implement a function for clicking arbitrary links in a label.

Usage is simply:

What the code does is to install a signal handler for the linkHovered(QString) signal as mentioned above, then moving the mouse cursor over the QLabel until the signal is emitted and the link hovered is the one we are looking for. If the link is not found, nothing is clicked.

QDoc

Introduction

qdoc3 is the currently available configurable documentation generation tool. qdoc3 is used to generate the Qt Reference Documentation. The QDoc manual [doc.qt.nokia.com] is regularly updated.

Current features

• Supports C++ and QML input.
• Supports HTML and DITA XML output.
• Possibility to link multiple documentation packages together using index files.

Future changes

It is hard to maintain and implement new features in qdoc3. qdoc3 is currently also not able to generate properly modularized Qt reference documentation. Therefore some work is required to future-proof QDoc. This will probably require a rewrite of significant parts of QDoc.

Proposed changes are:

• Rename qdoc3 to just qdoc.
• Make it possible to run QDoc on a single file.
• Convert QDoc to an architecture which uses plugins. This would make it possible to ship plugins with their respective modules (ship qdoc-base in qtbase and the QML parsing plugin in QtDeclarative). It would then also be possible to easily implement plugins for different input/output formats and different.
• Use a proper C++ parser. Currently qdoc3 tries to use some tricks to generate documentation. qdoc3 for instance does not expand macros, which means that a macro has to be added to an ignore list to skip parsing the macro. A solution could be to use the Abstract Syntax Tree-parser which is used by Qt Creator. That parser properly expands macros and would make using ignore lists obsolete.
• Make it possible to run QDoc on individual modules, merging the content afterwards if requested.
• Merge the Generator and PageGenerator classes, these classes were used separately for QtJambi, but now All generators are a subclass of PageGeneratr, which is a subclass of Generator.

Requested Features

See also development@qt-project.org, RFC: The Future of QDoc

• Make it possible to have documentation in headers
• Enums should be documented in the header inline (doxygen style)
• Have Qt Creator be able to build the docs as target

Written By : Girish Ramakrishnan, ForwardBias Technologies

Basics

A locale is a set of parameters that define language and other preferences a user may choose for their interface. Basics of Locales [developer.qt.nokia.com] explains the basics. In Qt, locales are implemented using QLocale and QSystemLocale.

QSystemLocale

QSystemLocale is an interface to query the user’s locale information. QSystemLocale::query() [doc.qt.nokia.com] can be used to query the locale data including the name of a month, the negative sign for numbers etc.

QSystemLocale provides locale information from the Operating System. On Windows, QSystemLocale::query() uses GetLocaleInfo [msdn.microsoft.com]).aspx. On the Mac OS X, QSystemLocale::query() uses CFLocaleGetValue. On Linux, query() returns only the measurement system by inspecting the LC_MEASUREMENT, LC_ALL and LANG environment variables (in that order).

QSystemLocale::query() can be overridden by an application to provide further customizations to the user’s locale.

The default locale

Qt programs can be run in any locale by setting the ‘default’ locale using QLocale::setDefault(). When the default locale is not set, Qt uses the information from QSystemLocale i.e the locale information from the Operating System.

QLocale

QLocale is the “front-end” class that helps in formatting data based on a locale id. QLocale uses the <language>_<country>.<codeset> format for the locale identifier. A QLocale that is created using no arguments (QLocale()) is equivalent to the default locale. When the default locale is not set, QLocale() is equivalent to the system locale.

There are two code paths that QLocale uses to determine the formatting information. The first case is when the default locale (QLocale::setDefault) has not been set and a QLocale object with no constructor arguments is used. In such a case, QLocale() queries all formatting information through QSystemLocale::query(). This results in QLocale formatting data as it has been configured in the Operating System. In the second case, a default locale has been set or a QLocale object is created with a language and country (locale id). In this case, Qt refers to qlocale_data_p.h [qt.gitorious.org] to determine how to format data. qlocale_data_p.h is generated from CLDR [cldr.unicode.org] using the cldr2qlocalexml.py and qlocalexml2cpp.py scripts at local_database [qt.gitorious.org].

To reiterate:

• When using the system locale, formatting information is queried from the OS and not CLDR data.
• When a default locale is set or a QLocale object is created with a locale id, formatting information is obtained from CLDR data.

Fallback locale

The Fallback locale (QSystemLocale::fallbackLocale [doc.qt.nokia.com]) is a QLocale created with the locale id detected using environment variables (LC_ALL and LANG). If the environment variables are not set, GetUserDefaultLCID is used on Windows and CFLocaleGetIdentifier is used on Mac OS X.

Widgets and locales

Every widget can be set a locale individually using QWidget::setLocale(). Locales propagate from parent to children. When not set, it is the same as the default locale. Locale settings propagate to children. Qt sends a QEvent::LocaleChange event to a widget when it’s locale changes.

Написано от : Girish Ramakrishnan, ForwardBias Technologies

Основи

Като за начало може да прочетете Основи на локализациите [developer.qt.nokia.com] . В Qt, локализациите са реализирани чрез QLocale и QSystemLocale.

QSystemLocale

QSystemLocale е интерфейс за запитване за информация за локализацията на потребителя. QSystemLocale::query() [doc.qt.nokia.com] може да се използва за да се взема информация като име на месеца, отрицателен знак за числа и т.н.

QSystemLocale::query() може да бъде предефинира от приложението с цел да предостави по-нататъшно персонализиране на потребителската локализация.

Локализация по подразбиране

Qt програмите мога да се пускат с всякаква локализация като се посочи такава по подразбиране с QLocale::setDefault(). Когато не е зададена локализация по подразбиране, Qt използва информацията от QSystemLocale, т.е тази от операционната система.

QLocale

QLocale е “front-end” клас, който помага във форматирането на данните, базирайки се на идентификатора на локализацията. QLocale използва формата <език>_<страна>.<код> за идентификатор. QLocale, който е създаден без параметри (QLocale()) е еквивалентен на този по подразбиране. Когато няма зададен по подразбиране, се използва системният.

Има два начина, по които QLocale определя форматирането. Първия начин е, когато няма зададена по подразбиране локализация (QLocale::setDefault) и QLocale обект е създаден с конструктор по подразбиране. В такъв случай, QLocale() събира всичката информация през QSystemLocale::query(). Втория вариант е, когато има зададена по подразбиране локализация или QLocale обект е създаден с език и страна(идентификатор на локализацията). В този случай, Qt се обръща към qlocale_data_p.h [qt.gitorious.org] за да определи как да форматира данните. qlocale_data_p.h е генериран от CLDR [cldr.unicode.org] като се използват скриптовете cldr2qlocalexml.py и qlocalexml2cpp.py от local_database [qt.gitorious.org].

Нека да повторим:

• Когато използваме системна локализация, информацията за форматирането идва от ОС-а, а не от CLDR данните.
• Когато има зададена локализация по подразбиране или QLocale обект е създаден с идентификатор, информацията за форматирането идва от CLDR данните.

Резервна локализация

Резервната локализация (QSystemLocale::fallbackLocale [doc.qt.nokia.com]) е QLocale създаден като се използва идентификатор, намерен в променливите на средата (LC_ALL и LANG). Ако тези променливи не са настроени, GetUserDefaultLCID се използва на Windows и CFLocaleGetIdentifier на Mac OS X.

Графични елементи и локализации

На всеки графичен елемент може да се зададе индивидуална локализация чрез QWidget::setLocale(). Локализацията се предава от родител на децата, когато не е зададена.
Qt изпраща събитието QEvent::LocaleChange към графичен елемент, когато неговата локализация се смени.

QtWebKit

Какво е Qt WebKit?

WebKit е един от най-популярните начини за обработка и визуализация на уеб страници и изпълнение на JavaScript.
За повече информация посетете страницата за WebKit в Wikipedia [en.wikipedia.org]

Qt WebKit е порт на WebKit към Qt. QtWebKit ползва публични API на Qt и теоретично може да бъде ползван на всяка платформа, която се подържа от Qt (теоретично, защото WebKit се нужда е от добър съвременен компилатор ).

Разработване на QtWebKit

Начало

QtWebKit е модул на Qt. За да го полвате трябва да го включите във вашия проект. Добавете следният ред съм вашия .pro файл:

Приложения, използващи QtWebKit

QtWebKit често се ползва за броузъри или за вграждане към други приложения , за да обработва уеб съдържание.

Как да вземем участие в разработването на QtWebKit?

Работата по QtWebKit е напълно отворена. Всеки, който иска да се присъедини е добре дошъл.

Комуникация

Име ежедневни дискусии в IRC или по майлинг листата.

Каналът в IRC #qtwebkit се ползва за разработване с Qt, каналът #webkit е за обща разработка на WebKit.

Основните майлинг листи са WebKit-Qt [lists.webkit.org] и WebKit-dev [lists.webkit.org]

Моля, обърнете внимание, че тези методи за комуникация се ползват са самото разработване на WebKit, а не за разработване на приложения, които го ползват.

QtWebKit

What is Qt WebKit?

WebKit is one of the major engine to render webpages and execute JavaScript code.
More information about WebKit on Wikipedia [en.wikipedia.org]

Qt WebKit is the port of WebKit on top of Qt. QtWebKit relies on the public APIs of Qt and can theoretically be used on any platform supported by Qt (theoretically because WebKit also requires a recent/good compiler).

Developing with QtWebKit

Getting started

QtWebKit is a module of Qt, to use you need to add it to your project file. Add the following line to your .pro file:

Applications using QtWebKit

QtWebKit is often used as a rendering engine, as a runtime, or to write a browser.

How to participate in the development of QtWebKit?

The work on QtWebKit is fully open. Everyone interested is welcome to participate.

Communication

The daily discussions are done on IRC and on mailing lists.

On IRC, the channel #qtwebkit is used for the development with Qt, and the channel #webkit for general development of WebKit, both channels are on the network FreeNode. (For a full list of IRC channels see OnlineCommunities.)

Mails threads are used for in-depth discussion like new APIs or architectural changes. The main mailing lists to join are WebKit-Qt [lists.webkit.org] and WebKit-dev [lists.webkit.org]

Note that those mailing list and IRC channel are for the development of WebKit itself, not the development of application using WebKit.

QtVariant

Introduction

In C++, a variable needs to have its type known at compile time. There are situations that however require us to deal with variables whose type is known only at run time. For example, let’s say you have a function that returns a value from the database. What would its return value be? In C, it would be a “void *” and an additional information would provide its type. Or assume that you allow the user to attach arbitrary information to the cells of your custom table widget. What type be the argument type for this function setUserCellData(type x)?

A QVariant can be used in the above situations and can be used to hold a value of any type. You can ask a QVariant for its type and handle the value stored inside it appropriately.

Before understanding Qt’s implementation, we will first try to see the various problems involved in designing the QVariant to appreciate the final solution better.

QVariant functionality requirements

1. QVariant should not (and cannot) be a template class. If QVariant is a template, every class that store a QVariant needs to become a template.
2. QVariant must work for both POD and non-POD data types. It should work for any type that is copyable and behaves as a value based type. Note that the support for non-POD types means that one cannot use a C union to hold all known types since C++ disallows placing non-POD types in a union.
3. QVariant must be able to store custom user types. So, if you write a MyStruct, you should be able to place it in a QVariant.
4. QVariant should (and cannot) not use C++ RTTI. In C++, RTTI only works with polymorphic classes.

Storing the value as ‘void *’

An idea would be to hold a ‘void *’ and a type inside QVariant. We can have a QVariant constructor as a function template that can just fit in any type. Like:

However, we will have trouble writing the destructor. How does one ‘delete’ the void pointer? In C++ you cannot delete a ‘void *’.

Arriving at the solution

As we can deduce from above, to delete the void * we simply need to know the type. And since QVariant needs to support user defined types it is not possible to put a huge switch case to reinterpret_cast the void * to a specific type and delete the pointer.

We also have a problem when trying to access the content of the QVariant. variant.value<MyStruct>() should not crash under any circumstance. If a conversion is not possible, it should return a default constructed MyStruct.

The solution is to have a system that can construct a value from a void *, destroy a void * and cast a void * type to access the value. If we have functions for these tasks for every type that can be stored in a QVariant, then QVariant can use these functions to work on the void *.

qMetaTypeConstructHelper and qMetaTypeDeleteHelper are the template construction helpers
qRegisterMetaType<MyStruct>(“MyStruct”) —- QMetaType::registerType(“MyStruct”, ctr, dtr); —- Internally it’s all stored in a QVector<QCustomTypeInfo>

If you do qRegisterMetaType for all types, we are done! But it’s a pain?
Q_DECLARE_METATYPE(Type) —— Create a class QMetaTypeId that provides qt_metatype_id() that registers on demand.

qMetaTypeId provides compile time look up of a type’s id

QtVariant

Въведение

В C++ променливите трябва да имат тип, който да е известен по време на компилацията. Но има ситуации, които налагат да се използват променливи, чийто тип е известен само по време на изпълнение. На пример, нека да кажем, че имате функция, която връща стойност от база данни. Какъв ще бъде типа на върнатата стойност? В C, ще бъде “void *” и допълнителна информация ще бъде предоставена за типа и. Или да предположим, че вие позволявате на потребителя да добавя произволна информация в клетките на разработена от вас таблица. Какъв тип трябва да бъде аргумента на тази функция – setUserCellData(type x)?

В тези ситуации може да се използва QVariant и той може да съхранява стойност от всеки тип. Вие можете да питате QVariant за типа и да обработите стойността, съхранена вътре подобаващо.

Преди да разберем реализацията на Qt, първо ще се опитаме да разберем различните проблеми, включени в дизайна на QVariant, за да оценим по-добре крайното решение.

Изисквания към функционалността на QVariant

1. QVariant не трябва ( и не може) да бъде шаблонен клас. Ако QVariant е шаблонен, всеки клас, които съхранява QVariant трябва да стане.
2. QVariant трябва да работи както за POD, така и за не-POD типове данни. Трябва да работи с всеки тип, който може да се копира и да се държи като клас за съхранение на данни. Забележете, че поддръжката на не-POD типове, означава, че не може да се използва C типа union за съхранение на всички известни типове данни, тъй като C++ не позволява слагането на не-POD типове в union.
3. QVariant трябва да може да съхранява потребителски типове. Така, че ако напишете MyStruct, трябва да можете да я съхраните в QVariant.
4. QVariant не трябва (и не може) да използва C++ RTTI. В C++, RTTI работи само с полиморфични класове.

Съхванение на стойността като ‘void *’

Идейно би било да се пази ‘void *’ и типа в QVariant. Може да имаме QVariant конструктор като функционален шаблон, който да пасва на всеки тип. Нещо като:

Обаче имаме проблем, когато трябва да направим деструктор. Как да ‘delete’ void указател? В C++ не можете да унищожавате ‘void *’.

Намиране на решението

Както можем да се досетим от горния пример, за да унищожим void *, ние просто трябва да знаем типа. И тъй като QVariant трябва да поддържа дефинирани от потребителя типове, не е възможно да се сложи един голям switch с reinterpret_cast на void * към даден тип и да унищожим указателя.

Също имаме и проблем, когато искаме да вземем съдържанието на QVariant. variant.value<MyStruct>() не трябва да дава грешка при никакви обстоятелства. Ако конвертирането не е възможно, трябва да върнем променлива от тип MyStruct, създадена с конструктора му по подразбиране.

Решението е да имаме система, която може да конструира стойност от void *, да унищожава void * и да превръща void * в правилния тип, за да може да работи със стойността. Ако имаме функции за тези дейности за всеки тип, който може да се съхранява в QVariant, тогава QVariant може да използва тези функции за да работи с void *.

qMetaTypeConstructHelper и qMetaTypeDeleteHelper са помощни шаблонни функции
qRegisterMetaType<MyStruct>(“MyStruct”) —- QMetaType::registerType(“MyStruct”, ctr, dtr); —- Вътрешно всичко се пази в QVector<QCustomTypeInfo>

Ако направим qRegisterMetaType за всички типове, ще сме готови! Но това не е ли прекалено много работа?
Q_DECLARE_METATYPE(Type) —— Създава клас QMetaTypeId, който предоставя qt_metatype_id(), което регистрира при нужда.

qMetaTypeId предоставя възможност за проверка на номера на типа по време на компилация

Qt Help Generator

qhelpgenerator is the tool used to generate help files which can be read by Qt Assistant and Qt Creator.

qhelpgenerator creates an sqlite database containing the documentation html pages and a list of keywords, which can be used for searching in the documentation.