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

Creating a headless app

There are several steps involved in creating a headless app. The following
sections explain each step in detail, helping you build a headless app from scratch.

You can also create a headless app by using the Headless app template in the Momentics
IDE for BlackBerry.

Create the headless project

A headless app consists of two separate projects in the Momentics
IDE: a UI part and a headless part. You create these projects
separately and then link them together to form the full headless app.

To create the headless part of the app, you start with a new Cascades project that uses the Standard empty project template, and then
modify the files that are included in that template. To learn how to create this
type of project, see Creating a Cascades project.

Even if you're planning to create an app that doesn't use Cascades and uses only core APIs, you must still start by modifying a
new Cascades project.

After you create this project, you need to modify the main.cpp, applicationui.hpp,
and applicationui.cpp files. All of these files are located in the src folder of the
project.

main.cpp

Here are the changes that you need to make to this file:

Include <bb/Application> instead of
<bb/cascades/Application>. The template uses the Cascades
version of the Application class (in the
bb::cascades namespace), but a headless app uses the more
generic version of Application.

Remove the specification of the bb::cascades namespace.
Instead, add a using statement and specify
bb::Application to make sure that the app references the
correct Application class.

Remove the inclusion of Qt classes
that support translation and debugging. You generally include translation and
debugging support in the UI part of your app, and so these classes aren't
required for the headless part.

Remove the Q_DECL_EXPORT macro from the main()
function declaration. This macro is used for shared libraries in Qt and isn't
required here.

applicationui.hpp

Here are the changes that you need to make to this file:

Change the file name to "HeadlessApplication.hpp" or something similar. This
change isn't strictly required, but it can be helpful to rename this file to
prevent any confusion about its purpose. This headless part of the app doesn't
include any UI elements. Regardless of the file name that you choose to use,
make sure to use the correct file name in other locations in your project (for
example, in main.cpp).

Use the bb::system namespace instead of the
bb::cascades namespace. The headless part doesn't use any
Cascades
classes, but it does use classes in the bb/system library
(namely, the InvokeManager class).

Remove declarations that provide support for translation and
locale changes, including QTranslator, onSystemLanguageChanged(), m_pTranslator, and m_pLocaleHandler.

Add a declaration for a private slot function called
onInvoked(), as well as an InvokeManager
private variable. These elements are used to handle invocation requests for the
headless part of the app.

applicationui.cpp

Here are the changes that you need to make to this file:

Change the file name to "HeadlessApplication.cpp". Similar to the change to the
applicationui.hpp file above, a different name can help prevent confusion about
this file's purpose. Make sure to use the same name as the corresponding .hpp
file, and include that .hpp file in this .cpp file.

Remove the inclusion of Cascades
classes. The headless part doesn't use any Cascades
classes or other features.

Remove the prepopulated code from the constructor. Most of this code is used to
handle the creation of a QML document from a .qml file in Cascades,
which isn't required here. Instead, use the constructor to initialize the
_invokeManager private variable that you declared earlier,
set its parent to the current object, and connect its invoked()
signal to the onInvoked() slot function.

Remove the definition of the onSystemLanguageChanged()
function. This function is included to support translation, which isn't required
in the headless part of the app.

Define the onInvoked() slot function, which is called when the
headless app is invoked.

Modify the project structure

Because the headless part of the app uses the InvokeManager and
bb::Application classes, you need to modify the .pro file in the
project. This file is located in the root folder of the project and has the same name as
the project (for example, "HeadlessPart.pro").

You should also remove cascades10 from the CONFIG line,
because the headless part doesn't use any Cascades
features.

To finish configuring the headless project, remove the bar-descriptor.xml file and the
asset folder from the project. Neither of these are used in the headless part of the
app.

Create the UI project

After you create the headless project and modify it to become the
headless part of the app, you can create the UI part.

To build your UI using Cascades APIs, start with a Cascades project. To build your UI using core APIs,
start with a Core Native project.

Add assets

To link the headless and UI parts of the app, you must add the headless
part as an asset in the bar-descriptor.xml file of the UI part. You can use the <configuration> element for each launch configuration
that you plan to use. You specify an entry point ID and use it to reference the binary
of the headless part of the app.

In the project that you created for the UI part, open the bar-descriptor file and find
the <configuration> element for a launch configuration that you want
to modify (for example, the Device-Release configuration). Assuming that the project
names are "HeadlessUI" and "HeadlessPart" for the UI part and headless part of the app,
respectively, your configuration should look similar to the following:

To determine the location of the binary for the headless part of the
app (which appears as the value of the path
attribute in the entry point asset), consider the project structure
that's illustrated in the image on the right. The headless part
binary is generated in /arm/HeadlessPart, so to correctly reference
this binary, a path of ../HeadlessPart/arm/HeadlessPart is used.

Modify entry points

Before you can package the two parts as one app, you need to modify the
entry points in the bar-descriptor.xml file of the UI part. This modification allows the
UI and headless components of your app to use separate entry points.

Specify the appropriate permissions

Headless apps require the _sys_run_headless system permission and
start when they are triggered. You specify this permission in the bar-descriptor.xml
file of the UI part of the app:

<permission system="true">_sys_run_headless</permission>

Long-running headless apps require the _sys_headless_nostop system
permission, as well as _sys_run_headless system
permission, to run at all times. If you need to keep your headless app running
indefinitely, add the following permission in the bar-descriptor.xml file of the UI part
of the app:

<permission system="true">_sys_headless_nostop</permission>

For more information about app permissions and how to use them, see App permissions.

Add invocation framework support for triggers

The headless part of an app is started in response to a trigger. A trigger represents an
event that your headless app should respond to, such as receiving a new message. To
qualify as a headless app, your app must specify itself as an invocation target with the
type application.headless, which allows it to be
invoked in response to a trigger. To learn more about triggers and which ones are
available, see Triggers.

You need to specify the invocation target for both the UI part and the
headless part of your app. Here's an example of how to specify the invocation target for
the UI part:

In the invocation target for the headless part, the system STARTED action is used in the filter. By using this
action, the headless part of the app is invoked as soon as the app is installed on the
device and the device is restarted.

Build and install the app

Now that you've created the UI and headless parts of the app and
configured them correctly, you can build the entire app and install it on a device. You
need to build the headless part first because the binary of the headless part is
referenced by the UI part and needs to be available before the UI part can be built.
After you build the headless part, you can build the UI part.

You don't install the headless part of the app on the device; you should install only
the UI part.

If you have specified the appropriate permissions in your bar.descriptor.xml file, you can install the UI part of your headless app like
any other app.

Last modified: 2015-02-23

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

1. Choose your focus

This is the focus controller. Use this controller to choose your primary development approach (Cascades or Core).

By selecting a focus, you get to decide what content should be front and center on the site.

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

3. 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 check boxes to display the samples relevant to your focus.

4. Educate yourself

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

The documentation for your preferred focus always appears at the top of the left-hand navigation, but you can still access the rest of the documentation at the bottom.

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