Handling BlackBerry Classic navigation key events

The BlackBerry Classic device includes four physical navigation keys. These keys provide one-touch shortcuts to answer a call or return to a previous screen. The Send and End keys are predefined and can't be customized. You can define the behavior of the Menu and Back keys.
  • Send key: Opens the Phone app or answers an incoming call.
  • Menu key: By default, this key performs no action. You must add code to handle Menu key events. To capture Menu key events, you can use the menubutton event in the com.blackberry.app plugin.

    In most apps, the typical behavior of the Menu key is to open the app's action menu.

  • Back key: By default, this key minimizes the app and returns the user to the home screen. To change the default behavior, you can use the backbutton event in the com.blackberry.app plugin.

    In most apps, the typical behavior of the Back key is to return to the previous screen within the app; only when there are no other screens to close does the Back key minimize the app and return the user to the home screen.

  • End key: Ends a call or minimizes the current app and returns the user to the home screen.

Best practices

Avoid unnecessary customization of the navigation keys. Although the Menu and Back keys can be customized, be cautious about deviating from their typical behavior. Users expect the navigation keys to work the same way in every app and context.

Handling menubutton and backbutton input events

The menubutton and backbutton events are part of the com.blackberry.app plugin. To access these events, you need to add the com.blackberry.app plugin to your project using either the SDK web tool or the webworks plugin add command.

  1. To attach an event listener that listens for the Menu or Back key to be pressed, use document.addEventListener. You must add the listener after the deviceready event fires. For example:
    document.addEventListener("deviceready", function () {
        document.addEventListener('menubutton', onMenuButton);
        document.addEventListener('backbutton', onBackButton);
    }); 
  2. To specify the app behavior when each key event fires, add the callback functions. For example:
    function onMenuButton() {
        console.log("The Menu button was pressed");
    }
    
    function onBackButton() {
        console.log("The Back button was pressed");
    }

Last modified: 2014-10-09



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

comments powered by Disqus