shod.1

.TH SHOD 1
.SH NAME
.B shod
\- hybrid window manager
.SH SYNOPSIS
.B shod
.SH DESCRIPTION
.B shod
is a hybrid (tiling and floating) reparenting X11 window manager which supports tabs, multiple monitors, themes, and window rules.
.B shod
sets no keybindings;
reads no configuration other than X resources;
and works only via mouse with a given key modifier (Alt by default)
and by responding to client messages with EWMH hints
(so it is needed
.IR wmctrl (1)
to control shod).
.PP
.B shod
maintains one monitor for each physical monitor found by
.IR Xinerama (1).
One of the monitors is the focused one, where new windows go to when they are created.
Each monitor contains a set of desktops.
One of the desktops of a monitor is the focused desktop for that monitor.
.PP
Most windows are displayed in frames (containers with borders, titlebars and buttons; each window is a tab in a frame).
But some windows are special and are displayed in different ways.
.SS Frames
Windows are displayed in frames.
A frame contains borders (four edges and four corners),
tabs (one for each client in the window),
two buttons (a minimize and a close button),
the content (which is the window of the selected tab),
and an optional dialog window centered on the content.
The buttons and the tabs of a frame together are called the title bar of that frame.
Windows can be grouped into the same frame with tabs.
One of the tabs is the selected tab.
Only the contents of the selected tab of a frame is shown in that frame.
.PP
Each frame has one of the following four states:
.TP
Minimized
Minimized frames belong to no monitor or desktop.
Minimized frames are not shown on the screen.
When a minimized frame is unminimized,
it becomes a normal frame on the focused desktop of the focused monitor.
.TP
Sticky
Sticky frames belong only to a monitor; but they do not belong to any desktop.
Instead, they are \(lqsticked\(rq to the monitor, and they appear on the screen
no matter which desktop is focused on that monitor.
.TP
Tiled
Tiled frames belong to a desktop and its monitor.
The monitor is split up horizontally into columns.
Each column handles arbitrary frames and arranges them vertically in a nonoverlapping way.
They can then be moved and resized between and within columns at will.
(This tiling style is the same used by the old wmii(1) window manager and the acme(1) editor).
.TP
Normal
Normal frames belong to a desktop and its monitor.
Normal frames, along with sticky frames, are called floating frames.
Normal frames appear only when its desktop is the focused one for its monitor.
.PP
A non\-minimized frame can also be made fullscreen or shaded, but not both.
A floating (sticky or normal) frame can also be raised above other floating windows
or lowered below other floating frames.
.PP
When a new frame spawns, it is set as
.BR Normal ,
and it is placed in an unoccupied region of the monitor.
The first frame in a monitor is centered on the monitor.
.PP
The frame stacking order is the following (from bottom-to-top):
.IP \(bu 2
Tiled frames appear below any other frames.
.IP \(bu 2
Lowered floating frames appear on top of tiled frames.
.IP \(bu 2
Regular floating frames appear on top of lowered floating frames.
.IP \(bu 2
Raised floating frames appear on top of regular floating frames.
.IP \(bu 2
Fullscreen frames appear on top of raised floating frames.
.PP
.B shod
sets the property
.B _SHOD_TAB_GROUP
on each window to the ID of the window of the focused tab of its frame.
All the windows in the focused frame have the
.B _NET_WM_STATE_FOCUSED
atom set in the
.B _NET_WM_STATE
property.
.PP
The initial state of a window and whether it will be displayed in a new frame
or in a new tab of an existing frame is specified by the values of the
.BR *desktop ,
.BR *state ,
and
.B *autotab
X resources.
.PP
Transient/dialog windows are not mapped into a new frame or a new tab of an existing frame;
instead, they are centered on the content of the window it is a transient for.
This behavior is the same as sheets in macOS window system.
.SS Prompt
A window of type
.B _NET_WM_WINDOW_TYPE_PROMPT
(called prompt window)
is mapped on the top of the focused monitor.
This window will stay focused and mapped until be closed or a mouse
button is pressed outside that window.  This is an EWMH extension,
only used by
.IR xprompt (1).
.PP
.B shod
does not change the size of the prompt window.
However, shod changes its position.
.SS Desktop windows
Windows of type
.B _NET_WM_WINDOW_TYPE_DESKTOP
(called desktop windows)
are mapped bellow all other windows and are stacked on the order they are spawned.
Desktop windows cannot be manipulated.
Desktop windows have no decoration around them.
.PP
Desktop windows indicates a desktop feature.
That includes windows such as
.IR conky (1)
and windows that manage desktop icons.
.PP
.B shod
does not change the size nor the position of desktop windows.
.SS Notification windows
Windows of type
.B _NET_WM_WINDOW_TYPE_NOTIFICATION
(called notifications windows)
are popped up on the top right corner, one above another.
Notification windows cannot be manipulated.
Notification windows have a decoration around them;
this decoration is the same as the borders of the active frame
(or, for urgent notifications, the same as the borders of an urgent frame).
.PP
An example of a notification window would be a bubble appearing with informative text such as
"Your laptop is running out of power" etc.
.PP
The screen corner where notification windows pop up can be changed with the
.B shod.notification.gravity
X resource.
.PP
.B shod
does not change the size of notification windows.
However, shod changes its position.
.SH USAGE
There are several ways
.B shod
can manage windows.
See the section
.B EXAMPLES
for examples on how to use
.IR wmctrl (1)
for controlling shod.
.SS Managing windows with the mouse
The main method for managing windows is the mouse.
.PP
The buttons set with the
.B shod.focusButtons
X resource are used to focus a frame when clicking on it.
If no button is specified, the focus follows the mouse pointer.
.PP
The buttons set with the
.B shod.raiseButtons
X resource are used to raise a frame when clicking on it.
.PP
The modifier set with the
.B shod.modifier
X resource is the modifier key.
Pressing the modifier key and dragging a frame with the Button 1
(the left mouse button) will move that frame.
Pressing the modifier key and dragging a frame with the button 3
(the right mouse button) will resize that frame.
.PP
Resizing a frame can also be performed by dragging the frame border with the Button 1,
without pressing any modifier.
Moving a frame can also be performed by dragging the frame border with the button 3,
without pressing any modifier.
Moving a frame can also be performed by dragging a tab of the frame with the Button 1,
without pressing any modifier.
.PP
A tab can be detached from its frame by dragging it with the Button 3.
A detached tab, while being dragged with the Button 3,
can be attached into another frame by dropping it into another frame's title bar.
Double clicking on a tab shades or unshades the frame.
.PP
Each frame has two buttons on its title bar.
Clicking with the mouse Button 1 on the left button (called the minimize button)
minimizes the frame.
Clicking with the mouse Button 1 on the right button (called the close button)
closes the window on the focused tab, and, if it was the last tab on the frame, deletes the frame.
.PP
When a normal frame is moved from one monitor to another,
that frame moves from the desktop it is in to the focused desktop
of the monitor it is moved to.
.SS Managing windows with state client messages
The
.IR wmctrl (1)
utility can be used to send client messages to the window manager,
and
.B shod
respects those messages in different ways.
For example, running the following command toggles the sticky option
on the active frame.
.IP
.EX
$ wmctrl -r :ACTIVE: -b toggle,sticky
.EE
.IP \(bu 2
Setting the
.B sticky
state on a window, sticks the window's frame on the monitor.
.IP \(bu 2
Setting both the
.BR maximize_vert " and " maximize_horz
states on a window, tiles the window's frame.
For more information on manipulating tiled windows, see the section
.B Managing tiled windows
below.
.IP \(bu 2
Setting the
.B hidden
state on a window,
minimizes the window's frame
(it won't be displayed on any desktop or on any monitor).
.IP \(bu 2
Setting the
.B fullscreen
state on a window, makes the content of the window's frame be maximized to fit the entire screen.
.IP \(bu 2
Setting the
.B above
state on a floating window, raises the window's frame above all other floating frames.
.IP \(bu 2
Setting the
.B below
state on a floating window, lowers the window's frame below all other floating frames.
.IP \(bu 2
Setting the
.B shaded
state on a window, collapses the window's frame into its title bar.
.PP
All other client messages are ignored.
.SS Managing windows with other EWMH client messages
.B shod
acts upon other EWMH client messages sent to windows and to the root window.
Most client messages can be sent via
.IR wmctrl (1)
with a specific option.
The options and the messages they send are specified below.
.IP \(bu 2
A message sent with the
.BI \-s " NUMBER"
option of
.IR wmctrl (1)
makes
.B shod
changes the desktop.
That is,
hide the windows on the current desktop and show the windows on a new desktop.
If the desktop is on another monitor,
.B shod
instead moves the pointer to that monitor and focus a window on it.
.IP \(bu 2
A message sent with the
.B \-k on
or
.B \-k off
options of
.IR wmctrl (1)
makes
.B shod
show or hide the desktop, respectively.
.IP \(bu 2
A message sent with the
.BI \-a " WINDOW"
option of
.IR wmctrl (1)
makes
.B shod
change the active frame.
That is, focus and raise the frame of the specified window.
.IP \(bu 2
A message sent with the
.BI \-c " WINDOW"
option of
.IR wmctrl (1)
makes
.B shod
close gently the specified window.
.IP \(bu 2
A message sent with the
.BI \-e " POSITION"
option of
.IR wmctrl (1)
makes
.B shod
change the position and geometry of the frame of the specified window.
.IP \(bu 2
A message sent with the
.BI \-t " NUMBER"
option of
.IR wmctrl (1)
makes
shod
move the frame of the specified window to the specified desktop.
.SS Managing windows with configure request events
.B shod
acts upon configure request events sent to windows by resizing and moving their frames
just as if the user have resized or moved them with the mouse.
.SS Managing tiled windows
When a window is maximized, its frame is tiled by
.BR shod .
A tiled frame behaves differently of regular frames.
Tiled frames are organized in columns.
Each tiled frame ocupies a row in a column.
.PP
In order to move a tiled frame from one column to another
just move the frame left or right with
.IR wmctrl (1)
or with the mouse.
This will move the frame from its current column to the column to its
left or right, or it will create a new column, if needed.
.PP
In order to move a tiled frame up or down a column,
just move the frame up or down with
.IR wmctrl (1)
or with the mouse.
.PP
Resizing a tiled frame with
.IR wmctrl (1)
or with the mouse
will change the size of the frame, the size of the column it is in,
and the size of the neighboring frames.
.SH ENVIRONMENT
The following environment variables affect the execution of
.B shod
.TP
.B DISPLAY
The display to start
.B shod
on.
.SH RESOURCES
.B shod
understands the following X resources.
.SS WM Requests
These options control how WM requests are handled.
.TP
.B shod.ignoreIndirect
Window management requests (such as to send a window to a given desktop)
can be originated from one of two different sources:
by the application (indirect request) or by the user (direct request).
Applications requesting themselves to maximize their windows
or send their windows to a given desktop can be an annoyance.
If this resource is set to
.BR true ,
indirect requests are ignored.
.SS Mouse behavior
These resources specify the mouse buttons that control windows
and the keyboard modifier that can be used with mouse buttons.
.TP
.B shod.focusButtons
Which mouse buttons can be used to focus a window when clicking on it.
.I buttons
is a string of numbers 1 to 5 (corresponding to mouse buttons 1 to 5).
For example, setting this resource to
.B 13
makes windows be focused when clicking on them with the mouse buttons 1 and 3
(the left and right mouse buttons, respectively).
If this is set to a blank string, no mouse button is used to focus window,
and
.B shod
uses the focus-follow-cursor focusing style.
By default, focus follows mouse click on button 1.
.TP
.B shod.modifier
Which modifier, from
.B Mod1
to
.B Mod5
is used to move and resize windows with the mouse pointer.
.TP
.B shod.raiseButtons
Which mouse buttons can be used to raise a window when clicking on it.
.I buttons
is a string of numbers 1 to 5 (corresponding to mouse buttons 1 to 5).
For example, setting this resource to
.B 13
makes windows be raised when clicking on them with the mouse buttons 1 and 3
(the left and right mouse buttons, respectively).
By default, raise occurs on mouse click on button 1.
.SS General appearance
These resources control the appearance of frames and whether the titlebar is visible.
.TP
.B shod.font
The font in the X Logical Font Description of the text in the title bar.
.TP
.B shod.theme
Path to a .xpm file containing the border decorations.
The x_hotspot is interpreted as the width of the border for that decoration.
The y_hotspot is interpreted as the width of the buttons for that decoration.
The size of the corner is calculated as the sum of the width of the border and the width of the buttons.
The height of the title bar (and its tabs) is equal to the width of the buttons.
The .xpm file contains in it nine squares representing all the possible decoration states for a frame.
A sample .xpm file is distributed with shod.
.TP
.B shod.hideTitle
If set to \(lqtrue\(rq, the title bars of frames with a single tab are hidden.
.SS Tiling appearance
These resources control the appearance and spacement between tiled frames.
.TP
.B shod.gapOuter
The gap in pixels between the sides of the monitor and the frames.
.TP
.B shod.gapInner
The gap in pixels between the tiled frames.
.TP
.B shod.ignoreGaps
If set to \(lqtrue\(rq, a single tiled frame ingores the gaps.
.TP
.B shod.ignoreTitle
If set to \(lqtrue\(rq, a single tiled frame ingores the title bar.
.TP
.B shod.ignoreBorders
If set to \(lqtrue\(rq, a single tiled frame does not have borders.
.TP
.B shod.mergeBorders
If set to \(lqtrue\(rq, the borders of adjacent tiled frames are merged into a single border.
.SS Window rules
These resources control how a new window is managed.
They are described according to a group
.RB ( role ,
.BR class ,
.BR instance ,
or
.BR title )
and to the description of the group.
User-placed windows ignore rules.
Groups and descriptions are case sensitive.
See the examples for more information.
.TP
.B shod.GROUP.DESCRIPTION.autotab
Controls whether a new window should be tabbed with the focused window if they have the same class.
If set to
.BR floating ,
auto tabbing occurs if the focused window is floating.
If set to
.BR tilingAlways ,
auto tabbing occurs if the focused window is tiled.
If set to
.BR tilingMulti ,
auto tabbing occurs if the focused window is tiled
and there is at least two tiled windows.
If set to
.BR always ,
auto tabbing occurs if the focused window has a visible title bar.
If set to
.BR off ,
auto tabbing does not occur.
.TP
.B shod.GROUP.DESCRIPTION.desktop
Controls in which desktop a new window should be mapped on.
.TP
.B shod.GROUP.DESCRIPTION.state
Controls the initial state of a new window.
If set to
.BR normal ,
the window begins in normal state (the default).
If set to
.BR sticky ,
the window begins sticked on the screen.
If set to
.BR tiled ,
the window begins tiled.
If set to
.BR minimized ,
the window begins minimized.
.TP
.B shod.GROUP.DESCRIPTION.position
TODO
.SS Notification control
This resource control the placement of notification windows.
.TP
.B shod.notification.gravity
Specify the gravity, that is, where in the screen to display notification windows.
The gravity can be "NE" for NorthEastGravity (display on the top right corner of the screen);
"SE" for SouthEastGravity (display on the bottom right corner of the screen);
"C" for CenterGravity (display on the center of the screen); etc.
.TP
.B shod.notification.gap
The gap between notifications.
.SH EXAMPLES
The following is a sample configuration for X resources.
It must be placed in
.B $HOME/.Xresources
or
.B $HOME/.Xdefaults
or other file called by
.IR xrdb (1).
This example makes shod uses a 7 pixels wide gap around and between tiled windows.
It also sets three window rules:
windows with the
.B "browser"
role should be mapped on the second desktop;
windows of class
.B "Zathura"
should be mapped tiled;
and windows of class
.B "XTerm"
should be tabbed with other windows of the same class.
.IP
.EX
shod.gapOuter:                  7
shod.gapInner:                  7
shod.role.browser.desktop:      2
shod.class.Zathura.state:       tiled
shod.class.XTerm.autotab:       always
.EE
.PP
The following is a sample configuration for
.IR sxhkd (1),
a program that binds keypresses (or key releases) to commands.
This example uses
.IR wmctrl (1)
for sending EWMH hints to
.BR shod.
It uses
.IR wmr (1)
(a script shown below) for moving and resizing windows, respectively.
.IP
.EX
# Start terminal
mod1 + Return
	xterm

# Killing windows
mod1 + shift + q
	wmctrl -c :ACTIVE:

# Workspace
mod1 + {1,2,3,4,5,6,7,8,9,0}
	wmctrl -s {0,1,2,3,4,5,6,7,8,9}
mod1 + shift + {1,2,3,4,5,6,7,8,9}
	wmctrl -r :ACITVE: -t {0,1,2,3,4,5,6,7,8,9}

# Resize/move windows with wmr
mod1 + {c, v, shift + c, shift + v}
	wmr 0 0 {-25 0, 0 -25, +25 0, 0 +25}
mod1 + shift + {h, j, k, l}
	wmr {-10 0, 0 10, 0 -10, 10 0} 0 0

# Change window status to sticky/above/below/minimized/fullscreen/maximized
mod1 + shift + {s, a, b, z, f}
	wmctrl -r :ACTIVE: -b toggle,{sticky,above,below,hidden,fullscreen}
mod1 + shift + t
	wmctrl -r :ACTIVE: -b toggle,maximized_vert,maximized_horz

# Call the unminimize.sh script
mod1 + shift + u
	unminimize.sh
.EE
.PP
The previous example binds the following keys to the following commands:
.TP
.B Mod4 + Enter
Spawns a terminal emulator window.
.TP
.B Mod4 + Shift + Q
Gently closes the active windows.
.TP
.B Mod4 + <N>
Go to the N-th desktop.
.TP
.B Mod4 + Shift + <N>
Send active window to the N-th desktop.
.TP
.B Mod4 + C
Shrink the active window horizontally by 25 pixels.
.TP
.B Mod4 + Shift + C
Expand the active window horizontally by 25 pixels.
.TP
.B Mod4 + V
Shrink the active window vertically by 25 pixels.
.TP
.B Mod4 + Shift + V
Expand the active window vertically by 25 pixels.
.TP
.B Mod4 + Shift + H
Move the active window 10 pixels to the left.
.TP
.B Mod4 + Shift + J
Move the active window 10 pixels down.
.TP
.B Mod4 + Shift + K
Move the active window 10 pixels up.
.TP
.B Mod4 + Shift + L
Move the active window 10 pixels to the right.
.TP
.B Mod4 + Shift + S
Make the active window sticky;
or make it normal if it was sticky.
.TP
.B Mod4 + Shift + A
Raise the active window above the others;
or move it to its normal place if it was already above others.
.TP
.B Mod4 + Shift + B
Lower the active window below the others;
or move it to its normal place if it was already below others.
.TP
.B Mod4 + Shift + Z
Hide the active window.
.TP
.B Mod4 + Shift + F
Make the active window fullscreen;
or make it normal if it was already fullscreen.
.TP
.B Mod4 + Shift + T
Tile the active window;
or make it floating if it was already tiled.
.TP
.B Mod4 + Shift + U
Call the unminimize.sh script (see below).
.PP
The following is a sample script for
.IR dmenu (1).
This script lists the minimized windows and unminimizes the selected one.
This script uses
.IR xprop (1)
to obtain the X properties set by
.BR shod.
.IP
.EX
#!/bin/sh

lsw() {
	xprop -notype -f "_NET_CLIENT_LIST" 0x \(aq $0+\en\(aq -root "_NET_CLIENT_LIST" |\e
	cut -d\(aq \(aq -f2- |\e
	sed \(aqs/, */\e
/g\(aq
}

ishidden() {
	xprop -notype -f "_NET_WM_STATE" 32a \(aq $0+\en\(aq -id "$1" "_NET_WM_STATE" |\e
	cut -d\(aq \(aq -f2- |\e
	sed \(aqs/, */\e
/g\(aq | grep -q "_NET_WM_STATE_HIDDEN"
}

printname() {
	name="$(xprop -notype -f "_NET_WM_NAME" 8s \(aq $0+\en\(aq -id "$1" "_NET_WM_NAME" 2>/dev/null)"
	[ "$(echo $name)" = "_NET_WM_NAME: not found." ] && \e
	name="$(xprop -notype -f "WM_NAME" 8s \(aq $0+\en\(aq -id "$1" "WM_NAME" 2>/dev/null)"

	echo $name |\e
	cut -d\(aq \(aq -f2- |\e
	sed \(aqs/, */\e
/g\(aq
}

for win in $(lsw)
do
	ishidden $win && printf "%s: " $win && printname $win
done |\e
dmenu -i -l 8 -p "unminimize window:" |\e
cut -d: -f1 |\e
xargs wmctrl -b toggle,hidden -ir
.EE
.PP
The following script moves and resize the active window by a relative amount of pixels.
.IP
.EX
#!/bin/sh
# wmr: move and resize window relative to its current position and size

set -e

usage() {
	echo "usage: wmr x y w h" >&2
	exit 1
}

[ $# -ne 4 ] && usage
eval $(xdotool getactivewindow getwindowgeometry --shell)
xadd=$1
yadd=$2
wadd=$3
hadd=$4
X=$(( X + xadd ))
Y=$(( Y + yadd ))
WIDTH=$(( WIDTH + wadd ))
HEIGHT=$(( HEIGHT + hadd ))
wmctrl -r :ACTIVE: -e 0,$X,$Y,$WIDTH,$HEIGHT
.EE
.SH SEE ALSO
.IR dmenu (1),
.IR sxhkd (1),
.IR wmctrl (1),
.IR xprompt (1)
.SH BUGS
.RI XSizeHints (3)
are ignored.
Size hints make no sense in a tiled and tabbed window manager.
They only make sense when the size of a single frame depends only on a single window,
and a single window dictates the size of a single frame.
When the size of a frame depends on the size of other frames (as in the tiled situation),
or when a set of windows must have the same size (as in a tabbed situation),
it makes no sense to constrain the size of a frame based on the size hints of a single window,
because the relation from windows to frames is no more one-to-one.
.PP
Naming things is hard.
In the context of X Window System, a "window" can mean
the UI object the user sees on the screen,
or the Xlib object the programmer manipulates on the code.
Usually, there is one window (Xlib object) to one window (UI object),
but since
.B shod
is a tabbed window manager,
there can exist more than one window (Xlib object) in a single window (UI object).
To help on that, this manual uses the term "frame" to call windows (UI object),
and the term "window" to the other sense.
But, for historical reasons, the code uses the term "client" to refer to the UI object (frames).
.PP
EWMH hints (and other properties) may not be updated when they should.
This is a bug and should be reported.