.\"	$OpenBSD: cwm.1,v 1.17 2007/11/28 16:35:52 ian Exp $
.\"
.\" The following requests are required for all man pages.
.Dd June 29, 2007
.Dt CWM 1
.Os
.Sh NAME
.Nm cwm
.Nd a lightweight and efficient window manager for X11
.Sh SYNOPSIS
.\" For a program:  program [-abc] file ...
.Nm cwm
.Op Fl s
.Op Fl d Ar display
.Op Fl f Ar fontname
.Sh DESCRIPTION
.Nm
is a window manager for X11.
It was originally inspired by evilwm, but was rewritten from scratch
due to limitations in the evilwm codebase.
The from-scratch rewrite borrowed some code from 9wm.
.Nm
contains many new features which all concentrate on the efficiency and
transparency of window management.
.Nm
also aims to maintain the simplest and most pleasant aesthetic.
.Pp
The following notation is used throughout this page:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It Ic C
Control
.It Ic M
Meta (Alt on PCs)
.It Ic S
Shift
.It Ic M1
Left mouse button
.It Ic M2
Middle mouse button
.It Ic M3
Right mouse button
.El
.Pp
.Nm
is very simple in its use.
Most of the actions are initiated via keybindings.
The current keybindings are described below;
their functionality is described in more detail later.
.Pp
.Bl -tag -width "C-M-EscapeXXX" -offset indent -compact
.It Ic C-M-Enter
Spawn a new terminal.
.It Ic C-M-Delete
Lock the screen.
.It Ic M-Enter
Hide current window.
.It Ic M-Down
Lower current window.
.It Ic M-Up
Raise current window.
.It Ic M-/
Search for windows.
.It Ic C-/
Search for applications.
.It Ic C-M-n
Label current window.
.It Ic M-Tab
Cycle through currently visible windows.
.It Ic M-S-Tab
Reverse cycle through currently visible windows.
.It Ic C-M-x
Delete current window.
.It Ic C-M-Escape
Enter group edit mode.
.It Ic C-M-[n]
Select group n, where n is 1-9.
.It Ic C-M-0
Select all groups.
.It Ic M-Right
Switch to next group.
.It Ic M-Left
Switch to previous group.
.It Ic C-M-f
Toggle full-screen size of window.
.It Ic C-M-=
Toggle vertical maximization of window.
.It Ic M-?
Spawn
.Dq Exec program
dialog.
.It Ic M-.
Spawn
.Dq Ssh to
dialog.
This parses
.Pa $HOME/.ssh/known_hosts
to provide host auto-completion.
.Xr ssh 1
will be executed via the configured terminal emulator.
.It Ic CM-q
Spawn
.Dq Exec WindowManager
dialog; allows you to switch from
.Nm
to another window manager without restarting the X server.
.El
.Pp
The mouse bindings are also important, they are:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It M-M1
Move a window.
.It C-M-M1
Toggle a window's membership in the current group.
A blue highlight indicates the window has been added to the group;
a red highlight indicates it has been removed.
.It M-M2
Resize a window/select a window.
.It M-M3
Lower a window.
.El
.Pp
The options for
.Nm
are as follows:
.Bl -tag -width Ds
.It Fl d Ar display
Specify the display to use.
.It Fl f Ar fontname
Makes the
.Xr Xft 3
font string
.Ar fontname
the default font.
.It Fl s
Set sticky group mode on.
The default behavior for new windows is to not assign any group.
This changes the default behavior to assigning the currrently selected
group to any newly created windows.
.El
.Sh POINTER MOVEMENT
The pointer can be moved with the use of the keyboard through bindings.
C-[UP|DOWN|LEFT|RIGHT] moves the pointer a small amount, while
C-shift-[UP|DOWN|LEFT|RIGHT] moves the pointer a larger amount.
For example, to move the pointer to the left by a small amount,
press C-LEFT.
To move the pointer down by a larger amount, press C-shift-DOWN.
.Sh WINDOW MOVEMENT AND RESIZING
.Nm
windows can be moved with the use of the keyboard through Vi-like bindings.
M-[hjkl] moves the current window a small amount, while M-shift-[hjkl] moves
the current window a larger amount.
For example, to move the current window to the left a small amount, press M-h.
To move the current window down by a larger amount, press M-shift-j.
.Pp
Similarly, windows may be resized with the same keybindings with the addition
of the Control key.
C-M-[hjkl] resizes the window a small amount and C-M-shift-[hjkl]
resizes by a larger increment.
.Sh SEARCH
.Nm
features the ability to search for windows by their current title,
old titles, and by their label.
The priority for the search results are: label, current title,
old titles in reverse order, and finally window class name.
.Nm
keeps a history of the 5 previous titles of a window.
.Pp
When searching, the leftmost character of the result list may show a
flag:
.Pp
.Bl -tag -width 10n -offset -indent -compact
.It !
The window is the currently focused window.
.It &
The window is hidden.
.El
.Pp
The following keybindings may be used to navigate the result list:
.Pp
.Bl -tag -width "[Down] or C-sXXX" -offset indent -compact
.It Ic [Down] No or Ic C-s
Select the next window in the list.
.It Ic [Up] No or Ic C-r
Select the previous window in the list.
.It Ic C-u
Clear the input.
.It Ic [Enter]
Focus the selected window.
.It Ic [Esc]
Quit.
.It Ic C-a
Whenever there are no matching windows, list every window.
.El
.Sh GROUPS
.Nm
has the ability to group windows together, and use the groups to
perform operations on the entire group instead of just one window.
Currently, the only operation that is supported is to hide and unhide
the grouped windows.
Together with the
.Fl s
option, this can be used to emulate virtual desktops.
.Pp
To edit groups, enter the group edit mode, and select/unselect the
groups with the group selection mouse click.
A blue border will be shown on the currently selected windows.
The group selection keyboard shortcuts can also be used to change
which group to edit.
.Sh MENUS
Menus are recalled by clicking the mouse on the root window:
.Pp
.Bl -tag -width 10n -offset -indent -compact
.It M1
Show list of currently hidden windows.
Clicking on an item will unhide that window.
.It M2
Show list of currently defined groups.
Clicking on an item will hide/unhide that group.
.It M3
Show list of applications as defined in
.Pa ~/.calmwm .
Clicking on an item will spawn that application.
.El
.Sh ENVIRONMENT
.Bl -tag -width "DISPLAYXXX"
.It DISPLAY
.Nm
starts on this display unless the
.Fl d
option is given.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa ~/.calmwm
Any directory entries here are shown in the application menu.
When it is selected, the image is executed with
.Xr execve 2 .
One use of this is to create symbolic links for your favorite
applications in this directory using
.Xr ln 1 .
.Pp
The entries
.Nm term
and
.Nm lock
have a special meaning.
When they exist they point to the terminal program and screen locking
programs used by the keybindings specified above.
The defaults for these are
.Xr xterm 1
and
.Xr xlock 1 ,
respectively.
.It Pa ~/.calmwm/.autogroup
Symlinks in this directory are read upon startup and control the
automatic grouping feature, which is based on the window name and class
properties.
To obtain the name and class of a window, use
.Ql xprop WM_CLASS ,
then click on the window.
The first quoted string is the window name; the second one is the
window class.
.Pp
The name of a link can be the window class, or the window class and name
separated by a comma.
The link target is a group name (one, two, \&..., nine).
For example, to make all windows in the
.Xr xterm 1
class go to the third group:
.Bd -literal -offset indent
$ ln -s three ~/.calmwm/.autogroup/XTerm
.Ed
.It Pa ~/.calmwm/.settings
Files in this directory cause various configuration options to be
set or unset.
Currently the only setting availiable is whether or not sticky groups
are activated.
To activate sticky groups create a file in this directory with the name
``sticky''.
.It Pa ~/.calmwm/.ignore
Any files in this directory cause
.Nm
to ignore programs by that name by not drawing borders around them.
For example the command
.Bd -literal -offset indent
$ ln -s three ~/.calmwm/.ignore/xclock
.Ed
will cause any instances of
.Xr xclock 1
to not have borders.
.It Pa ~/.calmwm/.keys
Symlinks in this directory cause the creation of keyboard shortcuts.
The default shortcuts will always be created. In case of conflict, 
user-defined shortcuts take precidence.
The name of a link here is first the modifier keys, followed by a ``-''.
The following modifiers are recognised:
.Bl -tag -width Ds
.It Pa C
The Control key.
.It Pa M
The Meta key.
.It Pa S
The Shift key.
.It Pa 2
The Mod2 key.
.It Pa 3
The Mod3 key.
.It Pa 4
The Mod4 key (normally the windows key).
.El
The ``-'' should be followed by either a keysym name, taken from
.Pa /usr/X11R6/include/X11/keysymdef.h ,
or a numerical keycode value enclosed in ``[]''.
The target of the link should be either the name of a task from the
``name_to_kbfunc''
structure in
.Pa /usr/src/xenocara/app/cwm/conf.c ,
or, alternatively it should be the commandline that is wished to be executed.
A special case is the ``unmap'' keyword, which causes any bindings using the 
named shortcut to be removed. This can be used to remove a binding which conflicts
with an application.
For example, to cause
.Ic C-M-r
to add a label to a window:
.Bd -literal -offset indent
$ ln -s "label" ~/.calmwm/.keys/CM-r
.Ed
Launch an xterm running
.Xr top 1
with C-S-Enter:
.Bd -literal -offset indent
$ ln -s "/usr/X11R6/bin/xterm -e top" ~/.calmwm/.keys/CS-Return
.Ed
Remove a keybinding for Mod4-o
.Bd -literal -offset indent
$ ln -s "unmap" 4-o
.Ed
.El
.Sh AUTHORS
.An -nosplit
.Pp
.Nm
contains some code from 9wm.
.Pp
The
.Nm
software has been developed by
.An Marius Aamodt Eriksen Aq marius@monkey.org
with contributions from
.An Andy Adamson Aq dros@monkey.org ,
.An Niels Provos Aq provos@monkey.org ,
and
.An Antti Nykänen Aq aon@iki.fi .
Ideas, discussion with many others.
.\" .Sh HISTORY
.\".Aq marius@monkey.org .
.\" .Sh CAVEATS