Archives For UI and Navigation

Welcome to part five of my article series on ‘Supporting BlackBerry Passport and 10.3 SDK / API’

First three parts of this article series help you to support the BlackBerry Passport from SDK / API 10.2 – the other ones are using SDK 10.3

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
  4. Supporting BlackBerry Passport – Git, Colors and ActionBar

Switching themes

In part #4 we’ve seen that some pages won’t look so good in 10.3 because of bright ActionBar.

Here’s the Home Page of my TimeTracker App using the new compact ActionBar:


I have to redesign this page for the bright theme without using black background. (Will do this later – needs some work on images)

As a first step I made the Theme configurable from settings – so users on Passport can switch to the dark theme:


In my settings data I’m storing ‘Default’, ‘Dark’ or ‘Bright’ and check this at startup. app.visualStyle() returns my settings value.

I’m also calling this function immediately after saving the settings – Cascades dynamically changes the style.

function setVisualStyle(){
    if(app.visualStyle() == "Default"){
    if(app.visualStyle() == "Dark"){
        if ( == VisualStyle.Bright) {
    } else {
        if ( == VisualStyle.Dark) {

There’s one rule: on devices using OLED  displays it’s not recommended to use the bright style, so I’m hiding this settings option:


Container {
    id: visualStyleContainer
    visible: !app.isOrganicDisplayTechnology()


bool ApplicationUI::isOrganicDisplayTechnology()
    bb::device::DisplayInfo display;
    return display.displayTechnology() == DisplayTechnology::Oled;

On a Z30 the user has no chance to switch to the bright theme, but on BlackBerry Passport users can toggle between dark and bright.

I also changed the Home Page to display only one button (Start or Stop) in the middle between TabMenu and ActionMenu – so it looks like the Signature ActionItem – only using a larger one. Here’s how it looks now using the dark theme:


Don’t use disabled Signature Actions

I already wrote about Signature ActionItems in part #4 of this series.

There may be situations where your Signature Action will be disabled – per ex. no data to send. Disabling ‘normal’ ActionItems is easy – simply set enabled to false. But using a Signature Action this doesn’t look well – even if the user has hidden all ActionItem Labels what’s possible in 10.3 from Device Settings.

Here’s an example how enabled / disabled SignatureActions are looking from bright or dark theme:


Because the background color of a Signature Action remains the same for disabled Actions the difference between both states isn’t always easy to recognize. So for me it’s clear I never will disable a Signature ActionItem.

On the other side: having an enabled Signature Action telling the user after tapping on it that there’s no data to send isn’t the best solution 😉

Unfortunately the ‘Signature’ property of an ActionItem can only be set once while creating the ActionItem so you cannot switch between OnBar and Signature.

Here’s how I’m dealing with this. Example is from TimeTracker’s Server Queue: sometimes there’s data inside the queue – sometimes not. If there’s data and network coverage TimeTracker will send queued data out automatically. Perhaps something went wrong and the user wants to trigger it manually – so there’s the ActionItem ‘Try again’.

If there’s nothing in the Queue I’m using a ‘normal’ disabled ActionItem:


If there’s some data,  the ActionItem was changed into an enabled Signature ActionItem:


Now both states are easy to distinguish 🙂

attachedObjects: [
     ActionItem {
        id: tryAgainAction
        title: qsTr("Try again")
        imageSource: "asset:///images/try_again.png"
        ActionBar.placement: ActionBarPlacement.Signature
        onTriggered: {
            // do your stuff
actions: [
    ActionItem {
        title: qsTr("Network")
        imageSource: "asset:///images/info_cloud.png"
        ActionBar.placement: ActionBarPlacement.OnBar
        onTriggered: {
            // do your stuff
    ActionItem {
        id: tryAgainActionDisabled
        title: qsTr("Try again")
        enabled: false
        imageSource: "asset:///images/try_again.png"
        ActionBar.placement: ActionBarPlacement.OnBar
        onTriggered: {
            // dummy
    ActionItem {
        id: adminAction
        title: qsTr("Admin")
        imageSource: "asset:///images/server.png"
        ActionBar.placement: ActionBarPlacement.OnBar
        onTriggered: {
            // do your stuff

There are now two Actionitems: one inside actions [ ] the other one as attached Object.

If the state changes I’m swapping the ActionItems. There’s no problem to remove / add the same Action more then one time because the removed Action still has the current Page as parent and can be reused.

} else {

I cannot insert an ActionItem at a specific position on ActionBar, so I’m also removing the adminAction and add again after adding the disabled tryAgainAction.

Please note: Adding the Signature ActionItem I don’t have to do this because a Signature Action always will be positioned in the middle.

Touch Enabled Keyboard and Scrolling (ListView, ScrollView)

How cool it is to scroll through pages from your touch enabled keyboard is easy to test:

Open the Browser and scroll through a long Page. If you need more space: rotate the Passport and scroll from the (now vertical positioned) keyboard.

Go back to your app and try to scroll through your Pages – if using ListView or ScrollView this should work.

uuups – some Lists or ScrollViews don’t scroll

At first I was thinking there’s a bug (Tested using a pre-release SDK and Simulator).

Then tried to find out which Pages scroll and which not – and finally found out the reason and it makes sense. So please don’t blame Cascades if a Page isn’t scrolling out of the box.

Remember: we’re on a Keyboard and Keyboard events are always working on the field having the Focus. If you want to enter a word into a TextField you have to Tap on the field or your app must use requestFocus() !

Same with Touch Events from your Passport Keyboard. In most Pages it will simply work, because the ScrollView or ListView is the first UI Control getting the focus automatically.

But this isn’t always true. I’m running into situations where a Page is structured this way:

  • Page
    • ScrollView disabled
      • Container for content if no-data-available
    • ListView
      • ListItems

Opening this Page with data in your List doesn’t scroll from keyboard because the ListView doesn’t have the Focus. The ScrollView has the Focus, but nothing to scroll because it’s disabled.

Now it’s up to you to manage the Focus if you’re running the app on a device like Passport where you can touch on the Keyboard: use Signals/Slots or functions.

function requestFocusToScrollTheList(){    
    if (dataModelTracked.size() && app.isKeyboardDevice()) {

Hint: don’t set the focus from onCreationCompleted{} – the Page must be visible before requesting the focus will work.

EDITED 2014-09-30:

There seems to be a bug (see this Issue) if scrolling from Touch-Keyboard, then from Touch-Screen, then back to Keyboard and scrolling stops working.

Workaround: at ListView set this policy:

    focusRetentionPolicyFlags: FocusRetentionPolicy.LoseToFocusable

Now also users of your app can benefit from the cool scrolling function using touch gestures on BlackBerry Passport 🙂

It’s worth to support this – you know there will be the BlackBerry Classic later this year using a Trackpad besides the screen – I don’t know but could imagine it will work similar.

More Gestures on Keyboard

Scrolling is a built-in feature, but you can add your own touch functionality.

Here per ex. HowTo detect if the user swiped horizontally:

eventHandlers: [
    TouchKeyboardHandler {
        id: touchKeyboard
        property int startX
        property int stopX
        onTouch: {
            if (event.touchType == TouchType.Down) {
                startX = event.screenX
            if (event.touchType == TouchType.Up) {
                stopX = event.screenX
                var distance = Math.abs(stopX - startX)
                if (distance > 360) {
                    console.debug("Swiped horizontally " + distance)
                } else {
                    console.debug("distance too short")

I’m testing if the user moved his fingers horizontally more then 360 px (around 25% of width of keyboard) – if device is in Landscape you must reduce the value.

Using Touch Events isn’t easy – please take a look at Cascades documentation, because this isn’t covered by this article series.


Next part will focus on Design Units. Have fun with BlackBerry Passport.

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.

This is Part 3 of my ‘Support BlackBerry Passport’ series – you should read the other parts first:

  1. Supporting BlackBerry Passport – step one 10.2
  2. Supporting BlackBerry Passport – Keyboard Shortcuts

This article is the last one with some tips and tricks HowTo support the Passport from 10.2 SDK / API – part 4 will start using 10.3 SDK / API.

Most screenshots again are from my TimeTracker App – some are from one of my Conference2Go Apps: IoT Conference.

Let’s start with a ListView, where I displayed tracked time logs. Running on a Z30 the list looks different for Portrait and Landscape:


In Portrait the most important informations are visible from first row:

  • Time Category Image
  • Time tracked from HH:MM … to HH:MM
  • Duration HH:MM
  • Marker Image if tracked ‘over night’

second row gives some short information on Customer name (if there’s a customer connected) and Time Category Name.

Rotating to Landscape gives you more space to display some words from

  • Project (if available)
  • Order (if available)
  • Task (if available)


What to do on the Passport ? By default I’m using the Portrait Layout, but in this case there would be much empty space on the right side of the screen – so I decided to use the Landscape Layout as default layout for Passport. Here’s the result:


Before Passport the layouting was easy done: the Container containing the Label fields for Landscape was only visible if device was rotated to landscape:

Container {
    id: column2Container
    visible: OrientationSupport.orientation == UIOrientation.Landscape
    layoutProperties: StackLayoutProperties {
        spaceQuota: 1.3
    // Label .....
} // end column2Container

The Container becomes visble in Landscape – using spaceQuota arranging the available space for all the content displayed in StackLayout with orientation LeftToRight.

To get this also visible on Passport you could think I only had to change the visible property:

Container {
    visible: app.isPassport() || OrientationSupport.orientation == UIOrientation.Landscape
} // end column2Container

Unfortunately it’s not so easy because this Container is part of an ListItem and from inside a ListItemComponent I don’t have access to C++ methods, so app.isPassport() always will return false. To make it run we have to delegate this to the ListView where the ListItemComponent lives in:

ListView {
    id: trackedList
    // ...
    property bool column2Visible: app.isPassport() || OrientationSupport.orientation == UIOrientation.Landscape
    // ...
    listItemComponents: [
        ListItemComponent {
            type: "item"
            CustomListItem {
                id: itemRoot
                dividerVisible: true
                highlightAppearance: HighlightAppearance.Full
                TrackedListItemContainer {
                    // extra QML file layouting our ListItem
                } // end outerItemContainer
            } // end itemRoot
        }, // end ListItemComponent item

    ] // end listItemComponents
    // headerItem
    // onTriggered{} and other functions
} // end ListView

Now we can access the property from inside the ListItemComponent (TrackedListitemContainer):

Container {
    // ...
    visible: itemRoot.ListItem.view.column2Visible
    // ...
} // end column2Container

At the end it’s easy as soon as you understood how ListItemComponents are working.

UI on Passport’s High-Density (453 dpi) screen looks great 🙂

Even small Fonts are looking fine. Tap on the screenshot above  and zoom in to verify.

Please be aware that this high density can be a problem for users – not all eyes are able to read such small fonts and not everyone uses high end glasses to make it readable.

In my apps I’m following the UI Guidelines and I’m using SystemFontStyles like TitleText, SubTitleText, … and it’s up to the OS to choose the font and size.

On Z30 it’s very rare to hear users complaining about too small fonts, but on high-density devices like Passport this can happen. Fortunately users can change this from System Settings | Display:


Changing this Font Size immediately affects all apps – even already running apps.

In many cases you have nothing to do if your design follows the rules on adaptive layouting. Here are screenshots from my IoT Conference App:

Sessions using default font size of 8:


and here the same list with font size of 14:


Hint: this conference app must be slightly  tuned for Passport and I haven’t done this yet: Icons are too small – but text is working for all sizes.

Back to my TimeTracker App where the List Layout is very specific and won’t survive larger fonts:


Now the Duration is missing because there’s not enough space anymore using such a large font. Changing to ’12’ duration will be partly there – changing to larger then ’14’ from…to time will only be visible partly. Both informations are important and should always be visible independent from Font Size.

Here’s a solution HowTo survive such kind of layouts:

Label {
    text: ListItemData.hourMinuteLocal + "-" + ListItemData.hourMinuteLocalStop
    textFit.maxFontSizeValue: itemRoot.ListItem.view.titleTextMaxSize
    textStyle.base: SystemDefaults.TextStyles.TitleText
    textStyle.fontWeight: FontWeight.W500

There are some ‘textFit’ properties on Labels where you can set min and max font sizes and more. In this case I want to limit the font size for TitleText. The property itself is defined at ListView:

ListView {
    id: trackedList
    // ...
    property bool column2Visible: app.isPassport() || OrientationSupport.orientation == UIOrientation.Landscape
    property int categoryImageSize: app.isPassport()?120:80
    property int imageSize: app.isPassport()?120:81
    property int markerImageSize: app.isPassport()?92:61
    property int titleTextMaxSize: app.isPassport()?11:10
    property int bodyTextMaxSize: app.isPassport()?10:9
    // ...
} // end ListView

As you can see I have different max values for Passport and other devices.

Some rules:

  • At first always design your layout using default font size to get an optimal result
  • Then change font sizes from Settings
  • Try to find a layout design working with all sizes
    • If not find out maximum values

Don’t forget: all of this is HowTo make it work from 10.2 without switching to 10.3 API. Using 10.3 and ‘DU’s’ (Design Units) and asset folders for density / size / … there are more options to do it then from 10.2 where you only can use the 1440×1440 static assets folder to place assets used by passport.

As soon as you’re using multiple QML files with same name  for different devices, density etc. development becomes more difficult. At first you should always try to do your work from one single QML file for a Page, Sheet, Container. Later when your UI is more stable, duplicate the files and do the device-specific layouting. Doing this too early means all changes must me done in multiple files.

Here’s a tip HowTo use functions with some UI Logic from more then one QML File without duplicating the functions itself:

  • Create an extra QML File for a Container
    • This Container only contains functions, no UI Controls
  • Attach this Container to all Pages (per ex. PageXYZ.qml in assets/ and also assets/1440×1440) calling these functions

Then you only have to manage the function from one place.

Here’s the Container containing UI Logic. In this case there are two functions to check if a tracked data item is overlapping start or stop time with already tracked items. Functions are filling a temp GroupDataModel to check this, so it’s also inside the Container – no one else needs it.

I’m placing such Containers inside an extra folder: assets/ui_logic to make it clear that these qml files only contain some logic.

This is assets/ui_logic/CheckOverlappingTimes.qml:

import bb.cascades 1.2

Container {
    id: checkOverlappingTimes
    attachedObjects: [
        GroupDataModel {
            // f,t, id
            id: dataModelOverlap
            sortingKeys: [ "f" ]
            sortedAscending: false
            grouping: ItemGrouping.ByFullValue
    function isStartNotOverlapping(start){      
        // your logic
    function isStartStopNotOverlapping(uuid, start, stop){
        // your logic

Pages calling these functions:

import "ui_logic"
Page {
    id: myPage
    // ...
    attachedObjects: [
        // dummi
        CheckOverlappingTimes {
            id: checkOverlappingTimes
            visible: false
    // ...
    actions: [
       ActionItem {
            id: saveAction
            title: qsTr("Save")
            ActionBar.placement: ActionBarPlacement.OnBar
            imageSource: "asset:///images/save.png"
            onTriggered: {
                var startStopValid = checkOverlappingTimes.isStartStopNotOverlapping(uuid, startTime, stopTime)
                    // do something
    // ...

Now all calls to these functions are delegated to our special Container.

Hope you got some ideas where to look in your apps to support Passport Device from your 10.2 API.

Next article will go one step further and use 10.3 API which means you have to support two different APIs – I’ll tell you how I’m doing this.

Have Fun with BlackBerry Passport !

… and don’t forget: See the bigger picture soon in Toronto, London or Dubai.

This article is a follow up of supporting blackberry passport – step one 10.2

While preparing my apps for BlackBerry Passport I notices some “problems” using shortcuts. As a good native-app-citizen I always try to provide shortcuts for users of Q5 / Q10 to ease their workflow.

Upcoming BlackBerry Passport has a much cooler and innovative keyboard: only 3 rows of physical keys plus one or more virtual rows with context-sensitive virtual keys. … will blog about this later in detail.


As you can see the physical keys are missing the ‘alt’ and ‘shift’ keys. Take a look at Cascades documentation on shortcuts: you’ll see that you can use shortcuts with combinations of ‘alt’ or ‘shift’ and there are some situations where I did this in my TimeTracker app (

Here’s a special screen where I’m using a Segmented TitleBar:


To switch between the ‘Tabs’ from Segmented TitleBar you have to tap on a Tab, which means you have to move your hand from the keyboard. Using shortcuts you can go on easy. It’s always a challenge to find the right keys working for all your screens in all languages without collision of SystemShortcuts. So I decided to number the Segments and to use the number as Shortcut key. This will be consistent through all languages and looks the same on all Pages with Segmented TitleBars.

For the user it’s easy to understand and to remember:


To type 1, 2, 3 or 4 you have to type ‘alt w’, ‘alt e’, ‘alt r’ or ‘alt s’. I used a trick to display the numbers:

shortcuts: [
    Shortcut {
        key: "2"
    Shortcut {
        key: qsTr("Alt + e")

You can define more then one shortcut for an Actionitem and Cascades will always show the first one. So in this case the ‘2’ will be visible, but to type a ‘2’ in reality the user has to press ‘alt’ and ‘e’.

Now with Passport there’s no ‘alt’ and there are no numbers, so my tricky workaround won’t work on this screen:


Here’s a possible solution:

shortcuts: [
    Shortcut {
        key: app.isPassport()?qsTr("D"):"2"
    Shortcut {
        key: qsTr("Alt + e")

It’s up to you: change all shortcuts or provide different sets for Q5/Q10 vs Passport. Using shortcuts like ‘D’ it’s important to make them translatable – then you can translate them easy without changing the code itself.

Here are the new shortcuts on Passport:


BTW: take a look at the screen layout: BlackBerry Passport allows to place big icons to ‘jump’ to other areas. (Users of this app like it to have big buttons)

Remark: I have to redesign the upscaled Icons to make them look better – it’s on the ToDo 😉

See the bigger picture

Have fun moving your apps forward to BlackBerry Passport !

… and don’t forget: See the bigger picture soon in Toronto, London or Dubai.

In 3 weeks BlackBerry will launch the BlackBerry Passport worldwide: See the bigger picture in Toronto, London and Dubai. BlackBerry Passport is different:

  • Big Screen: 1440 x 1440 Pixel – great for long Text, Spreadsheets, Images, Video and more
  • High Density: 453 dpi (more then iPad Mini Retina with 326 dpi)
  • New Keyboard: Gestures on physical keyboard will allow new ways to work

…and all put into a mobile device with 1:1 screen sized like a Passport.

I don’t want to get into the details here – take look at CrackBerry to find out more.

What does the BlackBerry Passport mean for developers ?

BlackBerry Passport is the first device running OS 10.3.0 and there’s a SDK available since some time.

10.3 offers a great UX and looks cool. 10.3 introduces some decent colors, a redesigned ActionBar and is changing the way you’re layouting your screens: from now on there are DU’s (Design Units) instead of Pixel. Using DU’s it’s easier to support devices with different dpi (Density) – but it’s much work for developers. At the moment (September 2014) there’s only one device using 10.3 UI / UX: the BlackBerry Passport, but later this year (around November 2014) there will be an update to 10.3.1 for all devices in the field. This means we have some months to redesign our apps.

Of course 10.2 apps are running on 10.3 devices and if you’re using DockLayouts and StackLayouts with space quota there’s a chance that your app will run on BlackBerry Passport without looking ugly. (see my blog post on Adaptive Layouting)

I really recommend to run your apps from BlackBerry Passport Simulator to check if all works well.

Step one: support Passport from 10.2

Before updating to DU’s, new ActionBar etc I recommend at first to support the Passport from 10.2 SDK. In this blog post I will give you some tips and tricks to make your life easier. I’m also testing on Z30 using 10.3 Developer OS to demonstrate differences important with 10.3.1 release later.

Use the static asset selectors if you have to provide some assets specific to BlackBerry Passport.

I will explain what I did to support BlackBerry Passport using my app TimeTracker as example. Read more about TimeTracker App at At the end I had to change some qml files and some background images.


Even if you compile your apps using 10.2 SDK the app will look different on 10.3 devices.


There are some important differences how TitleBars are looking under 10.3.

Here’s a Segmented TitleBar:

left side: 10.2, right side: 10.3


The height is the same, but now the text is colored and below the titlebar there’s a divider with gradient.

The same TitleBar using a bright theme:


The Passport uses a light grey background and black text, where 10.2 devices are using a blue colored titlebar with white text.

Text colors and background are set by default from Cascades so this should cause no trouble.

….if you’re not using FreeForm Titlebars like this one:


For devices running 10.2 I set the text color to Color.White, because this works well on black or blue colored titlebars.

But it doesn’t work on  the Passport: white text isn’t readable. I had to change the color to Color.Black:

Label {
    id: titlebarLabel
    text: "Titlebar"
    textStyle.base: SystemDefaults.TextStyles.TitleText
    textStyle.color: app.isPassport()?Color.Black : Color.White
    verticalAlignment: VerticalAlignment.Center
    layoutProperties: StackLayoutProperties {
        spaceQuota: 1

You see I’m asking a C++ method if the app is running on a Passport:

bool ApplicationUI::isPassport()
    bb::device::DisplayInfo display;
    if (display.pixelSize().width() == 1440 && display.pixelSize().height() == 1440) {
        return true;
    } else {
        return false;

There’s another problem with this Titlebar: the icons are looking good on dark or blue 10.2 – TitleBars, but not on Passport – I have to change the Icons – more about Icons later.


Let’s go on with the ActionBar. Using 10.2 API we cannot use the new colored Action in the middle:


Here are ActionBars using a dark theme:


They’re looking similar, but the 10.3 ActionBar is less in height: if you’re using Background Images perhaps there’s now some more space visible as you’re expecting.

Using a bright theme there’s another difference:


10.2 always used a dark ActionBar – doesn’t matter if running a dark or bright theme.

10.3 is using a grey colored ActionBar on bright themes. We’re in luck: Cascades inverts all the Icons, so we can still use the same set of icons.

Pages on bright theme are looking much better now without the black colored ActionBar at the bottom, but….

In some cases my HomePage is using Images looking good together with a dark ActionBar, but not so good under 10.3 bright themes now:


The clock image is on a black background – have to redesign this and change the Page to a bright background later. Check your apps if you’re running into this side-effect of using a bright ActionBar.

Attention: Passport can change orientation

In the past all keyboard devices (Q5, Q10) using a square screen cannot rotate, but Passport allows this ! You may ask why you should rotate a square screen ? It’s because of the new innovative keyboard: swiping on the keyboard to scroll through large lists or pages sometimes it’s more comfortable to change orientation and use the keyboard as vertical touch area.

Is your app supporting Touch Devcies (Z3, Z10, Z30) with different layouts for Portrait and Landscape ?

A common way to do this is using an OrientationHandler:

attachedObjects: [
    OrientationHandler {
        onOrientationAboutToChange: {
            // do your re-layouting stuff
    // ...

Then you probably do some stuff like if landscape then this … if portrait then that … always expecting that you’ll get the event from a 16:9 or 16:10 device, but not from a square device.

I normaly have done my default layout for Portrait on Touch and if there’s a different layout for Q5 / Q10 I did this inside onCreationCompleted{}

Now using the Passport it may happen that your app gets an event telling that the Device was rotated to Landscape.

Running your code to relayout for Landscape won’t look very well on Passport 😉

So I did a search/replace for OrientationHandler and simply added 3 lines of code:

attachedObjects: [
    OrientationHandler {
        onOrientationAboutToChange: {
            // do your re-layouting stuff
    // ...


Disabled TextFields look much different on 10.3:


Disabled TextFields under 10.2 were looking like you can do something where 10.3 clearly shows a disabled text only.

10.3 uses  less space then 10.2 for disabled TextFields.

Editable TextFields look like this on a dark theme:


10.3. again uses slightly less space then 10.2

and here’s the same on a bright theme:


From my feeling 10.3 looks much more elegant.

Toggle Buttons

Toggle Buttons are redesigned for 10.3 and now are something shorter and slightly higher:


Please check if your layout is still looking good.


In some cases I’m using different background images for Q5/10, Z10/30 Portrait/Landscape. Of course these Images must be designed for Passport and placed into assets/1440×1440/images.

Here’s a background image on Z30 Portrait:


and here on Passport:


Also take a look at the Icon left beside the text ‘No queued data…’ – both are looking same size, but on Z30 the Icon is 61×61 and on Passport I resized to 92×92 Pixel:

ImageView {
    property int imageSize: app.isPassport()?92:61
    imageSource: "asset:///images/server_color.png"
    minWidth: imageSize
    maxWidth: imageSize
    minHeight: imageSize
    maxHeight: imageSize
    scalingMethod: ScalingMethod.AspectFit
    verticalAlignment: VerticalAlignment.Top
    horizontalAlignment: HorizontalAlignment.Center

Please take a look at Cascades docs on DU’s (Design Units)

For me I decided that all my pixel sizes are working well on Z30 – this means: 8 Pixel per du (Design Unit), on Passport there are 12 Pixel per du.

Knowing this makes it easy to get similar sizes on 10.2: for Icons of 61×61 I’m using 92×92 on Passport, for Icons of 81×81 I’m using 120×120 on Passport.

To get it run quick and dirty I upscaled my existing Icons – of course normaly the other way is recommended: provide high density Icons and do a downscale. All my upscaled Icons are looking well on Passport, so I can do this later.


Sometimes for complex layouts it’s the best to have a separate layout for Passport in assets/1440×1440.

Here you can see different layouts of HomeScreen. At first Z30 Portrait and Landscape:



Running on the Q5/Q10 there’s only less space, so no clock Image:


All three layouts above are done inside one QML file.

Now on Passport’s big square screen I layouted different and placed an extra QML file into assets/1440×1440


Another Page I did an extra layout for Passport:

On Z30:


This is a rather complex Page: you can tap on the earth and TimeZone info will appear and inserted. Also if time was tracked over midnight an extra marker icon will be inserted etc. – so there’s already much logic included.

Here’s how it looks on Passport:


I completely redesigned the layouting for Passport.

Please also take a look at ActiveFrames: sizes are different for Passport !

Start supporting Passport now

Hopefully you got some ideas HowTo get your app run on BlackBerry Passport without complete redesign and without too much work.

Stay tuned for a follow up blog post where I will tell you what to do if you want to support 10.3 API.

Yes – it’s some work but it’s worth the work: 10.3 looks much better and using Design Units you’ll also be prepared for upcoming devices – what about a Full HD Touch as high-end ?

Have fun !

Edit: 2014-09-03: I’ve written a follow-up article on BlackBerry Passport and keyboard shortcuts.

ekkes Express Charts is an application to create charts on-the-fly and can be integrated into BlackBerry EXPRESS.

Here’s an Overview about the APP and HowTo download und use.

Easy Data Entry

One of the goals of my new app is to enhance productivity and always to have a Fast Lane.


That’s why I implemented the Easy Data Entry.

Starting the app you’ll get a list of all your saved chart data. The very first time this list will be empty and there’s a Dialog to let the user know about this:


If you want to use emoticons, don’t forget the property:

infoDialog.emoticonsEnabled = true

As next you can tell the app how many columns you want to enter:


From the Picker you can seelct between 2 and 9 Columns. Then tap on the ‘Go on’ Action.

Please notice that the Back Button in the ActionBar changed to Cancel to let you know that you can cancel this and gob back to the previous Page.

To overwrite teh default Back Button you can add this to your code:

paneProperties: NavigationPaneProperties {
    backButton: ActionItem {
        title: qsTr("Cancel")
        imageSource: "asset:///images/ic_cancel.png"
        onTriggered: {

Cascades makes it easy to create Objects dynamically and from the number you selected the next Page will display exactly the fields you need to enter your data:


there are 3 rows with Label, Value and optional Unit.

To create objects dynamically you have to attach the Component Definition – in this case describing the UI for one row:

attachedObjects: [
     ComponentDefinition {
         id: dataRowComponent
         Container {
             id: dataContainer
     ...... your UI controls
         } // end data container
     }, // dataRowComponent

and from a simple loop create them dynamically:

function createColumns(){
     var max = selectNumberColumnsContainer.columnCount
     for (var i = 0; i < max; i ++) {

The keyboard comes up automatically, because the first field requests the focus.


This is important if working with devices like Q5 / Q10: the user can immediately start to type. Without requesting the focus he/she has to tap on the field before typing.

Filling out all the fields from last field the keyboard automatically disappears so you can see it all and verify.


Before going on and customize or save the data you can directly control the generated chart clicking on the ‘Preview’ Button:


You can rotate to Landscape and if it looks ok capture the Chart and Save the Image or go back and customize.

There are some small things implemented to create a great UX, per ex.:

If coming from BlackBerry EXPRESS the ActionBar looks different:


Coming from another 3rdParty appliucation you’ll get this one:


Sending the Image back automatically closes the Page and returns to the calling application.

Have FUN with ekkes Express Charts 🙂

Cascades gives you the power to navigate easy through your apps.

You can start with a TabbedPane to separate your app into segments.

Each TabbedPane can contain single Pages or a NavigationPane as root of a stack of Pages you can push() and pop().

Here’s an example from SerCar10  (Management of ServiceCars with Cascades). In this article we want to take a look HowTo add, edit, delete positions of work. In this blog I only demonstrate dealing with positions of parts from your stock items catalogue. Another blog will focus HowTo add working hours.

Hint: Sourcecode – snippets will follow later


Here’s a short overview what you can do:


  • A: HomeScreen of the APP is a TabbedPane
  • B: Tapping on WorkOrders opens scheduled Work Orders, a NavigationPane with a ListView
  • C: Tapping on one Item (Work Order) shows details of this Work order
  • D: Action opens another Page with a ListView displaying all positions of work done for thie order. (Parts, Hours, Attachments)
  • E: Selecting parts – Action opens another ListView ‘on top’ from where you can select parts
  • F: Selecting a part opens a Page with details ‘on top’ where you can enter the Quantity
  • G: Action to save the selected part adds this item to the list of positions, recalculates pos value and totals and sets Working Order status in root ListView.
  • H: Tapping on a Part item in list of positions opens details of this position
  • I: From this details Page you can edit the quantity or delete the position. Changes are immediately visible in list of work positions.

Screenshots from this Workflow




































Peeking (looking back)

With Cascades and BlackBerry 10 it’s easy to know where you are in your workflow: you can peek back from your Content area to the last Page or from the Action Bar to the complete Application. Here are some samples:












Short Video to demo HowTo add, edit or delete positions of work orders:

Attention: Please switch HD ON (Top Right Corner of Video)

(c) 2012 Creative Commons License 3.0 (BY-NC-SA) by ekkescorner