Input

The Input object allows you to use a touch-enabled keyboard to control your application. This is a new input event layer for use with touch-enabled keyboards beginning with BlackBerry 10.3. This is a new keyboard event and does not represent standard DOM mouse events or HTML5 touch events on the screen.

This plugin is not included in BlackBerry 10 WebWorks SDK version 2.1, but you can add it from the Cordova registry using the installation command below. If you are adding a plugin from the Cordova registry, you must be connected to the internet. If you want to install the plugin while offline, you can download the plugin from GitHub for later installation.

The Input API had significant updates since its initial 0.9 release on GitHub in June 2014. For more information, see the GitHub Commits.

Installation:

To use this API in your project, add the input plugin:

webworks plugin add com.blackberry.ui.input

Applications should use document.addEventListener to attach an event listener after the deviceready event fires.

touchenabledkeyboard

This event is fired by the system. If you want to listen for the event you can do so using the document.addEventListener function and remove the listener using the document.removeEventListener function. The touchenabledkeyboard event is triggered when the user interacts with the touch-enabled keyboard.

Synopsis:

Event

Parameters:

event {Object}

The event object contains the following properties for the touchenabledkeyboard event.

type {String}

A String that identifies the event type as "touchenabledkeyboard".

timeStamp {Number}

A Number containing the time stamp of the touch event.

touches {Array}
An Array that defines a list of multiple touch points. Each array element has the following properties.
  • identifier: A Number containing an identifier assigned to each distinct touch point. Identifiers are only valid from TouchPressed through to TouchReleased. Once released, the identifier can be recycled with a new touch point. {Number}
  • keyboardX: A Number containing the x-axis position of the touch point. {Number}
  • keyboardY: A Number containing the y-axis position of the touch point. {Number}
  • state: A String containing the state of the identified touch point. {String}
    • TouchPressed: Triggered when the user's finger touches the touch-enabled keyboard.
    • TouchMoved: Triggered when the user's finger is moved along the touch-enabled keyboard.
    • TouchReleased: Triggered when the user's finger is lifted from the touch-enabled keyboard.
    • TouchStationary: Triggered while the user's finger is touching the touch-enabled keyboard, but isn't moving.

Example:

<script type="text/javascript">

document.addEventListener("deviceready", function () {
    document.addEventListener("touchenabledkeyboard", touchKeyboardCallback);
});

function touchKeyboardCallback(event) {   
    event.timeStamp; 
    event.touches.forEach(
        function (touch){
            console.log('Touch identifier: ' + touch.identifier);
            console.log('Touch State: ' + touch.state);  
            console.log('X: ' + touch.keyboardX 
                + 'Y: ' + touch.keyboardY);  
        }
    )
}
             
</script>

Last modified: 2014-08-07



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

comments powered by Disqus