Andrew Kesterson
9151438fad
Group K, and the first verbs to reach the akgl_ui subsystem 0.9.0 brought in: MENU and GETMENU and RMENU, DIALOG, HUD and UISTYLE. A program that wanted a title screen had to draw one out of CHAR and GETKEY, which is what both breakout tutorials make a reader do. The interesting part is the impedance mismatch. libakgl's UI is immediate mode -- widgets are re-declared inside a frame bracket every frame and clay borrows their text until the bracket closes -- and a BASIC program says MENU 1, "START" on line 100 and expects it up on line 900, several hundred frames later. So src/ui_akgl.c is retained on this side and immediate on that one: the record's entry points are setters that copy into akbasic_AkglUi, and akbasic_ui_akgl_render() replays the whole set once a frame from the host's pump. No BASIC string, which lives in the per-line value pool, is ever what clay is handed. The shapes are borrowed rather than invented. MENU retires the way SOLID does -- no entries retires one, no arguments retire them all. GETMENU holds the step loop the way GETKEY does, so parking is not blocking: the step still returns, the host keeps its frame rate, and the sprite, audio and collision services keep running underneath because they run before the blocking checks. RMENU(n,1) reads and clears the way BUMP() does. Withdrawing the device or retiring the menu releases a holding GETMENU with 0 rather than wedging the script, which is akbasic_input_service()'s rule for a withdrawn keyboard. One thing a program has to know, and docs/19-user-interface.md says it twice: a menu that is up owns the cursor keys and Return. It has to, and retiring it gives them back -- forget the MENU n before an INPUT and the INPUT never sees the Return that ends it. akbasic_runtime_set_ui() is its own function rather than a fifth argument to akbasic_runtime_set_devices(), whose signature has twenty-eight call sites in tests and documentation that are about something else. deps/libakgl is not touched. akgl_UiAnchor has the four corners and dead centre, so HUD offers exactly those five; TODO.md records what a top-centre and bottom-centre would cost upstream, along with the three other things this deliberately leaves out. No new error code either -- DEVICE, BOUNDS, SYNTAX and TYPE cover the group, and 520 stays free. tools/screenshot.c had to learn that "needs a font" and "draws the text grid" are two questions. They were one, and a UI figure came out black: the text layer owns every pixel of the rows it covers and painted over the widgets. The new ui=1 fence attribute asks for the first without the second; MAINTENANCE.md documents it. 112/112 in both configurations, 112/112 under ASan and UBSan, coverage 94.1% against the 90% gate with src/runtime_ui.c at 99% of lines and 100% of functions, doxygen clean, and the four new figures byte-identical on a re-render. TODO.md section 8's gate table was stale on several counts besides these and is refreshed with measured numbers. Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
8.1 KiB
19. Menus and dialogs
Everything in this chapter needs the SDL build and a UI device. Without one each verb refuses by name:
10 MENU 1, "START", "QUIT"
? 10 : RUNTIME ERROR MENU needs a UI device and this runtime has none
Every picture in this chapter is generated by running the listing above it; see
MAINTENANCE.md if you are editing one.
Three widgets, and no fourth
A menu the player picks from, a panel that says something, and a line of text pinned to
a corner. That is the whole set, and it is the set because it is the set
libakgl supplies — these verbs are a thin skin over
akgl_ui_menu, akgl_ui_dialog and akgl_ui_label, and they are deliberately not a
window toolkit. What is not here, at the end, says what to do when you want more.
MENU
10 UISTYLE 1, 8, 2
20 MENU 1, "START", "OPTIONS", "QUIT"
MENU n, item$ [, item$ ...] puts menu n on screen with those entries. n runs 1 to
4, so a pause menu can sit over a title menu, and there are at most 16 entries — that is
libakgl's own ceiling and not a number invented here.
The player moves the highlight with the cursor keys or a D-pad and confirms with Return or a gamepad's south button. The mouse works too: moving onto a row highlights it and clicking one confirms it. A pointer sitting still claims nothing, so a mouse parked over the list does not fight the keyboard for the highlight.
Defining a menu resets its highlight to the first entry and forgets any unread choice. The entries have just changed meaning; an index into the old list is not worth carrying across, and a stale choice of an entry that no longer exists is worse.
MENU n with nothing after it retires that menu. MENU on its own retires all four —
the same convention SOLID uses, where no rectangle retires one and no arguments retire
them all.
GETMENU
10 MENU 1, "START", "OPTIONS", "QUIT"
20 GETMENU 1, C%
30 ON C% GOTO 500, 600, 900
GETMENU n, var parks the program until somebody chooses, then puts the entry's number
in var — 1 for the first — and carries on. The variable has to be a numeric one with a
sigil, C% or C!; a bare C is a label in this dialect and cannot be assigned to at
all, which is the same rule GETKEY keeps.
Parking is not blocking. The interpreter never stops returning to its host: while a
GETMENU is unanswered every step comes straight back without advancing the program, so
the frame rate holds, sprites keep moving, PLAY keeps draining its queue, and a game
that embeds the interpreter stays in control of its own loop. What stops is the program,
which is the part you asked for.
Two things end the wait without a choice, and both assign 0 rather than leaving the program parked forever: retiring the menu, and the host taking the UI device away. A script waiting on something that no longer exists is worse than a script told nothing happened.
RMENU
100 REM the same menu, without parking on it
110 IF RMENU(1,1) THEN C% = RMENU(1,0) : GOSUB 800
120 GOSUB 900 : REM move everything else
130 GOTO 110
RMENU(n, 0) is the entry currently highlighted. RMENU(n, 1) is -1 once the menu has
been confirmed and 0 otherwise, and reading it clears it — exactly the contract
BUMP() carries, and for the same reason: without it a program that polls in a loop sees
the same choice forever.
Reading the highlight does not clear anything. Only field 1 consumes.
This is what a game with a loop of its own wants. GETMENU is what a title screen wants.
DIALOG
10 UISTYLE 1, 8, 2
20 DIALOG "IT IS PITCH BLACK."
A panel across the bottom of the screen with wrapped text on it. DIALOG text$ puts it
up; DIALOG on its own takes it down.
There is no dismiss key and no return value. libakgl's dialog has neither — a panel
is up because the frame declares it — so showing and hiding is the program's business
and DIALOG with no argument is the dismissal. The usual shape is a GETKEY between
the two:
10 DIALOG "YOU FOUND A KEY."
20 GETKEY K$
30 DIALOG
The text wraps but does not scroll or page. A message longer than the panel is clipped by it, visibly, which is deliberate on libakgl's side: a clipped line is a bug you can see.
HUD
10 UISTYLE 1, 8, 2
20 HUD 1, 0, "LIVES 3"
30 HUD 2, 1, "SCORE 00120"
40 HUD 3, 4, "PAUSED"
HUD n, anchor, text$ pins a line of text somewhere on the screen. n is a slot, 1 to
8, and the anchor is one of five places:
| Anchor | Where |
|---|---|
| 0 | Top left |
| 1 | Top right |
| 2 | Bottom left |
| 3 | Bottom right |
| 4 | Centre |
Five, and the numbering is not the reading order, because these are libakgl's five
akgl_UiAnchor values and its numbering. There is no top-centre or bottom-centre.
A title bar is two corners or the middle.
A slot keeps its text until something replaces or retires it, so a score display is one
HUD per change rather than one per frame. HUD n retires slot n and HUD retires
all eight.
UISTYLE
10 UISTYLE 3, 7, 2, 14, 8
20 MENU 1, "ONE", "TWO"
30 HUD 1, 0, "STYLED"
UISTYLE fill, edge, ink [, padding [, radius]] sets the one look every widget draws
with. The three colours are ordinary palette indices, 1 to 16, the same ones COLOR
takes. padding is the gap in pixels between a panel's edge and its text, and between a
HUD label and the screen edge it hugs; radius rounds the corners, and 0 is square.
Padding defaults to 8 and radius to 0.
UISTYLE with no arguments goes back to libakgl's own default, a dark textbox with
parchment ink. It goes back to the library's default rather than to a copy of it, so
"never styled" and "styled back" stay the same thing.
There is one style, shared. Per-widget looks are not implemented — see below.
Who owns the keyboard
A menu that is up owns the cursor keys and Return. It has to: those are how a menu is
driven, and something has to have them. While at least one menu has entries, Up, Down and
Return go to it and never reach GET, GETKEY or the line editor.
Everything else still gets through — letters, Escape, function keys, the gamepad buttons a menu does not use. And retiring the menu gives the keys straight back:
10 MENU 1, "YES", "NO"
20 GETMENU 1, C%
30 MENU 1 : REM now INPUT can have Return again
40 INPUT "NAME"; N$
Forget line 30 and the INPUT on line 40 will never see the Return that ends it. That is
the one way these verbs can surprise a program, so it is worth the line.
What is not here
The rest of clay. libakgl builds its widgets on a full immediate-mode layout engine — containers, flexible sizing, scrolling regions, images inside panels, custom elements, hit-testing any element — and none of that is reachable from BASIC. A verb per clay concept would be a second language inside this one.
Specifically absent, and each on purpose:
- Per-widget styles. One
UISTYLE, shared by everything. - Scrolling. Neither the dialog nor the menu scrolls; 16 entries is the menu's limit and a longer one wants sub-screens.
- Top-centre and bottom-centre HUD anchors, because
akgl_UiAnchorhas neither. - Mouse position, hover state, or clicks on anything but a menu row. A program cannot ask where the pointer is.
- Any way to dismiss a dialog from inside it.
A game that needs those is writing C against akgl/ui.h, which is the route libakgl
documents for exactly this case, and it can do that in the same window this interpreter
is drawing into — Chapter 10 is how the two meet.
One cost worth knowing about: libakgl re-rasterizes every line of widget text every
frame. A HUD that changes once a level is free; one rebuilt every frame is the
expensive case, and a program that has one should say so with TI# before blaming the
interpreter.