react-x11 2.12.0 → 2.13.0

package/src/index.d.ts

@@ -163,8 +163,21 @@ export function useClipboard(): Clipboard;
  * branches on it through the theme's `controls: 'auto'` policy; this is for
  * application code composing its own controls to sit beside native ones. It
  * is a property of the backend and never changes over the app's life.
+ *
+ * `'embedding'` is whether this connection can take another process's window
+ * into its own — X11, never Cocoa or the headless mock. Ask it before
+ * rendering a `<foreign>`, which refuses with one `onError` where it is
+ * false. Also a property of the backend, and it never changes either.
+ *
+ * `'glOverlay'` is whether the children of a `<glarea>` are drawn above its
+ * GL surface — laid out in its box, painted on panes stacked over it, hit
+ * before it. Both backends draw them; translucency is the difference,
+ * composited by Core Animation on Cocoa and opaque on X11, where what a
+ * child leaves unpainted shows the surface's `clearColor` (docs/elements.md).
+ * Ask it before handing a surface its HUD. A property of the backend.
  */
-export type SupportsFeature = 'transparency' | 'shaders' | 'nativeControls';
+export type SupportsFeature =
+  'transparency' | 'shaders' | 'nativeControls' | 'embedding' | 'glOverlay';
 
 /**
  * Can this **display** do something? `'transparency'` is true when the

package/src/node.d.ts

@@ -820,5 +820,16 @@ export declare class WindowNode extends Node {}
 export declare class PopupNode extends WindowNode {}
 /** The precedents for an element owning a real child X window — a surface of
  * its own, and one holding somebody else's window. */
-export declare class GlAreaNode extends Node {}
+export declare class GlAreaNode extends Node {
+  /**
+   * `true`: the pointer over the surface is dispatched through the owning
+   * window's event manager, at this node, on this backend. So an element
+   * built on `<glarea>` must not listen for the pointer on `node.window` —
+   * on X11 that selects the event on the surface's own window, and X then
+   * delivers it there instead of to the tree. Readable without rendering,
+   * as `GlAreaNode.prototype.forwardsPointer`; absent on a core that does
+   * not deliver it.
+   */
+  readonly forwardsPointer: true;
+}
 export declare class ForeignNode extends Node {}

package/src/nodes/window/flush.js

@@ -84,6 +84,29 @@ export class WindowFlush {
     this._pacer.charge(ms);
   }
 
+  /**
+   * Panes for the children of every `<glarea>` here, where this frame's
+   * layout put them (src/gloverlay.js). True when one was made, resized or
+   * dropped, which the frame then owes a paint for.
+   */
+  _syncOverlays() {
+    let changed = false;
+    for (const area of this._overlaid) {
+      if (area.destroyed || area.root !== this) {
+        this._overlaid.delete(area);
+        continue;
+      }
+      if (area._syncOverlay()) changed = true;
+    }
+    return changed;
+  }
+
+  /** …and their paint, with the frame's own damage: a claim inside a
+   * `<glarea>`'s children is in that list like any other. */
+  _paintOverlays(damage) {
+    for (const area of this._overlaid) area._paintOverlay(damage);
+  }
+
   /**
    * A frame: layout if owed, then the paint passes — or the presenter's
    * frame — then the backend's word. Runs on the window's clock through
@@ -254,6 +277,12 @@ export class WindowFlush {
     // …and the next commit's claims name the arrangement this frame leaves
     // behind again, from before whatever scroll comes with them
     this._laidOut = false;
+    // The children of a `<glarea>` get panes where they are now: after
+    // layout and the scroll's shift, before the damage is taken, so a pane
+    // made or resized in this frame is painted in it, whole
+    if (this._overlaid.size !== 0 && this._syncOverlays()) {
+      this.needsPaint = true;
+    }
     if (!this.needsPaint) return false;
     this.needsPaint = false;
     const damage = this._takeDamage(width, height);
@@ -276,6 +305,8 @@ export class WindowFlush {
     // list was still taken (its bookkeeping is what keeps the two paths one
     // code) and is simply not consumed; the presenter diffs at the layer.
     if (typeof this.window.presentFrame === 'function') {
+      // the panes are no presenter's: they paint from the damage either way
+      if (this._overlaid.size !== 0) this._paintOverlays(damage);
       this.window.presentFrame(this, damage);
       this.app._reactX11Startup?.painted();
       return true;
@@ -297,6 +328,10 @@ export class WindowFlush {
     for (const rect of damage ?? [null]) {
       this._paintRegion(ctx, rect, width, height);
     }
+    // …and the panes over the surfaces, with the same damage: a claim from
+    // a `<glarea>`'s children is theirs to repaint — the window's pass under
+    // the surface is one nobody sees. Inside the cache's frame, like a pass.
+    if (this._overlaid.size !== 0) this._paintOverlays(damage);
     // after every region: an entry drawn in one damage rect must not be
     // evicted before the next rect of the same frame asks for it
     this._paintCache?.endFrame();

package/src/nodes/window/window.js

@@ -191,6 +191,15 @@ export class WindowNode extends Scrollable(Node) {
     // behind one `size` read on the motion path, and a tree that never asked
     // for attention must not pay a property walk to find that out.
     this._attentionNodes = new Set();
+    // The GL surfaces in this window, bottom to top: `<glarea>`s, stacked
+    // above everything 2D here, which the hit test therefore asks before the
+    // tree (`EventManager._surfaceAt`). A surface joins when its window is
+    // made and leaves when it goes (src/glnodes.js).
+    this._surfaces = [];
+    // …and the ones with children, whose panes each frame syncs after layout
+    // and paints with its damage (nodes/window/flush.js, src/gloverlay.js).
+    // Empty is one `size` read a frame.
+    this._overlaid = new Set();
     this.events = new EventManager(this);
     // ids of the child windows in the order the *server* stacks them,
     // bottom to top — see _restackWindowChildren

package/src/types/elements.d.ts

@@ -915,6 +915,16 @@ export interface SvgProps extends DrawnProps<DrawnNode> {
 
 export type FrameLoop = 'demand' | 'always';
 
+/**
+ * `<glarea>`: a GL surface in the layout. Its **children** are 2D content
+ * drawn above the surface — laid out in its box like a `<box>`'s and cut to
+ * it, painted over the GL frame, hit before it — composited on the Cocoa
+ * backend and opaque on X11 (docs/elements.md); `useSupports('glOverlay')`
+ * asks whether they will be. The pointer over it is the tree's, as over any
+ * node: the handlers it inherits (`onMouseDown`, `onClick`, `onWheel`, …)
+ * fire at the child under the pointer or the `<glarea>` and bubble, on both
+ * backends, and `GlAreaNode.forwardsPointer` says so at run time.
+ */
 export interface GlAreaProps extends DrawnProps<DrawnNode> {
   /** CSS colour, or `[r, g, b, a]` floats. Default black. */
   clearColor?: Color | [number, number, number, number];
@@ -937,17 +947,6 @@ export interface GlAreaProps extends DrawnProps<DrawnNode> {
   onDraw?: (gl: any, info: DrawInfo) => void;
   /** No GL surface — no GLX, or no matching visual. */
   onError?: (err: Error) => void;
-  /**
-   * The wheel over the surface. Inherited from `EventHandlers` like every
-   * other element's, and listed here because it is the **only** pointer
-   * event a `<glarea>` currently reports: the surface owns its own X window,
-   * so it selects the wheel there and hands it to the window's event manager
-   * (see docs/elements.md). Deltas are pixels, `preventDefault()` takes the
-   * default scroll action back, and it bubbles from this node.
-   */
-  onWheel?: (ev: WheelEvent<DrawnNode>) => void;
-  /** A click inside the surface that hit no mesh. */
-  onPointerMissed?: (ev: MouseEvent<DrawnNode>) => void;
 }
 
 // --- embedding -------------------------------------------------------------
@@ -973,7 +972,9 @@ export interface ForeignProps extends DrawnProps<DrawnNode> {
    */
   windowId?: number;
   /** The container window's id, offered as soon as it exists, so a program
-   * can be spawned into it. Fires before there is anything embedded. */
+   * can be spawned into it. Fires before there is anything embedded — and
+   * never on a backend with no embedding (`useSupports('embedding')`), so the
+   * id is always a real window's. */
   onReady?: (info: { windowId: number; node: DrawnNode }) => void;
   /** A client is in. */
   onEmbedded?: (info: EmbeddedInfo) => void;
@@ -982,7 +983,8 @@ export interface ForeignProps extends DrawnProps<DrawnNode> {
   /** `XEMBED_REQUEST_FOCUS`: the client wants the focus. It is given through
    * the focus manager unless a handler prevents it by focusing elsewhere. */
   onRequestFocus?: (info: { node: DrawnNode }) => void;
-  /** The embed failed — no such window, or it went away mid-handshake.
+  /** The embed failed — no such window, or it went away mid-handshake — or
+   * this backend cannot embed at all, which is reported once, at mount.
    * Without a handler the failure is a console warning. */
   onError?: (err: Error) => void;
 }