Context Menus

BlackBerry 10 allows for a press and hold context menu that is very similar to the action bar overflow menu. If you add one of these menus to your screen you can also automatically wire up your image lists and/or grid lists to the control. NOTE: You can only have one context menu on a screen

When wired to an image list or grid list, pressing and holding on the image list item will "peek" the context menu and passing it the selected element. Peeking the context menu will show the row of action icons that can be clicked and part of the context information in the header of the menu.

When the user swipes from right to left it will pull the full menu into view if they want to see the text labels for all the items.

Markup for the context menu looks a lot like the action bar markup. You are able to create a data-bb-type="context-menu" that has a series of data-bb-type="action" elements. An action item consists of an image and text. To react to the clicking of an action simply assign an onclick handler to the action element.

    <div data-bb-type="context-menu">
        <div data-bb-type="action" data-bb-img="images/actionBar/cog_dark_theme.png">Email Work</div>
        <div data-bb-type="action" data-bb-img="images/actionBar/cog_dark_theme.png">Invite to Meeting</div>
        <div data-bb-type="action" data-bb-img="images/actionBar/cog_dark_theme.png">Call Work</div>
        <div data-bb-type="action" data-bb-img="images/actionBar/cog_dark_theme.png">View details</div>
        <div data-bb-type="action" data-bb-img="images/actionBar/cog_dark_theme.png" onclick="alert('Delete');">Delete</div>
    </div>

Image Sizes

Images for actions on the context menu will be scaled the same as the action bar.

• BlackBerry PlayBook - 40 x 40 pixels
• BlackBerry 10 - 80 x 80 pixels

"Pinning" a Context Menu Action

There are scenarios where you have a specific action that you wish to call out in your context menu as something different or special ("Delete" is a good example). To make this action stand out it can be "pinned" to the bottom of the menu away from your other actions. This can be done by providing the data-bb-pin="true" attribute for an action.

    <div data-bb-type="context-menu">
        <div data-bb-type="action" data-bb-img="email.png">Email Work</div>
        <div data-bb-type="action" data-bb-pin="true" data-bb-img="del.png">Delete</div>
    </div>

JavaScript Interface

Each context menu has the ability to be both peeked and shown using JavaScript. These methods are called with a parameter that contains a title, description and selected DOM element.

To peek the icons on the context menu use the following code:

    var context = document.getElementById('mycontextmenu');
    context.menu.peek({title:'My Title', description: 'My Description', selected: mySelectedDOMElement});

To show the full context menu use the following code:

    var context = document.getElementById('mycontextmenu');
    context.menu.show({title:'My Title', description: 'My Description', selected: mySelectedDOMElement});

To grab the item that was selected from within your onclick of an action item. This selected object is the one that was passed into the peek or show functions. You can refer to the selected property of the menu like in the following code:

    function myclick() {
        var selectedItem,
            context = document.getElementById('mycontextmenu');
   
        // context.menu.selected is the DOM element that was selected in the press-and-hold
        selectedItem  = context.menu.selected;
        if (selectedItem) {
            //... do something
        }
    }

The caption and image of an action item can be changed using the setCaption() and setImage() functions.

var myAction = document.getElementById('myAction');
myAction.setCaption('hello world');
myAction.setImage('images/newImage.png');