sxwm developer docs

Table of Contents

• Headers

• sxwm.c

  • Function Table
  • Functions

Headers

sxwm.c

Function Table

Functions

Below, each entry shows the compact signature and a detailed description. Use anchors in the table to jump here.

add_client

(Window w, int ws) -> Client *

Returns NULL on allocation failure.

Create and register a client in workspace ws. Select inputs, grab mouse
buttons, set protocols (WM_DELETE_WINDOW), capture initial geometry, set
monitor by cursor position, set _NET_WM_DESKTOP, and raise the window.
Sets global focus if it is the first client in the current workspace.

apply_fullscreen

(Client *c, Bool on) -> void

Enter: save geometry, clear floating, set fullscreen, remove borders,
resize to monitor bounds, raise, set EWMH state. Exit: restore geometry
and border, clear state, recompute monitor if tiled, then retile and
repaint borders.

centre_window

(void) -> void

If the focused client exists, is mapped and floating, move it to the
center of its current monitor workarea and apply via XMoveWindow.

change_workspace

(int ws) -> void

Abort if ws is invalid or already current. Grab server. Remember which
scratchpads are visible and unmap them. Unmap all non-scratchpad windows
in the current workspace. Switch current_ws, remap windows in the target
workspace, move visible scratchpads into the new workspace, and map them.
Retile, choose focus (prefer visible scratchpad, else first window on the
current monitor), set input focus, update _NET_CURRENT_DESKTOP and
per-client _NET_WM_DESKTOP. Ungrab server and sync. Maintain
previous_workspace and in_ws_switch flags.

check_parent

(pid_t p, pid_t c) -> int

Walk the process tree via get_parent_process until p or 0 is reached.
Return c if p is an ancestor of c, else 0.

clean_mask

(int mask) -> int

Strip LockMask, NumLock, and Mode_switch bits so key matching is stable.

close_focused

(void) -> void

If focused exists, clear scratchpad binding if any. If the client supports
WM_DELETE_WINDOW, send a ClientMessage. Otherwise unmap and kill the
client. Layout updates are handled by subsequent notifications.

dec_gaps

(void) -> void

If user_config.gaps > 0, decrement and retile, then repaint borders.

find_client

(Window w) -> Client *

Linear search across all workspaces for a client with top-level window w.

find_toplevel

(Window w) -> Window

Walk up the X window tree via XQueryTree until the root parent is reached
and return that top-level window id.

focus_next

(void) -> void

From the current focus (or head), loop forward (wrap) to the next mapped
client on current_mon. If found, set focus and call set_input_focus.

focus_prev

(void) -> void

From the current focus (or head), walk backward (wrap) to the previous
mapped client on current_mon. If found, set focus and call set_input_focus.

focus_next_mon

(void) -> void

If multiple monitors, focus the first mapped, non-fullscreen client on the
next monitor. If none exist, warp the pointer to the next monitor center.

focus_prev_mon

(void) -> void

Same as focus_next_mon but targeting the previous monitor.

get_monitor_for

(Client *c) -> int

Compute the client center and return the monitor whose bounds contain it.
Fallback to 0 if none match.

get_parent_process

(pid_t c) -> pid_t

Read /proc/%u/stat and parse the parent PID for process c. Return 0 on
failure.

get_pid

(Window w) -> pid_t

Read _NET_WM_PID from the window as a 32-bit XA_CARDINAL and return it, or
0 if missing.

get_workspace_for_window

(Window w) -> int

Check XClassHint against user_config.open_in_workspace rules. If a class
or name matches, return that workspace id. Else return current_ws.

grab_button

(Mask button, Mask mod, Window w, Bool owner_events, Mask masks) -> void

Call XGrabButton with async mode on root and sync on non-root windows.

grab_keys

(void) -> void

Ungrab all keys, then for each binding in user_config.binds, compute
keycode and grab with guard modifier combinations so bindings remain
usable with Lock, NumLock, or Mode_switch active.

hdl_button

(XEvent *xev) -> void

ButtonPress handler. On tiled windows:

• Mod+Shift+Left: begin swap drag (DRAG_SWAP).
• Mod+Left or Mod+Right: toggle_floating to allow drag.
• Plain Left: focus the clicked window.

On floating windows, begin DRAG_MOVE (left) or DRAG_RESIZE (right),
recording drag origin and grabbing the pointer.

hdl_button_release

(XEvent *xev) -> void

If in DRAG_SWAP and a target is set, swap clients, retile, and repaint.
Always ungrab the pointer and clear drag state.

hdl_client_msg

(XEvent *xev) -> void

Handle _NET_CURRENT_DESKTOP by calling change_workspace. Handle
_NET_WM_STATE actions for _NET_WM_STATE_FULLSCREEN: add/remove/toggle via
apply_fullscreen and raise on entry.

hdl_config_ntf

(XEvent *xev) -> void

On root ConfigureNotify, refresh monitors, retile, and repaint borders.

hdl_config_req

(XEvent *xev) -> void

Honor ConfigureRequest for floating or fullscreen clients by forwarding
geometry. Ignore for tiled clients (layout is enforced by WM).

hdl_dummy

(XEvent *xev) -> void

No operation.

hdl_destroy_ntf

(XEvent *xev) -> void

Unlink the destroyed client. If it swallowed another, remap it. If it was
swallowed, remap the swallower. Pick a new focus on the same monitor if
possible. Update _NET_CLIENT_LIST, retile current workspace, repaint, and
refocus if applicable.

hdl_keypress

(XEvent *xev) -> void

Match keycode+mods (cleaned) against user_config.binds and dispatch:

• TYPE_CMD: spawn argv
• TYPE_FUNC: call function
• TYPE_WS_CHANGE / TYPE_WS_MOVE
• TYPE_SP_REMOVE / TYPE_SP_TOGGLE / TYPE_SP_CREATE
  Update _NET_CLIENT_LIST when workspace topology changes.

hdl_mapping_ntf

(XEvent *xev) -> void

Refresh keyboard mapping, detect modifier masks, and regrab keys.

hdl_map_req

(XEvent *xev) -> void

Ignore invisible or override-redirect windows. If already managed and on
current workspace, ensure mapped and optionally focus. Otherwise:
classify window type, decide floating or tiled (consider utility/dialog,
modal, size hints, transient), enforce max clients, choose target
workspace via rules, call add_client, set WM_STATE, center floating, set
borders, attempt swallowing (class rules + parent PID), honor requested
fullscreen, map if on current workspace, and update borders/focus.

hdl_motion

(XEvent *xev) -> void

Throttle by motion_throttle. Identify monitor under pointer. For DRAG_SWAP
track hovered tiled target and show swap border. For DRAG_MOVE compute new
position, apply snapping inside monitor workarea, auto-toggle to floating
if moved far enough, and move window. For DRAG_RESIZE grow from bottom
right and clamp to monitor workarea.

hdl_property_ntf

(XEvent *xev) -> void

On root:

• _NET_CURRENT_DESKTOP: read and change_workspace.
• _NET_WM_STRUT_PARTIAL: update_struts, retile, repaint.

On client:

• _NET_WM_STATE: mirror fullscreen flag using apply_fullscreen.

hdl_unmap_ntf

(XEvent *xev) -> void

If not switching workspaces, mark the client as unmapped. Update client
list, retile, and repaint.

inc_gaps

(void) -> void

Increment gaps and retile, then repaint borders.

init_defaults

(void) -> void

Fill default_config (modkey, gaps, border colors via parse_col, movement
steps, per-monitor master widths, rule arrays, throttles, snap distance,
and flags). Copy to user_config.

is_child_proc

(pid_t parent_pid, pid_t child_pid) -> Bool

Walk PPID chain up to a limit using /proc. Return True if parent_pid is
found. Print simple diagnostics on failures.

move_master_next

(void) -> void

Rotate the head node to the tail of the current workspace list. Retile,
optionally warp to the old focused window, send WM_TAKE_FOCUS, repaint.

move_master_prev

(void) -> void

Move the tail node to head (becomes new master). Retile, optional warp,
send focus, repaint.

move_next_mon

(void) -> void

If focused and multiple monitors, reassign focused to next monitor. If
floating, center and clamp inside the target monitor. Retile and optionally
warp cursor. Repaint.

move_prev_mon

(void) -> void

Same as move_next_mon but previous monitor.

move_to_workspace

(int ws) -> void

Unmap focused, unlink from current list, push to target workspace head,
update _NET_WM_DESKTOP, retile current workspace, and refocus its head.

move_win_down

(void) -> void

For a focused floating client, move by move_window_amt down via XMoveWindow.

move_win_left

(void) -> void

For a focused floating client, move left by move_window_amt.

move_win_right

(void) -> void

For a focused floating client, move right by move_window_amt.

move_win_up

(void) -> void

For a focused floating client, move up by move_window_amt.

other_wm

(void) -> void

Temporarily set error handler to other_wm_err, attempt to select
SubstructureRedirectMask on root to detect another WM, then restore.

other_wm_err

(Display *d, XErrorEvent *ee) -> int

Always exits with failure.

Print a message and exit because another WM has the redirect. Returns 0
but does not reach caller.

parse_col

(const char *hex) -> long

Parse and allocate an XColor from a hex string. On failure, return the
default white pixel. OR 0xff into the high byte to set an alpha-like
component and return the pixel.

quit

(void) -> void

Close display and free cursors. Print a message and clear running flag.
Optional mass-kill code is commented out.

reload_config

(void) -> void

Free binding commands and rule arrays, wipe user_config, re-init defaults,
re-parse config (fallback to defaults on error), regrab keys and buttons
on root and clients, rebuild root grabs, update desktop props and client
list, sync, retile, and repaint.

remove_scratchpad

(int n) -> void

If scratchpad slot n holds a client, remap it and clear the slot. Update
client list and borders.

resize_master_add

(void) -> void

Increase user_config.master_width for the focused monitor by
resize_master_amt (bounded). Retile and repaint.

resize_master_sub

(void) -> void

Decrease user_config.master_width for the focused monitor by
resize_master_amt (bounded). Retile and repaint.

resize_stack_add

(void) -> void

If focused is a stack client (tiled and not master), increase its
custom_stack_height by resize_stack_amt and retile.

resize_stack_sub

(void) -> void

If focused is a stack client, decrease custom_stack_height (bounded to a
minimum) and retile.

resize_win_down

(void) -> void

If focused is floating, grow height by resize_window_amt, clamp to monitor
workarea, and apply via XResizeWindow.

resize_win_left

(void) -> void

If focused is floating, shrink width by resize_window_amt (bounded), and
apply.

resize_win_right

(void) -> void

If focused is floating, grow width by resize_window_amt (bounded), and
apply.

resize_win_up

(void) -> void

If focused is floating, shrink height by resize_window_amt (bounded), and
apply.

run

(void) -> void

Set running flag and loop on XNextEvent, dispatching through xev_case
until running is cleared.

reset_opacity

(Window w) -> void

Delete _NET_WM_WINDOW_OPACITY property to restore default compositor
opacity.

scan_existing_windows

(void) -> void

Query root children. For each viewable, non-override-redirect child,
synthesize a MapRequest and feed it to hdl_map_req so sxwm begins
managing existing windows on startup.

select_input

(Window w, Mask masks) -> void

Wrapper for XSelectInput.

send_wm_take_focus

(Window w) -> void

If the window supports WM_TAKE_FOCUS, send the ClientMessage so clients
that require it can accept focus.

setup

(void) -> void

Open display, set root, setup_atoms, probe for other WM, load defaults and
parse config, compute modifier masks, grab keys, run autostart, load and
set cursors, cache screen size, update monitors, select root events,
grab root mouse buttons, initialize event table, scan existing windows,
and ignore SIGCHLD to prevent zombies.

setup_atoms

(void) -> void

Intern all required EWMH/ICCCM atoms, create _NET_SUPPORTING_WM_CHECK,
publish number of desktops, names, current desktop, supported atom list
on root, and compute initial workarea.

set_frame_extents

(Window w) -> void

Write border width on all four sides to _NET_FRAME_EXTENTS.

set_input_focus

(Client *c, Bool raise_win, Bool warp) -> void

If c is mapped: set global focus, call XSetInputFocus on toplevel, send
WM_TAKE_FOCUS, optionally raise if floating, publish _NET_ACTIVE_WINDOW,
repaint borders, and optionally warp pointer. If c is NULL: focus root
and clear _NET_ACTIVE_WINDOW. Flush.

set_opacity

(Window w, double opacity) -> void

Clamp opacity to [0.0, 1.0], convert to 32-bit fixed point, and write
_NET_WM_WINDOW_OPACITY.

set_win_scratchpad

(int n) -> void

Assign focused window to scratchpad slot n by storing and unmapping it.
If a different client was already in the slot, remap it and clear the
slot first.

set_wm_state

(Window w, long state) -> void

Write ICCCM WM_STATE with state and None icon window.

snap_coordinate

(int pos, int size, int screen_size, int snap_dist) -> int

Snap left edge to 0 or right edge to screen_size when within snap_dist,
otherwise return pos unchanged.

spawn

(const char * const *argv) -> void

Split argv by "|" into N commands, create N-1 pipes, fork N children,
wire stdin/stdout with dup2, execvp each stage, close fds in parent, and
free temporary allocations. Close the X connection fd in children.

startup_exec

(void) -> void

For each non-NULL user_config.to_run[i], build argv, call spawn, and free
argv pieces.

swallow_window

(Client *swallower, Client *swallowed) -> void

If eligible and not already linked: unmap swallower, link both ways, copy
geometry/floating state, move/resize swallowed if floating, retile and
repaint.

swap_clients

(Client *a, Client *b) -> void

Swap two nodes in the singly-linked list of the current workspace,
handling the adjacent case and the general case.

switch_previous_workspace

(void) -> void

Call change_workspace(previous_workspace).

tile

(void) -> void

Recompute struts, then for each monitor: build list of visible, non-
floating, non-fullscreen clients on that monitor. If monocle layout enabled, configure
every window to take all the space then leave. Otherwise, places master at left
with width master_width[m], stack on right with gaps. Compute stack
heights using per-client custom_stack_height or auto-split; enforce
minimums and absorb rounding remainder at bottom. Configure windows,
optionally raise floating windows, and repaint borders. Skip layout if a
single fullscreen client exists.

toggle_floating

(void) -> void

Toggle focused floating state. If leaving fullscreen, clear it and restore
borders. When entering floating, capture current server-side geometry.
When leaving floating, recompute monitor. Retile, repaint, and if floating,
raise and refocus.

toggle_floating_global

(void) -> void

Flip global_floating. If any tiled exists, set all to floating (storing
current geometry) and raise them; otherwise leave state. Retile and repaint.

toggle_fullscreen

(void) -> void

Toggle fullscreen on focused via apply_fullscreen.

toggle_monocle

(void) -> void

Enable/disable the monocle layout. Most of the logic is near the top of tile

toggle_scratchpad

(int n) -> void

Move scratchpad n into current workspace if needed. Update _NET_WM_DESKTOP,
set its monitor to the focused monitor, and map or unmap. On mapping,
focus it. Retile, repaint, and update client list.

unswallow_window

(Client *c) -> void

If c has a swallower, unlink the relation, remap the swallower, focus it,
then retile and repaint.

update_borders

(void) -> void

Set border pixel for each client on the current workspace to focused or
unfocused color. Publish _NET_ACTIVE_WINDOW with focused id if any.

update_client_desktop_properties

(void) -> void

For every client in every workspace, write its _NET_WM_DESKTOP value.

update_modifier_masks

(void) -> void

Read X modifier mapping; detect which modifier bit holds Num_Lock and
Mode_switch keycodes. Update numlock_mask and mode_switch_mask.

update_mons

(void) -> void

Free old monitor array, query Xinerama for screens if active, else fall
back to a single monitor covering the display. Define cursor for each
screen root.

update_net_client_list

(void) -> void

Flatten all client windows and write _NET_CLIENT_LIST on root.

update_struts

(void) -> void

Reset reserves on monitors. For each DOCK window, read
_NET_WM_STRUT_PARTIAL and expand per-monitor reserves based on the dock
location. Update workarea afterward.

update_workarea

(void) -> void

Publish per-monitor workareas (x, y, w, h) to _NET_WORKAREA.

warp_cursor

(Client *c) -> void

Move pointer to the window center on root and sync.

window_has_ewmh_state

(Window w, Atom state) -> Bool

Read _NET_WM_STATE and test for membership of state.

window_set_ewmh_state

(Window w, Atom state, Bool add) -> void

Read existing _NET_WM_STATE, rebuild the list without state, and append
state if add is True. Write the result or delete the property if empty.

window_should_float

(Window w) -> Bool

Check XClassHint and match name/class against user_config.should_float.

window_should_start_fullscreen

(Window w) -> Bool

Check XClassHint and match name/class against user_config.start_fullscreen.

xerr

(Display *d, XErrorEvent *ee) -> int

Ignore common benign X errors (BadWindow, BadDrawable, BadMatch) and
return 0.

xev_case

(XEvent *xev) -> void

If type is in range, dispatch to evtable[type]. Otherwise print an error.

main

(int ac, char **av) -> int

EXIT_SUCCESS

If -v or --version, print version, author, and license info. Otherwise
call setup(), print "sxwm: starting...", then run() and return success.