a2d/APIs.md

DeskTop APIs

There are three distinct API classes that need to be used:

• Mouse Graphics Tool Kit - graphics primitives, windowing and events
• DeskTop Jump Table - simple JSR calls starting at $4003 MAIN, no arguments
• DeskTop API - another MLI-style interface starting at $8E00 AUX

Mouse Graphics Tool Kit

This is a complex API library written by Apple circa 1985. It consists of:

• Graphics Primitives - screen management, lines, rects, polys, text, patterns, pens
• Mouse Graphics - windows, menus, events, cursors

Entry point is fixed at $4000 AUX, called MLI-style (JSR followed by command type and address of param block).

See MGTK.md for further documentation.

DeskTop Jump Table

Call from MAIN (RAMRDOFF/RAMWRTOFF). Call style:

   jsr $xxxx

NOTE: Most of these calls have not been identified yet.

JUMP_TABLE_REDRAW_ALL ($4015)

Redraws all DeskTop windows. Required after a drag or resize. Follow with DESKTOP_REDRAW_ICONS call.

JUMP_TABLE_CLEAR_SEL ($401E)

Deselect all DeskTop icons (volumes/files).

JUMP_TABLE_CUR_POINTER ($4039)

Changes mouse cursor to the default pointer. Note that bitmap is in the language card memory so it must be swapped in.

JUMP_TABLE_CUR_WATCH ($403C)

Changes mouse cursor to a watch. Note that bitmap is in the language card memory so it must be swapped in.

DeskTop API

Call from AUX (RAMRDON/RAMWRTON). Call style:

   jsr $8E00
   .byte command
   .addr params

NOTE: Only a single call has been identified so far.

Commands:

DESKTOP_REDRAW_ICONS ($0C)

Parameters: none (pass $0000 as address)

Redraws the icons on the desktop (mounted volumes, trash). This call is required in these cases:

• After destroying a window (CloseWindow)
• After repainting the desktop (JUMP_TABLE_REDRAW_ALL) following a drag (DragWindow)
• After repainting the desktop (JUMP_TABLE_REDRAW_ALL) following a resize (GrowWindow)

DeskTop Data Structures

DeskTop's state - windows, icons - is accessible indirectly via APIs, and data structures can be accessed directly.

Selection

• path_index (byte) - id of active window in path_table

• selected_file_count (byte) - number of selected icons

• selected_file_list (array of bytes) - ids of selected icons

Window - representing an open directory

• path_table (array of addrs) - maps window id to window record address

Window record: 65-byte pathname buffer; it is a length-prefixed absolute path (e.g. /HD/GAMES)

Icon - representing a file (in a window) or volume (on the desktop)

• file_table (array of addrs) - maps icon id to icon record address

Icon record: 27-byte structure optimized for rendering the file/volume icon.

     .byte icon      icon index
     .byte ??
     .byte type/window_id
                     (bits 0-3 window_id)
                     (bits 4,5,6)
                            000 = directory
                            001 = system
                            010 = binary
                            011 = basic
                            100 = (unused)
                            101 = text/generic
                            110 = (unused)
                            111 = trash
                     (bit 7 = open flag)
     .word iconx     (pixels)
     .word icony     (pixels)
     .addr iconbits  (addr of {mapbits, mapwidth, reserved, maprect})
     .byte len       (name length + 2)
     .res  17  name  (name, with a space before and after)