Cosc 5/4730

1. Cosc5/4730 Input Keyboard, touch, and Accelerometer

2. 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.

3. 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 keyListener removeKeyListener(KeyListener listener); • The keylistener is in the package net.rim.device.api.system.KeyListener

4. KeyListener • You’ll need to implement a KeyListener and it’s methods public class myKeyListener implements KeyListener { booleankeyChar(char key, int status, int time) {} • Invoked when a sequence of zero or more keyDowns generates a character. booleankeyDown(intkeycode, int time) {} • Invoked when a key has been pressed. booleankeyRepeat(intkeycode, int time) {} • Invoked when a key has been repeated. booleankeyStatus(intkeycode, int time) {} • Invoked when the ALT or SHIFT status has changed. booleankeyUp(intkeycode, 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.

5. KeyListener (2) • Example: public booleankeyChar( 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.

6. 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.

7. 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

8. 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)

9. Navigation methods • booleannavigationClick(int status, int time) • Called when trackball/pad is pushed • booleannavigationUnclick(int status, int time) • Called when trackball/pad is released (after a click) • booleannavigationMovement(intdx,intdy,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.

10. Note: Trackwheel/trackball • If the device does not have a this, then the methods will never be called • The Storm 1and 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.

11. 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.

12. Touch events • Added in 4.7+ OS. • Override • protected booleantouchEvent(TouchEvent message) • Inside handle the message • Use message.getEvent() and TouchEvent. Constants to figure what happened.

13. Touch events (2) • TouchEvent • IntgetEvent() 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.

14. Touch events (3) • For TouchEvent.GESTURE to figure out the gesture • TouchGestureTouchEvent.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 • intgetSwipeAngle() Retrieves the angle (in degrees) associated with a swipe gesture relative to the device's current upward direction • intgetSwipeMagnitude() Retrieves the magnitude (in pixels) associated with a swipe gesture.

15. 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.

16. 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.

17. 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.

18. Accelerometer Sensor • net.rim.device.api.system.AccelerometerSensor.* • Two methods of using it in a RAW method • Call it directly • Use the listener

19. Direct call import net.rim.device.api.system.AccelerometerSensor.*; import net.rim.device.api.system.Application; private short[] xyz = new short[ 3 ]; //for accelerometer data private Channel accChannel; //for the accelerometer channel //open accelerometer channel accChannel = AccelerometerSensor.openRawDataChannel( Application.getApplication() ); //read the data (as many times as needed) accChannel.getLastAccelerationData( xyz ); //when done close the channel accChannel.close();

20. Accelerometer Listener • class .. implements AccelerometerListener • Implement public void onData(AccelerometerData data) { //Sensor data short sx = data.getLastXAcceleration(); short sy = data.getLastYAcceleration(); short sz= data.getLastZAcceleration(); //whatever you want to do with it. }

21. 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; }

22. 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 intgetOrientation() 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.

23. 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

24. Q A &