Physical keyboard shortcuts

The concept of physical keyboard shortcuts applies only to Cascades. If you want to listen for physical keyboard events using C, see Low-level keyboard events which applies to both the physical and touch screen keyboards.

Keyboard shortcuts provide a way to perform actions in your Cascades app using specified keys on the keyboard. Keyboard shortcuts improve usability and user experience by decreasing the effort required to perform commonly used actions in an application. For example, you could implement a shortcut to create an entry, scroll to the top of a page, or power up your character during gameplay.

Keyboard shortcuts are supported only on devices with a physical keyboard. On all-touch devices, keyboard shortcuts aren't available. However, you have more screen space to work with on these devices, so you might choose to provide additional options in your UI to make up for the lack of shortcuts.

It's important to remember that shortcuts are not the only way to perform the desired action in your app. They're just shortcuts after all.

System shortcuts

System shortcuts are intended for actions that are common to many apps, such as search, create new, or zoom. The functionality for these common features doesn't need to be identical from app to app, but they should be conceptually related.

The image to the right shows how a system shortcut is implemented in the Calendar app. When the C key is pressed, the SystemShortcuts::CreateNew shortcut is invoked. Within the scope of the Calendar app, the shortcut creates a calendar entry.

Your app doesn't know how to respond to a system shortcut automatically, so you’ll have to provide the logic. In the above example, invoking the CreateNew shortcut creates a calendar entry, but invoking the CreateNew shortcut in BlackBerry Hub creates an email message.

System shortcut used in the Calendar app.

Best practices

Implement system shortcuts wherever possible in your app. If your app uses features such as create new, reply, or search, implement the appropriate system shortcut to improve ease of use.

Avoid using a system shortcut to do something it wasn't intended to do. For example, if your app has a "sort" action, avoid using the "search" system shortcut because they start with the same letter.

Attach system shortcuts directly to an ActionItem .

Creating system shortcuts

Here's how to attach a SystemShortcut to an existing ActionItem, in QML:

import bb.cascades 1.1

Page {
    TextArea {
        id: shortcutText
        text: ""
    }

    actions: [
        ActionItem {
            id: action1
            title: "myActionTitle"
            ActionBar.placement: ActionBarPlacement.OnBar 
            onTriggered: {
                shortcutText.text += " action1 ActionItem triggered\n"
            }
 
            shortcuts: [
                SystemShortcut {
                    type: SystemShortcuts.CreateNew
                    onTriggered: {
                        shortcutText.text += " action1 CreateNew 
                        shortcut triggered\n"
                    }
                }
            ]
        }
    ]
}
ActionItem* actionItem1 = ActionItem::create().title("myActionTitle1");
SystemShortcut* systemShortcut = new 
SystemShortcut(SystemShortcuts::CreateNew);

// If any Q_ASSERT statement(s) indicate that the slot failed to connect to 
// the signal, make sure you know exactly why this has happened. This is not
// normal, and will cause your app to stop working!!
bool connectResult;

// Since the variable is not used in the app, this is added to avoid a 
// compiler warning.
Q_UNUSED(connectResult);

connectResult = connect(systemShortcut, SIGNAL(triggered()), this,
                        SLOT(onSystemShortcut()));

// This is only available in Debug builds.
Q_ASSERT(connectResult);

Page* myPage = Page::create();
myPage->addAction(actionItem1, ActionBarPlacement::OnBar);
actionItem1->addShortcut(systemShortcut);

Not applicable

The benefit of system shortcuts is familiarity for the user. The system defines the key associated with each system shortcut type and the value cannot be changed. For example, C is always the CreateNew shortcut in the English version of an app. Users can expect that pressing C creates an entry, note, or whatever else applies in the context of the app. This consistency allows users to quickly become comfortable and proficient when using an app for the first time.

System shortcuts can be different from language to language. For example, T (meaning top) may be the shortcut for scrolling to the top of a page in an English-based app, while P (meaning parte superior which roughly translates to "top part") is the translation for the same shortcut in Spanish.

Supported shortcut types

The following table provides the supported SystemShortcut types, the English locale key associated with the shortcut types, and their function.

Type

Key

Function

CreateNew

C

Create an entry

Edit

E

Edit current content

Forward

F

Forward a message

JumpToBottom

B

Jump to bottom

JumpToTop

T

Jump to top

NextSection

N

Jump to the next section

PreviousSection

P

Jump to the previous section

Reply

R

Reply to a message

ScrollDownOneScreen

Space

Scroll down one screen

ScrollUpOneScreen

Shift + Space

Scroll up one screen

Search

S

Start a search

Undo

U

Undo

ZoomIn

I

Zoom in

ZoomOut

O

Zoom out

Localized system shortcuts

The following table provides the localized system shortcut for each of the system shortcut types.

Type

English

German

Spanish

French

Italian

CreateNew

C

C

C

N

N

Edit

E

E

E

E

E

Forward

F

F

V

F

I

JumpToTop

T

T

P

T

A

JumpToBottom

B

B

F

B

B

NextSection

N

N

S

S

S

PreviousSection

P

P

A

P

P

Reply

R

R

R

R

R

ScrollDownOneScreen

Space

Space

Space

Space

Space

ScrollUpOneScreen

Shift + Space

Shift + Space

Shift + Space

Shift + Space

Shift + Space

Search

S

S

B

C

C

Undo

U

U

D

A

D

ZoomIn

I

I

I

I

I

ZoomOut

O

O

O

O

O

Key shortcuts

Key shortcuts, also known as shortcuts, are used for actions that are conceptually specific to an application. For example, a camera app can have a shortcut to turn on the camera light, or a game can have a "jump to hyperspace" shortcut. These features are typically unique to a single app and not widely supported elsewhere.

The image to the right shows a key shortcut from the Calculator app. When the Enter key is pressed, the equation is calculated.

Key shortcuts differ from system shortcuts in how they are defined. You can choose the key that triggers the shortcut by specifying a key property, and the system does not automatically translate the shortcuts. Like system shortcuts, you need to provide the logic for how your app responds to a shortcut event.

Key shortcut used in the Calculator app.

Best practices

Use system shortcuts over key shortcuts whenever possible. If a system shortcut is available, avoid overlapping functionality by creating a custom key shortcut to perform the same task.

Be careful when mixing system shortcuts with key shortcuts. Because system shortcuts are automatically translated, and key shortcut translations need to be explicitly defined, you run the risk of duplication. Creating a key shortcut that uses the same key as a system shortcut may cause the system shortcut to be ignored.

Attach shortcuts directly to an ActionItem .

Creating key shortcuts

To create a key shortcut, attach a Shortcut object, define the key property, and specify the logic for the onTriggered signal event. Single characters and modifiers are supported as possible values for the key property (C, !, Alt + G, and Shift + B are acceptable), while multiple characters (Alt + LGX for example) are not supported. If multiple modifier keys are used (Shift + Alt + H for example), the order in which the modifier keys are pressed affects how the shortcut is triggered. A shortcut with a key property of Shift + Alt + H requires the user to press Alt + Right-Shift to enable shift-lock mode, then Alt, then H to trigger the shortcut. In addition, the key parameter is case insensitive, so Alt + h is equivalent to Alt + H.

import bb.cascades 1.1

Page {
    TextArea {
        id: shortcutText
        text: ""
    }

    actions: [
        ActionItem {
            id: action1
            title: "myActionTitle"
            imageSource: "asset:///myImageName"
            ActionBar.placement: ActionBarPlacement.OnBar 
            onTriggered: {
                shortcutText.text += " action1 ActionItem triggered\n"
            }
 
            shortcuts: [
                Shortcut {
                    key: qsTr("x")
                    onTriggered: {
                        shortcutText.text += " action1 CreateNew 
                        shortcut triggered\n"
                    }
                }
            ]
        }
    ]
}
ActionItem* actionItem2 = ActionItem::create().title("myActionTitle");
Shortcut* myShortcut = Shortcut::create()
        .key("x")
        .onTriggered(this, SLOT(onKeyShortcut()));

myPage->addAction(actionItem2, ActionBarPlacement::OnBar);
actionItem2->addShortcut(myShortcut);

Not applicable

You can define shortcuts for controls that are not focusable by default. For controls that do not have a FocusPolicy , you must define one explicitly using the focusPolicy property to use the shortcut feature.

Container {
    focusPolicy: FocusPolicy.KeyAndTouch
    Label {
            focusPolicy: FocusPolicy.KeyAndTouch
    }
}

Coming soon

Not applicable

Shortcuts also support the use of localization by declaring the key property as a QString and adding Retranslate.onLanguageChanged . Translating shortcuts also requires the use of a modifier in the string.

import bb.cascades 1.1

Page {
    TextArea {
        id: shortcutText
        text: ""
    }

    actions: [
        ActionItem {
            id: action1
            title: "myActionTitle"
            imageSource: "asset:///myImageName"
            ActionBar.placement: ActionBarPlacement.OnBar 
            onTriggered: {
                shortcutText.text += " action1 ActionItem triggered\n"
            }
 
            shortcuts: [
                Shortcut {
                    key: qsTr("Alt + x") + Retranslate.onLanguageChanged
                    onTriggered: {
                        shortcutText.text += " action1 CreateNew 
                        shortcut triggered\n"
                    }
                }
            ]
        }
    ]
}

Coming soon

Not applicable

Control shortcuts

Control shortcuts consist of a set of system shortcuts applied to a Cascades UI object, typically a control. Control shortcuts are applied by default and are designed to improve navigation of controls and increase efficiency.

The image to the right shows an example of a commonly used control shortcut for ListView . When a ListView is in focus, pressing the T key automatically scrolls the list to the top.

The following examples illustrate a few of the supported control shortcuts in a ListView:

  • Space: Scroll down one screen
  • Shift + Space: Scroll up one screen
  • T: Jump to top
  • B: Jump to bottom
  • N: Jump to next section
  • P: Jump to previous section
Control shortcut in a list view.

There are some situations where you may need to manage focus to make sure control shortcuts work correctly. For example, if you use two ListView objects on a single screen, your application needs to switch focus between the ListView objects when a user interacts with them to ensure that the shortcut events apply to the correct ListView.

Best practices

Be careful when mixing control shortcuts with key shortcuts. If you define a key property for your app that is already a system shortcut, the key shortcut overrides the control shortcut.

Don't attach additional system or key shortcuts to a control. Although it's possible to do so, it's not recommended. The best practice for implementing shortcuts is to attach them directly to an ActionItem.

Event propagation for shortcuts

A shortcut event is triggered when the key assigned to a Shortcut or SystemShortcut object is pressed.

When a shortcut event is triggered, the event propagates from the control in focus up to the root of the scene. If no control is in focus, all shortcut events propagate to the root. If a match is found, the action is performed and the event is consumed. The best practice for implementing shortcuts is to attach them to an ActionItem at the root of the scene (such as a Page ), or to an ActionItem of an individual control. If you attach a shortcut to an ActionItem on a control, the control must be in focus.

The following diagram demonstrates the shortcut traversal process:

Diagram showing shortcut event propagation.

For shortcuts attached to an AbstractActionItem , when a shortcut is triggered, the triggered signal for the AbstractActionItem is emitted as well.

If you want to use a shortcut on a CustomControl, you need to use the inputRoute.primaryKeyTarget property to set the CustomControl as a target for the key event. Setting inputRoute.primaryKeyTarget to true allows the shortcut to emit a triggered() signal when the assigned shortcut key is pressed.

Last modified: 2015-07-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus