evilwm.1

'\" t
.
.\" ASCII for Unicode ellipsis is three dots
.schar \[u2026] ...
.\" New escape [...] maps to Unicode ellipsis
.char \[...] \[u2026]
.
.\" an-ext.tmac: Check whether we are using grohtml.
.nr mH 0
.if \n(.g \
.  if '\*(.T'html' \
.    nr mH 1
.
.\" What about gropdf?
.nr mP 0
.if \n(.g \
.  if '\*(.T'pdf' \
.    nr mP 1
.
.\" an-ext.tmac: Start example.
.de EX
.  nr mE \\n(.f
.  nf
.  nh
.  ft CW
..
.
.\" an-ext.tmac: End example.
.de EE
.  ft \\n(mE
.  fi
.  hy \\n(HY
..
.
.\" Top level heading; wraps .SH.  This seems to confuse lintian.
.de H1
.  if \\n(mP .pdfhref O 1 \\$*
.  SH \\$*
..
.
.\" 2nd level heading; wraps .SS
.de H2
.  if \\n(mP .pdfhref O 2 \\$*
.  SS \\$*
..
.
.\" 3rd level heading; bold font, no indent
.de H3
.  if \\n(.$ \{\
.    if \\n(mP .pdfhref O 3 \\$*
.    .B \&"\\$*"
.  \}
.  br
..
.
.\" Render URL
.de UU
.  ie \\n(mH \{\
\\$1\c
.    do HTML-NS "<a href='\\$2'>"
\\$2\c
.    do HTML-NS "</a>"
\\$3
.  \}
.  el \{\
.    ie \\n(mP \{\
.      pdfhref -W -P "\\$1" -A "\\$3" "\\$2"
.    \}
.    el \{\
\\$1\\$2\\$3
.    \}
.  \}
..
.
.\"
.
.ie \\n(mP \{\
.  nr PDFOUTLINE.FOLDLEVEL 3
.  pdfview /PageMode /UseOutlines
.  pdfinfo /Title evilwm 1.4
.  pdfinfo /Author Ciaran Anscomb
.\}
.
.TH "evilwm" "1" "October 2022" "evilwm-1.4"
.hy 0
.nh
.H1 NAME
.PP
evilwm\[em]minimalist window manager for X11
.H1 SYNOPSIS
.PP
\fBevilwm\fR \[lB]\fIOPTION\fR\[rB]\[...]
.H1 DESCRIPTION
.PP
\fBevilwm\fR is a minimalist window manager for the X Window System. It features plenty of reconfigurable mouse and keyboard controls while providing a clean display, uncluttered by less useful window furniture (like title bars).
.H1 OPTIONS
.TP
\f(CB\-\-display\fR \fIdisplay\fR
specifies the X display to run on. Usually this can be inferred from the \f(CBDISPLAY\fR environment variable.
.TP
\f(CB\-\-term\fR \fItermprog\fR
specifies an alternative program to run when spawning a new terminal (defaults to xterm, or x-terminal-emulator in Debian). Separate arguments with whitespace, and escape needed whitespace with a backslash. Remember that special characters will also need to be protected from the shell.
.TP
\f(CB\-\-fn\fR \fIfontname\fR
specify a font to use when resizing or displaying window titles (X Logical Font Description, with * and ? wildcards).
.TP
\f(CB\-\-fg\fR \fIcolour\fR
.TQ
\f(CB\-\-fc\fR \fIcolour\fR
.TQ
\f(CB\-\-bg\fR \fIcolour\fR
frame colour of currently active, fixed active, and inactive windows respectively. Either specify an X11 colour name like \f(CBgoldenrod\fR, or a hex triplet like \f(CB#DAA520\fR.
.TP
\f(CB\-\-bw\fR \fIborderwidth\fR
width of window borders in pixels.
.TP
\f(CB\-\-snap\fR \fIdistance\fR
enable snap-to-border support. \fIdistance\fR is the proximity in pixels to snap to.
.TP
\f(CB\-\-kbpx\fR \fIdistance\fR
modify keyboard move/resize distance, in pixels.
.TP
\f(CB\-\-quickmove\fR \fImultiplier\fR
.TQ
\f(CB\-\-quickmovems\fR \fImilliseconds\fR
multiply keyboard move distance by \fImultiplier\fR when there was a kbmove in the last \fImilliseconds\fR ms. Defaults to 1.0 and 250 respectively.
.TP
\f(CB\-\-wholescreen\fR
ignore monitor geometry and use the whole screen dimensions. This is the old behaviour from before multi-monitor support was implemented, and may still be useful, eg when one large monitor is driven from multiple outputs.
.TP
\f(CB\-\-numvdesks\fR \fIvalue\fR
number of virtual desktops to provide. Effective value for relative moves will be the greatest integer multiple of \f(CB\-\-modvdesks\fR less than or equal to this value. Defaults to 8.
.TP
\f(CB\-\-modvdesks\fR \fIvalue\fR
vdesk loop modulus and distance for left/right relative vdesk. Relative movement up from n*\fIvalue\fR-1 or down from n*\fIvalue\fR will instead move down or up (respectively) by \fIvalue\fR-1. This is equivalent to having a two-dimensional looping vdesk array of num/mod (lr) x mod (ud). Defaults to 0. \fIvalue\fR being 0 is equivalent to it being the current value of \f(CB\-\-numvdesks\fR.
.IP
Example: \f(CB\-\-numvdesks 12 \-\-modvdesks 4\fR will give a 2x4 array with numbering
.IP
.EX
3\ 7\ B
2\ 6\ A
1\ 5\ 9
0\ 4\ 8
.EE
.TP
\f(CB\-\-docks\fR \fIvalue\fR
set to 0 to hide all docks initially.
.TP
\f(CB\-\-soliddrag\fR \fIvalue\fR
.TQ
\f(CB\-\-solidsweep\fR \fIvalue\fR
set to 1 to draw a window outline while moving or resizing.
.TP
\f(CB\-\-mask1\fR \fImodifier\fR\[lB]+\fImodifier\fR\[rB]\[...]
.TQ
\f(CB\-\-mask2\fR \fImodifier\fR\[lB]+\fImodifier\fR\[rB]\[...]
.TQ
\f(CB\-\-altmask\fR \fImodifier\fR\[lB]+\fImodifier\fR\[rB]\[...]
override the default keyboard modifiers used to grab keys for window manager functionality.
.IP
\f(CBmask1\fR is used for most keyboard controls (default: control+alt), and \f(CBmask2\fR is used for mouse button controls and cycling windows (default: alt). \f(CBaltmask\fR is used to modify the behaviour of certain controls (default: shift). Modifiers may be separated with + signs. Valid modifiers are \[aq]shift\[aq], \[aq]control\[aq]/\[aq]ctrl\[aq], \[aq]mod1\[aq]/\[aq]alt\[aq], \[aq]mod2\[aq]\[...]\[aq]mod5\[aq].
.TP
\f(CB\-\-bind\fR \[lB]\fImodifier\fR+\[rB]\[...]\fIkey/button\fR=\[lB]\fIfunction\fR\[lB],\fIflag\fR\[lB]+\fIflag\fR\[rB]\[...]\[rB]\[rB]
bind a key or mouse button pressed with specified modifiers to a window manager function. \fIkey/button\fR is an X11 keysym name or \[aq]buttonN\[aq], where N is a positive integer of decimal, 0xhexadecimal, or 0octal form, \fImodifiers\fR are as above, but may also include \[aq]mask1\[aq], \[aq]mask2\[aq] and \[aq]altmask\[aq] to refer to configured mask variables. See FUNCTIONS for a list of available functions and the flags they recognise. If \fIfunction\fR is empty, a bind is removed.
.TP
\f(CB\-\-bind\fR \fIbutton\fR=\[lB]\fIfunction\fR\[lB],\fIflag\fR\[rB]\[...]\[rB]
bind a mouse button to a window manager function. While modifiers can be specified, they will be ignored; the button on its own will trigger if pressed within a window\[aq]s frame, or with \[aq]mask2\[aq] held anywhere within a window. Function and flags is as with key binds above. Valid buttons are
.TP
\f(CB\-\-nodefaultbinds\fR
don\[aq]t use the original compiled-in default bindings.
.TP
\f(CB\-\-app\fR \[lB]\fIname\fR\[rB]\[lB]/\[lB]\fIclass\fR\[rB]\[lB]/\[lB]\fItitle\fR\[rB]\[rB]\[rB]
match an application by instance name and class (for help in finding these, use the \fIxprop\fR tool to extract the \fIWM_CLASS\fR property; the two strings are \fIname\fR and \fIclass\fR respectively, checked exactly), and by title (checked as substring, \fIWM_NAME\fR in \fIxprop\fR).
.IP
Ex: \f(CB\-\-app a/b/c\fR will match a window with WM_CLASS { "a", "b" } and a WM_NAME containing the letter c anywhere.
Ex: \f(CB\-\-app a\fR will match a window with WM_CLASS\[lB]0\[rB] "a".
Ex: \f(CB\-\-app /b\fR will match a window with either blank or missing WM_CLASS\[lB]0\[rB], and WM_CLASS\[lB]1\[rB] "b".
Ex: \f(CB\-\-app //c\fR will match a window with completely blank/missing WM_CLASS and a WM_NAME containing the letter c anywhere.
Subsequent \f(CB\-\-geometry\fR, \f(CB\-\-dock\fR, \f(CB\-\-vdesk\fR and \f(CB\-\-fixed\fR options will apply to this match.
.TP
\f(CB\-g\fR, \f(CB\-\-geometry\fR \fIgeometry\fR
apply a geometry (using a standard X geometry string) to applications matching the last \f(CB\-\-app\fR.
.TP
\f(CB\-m\fR, \f(CB\-\-manual\fR
specify that application should be entirely ignored when it asks to move.
.TP
\f(CB\-d\fR, \f(CB\-\-dock\fR
specify that application should be considered to be a dock, even if it lacks the appropriate property.
.TP
\f(CB\-v\fR, \f(CB\-\-vdesk\fR \fIn\fR
specify a default virtual desktop for applications matching the last \f(CB\-\-app\fR. Note that virtual desktops are numbered from zero.
.TP
\f(CB\-f\fR, \f(CB\-\-fixed\fR
specify that application is to start with a fixed client window.
.TP
\f(CB\-h\fR, \f(CB\-\-help\fR
show help
.TP
\f(CB\-hh\fR, \f(CB\-\-writedefaults\fR
show all option defaults, in a format that could be put in your \fI.evilwmrc\fR
.TP
\f(CB\-V\fR, \f(CB\-\-version\fR
show program version
.PP
\fBevilwm\fR will also read options, one per line, from a file called \fI.evilwmrc\fR in the user\[aq]s home directory. Options listed in a configuration file should omit the leading dash(es). Options specified on the command line override those found in the configuration file.
.H1 USAGE & FUNCTIONS
.PP
In \fBevilwm\fR, the focus follows the mouse pointer, and is not lost if you stray onto the root window. The current window border is shaded gold (unless it is fixed, in which case blue), with other windows left as a dark grey.
.PP
The keyboard and mouse button controls can be configured with the \f(CB\-\-bind\fR option to a number of built-in functions. Typically, these functions respond to an additional set of flags that modify their behaviour: \f(CBup\fR/\f(CBu\fR/\f(CBon\fR, \f(CBdown\fR/\f(CBd\fR/\f(CBoff\fR, \f(CBleft\fR/\f(CBl\fR, \f(CBright\fR/\f(CBr\fR, \f(CBtop\fR, \f(CBbottom\fR, any number, \f(CBrelative\fR/\f(CBrel\fR, \f(CBtoggle\fR, \f(CBvertical\fR/\f(CBv\fR, \f(CBhorizontal\fR/\f(CBh\fR.
.TP
\f(CBbind command\fR, default key
Description.
.PP
You can use the mouse to manipulate windows either by click/dragging the single-pixel border (easier when they align with a screen edge), or by holding down \f(CBmask2\fR/Alt and doing so anywhere in the window. The \f(CBmask2\fR/Alt-based controls are:
.TP
\f(CBmove\fR, Button 1
Move window with mouse.
.TP
\f(CBresize\fR, Button 2
Resize window between starting upper-left corner and mouse position.
.TP
\f(CBlower\fR, Button 3
Put window at back of render order.
.TP
\f(CBnext\fR, Tab
Classic Alt+Tab, switch to most recently selected window and keep switching to less recent windows on every consecutive press while the modifier key(s) are held
.PP
Most keyboard controls are used by holding down \f(CBmask1\fR/Control+Alt, then pressing a key. Available functions are:
.TP
\f(CBspawn\fR, Return
Spawn new terminal (or other process) with the command in \f(CB\-\-term\fR.
.TP
\f(CBdelete\fR, Escape
.TQ
\f(CBkill\fR, Shift+Escape
Delete current window, nicely. Hold \f(CBaltmask\fR/Shift as well to force \f(CBkill\fR a client if it does not respond to \f(CBdelete\fR.
.TP
\f(CBlower\fR, Insert
Lower current window to back of render order.
.TP
\f(CBraise\fR, (none)
Raise current window.
.TP
\f(CBmove,relative+\fR, H, J, K, L
.TQ
\f(CBresize,relative+\fR, Shift+ H, J, K, L
Move window left, down, up or right (\f(CB\-\-kbpx\fR/16 pixels). Holding \f(CBaltmask\fR/Shift resizes the window narrower, taller, shorter, or wider.
.TP
\f(CBmove,top+\fR/\f(CBmove,bottom+\fR, Y, U, B, N
Move window to the top-left, top-right, bottom-left or bottom-right of its current monitor.
.TP
\f(CBinfo\fR, I
Show extra information about the current window for as long as the key is held.
.TP
\f(CBresize,toggle+\fR, Equals
Toggle maximization of current window to current monitor vertically, or horizontally when holding \f(CBaltmask\fR/Shift
.TP
\f(CBresize,toggle+v+h\fR, X
Toggle maximization of current window to current monitor.
.TP
\f(CBdocks,toggle\fR, D
Toggle visible state of windows claiming to be docks or marked as docks through \f(CB\-\-app \-d\fR, eg pagers and launch bars.
.TP
\f(CBbinds,toggle\fR, Compose
Toggle all other bindings (stop listening to any bind other than \f(CBbinds,toggle\fR, \f(CBbinds, up\fR, or mouse actions on the border).
.TP
\f(CBfix,toggle\fR, F
Fix or unfix current window. Fixed windows remain visible when you switch virtual desktop.
.TP
\f(CBvdesk,\fR, 1\[em]8
Switch to specific virtual desktop (internally, desktops are numbered from zero, so this actually switches to desktops 0\[em]7; this only becomes important if you use application matching).
.TP
\f(CBvdesk,relative+down\fR, Left
Switch to next lower numbered virtual desktop, modulo \f(CBmodvdesks\fR.
.TP
\f(CBvdesk,relative+up\fR, Right
Switch to next higher numbered virtual desktop, modulo \f(CBmodvdesks\fR.
.TP
\f(CBvdesk,relative+left\fR, Down
Switch to virtual desktop \f(CBmodvdesks\fR higher, modulo \f(CBnumvdesks\fR.
.TP
\f(CBvdesk,relative+right\fR, Up
Switch to virtual desktop \f(CBmodvdesks\fR lower, modulo \f(CBnumvdesks\fR.
.TP
\f(CBvdesk,toggle\fR, A
Switch to the previously selected virtual desktop.
.PP
To make \fBevilwm\fR reread its config, send a HUP signal to the process. To make it quit, kill it, ie send a TERM signal.
.H1 FILES
.PP
\fI$HOME/.evilwmrc\fR
.H1 LICENCE
.PP
Copyright (C) 1999-2022 Ciaran Anscomb <evilwm@6809.org.uk>
.PP
This is free software. You can do what you want to it, but if it breaks something, you get to pay for the counselling. The code was originally based on aewm, so this is distributed under the same terms, which follow.
.H1 AEWM LICENCE
.PP
Copyright (c) 1998-2000 Decklin Foster.
.PP
THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES OF ANY KIND. IN NO EVENT SHALL THE AUTHOR BE HELD LIABLE FOR ANY DAMAGES CONNECTED WITH THE USE OF THIS PROGRAM.
.PP
You are granted permission to copy, publish, distribute, and/or sell copies of this program and any modified versions or derived works, provided that this copyright and notice are not removed or altered.
.PP
Portions of the code were based on 9wm, which contains this license:
.IP
.EX
9wm\ is\ free\ software,\ and\ is\ Copyright\ (c)\ 1994\ by\ David\ Hogan.
Permission\ is\ granted\ to\ all\ sentient\ beings\ to\ use\ this
software,\ to\ make\ copies\ of\ it,\ and\ to\ distribute\ those\ copies,
provided\ that:
\ \ (1)\ the\ copyright\ and\ licence\ notices\ are\ left\ intact
\ \ (2)\ the\ recipients\ are\ aware\ that\ it\ is\ free\ software
\ \ (3)\ any\ unapproved\ changes\ in\ functionality\ are\ either
\ \ \ \ \ \ \ \ (i)\ only\ distributed\ as\ patches
\ \ \ \ or\ (ii)\ distributed\ as\ a\ new\ program\ which\ is\ not\ called\ 9wm
\ \ \ \ \ \ \ \ \ \ \ \ and\ whose\ documentation\ gives\ credit\ where\ it\ is\ due
\ \ (4)\ the\ author\ is\ not\ held\ responsible\ for\ any\ defects
\ \ \ \ \ \ or\ shortcomings\ in\ the\ software,\ or\ damages\ caused\ by\ it.
There\ is\ no\ warranty\ for\ this\ software.\ \ Have\ a\ nice\ day.
.EE
.H1 SEE ALSO
.PP
\fBxterm\fR (1), \fBxprop\fR (1), \fBxmodmap\fR (1), \fBxorg-xfontsel\fR (1)