Key States and Transitions

Each key on your keypad can be in five different states, as defined by the pl_kp_event_codes constant. Here are those states:

0- PL_KP_EVENT_LONGRELEASED: The key has been released "for a while".

1- PL_KP_EVENT_RELEASED: The key has been released (just now).

2- PL_KP_EVENT_PRESSED: The key has been pressed (just now).

3- PL_KP_EVENT_LONGPRESSED: The key has been pressed "for a while".

4- PL_KP_EVENT_REPEATPRESSED: Auto-repeat for the key.

The diagram below shows all key states and possible state transitions.

Possible state transitions are indicated by arrows. Red arrows show transitions for when the key is pressed (or remains pressed), blue -- for when the key is released (or remains released). The time it takes for the key to transition from one state to another is quantified in 10ms intervals. This is the time period at which the kp. object will perform keypad scans. Each transition delay, expressed in 10ms intervals, is defined by a dedicated property, so you can decide for yourself what "just now" and "for a while" mean. Each time the key transitions to the next state, the on_kp event is generated. See Servicing Keypad Events for how to work with events. The keypad object has a buffer that can hold up to 8 keypad events.

When the keypad is enabled (kp.enabled is set to 1- YES), the keypad buffer is cleared and each key's state is set to "longreleased". Press the key long enough, and the key will go into the "pressed" state. From there, the key can go to "released" and, later, "longreleased" if you let go of that key, or into "longpressed" and then "repeatpressed" if you keep the key pressed.

Five available key states, along with adjustable state transition times, allow you to create sophisticated keypad input. For example, it is possible to have a mixed alphanumerical input, like the one used on mobile phones for SMS entry. "Longpressed" events can be assigned to add a digit, for example, "1" if you press the "1ABC" key. "Pressed" events rotate between letters of the key ("A"->"B"->"C"->"A", etc.), unless another key is pressed or rotation times out on "longreleased" event. In both cases, input advances to the next character.