Key States and Transitions
Each key on your keypad can be in one of the five states, as defined by the pl_kp_event_codes constant:
0- PL_KP_EVENT_LONGRELEASED: The key has been released "a while ago".
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 "a while ago".
4- PL_KP_EVENT_REPEATPRESSED: Auto-repeat for the key.
The following diagram shows all key states and possible state transitions:
Red arrows show transitions for when the key is pressed (or remains pressed), blue — for when the key is released (or remains released). Each time a key transitions to the next state, this change is recorded into the keypad event FIFO, which has the depth of 8 states.
Enabling the keypad object (setting kp.enabled = 1- YES) clears the keypad event FIFO and sets each key's state 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.
On matrix keypads, the kp. object will track the state of all keys on the keypad simultaneously, and it is possible to press several keys at once — state transitions will be recorded independently for each key. Binary keypads only allow to track a single key at a time. This is because a binary keypad is only capable of sending a single key code at any given moment.
The time it takes for a key to transition from one state to another is quantified in 10ms intervals. This is the time period at which the kp. object "pings" the keypad. Each transition's delay, expressed in 10ms intervals, is defined by a dedicated property, so you can decide for yourself what "just now" and "a while ago" mean. The properties are: kp.longpressdelay, kp.longreleasedelay, kp.pressdelay, kp.releasedelay, and kp.repeatdelay. Five available key states, along with adjustable state transition times, allow you to create sophisticated keypad input and get away with having fewer keys.
In addition, kp.autodisablecodes property allows you to define a list of keys and their state transitions that will cause the keypad to be disabled (kp.enabled=0 - NO). Keypad auto-disabling may be very useful. For example, if your keypad has keys <0> ~ <9>, <ENTER>, and <CANCEL>, then you can set kp.autodisablecodes to the key code of the <ENTER> key and select _PRESSED as the auto-disabling state. Meaning, as soon as the <ENTER> key is pressed, the keypad will be disabled for further input until you re-enable it by setting kp.enabled= 1- YES.
If the kp.genkpevent= 1- YES then your app gets one on_kp event for each state transition (for each keypad event in the FIFO). If the kp.genkpevent= 0- NO, then you will need to poll for state transitions using the kp.getkey method. More on this in Receiving Keypad Events Through On_kp Events and Receiving Keypad Events Using Kp.getkey Method.
Note that there is an additional state on the diagram. It is called "lockup" and it happens when a key stays pressed for kp.lockupdelay number of 10ms intervals. Lockups (stuck keys) can happen on a keypad of any type. Capacitive sensor keypads are especially prone to lockups caused by ESD and moisture (a droplet of water is often indistinguishable from a finger touching on a key). Note that "lockup" is not a key state. Rather, it is a condition of the keypad as a whole. Once the lockup condition is detected the keypad is disabled (kp.enabled= 0- NO).