Keyboard shortcuts

Keyboard shortcuts provide a way to perform an action in your Cascades app using a predefined key from 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 a new 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 full-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 just shortcuts. Make sure the shortcut is not the only way to perform the desired action in your app.

Cascades supports different types of shortcuts that you can use in your app. Keyboard shortcuts are available with an API level of 10.1 or later.

System shortcuts

System shortcuts are intended for actions that are common to many applications, such as search, create new, or zoom. The functionality for these common features doesn't need to be identical from app to app to, just 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, this creates a new calendar entry.

Your app doesn't know how to respond to a system shortcut automatically, so you’ll still have to provide the logic. In the above example, invoking the CreateNew shortcut creates a new calendar entry, but invoking the CreateNew shortcut in BlackBerry Hub creates a new 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. If your app has an option to sort, avoid using the search system shortcut to perform the action you want just because the shortcut key starts with the desired letter.

Attach system shortcuts directly to an ActionItem.

Creating system shortcuts

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

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"
                    }
                }
            ]
        }
    ]
}

Here's how to do the same thing in C++:

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);

The benefit of system shortcuts is familiarity for the user. The key that is associated with each system shortcut type is predefined by the system and cannot be changed, except through translation. This means that C will always be tied to the CreateNew shortcut in the English version of an app. Users can expect that pressing C creates a new entry, note, or whatever it is they want to create depending on the context of the app. This consistency allows users to quickly become comfortable and proficient when using an app for the first time.

The only time this key will change is when using a different 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 the shortcut types, and their function.

Type

Key

Function

ScrollDownOneScreen

Space

Scroll down one screen

ScrollUpOneScreen

Shift + Space

Scroll up one screen

ZoomIn

I

Zoom in

ZoomOut

O

Zoom out

JumpToTop

T

Jump to top

JumpToBottom

B

Jump to bottom

NextSection

N

Jump to the next section

PreviousSection

P

Jump to the previous section

Reply

R

Reply to a message

Forward

F

Forward a message

Edit

E

Edit current content

Search

S

Start a search

Undo

U

Undo

CreateNew

C

Create a new entry

Localized system shortcuts

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

Type

English

German

Spanish

French

Italian

ScrollDownOneScreen

Space

Space

Space

Space

Space

ScrollUpOneScreen

Shift + Space

Shift + Space

Shift + Space

Shift + Space

Shift + Space

ZoomIn

I

I

I

I

I

ZoomOut

O

O

O

O

O

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

Forward

F

F

V

F

I

Edit

E

E

E

E

E

Search

S

S

B

R

C

Undo

U

U

D

A

D

CreateNew

C

C

C

N

N

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 flash, or a game can have a jump to hyperspace shortcut. These features are typically unique to a single app, so there is no reason to expect these to be widely supported.

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

Key shortcuts differ from system shortcuts in how they are defined. You are able to choose the key that triggers the shortcut by specifying a key property, and shortcuts are not automatically translated by the system. 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 to perform an action, 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 in QML, 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 the modifier keys are pressed in 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.

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"
                    }
                }
            ]
        }
    ]
}

Here's how to do the same thing in C++:

ActionItem* actionItem2 = ActionItem::create().title("myActionTitle");
Shortcut* myShortcut = Shortcut::create()
        .key("x")
        .onTriggered(this, SLOT(onKeyShortcut()));

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

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 make use of the shortcut feature.

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

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.

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"
                    }
                }
            ]
        }
    ]
}

Control shortcuts

Control shortcuts consist of a set of system shortcuts applied to a Cascades UI object, typically a control. Control shortcuts are applied to specific Cascades controls by default, and are designed to ease navigation in 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 conrol 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 header
  • P: Jump to previous section header
Control shortcut in a ListView.

Control shortcuts are implemented automatically by Cascades, so you typically don't need to do any extra work in your app to use them.

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 control shortcut events are received by the correct ListView.

Best practices:

Be careful when mixing control shortcuts with key shortcuts. Key shortcuts can override system shortcuts if you define a key property for your application that is already used as a system shortcut. Because control shortcuts consist of system shortcuts, this can cause the control shortcut to be ignored.

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 currently in focus, all shortcut events are redirected 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.

For more information about the primaryKeyTarget property, see InputRouteProperties.

Last modified: 2014-09-29



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

comments powered by Disqus