Description

On some hardware, the device's display orientation is different than the UI orientation, for example, when using a landscape UI on a portrait display panel. Qt Quick Ultralite enables rotating the entire application's content by a chosen multiple of 90 degrees to handle such scenarios. The application project's MCU.Config.displayRotationAngle property can for example be set to 90 to enable designing and implementing the UI in landscape orientation, but rendering it on the portrait display as if the display actually had a landscape orientation. The final effect is illustrated below:

A landscape UI on a portrait display with 90 degrees static screen rotation

Usage

The display rotation is configurable using the MCU.Config.displayRotationAngle and MCU.Config.showDesktopPreviewInNaturalDisplayOrientation QmlProject properties. The following example configuration demonstrates how to use them:

MCU.Config {
    displayRotationAngle: 90
    showDesktopPreviewInNaturalDisplayOrientation: false
}

The rotation behavior is different depending on whether the application is run on the target hardware or on desktop. By default, the application UI is loaded without rotation on the desktop platform, but you can override this behavior by setting MCU.Config.showDesktopPreviewInNaturalDisplayOrientation to false.

Handling custom drawing in PaintedItem

When rotation is enabled, the application operates on a transformed coordinate system (virtual coordinate system) when compared to the physical screen (physical coordinate system) on the device. You should consider this difference in your custom PaintedItem implementation.

Your custom implementation of the PaintedItemDelegate::paint() method should handle the transform argument, to apply the necessary transform.

Qt Quick Ultralite painteditem Example demonstrates how you can handle screen rotation from a custom painted item.

Performance implications

When a display rotation angle of 90, 180, or 270 is used, the resource compiler pre-rotates the image resources specified in the application's qmlproject file. That way, they can be blended without rotation at runtime, avoiding a costly performance overhead.

All the glyph alpha maps for the text are rotated at runtime when blended. This rotation might have significant performance impact depending on platform. You can use the text cache feature to enable drawing text without rotation as long as the corresponding text cache entry doesn't have to be re-generated. The text cache entries are only re-generated if the text changes or the text cache is too small so the cached entries must be removed to make space for new ones.

StaticText items do not use the text cache, so it might be preferrable to use the Text item instead when display rotation is enabled.