# 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) ```