Archives For Keyboard Devices (Q10, Classic, Passport)

This is part #3 of my blog series ‘Supporting BlackBerry Classic’ as native BlackBerry10 developer.

Please read about screen sizes and first steps here and about Shortcuts here.

BlackBerry Classic isn’t only a great BlackBerry 10 Device with a physical keyboard and touch screen above –

there’s also the TrackPad back which gives you control on focus and speeds up working:

classic_trackpad

On a ‘normal’ Touchscreen Device (with or without a physical Keyboard) most times you’re not thinking about foucs: you touch on a UI Control or ActionItem and then something happens or you scroll through the content (using your fingers on touchable screen or on touchable keyboard on BlackBerry Passport)

Using a TrackPad is different. Think using a very small TouchPad outside of your TouchScreen or using a Mouse with clickable TrackWeel.

The TrackPad makes it very easy to move around on your screen and to ‘click’ on something. Of course you want to know which UI Control gets the Focus before clicking on it. In most cases Cascades does this for you and highlights the control getting the focus.

Here’s a TabbedPane where the actualTab is selected as usual:

select_vs_focus

While using the TrackPad the focus was shown to let you know which Tab gets the focus. Clicking on the Tab with focus selects this Tab.

Using a TrackPad you – as a developer – must always think about focus vs selected. For users of your app it should be easy to distinguish.

For this TabbedPane Cascades uses different background colors from the uipalette of your Theme to highlight the control with focus.

There are some UI Controls not getting focus by default: per ex. Labels, Containers, ImageView.

Here’s an ImageView using focusPolicy to let Cascades know that this control needs to get the focus:

ImageView {
    id: startButton
    navigation {
        focusPolicy: NavigationFocusPolicy.Focusable
    }
    // ...
    gestureHandlers: [
        TapHandler {
            onTapped: {
                // doSomething
            }
        }
    ]
}

Using the TrackPad and ‘clicking’ on the Image will be the same as tapping on it: the onTapped() was executed – so it’s the same as tapping with a finger on it.

Tip: don’t use onTouch() instead of TapHandler – clicking the TrackPad will do nothing !

Using the NavigationPolicy.Focusable Cascades will highlight the ImageView with focus:

00_focus_startbutton

There are two lines at top and bottom and the background is slightly different. If this is ok for you, you’re done.

There will be situations where you want to change something more. Here’s another ImageView used as a placeholder for an empty list as long as there’s no data to be displayed. The Image has a Taphandler and ‘clicked’ there will be some informations for the user why there’s no data.

Here are the ImageViews on bright or dark theme and NO focus:

01_no_focus

Before going on with focus from TrackPad take a look at the ActionBar: the Signature ActionItem in the middle is disabled, because we don’t have data.

NEVER disable a Signature ActionItem ! Signature Actionitems are colored and it’s not easy to know if it’s enabled or disabled – a better way is to remove the ActionItem and to add as soon as there’s some data:

01_no_signature

Adding or removing is easy done:

    attachedObjects: [
        ActionItem {
            id: summaryOpenAction
            title: qsTr("Summary")
            imageSource: "asset:///images/ic_calendar_month.png"
            ActionBar.placement: ActionBarPlacement.Signature
            onTriggered: {
                navigationPane.pushTimeSummaryOpen()
            }
        }
    ]
ScrollView {
    id: scrollView
    visible: false
    onVisibleChanged: {
        if(visible){
            removeAction(summaryOpenAction)
        } else {
            addAction(summaryOpenAction)
        }
    }
    // ...

and now the ImageView with focus from TrackPad navigation:

02_default_focus

Cascades allows you to customize the colors or to change the brightness or saturation.

Same ImageViews customized:

03_customized

The Label on top of the ImageView becomes red if focused and the brightness was changed so the user knows immediately which control has focus.

 

Container {
    ImageView {
        id: image_01
        navigation.focusPolicy: NavigationFocusPolicy.Focusable
        //...
        effects: [
            BrightnessEffect {
                enabled: image_01.navigation.wantsHighlight
                brightness: rootPane.isDark()? 50.0 : -10.0
            }
        ]
    }
    Label {
        id: label_01
        text: ""
        //...
        textStyle.color: image_01.navigation.wantsHighlight? Color.Red :Color.Black
    }
    gestureHandlers: [
        TapHandler {
            onTapped: {
                doSomething()
            }
        }
    ]
    // ...

The ImageView gets NavigationFocusPolicy.Focusable and a BrightnessEffect with different values for dark or bright theme.

Text color of the Label changes from black to red as soon as the ImageView wants to be highlighted.

Tip: Don’t forget: if coloring Labels try to use Colors from your uipalette.

Below you can see some Labels using uipalette.primaryBase and uipalette.primary:

08_palette_colors

Label {
     text: qsTr("in")
     textStyle.fontSize: FontSize.Large
     textStyle.color: ui.palette.primaryBase
 }
 Label {
     id: daysLeftLabel
     text: ""
     textStyle.fontSize: FontSize.XXLarge
     textStyle.color: ui.palette.primary
 }
 Label {
     text: qsTr("days")
     textStyle.fontSize: FontSize.Large
     textStyle.color: ui.palette.primaryBase
 }

Documentation TrackPad, BrightnessEffect

stay tuned – more info HowTo support BlackBerry Classic will follow.

This is part #2 of my blog series ‘Supporting BlackBerry Classic’ as native BlackBerry10 developer.

Please read about screen sizes and first steps here.

Shortcuts

Shortcuts are a powerful concept to help users to navigate through your app using the keyboard. BlackBerry Q10 and Q5 were the first devices with full QWERTY / QWERTZ keyboard for BlackBerry 10 followed by BlackBerry Passport. Read about differences between Q10 and Passport here.

Device Shortcuts

Doing a long-press on a key using OS 10.2 / 10.3.0 you could add a speed-dial – shortcut.

OS 10.3.1 and BlackBerry Classic are offering much more options what to do from long-pressing a key:

01_longpress

YES gives you some options:

02_assign_shortcut

03_other_shortcuts

From Settings | Shortcuts …

04_settings_shortcuts

… it’s easy to get an overview of all assigned keys:

05_settings_shortcuts_overview

It’s a good idea to explain to your users HowTo define a shortcut to open your app with a single longpress.

Shortcuts inside your APP

The easiest way to use Shortcuts inside your App is to add them to your Actions:

actions: [
        ActionItem {
            title: qsTr("Edit Pos") + Retranslate.onLanguageChanged
            imageSource: "asset:///images/ic_view_list.png"
            ActionBar.placement: ActionBarPlacement.Signature
            onTriggered: {
                // do your stuff
            }
            shortcuts: [
                SystemShortcut {
                    type: SystemShortcuts.Edit
                }
            ]
        },
        ActionItem {
            title: qsTr("Map of this site") + Retranslate.onLanguageChanged
            imageSource: "asset:///images/ic_map.png"
            ActionBar.placement: ActionBarPlacement.InOverflow
            onTriggered: {
                // do your stuff
            }
            shortcuts: [
                Shortcut {
                    key: qsTr("m")
                }
            ]
        }
    ]

There are two different types of shortcuts:

  • SystemShortcut
  • Shortcut

SystemShortcuts will be translated by Cascades – to avoid collisions it’s recommended to translate your custom Shortcuts using qsTr(“xxx”)

Opening the Menu, Users will see the small letter of the shortcut – so it’s easy to learn and understand them:

06_actions_w_shortcut

You can add Shortcuts also to Tabs, Images, Pages, …

Here’s a (simplified) Layout from one of my apps where Shortcuts are defined at Page level and working great on OS 10.2.x (Q5, Q10) and also OS 10.3.0 (Passport):

shortcuts1

Running the same app on OS 10.3.1 and BlackBerry Classic the Shortcuts stopped working.

BlackBerry Classic and Trackpad are changing the way UI Controls can be focussed or selected. (Will blog about this in Part #3)

So I tried to place the Shortcuts at the Container and it still didn’t work. Then I tried to place them at the ListView because the ListView is the UI Control the TrackPad is using to scroll and to focus. Voilá: This was working on BlackBerry Classic:

shortcuts2

But it only works on 10.3.1 and Classic – not on 10.3.0 and Passport – so I added a switch like this:

// ...
attachedObjects: [
    ComponentDefinition {
        id: myShortcutComponent
        SystemShortcut {
            type: SystemShortcuts.Search
            onTriggered: {
                // do your stuff
            }
        }
    }
]
// ...
if (app.isPassport()){
    myPage.shortcuts = [myShortcutComponent.createObject()]
    } else {
     myListView.shortcuts = [myShortcutComponent.createObject()]
}
    ]

Now my app is working fine on 10.3.0 / 10.3.1 and Passport or Classic.

There were no problems using KeyListeners. Shortcuts are bound to a specific UI Control, where KeyListeners can be everywhere and if a Key wasn’t catched it goes up to the parent until root object is reached. I’m using KeyListener for attached external Keyboards and handling ESC for Back, Arrows etc.

Sample at Github

To see Shortcuts in action I created a sample at Github.

github_shortcuts

Curious: Now from this small sample app OS 10.3.1 and Classic also work fine using Shortcuts at Page level. Haven’t figured out what makes it different in my more complex app. At Cascades Forum I noticed that other’s also have some problems with Shortcuts on 10.3.1 / Classic. So if you’re running into this try to move the Shortcuts to the UI Control getting the focus from Trackpad.

Have Fun with the Classic and stay tuned for Part #3 about Focus and TrackPad.

BlackBerry Classic was just launched on 2014-12-17 and – like BlackBerry Passport – introduces some new ways to navigate through the apps. It’s new for BlackBerry10 Apps, but for users coming from Bold 9900 or so it’s the classic way to navigate.

BlackBerry Passport introduced a touchable Keyboard and a large square screen (1440×1440) with high density. BlackBerry Passport also was the first device with OS 10.3.0. I wrote a blog series ‘HowTo support BlackBerry Passport‘ – you should read this first, because some new ways to develop native BlackBerry 10 apps (like Design Units – du) are explained in detail.

BlackBerry Classic introduced the TrackPad and some hardware keys users voted for. BlackBerry Classic is the first device running OS 10.3.1. All existing devices  running OS 10.2 will also get an update to 10.3.1 in first quarter of 2015.

This blog series will give you some tips and tricks HowTo support the Classic from your native BlackBerry 10 apps. In most cases there’s nothing you have to do to make your apps run on Classic, but to support all new features best and to provide the native UX there will be some work. It’s also a good idea for all your apps to support OS 10.3.1 – then your apps will look and work great in 2015 on all devices

Screen Size

If your app already supports the Q10, your app will display content correct, because both devices are square and have 720 x 720 Pixel.

But there are differences: the Classic screen is larger with 3.5″ where the Q10 has 3.1″ – the density of Classic is lower: 294 ppi (Q10 328 ppi)

classic_q10_device

If you’re using OS 10.2 or design your screens the old way using pixel, your app will display the same content on Classic as on Q10 – so your app won’t profit from the extra space. That’s why – starting with OS 10.3.0 and Passport – you should use Design units (ui).

classic_q10_du

Using design units you’ll get an extra row in lists or see more text. To understand du’s please read also my blog from ‘Support Passport‘ series.

The good thing for all your Icons: if you already support the Z30 with 8ppd – Cascades will use them on BlackBerry Classic.

Navigation concept

The Passport was the first BlackBerry 10 device offering a second touchable area outside the touch screen itself: the Keyboard. Read all about the Passport from my blog series here.

BlackBerry Classic does the same but different: Between the touchscreen and physical keyboard you’ll find the BlackBerry Toolbelt with the TrackPad in the middle:

classic_kbd

If you ever used a legacy BlackBerry like Bold 9900 you already know the toolbelt – now BlackBerry makes this available for BlackBerry 10.

There’s no other way I know to navigate fast through your apps and typing as using a BlackBerry physical keyboard together with the toolbelt. The best is to test it out – you really must feel this under your thumbs. There are also some articles and videos available at blackberry blogs. My blog series explains what this means to you as a developer of native BlackBerry 10 apps.

OS 10.3.1 – external Keyboards

The Classic is also the first device using OS 10.3.1 which will be available for all devices soon in 2015.

One of the most important – and long missed – features for business apps is supporting international keyboard layouts if connecting external keyboards via Bluetooth or USB.

ext_kbd_layouts

Using a Classic in normal situations you don’t need an external keyboard, but for mobile-only scenarios where you connect the device to a large screen via HDMI / Miracast and an external keyboard via Bluetooth / USB it makes sense. OS 10.3.1 will also run on touch-only devices like Z30 where from time to time it’s a great idea to enter long text from a physical keyboard.

OS 10.3.1 and Bluetooth issues

Over all I had less issues while testing OS 10.3.1 early releases – and these issues were some ‘special’ issues not targeting most of you.

If you explore all the Bluetooth stuff you’ll notice many new functions and API for 10.3.1. It’s great to see that BlackBerry is working on this and most enhancements will cover Bluetooth LE.

I detected the issues from an app supporting the ‘old’ Bluetooth to connect Scanner and mobile Printer via serial protocol (SPP). In my usecase customer has only this app in work perimeter using Bluetooth – so to reduce battery consumption while launching the app I switched Bluetooth on, then wait for the event BT_EVT_RADIO_INIT before connecting my devices. Closing the app, Bluetooth was switched off automatically by the app.

Worked fine under 10.2 and 10.3.0 on Passport, but failed on 10.3.1. From my tests I found out that there are some new Events for 10.3.1, but two of the existing events were not sent:

  • BT_EVT_RADIO_SHUTDOWN
  • BT_EVT_RADIO_INIT

Thanks to @jcmrim pointing me to the right direction to find the reason and a workaround. There’s a new filtering option on 10.3.1 – see here. From docs the default is NOT filtering, so all events should come through. Setting this default manually again will bring back the missing events 🙂

int filterSuccess =  bt_ldev_set_filters(BT_EVT_ALL_EVENT, true);
if(filterSuccess == -1){
    qWarning() << "Filtering wrong " << filterSuccess;
}

The other issue happens if more then one Bluetooth device is connected via SPP to the BlackBerry – in my use-case a Scanner together with a Printer. Disconnecting one of the devices – per ex. while changing the battery – also disconnects the other one. Worked well on 10.2 and 10.3.0 on Passport but not on 10.3.1 and Classic. This issue is reported to BlackBerry and I got info it’s already fixed and will be available soon.

In my app I made it easy to re-connect using NFC, so it’s only one extra tap to work on. (will blog about this Bluetooth App soon)

OS 10.3.1 and ‘TabbedPane-inside-Sheet’ issue

One of my apps (SerCar10 for ServiceCars) is a complex app supporting different users with different roles like office, sales, driver, dispatcher, …

My first idea was to develop some small apps and “connect” those feature-apps using InvokationFramework and CARDs. The integration I needed was too deep, so I had to put it all into one big app where UI will look different for different roles: a service car driver can only select parts from a list and add to the work order, where from office this list can be managed (add, edit, delete).

Finally I separated modules using their own TabbedPane to make it easy to navigate. This means some users with some roles must get access to more then one module and so I created a hierarchical TabbedPane, which is no default Cascades UI Control. But there are Sheets to separate a sub-workflow and Sheets can have a Pane as root element: doesn’t matter if it’s a NavigationPane or a TabbedPane. So I’m using Sheets to separate the modules.

Here’s a short sample so you can understand better:

The usual root TabbedPane will push another TabbePane on top, which means: a Sheet was opened with another TabbedPane on board. In this case the ‘Data’ Tab from root TabbedPane opens another TabbedPane on top from where office employee can edit some data.

01_root_tabbed_pane

This (Sub) TabbedPane works same way as the root TabbedPane. Here you get acces to lists of Units, Groups, Parts, Contacts with CRUD functionality. Because it’s a Sheet you can peek back but not close the Sheet by swiping.

02_data_ tabbed_pane

Normaly there would be buttons like OK and Cancel to exit a Sheet. For my (sub) TabbedPanes I’m using a special (Back) Tab at the bottom to go back explicitely.

03_back_to_root

Going back the Sheet and all content was destroyed to free up memory.

So far so good. Works on 10.2 and 10.3.0 but crashed the app on 10.3.1

Took some time to figure out what happened and to find a workaround. The TabbedPane was created together with the Sheet and this won’t work anymore. Using an empty Page instead and creating the (Sub) TabbedPane with a delay of 30 ms makes it run on 10.3.1 🙂

Sheet {
    id: dataEntrySheet
    onClosed: {
        // ....
    }
    attachedObjects: [
        DataEntryTabbedPane {
            id: tabbedPane
        },
        QTimer {
            id: startupDelayedTimer
            interval: 30
            singleShot: true
            onTimeout: {
                dataEntrySheet.setContent(tabbedPane)
            }
        }
    ]
    Page {
        // DUMMY
    }

    onCreationCompleted: {
        startupDelayedTimer.start()
    }
}

The good thing: there’s no flicker or so while creating the TabbedPane.

again: not a common use-case but perhaps you run into similar situations and using a QTimer to create Controls async can help.

UX on Classic

I tested my apps on BlackBerry Classic and found some layouts looking ugly while navigating using the TrackPad. This was expected because now there’s a special highlight color for List Rows or UI Controls with focus from TrackPad and if you’re already using colored text or images the highlighting must be adjusted.

Also found some workflows with different behaviour between Passport and Classic – esp. if using Shortcuts and KeyListener.

I’ll report about my experiences and solutions in detail to help you to provide smooth workflows.

The great thing: Cascades offers all you need from new OS 10.3.1 API to provide great UX on all devices 🙂

Please stay tuned for the next parts coming soon.

Over all it’s really fun to navigate through BlackBerry10 apps from TrackPad. This enables me to design fast and smooth workflows in business apps which will make users more productive.

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.

kbd_q10_pp

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 (http://TimeTracker10.org)

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

q10_segmented_tb

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:

q10_numbered_keys

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:

passport_segmented_tb

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:

IMG_20140903_130049

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 TimeTracker10.org. At the end I had to change some qml files and some background images.

asset_selector

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

TitleBar

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

titlebar_dark

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:

titlebar_bright

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:

titlebar_free

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.

ActionBar

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

specialAction

Here are ActionBars using a dark theme:

actionBar

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:

actionBarBright

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:

homepage

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
            homePage.reLayout(orientation)
        }
    },
    // ...
]

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: {
            if(app.isPassport()){
                return
            }
            // do your re-layouting stuff
            homePage.reLayout(orientation)
        }
    },
    // ...
]

TextFields

Disabled TextFields look much different on 10.3:

disabled_text

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:

textfields_dark

10.3. again uses slightly less space then 10.2

and here’s the same on a bright theme:

textfields_bright

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:

toggle_button

Please check if your layout is still looking good.

Images

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:

bg_z30

and here on Passport:

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

Relayouting

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:

home_z30_portrait

home_z30_landscape

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

home_q10

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

home_passport

Another Page I did an extra layout for Passport:

On Z30:

time_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:

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

If you’re NOT developing for BlackBerry 10 platform perhaps your users are complaining apps running too slow.

Speedy Q10

On BlackBerry 10 you have to think ahead because apps are running so incredible fast – esp. using Keyboard devices like Q10 – that you run into situations not thinking about on a ‘normal’ smartphone.

You speed up users workflow using shortcuts:

E → 12 → enter

and you’re done with:

  • tip on E to edit the quantity of an order position
  • new page opens
  • curser already in quantity field
  • keyboard switched to numeric mode
  • type 12 as new quantity
  • tip on ENTER key
  • new quantity saved
  • page closed
  • list summary recalculated

this is an intuitive and fast way to work with business apps on a smartphone.

And sometimes it can be too fast 😉

DeleteAction on Z10 (Touch)

As a good citizen of Cascades UI design guidelines you’re using a special ActionItem to delete a row in a list or so:

DeleteActionItem {
    id: deletePositionAction
    title: qsTr("Delete Position") + Retranslate.onLanguageChanged
    ActionBar.placement: ActionBarPlacement.InOverflow
    onTriggered: {
        // delete the position
    }
}

Delete actions are always placed at the bottom of your menu. Here’s how it looks like on a Touch Device:

menu

To get something deleted you have to do a first tap to get the menu:

overflow-menu-on-Z10

then you have to tap on the delete action:

delete-on-Z10

there’s enough time to decide what to do and you have to tap directly on the delete action, so normaly you don’t ask the user “do you really want to delete this item ?”

DeleteAction on Q10 (Keyboard)

Now on Q10 the situation is different using shortcuts. You must know that Cascades automatically maps some actions to keys – and this will work in all applications without the need for you to code this by yourself. If a user on the Q10 taps on the menu, then the keyboard shortcuts become visible:

menu_marked_keys

the DEL – key is mapped to the Delete Action. automatically.

the E – key is mapped to the Edit Quantity Action by me as a SystemShortcut:

SystemShortcut {
    type: SystemShortcuts.Edit
}

Because I want to edit something, I’m using one of the SystemShortcuts instead of my own custom ShortCuts.

Now we enter the dangerous area 😉

detail_on_device

If the user tips on the DEL key here, the delete action will be triggered. without any warning. perhaps it was the wrong key and the user wanted to type P or ENTER.

You have to find a way to avoid this.

Undo – the user-friendly solution

Normaly converting apps from Touch (Z10) to Keyboard (Q10) is easy and soon done – but you should carefully test your app on Q10 to find hidden traps.

What can you do to avoid deleting a record by accident ? the easiest way would be to insert a yes/no SystemDialog and always ask if the record should be deleted. But now you’re breaking the users workflow. not so good.

here’s one solution:

  • on Z10 use it as before
  • on Q10 add an Undo function

Undo must be implemented a way not breaking users flow. There is a UI control you can use for this: Cascades SystemToast: a small popup window going away after a short time. And here’s my solution:

If DeleteAction is triggered, test if you’re on a keyboard device and if so, don’t execute the delete logic. Instead of this I’m changing the Icon of the list row and bring up a Toast with the same icon and some text to inform the user.

SystemToast {
    id: deleteToast
    body: qsTr("Position will be deleted") + Retranslate.onLanguageChanged
    icon: "asset:///images/position_to_be_deleted_small.png"
    position: SystemUiPosition.BottomCenter
    button.label: qsTr("Undo")
    onFinished: {
        if(deleteToast.orderId > 0){
            if (value == SystemUiResult.ButtonSelection) { 
                // UNDO clicked - revert to normal Icon in this case
            } else {
                // do your DELETE stuff
            }
        }
    }
}

undo_on_device

Now it’s up to the user:

  • if DEL was done by accident click on the Undo button an all will change back to normal
  • if DEL is what user wants to do simply follow the workflow – ther Toast will disappear automatically

From my POV this is an elegant way to solve this situation: user has full control and workflow not broken 🙂

The Video

here’s a short video where you can see how it works before and after:

Some tips for developers implementing such a solution

Toasts will go away after a short time, but you cannot set this delay. Toasts with a button will remain on screen until user does some work on UI, which will start the countdown until Toast disappears. In some situations this is too long for me, so I want to dismiss the Toast per ex. if user triggers another action, clicks the back button or something else.

cancel() on a Toast will stop and hide the toast immediately. cool. or not ? If Toast is canceled means, user has NOT clicked the Undo Button, so the data can be deleted.

But cancel() doesn’t trigger the onFinshed() at Toast. with a little trick this will work:

add a boolean property ‘killed’ to the Toast, fire this if you cancel() the Toast and now onKilled() at the Toast can execute the same delete- businesslogic as onFinished() from TimeOut.

I will publish some code on this later and will also add this pattern to my workshops on Cascades, because you’ll need this all the time in business apps.

Have fun with Q10

If you need an App: I’m developing quality BlackBerry10 APPS for customers around the world 😉
If you want to write such kind of apps by yourself: You can book a training (in german or english)

ekke

OpenDataSpace just got some updates: most important one is the support of BlackBerry Q10 with physical keyboard.

We also added an Action to ApplicationMenu: FAQ, where you find answers for your questions or can add new questions.

Here are some screenshots, so you can imagine how it looks on the Q10.

Screenshots on the device are made using Heiko Behrens ShapeItApp

Login into OpenDataSpace:

ods-login-q10

Some DataRooms and Content listed on Q10:

ods-datarooms-q10

ods-dataroom-content-q10

All the functionality from Touch devices like Peek-back are also available on Q10 of course:

ods-peek-q10

As you can see, on Q10 OpenDataSpace is using a dark theme, where on the Z10 we’re using the bright one. It’s recommended to use a dark theme because of the OLED and will give you more battery power.

OpenDataSpace now also has specific Images as Scene Cover if minimized (running in background):

ods-minimized

OpenDataSpace is available from BlackBerry World

the app is FREE and there’s also a FREE account from ods for up to 5 users and 2 GB Data Space.

Sources are available at Github (Open Source)

OpenDataSpace is Built For BlackBerry

BuiltForBlackBerry