Supporting BlackBerry Passport – step one: 10.2

September 2, 2014 — 6 Comments

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.

6 responses to Supporting BlackBerry Passport – step one: 10.2


    I have a problem wiz my BlackBerry passport, how I can change the font model in both language, english and, arabic


    Do you know how tall (in pixels) the action bar is on the Passport?


      have not tried yet, because in many cases I’m using compact action bar now where I need the total space
      But for some ListView with compact action bar and signature action the last row was partly hidden by overflow and tab menu
      adding ui.du(12) as bottomPadding to the ListView adds exactly that amount of space so the divider of last row in list is at top of overflow and tab menu
      so i would try to use this value: ui.du(12) == 144 px


    Hi Ekke,

    I have apps on BlackBerry World, if I don’t use 10.3 new feature — can my apps support 10.3 device without change on my code?
    Or I must change something on my code to support new device?



      to ask these kind of questions it’s always the best to use the forums.
      …. and there’s no real answer – it depends from your app. Read my blog series and you know there can be situations where scrolling not works from Passport Keyboard. not a bug, but bad UX.
      Passport is square but supports Landscape. You should test your apps if all works smooth. … follow up discussions please in the forum – then all can read it.

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