Queue Monitoring

Monitor queue for key press events. More...

Macros
#define	KBD_QUEUE_SIZE   16
	Size of a keyboard queue.
#define	KBD_QUEUE_END   -1
	Delimiter value for kbd_queue_pop()

Functions
void	kbd_set_repeat_timing (uint16_t start, uint16_t interval)
	Configures held key auto-repeat intervals.
int	kbd_queue_pop (maple_device_t *dev, bool xlat)
	Pop a key off a specific keyboard's queue.
void	kbd_set_queue (int active) __deprecated
	Activate or deactivate global key queueing.
int	kbd_get_key (void) __deprecated
	Pop a key off the global keyboard queue.

Detailed Description

Monitor queue for key press events.

Popping from the Queue

One method of checking for key input is to use the internal key press queue. This is most frequently used when keyboard input is used within a text processing context, which is only concerned with individual key press events, rather than the frame-by-frame state.

We simply pop keys off of the queue in a loop, until the queue is empty:

int k;

while((k = kbd_queue_pop(device, 1)) != KBD_QUEUE_END)
    printf("Key pressed: %c!\n", (char)k);

Repeated Presses

As with a text processor, a key which has been held down for a duration of time will generate periodic key press events which will be pushed onto the queue.

Macro Definition Documentation

KBD_QUEUE_END

#define KBD_QUEUE_END   -1

Delimiter value for kbd_queue_pop()

Value returned from kbd_queue_pop() when there are no more keys in the queue.

See also

kbd_queue_pop()

KBD_QUEUE_SIZE

#define KBD_QUEUE_SIZE   16

Size of a keyboard queue.

Each keyboard queue will hold this many elements. Once the queue fills, no new elements will be placed on the queue. As long as you check the queue relatively frequently, the default of 16 should be plenty.

Note

This MUST be a power of two.

Function Documentation

kbd_get_key()

int kbd_get_key

(

void

)

Pop a key off the global keyboard queue.

Deprecated

This function pops the front off of the keyboard queue, and returns the value to the caller. The value returned will be the ASCII value of the key pressed (accounting for the shift keys being pressed).

If a key does not have an ASCII value associated with it, the raw key code will be returned, shifted up by 8 bits.

Returns

The value at the front of the queue, or KBD_QUEUE_END if there are no keys in the queue or queueing is off.

Note

This function does not account for non-US keyboard layouts properly (for compatibility with old code), and is deprecated. Use the individual keyboard queues instead to properly account for non-US keyboards.

See also

kbd_queue_pop()

kbd_queue_pop()

int kbd_queue_pop	(	maple_device_t *	dev,
		bool	xlat )

Pop a key off a specific keyboard's queue.

This function pops the front element off of the specified keyboard queue, and returns the value of that key to the caller.

If the xlat parameter is true and the key represents an ISO-8859-1 character, that is the value that will be returned from this function. If the key cannot be converted into a valid ISO-8859-1 character the raw key code, shifted up by 8 bits, will be returned.

If the xlat parameter is false, the lower 8 bits of the returned value will be the raw key code. The next 8 bits will be the modifier keys that were down when the key was pressed (kbd_mods_t). The next 8 bits will be the lock key/LED statuses (kbd_leds_t).

Parameters

dev	The keyboard device to read from.
xlat	Set to true to do key translation. Otherwise, you'll simply get the raw key value. Raw key values are not mapped at all, so you are responsible for figuring out what it is by the region.

Returns

The value at the front of the queue, or KBD_QUEUE_END if there are no keys in the queue.

kbd_set_queue()

void kbd_set_queue

(

int

active

)

Activate or deactivate global key queueing.

Deprecated

This function will turn the internal keyboard queueing on or off. Note that there is only one queue for the whole system, no matter how many keyboards are attached, and the queue is of fairly limited length. Turning queueing off is useful (for instance) in a game where individual keypresses don't mean as much as having the keys up or down does.

You can clear the queue (without popping all the keys off) by setting the active value to a different value than it was.

The queue is by default on, unless you turn it off.

Parameters

active

Set to non-zero to activate the queue.

Note

The global queue does not account for non-US keyboard layouts and is deprecated. Please use the individual queues instead for future code.

kbd_set_repeat_timing()

void kbd_set_repeat_timing	(	uint16_t	start,
		uint16_t	interval )

Configures held key auto-repeat intervals.

This function is used to configure the specific timing behavior for how the internal queue treats a key which is being held down. Giving non-zero values for both parameters will cause the held key to be re-enqueued every interval milliseconds after it has been held for the initial start time in milliseconds.

Specifying a value of zero for the two parameters disables this repeating key behavior.

Note

By default, the start time is 600ms while the repeating interval is 20ms.

Parameters

start	The duration after which the held key starts to register as repeated key presses (or zero to disable this behavior).
interval	The duration between subsequent key repeats after the initial start time has elapsed.

See also

kbd_queue_pop()