Building the UI

Building a great UI involves more than just adding controls to a screen - it's about creating a fluid and intuitive experience throughout the entire app. Users like what they're familiar with, so give them an app that really feels like it's BlackBerry 10. Not sure what really makes up the BlackBerry 10 experience? Have a look at the Key principles of design in the UI Guidelines.

Application structure

The first step of building your UI is deciding what structure makes the most sense for your app. For inspiration, see the UI guidelines for Application structure. The guidelines contain lots of use cases and examples for the different types of structures that you can use in your app. For details about implementation, see the Navigation documentation.

The most basic structure that you can have is a single screen. Larger apps need to use a tab navigation, drill-down navigation, or a combination of the two.


In Cascades, a screen is represented by the Page component. A page can have a titlebar, actions (displayed on the action bar), and content.

A page that displays a title bar, content, and an action bar.

Title bar

The TitleBar comes in three different flavors specified by the TitleBarKind enum. The most basic is the default title bar, which supports title text and actions for accepting or dismissing an option.

The default title bar.

The segmented title bar supports a segmented control and is useful for filtering or changing content is that is displayed on the page.

A segmented title bar.

The third option is the free-form title bar which represents an expandable title bar that can contain any controls that you want.

An expandable title bar.

And the fourth option is the text field title bar which contains a text field that can accept text from the user.

A title bar with a text field.


Actions can be displayed on a screen in a few different ways. The default is to display actions in the action menu, which is accessible by tapping a button on the right side of the action bar.

You can also force actions to be displayed directly on the action bar. Here's an example of a screen that has three actions, with only one of the actions being displayed on the bar.

A Cascades app showing the action menu.


The content for a screen can be any component that inherits from Control. Typically, this would be a root container that you would use to lay out the rest of the UI for the page.

You can read more about the types of components that you can use in Screen layout and components.

Tab navigation

Most apps are going to be larger than a single screen, in which case you need to consider how you want to organize additional screens. One option is to use TabbedPane to create a tab navigation. When the user taps a tab, the Page for that tab is displayed. Like actions, tabs can be displayed in a few different ways. The default is to display tabs at the bottom of the screen, but this behavior depends on whether actions are there as well.

Tabs displayed on the action bar.

If you don't want your tabs displayed on the action bar (or, if there isn't room), tabs can also be accessed from a tab menu at the left side of the action bar.

Tabs being displayed in the tab menu.

Drill-down navigation

The second option for structuring pages in an app is to create a drill-down navigation using NavigationPane. In a drill-down navigation, pages are organized in a stack hierarchy. When a new screen is pushed onto the stack, the previous page is hidden behind it.

A diagram showing how screens are pushed and popped on the stack.

By default, each screen that gets pushed onto the stack includes a back button at the left side of the action bar. When the user taps the button, the screen gets popped off the stack, revealing the previous screen.

The back button used with the navigation pane.


In the previous sections, we've talked about two different types of menus. The action menu, which contains actions specific to a screen, and the tab menu, which lists the tabs in a TabbedPane. There are also two more types of menus that you can employ in your app: the context menu and the application menu.

The context menu contains actions that are specific to a particular control within a screen (for example, "Copy", "Select More", and "Share"). The user can access the context menu by touching and holding the control.

Screens showing how the user can open the context menu.

The application menu contains important actions that are independent of context (for example, "Settings", "Log Out", and "about"). The user can access the application menu by swiping down from the top of the screen.

Screens showing how the user can open the application menu.

Screen layout and components

After you come up with a suitable structure for your app, it's time to start thinking about how you want the content on your screen to appear. For inspiration, the UI Guidelines for Screen views have some good suggestions for how to present your content.

The first thing you should consider when it comes to designing your screens are the actual controls that you need to use.


Cascades comes with a wide selection of core controls, each of which has a specific purpose. To provide your users with a consistent and familiar experience, you should make sure you're using the right control for the job. Here are some of the common controls that Cascades features, and you can find a complete list in Controls and visual components.

Pickers and drop-downs

When the user needs to select from a list of options, pickers and drop-downs are the way to go. The Picker is most useful when the user needs to choose from 2-3 sets of interconnected values, while the DropDown is useful for single values.

A picker control.

A drop-down list.


When it comes to displaying large amounts of data, the ListView is the way to go. Whether it's text, images, or other controls, the ListView provides a ton of different options for presenting your stuff.

Examples of two different types of lists.

Selection controls

Cascades provides a few different controls that you can use for presenting your users with options.

A CheckBox is useful when the user can select multiple items.

A selected check box. A cleared check box.

A RadioGroup is preferred when the user can select one item from a list of mutually exclusive options.

An active radio button. An inactive radio button.

The ToggleButton should be used when the user can switch between two distinct states, like On and Off.

A toggle switch that's turned on. A toggle switch that's turned off


After you determine what controls you'll need to use, the next step is to figure out how to position everything on the screen. The Layout that you choose determines how controls are arranged within the container (for example, the StackLayout arranges controls in a stack). The layout properties that you specify on each control determine how they're positioned relative to their siblings.

Stack layouts

The StackLayout positions its children in a vertical or horizontal stack.

Buttons arranged in a stack layout.

Dock layouts

The DockLayout anchors its children to a particular area of the screen (for example, upper-right, center-left, and bottom-center).

Buttons arranged in a dock layout.

Absolute layouts

The AbsoluteLayout allows you to specify exactly where controls should be on the screen. This layout is not recommended for most UIs.

Buttons arranged using an absolute layout.


The padding for a Container determines how much empty space there should be between the edge of the container and its children.

The image on the left doesn't use any padding. The controls are flush against the side of the screen. The image on the right uses padding on the top and the left sides of the container, creating some space between the edges of the container and the controls.

Two screens containing buttons, one that uses padding and one that does not.


Margins are similar to padding, except that they specify how much empty space there is between siblings within the container, rather than the parent container.

In the image below, controls 1 and 2 have a small margin between them while 2 and 3 have a much larger margin.

Buttons with margins in between them.

Designing for different screen sizes and orientation

Throughout the planning and development of your app, you should always be thinking about UI adaptability. You should ask yourself questions like, how will this look on a larger/smaller screen, does this screen make sense in both portrait and landscape, and what can I do with this layout to reduce rework later on?

Although it's not possible to predict how your app is going to look on every new device that's released, there are some steps that you can take to make things less painful later.

Resolution independence

When you're designing a UI, you should always consider how it looks on a larger or smaller screen size. If your UI looks cluttered on a device with a large screen, you probably need to do some work restructuring your app before you even try running on a device with a smaller screen. When it comes to writing the actual code, there are a couple strategies that you can use to make things easier for yourself.

Relative layouts

Whenever possible, use relative layouts like StackLayout and DockLayout to position the controls in your UI. Since AbsoluteLayout relies on providing specific pixel coordinates for controls, you would have to create a UI for each screen resolution that you target.

Here's an example of a UI developed for a large screen. The screen has a text control at the top and bottom. Depending on the type of layout that you create this with, it might not work well on a smaller screen.

An example UI with controls at the top and bottom of the screen.

Here's how the same code would look on a smaller screen, if you used an AbsoluteLayout to position the controls.

The control at the bottom of the screen gets cut off altogether, because the AbsoluteLayout requires specific pixel coordinates and those coordinates would appear off screen on the smaller device.

The incorrect version of the layout.

Here's how the same code would look on a smaller screen, if you used a DockLayout to position the controls.

The control at the bottom of the screen does not get cut off, because the DockLayout allows you to dock children to a specific part of the screen.

The correct version of the layout.

Adaptive assets

If your app uses images or graphics, there's a bit of additional work involved with creating an adaptable UI.

For graphics that you want to be able to scale, you can nine-slice scale the images so they don't become stretched or skewed when they're scaled. For graphics that you absolutely cannot scale, you should use the static asset selector so that the app chooses the correct image based on the resolution of the device.


Not every UI should be available in both portrait and landscape views. For some apps, such as those that display large lists, the portrait view is preferred. For other apps, such as those that display pictures or videos, you probably want the ability to switch back and forth between views.

Here's an example where supporting both portrait and landscape doesn't quite work. The landscape view lists fewer items than the portrait view, while providing no additional value.

An example of a list that should not be available in landscape view.

Here's an example where you might want to support both orientations. By supporting landscape, the user can view the image at a larger size.

An example of an image that works well in landscape view.

What's next?

Now that you know how to design and build your UI, it's time to learn about Providing an integrated experience for your users.

Last modified: 2015-03-31

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

comments powered by Disqus