com.blackledge.david.tivo.widgets.qk
Interface QuickKeyboardHandler

All Known Implementing Classes:

DirectionalKeyboardHandler, QuadrantsKeyboardHandler, RowColumnKeyboardHandler, TextingKeyboardHandler, TextingRowColumnKeyboardHandler

public interface QuickKeyboardHandler

The class that defines the layout, cues, and logic in selecting keyboard characters in a minimal number of strokes.

Version:

1.0

Method Summary

void	abortCharacter() Reset handler state - the user pressed an aborting key like delete/backspace and the last uncommitted value passed to QuickKeyboard.setCharacter(String) is deleted (no need to do it yourself.
boolean	buttonPress(int keyCode) Alters the state of the keyboard handler and may cause a character to be set and possibly the cursor to be advanced.
void	finishCharacter() Set a character if you can settle on one in current state, then reset state - the user pressed an escaping action key like left/right/space - if you cannot settle on a character in the current state (i.e.
String[]	getCharacterLayout() Array of strings as character rows {"abcd","efgh"...} - use spaces to create gaps
List	getCues() List of all currently active cues to display to the user indicating what a particular keyCode will activate on the screen given the current state of the keyboard handler.
Map	getExtraKeyLabels() To provide a map of any other keys you want displayed to the user with a short label next to them.
void	init(QuickKeyboard keyboard) initialization - handler needs to hold on to this reference to call QuickKeyboard.setCharacter(String), etc., as appropriate.

Method Detail

init

void init(QuickKeyboard keyboard)

initialization - handler needs to hold on to this reference to call QuickKeyboard.setCharacter(String), etc., as appropriate.

getCharacterLayout

String[] getCharacterLayout()

Array of strings as character rows {"abcd","efgh"...} - use spaces to create gaps

Returns:

all rows to be layed out.

getCues

List getCues()

List of all currently active cues to display to the user indicating what a particular keyCode will activate on the screen given the current state of the keyboard handler. Called after getCharacterLayout. Instances will be associated with the created views, so if you re-use your instances, the views will be re-used and may be animated to their new position/size. Instances not re-used will be dereferenced and the views removed.

Returns:

List of QKCue objects

getExtraKeyLabels

Map getExtraKeyLabels()

To provide a map of any other keys you want displayed to the user with a short label next to them. The map should have (key, value) pairs where the key is an Integer object and the value is a String like (new Integer(keyCode),"The Short Label"). This is useful for any non-cue keys the handler supports that the user needs to know about e.g. support for Thumbs Up to change to an Uppercase character set layout. The keyboard will attempt to display this next to the main layout with each pair on a row of its own, so long lists may not display well. Basic implementation should just get QuickKeyboard.getDefaultExtraKeys() and optionally add to that LinkedHashMap before returning it.

buttonPress

boolean buttonPress(int keyCode)

Alters the state of the keyboard handler and may cause a character to be set and possibly the cursor to be advanced. Typically, each button press changes the state until a character is decided on, at which time the handler calls QuickKeyboard.setCharacter(String) and usually QuickKeyboard.nextCharacter(). This is also where the handler should support additional character sets on particular button presses e.g. Thumbs Up/Down for upper/lowercase set. Use getExtraKeyLabels() to provide a list of cues for these mode changing keys. Layout/cues will be requested next.

Parameters:

keyCode - the key pressed by the user

Returns:

true if the key was handled by the keyboard handler (i.e. the button caused s change in the handler's state), false if not (usually would result in a "bonk")

abortCharacter

void abortCharacter()

Reset handler state - the user pressed an aborting key like delete/backspace and the last uncommitted value passed to QuickKeyboard.setCharacter(String) is deleted (no need to do it yourself. layout/cues will be requested next.

finishCharacter

void finishCharacter()

Set a character if you can settle on one in current state, then reset state - the user pressed an escaping action key like left/right/space - if you cannot settle on a character in the current state (i.e. if you were just displaying something that really wasn't chosen by the user), be sure to call QuickKeyboard.setCharacter(String) with a null value here to abort it. layout/cues will be requested next.