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).

Concepts

GrafPort

The port block is reused in several places. It has the following structure:

  .word left           pixels from screen left edge
  .word top            pixels from screen top edge
  .addr addr           screen address $2000
  .word stride         screen stride $80
  .word hoff           pixels scrolled left
  .word voff           pixels scrolled up
  .word width          pixels wide
  .word height         pixels tall

Drawing state can be set to a port (SetPort) and then subsequent operations will occur within the port: they will be clipped to the bounds and the offset will be taken into account. For example, if hoffset is 15 and voffset is 5 then a pixel plotted at 40, 40 will appear at 40 - 15 = 25 pixels from the left edge and 40 - 5 = 35 pixels from the top edge.

Pattern

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

Window Parts

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.

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.

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.
• If target element is title bar then initiate window drag.
• If target element is resize box then initiate window resize.
• Otherwise, it is content area; call FindControl.
• If content part is a scrollbar then initiate a 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 clicked, exit the DA, otherwise ignore.

Window Drag

• Call DragWindow.
• 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.
• Call JUMP_TABLE_REDRAW_ALL.
• Call DESKTOP_REDRAW_ICONS.
• Call UpdateThumb if needed to adjust scroll bar settings. (Details TBD).
• Redraw window.

Window Scroll

Drawing Operations

Commands