Themes

When you create a Cascades app, most of the UI controls that you use have a predefined look and feel. Visual elements, such as font color, background color, and shading, are already set for these controls, so you don't have to worry about setting them manually. Cascades controls are designed to be visually consistent so that your UIs maintain a consistent appearance that's attractive and user-friendly.

The specific look and feel of UI controls depends on the theme that's set for your app. A theme represents a set of visual attributes that apply to all of the Cascades controls that you use in your app. For example, consider the Button that's pictured to the right. The background color, text color, and border of the button all depend on the theme that the app uses. Similarly, the default background color of a Container also depends on the app's theme, and other controls have visual attributes that are controlled by the theme.

Screen shot showing a button in Cascades.

Currently, there are two themes that you can use in your apps: a bright theme and a dark theme. Depending on the device that your app runs on, either the bright theme or dark theme is applied to your UI controls. If your app is run on a device with an LCD screen (such as the BlackBerry Z10 smartphone), the bright theme is used by default. If your app is run on a device with an OLED screen (such as the BlackBerry Q10 smartphone), the dark theme is used by default. To learn more about how to design your apps for OLED screens, see Designing for OLED displays in the UI Guidelines for BlackBerry 10.


Cascades device comparison themes

Setting the theme for your app

You aren't able to change the theme that your app uses while the app is running. If you want to force your app to use a particular theme no matter what device it's run on, you can specify the theme in the bar-descriptor.xml file of your project in the Momentics IDE. This file is included automatically when you create a new project, and it contains general settings that apply to your entire app, such as permissions, build configurations, and author information.

Screen shot showing the bar-descriptor.xml file in a project.

You can add an environment variable definition that forces your app to use the theme that you specify. The environment variable is called CASCADES_THEME and you can set it to either bright or dark. Here's the line of code that you'd need to add on the Source tab in the bar-descriptor.xml editor to force your app to use a dark theme:

<env var="CASCADES_THEME" value="dark"/>

In general, you shouldn't force your apps to use a bright theme. Instead, either create assets that appear properly using both themes, or create separate assets for each theme and use the static asset selector (discussed below) to select the correct set when your app runs.

Because you might not know which device your app is running on (and thus, which theme your app is using), you should design your app's assets to work with either a bright or dark theme. For example, if you use custom icons or other images, you should make sure that they appear correctly in both themes. To learn more about developing apps for different BlackBerry 10 devices, see Device characteristics.

To help you manage your bright and dark assets, Cascades includes a static asset selector that determines the theme that's running on your target device and automatically selects the right set of assets. This selector lets you specify theme-based assets, as well as resolution-based assets. To learn more about selecting assets based on theme, see Static asset selection.

Retrieving theme information

Cascades provides several classes that work together to let you retrieve theme information in your apps. The following sections describe these classes and how they're related, and also provide a short C++ code sample that demonstrates how to use each class. A QML code sample is provided below in the Retrieving theme information in QML section.

ThemeSupport

The ThemeSupport class lets you query, at runtime, which theme your app is currently using. You can call Application::themeSupport() to retrieve a ThemeSupport object, and then you can call ThemeSupport::theme() to determine the current theme (represented by a Theme object).

ThemeSupport *themeSupport = Application::instance()
                                          ->themeSupport();
Theme *currentTheme = themeSupport->theme();

Theme

The Theme class represents a particular theme consisting of various visual elements, such as color. You can call Theme::colorTheme() to retrieve the color configuration of the theme (represented by a ColorTheme object).

ColorTheme *colorTheme = currentTheme->colorTheme();

ColorTheme

The ColorTheme class represents a color configuration for a theme. This configuration includes an associated visual style (such as bright or dark), which is represented by a VisualStyle object. You can retrieve the style by calling ColorTheme::style().

VisualStyle::Type style = colorTheme->style();

VisualStyle

The VisualStyle class is an enumeration class that represents a theme's overall visual color style. Currently, this class includes enumeration values corresponding to a bright theme ( VisualStyle::Bright) and a dark theme ( VisualStyle::Dark).

switch (style) {
    case VisualStyle::Bright:
        // The app is using a bright theme

    case VisualStyle::Dark:
        // The app is using a dark theme

    default:
        // The app is using an unknown theme
}

SystemDefaults::Paints

The Paints class gives you access to the default colors for text and the background of containers. This class is part of SystemDefaults, which lets you determine default values for various visual elements, such as color and text style. You can call SystemDefaults::Paints::defaultText() to retrieve the text color (as a ColorPaint object), and you can call SystemDefaults::Paints::containerBackground() to retrieve the container background color (as a Paint object). The colors that you retrieve depend on the theme that your app uses, so you can use these functions to determine the colors that might look best for other visual components in your app.

ColorPaint *textColor = SystemDefaults::Paints::defaultText();
Paint *containerBackgroundColor = SystemDefaults::Paints::containerBackground();

Retrieving theme information in QML

Here's how to determine the current theme for an app in QML. This code sample uses a custom JavaScript function, themeStyleToString(), to convert the theme to a text string, and then the string is displayed by using a Label. The background of the Container is also set to the default background color.

Container {
    id: myContainer

    background: SystemDefaults.Paints.ContainerBackground

    function themeStyleToString(style) {
        switch (style) {
            case VisualStyle.Bright:
                return "Theme: Bright"
            case VisualStyle.Dark:
                return "Theme: Dark"
        }
        
        return "Theme: Unknown"
    }

    Label {
        text: myContainer.themeStyleToString(Application.themeSupport
                                                        .theme
                                                        .colorTheme
                                                        .style)
    }
}

Last modified: 2014-04-03

comments powered by Disqus