a2d/APIs.md
2018-05-27 09:31:43 -07:00

276 lines
6.0 KiB
Markdown

# DeskTop APIs
There are three distinct API classes that need to be used:
* MouseGraphics ToolKit - 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
In addition, some DeskTop data structures can be accessed directly.
<!-- ============================================================ -->
## MouseGraphics ToolKit
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](MGTK.md) for further documentation.
<!-- ============================================================ -->
## DeskTop Jump Table
Call from MAIN (RAMRDOFF/RAMWRTOFF); AUX language card RAM must be banked in. Call style:
```
jsr $xxxx
```
Some calls take parameters in registers.
> NOTE: Not all of the calls have been identified.
> Routines marked with * are used by Desk Accessories.
#### `JUMP_TABLE_MAIN_LOOP` ($4000)
Enter DeskTop main loop
#### `JUMP_TABLE_MGTK_RELAY` ($4003)
MGTK relay call (main>aux)
#### `JUMP_TABLE_SIZE_STRING` ($4006)
Compose "nnn Blocks" string into internal buffer
#### `JUMP_TABLE_DATE_STRING` ($4009)
Compose date string into internal buffer
#### `JUMP_TABLE_0C` ($400C)
???
#### `JUMP_TABLE_0F` ($400F)
Auxload
#### `JUMP_TABLE_EJECT` ($4012)
Eject command
#### `JUMP_TABLE_REDRAW_ALL` ($4015) *
Redraws all DeskTop windows. Required after a drag or resize.
Follow with `DT_REDRAW_ICONS` call.
#### `JUMP_TABLE_DESKTOP_RELAY` ($4018)
DESKTOP relay call (main>aux)
#### `JUMP_TABLE_LOAD_OVL` ($401B)
Load overlay routine
#### `JUMP_TABLE_CLEAR_SEL` ($401E) *
Deselect all DeskTop icons (volumes/files).
#### `JUMP_TABLE_MLI` ($4021)
ProDOS MLI call (Y=call, X,A=params addr) *
#### `JUMP_TABLE_COPY_TO_BUF` ($4024)
Copy to buffer
#### `JUMP_TABLE_COPY_FROM_BUF:=` ($4027)
Copy from buffer
#### `JUMP_TABLE_NOOP` ($402A)
No-Op command (RTS)
#### `JUMP_TABLE_2D` ($402D)
??? (Draw type/size/date in non-icon views?)
#### `JUMP_TABLE_ALERT_0` ($4030)
Show alert 0
#### `JUMP_TABLE_ALERT_X` ($4033)
Show alert X
#### `JUMP_TABLE_LAUNCH_FILE` ($4036)
Launch file
#### `JUMP_TABLE_CUR_POINTER` ($4039) *
Changes mouse cursor to pointer.
#### `JUMP_TABLE_CUR_WATCH` ($403C)
Changes mouse cursor to watch.
#### `JUMP_TABLE_RESTORE_OVL` ($403F)
Restore from overlay routine
<!-- ============================================================ -->
## DeskTop API
Call from AUX (RAMRDON/RAMWRTON). Call style:
```
jsr $8E00
.byte command
.addr params
```
Return value in A, 0=success.
> NOTE: Only some of the calls have been identified.
Commands:
### `DT_ADD_ICON` ($01)
Parameters: { addr icondata }
Inserts an icon record into the table.
### `DT_HIGHLIGHT_ICON` ($02)
Parameters: { byte icon }
Highlights (selects) an icon by number.
### `DT_REDRAW_ICON` ($03)
Parameters: { byte icon }
Redraws an icon by number.
### `DT_REMOVE_ICON` ($04)
Parameters: { byte icon }
Removes an icon by number.
### `DT_HIGHLIGHT_ALL` ($05)
Parameters: { byte window_id }
Highlights (selects) all icons in a window.
### `DT_UNHIGHLIGHT_ALL` ($06)
Parameters: _N/A_
Unhighlights (deselects) all icons.
### `DT_CLOSE_WINDOW` ($07)
Parameters: { byte window_id }
Closes the specified window.
### `DT_GET_HIGHLIGHTED` ($08)
Parameters: { .res 20 }
Copies the numbers of the first 20 selected icons to the given buffer.
### `DT_FIND_ICON` ($09)
Parameters: { word mousex, word mousey, (out) byte result }
Find the icon number at the given coordinates.
### `DT_UNHIGHLIGHT_ICON` ($0B)
Parameters: { addr iconentry }
Unhighlights the specified icon. Note that the address of the icon
entry is passed, not the number.
### `DT_REDRAW_ICONS` ($0C)
Parameters: none (pass $0000 as address)
Redraws the icons on the desktop (mounted volumes, trash). This call
is required after destroying, moving, or resizing a desk accessory window.
### `DT_ICON_IN_RECT` ($0D)
Parameters: { byte icon, rect bounds }
Tests to see if the given icon (by number) overlaps the passed rect.
### `DT_REDRAW_ICON_IDX` ($0E)
Parameters: { byte icon_index }
Redraws the icon at the given index in the icon list. Note that this
is not the same as the icon number.
<!-- ============================================================ -->
## DeskTop Data Structures
DeskTop's state - selection, windows, icons - is only partially accessible
via APIs. Operations such as opening the selected file requires accessing
internal data structures 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)
```