path: root/app/cwm/cwm.1

.\"	$OpenBSD: cwm.1,v 1.65 2019/07/09 21:38:44 kn Exp $
.\"
.\" Copyright (c) 2004,2005 Marius Aamodt Eriksen <marius@monkey.org>
.\"
.\" 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: July 9 2019 $
.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 nv
.Op Fl c Ar file
.Op Fl d Ar display
.Sh DESCRIPTION
.Nm
is a window manager for X11 which contains many features that
concentrate on the efficiency and transparency of window management,
while maintaining the simplest and most pleasant aesthetic.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl c Ar file
Specify an alternative configuration file.
By default,
.Nm
loads
.Pa ~/.cwmrc ,
if present.
Any error messages from lines in the configuration file will be sent to
.Em stderr ;
however,
.Nm
will continue to process the rest of the configuration file.
.It Fl d Ar display
Specify the display to use.
.It Fl n
Configtest mode.
Only check the configuration file for validity.
.It Fl v
Verbose mode.
Multiple
.Fl v
options increase the verbosity.
.El
.Pp
.Nm
actions are initiated either via key or mouse bindings.
The following notations are used throughout this page:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It Ic C
Control key.
.It Ic M
Meta key.
.It Ic S
Shift key.
.It Ic 4
Mod4 (windows) key.
.It Ic M1
Left mouse button.
.It Ic M2
Middle mouse button.
.It Ic M3
Right mouse button.
.El
.Pp
The default key bindings are:
.Pp
.Bl -tag -width "CM-EscapeXXXXX" -offset indent -compact
.It Ic CM-Return
Spawn a new terminal.
.It Ic CM-Delete
Lock the screen.
.It Ic M-Return
Hide current window.
.It Ic M-Down
Lower current window.
.It Ic M-Up
Raise current window.
.It Ic M-slash
Search for windows.
.It Ic C-slash
Search for applications.
.It Ic CM-n
Label current window.
.It Ic M-Tab
Cycle through currently visible windows.
.It Ic MS-Tab
Reverse cycle through currently visible windows.
.It Ic CM-x
Close current window.
.It Ic CM-[n]
Toggle visibility of group n, where n is 1-9.
.It Ic CM-a
Toggle visibility of all groups.
.It Ic CM-g
Toggle group membership of current window.
.It Ic M-Right
Cycle through active groups.
.It Ic M-Left
Reverse cycle through active groups.
.It Ic CMS-f
Toggle freezing geometry of current window.
.It Ic CM-s
Toggle stickiness of current window.
.It Ic CM-f
Toggle full-screen mode of current window.
.It Ic CM-m
Toggle maximization of current window.
.It Ic CM-equal
Toggle vertical maximization of current window.
.It Ic CMS-equal
Toggle horizontal maximization of current window.
.It Ic M-[hjkl]
Move window by a small amount.
.It Ic MS-[hjkl]
Move window by a large amount; see
.Xr cwmrc 5 .
.It Ic CM-[hjkl]
Resize window by a small amount.
.It Ic CMS-[hjkl]
Resize window by a large amount; see
.Xr cwmrc 5 .
.It Ic M-question
Spawn
.Dq exec program
dialog.
.It Ic M-period
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-w
Spawn
.Dq exec WindowManager
menu, allowing a switch to another window manager.
.It Ic CMS-r
Restart.
.It Ic CMS-q
Quit.
.El
.Pp
The default mouse bindings are:
.Pp
.Bl -tag -width "CM-EscapeXXXXX" -offset indent -compact
.It Ic M-M1
Move current window.
.It Ic CM-M1
Toggle group membership of current window.
.It Ic M-M2
Resize current window
.It Ic M-M3
Lower current window.
.It Ic CMS-M3
Hide current window.
.El
.Pp
The following key bindings may be used to navigate
search and exec dialogs:
.Pp
.Bl -tag -width "[Down] or C-s or M-j" -offset indent -compact
.It Ic [Return]
Select item.
.It Ic [Down], C-s No or Ic M-j
Next item.
.It Ic [Up], C-r No or Ic M-k
Previous item.
.It Ic [Backspace] No or Ic C-h
Backspace.
.It Ic C-u
Clear input.
.It Ic C-a
List all available items.
.It Ic [Esc]
Cancel.
.El
.Pp
.Nm
rereads its configuration file when it receives a hangup signal,
.Dv SIGHUP ,
by executing itself with the name and arguments with which it was started.
This is equivalent to the
.Ar restart
function.
.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 Ds -offset indent -compact
.It !
Window is currently focused.
.It &
Window is hidden.
.El
.Sh APPLICATIONS
.Nm
manages a list of applications defined with the
.Cm command
configuration option.
.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.
Together with the
.Pa sticky
option, this can be used to emulate virtual desktops.
.Pp
To edit groups, use the group selection commands to toggle membership
of a group.
A blue border will be shown briefly on windows added to the current group,
and a red border will be shown on those just removed.
.Sh MENUS
Menus are recalled by clicking the mouse on the root window:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It Ic M1
Show list of currently defined windows.
Selecting an item will warp to that window, unhiding it if necessary.
.It Ic M2
Show list of currently defined groups.
Selecting an item will hide/unhide that group.
.It Ic M3
Show list of applications as defined in the configuration file.
Selecting an item will spawn that application.
.El
.Sh ENVIRONMENT
.Bl -tag -width "DISPLAYXXX" -compact
.It DISPLAY
.Nm
starts on this display unless the
.Fl d
option is given.
.El
.Sh FILES
.Bl -tag -width "~/.cwmrcXX" -compact
.It Pa ~/.cwmrc
Default
.Nm
configuration file.
.El
.Sh SEE ALSO
.Xr cwmrc 5
.Sh HISTORY
.Nm
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, however that code
has since been removed or rewritten.
.Pp
.Nm
first appeared in
.Ox 4.2 .
.Sh AUTHORS
.An -nosplit
.Nm
was 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\(:anen Aq aon@iki.fi .
Ideas, discussion with many others.