KO

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

Fenêtres système sur l'ordinateur (0.5.82)

Une application de formulaires (ou un jeu SDL) exportée pour Linux ou Windows a, sans Tauri :

  • les fenêtres de fichiers du système : FilePicker::open(['multiple' => true, 'filters' => ['Musique' => ['mp3', 'ogg']]]), FilePicker::folder(), FilePicker::open(['folder' => true, 'multiple' => true]) (plusieurs dossiers : zenity et Windows), FilePicker::save(['file_name' => 'liste.fls']). Ce sont des Tasks : la fenêtre est un autre programme (zenity ou kdialog sous Linux, PowerShell sous Windows), l'image continue. Native::supports('open') dit si l'ordinateur en a une (installer zenity sinon).
  • une icône dans la zone de notification : JumPHP\Native\SystemTray::show('Mon appli', $engine->config->path('assets/icon.png'), ['show' => 'Afficher', 'quit' => 'Quitter']), puis poll() à chaque image ('activate' au clic, ou l'id du menu), close(). Windows : NotifyIcon ; Linux : AppIndicator ou Gtk.StatusIcon avec Python 3, sinon zenity (un clic, pas de menu). GNOME n'affiche ces icônes qu'avec son extension AppIndicator. Sous Xfce, MATE, LXDE et LXQt (0.5.84) c'est Gtk.StatusIcon d'abord : un clic ou un double clic sur l'icône donne 'activate' ; si le panneau n'a pas d'ancienne zone de notification et ne l'a pas prise au bout de 3 s (0.5.86), c'est un AppIndicator à la place : l'icône est toujours quelque part. Ailleurs le clic du milieu sur l'AppIndicator donne la première entrée du menu. SystemTray::show($titre, $icone, $menu, ownMenu: true) (0.5.87, Linux avec un panneau StatusNotifierItem : Xfce, KDE, GNOME avec son extension) : l'icône n'a pas de menu à elle ; un clic gauche donne 'activate', un clic droit 'context X Y' (le point cliqué, en pixels de l'écran) et le programme ouvre son propre menu là (le menu du panneau était décalé sur un écran mis à l'échelle).
  • une fenêtre qui naît cachée (0.5.86) : window_hidden: true dans project.yaml ; le programme la montre (SDL_ShowWindow) quand il a quelque chose à y dessiner (pas de fenêtre vide avec sa barre de titre au démarrage).
  • ouvrir une adresse (0.5.88) : Shell::openUrl(), openPath(), reveal() marchent aussi dans un programme SDL (xdg-open sous Linux, open sous macOS, le gestionnaire d'adresses de Windows) ; un textbox multi-lignes se sélectionne à la souris (la ligne sous le pointeur), en lecture seule aussi : Ctrl+C copie.
  • champs et listes (0.5.86) : un textbox d'une ligne montre les sauts de ligne de son texte comme des espaces (ils sortaient de la case) ; la liste ouverte d'un combobox est aussi large que son plus long élément.
  • plusieurs fenêtres SDL (SDL_CreateWindow à côté de celle du moteur) : l'évènement 'window-close' de $engine->input donne l'id de la fenêtre fermée (bouton, Alt+F4, barre des tâches) ; SDL n'envoie 'quit' qu'à la dernière. La fermeture de la fenêtre du moteur quitte, sauf avec $engine->ownWindowClose = true (le programme décide). Exemple : la version bureau de WinZik (apps/winzik/src/Native/ du dépôt duchnoun/winzik).
  • la souris de plusieurs fenêtres (0.5.84) : l'évènement 'mouse-event' de $engine->input donne chaque évènement de la souris dans son ordre ('down' / 'up' / 'move' / 'wheel', le bouton, x, y en pixels de la fenêtre où il a eu lieu) ; avec les évènements 'window' ENTER / LEAVE (l'id de la fenêtre), le programme sait où va chaque clic, même un clic plus court qu'une image (lire l'état de la souris à chaque image en perd).
  • le clic qui donne le focus (0.5.85) : le moteur active SDL_MOUSE_FOCUS_CLICKTHROUGH ; sous X11, SDL jetait un clic arrivé dans les 10 ms suivant la prise de focus, si bien que le premier clic sur une fenêtre venant d'un autre programme était perdu (Xfce).
  • un dialogue = une fenêtre (0.5.83) : JumPHP\Gui\Form::$dialogFillsView = true fait occuper aux dialogues (dialog: true) toute leur vue, sans voile ni marge ; $form->dialogSize($maxW, $maxH) donne la taille qu'il veut, pour dimensionner sa fenêtre (la version bureau de WinZik).