X-Git-Url: https://code.delx.au/spectrwm/blobdiff_plain/dff29edabae6c98d199542471d2d802517d3c40c..ac945112ba4384fc68fea1e2ee387c5407b05bbb:/spectrwm.1 diff --git a/spectrwm.1 b/spectrwm.1 index 720a38a..6e7f521 100644 --- a/spectrwm.1 +++ b/spectrwm.1 @@ -1,6 +1,6 @@ .\" Copyright (c) 2009-2012 Marco Peereboom .\" Copyright (c) 2009 Darrin Chandler -.\" Copyright (c) 2011-2012 Reginald Kennedy +.\" Copyright (c) 2011-2015 Reginald Kennedy .\" Copyright (c) 2011-2012 Lawrence Teo .\" Copyright (c) 2011-2012 Tiago Cunha .\" Copyright (c) 2012 David Hill @@ -50,16 +50,12 @@ Meta .It Cm S Shift .It Aq Cm Name -Named key -.It Cm M1 -Mouse button 1 -.It Cm M3 -Mouse button 3 +Named key or button .El .Pp .Nm is very simple in its use. -Most of the actions are initiated via key or mouse bindings. +Most of the actions are initiated via key or pointer bindings. See the .Sx BINDINGS section below for defaults and customizations. @@ -71,7 +67,10 @@ 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. +The format of the file is +.Pp +.Dl Ar keyword Li = Ar setting +.Pp For example: .Pp .Dl color_focus = red @@ -82,42 +81,96 @@ Colors need to be specified per the .Xr XQueryColor 3 specification. .Pp +Comments begin with a #. +When a literal +.Ql # +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[]:application, e.g. ws[2]:xterm launches an -xterm in workspace 2. +Defined in the format +.Li ws Ns Bo Ar idx Bc : Ns Ar application , +e.g. ws[2]:xterm launches an +.Xr xterm 1 +in workspace 2. +.Pp +Note that workspace mapping is handled via +.Pa libswmhack.so . +When +.Ic autorun +spawns windows via a daemon, ensure the daemon is started +with the correct +.Pa LD_PRELOAD +in its environment. +.Pp +For example, starting +.Xr urxvtd 1 +via +.Xr xinit 1 : +.Bd -literal -offset indent +LD_PRELOAD=/usr/lib/libswmhack.so.0.0 urxvtd -q -o -f +.Ed +.Pp +Spawned programs automatically have +.Pa LD_PRELOAD +set when executed. .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 -Color of the status bar border in screen +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 -Color of the status bar window in screen +Background color of the status bar(s) in screen .Ar x . -.It Ic bar_delay -Update frequency, in seconds, of external script that populates the status bar. .It Ic bar_enabled -Enable or disable status bar. +Set default +.Ic bar_toggle +state; default is 1. +.It Ic bar_enabled_ws Ns Bq Ar x +Set default +.Ic 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 the 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 in 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 +.Xr dmenu 1 +does not support Xft fonts. .Pp -Example for Xft: +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 -Example for XLFD: +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 @@ -128,12 +181,11 @@ 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 +Set the bar format string, overriding .Ic clock_format and all of the .Ic enabled @@ -146,39 +198,40 @@ It may contain the following character sequences: .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 "+C" Ta "Window class (from WM_CLASS)" .It Li "+D" Ta "Workspace name" .It Li "+F" Ta "Floating indicator" .It Li "+I" Ta "Workspace index" +.It Li "+M" Ta "Number of iconic (minimized) windows in workspace" .It Li "+N" Ta "Screen number" -.It Li "+P" Ta "Window class and title separated by a colon" +.It Li "+P" Ta "Window class and instance separated by a colon" .It Li "+S" Ta "Stacking algorithm" -.It Li "+T" Ta "Window title" +.It Li "+T" Ta "Window instance (from WM_CLASS)" .It Li "+U" Ta "Urgency hint" .It Li "+V" Ta "Program version" -.It Li "+W" Ta "Window name" +.It Li "+W" Ta "Window name (from _NET_WM_NAME/WM_NAME)" .It Li "++" Ta "A literal" Ql + .El .Pp -All character sequences may limit its output to a specific length, for example -+64A. +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 , +Justify the status bar text. +Possible values are +.Ar left , +.Ar center , and -.Pa right . +.Ar 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. +Note that if the output is not 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 +Bind key or button combo to action .Ar x . See the .Sx BINDINGS @@ -186,52 +239,89 @@ section below. .It Ic border_width Set window border thickness in pixels. Disable all borders by setting to 0. +.It Ic boundary_width +Set region containment boundary width in pixels. +This is how far a window must be dragged/resized (with the pointer) +beyond the region edge before it is allowed outside the region. +Disable the window containment effect 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 +.Ic bar_action script. +.It Ic iconic_enabled +Display the number of iconic (minimized) windows in the status bar. +Enable by setting to 1. .It Ic color_focus -Border color of the currently focussed window. +Border color of the currently focused window. +Default is red. +.It Ic color_focus_maximized +Border color of the currently focused, maximized window. +Defaults to the value of +.Ic color_focus . .It Ic color_unfocus -Border color of unfocussed windows. +Border color of unfocused windows, default is rgb:88/88/88. +.It Ic color_unfocus_maximized +Border color of unfocused, maximized windows. +Defaults to the value of +.Ic color_unfocus . .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. +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 +.Ar first , +.Ar next , +.Ar previous (default) and -.Pa last . -.Pa next +.Ar last . +.Ar next and -.Pa previous +.Ar 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. +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 +.Ar first and -.Pa last +.Ar last (default). .It Ic focus_mode -Using a value of -.Pa follow_cursor -will make the window manager focus the window -under the mouse when switching workspaces and creating windows. +Window focus behavior with respect to the pointer. +Possible values: +.Pp +.Bl -tag -width "default" -offset indent -compact +.It Ar default +Set window focus on border crossings caused by cursor motion and +window interaction. +.It Ar follow +Set window focus on all cursor border crossings, including workspace switches +and changes to layout. +.It Ar manual +Set window focus on window interaction only. +.El +.It Ic maximize_hide_bar +When set to 1, +.Ic maximize_toggle +will also hide/restore the bar visibility of the affected workspace. +Defaults to 0. +.It Ic java_workaround +Workaround a Java GUI rendering issue on non-reparenting window managers by +impersonating the LG3D window manager, written by Sun. +Default is 1. .It Ic keyboard_mapping -Clear all key bindings and load new key bindings from the specified file. +Clear all key bindings (not button bindings) and load new bindings from the +specified file. This allows you to load pre-defined key bindings for your keyboard layout. See the .Sx KEYBOARD MAPPING FILES @@ -240,75 +330,92 @@ 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 +.Li ws Ns Bo Ar idx Bc : Ns Ar master_grow : Ns Ar master_add : Ns Ar stack_inc : Ns Ar always_raise : Ns Ar stack_mode , +e.g. ws[2]:-4:0:1:0:horizontal sets worskspace 2 to the horizontal stack +mode, shrinks the master area by 4 ticks and adds one window to the +stack, while maintaining default floating window behavior. +Possible +.Ar stack_mode +values are +.Ar vertical , +.Ar vertical_flip , +.Ar horizontal , +.Ar horizontal_flip and -.Pa fullscreen . +.Ar fullscreen . .Pp See -.Pa master_grow , -.Pa master_shrink , -.Pa master_add , -.Pa master_del , -.Pa stack_inc , -.Pa stack_dec , +.Ic master_grow , +.Ic master_shrink , +.Ic master_add , +.Ic master_del , +.Ic stack_inc , +.Ic stack_dec , +.Ic stack_balance , and -.Pa always_raise +.Ic 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 +One should familiarize oneself with these commands before experimenting +with the +.Ic 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 name +Set the name of a workspace at start-of-day. +Defined in the format +.Li ws Ns Bo Ar idx Bc : Ns Ar name , +e.g. ws[1]:Console sets the name of workspace 1 to +.Dq Console . .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 +.It Ic quirk Ns Bq Ar c Ns Li : Ns Ar i Ns Li : Ns Ar n Add "quirk" for windows with class -.Ar c +.Ar c , +instance +.Ar i 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[]:WIDTHxHEIGHT+X+Y, -e.g.\& screen[1]:800x1200+0+0. +Allocates a custom region, removing any autodetected regions which occupy the +same space on the screen. +Defined in the format +.Li screen Ns Bo Ar idx Ns Bc : Ns Ar width Ns x Ns Ar height Ns + Ns Ar x Ns + Ns Ar 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 +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 +.Ar first , +.Ar next , +.Ar previous and -.Pa last +.Ar last (default). -.Pa next +.Ar next and -.Pa previous +.Ar previous are relative to the focused window. .It Ic stack_enabled -Enable or disable displaying the current stacking algorithm in the status bar. +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, @@ -326,80 +433,107 @@ Users may need to set program[term] (see the section) to use an alternate copy of the .Xr xterm 1 binary without the setgid bit set. -.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. +.It Ic tile_gap +Pixel width of empty space between tiled windows. +Negative values cause overlap. +Set this to the opposite of +.Ic border_width +to collapse the border between tiles. +Disable by setting to 0. +.It Ic urgent_collapse +Minimizes the space consumed by the urgency hint indicator by removing the +placeholders for non-urgent workspaces, the trailing space when there are +urgent windows and the default leading space. 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 . +Enable or disable the urgency hint indicator in the status bar. +Note that many terminal emulators require an explicit setting for the bell +character to trigger urgency on the window. +In +.Xr xterm 1 , +for example, one needs to add the following line to +.Pa .Xdefaults : +.Bd -literal -offset indent +xterm.bellIsUrgent: true +.Ed .It Ic verbose_layout -Enable or disable displaying the current master and stack values in the status -bar. +Enable or disable displaying the current master window count and stack column/row +count in the status bar. +Enable by setting to 1. +See +.Ar master_add , +.Ar master_del , +.Ar stack_inc +and +.Ar stack_dec +for more information. +.It Ic workspace_clamp +Prevents workspaces from being swapped when attempting to switch to a workspace +that is mapped to another region. +Use +.Ar warp_focus +if you want to focus on the region containing the workspace and +.Ar warp_pointer +if you want to also send the pointer. +Enable by setting to 1. +.It Ic window_class_enabled +Enable or disable displaying the window class name (from WM_CLASS) in the +status bar. +Enable by setting to 1. +.It Ic window_instance_enabled +Enable or disable displaying the window instance name (from WM_CLASS) in the +status bar. Enable by setting to 1. .It Ic window_name_enabled -Enable or disable displaying the window name in the status bar. +Enable or disable displaying the window display name (from _NET_WM_NAME/WM_NAME) +in the status bar. Enable by setting to 1. .Pp To prevent excessively large window names from pushing the remaining text off -the screen, it's limited to 64 characters, by default. +the bar, it's limited to 64 characters, by default. See the .Ic bar_format option for more details. +.It Ic warp_focus +Focus on the target window/workspace/region when clamped. +For example, when attempting to switch to a workspace that is mapped on another +region and +.Ar workspace_clamp +is enabled, focus on the region with the target workspace. +Enable by setting to 1. +.It Ic warp_pointer +Centers the pointer on the focused window when using bindings to +change focus, switch workspaces, change regions, etc. +Enable by setting to 1. .It Ic workspace_limit -Set the total number of workspaces available. Minimum is 1, maximum is 22, default is 10. +Set the total number of workspaces available. +Minimum is 1, maximum is 22, default is 10. .El .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. +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 -The default programs are described below: -.Pp -.Bl -tag -width "screenshot_wind" -offset indent -compact -.It Cm term -xterm -.It Cm screenshot_all -screenshot.sh full -.It Cm screenshot_wind -screenshot.sh window -.It Cm lock -xlock -.It Cm initscr -initscreen.sh -.It Cm menu -dmenu_run \-fn $bar_font \-nb $bar_color \-nf $bar_font_color \-sb $bar_border \-sf $bar_color -.El -.Pp Custom programs in the configuration file are specified as follows: .Pp -.Dl program[] = [ [... ]] +.Dl program Ns Bo Ar action Bc = Ar progpath Op Ar arg Op Ar arg ... .Pp -.Aq name +.Ar action is any identifier that does not conflict with a built-in action or keyword, -.Aq progpath +.Ar progpath is the desired program, and -.Aq arg +.Ar arg is zero or more arguments to the program. .Pp -The following variables represent settable values in -.Nm -(see the -.Sx CONFIGURATION FILES -section above), -and may be used in the -.Aq arg -fields and will be substituted for values at the time the program is spawned: +Remember that when using +.Ql # +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 @@ -408,39 +542,74 @@ fields and will be substituted for values at the time the program is spawned: .It Cm $bar_font_color .It Cm $color_focus .It Cm $color_unfocus +.It Cm $dmenu_bottom +\-b if +.Ic bar_at_bottom +is enabled. +.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 Mod+Shift+B launches firefox +bind[ff] = MOD+Shift+b # Now M-S-b launches firefox .Ed .Pp -To undo the previous: +To cancel the previous, unbind it: .Bd -literal -offset indent -bind[] = Mod+Shift+b -program[ff] = +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 $dmenu_bottom \-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 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 .Sh BINDINGS .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-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 +provides many functions (or actions) accessed via key or pointer bindings. .Pp -The default key bindings are described below: +The default bindings are listed below: .Pp .Bl -tag -width "M-j, M-XXXXXX" -offset indent -compact +.It Cm Ns Aq Cm Button1 +focus +.It Cm M- Ns Aq Cm Button1 +move +.It Cm M- Ns Aq Cm Button3 +resize +.It Cm M-S- Ns Aq Cm Button3 +resize_centered .It Cm M-S- Ns Aq Cm Return term .It Cm M-p @@ -451,10 +620,12 @@ quit restart .It Cm M- Ns Aq Cm Space cycle_layout -.It Cm M-S- Ns Aq Cm \e +.It Cm M-S-\e flip_layout .It Cm M-S- Ns Aq Cm Space stack_reset +.It Cm Aq Ar unbound +stack_balance .It Cm M-h master_shrink .It Cm M-l @@ -481,12 +652,16 @@ focus_next focus_prev .It Cm M-m focus_main +.It Cm M-u +focus_urgent .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 @@ -495,6 +670,14 @@ wind_kill .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 Aq Ar unbound +mvrg_next +.It Cm Aq Ar unbound +mvrg_prev .It Cm M- Ns Aq Cm Right ws_next .It Cm M- Ns Aq Cm Left @@ -505,10 +688,18 @@ ws_next_all ws_prev_all .It Cm M-a ws_prior +.It Cm M-S- Ns Aq Cm Down +ws_prev_move +.It Cm M-S- Ns Aq Cm Up +ws_next_move .It Cm M-S- Ns Aq Cm Right -screen_next +rg_next .It Cm M-S- Ns Aq Cm Left -screen_prev +rg_prev +.It Cm Aq Ar unbound +rg_move_next +.It Cm Aq Ar unbound +rg_move_prev .It Cm M-s screenshot_all .It Cm M-S-s @@ -525,6 +716,12 @@ initscr iconify .It Cm M-S-w uniconify +.It Cm M-e +maximize_toggle +.It Cm M-S-e +fullscreen_toggle +.It Cm M-r +raise .It Cm M-S-r always_raise .It Cm M-v @@ -556,6 +753,16 @@ search_win The action names and descriptions are listed below: .Pp .Bl -tag -width "M-j, M-XXXX" -offset indent -compact +.It Cm focus +Focus window/region under pointer. +.It Cm move +Move window with pointer while binding is pressed. +.It Cm resize +Resize window with pointer while binding is pressed. +.It Cm resize_centered +Same as +.Ic resize +but keep window centered. .It Cm term Spawn a new terminal (see @@ -578,6 +785,8 @@ Cycle layout. Swap the master and stacking areas. .It Cm stack_reset Reset layout. +.It Cm stack_balance +Balance master/stacking area. .It Cm master_shrink Shrink master area. .It Cm master_grow @@ -598,12 +807,17 @@ Focus next window in workspace. Focus previous window in workspace. .It Cm focus_main Focus on main window in workspace. +.It Cm focus_urgent +Focus on next window with the urgency hint flag set. +The workspace is switched if needed. .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 status bar in all workspaces. +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 @@ -613,13 +827,31 @@ Switch to workspace .Ar n , where .Ar n -is 1 through workspace_limit. +is 1 through +.Ic workspace_limit . .It Cm mvws_ Ns Ar n Move current window to workspace .Ar n , where .Ar n -is 1 through workspace_limit. +is 1 through +.Ic 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 mvrg_next +Move current window to workspace in next region. +.It Cm mvrg_prev +Move current window to workspace in previous region. .It Cm ws_next Switch to next workspace with a window in it. .It Cm ws_prev @@ -628,12 +860,20 @@ Switch to previous workspace with a window in it. 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 screen_next -Move pointer to next region. -.It Cm screen_prev -Move pointer to previous region. +.It Cm rg_next +Switch to next region. +.It Cm rg_prev +Switch to previous region. +.It Cm rg_move_next +Switch region to next screen. +.It Cm rg_move_prev +Switch region to previous screen. .It Cm screenshot_all Take screenshot of entire screen (if enabled) (see @@ -661,11 +901,19 @@ above). .It Cm iconify Minimize (unmap) currently focused window. .It Cm uniconify -Maximize (map) window returned by dmenu selection. +Restore (map) window returned by +.Xr dmenu 1 +selection. +.It Cm maximize_toggle +Toggle maximization of focused window. +.It Cm fullscreen_toggle +Toggle fullscreen state of focused window. +.It Cm raise +Raise the current window. .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). +Fake a middle mouse button click (Button2). .It Cm width_shrink Shrink the width of a floating window. .It Cm width_grow @@ -692,40 +940,88 @@ Search the windows in the current workspace. .Pp Custom bindings in the configuration file are specified as follows: .Pp -.Dl bind[] = +.Dl bind Ns Bo Ar action Bc = Ar combo .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: +.Ar action +is one of the actions listed above (or empty to unbind) and +.Ar combo +is in the form of zero or more modifier keys and/or special arguments +(Mod1, Shift, MOD, etc.) and a normal key (b, Space, etc.) +or a button (Button1 .. Button255), separated by +.Ql + . +Multiple key/button combinations may be bound to the same action. +.Pp +Special arguments: +.Bl -tag -width "anymodxxxx" -offset indent -compact +.It Cm MOD +Substituted for the currently defined +.Ic modkey . +.It Cm ANYMOD +Select all modifier combinations not handled by another binding. +.It Cm REPLAY +Reprocess binding press/release events for other programs to handle. Unavailable for +.Ic move , +.Ic resize +and +.Ic resize_centered . +.El +.Pp +.Cm MOD +example: .Bd -literal -offset indent bind[reset] = Mod4+q # bind Windows-key + q to reset bind[] = Mod1+q # unbind Alt + q +bind[move] = MOD+Button3 # Bind move to M-Button3 +bind[] = MOD+Button1 # Unbind default move binding. .Ed .Pp -To use the currently defined -.Ic modkey , -specify MOD as the modifier key. +.Cm ANYMOD +example: +.Bd -literal -offset indent +bind[focus] = ANYMOD+Button3 +bind[move] = MOD+Button3 +.Ed .Pp -Multiple key combinations may be bound to the same action. +In the above example, +.Cm M- Ns Aq Cm Button3 +initiates +.Ic move +and +.Cm Aq Cm Button3 +pressed with any other combination of modifiers +sets focus to the window/region under the pointer. .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 å: +.Cm REPLAY +example: +.Bd -literal -offset indent +bind[focus] = REPLAY+Button3 +.Ed +.Pp +In the above example, when +.Cm Aq Cm Button3 +is pressed without any modifier(s), focus is set to the window under the +pointer and the button press is passed to the window. +.Pp +To bind non-latin characters such as \[oa] or \[*p] you must enter the xkb +character name instead of the character itself. +Run +.Xr xev 1 , +focus the window and press the specific key and in the terminal output read +the symbol name. +In the following example for \[oa]: .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) "å" + XLookupString gives 2 bytes: (c3 a5) "\[oa]" + XmbLookupString gives 2 bytes: (c3 a5) "\[oa]" XFilterEvent returns: False .Ed .Pp -The xkb name is aring. In other words, in .spectrwm.conf add: +The xkb name is aring. +In other words, in +.Pa spectrwm.conf +add: .Bd -literal -offset indent bind[program] = MOD+aring .Ed @@ -733,7 +1029,7 @@ bind[program] = MOD+aring Keyboard mapping files for several keyboard layouts are listed below. These files can be used with the -.Pa keyboard_mapping +.Ic keyboard_mapping setting to load pre-defined key bindings for the specified keyboard layout. .Pp @@ -758,7 +1054,8 @@ 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:VCLSalFrameXXX" -offset indent -compact +.Bl -tag -width "OpenOffice.org N.M:VCLSalFrameXXX" -offset indent \ +-compact .It Firefox\-bin:firefox\-bin TRANSSZ .It Firefox:Dialog @@ -790,53 +1087,116 @@ XTERM_FONTADJ The quirks themselves are described below: .Pp .Bl -tag -width "XTERM_FONTADJXXX" -offset indent -compact +.It ANYWHERE +Allow window to position itself, uncentered. .It FLOAT This window should not be tiled, but allowed to float freely. +.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 WM_CLASS +class/instance value. +Has no effect when +.Ic focus_mode +is set to +.Ar follow . +.It FOCUSPREV +On exit force focus on previously focused application not previous +application in the stack. +.It FULLSCREEN +Remove border to allow window to use full region size. +.It IGNOREPID +Ignore the PID when determining the initial workspace for a new window. +Especially useful for terminal windows that share a process. +.It IGNORESPAWNWS +Ignore the spawn workspace when determining the initial workspace for a +new window. +.It MINIMALBORDER +Remove border when window is unfocused and floating. +.It NOFOCUSCYCLE +Remove from normal focus cycle (focus_prev or focus_next). The window can +still be focused using search_win. +.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 +.Ar follow . +.It OBEYAPPFOCUSREQ +When an application requests focus on the window via a _NET_ACTIVE_WINDOW +client message (source indication of 1), comply with the request. +Note that a source indication of 0 (unspecified) or 2 (pager) are always +obeyed. .It TRANSSZ -Adjusts size on transient windows that are too small using dialog_ratio +Adjusts size on transient windows that are too small using +.Ic dialog_ratio (see .Sx CONFIGURATION FILES ) . -.It ANYWHERE -Allow window to position itself, uncentered. +.It WS Ns Bq Ar n +Force a new window to appear on workspace +.Ar n . .It XTERM_FONTADJ -Adjust xterm fonts when resizing. -.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. +Adjust +.Xr xterm 1 +fonts when resizing. .El .Pp Custom quirks in the configuration file are specified as follows: .Pp -.Dl quirk[:] = [ + ... ] +.Dl quirk Ns Bo Ar class Ns Bo : Ns Ar instance Ns Bo : Ns Ar name Bc Bc Bc = Ar quirk Op + Ar quirk ... .Pp -.Aq class -and -.Aq name -specify the window to which the quirk(s) apply, and -.Aq quirk +.Ar class , +.Ar instance +(optional) and +.Ar name +(optional) are patterns used to determine which window(s) the quirk(s) apply +to and +.Ar quirk is one of the quirks from the list above. +.Pp +Note that patterns are interpreted as POSIX Extended Regular Expressions. +Any ':', '[' or ']' must be escaped with '\\'. +See +.Xr regex 7 +for more information on POSIX Extended Regular Expressions. +.Pp For example: .Bd -literal -offset indent -quirk[MPlayer:xv] = FLOAT + FULLSCREEN + FOCUSPREV -quirk[pcb:pcb] = NONE # remove existing quirk +quirk[MPlayer] = FLOAT + FULLSCREEN + FOCUSPREV # Float all windows having a \ +class of 'MPlayer' +quirk[.*] = FLOAT # Float all windows by default. +quirk[.*:.*:.*] = FLOAT # Same as above. +quirk[Firefox:Navigator] = FLOAT # Float all Firefox browser windows. +quirk[::Console] = FLOAT # Float windows with WM_CLASS not set and a \ +window name of 'Console'. +quirk[\\[0-9\\].*:.*:\\[\\[\\:alnum\\:\\]\\]*] = FLOAT # Float windows with WM_CLASS \ +class beginning with a number, any WM_CLASS instance and a \ +_NET_WM_NAME/WM_NAME either blank or containing alphanumeric characters without spaces. +quirk[pcb:pcb] = NONE # remove existing quirk .Ed .Pp You can obtain -.Aq class +.Ar class , +.Ar instance and -.Aq name +.Ar 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 +$ xprop | grep \-E "^(WM_CLASS|_NET_WM_NAME|WM_NAME)" WM_CLASS(STRING) = "Navigator", "Firefox" +WM_NAME(STRING) = "spectrwm - ConformalOpenSource" +_NET_WM_NAME(UTF8_STRING) = "spectrwm - ConformalOpenSource" +.Ed +.Pp +Note that +.Xr xprop 1 +displays WM_CLASS as: +.Bd -literal -offset indent +WM_CLASS(STRING) = "", "" .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 @@ -887,7 +1247,7 @@ and .Xr grep 1 : .Bd -literal -offset indent $ WINDOWID=`xprop \-root _NET_ACTIVE_WINDOW | grep \-o "0x.*"` -$ xprop \-id $WINDOWID WM_NAME | grep \-o "\\".*\\"" +$ xprop \-id $WINDOWID _NET_WM_NAME | grep \-o "\\".*\\"" .Ed .Pp A window can be focused by sending a _NET_ACTIVE_WINDOW client message @@ -917,12 +1277,18 @@ 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): +to send the message (assuming 0x4a0000b is the id of the window to be +floated or un-floated): .Bd -literal -offset indent $ wmctrl \-i \-r 0x4a0000b \-b toggle,_NET_WM_STATE_ABOVE .Ed .Pp +Windows can also be iconified and un-iconified by substituting +_NET_WM_STATE_HIDDEN for _NET_WM_STATE_ABOVE in the previous example: +.Bd -literal -offset indent +$ wmctrl \-i \-r 0x4a0000b \-b toggle,_NET_WM_STATE_HIDDEN +.Ed +.Pp Floating windows can also be resized and moved by sending a _NET_MOVERESIZE_WINDOW client message to the root window. For example, @@ -958,7 +1324,8 @@ was inspired by xmonad & dwm. .Nm was written by: .Pp -.Bl -tag -width "Ryan Thomas McBride Aq mcbride@countersiege.com " -offset indent -compact +.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