C

Safety-Critical UI with Qt Quick Designer

You can use Qt Quick Designer included in Qt Creator for designing an application UI that contains both safety-critical and non-safety elements. This topic introduces the Qt Safe Renderer related functionality in Qt Quick Designer. For more information about how to use Qt Quick Designer, see Editing QML Files in Design Mode.

Note: Similar functionality is also available in Qt Design Studio. For more information, see Editing QML Files in Qt Design Studio's Design Mode.

Accessing Qt Quick Designer

Before you can access Qt Quick Designer, you must launch Qt Creator and open or create a new Qt Quick project that contains at least one Qt Quick UI form (a .ui.qml file).

Note: If you are using Qt Creator 6 or later, you can enable Qt Quick Designer by checking the QmlDesigner under Help > About plugins > Qt Quick.

Qt Creator provides wizard templates for creating a new Qt Quick project from scratch. When you create the Qt Quick Application - Stack project, the generated project contains empty Qt Quick UI forms where you can add safety-critical elements. See the Creating Qt Quick Projects for detailed steps how to create a new Qt Quick project.

When you have the Qt Quick project open in Qt Creator's Edit mode (1), select a .ui.qml form under your project (2) and enter to Qt Quick Designer by selecting Design (3) or by double-clicking the .ui.qml form.

Using Qt Safe Renderer QML Types

In Qt Quick Designer, Qt Safe Renderer provides the safety-critical UI elements as QML Types. From Qt Safe Renderer 2.0 onwards, the Qt Safe Renderer installation includes pre-built binaries of the Qt Safe Renderer plugins so you can start using the safety-critical QML types without separately building Qt Safe Renderer.

In Library view, you find the Qt Safe Renderer components (2) by typing "safe" (1) into the search field:

You can drag and drop the Qt Safe Renderer QML types into the Form Editor (3). The QML code is automatically updated to the Text Editor. The import statement (4) and the QML code for the dropped QML types (5) are added to the editor:

Safety-Critical QML Types

Qt Safe Renderer provides the following safety-critical QML types:

The safety-critical QML types are rendered in the UI by Qt Safe Renderer. They are rendered as raw bitmaps. The Qt Safe Renderer messaging interface defines how non-safe parts of system can communicate with safety-critical items on runtime. For more information, see the safety-critical QML type topics.

In Qt Quick Designer, you can work with the safety-critical QML types just like with any other QML types. For example, you can drag and drop the safety-critical types to the canvas (that is the working area where you create your UI) or to the navigator, and define properties and connections for them. For detailed information about how to use Qt Quick Designer, see Editing QML Files in Design Mode. Especially, Creating Components provides information how to use Qt Quick Designer for creating UI screens that contain QML types.

There are also many other properties available for the safety-critical QML types than listed in the sections below. See Specifying Item Properties for more information about using the properties.

Mandatory Properties for Safe QML Types

You must remember to define the following properties for each safe QML type that you add to the canvas:

PropertyDescription
fillColorfillColor is mandatory, if you use output verification.

For more information, see Qt Safe Renderer Output Verification.

SafeImage QML Type

With the SafeImage QML type, you can add images to your UI. The SafeImage supports the image formats listed in Qt Image Formats.

If you are using a resource collection file (.qrc) for storing your images, you can add the image file into the .qrc file as follows:

  1. In Qt Creator, open the Edit mode.
  2. In Projects, right-click the .qrc file.
  3. Select Open in Editor.
  4. Select Add Files.
  5. Browse to the image file and select Open.

See Enabling Qt Safe Resource Compiler Tool for more information about how to use Qt Safe Resource Compiler Tool for generating MISRA compliant data structures.

You can change the image in SafeImage with the following steps:

  1. In Qt Creator, open the Design mode.
  2. Right-click SafeImage in the canvas or in the item navigator.
  3. Select Change Source URL in the context menu.
  4. Browse to the image file and select Open.

Note: If part of the image is transparent, you should set fill color for the image. Otherwise the safety-critical content may not be properly visible. You can edit the fill color via Properties.

An example source code for SafeImage:

    SafeImage {
    id: safeImage1
    x: 314
    y: 235
    width: 65
    height: 65
    // image added to the .qrc file
    source: "safeimage.png"
}

Runtime Functionality

On runtime, you can change the position of SafeImage on the layout.

SafePicture QML Type

With SafePicture QML type, you can add safety-critical ISO icons to your UI.

Add the ISO icon to SafePicture with the following steps:

  1. Drag and drop SafePicture to the canvas from Components in Library.
  2. Right-click the picture element and select Choose Icon to open the ISO Icon Browser.
  3. To find icons, select a criterion for filtering icons and enter a search string.
  4. Select an icon in the list and then select OK to add the icon.

You can also adjust the icon color:

  1. Right-click the icon on the canvas or in the navigator.
  2. Select Edit Color in the context menu or open Properties.
  3. Select color.
  4. In Properties, edit fillColor. Setting the fillColor is mandotory, if you are using output verification.

See also ISO Icon Browser.

In the .pro file, the used ISO icons are listed as follows:

ISO_ICONS += \
    iso_grs_7000_4_2423 \
    iso_grs_7000_4_0238 \
    iso_grs_7000_4_0245 \

An example source code for SafePicture:

SafePicture {
    id: safePicture
    x: 90
    y: 226
    width: 65
    height: 65
    source: "qrc:/iso-icons/iso_grs_7000_4_0004.dat"
}

Runtime Functionality

On runtime, you can change the position of SafePicture on the layout. From Qt Safe Renderer 1.2 onwards, you can change the color of SafePicture on runtime. The color is changed by using an event provided by SafeRenderer::QSafeEventSetColor.

SafeText QML Type

With the SafeText QML Type, you can add safety-critical texts to your UI. Qt Safe Renderer utilizes the Qt Prerendered Fonts (QPF2) in the safe texts. The texts in the QML source code can be internationalized just like any other Qt Quick code. For more information, see Internationalization and Localization with Qt Quick.

You can add the text in the Properties window. The SafeText properties are visible in the window after you have highlighted the SafeText type in the navigator or on the canvas.

Add the text in SafeText as follows:

  1. Select SafeText on the canvas or in the navigator.
  2. In SafeText properties window, type the text into Text.

The default color of the text is black. If the background color in your view is black, remember to change the text color for SafeText:

  1. Right-click SafeText on the canvas or in the navigator.
  2. Select Edit Color in the context menu or open Properties.
  3. Select color.
  4. In Properties, edit fillColor. Setting the fillColor is mandotory, if you are using output verification.

An example source code for SafeText:

SafeText {
    id: safeText
    x: 80
    y: 80
    width: 129
    height: 65
    text: "text"
}

Dynamic SafeText

With the dynamic SafeText, you can change the text in the SafeText QML type on runtime. The dynamic SafeText is availabe from Qt Safe Renderer 1.1 onwards. You can enable the dynamic SafeText as follows:

  1. Select SafeText on the canvas or in the navigator.
  2. In SafeText properties window, enable Dynamic.

In the generated QML source code, the runtimeEditable property is set to true.

When you build a Qt Quick project that contains dynamic SafeText types, a .qpf2 file is generated for each font type that you use in dynamic SafeText QML types. If the runtimeEditable property is left to its default value false, an .srb file is generated. For more information about the generated files, see Generating Safe Layout Data.

Note: Internationalization and localization are not supported in the dynamic text.

Runtime Functionality

On runtime, you can change the position of SafeText on the layout. From Qt Safe Renderer 1.1 onwards, you can also change the text and color on runtime.

For more information about changing the text, see Dynamic SafeText.

You can change the color on runtime by using an event provided by SafeRenderer::QSafeEventSetColor.

Localizing Safety-Critical Elements

You can use localized bitmaps and static texts in safety-critical QML types.

Add localized bitmaps to your project via Qt resource file (.qsr) as follows:

<RCC>
<qresource prefix="/" lang="fi">
    <file alias="flag.png">flags/fi.png</file>
</qresource>
<qresource prefix="/" lang="en">
    <file alias="flag.png">flags/gb.png</file>
</qresource>
</RCC>

See Resource Compiler (rcc) for more information about resource compiler in Qt.

Use qsTr function for marking texts for translation as follows:

SafeText {
    id: textItem
    objectName: "textItem"
    height: 84
    width: 384
    color: "black"
    verticalAlignment: Text.AlignVCenter
    font.pixelSize: 64
    fillColor: "white"
    text: qsTr("Hello world!")
}

Translations for different languages are provided in separate translation files (.ts). For more information, see Internationalization and Localization with Qt Quick and Qt Linguist Manual.

See the following topics for more information about localization in Qt Safe Renderer:

  • Enabling Localization lists all variables required in the project file (.pro) for localization.
  • The Localization example demonstrates how to localize safety-critical UI content.

Previewing Qt Quick UI Form

Previewing via QML Scene

The created Qt Quick UI forms (.ui.qml) can be previewed with the QML Scene as follows:

  1. Open the Qt Quick UI form in Qt Quick Designer or Qt Creator's Edit mode.
  2. Select Tools > External > Qt Quick > Qt Quick 2 Preview (qmlscene).

QML Scene enables you to load QML documents for viewing and testing while you are developing an application.

If you have added SafePicture QML Types to your UI form by using ISO Icon Browser, generated code contains a qrc:/ prefix:

SafePicture {
    id: safePicture1
    x: 182
    y: 135
    source: "qrc:/iso-icons/iso_grs_7000_4_0001.dat"
}

QML Scene does not render the icon if the prefix is in the QML code. You need to remove it manually before using QML Scene:

source: "iso-icons/iso_grs_7000_4_0001.dat"

Running the Project

You can preview the UI forms on your host environment by running the project. To run the project, select Build > Run.

If you have added your safety-critical elements to Qt Quick UI forms in the Qt Quick Application - Stack project, you should be able to run the project without enabling the Qt Safe Renderer tools. For more information about the tools and required project file modifications, see Enabling Qt Safe Renderer in Project.

Constraints

The Qt Safe Renderer QML types have the following constraints:

  • There is no localization support for the dynamic SafeText.
  • The Qt Safe Renderer QML types cannot be used in the views defined by Qt Quick View QML types.
  • The supported positioners are a column, a row, anchors, and an absolute x-coordinate and y-coordinate.
  • The objectName and the id must be equal. Otherwise an unhandled exception is thrown.

In general, the Qt Safe Renderer QML types should not be mixed with regular Qt Quick QML types, such as MouseArea. Especially, Qt Safe Renderer does not support the following features and types in the Qt Quick UI form files:

Unsupported Feature
JavaScript blocks
Function definitions
Function calls (except qsTr())
Other bindings than pure expressions
Signal handlers
States in other items than the root item
Root items that are not derived from QQuickItem or Item
Unsupported Type
Behavior
Binding
Canvas
Component
Shader effect
Timer
Transform

Available under certain Qt licenses.
Find out more.