Key listeners

The KeyListener class is closely related to shortcuts. You can use a KeyListener to listen for any key press that produces a character. This means that you can listen for any key except for the modifier keys such as the Shift, Alt and Control keys. However, any key press that generates a character will supply information about the state of the modifier keys in its signal parameter.

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

A call sequence for a key being pressed and immediately released looks like this:

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

This sequence gives you a couple options for how you create 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 Control 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.

Key listener 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 if 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 QML sample that includes a Page with a Container, TextField, Button, and Slider.

Page {
    Container {
        TextField {}
        Button {}
    }
    Slider {}
}
  • A KeyListener attached to the TextField will receive key events only when the TextField is in focus.
  • A KeyListener attached to the Container will receive key events when either the TextField or Button is in focus, but not if the Slider is in focus.
  • A KeyListener attached to the Page will receive 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.

Differences compared to shortcuts

There are a few key differences between a KeyListener and a shortcut:

  • A KeyListener provides pressed/released signals while a shortcut only provides a triggered signal.
  • KeyListener signals are sent to all key listeners in the propagation path, while shortcuts will only send a signal to the first slot encountered.
  • There is no signal parameter passed with the shortcut trigger signal. KeyListener signals provide a KeyEvent parameter.
  • You can attach shortcuts to an ActionItem.
  • You can use a KeyListener to respond to virtual keyboard input, while shortcuts are limited to devices with a physical keyboard.

Implementing a KeyListener

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

Page {
    keyListeners: [
        KeyListener {
            onKeyEvent: { 
                //Perform an action when the signal is emitted
            }
             
            onKeyPressed: {  
                //Perform an action when the signal is emitted 
            }
 
            onKeyReleased: {  
                //Perform an action when the signal is emitted
            }        
        }
    ]
}

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

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

Last modified: 2013-12-21

comments powered by Disqus