---------------------------------------
3]EDLINE
3]A STRING GADGET UTILITY FOR AMIGA BASIC
3]By Richard Gallagher, Salem, OR
---------------------------------------

     Anyone who has used AmigaBASIC has seen a string gadget. It's in the
small window that appears when the "Save As" menu item is selected. The
string gadget shows the current name of the program and allows changes to be
made. Unfortunately, the string gadget is one of the Intuition features that
is not supported by Amiga Basic for use in user programs.
     You could use the library routines to "bypass" Amiga Basic and go
directly to the Intuition.library, but this requires the additional work of
setting up structures, which are also not supported by Amiga Basic.
     My problem was that I wanted to display a string on the screen, allow
the user to make changes in that string, and press Return to enter the new
string. I also wanted to be able to make some restrictions, such as maximum
length of the string and restricting certain strings to numbers only.
     So I wrote the subprogram EDLINE to serve as a simple string gadget
for Amiga Basic. It doesn't attempt to exactly imitate the Intuition string
gadget but provides fundamental line editing you may find useful in your
programs.

3]HOW TO USE EDLINE
     An example is the easiest way to describe how to use EDLINE. Suppose
you have a program that prints address labels. Each line of the address must
not exceed the width of the label -- say, 30 spaces. If the variable
"ADDRESS$" contains the string "1234 Main Street", you would set up the call
to EDLINE with the following program lines:

1 S$=SPACE$(30)      'create the buffer for maximum length (30)
2 LSET S$=ADDRESS$   'put the string in the buffer, left-justify
3 LOCATE 10,5        'locate the pen to print the prompt string
4 PRINT "Change the current address: ";   'note the semi-colon!
5 CALL EDLINE (S$)   'call the subprogram
6 CALL STRIP (S$)    'a companion subprogram--see below
7 ADDRESS$=S$        'complete the change

     The first line sets up a buffer (S$) with the maximum spaces allowed
(30).
     The second line left-justifies the ADDRESS$ string in the buffer S$.
     The third line moves the pen to the desired position on the screen.
     The fourth line prints the prompt string you will use. The semi-colon
is important. Wthout it the gadget box would be drawn at the beginning of
the next line instead of after the colon.
     The fifth line calls EDLINE.
     The sixth line calls STRIP, a short subprogram that strips all leading
and trailing blank spaces from the entered string.
     The last line sets the variable ADDRESS$ to the new address.

3]SPECIFICATIONS
     EDLINE does not set up its own requester window. It uses the current
cursor position to draw a mock gadget box, and uses the following colors:

color 2 - foreground
color 1 - background
color 3 - highlight

     On a standard workbench screen this would be black letters on a white
background with an orange highlight box. Do not use EDLINE on a screen
with a depth of one (two colors).
     EDLINE recognizes the following special keys:
left and right arrows - move left/right through buffer
BACK SPACE and DEL - backspace and delete
CTRL-X - clear buffer to all blank spaces (instead of Right AMIGA-X)

     Note: There are two more major differences between EDLINE and Intuition
string gadgets:
     1 - EDLINE does NOT have an Undo feature like true Intuition string
gadgets (Right AMIGA-Q). Once you make a change, the only way to go back to
the original string is to retype it yourself the way it was!
     2 - EDLINE uses overstrike rather than insert editing. That is, what
you type prints over what is already in the box, rather than pushing
existing text to the right as you enter characters.

3]USING EDLINE TO ENTER NUMERICAL STRINGS
     EDLINE allows the programmer to limit the ASCII values it will accept
as input. This would be of value if the subprogram is used to change an
integer value and the user is expected to enter only the digits 0-9. If the
calling program sets the variables KEYMIN% and KEYMAX% before calling
EDLINE, these will be the minimum and maximum ASCII values that can be used
to edit the string. The default values are KEYMIN%=32 and KEYMAX%=126. This
allows all the normal printable keyboard characters to be entered. To limit
the entries to only digits 0-9, set the variables as follows:

KEYMIN%=48  (CHR$(48)='0')
KEYMAX%=57  (CHR$(57)='9')

     The ASCII decimal values are listed the the Appendix to the Amiga Basic
Manual.
     Here is an example program fragment that uses EDLINE to change the
value of the variable FILENUMBER, which is a positive integer of three
digits or fewer:
1 S$=SPACE$(3)         'set up the buffer for 3 digits
2 F$=STR$(FILENUMBER)  'change FILENUMBER to string
3 CALL STRIP (F$)      'remove leading blank space(s)
2 RSET S$=F$           'right justify number in buffer
3 KEYMIN%=48           'set ASCII minimum to digit '0'
4 KEYMAX%=57           'set ASCII maximum to digit '9'
5 EDLINE S$            'alternate method of calling EDLINE
6 FILENUMBER=VAL(S$)   'change string to integer

     Finally, because EDLINE does not use its own window, it will remain on
the screen unless your program does something to erase it. Here are three
ways to do that:

CLS                          'clears the entire screen
LOCATE ,1 : PRINT SPACE$(80) 'clears the line
LINE(a,b)-(c,d),0,bf         'clears a segment of the screen
                             'covered by rectangle (a,b)-(c,d)

     The program "EDLINE.test" uses the subprograms EDLINE and STRIP in a
small test program that follows the examples above. Try it out to see how it
works and examine the program listing. If you would like to use the
subprograms yourself, you can drag the subprograms' icon over to your own
Amiga Basic workdisk and use the MERGE command to add the file EDLINE to
your program.

4]END OF TEXT