It seems like the browser you are using has JavaScript disabled. As a result, the site will not function properly. We really want you to enable it so you may experience our site as we intended it. If you have no idea what we are talking about or if you need help, visit http://www.enable-javascript.com×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

Oops, it seems like you're using an old browser that we do not fully support. If you're able to, please upgrade your browser here.×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

Design units in 10.3

With the release of API level 10.3 for the BlackBerry 10 Native SDK, we've introduced some new features to help make it easier to design and build your apps. In this article, we take a look at design units, a new concept that's been added to Cascades to give you more flexibility than ever.

Design units let you create adaptable UIs more easily. Along with other features such as relative layouts, space quotas, and asset selection, design units help you create UIs that look good and scale well on a variety of BlackBerry 10 devices.

A design unit is a unit of measurement that's independent of any particular device or screen resolution. A single design unit corresponds to a different number of pixels depending on the device that the app runs on. For example, on a BlackBerry Z30 smartphone, one design unit corresponds to 8 pixels. On a BlackBerry Z10 smartphone, one design unit corresponds to 10 pixels. These mappings help make sure that your UI maintains proper spacing and scaling when your app is run on devices with different screen densities.

In our documentation, you might sometimes see design units abbreviated as "du".

Cascades automatically converts design units into pixel values that are optimal for the device that the app runs on. Here's a table that describes how design units translate to pixel values for each device.

Device

Pixels per design unit

Width (du)

Height (du)

BlackBerry Z30 and BlackBerry Z3

8

90

160

BlackBerry Q10 and BlackBerry Q5

9

80

80

BlackBerry Z10

10

76.8

128

BlackBerry Passport

12

120

120

You can use design units to specify dimensions in your UI, such as the length and width of a control, the amount of space for a margin, and so on. You can check out QML Properties for more information about specifying dimensions and other properties. There are several conversion functions for design units that are available through the UIObject::ui property. The UIConfig object that this property returns contains three different conversion methods:

Converts a pixel value into an equivalent pixel value. This function doesn't
change the pixel amount; it's a way to explicitly show that a dimension is
measured in pixels. Generally, you should always try to use design units or
snapped design units instead.

Here's how to create a simple UI using design units for padding and margin values instead of pixels:

Why use design units?

If you're already using pixel values in your apps and you're comfortable working with them, it might seem like a lot of work to switch to design units instead. There's really one main reason to use design units: an app that uses design units is able to retain its relative dimensions regardless of the screen density of the device that it runs on.

Consider the following scenario: you've designed your app UI with only earlier BlackBerry 10 devices in mind (BlackBerry Z10, BlackBerry Z30, BlackBerry Q10, and so on). Although these devices have different screen sizes, shapes, and resolutions, they all have a similar screen density that ranges from 295 dpi to 356 dpi. Because the screen densities are so similar, you can specify dimensions using real pixel amounts and still create a single UI that works well for all devices (if you follow other guidelines for resolution independence such as using relative layouts and space quotas). However, if you run the app on a device that has a much higher screen density, the pixel dimensions don't retain their relative size.

To learn more about design units, as well as other techniques to help you create adaptable UIs, take a look at Resolution independence in the Best Practices section of the documentation.

1. Download the tools

Before you start developing, you'll need to visit the Downloads tab. Here you'll find downloads for the BlackBerry 10 Native SDK, BlackBerry 10 Device Simulator, and some other useful tools.

2. Try the sample apps

Now featuring a filter control, the Sample apps tab allows you to search for samples by name or by feature.

Select either the Core or Cascades radio buttons to display the samples relevant to you.

3. Educate yourself

The Documentation tab contains tons of examples, tutorials, and best practices to guide you along the path towards building an awesome app.

You can access all the documentation that you need in the left-hand navigation.

4. Start developing

The Reference tab is where you'll find essential details about how to use our APIs.

You can use the left-hand navigation to choose how you would like to browse the reference: by module, by topic, or alphabetically. If you have an idea of what you are looking for, start typing it in the Filter box.