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

Active Frames

Active Frames are dynamic app covers that are displayed on the home screen
when your app is minimized. Every app uses app covers by default. Just swipe up from the
bottom bezel within an app and the app cover is displayed automatically. Tapping the app
cover takes you back into the app.

An app cover is a noninteractive scene that the Cascades framework automatically updates whenever the cover changes. By
default, the app cover displays a scaled-down version of the scene that's being
displayed in the app. For many apps, using the default app cover might be the best
option because it displays the current visual state of the app for the user.

However, there might be instances where you want to display specific
information in the app cover. For example, in a weather app you could display the
current temperature. You can create your own app covers using the SceneCover class.

For best practices for using app covers, see the Active Frames topic in the UI Guidelines.

Creating a cover

An app cover is similar to any other screen that you might create in your
app. You can create the content for the cover using either QML or C++ and the app cover
can support whichever controls that you want to display.

Although the root node of the scene needs to be an
AbstractPane subclass, the root of a cover
can be a Control. The major difference is that users
can't interact with a cover, and it doesn't support animations.

You can download the Cascades Cookbook app, which demonstrates how to create
covers using both C++ and QML, from the Sample
Apps page.

Because it doesn't have a custom cover, the app
displays a scaled-down version of the current scene. Here's what the
cover might look like when the home screen of the app is being
displayed.

To create the content for a cover in C++, you
need to create the controls and add them to a root
container. The custom cover for the Cascades Cookbook app contains a 334 x 396
pixel image for the background, a Label indicating the name of the
cookbook, and various containers and layouts for positioning
the controls.

The background image is designed specifically
for the dimensions of the BlackBerry Z10. If your app also targets devices with
a physical keyboard, you need another background image that
is 310 x 211 pixels. Since the cover itself is small
compared to a regular screen, the label uses a custom TextStyle with a SmallFontSize.

// A small UI consisting of just an ImageView in a Container
// is set up and used as the cover for the app when running
// in minimized mode
Container *coverContainer = Container::create().background(
Color::fromRGBA(0, 0, 0, 1));
coverContainer->setLayout(new DockLayout());
// A background image for the app cover
ImageView *coverImage = ImageView::create(
"asset:///images/app-cover.png").scalingMethod(
ScalingMethod::AspectFit);
Container *titleContainer = Container::create().bottom(31);
titleContainer->setHorizontalAlignment(HorizontalAlignment::Center);
titleContainer->setVerticalAlignment(VerticalAlignment::Bottom);
Container *labelContainer =
Container::create().preferredSize(84, 42).background(
Color::fromARGB(0xff121212));
labelContainer->setLayout(new DockLayout());
// A title for the "book" cover so that one can see that it
// is the C++ version of the cookbook that is running
Label* title = Label::create("C++");
title->textStyle()->setColor(Color::fromARGB(0xffebebeb));
title->textStyle()->setFontSize(FontSize::PointValue);
title->textStyle()->setFontSizeValue(6);
title->setHorizontalAlignment(HorizontalAlignment::Center);
title->setVerticalAlignment(VerticalAlignment::Bottom);
// Setting up the title Container with a title
labelContainer->add(title);
titleContainer->add(labelContainer);
// Adding the background image and the title Container
coverContainer->add(coverImage);
coverContainer->add(titleContainer);

After you add the components to the root container, you create an
instance of SceneCover using the root container, retrieve an instance
of Application, and set the cover.

Using two SceneCover objects allows you to design the large and small
app covers to show specific parts of your app, including dynamic content in your
app.

Using a SceneCover and an ApplicationViewCover allows you to design one specific app
cover and let the other app cover be a scaled version of the current scene in your app.
Setting the CoverDetailLevel determines which app cover
is used. A CoverDetailLevelof High indicates that this app cover is used for large Active Frames. A
CoverDetailLevel of Medium indicates that this app cover is used for small Active Frames.

The following code sample shows how to create a MultiCover using two SceneCover
objects:

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.