Keyboard Control Function Reference

Int := AppendKeyCodeToMacro"> AppendKeyCodeToMacro(Name,KeyCode,Trigger)

Explanation

This function is used to append a keystroke to an existing macro. 'Name' is the name used to create the macro. Keycode is the numeric keycode to be appended (use ParseKey for an easy way to get a keycode value). Trigger is used to allow function 'nesting' and is not used internally by the function at all.

Example

To append the key code for a 'Ctrl-F10' keystroke to a macro named "LUParts", a derivation formula (or procedure statement) could include:

AppendKeyCodeToMacro("LUParts",ParseKey("CtrlF10"),"")

Use It For

Adding keys to macros.

Int := AppendStringToMacro(Name,Text,Trigger)

Explanation

This function is used to append a text string to an existing macro. When the macro is played back, the string will be inserted into the macro. 'Name' is the name used to create the macro. Text is the string to append. Trigger is used to allow function 'nesting' and is not used internally by the function at all.

Example

To append the string 'SDS97*' to a macro named "LUParts", a derivation formula (or procedure statement) could include:

AppendStringToMacro("LUParts","SDS97*","")

Use It For

Adding text to macros.

Int := BuildMacro(Name,Trigger)

Explanation

This function records a keyboard macro interactively. The first key pressed after BuildMacro is called will be the macro key. Subsequent key presses will be appended to the macro until Alt-Escape is pressed at which time macro recording is terminated. Alt-Escape is NOT recorded in the macro. Keystrokes are NOT fed to the underlying program while recording occurs. When BuildMacro is invoked, information is displayed in the upper right corner of the screen to keep you apprised of its progress. The function is identified by 'Name'. If a macro already exists in memory under 'Name', it is replaced by the new macro.

Trigger is provided to allow function 'nesting' and its value is not used by the function.

Example

To record a macro called "LUParts", the following could be used:

BuildMacro("LUParts","") 

Upon execution of the function, the first key pressed would become LUPart's macro popup key. All subsequent key presses would be recorded until the user pressed Alt-Escape, at which time keyboard processing will return to normal.

Use It For

Recording new keyboard macros.

Int := ChangeMacroKey(Name,KeyCode,Trigger)

Explanation

This function is used to change an existing macro's popup key. 'Name' identifies the macro, 'Keycode' is a numeric keyboard scan code (use ParseKey to obtain a value for Keycode symbolically). Trigger is provided to allow function 'nesting' and its value is not used by the function.

Example

A function call to change a macro named "LUParts" popup key to Alt-F12 would appear as:

ChangeMacroKey("LUParts",ParseKey("AltF12"),"") 

Use It For

Re-assigning macro keys.

Int := EnableMacros(Enable,Trigger)

Explanation

This function is used to enable or disable macros. When macros are enabled and a user presses a popup key assigned to a macro loaded in memory, that macro will be executed. When macros are disabled, the keyboard functions in a standard manner.

The value of 'Enable' is used to determine whether macros will be enabled or disabled. If Enable's value is set to 0, macro functionality is disabled. If Enable's value is set to 1, macro functionality is enabled,

Trigger is provided to allow function 'nesting' and its value is not used by the function.

Example

A formula to disable macro functions:

EnableMacros(0,"")

Use It For

Controlling when macros may popup.

String := GetKeyName(Keycode, Trigger)

Explanation

This function will return a symbolic name for a given keycode. See ParseKey for information on keycodes and the possible names returned by this function:

Example

To obtain a symbolic name for a keycode value of 22272:

GetKeyName(22272,"") 

which would return a value of:

"ShiftF4"

Use It For

Clarifying keyboard monitoring activities. Documentation.

Int := KillMacro(Name,Trigger)

Explanation

This function is used to destroy a macro presently loaded into memory. 'Name' identifies the macro to destroy. After a macro is destroyed, processing of its 'popup' key returns to normal.

Trigger is provided to allow function 'nesting' and its value is not used by the function.

Example

To destroy a macro named 'LUParts':

KillMacro("LUParts","") 

Use It For

Managing macro definitions.

Int := LoadMacros(FileName,Trigger)

Explanation

This function is used to load a macro file previously saved with the SaveMacros function. Any macro definitions in memory at the time LoadMacros is executed are destroyed and replaced by the macro definitions stored in FileName. 'Filename' is a fully-qualified DOS file name referring to a file containing valid macro definitions create by SaveMacros.

Trigger is provided to allow function 'nesting' and its value is not used by the function.

Example

To load a macro file called 'C:\DATABASE\OE\POENTRY.MAC' (saved with SaveMacros):

LoadMacros("C:\DATABASE\OE\POENTRY.MAC","")

Use It For

Retrieving macro definition libraries from disk.

Int := MAC_Compress(Trigger)

Long := ParseKey(KeyName)

Explanation

This function accepts a text string that symbolically references a keystroke and returns a the BIOS keyboard scan code assigned to the string. The function takes the 'sting' out of HandTool keyboard programming by allowing you to refer to Shift-F4 as "ShiftF4" instead of 22272.

Keyname must be one of the following (Keyname in quotes. Value returned by ParseKey follows in parentheses:

Case does not matter. If Keyname is incorrectly spelled or punctuated, ParseKey will fail and return a value of 0.

Example

To retrieve the keycode for the Control-F11 key:

ParseKey("CtrlF11")

WARNING: ParseKey is very precise and is intolerant of even slight variations of spelling or punctuation (there is none). Please check your work carefully!

Use It For

Avoiding messy hexadecimal notations!

Int := RunMacro(Name,Trigger)

Explanation

This function executesthe macro identified by 'Name'. Name must identify a macro definition presently loaded into memory.

Trigger is provided to allow function 'nesting' and its value is not used by the function.

Example

To run a macro called 'PrintInvoice':

RunMacro("PrintInvoice","")

Use It For

Executing macros without pressing the macro's popup key.

Int := SaveMacros(FileName,Trigger)

Explanation

This function writes all active macro definitions to the disk file named 'FileName'. Macro libraries saved with SaveMacros may be subsequently re-loaded from the disk file by the LoadMacros function. Any active macros are not affected by the SaveMacros function and remain available for use.

Trigger is provided to allow function 'nesting' and its value is not used by the function.

Example

To save all currently active macros to a disk file named 'C:\DATABASE\OE\POENTRY.MAC':

SaveMacros("C:\DATABASE\OE\POENTRY.MAC","") 

Use It For

Saving freshly recorded macros to disk for later use.

Int := SetKeystrokeDelay(Wait,Trigger)

Explanation

This function sets the rate at which keystrokes are 'fed' back to the program when a keyboard macro is executed, either by using RunMacro or pressing the macro's popup key. The value of 'Wait' is interpreted as milliseconds.

Example

To feed keystrokes from macros at a rate of one per second:

SetKeystrokeDelay(1000,"")

Use It For

To prevent buffer overruns. To emulate a typist's actual speed for demos.

Int := StuffKBKeycode(Keycode, ClearBuffer, Trigger)

This function was previously distributed in CORECDF.EXE.

Explanation

Stuffs the keyboard buffer with the specified keycode. If clear is true, then the keyboard buffer will be cleared of all pending input beforehand (including executing macros).

CAUTION: If you stuff a re-derive-all (Ctrl-F9) code in a form, DataEase will enter an endless loop. One proper way to around this is to condition the Ctrl-F9 on the contents of the field i.e. Your field derivation formula for a field named 'DeriveAll' would be:

If(DeriveAll=Blank, StuffKBKeyCode(ParseKey("CtrlF9",""),1,""),
0)

After deriving once, the DeriveAll field would contain the code returned by StuffKBCode and would, therefore, not re-derive again.

Example

To emulate the pressing of the Ctrl-F10 function key in a derivation:

StuffKBKeycode(ParseKey("CtrlF10",""),0,"") 

Use It For

Doing automatic relationship lookups, running procedures from a form (F9,1,Enter,Name of proc,Enter). Forcing F8 after each record is entered into a subform so that totals re-derive properly, etc.

NOTE

StuffKBKeycode's functionality has been altered since HandTools 1.0x. Previously StuffKBKeycode forced the keycode into the computer's BIOS keyboard buffer. Now, StuffKBKeycode actually creates and runs a one-character keyboard macro. While our testing indicates that the new version will perform exactly as the old version did, there might be minor incompatibilities. Please notify us if you experience any such behavior.

Int := StuffKBString(Text, Trigger)

This function was previously distributed in CORECDF.EXE.

Explanation

Stuffs a string into the keyboard buffer as if it had been typed by the user. If clear is not zero, then the keyboard buffer will be cleared beforehand and any executing macros are terminated. Returns 0.

Example

To stuff the contents of the field 'PartNo', followed by a '*', followed by a Ctrl-F10 key code into the keyboard buffer:

StuffKBKeyCode(ParseKey("CtrlF10",""),0,StuffKBString("*",0,StuffKBString(PartNo,1,"")))

Note that the sequence of function execution is from the 'innermost' function to the 'outermost' function, or right-to-left.

Use It For

Doing automatic relationship lookups, running procedures from a form (F9,1,Enter,Name of proc,Enter). Forcing F8 after each record is entered into a subform so that totals re-derive properly, etc.

NOTE

StuffKBString's functionality has been altered since HandTools 1.0x. Previously StuffKBString forced a string directly into the computer's BIOS keyboard buffer. Now, StuffKBString actually creates and runs a dynamic keyboard macro. While our testing indicates that the new version will perform exactly as the old version did, there might be minor incompatibilities. Please notify us if you experience any such behavior.

Int := GetLastKeyCode(Trigger)

This function was previously distributed in CORECDF.EXE.

Explanation

MACROCDF records each key stroke as it is entered. This function returns the keyboard scan code for the most recently typed key. This is useful for determining which key was typed to exit a field. The code returned may be interpreted symbolically useing GetKeyName.

Example

To derive the symbolic name of the last key pressed on the keyboard:

ParseKey(GetLastKeycode(""),"")

Use It For

Process flow control, changing tab orders, etc.

Int := RemapKBKey(OldKey, NewKey, Trigger)

This function was previously distributed in CORECDF.EXE.

Explanation

RemapKBKey allows you to disable or re-define the interpretation of any key on the keyboard. OldKey is the extended scan code/character code combination for the key to be re-mapped.

Example

You may disable the key defined by OldKey completely by specifying a value for NewKey of 0. For example, to disable the F7 key, call RemapKBKey as follows:

RemapKBKey(ParseKey("F7",""),0,"")

You may remap the key defined by OldKey by specifying a different key code in NewKey. For example, to cause any key press of down-arrow to be returned as a tab, call RemapKBKey as follows:

RemapKBKey(ParseKey("down",""),ParseKey("Tab",""),"")

Finally, to restore a previously re-mapped key's original interpretation, specify NewKey equal to OldKey. For example, to restore the down-arrow to its original interpretation, call RemapKBKey as follows:

RemapKBKey(ParseKey("Down",""),ParseKey("Down",""),"")

Key remapping remains in effect until specifically disabled or until MACROCDF is unloaded by DataEase, whichever comes first. Note that key remapping occurs prior to evaluation of macro popup keys.

Use It For

Remapping the keyboard to a more standard operating environment. Preventing accidental or inappropriate deletion, modification, and/or entry of records by selectively disabling F2, F7 and/or F8 keys. Making use of F11 and F12 function keys.

Int := StoreKeyMapFile(Filename,Trigger)

This function was previously distributed in CORECDF.EXE.

Explanation

StoreKeyMapFile writes all presently defined mappings to disk in a file specified by filename. If no keys are presently remapped the call will fail and no file will be created.

The stored key mappings may subsequently be loaded with LoadKeyMapFile. In this fashion entire keyboard definitions may be designed and loaded on demand. Please note that keyboard mappings and keyboard macros are different entities. Saving the keyboard map does not save any macros that may be in effect at the time and vice-versa.

StoreKeyMapFile returns false (0) if there was an I/O error on Filename. It returns true (non-zero) if the operation was successful.

Example

To store the present keyboard mappings into a file named 'C:\MAPS\LOTUS.MAP':

StoreKeymapFile("C:\MAPS\LOTUS.MAP")

Use It For

Storing popular keyboard mapping files.

Int := LoadKeyMapFile(Filename,Trigger)

This function was previously distributed in CORECDF.EXE.

Explanation

LoadKeyMapFile attempts to load a keyboard definition previously stored by StoreKeyMapFile. Any current mappings will be replaced by those loaded from the file. Note that LoadKeyMapFile has no error checking mechanism to determine that FileName is actually a valid keyboard definition file.

In this fashion entire keyboard definitions may be designed and loaded on demand from within DQL or a field derivation formula.

Example

To load the keyboard definition file 'C:\MAPS\LOTUS.MAP':

LoadKeymapFile("C:\MAPS\LOTUS.MAP","")

Use It For

Selectively loading specific keyboard personalities.

Int := ClearKeyMaps(Trigger)

This function was previously distributed in CORECDF.EXE.

Explanation

ClearKeyMaps clears any remap definitions in effect from calls to either RemapKBKey or LoadKeyMapFile, thus restoring keyboard operation to its default behavior.

Int := GoBack(Trigger)

Explanation

MACROCDF's keyboard filtration section always saves the code of the last key typed. We have identified nine keys as being 'Field Exit' keys. That is, when they are type, they cause DataEase to exit a field during form entry, resulting in a re-derivation if one is warranted. Many times you may want to make the cursor return to the field following execution of the derivation logic. GoBack attempts to give you a facility for inducing such action, by defining key codes that attempt to cancel out the nine movement keys and, if one of these codes is in the key code register at the time GoBack is called, GoBack stuffs the reversal keycode into the keyboard buffer.

It should be said that GoBack's success rate is going to be very dependent upon the form's field arrangement and other factors. It is recommended that any form employing GoBack use RemapKBKey to disable as many navigation keys as practicable, restricting field to field movement to only those keys whose functionality is predictable and reversible (Tab, Shift-Tab, Enter). Also, it is important to suppress the form's automatic tab on field fill feature.

The nine keys that GoBack will reverse and the reversing codes stuffed into the buffer are:

Key Reverse Key

Tab Shift-Tab Shift-Tab Tab Up Arrow Dn Arrow Dn Arrow Up Arrow Enter Shift-Tab Pg Dn Pg Up PgUp Pg Dn Left Arrow Tab Right Arrow Shift-Tab

You might employ GoBack to error check a field after it has been input, and, if the check fails, force the cursor back to the field. Such logic would be embedded in a hidden control center field as follows:

If( ReadCRT(2,1,1,"")=" ",Blank,-- Don't derive if just entering form
  If(FirstC(Field To Examine,1)="X", blank,-- If field starts with X, everything is cool
    CRTWriteAttr(4,5,Color(15,4), "First character must be 'X'",1500,-- Display an error message
     GoBack(""))))                                   -- GoBack