ntk 3.7.2 → 3.9.0

package/lib/app.js

@@ -81,8 +81,41 @@ export default class App {
     return chooseGLXConfig(this, spec);
   }
 
-  rootWindow() {
-    return new Window(this, { id: this.display.screen[0].root });
+  rootWindow(screen = 0) {
+    return new Window(this, { id: this.display.screen[screen].root });
+  }
+
+  /**
+   * Release a pointer or keyboard frozen by a synchronous grab (X
+   * AllowEvents). A window manager grabs buttons on client windows with
+   * `pointerMode: 0` so it sees the press first; this decides what happens
+   * to it:
+   *
+   *   'replay'  — hand the event back to the client as if we never saw it
+   *               (click-to-focus: raise the window, let the click through)
+   *   'async'   — thaw, keeping the event for ourselves
+   *   'sync'    — thaw for one more event, then freeze again
+   *
+   * The keyboard and both-devices variants carry their X names.
+   *
+   * @param {string|number} [mode] one of the names above, or a raw X mode
+   * @param {number} [time] CurrentTime by default
+   */
+  allowEvents(mode = 'replay', time = 0) {
+    const MODES = {
+      async: 0, // AsyncPointer
+      sync: 1, // SyncPointer
+      replay: 2, // ReplayPointer
+      async_keyboard: 3,
+      sync_keyboard: 4,
+      replay_keyboard: 5,
+      async_both: 6,
+      sync_both: 7
+    };
+    const value = typeof mode === 'number' ? mode : MODES[mode];
+    if (value === undefined) throw new Error(`ntk: unknown AllowEvents mode '${mode}'`);
+    this.X.AllowEvents(value, time);
+    return this;
   }
 
   createPixmap(args) {

package/lib/events_map.js

@@ -14,6 +14,9 @@ eventName[8] = 'mouseout';
 eventName[9] = 'focus';
 eventName[10] = 'blur';
 eventName[12] = 'expose';
+// CreateNotify: a child window appeared under a parent we watch. Carries a
+// `parent` field, so it arrives as a child-event like the *_request ones.
+eventName[16] = 'create';
 eventName[17] = 'destroy';
 eventName[18] = 'unmap';
 eventName[19] = 'map';
@@ -21,7 +24,7 @@ eventName[20] = 'map_request';
 eventName[21] = 'reparent';
 eventName[22] = 'resize';
 eventName[23] = 'configure_request';
-// 25 - gravity
+eventName[24] = 'gravity';
 eventName[25] = 'resize_request';
 eventName[26] = 'circulate';
 eventName[27] = 'circulate_request';
@@ -49,6 +52,15 @@ export const mask = {
   expose: x11.eventMask.Exposure,
   map_request: x11.eventMask.SubstructureRedirect,
   configure_request: x11.eventMask.SubstructureRedirect,
+  circulate_request: x11.eventMask.SubstructureRedirect,
+  // a child window appeared under a window we watch — the one
+  // SubstructureNotify event with its own name, because the rest
+  // (map/unmap/destroy/resize/reparent of a child) are the same event types
+  // a window gets about itself and are emitted on the child's own wrapper
+  create: x11.eventMask.SubstructureNotify,
+  gravity: x11.eventMask.StructureNotify,
+  circulate: x11.eventMask.StructureNotify,
+  resize_request: x11.eventMask.ResizeRedirect,
   destroy: x11.eventMask.StructureNotify,
   keyup: x11.eventMask.KeyRelease,
   property: x11.eventMask.PropertyChange,
@@ -85,6 +97,8 @@ export const toSnake = {
   onExpose: 'expose',
   onMapRequest: 'map_request',
   onConfigureRequest: 'configure_request',
+  onCirculateRequest: 'circulate_request',
+  onCreate: 'create',
   onDestroy: 'destroy',
   onKeyUp: 'keyup',
   onPropertyChange: 'property',

package/lib/window.js

@@ -33,14 +33,49 @@ const forwardedXAttributes = [
   'cursor'
 ];
 
+/**
+ * Turn a GetProperty reply into the shape the caller asked for. X property
+ * types are atoms, so the only distinction we can make without a round trip
+ * is against the predefined ones: STRING is latin-1 by definition (ICCCM),
+ * and everything else carrying text — UTF8_STRING above all — is UTF-8.
+ */
+function decodeProperty(prop, as, X) {
+  if (as === 'string') {
+    const encoding = prop.type === X.atoms.STRING ? 'latin1' : 'utf8';
+    // these properties are conventionally NUL-terminated, sometimes twice
+    return prop.data.toString(encoding).replace(/\0+$/, '');
+  }
+  if (as === 'numbers') {
+    const out = [];
+    for (let i = 0; i + 4 <= prop.data.length; i += 4) out.push(prop.data.readUInt32LE(i));
+    return out;
+  }
+  return { type: prop.type, data: prop.data };
+}
+
 export default class Window extends Drawable {
   // one wrapper per X window id and connection: constructing a Window for a
-  // known id returns the cached instance
-  static cache = new Map();
+  // known id returns the cached instance. Keyed by connection as well as
+  // id, because ids are only unique within a server, not within a process —
+  // two connections to the same display see the same root window, and a
+  // window manager sees every other client's ids.
+  static cache = new WeakMap();
+
+  static _cacheFor(app) {
+    let byId = Window.cache.get(app);
+    if (!byId) Window.cache.set(app, (byId = new Map()));
+    return byId;
+  }
 
   constructor(app, args = {}) {
+    // 0 is X None, not a window. Without this it fails the truthiness test
+    // below and falls through to the create path, silently making a real
+    // 800x800 window out of what was almost certainly a missing id.
+    if (args.id === 0) {
+      throw new Error('ntk: 0 (None) is not a window id');
+    }
     if (args.id) {
-      const cached = Window.cache.get(args.id);
+      const cached = Window._cacheFor(app).get(args.id);
       // TODO: check event mask, if more events in args - update it
       if (cached) return cached;
     }
@@ -151,7 +186,7 @@ export default class Window extends Drawable {
       });
     }
 
-    Window.cache.set(this.id, this);
+    Window._cacheFor(app).set(this.id, this);
 
     if (args.title) {
       this.setTitle(args.title);
@@ -218,14 +253,19 @@ export default class Window extends Drawable {
       if (this._dirty) this._present();
     });
 
+    // Events about a *child* of this window: the substructure requests a
+    // window manager lives on (map_request, configure_request) plus
+    // create. The whole X event is carried through — a ConfigureRequest
+    // without its geometry and value mask says only "someone wants
+    // something", which is not enough to answer it — with `parent` and
+    // `window` upgraded from raw ids to Window objects.
     this.on('child-event', (ev) => {
       const eventName = xevents.eventName[ev.type];
-      const ntkev = {
-        parent: this,
-        window: new Window(app, { id: ev.wid })
-      };
+      if (!eventName) return;
+      const child = new Window(app, { id: ev.wid });
+      const ntkev = { ...ev, parent: this, window: child, target: child };
       // wait until we know that we track correct x,y,w,h values
-      ntkev.window._readyPromise.then(() => {
+      child._readyPromise.then(() => {
         this.emit(eventName, ntkev);
       });
     });
@@ -236,7 +276,14 @@ export default class Window extends Drawable {
       if (!eventMask) return;
       if ((eventMask & this.eventMask) === 0) {
         this.eventMask |= eventMask;
-        X.ChangeWindowAttributes(this.id, { eventMask: this.eventMask }, () => {});
+        // the selection can legitimately fail — SubstructureRedirect is
+        // one-client-only, so `on('map_request')` is how you find out
+        // another window manager owns this window. Route it to the app's
+        // error hook rather than dropping it; selectInput() is the
+        // explicit form that hands the error straight back.
+        X.ChangeWindowAttributes(this.id, { eventMask: this.eventMask }, (err) => {
+          if (err) this.app.options.onXError?.(err);
+        });
       }
     });
 
@@ -257,7 +304,7 @@ export default class Window extends Drawable {
   }
 
   _forget() {
-    Window.cache.delete(this.id);
+    Window._cacheFor(this.app).delete(this.id);
     delete this.X.event_consumers[this.id];
   }
 
@@ -997,6 +1044,308 @@ export default class Window extends Drawable {
 
   reparentTo(newParent, x, y) {
     this.X.ReparentWindow(this.id, newParent.id, x, y);
+    return this;
+  }
+
+  /** Move to the top of the stacking order among its siblings. */
+  raise() {
+    safeRelease(this.X, () => this.X.RaiseWindow(this.id));
+    return this;
+  }
+
+  /** Move to the bottom of the stacking order among its siblings. */
+  lower() {
+    safeRelease(this.X, () => this.X.ConfigureWindow(this.id, { stackMode: 1 }));
+    return this;
+  }
+
+  // ---------------------------------------------------------------------
+  // Reading properties
+  //
+  // ntk could write window properties (setTitle, setSizeHints, setClass)
+  // but never read them, which is fine for a client — it knows what it
+  // wrote — and useless for a window manager, whose whole job is to act on
+  // what *other* clients declare about themselves.
+  // ---------------------------------------------------------------------
+
+  /**
+   * Read a property. `name` is an atom name ('WM_NAME', '_NET_WM_STATE');
+   * interned atoms are cached per connection, so repeat reads cost no
+   * extra round trip.
+   *
+   * Resolves to `null` when the property is not set, otherwise to the
+   * decoded value chosen by `as`:
+   *   'buffer' (default) — `{ type, data }` with the raw bytes
+   *   'string'           — text, UTF-8 or latin-1 by the property's type
+   *   'numbers'          — an array of 32-bit values (atom lists, cardinals)
+   *
+   * @param {string} name
+   * @param {object} [options] `{ as, type, length }` — `type` restricts the
+   *   read to one property type (0, the default, accepts any), `length` is
+   *   the cap in 32-bit units.
+   */
+  async getProperty(name, options = {}) {
+    const { as = 'buffer', type = 0, length = 0x1fffffff } = options;
+    const atom = await this.atom(name);
+    return new Promise((resolve, reject) => {
+      safeRelease(this.X, () =>
+        this.X.GetProperty(0, this.id, atom, type, 0, length, (err, prop) => {
+          if (err) return reject(err);
+          // an unset property answers with type None and no bytes
+          if (!prop || !prop.type || !prop.data.length) return resolve(null);
+          resolve(decodeProperty(prop, as, this.X));
+        })
+      );
+    });
+  }
+
+  /**
+   * Write a property — the counterpart of getProperty, and the general form
+   * of setTitle/setClass/setSizeHints. Strings are written as UTF8_STRING,
+   * arrays of numbers as 32-bit lists; `type` names the property type atom
+   * ('ATOM', 'CARDINAL', 'WINDOW', 'UTF8_STRING', 'STRING'), which is what
+   * EWMH properties are picky about.
+   *
+   *   wnd.setProperty('_NET_WM_NAME', 'a title');
+   *   wnd.setProperty('_NET_CLIENT_LIST', ids, { type: 'WINDOW' });
+   *
+   * @param {string} name atom name of the property
+   * @param {string|number[]|Buffer} value
+   * @param {object} [options] `{ type, format }`
+   */
+  async setProperty(name, value, options = {}) {
+    const isList = Array.isArray(value);
+    const { type = isList ? 'CARDINAL' : 'UTF8_STRING', format = isList ? 32 : 8 } =
+      options;
+    const [property, typeAtom] = await Promise.all([this.atom(name), this.atom(type)]);
+    let data = value;
+    if (isList) {
+      const words = new Uint32Array(value);
+      data = Buffer.from(words.buffer, words.byteOffset, words.byteLength);
+    } else if (typeof value === 'string') {
+      data = Buffer.from(value, type === 'STRING' ? 'latin1' : 'utf8');
+    }
+    if (this._destroyed) return this;
+    safeRelease(this.X, () => {
+      this.X.ChangeProperty(0, this.id, property, typeAtom, format, data);
+    });
+    return this;
+  }
+
+  /**
+   * Intern an atom by name. node-x11 caches them per connection, so asking
+   * again for one already interned costs no round trip.
+   * @returns {Promise<number>} the atom id
+   */
+  atom(name) {
+    return new Promise((resolve, reject) => {
+      this.X.InternAtom(false, name, (err, id) => (err ? reject(err) : resolve(id)));
+    });
+  }
+
+  /**
+   * The window's title as the ICCCM/EWMH pair defines it: _NET_WM_NAME
+   * (UTF-8) if the client set one, else WM_NAME. Resolves to null when the
+   * window has neither. The read counterpart of setTitle.
+   */
+  async getTitle() {
+    const netName = await this.getProperty('_NET_WM_NAME', { as: 'string' }).catch(() => null);
+    if (netName) return netName;
+    return this.getProperty('WM_NAME', { as: 'string' }).catch(() => null);
+  }
+
+  /**
+   * WM_NORMAL_HINTS as an object shaped like setSizeHints' argument —
+   * `{ minWidth, minHeight, maxWidth, maxHeight, widthInc, heightInc,
+   * baseWidth, baseHeight, minAspect, maxAspect, gravity }`, each present
+   * only if the client set its flag. Resolves to `{}` when the window has
+   * no hints, so callers can destructure without a null check.
+   */
+  async getSizeHints() {
+    const v = await this.getProperty('WM_NORMAL_HINTS', { as: 'numbers' }).catch(() => null);
+    if (!v || v.length < 18) return {};
+    const flags = v[0];
+    const hints = {};
+    if (flags & 16) {
+      hints.minWidth = v[5];
+      hints.minHeight = v[6];
+    }
+    if (flags & 32) {
+      hints.maxWidth = v[7];
+      hints.maxHeight = v[8];
+    }
+    if (flags & 64) {
+      hints.widthInc = v[9];
+      hints.heightInc = v[10];
+    }
+    if (flags & 128) {
+      hints.minAspect = [v[11], v[12]];
+      hints.maxAspect = [v[13], v[14]];
+    }
+    if (flags & 256) {
+      hints.baseWidth = v[15];
+      hints.baseHeight = v[16];
+    }
+    if (flags & 512) hints.gravity = v[17];
+    return hints;
+  }
+
+  /**
+   * GetWindowAttributes — `{ mapState, overrideRedirect, ... }`. A window
+   * manager adopting the windows that already existed when it started
+   * needs both: override-redirect windows are none of its business, and
+   * only mapped ones should get a frame.
+   */
+  getAttributes() {
+    return new Promise((resolve, reject) => {
+      safeRelease(this.X, () =>
+        this.X.GetWindowAttributes(this.id, (err, attrs) => (err ? reject(err) : resolve(attrs)))
+      );
+    });
+  }
+
+  // ---------------------------------------------------------------------
+  // Managing other clients' windows
+  // ---------------------------------------------------------------------
+
+  /**
+   * Select an event mask explicitly, reporting failure. Handler-driven
+   * selection (`on('map_request')`, the onXxx constructor args) covers the
+   * ordinary case; this exists for the mask that can be refused —
+   * SubstructureRedirect belongs to one client at a time, so
+   *
+   *   await app.rootWindow().selectInput(SubstructureRedirect | SubstructureNotify)
+   *
+   * either makes you the window manager or rejects with BadAccess because
+   * something else already is. The mask is OR-ed into whatever handlers
+   * have already asked for.
+   */
+  selectInput(mask) {
+    this.eventMask |= mask;
+    return new Promise((resolve, reject) => {
+      this.X.ChangeWindowAttributes(this.id, { eventMask: this.eventMask }, (err) =>
+        err ? reject(err) : resolve(this)
+      );
+    });
+  }
+
+  /**
+   * Add this window to our save-set (X ChangeSaveSet). A window manager
+   * reparents clients into frames it owns; without the save-set, the
+   * clients would be destroyed along with those frames if the WM exits.
+   * With it the server reparents them back to the root and remaps them.
+   */
+  addToSaveSet() {
+    safeRelease(this.X, () => this.X.ChangeSaveSet(1, this.id));
+    return this;
+  }
+
+  removeFromSaveSet() {
+    safeRelease(this.X, () => this.X.ChangeSaveSet(0, this.id));
+    return this;
+  }
+
+  /**
+   * Tell the client where it really ended up (ICCCM 4.1.5). A reparented
+   * window's own ConfigureNotify carries coordinates relative to its
+   * frame, which is not what the client asked about, and a
+   * ConfigureRequest the window manager decided to refuse produces no
+   * ConfigureNotify at all — clients that resize themselves hang waiting
+   * for one. Both cases are answered by a synthetic event carrying
+   * root-relative coordinates.
+   *
+   * @param {object} geometry `{ x, y, width, height, borderWidth }` in
+   *   root coordinates; anything omitted comes from the window.
+   */
+  sendConfigureNotify(geometry = {}) {
+    const {
+      x = this.x,
+      y = this.y,
+      width = this.width,
+      height = this.height,
+      borderWidth = 0
+    } = geometry;
+    const ev = Buffer.alloc(32);
+    ev[0] = 22; // ConfigureNotify
+    ev.writeUInt32LE(this.id >>> 0, 4); // event window
+    ev.writeUInt32LE(this.id >>> 0, 8); // the window itself
+    ev.writeUInt32LE(0, 12); // above-sibling: None
+    ev.writeInt16LE(x, 16);
+    ev.writeInt16LE(y, 18);
+    ev.writeUInt16LE(width, 20);
+    ev.writeUInt16LE(height, 22);
+    ev.writeUInt16LE(borderWidth, 24);
+    ev[26] = 0; // override-redirect
+    safeRelease(this.X, () =>
+      this.X.SendEvent(this.id, 0, x11.eventMask.StructureNotify, ev)
+    );
+    return this;
+  }
+
+  /**
+   * Ask the client to close, the polite way: a WM_DELETE_WINDOW client
+   * message if it advertised the protocol in WM_PROTOCOLS, so it can save
+   * work or put up a confirmation. Clients that did not advertise it have
+   * no such path and are killed outright (X KillClient), which is what
+   * `xkill` does.
+   *
+   * This is the window manager's side of the protocol `setActions()` opts
+   * a window into.
+   *
+   * @returns {Promise<boolean>} true if asked politely, false if killed
+   */
+  async close() {
+    const protocols = await this.getProperty('WM_PROTOCOLS', { as: 'numbers' }).catch(() => null);
+    const deleteAtom = await this.atom('WM_DELETE_WINDOW').catch(() => 0);
+    if (!deleteAtom || !protocols || !protocols.includes(deleteAtom)) {
+      safeRelease(this.X, () => this.X.KillClient(this.id));
+      return false;
+    }
+    const wmProtocols = await this.atom('WM_PROTOCOLS');
+    const ev = Buffer.alloc(32);
+    ev[0] = 33; // ClientMessage
+    ev[1] = 32; // format
+    ev.writeUInt32LE(this.id >>> 0, 4);
+    ev.writeUInt32LE(wmProtocols >>> 0, 8);
+    ev.writeUInt32LE(deleteAtom >>> 0, 12);
+    ev.writeUInt32LE(0, 16); // CurrentTime
+    safeRelease(this.X, () => this.X.SendEvent(this.id, 0, 0, ev));
+    return true;
+  }
+
+  /**
+   * Grab a mouse button on this window (X GrabButton). A window manager
+   * uses this to see clicks that belong to the client: with
+   * `pointerMode: 0` (synchronous) the pointer freezes on press until
+   * `app.allowEvents()` decides what happens — 'replay' hands the click
+   * back to the client, so click-to-focus can raise the window without
+   * swallowing the click.
+   *
+   * @param {object} [options] `{ button (0 = any), modifiers (0x8000 =
+   *   any), ownerEvents, events, pointerMode, keyboardMode, confineTo,
+   *   cursor }`
+   */
+  grabButton(options = {}) {
+    const {
+      button = 0,
+      modifiers = 0x8000,
+      ownerEvents = false,
+      events = x11.eventMask.ButtonPress | x11.eventMask.ButtonRelease,
+      pointerMode = 1,
+      keyboardMode = 1,
+      confineTo = 0,
+      cursor = 0
+    } = options;
+    this.X.GrabButton(
+      this.id, ownerEvents, events, pointerMode, keyboardMode,
+      confineTo, cursor, button, modifiers
+    );
+    return this;
+  }
+
+  ungrabButton(button = 0, modifiers = 0x8000) {
+    safeRelease(this.X, () => this.X.UngrabButton(this.id, button, modifiers));
+    return this;
   }
 
   queryTree(callback) {
@@ -1004,12 +1353,13 @@ export default class Window extends Drawable {
     this.X.QueryTree(this.id, (err, tree) => {
       if (err) return callback(err);
       const children = tree.children.map((id) => new Window(app, { id }));
-      const parent = new Window(app, { id: tree.parent });
+      // the root window has no parent — QueryTree answers None (0) for it
+      const parent = tree.parent ? new Window(app, { id: tree.parent }) : null;
       // note that this root may be different from app.rootWindow() because
       // there can be multiple screens (and roots)
       const root = new Window(app, { id: tree.root });
-      const readyPromises = [...children, parent, root].map((w) => w._readyPromise);
-      Promise.all(readyPromises).then(() => {
+      const wrappers = [...children, root, ...(parent ? [parent] : [])];
+      Promise.all(wrappers.map((w) => w._readyPromise)).then(() => {
         callback(null, { parent, root, children });
       });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "3.7.2",
+  "version": "3.9.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",
@@ -51,7 +51,7 @@
     "parse-color": "^1.0.0",
     "pngjs": "^7.0.0",
     "postcss": "^8.5.23",
-    "x11": "^3.1.2",
+    "x11": "^3.2.0",
     "yoga-layout": "^3.2.1"
   },
   "scripts": {