Qt Reference Documentation



A scalable application is an application that can run on more than one form factor. In particular, it can cope with different screen sizes, DPI, and aspect ratios. You need to consider scalability when:

This document discusses how scalable applications can be created.

Developing Scalable UIs

This section shows the basics of how we advice scalable applications to be implemented using QML. We recommend that you follow these techniques:

Using small top-level layouts makes your codebase smaller and easier to maintain. Also, components that scales relative to their parent are more reusable. The layouts should be children of the application's root item. You can change between them by, for instance, using the opacity property of Item; that is, if your application has more tham one top-level layout. Such a top-level layout is also often referred to as a page, i.e., a layout that uses the entire screen. For instance, an organizer application will typically have separate pages for showing the calender and editing todo items.

You should define the measurements separate from the UI, for instance by using a JavaScript object that you fill in with a script on application start up.

QML provides several ways of laying out components, e.g, using anchor based layout, the more classic Grid; Column; and Row elements, and by setting the dimensions of Items directly. When laying out components in scalable applications, you should generally prefer using anchors and set width and height based on parent size where possible. Layouts are not only relevant to top-level layouts; components often contain child Items.

The following sections describe in more detail the different aspects of scalability that should be considered in order to achieve the desired level of flexibility within your application.

Implementing the Top-Level Layouts

As mentioned, each application should use separate top-level layout QML definitions to support separate layout configurations / form factors.

Consider an application that has to be deployed to at least two devices, which both have very different screen sizes and DPI values. The two form factors of the application will share many common components and attributes, and will most likely connect to the same data model.

Therefore, the top-level definitions should be quite straightforward and short, with the majority of the functionality refactored into contained Components. It is important to try to avoid unnecessary duplication between these top-level definitions, in order to improve maintainability.

There are some patterns that you might consider when designing your top level layouts:

The Loader component can be used to load separate QML files based on some criteria, such as Device Profile (configuration of screen pixel resolution and DPI density). In the case of form factor, this information will not change during the application's lifetime, therefore there is no issue with memory usage or performance.

Defining Measurements

When you are defining the measurements within an application or component layout, there are a number aspects to consider:

These aspects combine together to resolve the final layout for a given Device Profile. However, although there are dependencies between them, it is important to manage and control the different aspects separately.

It is strongly recommended that Layout measurements should be stored in a separate place from the component layout structure definition files. The reason for this is that layout structure, for a given form factor, can be re-used for different Device Profiles. However, measurements will almost always vary between Device Profiles or Device Categories.

If the opposite approach (complete duplication of entire QML files) was taken, then all of the layout states and structure definitions would be duplicated between the copied QML files, and only the measurement values would change.

The main benefit of using separate measurement definition files are:

Using QML's Layout Features

For a given form factor, top-level Layouts structure definitions, or component layout structure definitions, should in general be defined in a proportional way using a combination of

These basic building blocks, along with the powerful evaluation capabilities of JavaScript expressions within every QML binding, are designed to allow the majority of the layout structure definition to be defined in a Device Profile independent way.

There are some limitations of the basic grid type layouts. They are designed to accommodate a number of Items, but use the current sizes of those items. There is a similar issue with the basic anchor type layout. In particular, it can be difficult to spread a number of child items proportionately across an area of their container.

By combining the features of the layout managers with simple JavaScript expressions, a richer variety of designs can be expressed, without having to resort to additional layout measurement parameters or measurement values.

Here are some things not to do with layouts:

Orientation Switches

Application top-level page definitions, and reusable component definitions, should use one QML layout definition for the layout structure. This single definition should include the layout design for separate Device Orientations and Aspect Ratios. The reason for this is that performance during an orientation switch is critical, and it is therefore a good idea to ensure that all of the components needed by both orientations are loaded when the orientation changes.

On the contrary, you should perform thorough tests if you choose to use a Loader to load additional QML that is needed in separate orientations, as this will affect the performance of the orientation change.

In order to enable layout animations between the orientations, the anchor definitions must reside within the same containing component. Therefore the structure of a page or a component should consist of a common set of child components, a common set of anchor definitions, and a collection of states (defined in a StateGroup) representing the different aspect ratios supported by the component. (However note that orientation change animations are not possible on Symbian due to compatibility support for S60 applications).

If a component contained within a page needs to be hosted in numerous different form factor definitions, then the layout states of the view should depend on the aspect ratio of the page (its immediate container). Similarly, different instances of a component might be situated within numerous different containers in a UI, and so its layout states should be determined by the aspect ratio of its parent. The conclusion is that layout states should always follow the aspect ratio of the direct container (not the "orientation" of the current device screen).

Within each layout State, you should define the relationships between items using native QML layout definitions. See below for more information. During transitions between the states (triggered by the top level orientation change), in the case of anchor layouts, AnchorAnimation elements can be used to control the transitions. In some cases, you can also use a NumberAnimation on e.g. the width of an item. Remember to avoid complex JavaScript calculations during each frame of animation. Using simple anchor definitions and anchor animations can help with this in the majority of cases.

There are a few additional cases to consider: