The app’s file types and URL schemes registered without a setup (developer builds); a web
browser’s default (default_browser_status / default_browser_request).
Host-driven boundary shared by browser workers, the native Android adapter and the iOS host
(apple_ios.rs: only the host part there, docs/APPLE.md AP5).
The streaming form of write_file: the bytes go into a sibling of the target, commit puts
it in place in one step (readers see the old file or all of the new one); dropped without
commit, the sibling is removed and the target is unchanged. Checked and routed like
write_file when it is created. OS paths: an exclusive “NAME.tmp-PID-SEQ-TIME” beside the
file, fsync and rename (Linux keeps the old file’s access bits; the browser: in memory until
commit). Mounts: a “NAME.tmp-..” file of the mount, renamed by the provider (one without
rename gets the whole file written); a provider whose rename cannot replace a file
(atomic_rename() == false, content://) gets the bytes written in place at commit.
Nonblocking exclusive sidecar lock; drop releases it. All cooperating writers must lock
the same path before checking and replacing data. OS files: across processes (Windows: an
exclusive handle, Linux: flock); a mount without OS files: inside this process.
no input method (Windows: the window’s input context is taken away; X11: no IBus; Wayland:
the password purpose); ui’s TB_PASSWORD boxes set it themselves
the library’s version, “MAJOR.MINOR.PATCH” (the root Cargo.toml; docs/VERSIONING.md says what a
change of each part promises). Not the app’s version: that is rt::app_version!().
the window is drawn inside its owner (a Wayland subsurface): win_get_rect / win_set_rect /
E_WINPOS use positions relative to the owner’s surface origin (px), the owner carries it
with WST_TILED: which edges touch the tiling (EDGE_* << WST_TILED_SHIFT; Wayland’s
xdg_toplevel tiled_* states, X11 the edges of a one-direction maximize); the UI keeps its
resize band off them, as from a maximized window
Android: the runtime ended (ui.quit): the activity goes and its process with it, a new start
needs a new runtime; iOS: the process ends (UIKit’s loop never returns). Elsewhere nothing:
there the main loop ends the program
Android: while on, the back key reaches the app as Esc (a page of the app goes back, a popup
closes; UIC_ESCAPE when nothing took it) instead of ending the activity. Elsewhere nothing:
there Esc is a key of its own
Validate a multi-format text clipboard before replacing the previous contents.
Formats must be distinct TEXT/HTML/RTF/DOCX; text and HTML are NUL-free UTF-8.
the processor name from CPUID 0x80000002..4 (macOS, iOS: sysctl machdep.cpu.brand_string,
“Apple M2”, on an Intel Mac Intel’s name; under Rosetta 2 the Mac’s own chip), blanks trimmed cpu_brand
(E3) the nearest of the first shapes (CUR_ARROW .. CUR_NONE) to a shape of CUR_X0 ..
CUR_X_END, for the platforms and cursor themes without it; other shapes unchanged
what drag_query makes of the hook’s answer (accepted types t, effects e) to a drag offering
types with the effects allowed (0: not said, every effect) and the modifier keys mods -> (accepted
types, the effect, every effect taken); (0, 0, 0) = refused (no kind or no effect in common).
Files are never moved. For the OS layers and headless tests (ui’s dragover expect)
the effect of a drop: the modifier keys choose (Ctrl copy, Shift move, Ctrl+Shift link),
else the first of copy / move / link that allowed has (0: none)
(OS layers) what platform window pw takes at (x, y) px of a drag offering types with the
effects allowed (0: the source does not say, every effect) -> (accepted types, the effect);
(0, 0) = refused
(OS layers) drag_query and every DE_* effect the target there takes of the allowed ones
(Wayland’s wl_data_offer.set_actions) -> (accepted types, the effect, the effects); (0, 0, 0)
= refused
drag data out of the app (call while the left button is held) -> started; E_DRAG_END
(data = the effect, 0 = cancelled or refused) follows. Only the standard kinds leave
the app.
drop_allowed() -> the DE_* effects the source of the drop drop_data_take took last allows, as
the platform gave them with the drop (drop_set_allowed: the same the drag said in E_DRAG over
the window); 0: the platform does not say (the browser, Android). Read it right after
drop_data_take
drop_finish(serial, effect) -> answered: the source of drop serial (drop_waiting) learns how
the drop ended: the DE_* effect it was taken with, 0 = not taken. false: that drop does not
wait (answered already, or a newer drop replaced it). Windows: EndOperation(S_OK, effect),
not taken EndOperation(E_ABORT, DROPEFFECT_NONE); X11: XdndFinished with “accepted” and the
effect’s action; Wayland: taken wl_data_offer.finish (the action stays the one negotiated
before the drop), not taken the offer destroyed without finish
drop_hold(on): (the UI, at its start) the program answers drops itself. On, the OS layers keep
a drop’s answer to its source open after E_DROP where the platform allows a later answer, until
drop_finish: Windows when the source’s data object offers IDataObjectAsyncCapability in async
mode (StartOperation in IDropTarget::Drop, EndOperation later), X11 (XdndFinished), Wayland
(wl_data_offer.finish); everywhere else, and on Windows for every other source, the answer went
at the drop (drop_waiting says 0). Off (the default): every drop is answered at once, as before
(OS layers) the DE_* effects the source of the pending drop allows, as the platform gives them
with the drop: Windows IDropTarget::Drop’s pdwEffect, X11 the source’s XdndActionList with the
action of its last XdndPosition (every effect without a list), Wayland the offer’s
source_actions, macOS the drag’s operation mask. Not called (the browser, Android): 0
(OS layers) the lines of a URL list (text/uri-list, text/x-moz-url, UniformResourceLocator):
‘#’ lines skipped, every other line one URL; local files are left to drop_uri_list -> URLs
added (also used for the URL a browser drags)
drop_waiting() -> the serial of the last drop whose answer to its source waits for drop_finish;
0: none (it was answered at the drop, or no drop came). Read it right after drop_data_take
(E8) the files the last system file dialog with FD_MULTI chose (its first is also in
file_dialog’s path; Ctrl / Shift in the dialog choose more); one entry after a dialog that
chose one file, empty after a cancelled one. Windows and Linux’s portal choose several, the
other systems’ dialogs one (docs/GUIDE.md section 7)
Some(0) only for a missing path, Some(1/2) for file/directory, None for other errors. A
folder mount answers for its OS file; other mounts have only their kind (0 for missing and
for errors alike).
A host’s raw finger, in px of its window (Event::win as for every pointer event): this is all a
platform does for touch; pan, fling, tap, long press and what takes the finger are decided in
ui/touch.rs. Every finger goes through here, in the order they happen; a finger that goes away
without an Up gets a Cancel. The browser and Android, whose windows live in one surface, come
through jfgui_finger instead. -> false when the event was dropped
the Event of a raw finger: E_DOWN / E_MOVE / E_UP with PTR_TOUCH in its data. id: the host’s
number of this finger while it is down (a second one has another); age_ms: how old the sample
is now (the velocity needs it; 0 when the host does not know)
Committed text of any length: commits of at most 4096 bytes, split between characters ->
the bytes queued (fewer: the commit queue or the event ring is full, the rest can follow
once the app took these).
(E4) the app draws the composition (ime_preedit) at its caret itself: Windows hides the
input method’s own composition window (its candidates stay; WM_IME_SETCONTEXT without
ISC_SHOWUICOMPOSITIONWINDOW, sent again to the window with the keyboard on a change). IBus
and Wayland’s text input have no window of their own for it: nothing changes there
(E4) the purpose of the text being typed (IP_*): Windows takes the input method away for
IP_PASSWORD and gives it back for the others (also when a window gets the keyboard); X11 keeps
the keys of an IP_PASSWORD field from IBus; Wayland’s text input gets it as its content
purpose (again when it changes while enabled); elsewhere it is only kept (ime_purpose_of).
ui’s TB_PASSWORD boxes set IP_PASSWORD themselves while they have the keyboard
a POSIX locale name or a BCP 47 tag as a BCP 47 tag: language lower case, a script title
case, a region upper case (“zh_hant_tw” -> “zh-Hant-TW”); None for “C” / “POSIX” / empty
write the lines to path (rotated at max_bytes, keep older files path.1 .. path.keep);
None stops -> false when the file cannot be opened, or when its bytes would reach the
provider only at the end (a mount without streams or OS files: nothing of the last segment
or a crash line would arrive before the log stops)
one image on one PDF 1.4 page: objects 1 Catalog, 2 Pages, 3 Page, 4 Contents, 5 Image
(/DeviceRGB 8 bit /FlateDecode, composited over white – with PJF_SMASK and a straight
source: straight colours), 6 Info, [7 /SMask alpha]; classic xref pdf_write_image
The name under which a file the user chose stays reachable after a restart, for a list of
recent files or a session (ui.recent_add keeps this one). A document of Flatpak’s
documents portal ($XDG_RUNTIME_DIR/doc/ID/NAME) is asked for its lasting form
(Documents.Add, persistent; linux_docs.rs): <mount>/<ID>/<NAME> of the portal’s answer.
Where the portal reaches the real file that is a lasting document of it; for a document
of its own mount the portal answers that document’s own ID, so inside the sandbox the name
stays as the dialog gave it (the portal’s file dialog makes lasting documents, “Open with”
session ones). Every other name comes back unchanged: Android keeps the grant of a
content:// document and the browser the handle of a /handles/ file when the user
chooses it, and OS paths need nothing. The name must be readable under the app’s
permissions.
show dirty rectangles (None = everything) of the main window’s framebuffer; its pixels
outside them must be what the last present showed (the backends keep whole frames up to
date from it)
(frames handed to win_present, microseconds spent in the platform’s present paths) since
the start, all windows together: win_present itself plus the work it defers (X11: a
segment that frees up, Wayland: the frame callback, the browser and Android: the
composition and the hand-over to the host). For measurements (linuxtest –test pbench).
where a window the user moves may be (x, y; w its width; screen the area’s size; dpi for the
margin): the title bar stays on the screen, at least 48 DIP of the window at each side
n pixels of src (B, G, R, A) -> n * 3 bytes of dst (R, G, B; PRW_BGR: B, G, R). Straight:
c * a / 255 + 255 - a (rounded); PRW_PREMUL: c + 255 - a; PRW_COPY / PRW_OPAQUE: c
[print_row_white]
WebAssembly’s compiler-managed value/call stacks satisfy their platform ABI (Apple Silicon: the
system starts every thread; Intel Macs read rsp as Windows and Linux do).
a title bar action as GNOME names it (GDesktopTitlebarAction): toggle-maximize (also
-horizontally / -vertically, which xdg-shell can not do: GTK treats them alike), minimize,
lower, menu, none; toggle-shade is none (no compositor shades client-side windows)
a button layout in GNOME’s button-layout syntax (GTK’s gtk-decoration-layout): the left
side, ‘:’, the right side, names separated by ‘,’. close, minimize and maximize are kept,
other names (appmenu, icon, menu, spacer) and repeats skipped; without ‘:’ everything is
the left side (as GTK reads it)
(ui touch.rs) a text field got the focus through a finger (show) or lost it: the on-screen keyboard
of window w. Windows: InputPane; Wayland: text-input follows the focus by itself (the compositor’s
keyboard); elsewhere the host’s job (Android, the browser) or nothing there is to ask (X11)
(ui touch.rs) the host’s main pointer is a finger at the start (Android, iOS; a phone’s browser:
pointer: coarse; a Windows tablet in slate posture): no scroll bars from the first frame on; the
next pointer event decides again
(ui touch.rs) a finger’s gesture reached a widget (a tap, a drag), or it did not (a scroll):
Android and iOS ask after the finger lifted whether the keyboard has to follow
move a file or folder into the trash (Windows: the recycle bin; Linux: the freedesktop
trash) -> false: it stays where it was, never deleted for good (trash.rs). Counts as
writing the path; a vfs name needs a folder mount.
Write an exclusively created sibling, flush it, then replace path (a mount: its own way of
replacing a file; missing folders are created). [plat_file_write]