Weekend Coder: Keyboard shortcuts make apps better

By Brian Scheirer on 6 Jul 2013 02:16 pm EDT

Keyboard shortcuts are the real reason why hardware keyboard phones still exist! Since I leave the editorial pieces to other writers, I won’t rant about how much I love keyboard shortcuts. Instead I’ll do what I do best and show all you fine people how to add them to your Cascades apps.

Before I get started and before anyone asks, no you can’t open the Z10 keyboard and use keyboard shortcuts, these are just for Q5 and Q10 users. On that same note the Z10 will ignore shortcut so you don’t need to repackage without shortcuts for your app to work on the Z10.

There are two main ways to define shortcuts. The shortcut can either be a “System Shortcut” or a “Custom Shortcut.” System shortcuts a list of shortcuts that the user may be familiar with based on using default apps like the Hub. For instance if you press “S” in the Hub a search bar will appear. So if your app has similar functionality you can call the system shortcut for search and when the user presses “S” you can have your search bar appear. Alternatively you could define a custom shortcut for they key “S” to do the same thing. So you may be asking yourself why use a system shortcut. The reason is system shortcuts are localized. If the user sets their language to Spanish the system shortcut for search is “B”. A full list of system shortcuts with their localized letters can be found here.

Next, I like to think of shortcuts being able to be defined in two main places, on an action and not on an action. I’d like to show you an example of each. I’ll use a mix of system and custom shortcuts to show each of those as well. Let’s first look at a system shortcut on an action, consider the following code:

import bb.cascades 1.0 Page {     //...     actions: [         ActionItem {             id: action1             title: "Search"             onTriggered: {                 //call function to open your search             }             shortcuts: [                 SystemShortcut {                     type: SystemShortcuts.Search                     onTriggered: {                         //call function to open your search                     }                 }             ]         }     ] }

This code will create an action in the overflow menu. That action can be called by opening the overflow menu and then pressing the action called “Search.” Or it can be accessed by pressing the “S” key. One neat feature you get for free when using action in the overflow menu is shortcuts automatically show in the top right corner of the action.

Looking back at the code above, realize you’ll need to put your function(s) in two signals for them both to work. It needs to be in the action itself and in the shortcut. Both of these are onTriggered signals.

Now let’s look at an example of using shortcuts that are not tied to an action. I think a great way to show this is to have a shortcut do the same thing as a Button. So the shortcut isn’t necessarily having the system press the button for you, rather you define a shortcut that does the same thing as a Button. Again let’s look at some code:

import bb.cascades 1.0 Page {     Container {         Button {             text: "Help"             onClicked: {                 mySheet.open();             }         }     }     attachedObjects: [         Sheet {             id: mySheet             //...         }     ]     shortcuts: [         Shortcut {             key: "H"             onTriggered: {                 mySheet.open();             }         }     ] }  

This code above has a Button that opens a Sheet. Also there a custom shortcut defined within main Page that defines the key “H” to open the same sheet. Custom shortcuts are limited to single keys, you can have “Shift+H” or “Alt+H” as well but not “K+H”. Additionally you can have “Enter” as shortcut. Another thing to consider when using custom shortcuts you should let your users know what they are by putting as list of them somewhere in your app. Say for example in your help Sheet:

Sheet {     id: mySheet     Page {         Container {             Label {                 text: "Press the 'H' key to open the Help.\n                 Press the 'Enter' key to close Help."                 multiline: true             }             Button {                 text: "close"                 onClicked: {                     mySheet.close();                 }             }                  }         shortcuts: [             Shortcut {                 key: "Enter"                 onTriggered: {                     mySheet.close();                 }             }         ]     } }

One last thing I’d like to bring up about shortcuts is there are a few built in for you. These are called Control Shortcuts. Much like system shortcuts, control shortcuts perform user expected actions but don’t need to be defined in any way. Say for instance if a ScrollView or ListView is the element in focus, if key “T” is pressed the ScollView/ListView will be returned to the top. Same can be done with “B” for bottom. There are few other instances of these listed in the official docs, as well as you may notice some others when playing around on your own.

Now go have fun adding shortcuts to your own apps to make hardware keyboard BlackBerry phones "better" than their full touch counterparts.

Reader comments

Weekend Coder: Keyboard shortcuts make apps better


Warning: I actually am a developer.

We should all be grateful that BlackBerry saw fit to include both those predefined SystemShortcuts and those Control shortcuts. These really didn't exist on the old BBOS, so every developer had to figure it out for themselves. It may not seem to hard on the surface, but keep in mind that these shortcuts are actually localized. If you have a Spanish or French keyboard, for example, the hotkeys for an action may actually be different. Its nice for BlackBerry to give all developers a way of handling this essentially for free.

Yes, I remember the fond days of trying to read BlackBerry user manuals in a dozen different languages, just to build a grid of the correct hotkeys to use in my apps. It wasn't fun, and I'm glad I don't have to do that again. (I'm not sure how many other developers put in the effort to do that either, which probably lead to consistency problems for non-English-typing users.)

I can confirm that on BBOS all of my apps use the English language shortcuts no matter what the local preferences were (even if it was a language that I otherwise fully supported).

Wish I had some knowledge in app writing. Should really spend some time figuring it out with all the great tools available.

Posted via CB10

Hi Brian,
if adding a shortcut to an Actionitem,
hitting the shortcut will always trigger the onTriggered{} from the Actionitem,
so in your case both onTriggered{} will be executed: at first from the shortcut, then from ActionItem.
You can test easy if trying this:
ActionItem {

id: action1
title: "Search"
onTriggered: {
console.debug("triggered by ActionItem")

shortcuts: [
SystemShortcut {
type: SystemShortcuts.Search
onTriggered: {
console.debug("triggered by Shortcut")
hitting the key you'll see both in console
this is only with ActionItems as far as I've noticed yet,
from Tabs{} you have to call the function from both: Tab and ShortCut


THANK YOU BRIAN. We need more keyboard shortcuts in apps, in the core OS, everywhere!! This is exactly what makes physical keyboards so useful. Its half the reason I'm still with BlackBerry and why I can tolerate a smaller screen. Although BlackBerry needs to make a 4in Q10 or slider.

Posted via CB10

It would be awesome if the z10 was updated so that keyboard shortcuts worked on it too!

Posted via CB10

Yeah it's a bit infuriating that the Z10 doesn’t support shortcuts, I simply ask why? Awesome gestures like two finger swipe up and boom you have all the access you need, furthermore the spacing on the z10 keyboard would allow it the space bar could be shortened a bit to allow some extra virtual keys and the asdf row has wider keys than the qwerty row allowing for an alt button so on and so forth. It seems a no brainer BlackBerry 10 virtual keyboard is the best for xyz why not at shortcuts to that list heck they could at least make it a settings option. don't get me wrong I LOVE my BlackBerry but I also want to see them differentiate in the market as many ways as possible. I also am a sicker for screen real estate that's why I wish there was a torch like slider BlackBerry 10 handset coming instead of a new bbos phone, I just wish I knew what was going on and furthermore understood any of it lol.

Posted via CB10

Edit don't know how to edit comments in CB10 anyways was supposed to read sucker.

Posted via CB10

The first reason that I have BlackBerry is the easy shortcuts when typing and work on it. I miss my old 8130 curve with all shortcuts. I hope Q 10 will be the same with that

Posted via CB10

Hey, Brian.. I just threw those into my app the other day, but I noticed that it works the exact same with the action icons not having the "OnTriggered" the second time for the shortcut part. Any idea if it's just fine to do it this way, or should you be duplicating the ontrigger?

Thanks bud!

- Developer of 'Web Design Cheat Sheet' for BB10 (Posted via CB10)

Same thing I mentioned above to Ekke, thought this was a bug. I have only been using the Gold 10.1 APIs, is 10.2 Beta the same?... Docs didn't seem to mention the best practice for this either. Perhaps I'll ask around at BBDev and see what they have to say.

Yeah. Been using 10.2 and everything seems to check out. I don't quite see why you would need to assign the function again, if you set it to something different, it overwrites it (as mentioned above) so I think it just means doing it twice is redundant. Would love to hear what the best practices are though, thanks man!

- Developer of 'Web Design Cheat Sheet' for BB10 (Posted via CB10)

Instead of talking about something we already know and honestly doesn't save that much time how about we talk about how come Z10 users in the USA still don't have 10.1 available to download...?

Posted via CB10

I'm not sure you totally understand the point of this post... judging by how 'we all already knew this', I'm guessing you have many apps on BlackBerry World.

Erm....ya think? Remember who invented the mouse, and why ;)

From a real keyboard, w/ NO autocorrect

It is unfortunate that people come here spewing nonsense, but such is life.
As for this, only thing I would point out is that this feature is 10.1 and newer only (obviously since the Q10 launched with 10.1). And unless I am missing something (and I might very well be), you cant have this in your app and release a 10.0 version.

love my keyboard for the web browsing alone!

R = reader = EASY to view web pages.
L= reload
S= search or find on the page = i use this ALOT!!!!!!!!! CAN'T do this on anything but my desktop and q10 lol