Cosc 5/4730

InputKeyboard, touch, and Accelerometer

Keyboard input

• When you have input boxes, you don’t have to deal with keyboard events, since they are already handled.

• But there are many times where you want to handle keyboard events.– Such as games.

Keyboard input

• Implement a event keyListener and then add that keyListener so you app receives the events.

• Within the MainScreen:addKeyListener(new myKeyListener ());• To remove a keyListenerremoveKeyListener(KeyListener listener);• The keylistener is in the package

net.rim.device.api.system.KeyListener

KeyListener• You’ll need to implement a KeyListener and it’s methods public class myKeyListener implements KeyListener { boolean keyChar(char key, int status, int time) {}

– Invoked when a sequence of zero or more keyDowns generates a character. boolean keyDown(int keycode, int time) {}

– Invoked when a key has been pressed. boolean keyRepeat(int keycode, int time) {}

– Invoked when a key has been repeated. boolean keyStatus(int keycode, int time) {}

– Invoked when the ALT or SHIFT status has changed. boolean keyUp(int keycode, int time) {}

– Invoked when a key has been released.– Note that keyUp events are disabled by default for performance reasons, and must be explicitly

enabled via Application.enableKeyUpEvents(boolean).}

– Return True if you consumed the event and false otherwise.

KeyListener (2)• Example: public boolean keyChar( char key, int status, int time ) { if ( key == Characters.ENTER ) { return true; //event consumed. } else if (key == 'j') { return true; } return false; }

• key – Character generated, after any

effects of the ALT or SHIFT keys and any complex keyboard mappings.

• For the other methods– keycode - Key scan code of the

character shown, before any effects of the ALT or SHIFT keys.• Using Keypad.key(keycode) gets

the key pressed; alphabetic keys are always upper case.

• Using keypad.status(keycode) gets the modifier key status at the time of the keypress.

– Status• Status of the ALT, SHIFT and CAPS

LOCK keys.– Time

• Number of milliseconds since the device was turned on.

KeyListener and MainScreen

• A KeyListener is already added to the MainScreen by default

• So you only need to override the methods you want– Say KeyChar(…) and skip the rest if you don’t need

them.

Soft keys

• Volume up/down• Convenience_1 and conveniece_2 keys • Send, Menu, Escape/back, End

• Using KeyDown you can capture the keys• Keypad.key(keycode) == Keypad.KEY_MENU– KEY_ESCAPE, KEY_SEND, KEY_END– KEY_VOLUME_DOWN, KEY_VOLUME_DOWN– KEY_CONVENIENCE_1, KEY_CONVENIENCE_2

Trackwheel/trackball

• Since at least 4.6 the listener have been deprecated.• Instead of using this interface, developers are

strongly encouraged to use the "navigation" methods in the Screen class (or subclasses , like MainScreen) to receive such notifications.

• Override any (or all) of the following 3 methods: – navigationClick(int, int)– navigationUnclick(int, int)– navigationMovement(int, int, int, int)

Navigation methods

• boolean navigationClick(int status, int time) • Called when trackball/pad is pushed

• boolean navigationUnclick(int status, int time)• Called when trackball/pad is released (after a click)

• boolean navigationMovement(int dx,int dy,int status, int time) – Call when “moved”– dx is the magnitude of navigational motion: negative for a

move left and positive for a move right.– dy is the magnitude of navigational motion: negative for an

upwards move, and positive for a downwards move.

Note: Trackwheel/trackball

• If the device does not have a this, then the methods will never be called

• The Storm 1 and 2 are currently the only ones without navigation. The Touch series does have one.

– So it is safe to program for them to allow for cross device.

• This is the same for touch, if the device is not a touch enabled, then the methods won’t get called.

Note2: Trackwheel/trackball

• When your program is consuming that input, you need to make sure your program has the focus.– Meaning the menu is not open.– Because if you consume the events while the menu

is open, then you can not use the menu!– You can override:

protected void onFocusNotify(boolean focus) {havefocus = focus;// havefocus is a local variable} • focus is true when you screen has focus, false otherwise.

Touch events

• Added in 4.7+ OS. • Override– protected boolean touchEvent(TouchEvent

message)– Inside handle the message• Use message.getEvent() and TouchEvent. Constants to

figure what happened.

Touch events (2)

• TouchEvent– Int getEvent() Retrieves the event code associated with this

touch event.• Events: TouchEvent.CANCEL, CLICK, DOWN, MOVE, UNCLICK, UP

AND GESTURE– getX(1) returns x for first (finger) touch

• getX(2) return x for second (finger) touch– getY(1) return y for first (finger) touch.

• getY(2) return y for second (finger) touch– getMovePoints(int touch, int[] x, int[] y, int[] time)

• Retrieves the global coordinates for the current sequence of touch move input events for the specified touch point.

Touch events (3)• For TouchEvent.GESTURE to figure out the gesture

– TouchGesture TouchEvent.getGesture()– Then use TouchGesture.getEvent() to see which constant it is.

• TouchGesture.CLICK_REPEAT– Click and pause at a specific point on the touch screen for more than 500 milliseconds.

• TouchGesture.DOUBLE_TAP– Two consecutive quick touch and release gesture on the touch screen.

• TouchGesture.HOVER– Touch and pause at a specific point on the touch screen for more than the user-defined number of

milliseconds (configurable setting found in Screen/Keyboard Options).• TouchGesture.TAP

– Quick touch and release gesture on the touch screen.• TouchGesture.SWIPE

– Quick motion gesture across the touch screen. Once you know it is a SWIPE, you can figure out the direction using gesture.getSwipeDirection() which returns» SWIPE_EAST, SWIPE_NORTH, SWIPE_SOUTH, SWIPE_WEST

– int getSwipeAngle() Retrieves the angle (in degrees) associated with a swipe gesture relative to the device's current upward direction

– int getSwipeMagnitude() Retrieves the magnitude (in pixels) associated with a swipe gesture.

Touch Events API 6.0+

• Two fingers, called a PINCH in Blackberries.– TouchGesture.PINCH_BEGIN

• When two touch points are detected.• The midpoint between the two initial touch points is stored as

TouchEvent.getX(1) and TouchEvent.getY(1).– getGlobalX(1), GetGlobalY(1) may have the touch point for the first

“finger” and the second “finger” maybe in getGlobalX(2), GetGlobalY(2)

– TouchGesture.PINCH_END• When one or both touch points are released

– TouchGesture.PINCH_UPDATE• When one or both touch points are moved.

Touch Events API 6.0+ (2)

• A Pinch gesture generates a series of PINCH_UPDATE events as the user moves one or both fingers.

• float getPinchMagnitude()– Retrieves the pinch magnitude of the

TouchGesture.PINCH_BEGIN, TouchGesture.PINCH_UPDATE, or TouchGesture.PINCH_END event currently being processed.

Accelerometer Sensor• X axis runs from east (negative values) to west

(positive values);• Y axis runs from north (negative values) to south

(positive values); and• Z axis runs from the front of the BlackBerry device

(negative values) to the back of the device (positive values).

//left right first. if (xyz[0] > 0) { left(); } else if(xyz[0] <0) { right(); } //up and down if(xyz[1] > 600) { //allow for about a 45% tilt

down(); } else if(xyz[1] <400) {

up(); } See AccelerometerSensor API for more

Information.

Accelerometer Sensor

• net.rim.device.api.system.AccelerometerSensor.*

• Two methods of using it in a RAW method– Call it directly– Use the listener

Direct callimport net.rim.device.api.system.AccelerometerSensor.*;import net.rim.device.api.system.Application;private short[] xyz = new short[ 3 ]; //for accelerometer dataprivate Channel accChannel; //for the accelerometer channel//open accelerometer channelaccChannel =

AccelerometerSensor.openRawDataChannel( Application.getApplication() );

//read the data (as many times as needed)accChannel.getLastAccelerationData( xyz );//when done close the channelaccChannel.close();

Accelerometer Listener• class .. implements AccelerometerListener

• Implement public void onData(AccelerometerData data) {

//Sensor datashort sx = data.getLastXAcceleration();short sy = data.getLastYAcceleration();short sz = data.getLastZAcceleration();//whatever you want to do with it.

}

Accelerometer Listener (2)• Still need to set the listener and create the “channel” for it.Channel channel = null;if ( AccelerometerSensor.isSupported() ) { //make sure there is an Accelerometer! if (channel == null) { channel = AccelerometerSensor.openRawDataChannel(Application.getApplication()); } channel.setAccelerometerListener(this);}

//closes the channel and removes listener (by closing it) and releases the memory and saves power.public void unregisterAccelerometer() { if (channel != null) { //so exists, needs to be closed. channel.close(); } channel = null;}

Accelerometer Orientation

• Instead of using in RAW mode, you can use to figure out the “Orientation” of the phone– channel =

AccelerometerSensor.openOrientationDataChannel( Application.getApplication());

– Use the int getOrientation() method.– Returns the following: -1 when in RAW mode

• AccelerometerSensor.ORIENTATION_BACK_UP, ORIENTATION_BOTTOM_UP, ORIENTATION_FRONT_UP, ORIENTATION_LEFT_UP, ORIENTATION_RIGHT_UP, ORIENTATION_TOP_UP, ORIENTATION_UNKNOWN

– Note: getLastAcceration methods may through exceptions if you call them or return garage.

BlackBerry Orientation

• Screen flipping between portrait and landscape is a problem. – To stop it, need to use setAcceptableDirections( int).

This is for the whole application and while in theory can be changed, in practice doesn’t.

– In the UiApplication constructor, before pushScreen add

– Ui.getUiEngineInstance().setAcceptableDirections(Display.DIRECTION_NORTH); //portrait• or DIRECTION_WEST or DIRECTION_EAST for landscape

QA&