
                   INT 60h SPECIFICATION (1.030 - 1.090 )
                   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 1.0 AVAILABLE SERVICES

 1.1 The following services are available in all release versions of the
     ROMS (release versions are 1.030, 1.040, 1.052, 1.07x, 1.09x, where x 
     determines the language).

 SERVICE		FUNCTION
 -------		--------

    00h			Get version number (of ROMs)
    01h			Line Editor
    02h			Get current application
    03h			Reserved for custom add-ins
    .
    .
    08h			Screen Save/Restore
    09h			Draw Box
    .
    .
    0Fh			Menu Handling
    10h			Box Area Calculation
    .
    .
    12h			Message windows
    .
    14h			Error windows


 2.0 DETAILED DESCRIPTION OF SERVICES
     -------- ----------- -- --------


 2.1   GENERAL
       -------

 2.1.1 Where co-ordinates are specified in 16 bit registers (eg. top right,
       bottom left), the upper byte is the y co-ordinate, and the lower
       byte is the x co-ordinate.

 2.1.2 For all box drawing routines (including menus, help, etc.), if
       the box is larger than the physical screen size, characters
       will be displayed incorrectly.


 2.2   Fn 00h  Get version number
       --------------------------

       Parameters:
           None.
       Returns:
           DS:DX   Version number (zero terminated string)


 2.3   Fn 01h  Line Editor
       -------------------

       Parameters:
           DS:SI   Pointer to editor control structure           
       Returns:
           AX      The character which caused termination

       Description
       -----------
           Edits the line of text.  The text can be in a box (or not),
           and text can be longer than screen width.  Scroll margins
           exist at either end of the edit window.
           The control structure is as follows:-

           ep_targ    dw      ?    ; far ptr to string to be edited. Result
                      dw      ?    ; edit is also placed here. All strings
                                   ; zero terminated.
           ep_pos     dw      ?    ; initial position, in bytes, into the
                                   ; text on entry (starting at zero).
           ep_max     dw      ?    ; max length of edited string.
           ep_xpos    db      ?    ; screen xpos (starting at 0)
           ep_ypos    db      ?    ; screen ypos (starting at 0)
           ep_mode    db      ?    ; When set to 2 the string will be cleared
                                   ; as editing starts (eg. files load); If
                                   ; set to 0, the string is not cleared
                                   ; (eg. editing a worksheet cell)
           ep_hit     dw      ?    ; Initial keypress to be processed before
                                   ; getting keypress form user. Typically
                                   ; used for preprocessing characters.
           ep_tit     dw      ?    ; box title and prompt in the form:
                      dw      ?    ;   db 'TITLE',0,'PROMPT',0,0.
           ep_exit    dw      ?    ; array of keycodes (see below) that allow
                                   ; exit from the editor.
           ep_fn      dw      ?    ; address of the getkey routine. Routine 
                      dw      ?    ; should return a 16 bit keycode in AX
           ep_wid     db      ?    ; Maximum box or screen width
           ep_wind    db      ?    ; Set to 0FFh for no box, 0 for a single
                                   ; line box, 1 for a double line box.
           ep_res     dw      ?    ; Reserved
                      dw      ?
           ep_udel    dw      ?    ; address of the undelete routine. This
                      dw      ?    ; routine is called every time a character
                                   ; is deleted. If not needed, use a dummy
                                   ; routine (ret far). DS:BX points to the
                                   ; deleted text. AH is 0 for the left delete
                                   ; and 1 for the right delete. Avoid changing
                                   ; segment registers.

           Notes:
           1. The target buffer should be at least 'max'+1 bytes
              long to accomodate the zero terminator.
           2. If a default string is required, put it in the
              target buffer, zero terminated.
           3. The array of exit keys consists of 16 bit 'keys'.
              The top nibble is zero  for the standard 256 characters,
              but for control characters like home, end,etc., it is
              set to 1.
           4. KEYCODES: Normal ASCII characters represented as AL=ASCII 
              code, AH=0,eg. 'A' is 0041h.
              Extended keycodes represented as AL=scan code,AH=1,
              eg. left arrow=0148h.
              Special (DIP specific) keycodes represented as AL=code,
              AL=2/3. eg. Before sending undeleted characters (always
              inserted, no ^ processing) send 0201h, and send 0202h at
              end of undelete characters.
           5. If you specify a box, then 2 bytes is taken away from
              'wid' when editing.
           6. Similarly, if you give a prompt, this will reduce
              your play area as well.


 2.4   Fn 02h  Get current application
       -------------------------------

       Parameters:
           DL       Set to FFh (-1)
       Returns:
           AL       Current application

           where    AL=0    Not in application
                       1    Worksheet
                       2    Diary
                       3    Editor
                       4    Address Book
                       5    Calculator
                       6    Setup
                       7    Applications menu

       Description
       -----------
           Determines the current application. This would typically be
           done from an editor hook or TSR.


 2.5   Fn 03h  Reserved for custom add-ins
       -----------------------------------

       Please contact Atari directly


Fn 03H  Reserved for Custom Add-ins

A series of 'hooks' are provided into the Editor to enable users to 
control the Editor from the outside.

There are 5 Editor 'hooks'. These enable an application spawned from 
within the Editor to access a limited number of internal functions 
which modify the text and environment.

        EDHO_GOTO       Move the cursor position
        EDHO_GET        Get the cursor position
        EDHO_REF        Refresh the screen
        EDHO_LOC        Get location of character at cursor
        EDHO_INS        Insert strring into text
        EDHO_DEL        Delete characters from text


EDHO_GOTO  Move the cursor position

Parameters:
        AL      0
        CX      Repetition count
        DX      Type of movement

Returns:
        AX      Number of characters moved

Note:   There are 6 types of movement:

            1       Character
            2       Word
            3       Line
            4       Start/End of line
            5       Start/End of para
            6       Start/End of file

A negative repetition count moves backwards.


EDHO_GET    Get the cursor position

Parameters:
        AL      1

Returns:
        BX      Column offset
        DX      Line number

Note:  Returns the current cursor location.


EDHO_REF    Refresh the screen

Parameters:
        AL      2
        BX      Cursor location override
        DX      Invalid flag override

Returns:
        None

Note:  Cursor override is only applicable if the cursor is outside 
the scroll margins, and forces a refresh from the point specified:

            0       Do nothing
            1       Refresh using top scroll margin
            2       Refresh using center
            3       Refresh using bottom scroll

Invalid flag override consisits of 5 bits which are used internally 
by the Editor. They are ORed with any existing bits, and determine 
what type of refresh is performed:

            0       Use default override
            1       Refresh current line
            2       Refresh current paragraph
            4       Refresh current offset
            8       Check within scroll margins
           10H      Refresh border/frame
           20H      Complete redraw


EDHO_LOC       Get location of character at cursor

Parameters:
        AL      3

Returns:
        ES:BX       Address of text

Note:  This service gets the address in RAM of the character at the 
cursor.


EDHO_INS        Insert string into text

Parameters:
        AL      4
        ES:BX       Address of AZCIIZ string to insert

Returns:
        AX      0 if failed

Note:  Inserts text at current cursor position, and moves cursor to 
end of string.


EDHO_DEL        Delete characters from text

Parameters:
        AL      5
        CX      Number of characters to delete
        DX      0 prevents characters from going in Undelete buffer

Returns:
        AX      0 if failed

Note:  A negative number in CX simulates backspace, a positive number 
simulates Delete.


 2.6   Fn 08h  Screen Save/Restore
       ---------------------------

       Parameters:
           AL       Sub-service (0-3)
           BH       Video page number
           DS:SI    Buffer to store saved screen RAM
           CX       Bottom right of screen area to save (inclusive)
           DX       Top left of screen area to save (inclusive)
       Returns:
           None.

       Description
       -----------
           This function either saves or restores the screen area defined
           by CX and DX to the buffer pointed to by DS:SI.
           The sub-service are as follows:-

               00  Save characters only
               01  Save characters + attributes
               02  Restore characters only
               03  Restore characters + attributes
 

 2.7   Fn 09h  Draw Box
       ----------------

       Parameters:
           AL       Type (0=single line, 1=double line)
           BH       Video page number
           CX       Bottom right of box
           DX       Top left of box
       Returns:
           None.

       Description
       -----------
           This function draws a box at the specified location on the
           screen.


 2.8   Fn 0Fh  Menus
       -------------

       Parameters:
           AL       Type (0=single line, 1=double line)
           AL       Bits 3..7 max depth of menu (including borders)
           BH       Video page number
           CH       Last top line
           CL       Last selected item
           DX       Top left of box
           DS:SI    Menu text (double terminated zero)
           ES:DI    Defaults text (double terminated zero)
           (if DI is FFFFh there is no default text)

       Returns:
           AX       -1 for ESC pressed
               OR
           AH       top line
           AL       selected line


       Description
       -----------
           Draws a menu at the location specified in DX. CH specifies the
           line that will appear at the top of the screen, and CL specifies
           the line that the cursor will be on (with respect to the menu
           text, not including the title). The first line of the menu text
           is the menu title and does not have a corresponding entry in the
           defaults text. If no title is required this can be set to zero
           (null string). If bits 3..7 of AL are 0 then the menu will not
           have depth checking. If a single line box is selected, the
           function will draw an empty box (with the title) and return.
           Otherwise the menu will be displayed, and once a selection has
           been made, the menu box becomes single line and control returns
           to the caller.


 2.9   Fn 10h  Box Area Calculation
       ----------------------------

       Parameters:
           DX       Top left of box
           DS:SI    Menu text (double terminated zero)
           ES:DI    Defaults text (double terminated zero)

       Returns:
           AH       Number of items (including title)
           AL       Number of items (including title)
           BX       Number of bytes used (excluding attributes)
           CX       Bottom right of box

       Description
       -----------
           Calculates the number of bytes needed to save the screen for a
           given menu. Note that the maximum width is assumed to be the
           maximum menu item + the maximum default.
           Also DX is destroyed by this call.


 2.10  Fn 12h  Message Windows
       -----------------------

       Parameters:
           BH       Video page number
           DX       Top left of box
           DS:SI    Message text (double terminated zero)

       Returns:
           None.


       Description
       -----------
           Displays text at DS:SI on the screen in a double line box.
           First line of text is taken as the title.
           This service is used for the information messages, such as
           Loading, saving, etc.


 2.10  Fn 14h  Error Windows
       ---------------------

       Parameters:
           BH       Video page number
           DX       Top left of box
           CX       Must be set to non-zero value
           DS:SI    Error text (double terminated zero)

       Returns:
           None.


       Description
       -----------
           Displays text at DS:SI on the screen in a double line box.
           There is no title. A beep is emitted and the function waits
           For a key to be pressed. The screen is then restored and then
           control is returned to the caller.


