Non-API level differences between Qt Quick Ultralite and Qt Quick


See also the list of Known Issues or Limitations.

Application startup code

The application class is currently available within internal API sets. Thus you can create the application startup code by using the pragma main statement at the top of your application's root QML file.

The Qt Quick Ultralite Code Generator tool converts the new QML pragma statement to a proper int main() function that is responsible for the application startup. The following code snippet illustrates how you can use the pragma main statement:

pragma main

Rectangle {

Note: Your application can only have a single occurrence of the root QML file.

Import statement with optional version number

Unlike Qt Quick, which requires a version number against the import statement, Qt Quick Ultralite ignores version number in the import statement. To write qml that is compatible with Qt Quick, the version number must not be omitted. See also the compatibility page.

Dealing with image resources

Qt Quick Ultralite does not allow you to load dynamic images at run time. All images must be registered via the Qt Quick Ultralite resource system. For additional documentation refer to Image.

If you use the asset directly as a source property, you can use a string literal:

Image {
   source: 'qrc:///path/to/your/asset.png'

If you use the asset within a script expression, it might be necessary to explicitly create an image by wrapping its path within the Qul::image() helper function. The Qt Quick Ultralite Code Generator tool processes the function at compile time. You can wrap the path as follows:

Image {
    source: mouseArea.pressed ? Qul.image('qrc:///path/to/your/asset_pressed.png') : Qul.image('qrc:///path/to/your/asset_normal.png')

ListModel {
   ListElement { name: "John Smith"; phoneNumber: "555 123 456"; avatar: Qul.image('qrc:///path/to/avatar.png'; }

Image optimizations

On some platforms, if you use a transformation to rotate or scale an image, it might be beneficial to compile the image in a different format. To enable this optimization, set the QUL_OPTIMIZE_FOR_ROTATION or QUL_OPTIMIZE_FOR_SCALE source file flag on the image resource. Example:


In applications, icon images usually have only a single color with alpha transparency. Qt Quick Ultralite detects such images and stores them in an optimized alpha map format. This works as long as the image has only one color. If the image has big transparent border, the image is automatically cropped.

Script expressions

Qt Quick Ultralite does not fully support the ECMAScript Language Specification and only a minimal subset of APIs is implemented. However, you can still use script expressions in the following cases:

  • In a body of property bindings. These script expressions describe relationships between QML object properties. When dependencies of a property change, the property is automatically updated too, according to the specified relationship.
  • In a body of Signal handlers. These script statements are automatically evaluated whenever a QML object emits an associated signal.
  • In a definition of custom methods. Script functions that are defined within a body of a QML object become methods of that object.

Qt Quick Ultralite does not support using standalone JavaScript resource (.js) files. As the script code is converted to C++ code when you define custom script methods, it is important to declare an argument type. If a method returns a value, then the return type needs to be declared within the method signature. Inside a function, it is possible to use var variables, but they always must be initialized for the type to be deduced:

function getColor(i : int, pressed: bool) : color {
    var isEven = i % 2 == 0
    if (pressed) {
        return "#AAFFAA"
    else if (isEven) {
        return "#AACCAA"
    return "#CCAACC"

Model-View-Delegate pattern


Qt Quick Ultralite allows you to define models within QML in a similar way as Qt Quick:

  • You can declare ListModel and ListElement primitives
  • You can pass a list of objects
  • You can give an integer value

Unlike in Qt Quick, ListModel and ListElement are read-only. This implies that you cannot change values that are stored in such a model.

Note: If you need mutable models, see Qul::ListModel and Integrating C++ code with QML.

If you use a list as a model, you need to initialize it due to the lack of list and var basic QML Types.

ListView {
model: [
  { name: "John Smith"; phoneNumber: "555 123 456"; avatar: Qul.image('qrc:///path/to/john.jpg'; },
  { name: "Anne Smith"; phoneNumber: "555 654 321"; avatar: Qul.image('qrc:///path/to/anne.jpg'; }

Qt Quick Ultralite requires that the model is declared in the same file that it is used in.

Role access

Unlike in Qt Quick, access to model roles from delegates must go through the modelData property. Unqualified access or access using the model property is not supported:

ListModel {
    id: model
    ListElement {
        cost: "2.45"

ListView {
    model: model
    delegate: Text {
        text: modelData.cost // OK
        //text: model.cost // allowed in Qt Quick, not allowed in Qt Quick Ultralite
        //text: cost // allowed in Qt Quick, not allowed in Qt Quick Ultralite


Qt Quick Ultralite requires that the delegate is declared in the same file that it is used in.

To optimize run time memory footprint and to avoid dynamic allocations, only a certain number of delegates are created. The exact number of delegates is estimated during compile time and the estimation is based on a view container size and the delegate size.

The number of created delegates is higher than the number of visible delegates. For example, that enables a smooth scrolling effect. Once a delegate becomes invisible it can be reused and filled with data that corresponds to elements that soon becomes visible.

Available under certain Qt licenses.
Find out more.