keyboard.h File Reference

Integration of stdin with a simple keyboard. More...

#include <nds/arm9/background.h>
#include <nds/ndstypes.h>

Data Structures
struct	Keyboard
	Describes a keyboard. More...
struct	KeyMap
	Defines a key mapping. More...

Typedefs
typedef struct Keyboard	Keyboard
	Describes a keyboard.
typedef void(*	KeyChangeCallback) (int key)
	Callback function pointer when a key changes.
typedef struct KeyMap	KeyMap
	Defines a key mapping.

Enumerations
enum	KeyboardState {   Lower = 0 ,   Upper = 1 ,   Numeric = 2 ,   Reduced = 3 }
	States the keyboard can be in, currently only Lower and Upper supported. More...
enum	Keys {   NOKEY = -1 ,   DVK_FOLD = -23 ,   DVK_TAB = 9 ,   DVK_BACKSPACE = 8 ,   DVK_CAPS = -15 ,   DVK_SHIFT = -14 ,   DVK_SPACE = 32 ,   DVK_MENU = -5 ,   DVK_ENTER = 10 ,   DVK_CTRL = -16 ,   DVK_UP = -17 ,   DVK_RIGHT = -18 ,   DVK_DOWN = -19 ,   DVK_LEFT = -20 ,   DVK_ALT = -26 }
	Enum values for the keyboard control keys. More...

Functions
Keyboard *	keyboardDemoInit (void)
	Initializes the default keyboard of libnds.
void	keyboardExit (void)
	De-initializes the keyboard system, if initialized.
s16	keyboardGetChar (void)
	Waits for user to press a key and returns the key pressed.
const Keyboard *	keyboardGetDefault (void)
	Gets the default keyboard.
s16	keyboardGetKey (int x, int y)
	Returns the ASCII code for the key located at the supplied x and y.
void	keyboardGetString (char *buffer, int maxLen)
	Reads the input until a the return key is pressed or the maxLen is exceeded.
void	keyboardHide (void)
	Hides the keyboard.
static Keyboard *	keyboardInit (const Keyboard *keyboard, int layer, BgType type, BgSize size, int mapBase, int tileBase, bool mainDisplay, bool loadGraphics)
	Initializes the keyboard system with the supplied keyboard.
void	keyboardShow (void)
	Displays the keyboard.
s16	keyboardUpdate (void)
	Processes the keyboard.

Detailed Description

Integration of stdin with a simple keyboard.

The keyboard component allows the use of a default keyboard via stdin as well as direct via the functions exposed below. The default behavior is a hidden keyboard that shows on a call to scanf(stdin, ...).

By default the keyboard uses background 3 of the sub display, consumes approximatly 40 KiB of background VRAM begining at tile base 0 and 4 KiB of map stored at map base 20. The default is designed to work alongside an instance of the demo console.

To customize keyboard behavior and resource usage modify the keyboard structure returned by keyboardGetDefault() or create your own keyboard.

Enumeration Type Documentation

KeyboardState

enum KeyboardState

States the keyboard can be in, currently only Lower and Upper supported.

Enumerator
Lower	Normal keyboard display (lowercase letters)
Upper	Caps lock held.
Numeric	Numeric only keypad (not provided by the default keyboard)
Reduced	Reduced footprint keyboard (not provided by the default keyboard)

Keys

enum Keys

Enum values for the keyboard control keys.

Negative values are keys with no sensible ASCII representation. Numbers are chosen to mimic ASCII control sequences.

Enumerator
NOKEY	No key was pressed.
DVK_FOLD	Fold key (top left on the default keyboard)
DVK_TAB	Tab key.
DVK_BACKSPACE	Backspace.
DVK_CAPS	Caps key.
DVK_SHIFT	Shift key.
DVK_SPACE	Space key.
DVK_MENU	Menu key.
DVK_ENTER	Enter key.
DVK_CTRL	Ctrl key.
DVK_UP	Up key.
DVK_RIGHT	Right key.
DVK_DOWN	Down key.
DVK_LEFT	Left key.
DVK_ALT	Alt key.

Function Documentation

keyboardDemoInit()

Keyboard * keyboardDemoInit

(

void

)

Initializes the default keyboard of libnds.

Same as calling:

keyboardInit(NULL, 3, BgType_Text4bpp, BgSize_T_256x512, 20, 0, false, true)

Returns

A pointer to the new active keyboard, which you can modify (to setup key press and key release callbacks, for example).

keyboardExit()

void keyboardExit

(

void

)

De-initializes the keyboard system, if initialized.

After calling this function you'll need to call keyboardInit() again to use the keyboard, so it is safe to free any struct that you may have allocated (for example, if you're using a custom keyboard).

keyboardGetChar()

s16 keyboardGetChar

(

void

)

Waits for user to press a key and returns the key pressed.

Use keyboardUpdate instead for async operation.

Remember to call scanKeys() every frame if you use keyboardGetChar().

Returns

The key pressed.

keyboardGetDefault()

const Keyboard * keyboardGetDefault

(

void

)

Gets the default keyboard.

Returns

Returns a read-only pointer to the default keyboard.

keyboardGetKey()

s16 keyboardGetKey	(	int	x,
		int	y
	)

Returns the ASCII code for the key located at the supplied x and y.

Will not effect keyboard shift state.

Parameters

x	The pixel x location.
y	The pixel y location.

Returns

The key pressed or NOKEY if user pressed outside the keypad.

keyboardGetString()

void keyboardGetString	(	char *	buffer,
		int	maxLen
	)

Reads the input until a the return key is pressed or the maxLen is exceeded.

Parameters

buffer	A buffer to hold the input string
maxLen	The maximum length to read

keyboardHide()

void keyboardHide

(

void

)

Hides the keyboard.

If scrollSpeed has been set to a non-zero value it will scroll it out of the screen. If not, it will hide it right away.

keyboardInit()

static Keyboard * keyboardInit ( const Keyboard *  keyboard, int  layer, BgType  type, BgSize  size, int  mapBase, int  tileBase, bool  mainDisplay, bool  loadGraphics  )

inlinestatic

Initializes the keyboard system with the supplied keyboard.

Note

If you pass a custom keyboard struct to this function, make sure that the pointer is never deallocated while the keyboard is in use. That pointer will be used to restore the keyboard to the right state every time it is hidden and shown again on the screen.

Parameters

keyboard	The keyboard struct to initialize (can be NULL).
layer	The background layer to use.
type	The background type to initialize.
size	The background size to initialize.
mapBase	The map base to use for the background.
tileBase	The graphics tile base to use for the background.
mainDisplay	If true the keyboard will render on the main display.
loadGraphics	If true the keyboard graphics will be loaded.

Returns

A pointer to the new active keyboard, which you can modify (to modify the key press and key release callbacks, for example).

keyboardShow()

void keyboardShow

(

void

)

Displays the keyboard.

This will set the state of the keyboard to the original one (the one it had when the keyboard was initialized). If the default state of the keyboard is to show upper-case letters, this will return to that state.

keyboardUpdate()

s16 keyboardUpdate

(

void

)

Processes the keyboard.

Should be called once per frame when using the keyboard in an async manner.

Remember to call scanKeys() every frame if you use keyboardUpdate().

Returns

The ASCII code of the key pressed or NOKEY if no key was pressed.