Touch Typing Has a Whole New Meaning

HOW-TO / 09.26.14 / Mark Sohm
© User:Colin / Wikimedia Commons / CC-BY-SA-4.0, via Wikimedia Commons

© User:Colin / Wikimedia Commons / CC-BY-SA-4.0, via Wikimedia Commons

The capacitive touch keyboard on the upcoming BlackBerry Passport gives users a new way to interact with their BlackBerry.  It allows users to have different interactions for pressing and touching a key.  An application is able to differentiate between the two types of events and capture where the user touches the keyboard and where they move their fingers across the keyboard, similar to what is done with touch screen displays.  This provides a totally new way for users to interact with your application.  You could do something as  simple as detecting a swiping movement on the keyboard and scroll the content of your application, or something more complex like making use of the touch keyboard as a gamepad to control a game.  Either way, this frees up the screen, which can now be used for more content and less controls.

We’ve added some new APIs in both WebWorks and Cascades to capture keyboard touch events.  Let’s take a look at an example in C++.




//Create an event listener for the TouchKeyboardHandler Container* container = root->findChild<Container*>("mainContainer");


//Set focus to the container, enabling all types of TouchKeyBoard events. container->requestFocus();


//Setup the TouchKeyboardHandler bb::cascades::TouchKeyboardHandler* handler = TouchKeyboardHandler::create().onTouch( this, SLOT(handleTouch(bb::cascades::TouchKeyboardEvent *)));




The code sample above shows accessing a Container that’s defined in QML and adding a TouchKeyboardHandler to it.  It begins with focus on the container by calling container->requestFocus(), which enables all types of touch events to be caught.  Controls can bubble touch events up to their parent controls if they are not consumed.  Note that all keyboard touch events except Cancel are captured by TextField and TextArea.  In order to capture up, down and movement touch events, focus must be set to a non-text entry field like the Container used above.  To receive the touch signals, we define a handleTouch method like this:

void ApplicationUI::handleTouch(bb::cascades::TouchKeyboardEvent *event) { bb::cascades::TouchType::Type touchType; touchType = event->touchType();


QString msg = QString("Touch keyboard event type is = ");


if (touchType ==  bb::cascades::TouchType::Down) { msg.append("Down"); } else if (touchType ==  bb::cascades::TouchType::Up) { msg.append("Up"); } else if (touchType ==  bb::cascades::TouchType::Move) { msg.append("Move"); } else if (touchType ==  bb::cascades::TouchType::Cancel) { msg.append("Cancel"); } msg.append(" Finger: "); msg.append(QString::number(event->fingerId())); msg.append (" X: "); msg.append(QString::number(event->screenX())); msg.append (" Y: "); msg.append(QString::number(event->screenY())); msg.append("n");

m_outputTextArea->setText(msg + m_outputTextArea->text()); }

In this method we’re collecting information about the touch event and displaying it in text form in a TextArea.  The touch type, x/y coordinates and finger Id are displayed.  Finger Id refers to the unique touch point for the TouchKeyboardEvent.  For example finger Id would be 0-3 if you had 4 fingers placed on the keyboard at the same time.




Touch keyboard events can also be captured directly in QML.  Here’s a code snippet that you could place within a control to capture touch keyboard events.

eventHandlers: [ TouchKeyboardHandler { onTouch: { console.log("TouchKeyboard event captured From QML! Event: " + event.touchType); } } ]




WebWorks developers are also able to work with touch keyboard events.  The touch type (start, move and end) and x/y positions can be captured in WebWorks as well.  The next code sample shows how that can be done.

<script type="text/javascript"> 


document.addEventListener("keyboardtouchstart", touchCallback); document.addEventListener("keyboardtouchmove", touchCallback); document.addEventListener("keyboardtouchend", touchCallback);

function touchCallback(event) {

if (event.type==="keyboardtouchstart")) { console.log('The user touched the keyboard at ' + event.timeStamp + '.'); }


if (event.type==="keyboardtouchmove") { console.log('The user has moved to: X coord: ' + event.x + ', Y coord: ' +  event.y); }


if (event.type==="keyboardtouchend") { console.log('Finger lifted from keyboard at ' + event.timeStamp + '.'); } } </script>


Using the Simulator


The BlackBerry Simulator Controller can be used to simulate touch keyboard events on the BlackBerry 10 Simulator.  Once the Controller is connected to the simulator, click on the “Touch Area” heading to expand a grey rectangle below.  You can then left click and drag in that rectangle to simulate touch events.  A limitation with this over a real BlackBerry Passport is that you can only simulate a single touch point at a time.



This should cover everything you need to know to create a touch keyboard enabled application.  If you have any questions, visit our BlackBerry Developer Forum and ask me.

Mark Sohm

About Mark Sohm

Senior Technical Solutions Manager on the Solution Architects team.

Mark Sohm joined BlackBerry in 2003 and currently works as a Senior Technical Solutions Manager on the Solutions Architects team. Mark Sohm has been helping developers create applications using BlackBerry technologies for over 15 years, starting way back with the very first BlackBerry JDK on BlackBerry OS 3.6 through to BlackBerry 10 and now Android with BlackBerry Dynamics and Android Enterprise.