ntk 4.0.0 → 4.2.0

package/lib/app.js

@@ -17,6 +17,21 @@ export default class App {
    *   instead of querying the server for one) }
    */
   constructor(display, options = {}) {
+    // ntk decodes property payloads and atom lists with little-endian
+    // readers. That is not an assumption about the host: node-x11 declares a
+    // byte order in its connection hello (`display.byte_order`, 0 LSBFirst /
+    // 1 MSBFirst, x11 >= 3.4) and then encodes every request LSBFirst
+    // regardless — so on a big-endian host the declared order and the actual
+    // encoding disagree and the connection is garbage from its first
+    // request, well before anything reaches us. Say so, rather than
+    // rendering nonsense. (An older x11 leaves the field undefined, which
+    // reads as LSBFirst and is right everywhere node-x11 currently works.)
+    if (display.byte_order) {
+      throw new Error(
+        'ntk: this X connection is MSBFirst (big-endian); node-x11 encodes requests ' +
+          'LSBFirst only, so the connection cannot be used'
+      );
+    }
     this.display = display;
     this.X = display.client;
     this.options = options;

package/lib/clipboard.js

@@ -27,21 +27,6 @@ import { safeRelease } from './cleanup.js';
 
 const DEFAULT_TIMEOUT = 2000;
 
-// SendEvent takes the raw 32-byte wire form of the event to deliver and
-// node-x11 has no packer for outgoing events, so build SelectionNotify
-// (code 31) by hand: CARD8 code, pad, CARD16 sequence (filled server-side),
-// TIMESTAMP, requestor WINDOW, then selection/target/property ATOMs.
-function encodeSelectionNotify(time, requestor, selection, target, property) {
-  const b = Buffer.alloc(32);
-  b[0] = 31;
-  b.writeUInt32LE(time >>> 0, 4);
-  b.writeUInt32LE(requestor >>> 0, 8);
-  b.writeUInt32LE(selection >>> 0, 12);
-  b.writeUInt32LE(target >>> 0, 16);
-  b.writeUInt32LE(property >>> 0, 20);
-  return b;
-}
-
 export default class Clipboard {
   constructor(app) {
     this.app = app;
@@ -192,11 +177,13 @@ export default class Clipboard {
       if (text === undefined) {
         property = 0; // raced with a SelectionClear we haven't seen yet
       } else if (ev.target === a.TARGETS) {
-        const data = Buffer.alloc(12);
-        data.writeUInt32LE(a.TARGETS, 0);
-        data.writeUInt32LE(a.UTF8_STRING, 4);
-        data.writeUInt32LE(X.atoms.STRING, 8);
-        X.ChangeProperty(0, ev.requestor, property, X.atoms.ATOM, 32, data);
+        // x11 >= 3.4 encodes a number array at the property's declared
+        // format, so this reaches the requestor as three CARD32 atoms
+        X.ChangeProperty(0, ev.requestor, property, X.atoms.ATOM, 32, [
+          a.TARGETS,
+          a.UTF8_STRING,
+          X.atoms.STRING
+        ]);
       } else if (ev.target === a.UTF8_STRING) {
         X.ChangeProperty(0, ev.requestor, property, a.UTF8_STRING, 8, Buffer.from(text, 'utf8'));
       } else if (ev.target === X.atoms.STRING) {
@@ -208,12 +195,17 @@ export default class Clipboard {
         // with property None per ICCCM
         property = 0;
       }
-      X.SendEvent(
-        ev.requestor,
-        0,
-        0,
-        encodeSelectionNotify(ev.time, ev.requestor, ev.selection, ev.target, property)
-      );
+      // mask 0: SelectionNotify is addressed to the requestor itself, so it
+      // goes to the client that created that window rather than to whoever
+      // selected events on it (ICCCM 2.2)
+      X.SendEvent(ev.requestor, 0, 0, {
+        name: 'SelectionNotify',
+        time: ev.time,
+        requestor: ev.requestor,
+        selection: ev.selection,
+        target: ev.target,
+        property
+      });
     });
   }
 

package/lib/cursor.js

@@ -23,10 +23,24 @@ export const cursorShapes = {
   'not-allowed': 0 // XC_X_cursor
 };
 
+/**
+ * The invisible cursor, spelled as CSS spells it. It is a name but not a
+ * shape: the 'cursor' font has no glyph meaning "no cursor", so this one is
+ * built from an empty bitmap instead of looked up. Kept out of
+ * `cursorShapes` for exactly that reason — every value in there is a glyph
+ * index, and this has none.
+ */
+export const BLANK_CURSOR = 'none';
+
+/** Every name `setCursor` accepts, for the error message and for docs. */
+export const cursorNames = [...Object.keys(cursorShapes), BLANK_CURSOR];
+
 /**
  * Resolve a friendly cursor name (see `cursorShapes`) or a raw cursor-font
  * glyph index to the glyph index. Throws on unknown names so typos surface
- * immediately instead of silently keeping the old cursor.
+ * immediately instead of silently keeping the old cursor. `'none'` is a
+ * valid cursor name but not a glyph, so it never reaches here — see
+ * `CursorCache.get`.
  */
 export function resolveCursorShape(nameOrShape) {
   if (typeof nameOrShape === 'number') {
@@ -38,7 +52,7 @@ export function resolveCursorShape(nameOrShape) {
   const shape = cursorShapes[nameOrShape];
   if (shape === undefined) {
     throw new Error(
-      `unknown cursor name '${nameOrShape}' — valid names: ${Object.keys(cursorShapes).join(', ')}`
+      `unknown cursor name '${nameOrShape}' — valid names: ${cursorNames.join(', ')}`
     );
   }
   return shape;
@@ -56,10 +70,12 @@ export class CursorCache {
     this.X = app.X;
     this._font = 0; // the 'cursor' font, opened on first use
     this._byShape = new Map(); // glyph index -> cursor xid
+    this._blank = 0; // the invisible cursor, built on first use
   }
 
   /** cursor xid for a friendly name or raw glyph index, creating it on first use */
   get(nameOrShape) {
+    if (nameOrShape === BLANK_CURSOR) return this.blank();
     const shape = resolveCursorShape(nameOrShape);
     const cached = this._byShape.get(shape);
     if (cached) return cached;
@@ -79,6 +95,41 @@ export class CursorCache {
     return cid;
   }
 
+  /**
+   * The invisible cursor, created once per connection. Hiding the pointer is
+   * not the same thing as X's cursor None, which means *inherit the parent's*
+   * — for a top-level window that is the root's cursor, so the pointer stays
+   * on screen. A cursor whose mask is empty is the way to hide it: mask bits
+   * that are 0 are not drawn, so a 1x1 all-zero mask draws nothing at all.
+   */
+  blank() {
+    if (this._blank) return this._blank;
+    const X = this.X;
+    const pid = X.AllocID();
+    // depth 1 — CreateCursor takes bitmaps, not pixmaps of the window depth
+    X.CreatePixmap(pid, X.display.screen[0].root, 1, 1, 1);
+    // a freshly created pixmap's contents are *undefined* per the protocol,
+    // so it has to be cleared. Skipping this is how the recipe ends up
+    // hiding the cursor on one server and drawing a stray pixel on another
+    const gc = X.AllocID();
+    X.CreateGC(gc, pid, { foreground: 0 });
+    X.PolyFillRectangle(pid, gc, [0, 0, 1, 1]);
+    X.FreeGC(gc);
+    X.ReleaseID(gc);
+
+    const cid = X.AllocID();
+    const black = { R: 0, G: 0, B: 0 };
+    // source and mask are the same empty bitmap; the colours are immaterial
+    // when nothing is drawn, but the request needs them
+    X.CreateCursor(cid, pid, pid, black, black, 0, 0);
+    // the cursor keeps its own copy of the bitmaps, so the pixmap goes now
+    // rather than living as long as the connection
+    X.FreePixmap(pid);
+    X.ReleaseID(pid);
+    this._blank = cid;
+    return cid;
+  }
+
   /** free the server-side cursors (and the font); safe to call repeatedly */
   dispose() {
     const X = this.X;
@@ -89,6 +140,14 @@ export class CursorCache {
       });
     }
     this._byShape.clear();
+    if (this._blank) {
+      const cid = this._blank;
+      this._blank = 0;
+      safeRelease(X, () => {
+        X.FreeCursor(cid);
+        X.ReleaseID(cid);
+      });
+    }
     if (this._font) {
       const fid = this._font;
       this._font = 0;

package/lib/events_map.js

@@ -64,6 +64,9 @@ export const mask = {
   destroy: x11.eventMask.StructureNotify,
   keyup: x11.eventMask.KeyRelease,
   property: x11.eventMask.PropertyChange,
+  // not an X event of its own: Window derives it from the PropertyNotify for
+  // _NET_WM_STATE, so it needs the same mask a 'property' listener does
+  statechange: x11.eventMask.PropertyChange,
   selection: 0,
   selection_request: 0,
   message: 0

package/lib/index.js

@@ -2,8 +2,9 @@ import x11 from 'x11';
 
 import App from './app.js';
 import Clipboard from './clipboard.js';
-import { CursorCache, cursorShapes, resolveCursorShape } from './cursor.js';
+import { BLANK_CURSOR, CursorCache, cursorNames, cursorShapes, resolveCursorShape } from './cursor.js';
 import Window from './window.js';
+import { decodeKey, groupForState } from './keyboard.js';
 import Pixmap from './pixmap.js';
 import Picture from './picture.js';
 import { Image, decodeImage, loadImage } from './image.js';
@@ -110,7 +111,9 @@ export {
   App,
   Clipboard,
   Window,
+  BLANK_CURSOR,
   CursorCache,
+  cursorNames,
   cursorShapes,
   resolveCursorShape,
   Pixmap,
@@ -138,7 +141,9 @@ export {
   cssColor,
   cssColorStraight,
   premultiply,
-  cssLength
+  cssLength,
+  decodeKey,
+  groupForState
 };
 // the yoga-layout instance ntk lays HtmlView out with — downstream layout
 // consumers (e.g. the react-x11 renderer) must share it to avoid loading a

package/lib/keyboard.js

@@ -0,0 +1,114 @@
+import { keysymToUnicode } from './text/keysym-unicode.js';
+
+// Turning a key event into a character.
+//
+// X's core keyboard map is a flat list of keysyms per keycode, and XKB lays
+// its groups over that list in pairs: [g1l1, g1l2, g2l1, g2l2, ...]. A layout
+// switch moves the *active group*, which arrives in bits 13-14 of every key
+// event's state field — the keymap itself does not change, so no
+// MappingNotify is sent and nothing can be refetched in response. Reading
+// those two bits is the whole of layout support for the common case.
+//
+// What this cannot do is level 3, the AltGr row. The core map is ambiguous
+// there: four keysyms on a keycode are two groups of two levels under
+// `us,ru`, and one group of four levels under `us(intl)`, and nothing in the
+// core protocol distinguishes them. The request that resolves it is
+// XkbGetMap, which node-x11 does not implement — its xkb module says so in
+// as many words. Guessing would break multi-layout users to half-serve
+// AltGr users, so this reads groups only.
+
+const SHIFT_MASK = 1;
+const LOCK_MASK = 2;
+
+// XKB reports the effective group in bits 13-14 of the core state field
+const GROUP_SHIFT = 13;
+const GROUP_MASK = 3;
+
+// Pairs, because that is all the core keyboard map can express
+const LEVELS_PER_GROUP = 2;
+
+/** The active XKB layout group, 0-3, from a key event's state field. */
+export function groupForState(state) {
+  return (state >> GROUP_SHIFT) & GROUP_MASK;
+}
+
+/** NoSymbol is 0, and a short keysym list simply ends. */
+function present(sym) {
+  return sym !== undefined && sym !== 0;
+}
+
+/**
+ * The character a keysym types, or undefined for keys that type nothing —
+ * arrows, function keys, modifiers.
+ */
+function charOf(sym) {
+  const cp = present(sym) ? keysymToUnicode(sym) : undefined;
+  return cp === undefined ? undefined : String.fromCodePoint(cp);
+}
+
+/**
+ * Whether a key's two levels are the lower and upper case of one letter.
+ *
+ * This is what decides whether CapsLock applies. XKB asks the key's *type*:
+ * its ALPHABETIC type folds Lock into the level, and the two-level type used
+ * for the number row does not — which is why CapsLock does not turn `1` into
+ * `!` on any real desktop. Unicode case mapping answers the same question
+ * without the XKB map, and answers it for Cyrillic and Greek too.
+ */
+function isCasePair(lowerChar, upperChar) {
+  if (lowerChar === undefined || upperChar === undefined) return false;
+  return lowerChar !== upperChar && lowerChar.toUpperCase() === upperChar;
+}
+
+/**
+ * Decode a key event against the keyboard map.
+ *
+ * @param {number[]} syms the keycode's keysyms, as `GetKeyboardMapping`
+ *   returns them — `X.keycode2keysyms[ev.keycode]`
+ * @param {number} state the event's modifier/group state (`ev.buttons`)
+ * @returns {{ keysym: number, baseKeysym: number, group: number,
+ *   codepoint: number|undefined }|undefined} undefined when the keycode maps
+ *   to nothing at all
+ */
+export function decodeKey(syms, state) {
+  if (!syms || syms.length === 0) return undefined;
+
+  const group = groupForState(state);
+  let base = group * LEVELS_PER_GROUP;
+  // X core protocol: a group with no symbols on this key falls back to
+  // group 1. Layouts differ in which keys they define, so this is normal —
+  // a Cyrillic layout leaves the function row to the Latin one.
+  if (!present(syms[base]) && !present(syms[base + 1])) base = 0;
+
+  const first = syms[base];
+  if (!present(first)) return undefined;
+  const firstChar = charOf(first);
+
+  let second = syms[base + 1];
+  let secondChar = charOf(second);
+  if (!present(second)) {
+    // "if the second element is NoSymbol, the group is treated as the lower
+    // and upper case of the first when the first has a case, and as the first
+    // twice otherwise" — X core protocol, Keyboard and Pointer. There is no
+    // uppercase *keysym* to name in that case, only an uppercase character.
+    second = first;
+    const upper = firstChar === undefined ? undefined : firstChar.toUpperCase();
+    secondChar = upper !== undefined && upper.length === 1 ? upper : firstChar;
+  }
+
+  const shift = (state & SHIFT_MASK) !== 0;
+  const lock = (state & LOCK_MASK) !== 0 && isCasePair(firstChar, secondChar);
+  const upperLevel = shift !== lock;
+
+  const keysym = upperLevel ? second : first;
+  const char = upperLevel ? secondChar : firstChar;
+  return {
+    keysym,
+    // group 1, level 1 — what a keyboard shortcut should match against, so
+    // Ctrl+Z stays Ctrl+Z while the user is typing Cyrillic. GTK, Qt and
+    // browsers all resolve accelerators this way.
+    baseKeysym: present(syms[0]) ? syms[0] : keysym,
+    group,
+    codepoint: char === undefined ? undefined : char.codePointAt(0)
+  };
+}