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

12 KiB

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.

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

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

/**
 * @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

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