Skip to content
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page. ×
  • BlackBerry Developer
  • Useful links
  • Blog
  • YouTube
  • Forum
  • Signing
  • Login
  • Register

Would you like to tell us how we are doing?

You bet No thanks
Native SDK for BlackBerry 10
Release Notes for SDK
  • Downloads
  • Sample apps
  • Documentation
  • Reference
Oops, it seems like you're using an old browser that we do not fully support. If you're able to, please upgrade your browser here. ×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page. ×
Native SDK for BB10
  • Downloads
  • Sample apps
  • Documentation
  • Reference
  • Release Notes for SDK
A header image for the Belt article.

Featured sample: Belt

Published: January 29th, 2015

View in GitHub

Learn about creating apps for the BlackBerry Classic

The 10.3.1 Gold release of the BlackBerry 10 Native SDK supports two new devices: the BlackBerry Passport smartphone and the BlackBerry Classic smartphone. In this article, we focus on the Belt sample app, which demonstrates how an app can take advantage of the navigation keys of the BlackBerry Classic.

The Belt app shows you how to create a game that tests your BlackBerry Classic navigation skills (and how to handle the user's key presses and trackpad input in QML). You can download and import the Belt sample app from GitHub.

After the game starts, you tap a button to generate a random grid that contains rows of buttons. The buttons are labelled "call", "end", "menu", "back", or "trackpad".

To win, you clear the buttons on the grid by using the trackpad to navigate to each button and pressing the corresponding key on your device. A function in the app clears the button by setting the text to an empty string and the color of the button to gray.

Screen shot showing the starting UI of the Belt sample app.

The UI is straightforward. It uses custom components to represent a row of buttons and each individual button. There are two interesting parts of the app that we want to explore: generating the grid of buttons and handling the user's key presses and trackpad input.

Generating the grid

The main.qml file generates the UI using two basic Container objects. The first container includes a Label with the instructions for how to play the game and three attached objects, which represent rows of buttons, a divider, and a DisplayInfo object. The second container includes a Button to generate the grid and a Label to update when the user wins the game.

The DisplayInfo object is attached to the first container. The app can access the screen width and height so that it can dynamically create the correct number of rows of buttons to fill the screen.

                    // Retrieve screen height and width
                    var height = displayInfo.pixelSize.height
                    var width = displayInfo.pixelSize.width
                    
                    // Calculation to determine number of buttons
                    // in a row based on screen width
                    var columns = (width - ui.du(10) - (ui.du(25) / 2))
                    columns = (columns / ui.du(25))
                    
                    // Take height and subtract padding
                    height = (height - ui.du(30))
                    
                    // 65 is the height of button plus padding
                    var rows = height / 65
                    
                    // Calculation to determine number of rows based on screen height
                    rows = (height - (rows * ui.du(2))) / 56
                    
                    // Generate the column rows of buttons
                    for(var i = 0; i < rows; i++) {
                        var createdObject = row.createObject()
                        createdObject.createButtons(columns, beltText, beltColors)
                        createdObject.topMargin = ui.du(2)
                        root.add(createdObject)
                    }    
        

The custom component that is defined in Row.qml creates the random sequencing of buttons in each row.

Screen shot showing a row in the Belt sample app.

The custom component also tracks which buttons in each row have to be checked to see if the user performed the correct action for that button. Each row is made up of buttons that are defined using the BeltButton custom component.

Handling user input

The custom component that is defined in BeltButton.qml defines each button on the grid. Each button has a simple definition:

        Button {
            id: button
            maxWidth: ui.du(25)
            minWidth: ui.du(25)
            text: root.text
            color: Color.create(root.color)

Each button also has a set of DeviceShortcut listeners that allow the app to intercept key press events on the BlackBerry Classic. If the text of the button matches the key that the user pressed, the button is cleared on the grid.

        // Shortcuts representing each button on the belt. 
        // These allow us to intercept key press events.
        shortcuts: [
            // The Send button (phone call initiation)
            DeviceShortcut {
                type: DeviceShortcuts.SendTap
                onTriggered: {
                    if(text.indexOf("call") >= 0) {
                        clearButton()
                    }
                }
            },
            // The Menu button
            DeviceShortcut {
                type: DeviceShortcuts.MenuTap
                onTriggered: {
                    if(text.indexOf("menu") >= 0) {
                        clearButton()
                    }
                }
            },
            // The Back button
            DeviceShortcut {
                type: DeviceShortcuts.BackTap
                onTriggered: {
                    if(text.indexOf("back") >= 0) {
                        clearButton()
                    }
                }
            },
            // The End button (end call)
            DeviceShortcut {
                type: DeviceShortcuts.EndTap
                onTriggered: {
                    if(text.indexOf("end") >= 0) {
                        clearButton()
                    }
                }
            }
        ]
        

Finally, a TrackpadHandler is attached to the button to handle the user's interaction with the trackpad. If the text of the button is "trackpad" and the user presses and releases the trackpad, the button is cleared.

        // Event handler for tracking user interaction with
        // the belt trackpad.
        eventHandlers: [
            TrackpadHandler {

                onTrackpad: {

                    switch (event.trackpadEventType) {
                        // User has started to trackpad interaction
                        case TrackpadEventType.Begin:
                            {
                                console.log("TrackpadEventType.Begin");
                                break;
                            }
                        // Trackpad continuing to be swiped 
                        //(moving finger over trackpad)
                        case TrackpadEventType.Move:
                            {
                                console.log("TrackpadEventType.Move:  x:" 
                                + event.deltaX + " y:" + event.deltaY);
                                break;
                            }
                        // User has ended trackpad interaction
                        case TrackpadEventType.End:
                            {
                                console.log("TrackpadEventType.End");
                                break;
                            }
                        // User has pressed the trackpad
                        case TrackpadEventType.Press:
                            {
                                console.log("TrackpadEventType.Press");
                                break;
                            }
                        // User released the trackpad
                        case TrackpadEventType.Release:
                            {
                                console.log("TrackpadEventType.Release");
                                if(button.text == "trackpad") {
                                    clearButton()
                                }
                                break;
                            }
                        // Interaction has been canceled
                        case TrackpadEventType.Cancel:
                            {
                                console.log("TrackpadEventType.Cancel");
                                break;
                            }
                    }
                }
            }
        ]
        

That's it! Have fun playing with this app on your BlackBerry Classic. And feel free to reuse some of these techniques in your own app. For more information about the BlackBerry Classic, check out Device characteristics and BlackBerry Classic navigation keys.

P.S. If you are looking for a sample app that targets the BlackBerry Passport, check out the Gears app in GitHub.

3.0 Gold plug-in for Visual Studio10.3.1 Gold is here!

Archive

  • Native documentation revisited
  • 3.0 Gold plug-in for Visual Studio
  • Featured sample: Belt
  • 10.3.1 Gold is here!
  • That's so Classic!
  • Static asset selection
  • Get on the grid
  • Design units in 10.3
  • Momentics IDE 2.1 Gold is here!
  • Networking 101
  • Plug-in for Visual Studio is Gold!
  • Lights, sounds, previews!
  • New on the Dev Blog - January 2014
  • Updates to start off the New Year
  • Money, money, money!
  • We want your feedback!
  • New plug-in for Microsoft Visual Studio
  • Dev Blog - Blast from the past
  • Featured API: String pattern registry
  • New on the Dev Blog - October 2013
  • Momentics IDE 2.0 is here!
  • Featured library: Unified Data Source
  • Training for Native Developers
  • What's new on the Developer Blog
  • Do you read the release notes?
  • Featured sample: XandOs
  • Featured library: Cocos2D-X
  • Featured API: Identity Service
  • Updates in 10.2 Gold
  • Analyze your apps using profiling
  • Featured sample: Pull My Beard

Technologies

  • Native
  • HTML5
  • AIR
  • Android
  • PlayBook
  • BlackBerry OS

Programs

  • Partner Program
  • Academic programs
  • Developer groups
  • BlackBerry 10 Dev Alpha
  • Built for BlackBerry
  • BlackBerry Builder

Support

  • Code Signing Help
  • YouTube Channel
  • Developer forums
  • Knowledge Base

BlackBerry World

  • Sign your app
  • Submitting your app

Follow us on:

  • Facebook
  • YouTube
  • Twitter
  • BlackBerry Blogs
  • BBM Channels
BBM Channels

BBM Channels

Developer Relations is on BBM Channels! Join the conversation by signing up for the beta program and scanning the barcode to the right.

Register for BBM Channels beta ›
  • Legal & Trademarks
Copyright © 2021 BlackBerry Limited, unless otherwise noted.
  1. 1. Download the tools

    Before you start developing, you'll need to visit the Downloads tab. Here you'll find downloads for the BlackBerry 10 Native SDK, BlackBerry 10 Device Simulator, and some other useful tools.

  2. 2. Try the sample apps

    Now featuring a filter control, the Sample apps tab allows you to search for samples by name or by feature.

    Select either the Core or Cascades radio buttons to display the samples relevant to you.

  3. 3. Educate yourself

    The Documentation tab contains tons of examples, tutorials, and best practices to guide you along the path towards building an awesome app.

    You can access all the documentation that you need in the left-hand navigation.

  4. 4. Start developing

    The Reference tab is where you'll find essential details about how to use our APIs.

    You can use the left-hand navigation to choose how you would like to browse the reference: by module, by topic, or alphabetically. If you have an idea of what you are looking for, start typing it in the Filter box.