Supporting BlackBerry Passport – 10. 3 Git, Colors and ActionBar

September 9, 2014 — Leave a comment

First three parts of this article series help you to support the BlackBerry Passport from SDK / API 10.2.

Please read these articles before going on:

  1. Supporting BlackBerry Passport – step one 10.2
  2. Supporting BlackBerry Passport – Keyboard Shortcuts
  3. Supporting BlackBerry Passport – Fonts, Layouts, Logic

Now we’ll go one step further and switch over to 10.3 API. This is always a great challenge HowTo manage different APIs – doesn’t matter if you’re developing for Android, iOS or BlackBerry 10 – esp. if you’re knowing that you have to maintain a project for different API a longer time. This month (September 2014) only BlackBerry Passport will run OS 10.3.0 – at the end of this year (November 2014) OS 10.3.1 is expected and will be available for all devices in the market. If it will take around 3 months to be available in most countries – so there will be a minimum timeframe of 6 – 9 months where we have to support 10.2 and 10.3.

Normaly I’m waiting some time before switching to the next API level, but this time OS 10.3 is so different from 10.2 and gives us more ways to provide good looking apps, I will bring all my apps to 10.3 very soon.

There are many ways to manage different API levels. I’m not a friend of any pre-processors and dealing with if 10.2 then this – if 10.3 then this.

10.3 is so different – there will be many cases where I have to re-layout Pages completely or restructure my QML Files or rethinking what using DU’s (Design Units) means in reality. The Business Logic (C++) will be nearly the same, but UI (QML) changes will end in some more long nights 😉

edited 2014-10-20: As I wrote above: there are many ways to manage multi OS API Levels. If you like to have it all in ONE Source Tree instead of managing Branches and Git CherryPicking, here’s a great post written by Derek (@dkonigs) : blackberry-10-multiple-os-versions-from-one-src-tree

Using Git Branches to manage API Levels 10.2 and 10.3

One year ago I wrote an article HowTo manage different API levels using Git branches and cherry-picking.

So I created a Branch for current 10.2 Development where Master is used for newest API Level (10.3).


10.2 API Branch and 10.3 Master are both checked out as two projects in Momentics IDE. To make this possible I changed the Eclipse Project name inside .project:

<?xml version="1.0" encoding="UTF-8"?>
    // ...

Here are both projects inside Momentics IDE:


Hint: rename the Launch Configurations – Momentics is using the entry point name which in both cases is ‘timetracker’


I like it to have both projects parallel in one IDE – then it’s easy to deploy and test both  APIs without checking out a Branch, refreshing / cleaning the Project,  rebuild …

Some fresh (Branding) Color

Now to start with 10.3 specific things the easiest one is to use some branding color. Cascades documentation explains how colors are working in 10.3 – let’s define a Primary Color in your bar-descriptor.xml. The documentation provides some sample colors good looking on bright and dark themes. You should always test your color scheme on dark and bright !


Using this Primary Color Cascades will calculate all other Colors, Gradients and Font Colors for you. Let’s take a look at some screenshots after setting of a Primary Color:

Selected Tab from TabbedPane:


TitleBar Title, Gradient (Delimiter) and ToggleButton on bright theme (Passport) and dark theme (Z30):


CheckBox and Custom Pickers on bright theme (Passport) and dark theme (Z30):


Isn’t this easy to get your app branded ? The really cool part is, that Cascades generates a complete UIPalette for you behind the scenes and you can use all properties from this UIPalette, per ex.:

Container {
    background: ui.palette.primarySoft
    Label {
        text: "Primary Soft " + Color.toHexString(ui.palette.primarySoft).toUpperCase();

Now if you’re changing your branding color, all Containers with primarySoft color will get the new one. Same is with Fonts – you have access to all generated values. I’m not a Designer and sometimes it’s not easy to find the right colors – relying on Cascades UIPalette I know they all match 🙂


Another great 10.3 feature: dynamic switching of Themes. In 10.2 you – as the developer – have to decide if you’re using the bright or dark theme or the default one. Default theme on OLED displays is dark – on other displays is bright, per ex. BlackBerry Passport default theme is bright and Z30 default theme is dark. There’s one golden rule: Using a dark theme is always OK – bright theme should not be used on AMOLED displays, because dark theme is optimized for better battery usage.

In 10.3 you can add a Theme-Switch to your Settings and allow users to switch the Theme:

Button {
    text: "Switch theme"  
    onClicked: {
        if ( == VisualStyle.Bright) {
        else {

You should warn the user if setting a bright theme on OLED.

I’m always supporting both themes. Sometimes it wasn’t easy to set Font colors and backgrounds – now using UiPalette you’ll always use the right one.

10.3 ActionBar

ActionBar in 10.3 gives you more flexibility.  Taking a look at 10.3 native apps like Calendar you’ll find the new Signatur Actionitem:


The Signature ActionItem will always be in the middle of your ActionBar and use your Color (see above) as background. You can also set the color by yourself, but it’s recommend to use the default one. TimeTracker App will give the user the freedom to change between bright or dark Theme, but UIPalette will be static.

There’s also a new way to hide most part of your ActionBar – only the overflow menu and Tabs are visible.

Page {
    id: homePage
    // ...

I will use this from TimeTracker’s HomePage where I have my own big buttons to Start or Stop a Time:


I have to redesing this Page for 10.3 and only place one big button in the midle – this will mimic the Signature ActionItem. (Also – as already written I will redesign the Page to better fit the bright theme from Passport where the ActionBar isn’t anymore with dark background as before.)

Taping on START Button, there will follow three Pages you normally only tap on the Action or type ‘g’ for GO on your Keyboard.

Changing this default action as Signature:

ActionItem {
    title: qsTr("Go On")
    ActionBar.placement: ActionBarPlacement.Signature
    // ...

Now take a look at these three Pages with or without a Signature Action:



Have fun with 10.3 and stay tuned … this was only the beginning – there will be more in this series to learn about the new features.

No Comments

Be the first to start the conversation!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s