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()
Possibly related posts:
21 comments
I see there is a QML Video element. Is it possible to use it yet? I have tried to with a build from the main QT git source and it gives an unknown element error. And will it be able to play whatever formats the system(Linux in my case) has codecs installed?
Does QML work with OpenGL rendering? If so is there an example of the proper way to setup the QT window and QML environment? And is it possible to have an OpenGL element inside of a QML hierarchy?
Also, what is the best way to work with the latest Qt source from the master git branch and the latest Qt Creator git branch? Are they kept in sync or are they meant to be two completely separate source trees that you build from and run in parallel with each using its own libraries? It would be fantastic to have a absolutely basic blog post on how to work with git and the various Qt branches and versions.
I really like what I’m seeing with the Declarative stuff but so far it has been a struggle to get up to speed with many very basic things required to work with it. The IRC QML channel is usually completely dead and the forums seem to average about 1 post a week.
I’ve been using the Declarative stuff for a couple months now and like what I am seeing so far. There are two criticisms that come to mind though:
1. Once I’ve moved beyond playing with the examples and trivial test projects the QML files rapidly start to become a giant mess of data and behavior. Perhaps I don’t have enough experience yet to break up my QML into sub-elements and dynamically load them into the scene or have a really good real world example to learn from.
2. Even on a high end workstation I am seeing quite a bit of slowdown for some things like a flickable element with 100 or so text elements. I know this is still very early bleeding edge stuff but regardless of how much more optimization goes into the Declarative stuff you are pretty much at the mercy of the underlying Qt/Declarative engine. I don’t see any way to ensure that you want your QML scene to run frame locked to vertical blank or some fixed screen update rate.
@barryw: 1. The demos in demos/declarative break the QML into more components. We’ll work on improved demos with better modularization for the release.
2. that sounds far, far below the performance we’d expect to see. Have you tried using -graphicssystem raster or -graphicssystem opengl? The X11 graphics system is particularly bad for animated scenes.
We had already experimentally reimplemented our GUI here in QML with the patch that was available for 4.6.0, and even though the scene was quite complex, this was no big deal to make the changes since everything could be nicely modularized into reusable Qml components.
One feature I still miss very much, though, is the ability to use images with an alpha channel and to have MouseArea s that take transparent pixels into account for ignoring clicks on them. I have implemented an event filter for that, but it resulted in quite hacky code in which I am not completely confident, especially for the hover events part (“enter” and “leave” events).
I know rectangle-only parts were chosen for performance issues, but having that feature as an optional flag (somehow like the “smooth” properties) wouldn’t kill anyone, wouldn’t it?
Thanks for the response Martin.
I just ran the QML interface I was referring to and it is much faster now that I have updated to the latest git master source from my older version. It would be nice still to be able to have the option of having the QML scene be frame locked or have fixed rendering timer. Even if the QML scene isn’t very complex you still get stutters and slowdowns from activity going on.
A few more QML questions:
1. Is it possible to have an OpenGL element with rendering being done in C++ in its own thread or a video element inside a QML hierarchy playing an mpg source?
2. I see people using the opacity property to swap between various QML elements in a scene. Is it possible to load a QML file into a specific spot in an existing QML scene hierarchy?
3. I haven’t been able to figure out how to make a QML element follow the mouse around with a SpringFollow type motion. Anyone know how?
4. When I use -graphicssystem opengl on Ubuntu 9.10 with recent code from the git master repo I get weird font rendering issues with a TTF loaded with FontLoader. Certain letters in strings are vertically offset by a pixel or so and other glitches.
5. Is there a way to put up a framerate monitor for a QML scene?
6. How about for the Image element allowing use of actual OpenGL fragement shader programs?
Is it possible to define a ListView of one list item, then have it switch between the items?
Sorry, one item in the view area, but multiple loaded, then use the flick scroll to move between them. or define a fadescroll? I really like the idea of using models to manage data in a 1-item display area
Currently there is no support, in QML, for “Right to Left” layouts. It is useful not only for text, but for images and elements too.
i.e. I need to realize a ListView of images where the first one stays on the right of the view and the next one to its left. I don’t know how can I realize it with the current API.
“i.e. I need to realize a ListView of images where the first one stays on the right of the view and the next one to its left. I don’t know how can I realize it with the current API.”
PathView & PathLine?
@barryw: “PathView & PathLine?”
Thanks! I also wanted right-to-left listviews, and this should solve it, will try it soon.
I was looking for a simple property that would define the sense of the list view, but didn’t find anything like it.
Yes, the “PathView + PathLine” solution works…but it’s a workaround. The items are placed by density on the path so the spacing isn’t managed in the same way of a ListView.
In qt-declarative-4.6.0 I can connect signal in Java Script block like this: item.clicked.connect(console.log(‘test’)). Where item is created using createComponent() and createObject(). But in 4.7.0-tp1 I can’t. How I can to fix it?
@barryw so setting the ListView to horizontal with “ListView { orientation: “Horizontal” }” is not enough?
@designker
It was zuck who asked the question.
@designker: I don’t know barryw’s problem. But in my case this is not enough. I would like to have the elements in the ListView pushed towards the right. Kind of like “align right” for text.
So if the ListView is 200px wide, each item in the list is 50px wide, the spacing is 0px and there are only 3 items in the list, then the first item will be at the position x=50px, the second at x=100px and the third at x=150px.
I hope I explained myself better.
I moved my current code early this week/over the weekend to use Qt 4.7 TP1.
It’s a pleasure to see stuff getting more coherent.
Although, I have some small “remarks”:
1) I can see some inconsistency in the documentation: sometimes there are bits missing/misnamed
2) Again, about the doc, the part about Dynamically Allocated Components needs to be putted up to speed: I’m currently able to instantiate dynamically Components from C++ side and inject, but NOT from QML. Using, of course, the stuff in the doc.
3) Something like “engine->executeJavascript()”? So that code can be executed within the QML scope, without have to make a new component and so forth?
4) If I load a QML from file, and there is an error in it, I get clear messages on the console. If the same file I load it using C++ code (Component.create() and…), I just get a crash.
5) I just moved to import QMLs inside my QRC so that I can ship them with the app easily. This made the error messages go all jerky: I don’t get the line where the error is anymore.
If you guys those are actually bugs, I will take care of submitting them to bugzilla.
A part from this “bumps” during the development, I LOVE QML.
@zuck: Unfortunately right aligning in views is not possible. If you add a suggestion to http://bugreports.qt.nokia.com/ it can be considered for a future release
@barryw 1) Currently we don’t have any easy way to integrate/blend with GL content, but *might* investigate this in our OpenGL integration. Video elements should be in there, format support depends on your backend. 2) You can use the Loader element to load a “new” component into a scene. 3) You need an Item that has mouse tracking enabled and use that to let a child of this component track the mouse 4) Can you take a screenshot and report a bug with component Declarative (assuming you don’t see the same issue in the examples/demos outside of declarative) at http://bugreports.qt.nokia.com/ 5) You can define export QML_SHOW_FRAMERATE=1 and then take that to e.g. a graphing tool where you inverse the ms number to get a insta-framerate. Also, the QML inspector in Creator gives you this. 6) Again, something we *might* research in our OpenGL support.. Watch this space
@detro: 1, 2: It would be great if you could collect the inconsistencies you find in the documentation and submit a bug some time. When you deal with it all day you start to overlook those things.
3. This is not something we’re considering at the moment. I think there is a suggestion in Jira already.
4. The errors are available via the QDeclarativeComponent::errors() method: http://doc.qt.nokia.com/4.7-snapshot/qdeclarativecomponent.html#errors. You can iterate over them using qWarning() to print each one. The QML runtime does this for you. It shouldn’t crash in any case – create() should return 0 on error.
5. Sounds like a bug.
@ThomasM, the video element is in a module, try ‘import Qt.multimedia 4.7′.
Hoping it’ll release soon on the Creator platform as an SDK. Compiled 4.7 for several hours, several times. Puts out out a bad exe file on Windows, just crashes. Probably my machine. Got no time to debug it. Too much to do to try again, switching from fixed OpenGL to OpenGL ES. QML is a must have. Got 4 beagleboards and an N900 just sitting and waiting. I think that next to OpenGL support, QML is the most important upgrade I’ve seen from the Trolls. What’s next? Transformer cell phones?
Comments on this entry are closed.