Avigo FwSDK Keyboard input routines library v1.0
Written for Avigo FwSDK v0.92 beta 3
By Sam Rauch
srauch@umich.edu

***IF YOU MAKE ANY ENHANCEMENTS OR FIND ANY BUGS PLEASE LET ME KNOW SO THAT I
CAN UPDATE THE GENERAL RELEASE***

The Avigo FwSDK keyboard input routines consist of two files: keyboard.h
and keyboard.c  (and a number of other files to allow you to build the .rel file
and a sample application)

keyboard.h provides all the headers and #define's that should be necessary to
use the keyboard input routines within your app.

keyboard.c defines those functions as well as additional functions and variables.
You SHOULD NOT have to access the additional functions defined in keyboard.c - If
you find it necessary to do so, please let me know what you are doing so that I
can provide a way for others to do the same.

When compiled, this code should take up only a few bytes in the 16K RAM bank and
around a third of a code bank.

HOW TO USE IT
-------------
I suggest you compile the sample project, then place keyboard.h in 
your [avigosdk]/inc directory and keyboard.rel in your [avigosdk]/lib directory.
This way you can use the keyboard in any app you develop.  If you include
keyboard.rel in your app, you should also include avicons.rel since the keyboard
uses the system icons.

WHAT IT DOES
------------
The keyboard library provides 5 functions:
void open_keyboard(unsigned char mode);
void open_keyboard_extended(unsigned char mode, unsigned char backup, int x, int y);
char keyboard_is_open();
unsigned char check_keyboard(int key, unsigned char x, unsigned char y);
void close_keyboard();

open_keyboard*
	initiliaze the keyboard and display it on the screen.
keyboard_is_open
	return 1 or 0 depending on whether the keyboard is open.
check_keyboard
	return the character, if any, that the user has entered on the keyboard
close_keyboard
	reset state variables and restore the LCD screen behind the keyboard if
	it was backed up

For details on how to use the functions, please look at keyboard.h

The keyboard is like the standard Avigo keyboard in that:
	1. All of the options on the keyboard are available - shift, caps, accents, symbols, etc.
	2. The transition between states (see note below) is the just like it is on the Avigo keyboard
	3. It provides access to the password keyboard.
	4. It is compatible with all available Avigo Language packages

The keyboard library WILL NOT keep track of the entire string you have entered.
You are responsible for displaying the text entered.

LANGUAGE COMPATIBILITY
----------------------
The keyboard library will identify the language type of the Avigo it is running
on and enter characters appropriately.  It is my understanding that the German
keyboard is different from the English keyboard in only 1 key, the French 
keyboard has different placement for a handful of keys, and the Italian and
Spanish keyboards are identical to the English keyboard.  I have tested the
library with system software for all of these languages and it seems to work just
fine.  If you find that it has an incompatibility with your Avigo, please let me
know and I will try to get it fixed.

KEYBOARD STATE TRANSITION
-------------------------
The Avigo provides something like 20 different keyboard images for different
"keyboard states".  I looked at how the Avigo moves between each and have
done my best to re-create it.  If I have made a mistake, please let me know.  The
information in this section is not really important unless you are curious about
what the keyboard will do when you start it in a certain state or just wanted to
figure out what I meant by "keyboard states..."
The state transition rules are roughly:

PASSWORD
1. The PASSWORD keyboard always stays in the PASSWORD state
NORMAL
1. Keyboard can start in a state I will call "First Capitalized" - In this state
all the letters are capitalized, but neither the shift key nor the caps key are
highlighted.  Pressing any key will go to the NORMAL state (or CAPS if CAPS was
pressed, SHIFT if shift was pressed, etc.)
2. CAPS state is toggled with the CAPS button
3. SHIFT state is toggled with the SHIFT button
4. ACCENT states - pressing any accent button will clear any other accent state
and set the keyboard to its own accent state. (or toggle the accent off if it
was already on)
5. Pressing SYMBOL will go the the SYMBOL keyboard and clear any other state
6. Entering a regular key will clear any state that was set except CAPS (including 
SYMBOL) and go back to the NORMAL state (or CAPS)

Release Notes
-------------
v1.0
	-Initial release
