Using the KEYMAP Dialog

Contents of Article


Introduction

Non-US 104 Key Keyboards

Using the Keymap Dialog

A Note about Line Command Mapping

Customizing a Single Key

Entry of key mapping definitions

Dealing with pasting errors in KEYMAP

Overriding (Passthru) Mappings

Available key mapping definition options

Assigning Multiple Functions

Location of Primary Commands in a Macro

Auto Repeat / Set Cursor Position

Controlling the Keyboard Repeat Rate

Finalizing Your Keymap Customization


Introduction


The SPFLite Key Mapping Dialog appears as follows:



The Keymap dialog contains two basic areas.  


The top half contains a map of a typical 104 key keyboard.  Although layouts may differ on your computer, especially for laptop keyboards, the customization is performed via the logical key name, not its physical location.  So regardless of where a key is on your keyboard, customization is done using its name.  Simply use the equivalent key on the provided layout.


In the upper right hand corner, you will also see three icons representing the 3 mouse buttons.   That is because these buttons are now defined in the same way as keyboard keys.  (After all, that's what they are being treated like, in this function).  The L, M and R refers to the Left, Middle and Right mouse buttons.


The definitions for each key are displayed in the same font as you choose for the edit session.  So, if you have mapped some special-character keys, they will display here exactly as you see them in an edit session or in the (CharSet) popup window.


Because these are logical key definitions, SPFLite has no idea what your physical keyboard layout really looks like.  For laptops, you may not have all these keys; there may be only one Windows key instead of two.  You also may not have a physical numeric pad, but may be able to generate those keys by holding down an auxiliary key, often labeled Fn.  For example, Fn + the regular 7 key may be the same as the keypad 7 key.  


This means it is possible you can define a key mapping for a key that doesn't exist on your keyboard.  No harm is done, but you just wouldn't be able to use it.  Consult your hardware documentation for details on your particular keyboard.  SPFLite is unable to map auxiliary keys such as Fn, or any extra keys such as multimedia keys, that are outside the realm of a standard 104 keyboard.


Non-US 104 Key Keyboards


Some SPFLite users do not use a conventional US/English keyboard but instead use a national keyboard which contains additional keys required by other languages.  Often, these keys require the use of the AltGr key (the right-hand Alt key, which stands for Alternate Graphic).  As well, the keyboard layouts differ, and there may more or fewer keys than the layout shown above.  This can make SPFLite keyboard customization a challenge.


Note:  It's important to bear in mind that SPFLite internally processes data using ANSI characters only, which are stored in the Microsoft 1252 character set.  MS 1252 supports the Western European languages: Afrikaans, Basque, Catalan, Danish, Dutch, English, Faroese, Finnish, French, Galician, German, Icelandic, Indonesian, Italian, Malay, Norwegian, Portuguese, Spanish, Swahili, and Swedish.  That's a lot, but it's not everything.  If you need to type something in a language other than those, SPFLite may not be your best choice.


These issues are assisted by:





The column headed KEYNAME is the one telling you which SPFLite key needs to be customized.  In the sample shown, the keys pressed were the A key, the Enter key, and the PageUp key.  The KEYNAME string, like PGUP, corresponds to the name displayed in KEYMAP where you see the label Current Key for a given key.


Some keyboards have extra keys that are not used by SPFLite, and the KeyboardTest tool will report these keys as Unknown key.  If this happens, you can use those keys in SPFLite for their original purpose, the same as a (Passthru) key is used, but you will be unable to remap these unknown keys.  That is because SPFLite does not know what its "keyboard scan code" means, and doesn't know what to do with it, except to "pass it through".


The very fact that you can't map them means that you can't even map them to (Passthru).  The point is that SPFLite will pass-through any key codes it doesn't recognize as if they were mapped to (Passthru).  You don't have to do anything in SPFLite to use those keys - just use them.


If you have a multi-media keyboard with keys for things like Play, Pause and volume controls, SPFLite never sees these keys, so you don't need to worry about them.


Using the Keymap Dialog


The bottom half of the KeyMap dialog becomes active once you click on an individual key icon in the top half.  In the screen display above, the V key has been selected.  Note the V key graphic in the top half has been obscured, and the key is then displayed in the bottom half, along with the current action assignments for each of the eight possible chord combinations.


The right side of the bottom half provides reminders of the format of various command types you can enter in the key mapping definition fields.


Also, there is a button labeled Show Character Map.  When clicked, a new separate dialog will be opened, with a character map that uses the ANSI collating sequence.  See Character Maps for more information.


At the bottom are two buttons Cancel and Done.  Clicking Cancel will terminate the dialog without saving any changed keyboard assignments.  Clicking the Done button will save the changes and return to your edit session.  Saved changes to the key map will take effect immediately; no restart of SPFLite is required to active them.


Within the Key Map window, you can jump from one of the eight various definitions (all the combinations of Shift, Ctrl and/or Alt) of a key to another by using the Tab and Backtab keys.  This reduces the need to frequently alternate between the mouse and keyboard when entering many definitions for the same physical key.


A Note about Line Command Mapping


The : colon notation for key-mapping of line commands that is utilized in IBM ISPF is not directly supported.  In prior versions, if you tried it, you would have created invalid syntax.  For example, if you previously mapped Alt-R to just :R, when you use it, it would not repeat a line but would simply report, Unknown command.  


Now, an attempt to define a key with a line command like :R will result in a warning popup message advising the user that the command has been automatically converted to the SPFLite-compatible equivalent format of {R}.


Customizing a Single Key


To customize a key, perform the following steps:






Entry of key mapping definitions


You can enter key mapping definitions manually, or by pasting them in.  You will see the text of each key mapping definition is displayed in the same font as your fixed-width editing font.  (If you start up SPFLite with the -KEYMAP command line option, you will temporarily see the dialog displayed with a default font.)


To assist in remembering primitive function names, a drop-down list is provided in the lower right corner of the dialog, shown as Valid keyboard Primitives.  If you open this list and select an item by clicking on it, the value will be placed in the clipboard. You can then paste that value into the text box for your desired key, using the Ctrl-V key.  This saves time and avoids typing errors.


You can also paste any text into a definition field it you obtained it from outside the KEYMAP dialog, or even outside of SPFLite.  It is your responsibility to ensure that such pasted mapping definitions are properly formatted.  After you paste data, you can still manually modify or correct it as needed.


Dealing with pasting errors in KEYMAP


If you were to inadvertently paste some very large amount of text into a key mapping field by mistake (say, if you forgot that you just placed a large amount of data into the Windows clipboard previously), you can press Ctrl-Z right away, which will 'undo' the paste operation and will erase the key definition field you were just working on.  


To limit the effect of an inappropriate paste into one of these fields, if the clipboard contains multiple lines of text, only the first line will get pasted into a key mapping field.


Overriding (Passthru) Mappings


Ordinarily, key mappings that default to (Passthru) are left alone.  But, you may have a requirement to override them.  What sort of situations might call for this?  Here are some possible examples:



Available key mapping definition options


(Passthru)

(Passthru) is a primitive keyboard function which simply says the key should “pass through” whatever Windows would normally have done when the key is pressed.  This is the standard value for most of the alphanumeric keys, and provides the most obvious key assignment.  So, for instance, you don't have to spell out that the plain X key types “X” – you just “pass it through”.


If you attempt to completely blank-out or delete a key definition for a Normal or Shift form, SPFLite will replace it with (Passthru).  For other keys, erasing a definition will cause it to become (Null).


For the mouse only, (Passthru) has no meaning and is treated the same as (Null).



(Null)

(Null) requests that no action be performed.  This is the value for unassigned key combinations.  


If you attempt to completely blank-out or delete a key definition (other than the Normal or Shift forms), SPFLite will replace it with (Null).


When you have a key mapped to a line command, there is an implied (Enter) that is automatically inserted.  In some cases, this implied (Enter) may not be what you wish.  To suppress the implied (Enter), you can put (Null) after all other commands or functions.


command

Any text entered without being enclosed in (), [], {} or <> characters is assumed to be an SPFLite primary command and its operands, and it will be entered as such on the command line.   Such commands are processed as if there was an implied (Enter) function on the command.


When text is entered on the command line, and a command key is pressed rather than the ENTER key, SPFLite concatenates the contents of the command line to the definition of the command key. The result is handled as a single, composite command by SPFLite.  


For example, when you use a Command key defined as a scroll command (UP, DOWN, LEFT, or RIGHT), the value entered on the command line becomes the operand of the scroll command.  Assume you have the PageDn key mapped to the DOWN primary command.  Entering HALF on the command line and then pressing the PageDn key results in a composite command of DOWN HALF being issued to scroll the screen down by half its height.


You may choose to override this concatenation when you set up the command key definition by preceding the command with a ! (exclamation mark character).  This causes the programmed command to replace whatever is in the command line.   e.g. If you have a key programmed for RESET, it would probably be wise to prefix it with a ! to prevent the RESET command processor being confused by possible command line 'remnants' existing when the command key is pressed.


Note: As mentioned above, a plain, unenclosed command is treated as if there is an implied (Enter) function on the command.  That works well if the only thing you want to do is a primary command.  However, you might wish to combine line commands, primary commands and other functions in a single key mapping.  To do that, you will need to explicitly specify each part.  For the part of the mapping that has a primary command, you will have to use all the steps you would take if you did it manually, and the command itself becomes a text string in brackets.  So, an implicit primary command might be CHANGE ABC DEF.  If you wrote this as an explicit command as part of a larger key mapping string, the part for the primary command would be mapped as


(Home)[CHANGE ABC DEF](Enter)


{line-cmd}

A string enclosed in { } braces is treated as a line command.  The text of the string will be entered in the line command area of the line on which the cursor is currently located.   If the cursor is not currently on a valid line, then no action is performed.  


In ISPF, a PF key might have assigned the value of :I2 to request an insertion of two lines, a notation which SPFLite does not support.  That request in SPFLite is entered as {I2}.  If you attempt to define a line command using the ISPF : colon notation, SPFLite will automatically convert it to the brace notation and will issue a warning.


Line Command Toggling:  If you have a key mapped to a line command like {CC}, and there is any existing line command other than CC in the sequence area, the CC command will be entered there, replacing the existing command.  If the sequence area already has a CC line command, and you press the key mapped to {CC}, the existing CC line command will be erased.  This line-command toggling action allows you to easily undo a line command if you placed it on a line by mistake.


You can toggle the state of excluded lines and User Lines with the TX and TU line commands, respectively.  Suggested mappings that retain the current cursor location are as follows:


Ctrl-Alt X = {TX}(Enter)(Up)

Ctrl-Alt U = {TU}(Enter)(Up)


Implied (Enter):  When you have a key mapped to a line command such as {CC}, there is an implied (Enter) that is automatically inserted afterwards.  This implied (Enter) may or may not be what you wish.  If you don't want this implied (Enter), there are some ways to to address this:


  • To suppress the implied (Enter), you can put (Null) after all other commands or functions, like {CC}(Null).
  • In IBM ISPF, a mapped line command will leave the cursor in the first position of the sequence area.  You can replicate this action with {CC}(LineNo).
  • As may be seen above in the TX/TU example, line commands which you need to have acted-upon right away cannot have the implied (Enter) suppressed; otherwise, nothing will happen.


Special Line Commands:  There are special line-command formats for labels and tags.  Note that labels and tags can be set, cleared or toggled independently of each other and can coexist on the same line.


{.label}

Enter label into sequence area

{..label}

Toggle label; enter label if no label present, else clear any label that is present

{.}

Clear any label that may be present

{..}

Clear any label that may be present; same as {.}

{:tag}

Enter tag into sequence area

{::tag}

Toggle tag; enter tag if no tag present,  else clear any tag that is present

{:}

Clear any tag that may be present

{::}

Clear any tag that may be present; same as {:}



(primitive)

Just as with (PassThru) and (Null) above, any string enclosed in ( ) parentheses is treated as a keyboard primitive function.  Keyboard primitives are those functions other than line commands or primary commands.  There are currently over 90 keyboard primitive functions available.  Only primitive names predefined by SPFLite may be specified.


To assist in remembering primitive function names, a drop-down list is provided in the lower right corner of the dialog, shown as Valid keyboard Primitives.  If you open this list and select an item by clicking on it, the value will be placed in the clipboard.   You can then paste that value into the text box for your desired key, using the Ctrl-V key.  This saves time and avoids typing errors.


A description of all primitive functions is provided in the "List of Keyboard Primitives"


(primitive/

ClipName)

For primitive functions which refer to the clipboard, the default is always the normal Windows clipboard.  If you wish to direct the function to use a Private Named Clipboard, the clipboard name should be provided following the primitive name, separated by a / character.  For example to perform a Copy operation to named clipboard Fred, you would enter (COPY/FRED) for the key value.  To perform a Paste operation from named clipboard Bill, you would enter (PASTE/BILL) for the key value.

(cursorFunction/

count)

These five specific cursor movement functions only will accept a count option.  These functions are:

  • (Left/count)
  • (Right/count)
  • (Up/count)
  • (Down/count)
  • (Column/count)


The count field causes the given function to move the cursor left, right, up or down the indicated number of columns or lines.  For Column, count indicates the absolute column number on the current data line where the cursor is to be positioned.  For these functions, the count field is similar to the repetition factor described next, except that the performance in repositioning the cursor is much faster.


If count and the preceding slash are omitted, it is the same as if the value were 1.


(n:primitive)

You can also specify a repetition factor for primitive functions.  The repetition factor is specified as a decimal number just after the opening left parenthesis of the function, and followed by a colon.


For example, the function (Right) will move the cursor one character to the right.  If you wanted to move the cursor four positions to the right, you cold enter this as (Right)(Right)(Right)(Right).  


With a repetition factor, this can be simplified to (4:Right).


Repetition factors can only be used within primitive functions in ( ) parentheses, not on un-enclosed primary commands or on the other types of enclosed keyboard items like [ ], { } or < >.


A description of all primitive functions is provided in the "List of Keyboard Primitives"


[text-string]

Any text string enclosed in [  ] brackets will be entered at the current cursor location as if manually typed from the keyboard.   This could be used, for example, to enter boilerplate text, or any other repetitive phrase.  Embedded blanks are allowed in the text string.  You could map a key to a foreign letter by putting that one letter in brackets, such as the letter [ø].


Note: Former Tritus SPF users that were able to map a string like ABC using a primary command of DATA ABC can achieve the same thing with an SPFLite key mapping definition of [ABC].


What if your data actually contains a left or right bracket?  Just double any brackets you need to use as literal values.


Example:  You want a key to generate:                  X[y] = Z

Solution:  In the key definition field, you enter:        [X[[y]] = Z]


(nn:[text-string])

This variation of the normal text string enclosed in [  ] brackets is used when you desire a repetition of the provided string.  In addition to being a simplified format, and allowing you to define long strings that would be awkward and error-prone to type manually, this method is also significantly faster in performance.   This could be used, for example, to enter a long string of equal characters.


Example:        You want a key to generate a string of 40 * characters, so rather than entering:

                     [****************************************]


               you enter this instead:

                       (40:[*])


Similarly if you enter:

                       (4:[----+----|])


               it would be the same as

                       [----+----|----+----|----+----|----+----|]


<key-label>

Text enclosed in <> angle brackets is a key label.  If present, the optional <key-label> field must be leftmost in the key definition field.  A key label provides the text that will appear, along with the key name, at the bottom of the edit screen when the display of 1 or more Keyboard Help lines is enabled.  (This is like the PFSHOW command in prior versions of SPFLite.)  See Options - Screen for activating this option. For example, if the entry for the unshifted F3 key were coded as <End>end then it would show on the bottom of the Edit screen as F3=End.  


Note that what is shown as Keyboard Help is the key label, not the key definition.  So, the label of the key that is displayed, and the definition of the key that is acted on, are completely different things.


Key labels are helpful if you (or some other user you are assisting) need to be reminded what certain keys do.  Once you can remember the definitions, the display of the key labels can be removed to save screen space.


Assigning Multiple Functions


Multiple keyboard functions can be entered for one key.  In fact, this is how keyboard macros are created, by "stringing together" a series of keyboard functions.  (This is further discussed below under "Keyboard Macros".)  When this is done, the functions are processed left to right. Suppose you wanted to put a label of .AA on the current line, then home the cursor, and issue a CHANGE command against that labeled line. Say you wanted to call this activity the “ABC” key.  (When you perform line and primary commands like this “the hard way” you may need an intermediate Enter after the part that sets the line label.)  The following key entry could accomplish this:


<ABC>{.AA}(Enter)(Home)[CHANGE ABC DEF ALL .AA](Enter)                -- Version 1


However, there is no need to be so detailed.  Since strings outside of any enclosures like (), [], {} and <> represent primary commands, you can just enter the primary-command as-is, if there's only one of them.  Also, there is an implied (Enter) that takes place when line-command entries like {.AA} are used.  That will eliminate the need for the (Home) and (Enter) functions above.  The simplified, and faster version, looks like this:


<ABC>{.AA}CHANGE ABC DEF ALL .AA                                                -- Version 2


It is important to understand that the two macro definitions are equivalent.  The reason it's important is that if you use the Keyboard Recording feature and type your keystrokes in, they will be recorded literally, much like what is seen in Version 1 above.   You may wish to simplify it to something more like Version 2, for performance reasons.


Location of Primary Commands in a Macro


When a macro contains a primary command, as the previous topic discussed, performance is improved when the command is NOT enclosed in [  ] characters.  However, if the primary command is not the last action in the macro sequence, it should be entered as Version 1 above.


For example, take a macro that is supposed to do a PASTE command after the data line where the cursor is currently on, and keep the cursor from losing its current location.  The macro should seemingly look like:


(SaveCursor){A}PASTE(RestoreCursor)


But it would actually fail, as the characters PASTE(RestoreCursor) would be entered in the line-command area, which won't work.  After getting the A line command where it's needed, we need to reposition the cursor up to the Home position.  The macro must be coded as:


(SaveCursor){A}(Home)[PASTE](Enter)(RestoreCursor)


which would execute as we desire.


Auto Repeat / Set Cursor Position


This is a dual purpose field, so we will treat each separately.




Controlling the Keyboard Repeat Rate


SPFLite respects the keyboard timing options that are configured in Windows.  If you select the Windows Control Panel and then Keyboard Properties, you can set the keyboard Repeat Rate and Repeat Delay.


If you find that your keys are “jumping the gun” and repeating too soon when you hold them down, increasing the Repeat Delay may help.  However, for most users, you will get the greatest productivity by making the keyboard operate as fast as possible.


Finalizing Your Keymap Customization


Once you are finished with your mapping activities (and you may customize as many keys at once as you like), click the Done button at the bottom.  You don't have to “save” each key one at a time; Done will save every key you have defined or modified.


Created with the Personal Edition of HelpNDoc: Easily create EPub books