(* demo_ui.pas —— Pascal 第四层:**最新 UI 接口**(宿主 `ui_*` 图元 + 绘图窗口) demo_ui.pas -- Pascal layer 4: the newest UI interface (host ui_* primitives + draw window) 这一层和第三层(BGI/`uses Graph`)刻意不同。BGI 是"固定分辨率 + 索引色"的老世界, This layer is deliberately different from layer 3 (BGI / uses Graph). BGI is the old world 这一层是**宿主窗口 + 0xAARRGGBB 真彩 + 统一消息队列**。四条关键差别: of fixed resolution + indexed colour; this one is a host window + 0xAARRGGBB true colour + a single message queue. Four key differences: ① **开窗显式**:`ui_win_open(标题, 宽, 高)`,宽高来自 `ui_scr_get_w()/ui_scr_get_h()` 1) Window opening is explicit: ui_win_open(title, w, h); w/h come from ui_scr_get_w()/ui_scr_get_h() (可用绘图区),不是写死的 640x480。 (the usable draw area), not a hardcoded 640x480. ② **屏幕方向要问**:`ui_scr_get_orientation()` 返回 0=竖屏 / 1=横屏 —— 程序据此决定 2) Ask for the screen orientation: ui_scr_get_orientation() returns 0 = portrait / 1 = landscape; the program "面板怎么摆"。这是**开窗前就能问**的(详见 `docs/VML宿主接口.md`)。 uses it to decide the panel layout. This can be asked before the window is opened (see the VML host interface doc). ③ **显式呈现**:图元只是追加进场景,`ui_2d_present()` 才是"这一帧画完了"的帧边界。 3) Explicit present: primitives are only appended to the scene; ui_2d_present() is the frame boundary meaning this frame is done. ④ **输入是消息队列**:`ui_msg_fetch_wait(超时) / ui_msg_get_a() / ui_win_is_closed()` 收 4) Input is a message queue: ui_msg_fetch_wait(timeout) / ui_msg_get_a() / ui_win_is_closed() receive 键盘、触摸、定时器、窗口事件 —— 全部走同一个队列。 keyboard, touch, timer and window events -- all through the same queue. 跑法(桌面 vmlcli): How to run (desktop vmlcli): dotnet scripts/vmlcli/bin/Release/net10.0/vmlcli.dll Examples/pascal/demo_ui.pas \ --screen 480x640 --frames out_frames/ ⚠ **要看画面请用 `--frames 目录`,不要用 `--frame 单个文件`**。原因不在本程序: WARNING: to see images use --frames DIR, not --frame SINGLE-FILE. The reason is not this program: `ui_win_close()`(#521)在宿主侧把**整个场景置空**(`VmlHostRuntime.WinClose` ui_win_close() (#521) clears the whole scene on the host side (VmlHostRuntime.WinClose 的 `_scene = null`),于是程序跑完之后 `--frame` 那一刀已经没有场景可取, sets _scene = null), so once the program has finished there is no scene left for --frame, 只会打一行「没有可导出的帧(场景是空的)」。`--frames` 是**每帧 present 当场拍快照**, it just prints "no frame to export (the scene is empty)". --frames snapshots on each present, 所以照常出图。这是桌面脚手架的行为,不是本程序写错了。 so images still come out. This is desktop-scaffold behaviour, not a mistake in this program. ◆ **有界**(任务要求:按 N 帧或收到键就退出)—— 三条出口都写了: * Bounded (task requirement: exit after N frames or on a key) -- all three exits are written: · 收到**任意按键**(消息类型 1 = KeyDown)立刻退出 . any key press (message type 1 = KeyDown) exits immediately · 或画满 150 帧自动退出(每帧 `ui_msg_fetch_wait(30)` 最多等 30ms ⇒ 约 4.5 秒) . or auto-exit once 150 frames are drawn (each frame ui_msg_fetch_wait(30) waits up to 30ms => about 4.5 s) · 或用户点了标题栏的返回箭头(`ui_win_is_closed() <> 0`) . or the user taps the back arrow in the title bar (ui_win_is_closed() <> 0) 退出前 `ui_win_close()`,程序正常结束、退出码 0。 Before exiting it calls ui_win_close(); the program ends normally with exit code 0. ◆ 三条本前端的写法要求 * Three coding rules for this frontend ① **裸调库函数不写声明**(同目录 `catch.pas` 的约定):`Lib/shared/src/vmlui.c` 1) Call library functions without declaring them (the convention of catch.pas in this directory): Lib/shared/src/vmlui.c 编出来的 `vmlui.vml` 由 `vmltool.config.xml` 挂上来,直接写 `ui_2d_rect(...)` 即可。 is compiled to vmlui.vml, hooked up by vmltool.config.xml; just write ui_2d_rect(...) directly. ② **颜色用 Pascal 的十六进制字面量 `$FF101018`**(`$` 是 Pascal 的数字前缀)。 2) Use Pascal hex literals for colours: $FF101018 ($ is the Pascal number prefix). 文档给的记法是 `0xAARRGGBB`,而它作为 32 位有符号整数**会溢出** —— 写成 The docs write it as 0xAARRGGBB, but as a 32-bit signed integer it overflows; writing 十进制负数当然也行,但**极容易算错**:本文件第一版手算了 11 条,错了 5 条, a decimal negative also works, but is very easy to get wrong: the first version of this file hand-computed 11 values and got 5 wrong, 画出来的颜色只是"差一点点"(比如该 `#2E7D32` 画成了 `#2F7D32`), the colours came out only slightly off (e.g. #2E7D32 drawn as #2F7D32), 肉眼根本看不出,是靠 `--frames` 出图后**逐像素比色**才发现的。 invisible to the eye; it was found only by comparing pixels in the --frames output. ③ **正文里不用数字**。Pascal 的 `Str()`(整数转串)本前端没有,而字符串 `+` 3) No numbers in body text. This frontend has no Pascal Str() (int to string), and string + 又不是拼接(见 `demo_std.pas` 的说明)⇒ **没有现成的"拼一串带数字的话"这条路**。 is not concatenation (see demo_std.pas) => there is no ready way to build a string containing numbers. 所以状态一律用**形状与固定标签**表达(进度条用 `ui_2d_rect` 的宽度、方向用 So state is always expressed with shapes and fixed labels (progress bar via ui_2d_rect width, direction via 两个不同的词)—— 这与同目录 `Examples/fortran/sokoban.f90` 的取舍一致。 two different words) -- the same trade-off as Examples/fortran/sokoban.f90. ⚠ 另外:**Pascal 的两种块注释都不嵌套**(花括号那种与括号星号那种都是), WARNING: also, neither of Pascal's two block comment forms nests (neither the brace form nor the paren-star form), 所以本文件里提到注释符号一律用文字说,不写真符号。 so this file always names comment symbols in words and never writes the real symbols. *) program DemoUi; { `ui_*`(本平台的**宿主 UI 库**:窗口 / 图元 / 文本 / 帧呈现)全部声明在 The ui_* host UI library (window / primitives / text / present) is declared in `Lib/pascal/vml_ui.pas` 里,`uses vml_ui` 把它拉进来 —— 与 `uses Graph` 拉 BGI、 Lib/pascal/vml_ui.pas; `uses vml_ui` pulls it in, same mechanism as `uses Graph` `uses Crt` 拉终端是同一套机制。 for BGI and `uses Crt` for the terminal. ⚠ **这条 `uses` 不是装饰,是必需的**:Pascal 里"零参函数"与"变量"**语法形状完全一样** WARNING: this `uses` is required, not decoration: in Pascal a zero-arg function and a (都不带括号),`w := ui_scr_get_w;` 到底是一次调用还是一个变量,只能靠**声明**分。 variable have exactly the same syntax, so only a *declaration* tells them apart. 裸写成 `ui_scr_get_w` / `ui_2d_present`(不带括号)时,删掉这一行就报「未声明的变量」(实测); A bare ui_scr_get_w / ui_2d_present (no parentheses) reports an undeclared variable without it 带括号的调用不受影响(本文件的 `ui_*` 恰好全带括号)。 (measured); parenthesised calls are unaffected -- every call here is parenthesised. `ui_*` 的实现在 `Lib/shared/vmlui.vml`(由 `Lib/shared/src/vmlui.c` 生成), The implementation lives in Lib/shared/vmlui.vml (generated from Lib/shared/src/vmlui.c); `uses vml_ui` 会经 `AutoLinkUnit` 把它链上。 `uses vml_ui` links it in via AutoLinkUnit. } uses vml_ui; var w, h, ori, frame, maxf, msg, kc, running: integer; bx, by, bw, bh: integer; label1, label2: string; begin { ① 开窗:尺寸传 0 ⇒ **交给宿主用真实可用区**。开窗**之前** `ui_scr_get_w/h` 只能估算,而估算与 } { 1) Open the window: pass size 0 ⇒ **the host uses the real available area**. **Before** the open, } { 实际总有出入(这就是"内容偏上"的根因)⇒ 所以尺寸改在**开窗之后**问(那时才是真实画布)。 } { `ui_scr_get_w/h` can only estimate and the estimate differs from reality (exactly why the content sat high) ⇒ the size is now queried **after** the open, when it is the real canvas. } ui_win_open('Pascal UI demo', 0, 0); { ② 问可用绘图区(**开窗之后**问 —— 这时拿到的是真实画布);拿不到就给个兜底尺寸 } { 2) ask for the usable draw area (**after** the open, when it is the real canvas); if unavailable use a fallback size } w := ui_scr_get_w(); h := ui_scr_get_h(); if w <= 0 then begin w := 360; end; if h <= 0 then begin h := 620; end; { ③ 问屏幕方向:0 = 竖屏,1 = 横屏 } { 3) ask the screen orientation: 0 = portrait, 1 = landscape } ori := ui_scr_get_orientation(); if ori = 1 then begin label1 := 'orientation = LANDSCAPE (1)'; end else begin label1 := 'orientation = PORTRAIT (0)'; end; label2 := 'ui_win_open / ui_2d_rect / ui_2d_circle / ui_2d_line / ui_2d_text / ui_2d_present'; { ④ 方向决定面板怎么摆:横屏把方块放右上,竖屏放右下 } { 4) orientation decides the panel layout: landscape puts the box top-right, portrait bottom-right } bx := 24; by := 24; bw := 140; bh := 100; if ori = 1 then begin bx := w - bw - 24; by := 120; end else begin by := h - bh - 110; end; maxf := 150; frame := 0; running := 1; while running = 1 do begin { ── 每帧重画(保留模式:场景每帧从头追加)────────────────── } { -- redraw every frame (retained mode: the scene is appended from scratch each frame) --- } ui_2d_clear($FF101018); { 深底 } { dark background } { 标题 } { title } ui_2d_text(16, 16, 'Pascal UI demo', $FF9AD8FF, 20, VML_ANCHOR_LEFT); { 浅蓝 } { light blue } ui_2d_text(16, 44, label1, $FFFFD34A, 15, VML_ANCHOR_LEFT); { 黄 } { yellow } ui_2d_text(16, 66, label2, $FF8A9AA8, 11, VML_ANCHOR_LEFT); { 灰 } { grey } { 图元三件套:线 / 矩形 / 圆 } { the primitive trio: line / rect / circle } ui_2d_line(16, 92, w - 16, 92, $FF33506A, 1); { 分隔线 } { separator line } ui_2d_rect(bx, by, bw, bh, $FF2E7D32, 1, 0, 8); { 深绿实心圆角框 } { dark green filled rounded box } ui_2d_rect(bx + 12, by + 12, bw - 24, bh - 24, $FF66BB6A, 0, 2, 0); { 浅绿空心框 } { light green hollow box } ui_2d_circle(w div 2, h div 2, 44, $FFE74C3C, 1, 0); { 红实心圆 } { red filled circle } ui_2d_circle(w div 2, h div 2, 20, $FFF1C40F, 1, 0); { 黄内圆 } { yellow inner circle } { 帧计数进度条(**不写字**:这里没有整数转串,见文件头第 ③ 条) } { frame counter progress bar (no text: there is no int-to-string here, see rule 3 in the file header) } ui_2d_rect(16, h - 62, w - 32, 14, $FF22303C, 1, 0, 3); { 进度条底 } { progress bar background } ui_2d_rect(16, h - 62, (w - 32) * frame div maxf, 14, $FF00C2A8, 1, 0, 3); { 进度条 } { progress bar } ui_2d_text(16, h - 42, 'press any key to exit', $FF8A9AA8, 13, VML_ANCHOR_LEFT); ui_2d_text(w - 16, h - 42, 'ui_2d_present every frame', $FF8A9AA8, 13, VML_ANCHOR_RIGHT); { ── 帧边界 ────────────────────────────────────────────────── } { -- frame boundary --- } ui_2d_present(); frame := frame + 1; { 出口 A:画满 maxf 帧 } { exit A: maxf frames drawn } if frame >= maxf then begin running := 0; end; { 出口 B:收到任意按键(消息类型 1 = KeyDown) } { exit B: any key received (message type 1 = KeyDown) } if running = 1 then begin msg := ui_msg_fetch_wait(30); if msg = 1 then begin kc := ui_msg_get_a(); running := 0; end; end; { 出口 C:用户点了标题栏的返回箭头 } { exit C: the user tapped the back arrow in the title bar } if ui_win_is_closed() <> 0 then begin running := 0; end; end; { 正常收尾:关窗 } { normal finish: close the window } ui_win_close(); end.