JoyCheck Widget Guide
by Jon Lambert

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

The JoyCheck Widget makes it easier to add customizable controls to your game or application. It is comprised of one or two objects, a Joystick 2 object called the "JoyCheck Widget" and an Active object called the "JoyCheck Widget - JoySaver". The Joystick 2 object has two behaviors, one called "JoyBinder" and one called "JoyWatcher". The Active object has one behavior called "JoySaver".

To add the JoyCheck Widget to your game or application, you will need to include either the "JoyCheck Widget" object alone or both the "JoyCheck Widget" object and the "JoyCheck Widget - JoySaver" objects in each frame of the application that requires the functionality. The "JoyCheck Widget - JoySaver" 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 "JoyCheck Widget - JoySaver" object is only necessary if you require the functionality in more than one frame, but is absolutely necessary if such is the case, as the Joystick 2 object cannot be made global and as a result cannot store the alterable values across frames.

The "JoyBinder" behavior has one event. When the object's internal flag 0 is on and a button is pressed on a particular joystick, the object will record a string converted into a value into a particular alterable value. The string converted will be the button's value (as defined by the "Last single button released" expression in the Joystick 2 object) with a 0 affixed to the end. This is known as the default state. The object will only accept input from the joystick whose value is equal to the value conversion of the JoyCheck Widget's Alterable String A, known as the JoyStick string. As the JoyStick 2 object only supports up to 16 joysticks, the event will only use values from 1 to 16. The alterable value is it recorded into will be equal to the value conversion of the JoyCheck Widget's Alterable String B, known as the BindValue string. As the JoyStick 2 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 1 button is pressed, and the BindValue string is equal to "0", then the value 10 will be stored in Alterable Value A (indexed as 0).

The "JoyWatcher" behavior has five events. The first event is an "Always" event and runs a fastloop called "JoyCheck" 26 times (as there are only 26 alterable values in any Joystick 2 object.) The second through fifth events all read buttonstates.

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

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

The fourth event reads whether the button whose value is bound to the alterable value with the same index as the "JoyCheck" 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 button whose value is bound to the alterable value with the same index as the "JoyCheck" loop was not being held. If this is true, the button's value is changed to include a 0 at the end (returning to the default state.) The event can only be true if the button's stored value ended with a 3. This is to make sure that the button's being released and the button's not being held can be detected as separate events.

The "JoySaver" behavior has three events. The first event is a "Start of Frame" event that runs a fastloop called "JoyRestore" 26 times (as there are only 26 alterable values in any Active or Joystick 2 object.) The second event copies the value of the "JoyCheck Widget - JoySaver" object whose index is equal to the loop index of the "JoyRestore" loop to the Joystick 2 object's value whose index is equal to the loop index of the "JoyRestore" loop.

The third event is true every time the JoyCheck loop is run, and records the default state of each button bound to the JoyCheck Widget.

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

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