class Editor

Whether this window's menu is currently exported to a global menu.

Registers a face for glyph lookup; returns its id, or nil on failure. Idempotent per (path, pixelSize). System clipboard. Empty when headless.

Whether the main window is still open — false once the user has closed it or requestClose() was called.

False while minimized/occluded. The frame loop gates continuous (animation-driven) redraw work on this, since Yoga/cull-rect visibility has no idea the whole window is off-screen.

Which registrar name this panel owns, or empty.

How many rows the imported menu has. See menuImportItem(_:).

Changes whenever the imported menu does.

How many notifications are live. See notification(_:).

Whether this process is serving notifications.

See Engine::notificationsNextExpiryMs.

Changes whenever the set of notifications or any of their contents does.

Who names GPU resources for the frames this editor produces.

Itself, unless told otherwise — which is what makes an ordinary app unaware that this question exists. A client under a shared renderer assigns the compositor here, once, at startup:

guard let editor = LavaClient.open(title: "My App") else { exit(1) }
editor.resources = compositor      // ids now come from the renderer

Set before loading anything. Ids already stamped into a UIFont or a UIImage are not revisited, so a switch after the fact leaves the resources loaded before it naming things in the wrong process.

Whether the tray is live, either owning org.kde.StatusNotifierWatcher or following another desktop's.

How many tray items there are. See statusNotifierItem(_:).

How many rows the open tray menu has.

Changes when the open tray menu's layout does, including when it first arrives: a menu is empty until the application answers.

Changes whenever the item list or any item's display data does.

Number of open windows. Zero is how an app knows to exit.

Ids of the open windows, in creation order.

Adds an item to the open menu.

• id: Returned by appMenuPopActivation() when the panel activates the item.
• title: The item's label.
• enabled: Whether it can be activated.
• checked: -1 not checkable, 0 unchecked, 1 checked.

Adds a separator to the open menu.

Register this window's menu with the session AppMenu registrar.

The same, under an id this process supplies rather than an X11 window id — which is what a compositor client has instead: its surface id, the number the panel hears about when the window takes focus.

Opens a top-level menu in the exported menu being rebuilt. Close it with appMenuEndMenu().

Starts rebuilding the exported menu. Follow with appMenuBeginMenu, appMenuAddItem and friends, then appMenuCommitUpdate().

Publishes the menu built since appMenuBeginUpdate().

Withdraws this window's exported menu from the global menu registrar.

Closes the menu appMenuBeginMenu(id:title:) opened.

Runs the exported menu's GLib loop once. Call once per frame.

Panel-activated MenuID raw string, or empty if the queue is empty.

True if a menu registrar — org.lavaui.AppMenu.Registrar or the canonical com.canonical.AppMenu.Registrar — is on the session bus and canvas was built with libdbusmenu-glib.

Drives this window from a draw arena another process writes, instead of from a DrawList submitted in this one.

The producer creates the arena and this attaches to it, so the order is producer-then-renderer. Returns false if it is missing or its header does not check out.

The same capture as PNG bytes.

For a caller that is not about to put it in JSON — the compositor answering CaptureSurface for a client, where base64 would be a third more bytes on the wire and a decode at the other end, to satisfy a protocol the renderer is not speaking.

Capture the resolve target as PNG (base64). Region in framebuffer pixels; omit or pass w/h ≤ 0 for the full frame. maxSide > 0 downsamples so the longer encoded side ≤ maxSide. Returns (base64, encodedWidth, encodedHeight) or nil on failure.

Closes one window. Every other window, and the device, survive it.

Decodes an image file to RGBA8 without touching the GPU.

Safe to call from a worker thread — that is the whole point. Decoding a JPEG is tens of milliseconds and does not need the device; only the upload does. Returns nil if the file will not decode.

maxPixelSize (0 = native) caps the longer edge. Returned width and height are the size after any downscale, so the caller sizes its texture from these rather than from what the file claimed.

turn is applied after the orientation the file itself declares — the decoder always applies that one — so it composes with what is on screen rather than with how the sensor read out. It is done here and not by the caller so that there is one implementation of turning pixels in the whole system: a viewer that turned a photograph one way on screen and another way into the file it wrote would be wrong in the way nobody notices until the file is saved.

The same decode from encoded bytes already in memory, for an image that never had a path — downloaded, generated, unpacked from an archive.

bytes are the encoded file (PNG, JPEG, …), not raw pixels: the format is sniffed the way it is for a file.

Stops driving window from a draw arena; the inverse of attachDrawArena(id:window:).

Paths from the most recent .fileDrop event. Valid only while handling that event — the next drop overwrites them.

RGBA8 → baseline JPEG at quality (1-100), always at native size.

For writing a transformed photograph back where it came from. PNG is the better encoder for everything this framework normally does, and the wrong one here: re-encoding a 24-megapixel JPEG losslessly turns six megabytes into a hundred and thirty, which is not what anyone means by "save".

Alpha is discarded — JPEG has none. Do not route an image that uses it through here.

RGBA8 → PNG. maxSide 0 is native.

Current swapchain / framebuffer size in pixels.

Frames published for window that its consumer has not taken yet.

Zero unless this window publishes to another process. See FrameSink.framesInFlight — advisory back-pressure, not a lock.

Whether the engine already has this key resident.

Inject a key event. action: 0 release, 1 press, 2 repeat (GLFW).

Inject mouse button. button is GLFW-style (0 = left); mods too (KeyMods), for a scripted Ctrl+click or Shift+click.

Inject pointer motion into the same queue as GLFW (layout pixels).

Inject wheel/trackpad delta (notches), same coalescing queue as real scroll.

Inject UTF-8 text as character events (focused text field path).

False while this window is minimized/occluded.

Install face for draw-list text (must match UIFont used for measure).

Load a PNG/JPEG for Image views. Returns a handle or nil on failure. Idempotent per absolute path.

Asks the owning application to fill a submenu before it is opened.

Runs a row of the imported menu, in the application that owns it.

Tells the importer the dropdown closed, so it stops refreshing a submenu nobody has open.

One row of the imported menu, by index in 0..<menuImportItemCount.

Runs the menu importer's GLib loop once. Call every frame while a panel is showing an imported menu.

Whose menu to import. 0 shows none.

menuService / menuObjectPath come from the focused window's KDE Wayland AppMenu address when the compositor has one; empty falls back to the AppMenu registrar under windowId — ActiveWindow.registrarId, which is the surface id for Wayland clients and an XID for X11 ones — then to a registrar entry whose DBus sender has pid (Qt5 Wayland).

Own a registrar name and start importing menus. False without a bus.

One live notification, by index in 0..<notificationsCount.

The key of a notification's action — what notificationInvokeAction(_:key:) takes. index is the notification's position, action the action's.

The label shown for a notification's action.

Closes notification id, as dismissed by the user.

Closes every notification.

Invokes the action named key on notification id and closes the notification.

Pumps the notification bus and retires expired notifications. Call every frame.

Holds every notification's countdown while paused — the pointer is over the stack.

Claims org.freedesktop.Notifications and starts serving. False when the session already has a notification daemon, or has no bus.

Opens a window with its own Vulkan renderer and shows it.

Returns nil when the window or the renderer cannot be created; the engine logs why on standard error.

• assetsRoot: Directory holding the engine's shaders and bundled fonts.
• width: Initial width of the window, in pixels.
• height: Initial height of the window, in pixels.
• title: The window title.

Opens an engine that lays out and emits frames for another process to draw: no Vulkan, no window, no GPU.

Everything above this — LavaWindow, the view tree, layout, emit — is unchanged and unaware. That is the point: a client is not a second frame loop, it is the same one with the parts that need a screen answering honestly that they have none. renderFrame succeeds and draws nowhere, capturePngBase64 returns nil, loadImage returns nil (see below), and the rest behaves exactly as it does in a window.

Two things a client cannot answer for itself and must be told:

• Size. There is no surface to measure, so setClientSize is the only way it learns one, and the initial width/height here are a guess until something says otherwise.
• Input. The inject* entry points are the whole input path, not a test affordance layered over a real one — which is what lets the agent server drive a client with no compositor on the other end.

Known gaps, both by design and both scoped as later work: images fail to load (a texture id is per-process and there is no RegisterFont equivalent for images yet), and registerFont hands out ids from a local table that means nothing to a renderer elsewhere.

Opens an additional window. Returns its id, or nil on failure.

It starts hidden. Draw a frame into it, then setVisible(true, window:) — showing a window before its first frame presents an undefined swapchain image, which looks like a flash of garbage.

A client engine accepts this too: the window is an arena and an input queue, and nothing on screen. Asking the compositor for a surface is LavaApp.openWindow, which is what an app should call.

Raw input: mouse, resize, key (see InputEventKind).

Queues an event that arrived already formed — from a renderer in another process — rather than one derived from a device here.

The only way some events can reach a client at all: .resize, .nodeHover, .nodeScroll and .nodeAnimationDone are answers a renderer produces by looking at its own retained scene, and a client has no scene and no device to synthesize them from. A .resize is also state, not just an event, and updates what framebufferSize reports from here on.

Thread-safe, like every input entry point — the queue is the one thing in a window that has always been touched from more than one thread. Callers still have to wakeEventLoop() if the loop may be parked.

Sends this window's frames somewhere other than the engine — a shared arena another process renders from.

Takes effect for DrawLists built after it, so a client installs the sink before LavaApp.run rather than during. A list already holding the old sink keeps writing to it, which is the safe way round: the alternative is swapping the storage out from under a frame that is halfway emitted.

Drive the window from this thread. timeout < 0 blocks until an event arrives, 0 polls, > 0 waits at most that long. Blocking is what keeps an idle UI at zero CPU while still waking immediately on input.

Loads one face of a font file at a size, returning its font id, or nil when the file cannot be loaded.

Idempotent per file contents (canvas::FontKey), not per path.

• path: The font file.
• pixelSize26_6: The size in 26.6 fixed point: pixels × 64.
• faceIndex: Which face of a collection (.ttc); 0 for a single-face file.
• rasterFlags: A canvas::RasterFlags hinting selection.

Decode on a worker, upload on the main thread.

The split is not an optimization, it is a requirement in both directions: decoding a JPEG is tens of milliseconds and would stall the frame, and uploading touches the Vulkan device, which is the main thread's alone.

Render and present one frame.

Ask the frame loop to exit (GLFW should-close). Safe from menu actions.

Offers a wheel notch to the retained scroll containers under the pointer, after nothing in this process wanted it.

The renderer normally keeps the wheel — that is what lets a list scroll while this process is busy — and only forwards the event where a node declared a handler of its own. Whether that handler takes a given notch is a question only this process can answer, so when the answer is no, the event goes back. Returns whether anything moved.

Tells a client window how big it is, queueing the .resize its tree needs to re-lay-out. No-op on a window that has a renderer, which measures its own surface instead.

The pointer image over this window.

Windowed only: a client has no pointer to set, and asks the compositor instead (CursorBridge). No-op there rather than an error, so the same call site works in both modes.

Constrains interactive resizing of a local window. Zero means no minimum on that axis. Client surfaces use their compositor host.

Whole-window camera. Layout and Yoga stay at zoom=1; the quad shader applies center-zoom then pan. Hit-tests must unproject first.

Shows or hides a window without closing it.

Sends the item a left click (Activate). The coordinates are screen pixels, which many items ignore.

Drops the tray menu statusNotifierOpenMenu(_:) opened. The item is not told.

Asks the item to show its own context menu (ContextMenu), for a right click.

One tray item, by index in 0..<statusNotifierItemCount.

Asks the owning application to fill a tray submenu before it is opened.

Runs a row of the open tray menu, in the application that owns it.

One row of the open tray menu, by index in 0..<statusNotifierMenuItemCount.

Opens key's DBusMenu. False when the item exports none — activate it instead.

Runs the tray's GLib loop once. Call every frame while the panel is up.

Sends the item a scroll of delta steps, "vertical" or "horizontal".

Sends the item a middle click (SecondaryActivate).

Own org.kde.StatusNotifierWatcher. False if the name is taken or there is no session bus.

Drops the sink publishFrames installed, and the arena it owns.

A closed client window that left its sink behind would keep a shared-memory mapping for a surface nobody is drawing. The engine window and the sink are separate objects; closing one does not drop the other.

Publishes a finished frame to the window list was created for. The list must belong to this editor.

Consumes "this window needs redrawing for a reason of its own".

The third repaint signal, alongside "a producer published" and "input arrived": the renderer moves scene nodes itself — a scroll today — and when it does, nothing is published and nothing is queued, because the point of a retained tree is that the producer is not involved.

Drops one reference to a loaded image.

The GPU memory is not normally freed here. At zero references the image goes dormant, keeping its pixels and its id so reloading the same key costs nothing. Eviction from there is LRU, and never touches an image a window's current frame still names. Standalone images are evicted against a byte budget (LAVA_IMAGE_CACHE_MB, 256 by default); atlased ones against atlas occupancy, since a cell is far too small to move a byte budget but the cells themselves run out. Allocated atlas pages stay resident either way.

Uploads pre-decoded pixels. Main thread only — it touches the device.

key is the texture identity (see UIImage.cacheKey); path is the file it came from, and defaults to key for callers that decode at native size and need no distinction.

Unblock a waiting pumpEvents from any thread (agent socket watcher).

Whether this window has been asked to close (its titlebar X, a WM request). The caller decides what that means — closing the last window usually ends the app, closing any other is just closeWindow.

False for a window that is already closed: "asked to close" and "does not exist" are different questions, and windowCount answers the second.