sscrotwm.1

.\" Copyright (c) 2012 Jacob Courtneay <jacob@sporkexec.com>
.\" Copyright (c) 2009 Marco Peereboom <marco@peereboom.us>
.\" Copyright (c) 2009 Darrin Chandler <dwchandler@stilyagin.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: February 15 2012 $
.Dt SSCROTWM 1
.Os
.Sh NAME
.Nm sscrotwm
.Nd window manager for X11
.Sh SYNOPSIS
.Nm sscrotwm
.Sh DESCRIPTION
.Nm
(Shriveled scrotwm) 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.
It was forked from scrotwm when it became too bloaty and when the authors
decided on an unfortunate name change to spectrwm due to butthurt users.
.Pp
When
.Nm
starts up, it reads settings from its configuration file,
.Pa sscrotwm.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 customizations.
.Sh CONFIGURATION FILES
.Nm
first tries to open the user specific file,
.Pa ~/.sscrotwm.conf .
If that file is unavailable,
it then tries to open the global configuration file
.Pa /etc/sscrotwm.conf .
.Pp
.Nm
needs a configuration file present to be useful, as there are no
built-in defaults. The configuration file provided includes recommended
settings and examples.
.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
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 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 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 screen.
.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 horizontal
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 screen span multiple monitors, create a region big enough to cover
them all, e.g. screen[1]:2048x768+0+0 makes the screen span two monitors with
1024x768 resolution sitting one next to the other.
.El
.Pp
Colors need to be specified per the
.Xr XQueryColor 3
specification.
.Sh PROGRAMS
.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[<name>] = <progpath> [<arg> [... <arg>]]
.Pp
.Aq name
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
Example:
.Bd -literal -offset indent
program[ff] = /usr/local/bin/firefox http://github.com/
bind[ff] = Mod+Shift+b # Now Mod+Shift+B launches firefox
.Ed
.Pp
To undo the previous:
.Bd -literal -offset indent
bind[] = Mod+Shift+b
program[ff] =
.Ed
.Sh BINDINGS
.Nm
provides many functions (or actions) accessed via key or mouse bindings.
.Pp
The default 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 action names and descriptions are listed below:
.Pp
.Bl -tag -width "M-j, M-<TAB>XXXX" -offset indent -compact
.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 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 10.
.It Cm mvws_ Ns Ar n
Move current window to workspace
.Ar n ,
where
.Ar n
is 1 through 10.
.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_prior
Switch to last visited workspace.
.It Cm screen_next
Move pointer to next region.
.It Cm screen_prev
Move pointer to previous region.
.It Cm float_toggle
Toggle focused window between tiled and floating.
.It Cm always_raise
When set tiled windows are allowed to obscure floating windows.
.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.
.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) 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 "+".
For 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.
.Sh QUIRKS
.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 quirks 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 FULLSCREEN
Remove border to allow window to use full screen size.
.It FOCUSPREV
On exit force focus on previously focused application not previous application
in the stack.
.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.
.Sh EWMH
.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
.Pp
A window can be focused by sending a _NET_ACTIVE_WINDOW client message
to the root window.
For example, using
.Xr wmctrl 1
to send the message
(assuming 0x4a0000b is the id of the window to be focused):
.Bd -literal -offset indent
$ wmctrl \-i \-a 0x4a0000b
.Ed
.Pp
Windows can be closed by sending a _NET_CLOSE_WINDOW client message
to the root window.
For example, using
.Xr wmctrl 1
to send the message
(assuming 0x4a0000b is the id of the window to be closed):
.Bd -literal -offset indent
$ wmctrl \-i \-c 0x4a0000b
.Ed
.Pp
Windows can be floated and un-floated by adding or removing the
_NET_WM_STATE_ABOVE atom from the _NET_WM_STATE property of the window.
This can be achieved by sending a _NET_WM_STATE client message to the
root window.
For example, the following toggles the floating state of
a window using
.Xr wmctrl 1
to send the message (assuming 0x4a0000b is the  id of the window floated
or un-floated):
.Bd -literal -offset indent
$ wmctrl \-i \-r 0x4a0000b \-b toggle,_NET_WM_STATE_ABOVE
.Ed
.Pp
Floating windows can also be resized and moved by sending a
_NET_MOVERESIZE_WINDOW client message to the root window.
For example,
using
.Xr wmctrl 1
to send the message (assuming 0x4a0000b is the id of
the window to be resize/moved):
.Bd -literal -offset indent
$ wmctrl \-i \-r 0x4a0000b \-e 0,100,50,640,480
.Ed
.Pp
This moves the window to (100,50) and resizes it to 640x480.
.Pp
Any _NET_MOVERESIZE_WINDOW events received for stacked windows are ignored.
.Sh SIGNALS
Sending
.Nm
a HUP signal will restart it.
.Sh FILES
.Bl -tag -width "/etc/sscrotwm.confXXX" -compact
.It Pa ~/.sscrotwm.conf
.Nm
user specific settings.
.It Pa /etc/sscrotwm.conf
.Nm
global settings.
.El
.Sh HISTORY
.Nm
was forked from scrotwm, which was inspired by xmonad & dwm.
.Sh AUTHORS
.An -nosplit
.Nm
was written by:
.Bl -tag -width "Jacob Courtneay Aq jacob@sporkexec.com " -offset indent -compact
.It Cm Jacob Courtneay Aq jacob@sporkexec.com
.El
.Pp
scrotwm was written by:
.Bl -tag -width "Ryan Thomas McBride Aq mcbride@countersiege.com " -offset indent -compact
.It Cm Marco Peereboom Aq marco@peereboom.us
.It Cm Ryan Thomas McBride Aq mcbride@countersiege.com
.It Cm Darrin Chandler Aq dwchandler@stilyagin.com
.It Cm Pierre-Yves Ritschard Aq pyr@spootnik.org
.It Cm Tuukka Kataja Aq stuge@xor.fi
.It Cm Jason L. Wright Aq jason@thought.net
.It Cm Reginald Kennedy Aq rk@rejii.com
.It Cm Lawrence Teo Aq lteo@lteo.net
.It Cm Tiago Cunha Aq tcunha@gmx.com
.El