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
|
<HTML>
<BODY>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->
FvwmButtons - the FVWM buttonbox module
</PRE>
<H2>SYNOPSIS</H2><PRE>
FvwmButtons is spawned by fvwm, so no command line invoca-
tion will work.
</PRE>
<H2>DESCRIPTION</H2><PRE>
The FvwmButtons module provides a window of buttons which
sits on the X terminal's root window. The user can press
the buttons at any time, and trigger invocation of a user-
specified command by the window manager. FvwmButtons only
works when fvwm is used as the window manager.
The buttonbox can be of any configuration or geometry, and
can have monochrome or color icons to represent the
actions which would be invoked.
</PRE>
<H2>INITIALIZATION</H2><PRE>
During initialization, <I>FvwmButtons</I> will search for a con-
figuration file which describes the buttonbox geometry,
color, icons, and actions. The format of this files will
be described later. The configuration file will be the one
which fvwm used during its initialization.
To use FvwmButtons with several different configurations,
you can invoke FvwmButtons with an optional parameter,
which it will use as its name instead (e.g "Module Fvwm-
Buttons SomeButtons"). SomeButtons will then read only
the lines in the configuration file starting with "*Some-
Buttons", and not the lines belonging to FvwmButtons.
You can also specify an optional configuration file to use
instead of the default fvwm configuration file, by giving
a second argument which is a filename. This will override
the setting "*FvwmButtonsFile", see below.
</PRE>
<H2>INVOCATION</H2><PRE>
FvwmButtons can be invoked by inserting the line 'Module
FvwmButtons' in the .fvwmrc file. This should be placed in
the InitFunction if FvwmButtons is to be spawned during
fvwm's initialization, or can be bound to a menu or mouse
button or keystroke to invoke it later. Fvwm will search
directory specified in the ModulePath configuration option
to attempt to locate FvwmButtons.
</PRE>
<H2>CONFIGURATION OPTIONS</H2><PRE>
The following options int the .fvwmrc file are understood
by FvwmButtons:
Specifies the background color for the buttons. A
relief and a shadow color will also be calculated
from this.
*FvwmButtonsColumns <I>columns</I>
Specifies the number of columns of buttons to be
created. If unspecified, the number of columns will
be set to the number of buttons requested, divided
by the number of rows. If both the rows and columns
are specified, but do not specify as many buttons
as are defined, then the users columns specifica-
tion will be ignored.
*FvwmButtonsFile <I>filename</I>
Specifies that the configuration for this button is
found in the file <I>filename</I>, which will have to be
given with full pathname, or is assumed to be in
fvwm's startup directory. The configuration file is
in the same format as fvwm's configuration file,
but each line is read as if prefixed by "*FvwmBut-
tons". Comments are given by starting a line with
"#", line continuation is done by ending a line
with a "\".
*FvwmButtonsFont <I>font</I>
Specifies the font to be used for labeling the but-
tons, or <I>None</I>.
*FvwmButtonsFore <I>color</I>
Specifies the color used for button label text and
monochrome icons.
*FvwmButtonsFrame <I>width</I>
Specifies the width of the relief around each but-
ton. If this is given as a negative number, the
relief will at all times be the inverse of the nor-
mal relief. In effect, you will get a sunken but-
ton, which is raised when activated.
*FvwmButtonsGeometry <I>geometry</I>
Specifies the FvwmButtons window location. The size
should not be specified, as FvwmButtons automati-
cally chooses a size which gracefully accomodates
all its buttons. The geometry is a standard X11
window geometry specification.
*FvwmButtonsPadding <I>width</I> <I>height</I>
The amount of free space between the relief of the
button and its contents is normally 2 pixels to the
sides and 4 pixels above and below, except for
swallowed windows and containers, which are not
padded at all, unless given specific orders. This
<I>height</I> pixels.
*FvwmButtonsRows <I>rows</I>
Specifies the number of rows of buttons to be cre-
ated. If unspecified, 2 rows will be used.
*FvwmButtons(<I>options</I>) [<I>title</I> <I>icon</I> <I>command</I>]
Specifies the contents of a button in the button-
box. The following <I>options</I>, separated by commas or
whitespace, can be given a button:
<I>width</I>x<I>height</I>
The button will be <I>width</I> times the normal button
width and <I>height</I> times the normal button height.
Action [(<I>options</I>)] <I>command</I>
Specifies an fvwm command to be executed when the
button is activated by pressing return or a mouse
button. If <I>command</I> contains whitespace it must be
quoted. The current options are:
Mouse <I>n</I> - this action is only executed for mouse
button <I>n</I>. One actions can be defined for each
mouse button, in addition to the general action.
Back <I>color</I>
Specifies the background color to be used drawing
this box. A relief color and a shadow color will
also be calculated from this.
Container [(<I>options</I>)]
Specifies that this button will contain a miniature
buttonbox, more or less equivalent to swallowing
another FvwmButtons module. The options are the
same as can be given for a single button, but they
affect all the contained buttons. Options available
for this use are <I>Back,</I> <I>Font,</I> <I>Fore,</I> <I>Frame</I> and
<I>Padding</I>. Flags for Title and Swallow options can be
set with <I>Title(flags)</I> and <I>Swallow(flags</I>. You
should also specify either "Columns <I>width</I>" or "Rows
<I>height</I>", or "Rows 2" will be assumed for purpose of
arranging the buttons inside the container. For an
example, see the <I>Sample</I> <I>configuration</I> section.
The container button itself (separate from the con-
tents) can take format options like <I>Frame</I> and
<I>Padding</I>, and commands can be bound to it. This
means you can make a sensitive relief around a con-
tainer, like
*FvwmButtons(2x2, Frame 5, Padding 2 2, Action
Beep,\
tainer a size setting <I>width</I>x<I>height</I>.
End Specifies that no more buttons are defined for the
current container, and further buttons will be put
in the container's parent. This option should be
given on a line by itself, i.e
*FvwmButtons(End)
Font <I>fontname</I>
Specifies that the font <I>fontname</I> is to be used for
labeling this button.
Fore <I>color</I>
Specifies a color of the title and monochrome icons
in this button.
Frame <I>width</I>
The relief of the button will be <I>width</I> pixels wide.
If <I>width</I> is given as a negative number, the relief
will at all times be the inverse of the normal
relief. In effect, you will get a sunken button,
which is raised when activated.
Icon <I>filename</I>
The name of an X11 bitmap file or XPM color icon
file, containing the icon to display on the button.
FvwmButtons will search through the path specified
in the fvwm IconPath or PixmapPath configuration
items to find the icon file.
NoSize
This option specifies that this button will not be
considered at all when making the initial calcula-
tions of buttonsizes. Useful for the odd button
that gets just a couple of pixels to large to keep
in line, and therefor blows up your whole button-
box. "NoSize" is equivalent to "Size 0 0".
Padding <I>width</I> <I>height</I>
The amount of free space between the relief of the
button and its contents is normally 2 pixels to the
sides and 4 pixels above and below, except for
swallowed windows and containers, which are by
default not padded at all. This option sets the
horizontal padding to <I>width</I> and the vertical
padding to <I>height</I>.
Size <I>width</I> <I>height</I>
Specifies that the contents of this button will
require <I>width</I> by <I>height</I> pixels, regardless of what
not get very large without this option specified,
as FvwmButtons does not consider sizes for swallow-
ing buttons. Note that this option gives the mini-
mum space assured; other buttons might require the
buttonbox to use larger sizes.
Swallow [(<I>flags</I>)] <I>hangon</I> <I>command</I>
Causes FvwmButtons to execute <I>command</I>, and when a
window matching the name <I>hangon</I> appears, it is cap-
tured and swallowed into this button. An example:
*FvwmButtons(Swallow XClock 'Exec xclock &')
will take the first window whose name, class or
resource is "XClock" and display it in the button.
Modules can be swallowed by specifying the module
instead of 'Exec whatever', like:
*FvwmButtons(Swallow "FvwmPager" "FvwmPager 0 0")
The flags that can be given to swallow are:
NoClose / Close - Specifies whether the swallowed
program in this button will be unswallowed or
closed when FvwmButtons exit cleanly. "NoClose" can
be combined with "UseOld" to have windows survive
restart of windowmanager. The default setting is
"Close".
NoHints / Hints - Specifies whether hints from the
swallowed program in this button will be ignored or
not, useful in forcing a window to resize itself to
fit its button. The default value is "Hints".
NoKill / Kill - Specifies whether the swallowed
program will be closed by killing it or by sending
a message to it. This can be useful in ending pro-
grams that doesn't accept window manager protocol.
The default value is "NoKill". This has no effect
if "NoClose" is specified.
NoRespawn / Respawn - Specifies whether the swal-
lowed program is to be respawn if it dies. If
"Respawn" is specified, the program will be
respawned using the original <I>command</I>. Use this
option with care, the program might have a very
legitimate reason to die.
NoOld / UseOld - Specifies whether the button will
try to swallow an existing window matching the
<I>hangon</I> name before spawning one itself with <I>com-</I>
<I>mand</I>. The default value is "NoOld". "UseOld" can
to swallow an old window, and not spawn one itself
if failing, let the <I>command</I> be "Nop":
*FvwmButtons(Swallow (UseOld) "Console" Nop)
If you want to be able to start it yourself, com-
bine it with an action:
*FvwmButtons(Swallow (UseOld) "Console" Nop, \
Action `Exec "Console" console &`)
NoTitle / UseTitle - Specifies whether the title of
the button will be taken from the swallowed win-
dow's title or not. If "UseTitle" is given, the
title on the button will change dynamically to
reflect the window name. The default is "NoTitle".
Title [(<I>options</I>)] <I>name</I>
Specifies the title which will be written on the
button. Whitespace can be included in the title by
quoting it. If a title at any time is to long for
its buttons, characters are chopped of one at a
time until it fits. If <I>justify</I> is "Right", the
head is removed, otherwise its tail is removed.
These <I>options</I> can be given to Title:
Center - The title will be centered horizontally.
This is the default.
Left - The title will be justified to the left
side.
Right - The title will be justified to the right
side.
Side - This will cause the title to appear on the
right hand side of any icon or swallowed window,
instead of below it which is the default. If you
use small icons, and combine this with the "Left"
option, you can get a look similar to fvwm's menus.
Legacy fields [<I>title</I> <I>icon</I> <I>command</I>]
These fields are kept for compatibility with previ-
ous versions of FvwmButtons, and their use is dis-
couraged. The <I>title</I> field is similar to the option
Title <I>name</I>. If the title field is "-", no title
will be displayed. The <I>icon</I> field is similar to
the option Icon <I>filename</I>. If the icon field is "-"
no icon will be displayed. The <I>command</I> field is
similar to the option Action <I>command</I> or alterna-
tively Swallow "<I>hangon</I>" <I>command</I>.
Any fvwm command is recognized by FvwmButtons. See
<B>fvwm(1)</B> for more info on this. The Exec command has
a small extension when used in Actions, its syntax
is here:
Exec ["hangon"] command
When FvwmButtons finds such an Exec command, the
button will remain pushed in until a window whose
name or class matches the qouted portion of the
command is encountered. This is intended to provide
visual feedback to the user that the action he has
requested will be performed. If the qouted portion
contains no characters, then the button will pop
out immediately. Note that users can continue
pressing the button, and re-executing the command,
even when it looks "pressed in."
Quoting
Any string which contains whitespace must be
quoted. This include commands. Quoting can be done
with any of the three quotation characters; single
quote:
'This is a "quote"',
double quote:
"It's another `quote'",
and backquote:
`This is a strange quote`.
The backquoting is purposeful if you use a prepro-
cessor like FvwmCpp and want it to get into your
commands, like this:
#define BG gray60
*FvwmButtons(Swallow "xload" `Exec xload -bg BG
&`)
</PRE>
<H2>ARRANGEMENT ALGORITHM</H2><PRE>
FvwmButtons tries to arrange its buttons as best it can,
by using recursively, on each container including the but-
tonbox itself, the following algorithm.
Getting the size right
First it calculates the number of button unit areas
it will need, by adding the width times the height
in buttons of each button. Containers are for the
the number of rows is given, it will calculate how
many columns are needed, and stick to that, unless
<I>columns</I> is larger, in which case you will get some
empty space at the bottom of the buttonbox. If the
number of columns is given, it calculates how many
rows it needs to fit all the buttons. If neither
is given, it assumes you want two rows, and finds
the number of columns from that.
Shuffling buttons
Now it has a large enough area to place the buttons
in, all that is left is to place them right. The
algorithm assumes the buttons are all of unit size,
and places them in a left to right, top to bottom
western fashion. Then it looks at button 1, and
considers: Is this button larger than normal? If
it isn't, the same thing is done for the next but-
tons. When a button is found that is larger than
1x1, space must be provided for it. The algorithm
assumes it is in the right coordinate, its upper
left corner should be unchanged. It then "slides"
away the buttons that occupies the places needed
for this button. The buttons are slid to the right,
wrapping around to the next line. When all the
space has been cleared for this button the algo-
rithm continues with the next button, doing the
same.
Containers
Containers are arranged by the same algorithm, in
fact they are shuffled recursively as the algorithm
finds them.
Clarifying example
An example might be useful here: Suppose you have 6
buttons, all unit sized except number two, which is
2x2. This makes for 5 times 1 plus 1 times 4 equals
9 unit buttons total area. Assume you have
requested 3 columns.
1) +---+---+---+ 2) +---+---+---+ 3) +---+---+---+
| 1 | 2 | 3 | | 1 | 2 | | | 1 | 2 | |
+---+---+---+ +---+---+---+ +---+---+---+
| 4 | 5 | 6 | | 3 | 4 | 5 | | 3 | | 4 |
+---+---+---+ +---+---+---+ +---+---+---+
| | | 6 | | | 5 | 6 | |
+-----------+ +---+-------+ +---+---+---+
4) +---+---+---+ 5) +---+-------+
| 1 | 2 | | | 1 | |
+---+---+---+ +---+ 2 |
| 3 | | | | 3 | |
+---+---+---+ +---+---+---+
The algorithm starts as in figure 1. The first
large button it finds is number 2, and it will try
to free up each of the unit areas it occupies, in a
left to right, top to bottom order. First it sees
that button 3 is in its way, and it shifts all the
buttons, giving figure 2. Now it finds that button
4 is in the way, so button 4 to 6 are shifted,
yielding figure 3. Button 4 is still barring
progress, so it shifts button 4 to 6 once more,
ending up at figure 4. Now all the button units
required by button 2 are freed, and button 2 can be
given its real size.
What size will the buttons be?
When FvwmButtons has read the icons and fonts that
are required by its configuration, it can find out
which size is needed for every non-swallowing but-
ton. The unit button size of a container is set to
be large enough to hold the largest button in it
without squeezing it. Swallowed windows are simple
expected to be comfortable with the buttonsize they
get from this scheme. If a particular configuration
requires more space for a swallowed window, it can
be set in that button's configuration line using
the option "Size <I>width</I> <I>height</I>". This will tell
FvwmButtons to give this button at least <I>width</I> by
<I>height</I> pixels inside the relief and padding.
</PRE>
<H2>SAMPLE CONFIGURATION</H2><PRE>
The following are excepts from a .fvwmrc file which
describe FvwmButtons initialization commands:
##########################################################
# Load any modules which should be started during fvwm
# initialization
ModulePath /usr/lib/X11/fvwm:/usr/bin/X11
# Make sure FvwmButtons is always there.
AddToFunc InitFunction "I" Module FvwmButtons
AddToFunc RestartFunction "I" Module FvwmButtons
# Make it titlebar-less, sticky, and give it an icon
Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky
##########################################################
*FvwmButtonsFore Black
*FvwmButtonsRows 1
*FvwmButtonsFont -*-helvetica-medium-r-*-*-12-*
*FvwmButtonsPadding 2 2
*FvwmButtons(Title Resize,Icon resize.xpm ,Action Resize)
*FvwmButtons(Title Move ,Icon arrows2.xpm,Action Move )
*FvwmButtons(Title Lower ,Icon Down ,Action Lower )
*FvwmButtons(Title Raise ,Icon Up ,Action Raise )
*FvwmButtons(Title Kill ,Icon bomb.xpm ,Action Destroy)
*FvwmButtons(1x1,Container(Rows 3,Frame 1))
*FvwmButtons(Title Dopey ,Action \
`Exec "big_win" xterm -T big_win -geometry 80x50 &`)
*FvwmButtons(Title Snoopy, Font fixed, Action \
`Exec "small_win" xterm -T small_win &`)
*FvwmButtons(Title Smokin')
*FvwmButtons(End)
*FvwmButtons(Title Xcalc, Icon rcalc.xpm,\
Action `Exec "Calculator" xcalc &`)
*FvwmButtons(Title XMag, Icon magnifying_glass2.xpm,\
Action `Exec "xmag" xmag &`)
*FvwmButtons(Title Mail, Icon mail2.xpm,\
Action `Exec "xmh" xmh &`)
*FvwmButtons(4x1, Swallow "FvwmPager" `FvwmPager 0 3`\
Frame 3)
*FvwmButtons(Swallow(UseOld,NoKill) "xload15" `Exec xload\
-title xload15 -nolabel -bg rgb:90/80/90 -update 15 &`)
The last lines are a little tricky - one spawns an Fvwm-
Pager module, and captures it to display in a quadruple
width button. is used, the Pager will be as big as possi-
ble within the button's relief.
The final line is even more magic. Note the combination of
<I>UseOld</I> and <I>NoKill</I>, which will try to swallow an existing
window with the name "xload15" when starting up (if fail-
ing: starting one with the specified command), which is
unswallowed when ending FvwmButtons.
The color specification <I>rgb:90/80/90</I> is actually the most
correct way of specifying independent colors in X, and
should be used instead of the older <I>#908090</I>. If the latter
specification is used in your configuration file, you
should be sure to escape the hash in any of the <I>command</I>s
which will be executed, or fvwm will consider the rest of
the line a comment.
</PRE>
<H2>COPYRIGHTS</H2><PRE>
by Robert Nation
Copyright 1993, Robert Nation. No guarantees or warranties
or anything are provided or implied in any way whatsoever.
Use this program at your own risk. Permission to use this
program for any purpose is given, as long as the copyright
is kept intact.
Further modifications and patching by Jarl Totland, copy-
right 1996. The statement above still applies.
</PRE>
<H2>AUTHOR</H2><PRE>
Robert Nation. Somewhat enhanced by Jarl Totland.
</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
|
