KeypadInputWindow Class Reference

Implements window with keypad access functionality Creates a window that captures input from the keypad. Provides methods for entering data using a mobile-style user experience. More...

#include <KeypadInputWindow.h>

List of all members.

Public Types

enum  InputMode { INPUT_123, INPUT_ABC, INPUT_abc, INPUT_DISABLED }
enum  InputModeChange { INPUT_NO_CHANGE, INPUT_NUMBER_MODE_CHANGE, INPUT_CAPSLOCK_MODE_CHANGE }

Public Member Functions

 KeypadInputWindow (int idResource)
 Default constructor Initializes the class and sets the keypad into uppercase character mode.
virtual ~KeypadInputWindow ()
 Class destructor Uninitializes the window.
InputMode getInputMode ()
 Return the current input mode Returns the input mode the keypad is currently put into.

Protected Member Functions

virtual void onKeyPress (int keyCode, bool shiftDown)=0
 Key press event Implementation should override this function to implement method that will be executed when user presses (but does not release) the button on keypad.
virtual void onStaticScreenKeyPress (int keyCode)=0
 Receive basic input only Implementation should override this function to implement method that will be executed when advanced keypad handling features are disabled and only basic keypresses are accepted.
virtual void onKeyRelease (int keyCode, bool shiftDown)=0
 Key release event Implementation should override this function to implement method that will be executed when user has released the button on keypad.
virtual void onFunctionAccess (int fn)=0
 Function key press event Implementation should override this function to implement method that will be executed when user has pressed the one of the function keys (F1...F10) on keypad.
virtual bool onCharInput (unsigned char in, InputModeChange inputModeChange, bool commitNow)=0
 Character input event Implementation should override this function to implement method that will be executed every time the user has pressed (and released) the key. The method captures every character the user has selected. With multiple keypresses on one button this method is called every time to preview the character currently chosen.
virtual void onCharCommit ()=0
 Character commit event Implementation should override this function to implement method that will be executed every time the character commit timeout has passed. In that case the last temporary character (that was sent to onCharInput()) should be taken as the final character that will not change anymore.
virtual bool specialFunction (int keyCode)=0
 Special function keypress event Implementation should override this function to implement method that will be executed every time the user has pressed the key. This method can be used to trap special keypressed that should be handled differently. If the return code is false no further processing of the keypress will be done and the keypress is considered handled here.
virtual bool onDelete (bool delAll)=0
 Delete key press event Implementation should override this function to implement method that will be executed every time the user has pressed the DEL key. The method will detect if the delete key was pressed shortly or was held down for longer time.
virtual void onMenu ()=0
 Menu key press event Implementation should override this function to implement method that will be executed every time the user has pressed the MENU key.
virtual bool inputEnabled ()=0
 General keypress event Implementation should override this function to implement method that will be executed every time the user has pressed the key on a keypad. This method is used to capture the keypresses and optionally discard them.
virtual void onInitialize ()=0
 Initialization event handler Implementation should override this function to implement method that will be executed when the window is being initialized.
virtual bool onKeyDown (int keyCode)
 Key press event Method is called when user presses a key (but does not release it).
virtual bool onKeyUp (int keyCode)
 Key release event Method is executed when user releases the pressed key.
virtual void onTimer (int idTimer)
 Execute when the waiting timers are fired Method is executed if any of the timers associated with keypad input are fired.
virtual void onClose ()
 Process the window close event Processes the window close event, stops all the active timers.
virtual bool onModalFinished (GuiWindow *pModal)
 Process the modal window close event Processes the event of closing the modal child window, resets the shift flag.
void setNumberMode (bool newMode)
 Enable or disable the number mode Enables or disables the numeric mode of the keypad. Triggers the onCharInput() method with INPUT_NUMBER_MODE_CHANGE event.

Protected Attributes

bool staticTextOnly

Detailed Description

Implements window with keypad access functionality Creates a window that captures input from the keypad. Provides methods for entering data using a mobile-style user experience.

Keypad can be put into numeric, uppercase or lowercase mode. In character mode different characters can be selected by pressing the appropriate keypad button repeatedly. When using numeric mode, the numbers can be directly entered without multiple keypresses.

This class provides methods for handling the input events that will be generated by use cases described above.


Member Enumeration Documentation

Keypad input modes

Enumerator:
INPUT_123 

Numeric mode

INPUT_ABC 

Uppercase character mode

INPUT_abc 

Lowercase character mode

INPUT_DISABLED 

Input disabled

Input mode changes

Enumerator:
INPUT_NO_CHANGE 

No change occurred

INPUT_NUMBER_MODE_CHANGE 

Changed number mode to character mode or vice versa

INPUT_CAPSLOCK_MODE_CHANGE 

Changed character mode to uppercase or lowercase


Constructor & Destructor Documentation

KeypadInputWindow::KeypadInputWindow ( int  idResource  ) 

Default constructor Initializes the class and sets the keypad into uppercase character mode.

Parameters:
idResource Unique window identifier

Member Function Documentation

KeypadInputWindow::InputMode KeypadInputWindow::getInputMode (  ) 

Return the current input mode Returns the input mode the keypad is currently put into.

Returns:
Returns input mode
virtual bool KeypadInputWindow::inputEnabled (  )  [protected, pure virtual]

General keypress event Implementation should override this function to implement method that will be executed every time the user has pressed the key on a keypad. This method is used to capture the keypresses and optionally discard them.

Returns:
Returns true if the keypress should be handled by all other methods. If returns false then the keypress event will be discarded.
virtual bool KeypadInputWindow::onCharInput ( unsigned char  in,
InputModeChange  inputModeChange,
bool  commitNow 
) [protected, pure virtual]

Character input event Implementation should override this function to implement method that will be executed every time the user has pressed (and released) the key. The method captures every character the user has selected. With multiple keypresses on one button this method is called every time to preview the character currently chosen.

Parameters:
in Character currently selected. This is the C char value, not the button identifier!
inputModeChange Set to one of the input mode change values to specify if the input mode was changed during the keypress process (i.e. changing uppercase to lowercase)
commitNow If set to true, this is the final character that will not be changed
Returns:
Returns true if the character input event was handled successfully.
virtual bool KeypadInputWindow::onDelete ( bool  delAll  )  [protected, pure virtual]

Delete key press event Implementation should override this function to implement method that will be executed every time the user has pressed the DEL key. The method will detect if the delete key was pressed shortly or was held down for longer time.

Parameters:
delAll Set to true if the DEL key was pressed for longer time (indicating that the user would like to delete all data (i.e. clear the field completely).
Returns:
Returns true if the key press event was handled successfully.
virtual void KeypadInputWindow::onFunctionAccess ( int  fn  )  [protected, pure virtual]

Function key press event Implementation should override this function to implement method that will be executed when user has pressed the one of the function keys (F1...F10) on keypad.

Parameters:
fn Identifier of the function key pressed
bool KeypadInputWindow::onKeyDown ( int  keyCode  )  [protected, virtual]

Key press event Method is called when user presses a key (but does not release it).

Parameters:
keyCode Identifier of the button the user is pressing
Note:
The keyCode is not the character code

The following methods are invoked:

  • If the menu button is pressed, the onMenu() method is called
  • If shift key is pressed, the shift flag is set
  • If keypad input is disabled, no further keypresses are checked
  • Execute the onKeyPress() method
Returns:
Returns true if the keypress was handled.
virtual void KeypadInputWindow::onKeyPress ( int  keyCode,
bool  shiftDown 
) [protected, pure virtual]

Key press event Implementation should override this function to implement method that will be executed when user presses (but does not release) the button on keypad.

Parameters:
keyCode Identifier of the button being pressed
shiftDown Set to true, if the shift button is also pressed
virtual void KeypadInputWindow::onKeyRelease ( int  keyCode,
bool  shiftDown 
) [protected, pure virtual]

Key release event Implementation should override this function to implement method that will be executed when user has released the button on keypad.

Parameters:
keyCode Identifier of the button being released
shiftDown Set to true, if the shift button was also pressed
bool KeypadInputWindow::onKeyUp ( int  keyCode  )  [protected, virtual]

Key release event Method is executed when user releases the pressed key.

Parameters:
keyCode Identifier of the button the user is pressing
Note:
The keyCode is not the character code

The following methods are invoked:

  • If shift is released, the shift flag will be reset
  • If keypad is disabled no further processing occurs
  • If shift is released after a delay put the keypad in number mode
  • Execute the onKeyRelease() method
Returns:
Returns true if key release event was successfully handled.
bool KeypadInputWindow::onModalFinished ( GuiWindow *  pModal  )  [protected, virtual]

Process the modal window close event Processes the event of closing the modal child window, resets the shift flag.

Parameters:
pModal Pointer to the modal window that is being closed
Returns:
Returns true
virtual void KeypadInputWindow::onStaticScreenKeyPress ( int  keyCode  )  [protected, pure virtual]

Receive basic input only Implementation should override this function to implement method that will be executed when advanced keypad handling features are disabled and only basic keypresses are accepted.

Parameters:
keyCode Identifier of the button that was pressed
void KeypadInputWindow::onTimer ( int  idTimer  )  [protected, virtual]

Execute when the waiting timers are fired Method is executed if any of the timers associated with keypad input are fired.

There are two timers associated with the keypad:

  • TIMER_ID_WAITKEYS - Waits for further keypresses and if the period elapses the character selected will be committed using the onCharCommit() method
  • TIMER_ID_HOLDKEYS - Waits to react to user event of holding down the key for a specific time. For example holding down the shift key triggers case mode change, holding down delete triggers onDelete() method to execute.
Parameters:
idTimer Identification to the timer that was fired
void KeypadInputWindow::setNumberMode ( bool  newMode  )  [protected]

Enable or disable the number mode Enables or disables the numeric mode of the keypad. Triggers the onCharInput() method with INPUT_NUMBER_MODE_CHANGE event.

Parameters:
newMode Set to ture to enable numeric mode, false to disable it.
virtual bool KeypadInputWindow::specialFunction ( int  keyCode  )  [protected, pure virtual]

Special function keypress event Implementation should override this function to implement method that will be executed every time the user has pressed the key. This method can be used to trap special keypressed that should be handled differently. If the return code is false no further processing of the keypress will be done and the keypress is considered handled here.

Parameters:
keyCode Identifier of the button being pressed
Returns:
Returns true if the keypress was a special function keypress and no further processing should be done. If set to false all other methods for handlng the keypress will be executed as well.

Member Data Documentation

If set to true, no advanced keypad events are handled. With every keypress only the onStaticScreenKeyPress() is called


The documentation for this class was generated from the following files:
Generated on Wed Oct 20 11:13:44 2010 for libspatha by  doxygen 1.6.3