Keyboard input

BlackBerry devices can have either a physical keyboard or touch screen keyboard. For devices with a touch screen keyboard, the keyboard appears only in certain contexts (for example, when the user taps a text field). With both types of keyboards, it's possible to listen for and respond to keyboard input.

Invoking the touch screen keyboard

You can control the touch screen keyboard by using the functions defined in virtualkeyboard.h . This header file includes functionality for hiding and showing the keyboard and handling keyboard events.

Cascades does not have an API for opening and closing the touch screen keyboard. However, there still are some ways that you can invoke the touch screen keyboard. When the user taps on a TextField or a TextArea , the keyboard displays automatically to capture input. To invoke the keyboard yourself, you can call requestFocus() on the control that you want the user to type into. For more information about how text controls handle input, see Handling text input .

Low-level keyboard events

Low-level keyboard input events are delivered to the app through the SCREEN_EVENT_KEYBOARD event type. You can access the events directly through the Screen API or you can register for the events through BlackBerry Platform Services (BPS). If you want to capture keyboard events that are specific to a certain area of the screen (for example, a text field) you can use input sessions.

Input sessions allow your app to capture events that are specific to a certain region, device, or screen event type. For example, you can create a session when a text field receives input focus in order to capture text entry in that field, and then destroy the session upon losing input focus. Sessions aren't restricted to on-screen events. You can create sessions to capture off-screen events from a gamepad, keyboard, mouse (or other pointing device), or the touch-sensitive keyboard.

Cascades keyboard events

In Cascades, you can use a KeyListener object to listen for any key press that produces a character (any key except for modifier keys such as the Shift, Alt, and Control). However, any key press that generates a character provides information about the state of the modifier keys in its event parameters. Unlike physical keyboard shortcuts, KeyListener events support both the physical and touch screen keyboards. In addition to the types of keyboards that the APIs support, there are a few differences in usage:

  • A KeyListener provides keyPressed() and keyReleased() signals while a shortcut provides only a triggered() signal.
  • KeyListener signals are sent to all key listeners in the propagation path, while shortcuts send a signal to the first slot it encounters.
  • There is no signal parameter passed with the shortcut triggered() signal. KeyListener signals provide a KeyEvent parameter containing information about the key press.
  • You can attach shortcuts to an ActionItem.

Supported controls

You can attach a KeyListener to any control that inherits from Control or AbstractPane . Attaching a KeyListener to an AbstractActionItem is not supported.

Key listener behavior

A KeyListener provides 3 signals to connect to:

  1. keyEvent: Emitted first when a key is pressed or released
  2. keyPressed: Emitted immediately when a key is pressed
  3. keyReleased: Emitted immediately when a key is released

This diagram is the call sequence when a key is pressed and immediately released:

Diagram showing the KeyListener call sequence when a key is pressed then released.

This sequence gives you a couple of options for creating the slots in your app. Your first option is to create two slots: one to handle the keyPressed() signal and one to handle the keyReleased() signal. Your second option is to create a single slot to handle the keyEvent() signal, then determine the key state by examining the keyEvent signal parameter.

Key events

Each signal provides a keyEvent parameter called event. This object is used to access information about the key that was pressed. The keyEvent event objects have the following properties:

  • key: An integer corresponding to the char code (UTF-8) of the key being pressed.
  • keycap: A value corresponding to the key that was pressed to generate the event. The keycap is a static code for each physical key. The keycap for a particular key is always the same, regardless of differences in the printed keyboard layout (for example QWERTY, AZERTY).
  • pressed: A Boolean expression indicating whether the key was pressed or released.
  • altPressed: A Boolean expression indicating whether the alt modifier key was pressed while the key was pressed.
  • shiftPressed: A Boolean expression indicating whether the shift modifier key was pressed while the key was pressed.
  • ctrlPressed: A Boolean expression indicating whether the ctrl modifier key was pressed while the key was pressed.
  • pressedDuration: The length of time in milliseconds that the key has been held in a pressed state.
  • unicode: The Unicode value of the key pressed to generate the event.

Signal traversal

KeyListener signals are first emitted for the control that's currently in focus. Then, the signals are emitted for its parent control, and so on, all the way through the tree. Unsupported controls are skipped automatically during the traversal, and there is no way to stop the propagation manually.

In the diagram below, the control tree on the left illustrates the traversal path if the focus is on the F node. The control tree on the right illustrates the traversal path when nothing is in focus. The root of the scene (in this case, the C node) receives the KeyListener signal, and the traversal continues toward the TabbedPane . The blue arrows illustrate the order in which the KeyListener signals are emitted for the different controls.

Diagram showing the KeyListener traversal path.

Signal traversal example

Consider the following example that includes a Page with a Container , TextField , Button , and Slider .

Page {
    Container {
        TextField {}
        Button {}
    }
    Slider {}
}

Not applicable

Not applicable

  • A KeyListener attached to the TextField receives key events only when the TextField is in focus.
  • A KeyListener attached to the Container receives key events when either the TextField or Button is in focus, but not when the Slider is in focus.
  • A KeyListener attached to the Page receives key events when any object is in focus.
  • If a KeyListener object is attached to the TextField, the Container, and the Page, three signals are emitted when a key is pressed with the TextField in focus. The signals are emitted beginning with the object in focus and moving toward the root.

Handling keyboard events

Here are some examples for how to handle keyboard events using input sessions and KeyListener.

In Cascades, attach a KeyListener to a supported node type and specify the logic for how your app responds to a key event.

For low-level keyboard events, request the screen event through BPS, and look for events of type SCREEN_EVENT_KEYBOARD.

import bb.cascades 1.1

Page {
    keyListeners: [
        KeyListener {
            onKeyEvent: { 
                console.log("A " + event.unicode + 
                        " key event has occurred")
            }
             
            onKeyPressed: {  
                console.log("The " + event.unicode + 
                        " key was pressed")
            }
 
            onKeyReleased: {  
                console.log("The " + event.unicode + 
                        " key was released")
            }        
        }
    ]
}
#include <bb/cascades/KeyEvent>
#include <bb/cascades/KeyListener>
#include <bb/cascades/Page>
KeyListener* myKeyListener = KeyListener::create()
   .onKeyEvent(this, SLOT(onKeyEventHandler(bb::cascades::KeyEvent *)))
   .onKeyPressed(this, SLOT(onKeyPressedHandler(bb::cascades::KeyEvent *)))
   .onKeyReleased(this, SLOT(onKeyReleasedHandler(bb::cascades::KeyEvent *)));
 
Page* myPage = Page::create();
myPage->addKeyListener(myKeyListener);
#include< bps/screen.h>
#include <bps/bps.h>
#include <bps/event.h>
void handleScreenEvent(bps_event_t *event)
{
    screen_event_t screen_event = screen_event_get_event(event);

    int screen_val;
    screen_get_event_property_iv(screen_event, SCREEN_PROPERTY_TYPE, &screen_val);

    if (screen_val == SCREEN_EVENT_KEYBOARD) {
        screen_get_event_property_iv(screen_event, SCREEN_PROPERTY_KEY_FLAGS, &screen_val);

        if (screen_val & KEY_DOWN) {
            screen_get_event_property_iv(screen_event, SCREEN_PROPERTY_KEY_SYM,&screen_val);

            printf("The '%c' key was pressed\n", (char)screen_val);
            fflush(stdout);
            
            // ...
        }
        // ...
    }
}

Last modified: 2015-05-07



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

comments powered by Disqus