.Dd $Mdocdate: February 15 2012 $

.Os

.Nm spectrwm

.Nd window manager for X11

.Nm spectrwm

.Nm

is a minimalistic window manager that tries to stay out of the way so that

valuable screen real estate can be used for much more important stuff.

It has sane defaults and does not require one to learn a language to do any

configuration.

It was written by hackers for hackers and it strives to be small, compact and

fast.

.Pp

When

.Nm

starts up, it reads settings from its configuration file,

.Pa spectrwm.conf .

See the

.Sx CONFIGURATION FILES

section below.

.Pp

The following notation is used throughout this page:

.Pp

.Bl -tag -width Ds -offset indent -compact

.It Cm M

Meta

.It Cm S

Shift

.It Aq Cm Name

Named key

.It Cm M1

Mouse button 1

.It Cm M3

Mouse button 3

.El

.Pp

.Nm

is very simple in its use.

Most of the actions are initiated via key or mouse bindings.

See the

.Sx BINDINGS

section below for defaults and customizations.

.Nm

first tries to open the user specific file,

.Pa ~/.spectrwm.conf .

If that file is unavailable,

it then tries to open the global configuration file

.Pa /etc/spectrwm.conf .

.Pp

The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.

For example:

.Pp

.Dl color_focus = red

.Pp

Enabling or disabling an option is done by using 1 or 0 respectively.

.Pp

Colors need to be specified per the

.Xr XQueryColor 3

specification.

.Pp

Comments begin with a #. When a literal '#' is desired in an option, then it

must be escaped with a backslash. i.e. \e#

.Pp

The file supports the following keywords:

.Bl -tag -width 2m

.It Ic autorun

Launch an application in a specified workspace at start-of-day.

Defined in the format ws[<idx>]:application, e.g. ws[2]:xterm launches an

xterm in workspace 2.

.It Ic bar_action

External script that populates additional information in the status bar,

such as battery life.

.It Ic bar_at_bottom

Place the statusbar at the bottom of each region instead of the top.

.It Ic bar_border Ns Bq Ar x

Border color of the status bar(s) in screen

.Ar x .

.It Ic bar_border_unfocus Ns Bq Ar x

Border color of the status bar(s) on unfocused region(s) in screen

.Ar x .

.It Ic bar_border_width

Set status bar border thickness in pixels.

Disable border by setting to 0.

.It Ic bar_color Ns Bq Ar x

Background color of the status bar(s) in screen

.Ar x .

.It Ic bar_enabled

Set default

.Ar bar_toggle

state; default is 1.

.It Ic bar_enabled_ws Ns Bq Ar x

Set default

.Ar bar_toggle_ws

state on workspace

.Ar x ;

default is 1.

.It Ic bar_font

Font used in the status bar. Either Xft or X Logical Font Description (XLFD)

may be used to specify fonts. Fallback fonts may be specified by separating

each font with a comma. If all entries are XLFD syntax, font set will be

used. If at least one entry is Xft, Xft will be used. Note that if Xft is in

use, only the first font that successfully loads will be used regardless of

missing glyphs. The default is to use font set. Also note that dmenu does

not support Xft fonts.

.Pp

Xft examples:

.Bd -literal -offset indent

bar_font = Terminus:style=Regular:pixelsize=14:antialias=true

bar_font = -*-profont-medium-*-*-*-11-*-*-*-*-*-*-*,Terminus:pixelsize=14,\

-*-clean-medium-*-*-*-12-*-*-*-*-*-*-*

.Ed

.Pp

Font set examples:

.Bd -literal -offset indent

bar_font = -*-terminus-medium-*-*-*-14-*-*-*-*-*-*-*

bar_font = -*-profont-medium-*-*-*-11-*-*-*-*-*-*-*,\

-*-terminus-medium-*-*-*-14-*-*-*-*-*-*-*,\

-*-clean-medium-*-*-*-12-*-*-*-*-*-*-*

.Ed

.Pp

To list the available fonts in your system see

.Xr fc-list 1

or

.Xr xlsfonts 1

manpages.

The

.Xr xfontsel 1

application can help with the XLFD setting.

.Pp

.It Ic bar_font_color Ns Bq Ar x

Color of the font in status bar in screen

.Ar x .

.It Ic bar_format

Set the bar_format string and overrides

.Ic clock_format

and all of the

.Ic enabled

options.

The format is passed through

.Xr strftime 3

before being used.

It may contain the following character sequences:

.Bl -column "Character sequence" "Replaced with" -offset indent

.It Sy "Character sequence" Ta Sy "Replaced with"

.It Li "+<" Ta "Pad with a space"

.It Li "+A" Ta "Output of the external script"

.It Li "+C" Ta "Window class"

.It Li "+D" Ta "Workspace name"

.It Li "+F" Ta "Floating indicator"

.It Li "+I" Ta "Workspace index"

.It Li "+N" Ta "Screen number"

.It Li "+P" Ta "Window class and title separated by a colon"

.It Li "+S" Ta "Stacking algorithm"

.It Li "+T" Ta "Window title"

.It Li "+U" Ta "Urgency hint"

.It Li "+V" Ta "Program version"

.It Li "+W" Ta "Window name"

.It Li "++" Ta "A literal" Ql +

.El

.Pp

All character sequences may limit its output to a specific length, for

example +64A. Any characters that don't match the specification are copied

as-is.

.It Ic bar_justify

Justify the status bar text. Possible values are

.Pa left ,

.Pa center ,

and

.Pa right .

.Pp

Note that if the output is not

.Pa left

justified, it may not be properly aligned in some circumstances, due to the

white-spaces in the default static format.

See the

.Ic bar_format

option for more details.

.It Ic bind Ns Bq Ar x

Bind key combo to action

.Ar x .

See the

.Sx BINDINGS

section below.

.It Ic border_width

Set window border thickness in pixels.

Disable all borders by setting to 0.

.It Ic clock_enabled

Enable or disable displaying the clock in the status bar.

Disable by setting to 0

so a custom clock could be used in the

.Pa bar_action

script.

.It Ic color_focus

Border color of the currently focussed window.

.It Ic color_unfocus

Border color of unfocussed windows.

.It Ic dialog_ratio

Some applications have dialogue windows that are too small to be useful.

This ratio is the screen size to what they will be resized.

For example, 0.6 is 60% of the physical screen size.

.It Ic disable_border

Remove border when bar is disabled and there is only one window on the

region.

.It Ic focus_close

Window to put focus when the focused window is closed.

Possible values are

.Pa first ,

.Pa next ,

.Pa previous

(default) and

.Pa last .

.Pa next

and

.Pa previous

are relative to the window that is closed.

.It Ic focus_close_wrap

Whether to allow the focus to jump to the last window when the first window

is closed or vice versa. Disable by setting to 0.

.It Ic focus_default

Window to put focus when no window has been focused. Possible values are

.Pa first

and

.Pa last

(default).

.It Ic focus_mode

Window focus behavior with respect to the mouse cursor. Possible values:

.Pp

.Bl -tag -width "default" -offset indent -compact

.It Cm default

Set window focus on border crossings caused by cursor motion and

window interaction.

.It Cm follow

Set window focus on all cursor border crossings, including workspace switches

and changes to layout.

.It Cm manual

Set window focus on window interaction only.

.El

.It Ic keyboard_mapping

Clear all key bindings and load new key bindings from the specified file.

This allows you to load pre-defined key bindings for your keyboard layout.

See the

.Sx KEYBOARD MAPPING FILES

section below for a list of keyboard mapping files that have been provided

for several keyboard layouts.

.It Ic layout

Select layout to use at start-of-day. Defined in the format

ws[idx]:master_grow:master_add:stack_inc:layout:always_raise:stack_mode, e.g.

ws[2]:-4:0:1:0:horizontal sets worskspace 2 to the horizontal stack mode and

shrinks the master area by 4 ticks and adds one window to the stack, while

maintaining default floating window behavior.

Possible stack_mode values are

.Pa vertical ,

.Pa vertical_flip ,

.Pa horizontal ,

.Pa horizontal_flip

and

.Pa fullscreen .

.Pp

See

.Pa master_grow ,

.Pa master_shrink ,

.Pa master_add ,

.Pa master_del ,

.Pa stack_inc ,

.Pa stack_dec ,

and

.Pa always_raise

for more information.

Note that the stacking options are complicated and have side-effects. One

should familiarize oneself with these commands before experimenting with the

.Pa layout

option.

.Pp

This setting is not retained at restart.

.It Ic modkey

Change mod key.

Mod1 is generally the ALT key and Mod4 is the windows key on a PC.

.It Ic program Ns Bq Ar p

Define new action to spawn a program

.Ar p .

See the

.Sx PROGRAMS

section below.

.It Ic quirk Ns Bq Ar c:n

Add "quirk" for windows with class

.Ar c

and name

.Ar n .

See the

.Sx QUIRKS

section below.

.It Ic region

Allocates a custom region, removing any autodetected regions which occupy the

same space on the screen.

Defined in the format screen[<idx>]:WIDTHxHEIGHT+X+Y,

e.g.\& screen[1]:800x1200+0+0.

.Pp

To make a region span multiple monitors, create a region big enough to cover

them all, e.g. screen[1]:2048x768+0+0 makes the region span two monitors with

1024x768 resolution sitting one next to the other.

.It Ic region_padding

Pixel width of empty space within region borders.

Disable by setting to 0.

.It Ic spawn_position

Position in stack to place newly spawned windows.

Possible values are

.Pa first ,

.Pa next ,

.Pa previous

and

.Pa last

(default).

.Pa next

and

.Pa previous

are relative to the focused window.

.It Ic inherit_workspace

Spawned applicatons inherit the workspace id.

Disable by setting to 0.

.It Ic stack_enabled

Enable or disable displaying the current stacking algorithm in the status

bar.

.It Ic term_width

Set a preferred minimum width for the terminal.

If this value is greater than 0,

.Nm

will attempt to adjust the font sizes in the terminal to keep the terminal

width above this number as the window is resized.

Only

.Xr xterm 1

is currently supported.

The

.Xr xterm 1

binary must not be setuid or setgid, which it is by default on most systems.

Users may need to set program[term] (see the

.Sx PROGRAMS

section) to use an alternate copy of the

.Xr xterm 1

binary without the setgid bit set.

.It Ic tile_gap

Pixel width of empty space between tiled windows.

Disable by setting to 0.

.It Ic title_class_enabled

Enable or disable displaying the window class in the status bar.

Enable by setting to 1.

.It Ic title_name_enabled

Enable or disable displaying the window title in the status bar.

Enable by setting to 1.

.It Ic urgent_enabled

Enable or disable the urgency hint.

Note that many terminal emulators require this to be enabled for it to

propagate.

In xterm, for example, one needs to add the following line

.Pa xterm.bellIsUrgent: true

to

.Pa .Xdefaults .

.It Ic verbose_layout

Enable or disable displaying the current master window count and stack column/row

count in the status bar.

Enable by setting to 1.

See

.Pa master_add ,

.Pa master_del ,

.Pa stack_inc

and

.Pa stack_dec

for more information.

.It Ic window_name_enabled

Enable or disable displaying the window name in the status bar.

Enable by setting to 1.

.Pp

To prevent excessively large window names from pushing the remaining text off

the bar, it's limited to 64 characters, by default.

See the

.Ic bar_format

option for more details.

.It Ic workspace_limit

Set the total number of workspaces available. Minimum is 1, maximum is 22,

default is 10.

.El

.Nm

allows you to define custom actions to launch programs of your choice and

then bind them the same as with built-in actions.

See the

.Sx BINDINGS

section below.

.Pp

Custom programs in the configuration file are specified as follows:

.Pp

.Dl program[<action>] = <progpath> [<arg> [... <arg>]]

.Pp

.Aq action

is any identifier that does not conflict with a built-in action or keyword,

.Aq progpath

is the desired program, and

.Aq arg

is zero or more arguments to the program.

.Pp

Remember that when using # in your program call, it must be escaped with a

backslash. i.e. \e#

.Pp

The following argument variables will be substituted for values at the time the program

is spawned:

.Pp

.Bl -tag -width "$bar_font_color" -offset indent -compact

.It Cm $bar_border

.It Cm $bar_color

.It Cm $bar_font

.It Cm $bar_font_color

.It Cm $color_focus

.It Cm $color_unfocus

.It Cm $region_index

.It Cm $workspace_index

.El

.Pp

Example:

.Bd -literal -offset indent

program[ff] = /usr/local/bin/firefox http://spectrwm.org/

bind[ff] = Mod+Shift+b # Now M-S-b launches firefox

.Ed

.Pp

To cancel the previous, unbind it:

.Bd -literal -offset indent

bind[] = Mod+Shift+b

.Ed

.Pp

Default programs:

.Bl -tag -width "screenshot_wind" -offset indent -compact

.It Cm lock

xlock

.It Cm menu

dmenu_run \-fn $bar_font \-nb $bar_color \-nf $bar_font_color \-sb

$bar_border \-sf $bar_color

.It Cm term

xterm

.It Cm initscr

initscreen.sh # optional

.It Cm screenshot_all

screenshot.sh full # optional

.It Cm screenshot_wind

screenshot.sh window # optional

.El

.Pp

Note that optional default programs will not be validated unless overridden.

If a default program fails validation, you can resolve the exception

by installing the program, modifying the program call or disabling the program

by freeing the respective key binding.

.Pp

For example, to override

.Ic lock :

.Bd -literal -offset indent

program[lock] = xscreensaver-command --lock

.Ed

.Pp

To unbind

.Ic lock

and prevent it from being validated:

.Bd -literal -offset indent

bind[] = MOD+Shift+Delete

.Ed

.Nm

provides many functions (or actions) accessed via key or mouse bindings.

.Pp

The current mouse bindings are described below:

.Pp

.Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact

.It Cm M1

Focus window

.It Cm M-M1

Move window

.It Cm M-M3

Resize window

.It Cm M-S-M3

Resize window while maintaining it centered

.El

.Pp

The default key bindings are described below:

.Pp

.Bl -tag -width "M-j, M-<TAB>XXXXXX" -offset indent -compact

.It Cm M-S- Ns Aq Cm Return

term

.It Cm M-p

menu

.It Cm M-S-q

quit

.It Cm M-q

restart

.It Cm M- Ns Aq Cm Space

cycle_layout

.It Cm M-S- Ns Aq Cm \e

flip_layout

.It Cm M-S- Ns Aq Cm Space

stack_reset

.It Cm M-h

master_shrink

.It Cm M-l

master_grow

.It Cm M-,

master_add

.It Cm M-.

master_del

.It Cm M-S-,

stack_inc

.It Cm M-S-.

stack_dec

.It Cm M- Ns Aq Cm Return

swap_main

.It Xo

.Cm M-j ,

.Cm M- Ns Aq Cm TAB

.Xc

focus_next

.It Xo

.Cm M-k ,

.Cm M-S- Ns Aq Cm TAB

.Xc

focus_prev

.It Cm M-m

focus_main

.It Cm M-S-j

swap_next

.It Cm M-S-k

swap_prev

.It Cm M-b

bar_toggle

.It Cm M-S-b

bar_toggle_ws

.It Cm M-x

wind_del

.It Cm M-S-x

wind_kill

.It Cm M- Ns Aq Ar 1-9,0,F1-F12

.Pf ws_ Aq Ar 1-22

.It Cm M-S- Ns Aq Ar 1-9,0,F1-F12

.Pf mvws_ Ns Aq Ar 1-22

.It Cm M- Ns Aq Ar Keypad 1-9

.Pf rg_ Aq Ar 1-9

.It Cm M-S- Ns Aq Ar Keypad 1-9

.Pf mvrg_ Aq Ar 1-9

.It Cm M- Ns Aq Cm Right

ws_next

.It Cm M- Ns Aq Cm Left

ws_prev

.It Cm M- Ns Aq Cm Up

ws_next_all

.It Cm M- Ns Aq Cm Down

ws_prev_all

.It Cm M-a

ws_next_move

.It Cm M-S- Ns Aq Cm Left

ws_prev_move

.It Cm M-S- Ns Aq Cm Up

ws_prior

.It Cm M-S- Ns Aq Cm Right

rg_next

.It Cm M-S- Ns Aq Cm Left

rg_prev

.It Cm M-s

screenshot_all

.It Cm M-S-s

screenshot_wind

.It Cm M-S-v

version

.It Cm M-t

float_toggle

.It Cm M-e

float_toggle

.It Cm M-S- Ns Aq Cm Delete

lock

.It Cm M-S-i

initscr

.It Cm M-w

iconify

.It Cm M-S-w

uniconify

.It Cm M-S-r

always_raise

.It Cm M-v

button2

.It Cm M--

width_shrink

.It Cm M-=

width_grow

.It Cm M-S--

height_shrink

.It Cm M-S-=

height_grow

.It Cm M-[

move_left

.It Cm M-]

move_right

.It Cm M-S-[

move_up

.It Cm M-S-]

move_down

.It Cm M-S-/

name_workspace

.It Cm M-/

search_workspace

.It Cm M-f

search_win

.El

.Pp

The action names and descriptions are listed below:

.Pp

.Bl -tag -width "M-j, M-<TAB>XXXX" -offset indent -compact

.It Cm term

Spawn a new terminal

(see

.Sx PROGRAMS

above).

.It Cm menu

Menu

(see

.Sx PROGRAMS

above).

.It Cm quit

Quit

.Nm .

.It Cm restart

Restart

.Nm .

.It Cm cycle_layout

Cycle layout.

.It Cm flip_layout

Swap the master and stacking areas.

.It Cm stack_reset

Reset layout.

.It Cm master_shrink

Shrink master area.

.It Cm master_grow

Grow master area.

.It Cm master_add

Add windows to master area.

.It Cm master_del

Remove windows from master area.

.It Cm stack_inc

Add columns/rows to stacking area.

.It Cm stack_dec

Remove columns/rows from stacking area.

.It Cm swap_main

Move current window to master area.

.It Cm focus_next

Focus next window in workspace.

.It Cm focus_prev

Focus previous window in workspace.

.It Cm focus_main

Focus on main window in workspace.

.It Cm swap_next

Swap with next window in workspace.

.It Cm swap_prev

Swap with previous window in workspace.

.It Cm bar_toggle

Toggle overall visibility of status bars.

.It Cm bar_toggle_ws

Toggle status bar on current workspace.

.It Cm wind_del

Delete current window in workspace.

.It Cm wind_kill

Destroy current window in workspace.

.It Cm ws_ Ns Ar n

Switch to workspace

.Ar n ,

where

.Ar n

is 1 through workspace_limit.

.It Cm mvws_ Ns Ar n

Move current window to workspace

.Ar n ,

where

.Ar n

is 1 through workspace_limit.

.It Cm rg_ Ns Ar n

Focus on region

.Ar n ,

where

.Ar n

is 1 through 9.

.It Cm mvrg_ Ns Ar n

Move current window to region

.Ar n ,

where

.Ar n

is 1 through 9.

.It Cm ws_next

Switch to next workspace with a window in it.

.It Cm ws_prev

Switch to previous workspace with a window in it.

.It Cm ws_next_all

Switch to next workspace.

.It Cm ws_prev_all

Switch to previous workspace.

.It Cm ws_next_move

Switch to next workspace with the current window.

.It Cm ws_prev_move

Switch to previous workspace with the current window.

.It Cm ws_prior

Switch to last visited workspace.

.It Cm rg_next

Switch to next region.

.It Cm rg_prev

Switch to previous region.

.It Cm screenshot_all

Take screenshot of entire screen (if enabled)

(see

.Sx PROGRAMS

above).

.It Cm screenshot_wind

Take screenshot of selected window (if enabled)

(see

.Sx PROGRAMS

above).

.It Cm version

Toggle version in status bar.

.It Cm float_toggle

Toggle focused window between tiled and floating.

.It Cm fullscreen_toggle

Toggle fullscreen layout.

.It Cm lock

Lock screen

(see

.Sx PROGRAMS

above).

.It Cm initscr

Reinitialize physical screens

(see

.Sx PROGRAMS

above).

.It Cm iconify

Minimize (unmap) currently focused window.

.It Cm uniconify

Maximize (map) window returned by dmenu selection.

.It Cm always_raise

When set tiled windows are allowed to obscure floating windows.

.It Cm button2

Fake a middle mouse button click (mouse button 2).

.It Cm width_shrink

Shrink the width of a floating window.

.It Cm width_grow

Grow the width of a floating window.

.It Cm height_shrink

Shrink the height of a floating window.

.It Cm height_grow

Grow the height of a floating window.

.It Cm move_left

Move a floating window a step to the left.

.It Cm move_right

Move a floating window a step to the right.

.It Cm move_up

Move a floating window a step upwards.

.It Cm move_down

Move a floating window a step downwards.

.It Cm name_workspace

Name the current workspace.

.It Cm search_workspace

Search for a workspace.

.It Cm search_win

Search the windows in the current workspace.

.El

.Pp

Custom bindings in the configuration file are specified as follows:

.Pp

.Dl bind[<action>] = <keys>

.Pp

.Aq action

is one of the actions listed above (or empty to unbind) and

.Aq keys

is in the form of zero or more modifier keys

(MOD, Mod1, Shift, etc.) and one or more normal keys

(b, space, etc.), separated by "+".

.Pp

Example:

.Bd -literal -offset indent

bind[reset] = Mod4+q # bind Windows-key + q to reset

bind[] = Mod1+q # unbind Alt + q

.Ed

.Pp

To use the currently defined

.Ic modkey ,

specify MOD as the modifier key.

.Pp

Multiple key combinations may be bound to the same action.

.Pp

To bind non-latin characters such as å or π you must enter the xkb

character name instead of the character itself. Run xev, focus the window

and press the specific key and in the terminal output read the symbol name.

In the fallowing example for å:

.Bd -literal -offset indent

KeyPress event, serial 41, synthetic NO, window 0x2600001,

root 0x15a, subw 0x0, time 106213808, (11,5), root:(359,823),

state 0x0, keycode 24 (keysym 0xe5, aring), same_screen YES,

XLookupString gives 2 bytes: (c3 a5) "å"

XmbLookupString gives 2 bytes: (c3 a5) "å"

XFilterEvent returns: False

.Ed

.Pp

The xkb name is aring. In other words, in .spectrwm.conf add:

.Bd -literal -offset indent

bind[program] = MOD+aring

.Ed

Keyboard mapping files for several keyboard layouts are listed

below.

These files can be used with the

.Pa keyboard_mapping

setting to load pre-defined key bindings for the specified

keyboard layout.

.Pp

.Bl -tag -width "spectrwm_XX.confXXX" -offset indent -compact

.It Cm spectrwm_cz.conf

Czech Republic keyboard layout

.It Cm spectrwm_es.conf

Spanish keyboard layout

.It Cm spectrwm_fr.conf

French keyboard layout

.It Cm spectrwm_fr_ch.conf

Swiss French keyboard layout

.It Cm spectrwm_se.conf

Swedish keyboard layout

.It Cm spectrwm_us.conf

United States keyboard layout

.El

.Nm

provides "quirks" which handle windows that must be treated specially

in a tiling window manager, such as some dialogs and fullscreen apps.

.Pp

The default quirks are described below:

.Pp

.Bl -tag -width "OpenOffice.org N.M:VCLSalFrame<TAB>XXX" -offset indent \

.It Firefox\-bin:firefox\-bin

TRANSSZ

.It Firefox:Dialog

FLOAT

.It Gimp:gimp

FLOAT + ANYWHERE

.It MPlayer:xv

FLOAT + FULLSCREEN + FOCUSPREV

.It OpenOffice.org 2.4:VCLSalFrame

FLOAT

.It OpenOffice.org 3.1:VCLSalFrame

FLOAT

.It pcb:pcb

FLOAT

.It xine:Xine Window

FLOAT + ANYWHERE

.It xine:xine Panel

FLOAT + ANYWHERE

.It xine:xine Video Fullscreen Window

FULLSCREEN + FLOAT

.It Xitk:Xitk Combo

FLOAT + ANYWHERE

.It Xitk:Xine Window

FLOAT + ANYWHERE

.It XTerm:xterm

XTERM_FONTADJ

.El

.Pp

The quirks themselves are described below:

.Pp

.Bl -tag -width "XTERM_FONTADJ<TAB>XXX" -offset indent -compact

.It FLOAT

This window should not be tiled, but allowed to float freely.

.It TRANSSZ

Adjusts size on transient windows that are too small using dialog_ratio

(see

.Sx CONFIGURATION FILES ) .

.It ANYWHERE

Allow window to position itself, uncentered.

.It XTERM_FONTADJ

Adjust xterm fonts when resizing.

.It FULLSCREEN

Remove border to allow window to use full region size.

.It FOCUSPREV

On exit force focus on previously focused application not previous

application in the stack.

.It NOFOCUSONMAP

Don't change focus to the window when it first appears on the screen.

Has no effect when

.Ic focus_mode

is set to follow.

.It FOCUSONMAP_SINGLE

When the window first appears on the screen, change focus to the window

if there are no other windows on the workspace with the same class/name.

Has no effect when

.Ic focus_mode

is set to follow.

.El

.Pp

Custom quirks in the configuration file are specified as follows:

.Pp

.Dl quirk[<class>:<name>] = <quirk> [ + <quirk> ... ]

.Pp

.Aq class

and

.Aq name

specify the window to which the quirk(s) apply, and

.Aq quirk

is one of the quirks from the list above.

For example:

.Bd -literal -offset indent

quirk[MPlayer:xv] = FLOAT + FULLSCREEN + FOCUSPREV

quirk[pcb:pcb] = NONE # remove existing quirk

.Ed

.Pp

You can obtain

.Aq class

and

.Aq name

by running

.Xr xprop 1

and then clicking on the desired window.

In the following example the main window of Firefox was clicked:

.Bd -literal -offset indent

$ xprop | grep WM_CLASS

WM_CLASS(STRING) = "Navigator", "Firefox"

.Ed

.Pp

Note that grepping for WM_CLASS flips class and name.

In the example above the quirk entry would be:

.Bd -literal -offset indent

quirk[Firefox:Navigator] = FLOAT

.Ed

.Pp

.Nm

also automatically assigns quirks to windows based on the value

of the window's _NET_WM_WINDOW_TYPE property as follows:

.Pp

.Bl -tag -width "_NET_WM_WINDOW_TYPE_TOOLBAR<TAB>XXX" -offset indent -compact

.It _NET_WM_WINDOW_TYPE_DOCK

FLOAT + ANYWHERE

.It _NET_WM_WINDOW_TYPE_TOOLBAR

FLOAT + ANYWHERE

.It _NET_WM_WINDOW_TYPE_UTILITY

FLOAT + ANYWHERE

.It _NET_WM_WINDOW_TYPE_SPLASH

FLOAT

.It _NET_WM_WINDOW_TYPE_DIALOG

FLOAT

.El

.Pp

In all other cases, no automatic quirks are assigned to the window.

Quirks specified in the configuration file override the automatic quirks.

.Nm

partially implements the Extended Window Manager Hints (EWMH) specification.

This enables controlling windows as well as

.Nm

itself from external scripts and programs.

This is achieved by

.Nm

responding to certain ClientMessage events.

From the terminal these events

can be conveniently sent using tools such as

.Xr wmctrl 1

and

.Xr xdotool 1 .

For the

actual format of these ClientMessage events, see the EWMH specification.

.Pp

The id of the currently focused window is stored in the _NET_ACTIVE_WINDOW

property of the root window.

This can be used for example to retrieve the

title of the currently active window with

.Xr xprop 1

and

.Xr grep 1 :

.Bd -literal -offset indent

$ WINDOWID=`xprop \-root _NET_ACTIVE_WINDOW | grep \-o "0x.*"`

$ xprop \-id $WINDOWID WM_NAME | grep \-o "\\".*\\""

.Ed