=======================================

"SUPER INPUT Modern" - by Einar Saukas

=======================================



SUPER INPUT Modern is a sophisticated multi-line INPUT utility that

executes anywhere on screen, supports all ASCII characters, and

provides specific interfaces for BASIC and Assembly programs.



The implementation was higly optimized for code size. Notice there

would be no advantage to optimize it for speed instead, since it must

wait for the user to press each key anyway.



During execution, the input cursor will appear in front of existing

characters, just like in modern text editors. However, if you prefer

the cursor moving between characters in classic ZX-Spectrum style, use

"SUPER INPUT Classic" instead, that is available at

http://www.worldofspectrum.org/infoseekid.cgi?id=0027715





============

SPECIAL KEYS

============



Shift-0     DEL

Shift-1     CLEAR

Shift-2     CAPS

Shift-3     INS/OVERWR.

Shift-4     END

Shift-5     LEFT

Shift-6     DOWN

Shift-7     UP

Shift-8     RIGHT

Shift-9     DEL CURRENT

Symbol-I    COPYRIGHT

Enter       EXIT





==============

BASIC PROGRAMS

==============



In BASIC, it works like "INPUT z$" and it's configured using the

following commands:



  * "DIM z$(n)" to indicate the maximum input size.



  * "LET z$=" to set a different initial string (otherwise it will

    keep the previous value, which is initially empty).



  * "PRINT AT" to set the position on screen.



  * "INK", "PAPER" or "BRIGHT" to set different colours (it may be

    convenient to choose a distinct background to indicate the input

    area).



  * "LET x=USR 65000" to execute it and calculate the result size

    excluding trailing spaces.



Afterwards the trailing spaces can be easily discarded using something

like "LET s$=z$( TO x)".



A typical BASIC program using SUPER INPUT looks as follows:



  10 CLEAR 64999: LOAD ""CODE

  20 DIM z$(100)

  30 LET z$="Demo"

  40 PRINT AT 7,0;"Input: ";PAPER 6;

  50 LET x=USR 65000

  60 PRINT AT 15,0;"Text=";z$( TO x);"."



Notice that SUPER INPUT can use any active channel, including #0 that

works like standard INPUT at the lower screen. In this case, it will

simply use the current BORDER colour, unless you specify different

colours directly inside the PRINT statement (remember that commands

INK, PAPER and BRIGHT outside a PRINT statement will reactivate the

main screen):



  10 CLEAR 64999: LOAD ""CODE

  20 DIM z$(57)

  30 LET z$="Demo"

  40 PRINT #0;AT 0,0;"Input: ";PAPER 6;

  50 LET x=USR 65000

  60 PRINT AT 15,0;"Text=";z$( TO x);"."



Since SUPER INPUT reuses the value previously stored in variable

z$, a program may check the result string to validate if it meets a

certain criteria, and continue editing otherwise, such as follows:



  10 CLEAR 64999: LOAD ""CODE

  20 DIM z$(20)

  30 PRINT #0;AT 0,0;"Number: ";PAPER 6;

  40 LET x=USR 65000: IF x=0 THEN GO TO 40

  50 FOR f=1 TO x: IF z$(f)<"0" OR z$(f)>"9" THEN GO TO 40

  60 NEXT f: PRINT AT 15,0;"Value=";VAL z$( TO x)



It's possible to change SUPER INPUT to choose a different variable

instead of z$. For instance, to use "DIM a$" instead of "DIM z$", you

just need to execute this once:



  POKE 65332,CODE "a"



Even so, it's more convenient to use "DIM z$" only, leaving all other

variables as regular strings. This way, when you need to input some

text on string a$ with at most size n, your program may use a GO SUB

routine that looks like this:



9000 DIM z$(n): LET z$=a$: PRINT #0;AT 0,0;

9010 LET x=USR 65000: LET a$=z$( TO x): RETURN





=================

ASSEMBLY PROGRAMS

=================



SUPER INPUT can be used directly in Assembly. Just open a channel, set

the cursor position, load your input buffer address in HL, then call

"main_input". It will return the same input buffer address in DE, and

the result size (excluding trailing spaces) in both HL and BC.



You don't need to use the same input buffer every time. If the user

must fill several fields in a form, it's usually easier to set each

field as an input buffer, using SUPER INPUT to fill them directly.

Just remember that each input buffer must have size NN+2, where the

first 2 bytes store the maximum input size NN, and the next NN bytes

contain the initial string.



A typical Assembly program using SUPER INPUT looks as follows:



INPUT_BUFFER:

        defw    100

REPT 100

        defb    ' '

ENDR



        ld      a, 2

        call    5633            ; open channel #2

        ...

        ld      a, 22           ; PRINT AT 1,0;

        rst     $10

        ld      a, 1

        rst     $10

        ld      a, 0

        rst     $10

        ...

        ld      hl, INPUT_BUFFER

        call    65026           ; "main_input"



SUPER INPUT always uses the value previously stored in the input

buffer. To start the next input with an empty string, the input buffer

must be cleaned first, as follows:



        ld      hl, INPUT_BUFFER

        call    65302           ; "main_clear"





=======

LICENSE

=======



You can freely use the SUPER INPUT routine in your programs, or adapt

this code according to your needs, as long as you clearly credit this.





=======

CREDITS

=======



Designed and implemented by Einar Saukas.



This utility uses the ROM routine "LOOK_VARS" to locate a program

variable in memory as published by Battle Bunny (JimG) at

http://www.worldofspectrum.org/forums/showthread.php?t=38043

