mirror of
https://github.com/mi57730/a2d.git
synced 2024-06-07 23:29:32 +00:00
Documentation updates
This commit is contained in:
Joshua Bell
parent
71c2da54ae
commit
9a2a595f8d
144
APIs.md
144
APIs.md
|
|
@ -6,6 +6,11 @@ There are three distinct API classes that need to be used:
|
|||
* 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:
|
||||
|
|
@ -17,60 +22,161 @@ Entry point is fixed at $4000 AUX, called MLI-style (JSR followed by command typ
|
|||
|
||||
See [MGTK.md](MGTK.md) for further documentation.
|
||||
|
||||
<!-- ============================================================ -->
|
||||
|
||||
## DeskTop Jump Table
|
||||
|
||||
Call from MAIN (RAMRDOFF/RAMWRTOFF). Call style:
|
||||
|
||||
Call from MAIN (RAMRDOFF/RAMWRTOFF); AUX language card RAM must be banked in. Call style:
|
||||
```
|
||||
jsr $xxxx
|
||||
```
|
||||
Some calls take parameters in registers.
|
||||
|
||||
> NOTE: Most of these calls have not been identified yet.
|
||||
> NOTE: Not all of the calls have been identified.
|
||||
> Routines marked with * are used by Desk Accessories.
|
||||
|
||||
#### JUMP_TABLE_REDRAW_ALL ($4015)
|
||||
#### `JUMP_TABLE_MAIN_LOOP` ($4000)
|
||||
|
||||
Redraws all DeskTop windows. Required after a drag or resize. Follow with DESKTOP_REDRAW_ICONS call.
|
||||
Enter DeskTop main loop
|
||||
|
||||
#### JUMP_TABLE_CLEAR_SEL ($401E)
|
||||
#### `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_CUR_POINTER ($4039)
|
||||
#### `JUMP_TABLE_MLI` ($4021)
|
||||
|
||||
Changes mouse cursor to the default pointer. Note that bitmap is in the language card memory so it must be swapped in.
|
||||
ProDOS MLI call (Y=call, X,A=params addr) *
|
||||
|
||||
#### JUMP_TABLE_CUR_WATCH ($403C)
|
||||
#### `JUMP_TABLE_COPY_TO_BUF` ($4024)
|
||||
|
||||
Changes mouse cursor to a watch. Note that bitmap is in the language card memory so it must be swapped in.
|
||||
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
|
||||
```
|
||||
|
||||
> NOTE: Only a single call has been identified so far.
|
||||
> NOTE: Only some of the calls have been identified.
|
||||
|
||||
Commands:
|
||||
|
||||
#### DESKTOP_REDRAW_ICONS ($0C)
|
||||
### `DT_ADD_ICON` ($01)
|
||||
|
||||
Parameters: { addr icondata }
|
||||
|
||||
### `DT_HIGHLIGHT_ICON` ($02)
|
||||
|
||||
Parameters: { byte icon }
|
||||
|
||||
### `DT_UNHIGHLIGHT_ICON` ($03)
|
||||
|
||||
Parameters: { byte icon }
|
||||
|
||||
### `DT_CLOSE_WINDOW` ($07)
|
||||
|
||||
Parameters: { byte window_id }
|
||||
|
||||
### `DT_FIND_ICON` ($09)
|
||||
|
||||
Parameters: { word mousex, word mousey, (out) byte result }
|
||||
|
||||
### `DT_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:
|
||||
Redraws the icons on the desktop (mounted volumes, trash). This call
|
||||
is required after destroying, moving, or resizing a window.
|
||||
|
||||
* 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)
|
||||
### `DT_ICON_IN_RECT` ($0D)
|
||||
|
||||
Parameters: { byte icon, rect bounds }
|
||||
|
||||
<!-- ============================================================ -->
|
||||
|
||||
## DeskTop Data Structures
|
||||
|
||||
DeskTop's state - windows, icons - is accessible indirectly via APIs,
|
||||
and data structures can be accessed directly.
|
||||
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
|
||||
|
||||
|
|
|
|||
20
README.md
20
README.md
|
|
@ -1,20 +1,20 @@
|
|||
# A2D
|
||||
# Apple II DeskTop
|
||||
|
||||
[](https://travis-ci.org/inexorabletash/a2d)
|
||||
|
||||
Work-in-Progress disassembly of Apple II Desktop (a.k.a. A2.Desktop)
|
||||
Work-in-Progress disassembly of Apple II Desktop (a.k.a. MouseDesk)
|
||||
|
||||
## Background
|
||||
|
||||
A2.Desktop started its life as "Mousedesk" by Version Soft, as a mouse-driven
|
||||
Mac-like "Finder" GUI application for 8-bit Apples with 128k of memory
|
||||
(Enhanced Apple //e, Apple //c) using double-hires monochrome graphics
|
||||
(560x192) and the ProDOS operating system.
|
||||
Apple II Desktop started its life as "MouseDesk" by Version Soft. It
|
||||
is a mouse-driven Mac-like "Finder" GUI application for 8-bit Apples
|
||||
with 128k of memory (Enhanced Apple //e, Apple //c) using double-hires
|
||||
monochrome graphics (560x192) and the ProDOS operating system.
|
||||
|
||||
Although the history is sketchy, it appears that Apple Computer licensed
|
||||
(or acquired) the software, and released it - rebranded as Apple II Desktop -
|
||||
as the initial system software for the Apple IIgs before 16-bit GS/OS
|
||||
replaced it. The rebranded version still functions on 8-bit Apples.
|
||||
Apple Computer acquired the software and released it - rebranded as
|
||||
Apple II Desktop - as the initial system software for the Apple IIgs
|
||||
before 16-bit GS/OS replaced it. The rebranded version still functions
|
||||
on 8-bit Apples.
|
||||
|
||||
Overview: http://toastytech.com/guis/a2desk.html
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,9 @@ DAs are documented here.
|
|||
|
||||
### Desk Accessory Lifecycle
|
||||
|
||||
* Loaded/invoked at $800 MAIN (have through $1FFF available)
|
||||
* DAs are loaded/invoked at $800 MAIN
|
||||
* Up to $1C00 MAIN is available
|
||||
* But AUX $1B00 and on must be preserved.
|
||||
* Save stack pointer
|
||||
* Copy DA code from MAIN to AUX (e.g. using `AUXMOVE`) at same address.
|
||||
* Transfer control to the AUX copy
|
||||
|
|
@ -25,6 +27,6 @@ DAs are documented here.
|
|||
* Destroy window (`CloseWindow`)
|
||||
* Tell DeskTop to redraw desktop icons (`DESKTOP_REDRAW_ICONS`)
|
||||
* Switch control back to MAIN (`RAMRDOFF`/`RAMWRTOFF`)
|
||||
* Ensure ALTZP and LCBANK1 are on
|
||||
* Ensure ALTZP and LCBANK1 are still on
|
||||
* Restore stack pointer
|
||||
* `rts`
|
||||
|
|
|
|||
|
|
@ -11,12 +11,7 @@ New desk accessories:
|
|||
* [This Apple](this.apple.s) - complete!
|
||||
* [Eyes](eyes.s) - complete!
|
||||
|
||||
## Desk Accessory Details
|
||||
|
||||
* Loaded at $800 through (at least) $14FF
|
||||
* Copy themselves from Main into Aux memory (same location)
|
||||
* Can call into ProDOS MLI and MGTK/A2D entry points ($4000, etc)
|
||||
* See [API.md](API.md) for programming details
|
||||
See [API.md](API.md) for programming details
|
||||
|
||||
## Files
|
||||
|
||||
|
|
@ -62,7 +57,7 @@ Mount this disk image in your emulator, or transfer it to a real floppy
|
|||
with [ADTPro](http://adtpro.com/), then follow the install instructions
|
||||
below.
|
||||
|
||||
### Mounting Folder via the Virtual ]\[ Emulator
|
||||
### Mount Folder in Virtual ]\[
|
||||
|
||||
If you use [Virtual \]\[](http://www.virtualii.com/) as your emulator,
|
||||
you can skip creating a disk image.
|
||||
|
|
@ -87,7 +82,7 @@ Transfer the `.built` files in the `out` directory, ensuring you:
|
|||
|
||||
* Drop the `.built` suffix
|
||||
* Ensure they have ProDOS file type `$F1`
|
||||
* Ensure they have start address `$800`
|
||||
* Ensure they have start address `$0800`
|
||||
* Ensure they have auxtype `$0640` (to match the originals)
|
||||
|
||||
The last three are tricky, and depend on how you're copying the files.
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ JUMP_TABLE_0F := $400F ; Auxload
|
|||
JUMP_TABLE_EJECT := $4012 ; Eject command
|
||||
JUMP_TABLE_REDRAW_ALL := $4015 ; Redraw all windows (e.g. after a drag) *
|
||||
JUMP_TABLE_DESKTOP_RELAY:= $4018 ; DESKTOP relay call (main>aux)
|
||||
JUMP_TABLE_LOAD_SEG := $401B ; Load dynamic routine
|
||||
JUMP_TABLE_LOAD_OVL := $401B ; Load overlay routine
|
||||
JUMP_TABLE_CLEAR_SEL := $401E ; Clear DeskTop selection *
|
||||
JUMP_TABLE_MLI := $4021 ; ProDOS MLI call (Y=call, X,A=params addr) *
|
||||
JUMP_TABLE_COPY_TO_BUF := $4024 ; Copy to buffer
|
||||
|
|
@ -33,7 +33,7 @@ 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_SEG := $403F ; Restore from dynamic routine
|
||||
JUMP_TABLE_RESTORE_OVL := $403F ; Restore from overlay routine
|
||||
|
||||
;;; ============================================================
|
||||
;;; API Calls (from aux memory)
|
||||
|
|
|
|||
|
|
@ -5539,7 +5539,7 @@ JT_AUXLOAD: jmp DESKTOP_AUXLOAD
|
|||
JT_EJECT: jmp cmd_eject
|
||||
JT_REDRAW_ALL: jmp redraw_windows ; *
|
||||
JT_DESKTOP_RELAY: jmp DESKTOP_RELAY
|
||||
JT_LOAD_SEG: jmp load_dynamic_routine
|
||||
JT_LOAD_OVL: jmp load_dynamic_routine
|
||||
JT_CLEAR_SELECTION: jmp clear_selection ; *
|
||||
JT_MLI_RELAY: jmp MLI_RELAY ; *
|
||||
JT_COPY_TO_BUF: jmp DESKTOP_COPY_TO_BUF
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@ L9052: lda #$00
|
|||
tya
|
||||
pha
|
||||
lda #$07
|
||||
jsr JUMP_TABLE_RESTORE_SEG
|
||||
jsr JUMP_TABLE_RESTORE_OVL
|
||||
jsr JUMP_TABLE_REDRAW_ALL
|
||||
pla
|
||||
tay
|
||||
|
|
@ -226,7 +226,7 @@ L91BC: clc
|
|||
tya
|
||||
pha
|
||||
lda #$07
|
||||
jsr JUMP_TABLE_RESTORE_SEG
|
||||
jsr JUMP_TABLE_RESTORE_OVL
|
||||
jsr JUMP_TABLE_REDRAW_ALL
|
||||
pla
|
||||
tay
|
||||
|
|
@ -394,7 +394,7 @@ L933F: pha
|
|||
cmp #$02
|
||||
bne L934F
|
||||
lda #$07
|
||||
jsr JUMP_TABLE_RESTORE_SEG
|
||||
jsr JUMP_TABLE_RESTORE_OVL
|
||||
jsr JUMP_TABLE_REDRAW_ALL
|
||||
L934F: MGTK_RELAY_CALL MGTK::InitPort, $D239
|
||||
MGTK_RELAY_CALL MGTK::SetPort, $D239
|
||||
|
|
|
|||
|
|
@ -1,5 +1,8 @@
|
|||
# Keyboard Control
|
||||
|
||||
It is possible to execute nearly every function in Apple II DeskTop
|
||||
with the keyboard.
|
||||
|
||||
△ = Open Apple
|
||||
|
||||
▲ = Solid Apple
|
||||
Loading…
Reference in New Issue
Block a user