MatchKeys

(Engine-Level Function)

Description: Returns true if the specified keyboard keys have been pressed in the sequence given.
Returns: Boolean
Usage: Steady State only.
Function Groups: Keyboard
Related to: MakeBuff | KeyCount |Keys
Format: MatchKeys(Enable, Keys)
Parameters:  
Enable

Required. Any numeric expression that enables the function. Testing of keyboard input is enabled when this parameter is true (i.e. not 0). If it is 0 (false), then the function's value is false.

In addition, the Enable parameter controls the type of comparison done. If the Enable is 1, a case-sensitive match is made. If the Enable is 2, then the match is not case-sensitive.

(Any non-zero value other than 2 will cause a case-sensitive match. The use of 1 and 2 is recommended for clarity.)
Keys

Required. A text expression giving the key sequence to watch for. The case of individual letters may be significant, depending on the Enable parameter.

To generate extended keys that are not already available as constants defined in the system layer, use MakeBuff to turn the character code(s) into a text expression. For example:

    PageUp    = Concat(MakeBuff(1, 253), MakeBuff(1, 0x49));
    F2        = Concat(MakeBuff(1,253), MakeBuff(1,60));
    F3        = Concat(MakeBuff(1,253), MakeBuff(1,61));
    CtrlZKey  = MakeBuff(1, 26);
Comments:

This function should be used in a window or page module to monitor key strokes.

The Enable parameter is a status expression controlling the comparison. The comparison starts after the Enable becomes true. If the Enable becomes false, the function's value becomes false and the comparison starts at the beginning of the Keys string again after the Enable becomes true. This feature is useful for resetting the MatchKeys function after an action using the function's result has been performed.
The MatchKeys function is also reset automatically when it occurs in an action trigger that becomes true.
The function's result is automatically set to 0 (false) when the state containing the function is entered. After the function becomes true, it remains true as long as the state does not change and the Enable remains true.
Any key sequence may be used for the Keys parameters including the function keys. Note that the MatchKeys function is case sensitive (upper and lower case letters are treated as different characters) when the Enable is an odd number. Often only one key is included in the Keys string. Several keys may be used in the Keys string and function as a password. The keys typed are not displayed on the screen by this function. Several MatchKeys functions may be active at any time, each comparing the keyboard input against their own Keys parameter.

If watching for function keys, you are advised not to override the behavior of F1.

Buffer constants for ASCII codes
Name of Constant Contents Description
BS MakeBuff(1, 8) Backspace key
CR MakeBuff(1, 13) Carriage return
CRLF Concat(CR, LF) CR/LF pair
ESC MakeBuff(1, 27) Escape key
FF MakeBuff(1,12) Form feed
LF MakeBuff(1, 10) Line feed
NULL MakeBuff(1, 0) Null byte
TAB MakeBuff(1, 9) Tab key
CtrlBraceOpen Concat(MakeBuff(1, 253), MakeBuff(1, 0xBC)) Ctrl and [
CtrlBraceClose Concat(MakeBuff(1, 253), MakeBuff(1, 0x39)) Ctrl and ]
UpArrow Concat(MakeBuff(1, 253), MakeBuff(1, 0x48)) Up arrow key
DownArrow Concat(MakeBuff(1, 253), MakeBuff(1, 0x50)) Down arrow key
LeftArrow Concat(MakeBuff(1, 253), MakeBuff(1, 0x4B)) Left arrow key
RightArrow Concat(MakeBuff(1, 253), MakeBuff(1, 0x4D)) Right arrow key
AltLeftArrow Concat(MakeBuff(1, 253), MakeBuff(1, 0x9B)) Alt and left arrow
AltRightArrow Concat(MakeBuff(1, 253), MakeBuff(1, 0x9D)) Alt and right arrow
SUpArrow Concat(MakeBuff(1, 253), MakeBuff(1, 0xB8)) Shift and up arrow
SDownArrow Concat(MakeBuff(1, 253), MakeBuff(1, 0xC0)) Shift and down arrow
PageUp Concat(MakeBuff(1, 253), MakeBuff(1, 0x49)) Page up key
PageDown Concat(MakeBuff(1, 253), MakeBuff(1, 0x51)) Page down key
HomeKey Concat(MakeBuff(1, 253), MakeBuff(1, 0x47)) Home key
EndKey Concat(MakeBuff(1, 253), MakeBuff(1, 0x4F)) End key
DeleteKey Concat(MakeBuff(1, 253), MakeBuff(1, 0x53)) Delete key
SPageUp Concat(MakeBuff(1, 253), MakeBuff(1, 0xB9)) Shift and page up
SPageDown Concat(MakeBuff(1, 253), MakeBuff(1, 0xC1)) Shift and page down
SHomeKey Concat(MakeBuff(1, 253), MakeBuff(1, 0xB7)) Shift and home
SEndKey Concat(MakeBuff(1, 253), MakeBuff(1, 0xBF)) Shift and end
CtrlPageUp Concat(MakeBuff(1, 253), MakeBuff(1, 0x84)) Ctrl and page up
CtrlPageDown Concat(MakeBuff(1, 253), MakeBuff(1, 0x76)) Ctrl and page down
CtrlHome Concat(MakeBuff(1, 253), MakeBuff(1, 0x77)) Ctrl and home
CtrlEnd Concat(MakeBuff(1, 253), MakeBuff(1, 0x75)) Ctrl and end
CtrlBKey MakeBuff(1, 2) Ctrl and B
CtrlCKey MakeBuff(1, 3) Ctrl and C
CtrlDKey MakeBuff(1, 4) Ctrl and D
CtrlIKey Concat(MakeBuff(1, 253), MakeBuff(1, 0xB5)) Ctrl and I
CtrlMKey Concat(MakeBuff(1, 253), MakeBuff(1, 0xBA)) Ctrl and M
CtrlPKey MakeBuff(1, 16) Ctrl and P
CtrlSKey MakeBuff(1, 19) Ctrl and S
CtrlTKey MakeBuff(1, 20) Ctrl and T
CtrlUKey MakeBuff(1, 21) Ctrl and U
CtrlVKey Concat(MakeBuff(1, 253), MakeBuff(1, 0x06)) Ctrl and V
CtrlXKey MakeBuff(1, 24) Ctrl and X
CtrlYKey MakeBuff(1, 25) Ctrl and Y
CtrlZKey MakeBuff(1, 26) Ctrl and Z
     
Buffer constants for non-ASCII codes
AltEnter Concat(MakeBuff(1, 253), MakeBuff(1, 0x32)) Alt and Enter
AltUpArrow Concat(MakeBuff(1, 253), MakeBuff(1, 0x98)) Alt and up arrow
SLeftArrow Concat(MakeBuff(1, 253), MakeBuff(1, 0xBB)) Shift and left arrow
SRightArrow Concat(MakeBuff(1, 253), MakeBuff(1, 0xBD)) Shift and right arrow
F2 Concat(MakeBuff(1, 253), MakeBuff(1, 0x3C)) F2
F3 Concat(MakeBuff(1, 253), MakeBuff(1, 0x3D)) F3
F4 Concat(MakeBuff(1, 253), MakeBuff(1, 0x3E)) F4
F5 Concat(MakeBuff(1, 253), MakeBuff(1, 0x3F)) F5
ShiftF2 Concat(MakeBuff(1, 253), MakeBuff(1, 0x55)) Shift and F2
ShiftF3 Concat(MakeBuff(1, 253), MakeBuff(1, 0x56)) Shift and F3
ShiftF4 Concat(MakeBuff(1, 253), MakeBuff(1, 0x57)) Shift and F4
ShiftF5 Concat(MakeBuff(1, 253), MakeBuff(1, 0x58)) Shift and F5
STab Concat(MakeBuff(1, 253), MakeBuff(1, 0x09)) Shift and Tab
CtrlTab Concat(MakeBuff(1, 253), MakeBuff(1, 0x94)) Ctrl and Tab
CtrlShiftTab Concat(MakeBuff(1, 253), MakeBuff(1, 0x9C)) Ctrl, Shift and Tab
CtrlMinus Concat(MakeBuff(1, 253), MakeBuff(1, 0x2A)) Ctrl and -
CtrlPlus Concat(MakeBuff(1, 253), MakeBuff(1, 0x2D)) Ctrl and +
CtrlShiftMinus MakeBuff(1, 0x1F) Ctrl, Shift and -
CtrlShiftPlus Concat(MakeBuff(1, 253), MakeBuff(1, 0x2E)) Ctrl, Shift and +
CtrlNumAdd Concat(MakeBuff(1, 253), MakeBuff(1, 0x90)) Ctrl and Numpad +
CtrlNumSubtract Concat(MakeBuff(1, 253), MakeBuff(1, 0x8E)) Ctrl and Numpad -
CtrlNumMultiply Concat(MakeBuff(1, 253), MakeBuff(1, 0x36)) Ctrl and Numpad *
CtrlShiftNumAdd Concat(MakeBuff(1, 253), MakeBuff(1, 0x9A)) Ctrl, Shift & Numpad +
CtrlShiftNumSubtract Concat(MakeBuff(1, 253), MakeBuff(1, 0x96)) Ctrl, Shift & Numpad -
AltNumMultiply Concat(MakeBuff(1, 253), MakeBuff(1, 0x37)) Alt & Numpad*
WinContext Concat(MakeBuff(1, 253), MakeBuff(1, 0xE8)) Context Menu Key
CtrlTilde Concat(MakeBuff(1, 253), MakeBuff(1, 0x26)) Ctrl and ~
CtrlShiftBraceOpen Concat(MakeBuff(1, 253), MakeBuff(1, 0xBE)) Ctrl, Shift and [
CtrlShiftBraceClose Concat(MakeBuff(1, 253), MakeBuff(1, 0x3A)) Ctrl, Shift and ]
Ctrl0 Concat(MakeBuff(1, 253), MakeBuff(1, 0x72)) Ctrl and 0
CtrlNum0 Concat(MakeBuff(1, 253), MakeBuff(1, 0x92)) Ctrl and Numpad0
Alt0 Concat(MakeBuff(1, 253), MakeBuff(1, 0x81)) Alt and 0
AltNum0 Concat(MakeBuff(1, 253), MakeBuff(1, 0x9E)) Alt and Numpad0
CtrlShiftNKey Concat(MakeBuff(1, 253), MakeBuff(1, 0x08)) Ctrl, Shift and N
CtrlShiftVKey Concat(MakeBuff(1, 253), MakeBuff(1, 0x05)) Ctrl, Shift and V

Comparisons exceeding 256 bytes (source string) is not supported and will return FALSE. Note that this is not the number of characters but the underlying bytes. Characters can be between 1 to 4 bytes since UTF-8 is supported.

Multi-character String comparison is not supported on VIC.

Example:

If MatchKeys(2,"Y");
[
  ...
]

When the letter "Y" is typed on the keyboard, regardless of case, the action will trigger, execute its script, and reset the MatchKeys function to wait until "Y" is typed again.

Related information:

Defined Constants for Buffers

Latching and Resetting Functions