Debian Codegraph @

upstream/opensuse-tumbleweed/man5/icewm-winoptions.5

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "ICEWM-WINOPTIONS 5"
61 .TH ICEWM-WINOPTIONS 5 2025-08-31 "icewm 3.9.0" "Standards, Environments and Macros"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SS NAME
67 .IX Subsection "NAME"
68 .Vb 1
69 \& icewm\-winoptions \- IceWM window options configuration file
70 .Ve
71 .SS SYNOPSIS
72 .IX Subsection "SYNOPSIS"
73 .Vb 5
74 \& $ICEWM_PRIVCFG/winoptions
75 \& $XDG_CONFIG_HOME/icewm/winoptions
76 \& $HOME/.icewm/winoptions
77 \& /etc/icewm/winoptions
78 \& /usr/share/icewm/winoptions
79 .Ve
80 .SS DESCRIPTION
81 .IX Subsection "DESCRIPTION"
82 The IceWM \fIwinoptions\fR file contains settings to control
83 \&\fIapplication specific\fR window appearance and behavior.
84 For instance, they control the window border, placement and size,
85 the window layer, its workspace, its visibility on the task bar
86 and its focus behavior.
87 .PP
88 The winoptions are established when \fBicewm\fR\|(1) starts. However,
89 they can be overridden later using \fBicesh\fR\|(1) or \fBicewmhint\fR\|(1).
90 The command \f(CW\*(C`icesh winoptions\*(C'\fR instructs icewm to reload the
91 \&\fIwinoptions\fR file, while \fIicewmhint\fR tunes a specific application
92 instance when it starts.
93 .SS FORMAT
94 .IX Subsection "FORMAT"
95 Each line in the file must be in one of the following formats:
96 .RS 4
97 .IP "\fINAME\fR\fB.\fR\fICLASS\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
98 .IX Item "NAME.CLASS.OPTION: VALUE"
99 .PD 0
100 .IP "\fICLASS\fR\fB.\fR\fIROLE\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
101 .IX Item "CLASS.ROLE.OPTION: VALUE"
102 .IP "\fINAME\fR\fB.\fR\fIROLE\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
103 .IX Item "NAME.ROLE.OPTION: VALUE"
104 .IP "\fICLASS\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
105 .IX Item "CLASS.OPTION: VALUE"
106 .IP "\fINAME\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
107 .IX Item "NAME.OPTION: VALUE"
108 .IP "\fIROLE\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
109 .IX Item "ROLE.OPTION: VALUE"
110 .IP "\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
111 .IX Item ".OPTION: VALUE"
112 .PD
113 .RE
114 .RS 4
115 .RE
116 .PP
117 Here \fINAME\fR and \fICLASS\fR are from the \fBWM_CLASS\fR property of the
118 window. This can be found in the output of \f(CW\*(C`icesh \-a getClass\*(C'\fR.
119 .PP
120 While \fIROLE\fR refers to the \fBWM_WINDOW_ROLE\fR property of the window,
121 which is the application instance specific name. Only a minority of
122 windows have it. See the output of \f(CW\*(C`icesh \-a list prop WM_WINDOW_ROLE\*(C'\fR.
123 .PP
124 In rare cases, a name, class or role may contain a period. If it does,
125 the period should be escaped by a single backslash.
126 .PP
127 Lastly, the \fIOPTION: VALUE\fR pair refer to the options and values
128 described below. A line with just a dot, followed by an option/value
129 pair, applies to all windows.
130 .SS OPTIONS
131 .IX Subsection "OPTIONS"
132 There are four categories: \fIgeneral\fR, \fIfunction\fR, \fIdecor\fR and
133 \&\fIfeature\fR.
134 .SS "GENERAL OPTIONS"
135 .IX Subsection "GENERAL OPTIONS"
136 These control general characteristics of windows:
137 .IP "\fBicon\fR: \fINAME\fR (default: none)" 4
138 .IX Item "icon: NAME (default: none)"
139 Specifies the icon name for the window. \fINAME\fR is the icon name, like
140 \&\fIutilities\-terminal\fR. It can also be a file, like \fIxterm.png\fR, a full
141 path, or a prefix of a path without sizes or suffix.
142 .IP "\fBworkspace\fR: \fIWORKSPACE\fR (default: current)" 4
143 .IX Item "workspace: WORKSPACE (default: current)"
144 Specifies the default workspace for the window. \fIWORKSPACE\fR is the
145 workspace number counting from zero (0).
146 .IP "\fBlayer\fR: {\fILAYER\fR|\fINUMBER\fR} (default: Normal)" 4
147 .IX Item "layer: {LAYER|NUMBER} (default: Normal)"
148 Specifies the default layer for the window. Layer can be one of the
149 following names or a number from zero to fifteen:
150 .Sp
151 .Vb 9
152 \& Desktop (0) Desktop window.
153 \& Below (2) Below the default layer.
154 \& Normal (4) Default layer for windows.
155 \& OnTop (6) Above the default layer.
156 \& Dock (8) Docked windows at edge of screen.
157 \& AboveDock (10) Windows above the dock.
158 \& Menu (12) The layer for menu\*(Aqs.
159 \& Fullscreen (14) When fullscreen and focused.
160 \& AboveAll (15) Always above anything.
161 .Ve
162 .IP "\fBgeometry\fR \fIgeometry\fR (default: WM_SIZE_HINTS property)" 4
163 .IX Item "geometry geometry (default: WM_SIZE_HINTS property)"
164 The default geometry for the window. This geometry should be specified
165 in a format that can be parsed by \fBXParseGeometry\fR\|(3):
166 .Sp
167 .Vb 1
168 \& [=][<width>{xX}<height>][{+\-}<xoffset>{+\-}<yoffset>]
169 .Ve
170 .Sp
171 The default geometry is taken from the WM_SIZE_HINTS property of the
172 window or else from the initial window geometry. This option overrides
173 the default.
174 .IP "\fBtray\fR: {\fBIgnore\fR|\fBMinimized\fR|\fBExclusive\fR|\fINUMBER\fR} (default: 0)" 4
175 .IX Item "tray: {Ignore|Minimized|Exclusive|NUMBER} (default: 0)"
176 The default tray option for the window. This affects both the tray and
177 the task pane. Tray can be one of the following three strings or a number
178 from zero (0) to two (2):
179 .Sp
180 .Vb 3
181 \& Ignore (0) No icon is added to the tray.
182 \& Minimized (1) Add to tray, no task when minimized.
183 \& Exclusive (2) Add to tray, no task button.
184 .Ve
185 .IP "\fBorder\fR: \fINUMBER\fR (default: 0)" 4
186 .IX Item "order: NUMBER (default: 0)"
187 The sorting order for task buttons, tray icons, quick switch and window
188 list. The default value is zero. Increasing positive values go right,
189 while decreasing negative values go left.
190 .IP "\fBopacity\fR: \fINUMBER\fR (default: 0)" 4
191 .IX Item "opacity: NUMBER (default: 0)"
192 Set the _NET_WM_WINDOW_OPACITY property if \fINUMBER\fR is a value between
193 1 and 100. \fINUMBER\fR is interpreted as percentage of maximum opaqueness.
194 .IP "\fBkeyboard\fR: \fIlayout\fR (default: none)" 4
195 .IX Item "keyboard: layout (default: none)"
196 Specifies the keyboard layout to use for this window.
197 The \fIlayout\fR is the name of a keyboard layout.
198 It can be a space\-separated list of arguments to the
199 \&\fBsetxkbmap\fR program. Please note that \fBsetxkbmap\fR
200 must be installed for this to work. Also define
201 a default keyboard layout in \fIpreferences\fR.
202 .IP "\fBframe\fR: \fIlabel\fR (default: none)" 4
203 .IX Item "frame: label (default: none)"
204 All windows with the same frame label become tabs in a single frame.
205 .SS "FUNCTION OPTIONS"
206 .IX Subsection "FUNCTION OPTIONS"
207 Function options enable/disable (1/0) the ability to take an action on
208 the window. The normal default for all options is enabled (1) unless
209 overridden by the application:
210 .PP
211 .Vb 7
212 \& fClose: {0|1} can be closed. (default: 1)
213 \& fHide: {0|1} can be hidden. (default: 1)
214 \& fMaximize: {0|1} can be maximized. (default: 1)
215 \& fMinimize: {0|1} can be minimized. (default: 1)
216 \& fMove: {0|1} can be moved. (default: 1)
217 \& fResize: {0|1} can be resized. (default: 1)
218 \& fRollup: {0|1} can be shaded. (default: 1)
219 .Ve
220 .SS "DECOR OPTIONS"
221 .IX Subsection "DECOR OPTIONS"
222 Decor options enable/disable (1/0) decorations on the window. The
223 normal default for all options is enabled (1) unless overridden by the
224 application or the theme:
225 .PP
226 .Vb 10
227 \& dBorder: {0|1} has border. (default: 1)
228 \& dClose: {0|1} has close button. (default: 1)
229 \& dDepth: {0|1} has depth button. (default: 1)
230 \& dHide: {0|1} has hide button. (default: 1)
231 \& dMaximize: {0|1} has maximize button. (default: 1)
232 \& dMinimize: {0|1} has minimize button. (default: 1)
233 \& dResize: {0|1} has resize grips. (default: 1)
234 \& dRollup: {0|1} has shade button. (default: 1)
235 \& dSysMenu: {0|1} has window menu. (default: 1)
236 \& dTitleBar: {0|1} has title bar. (default: 1)
237 .Ve
238 .SS "FEATURE OPTIONS"
239 .IX Subsection "FEATURE OPTIONS"
240 Feature options enable/disable (1/0) additional features of the window.
241 The normal default for all options is disabled (0) unless overridden by
242 the application:
243 .PP
244 .Vb 10
245 \& allWorkspaces: {1|0} show it on all workspaces.
246 \& appTakesFocus: {1|0} let the application take focus.
247 \& doNotCover: {1|0} don\*(Aqt place other windows over it.
248 \& doNotFocus: {1|0} do not give it focus.
249 \& doNotManage: {1|0} do not manage at all.
250 \& forcedClose: {1|0} no close confirmation dialog.
251 \& fullKeys: {1|0} don\*(Aqt install icewm key bindings.
252 \& ignoreNoFocusHint: {1|0} focus even when no\-input is set.
253 \& ignorePagerPreview: {1|0} do not show in pager preview.
254 \& ignorePositionHint: {1|0} always let icewm place the window.
255 \& ignoreQuickSwitch: {1|0} not on the quick switch.
256 \& ignoreTaskBar: {1|0} not on the task bar.
257 \& ignoreUrgentHint: {1|0} ignore urgent hints.
258 \& ignoreWinList: {1|0} not on the window list.
259 \& ignoreActivationMessages: {1|0} only user can focus window.
260 \& ignoreOverrideRedirect: {1|0} ignore the override redirect flag.
261 \& noFocusOnAppRaise: {1|0} no automatic focus on raise.
262 \& noFocusOnMap: {1|0} do not focus when mapped.
263 \& noIgnoreTaskBar: {1|0} always show on task bar.
264 \& startClose: {1|0} close the window immediately.
265 \& startFullscreen: {1|0} start full screen.
266 \& startMaximized: {1|0} start maximized.
267 \& startMaximizedHorz: {1|0} start maximized horizontal.
268 \& startMaximizedVert: {1|0} start maximized vertical.
269 \& startMinimized: {1|0} start minimized.
270 .Ve
271 .SS EXAMPLES
272 .IX Subsection "EXAMPLES"
273 This example uses the WM_WINDOW_ROLE property value \f(CW\*(C`pop\-up\*(C'\fR to deny
274 input focus to \fIChrome\fR pop\-ups and asks to close them immediately.
275 .PP
276 .Vb 9
277 \& google\-chrome.pop\-up.doNotFocus: 1
278 \& google\-chrome.pop\-up.forcedClose: 1
279 \& google\-chrome.pop\-up.ignorePagerPreview: 1
280 \& google\-chrome.pop\-up.ignoreUrgentHint: 1
281 \& google\-chrome.pop\-up.layer: Below
282 \& google\-chrome.pop\-up.noFocusOnAppRaise: 1
283 \& google\-chrome.pop\-up.noFocusOnMap: 1
284 \& google\-chrome.pop\-up.startClose: 1
285 \& google\-chrome.pop\-up.startMinimized: 1
286 .Ve
287 .PP
288 IceWM places dockapps in a container automatically, but for those
289 that fail to comply with the protocol it can also be emulated.
290 An emulated dockapp should appear on all workspaces, have
291 no decorations, and always be visible in a fixed location.
292 .PP
293 .Vb 8
294 \& wmtime.wmtime.allWorkspaces: 1
295 \& wmtime.wmtime.ignoreTaskBar: 1
296 \& wmtime.wmtime.ignoreQuickSwitch: 1
297 \& wmtime.wmtime.ignoreWinList: 1
298 \& wmtime.wmtime.layer: Below
299 \& wmtime.wmtime.dTitleBar: 0
300 \& wmtime.wmtime.dBorder: 1
301 \& wmtime.wmtime.geometry: 64x64\-74\-100
302 .Ve
303 .PP
304 Following shows how a shaped output\-only application is shown
305 without titlebar and minimal functionality.
306 .PP
307 .Vb 11
308 \& xeyes.tray: Exclusive
309 \& xeyes.ignoreWinList: 0
310 \& xeyes.ignoreTaskBar: 1
311 \& xeyes.allWorkspaces: 1
312 \& xeyes.dTitleBar: 0
313 \& xeyes.dBorder: 0
314 \& xeyes.dSysMenu: 0
315 \& xeyes.dResize: 0
316 \& xeyes.dClose: 0
317 \& xeyes.dMinimize: 0
318 \& xeyes.dMaximize: 0
319 .Ve
320 .SS FILES
321 .IX Subsection "FILES"
322 Locations for the \fIwinoptions\fR file are as follows:
323 .PP
324 .Vb 5
325 \& $ICEWM_PRIVCFG/winoptions
326 \& $XDG_CONFIG_HOME/icewm/winoptions
327 \& $HOME/.icewm/winoptions
328 \& /etc/icewm/winoptions
329 \& /usr/share/icewm/winoptions
330 .Ve
331 .PP
332 The locations are searched in the order listed; the first file found is
333 read and the remainder ignored.
334 .SS "SEE ALSO"
335 .IX Subsection "SEE ALSO"
336 \&\fBicewm\fR\|(1),
337 \&\fBicesh\fR\|(1),
338 \&\fBicewmhint\fR\|(1),
339 \&\fBsetxkbmap\fR\|(1),
340 \&\fBXParseGeometry\fR\|(3).
341 .SS AUTHOR
342 .IX Subsection "AUTHOR"
343 Brian Bidulock <mailto:[email protected]>.
344 .SS LICENSE
345 .IX Subsection "LICENSE"
346 \&\fBIceWM\fR is licensed under the GNU Library General Public License.
347 See the \fICOPYING\fR file in the distribution.