XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Keyman XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX A small but powerful key manager for the HP49 Attention: This file remained for historical reason only. It is not updated. Keyman handles mode-sensitive 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 w i t h o u t 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 one can have even 100 key assignments in USR mode, none of these in conflict with the standard function of a key. We recommend to assign related tools to the same key, similar as in the Examples 3,4 below regarding Keyman options. IMPORTANT: only for ROMversion 19-3 or higher. ---------------------------------------------------------------------------- NEW in version 7.2003: Reorganization of the browser More which includes also the listing of assigned keys, hithertoo on RclK longhold. OVER command added to the proposed assignments in More. Longhold time slightly longer so that it should work also on a good emulator. A revised html-document added. NEW in version 6.2003: For safety reason, the keymap browser from More searches for keymaps in the ports only, not in directories anymore. NEW in version 4.2003: Assignments on 0,1,2 added in More which set the corresponding port immediately. NEW in version 3.2003: ASMTs renamed to More. It now contains besides key assignments some additional tools including the key recorder, see below. These are only directly executed, hence are collected in a choose box. This grants also backward compatibilty. NEW in version 1.2003: LEFTarrow assignment is repeating now. Holding down LEFTarrow, you drive towards HOME but 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_ = LShold, RS_ = RShold, i.e., the shift is *hold* while pressing another key. o = Longhold. <| and |> denote the LEFT and RIGHT arrow keys, resp. All comments on Keyman's options refer to RPN-mode only. Here they are: 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, cf. 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 seconds. Clicking two different keys in sequence should not be done too hasty as this may erronously be interpreted as a double-click. 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 be replaced by a beep, Example 5. The objects O1,O2 can also be Key-records generated by K&SA longpressed, see below. All what is said in this paragraph holds also for other If-options. IfL Needs two arguments, arbitrary objects O2 and O1 in levels 2 and 1. Puts a program onto the stack which, if assigned to a key, executes O2 if the key is pressed a bit longer as usual, and otherwise O1. You'll quickly get a feeling on what "longer pressed" means, about 0.3 seconds as in IfD. We recommend to exercise with the commands RclK or A?D below or with the assignment of OVER to the RIGHT key proposed in More below. 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 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 somewhat misused to make things more clear. The program itself cannot be written in UsrRPL. This task-splitting is indispensable in assigning the Arrow keys. These keys clearly must preserve their cursor-moving function in edit mode. The same holds for the rightshift APPS key which is active only in edit mode. In these and other cases, O2 is usually the standard assignment of the assigned key or its keycode, recalled with K&SA. 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 is always displayed, IfE or IfP. In the IfP-case, O2 should not be usermade (the key would only 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? as explained in the next paragraph. ->TO? Makes a so-called TakeOver program from any object which usually looks like the original - the TakeOver command is unvisible unless flag -85 is set. If the output of ->TO? is assigned to a key then it is evaluated also in edit mode, otherwise the key would simply beep. IMPORTANT: 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? longer adds an "alpha-off" command (for leaving the alpha mode) to the program, not a TakeOver. Useful for assigning a key in alpha-planes. Such an assignment aims at setting a menu or similar things but not at staying in alpha mode. See Example 4 below. A?D Assigns or deletes a key. 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. Then delete the CANCEL key assignment in a second step. A?D does not assign shift-holds of the keys ALPHA and ON since these are ignored by the OS. Thus, assigning these shift-holds is wasted RAM. RclK Invokes the user assignment of the key asked for which may also be a shifthold key. If not assigned a corresponding message is displayed 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 recalls keycode and standard assignment also for shift-hold keys. It also displays type and type name of the key-object. As regards unshifted menu keys, a global name is simply quoted whereas a lib-name (aka rompointer) is quoted together with its content, and to the displayed type name an asterix is appended to remind that the type name refers to the content. For instance, K&SA applied to itself shows "8:Program*" and puts the K&SA-program, the lib-name K&SA, and 11.1 on levels 1, 2 and 3, resp. Also many hardkeys run a lib-name. E.g., if SIN is pressed after K&SA, we see SIN on two levels. SIN on level 2 is the lib-name but on level 1 it is the function SIN. These names are the same in this case, but are distinct in others. E.g., applied to the root key, one sees the root symbol on level 2 and xSQRT on level 1 (flag -85 set). It makes a difference whether a lib-name or its content is taken as an argument O2 for IfE?P. In PRG-mode, the lib-name is printed in the edit line while the function is immediately run, perhaps outside the editor. K&SA must be assigned to a key to ensure access to all keys, Example 2. More Opens a browser with 5 additional items. The last two are browsers as well. 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. The first four items in the More browser act as follows: Assigned Displays the list of all user-assigned keys. Thus, the user may always keep track on the current global assignment situation. PackKeys When deleting some assigned keys, the (hidden) UserKeys contains a lot of reduncancies. One regains the wasted memory (even more than 500 bytes) by running PackKeys from time to time. This also applies if you assigned the empty list to a key which will be ignored but cannot be deleted with DELKEYS. You'll then regain 32 bytes. RecordKeys A key-recorder for a sequence of key-presses. Recording can only be ended with CANCEL. A record is a SysRPL program and can directly be replayed or used as an argument for the If-options, see Example 8. ATTENTION: At most 15 keys can correctly be replayed by a single key-record (the current lenght of a record is always displayed). EXAMPLE: Start RecordKeys and press TOOLS, F1 and end with CANCEL. This creates a program which immediately sets the Flag Browser. KeymapBox For users who like alternatives in user key assignments. E.g., one may have a keymap Phys.K, an Engin.K etc. If a keymap contains many assignments, the commands RCLKEYS and STOKEYS become inacceptably slow. KeymapBox switches a keymap instantaneously. At the begin, the Box has only the item GetUKeys (get current UserKeys list). Run it after some assignments. This puts a list on the stack. Store it in a port, in 2:U.K, say. If running KeymapBox again,"Set 2:K.K" shows up in the box. The suffix .K is basic since KeymapBox looks for names with suffix .K in all ports. Such a name should contain a list obtained with GetUK or a code which evaluates to such a list. A keymap in the Box replaces 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. 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 21.1 with A?D. Now double-click APPS. This sets the lib 256 menu - also in the edit mode - while an ordinary key press sets the APPS Choose box. Instead of taking the standard assignment of 21.1, you may also take the keycode 21.1 itself. If you prefer long-press, use IfL instead of IfD in the example. In this case, the key assignment says << If longpressed the lib 256 menu is set, else the APPS choose box >> 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- directory 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 key 23.1 (TOOL) using A?D. From now on, if TOOL is pressed a bit longer, the STACK-menu will appear which also holds true in edit mode and makes programming faster. This example presents one of the items in More, see the Appendix. 3. IfE?P. It is convenient to have the most important Keyman commands on key K and its shiftings. We assign the program << RclK >> or the rompointer RclK to LS_K with A?D. Thus, LS K does RclK or RCL depending on whether leftshift is hold or not. RS_K (CUT) is one of several keys needed only in edit mode, hence may be used to assign K&SA. Put the standard assignment of 32.3 on level 2 and <> on Level 1. Hit IfE?P short, process with ->TO? and assign the output to 32.31. Then in default mode this key is waiting for another key press and invokes its standard assignment. In edit mode the key does cutting as before. The other Keyman commands are obtained in the next example. 4. We want to set the entire Keyman menu somehow with key K. It could be done with longhold K, for instance. 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 any mode. Clearly, if Keyman is purged the STO key works only outside USR mode. An alternative is to assign Keyman to ALPHA shift longhold. To realize this, process <<1200 MENU>> first with ->TO? longhold which adds a alphaoff to this program. Put the result on level 2, the standard assignment of ALPHA K (i.e., the character K) to level 1 and run IfL. Process the result with ->TO? and assign this to ALPHA K. Now, pressing K in ALPHA mode, puts 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 as follows: << If in ALPHA mode and K is shortly hit write K in the edit line, but if K is longhold (after releasing the ALPHA key) set Keyman's menu and leave the ALPHA mode >>. This is realized by More below. 5. Suppose you often need some command sequence or text in edit mode only. It is perhaps 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 prints the text in the command line just at the cursor position if the editor is active. Several standard assignments on the HP49 are made in this way, COPY, CUT etc. If a text is directly assigned to a key then the key immediately opens the editor (Immediate entry mode) which perhaps 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 directly to 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 IfE, but a similar and slightly more comfortable assignment is contained in More. 7. Version 1.2003 of OT49 contains various togglers, in particular ~ANG and ~COOR, toggling angle and the coordinate systems, resp. Since both are closely related, we want to have them on the same key, LS&pi, say. Put ~COOR on level 2 and ~ANG on level 1, run IfL, then ->TO? and assign this to LS&pi (104.21). A really useful and amazing assignment. If LS is hold and SPS is shortly hit, DEG toggles with RAD in the Header, 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 F1" (it invokes the Flag browser) with K&SA longhold. 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 MODE invokes the MODE dialog screen if normally hit, but sets the Flag browser if longpressed, without further key press. This impressing assignment is contained in More. 9. Record the key sequence "UpArrow NXT F6" (which runs the INFO option from) the interactive stack menu. Put this on level 2, 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 >>. Let the key record be the key sequence "UpArrow RS UpArrow". Then longhold UpArrow drives immediately to the highest level in the interactive stack. Very useful for people frequently working in the interactive stack. ------------------------------------------------------------------------------ REMARK 1. One may compose the If-options and gets an inexhaustible variety of possible ssignments. This all is completely 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 can be made readable with extable (a huge library) by setting flag -85. Results of the If-options can also be used in temporary menus to make a longhold decision on a menu key. Mixed UsrRPL and SysRPL objects can be managed with OT49. IfL or IfD may also be used for getting information on a key's function if the key is longhold or double-clicked. Recommended to those who do not remember their assignments. 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. Rewrite the assignment using the keycode instead of the standard assignment. This makes key assignments safe against upgrades. REMARK 3. People who like printing letters by holding down the alpha key with the left-hand thumb should not assign any alpha-hold key (rc.41) if it prints a character. It is better to assign rc.4, similar to Example 4. REMARK 4. A keymap can also be self-decompressing code, easily made with the BZ-tools from OT49, for instance. UserKeys lists are very homogeneous, hence compression rate is high, mostly over 90%. REMARK 5 FOR EXPERTS. Instead of using the lengthy standard assignments of the Arrow keys in edit mode, one may use the corresponding SysRPL commands for cursor moving, easily found if hacking the standard assignments of the Arrow keys. Some standard assignments are unnamed rompointers, e.g. that of 21.3. One saves many bytes if using the rompointer instead of its lengthy content. ------------------------------------------------------------------------------ Wolfgang Rautenberg - raut@math.fu-berlin.de - www.math.fu-berlin.de/~raut 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, and to Denis Martinez for his key recorder, essentially used in ROMPTR 4B0 D. ------------------------------------------------------------------------------ APPENDIX - Assignments from More (keys are quoted by the letter on it if any) More key assignments can be found in the separate tool Topkeys. ============================================================================== "RS_A..F" assigns the dispensable RShold menu keys in a nice way: If pressing a menu key while holding RS, quotes its name. That may be a global variable or a lib-name like %CH or a port-name. Thus, forget about quoting with RS EQW or with RS alpha for port names. Names from temporary or CST-menus are quoted if they are globals. Otherwise the name's program is recalled. This concerns in particular submenu-names like VECTR in MTH. RS& VECTR recalls a program which just sets the submenu VECTR. "o H: FlagBr" assigns the MODE key 22.2. If normally pressed works as before, but if longpressed invokes the Flag-browser without additional key presses. "o I: STACKMenu" assigns key I (TOOL) to invoke the STACK menu if TOOL is long pressed. This applies in edit menu as well. Thus, one has stack menu commands like DUP immediately at the disposal. Particularly useful while programming. "alpha K: Keyman" assigns alphashift K. If normally hit, the key preserves its standard function. Pressing K (not the alpha which has to be released before!) a bit longer sets Keyman's menu. "LS_K: RclK" assigns the important Keyman commands RclK to LS& K. Note that if the shift is hold and K is pressed longer, all assigned keys are displayed. "RS_K: K&SA" assigns the command K&SA, important for generating If-options. "RS K: More" assigns the Keyman option More. "<|: UPDIRrp LS<|: PICT" assigns the LeftArrow key (34.1) to go UPDIR if hit normally, and continues driving direction HOME if pressed longer. This nicely agrees with the path picture in the Header. PICTURE is now invoked with LS <| as on the HP48. Being in PICTURE, LS_<| toggles the graphic scroll mode. "LS_<|: PAINT" assigns LS_<| with a new plottype PAINT. It respects the size of PICT and does not create a new PPAR file. IMPORTANT: 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. There is no PPAR setting dialog to get the true pixel coordinates. These are important for painting by hand or replacing grobs at the right positions. In writing games pixel coordinates are needed permanently. SPECIAL FEATURE: PAINT runs also in edit mode, to look for some data, for instance. CANCEL nicely returns to the command line. "o |> OVER" assignes the OVER command to |> longhold which normally does SWAP. Thus, you have the two most important Stack operations just on one Key. "o_0..2 SetPort" Pressing key 0, 1 or 2 a bit longer, sets the corresponding port immediately. The chosen port is nicely displayed in the Header. --------------------------------------------------------------------- Wolfgang Rautenberg - raut@math.fu-berlin.de - www.math.fu-berlin.de/~raut CREDITS. The longhold rompointer uses a code of Jonathan Busby. Heiko Arneman translated my ASCII domument in html and created the nice pictures.