# Menus and widget library

The frontend is built by `create_menu_objects_`, using Digital Integration's reusable UI library. Its source paths include `library/ui/object.c`, `setattr.c`, `upicture.c`, `utext.c` and the individual control implementations. The reference initialization creates 636 widgets, including the mission planner, pilot log, help viewer and modem screens.

Every widget occupies 216 bytes in the original. The type determines which fields describe text, slider ranges or picture storage. Widgets form a parent/child tree. Child positions become absolute when assigned; parent rectangles also clip drawing and hit testing. Painting walks from back to front, while pointer selection searches in reverse order for an interactive widget.

## Drawing

The frontend uses indexed pixels at 640 × 480. Bitmap buttons are already painted into the background image; the separate button bitmap supplies the pressed or highlighted state. Text buttons use the menu font's measured advances, a bevel, and an optional drop shadow. Text lists paint the selected row before the glyphs. Slider positions use integer division, with a twelve-pixel minimum handle.

The palette is shared by the screen. Indexes 246 through 252 hold the UI bevel and text colours. Pictures may replace all lower entries or only a range. The preferences screen, for example, supplies entries 168 through 245 and leaves the lower range available for its rendered terrain preview. Menu navigation therefore carries palette state between screens.

The control arrows and logbook medals are loaded from `MENUSCRN` bitmaps into sprite buffers. Their descriptors include explicit dimensions and hotspots. Several descriptors intentionally show fewer rows than their source bitmap. The widgets' field at offset 96 points to these initialized descriptors, not to an image embedded in the executable.

## References and reconstruction

`tools/capture_menus_native.py` runs the original widget creation and painting routines with read-only game files, a deterministic clock, host directory listings and inactive worker threads. It exports the complete tree, attribute lists, callbacks and resource references. Standalone screenshots start from an explicitly cleared palette so each comparison is independent of the preceding screen. They show the initialized widgets before gameplay or pilot data are filled in; the preferences terrain preview is connected separately.

`tools/export_cpp_widgets.py` produces the C++ layout definitions from that tree. It includes resource paths and control definitions, while bitmap and font pixels continue to come from the selected installation. `tools/check_cpp_menus.py` compares the resulting C++ frames with the original pixel output. The layout export is only the frontend definition; navigation, configuration, pilot records and mission selection have their own runtime logic.

## Leaving the game

The Yes button calls `goodbye_sequence_` (`0x403794`) before exiting. This routine loads `MENUSCRN/GOODBYE.LBM`, a 640 × 512 image, into the 640 × 480 menu screen. The bottom 32 rows are cropped, with no resizing. It hides the pointer, fades the menu to black over 50 vertical retraces, switches images, and fades the Apache still in over another 50 retraces. After an 800-tick wait on the 200 Hz clock (four seconds), it fades out over 50 retraces and sets the final palette to black. Each fade level uses the original Q31 palette fader.

The goodbye skip flag is separate from the intro skip flag. Disabling menu animations also leaves the goodbye sequence intact. Ordinary keys and the confirming click do not interrupt it.

`tools/check_cpp_goodbye.py` executes the original routine to record its fade levels, screen downloads and wait, then follows the C++ No/Yes button flow on a private Xvfb display with temporary saves. It compares the still with the original loader's 307,200 RGB pixels and checks the hold, fades and response to ordinary keys. C++ presents the retrace steps at 60 Hz, giving a total duration of 6.5 seconds. Closing the host window remains immediate.