ntk 4.1.0 → 4.3.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

@@ -693,6 +693,66 @@ export default class Window extends Drawable {
     });
   }
 
+  /**
+   * Scroll the pixels of `rect` (window coordinates, `{x, y, width, height}`)
+   * by (dx, dy) within the retained backing store, server-side: one CopyArea
+   * of the band that survives the shift, in place of the caller re-drawing
+   * everything that merely moved. Returns true when the blit was issued;
+   * false means "not possible here", and the caller repaints `rect` exactly
+   * as it would have without this method — every refusal is the status quo.
+   *
+   * Refused when there is no (valid) backing store, when the delta is
+   * fractional (a sub-pixel shift changes every pixel, so there is nothing
+   * to copy), when it is zero, or when nothing of `rect` survives the shift
+   * after clamping to window ∩ backing.
+   *
+   * Backing-store only, deliberately: pixmap contents cannot be occluded, so
+   * an overlapping self-copy is fully defined (the server fetches the source
+   * region before storing) and the GraphicsExpose handling a window-drawable
+   * scroll would need never exists. The copy goes out with the present GC —
+   * graphicsExposures: 0, where the 2d context's GC would emit a NoExposure
+   * packet per copy — and in-order with the caller's follow-up drawing of
+   * the exposed strip on the same connection.
+   *
+   * The whole of `rect` is marked dirty, so the next present shows the
+   * scrolled band through the normal fence-aware path; the caller only has
+   * to draw the strip the shift exposed, plus any chrome that moved with
+   * the content (a scrollbar thumb, say).
+   */
+  scrollRegion(rect, dx, dy) {
+    if (!this._backing || !this._backingValid) return false;
+    if (!Number.isInteger(dx) || !Number.isInteger(dy) || (dx === 0 && dy === 0)) return false;
+    // clamp like a present: the backing is grow-only, so it can be larger
+    // than the window after a shrink
+    const w = Math.min(this.width, this._backing.width);
+    const h = Math.min(this.height, this._backing.height);
+    const x0 = Math.max(0, Math.floor(rect.x));
+    const y0 = Math.max(0, Math.floor(rect.y));
+    const x1 = Math.min(w, Math.ceil(rect.x + rect.width));
+    const y1 = Math.min(h, Math.ceil(rect.y + rect.height));
+    // the band that survives: dest = clamped rect ∩ (clamped rect + delta)
+    const dstX0 = Math.max(x0, x0 + dx);
+    const dstY0 = Math.max(y0, y0 + dy);
+    const dstX1 = Math.min(x1, x1 + dx);
+    const dstY1 = Math.min(y1, y1 + dy);
+    if (dstX1 <= dstX0 || dstY1 <= dstY0) return false;
+    safeRelease(this.X, () => {
+      this.X.CopyArea(
+        this._backing.id,
+        this._backing.id,
+        this._presentGc,
+        dstX0 - dx,
+        dstY0 - dy,
+        dstX0,
+        dstY0,
+        dstX1 - dstX0,
+        dstY1 - dstY0
+      );
+    });
+    this._markDirty({ x: x0, y: y0, w: x1 - x0, h: y1 - y0 });
+    return true;
+  }
+
   /*
    * Frame clock. Noisy events (see events_map coalesce), synthetic redraws
    * and requestAnimationFrame callbacks are delivered in "frames", paced by
@@ -1763,9 +1823,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.3.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",