winzik/docs/gui.md
David Nurdin 36a354c7c6 docs/gui.md: FilePicker in the browser
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
2026-11-06 15:43:46 +01:00

200 lines
12 KiB
Markdown

# Graphic apps in PHP (JumPHP\Gui): forms without HTML
A **graphic app** is a JumPHP program whose windows are **forms**: buttons, text boxes, lists, drop-down lists, check
boxes, sliders, pictures, videos, laid out in rows, columns and a responsive grid. They are drawn by the engine (SDL),
so the same app runs, unchanged, on Linux, Windows, macOS, in the browser, and as an Android / iOS app. No HTML, no CSS.
The forms are made in the **visual editor of the JumPHP IDE** (open a `forms/*.form.yaml` file: Design view): drop
widgets, move them, set them in the inspector, and **double click a widget to write its event** in the code behind,
as in the visual tools of old.
```bash
bin/jumphp gui:new contacts "Contacts" # a desktop app (apps/contacts, from skeleton-gui/)
bin/jumphp gui:new notes "Notes" --mobile # a phone app (portrait window, installable)
bin/jumphp install contacts
bin/jumphp run contacts # the window
bin/jumphp test contacts # phpunit (game tests) + the smoke test
bin/jumphp shot contacts # var/screenshots/shot.png
bin/jumphp build contacts # the browser version (dist/web)
bin/jumphp export:standalone contacts --linux --windows # executables
bin/jumphp android contacts / bin/jumphp apple contacts # phone apps (docs/android.md, docs/apple.md)
```
## An app
```
apps/contacts/
config/project.yaml kind: gui, view: window (the view is the window: forms lay themselves out in it), touch: false
forms/MainForm.form.yaml the window: its widgets (written by the visual editor; plain YAML by hand too)
src/Form/MainForm.php the code behind it: a class extending JumPHP\Gui\Form (a scene)
assets/fonts/ui.ttf the text font (Lato, OFL; ui-bold.ttf for bold): replace them to change the look
assets/images/ pictures for Image widgets and buttons
tests/MainFormTest.php tests that use the window (GameTestCase)
```
### The form file
```yaml
form:
title: Contacts # the window's title
theme: light # or dark; accent: '#3b6ef5'; fontSize, radius, controlHeight, padding (dp); zoom
layout: column # the window's own layout, gap, padding, items, justify, scroll (default true)
children:
- {type: label, id: heading, text: Contacts, style: title}
- type: row
children:
- {type: textbox, id: name, placeholder: Name, grow: 1, events: {submit: onNameSubmit}}
- {type: button, id: add, text: Add, style: primary, default: true, events: {click: onAddClick}}
- {type: listbox, id: people, height: fill, events: {change: onPeopleChange}}
```
### The code behind
```php
/**
* @property TextBox $name (the visual editor keeps these lines in step with the widgets' ids)
* @property Button $add
* @property ListBox $people
*/
final class MainForm extends Form
{
protected function loaded(array $params = []): void // the widgets are made (each time the form is shown)
{
$this->people->items = $this->engine->storage->readJson('people.json', []);
}
public function onAddClick(Button $sender): void
{
$this->people->addItem($this->name->text);
$this->name->text = '';
}
}
```
Widgets by id: `$this->add`, `$this->widget('add')`. Properties are read and written as fields
(`$this->add->enabled = false`); a change lays the form out again. Widgets made in code:
`$this->root->add(new Button(['id' => 'more', 'text' => 'More', 'events' => ['click' => 'onMoreClick']]))`, or
`$button->on('click', fn (Button $b) => ...)`.
Other windows: `$this->scenes()->switchTo(OtherForm::class)`. A dialog over the window: a form with `dialog: true`
(and `width`) pushed with `$this->scenes()->push(AskForm::class)`, closed with `$this->close($result)`; the window under
it gets `resume($result)`. Each frame: `tick(float $dt)`. Everything of the engine is there: `$this->engine->storage`,
`http()`, `tasks()`, `sound()`, timers (AGENTS.md).
## Layout: rows, columns, a grid, spacers
Sizes are **dp** (density-independent pixels): a button is as big on a HiDPI screen or a phone as on a plain screen.
| Container | Lays out its children |
|---|---|
| `column` (default) | one under the other |
| `row` | side by side, centred vertically; `wrap: true`: on several lines when the row is full |
| `grid` | in 12 columns (`columns`); each child takes `span` of them, **per screen width** |
| `stack` | on top of each other (a text over a picture) |
| `panel` | a column with a frame and a `title` |
Container settings: `gap` (between children), `padding`, `items` (start / center / end / stretch: across),
`justify` (start / center / end / between / around: along), `background`, `border`, `scroll` (a long content scrolls:
drag it, its bar or the mouse wheel).
Child settings: `width` / `height` = a number (dp), `auto` (what its content needs) or `fill` (all the room);
`grow` (shares the free room of a row or column: `grow: 1` and `grow: 2` = a third and two thirds); `align` (itself,
across); `minWidth`, `minHeight`; `visible`, `enabled`, `tooltip`.
A **spacer** without `size` takes the free room: one before a button pushes it to the end of a row, one on each side
centres it. With `size: 24` it is a fixed gap.
**Responsive**: the screen width in dp gives a breakpoint, `xs` (< 600, phones), `sm` (< 900, tablets), `md`
(< 1200), `lg`. In a grid, `span: {xs: 12, md: 6}` = the whole width on a phone, half from 900 dp; `hide: [xs]` hides a
widget on phones. The visual editor shows each width (desktop window, laptop, tablet, iPhone, Android; drag the desktop
window's edge).
## Widgets
| Type | Properties | Events (the first: double click) |
|---|---|---|
| label | text, style (title / subtitle / muted / small), size, bold, color, textAlign, wrap | click |
| button | text, style (default / primary / danger / flat), image, default (Return), cancel (Escape) | click |
| textbox | text, placeholder, password, multiline, rows, maxLength, readonly | change (string $text), submit, click |
| checkbox | text, checked | change (bool $checked), click |
| radio | text, checked, group (exclusive in the group, default the container) | change (bool $checked), click |
| combobox | items, selected, placeholder; `value()` | change (int $index, string $item), click |
| listbox | items, selected; `value()`, `addItem()`, `removeItem()`, `select()` | change (int, string), activate (double click / Return), click |
| slider | value, min, max, step | change (float $value) |
| progressbar | value, max, showText | click |
| image | src (assets/... or any file: `load($path)`), fit (contain / cover / fill / none) | click |
| video | src (a film of assets/videos/, or a folder of frames), fps, audio, autoplay, loop, controls; `play()`, `pause()`, `stop()`, `seek()` | end, click |
| spacer | size | |
| separator | | |
| column, row, grid, stack, panel | see Layout | click |
A widget of the app: a class extending `JumPHP\Gui\Widget` (`content()` = its size, `render()`), used with
`class: App\Gui\Gauge` in the form file.
**Video**: put the film in `assets/videos/` (`intro.mp4`, `.webm`, `.mov`, `.mkv`, `.avi`) and give it as `src:
assets/videos/intro.mp4`. SDL decodes no video stream, so `bin/jumphp` cuts it into pictures + its sound
(`assets/videos/intro/00001.jpg...`, `audio.ogg`; ffmpeg, in Docker) at the widget's `fps` before `run`, `test`, `shot`,
the builds and the exports, again only when the film changes; the packages carry the pictures, not the film. It then plays
the same on a PC, a Mac, a phone and the web. Commit the `assets/videos/intro/` folder too: the JumPHP playground and
the web IDE do not cut films. `bin/jumphp video contacts ~/film.mp4` does it by hand for a film from elsewhere.
## Keyboard, mouse, touch
Click / tap, double click, drag (sliders, lists, scrolled areas: a finger scrolls them), Tab / Shift+Tab between the
fields, Return clicks the `default: true` button (or submits a text box), Escape the `cancel: true` one (or closes a
dialog), arrows in lists / drop-down lists / sliders, held keys repeat, Ctrl+C / Ctrl+V in text boxes (where the target
has a clipboard). On phones the system keyboard opens with a text box.
The mouse wheel (and two fingers on a touchpad) scrolls what is under the pointer: a list, an open drop-down list, else
the scrolled area around it. Text comes from the system's text input: the keyboard's layout, dead keys (`^` then `e` = `ê`)
and input methods (Chinese, Japanese, Korean...: what they compose is shown underlined at the cursor, their window
opens under it). Both need the desktop image and the browser engine built with `docker/ext/php-sdl-events.patch`
(`bin/jumphp setup`, `bin/jumphp engine:build` or a newer `engine:download`): with older ones there is no wheel and the characters come from the
key codes.
## Tests
```php
final class MainFormTest extends GameTestCase
{
public function testAddingAName(): void
{
$this->game->start(MainForm::class);
$form = $this->game->scene();
$form->click($form->widget('name')); // focus
$form->type("Ada\n"); // \n = Return, \t = Tab
$form->click($form->widget('add'));
self::assertSame(['Ada'], $form->widget('people')->props['items']);
}
}
```
`click($widget, $double)`, `clickAt($x, $y)`, `type($text)`, `key(Pointer::DOWN)`. A form also lays out without
SDL (`new MainForm()`, `build($definition)`, `layoutTo($w, $h)`): plain PHPUnit tests of a layout.
## Text fields: selection, words, clipboard, right click
A `textbox` works like the system's: Shift + arrows / Home / End select, Ctrl + arrows jump by words (Ctrl + Shift: select words), Ctrl + Backspace / Ctrl + Delete delete
the word before / after the cursor, Ctrl + A selects everything, Ctrl + C / X / V copy, cut, paste (Shift + Delete cuts), a double click selects the word, a
drag selects, and a **right click** opens a small menu (Cut, Copy, Paste, Select all). A password is never copied. Typing replaces the selection.
The clipboard is the system's: on Linux it uses `wl-copy` / `wl-paste` or `xclip` (or `xsel`) (they are in the Docker runtime image of `bin/jumphp run`; an
exported Linux executable needs one of them installed), `pbcopy` / `pbpaste` on macOS, PowerShell on Windows, the browser's clipboard on the web.
A widget of your own with a context menu uses the trait `JumPHP\Gui\HasContextMenu` (rows: `menuItems()`, what they do: `runMenu()`).
## The interface's size follows the screen
On a HiDPI screen (a density above 1) the forms scale by themselves; on X11 and Windows, which do not report one, the scale of the desktop's own setting is used
(`Xft.dpi`, `GDK_SCALE`), or `JUMPHP_GUI_SCALE=1.5`. With a desktop that stretches a smaller picture to the screen (xrandr `--scale`, bilinear), every
text is blurred whatever the program: use the screen's own resolution and the DPI setting instead (Xft.dpi 144 for 150 %): the forms then draw at the real pixels.
## Graphics card in Docker (`bin/jumphp run`)
The runtime image has Mesa 25 (bookworm-backports) and the Vulkan drivers, and the host's `/dev/dri` is passed. A recent AMD GPU (gfx1150 and above, e.g. Strix Halo)
is unknown to the image's LLVM: `bin/jumphp run` then sets `MESA_LOADER_DRIVER_OVERRIDE=zink` (OpenGL over Vulkan) so that the GPU draws, not the CPU (a big
window lagged). `JUMPHP_MESA_DRIVER=<driver>` (also in `.env`) forces another driver: `radeonsi`, `iris`, `llvmpipe` (the CPU)...
## Choisir un fichier du visiteur dans le navigateur
`JumPHP\Native\FilePicker::open()` marche dans le navigateur (`Native::supports('open')`) : appelé depuis un clic, il ouvre le sélecteur de fichier du système,
écrit le fichier choisi dans la mémoire du moteur (`/tmp/jumphp-picked/<nom>`) et rend ce chemin ; lisez-le, gardez ce qu'il faut, supprimez-le. Dossier et
« enregistrer sous » : pas dans le navigateur. Exemple : le choix de la clé SSH de `jumphpsql`. Une application (`kind: gui`) démarre sans l'écran « click / tap to play ».