C

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

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 Qt5, which requires a version number against the import statement, Qt Quick Ultralite will ignore version number in the import statement

Dealing with image resources

Qt Quick Ultralite does not allow you to load dynamic images at run time. Also, The Qt Resource System is not supported. You need to mention all required image assets in the QML files. The Qt Quick Ultralite Code Generator tool processes the image assets and embeds the uncompressed assets, raw data buffers, and metadata information into the application binary.

As the url QML basic type is not supported, there exists an another basic type called image which is the type of the Image object's source property. You can create the image type at compile time from a string literal that represents a path to the image.

If you use the asset directly as a source property, you can give a relative path to the image:

...
Image {
   ...
   source: '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('path/to/your/asset_pressed.png') : Qul.image('path/to/your/asset_normal.png')
    ...
}
...
ListModel {
   id: contactsModel
   ListElement { name: "John Smith"; phoneNumber: "555 123 456"; avatar: Qul.image('path/to/avatar.png'; }
   ...
}

Image optimizations

On some platforms, if you use a transformation to rotate an image, it might be beneficial to compile the image in a different format. The code generator optimizes the assets for rotation when you add the ?rotated=true parameter to a file name:

Image {
    source: "images/my_image.png?rotated=true"

    transform: Rotation { ... }
}

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.

Dealing with string colors

The Qt Quick Ultralite Code Generator tool performs a string to a color conversion during compile time. There is no runtime conversion between strings and colors. However, the code generator can convert a string literal to a color at compile time.

Text {
    color: "red" // or "#FFFF0000" or "#FF0000"
    ...
}

Qt Quick Ultralite does not support conversion of a string to a color at the runtime. However, you can still use the Qt.rgba() method. In order to force an explicit conversion at compile time from a string to a color, the Qul.color method can be used as follows:

Text {
    ...
    color: mouseArea.pressed ? "red" : "#7F7F7F" // Does not compile!
    ...
    color: mouseArea.pressed ? Qul.color("red") : Qul.color("#7F7F7F") // OK
}
...

It is recommended to create a separate style singleton, such as Style.qml. You can create it as follows:

pragma singleton;
Object {
    readonly property color pressed: "#19f801";
    readonly property color normal: "#0066ff";
}

You can use the singleton within your code as follows:

Text {
    ...
    color: mouseArea.pressed ? Style.pressed : Style.normal
    ...
}

String concatenation

Qt Quick Ultralite does not support string concatenation. The following code snippet provides a workaround solution for a use case where you need to display text that consists of multiple strings. In Qt Quick, you can have the following code:

Text {
    ...
    text: "Current index = " + index
    ...
}

You need to reimplement it as follows:

Row {
    Text {
        ...
        text: "Current index = "
        ...
    }

    Text {
        ...
        text: rawCanBusHandler.gearShift
        ...
    }
}

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 Qul.color("#AAFFAA")
    }
    else if (isEven) {
        return Qul.color("#AACCAA")
    }
    return Qul.color("#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. It is also not possible to iterate from script expressions over model elements. Currently a known bug prevents using a model with multiple views.

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('path/to/john.jpg'; },
  { name: "Anne Smith"; phoneNumber: "555 654 321"; avatar: Qul.image('path/to/anne.jpg'; }
]
...
}

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

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.