BlackBerry Classic navigation keys

The BlackBerry Classic smartphone has four physical keys that are located above its keyboard: the Call, Menu, Back, and End keys. The Call, Back, and End keys trigger navigator events and perform system-level actions when pressed (for example, pressing the Call key opens the Phone app) unless your app handles those events instead. The Menu key triggers a screen event, and in the case of Cascades apps, it can also open the action menu.

To handle physical key presses, you can use the Screen Graphics Subsystem and navigator service APIs to perform low-level processing of the events. For example, you could implement a function to draw a menu when the user presses the Menu key.

If you're using Cascades, you can capture physical key events by attaching a DeviceShortcut object to the shortcuts property for a subclass of AbstractPane ( Page , NavigationPane , and so on).

If you override the behavior of the navigation keys, make sure that they behave in an expected way for users. For more BlackBerry Classic best practices, see Trackpad and Classic navigation keys .

Here are some examples of how to process Call, Menu, Back, and End key presses in your app.

import bb.cascades 1.4

Page {
    Container {
        id: root
        background: Color.Blue
    }
    shortcuts: [
        DeviceShortcut {
            type: DeviceShortcuts.SendTap
            onTriggered: {
                root.background = Color.Green
            }
        },
        DeviceShortcut {
            type: DeviceShortcuts.MenuTap
            onTriggered: {
                root.background = Color.Gray
            }
        },
        DeviceShortcut {
            type: DeviceShortcuts.BackTap
            onTriggered: {
                root.background = Color.Blue
            }
        },
        DeviceShortcut {
            type: DeviceShortcuts.EndTap
            onTriggered: {
                root.background = Color.Red
            }
        }
    ]
}

Coming soon

#include <bps/bps.h>
#include <bps/event.h>
#include <bps/navigator.h>
#include <bps/screen.h>
#include <screen/screen.h>
#include <sys/keycodes.h>
                    
// The first section is a stripped-down event handling loop.
while (!program_exit) }
    int domain;
    bps_event_t *event = NULL;
    if (BPS_SUCCESS != bps_get_event(&event, -1)) { 
        // Failed to get event. 
    }

    if (event) {
        domain = bps_event_get_domain(event);
        if (domain == navigator_get_domain()) {
            handle_navigator_event(event);
        } else if (domain == screen_get_domain()) {
            handle_screen_event(event);
        }
    }
}

// Call, Back, and End key presses trigger navigator events.
static void handle_navigator_event(bps_event_t *event) {
    int syskey_key;
    char syskey_id = NULL;
    int will_respond = 0;

    switch (bps_event_get_code(event)) {

        // Handle when the Call, Back, or End key is pressed.
        // This app handles the Back and End key presses, and
        // lets the system handle Call key presses.
        case NAVIGATOR_SYSKEY_PRESS:
            syskey_key = navigator_event_get_syskey_key(event);
            switch(syskey_key) {
                // Handle a Call key press.
                case NAVIGATOR_SYSKEY_SEND:
                    break;
                
                // Handle Back and End key presses.
                case NAVIGATOR_SYSKEY_BACK:
                case NAVIGATOR_SYSKEY_END:
                    will_respond = 1;
                    break;

                default:
                    // Handle unexpected key.
                    break;
            }
            
            const char *key_id = navigator_event_get_syskey_id(event);
            if (NULL == *key_id) {
                // Handle failure to get syskey ID.
            }
            if (BPS_SUCCESS != navigator_syskey_press_response(key_id, will_respond)) {
                // Handle error.
            }
    }
    
    return;
}

// Menu key presses trigger screen events.
static void handle_screen_event(bps_event_t *event) {
    int screen_val;
    
    screen_event_t screen_event = screen_event_get_event(event);
    screen_get_event_property_iv(screen_event, 
                                 SCREEN_PROPERTY_TYPE, 
                                 &screen_val);
    
    switch(screen_val) {
        // Trackpad events are of type SCREEN_EVENT_JOYSTICK. 
        case SCREEN_EVENT_KEYBOARD:
            // Get the key from the event.
            if (0 = screen_get_event_property_iv(screen_event,
                                                 SCREEN_PROPERTY_KEY_SYM, 
                                                 &key)) {
                if (KEYCODE_MENU == key) {
                    // Handle Menu key press.
                }
            } else {
                // Failed to get key from event.
            }
            break;
            
        default:
            // Handle non-Menu key presses.
            break;
    }
    
    return;
}

Last modified: 2015-05-07



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

comments powered by Disqus