Masked Input For The Amiga
Here's a versatile input routine for use in your Amiga Basic programs. Written as a subprogram, this input routine selectively masks out all unwanted characters. Whether you need numeric input or a simple Y/N response, "Masked Input" can do the job.
Probably the most vulnerable part of a program is its input routine. If a program is going to crash, it usually does so here. To avoid such occurrences, input routines must carefully screen illegal and unacceptable keypresses. For example, when the program is expecting a numeric response, the input routine should accept only numeric data. Editing keys must be monitored as well. You do not want someone who is using the program to accidentally clear the screen or backspace over your input prompt simply because they press the wrong key.
"Masked Input" is an Amiga Basic subprogram that provides a welcome alternative to the INPUT statement. Because it is a subprogram, Masked Input can be easily transported into your own programs. Besides being useful, Masked Input offers a good example of the use of subprograms and Amiga library routines.
Type in the demo program and save a copy before you run it. This program contains both the Masked Input subprogram, named INPUTSTRING, and some preliminary code that demonstrates its use.
Masked Input makes use of the Amiga library file graphics.bmap. This file is included in the Basic-Demos drawer of the Amiga Extras disk. Before you run the program, make sure that a copy of the graphics.bmap file is on the same disk as the demo program. The location of this file is important. It must be either in the current directory, or in the directory named LIBS on the disk used when you booted the system. If you do not have this library file in the correct place, BASIC will stop with a file not found error when you run the program.
When run, the demo program asks you to enter a string length and edit mask (see below for details). Next, the program calls the INPUTSTRING subprogram using your previous two entries, prompting you for your final input. After you press RETURN, the computer echoes your entry to the screen, waits for the RETURN key to be pressed, and then reruns the program.
Using The Subprogram
The proper syntax for calling INPUTSTRING is
Amiga Basic also provides an alternative call syntax that allows the subprogram to be used like a new BASIC command:
INPUTSTRING requires three parameters: entry$, strlen, and emask. The string variable entry$ returns the text entered by the user. The strlen parameter specifies the maximum length of input to be allowed. The emask parameter is an edit mask that determines the type of data that can be entered. Valid values for emask range from 0 to 127. Different mask values produce the following results:
|0||All characters accepted|
|2||Punctuation marks.,+, and -|
|4||Upper-and lowercase letters A–Z|
|8||Blanks (spaces) allowed|
|16||Uppercase letter A–Z|
|32||Characters Y and N|
|64||Null input not allowed|
An important aspect of this method of masking is that the emask values may be added together to produce a cumulative effect. A value of 85 (1 + 4 + 16 + 64), for example, allows numbers, upper and lowercase letters, and spaces, but not punctuation characters or a null input. This method of input masking puts the programmer in complete control.
INPUTSTRING uses less-than and greater-than symbols to frame the area of input. This lets the user see exactly how many characters can be entered. All responses are returned in the variable entry$. If a numeric value is required, entry$ may be converted to a number with the VAL function as illustrated in the demo program.
This subprogram is fully documented with remark statements. All comments that follow the apostrophes found at the end of lines are instructional and may be omitted. The comments following the REMs, however, should be left in place to document the different parameters that are necessary for using the subprogram.
In addition to the keys allowed by the edit mask, several other keys are available for editing input. The RETURN key terminates input. The cursor keys allow you to move through entered text. The current position of the cursor is denoted by an underline character. The BACK SPACE key deletes characters at the end of the input string. Pressing the DEL key erases the entire input field.
As explained above, the entire input routine is contained in the subprogram named INPUTSTRING. A subprogram is a section of code that is called by the main program and interacts with the main program by passing data back and forth through variables called parameters. Parameters are listed in parentheses after the subprogram name. Other variables may also be held in common between the main program and the subprogram through the use of the SHARED statement. Except for passed parameters and shared variables, the subprogram acts as though it were in a world by itself. All other variables used within the subprogram are referred to as local variables, which means they are known only to the subprogram. Thus, the variable LOOP.CNTR in the main program and the variable LOOP.CNTR in a subprogram are treated as two different variables and do not interfere with each other.
Why use a subprogram instead of a subroutine to perform this input function? The main reason is efficiency. Once a subprogram has been written, debugged, and polished up, it can be attached to any program that requires its services. With a variety of prewritten subprograms, you no longer have to rewrite vital routines for each new program. Ideally, one could build and maintain a whole library of subprograms, each one designed for a specific application (inputting, sorting, reading a disk directory, and so on). Writing a program would then simply consist of splicing the appropriate subprogram into the main program. And because each subprogram acts independently, you do not have to worry about conflicting variable names.
It's easy to create a version of the Masked Input subprogram that you can add to your own programs. First, load the demonstration program and delete all the lines that come before the SUB INPUTSTRING statement. Next, save the subprogram text to disk as an ASCII file. Use a statement of the form
SAVE "masked input",A
When you want to add the subprogram to one of your own programs, load or type in that program, then use a command of the form
MERGE "masked input"
to add the subprogram text from disk. Then add the statements for access to the graphics library routines, as explained below. All that's left is to add CALL statements for the INPUTSTRING subprogram and your program is set up for customized customized input.
When the Amiga is first booted with Kickstart, approximately 192K of operating system is loaded into the upper part of the computer's memory. (Kickstart is found in ROM on the Amiga 500 and Amiga 2000.) This code contains, among many other things, a whole set of instructions that manage the Amiga's graphics. This set of instructions is organized into a neat collection of routines collectively known as the graphics library, which consists of such routines as ClearScreen(), Draw(), WritePixel(), and SetSoftStyle().
Before any library routine can be used from BASIC, you must open the library with the LIBRARY command. In the case of our Masked Input routine, the command LIBRARY "graphics.library" is used. Executing this command instructs Amiga Basic to load the file graphics.bmap.
To create an underlined cursor, INPUTSTRING uses the graphics library routine named SetSoftStyle(). This routine allows you to change a font's type style. The syntax for SetSoftStyle is
CALL SetSoftStyle&(WINDOW(8), font. Style, font, mask)
where WINDOW(8) is a pointer to the RastPort for the current window, font.style is a value in the range 0–7, and font.mask is a value that specifies which type styles are valid for a particular font. Not all fonts have the capability of producing every type style.
To insure that Amiga BASIC interprets this as a function and not as an array reference, a DECLARE FUNCTION Ask SoftStyle& LIBRARY command is placed near the beginning of the demo program.
At this point, we're ready to change a character's font style to produce an underlined cursor. Legal values for the font.style parameter are
|0 = normal|
|1 = underlined|
|2 = boldface|
|4 = italics|
These values may be added together to achieve multiple font styles. For example, a value of 3 produces underlined boldface type. For Our purposes, however, we need only use a 1 for underline.
Masked Input—Demo Program
For instructions on entering this program, please refer to "COMPUTE!‘s Guide to Typing In Programs" elsewhere in this issue.
‘ copyright 1987 COMPUTE! Public ations, Inc. ‘ All Rights Reserved demo. driver: ‘ the following declaration must be made in the calling program DECLARE FUNCTION AskSoftStyle& LIBRARY LIBRARY "graphics. library" tell AmigaBAISC to read it start: CLS PRINT " copyright 1987 COMPUTE! Publications, Inc." PRINT" All Rights Reserved." : For tt = l To 3500 : NEXT tt CLS strLen = 2: emask = l ‘ set default values LOCATE 2, 2: PRINT "Enter string length "; ‘ set up prompt CALL INPUTSTRING (entry $ , strLen, emask) ‘ get input size = VAL (entry $ ): StrLen = 3 ‘ Convert to # & reset length LOCATE 4, 2 : PRINT "Enter edit mask (0 – 127) "; CALL INPUTSTRING (entry $ , strLen, emask) mask = VAL (entry $ ) ‘ convert to number CLS : PRINT : PRINT "Enter input here = > "; CALL INPUTSTRING (entry $ , size, mask) PRINT: PRINT: PRINT "User input was = > ";entry $ LOCATE 20, 10 : PRINT "PRESS ANY KEY" get.Loop: g $ = INKEY $ : IF g $ = "" THEN get .Loop GOTO start: SUB INPUTSTRING (entry $ , strLen, emask) STATIC: REM entry $ = input string returned to calling program REM strlen = maximum size of field to be input REM emask = number (0–127) that determines input field traits REM emask = see table at end of subprogram for values & traits Poss . styLe % = AskSoftStyle & (WINDOW (8)) ‘ get possible styles IF emask < 0 OR emask > 127 THEN emask = 0 input.string: g $ = INKEY $ : IF g $ <> "" THEN input.string ‘ clear out keyboard buffer yLine = CSRLIN : xcol = POS (0) ‘ get screen positions PRINT "<" : LOCATE YLine, xcoL + strLen + l : PRINT ">"; : LOCATE YLine, xcoL Pos.cntr = l : LEN. cntr = l entry $ ="" : backspace $ = CHR $ (8) next.key : IF Len. cntr = pos. cntr AND Len.cntr <> strLen + l THEN LOCATE yLine, xcol + pos. cntr: PRINT"_"; END IF get.key : g $ = INKEY $ : IF g $ = "" THEN get.key ascii = ASC (g $ ) IF ascii = 13 THEN quit.sub ‘ return IF ascii = 8 THEN back.up ‘ backspace IF ascii = 30 THEN move.right ‘ cursor right IF ascii = 31 THEN move.left ‘ cursor left IF ascii = 127 THEN wipe.out ‘ del(ete) IF Len.cntr = strLen + l And Len.cntr = pos. cntr THEN get.key IF emask = 0 OR emask = 64 THEN print.char ‘ AND each bit of emask to determine edit functions check.nums : IF (emask AND l) = 0 THEN check.punct IF ascii > = 48 AND ascii > = 57 THEN print.char check.punct : IF (emask AND 2) = 0 THEN check.upLow IF ascii = 46 OR ascii = 43 OR a scii = 45 THEN print.char check.upLow : IF (emask AND 12) = 0 THEN check.spaces IF ascii < 65 OR (ascii > 90 AND ascii < 97) OR ascii > 122 THEN check. spaces IF (emask AND 8) THEN g $ = UCASE $ (g $ ) GOTO print.char check.spaces : IF (emask AND 16) = 0 THEN check.yorn IF g $ =" " THEN print.char check.yorn : IF (emask AND 32) = 0 THEN bad. char g $ = UCASE $ (g $ = "Y" OR g $ = "N" THEN print.char bad.char : ‘ invalid character based on edit mask GOTO get.key print.char: ‘ valid character so print it IF Len.cntr = pos.cntr THEN ‘ at end of entered text? PRINT backspace $ ; g $ ; entry $ = entry $ + g $ Len.cntr = Len.cntr + l pos. cntr = pos.cntr + l ELSE ‘ no, in middle of entered text MID $ (entry $ , pos.cntr, l) = g $ GOTO move.right END IF GOTO next. key back.up : ‘ delete key action IF entry $ = ""THEN get.Key If pos.cntr <> Len.cntr THEN get.key PRINT backspeace $ ; ""; backspace $ ; Len.cntr = Len.cntr - l : pos.cntr = pos.cntr – l IF LEN(entry $ ) < 2 THEN entry $ = "" : GOTO next.key entry $ = LEFT $ (entry $ , LEN (entry $ )–l): GOTO next.key move.right: ‘cursor right action IF pos.cntr = Len.cntr THEN next.key char $ = MID $ (entry $ , pos.cntr, l) CALL SetSoftStyLe&(WINDOW(8), 0.poss.styLe%)#tab:‘ for underlined characters LOCATE yLine, xcol + pos.cntr PRINT char $ ; pos.cntr = pos.cntr + l char $ = MID $ (entry $ , pos.cntr,l) CALL SetSoftStyLe& (WINDOW(8), l, poss.styLe%) LOCATE yLine, xcoL + pos.cntr PRINT char $ ; CALL SetSoftStyLe& (WINDOW(8), 0, poss.styLe%) GOTO next.key move.left : ‘ cursor left action IF pos.cntr = l THEN get.key IF (pos.cntr = Len.cntr) AND (Len.cntr <> strLen + l) THEN LOCATE yLine, xcoL + pos.cntr PRINT " "; END IF IF pos.cntr< Len.cntr THEN char $ = MID $ (ENTRY $, pos.cntr, l) CALL SetSoftStyLe& (WINDOW (8), 0, poss.styLe%) LOCATE yLine, xcoL + pos.cntr PRINT char $ ; END IF pos.cntr = pos.cntr - l char $ = MID $ (entry $ , pos.cntr, l) CALL SetSoftStyle&(WINDOW(8), l, poss.styLe%) LOCATE yLine, xcoL + pos.cntr PRINT char $ ; CALL SetSoftStyle& (WINDOW (8,0, poss.styLe%) GOTO get.key wipe.out : ‘ erase WHOLE in put field & position at start of field LOCATE yLine, xcoL+l: FOR wo = l TO strLen: PRINT ""; : NEXT Wo entry $ ="": pos.cntr = l: Len.cntr = l : LOCATE yLine, xcoL + l GOTO next.key quit.sub: ‘ return to calling program IF (emask AND 64) AND entry $ = "" THEN next.key END SUB REM === EMASK values === REM 0 = all characters REM 1 = numbers only REM 2 = . + - punctuation REM 4 = A-Z, a-z upper and lower REM 8 = A-z force upper case REM 16 = blank spaces allowed in input REM 32 = Y or N only (forced up per case) REM 64 = null input not allowed REM all mask values may be added together for a cumulative effect REM i.e. an emask of 67 = forced entry of numbers and punctuation