QML on the Road to Release

As QML progresses towards its first official release we are again reviewing the APIs. This has resulted in a number of changes to the QML and C++ API in the Qt 4.7 alpha release, and a few more to come in the beta. Unfortunately this will result in some small adjustments for the early adopters, but I'm sure we all agree that its better to get the API right before release.

The QML API changes made in the Qt 4.7 alpha and also the changes coming in the beta are outlined below. If you find that your QML does not run after upgrading to a newer version of Qt be sure to check src/declarative/QmlChanges.txt first.

If you are getting started with QML and need a little help getting over a hurdle, or coaxing yourself into a declarative state of mind, join the #qt-qml channel on Freenode. Don't forget to show off your QML creations! We've also set up a dedicated mailing-list for QML-specific discussion: qt-qml@trolltech.com.

Changes in the alpha:

The "viewport" properties in Flickable were not well named. The properties actually refer to the content that is flicked rather than the viewport that you "look through".

• viewportWidth -> contentWidth
• viewportHeight -> contentHeight
• viewportX -> contentX
• viewportY -> contentY

We also removed the Flickable.reportedVelocitySmoothing property, which we're confident no one will miss.

In a later release we'd like to have a "TouchArea", so in order to have consistent naming in the future MouseRegion has been renamed MouseArea.

Connection syntax has been changed to allow connections to multiple signals of an object. Its name therefore changes to the plural. So the old form:

Connection { sender: a; signal: foo(); script: xxx }
Connection { sender: a; signal: bar(); script: yyy }

becomes:
Connections { target: a; onFoo: xxx; onBar: yyy }

ListView.sectionExpression has been replaced by section.property and section.criteria

ListModel is now strictly type-checked (previously, everything was a string)

• foo: "bar" continues to work as before
• foo: bar is now invalid, use foo: "bar"
• foo: true is now a bool (not string "true")
• foo: false is now a bool (not string "false" == true!)

PropertyAnimation::matchProperties and matchTargets have been renamed back to properties and targets. The semantics are explained in the PropertyAnimation::properties documentation and the animation overview documentation.

Easing curves and their parameters are now specified via dot properties:

• easing.type : enum
• easing.amplitude : real
• easing.overshoot : real
• easing.period : real

For example:
PropertyAnimation { properties: "y"; easing.type: "InOutElastic"; easing.amplitude: 2.0; easing.period: 1.5 }

C++ API:

C++ classes have been renamed QDeclarative... rather than Qml...

QML_DEFINE_... definition macros, previously global macros, are replaced by qmlRegisterType registration functions, which must be called explicitly, e.g.:

qmlRegisterType<minehuntgame>("MinehuntCore", 0, 1, "Game");

C++ API users should also consider using the QDeclarativeExtensionPlugin (previously named QmlModulePlugin) as a cleaner mechanism for publishing libraries of QML types.

The API of QmlView has been narrowed and its role as a convenience class reinforced. It has also been renamed QDeclarativeView:

• remove addItem()
• remove clearItems() - use 'delete root()'
• remove reset()
• resizeContent -> enum ResizeMode { SizeViewToRootObject, SizeRootObjectToView }
• remove setQml(), qml()
• rename setUrl(), ur() to setSource(), source()
• root() -> rootObject(), returns QGraphicsObject rather than QDeclarativeGraphicsItem
• remove quit() signal -> use quit() signal of engine()
• initialSize() signal removed
• Added status() to determine status of the internal QDeclarativeComponent
• removed execute() - setSource() will also execute the QML.

Upcoming changes in the Beta:

These changes will soon be available from the qt/4.7 git repository, and will be included in the Qt 4.7 beta release.

• PathView: offset property now uses range 0-1.0 rather than 0-100
• ListView, GridView::positionViewAtIndex() gained a 'mode' parameter to allow more fine grained control of where the view moves to.
• Removed Qt.playSound (replaced by SoundEffect element in the mulitmedia module)
• Removed Qt.closestAngle (use RotationAnimation instead)
• Removed NumberFormatter
• Removed DateTimeFormatter (use Qt.formatDateTime() instead)
• Using WebView now requires "import org.webkit 1.0"
• Using Particles now requires "import Qt.labs.particles 1.0"
• AnchorAnimation must now be used to animate anchor changes (and not NumberAnimation)

Behavior and Animation syntax has been changed to differentiate from property assignments. Previously animations and behaviors could be "assigned" to properties like this:

Item { x: Behavior {}; y: NumberAnimation {} }

To make it more obvious that these are not regular value assignments a new "on" syntax has been introduced:
Item { Behavior on x {}; NumberAnimation on y {} }
Only the syntax has changed, the behavior is identical.

C++ API:
QDeclarativeContext::addDefaultObject() has been replaced withQDeclarativeContext::setContextObject()