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

"SUPER INPUT Classic" - by Einar Saukas

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



SUPER INPUT Classic 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 between characters, in

classic ZX-Spectrum style. However, if you prefer the cursor moving in

front of existing characters, just like in modern text editors, use

"SUPER INPUT Modern" instead, that is available at

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





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

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 NEXT

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$(56)

  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 65012,96+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    65047           ; "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    65306           ; "main_clear"





==========

64 COLUMNS

==========



SUPER INPUT only depends on standard functionality provided by RST $10

thus it can be used with any currently active output channel.



For instance, it can be used together with 64#4, the 64 columns driver

for the ZX-Spectrum available here:



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



However, in this case a few minor changes are required due to 64#4

particularities:



  * Recompile SUPER INPUT to a different address (500 bytes lower) 

    since both SUPER INPUT and 64#4 are located in the same area of 

    memory.



  * Replace "call PO_FETCH" and "call PO_STORE" with instructions

    "ld hl,(65030)" and "ld (65030),hl" respectively, since 64#4 

    doesn't store screen coordinates in the standard addresses.



  * Replace "ld c,32" with "ld c,64", thus Shift-6 and Shift-7 will

    move 64 characters instead of 32.



  * Define block graphics that are missing from the official 64#4 

    fonts, but are used as cursor graphics in SUPER INPUT.



SUPER INPUT release also includes a version called "Classic64" with

these changes mentioned above.





=======

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.

