hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) NAME hass-cui - Character-Based User Interface Used by HASS ABSTRACT A character-based user interface (CUI) has been used for various programs supported by the Hydrologic Analysis Software Support (HASS) Program to enhance and facilitate program use. The interface provides for consistent user interaction across hydrologic applications. The system was designed for ease of programming and for portability to mini-computers and PC's as well as UNIX workstations. USER INTERFACE Program interaction takes place in a screen 80 characters wide by 24 characters high. Figure 1 shows the basic screen layout. Each screen consists of a list of available commands displayed at the bottom of the screen and one or more boxed-in areas that are referred to as panels. Commands are used to obtain additional information and to move between screens. There are three types of panels--data, assistance, and instruction. The data panel displayed at the top of the screen is always present. Data panels contain menus, forms, tables, and text to permit user interaction with the program. An assistance panel may be present depending on user or program assignments. When present, the assistance panel is displayed below the data panel (usually as the middle panel) and contains textual information, such as help messages, valid range of values, and details on program status. The instruction panel is displayed above the available commands when the user is expected to interact with the program. When present, the instruction panel contains information on what keystrokes are required to interact with the program. Each screen can be identified by a name and the path selected to reach the screen. The screen name appears in the upper left corner of the data panel, where the words "screen name" appear in figure 1. The first screen displayed by the program is named "Opening screen". All subsequent screens are named based on the menu option or program sequence that caused the current screen to be displayed. Screen names are followed by "(path)", a string of characters consisting of the first letter(s) of the menu options selected in order to arrive at the current screen. In some cases, descriptive text may follow the path to further help identify the screen. The path can aid in keeping track of the position of the current screen in the menu hierarchy. For example, "Open (FO)" indicates that the menu option Open was selected previously and that the path to this screen from the "Opening screen" consisted of two menu selections--File and Open. 7 Jul 1998 1 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) Figure 1. Basic screen layout +-screen name (path)------------------------program name and version-+ | | | | | | | | | Data panel | | | | | | | | | | | +--------------------------------------------------------------------+ +-assistance type----------------------------------------------------+ | | | Assistance panel | | | | | +--------------------------------------------------------------------+ +-instruction type---------------------------------------------------+ | | | Instruction panel | | | +--------------------------------------------------------------------+ Help:F1 Accept:F2 Prev:F4 Limits:F5 Intrpt:F6 Quiet:F8 Cmhlp Oops Table 1. hass-cui commands --------------------------------------------------------- Associated Command keystrokes*Description --------------------------------------------------------- Help F1 Displays help information in the or ;h assistance panel. The help information is updated as the user moves from field to field in the data panel or to a different screen. The program automatically closes the assistance panel if a screen is displayed for which no help information is available. Accept F2 Indicates that you have "accepted" or ;a the input values, menu option currently highlighted, or text message in the data panel. Selection of this command causes program execution to continue. Cmhlp F3c Displays brief descriptions of the or ;c commands available on the screen. 7 Jul 1998 2 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) Oops F3o Resets all data fields in an input or ;o form to their initial values. Dnpg F3d Displays next "page" of text in or ;d data panel. Available when all of the text cannot be displayed at one time. Uppg F3u Redisplays previous "page" of text or ;u in data panel. Available after execution of Dnpg (F3d). Prev F4 Redisplays a previous screen. Any or ;p modifications in the data panel are ignored. Which screen is the previous one may be ambiguous in some cases. Limits F5 Displays valid ranges for numeric or ;l fields and valid responses for character fields. As with the Help command, information on field limits is updated as the user moves from field to field in the data panel or to a different screen by using the arrow keys or the Enter (Return) key. Intrpt F6 Interrupts current processing. or ;i Depending on the process, returns the program to the point of execution prior to the current process or advances to the next step in the process. Status F7 Displays program status or ;s information. Quiet F8 Closes the assistance panel. or ;q Available when the assistance panel is open. Xpad F9 Opens the assistance panel as a or ;x "scratch pad." Text entered in the scratch pad is saved in a file called "XPAD.DAT". --------------------------------------------------------- * The function keys will execute the commands on most computer systems. On all computer systems, the semicolon key (";") followed by the first letter (upper or lower case) of the command can be used to execute the commands. The F3 function key may not be available on some systems. Commands 7 Jul 1998 3 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) The screen commands and their associated keystrokes are described in table 1. A subset of the screen commands is available for any given screen. Most commands can be executed by pressing a single function key. (The designation for a function key is "F#" where # is the number of the function key.) All of the commands can be executed in "command mode". Command mode is toggled on and off by pressing the semicolon (;) key. In command mode, any command can be executed by pressing the first letter of the command name; for example, "o" or "O" for the Oops command. When commands are discussed in this report, the command name is spelled out with the function key or keystroke given in parentheses. For example, Accept (F2) is the most frequently used command. Use Help (F1) and Limits (F5) to obtain additional information about the current screen and use Status (F7) to obtain information on the state of the program. Cmhlp (;c) will display information on the available commands. Use Quiet (F8) to close the assistance panel. To move between screens, use Accept (F2), Prev (F4), Intrpt (F6), Dnpg (;d), Uppg (;u), or Top (F10). To reset the values in the data panel, use Oops (;o). Xpad (F9) is used to save typed information in a file called XPAD.DAT. Data Panel There are four types of data panels--menu, form, table, and text. Menus offer a choice of two or more options. Data values are entered or modified in one or more data fields of a form or table. General or specific information, program progress, messages, and results of analyses may be displayed in a text data panel. The data panel appears at the top of the screen, as shown in figure 1. There are 16 rows in the data panel when the assistance panel is closed and 10 rows when the assistance panel is open. A single option is selected from a menu that consists of two or more options. There are two ways to select a menu option. Either press the first letter (not case sensitive) of the menu option; if more than one menu option begins with the same letter, press in sequence enough characters to uniquely identify the option; or use the arrow keys to move the cursor to the option and then execute Accept (F2). Forms may contain any number and combination of character, numeric, file name, or option fields. Character fields may be a variable entry, such as a descriptive text string (case sensitive), or they may require a specific entry, such as "yes" or "no" (not case sensitive). The text string "none" in a field indicates that the field is currently undefined. Option fields are activated and 7 Jul 1998 4 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) deactivated by positioning the cursor in the option field and pressing any key, such as the space bar. Use arrow keys to move up, down, and laterally between fields. The Enter (Return) key is used to move forward through fields. Use Accept (F2) to accept the entered and modified data and continue with the program. Executing Oops (;o) sets all fields in the current screen to their initial values. Executing Prev (F4) will cause the data values entered on the current screen to be ignored and the previous screen to be redisplayed. Tables may contain any number and combination of character, numeric, and file name columns. As with forms, character fields may require a specific entry or a variable entry. Use arrow keys to move up, down, and laterally between fields. The Enter (Return) key is used to move forward across rows and to the next row. Some tables may contain more rows than can be displayed in the 10 or 16 rows of the data panel. In these cases, the table is divided into multiple screens. Use Accept (F2) to move forward through each of the screens for the table and to continue with the program after the last screen of the table. Executing Oops (;o) sets all fields in the current screen to their initial values. Executing Prev (F4) will cause the data values entered on the current screen to be ignored and the previous screen to be redisplayed. Executing Intrpt (F6) will cause the data values entered on the current screen to be ignored and the remaining screens in the table to be skipped. Use Quiet (F8) to close the assistance panel and view the 16 lines of the data panel. A text data panel may contain a warning or error message, a tabular list of data, a progress message for an activity that may take more than a few seconds, or other general information. Execute Accept (F2) to continue to the next screen. In cases where the displayed text requires more lines than the number available in the data panel, the Prev (F4), Dnpg (;d), and Uppg (;u) commands may be available to move forward and backward (scroll) through the screens. Note that the up and down arrows also may be used to move through the screens. Intrpt (F6) may be available to permit skipping the remaining screens of text. Assistance Panel The assistance panel provides information to help the user enter data in the data panel or to allow note taking during a program session. The panel appears in the middle of the screen below the data panel. A name corresponding to the type of assistance being provided displays in the upper left corner of the panel, where the words "assistance type" appear in figure 1. The Help (F1), 7 Jul 1998 5 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) Limits (F5), Status (F7), Cmhlp (;c), and Xpad (F9) commands open the assistance panel. The program may open the assistance panel to display status information. Help and Limits provide information about the current screen and data fields; Status provides information about the current process; Cmhlp provides information about the available commands; and Xpad provides a "note pad" for making notes in the file XPAD.DAT. Use Quiet (F8) to close the assistance panel. Assistance panels display four lines at a time. In cases where the assistance information is greater than four lines, the cursor moves into the assistance panel. Use the up and down arrow keys to scroll through the information. If available, the Page Down and Page Up keys may be used to page through the information. Use the command mode toggle (;) to put the cursor back in the data panel. Instruction Panel The instruction panel provides information on how to interact with the current screen, such as how to enter data or how to advance to another screen. This panel appears at the bottom of the screen just above the screen commands (fig. 1). The instruction panel is present whenever the program requires input from the user. Up to four lines of text are displayed in an instruction panel. If an invalid keystroke is entered, the information in the instruction panel is replaced with an error message. In this case, the panel name (upper left hand corner) changes from the usual "INSTRUCT" to "ERROR." Once a valid keystroke is entered, the Instruct panel is redisplayed. SPECIAL FILES Three files are associated with the interaction between the user and the program. System defaults that control how the program operates can be overridden by setting parameters in the optional TERM.DAT file. A session record is written to the PROGRAM_NAME.LOG file each time the program is run; all or portions of this file can be used as input to the program at a later time. Error and warning messages, as well as some additional information, may be written to the file ERROR.FIL. System Defaults--TERM.DAT Certain aspects of the appearance and operation of the program are controlled by parameters within the program. These parameters specify things such as the computer system type, graphic output type, terminal type, program response to the Enter key, and colors. Each parameter is set based on the preferences of users who tested the program. The preset values can be overridden by creating 7 Jul 1998 6 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) a TERM.DAT file in the directory where the program is initiated (the current working directory). The available parameters and the format of the TERM.DAT file are described in Appendix B. If a TERM.DAT file does not exist in the current directory, the message "optional TERM.DAT file not opened, defaults will be used" is displayed briefly when the program starts. If the TERM.DAT file is present, the message "reading users system parameters from TERM.DAT" is displayed. Session Record--PROGRAM_NAME.LOG The keystrokes entered during a program session are recorded in the PROGRAM_NAME.LOG file. Each time the program is run, an PROGRAM_NAME.LOG file is created; if one already exists in the current directory, it is overwritten. All or part of this file can be used as input to the program as a means of repeating the same or similar tasks. To do this, first save the PROGRAM_NAME.LOG file under a different name. Modify the file to contain only the sequence of commands that need to be repeated. Then, at any point in a subsequent program session, press "@"; a small file name panel appears; type the name of the log file and press the Enter key. Appendix B describes the use and format of the PROGRAM_NAME.LOG file. Error and Warning Messages--ERROR.FIL Any error or warning messages produced during a program session are written to the ERROR.FIL file. Each time the program is run, an ERROR.FIL file is created; if one already exists in the current directory, it is overwritten. Diagnostic and summary reports also may be written to this file. Examine ERROR.FIL if an unexpected program response is encountered. Table 2.1. MENCRA values and corresponding program 7 Jul 1998 7 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) response ---------------------------------------------------------- MENCRA Data panel Program response contents when Enter is pressed ---------------------------------------------------------- NEXT menu Same as if Accept (F2) were executed: the highlighted menu option is selected and the program advances to the next screen. form For all but the last field on the form, causes the cursor to advance to the next field. For the last field on the form, the response is the same as for Accept (F2)--the program advances to the next screen. (Note: usually the rightmost, lowest field is the "last" field in the form. Occasionally, however, it is not!) table For each row, the cursor advances across the fields in the row. For all but the last row, the cursor advances from the last field in the row to the first field of the next row. For the last row, the cursor advances to the beginning of the last row. (Use Accept (F2) to advance to the next page of the table.) text Same as if Accept (F2) were executed--the program advances to the next screen. NONE menu No effect--it is ignored. form Cursor is advanced to the next field. When the cursor is in the last field, the cursor cycles back to the first field. table For each row, the cursor advances across the fields in the row. For all but the last row, the cursor advances from the last field in the row to the first field of the next row. For the last row, the cursor advances to the beginning of the last row. (Use Accept (F2) to advance to the next page of the table.) 7 Jul 1998 8 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) text No effect--it is ignored. DOWN menu Same as if the down arrow were pressed: the highlight bar moves to the next menu option. When the highlight bar is on the last menu option, it returns to the first menu option. form Cursor is advanced to the next field. When the cursor is in the last field, the cursor cycles back to the first field. table For each row, the cursor advances across the fields in the row. For all but the last row, the cursor advances from the last field in the row to the first field of the next row. For the last row, the cursor advances to the beginning of the last row. (Use Accept (F2) to advance to the next page of the table.) text No effect--it is ignored. ---------------------------------------------------------- Many of the TERM.DAT parameters control graphical output and give the user the opportunity to change graphics devices, text fonts, symbol sizes, and background color. The values assigned to the graphics parameters depend on the software library used for graphics generation. On UNIX-based computers, the Graphical Kernel System (GKS) is used. The user should note that the graphics parameter values used for GKS as supplied by different vendors will not be the same; the documentation for the user's implementation of GKS should be consulted. On DOS-based computers, the INTERACTER graphics library from Interactive Software Services is used for graphics generation. See the README file distributed with the program for the most current information on producing graphical output using INTERACTER. Table 2.2 lists TERM.DAT parameters with their allowable values and their default values when using the program on a DOS-based computer, on a Data General computer under DG/UX, and on other UNIX-based computers. Table 2.3 lists TERM.DAT parameters specific to screen color assignment on DOS-based computers. The final table, 2.4, shows an example TERM.DAT file that modifies the background color of the graphics screen display from the default of black to a shade of purple. 7 Jul 1998 9 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) Table 2.2. TERM.DAT parameters ------------------------------------------------------------------ Default values ------------------- Parameter DOS DG/UX Other Valid keyword UNIX values Description ------------------------------------------------------------------ TRMTYP PC VT100 VT100 PC Terminal type. VT100 OTHER MENCRA NEXT NEXT NEXT NONE Program response to Enter key. DOWN NEXT USRLEV 0 0 0 0 to 2 User experience level: 0=lots, 1=some, 2=none. GRAPHS YES YES YES NO Is a software library for YES graphics generation available? GKSDIS 1 1100 4 any GKS code number for workstation type for display terminal. GKSPRT 2 102 4 0-9999* GKS code number for workstation type for printer device. GKSPLT 3 7475 4 0-9999* GKS code number for workstation type for pen plotter. GKSMET 4 24 4 0-9999* GKS code number for metafile. GKPREC CHAR STROKECHAR STRING Text precision. CHAR STROKE GKSCFT 1 1 1 -9999 toText font for screen. 9999* GKPRFT 1 -2808 1 -9999 toText font for printer. 9999* GKPLFT 1 1 1 -9999 toText font for plotter. 9999* BCOLOR BLACK BLACK BLACK WHITE Background color of graphics BLACK screen display. OTHER 7 Jul 1998 10 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) BGRED 0 0 0 0 to 100Percent red for background of graphics screen display if BCOLOR=OTHER. BGREEN 0 0 0 0 to 100Percent green for background of graphics screen display if BCOLOR=OTHER. BGBLUE 0 0 0 0 to 100Percent blue for background of graphics screen display if BCOLOR=OTHER. SYMSIZ 100 100 100 1 to Symbol size ratio in 10000 hundredths. TXTEXF 133 100 100 0 to 200Text expansion factor in hundredths. TXTCHS 0 0 0 0 to 200Text character spacing in hundredths. ------------------------------------------------------------------ * Refer to GKS documentation and README file supplied with the program to determine valid values for these parameters. Table 2.3. TERM.DAT parameters for color display (DOS-based computers) ----------------------------------------------------------- Parameter Default Allowable keyword value values* Description ----------------------------------------------------------- CLRFRS 15 0 to 15 Standard foreground color. CLRBKS 1 0 to 15 Standard background color. CLRFRE 7 0 to 15 Foreground color for error messages in instruction panel. CLRBKE 4 0 to 15 Background color for error messages in instruction panel. CLRFRD 14 0 to 15 Color of first letter of commands in command mode. ----------------------------------------------------------- * 0-black, 1-blue, 2-green, 3-cyan, 4-red, 5-magenta, 6-brown, 7-light gray, 8-dark gray, 9-bright blue, 10-bright green, 11-bright cyan, 12-bright red, 13-bright magenta, 14-yellow, 15-white Figure 2. Example TERM.DAT --------------------------- 7 Jul 1998 11 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) BCOLOR OTHER BGRED 40 BGREEN 0 BGBLUE 60 --------------------------- Special files Each time the program is run, two files are produced that aid in troubleshooting and in future program execution--ERROR.FIL and PROGRAM_NAME.LOG. The ERROR.FIL file contains any error messages produced while running the program. Diagnostic and progress messages may be written to this file to aid in debugging. This file should be consulted if an unexpected program response is encountered. The PROGRAM_NAME.LOG file contains a log of all keystrokes made while running the program. This record of keystrokes is helpful when the program is repeatedly used to perform the same functions. The file can be used as input to the program; the keystrokes are read from the file as if they were typed in. To use the file in this way, first change its name to something other than PROGRAM_NAME.LOG to prevent the file from being overwritten the next time the program is started. On any screen within the program, type "@" to be prompted for the log file name. The contents of the file will be read and executed as appropriate. The first line in the log file should be an appropriate response to the screen where the name of the log file is provided. Occasionally, the log file contents will get out of sync with the input expected by the program. When this happens, the program should be terminated and the log file should be edited to correctly order the responses. Log files are most easily created by using the program for the processes to be repeated and then modifying the log file for future program execution. Alphabetic keys pressed will be recorded in the log file in the manner in which they were typed. Nonprinting keys that are pressed, such as the function keys, the semicolon, the arrow keys, or the Page Up and Page Down keys, will be represented in the log file by a unique code number preceded by a pound sign ("#"). These code numbers are listed in the table below. When planning to use a log file, you will discover it is easier to interpret the file when a menu option is chosen by entering the first letter of the menu option instead of by pressing the Enter or F2 key. 7 Jul 1998 12 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) Table 3. Codes used for nonprinting characters in a log file ----------------------------------------------- Code User's keystroke Associated command ----------------------------------------------- #227 ; or Esc* #208 Backspace #213 Return or Enter #301 Up Arrow #302 Down Arrow #303 Right Arrow #304 Left Arrow #307 Page Up #308 Page Down #401 F1 Help #402 F2 Accept #403 F3 #404 F4 Prev #405 F5 Limits #406 F6 Intrpt #407 F7 Status #408 F8 Quiet #409 F9 Xpad #410 F10 Top ----------------------------------------------- * The Escape key is only functional on DOS-based computers. METHOD The user interface was developed under the guidance of Dr. Albert Badre of the Georgia Institute of Technology who provided expertise on human-computer interaction. The established theory and practice of user interfaces were used. HISTORY Significant enhancements to the published version referenced below have been made by the U.S. Geological Survey (USGS) and Environmental Protection Agency. The USGS maintains the latest version. DATA REQUIREMENTS The sole input requirement for a user of the interface is a keyboard with or without function keys and arrow keys. A mouse is not used with the interface. The input requirements for a programmer adding the interface to an existing application are an ASCII file of screen directives that describe the contents, layout, and help information for each screen, and the corresponding Fortran subroutine calls for display of the screens. SYSTEM REQUIREMENTS UNIX-based computers (supported: Data General AViiON and 7 Jul 1998 13 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) Sun SPARCstation). DOS-based computers having a math coprocessor and 4 mb of memory (supported: IBM-compatible computers with a 386 or greater processor). HASS-CUI is written in Fortran and C. Generally, HASS-CUI applications are easily installed on other platforms. APPLICATIONS HASS-CUI is the user interface for a number of USGS supported programs, including: ANNIE - Program to list, table, plot data in a WDM file GLSNET - Regional hydrologic regression and network analysis using generalized least squares HSPEXP - Expert system for calibration of HSPF IOWDM - Program to store time-series data in a WDM file PEAKFQ - Flood-frequency analysis based on Bulletin 17B SWSTAT - Surface-Water Statistics HASS-CUI is also used in a number of programs supported by the Environmental Protection Agency. DOCUMENTATION Kittle, J.L., Jr., Hummel, P.R., and Imhoff, J.C., 1989, ANNIE-IDE, A system for developing interactive user interfaces for environmental models (programmers guide): U.S. Environmental Protection Agency, EPA/600/3-89/034, Environmental Research Laboratory, Athens, Ga., 166 p. CONTACTS Operation and Distribution: U.S. Geological Survey Hydrologic Analysis Software Support Program 437 National Center Reston, VA 20192 h2osoft@usgs.gov Official versions of U.S. Geological Survey water- resources analysis software are available for electronic retrieval via the World Wide Web (WWW) at: http://water.usgs.gov/software/ and via anonymous File Transfer Protocol (FTP) from: water.usgs.gov (path: /pub/software). The WWW page and anonymous FTP directory from which the LIB software can be retrieved are, respectively: 7 Jul 1998 14 hass-cui(1) U.S. Geological Survey (wrdapp) hass-cui(1) http://water.usgs.gov/software/lib.html --and-- /pub/software/general/lib WARNINGS On UNIX-based computers, a monospaced font with a vt100 line-drawing set must be used in order for all panel borders to be displayed properly. For X Window System users, most of the X Window miscellaneous fixed fonts will work well, in particular 8x13bold, 9x15bold, and 10x20. Users of DOS-based computers must load ANSI.SYS in their CONFIG.SYS file for panel borders and text to be displayed properly. SEE ALSO aide(1) - for programmer information on adding HASS-CUI to an existing application peakfq(1) - Flood-frequency analysis based on Bulletin 17B 7 Jul 1998 15