Using the static asset selector 
To adapt your UIs to different screen resolutions, you can take advantage of Cascades features such as relative layouts, margins, and nine-slice scaling, which work well in many cases. However, there are times when you might need to create and use different project assets that are designed specifically for one resolution or another. For example, you might have background images that don't scale very well automatically and can't be resized using nine-slice scaling. Or, you might need an entirely new layout, with different UI controls, to create the best possible user experience in a different resolution.
It's not just different resolutions that you need to consider. You should also consider the visual style (or theme) that your app and target device use. By default, devices with an LCD screen (such as the BlackBerry Z10 smartphone) use a bright theme, and devices with an OLED screen (such as the BlackBerry Q10 smartphone) use a dark theme. Each theme uses a different color scheme for core controls and other elements in an app. Here's an example of an app that's run using both the bright theme and the dark theme:
Similar to resolution-specific assets, you might have assets (such as icons or nine-slice scaled images) that are designed for one of these themes, but that don't work very well with the other theme. Consider the two assets in the image to the right. The first asset would probably work for both bright and dark themes. The second asset might look great using a bright theme, but it probably wouldn't be appropriate for a dark-themed app.
To help you customize your app for different resolutions and themes, Cascades includes a static asset selector. This feature lets you use different sets of assets in your apps, depending on the resolution or theme of the device that your app is running on. You don't need to rebuild or repackage your app to select the right assets, either; Cascades automatically selects the best set of assets for a particular device at runtime.
Because you can use the static asset selector to pick assets based on either resolution or theme, it can be helpful to understand what types of assets should be used in each case. Consider the following examples of asset types that you might want to use with each selector:
Selector type
Use for...
The static asset selector is built into the QNX Momentics IDE. It uses the folder structure of your project's assets folder to determine which set of assets to use for a particular set of device characteristics. The asset selector supports two types of assets: images and .qml files. Image assets need to be in one of the formats that Cascades supports, such as PNG or JPG. To learn more about images and using them as assets in your projects, see Images.
Selecting assets based on resolution
To take advantage of the static asset selector for different resolutions, you must place your assets in specific folders in your project. These folders need to have the same name as the screen resolution that they're associated with. For example, consider a device with a resolution of 720 x 720. To use assets that are specifically designed for this resolution, you should place the assets in an assets/720x720 folder. Similarly, for a device with a resolution of 720 x 1280, place your assets in an assets/720x1280 folder.
The width and height order in this folder-naming scheme is important. You need to list the screen dimensions that a device uses in its default orientation. For example, for smartphones (such as the BlackBerry Z10 smartphone), the default orientation is portrait and the screen width is listed first, followed by the screen height. Using this convention, a folder named 720x1280 works with the static asset selector, but a folder named 1280x720 does not. Note that the folder names are not case sensitive; folder names of "720x1280" and "720X1280" are equivalent.
Any assets that aren't located in a resolution folder (in other words, assets that are located at the root of the assets folder) are used as default assets for your app. The asset selector uses these default assets only if assets with the same name aren't found in another resolution folder, or in a theme folder (as discussed in the Selecting assets based on theme section below).
To illustrate the folder structure that's required, consider the example that's shown in the image on the right. The assets folder contains two resolution folders, 720x720 and 768x1280. These subfolders include assets that correspond to each resolution that the app supports. The assets folder also contains a single image asset, dev_icon.png, at its root.
As a developer using this folder structure, you don't need to know which specific device the app will run on. You only need to be aware that the app might be used on devices with different resolutions, and you should take that into account as you create your assets.
Consider what happens when an app with this folder structure is run on different devices:
- If the app is run on a device with a resolution of 720x720, the assets in the 720x720 folder are selected and used in the app.
- If the app is run on a device with a resolution of 768x1280, the assets in the 768x1280 folder are selected.
- The asset that's located at the root of the assets folder, dev_icon.png, is a default asset and is always used, regardless of the device resolution.
It's important to note that the other QML files and C++ files in your app don't need to change to accommodate this folder structure. When the app runs, Cascades selects the appropriate assets automatically and loads them for other files in the app to use.
Selecting assets based on theme
To let Cascades select assets based on the theme that a device uses, you use a folder structure that's similar to the one that you use for the resolution selector. Each folder needs to have the same name as the theme that it's associated with and should contain assets that are designed specifically for that theme. The two themes that are supported currently are VisualStyle.bright and VisualStyle.dark. For example, for a device that uses the dark theme, place your assets in an assets/VisualStyle.dark folder.
As with the resolution selector, the folders that you use for the theme selector aren't case sensitive; folder names of "VisualStyle.dark" and "VisualStyle.Dark" are equivalent.
To illustrate the folder structure that's required, consider the example that's shown in the image on the right. The assets folder contains two theme folders, VisualStyle.bright and VisualStyle.dark. These subfolders include assets that correspond to each theme that the app supports. The assets folder also contains a single image asset, dev_icon.png, at its root.
Similar to using the resolution selector, you don't need to know which specific device your app will run on. Just remember that your app might be run on devices with different default themes, so you need to consider this possibility when you design your assets.
Consider what happens when an app with this folder structure is run on different devices:
- If the app is run on a device that uses an LCD screen (which, by default, uses a bright theme), the assets in the VisualStyle.bright folder are selected and used in the app.
- If the app is run on a device that uses an OLED screen (which, by default, uses a dark theme), the assets in the VisualStyle.dark folder are selected.
- The asset that's located at the root of the assets folder, dev_icon.png, is a default asset and is always used, regardless of the device theme.
Selecting assets based on both resolution and theme
You can combine the resolution selector and theme selector in the same Cascades project. Simply create folders for each resolution and theme that you want to support, and nest these folders within the assets folder of your project. By using this approach, you can create separate sets of assets for each resolution-theme combination that your app supports.
For example, consider the folder structure that's shown in the image to the right. The assets folder contains two resolution folders, corresponding to a device with a physical keyboard (720x720) and the BlackBerry Z10 smartphone (768x1280). Each resolution folder contains its own main.qml file, which contains the UI of the app, optimized for each resolution. Within the 720x720 folder, there are folders that correspond to both the bright theme and dark theme.
Here's what happens when an app with this folder structure is run on different devices:
- If the app is run on a device with a physical keyboard, the assets in the 720x720 folder are selected and used in the app. Depending on the theme that the device uses, assets in either the 720x720/VisualStyle.bright folder or the 720x720/VisualStyle.dark folder are used as well.
- If the app is run on a BlackBerry Z10 smartphone, the assets in the 768x1280 folder are selected.
- The asset that's located at the root of the assets folder, dev_icon.png, is a default asset and is always used, regardless of the device theme.
Default assets and selector priority
If you place your assets at the root of the assets folder, they're considered default assets. These assets are used if no other assets with the same names are found in a resolution-specific or theme-specific folder.
To make sure that a set of assets is always selected, and to support additional device resolutions that might be added in the future, it's a good idea to always place a set of assets in the root assets folder. By using this convention, if your app is run on a device with an unexpected resolution (that is, a resolution that you didn't anticipate and create a resolution folder for), a default set of assets is still selected and used.
For example, you might decide to create your assets with a default resolution of 768 x 1280 in mind. In that case, your assets folder structure would look similar to the image on the right.
Selector priority
The static asset selector picks assets that are considered the best match for the device that an app is currently running on. In general, this means that an asset that matches more valid selectors for a particular device will be chosen over an asset that matches fewer selectors.
For example, if an app's project includes both VisualStyle.dark and 720x720/VisualStyle.dark folders in its assets folder, and the app is run on a device with a physical keyboard using the default dark theme, then the assets in the 720x720/VisualStyle.dark folder are selected and used. The assets in this folder match both the resolution selector and theme selector for the device, whereas the assets in the VisualStyle.dark folder match only the theme selector.
The theme selector has a higher priority than the resolution selector. For example, if your assets folder contained both VisualStyle.dark and 720x720 folders, and your app is run on a BlackBerry Q10 smartphone (which matches both selectors), the assets in the VisualStyle.dark folder are selected and used.
User-defined folders
You can create and use your own folders within the assets folder of your project. You might want to define your own folders to store different types of assets (for example, icons, backgrounds, and other UI elements) that your app uses. You can use any folder structure that makes sense for the assets in your project.
When you define folders yourself, you can still take advantage of the resolution selector and theme selector. You just need to make sure that your user-defined folders are listed at the lowest level of the selector folder structure. By using this approach, Cascades can choose the top-level resolution and theme folders properly, based on the target device, and you can still reference the assets in your user-defined subfolders at the lower levels.
For example, take a look at the folder structure in the image to the right. This structure includes a resolution-specific folder for devices with a physical keyboard (720x720), as well as theme-specific subfolders (VisualStyle.bright and VisualStyle.dark). Within these selector folders, user-defined folders are included for background images and icons.
If an app with this folder structure is run on a device with a physical keyboard, the assets in the 720x720/VisualStyle.bright folder or 720x720/VisualStyle.dark folder are used, depending on the theme. If the app is run on any other device, the assets in the root of the assets folder are used.
No matter what device the app is run on, you can always reference the assets in the backgrounds and icons folders in the same way. For example, if the backgrounds folder contains an image called appBackground.png, you can reference this image by using asset://backgrounds/appBackground.png in your app. Cascades automatically selects one of the following versions of the asset, whichever is best for the target device:
- 720x720/VisualStyle.bright/backgrounds/appBackground.png
- 720x720/VisualStyle.dark/backgrounds/appBackground.png
- backgrounds/appBackground.png
To use the asset selectors with your own folders, the selector folders (such as 720x720 or VisualStyle.bright) must be at a higher level in the folder structure than your user-defined folders. So, if an asset is located in a folder called backgrounds/720x720/VisualStyle.bright, it isn't recognized and selected automatically by the asset selector. Instead, you'd need to reference this asset directly by using asset://backgrounds/720x720/VisualStyle.bright in your app. This approach isn't recommended; instead, try to use the selector folder structure wherever possible.
Last modified: 2013-03-21