ntk 5.2.0 → 5.4.0

package/lib/window.js

@@ -2,6 +2,7 @@ import x11 from 'x11';
 
 import { safeRelease } from './cleanup.js';
 import Drawable from './drawable.js';
+import { packIcons, unpackIcons } from './imagedata.js';
 import Pixmap from './pixmap.js';
 import * as xevents from './events_map.js';
 import { decodeKey } from './keyboard.js';
@@ -432,6 +433,11 @@ export default class Window extends Drawable {
     if (args.windowType) {
       this.setWindowType(args.windowType);
     }
+    if (args.icon) {
+      // needs the atom interned first, so unlike the writers above it is not
+      // on the wire by the time createWindow returns
+      this.setIcon(args.icon).catch((err) => app.options.onXError?.(err));
+    }
     // ICCCM/EWMH hints at creation: `hints: { ... }`, the `sizeHints`/
     // `resizable` arguments that predate it, or the hint names on their own
     // at the top level. All of them land in one setHints call so that a
@@ -505,6 +511,9 @@ export default class Window extends Drawable {
       // them in the order they happened (a drag sees the move, then the up)
       this._flushCoalesced();
       this.emit(eventName, ntkev);
+      // a WM_DELETE_WINDOW ClientMessage is the window manager *asking*, and
+      // 'close' is that question in a form an application can answer
+      if (eventName === 'message') this._emitCloseRequest(ntkev);
       // anything drawn during the handlers becomes visible in one blit
       if (this._dirty) this._present();
     });
@@ -527,6 +536,18 @@ export default class Window extends Drawable {
     });
 
     this.on('newListener', (name) => {
+      // Listening for 'close' is the opt-in. WM_DELETE_WINDOW only reaches a
+      // client that advertised it in WM_PROTOCOLS — a window manager kills
+      // anyone else outright — and having to know that, on top of decoding a
+      // ClientMessage by hand, is the protocol showing through the toolkit.
+      if (name === 'close' && !this._closeArmed) {
+        this._closeArmed = true;
+        // interning WM_PROTOCOLS here as well as in addProtocol: the
+        // dispatch path matches against both atoms and node-x11 caches them
+        // per connection, so this costs one round trip and no more
+        this.atom('WM_PROTOCOLS').catch(() => {});
+        this.addProtocol('WM_DELETE_WINDOW').catch((err) => this.app.options.onXError?.(err));
+      }
       // 'statechange' is derived from a PropertyNotify, so it needs the atom
       // to compare against as well as the mask the table below selects
       if (name === 'statechange' && !this._netWmStateAtom) {
@@ -634,7 +655,7 @@ export default class Window extends Drawable {
     });
     if (!this._clearGc) {
       // reusable across reallocs: a GC is valid for any drawable of the
-      // same screen and depth (node-x11 has no FreeGC request)
+      // same screen and depth, so one outlives every backing pixmap
       this._clearGc = this.X.AllocID();
       this.X.CreateGC(this._clearGc, pixmap.id, {
         foreground: this.display.screen[0].white_pixel,
@@ -1415,6 +1436,9 @@ export default class Window extends Drawable {
    * atom name: `'WM_DELETE_WINDOW'`, `'WM_TAKE_FOCUS'`, `'_NET_WM_PING'`,
    * `'_NET_WM_SYNC_REQUEST'`. Each arrives as a `'message'` event.
    *
+   * `WM_DELETE_WINDOW` needs none of this by hand: listening for the
+   * `'close'` event adds the protocol and decodes the message for you.
+   *
    * Replaces the whole list. `addProtocol`/`removeProtocol` are the
    * accumulating forms, and the ones to reach for: the property is a *set*,
    * and a plain write of one atom silently drops the rest.
@@ -1528,6 +1552,82 @@ export default class Window extends Drawable {
     });
   }
 
+  /**
+   * EWMH `_NET_WM_ICON` — the icon a taskbar, alt-tab switcher or titlebar
+   * draws for this window.
+   *
+   *   wnd.setIcon(await loadImage('icon-48.png'));
+   *   wnd.setIcon([icon16, icon32, icon48]);
+   *   wnd.setIcon(await ctx.getImageData(0, 0, 64, 64));
+   *   wnd.setIcon(null);            // remove it
+   *
+   * An image is an ntk [`Image`](images.md), an `ImageData`, or anything
+   * with `{ width, height, data }` where `data` is straight
+   * (non-premultiplied) RGBA — the same contract as the rest of ntk, so
+   * whatever `loadImage()` or `getImageData()` gives you goes straight in.
+   *
+   * Passing several is the useful case: supply the sizes you have and the
+   * window manager picks whichever suits the slot it is filling, instead of
+   * scaling a single one badly. Nothing requires a particular order or a
+   * particular set of sizes; 16, 32 and 48 cover most desktops.
+   *
+   * This is the modern mechanism. `setWmHints({ icon })` writes the ICCCM
+   * pixmap instead, which is 1-bit-or-matched-depth and has no alpha; a
+   * window manager that understands both prefers this one.
+   *
+   * @param {object|object[]|null} images
+   * @returns {Promise<Window>}
+   */
+  async setIcon(images) {
+    const list = images == null ? [] : Array.isArray(images) ? images : [images];
+    if (!list.length) return this.deleteProperty('_NET_WM_ICON');
+
+    const data = packIcons(list, this.app.display);
+    const property = await this.atom('_NET_WM_ICON');
+    const cardinal = this.X.atoms.CARDINAL;
+    if (this._destroyed) return this;
+
+    // A ChangeProperty carries 24 bytes of header, so a full icon set can
+    // outrun the request limit on a connection created with
+    // `disableBigRequests` — 256x256 alone is 262152 bytes against a 262140
+    // cap. Replace with the first chunk, append the rest.
+    const maxBytes = ((this.app.display.max_request_length ?? 65535) - 6) * 4;
+    safeRelease(this.X, () => {
+      for (let o = 0; o < data.length; o += maxBytes) {
+        this.X.ChangeProperty(
+          o === 0 ? 0 : 2, // Replace, then Append
+          this.id,
+          property,
+          cardinal,
+          32,
+          data.subarray(o, Math.min(o + maxBytes, data.length))
+        );
+      }
+    });
+    return this;
+  }
+
+  /**
+   * Read `_NET_WM_ICON` back — every size the window advertises, largest
+   * last or in whatever order its client wrote them, as `ImageData`.
+   *
+   * Useful on your own window, and the point of it on someone else's: a
+   * window manager drawing titlebars reads this off each client it frames.
+   * Property bytes from another client are not to be trusted, so a
+   * truncated or nonsensical run yields the images that parsed cleanly
+   * rather than throwing.
+   *
+   * Resolves to `null` when the window has no icon.
+   *
+   * @returns {Promise<ImageData[]|null>}
+   */
+  async getIcon() {
+    const prop = await this.getProperty('_NET_WM_ICON');
+    if (!prop || !prop.data.length) return null;
+    const icons = unpackIcons(prop.data, this.app.display);
+    return icons.length ? icons : null;
+  }
+
   /** os.hostname(), looked up once, and absent in a browser bundle. */
   static _hostname() {
     if (Window._cachedHostname === undefined) {
@@ -2363,6 +2463,42 @@ export default class Window extends Drawable {
     return this;
   }
 
+  /**
+   * Turn a WM_DELETE_WINDOW ClientMessage into the `close` event.
+   *
+   * Only fires when something is listening, so a window that handles the
+   * raw `message` event itself — the only way to do this before `close`
+   * existed — keeps behaving exactly as it did, rather than suddenly
+   * acquiring a second handler that destroys it.
+   */
+  _emitCloseRequest(ev) {
+    if (ev.format !== 32 || !this.listenerCount('close')) return;
+    // node-x11 caches interned atoms per connection, so these are the ids
+    // the 'close' listener's addProtocol already interned
+    const X = this.X;
+    if (!X.atoms.WM_PROTOCOLS || ev.message_type !== X.atoms.WM_PROTOCOLS) return;
+    if (!X.atoms.WM_DELETE_WINDOW || ev.data?.[0] !== X.atoms.WM_DELETE_WINDOW) return;
+
+    let prevented = false;
+    this.emit('close', {
+      name: 'close',
+      window: this,
+      target: this,
+      // the timestamp the window manager stamped the request with, for
+      // passing back to setInputFocus and friends
+      time: ev.data[1],
+      preventDefault() {
+        prevented = true;
+      },
+      get defaultPrevented() {
+        return prevented;
+      }
+    });
+    // the default action, and the reason preventDefault has to be called
+    // synchronously: there is no point at which it could be awaited
+    if (!prevented && !this._destroyed) this.destroy();
+  }
+
   destroy() {
     this._destroyed = true;
     this._forget();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",