Contents of Article


Creating a macro using the Record function

Keyboard recording and Power Typing

Saving/Editing key content as .DO Files

Case Study: Implementing bookmarks

Case Study: Making editing easier on laptops


Introduction


SPFLite keyboard support allows you to create keyboard macros. 


Note that Keyboard Macros and Command Macros are completely different facilities. Refer to Command Macro Support for more information. 


A keyboard macro is a predefined series of keystrokes that are 'played back' when a specific key is pressed. You can create this series of keyboard entries manually, as described in Customizing a Single Key, by typing each primitive function name, text, line command etc. from left to right in the appropriate text box.


For macros with only a few entries, this is certainly feasible. For longer macros, the best approach may be to use the keyboard recording facility. To do this, you must first know what the macro recording key is mapped to, or define it if necessary.


Note that the keyboard recording facility is not ‘magic'. You will see that the end result of recording a macro is a text string in a key mapping definition entry, one that you could have typed yourself ‘the hard way'. The benefit of keyboard recording is that you can define a macro by concentrating on the actual keystrokes you use, rather than the syntax of the various entries described above.


If you have not redefined it, the default for the keyboard (Record) function is the Scroll Lock key. You are free to assign the (Record) function to any key you wish, as described above. For laptop keyboards, you may need to hold the Fn key to access the Scroll Lock key. 


It may be best to not initially change the definition of the (Record) function, so as not to confuse yourself while reading this documentation.


Creating a macro using the Record function


To record a keyboard macro, follow the following steps:


    • Decide what key or key combination you will be assigning the macro to.
    • Establish a normal edit session, and position the data and current cursor location exactly as you expect it to be when the macro is eventually used. If the macro is going to initially move the cursor to a common position (like Home), then the current cursor position may be unimportant.
    • Press the key to which (Record) is assigned. By default, this is set up as the Scroll Lock key.
    • You should see a red box in the status line saying  KB Recording  to indicate that Keyboard Recording is taking place.
    • At this point, carefully perform the keyboard activity that is to become the macro. This can consist of any combination of text entry, cursor movement, line command and/or primary command you desire. (If the sequence is complicated, you may wish to perform a “dry run” first to make sure you have it “just right” and write down the exact steps you will need.)
    • When all keyboard activity that is to be part of the macro is complete, press the key to which (Record) is assigned again. That will finish the Keyboard Recording, and the  KB Recording  status indication will disappear.
    • The required text string which makes up the macro will be placed in the Clipboard,
    • Enter a KEYMAP command to bring up the Keymap dialog.
    • Click the key you chose in the first step above.
    • Click the text box next to the particular key you wish to use, with any combination of Shift, Ctrl, and/or Alt.
    • Erase the current contents of the text box.
    • Right click in the box and Paste in the macro from the Clipboard. 
    • Click the Done button.


Your macro is now ready to use. 


You should test your macro after defining it, to make sure it does what you intended. Sometimes macros recorded as keystrokes this way are a little tricky to enter correctly on the first try, especially if they are long and complicated. It might take a few attempts to get every keystroke just right. If you find that a correction to a recorded macro is necessary, you can rerecord it by going through all those steps again. However, if it's just a minor flaw, you can simply edit the text definition of the macro that you pasted in. That may be much easier than re-recording it.


Be aware that with Keyboard Recording, everything you type will be recorded. That includes Backspace if you type something wrong and correct it. What this really means is, unless you plan on editing your keyboard definition later, if you make a mistake you will need to start over.


Keyboard recording and Power Typing


Keyboard Recording is allowed during Power Typing. However, since the status indicator is already showing .PowerType., the usual  message of .KB Recording. will not appear. However, keyboard recording proceeds as usual. When you press the key mapped to (Record), a second time, recording stops. At this point complete any other PT activities and press Enter to leave PT Mode. Now you can enter KEYMAP to save the recording to your chosen key.


Saving/Editing key contents as .DO files


If you create more complex keyboard macros, and need to edit them, it is sometimes awkward to do so within the limited input box available with the KEYMAP dialog. An alternative is to store the macro in a separate file in the MACROS folder. These saved files are simple text files stored with a .DO file extension.


To invoke a saved .DO file, simply enter DO name. e.g. to invoke ABCD.DO, just enter DO ABCD  in the KEYMAP entry.



DO file description

The contents of the .DO file are identical to the entry you would make in a KEYMAP entry field for a particular field. Except you may "spread out" the entries for multiple command over multiple lines. The DO process will process the lines in order.



Comments - You may insert complete line comments by starting the line with a Semi-Colon (;) These lines are totally ignored. You may also include completely blank lines for spacing and appearance.


You can also include comments on the actual data lines. This is done by leaving at least 1 blank after the real operands and starting the comment with a Semi-Colon (;)


You may include any of the KEYMAP directives in the .DO file. Keyboard Primitives, Line Commands and Primary Commands.



Example:

Suppose you have a key which inserts a boilerplate log entry and it was previously defined as:


(Home)(EraseEOL)[Up Max](Enter)(FirstLineCmd)[n5](Enter)[---/G/ ](ISODate)[ ](Time)(NewLine)(tab)


Editing could be difficult as you try and remember just what all those primitives really do. Instead this could be saved along with comments in a file named LogEnt.DO in your MACRO folder. The example shows  separate comment lines, blank lines and trailing comment types. 


; Create an empty Log entry at the top of the file

;

up max              ; Go home

(FirstLineCmd)      ; Go to top line cmd area 

[n5](Enter) 

; Enter some boilerplate with Date/Time 

[---/G/ ](ISODate)[ ](Time)    

(NewLine)

(tab)               ; Position cursor 


Now invoke this LogEnt.DO file by entering DO LogEnt in the key's text box in KEYMAP



Here is a second example


The comments here explain what it is doing. The macro would be invoked by a simple DO SUBIT command


;  Sample DO Macro - Copy the edit data to a new temporary tab

;                  - Repeat the top line 5 times

;                  - Replace all 11111 with 12345

;                  - Replace all SSSSS with Subject:

;                  - SUBMIT the resulting file

;                  - Return to orig tab, leave new tab open


cut .zf .zl                  ; Cut all lines

clip

; Now in the Clip tab, change the data

; Overtype the 1st line

UP max

(FirstLineCmd)(NewLine){R5}(Enter)

change all word "11111" "12345"

change all word "SSSSS" "Subject:"

submit

; Go back to original tab

swap prev



Case Study: Implementing bookmarks


A number of Windows text editors have a bookmark capability, in which you can set several “marks” in various places in your file, and then go back and successively find them. Here is an SPFLite implementation of such a capability, using tags as the representation of bookmarks. (Not SPFLite bookmarks, a term used interchangeably with labels, but a more generalized kind of bookmark that can exist in multiple places.)


First, we arbitrarily choose a tag name to represent a bookmark; tag :M is selected. See Working with Line Tags for more information on using tags.


Next, document the keys and the functions they will perform, which will be based on F2. (In IBM ISPF, F2 is commonly assigned to the 3270 SPLIT-screen command, a function that is not implemented in SPFLite. So, F2 may be a good choice as an available key to use.)  


We also want to keep the current cursor position when toggling bookmarks, so the toggle operation will be 'wrapped' in functions to save and restore the cursor. This example shows the use of SaveCursor and RestoreCursor functions.


    • F2 = Go to next bookmark
    • Shift F2 = Go to previous bookmark
    • Ctrl F2 = Toggle bookmark on current line
    • Alt F2 = Clear all bookmarks. In this implementation, you will see No lines (re)tagged if no bookmarks exist.


Finally, set the mapping of key F2 accordingly, and allow the keys to auto-repeat:


    • F2 = LOC :M NEXT
    • Shift F2 = LOC :M PREV
    • Ctrl F2 = (SaveCursor){::M}(RestoreCursor)
    • Alt F2 = TAG :M OFF


User Lines provide an alternative to tags for implementing bookmarks. Here is a possible implementation:


    • F2 = LOC U NEXT
    • Shift F2 = LOC U PREV
    • Ctrl F2 = (SaveCursor){TU}(RestoreCursor)
    • Alt F2 = REVERT ALL


Case Study: Making editing easier on laptops


Many laptops have keys like Insert and Delete in unconventional and hard-to-reach places on the keyboard, and they can be tiring to use, whereas the arrow keys are usually easy to reach. SPFLite key mapping can be used to provide an alternative for these hard-to-use keys.


First, document the features we wish to make available. The functions Insert, Delete and Backspace are to be made available using the Ctrl-arrow keys. 


Since Delete has the effect of “pulling” a line over to the left by one column, we also want to provide a “push” function by allowing a single blank to be inserted. It will be necessary to force the insert mode on, regardless of what it was before. So, an ordinary toggle-insert-mode command won't work for this. We also want to retain the cursor position after inserting a blank, to mirror how deletion of one character works. To do that, we need to generate a Left-Arrow cursor movement afterwards.


Besides, if we wanted to insert characters and have the cursor ‘travel' we could always just use an ordinary Insert key and then hold down the spacebar.


We also want the insert mode restored to what it used to be, and not just always turn it off, so this example shows the use of RestoreInsert instead of ResetInsert.


The functions to be provided are:


    • Ctrl-Left = destructive backspace one character
    • Ctrl-Right = toggle insert mode
    • Ctrl-Up = insert one blank character and retain cursor position
    • Ctrl-Down = delete one character and retain cursor position 


Finally, set the mapping of these keys, and allow the keys to auto-repeat (which is useful, since the arrow keys naturally auto-repeat):


    • Ctrl-Left = (Backspace)
    • Ctrl-Right = (Insert)
    • Ctrl-Up = (SetInsert)[ ](Left)(RestoreInsert)
    • Ctrl-Down = (Delete)


Created with the Personal Edition of HelpNDoc: Transform Your Word Document into a Professional eBook with HelpNDoc