libnds key input functions (ARM9)
libnds contains a set of wrapper functions around the raw KEYS register, which hide the missing X and Y buttons on the ARM9, and provide a couple of useful additional features.
scanKeys()
This function should be called once a frame to update the cached key state.
keysHeld()
Returns the keys that were down as of the last time scanKeys was called.
keysDown()
Returns the keys that were up two calls to scanKeys ago, but were down as of the time scanKeys() was called. This is very useful for making actions that need to occur only when a user first pushes a button, like moving down one in a menu selection.
keysUp()
Returns the keys that were down two calls to scanKeys ago, but were up as of the time scanKeys was called. This could be used to stop an action started by watching keysDown, e.g. a high jump where the time elapsed between the button being returned by keysDown and by keysUp specifies how high to jump.
Key defines
Each of the keyXXX calls returns a bitmask of these constants:
KEY_A
KEY_B
KEY_SELECT
KEY_START
KEY_RIGHT
KEY_LEFT
KEY_UP
KEY_DOWN
KEY_R (Right shoulder button)
KEY_L (Left shoulder button)
KEY_X
KEY_Y
KEY_TOUCH (Whether or not the TSC thinks there is a press)
KEY_LID (The magnetic hinge sensor)
Notes:
- Down means pushed, and up means released.
KEYS register (ARM7, ARM9)
| Register | Address:Width | Access | 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| KEYS | 0x04000130:16 | R | 000000 | L | R | down | up | left | right | start | select | B | A |
| KEYS_CR | 0x04000132:16 | R/W | Mode | IRQ | 0000 | L | R | down | up | left | right | start | select | B | A |
Each key normally reads as 1, becomming zero when depressed. Bits 15..10 typically read as 0, but this behavior should not be relied on: always mask off the high bits. A typical method of reading the keys is:
uint16 keysPressed = (~KEYS) & 0x3FF;
where each non-zero bit in keysPressed represents a pressed key.
An interrupt is only generated if the IRQ bit is set, and the keys pressed match the bits specified in KEYS_CR under the condition set by Mode.
Mode:
- 0: An interrupt is generated if any key specified is pressed (or)
- 1: An interrupt is generated only if all keys speciifed are pressed (and)
XKEYS (0x04000136:16) (ARM7 only)
| 15..8 | Other purposes, dunno yet |
| 7 | R | Hinge |
| 6 | R | Pen down |
| 1 | R | Y |
| 0 | R | X |
X and Y behave the same as other buttons (normally high, pulled low when pressed). The pen down bit will be cleared if the touch pad is being touched.
The hinge sensor is a small hall effect sensor (or other magnetic sensing device) above the ABXY cluster of buttons, which detects the speaker magnet as the case is closed. This sensor has the ability to generate an interrupt when opened (see Interrupts).