Choosext

A powerful extension of the CHOOSE command for the HP49/HP49+

Choosext is a very small library with a one-page menu shown in the first screenshot below. Its main command CHOOSX expands the ordinary CHOOSE command. The latter has three Arguments, a title, a nonempty list of items for choosing from, and a real (or zint) to scan the corresponding line for starting the box. CHOOSX has an additional argument, a list called the menu list below. It creates a user-defined menu while the choose box is active to do more than merely executing CANCL or OK. You see a simple builtin example by pressing righshift ALG (82.3) provided flag -117 is clear. The menu here contains besides CANCL and OK a HELP option on F1. With CHOOSX one can generate similar looking but much richer menus, see the examples. This tool has been written for the normal user who is not familiar with SysRPL. Load the library, store it in a port and attach it as usual. Tested in ROM versions 19-6 and in ROM 1.22 on the HP49+.

NEW in version 9.2003
Text revised. Menu names can now also be changed in place, see Example 1.

NEW in version 8.2003
Enriched menu. Choose renamed to CHOOSX. This has no effect in files containing the old commands (backward compatibility). It is now possible to modify the application menu while browsing, for instance if aiming at providing HELP for some items.

NEW in version 1.2003
Revised html-document replaces Choosext.txt.

NEW in version 1.2002: Error behaviour improved. New command CANCL added, to make traditional style appl-menus for the choose box. Text below revised.

CHOOSX will set an arbitrary user-made one-page menu with the option OK appended which will always be on F6. CANCL can optionally be used but is basically dispensable since the CANCL key does the same. If you want the menu to end with both CANC + OK, simply put the library command CANCL at the 5th position into the additional list argument. The set of CHOOSE-arguments used in Example 2 below The screen-shot displays a suitable set of arguments for CHOOSX. This argument structure is also displayed if the library has been chosen via the LIB key. The title in level 4 can be any string, the item list in level 3 any nonempty list. If a member of the item list is itself a list, only the head of this list is displayed in the browser. Its tail is automatically converted into a program which CHOOSX puts on the stack together with the truth value 1 provided OK is pressed on the item. This greatly simplifies the writing of a complex item list. The level 2 argument is the initial Index (position in the choose list), normally 1. The menu list in level 1 should have at most size 5, to leave room for the self-appending OK. It may be empty, in which case you see merely OK in the menu. A member m of the menu list can be a command, a name, a number or itself a list which, if empty, generates an empty space in the menu. The same happens if the empty string occurs in the menu list. If a list member of the menu list is not empty, its head will serve as the menu name, provided it isn't an internal program name. Important: The head may also be a program whose output must be a name string which depends on the program. Thus, the menu name may change during browsing or if pressing the menu key itself. Note that this often occurs in the operating system but is probably a new feature for UsrRPL programmers. It will be explained in detail in the examples below.

Again, the tail of a list member of the menu list is converted into a program to simplify the writing of complex menus. A menu option inside the choose box other than OK or CANCL (if present) will normally be executed and preserve the box and its menu. If you want the box be automatically discarded after executing a menu option, write the option as a list with CANCL at the end. This makes the former lower/upper case convention for menu names dispensable. . But one can always cancel with the CANCEL key as most people do anyway. Also OK is basically dispensable by using ENTER instead. As a matter of fact, ENTER, CANCEL, UpArrow and DownArrow and their shiftings, and some ALPHA-shifted keys are the only active hardkeys in a CHOOSX-browser. Chosing some letter after pressing ALPHA serves quick search of an browser item.

The other library commands are readily explained. Index yields the index of the scanned item as a positive real, essentially used in our examples below. CANCL may optionally included in the browser's menu or perhaps used in the menu options to cancel the box. Halt suspends a running choose box if included in its menu, to have a temporary look at the stack. This is generally recommended. The CONT key always resumes the choose box at its last scanned item. SaveS saves the entire screen (including menu) and RestS restores this saving, see the examples. Outside a choose box, these commands have no visible effect apart from Halt. The commands can be used also in other applications than browsers made by CHOOSX. An easy example for using CHOOSX rather than CHOOSE is counting the position of a letter in the alphabet A,...,Z. Just run the program

« "Position" { A B ... } 1 { { "POS" Index SaveS 1 DISP 1 WAIT RestS } } CHOOSX DROP ».

The dots in first list represent the rest of the alphabet. More elaborated applications using all other Choosext commands are the following examples.

Example 1. Generating a comfortable flag switcher for your most often used system flags. Let's assume these are the flags -40 (clock off/on), -56 (Beep on/off), -85 (UsrRPL/SysRPL Stack), -90 (Choose boxes in current/mini font), -95 ( ALG/RPN mode) and -117 (Browse/Menu). Of course, your favourite flags may be any other ones. Then the program below generates a browser as shown in the screenshot. Besides OK there are 3 menu option, a toggler named "Clr" or "Set" depending on whether the corresponding flag is currently clear or set, option MODE for temporarly visiting the MODE screen, and the Halt option. For instance, pressing Clr in the menu while scanning the 2nd item as in the screen sets flag -56. That is, the menu name has now become "Set" and no error beep will disturb anymore. This may be controlled by pressing the MODE option to see that the Beep option isn't anymore checked. Here the program which has been written in Exact mode:

« "Favourite flags"
   { -40 -56 -85 -90 -95 -117 }
   DUP X « 1
   { { « X Index GET
      FS? "Set" "Clr"   IFTE »
      X Index GET
     DUP IF FS? THEN
      CF ELSE SF END }
      { MODE SaveS
       22 KEYEVAL RestS }
     Halt }
     IF CHOOSX
    THEN DROP
  END   »
»   @ Title.
@ Item list of prefered flags is saved also
@ in the local variable X.Provide initial index.
@ The head of the first member of the menu list
@ is a program for setting the right menu name.
@ Get the indexed flag
and toggle it.
@ Menu option MODE. First save screen, it.
@ after visiting MODE restore the browser.
@ Halt for temporarily visiting the stack.
@ Run CHOOSX.
@ Here pressing OK simply leaves the
@ browser like CANCEL or ENTER.

Example 2. Generating a comfortable browser for the library Keyman which is assumed to be present on your calculator We also assume that library 256 is attached. Consider the program

« "The Keyman browser"
    0 7 FOR X
   1200 X XLIB~  NEXT
   { "Set Menu" 1200 MENU }
   9 LIST
   DUP
   « 1 ML
   IF CHOOSX
   THEN EVAL
   END   »
» @ Title
@ Put the Keyman commands on the stack.
@ The lib-command builder from library 256.
@ The menu setter
@ Item list including the menu-setter, stored
@ also in the local   variable (Symbol 142).
@ Provide initial Index   nd the menu list ML
@ Run CHOOSX
@ Pressing OK evals the scanned item.

Store this in KMBox, say. Before it works we have still to provide the not yet defined menu list ML. This list is not directly included into the above program to make it easily legible. Also ML will contain the local variable . It is the simplest local variable allowed to occur also outside the scope of the UsrRPL program which defines it (this extremely useful feature is unfortunately not explained in the HP49 documentation). ML is presented below. It contains 4 members all of which but the last one are lists again. Thus, the corresponding menu will show a gap just before the menu option OK on F6. This gap could be filled with CANCL by simply adding this command to ML as its last entry.
The head of the first member of ML is a program which yields the string "HELP" on F1 only as long as a Keyman command is scanned. Otherwise it yields the empty string so that F1 will remain blank (no help is needed for setting Keyman's menu). If KMBox is run after producing ML as indicated we get a browser as shown in the next two screenshots. Since the item list is longer in this example, remember the search function. For instance, [ALPHA][R] would scan RclK if it wasn't already scanned.

The left-hand screen scans the last Keyman command More, the other screen the item "Set Menu", with no HELP and no Eval option. The only way to realize this option is by pressing OK. On the other hand, if pressing Eval in the left-hand screen you invoke the More browser which itself has several subbrowsers. All these browsers are active, but we recommend to cancel these browser which returns the current main browser. Eval will be programmed in a way that it immediately evals a scanned item as long as it is a library command. Hence, you may also recall a user assigned key by pressing Eval on RclK. This will only temporarily overwrite the box with the "Hit Key" message. Moving to another item restores the browser perfectly, due to the commands SaveS and RestS which are essentially used in the Eval program. As is seen from these instances, the difference between the Eval option in the menu and evaluating an item with OK is that the former runs inside the browser and does not leave it.
We now are going to write down a menu list ML with the expected properties. Clearly, the HELP texts therein may be chosen according to the user wishes. Since Keyman has 8 commands the text list should have size 8. The HELP text will be displayed in a Message box. But it could also be displayed in a different way. Some of these methods may need SaveS and RestS for saving and restoring the browser screen.

{   { « Index 9 < "HELP" "" IFTE »     @ First member. Its head is here a program.
      IF Index 9 < THEN                        @ The tail without program delimiters.
     {                                                      @ Begin of the HELP text list.
       "IfD: o1 o2   If Double click then o1 else o2"
       "IfL: o1 o2   If longhold then o1 else o2"
       "IfE/P: o1 o2   If Edit mode then o1 else o2"
       "TO?: o TakeOver o"
       "A?DK: Assign or Delete a Key"
       "RclK: Rcl User Key"
       "K&SA: Keycode + Std Assignment"
       "More Tools"
       }                                                     @ End of HELP text list.
       Index GET MSGBOX END }      @ End of first member.
   { STK Index GET }                    @ 2nd member, recalls scanned item from .
   { « Index 9 < "Eval" "" IFTE »          @ 3rd member. It's head is again a program.
         IF Index 9 <
         THEN SaveS Index GET EVAL RestS
         END }                                        @ Save and restore screen after evaluation
      Halt }                                              @ The only non-list member of ML.

Since programming examples on a HP49 demand a lot of writing, they are included also in the package under the names Example1 and Example2 (with ML a part of the program).

Remark 1. There are certain restrictions on the menu options. For instance, an option for setting another menu, for instance the VAR menu, will be ignored if not handled by means of extra local variables. During a session with CHOOSX, its application menu is "frozen" until the scanned item is changed though a menu name may be changed "in place" as in Example1. One may visit other applications with their own menus provided these applications are professionaly programmed.

Remark 2. CHOOSX is nearly as powerful as the famous FPTR^Choose3 which can be managed only in SysRPL. In contrast to this, CHOOSX can completely be managed in UsrRPL. It makes a careful argument checking. For instance, if the initial Index number is negative, it will be corrected to1. However, a bug in the menu option is your problem.

Remark 3 for experts. The head of an item list member or an item itself may also be a bint in which case the browser displays the corresponding message. For instance, the SysRPL program
:: "Boot Messages" 0 BEGIN #1+DUP DUP JstGETTHEMSG NULL$? UNTIL DROP#1- {}N
%1 { ID Numb xIndex DECOMP$ FlashMsg } ONE{}N xCHOOSX DROP ;
recalls all boot messages - 33 pieces in ROM 19.6 and 46 in the latest ROMs.

Wolfgang Rautenberg

raut@math.fu-berlin.de www.math.fu-berlin.de/usr/raut

« "The Keyman browser" 0 7 FOR X 1200 X XLIB~ NEXT { "Set Menu" 1200 MENU } 9 LIST DUP « 1 ML IF CHOOSX THEN EVAL END » »	@ Title @ Put the Keyman commands on the stack. @ The lib-command builder from library 256. @ The menu setter @ Item list including the menu-setter, stored @ also in the local variable (Symbol 142). @ Provide initial Index nd the menu list ML @ Run CHOOSX @ Pressing OK evals the scanned item.
Store this in KMBox, say. Before it works we have still to provide the not yet defined menu list ML. This list is not directly included into the above program to make it easily legible. Also ML will contain the local variable . It is the simplest local variable allowed to occur also outside the scope of the UsrRPL program which defines it (this extremely useful feature is unfortunately not explained in the HP49 documentation). ML is presented below. It contains 4 members all of which but the last one are lists again. Thus, the corresponding menu will show a gap just before the menu option OK on F6. This gap could be filled with CANCL by simply adding this command to ML as its last entry. The head of the first member of ML is a program which yields the string "HELP" on F1 only as long as a Keyman command is scanned. Otherwise it yields the empty string so that F1 will remain blank (no help is needed for setting Keyman's menu). If KMBox is run after producing ML as indicated we get a browser as shown in the next two screenshots. Since the item list is longer in this example, remember the search function. For instance, [ALPHA][R] would scan RclK if it wasn't already scanned.

The left-hand screen scans the last Keyman command More, the other screen the item "Set Menu", with no HELP and no Eval option. The only way to realize this option is by pressing OK. On the other hand, if pressing Eval in the left-hand screen you invoke the More browser which itself has several subbrowsers. All these browsers are active, but we recommend to cancel these browser which returns the current main browser. Eval will be programmed in a way that it immediately evals a scanned item as long as it is a library command. Hence, you may also recall a user assigned key by pressing Eval on RclK. This will only temporarily overwrite the box with the "Hit Key" message. Moving to another item restores the browser perfectly, due to the commands SaveS and RestS which are essentially used in the Eval program. As is seen from these instances, the difference between the Eval option in the menu and evaluating an item with OK is that the former runs inside the browser and does not leave it. We now are going to write down a menu list ML with the expected properties. Clearly, the HELP texts therein may be chosen according to the user wishes. Since Keyman has 8 commands the text list should have size 8. The HELP text will be displayed in a Message box. But it could also be displayed in a different way. Some of these methods may need SaveS and RestS for saving and restoring the browser screen.
{ { « Index 9 < "HELP" "" IFTE » @ First member. Its head is here a program. IF Index 9 < THEN @ The tail without program delimiters. { @ Begin of the HELP text list. "IfD: o1 o2 If Double click then o1 else o2" "IfL: o1 o2 If longhold then o1 else o2" "IfE/P: o1 o2 If Edit mode then o1 else o2" "TO?: o TakeOver o" "A?DK: Assign or Delete a Key" "RclK: Rcl User Key" "K&SA: Keycode + Std Assignment" "More Tools" } @ End of HELP text list. Index GET MSGBOX END } @ End of first member. { STK Index GET } @ 2nd member, recalls scanned item from . { « Index 9 < "Eval" "" IFTE » @ 3rd member. It's head is again a program. IF Index 9 < THEN SaveS Index GET EVAL RestS END } @ Save and restore screen after evaluation Halt } @ The only non-list member of ML.