a2d/MGTK.md

# MGTK API

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

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

---

# Graphics Primitives

## Concepts

ca65 syntax is used for primitives: `.byte`, `.word` (interpreted as 16-bit signed integer), `.addr` (16-bit address), `.res N` (N byte buffer)

### Point
```
.word       xcoord
.word       ycoord
```

### Rect
```
.word       x1
.word       y1
.word       x2
.word       y3
```

### Pattern
A simple repeating 8x8 _pattern_ is defined by 8 bytes. All bits of each byte are used.

### MapInfo
Used with GrafPorts to define offsets/clipping, and bitmaps for source data.
```
Point       viewloc
.addr       mapbits         $2000 for the screen, or bitmap bits
.byte       mapwidth        $80, or stride for bitmap
.byte       reserved
Rect        maprect         a.k.a. cliprect
```

### GrafPort
There is always a current GrafPort (or "port" for short) that defines
the destination and pen state of drawing operations.
```
MapInfo     portmap
.res 8      penpattern
.byte       colormask_and
.byte       colormask_or
Point       penloc
.byte       penwidth        horizontal pen thickness
.byte       penheight       vertical pen thickness
.byte       penmode
.byte       textback        text background
.addr       textfont
```

### PolyList
```
.byte       count           number of vertices in this polygon
.byte       last            high bit set if there are more polygons
Point       vertex0
... repeats for each vertex
... repeats for each polygon
```

### Font
```
.byte       fonttype        0=regular, $80=double-width
.byte       lastchar        char code of last character (usually $7F)
.byte       height          pixels (1-16)
.res N      charwidth       pixels, for each char
.res N      row0            bits
.res N      row0right       bits (double-width only)
... repeats for each row
```

## Commands

Includes:

* Initialization
* GrafPort - assign, update, query ports
* Drawing - draw lines; frame, fill, and test rects and polys
* Text - draw and measure text
* Utility - configuration and version

---

# Mouse Graphics

Includes:

## Concepts

### Cursor
```
.res 24     bitmap          2x12 byte bitmap (XOR'd after mask)
.res 24     mask            2x12 byte mask (OR'd with screen)
.byte       hotx            hotspot coords (pixels)
.byte       hoty
```

### Event
```
.byte       kind            event_kind_*
.res 4
```
if `kind` is `event_kind_key_down`:
```
.byte       kind            event_kind_*
.byte       key             (ASCII code; high bit clear)
.byte       modifiers       (0=none, 1=open-apple, 2=solid-apple, 3=both)
.res 2      reserved
```
if `kind` is `event_kind_update:`
```
.byte       kind            event_kind_*
.byte       window_id
.res 3      reserved
```
otherwise:
```
.byte       kind            event_kind_*
.word       mousex
.word       mousey
```

```
event_kind_no_event        := 0    ; No mouse or keypress
event_kind_button_down     := 1    ; Mouse button was depressed
event_kind_button_up       := 2    ; Mouse button was released
event_kind_key_down        := 3    ; Key was pressed
event_kind_drag            := 4    ; Mouse button still down
event_kind_apple_key       := 5    ; Mouse button was depressed, modifier key down
event_kind_update          := 6    ; Window update needed

event_modifier_open_apple  := 1 << 0
event_modifier_solid_apple := 1 << 1
```

### Menu

Menu Bar record:
```
.word       count           Number of menu bar items

.byte       menu_id         Menu identifier
.byte       disabled        Flag
.addr       title           Address of length-prefixed string
.addr       menu            Address of Menu record
.res 6      reserved        Reserved
... repeats for each menu
```

Menu record:
```
.word       count           Number of items in menu

.res  5     reserved        Reserved
.byte       options         bit 0=OA, 1=SA, 2=mark, 5=check, 6=filler, 7=disabled
.byte       mark_char       Custom mark character if mark option set
.byte       char1           ASCII code of shortcut #1 (e.g. uppercase B); or 0
.byte       char2           ASCII code of shortcut #2 (e.g. lowercase b, or same); or 0
.addr       name            Address of length-prefixed string
... repeats for each menu item
```

### Window "winfo"
```
.byte       id
.byte       options         option_*
.addr       title
.byte       hscroll         scroll_option_*
.byte       vscroll         scroll_option_*
.byte       hthumbmax
.byte       hthumbpos
.byte       vthumbmax
.byte       vthumbpos
.byte       status
.byte       reserved
.word       mincontwidth    minimum content size (horizontal)
.word       maxcontwidth    maximum content size (horizontal)
.word       mincontlength   minimum content size (vertical)
.word       maxcontlength   maximum content size (vertical)
GrafPort    windowport      GrafPort record
.addr       nextwinfo       address of next lower window in stack
```

Windows have a _content area_ which has the requested dimensions. Above this is an optional
_title bar_ which in turn has an optional _close box_. Within the content area are an
optional _resize box_ and optional _scroll bars_.

```
option_dialog_box       := 1 << 0
option_go_away_box      := 1 << 1
option_grow_box         := 1 << 2

scroll_option_none      := 0
scroll_option_present   := 1 << 7
scroll_option_thumb     := 1 << 6
scroll_option_active    := 1 << 0
scroll_option_normal    := scroll_option_present | scroll_option_thumb | scroll_option_active
```
## Commands

Includes:

* Initialization
* Cursor Manager - set, show, hide
* Event Manager - get, peek, post
* Menu Manager - configure, enable, disable, select
* Window Manager - open, close, drag, grow, update
* Control Manager - scrollbars

## More

> NOTE: Movable windows must maintain an _offscreen_flag_. If a window is moved so that the
> content area is entirely offscreen then various operations should be skipped because
> the window's box coordinates will not be set correctly.

### Use by DAs

#### Input Loop

* Call `GetEvent`.
* If a key, then check modifiers (Open/Solid Apple) and key code, ignore or take action.
* If a click, call FindWindow.
* If target id not the window id, ignore.
* If target element is desktop or menu then ignore.
* If target element is close box then initiate [window close](#window-close).
* If target element is title bar then initiate [window drag](#window-drag).
* If target element is resize box then initiate [window resize](#window-resize).
* Otherwise, it is content area; call `FindControl`.
* If content part is a scrollbar then initiate a [scroll](#window-scroll).
* Otherwise, handle a content click using custom logic (e.g. hit testing buttons, etc)

#### Window Close

* Call `TrackGoAway`, which enters a modal loop to handle the mouse moving out/in the box.
* Result indicates clicked or canceled. If canceled, return to input loop.
* Call `CloseWindow`

#### Window Drag

* Call `DragWindow`, which enters a modal loop to handle the mouse moving out/in the box.
* Result indicates moved or canceled. If canceled, return to input loop.
* Call `JUMP_TABLE_REDRAW_ALL`.
* If _offscreen flag_ was not set, redraw desktop icons (`DESKTOP_REDRAW_ICONS`).
* Set _offscreen flag_ if window's `top` is greater than or equal to the screen bottom (191), clear otherwise.
* If _offscreen flag_ is not set, redraw window.

#### Window Resize

* Call `GrowWindow`, which enters a modal loop to handle resizing.
* Result indicates changed or canceled. If canceled, return to input loop.
* Call `JUMP_TABLE_REDRAW_ALL`.
* Call `DESKTOP_REDRAW_ICONS`.
* Call `UpdateThumb` if needed to adjust scroll bar settings.
* Redraw window.

#### Window Scroll

* Call `TrackThumb`, which enters a modal loop to handle dragging.
* Redraw window.