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.
Screens
In Cascades, a screen is represented by the Page component. A page can have a titlebar, actions (displayed on the action bar), and content.

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 segmented title bar supports a segmented control and is useful for filtering or changing content is that is displayed on the page.
The third option is the free-form title bar which represents an expandable title bar that can contain any controls that you want.
And the fourth option is the text field title bar which contains a text field that can accept text from the user.
Actions
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.
Content
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.

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.

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.

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.

Menus
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.

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.

Related docs
Design guidelines
Sample apps
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.
Controls
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
Lists
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.

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 RadioGroup is preferred when the user can select one item from a list of mutually exclusive options.
The ToggleButton should be used when the user can switch between two distinct states, like On and Off.
Layouts
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.

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

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

Padding
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.

Margins
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.

Related docs
Design guidelines
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.

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.

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.

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.
Orientation
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.

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.

Related docs
Design guidelines
Sample apps
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