Skip to main content

Apple-WM extension

XQuartz-specific extension letting an X11 window manager cooperate with the macOS native environment: draw Aqua-style window frames, control window levels relative to native apps, and receive notifications from the X11.app controller (menu commands, app activation, pasteboard). Only available on the XQuartz server on macOS.

X.require('apple-wm', (err, AppleWM) => {
    AppleWM.QueryVersion((err, [major, minor, patch]) => {});
    AppleWM.SelectInput(AppleWM.NotifyMask.All);
    AppleWM.SetWindowLevel(win, AppleWM.WindowLevel.Floating);
    X.on('event', ev => {
        if (ev.name === 'AppleWMControllerNotify' &&
            ev.type === AppleWM.EventKind.Controller.CloseWindow) {
            // user picked Close from the native menu
        }
    });
});

No version negotiation happens during require; call QueryVersion yourself if needed.

Frame requests take two rectangles describing the window: the inner (client) rect ix, iy, iw, ih and the outer (frame) rect ox, oy, ow, oh, all as unsigned 16-bit values.

Requests​

Listed in minor opcode order.

QueryVersion(cb)​

Minor opcode 0. cb(err, [major, minor, patch]) — extension version.

FrameGetRect(frameClass, frameRect, ix, iy, iw, ih, ox, oy, ow, oh, cb)​

Minor opcode 1. Computes the geometry of a frame part for a window with the given inner/outer rects. frameClass is a FrameClass value, frameRect a FrameRect value (Titlebar/Tracking/Growbox). cb(err, {x, y, w, h}) — the requested part's rectangle.

FrameHitTest(frameClass, px, py, ix, iy, iw, ih, ox, oy, ow, oh, cb)​

Minor opcode 2. Hit-tests point px, py against the frame of a window with the given rects. cb(err, hit) — numeric hit-test result (0 when no frame part is hit).

FrameDraw(screen, window, frameClass, attr, ix, iy, iw, ih, ox, oy, ow, oh, title)​

Minor opcode 3. Draws a native-styled frame for window on screen. frameClass is a FrameClass value, attr a bitmask of FrameAttr flags, title the titlebar string. No reply.

DisableUpdate(screen)​

Minor opcode 4. Temporarily suppresses compositing updates for screen (default 0) while a batch of drawing happens. Pair with ReenableUpdate. No reply.

ReenableUpdate(screen)​

Minor opcode 5. Re-enables updates suppressed by DisableUpdate. No reply.

SelectInput(mask)​

Minor opcode 6. Selects which Apple-WM notification events this client receives; mask is a bitmask of NotifyMask values. No reply.

SetWindowMenuCheck(index)​

Minor opcode 7. Places the checkmark on item index (0-based) of the X11.app Window menu previously set with SetWindowMenu. No reply.

SetFrontProcess()​

Minor opcode 8. Asks macOS to bring the X server (XQuartz) to the front, above native applications. No arguments, no reply.

SetWindowLevel(window, level)​

Minor opcode 9. Places window in one of the native window layers; level is a WindowLevel value. No reply.

CanQuit(state)​

Minor opcode 10. Tells the server whether it may quit (non-zero state = the window manager consents; the server asks via the controller events before quitting). No reply.

SetWindowMenu(items)​

Minor opcode 11. Replaces the window-manager section of the X11.app Window menu. items is an array where each element is either a plain string label or a [shortcut, label] pair (shortcut a single ASCII character used as the Cmd-key equivalent). No reply.

SendPSN(hi, lo)​

Minor opcode 12. Sends the window manager's macOS Process Serial Number (64 bits as two 32-bit halves) to the server. No reply.

AttachTransient(child, parent)​

Minor opcode 13. Marks window child as a transient attached to parent (sheet-like native behavior). Pass parent = 0 to detach. No reply.

Events​

Enable delivery with SelectInput. All three events share one parsed shape: {name, type, time, arg} where name is the event name below, type is the kind code (see EventKind), time is the server timestamp and arg is a kind-specific 32-bit argument (e.g. the window id for per-window controller actions).

AppleWMControllerNotify​

First event + 0, selected by NotifyMask.Controller. Sent when the user drives X11 windows from the native side. type is one of EventKind.Controller: MinimizeWindow 0, ZoomWindow 1, CloseWindow 2, BringAllToFront 3, WideWindow 4, HideAll 5, ShowAll 6, WindowMenuItem 9, WindowMenuNotify 10, NextWindow 11, PreviousWindow 12.

AppleWMActivationNotify​

First event + 1, selected by NotifyMask.Activation. X11.app gained or lost the native foreground. type is one of EventKind.Activation: IsActive 0, IsInactive 1, ReloadPreferences 2.

AppleWMPasteboardNotify​

First event + 2, selected by NotifyMask.Pasteboard. type is EventKind.Pasteboard.CopyToPasteboard (0) — the server wants the current selection copied to the macOS pasteboard.

Notes​

Enums attached to the extension object:

  • AppleWM.FrameRect = {Titlebar: 1, Tracking: 2, Growbox: 3}
  • AppleWM.FrameClass = {DecorLarge: 1, DecorSmall: 16, Managed: 1<<15, Transient: 1<<16, Stationary: 1<<17} (plus Reserved* placeholder bits)
  • AppleWM.FrameAttr = {Active: 1, Urgent: 2, Title: 4, Prelight: 8, Shaded: 16, CloseBox: 0x100, Collapse: 0x200, Zoom: 0x400, CloseBoxClicked: 0x800, CollapseBoxClicked: 0x1000, ZoomBoxClicked: 0x2000, GrowBox: 0x4000}
  • AppleWM.NotifyMask = {Controller: 1, Activation: 2, Pasteboard: 4, All: 7}
  • AppleWM.WindowLevel = {Normal: 0, Floating: 1, TornOff: 2, Dock: 3, Desktop: 4}
  • AppleWM.EventKind = {Controller: {...}, Activation: {...}, Pasteboard: {...}} (values listed under Events above)

Requires XQuartz; on any other server X.require('apple-wm', cb) calls back with an "extension not available" error.