1. Cosc 5/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 { 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.

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

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

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

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 boolean touchEvent(TouchEvent message) – Inside handle the message Use message.getEvent() and TouchEvent. Constants to figure what happened.

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

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

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.AccelerometerSens or.* 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 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.

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 &