Static asset selection

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 or Active Frames images that don't scale well 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 size of screen.

It's not only different screen sizes or densities 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 visual style 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 visual style and the dark visual style:


A comparison of the different visual styles.

For more information about the screen resolutions and display types of BlackBerry 10 devices, see Device characteristics.

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.

Icons designed for the light and dark themes.

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 for each device, either; Cascades automatically selects the best set of assets from the application .bar file 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...

Layout selector 10.3

Layout variations (for example, one layout for square screens and another layout for tall screens)

Theme selector

Images, icons, and custom controls that vary in style but not dimensions

Density selector 10.3

Images, icons, and custom controls designed for different screen densities

Resolution selector

Background images, Active Frames images, or absolute layouts designed for a particular resolution

In 10.3 and later it's recommended that you use layout and density selectors instead of resolution selectors.

The static asset selector is built into the 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 any type of asset, including images, .qml files, .js files, and even .xml files.

Selector priority

The static asset selector picks assets that are considered the best match for the device that an app is running on. In other words, an asset that matches more valid selectors for a particular device is 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 720x720 resolution 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, while 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.

The following list is a complete ranking of all the selector priorities:

  1. Number of selectors.
  2. Visual style (for example, VisualStyle.dark)
  3. Exact resolution (for example, 720x720)
  4. Screen density (for example, 12ppd) 10.3
  5. Minimum display width and height of the current orientation (for example, minw76h128du) 10.3
  6. Minimum display height of the current orientation (for example, minh128du) 10.3
  7. Minimum display width of the current orientation (for example, minw76du) 10.3
  8. Minimum display width and height of the default orientation (for example, mindw76h128du) 10.3
  9. Minimum display height of the default orientation (for example, mindh128du) 10.3
  10. Minimum display width of the default orientation (for example, mindw76du) 10.3

Asset selection based on layout 10.3

With the variety of devices available and their different shapes and dimensions, it's often necessary to have different UI layouts for different devices. The layout selector allows you to manage the different UIs that are currently available and still remain flexible for upcoming devices.

Here's an example of how you might want to support multiple layouts for different display sizes and orientations.

Screens showing different layout formations.

Unlike selection based on resolution, which requires that you create folders using the exact dimensions of a display, selection based on layout requires that you specify the minimum dimensions in design units. The benefit to specifying the minimum dimensions is that if new devices are released with larger displays, they're automatically supported without changes to your app.

Asset selection based on layout allows you to manage your layouts in a few different ways:

  • To maximize the reusability of your UI code, you can define a single layout that supports multiple devices with similar display shapes.
  • To use all of the screen space that's available, you can create different layouts for different display sizes.
  • You can also maintain different layouts for both portrait and landscape orientations.

Syntax

The syntax of the layout asset selector is as follows:

mindw000h000du

  • min is a static string indicating that the dimensions for the layout folder are the minimum that are supported.
  • d is an optional value that indicates whether you want layout selection to occur based on the dimensions of the default orientation of the device. When you omit this value, the app instead selects assets based on the dimensions of the initial orientation when the app starts. If the app starts in an orientation that you don't account for using asset folders, the scene must be reloaded before the application can load the correct assets.
  • w is a value that indicates the minimum width of the display in design units.
  • h is a value that indicates the minimum height of the display in design units.

Using the layout selector

Using the syntax described above, here's how to create a layout folder that is targeted toward devices with default orientation that's larger than 76 x 128 design units.

assets


 └─ mindw76h128du

When you run the application on a device, the asset selector does the following:

  • Automatically loads assets from the root of the assets folder
  • Checks the size of the device and determines whether there are suitable layout folders present (suitable folders have dimensions that are smaller than or equal to the dimensions of the device)
  • Chooses the folder with the largest dimensions, if more than one suitable folder is present
In the example above, only the BlackBerry Z30 and BlackBerry Z10 smartphones use the assets in the layout folder. Devices such as the BlackBerry Q10 and BlackBerry Q5 smartphones use only the assets from the root of the assets folder.

When you define a single layout to use on multiple devices, it's important that you update your UI code to use design units instead of pixel values for all dimensions. If you don't use design units, your layouts might not scale correctly on some devices.

Layouts for display shape

One way to reduce the amount of UI code that you have to write is to use a single layout for devices that have the same or similar relative dimensions. For example, you might want to use one layout for the taller displays of full touch screen devices and another layout for smaller devices with proportional dimensions.

assets


  ├─ mindw80h80du (BlackBerry Q10, BlackBerry Q5)


  └─ mindw76h128du (BlackBerry Z10, BlackBerry Z30)

The benefit to this technique is that you maintain only two basic types of layouts for your app. However, this technique doesn't take into account future devices with significantly larger displays.

For apps that are designed to fill the taller display of full touch screen devices, an easy way to change these apps for smaller displays that have proportional dimensions is to add a ScrollView to the mindw80h80du layout. To view an example of how to implement a ScrollView using the asset selector, see the starshipsettings app.

Layouts for display size

Although it's important to reduce the amount of code that you write, for devices with larger displays, you might want to customize your layouts to use all of the extra screen space that's available. Consider the example from the previous section.

assets


  ├─ mindw80h80du (BlackBerry Q10 and BlackBerry Q5)


  └─ mindw76h128du (BlackBerry Z10, BlackBerry Z30)

If this application is run on a future device that is 120 x 120 design units in size, the asset selector chooses the assets from the mindw80h80du folder. Technically, this layout still works on the new device because these devices all have the same relative dimensions. However, in terms of usability, the layout fails to take advantage of all of the extra space that's available on the larger screen. In this case, you might want to create a layout just for the larger device.

assets


  ├─ mindw80h80du (BlackBerry Q10, BlackBerry Q5)


  └─ mindw120h120du (Future device)


  └─ mindw76h128du (BlackBerry Z10, BlackBerry Z30)

Layouts for different orientations

If your application has different layouts for landscape and portrait, you can also define those layouts using layout selectors. Consider the example from the previous section.

assets


  ├─ mindw80h80du (BlackBerry Q10 and BlackBerry Q5)


  └─ mindw120h120du (Future device)


  └─ mindw76h128du (BlackBerry Z10, BlackBerry Z30)

In this example, you might want to provide both landscape and portrait layouts for the BlackBerry Z30 and BlackBerry Z10 smartphones. With all of the other devices having proportional dimensions, there's no need to provide separate layouts for those devices.

assets


  ├─ mindw80h80du (BlackBerry Q10,BlackBerry Q5)


  └─ mindw120h120du (Future device)


  └─ minw76h128du (BlackBerry Z10, BlackBerry Z30 portrait)


  └─ minw128h76du (BlackBerry Z10, BlackBerry Z30 landscape)

When the user changes the orientation of the device, the asset selector doesn't automatically load the assets for the new orientation. To update the assets, you must listen for changes to the orientation and reload the scene. For more information, see Orientation.

Asset selection based on visual style

To let the OS 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 layout 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 .qml file at its root, main.qml, which is used for both themes.

Screen showing the static asset selector with themes.

Similar to using the resolution selector, you don't need to know which specific device your app will run on. 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 .qml file at the root of the assets folder, main.qml, is a default asset and is always used, regardless of the device theme.

10.3 If you change the visual style at runtime, the app doesn't load the assets for that theme automatically. To load the correct assets, the app must reload the scene first.

Asset selection based on screen density

With the variety of devices available and their different screen densities, you might want to provide different sizes of images for different devices, instead of letting the framework scale your images for you.

To provide different images for different devices, you can add the images to assets folders that specify the target device's pixel per design unit value (pdd). The greater the number, the greater the pixel density of the device. To see a complete list of devices and their ppd values, see Design units. Here's an example that shows how to provide different images for each screen density.

assets


  ├─ 12ppd (Future device)  


  ├─ 10ppd (BlackBerry Z10)  


  ├─ 9ppd (BlackBerry Q10, BlackBerry Q5)


  └─ 8ppd (BlackBerry Z30)

If you don't provide a folder for a particular screen density, the framework chooses the best fit and scales the images automatically. This technique works well if you don't require pixel-perfect scaling of your images. For example, here's how you can use one high-resolution image for all types of devices.

assets


  └─ 16ppd (All devices)

If your app also has different images for bright and dark visual styles, you can use the theme selector in conjunction with the density selector. In this case, both folders contain a high-resolution image that the app can scale down for any screen density. Because the visual style selector has higher priority, devices that run a dark visual style choose that folder over the density folder.

assets


  └─ 16ppd (All bright-themed devices)


  └─ VisualStyle.dark (All dark-themed devices)

If your assets are customized for multiple screen densities and visual styles, you can nest the visual style folders within the density folders.

assets


  ├─ 12ppd (Future device)  


  ├─ 10ppd (BlackBerry Z10)  


  ├─ 9ppd


  |    ├─ VisualStyle.bright (BlackBerry Q5)


  |    └─ VisualStyle.dark (BlackBerry Q10)


  └─ 8ppd (BlackBerry Z30)

Asset selection based on resolution

When you use asset selection based on resolution, it's a good idea to always place a set of assets in the root assets folder. Placing a set of assets at the root of the asset folder ensures that a set of assets is always selected, and helps supports additional device resolutions that might be added in the future. 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.

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 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 768x1280 works with the static asset selector, but a folder named 1280x768 does not. The folder names are not case-sensitive; folder names of "768x1280" and "768X1280" are equivalent.

Assets that aren't located in a resolution folder (in other words, assets that are 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 a resolution folder or theme folder that corresponds to the resolution/theme that the app is running on (as discussed in Asset selection based on visual style).

To illustrate the folder structure that's required, consider the example that's shown in the image on the right. The assets folder contains three resolution folders, 720x1280, 720x720, and 768x1280. These subfolders include assets that correspond to each resolution that the app supports. The assets folder also contains a single .qml file at its root, main.qml, which is the .qml file that's used for all resolutions.

As a developer using this folder structure, you don't need to know which specific device the app runs 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.

Screen showing a folder structure that's compatible with the static asset selector.

Consider what happens when an app with this folder structure is run on different devices:

  • When the app is run on a device with a resolution of 720x1280, the assets in the 720x1280 folder are selected.
  • When the app is run on a device with a resolution of 720x720, the assets in the 720x720 folder are selected.
  • When the app is run on a device with a resolution of 768x1280, the assets in the 768x1280 folder are selected.
  • The .qml file that's located at the root of the assets folder, main.qml, is a default asset and is always used, regardless of the device resolution.

It's important to note that the other assets 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. You always use the same asset:/// prefix in code to load assets, regardless of which resolution subfolder the asset is in.

Asset selection based on both resolution and visual style

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 technique, 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 three resolution folders, corresponding to the BlackBerry Z30 smartphone (720x1280), a device with a physical keyboard (720x720), and the BlackBerry Z10 smartphone (768x1280).

Screen showing an example of the static asset selector, with themes and resolutions.

Within the 720x720 folder, there are folders that correspond to both the bright theme and dark theme, to support both the BlackBerry Q10 and BlackBerry Q5 smartphones. Each of the theme folders and the resolution folders for 720x1280 and 768x1280 contain its own custom background image, which is optimized for each device's resolution and theme.

The 720x720 folder also contains a main.qml at its root. This .qml file defines a layout that's designed specifically for the smaller screen. The root of the assets folder also contains a main.qml, which defines a default layout that's used for the devices with larger screens.

Here's what happens when an app with this folder structure is run on different devices:

  • If the app is run on a BlackBerry Q10 or BlackBerry Q5 smartphone, 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.
  • If the app is run on a BlackBerry Z30 smartphone, the assets in the 720x1280 folder are selected.
  • The .qml file that's at the root of the assets folder, main.qml, is a default asset and is used for both the BlackBerry Z10 and BlackBerry Z30 smartphones.

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 need to make sure that your user-defined folders are listed at the lowest level of the selector folder structure. By using this technique, Cascades can choose the top-level resolution and theme folders correctly, based on the target device, and you can still reference the assets in your user-defined subfolders at the lower levels.

For example, 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 720x720 resolution, 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.

Screen showing the static asset selector with user-defined folders.

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 assets/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 in a folder called backgrounds/720x720/VisualStyle.bright, the asset selector doesn't recognize it automatically. Instead, you'd need to reference this asset directly by using asset:///backgrounds/720x720/VisualStyle.bright in your app. This technique isn't recommended; instead, try to use the selector folder structure wherever possible.

Last modified: 2014-10-01



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus