Porting QML applications to Qt 5

When porting qml-related code from QT 4.8 to QT 5, application developers should is aware that the QML infrastructure have Undergone considerable changes in Qt 5. The sections below describe these changes and the impact they has on your existing code.

This article describes the changes that affect your existing code. If you is interested in the summary of all new features in Qt 5 for QML application development, see Qt QML Release Notes and Qt Quick Release Notes.

QML Language Changes

There is very few changes in the QML language this affect the porting of existing QT 4.8 QML code to QT 5. These is:

• Individual file imports no longer work (for example, import "MYTYPE.QML"). Import the containing directory instead.
• Relative file paths in JavaScript files is now resolved Relative to the location of the JavaScript file instead of the QM L file that imported it.
• It ' s no longer possible to override signals from the base component.

QtQuick Module

The QtQuick module has been updated to version 2. All QML applications should update their import statements to use the new version:

Import QtQuick 2.3

Property and Method Changes

• The ListView ' s highlightmovespeed and highlightresizespeed properties have the been renamed to Highlightmovevelocity and Highlightresizevelocity, respectively.
• TextInput and TextEdit ' s opensoftwareinputpanel () and Closesoftwareinputpanel () methods have been removed. Use the new Qt.inputmethod property and call Qt.inputMethod.show () Qt.inputMethod.hide () to show and hide the virtual keyb Oard.

Type and API changes

• Xmllistmodel has moved to its own module, Qtquick.xmllistmodel. Any code that uses the Xmllistmodel and Xmlrole types must import Qtquick.xmllistmodel instead.
• The local storage API that enables SQL support have been moved from the QML Global Object into a qtquick.localstorage Singleton type. Any code that requires the local storage API must import qtquick.localstorage instead. See THEQT Quick Local Storage documentation for examples.
• The layoutitem type has been removed from the QtQuick module as it is specific to the Graphics View fra Mework backend used in Qt Quick 1.

Behavioral changes

QtQuick 2 includes a number of behavioral changes and you should thoroughly test your applications after porting. These changes would not necessarily leads to run-time errors, but could break certain assumptions in your code. Below is the prominent changes to being aware of when porting your applications.

Item Opacity and Visibility:

• The input handling details of opacity and visible have changed. An opacity of zero longer affects input handling, where previously it stopped mouse input. A visibility of false no longer affects keyboard input, but still stops mouse input. The new enabled property stops mouse and keyboard input, but does not affect how or whether the item is rendered. A workaround for applying the old behavior in most cases are to bind enabled to (visible && opacity > 0.0) .
• Previously, if an item is in a positioner (i.e. a Row, Column, Grid and Flow) and the item ' s opacity changed to 0, or its visible value became false, the positioner would remove the item from its layout and collapse The space for that item. In QtQuick 2, the This "only" happens when an item's visible is false; The item opacity no longer affects whether the item is laid out. (This was consistent with the existing behavior of the ListView and GridView).

Text:

• The Textedit::textformat property now defaults to plaintext instead of AutoText.
• When Text::textformat was set to text.autotext format, the Text object would automatically switch to Text.style Dtext instead of text.richtext.

Other:

• Modifying the Image::sourcesize now fits the Image to the size, maintaining aspect ratio.
• For ListView and GridView, the cachebuffer property now have a non-zero default and delegates in the cache buffer is created asynchronously. Also, using a RightToLeft layout Now Also reverses the preferredhighlightbegin and Preferredhighlightend.
• For Loader, the sourcechanged and sourcecomponentchanged signals is now only emitted when their respect Ive properties change value. (previously Loader emitted both of these signals when either of the relevant properties had changed.)

Changes to experimental qt.labs modules

• The Qt.labs.particles module has been removed. It is replaced by the fully-fledged Qtquick.particles module which are an enormous improvement on its predecessor.
• The Qt.labs.shaders module has been removed as the Shadereffectitem and Shadereffectsource types from th Is module has been moved into the QtQuick module. Note the shadereffectitem type has been renamed Toshadereffect.

C + + code

In Qt 5, all QML applications is rendered with an OpenGL scenegraph architecture rather than the Graphics View framework Used in Qt 4. Due to the scale of this architectural change, the C + + API has been extensively restructured and theqtdeclarative Module has been deprecated in favor of the new MODULES:QT QML, which implements the QML engine and language infrastructu Re, and Qt Quick, which implements the visual canvas and Scenegraph backend.

All classes this were previously in the qtdeclarative module has been moved into the QT QML and QT Quick modules , and their class names has been changed to reflect their new module locations. The class name changes is as follows:

Qt QML
Qt Quick

• Qdeclarativecomponent-Qqmlcomponent
• Qdeclarativecontext-Qqmlcontext
• Qdeclarativeengine-Qqmlengine
• Qdeclarativeerror-Qqmlerror
• Qdeclarativeexpression-Qqmlexpression
• Qdeclarativeextensionplugin-Qqmlextensionplugin
• Qdeclarativeinfo-Qqmlinfo
• Qdeclarativelistreference-Qqmllistreference
• Qdeclarativenetworkaccessmanagerfactory-Qqmlnetworkaccessmanagerfactory
• Qdeclarativeparserstatus-Qqmlparserstatus
• Qdeclarativeproperty-Qqmlproperty
• Qdeclarativepropertymap-Qqmlpropertymap
• Qdeclarativepropertyvaluesource-Qqmlpropertyvaluesource
• Qdeclarativescriptstring-Qqmlscriptstring

• Qdeclarativeitem-Qquickitem
• Qdeclarativeview-Qquickview
• Qdeclarativeimageprovider-Qquickimageprovider

To use the new qqml* and qquick* classes in Qt 5, link against the Approprate module from your qmake .pro file. For example the following would link against both the QT QML and QT Quick modules:

QT + = QML Quick

Required header files can then be included:

#include <QtQml/QQmlEngine> #include <QtQuick/QQuickView>

(The qtdeclarative module is still available to developers as the Qt Quick 1 module, as discussed below.) However, it should not being used for new applications.)

Qdeclarativeitem and Qdeclarativeview

When porting to Qquickitem, note this qdeclarativeitem inherited from Qgraphicsitem; In contrast, Qquickitem inherits directly from Qobject, and any qgraphicsitem-specific functionality are no longer availabl E. In particular, Qquickitem does not has a paint () method for performing custom rendering through the Qpainter Api. Instead, in Qt 5, custom rendering should is performed through the new qsg* classes to take full advantage of the Scene graph. See the Qt Quick Scene graphdocumentation details on using these classes.

Alternatively, the Qquickpainteditem provides a paint () method and can be used as a convenient a-to port Qdecla rativeitem-based classes that use the Qpainter API. Note This method was less performant than using the qsg* classes.

When porting from Qdeclarativeview to Qquickview, note this qdeclarativeview inherited from Qgraphicsview. In contrast, Qquickview inherits from Qquickwindow and uses the Qwindow infrastructure introduced in Qt 5; Any qgraphicsview-specific functionality is no longer available.

Qmlscene Utility

The qmlviewer tool provided for prototyping and testing QML applications in Qt 4.x have been replaced with the qmlscene tool which integrates with the new scenegraph features in Qt 5.

QML Plugins

All QML plugins should extend Qqmlextensionplugin in Qt 5.

Additionally, plugins should use the new QT plugin infrastructure introduced in Qt 5. QML plugins no longer require the q_export_plugin2 () macro. Instead, they should use the Q_plugin_metadata () macro within the PLUGIN class declaration.

See the updated Creating C + + Plugins for QML documentation for a overview of Creating QML in Qt 5.

Qtdeclarative module in Qt 5

For the purposes of porting older applications, the qtdeclarative module are still available in Qt 5 but have been Renamed to Qt Quick 1. Applications that required Qt Quick 1 specific API (e.g. Qdeclarativeview or Qdeclarativeitem and the Graphics View Integr ation) can use the This module. Note that new applications should use the new QT QML and QT Quick modules instead.

To use the Qt Quick 1 module, add "declarative" to your Qmake . Pro File:

QT + = Declarative

Required header files can be included as follows:

#include <QtDeclarative/QDeclarativeView> #include <QtDeclarative/QDeclarativeItem>

Porting QML applications to Qt 5