Keyman

A small but powerful key manager for the HP49G/HP49G+

Keyman handles mode-sensitive key assignments. It can be stored in any port and is attached as usual. Besides shift-hold, Keyman supports two additional key functionalities, the double-click like on a PC-mouse, and the long-pressed key. With these tools, key assignments can be made without disturbing the standard function of keys. Assigning dispensable shifthold keys or keys dispensable either in edit or default mode should be prefered. Using shifthold and longhold possibilities there may be over 100 key assignments in USR mode, none of these in conflict with the standard function of a key, as exemplified by a sample of optional key assignments in More. Clearly, this has to be payed with slightly more care in operating the keys. We recommend to assign related utilities to the same key, in clusters so to speak, similar as in Examples 3 and 4 below.

Important: Load Keyman on the HP49 (only ROM version 19-6 or higher) and KeymanPlus (internally Keyman+) on the HP49G+ A global variable lht (long hold time) may but need not exist anymore. If not present, longhold operates with the default value 100 on Keyman and 1200 on Keyman+ (~ 0.4_s). If this doesn't satisfy you create lht with a value close to the mentioned. A lower value decreases, a higher value increased the longhold time, and in Keyman+ also the waiting time for a double-click.

What is NEW?

Version 5.2004. Bug fixed in K&SA of Keyman+. Also Keyman updated to 5.2004.

Version 4.2004 only Keyman+. Double-click improved. Also shifted ALPHA and ON handled by A?D and RclK.

Version 3.2004 only Keyman+. Optional assignment on simplified.

Version 2.2004 only Keyman+. Makes lht dispensable for a longhold option (uses default value 1200 if lht isn't found). The key assignment o 0..3 in More is more comfortable now, see Appendix.

Version 1.2004 only Keyman+. The optional key assignments in More, o 0..3, includes also Port3 (SD-card). Each of the numeric keys 0, 1, 2, 3 sets a corresponding port browser if the key is longhold.

Version 9.2003. Proposed key assignment on rightshift-hold F1 - F6 improved.

Version 8.2003. The longhold time may now be set by optionally creating the global variable lht, see under IfL below. KeymanPlus added , for the HP49G+.

Version 7.2003. Reorganization of the More browser including now also a listing of all assigned keys under the option Assigned. OVER command added to the proposed assignments in More. Longhold time should now work also on a good emulator. This document is a revised html version based on Keyman.txt. Putting the cursor to a picture yields additional information.

Version 6.2003. For safety reason, the keymap browser from More searches for keymaps in ports only.

Version 4.2003. Assignments on the keys 0, 1 and 2 added in More, setting the corresponding port immediately.

Version 3.2003. ASMTs renamed to More. It now contains besides key assignments some additional tools including the key recorder. These are only directly executed, hence are collected in a choose box. This grants backward compatibilty.

Version 1.2003. LEFTarrow assignment is repeating now. Holding down LEFTarrow, you drive UPDIR towards HOME but can stop at any "station". Wherever one stops, one returns to the menu page where the subdirectory is located.

Important: people applying the double-click from Keyman versions below 7.2001 must rename in the assignments ROMPTR 4B0 7 to ROMPTR 4B0 C (new location of the double-click detector). Easily be done with OT49.

Abbreviations: LS = leftshift, RS = rightshift, LS_ = LS_hold, RS_ = RS_hold, i.e., the shift is hold while pressing another key. o = Longhold, = LeftArrow. Similar symbols denote the other arrow keys. Here the description of the 8 commands of Keyman in detail.

IfD Needs two arguments, arbitrary objects O2 and O1 in level 2 and 1, resp. Puts a program on the stack which, if assigned to a key, evaluates O2 if the key is double-clicked and otherwise O1, see Example 1. The output of IfD must be processed with TO? whenever directly assigned, see TO? Execution is a bit delayed since double-click detection needs about 0.3_s. In version 4.2004 double-click tolerance is adjustable. It decreases with a smaller value in lht.
New since version 6.2001. Instead of choosing a standard assignment for O2 or O1, one may also take its keycode, i.e., a real of the form rc.p (r=row, c=column, p=plane). rc.p will automatically be replaced by the corresponding standard assignment. A real not identified as a keycode (e.g. the real 1), will just beep, see Example 5. The objects O1 and O2 can also be records generated by RecordKeys from More. All what is said here holds for other If-options as well.

IfL Needs two arguments, arbitrary objects O2 and O1 in levels 2 and 1. Creates a program which, if assigned to a key, executes O2 if the key is pressed a bit longer as usual, otherwise O1. You'll quickly get a feeling on what "longer pressed" means. Best exercise with the command A?D or some examples from the Appendix. The default longhold time is about 0.4_s on the HP49+. Clearly, IfL or IfD may also be used for getting information on a key assignment for those who do not remember it.
New since version 8.2003. If the default longhold time doesn't please you create a global variable named lht in HOME with a zint or real in it. 0 corresponds to the smallest resonable longhold time (for slow emulators). The default time without any lht on the path corresponds to 50 for the 49 and 1200 for the 49+. The scaling is free and allows optimal fine tuning.

IfE?P comprises IfE ("IfEdit") and IfP ("IfPRG"). IfE?P has two arguments, arbitrary objects O2 and O1 in level 2 and 1. Normally pressed, IfE?P puts a program onto the stack which, if assigned to a key, evaluates O2 if the key is hit in edit mode (i.e., a command line or edit line exist) and O1 else. In other words, the assignment runs the program « If in edit mode then O2 else O1 ». UsrRPL-delimiters for describing the assignment are here misused to make things more clear; the program itself cannot be written in UsrRPL. This task-splitting is indispensable in assigning the arrow keys which clearly must preserve their cursor-moving function in edit mode. The same holds for the RS APPS key which is active only in edit mode. In these and other cases, O2 is usually the standard assignment of the assigned key (recalled with K&SA) or simply its keycode. Pressing IfE?P a bit longer creates a program which, if assigned to a key, evaluates O2 if the key is pressed in PRG-mode and O1 else. What has been chosen, IfE or IfP, is displayed. In the IfP-case, O2 should not be user-made (the key would beep). Strings, commands and some other objects are printed in the edit line. Attention: if an assignment is made with the IfP option but hit in edit mode without PRG-indicator, then O1, not O2 is executed, maybe outside the command line. Thus, be careful in chosing IfE or IfP. The output of IfE?P must perhaps be processed with TO?.

TO? Makes a so-called TakeOver program from any object which usually looks like the original. Assigned to a key it is evaluated also in edit mode. Without the TakeOver, the key would simply beep. The TakeOver command is put on top of an object but is visible only if flag -85 is set. In a composition of the above If-options, only the last one (the program to be assigned, not its inner parts) need be processed with TO? to ensure activity in all modes.
Pressing TO? a bit longer adds an "α-off" command (for leaving the Alpha mode) to the program, not a TakeOver. Useful for assigning a key in alpha planes which aims at setting a menu, say, but not at staying the Alpha mode.

A?D Assigns or deletes a key including shifthold keys. If pressed normally, waits for a key-press to assign the object in level 1 to this key; if longer pressed it waits for a key-press to delete its assignment. A?D indicates whether it will assign or delete. If A?D is unintensionally pressed too short, answer with CANCEL. Recall it and then delete the CANCEL key assignment. Attention: A?D does not assign shiftholds of the keys Alpha and ON. These shiftholds are ignored by the operating system so that assigning them would be wasted RAM which is is not easily regained.

RclK Invokes the user assignment of the key asked for (if there is any). This may also be a shifthold key. Note that both RclK and A?D are no RPN-commands. Here it is more convenient to first choosing the operator and then the argument.

K&SA Recalls the keycode rc.p of a key together with its standard assignment which may be an argument for the various If-options as explained above. This powerful option runs for shift-hold keys as well. It displays type and type name of the key-object, in addition. As regards unshifted menu keys, a global name is simply quoted whereas a libname (aka rompointer) is quoted together with its content. To the displayed type name an asterix is appended to remind that the type name refers to the content. The screen displays the result of K&SA applied to More, telling us that a code object has type 25. The stack shows the content of the command (a code) , the libname More, and its key 12.1. Most keys run libnames. E.g., if SIN is pressed after K&SA, we see SIN on two levels. Level 2 is the libname but on level 1 it is the function SIN. These names are the same in this case but may be distinct in others. It makes a difference whether a libname or its content is taken as the argument O2 for IfE?P. In PRG mode, the libname is printed in the edit line while the function is immediately executed, maybe outside the editor. K&SA must be assigned to a key to ensure access to all keys, see Example 2 below.

More Opens a browser with 5 additional items (left-hand screen) of which the last two are browsers itself. The last item sets a box of useful key assignments described in the APPENDIX. These assignments exemplify the power of the If-options. Just try some assignments and purge the ones you are not pleased with, easily done with A?D longhold.
Here the explanations of the first four items in the left-hand browser. For the last see the Appendix.

Assigned Displays the list of all user-assigned keys. Thus, the user may always keep track on the current global assignment situation.

PackUKeys When deleting some assigned keys, the (hidden) UserKeys contains a lot of redundancies. This also applies if you assigned the empty list to a key which the system ignores but it looses 32 bytes. The wasted memory is regained (even more than 500 bytes) by running PackUKeys from time to time.

RecordKeys A powerful key-recorder for collecting a sequence of key-presses for later execution. A record can only be ended with CANCEL and can contain at most 15 key presses. There is a key counter in the headline controlling the number of pressed keys.
Example: Press RecordKeys. This displays REC 0 in the headline. Then press the key sequence
[MODE][F1][CANCEL]. This leaves a program on the stack setting the Flag Browser in just one keystroke. A record can directly be replayed but can also be used in a If-option as in Example 8.
Important: As is seen from this example, RecordKeys also activates keys valid only in closed environements (in the example key F1 inside the MODE browser). Such a luxus cannot be achieved with the KEYEVAL command.

Keymap Box For users who like alternative key assignments. One may have a keymap for physics (Phys.K say), another one for engineering, etc. RCLKEYS and STOKEYS are too slow for this. Keymap Box switches keymaps instantaneously. At the begin, it has only the item GetUKeys (recalls current UserKeys list). Running it after having made some assignments puts a list on the stack. Store it in a port, in 2:U.K, say. If running Keymap Box again, it contains "Set 2:U.K" .The suffix .K is basic here since Keymap box will search only for port names with suffix .K. Such a file should only contain a list obtained with GetUKeys or a self-decomressing code evaluating to such a list. The latter is easily made with the BZ-tools from OT49. A UserKeys list is huge but homogeneous. Hence, compression rate is mostly higher than 90%. Attention: A keymap overwrites the current key assignments completely.

Examples of application

1. IfD. To invoke the builtin library 256 which offers some useful commands, several keys have to be pressed. To get it with a single key you may choose the double-clicked APPS-key 21.1. Put « 256 MENU » onto level 2 and the standard assignment of APPS (obtained with K&SA) on level 1. Then apply IfD, process the result with TO and assign it to the APPS key with A?D. Now, double-clicking APPS sets the lib 256 menu - also in the edit mode - while an ordinary key press sets the APPS box as before. Instead of taking the standard assignment of 21.1, you may also take the real 21.1 itself. If you prefer long-press, use IfL instead of IfD.

2. IfL. It is very useful to get the STACK-menu (a subdirectory of the TOOL- menu) in all modes with a single key-stroke. Get the assignment of the STACK-submenu in the TOOL-menu, and the assignment of the TOOL-key, both with K&SA. Next, press IfL, process with TO? and assign this to TOOL (key 23) using A?D. From now on, if TOOL is pressed a bit longer, the STACK-menu will appear. This works in edit mode as well and makes programming much faster. This example is included also in the Appendix.

3. IfE?P. It is convenient to have more often used Keyman commands on key K and its shiftings. RS K (CUT) is one of several keys needed only in edit mode. Hence, it may be used for directly launching the More browser, needed only in default mode. Put the standard assignment of 32.3 on level 2 and the program « More » (or simply the command More) on Level 1. Hit IfE?P normally, process with TO? and assign the output to 32.3. Then in default mode this key runs More while in edit mode the key cuts text as before. Note that the dispensable LS_K and RS_K are still to our disposal. We use them by assigning « RclK » or simply RclK to LS_K with A?D. Thus, if the shift is hold then RclK is run instead of RCL. Similarly, we may assign K&SA directly to RS_K.

4. We still have many possibilities to set the entire Keyman menu somehow with key K. For instance, it could be done with longhold K. Put «1200 MENU » and 32.1 on level 2 and 1, press IfL, process the output with TO and assign this to Key K (STO). Then longhold STO invokes the Keyman menu in each mode. An alternative is to assign Keyman to ALPHA-shift longhold. To realize this, apply TO? longhold to «1200 MENU » which adds a "Turn α-off" command to it. Put the result on level 2, the standard assignment of alpha K (character K) on level 1 and run IfL. Process the output with TO? and assign this to ALPHA K. Now, pressing K in alpha mode, prints K in the editor as before, also repeatedly. But releasing the ALPHA key (still in alpha mode) and pressing K longer, sets Keyman's menu. The assignment reads « If key K in alpha mode is hit shortly write K in the edit line, but if K is longhold (after releasing ALPHA) set Keyman's menu and leave the alpha mode ». It is proposed also by More.

5. Suppose you often need some command sequence or text in edit mode only. It is obviously more easy to have it printed by a key instead of rewriting it over and over again. Put the text on Level 2, the real 1 on Level 1, apply IfE?P and TO? and assign this to your key. The key will then beep outside the edit mode (since 1 is no keycode!) but print the text in the command line just at the cursor position if the editor is active. Several standard assignments on the 49 are made in just this way, COPY, CUT etc. If a text is directly assigned to a key then the key immediately opens the editor which is not always wanted.

6. An easy but handy example of a composition of the above If-options is the assignment « If in edit mode then move cursor left else go UPDIR or go directly HOME if the key if longer pressed » to LeftArrow (34.1). PICTURE, normally invoked with 34.1, can as conveniently be entered also with 34.2 (default on the HP48). This example is easily made with IfL and IfE, but the Appendix contains a similar and still more comfortable assignment.

7. Younger versions of OT49 contains the togglers ~ANG and ~COOR for angle and coordinate systems, resp. Since both are closely related, we want to have them on the same key, LS_ say (104.21). Put ~COOR on level 2 and ~ANG on level 1, run IfL, then TO? and assign this to LS_. A really useful and amazing assignment. If LS is hold and SPC is shortly hit, DEG toggles with RAD, but while still holding LS and pressing SPC a bit longer, you see toggling the 3 coordinate system in the Header.

8. Record the key-sequence [MODE][F19] as in the example under RecordKeys. Apply IfL on this record on level 2 and 22.1 on level 1 and assign the result after processing it with TO? to key 22.1. Then the MODE key invokes the MODE dialog screen if normally hit, but runs immediately into the Flag browser if longpressed, hence saves an additional key press. This amazing assignment is contained in More.

9. Record the key sequence [][RS][F6] which runs the INFO option from the interactive stack menu. Put this on level 2, print 25.1 on level 1 and run IfL. Leave this on level 1, put 25.1 on level 2 and execute IfE. The result (after processing it with TO?) reads as « In edit mode move the cursor up; else visit the stack, and if longhold, display some INFO on the level 1 object ». A variant: record the key sequence [][RS][] and procede as before. Then longhold drives immediately to the highest level in the interactive stack. Very useful for those who are frequently working in the interactive stack.

Remark 1. Results of the If-options can also be used in library commands or temporary menus to make a longhold decision as you see from Keyman itself. One may compose the If-options and gets an inexhaustible variety of possible assignments. This all is independent on whether you can or cannot read the programs created with the If-options. The only what has to be kept in mind is how they were combined. All assignments are readable with the (huge) library extable by setting flag -85, provided you learn some SysRPL.

Remark 2. Mode-sensitive assignments containing standard assignments may not properly work after a ROM upgrade because pointers occurring in a standard assignment may move with the ROM. Rewriting the assignment using the keycode instead of the standard assignment makes key assignments safe against future upgrades.

Remark 3. Assigning a key with the empty list has no effect. Only programs (no matter whether program delimiters are visible) need a TakeOver on top to be executed in Edit mode. This may happen outside the editor on the stack.

Remark 4. If Keyman is purged from the ports, many keys assigned with Keyman will not work anymore in USR mode. Leave this mode or purge the assignments. If you only change a version, make sure the old version is in Port1 or Port2. Load the new version first in Port0. Then purge the old version and move the new version from Port0 to another Port. This procedure does not affect keys assigned with Keyman and makes storage of Keyman safe against a crash.

Remark 5. Items in the sub-boxes of More can be executed in programs via Recordkeys. We assume that More is assigned to RS K as proposed in the Appendix. Then the following key record will run GetUKeys (first item of More/KeymapBox), which immediately recalls the current UserKeys list:
            RS             (The RS key)
            K                (Key K = STO)
            (three times DownArrow, i.e., go down in More till the Keyman box)
            F6              (OK, this is set the Keymap box)
            F6              (OK, run first item in the Keymap Box which is GetUKeys)
            CANCEL (end the recording)
Just press Recordkeys and record this key sequence. Store it in GUK, say. Then GUK will recall the currently used keymap to the stack while you may watch the automated passing through the browsers similar as in the DEMO library 1234.

Remark 6 for experts. Instead of using the lengthy standard assignments of the arrow keys in edit mode, one may use the corresponding cursor moving commands, easily found hacking the standard assignments of the arrow keys. Some standard assignments are unnamed rompointers, e.g. that of 21.3. One saves bytes if using rompointers instead of their lengthy content. A rompointer assignment need no TakeOver on top if the rompointer itself has it on top. For instance, the optional assignments o 0..3 in Keyman+/More is the same for all 4 keys: ROMPTR 4B0 F. It first identifies the key and with its TakeOver on top it runs also in edit mode without disturbing the command line.

CREDITS
Thanks to Jonathan Busby for his code invoking the hexa key code, to Carsten Dominik for his fruitful proposal of creating the longpress option, to Simone A. Rapisarda whose basic ideas from SmartKeys inspired Keyman, to Denis Martinez for his key recorder, used in ROMPTR 4B0 D, to Joseph K. Horn and Rick Neufeld for beta-testing Keyman+, and to Heiko Arneman and Otto Praxl for help in creating this html-document.

Wolfgang Rautenberg - raut@math.fu-berlin.de - www.math.fu-berlin.de/~raut

APPENDIX

The sub-browser More/KeyAssignments. A key is denoted by the letter on it if any. More assignments are found in Topkeys or Topkeys+ which includes a special tool for remembeing user key assignments.

RS_A..F quote assign the dispensable RS-hold menu keys in a nice way for quoting the menu name. That may be a global variable, a rompointer (libname) like %CH or ABS, or a port name. Thus, forget about quoting with the quoter or with RS alpha for port names. Names from temporary or CST-menus are quoted only if these names are globals. Otherwise the program executed by the menu name is recalled.which is an excellent control possibility for self-made menus. A RS-hold menu key may also be pressed on submenu-names like VECTR in MTH. Then the stack contains what the menu key would do if pressed. But this is readable only if library extable is in port2.

o H FlagBox assign the MODE key 22.2. If normally pressed works as before, but if longer pressed invokes the Flag browser without additional key presses. Note that the longhold time can be adjusted.

o I StkMenu assign key I (TOOL) to invoke the STACK submenu of TOOL if long pressed. This applies in edit mode as well. Thus, this important menu is always at the disposal with a single keystroke, in particular while programming.

   n PICK
o    StkTop assign with 4 different operations. The key works in edit and default mode as before if normally clicked. If longer hold in default mode you go up to the stack top If first a numeric key n is pressed which opens the command line then does n PICK and closes the command line.

o K Keyman
RS K More assign K. If normally hit, the key runs its standard function. Pressing K a bit longer set Keyman's menu.
RS K will set the More browser in default mode in which RS K normally only beeps..

LS_K RclK RS_K K&SA assign the Keyman commands RclK and K&SA to the shiftholds of K.

UP←
LS PICT assign (34.1) to go UPDIR if hit normally but drive furrther direction HOME if pressed longer. You may stop at any station. Hence, UPDIR and HOME do not need different keys. The key choice nicely agrees with the path display in the Header. Important: PICTURE is now invoked with LS (standard on the HP48). Clearly, in the PICTURE environement, LS continues toggling with the graphic scroll mode.

LS_     PAINT assign LS_ with a new plot type PAINT. This one respects the size of PICT and does not create a new PPAR file. What is important and cannot be made in a PPAR dialog is that pressing (X,Y) in the PAINT environement displays the cursor's true pixel coordinates, i.e., X:0 and Y:0 is the left upper corner. These are important for painting by hand or placing grobs at the right positions, in programming games, etc. Special feature: PAINT runs also in edit mode. This allows to have look on data from PICTURE. CANCEL nicely returns to the command line.

o OVER assign the OVER command to longhold which normally does SWAP. Thus, you have two highly important stack operations just on one key.

o 0..3 Ports
(Keyman+)
o 0..2 Ports
(Keyman) Pressing in default mode key 0, 1, 2 or 3 a bit longer, sets a corresponding port browser (on the slow 49 the port menu is maintained) together with a 1-page menu containing the basic options for port managment. All port browsers are alike. In particular, longhold 3 is a card browser. Also some hardkeys are active in the browser: NXT toggles browser view, EVAL evals. Other hardkeys, in particular the arrow keys, 0,1,2,3 for visiting the other ports, +/- and ALPHA work as in the 49+ standard filer. Note: In an edit session the keys 0,1,2,3 set the corresponding port menu which is more useful during programming than a port browser.

RS_A..F quote	assign the dispensable RS-hold menu keys in a nice way for quoting the menu name. That may be a global variable, a rompointer (libname) like %CH or ABS, or a port name. Thus, forget about quoting with the quoter or with RS alpha for port names. Names from temporary or CST-menus are quoted only if these names are globals. Otherwise the program executed by the menu name is recalled.which is an excellent control possibility for self-made menus. A RS-hold menu key may also be pressed on submenu-names like VECTR in MTH. Then the stack contains what the menu key would do if pressed. But this is readable only if library extable is in port2.
o H FlagBox	assign the MODE key 22.2. If normally pressed works as before, but if longer pressed invokes the Flag browser without additional key presses. Note that the longhold time can be adjusted.
o I StkMenu	assign key I (TOOL) to invoke the STACK submenu of TOOL if long pressed. This applies in edit mode as well. Thus, this important menu is always at the disposal with a single keystroke, in particular while programming.
n PICK o StkTop	assign with 4 different operations. The key works in edit and default mode as before if normally clicked. If longer hold in default mode you go up to the stack top If first a numeric key n is pressed which opens the command line then does n PICK and closes the command line.
o K Keyman RS K More	assign K. If normally hit, the key runs its standard function. Pressing K a bit longer set Keyman's menu. RS K will set the More browser in default mode in which RS K normally only beeps..
LS_K RclK RS_K K&SA	assign the Keyman commands RclK and K&SA to the shiftholds of K.
UP← LS PICT	assign (34.1) to go UPDIR if hit normally but drive furrther direction HOME if pressed longer. You may stop at any station. Hence, UPDIR and HOME do not need different keys. The key choice nicely agrees with the path display in the Header. Important: PICTURE is now invoked with LS (standard on the HP48). Clearly, in the PICTURE environement, LS continues toggling with the graphic scroll mode.
LS_ PAINT	assign LS_ with a new plot type PAINT. This one respects the size of PICT and does not create a new PPAR file. What is important and cannot be made in a PPAR dialog is that pressing (X,Y) in the PAINT environement displays the cursor's true pixel coordinates, i.e., X:0 and Y:0 is the left upper corner. These are important for painting by hand or placing grobs at the right positions, in programming games, etc. Special feature: PAINT runs also in edit mode. This allows to have look on data from PICTURE. CANCEL nicely returns to the command line.
o OVER	assign the OVER command to longhold which normally does SWAP. Thus, you have two highly important stack operations just on one key.
o 0..3 Ports (Keyman+) o 0..2 Ports (Keyman)	Pressing in default mode key 0, 1, 2 or 3 a bit longer, sets a corresponding port browser (on the slow 49 the port menu is maintained) together with a 1-page menu containing the basic options for port managment. All port browsers are alike. In particular, longhold 3 is a card browser. Also some hardkeys are active in the browser: NXT toggles browser view, EVAL evals. Other hardkeys, in particular the arrow keys, 0,1,2,3 for visiting the other ports, +/- and ALPHA work as in the 49+ standard filer. Note: In an edit session the keys 0,1,2,3 set the corresponding port menu which is more useful during programming than a port browser.