(Files.hp48) Item: 106 by akcs.softcalc@hpcvbbs.cv.hp.com [brian maguire] Subj: UITL.LIB - user interface toolkit Date: 17 Dec 1992 Here's a user interface toolkit that I wrote close to 2 years ago. This library deals heavily with the user interface, which is comprised of the display, keyboard, and beeper. It was written before HP released their development tools, when I was still learning the internals of the 48, so some of the commands may not be up to par. Still, most of the commands perform powerful functions that are missing from the 48's built-in command set. I originally planned on releasing this library as part of a commercial software package containing various toolkits, but decided not to because of the poor market for toolkit libraries. Instead, I'm releasing this library in the public domain. It may be used and copied freely as long as it is NOT used commercially or as part of a third party software package without prior written permission by the author. Nor may the user be charge for this library beyond the cost of reproduction. Remember, this is still my code, and I retain all rights to it. If you would like to use portions of this library for any application that is sold commercially or posted to the public you MUST get my permission. I'm a pretty easy going guy and I do n't mind other people using my code, but I would like to know when portions of it get used, so please send me e-mail to the fact (this is not an option!). This software is presented as is, without warrantee of any kind. The user bears all risk. To the best of my knowledge, this code will work correctly on ROM versions A-J. Because this code was written before HP release their development tools, it m ay contain unfrozen entry points that may or may not cause the 48 to crash on future ROM versions. If you have questions about ROM version compatibility or you have problems/questions about any of the included commands, feel free to contact me. UITL : User interface tool library Copyright 1991 Brian J. Maguire All Rights Reserved The UITL library and this manual are presented as is, without warrantee, express or implied. Neither the software nor manual may be copied, stored in a retrieval device, or used commercially without written permission of the author. The user is granted limited use of this software for evaluation purposes only. Second parties may not have access to this software package. The author retains the right to revoke the software package at any time unless otherwise stated. Acceptance of this package constitutes agreement of these terms. A basic understanding of the 48 is expected by the user. Please forward comments or questions to... Brian Maguire 139 Kingsbury Dearborn, MI 48128 (313) 274-0428 1. PIXEL LOCATIONS Currently, the 48 uses two different graphic pointer. A complex number specifies a pixel location as defined by PPAR while a list of two binary integers specifies a horizontal and vertical distance from the top corner. A new type of pixel location pointer is used in this library. A single binary integer is used to specify both the horizontal and vertical distance from the top left corner. The right most five nibbles specifies the vertical distance from the left side while next five nibbles defines the distance from the top. For example, the list { #12345h #67890h } and the single binary integer #1234567890h define the same pixel. As another example, the diagram shown below shows a 15 * 3 grob. The pixel list representing the marked pixel is { # 9h, # 2h }. The same pixel is also represented by single binary integer # 900002h. ********************************************** * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ********************************************** * * * * * * * * *XX* * * * * * * * * * * * * * * *XX* * * * * * * ********************************************** * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ********************************************** NOTE: In order to read a binary integer used in graphic operations your 48 should be set to HEX mode. Likewise, your wordsize should be set to at least 40 bits to avoid loosing data. 2. BANG OPERATIONS This library contains commands that perform "bang" operations on graphics. Unlike most 48 commands, which return a new object, a bang type operation directly alters an object in memory. Therefore, an bang operation cannot be undone with the UNDO or LAST operations. Likewise, all pointers that referenced the original objects will point to the altered object. All library commands that perform bang operations end with the "­" character. If this character does not appear in the font used by you computer it is an upside-down "!". This character can be typed into the 48 by pressing [Right-Shift] [DEL] while the alpha shift is on. As an example of a bang type operation, if a grob is stored in 'G1', recalled to the stack, and used as a target grob by a bang type command, the grob in 'G1' is directly altered. As another example, the program << LCDGROB { #5h #5h } { #20h #20h } GNEG­ >> recalls the LCD graphic object and negates a square section. Because they do not create a new copy of a target object, bang operations can save considerable time. They also conserve memory since only one copy of the target object needs to exist in memory. In addition, they allow direct manipulation of the LCD, PICT, and MENU grobs (see the library commands LCDGROB, PICTGROB and MNUGROB). 3. DISPLAY GROBS The 48 uses three GROBs to store display information. The first grob is used to display the stack and status area. It is normally 131 * 56 pixel, but can be resized to any dimensions. The library command LCDGROB returns the actual LCD grob (not a copy). The second grob contains the menu information and is normally displayed on the bottom 8 pixels of the display screen. The menu grob is normally 131 * 8 pixel, but can be resized to any dimension. The library command MNUGROB returns the actual menu grob. The built-in command LCD-> returns a copy of both the status/stack and menu GROBs overlaid on a 131 * 64 grob. The final display grob is PICT. It is used for graphing and can be dimensioned to any size. The library command PICTGROB returns the actual PICT grob. When any on the three display GROBs are recalled to the stack using the appropriate library command and used as a target grob by a bang command the display grob is directly altered. When using the LCD grob and a target for a bang type graphic command only the top 56 pixel can be manipulated. If you want to display graphic information on the lower 8 pixels without altering the menu grob you can resize the LCD grob using the library command LDIM64 and turn the menu display off using the command MOFF. 4. LIBRARY COMMANDS ABOUTUI Info screen ALMCAT Programmable alarm catalog ALRT? Returns alert message (low battery, etc.) and 1 or 0 -> String 1 -> 0 BDKYBP If the beeper is turned on BDKYBP will beep. Otherwise, the display flashes. Flag -56 set -> Screen flashes Flag -56 clear -> Bad key Beep BORDR If the input object is a grob, BORDR draws a box around the graphic by expanding it by one pixel on the top, bottom, left, and right and drawing a box. If the real number (n) is on level one, the object on level two is converted to a grob using the font size(n) and centered in a box. Graphic -> Graphic Any, Real(n) -> Graphic BZYTGL If 0 is on level one the busy annunciator is turned off. Any other real number will turn the annunciator on. Real(0 or not 0) -> Busy annunciator is turned on or off B->PX Converts binary pixel location into a pixel list. Binary -> List äCAT Programmable STAT catalog. CMD? Returns 1 if last command is on, otherwise 0 is returned. Last command flag -> Real(1 or 0) CMDSET If 0 is on level one, last command is turned on. Any other real number turns last command off. Real(0 or not 0) -> Last command flag changed CMLBL Converts the object on level one into a circular menu label grob. This is a new style menu label. See SMENU. Any -> Graphic CTRGROB If two reals are on levels one and two, the object on level three is converted into a grob and centered. The real on level two is used as the font size while the real on level one specifys the grob's width. If a grob is on levels three and one, and a pixel location is on level two, the grob from level one is centered on the grob from level three using the location from level two as the center position. Any, Real(font), Real(width) -> Graphic Graphic, point, Graphic -> Graphic DEFKEYS Redefines the keyboard. The new keyboard definition continues until [ON] is pressed or flag 9 is set. Upon exiting the redefine keyboard the exit key and menu row are returned to levels two and one respectively. The DEFKEYS parameters are as follows. 5: Menu list 4: Keyboard definition list 3: Valid key object 2: Invalid key object 1: { Menu key toggle flag, Special menu flag } A) Menu list The menu list is any standard menu key list or a special menu key list (see SMENU). If it is a special menu list then the menu flag in the list on level one must be 1. Shifted key definitions are not acceptable in the DEFKEYS menu list. If you want to assign a shifted menu key you must do so in the keyboard definition list. B) Keyboard definition list This list must contain (key assignment, keycode) pairs. A key assignment can be any object, but should be a program or global name. A keycode is the standard HP keycode where a key is represented by its row, column, and shift plane. Alpha shifted keys cannot be defined. If the list is empty only the default keys are defined. They are [RIGHT SHIFT], [LEFT SHIFT], [NXT], [ON], and the menu keys. C) Valid key object An object, such as a program or global name, can be defined as a valid key object. This object will be executed only after a valid key is pressed. Any object other than a program, global name, or local name will be ignored. D) Invalid key object An object, such as a program or global name, can be defined as an invalid key object. This object will be executed only after an invalid key is pressed. If the object is not a program, global name, or local name, it will be ignored and the 48 will beep when an invalid key is pressed. E) Key toggle flag If the key toggle flag is a nonzero number, a menu label will flash when its associated key is pressed. Special menu flag If the special menu flag is a nonzero real number, the menu list on level five is used to create a special menu using the SMENU library command. Otherwise, the menu list is used to create a standard custom menu. list, list, obj, obj, list -> real, real DISP1 Displays the object on level two using the small font size. The real number from level one specifies the row number(1-9). Any, Real -> Object from level two is displayed DISP3 Displays the object from level two on the stack display using the large font size. The real number from level one specifies the stack level the object is displayed on. Any, Real -> Object from level two is displayed DMLBL Converts the object on level one into a directory stype menu label grob(normal menu label with bar on top). Any -> Graphic EQCAT Programmable equation catalog command EQWRTR Programmable command that edits an algebraic using the equation writer application. If [ON] is used to exit the application, the original expression is returned on level two and 0 is returned to level one. If [ENTER] is used to exit, the edited expression is returned to level two an 1 is returned to level one. Algebraic -> Algebraic' 1 Algebraic -> Algebraic 0 ERRMSSG Returns the error message string for the error number input on level one. Binary -> String Real -> String FLIP The grob on level one is rotated 180 degrees Graphic -> Graphic FREEZE? Returns real number 0 through 7 specifying the FREEZE display status. See FREEZE in the owner's manual. Freeze display status -> Real(0-7) FTGL Toggles flag state Real(flag) -> Flag state is toggled GAND Graphic AND operator. The grob from level one is ANDed with the grob from level three starting at the position on level two. Operates similar to the built-in command GOR. Graphic, List, Graphic -> Graphic Graphic, Complex, Graphic -> Graphic Graphic, Binary, Graphic -> Graphic GDEL­ Deletes section of grob. The pixel locations on levels two and one specify the area to delete. NOTE: This is a bang operation. Graphic, List, List -> Graphic Graphic, Complex, Complex -> Graphic Graphic, Binary, Binary -> Graphic GETKEY Waits for key stroke and returns the key number and shift number. Keys are consecutively numbered from 1 to 49, starting with the top left corner and advancing from left to right, top to bottom. ******************************* * 1 * 2 * 3 * 4 * 5 * 6 * ******************************* * 7 * 8 * 9 * 10 * 11 * 12 * ******************************* * 13 * 14 * 15 * 16 * 17 * 18 * ******************************* * 19 * 20 * 21 * 22 * 23 * 24 * ******************************* * 25 * 26 * 27 * 28 * 29 * ******************************* * 30 * 31 * 32 * 33 * 34 * ******************************* * 35 * 36 * 37 * 38 * 39 * ******************************* * 40 * 41 * 42 * 43 * 44 * ******************************* * 45 * 46 * 47 * 48 * 49 * ******************************* Sequential key numbers Keyboard -> Real(key, 1-49), Real(shift, 0-6) GKEEP Clears all pixels in a grob except those bounded by the rectangular region defined by the pixel locations input on levels one and two. This is not a bang operation. Graphic, point, point -> Graphic GNEG­ Inverts all pixel in the rectangular region defined by the pixel locations input on levels one and two. NOTE: This is a bang operation Graphic, point, point -> Graphic GOR­ Performs OR operation exactly like the built-in command GOR except GOR­ is a bang operation. Graphic(target), point, Graphic -> Graphic ->GRB The object on level two is converted into a grob. The real number on level one(1-3) defines the font size. This command is similar to the built-in command ->GROB with one exceptions. Unlike ->GROB, ->GRB recognizes carriage returns. Any, Real(1-3) -> Graphic GREPL­ Replaces a rectangular section in a grob exactly like the built- in command REPL except REPL­ is a bang operation. Graphic(target), point, Graphic -> Graphic GRID Draws a grid on LCD. The pixel location input on level three defines the top left corner. The list or binary on level two defines the pixel distance between horizontal and vertical grid lines respectively. Finally, the list or binary on level one defines the number of horizontal and vertical boxes contained in the grid. NOTE: An error will result if the bottom right corner of the grid is off the screen. List, List, List -> Draws grid on LCD Binary, Binary, Binary -> Draws grid on LCD GXOR­ Performs XOR operation exactly like the built-in command GXOR except GXOR­ is a bang operation. Graphic(target), point, Graphic -> Graphic HMRR This command creates a horizontal mirror image of the grob on level one. Graphic -> Graphic HOLD Similar to the built-in command FREEZE, HOLD holds, or maintains, the current display. Unlike FREEZE, which updates the screen when any key is pressed, the display is not updated until an object is executed or the [ON] key is pressed. The display is maintained similar to the message screens in the TIME, STAT, and PLOT menus. The area to be held is defined by a real number between 0 and 7 (see FREEZE in owner's manual). Real(0-7) -> Sets hold status HOLD? Returns a real number(0-7) specifying the HOLD display status. See HOLD. Hold display status -> Real(0-7) IMLBL Converts any object into an inverse menu label grob (labels used in solver menu). Any -> Graphic IORCL Recalls IOPAR. If IOPAR does not exist, it is created in the home directory. -> List IRPT IRPT is a must for programs that have a long run time. It allows you to interrupt a program, perform other calculations, and then restore the original program environment. If the key buffer is empty no action occurs. If however, a key has been pressed, the program is interrupted by saving and clearing the stack, saving the display, and halting the program. You can inspect the state of the stack before the program was halted with the library command IRPTSTK. Entering KILL will abort the program while entering CONT will restore the stack and display, and continue the program. When CONT is entered the display will jump slightly. This is completely normal. Keyboard -> Enters the Interrupt environment if a key is pressed IRPTSTK Returns the stack before a program was interrupted with the library command IRPT. The error message "Invalid Environment" is displayed if IRPT is not active. NOTE: IRPTSTK does not clear the current stack. It adds the contents of the stack before an interrupt to the current stack. If you want the current stack replaced with the interrupt stack use the sequence CLEAR IRPTSTK. -> Stack before interrupt KEYRPT As long as the key number input on level one remains pressed KEYRPT repeatedly evaluates the object on level two. Regardless of whether the key number from level one is pressed, the object on level two is evaluated at least once. The key number must be in the standard HP key format(rowcol,shift). Global, Real -> Local, Real -> Program, Real -> KEY-> Converts 48 key number (rowcol.shift) into consecutive key number and shift number. See GETKEY for explanation on consecutive key numbers. Real -> Real, Real āKEY Returns the alpha string assigned to the HP key number(rowcol.shift) on level one. The strings returned for shift numbers .1 through .3 are the same as those returned for .4 through .6. Real -> String ->KEY Converts a consecutive key number and shift number into a standard HP key code. See GETKEY for an explanation on consecutive key numbers. Real, Real -> Real LBOX Draws a box on LCD. The pixel locations input on levels one and two define opposite corners. point, point -> LCDGROB Returns the actual grob(not a copy) defining the LCD(stack) display. Its value continually changes every time the stack display changes. To see how this works, key in LCDGROB DUP and enter the graphic environment ([orange shift] [left arrow]). Now place the grob from level one on PICT ([blue shift] [up arrow] [blue shift] [left arrow] NXT NXT REPL ). The last stack display is placed on the screen. Now exit the graphic environment (ON) so the stack display can be updated. Finally enter the graphic environment again and place the grob from level one on PICT as before. This time a different value is placed on the screen. When used as a target grob by a bang command, the LCD grob is directly altered. -> Graphic ->LCDR Replaced the LCD(stack) display with the graphic input on level one like the built-in command ->LCD except for several differences. ->LCDR does not clear the display first, and grobs smaller than 131 pixel wide and 56 pixels tall are placed on top of the existing display. Graphic -> LCMD Returns the last command line as a string. If last command is turned off an empty string is returned. -> String LDIM56 Redimensions the LCD(stack) grob to 56 pixel in height. This is its default size. LDIM64 Redimensions the LCD(stack) grob to 64 pixel in height. This allows you to display graphics in the menu area(the menu display must be turned off using the library command MOFF). NOTE: You should reset the display with LDIM56 when exiting a program. LELINE The line connecting the two pixel locations input on levels one and two are erased on the LCD(stack) grob. point, point -> LINEQ Returns the equation of the line passing through the two points defined by the complex numbers (pixel locations) input on levels one and two. Complex, Complex -> Algebraic LLINE Draws a line on the LCD(stack) grob connecting the pixel locations input on levels one and two. The pixel locations cannot be outside the LCD grob. point, point -> LSTKEY Returns the standard HP key number of the last key pressed in the DEFKEYS environment and the last menu row (see DEFKEYS). The error "Invalid Environment" will occur if the DEFKEYS environment is not active. -> Real, Real LSTSTK Restores last stack as if [orange shift] [2] had been pressed. LSTSTK? Returns 1 if last stack is active, otherwise returns 0. Last stack flag -> Real(1 or 0) LTLINE Toggles the pixels on the LCD(stack) grob that lie on the line connecting the pixel locations input on levels one and two. The pixel locations cannot be outside the LCD grob. point, point -> MDISP Displays the object from level one on the menu grob using the small font size. Any -> Object displayed in menu area MKYņ Toggles a menu label from white on black to black on white and back to white on black. The real number 1 though 6 defines the menu label to be toggled. Any number less than 1 will toggle the first menu label. Likewise, any number greater than 6 will toggle the last label. Real(1-6) -> Menu label is toggled MLBL Converts the object on level one into a normal menu label grob. Any -> Graphic MNUGROB Returns the actual grob(not a copy) defining the menu display. Its value continually changes every time the menu display changes. To see how this works, key in MNUGROB DUP and enter the graphic environment ([orange shift] [left arrow]). Now place the grob from level one on PICT ([blue shift] [up arrow] [blue shift] [left arrow] NXT NXT REPL ). The last menu display is placed on the screen. Now exit the graphic environment (ON) and copy the current menu display to temporary memory (NEWOB). Finally, enter the graphic environment again and place the grob from level one on PICT as before. This time a different value is placed on the screen. When used as a target grob by a bang command, the menu grob is directly altered. -> Graphic MNUROW Sets menu row. The real number on level one specifies the new row. 1 sets the next row, 2 sets the previous row, and 3 sets the first row. REAL(-1,0 or 1) -> Changes current menu row. MOFF Removes the menu display from the screen and redimensions LCD to 131 by 64. See the section titled DISPLAY GROBS MON Displays the menu grob on the lower 8 pixels of the screen. MON? Returns 0 if the menu display is off. Otherwise, 1 is returned Menu display(off or on) -> Real(0 or 1) MTWRTR Edits a matrix using the matrix writer application. If [ON] is used to exit the application the original matrix is returned along with the real number 0. If [ENTER] is used to exit, the edited matrix is returned with the real number 1. Array(1) -> Array(1), 0 Array(1) -> Array(2), 1 MUPDT Updates the menu display. NEWEQ Programmable NEW command from SOLVE menu. NEWä Programmable NEW command from STAT menu. OMLBL Converts object on level one into an oval menu label grob. This is a new style menu label (see SMENU). Any -> Graphic PELINE The line connecting the two pixel locations input on levels one and two are erased on PICT. point, point -> PICT? Returns 1 is PICT is currently being displayed. Otherwise, LCD is displyed and 0 is returned. PICT displayed when a graph is drawn or the built-in command PVIEW is entered. LCD is the default display. It can be displayed within a program using the built-in command TEXT. -> Real PICTGROB Returns the actual grob(not a copy) defining PICT, the graphic display. Its value continually changes every time the stack display changes. To see how this works, purge PICT and recall it to the stack by entering PICT PURGE PICTGROB. Graphic 0 x 0 should be displayed in level one. Next redimension PICT by entering #131d #64d PDIM. Graphic 132 x 64 should be displayed on level one now. When used as a target grob by a bang command, PICT is directly altered. -> Graphic PPARCL Recalls PPAR. If it does not exist it is created in the current directory. -> List äPRCL Returns the STAT parameter list. If äPAR does not exist in the current directory, it is created. -> List PRESET Resets PICT and PPAR to their default values. PRTRCL Returns the Print parameter list. If PRTPAR does not exist in the home directory it is created. PX* If two pixel lists are on levels one and two, their corresponding components are multiplied. If levels one and two contain a pixel list and a real or binary number, each component of the pixel list is multiplied by the number. List, Real -> List List, Binary -> List List, List -> List Real, List -> List Binary, List -> List PX+ Adds corresponding components of two pixel lists. List, List -> List PX- Subtracts corresponding components of two pixel lists. List, List -> List PX/ If two pixel lists are on levels one and two, each component on level two is divided by the corresponding component on level one. If level two contains a pixel list and level one contains a real or binary number, each component of from level two is divided by the number on level one. Likewise, if a real or binary number is on level two and a pixel list is on level one, a new pixel list whose components are calculated by dividing the number from level two by the corresponding components on level one is returned. List, Real -> List List, Binary -> List List, List -> List Real, List -> List Binary, List -> List PX? Return 1 if the pixel location input on level one on. Otherwise. 0 is returned. Graphic, point -> Real(1 or 0) PXOFF­ Turns off one pixel in the grob from level two using the pixel location input on level one. NOTE: This is a bang operation Graphic, point -> Graphic PXON­ Turns on one pixel in the grob from level two using the pixel location input on level one. NOTE: This is a bang operation Graphic, point -> Graphic PX->B Converts a pixel location from a list type to a binary integer type. List -> Binary PX->R Converts a pixel list into two real numbers. List -> Real, Real R->PX Converts two real numbers into a pixel list. Real, Real -> List SMENU Creates a custom menu from a list much like the built-in command MENU with the following exceptions. If the object used to create a menu label is a global name, a standard label is created. All other objects are converted to a string. Next, the first character is striped and, if it matches one of the control characters listed below, a special menu label is created. Otherwise, a standard label is used. "D" - Directory Label White letters on a black box with a bar on top. "I" - Inverse Label Black letters on a white background, inside a box. The same label that are used in the solver menu. "O" - Oval Label White letters on a black oval. "C" - Circular Label Black letters on a white background, inside a rounded cornered box. "F" - Flag Indicator Label An integer between -64 and 64, excluding 0, must follow the character "F". This integer specifies a flag. The remaining portion of the string is used as the name for the label. If the specified flag is set, a small white box will appear on the right side of the label. As an example, "F-20PRG" will create a standard label with the name PRG. If flag -20 is set, a box will appear after the name. Three predefined menu labels can be displayed by using special strings. "BLANK" - No menu box "BOX" - White label in black box "GREY" - Grey pattern box As an example of how SMENU works, try creating the following menu. { "BOX" "GREY" "BLANK" "DDIR" "OCRV" "ISOLV" { "F-56BPOFF" << -56 FTGL >> } "CSEE" "ASTD" PRG1 } List -> Creates custom menu STK Programmable interactive stack command. STKUPDT Updates the stack display. STSUPDT Updates the status display. UNHOLD Removes the HOLD and FREEZE display flags specified by the real number on level one. See FREEZE in the owners manual and HOLD in this manual. Real -> Clears HOLD and FREEZE display status. YES? Create a custom menu with "YES" on the left and "NO" on the right. Pressing "YES", "NO" or [ON] exits the routine. If "YES" is pressed the real number 1 is returned to level one. Likewise, pressing "NO" or [ON] returns 0 or -1 respectively. Menu prompt -> Real(-1, 0 or 1)