WINDOWSWM(3)

📦 version 1.0.1, in nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

Okay bestie, this is the WindowsWM manual page — that’s the manual name — and it’s the Cygwin/X rootless window management extension. Official vibe: WindowsWM - Cygwin/X rootless window management extension. Slay. 💅

✨ SYNTAX ✨

Here’s the include and the full function signatures, copied exactly so you can paste them into your notes. No cap, don’t rename anything:

#include <X11/extensions/windowswm.h>

Bool XWindowsWMQueryExtension (Display *dpy,
        int *event_base, int *error_base);

Status XWindowsWMQueryVersion (Display *dpy, int *majorVersion,
        int *minorVersion, int *patchVersion);

Bool XWindowsWMDisableUpdate (Display *dpy, int screen);

Bool XWindowsWMReenableUpdate (Display *dpy, int screen);

Bool XWindowsWMSelectInput (Display *dpy, unsigned long mask);

Bool XWindowsWMSetFrontProcess (Display *dpy);

Bool XWindowsWMFrameGetRect (Display *dpy,
        unsigned int frame_style,
        unsigned int frame_style_ex,
        unsigned int frame_rect,
        short inner_x, short inner_y,
        short inner_w, short inner_h,
        short *ret_x, short *ret_y,
        short *ret_w, short *ret_h);

Bool XWindowsWMFrameDraw (Display *dpy, int screen,
        Window window,
        unsigned int frame_style,
        unsigned int frame_style_ex,
        short inner_x, short inner_y,
        short inner_w, short inner_h);

Bool XWindowsWMFrameSetTitle (Display *dpy, int screen,
        Window window,
        unsigned int title_length,
        const char *title_bytes);

🎀 ARGUMENTS 🎀

  • dpy — specifies the connection to the X server. That’s your display hookup, bestie.
  • screen — specifies which screen.
  • mask — mask of event types the client is interested in.
  • window — specifies which window.
  • frame_style — specifies the style of window frame decoration.
  • frame_style_ex — specifies the extended style of window frame decoration.
  • frame_rect — specifies which rectangle to return from the window frame decoration.
  • inner_x,inner_y,inner_w,inner_h — rectangle of the window content inside the window frame decoration.

Also, because the signatures above are extra: XWindowsWMFrameGetRect carries ret_x, ret_y, ret_w, ret_h, and XWindowsWMFrameSetTitle carries title_length plus title_bytes. Those are in the SYNTAX block exactly, so don’t let them ghost you. 👻

🦋 DATATYPES 🦋

🫶 Events 🫶

This extension has one event struct you need to know about, and it’s called XWindowsWMNotifyEvent:

typedef struct {
    int type;               * of event *
    unsigned long serial;   * # of last request processed by server *
    Bool send_event;        * true if came from a SendEvent request *
    Display *display;       * Display the event was read from *
    Window window;          * window of event *
    Time time;              * server timestamp when event happened *
    int kind;               * subtype of event *
    int arg;
    int x;
    int y;
    int w;
    int h;
} XWindowsWMNotifyEvent;

XWindowsWMNotifyEvent is sent to a client who has requested notification of WindowsWM events with XWindowsWMSelectInput.

⭐ Event types:

#define WindowsWMControllerNotify               0
#define WindowsWMActivationNotify               1
#define WindowsWMNumberEvents                   2

⭐ Event masks:

#define WindowsWMControllerNotifyMask           (1L << 0)
#define WindowsWMActivationNotifyMask           (1L << 1)

⭐ Kinds of ControllerNotify events:

#define WindowsWMMinimizeWindow                 0
#define WindowsWMMaximizeWindow                 1
#define WindowsWMRestoreWindow                  2
#define WindowsWMCloseWindow                    3
#define WindowsWMBringAllToFront                4
#define WindowsWMHideWindow                     5
#define WindowsWMMoveWindow                     6
#define WindowsWMResizeWindow                   7
#define WindowsWMActivateWindow                 8

⭐ Kinds of ActivationNotify events:

#define WindowsWMIsActive                       0
#define WindowsWMIsInactive                     1

⭐ Errors:

#define WindowsWMClientNotLocal                 0
#define WindowsWMOperationNotSupported          1
#define WindowsWMNumberErrors                   2

💜 Window Parameters 💜

Values for frame_rect argument to XWindowsWMFrameGetRect:

#define WindowsWMFrameRectTitleBar              1
#define WindowsWMFrameRectTracking              2
#define WindowsWMFrameRectGrowBox               3

Window frame styles:

#define WindowsWMFrameStyleBorder               0x800000
#define WindowsWMFrameStyleCaption              0xc00000
#define WindowsWMFrameStyleChild                0x40000000
#define WindowsWMFrameStyleChildWindow          0x40000000
#define WindowsWMFrameStyleClipChildren         0x2000000
#define WindowsWMFrameStyleClipSiblings         0x4000000
#define WindowsWMFrameStyleDisabled             0x8000000
#define WindowsWMFrameStyleDlgFrame             0x400000
#define WindowsWMFrameStyleGroup                0x20000
#define WindowsWMFrameStyleHScroll              0x100000
#define WindowsWMFrameStyleIconic               0x20000000
#define WindowsWMFrameStyleMaximize             0x1000000
#define WindowsWMFrameStyleMaximizeBox          0x10000
#define WindowsWMFrameStyleMinimize             0x20000000
#define WindowsWMFrameStyleMinimizeBox          0x20000
#define WindowsWMFrameStyleOverlapped           0
#define WindowsWMFrameStyleOverlappedWindow     0xcf0000
#define WindowsWMFrameStylePopup                0x80000000
#define WindowsWMFrameStylePopupWindow          0x80880000
#define WindowsWMFrameStyleSizeBox              0x40000
#define WindowsWMFrameStyleSysMenu              0x80000
#define WindowsWMFrameStyleTabStop              0x10000
#define WindowsWMFrameStyleThickFrame           0x40000
#define WindowsWMFrameStyleTiled                0
#define WindowsWMFrameStyleTiledWindow          0xcf0000
#define WindowsWMFrameStyleVisible              0x10000000
#define WindowsWMFrameStyleVScroll              0x200000

Window frame extended styles:

#define WindowsWMFrameStyleExAcceptFiles        16
#define WindowsWMFrameStyleExAppWindow          0x40000
#define WindowsWMFrameStyleExClientEdge         512
#define WindowsWMFrameStyleExComposited         0x2000000
#define WindowsWMFrameStyleExContextHelp        0x400
#define WindowsWMFrameStyleExControlParent      0x10000
#define WindowsWMFrameStyleExDlgModalFrame      1
#define WindowsWMFrameStyleExLayered            0x80000
#define WindowsWMFrameStyleExLayoutRtl          0x400000
#define WindowsWMFrameStyleExLeft               0
#define WindowsWMFrameStyleExLeftScrollBar      0x4000
#define WindowsWMFrameStyleExLtrReading         0
#define WindowsWMFrameStyleExMDIChild           64
#define WindowsWMFrameStyleExNoActivate         0x8000000
#define WindowsWMFrameStyleExNoInheritLayout    0x100000
#define WindowsWMFrameStyleExNoParentNotify     4
#define WindowsWMFrameStyleExOverlappedWindow   0x300
#define WindowsWMFrameStyleExPaletteWindow      0x188
#define WindowsWMFrameStyleExRight              0x1000
#define WindowsWMFrameStyleExRightScrollBar     0
#define WindowsWMFrameStyleExRtlReading         0x2000
#define WindowsWMFrameStyleExStaticEdge         0x20000
#define WindowsWMFrameStyleExToolWindow         128
#define WindowsWMFrameStyleExTopMost            8
#define WindowsWMFrameStyleExTransparent        32
#define WindowsWMFrameStyleExWindowEdge         256

🌈 DESCRIPTION 🌈

WindowsWM is a simple library designed to interface with the Windows-WM extension. This extension allows X window managers to better interact with the Cygwin XWin server when running X11 in a rootless mode. That’s the whole plot. 🫶

Also, the page literally says: “A more complete description will be forthcoming eventually.” So if you were hoping for more lore, bestie, same. 🙈

💖 FUNCTIONS 💖

  • XWindowsWMDisableUpdate — causes any updates to the windows on the screen to be queued until updates are reenabled with XWindowsWMReenableUpdate. This is useful to avoid intermediate redraws to the screen if a number of changes are going to be made at once. Updates should only be disabled temporarily while drawing to a window. These calls may be nested and each call to XWindowsWMDisableUpdate must be paired with a subsequent call to XWindowsWMReenableUpdate. Updating is not reenabled until the last unnested call to XWindowsWMReenableUpdate. Disabling updates applies to window content; however, it is implementation dependent whether window size and position changes are disabled as well. That “temporarily” is doing real work — don’t leave updates off forever, okay? 💀
  • XWindowsWMSelectInput — is used to request that a client receive notification of the WindowsWM events listed above. The event mask specifies the event types the client is interested in receiving. Passing an event mask of 0 stops notification of events.
  • XWindowsWMSetFrontProcess — directs the X server to make itself the front most application among all the other Windows applications. This causes X11 windows to move above other applications' windows and for the X server to start receiving keyboard and mouse events. Main character energy for the X server, honestly. 👑
  • XWindowsWMFrameDraw — can be used to decorate a top-level window with the standard Windows window frame and widgets. The frame_style controls the overall look of the window frame and frame_style_ex specifies the extended window style attributes. The dimensions of the X11 window content are passed as the inner_* rectangle. XWindowsWMFrameGetRect is used to calculate the size of the rectangle from the size of the window content, which is being reparented.
  • XWindowsWMFrameSetTitle — can be used to set the title of the Windows window decoration.
  • XWindowsWMFrameGetRect — returns a rectangle that encloses an element of the window frame decoration. The frame_rect argument specifies the element of interest. The inner_* rectangle (as described above) specifies the window geometry. If WindowsWMFrameRectTitleBar is passed for frame_rect, the inner_* parameters are ignored. The WindowsWMFrameRectTracking and WindowsWMFrameRectGrowBox rectangles are primarily intended to be used by the window manager to determine the correct placement for child windows to receive events. The tracking rectangle is the area of the window containing the close, collapse and zoom boxes. Typically when the cursor is over this area, the window manager will highlight the close, collapse, and zoom buttons to conform to the standard Aqua interface.
  • Other functions — include XWindowsWMQueryExtension, which returns the event and error base codes, and XWindowsWMQueryVersion, which returns the current version of the extension. (This information is cached by the library.) Iykyk. ✨

👑 RESTRICTIONS 👑

WindowsWM is only intended to be used on Cygwin when running a rootless XWin server. Periodt. 🎀

💖 That’s the whole manual, bestie: source/version vibes are XFree86, Version 1.0, and the filed page is WINDOWSWM(3). Go forth and rootlessly slay. 🦋✨

📦 where this page comes from