Debian Codegraph @

upstream/debian-unstable/man5/icewm-keys.5

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ICEWM-KEYS 5"
58 .TH ICEWM-KEYS 5 2026-01-18 "icewm\ 4.0.0" "Standards, Environments and Macros"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SS NAME
64 .IX Subsection "NAME"
65 .Vb 1
66 \& icewm\-keys \- icewm keys configuration file
67 .Ve
68 .SS SYNOPSIS
69 .IX Subsection "SYNOPSIS"
70 .Vb 5
71 \& $ICEWM_PRIVCFG/keys
72 \& $XDG_CONFIG_HOME/icewm/keys
73 \& $HOME/.icewm/keys
74 \& /etc/X11/icewm/keys
75 \& /usr/share/icewm/keys
76 .Ve
77 .SS DESCRIPTION
78 .IX Subsection "DESCRIPTION"
79 The \f(CW\*(C`keys\*(C'\fR file defines global keybindings to launch applications.
80 A keybinding has three parts: the word \fBkey\fR, a double-quoted string
81 with an X11 key combination and a program with its arguments.
82 These are separated by one or more spaces. Empty lines are allowed.
83 Comment lines start with a hash.
84 .PP
85 For example, the following defines a hotkey to restart \fBicewm\fR:
86 .PP
87 .Vb 1
88 \& key "Ctrl+Shift+r" icesh restart
89 .Ve
90 .PP
91 See the output of \f(CW\*(C`xmodmap \-pk\*(C'\fR for a list of the many keystroke names
92 you can use in icewm key definitions. Since IceWM version 3.4.0,
93 bindings can not only be defined by their keystroke name, but also by
94 their key label. In addition, the shifted key is now definable as well.
95 For example, the key with + and = can be bound in either of the
96 following four ways, which are identical:
97 .PP
98 .Vb 4
99 \& key "Ctrl+Shift+equal" xterm
100 \& key "Ctrl+Shift+=" xterm
101 \& key "Ctrl+plus" xterm
102 \& key "Ctrl++" xterm
103 .Ve
104 .PP
105 To bind the mouse, use \f(CW\*(C`Pointer_Button1\*(C'\fR for button 1, and so on.
106 This only works when the mouse is over the root window.
107 See below for examples.
108 .PP
109 Sometimes you may want to start an application just once. For this, use
110 the \f(CW\*(C`runonce\*(C'\fR keyword, which accepts an additional resource argument.
111 .PP
112 The command \f(CW\*(C`icesh keys\*(C'\fR instructs icewm to reload this file.
113 .SS FORMAT
114 .IX Subsection "FORMAT"
115 The syntax of the \fIkeys\fR file is as follows:
116 .RS 4
117 .IP "\fBkey\fR \fB""\fR\fIkey_combination\fR\fB""\fR \fIprogram\fR \fIoptions\fR" 4
118 .IX Item "key ""key_combination"" program options"
119 .RE
120 .RS 4
121 .RE
122 .PP
123 Where,
124 .IP \fBkey\fR 4
125 .IX Item "key"
126 The word \fBkey\fR begins the definition of a keybinding.
127 .IP \fIkey_combination\fR 4
128 .IX Item "key_combination"
129 A combination of modifiers and a key, like \f(CW\*(C`Ctrl+Alt+Delete\*(C'\fR.
130 Valid modifiers are Alt, AltGr, Ctrl, Hyper, Meta, Shift, Super.
131 Each modifier must be followed by a single plus-sign.
132 The key is either a keystroke name or a key label.
133 Instead of a key, mouse pointer buttons can be specified by
134 \&\f(CW\*(C`Pointer_Button1\*(C'\fR and up, like \f(CW\*(C`Shift+Pointer_Button3\*(C'\fR.
135 .IP "\fIprogram\fR \fIoptions\fR" 4
136 .IX Item "program options"
137 \&\fIprogram\fR is the name of the executable or its path.
138 It may start with a tilde or an environment variable,
139 which will be expanded.
140 The \fIoptions\fR are passed as arguments to the \fIprogram\fR.
141 .IP \fBrunonce\fR 4
142 .IX Item "runonce"
143 Is an alternative to \fBkey\fR. Its syntax is:
144 .RS 4
145 .RS 4
146 .IP "\fBrunonce\fR \fB""\fR\fIhotkey\fR\fB""\fR \fB""\fR\fIwmclass\fR\fB""\fR \fIprogram\fR \fIoptions\fR" 4
147 .IX Item "runonce ""hotkey"" ""wmclass"" program options"
148 .RE
149 .RS 4
150 .RE
151 .RE
152 .RS 4
153 .Sp
154 Here \fIwmclass\fR is the resource name and/or class. The class must be
155 prefixed by a dot. The program is only run when no other application
156 window with the same \fIwmclass\fR exists. Icewm ignores key repeat events
157 for this hotkey.
158 .RE
159 .IP \fBswitchkey\fR 4
160 .IX Item "switchkey"
161 Is an alternative to \fBkey\fR. In this case the \fIprogram\fR must print on
162 standard output the definition of a dynamic \fBicewm\-menu\fR\|(1).
163 This menu will presented as a popup menu.
164 .SS EXAMPLES
165 .IX Subsection "EXAMPLES"
166 Following is the example \fIkeys\fR file that ships with \fBicewm\fR\|(1):
167 .PP
168 .Vb 10
169 \& # This is an example for IceWM\*(Aqs hotkey definition file.
170 \& #
171 \& # A list of all valid keyboard symbols can be found in
172 \& # /usr/include/X11/keysymdef.h, XF86keysym.h, ...
173 \& # Omit the XK_ prefixs and replace XF86XK_ prefixes by XF86.
174 \& # Valid modifiers are Alt, AltGr, Ctrl, Shift, Meta, Super, Hyper.
175 \& #
176 \& key "Alt+Ctrl+t" xterm
177 \& key "Alt+Ctrl+b" xdg\-open about:blank
178 \& key "Alt+Ctrl+s" xdg\-open https://www.google.com
179 \&
180 \& key "Super+KP_Subtract" amixer sset PCM 5%\-
181 \& key "Super+KP_Add" amixer sset PCM 5%+
182 \&
183 \& # "Multimedia key" bindings for XFree86. Gather the
184 \& # keycodes of your advanced function keys by watching the
185 \& # output of the xev command whilst pressing those keys
186 \& # and map those symbols using xmodmap.
187 \&
188 \& key "XF86AudioLowerVolume" amixer sset PCM 5%\-
189 \& key "XF86AudioRaiseVolume" amixer sset PCM 5%+
190 \& key "XF86AudioMute" amixer sset PCM 0%
191 \& key "XF86HomePage" xdg\-open about:blank
192 \& key "XF86Search" xdg\-open https://www.google.com
193 \& key "XF86Eject" eject
194 \&
195 \& # display and select monitor setup configurations
196 \& switchkey "Super+p" icewm\-menu\-xrandr
197 \&
198 \& # display and select from all terminals
199 \& switchkey "Super+q" icesh \-Z switchmenu
200 .Ve
201 .PP
202 Following shows how to add mouse button bindings on the root window to
203 change the current workspace rolling the mouse wheel on the desktop:
204 .PP
205 .Vb 2
206 \& key "Pointer_Button4" icesh goto prev
207 \& key "Pointer_Button5" icesh goto next
208 .Ve
209 .PP
210 These are key bindings for single window tile operations to replace the
211 \&\fIKeyWinArrange\fR key bindings from the \fIpreferences\fR file:
212 .PP
213 .Vb 9
214 \& key "Ctrl+Alt+KP_Home" icesh \-f sizeto 49% 49% top left
215 \& key "Ctrl+Alt+KP_Up" icesh \-f sizeto 100% 49% top left
216 \& key "Ctrl+Alt+KP_Prior" icesh \-f sizeto 49% 49% top right
217 \& key "Ctrl+Alt+KP_Right" icesh \-f sizeto 49% 100% top right
218 \& key "Ctrl+Alt+KP_Next" icesh \-f sizeto 49% 49% bottom right
219 \& key "Ctrl+Alt+KP_Down" icesh \-f sizeto 100% 49% bottom left
220 \& key "Ctrl+Alt+KP_End" icesh \-f sizeto 49% 49% bottom left
221 \& key "Ctrl+Alt+KP_Left" icesh \-f sizeto 49% 100% top left
222 \& key "Ctrl+Alt+KP_Begin" icesh \-f sizeto 49% 49% center
223 .Ve
224 .SS FILES
225 .IX Subsection "FILES"
226 Locations for the \fIkeys\fR file are as follows:
227 .PP
228 .Vb 5
229 \& $ICEWM_PRIVCFG/keys
230 \& $XDG_CONFIG_HOME/icewm/keys
231 \& $HOME/.icewm/keys
232 \& /etc/X11/icewm/keys
233 \& /usr/share/icewm/keys
234 .Ve
235 .PP
236 The locations are searched in the order listed; the first file found is
237 read and the remainder ignored.
238 .SS "SEE ALSO"
239 .IX Subsection "SEE ALSO"
240 \&\fBicewm\fR\|(1).
241 .SS AUTHOR
242 .IX Subsection "AUTHOR"
243 Brian Bidulock <mailto:[email protected]>.
244 .SS LICENSE
245 .IX Subsection "LICENSE"
246 \&\fBIceWM\fR is licensed under the GNU Library General Public License.
247 See the \fICOPYING\fR file in the distribution.