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.
typedef void(*	KeyPutcCallback) (int)
	Callback used when libnds wants to push characters to the stdin FIFO.
typedef int(*	KeyUpdateCallback) (void)
	Callback to handle touch screen press/release events.

Enumerations
enum	KeyboardModifierMode {   KeyboardModifiersIgnore ,   KeyboardModifiersStickOnce ,   KeyboardModifiersStickAlways }
	Modes of handling CTRL and ALT buttons. More...
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 = '\t' ,   DVK_BACKSPACE = '\b' ,   DVK_CAPS = -15 ,   DVK_SHIFT = -14 ,   DVK_SPACE = ' ' ,   DVK_MENU = -5 ,   DVK_ENTER = '\n' ,   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.
int	keyboardFifoGetc (void)
	Fetches the first character available from the keyboard FIFO.
int	keyboardFifoPutc (char kc)
	Manually add a character to the keyboard FIFO.
void	keyboardFifoStart (void)
	Initializes the keyboard FIFO.
size_t	keyboardFifoStoredCharacters (void)
	Returns the number of characters currently available in the keyboard FIFO.
int	keyboardFifoUnputc (void)
	Try to remove the last character pushed to the keyboard FIFO.
void	keyboardFifoUpdate (void)
	Checks the state of the keyboard and saves key presses in the FIFO buffer.
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.
bool	keyboardIsVisible (void)
	Check if the active keyboard is visible or not.
int	keyboardModifierModeSet (KeyboardModifierMode mode)
	Changes the behaviour of the CTRL and ALT keys of the current 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

KeyboardModifierMode

enum KeyboardModifierMode

Modes of handling CTRL and ALT buttons.

Enumerator
KeyboardModifiersIgnore	CTRL and ALT are treated like all other buttons. Default behaviour.
KeyboardModifiersStickOnce	CTRL and ALT are held until another key is pressed (not CTRL or ALT).
KeyboardModifiersStickAlways	CTRL and ALT are held until they are pressed again.

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

keyboardFifoGetc()

int keyboardFifoGetc

(

void

)

Fetches the first character available from the keyboard FIFO.

This can be useful when using a custom keyboard, but not using OS functions like read().

Returns

It returns a character from the FIFO. If empty, it returns -1.

keyboardFifoPutc()

int keyboardFifoPutc

(

char

kc

)

Manually add a character to the keyboard FIFO.

This can be useful when simulating keyboard input.

A keyboard must be initialized before using this function. If you want to use a completely custom keyboard (not the libnds one) you need to call keyboardFifoStart() before using this.

Parameters

kc	The character to add to the FIFO.

Returns

On success it returns 0, if the FIFO is full it returns a negative value.

keyboardFifoStoredCharacters()

size_t keyboardFifoStoredCharacters

(

void

)

Returns the number of characters currently available in the keyboard FIFO.

Returns

The number of available characters to be read.

keyboardFifoUnputc()

int keyboardFifoUnputc

(

void

)

Try to remove the last character pushed to the keyboard FIFO.

This only works while there are entries in the FIFO. If they have been read already, this function does nothing.

Returns

It returns the key that hasn't been removed from the FIFO, or NOKEY if the buffer was empty.

keyboardFifoUpdate()

void keyboardFifoUpdate

(

void

)

Checks the state of the keyboard and saves key presses in the FIFO buffer.

If your application wants to do non-blocking reads of stdin it must regularly call this function so that key presses are registered and stored in the input FIFO buffer. You must call scanKeys() regularly as well.

This is only needed if you want to use the standard syscalls read(), ioctl() and fcntl() to access keyboard input. For example, this can be very useful if you're porting applications to the DS. If you are creating a new DS-specific application, use keyboardUpdate() instead, which is more efficient.

A keyboard must be initialized before using this function. If you want to use a completely custom keyboard (not the libnds one) you need to call keyboardFifoStart() before using this.

consoleDemoInit();
 
// Initialize demo keyboard and load graphics to VRAM
Keyboard *kbd = keyboardDemoInit();
keyboardShow();
 
int opt = 1;
ioctl(STDIN_FILENO, FIONBIO, &opt);
 
while (true)
{
    scanKeys();
    keyboardFifoUpdate();
 
    char buffer[50];
    size_t num = read(STDIN_FILENO, buffer, sizeof(buffer) - 1);
    buffer[num] = '\0';
 
    if (num > 0)
        printf("[%s] %zu chars\n", buffer, num);
}

You can also query the amount of characters in stdin available to be read;

int num;
if (ioctl(stdin, FIONREAD, &num) > 0)
    printf("Bytes available: %d\n", num);
else
    printf("Error\n");

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

keyboardIsVisible()

bool keyboardIsVisible

(

void

)

Check if the active keyboard is visible or not.

Returns

Returns true if the keyboard is visible, false if not.

keyboardModifierModeSet()

int keyboardModifierModeSet

(

KeyboardModifierMode

mode

)

Changes the behaviour of the CTRL and ALT keys of the current keyboard.

Normally the CTRL and ALT keys are treated like other keys. It is possible to make them "sticky" and remain pressed until another key is pressed or to make them remain pressed until they are pressed again, depending on what your application requires.

Parameters

mode	New mode to set.

Returns

On success it returns 0, on error it returns a negative number.

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.