Skip to main content

App

An App represents one connection to an X server and is the factory for windows and pixmaps.

createClient([options], [callback]) → Promise<App>​

import { createClient } from 'ntk';
const app = await createClient();           // uses $DISPLAY
const app2 = await createClient({ display: ':1' });
  • options is passed through to x11.createClient (e.g. { display: ':1' }). ntk additionally understands:
    • fontSource — pluggable system-font lookup for app.fonts (see fonts.md);
    • glxVisual — visual id getContext('opengl') should use instead of querying the server for one (see context-opengl.md);
    • onXError — called with X protocol errors that no request callback claimed (races like a request landing after its window was destroyed). Defaults to a console.warn; without any listener node-x11's error emit would throw inside its packet parser and wedge the connection.
  • The XRender extension is preloaded (required for the 2d context). GLX is preloaded when available; app.display.GLX is null when the server has no GLX support.
  • Keyboard mapping is fetched up front and kept up to date on MappingNotify, so keydown events carry codepoint.
  • A big-endian (MSBFirst) connection is rejected with an error. node-x11 declares the host byte order in its connection hello but encodes every request LSBFirst regardless, so such a connection is already inconsistent before ntk sees it; failing here beats decoding byte-swapped properties into plausible-looking nonsense.
  • The legacy node-style callback is also supported.

Properties​

  • app.display — the node-x11 display object (screen, Render, GLX, …)
  • app.X — the raw node-x11 client, for direct protocol requests
  • app.fonts — lazy FontManager: font matching/loading, shaping
  • app.clipboard — lazy Clipboard: selection/clipboard text transfer (write()/read())

Methods​

  • app.createWindow(args) → Window — see window.md
  • app.rootWindow() → Window — wrapper for the first screen's root window
  • app.createPixmap(args) → Pixmap — see pixmap.md
  • app.createColormap(visual, screen = 0) → id — allocate a colormap for a visual (alloc None). Windows created with an explicit visual get one automatically, so this is only needed to share one between windows
  • app.chooseGLXConfig(spec) → Promise<config> — pick a GLX-capable visual by querying the server; config.visual/config.depth feed createWindow and the whole object feeds getContext('opengl', config). See context-opengl.md
  • app.close() → Promise — flush pending requests, then close the connection

Resource management​

App implements both Symbol.asyncDispose (flush + close, prefer this) and Symbol.dispose (immediate terminate):

await using app = await createClient();
// connection closed automatically at end of scope

See resource-management.md.