summaryrefslogtreecommitdiff
path: root/doc/fluxbox-apps.5.in
blob: 9b32ca6e96496ecff449d26fb0f8db5859db9052 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
'\" t
.\"     Title: fluxbox-apps
.\"    Author: Jim Ramsay <i.am@jimramsay.com>
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 28 October 2011
.\"    Manual: Fluxbox Manual
.\"    Source: fluxbox-apps.txt
.\"  Language: English
.\"
.TH "FLUXBOX\-APPS" "5" "28 October 2011" "fluxbox\-apps\&.txt" "Fluxbox Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
fluxbox-apps \- per\-window attribute configuration for fluxbox(1)
.SH "SYNOPSIS"
.sp
~/\&.fluxbox/apps
.SH "SYNTAX"
.sp
Variable parameters are shown in emphasis: \fIargument\fR
.sp
All other characters shown are required verbatim\&. Whitespace is only required to delimit words, but it is fine to add more whitespace\&.
.SH "DESCRIPTION"
.sp
It is possible to force an application to always have the same dimensions, position, and other settings when it is first launched\&. These settings are saved in the \(oqapps\(cq file\&.
.sp
Most simple settings can be saved using the \(lqRemember\&...\(rq submenu of the window menu, which can usually be opened with a right\-click on the titlebar\&. More advanced features require manually editing the \(oqapps\(cq file\&. This may include using \fBGROUP SECTIONS\fR to set up automatic window tab groups\&.
.sp
You do not need to \(lqreload\(rq fluxbox after editing the apps file, the changes should be rescanned when the next window is opened\&.
.sp
The file is made up of two main types of sections, apps and groups, detailed below\&.
.SH "APP SECTIONS"
.sp
\fB[app]\fR sections provide settings for individual application windows\&.
.PP
These sections begin with a line of the format
.RS 4

\fB[app]\fR
\fB(\fR\fIpattern\fR\fB)\fR
\fB{\fR\fIcount\fR\fB}\fR
.RE
.sp
The \fIpattern\fR can be one or more patterns which match windows\&. For more details, see \fBCLIENT PATTERNS\fR\&. If you specify more than one \fIpattern\fR, they must ALL match for the settings to be applied\&.
.sp
The \fB{\fR\fIcount\fR\fB}\fR is optional\&. If specified, then the entry will only match at most that many windows at any time\&. If omitted, the default is to apply the settings to all matching windows\&.
.sp
This opening \fB[apps]\fR line is followed by any number of settings for the application\&. See \fBSETTINGS\fR for more details\&.
.PP
Each of these sections ends with the single line
.RS 4

\fB[end]\fR
.RE
.SH "GROUP SECTIONS"
.sp
The primary purpose of \fB[group]\fR sections is to group windows together\&. All windows in a group will be tabbed together automatically\&.
.PP
These sections begin with a line of the format
.RS 4

\fB[group]\fR
\fB(\fR\fIpattern\fR\fB)\fR
.RE
.sp
Where the \fIpattern\fR item is optional\&. If specified, this pattern must match for the group to take effect\&. It is common to use non\-window\-specific patterns such as \fB(workspace)\fR here\&. See \fBCLIENT PATTERNS\fR for more details\&.
.sp
This is followed by any number of \fB[app]\fR lines\&. These have a similar format to the \fB[app]\fR section detailed above in \fBAPP SECTIONS\fR, but do not contain any settings and do not have an associated \fB[end]\fR line\&.
.PP
Like this
.RS 4

\fB[app]\fR
\fB(\fR\fIpattern\fR\fB)\fR
.RE
.sp
This section may also contain settings that are applied to every window in the group\&. See the \fBSETTINGS\fR section for details\&.
.PP
As with \fB[app]\fR sections, each of these sections ends with the single line
.RS 4

\fB[end]\fR
.RE
.SH "SETTINGS"
.sp
These settings may be stored in the \(oqapps\(cq file\&. A settings line must appear inside either an \fB[app]\fR or \fB[group]\fR section\&.
.PP
The general format is
.RS 4

\fB[\fR\fIsetting\fR\fB]\fR
\fB{\fR\fIvalue\fR\fB}\fR
.RE
.sp
All allowed values are described below, except for \fIbool\fR which can simply have the value \fByes\fR or \fBno\fR, which enables or disables the associated setting, respectively\&.
.PP
\fB[Workspace]\fR {\fInumber\fR}
.RS 4
Forces the application to open on the
\fInumber\fR
workspace specified\&. Workspaces are set by number, beginning with 0\&.
.RE
.PP
\fB[Jump]\fR {\fIbool\fR}
.RS 4
Changes the active workspace to the remembered one when the application is opened\&. This is only useful when used in conjunction with
\fI[Workspace]\fR\&. See
\fBEXAMPLES\fR\&.
.RE
.PP
\fB[Head]\fR {\fInumber\fR}
.RS 4
Forces the application to open on the
\fInumber\fR
head specified (Xinerama only)\&.
.RE
.PP
\fB[Layer]\fR {\fInumber\fR}
.RS 4
Specify the layer to open the window on (by number)\&. Each layer has a number\&. The named ones are: 2\-AboveDock, 4\-Dock, 6\-Top, 8\-Normal, 10\-Bottom, 12\-Desktop\&.
.RE
.PP
\fB[Dimensions]\fR {\fIwidth[%]\fR \fIheight[%]\fR}
.RS 4
Opens the application with the specified
\fIwidth\fR
and
\fIheight\fR, in pixels\&. If the value is given in percent, then the window size will be based on the current screen\(cqs size\&.
.RE
.PP
\fB[Position]\fR (\fIanchor\fR) {\fIX[%]\fR \fIY[%]\fR}
.RS 4
Position the application at a particular spot\&. By default the upper\-left corner is placed at screen coordinates (\fIX\fR,\fIY\fR)\&. If you specify an
\fIanchor\fR, say BottomRight, then the lower\-right corner of the window is positioned (\fIX\fR,\fIY\fR) pixels from the lower\-right corner of the screen\&. If the value is given in percent, then the coordinates will be based on the current screen\(cqs size\&.
.PP
\fIanchor\fR may be set to one of:
.RS 4

\fBTopLeft Left BottomLeft Top Center Bottom TopRight Right BottomRight\fR
.RE
.RE
.PP
\fB[Deco]\fR {\fIvalue\fR}
.RS 4
.PP
Specify the decoration state\&. There are several predefined \fIvalue\fR sets:
.RS 4
.PP
\fBNORMAL\fR
.RS 4
Standard decorations
.RE
.PP
\fBNONE\fR
.RS 4
No decorations
.RE
.PP
\fBBORDER\fR
.RS 4
Like NONE except keep the X window border
.RE
.PP
\fBTAB\fR
.RS 4
Like BORDER except keep external tabs (if enabled)
.RE
.PP
\fBTINY\fR
.RS 4
Titlebar with only an iconify button
.RE
.PP
\fBTOOL\fR
.RS 4
Titlebar only
.RE
.sp
The
\fIvalue\fR
may also be a bitmask for finer\-grained control\&. The bits are, from (1<<0) to (1<<10): Titlebar, Handle/Grips, Border, Iconify Button, Maximize Button, Close Button, Menu Button, Sticky Button, Shade Button, External Tabs, Focus Enabled\&.
.RE
.RE
.PP
\fB[Shaded]\fR {\fIbool\fR}
.RS 4
Whether the window is Shaded (rolled\-up) or not\&.
.RE
.PP
\fB[Tab]\fR {\fIbool\fR}
.RS 4
Whether the window has tabs enabled\&.
.RE
.PP
\fB[FocusNewWindow]\fR {\fIbool\fR}
.RS 4
If enabled, a new window will grab X focus as soon as it is opened\&. If disabled, a new window will not grab X focus as soon as it is opened\&.
.RE
.PP
\fB[FocusHidden]\fR {\fIbool\fR}
.RS 4
If enabled, the window will not appear in
\fINextWindow\fR/\fIPrevWindow\fR
lists\&.
.RE
.PP
\fB[IconHidden]\fR {\fIbool\fR}
.RS 4
If enabled, the window will not appear in the icon area of the toolbar\&.
.RE
.PP
\fB[Hidden]\fR {\fIbool\fR}
.RS 4
A shortcut for setting both
\fBFocusHidden\fR
and
\fBIconHidden\fR
at the same time\&.
.RE
.PP
\fB[Sticky]\fR {\fIbool\fR}
.RS 4
Specify if an application should be sticky (shown on all workspaces) or not\&.
.RE
.PP
\fB[Minimized]\fR {\fIbool\fR}
.RS 4
Application should start minimized
.RE
.PP
\fB[Maximized]\fR {\fIvalue\fR}
.RS 4
.PP
Application should start maximized\&. \fIvalue\fR may be:
.RS 4
.PP
\fByes\fR
.RS 4
Fully maximized
.RE
.PP
\fBhorz\fR
.RS 4
Horizontally maximized
.RE
.PP
\fBvert\fR
.RS 4
Vertically maximized
.RE
.PP
\fBno\fR
.RS 4
Not maximized
.RE
.RE
.RE
.PP
\fB[Fullscreen]\fR {\fIbool\fR}
.RS 4
Application should start in fullscreen mode (fully maximized without any decorations)\&.
.RE
.PP
\fB[Close]\fR {\fIbool\fR}
.RS 4
Save settings on close\&. By default, application settings are not updated when a window is closed\&.
.RE
.PP
\fB[Alpha]\fR {\fIvalue\fR [\fIvalue\fR]}
.RS 4
Set the alpha value for this window\&. If two values are given, they correspond to the focused and unfocused transparency, respectively\&. One number only will be used for both values\&.
\fIvalue\fR
is an integer between 0 and 255\&.
.RE
.SH "CLIENT PATTERNS"
.PP
A \fIpattern\fR looks like this
.RS 4

\fB(\fR[\fIpropertyname\fR[!]=]\fIregexp\fR\fB)\fR
\&...
.RE
.sp
Match definitions are enclosed in parentheses \fB(\fR\&...\fB)\fR, and if no \fIpropertyname\fR is given then \fBName\fR is assumed\&. The \fIregexp\fR can contain any regular expression, or the special value \fB[current]\fR, which matches the corresponding value of the currently focused window\&. See \fIregex(7)\fR for more information on acceptable regular expressions\&.
.sp
\fIpropertyname\fR is not case sensitive, whereas the \fIregexp\fR is\&.
.sp
If you specify multiple \fB(\fR\fB\fIpattern\fR\fR) arguments, this implies an AND condition \- All specified patterns must match\&.
.sp
You can use \fB=\fR to test for equality or \fB!=\fR to test for inequality\&.
.PP
The following values are accepted for \fIpropertyname\fR
.RS 4
.PP
\fBName\fR
.RS 4
A string, corresponding to the CLASSNAME property (The first field of WM_CLASS from the output of the
\fBxprop(1)\fR
utility)\&.
.RE
.PP
\fBClass\fR
.RS 4
A string, corresponding to the CLASSCLASS property (The second field of WM_CLASS from the output of the
\fBxprop(1)\fR
utility)\&.
.RE
.PP
\fBTitle\fR
.RS 4
A string, corresponding to the window title (WM_NAME from
\fBxprop(1)\fR)\&.
.RE
.PP
\fBRole\fR
.RS 4
A string, corresponding to the ROLE property (WM_WINDOW_ROLE from
\fBxprop(1)\fR)\&.
.RE
.PP
\fBTransient\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is transient (typically, a popup dialog) or not\&.
.RE
.PP
\fBMaximized\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is maximized or not\&.
.RE
.PP
\fBMaximizedHorizontal\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is maximized horizontally or not\&.
.RE
.PP
\fBMaximizedVertical\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is maximized vertically or not\&.
.RE
.PP
\fBMinimized\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is minimized (iconified) or not\&.
.RE
.PP
\fBFullscreen\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is fullscreen or not\&.
.RE
.PP
\fBShaded\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is shaded or not\&.
.RE
.PP
\fBStuck\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is sticky (on all workspaces) or not\&.
.RE
.PP
\fBFocusHidden\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window has asked to be left off the focus list (or, the alt\-tab list), or not\&.
.RE
.PP
\fBIconHidden\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window has asked to be left off the icon list (or, the taskbar), or not\&.
.RE
.PP
\fBUrgent\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window has the urgent hint set\&.
.RE
.PP
\fBWorkspace\fR
.RS 4
A number corresponding to the workspace number to which the window is attached\&. The first workspace here is
\fB0\fR\&. You may also use
\fB[current]\fR
to match the currently visible workspace\&.
.RE
.PP
\fBWorkspaceName\fR
.RS 4
A string corresponding to the name of the workspace to which the window is attached\&.
.RE
.PP
\fBHead\fR
.RS 4
The number of the display head to which the window is attached\&. You may match this against the special value
\fB[mouse]\fR
which refers to the head where the mouse pointer currently resides\&.
.RE
.PP
\fBLayer\fR
.RS 4
The string name of the window\(cqs layer, which is one of
\fBAboveDock\fR,
\fBDock\fR,
\fBTop\fR,
\fBNormal\fR,
\fBBottom\fR,
\fBDesktop\fR
.RE
.PP
\fBScreen\fR
.RS 4
The number of the currently used
\fIscreen\fR\&. If the setup of the running xserver involves independent screens (\fInot Xinerama\fR), the $DISPLAY environment contains something like
\fI:0\&.1\fR
or
\fI:1\&.0\fR\&. The part after the dot (\fI\&.\fR) is the number of the screen\&.
.RE
.PP
\fB@XPROP\fR
.RS 4
A string, corresponding to any xproperty (Use either the
\fBxprop(1)\fR
utility or the
\fISetXProp\fR
command to set a xproperty to a window)
.RE
.RE
.PP
\fBMatches any windows with the CLASSNAME of "xterm"\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
(xterm)
.fi
.if n \{\
.RE
.\}
.PP
\fBMatches any windows with the same CLASSNAME as the currently focused window\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
(Name=[current])
.fi
.if n \{\
.RE
.\}
.PP
\fBMatches any windows on the same head as the mouse but on a different layer than the currently focused window\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
(Head=[mouse]) (Layer!=[current])
.fi
.if n \{\
.RE
.\}
.PP
\fBMatches any windows having a xproperty named FOO with "bar" in it\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
(@FOO=\&.*bar\&.*)
.fi
.if n \{\
.RE
.\}
.sp
.SH "FILES"
.PP
\fB~/\&.fluxbox/apps\fR
.RS 4
This is the default location for the application settings\&.
.RE
.SH "RESOURCES"
.PP
\fBsession\&.appsFile:\fR \fIlocation\fR
.RS 4
This may be set to override the location of the application settings\&.
.RE
.SH "EXAMPLES"
.sp
Here are some interesting and/or useful examples you can do with your apps file\&.
.sp
.if n \{\
.RS 4
.\}
.nf
# Put the first two windows which end with \*(Aqterm\*(Aq on workspace 1
[app] (name=\&.*[tT]erm) {2}
  [Workspace]   {1}
[end]

# Center kate with a specific size, and update these values when the window is
# closed\&.
[app] (name=kate)
  [Dimensions]  {1022 747}
  [Position]    (CENTER) {0 0}
  [Close]       {yes}
[end]

# When starting konqueror, jump to workspace 1 first and start it there\&.
[app] (name=konqueror)
  [Workspace]   {1}
  [Jump]        {yes}
[end]

# start all aterm without decorations
[app] (name=aterm)
  [Deco]        {NONE}
[end]

# a group with the gimp dock and toolbox
# appears on layer 4 (bottom)
[group]
  [app] (name=gimp) (role=gimp\-dock)
  [app] (name=gimp) (role=gimp\-toolbox)
  [Layer]       {4}
[end]
.fi
.if n \{\
.RE
.\}
.SH "AUTHORS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Jim Ramsay <i\&.am at jimramsay com> (>fluxbox\-1\&.0\&.0)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Curt Micol <asenchi at asenchi com> (>fluxbox\-0\&.9\&.11)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Tobias Klausmann <klausman at users sourceforge net> (\(lafluxbox\-0\&.9\&.11)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Grubert <grubert at users sourceforge net> (fluxbox)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Matthew Hawkins <matt at mh dropbear id au> (blackbox)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Wilbert Berendsen <wbsoft at xs4all nl> (blackbox)
.RE
.SH "SEE ALSO"
.sp
fluxbox(1) xprop(1) regex(7)
.SH "AUTHOR"
.PP
\fBJim Ramsay\fR <\&i\&.am@jimramsay\&.com\&>
.RS 4
Author.
.RE