ntk 4.1.0 → 4.2.0

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/index.js

@@ -2,7 +2,7 @@ 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';
@@ -111,7 +111,9 @@ export {
   App,
   Clipboard,
   Window,
+  BLANK_CURSOR,
   CursorCache,
+  cursorNames,
   cursorShapes,
   resolveCursorShape,
   Pixmap,

package/lib/window.js

@@ -1763,9 +1763,15 @@ export default class Window extends Drawable {
    * Set the mouse cursor shown over this window. Accepts a friendly name
    * ('text', 'pointer', 'wait', ... — see cursorShapes in lib/cursor.js and
    * docs/window.md) or a raw X11 cursor-font glyph index. Cursors are
-   * created once per connection and cached on the app. `setCursor(null)`
-   * restores the parent window's cursor (X cursor = None). Throws
-   * synchronously on unknown names.
+   * created once per connection and cached on the app. Throws synchronously
+   * on unknown names.
+   *
+   * Two things that sound alike and are not:
+   *
+   *   setCursor('none')  the pointer is invisible over this window
+   *   setCursor(null)    X cursor None — *inherit* the parent's cursor,
+   *                      which for a top-level window is the root's, so the
+   *                      pointer stays visible
    */
   setCursor(nameOrShape) {
     const cursor = nameOrShape == null ? 0 : this.app.cursors.get(nameOrShape);

package/package.json

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