KeyCheck Widget Guide
by Jon Lambert

You do not have to give Jon Lambert credit if you use the KeyCheck widget, although it would be appreciated.

The KeyCheck Widget makes it easier to add customizable controls to your game or application. It is comprised of two objects, a Keyboard object called the "KeyCheck Widget - KeyWatcher" and an Active object called the "KeyCheck Widget - KeyBinder". The Keyboard object half has one behavior called "KeyWatcher" and the Active object half has one behavior called "KeyBinder".

To add the KeyCheck Widget to your game or application, you will need to include both the "KeyCheck Widget - KeyBinder" and the "KeyCheck Widget - KeyWatcher" objects in each frame of the application that requires the functionality. The "KeyCheck Widget - KeyBinder" object is defined as a global object, so that you should not have to reload the values into the object at the start of each frame after the initial binding/loading.

The "KeyBinder" behavior has one event. When the object's internal flag 0 is on and a key is pressed, the object will record a string converted into a value into a particular alterable value. The string converted will be the key's value (as defined by the "Key value" expression in the Keyboard object) with a 0 affixed to the end. This is known as the default state. The alterable value is it recorded into will be equal to the value conversion of the "KeyCheck Widget - KeyBinder"'s Alterable String A, known as the BindValue string. As the Active object has a maximum of 26 alterable values, the event will only use values from 0 to 25 (alterable value indexes are 0-based).

For example, if the internal flag 0 is on and the "L" key is pressed, and the BindValue string is equal to "0", then the value "760" will be stored in Alterable Value A (indexed as 0). The "L" key's value as defined by the Keyboard object is 76.

The "KeyWatcher" behavior has five events. The first event is an "Always" event and runs a fastloop called "KeyCheck" 26 times (as there are only 26 alterable values in any Active object.) The second through fifth events all read keystates.

The second event reads whether the key whose value is bound to the alterable value with the same index as the "KeyCheck" loop has just been pressed (that is to say that it was not already being held.) If this is true, the key's value is changed to include a 1 at the end as opposed to a 0. Furthermore, the loop index of the "KeyCheck" loop is incremented by 1 to prevent the key from immediately being detected as having been held.

The third event reads whether the key whose value is bound to the alterable value with the same index as the "KeyCheck" loop had already been held (that is to say that it had not just been pressed.) If this is true, the key's value is changed to include a 2 at the end as opposed to a 0. The event can only be true if the key's stored value ended with a 1. This is to make sure that the key's being pressed and the key's being held can be detected as separate events.

The fourth event reads whether the key whose value is bound to the alterable value with the same index as the "KeyCheck" loop has just been released. If this is true, the key's value is changed to include a 3 at the end as opposed to a 0. 

The fifth event reads whether the key whose value is bound to the alterable value with the same index as the "KeyCheck" loop was not being held. If this is true, the key's value is changed to include a 0 at the end (returning to the default state.) The event can only be true if the key's stored value ended with a 3. This is to make sure that the key's being released and the key's not being held can be detected as separate events.

To detect the keystate of any bound key, simply use a "Compare two general values" event to compare Right$(Str$(AltValN("KeyCheck Widget - KeyBinder",n)),1) to either 0, 1, 2, or 3, where n is the index of the value that the key was bound to. For example, to test whether or not the "L" key (which has been stored in the 0th alterable value) has been held, you would use Right$(Str$(AltValN("KeyCheck Widget - KeyBinder",0)),1) = 2.

KeyCheck Key:
1 = Pressed
2 = Held
3 = Released
0 = Not Held