1FvwmButtons(1) Fvwm Modules FvwmButtons(1)
2
6 FvwmButtons - the fvwm buttonbox module
7
9 Module FvwmButtons [-g geometry] [-transient | -transientpanel] [name[configfile]]
10 FvwmButtons can only be invoked by fvwm. Command line invocation of
12 the FvwmButtons module will not work.
13
16 The FvwmButtons module provides a window of buttons which sits on the X
17 terminal's root window. The user can press the buttons at any time, and
18 trigger invocation of a user-specified command by the window manager.
19 FvwmButtons only works when fvwm is used as the window manager.
20 The buttonbox can be of any configuration or geometry, and can have
22 monochrome or color icons to represent the actions which would be in‐
23 voked. Even other applications can be 'swallowed' by the button bar.
24 Panels that are opened on a button press are available too. See CREAT‐
26 ING PANELS section for details.
27
30 The -g option specifies the geometry of the main window. The command
31 line option takes precedence over any other geometry settings in the
32 configuration file.
33 The -transient option tells FvwmButtons to terminate itself after the
35 first key or button press has been received (presses to open a sub
36 panel do not count) or a sub panel has been closed or respawned. This
37 is especially useful for sub panels where you want to select a single
38 button and have it closed automatically. It could be used to create
39 two-dimensional graphical menus. Since -transient is an option, not a
40 configuration setting you can use the same configuration for transient
41 and non transient button bars.
42 The -transientpanel option does roughly the same as the -transient op‐
44 tion, but instead of closing the whole button bar, the window is merely
45 hidden. This is very useful if the button bar is started as a subpanel
46 of another button bar because it avoids that it must be started again
47 when something is selected.
48
51 FvwmButtons is spawned by fvwm, so command line invocation will not
52 work.
53 FvwmButtons can be invoked by inserting the line 'Module FvwmButtons
55 OptionalName' in the .fvwm2rc file. This should be placed in the Start‐
56 Function if FvwmButtons is to be spawned during fvwm's initialization.
57 This can be bound to a menu or mouse button or keystroke to invoke it
58 later.
59 When invoked with the OptionalName argument, the OptionalName is used
61 to find configuration commands. For example:
62 AddToFunc StartFunction Module FvwmButtons MyButtonBox
64 FvwmButtons will then use only the lines starting with "*MyButtonBox",
66 instead of the default "*FvwmButtons".
67
70 The following commands are understood by FvwmButtons:
71 *FvwmButtons: Back color
74 Specifies the background color for the buttons. The relief and
75 shadow color are calculated from the background color.
76 *FvwmButtons: BoxSize algorithm
79 This option specifies how serious FvwmButtons takes the Rows and
80 Columns options (see below). It can be one of dumb, fixed or
81 smart.
82 If fixed is used and both Rows and Columns are specified and
84 non-zero, FvwmButtons uses exactly the number of rows and col‐
85 umns specified. If the box is too small to accommodate all but‐
86 tons the module will fail.
87 If smart is used FvwmButtons enlarges the box so all buttons
89 have a chance to fit. The number of columns is increased to at
90 least the width of the widest button and new rows are added un‐
91 til all buttons are placed. For the best tolerance of configura‐
92 tion errors use the smart option.
93 dumb is neither fixed nor smart. This is the default.
95 *FvwmButtons: Colorset colorset
98 Tells the module to use colorset colorset for the window back‐
99 ground. Refer to the fvwm man page for details about colorsets.
100 *FvwmButtons: ActiveColorset colorset
103 Tells the module to use colorset colorset for the background
104 color/image and/or title color of a button when the mouse is
105 hovering above a button.
106 *FvwmButtons: PressColorset colorset
109 Tells the module to use colorset colorset for the background
110 color/image and/or title color of a button when it is pressed.
111 *FvwmButtons: Columns columns
114 Specifies the number of columns of buttons to be created. If un‐
115 specified, the number of columns is set to the number of buttons
116 requested, divided by the number of rows. If both the rows and
117 columns are specified, but the number of buttons is more than
118 the rows and columns allow for, the columns specification is ig‐
119 nored unless the BoxSize option is fixed.
120 *FvwmButtons: File filename
123 Specifies that the configuration for this button is found in the
124 file filename. Filename can be a full pathname, or is assumed to
125 be in fvwm's startup directory. The configuration file is in the
126 same format as fvwm's configuration file, but each line is read
127 as if prefixed by "*FvwmButtons". Comments are given by starting
128 a line with "#". Line continuation is done by ending a line with
129 a "\".
130 *FvwmButtons: Font font
133 Specifies the font to be used for labeling the buttons, or None.
134 *FvwmButtons: Fore color
137 Specifies the color used for button label text and monochrome
138 icons.
139 *FvwmButtons: Frame width
142 Specifies the width of the relief around each button. If this is
143 a negative number, the relief is inverted. This makes the button
144 sunken normally and raised when activated.
145 *FvwmButtons: Geometry geometry
148 Specifies the FvwmButtons window location and size. The geome‐
149 try is a standard X11 window geometry specification.
150 *FvwmButtons: ButtonGeometry geometry
153 This option works like the Geometry option except that the size
154 is the size of a single button. The size of the whole FvwmBut‐
155 tons window is calculated by multiplying the button dimension by
156 the number of rows and columns.
157 *FvwmButtons: Padding width height
160 This option specifies the default horizontal padding to be width
161 pixels, and the vertical padding to be height pixels. The amount
162 of free space between the relief of the button and its contents
163 is normally 2 pixels on the sides and 4 pixels above and below,
164 except for swallowed windows and containers, which are not
165 padded at all, unless this option is used.
166 *FvwmButtons: Pixmap pixmapfile
169 Specifies a background pixmap to use. Specify "none" (without
170 the double quotes) for a transparent background.
171 *FvwmButtons: Rows rows
174 Specifies the number of rows of buttons to be created. The de‐
175 fault is 2 rows.
176 *FvwmButtons: (options) [title icon command]
179 Specifies the contents of a button in the buttonbox. The follow‐
180 ing options, separated by commas or whitespace, can be given a
181 button:
182 geometry
184 Specifies the size and position of the button within the
185 FvwmButtons window or container. The geometry is a stan‐
186 dard X11 window geometry specification. The button is
187 width times the normal button width and height times the
188 normal button height. If values for x and y are given,
189 the button is placed x (y) button units from the left
190 (top) of the container if x (y) is positive and x (y)
191 units from the right (bottom) if x (y) is negative. But‐
192 tons with position arguments (x and y) are placed before
193 those without them. If two or more buttons are forced to
194 overlap by this, FvwmButtons exits with an error message.
195 Action [(options)] command
198 Specifies an fvwm command to be executed when the button
199 is activated by pressing return or a mouse button. The
200 command needs to be quoted if it contains a comma or a
201 closing parenthesis.
202 The current options of the Action are: Mouse n - this ac‐
204 tion is only executed for mouse button n. One action can
205 be defined for each mouse button, in addition to the gen‐
206 eral action.
207 In the command part, you can use a number of predefined
209 variables: $left, $right, $top and $bottom are substi‐
210 tuted by the left, right, top and bottom coordinates of
211 the button pressed. $-left, $-right, $-top and $-bottom
212 are substituted likewise, but the coordinates are calcu‐
213 lated from the bottom or the right edge of the screen in‐
214 stead (for a button that is 5 pixels away from the right
215 screen border, $-right will be 5). $width and $height are
216 replaced by the width or height of the button. The vari‐
217 ables $fg and $bg are replaced with the name of the fore‐
218 ground or background color set with the Back or Fore op‐
219 tion (see below). All this is done regardless of any
220 quoting characters. To get a literal '$' use the string
221 '$$'.
222 Example:
224 *FvwmButtons: (Title xload, Action (Mouse 1) \
227 `Exec exec xload -fg $fg -bg $bg -geometry -3000-3000`)
228 Note: With fvwm versions prior to 2.5.0, actions could
231 not be assigned to a button that swallowed an application
232 window (see Swallow option). Such actions worked only
233 when the border around the button was clicked. This is
234 now possible, but to get back the old behavior, the Ac‐
235 tionIgnoresClientWindow can be used on the button:
236 *FvwmButtons: (Action beep, ActionIgnoresClientWindow, \
239 Swallow xeyes "Exec exec xeyes")
240 In this example, the action is only executed when you
243 click on the border of the button or the transparent part
244 of the xeyes window, but not on the xeyes window itself.
245 ActionIgnoresClientWindow
248 See the note in the description of Action above.
249 ActionOnPress
252 Usually the action is executed on the button release ex‐
253 cept for the Popup action. This option changes this be‐
254 havior, the action is executed on the button press. This
255 may be good, for example, with Menu or SendToModule that
256 generates popups, or when Frame is 0 and the button would
257 look unresponsive otherwise.
258 Back color
261 Specifies the background color to be used drawing this
262 box. A relief color and a shadow color are calculated
263 from this.
264 Center The contents of the button is centered on the button.
267 This is the default but may be changed by Left or Right.
268 Top The contents of the button is vertically aligned at the
271 top of the button. The default is to vertically center
272 it.
273 Colorset colorset
276 The given colorset can be applied to a container, a swal‐
277 lowed application and a simple button. To apply it to a
278 button or container, simply put the option in a line with
279 a button or container description. Drawing backgrounds
280 for individual buttons and containers with colorsets re‐
281 quires a lot of communication with the X server. So if
282 you are not content with the drawing speed of dozens of
283 buttons with colorset backgrounds, do not use colorsets
284 here. Setting colorsets as the background of swallowed
285 applications does not have this restriction but depends
286 entirely on the swallowed application. It may work as
287 you wish, but since it involves fiddling with other ap‐
288 plications' windows there is no guarantee for anything.
289 I have tested three applications: xosview works nicely
290 with a colorset background, xload works only with a VGra‐
291 dient or solid background and an analog xclock leaves a
292 trail painted in the background color after its hands.
293 If the swallowed window is an fvwm module (see the
295 (No)FvwmModule option to Swallow), then the colorset is
296 not applied to the swallowed module. You should use the
297 colorset in the module configuration. If the swallowed
298 module has a transparent colorset background, then the
299 FvwmButtons background (and not the button colorset) is
300 seen by transparency of the background of the swallowed
301 module. Refer to the fvwm man page for details about col‐
302 orsets.
303 ActiveColorset colorset
306 Use colorset colorset for the background color/image
307 and/or title color of the button when the mouse is hover‐
308 ing above it.
309 PressColorset colorset
312 Use colorset colorset for the background color/image
313 and/or title color of the button when it is pressed.
314 Container [(options)]
317 Specifies that this button will contain a miniature but‐
318 tonbox, equivalent to swallowing another FvwmButtons mod‐
319 ule. The options are the same as can be given for a sin‐
320 gle button, but they affect all the contained buttons.
321 Options available for this use are Back, Font, Fore,
322 Frame and Padding. Flags for Title and Swallow options
323 can be set with Title(flags) and Swallow(flags). You
324 should also specify either "Columns width" or "Rows
325 height", or "Rows 2" will be assumed. For an example, see
326 the Sample configuration section.
327 The container button itself (separate from the contents)
329 can take format options like Frame and Padding, and com‐
330 mands can be bound to it. This means you can make a sen‐
331 sitive relief around a container, like
332 *FvwmButtons: (2x2, Frame 5, Padding 2 2, Action Beep,\
334 Container(Frame 1))
335 Typically you will want to at least give the container a
337 size setting widthxheight.
338 End Specifies that no more buttons are defined for the cur‐
341 rent container, and further buttons will be put in the
342 container's parent. This option should be given on a line
343 by itself, i.e
344 *FvwmButtons: (End)
346 Font fontname
350 Specifies that the font fontname is to be used for label‐
351 ing this button.
352 Fore color
355 Specifies the foregound color of the title and monochrome
356 icons in this button.
357 Frame width
360 The relief of the button will be width pixels wide. If
361 width is given as a negative number, the relief is in‐
362 verted. This makes the button sunken normally and raised
363 when activated.
364 Icon filename
367 The name of an image file, containing the icon to display
368 on the button. FvwmButtons searches through the path
369 specified in the fvwm ImagePath configuration item to
370 find the icon file.
371 ActiveIcon filename
374 The name of an image file, containing an alternative icon
375 to display on the button when the mouse is hovering above
376 the button. If no ActiveIcon is specified, the image
377 specified by Icon is displayed (if there is one).
378 PressIcon filename
381 The name of an image file, containing an alternative icon
382 to display on the button when the button is pressed. If
383 no PressIcon is specified, the image specified by Icon is
384 displayed (if there is one).
385 Id id The id to be used to identify this button. The first
388 character of the id should be alphabetic. See also the
389 "DYNAMICAL ACTIONS" section.
390 Left The contents of the button are aligned to the left. The
393 default is to center the contents on the button.
394 NoSize This option specifies that this button will not be con‐
397 sidered at all when making the initial calculations of
398 button sizes. Useful for the odd button that gets just a
399 couple of pixels too large to keep in line, and therefore
400 blows up your whole buttonbox. "NoSize" is equivalent to
401 "Size 0 0".
402 Padding width height
405 The amount of free space between the relief of the button
406 and its contents is normally 2 pixels to the sides and 4
407 pixels above and below, except for swallowed windows and
408 containers, which are by default not padded at all. This
409 option sets the horizontal padding to width and the ver‐
410 tical padding to height.
411 Panel [ (options) ] hangon command
414 Panels can be swallowed exactly like windows are swal‐
415 lowed by buttons with the Swallow command below, but they
416 are not displayed within the button. Instead they are
417 hidden until the user presses the panel's button. Then
418 the panel (the window of the swallowed application) opens
419 with a sliding animation. The options can be any of the
420 flags described for the Swallow command. In addition a
421 direction 'left', 'right', 'up' or 'down' can be used to
422 specify the sliding direction.
423 The steps animation-steps option defines the number of
425 animation steps.
426 The delay ms option sets the delay between the steps of
428 the animation in milliseconds. Use zero for no delay.
429 The maximum delay is 10 seconds (10000). It doesn't make
430 any sense to use the delay option unless you also use the
431 smooth option.
432 The smooth option causes the panel to redraw between
434 the steps of the animation. The sliding animation may be
435 smoother this way, it depends on the application, and
436 display speed. The application may appear to grow in‐
437 stead of sliding out. The animation may be slower.
438 The Hints option causes FvwmButtons to use the applica‐
440 tions size hints to calculate the size of the animation
441 steps. Hints is the default. If the number of steps is
442 not what you want, try using NoHints.
443 The noborder option tells FvwmButtons to ignore the bor‐
445 ders of the window when calculating positions for the an‐
446 imation (equivalent to set noplr and noptb in the posi‐
447 tion option).
448 With the indicator option set, FvwmButtons will draw a
450 small triangle in the button that will open a panel. The
451 triangle points in the direction where the panel will pop
452 up. The indicator keyword may be followed by a positive
453 integer that specifies the maximum width and height of
454 the indicator. Without this size FvwmButtons will make
455 the indicator fit the button. You will probably want to
456 use the Padding option to leave a few pixels between the
457 indicator and the frame of the button.
458 The position option allows one to place the panel. The
460 syntax is:
461 position [context-window] [pos] [x y] [border-opts]
463 The argument context-window can be one of: Button, Module
465 or Root. The context-window is the window from which
466 panel percentage offsets are calculated. Button specifies
467 the panel's button, Module specifies FvwmButtons itself,
468 and Root specifies a virtual screen. The context-window
469 together with the sliding direction define a line segment
470 which is one of the borders of the context-window: the
471 top/bottom/left/right border for sliding
472 up/down/left/right.
473 The pos argument can be one of: center, left or right
475 (for sliding up or a down) or top or bottom (for sliding
476 left or right). It defines the vertical (sliding up and
477 down) or the horizontal (sliding left and right) position
478 of the Panel on the line segment. For example, for a
479 sliding up if you use a left pos, then the left borders
480 of the panel and of the context-window will be aligned.
481 The offset values x and y specify how far the panel is
483 moved from it's default position. By default, the numeric
484 value given is interpreted as a percentage of the context
485 window's width (height). A trailing "p" changes the in‐
486 terpretation to mean "pixels". All offset calculations
487 are relative to the buttons location, even when using a
488 root context.
489 The border-opts are: mlr, mtb, noplr and noptb. They de‐
491 fine which border widths are taken in account. By de‐
492 fault, the borders of FvwmButtons are not taken in ac‐
493 count. mlr reverses this default for the left and the
494 right border and mtb reverses this default for the top
495 and the bottom border. Conversely, by default the borders
496 of the Panel are taken in account. noplr reverses this
497 default for the left and the right border and noptb re‐
498 verses this default for the top and the bottom border.
499 The defaults are sliding up with a delay of five mil‐
501 liseconds and twelve animation steps. To post the panel
502 without any animation, set the number of steps to zero.
503 The default position is 'Button center'.
504 Please refer to the CREATING PANELS section for further
506 information on panels.
507 Example:
509 # To include the panel in a button
511 *FvwmButtons: (Panel(down, delay 0, steps 16) \
512 SubPanel "Module FvwmButtons SubPanel")
513 # To define the panel as an instance of
515 # FvwmButtons with a different name:
516 *SubPanel: (Icon my_lock.xpm, Action Exec xlock)
517 *SubPanel: (Icon my_move.xpm, Action Move)
518 ...
519 Right The contents of the button are aligned to the right. The
523 default is to center the contents on the button.
524 Size width height
527 Specifies that the contents of this button require width
528 by height pixels, regardless of what size FvwmButtons
529 calculates from the icon and the title. A button bar with
530 only swallowed windows will not get very large without
531 this option specified, as FvwmButtons does not consider
532 sizes for swallowing buttons. Note that this option gives
533 the minimum space assured; other buttons might require
534 the buttonbox to use larger sizes.
535 Swallow [(flags)] hangon command
538 Causes FvwmButtons to execute command, and when a window
539 with a name, class or resource matching hangon appears,
540 it is captured and swallowed into this button. The
541 hangon string may contain wildcard characters ('*') that
542 match any substring. Swallow replaces the variables $fg
543 and $bg as described above for the Action option (but if
544 you use the UseOld and NoClose options the application is
545 not be restarted when FvwmButtons is restarted and thus
546 does not get the new colors - if you changed them). An
547 example:
548 *FvwmButtons: (Swallow XClock 'Exec xclock -geometry -3000-3000 &')
550 takes the first window whose name, class, or resource is
552 "XClock" and displays it in the button. If no matching
553 window is found, the "Exec" command creates one. The ar‐
554 gument "-geometry -3000-3000" is used so that the window
555 is first drawn out of sight before its swallowed into
556 FvwmButtons.
557 Modules can be swallowed by specifying the module instead
559 of 'Exec whatever', like:
560 *FvwmButtons: (Swallow "FvwmPager" "FvwmPager 0 0")
562 The flags that can be given to swallow are:
564 NoClose / Close - Specifies whether the swallowed program
566 in this button will be un-swallowed or closed when Fvwm‐
567 Buttons exits cleanly. "NoClose" can be combined with
568 "UseOld" to have windows survive a restart of the window
569 manager. The default setting is "Close".
570 NoHints / Hints - Specifies whether hints from the swal‐
572 lowed program in this button will be ignored or not, use‐
573 ful in forcing a window to resize itself to fit its but‐
574 ton. The default value is "Hints".
575 NoKill / Kill - Specifies whether the swallowed program
577 will be closed by killing it or by sending a message to
578 it. This can be useful in ending programs that doesn't
579 accept window manager protocol. The default value is
580 "NoKill". This has no effect if "NoClose" is specified.
581 NoRespawn / Respawn / SwallowNew - Specifies whether the
583 swallowed program is to be respawned (restarted) if it
584 dies. If "Respawn" is specified, the program is respawned
585 using the original command. Use this option with care,
586 the program might have a legitimate reason to die. If
587 "SwallowNew" is given, the program is not respawned, but
588 if a new window with the specified name appears, it is
589 swallowed.
590 NoOld / UseOld - Specifies whether the button will try to
592 swallow an existing window matching the hangon name be‐
593 fore spawning one itself with command. The hangon string
594 may contain wildcard characters ('*') that match any sub‐
595 string.The default value is "NoOld". "UseOld" can be com‐
596 bined with "NoKill" to have windows survive a restart of
597 the window manager. If you want FvwmButtons to swallow an
598 old window, and not spawn one itself if failing, let the
599 command be "Nop":
600 *FvwmButtons: (Swallow (UseOld) "Console" Nop)
602 If you want to be able to start it yourself, combine it
604 with an action:
605 *FvwmButtons: (Swallow (UseOld) "Console" Nop, \
607 Action `Exec "Console" console &`)
608 NoTitle / UseTitle - Specifies whether the title of the
610 button will be taken from the swallowed window's title or
611 not. If "UseTitle" is given, the title on the button
612 changes dynamically to reflect the window name. The de‐
613 fault is "NoTitle".
614 NoFvwmModule / FvwmModule - By default, FvwmButtons
616 treats the swallowed window as an fvwm module window if
617 the 4 first letters of the command is "Fvwm" or the 6
618 first letters of the command is "Module". NoFvwmModule
619 and FvwmModule override this logic.
620 Title [(options)] name
623 Specifies the title to be written on the button. White‐
624 space can be included in the title by quoting it. If a
625 title at any time is too long for its buttons, characters
626 are chopped of one at a time until it fits. If justify is
627 "Right", the head is removed, otherwise its tail is re‐
628 moved. These options can be given to Title:
629 Center - The title is centered horizontally. This is the
631 default.
632 Left - The title is justified to the left side.
634 Right - The title is justified to the right side.
636 Side - Causes the title to appear on the right hand side
638 of any icon or swallowed window, instead of below which
639 is the default. If you use small icons, and combine this
640 with the "Left" or "Right" option, you can get a look
641 similar to fvwm's menus.
642 ActiveTitle name
645 Specifies the title to be written on the button when the
646 mouse is hovering above the button. If no ActiveTitle is
647 specified, the text specified by Title is displayed (if
648 there is any).
649 PressTitle name
652 Specifies the title to be written on the button when the
653 button is pressed. If no PressTitle is specified, the
654 text specified by Title is displayed (if there is any).
655 Legacy fields [title icon command]
658 These fields are kept for compatibility with previous
659 versions of FvwmButtons, and their use is discouraged.
660 The title field is similar to the option Title name. If
661 the title field is "-", no title is displayed. The icon
662 field is similar to the option Icon filename. If the icon
663 field is "-" no icon is displayed. The command field is
664 similar to the option Action command or alternatively
665 Swallow "hangon" command.
666 The command
668 Any fvwm command is recognized by FvwmButtons. See
669 fvwm(1) for more information.
670 The Exec command has a small extension when used in Ac‐
672 tions, its syntax is:
673 Exec ["hangon"] command
675 Example:
677 *FvwmButtons: (Action Exec "xload" xload)
679 The hangon string must be enclosed in double quotes.
681 When FvwmButtons finds such an Exec command, the button
682 remains pushed in until a window whose name, class or re‐
683 source matches the quoted portion of the command is en‐
684 countered. This is intended to provide visual feedback
685 to the user that the action he has requested will be per‐
686 formed. The hangon string may contain wildcard charac‐
687 ters ('*') that match any substring. If the quoted por‐
688 tion contains no characters, then the button will pop out
689 immediately. Note that users can continue pressing the
690 button, and re-executing the command, even when it looks
691 pressed in.
692 Quoting
695 Any string which contains whitespace must be quoted. Con‐
696 trary to earlier versions commands no longer need to be
697 quoted. In this case any quoting character will be passed
698 on to the application untouched. Only commas ',' and
699 closing parentheses ')' have to be quoted inside a com‐
700 mand. Quoting can be done with any of the three quotation
701 characters; single quote:
702 'This is a "quote"',
704 double quote:
706 "It's another `quote'",
708 and back quote:
710 `This is a strange quote`.
712 The back quoting is unusual but used on purpose, if you
714 use a preprocessor like FvwmCpp and want it to get into
715 your commands, like this:
716 #define BG gray60
718 *FvwmButtons: (Swallow "xload" `Exec xload -bg BG &`)
719 Any single character can be quoted with a preceding back‐
721 slash '\'.
722
724 Former versions of FvwmButtons (fvwm 2.0.46 to 2.3.6) had a different
725 way of handling panels. You can not use your old panel configuration
726 with the new panel feature. Read "CONVERTING OLD PANEL CONFIGURATIONS"
727 for more information.
728 HOW TO CREATE NEW PANELS
732 Any program that can be launched from within fvwm and that has a window
733 can be used as a panel. A terminal window could be your panel, or some
734 application like xload or xosview or another fvwm module, including
735 FvwmButtons itself. All you need to know is how to start your applica‐
736 tion from fvwm.
737 The button that invokes the panel is as easily configured as any other
739 button. Essentially you need nothing more than the Panel option:
740 *FvwmButtons: (Panel my_first_panel \
743 "Module FvwmButtons -g -30000-30000 my_first_panel")
744 *FvwmButtons: (Panel my_second_panel \
745 "Exec exec xterm -g -30000-30000 -n my_second_panel")
746 This works like the Swallow option. The difference is that the appli‐
749 cation is not put into the button when it starts up but instead hidden
750 from view. When you press the button for the panel the window slides
751 into view. The '-g -30000-30000' option tells the application that it
752 should be created somewhere very far to the top and left of your visi‐
753 ble screen. Otherwise you would see it flashing for a moment when
754 FvwmButtons starts up. Some applications do not work well with this
755 kind of syntax so you may have to live with the short flashing of the
756 window. If you want to make a panel from another instance of FvwmBut‐
757 tons you can do so, but you must give it a different name
758 ('my_first_panel' in above example). If you run FvwmButtons under the
759 same name, new panels are created recursively until your system runs
760 out of resources and FvwmButtons crashes! To configure a second button
761 bar with a different name, simply put '*new_name' in place of '*Fvwm‐
762 Buttons' in your configuration file. If you are not familiar with the
763 Swallow option or if you want to learn more about how 'swallowing' pan‐
764 els works, refer to the description of the Swallow option.
765 Now that your panel basically works you will want to tune it a bit.
767 You may not want a window title on the panel. To disable the title use
768 the fvwm Style command. If your button bar is 'sticky' you may want to
769 make the panel sticky too. And probably the panel window should have
770 no icon in case it is iconified.
771 Style name_of_panel_window NoTitle, Sitcky, NoIcon
774 You may want your panel to stay open only until you select something in
777 it. You can give FvwmButtons the -transientpanel option after the -g
778 option in the command. FvwmPager has a similar option '-transient'.
779 Last, but not least, you can now put an icon, a title or a small arrow
781 in the button so that you can see what it is for. A title or icon can
782 be specified as usual. To activate the arrow, just add '(indicator)'
783 after the 'Panel' keyword in the example above and the Padding option
784 to leave a few pixels between the arrow and the border of the button.
785 An optional direction in which the panel is opened can be given too:
786 *FvwmButtons: (Padding 2, Panel(down, indicator) my_first_panel \
789 "Module FvwmButtons -g -30000-30000 -transientpanel my_first_panel")
790 There are several more options to configure how your panel works, for
793 example the speed and smoothness of the sliding animation. Please refer
794 to the description of the Panel option for further details.
795 CONVERTING OLD PANEL CONFIGURATIONS
798 This section describes how to convert a pretty old syntax used in 2.2.x
799 versions. You may skip it if your syntax is more recent.
800 With the old panel feature you first had one or more lines defining
802 panels in your main FvwmButtons configuration:
803 ...
806 *FvwmButtons(Title WinOps,Panel WinOps)
807 *FvwmButtons(Title Tools ,Panel Tools)
808 ...
809 After the last configuration line for the main panel the configuration
812 of the first panel followed, introduced with a line beginning with
813 *FvwmButtonsPanel:
814 *FvwmButtonsPanel WinOps
817 *FvwmButtonsBack bisque2
818 ...
819 *FvwmButtonsPanel Tools
821 *FvwmButtonsBack bisque2
822 ...
823 And perhaps you had style commands for you panels:
826 Style FvwmButtonsPanel Title, NoHandles, BorderWidth 0
829 Style FvwmButtonsPanel NoButton 2, NoButton 4, Sticky
830 The new configuration looks much the same, but now the configuration of
833 the main panel is independent of the configuration of the sub panels.
834 The lines invoking the panels use the same syntax as the Swallow op‐
835 tion, so you simply add the name of the window to use as a panel and
836 the command to execute instead of the panel name. Note that you give
837 the new instance of FvwmButtons a different name.
838 *FvwmButtons: (Title WinOps, Panel WinOps \
841 "Module FvwmButtons WinOps")
842 *FvwmButtons: (Title Tools , Panel Tools \
843 "Module FvwmButtons Tools")
844 If you used something like 'Panel-d' you now have to use 'Panel(down)'
847 instead. To make the new panel vanish as soon as a button was selected
848 start FvwmButtons with the '-transientpanel' option:
849 *FvwmButtons: (Title Tools , Panel(down) Tools \
852 "Module FvwmButtons -transientpanel Tools")
853 The rest of the configuration is very easy to change. Delete the lines
856 '*FvwmButtonsPanel <name>' and add <name> to all of the following con‐
857 figuration lines for the panel instead. Use the same name in your Style
858 commands:
859 *WinOps: Back bisque2
862 ...
863 *Tools: Back bisque2
864 ...
865 Style "WinOps" Title, NoHandles, BorderWidth 0
866 Style "WinOps" NoButton 2, NoButton 4, Sticky
867 Style "Tools" Title, NoHandles, BorderWidth 0
868 Style "Tools" NoButton 2, NoButton 4, Sticky
869 That's it. The new panels are much more flexible. Please refer to
872 other parts of this documentation for details.
873 WHY WAS THE PANEL FEATURE REWRITTEN?
876 There are several reasons. The most important one is that the program
877 code implementing the panels was very disruptive and caused a lot of
878 problems. At the same time it made writing new features for FvwmBut‐
879 tons difficult at best. The second reason is that most users were sim‐
880 ply unable to make it work - it was way too complicated. Even I (the
881 author of the new code) had to spend several hours before I got it
882 working the first time. The third reason is that the new panels are
883 more versatile. Any application can be a panel in FvwmButtons, not
884 just other instances of FvwmButtons itself. So I sincerely hope that
885 nobody is angry about the change. Yes - you have to change your config‐
886 uration, but the new feature is much easier to configure, especially if
887 you already know how the Swallow option works.
888
891 FvwmButtons tries to arrange its buttons as best it can, by using re‐
892 cursively, on each container including the buttonbox itself, the fol‐
893 lowing algorithm.
894 Getting the size right
896 First it calculates the number of button unit areas it will
897 need, by adding the width times the height in buttons of each
898 button. Containers are for the moment considered a normal but‐
899 ton. Then it considers the given rows and columns arguments. If
900 the number of rows is given, it will calculate how many columns
901 are needed, and stick to that, unless columns is larger, in
902 which case you will get some empty space at the bottom of the
903 buttonbox. If the number of columns is given, it calculates how
904 many rows it needs to fit all the buttons. If neither is given,
905 it assumes you want two rows, and finds the number of columns
906 from that. If the BoxSize option is set to smart at least the
907 height/width of the tallest/widest button is used while the
908 fixed value prevents the box from getting resized if both rows
909 and columns have been set to non-zero.
910 Shuffling buttons
912 Now it has a large enough area to place the buttons in, all that
913 is left is to place them right. There are two kinds of buttons:
914 fixed and floating buttons. A fixed button is forced to a spe‐
915 cific slot in the button box by a x/y geometry argument. All
916 other buttons are considered floating. Fixed buttons are placed
917 first. Should a fixed button overlap another one or shall be
918 place outside the buttons window, FvwmButtons exits with an er‐
919 ror message. After that the floating buttons are placed. The al‐
920 gorithm tries to place the buttons in a left to right, top to
921 bottom western fashion. If a button fits at the suggested posi‐
922 tion it is placed there, if not the current slot stays empty and
923 the slot to the right will be considered. After the button has
924 been placed, the next button is tried to be placed in the next
925 slot and so on until all buttons are placed. Additional rows are
926 added below the bottom line of buttons until all buttons are
927 placed if necessary if the BoxSize option smart is used.
928 Containers
930 Containers are arranged by the same algorithm, in fact they are
931 shuffled recursively as the algorithm finds them.
932 Clarifying example
934 An example might be useful here: Suppose you have 6 buttons, all
935 unit sized except number two, which is 2x2. This makes for 5
936 times 1 plus 1 times 4 equals 9 unit buttons total area. Assume
937 you have requested 3 columns.
938 1) +---+---+---+ 2) +---+---+---+ 3) +---+---+---+
940 | 1 | | | 1 | | | 1 | |
941 +---+ + +---+ 2 + +---+ 2 +
942 | | | | | | 3 | |
943 + + + +---+---+ +---+---+---+
944 | | | | | | | |
945 +-----------+ +---+-------+ +---+---+---+
946 4) +---+---+---+ 5) +---+-------+ 6) +---+-------+
948 | 1 | | | 1 | | | 1 | |
949 +---+ 2 + +---+ 2 | +---+ 2 |
950 | 3 | | | 3 | | | 3 | |
951 +---+---+---+ +---+---+---+ +---+-------+
952 | 4 | | | 4 | 5 | | | 4 | 5 | 6 |
953 +---+---+---+ +---+---+---+ +---+---+---+
954 What size will the buttons be?
957 When FvwmButtons has read the icons and fonts that are required
958 by its configuration, it can find out which size is needed for
959 every non-swallowing button. The unit button size of a container
960 is set to be large enough to hold the largest button in it with‐
961 out squeezing it. Swallowed windows are simply expected to be
962 comfortable with the button size they get from this scheme. If a
963 particular configuration requires more space for a swallowed
964 window, it can be set in that button's configuration line using
965 the option "Size width height". This will tell FvwmButtons to
966 give this button at least width by height pixels inside the re‐
967 lief and padding.
968
971 A running FvwmButtons instance may receive some commands at run time.
972 This is achieved using the fvwm command
973 SendToModule FvwmButtons-Alias <action> <params>
975 Supported actions:
977 ChangeButton button_id options
980 can be used to change the title or icon of a button at run time.
981 button_id is the id of the button to change as specified using
982 the Id button option. It may also be a number, in this case the
983 button with the given number is assumed. And finally, button_id
984 may be in the form +x+y, where x and y are a column number and a
985 row number of the button to be changed. It is possible to spec‐
986 ify multiple option pairs (name with value) by delimiting them
987 using comma. Currently options include Title, ActiveTitle,
988 PressTitle, Colorset, Icon, ActiveIcon and PressIcon. These op‐
989 tions work like the configuration options of the same name.
990 ExpandButtonVars button_id command
993 replaces variables present in the command exactly like in the
994 Action button option and then sends the command back to fvwm.
995 button_id has the same syntax as described in ChangeButton
996 above.
997 PressButton button_id [mouse_button]
1000 simulates a mouse click on a button. button_id is the id of the
1001 button to press as specified using the Id button option and
1002 mouse_button is the number of mouse button used to click on the
1003 button e.g "1" for the left mouse button etc. Quotes around the
1004 number are not necessary. If mouse_button option is omitted,
1005 mouse button 1 is assumed. This command behaves exactly as if
1006 the mouse button was pressed and released on the button on in
1007 question.
1008 Silent This prefix may be specified before other actions. It disables
1011 all possible error and warning messages.
1012 Example:
1015 *FvwmButtons: (Id note1, Title "13:30 - Dinner", Icon clock1.xpm)
1017 SendToModule FvwmButtons Silent \
1019 ChangeButton note1 Icon clock2.xpm, Title "18:00 - Go Home"
1020
1024 The following are excerpts from a .fvwm2rc file which describe FvwmBut‐
1025 tons initialization commands:
1026 ##########################################################
1029 # Load any modules which should be started during fvwm
1030 # initialization
1031 # Make sure FvwmButtons is always there.
1033 AddToFunc StartFunction "I" Module FvwmButtons
1034 # Make it titlebar-less, sticky, and give it an icon
1036 Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky
1037 # Make the menu/panel look like CDE
1039 Style "WinOps" Title, NoHandles, BorderWidth 0
1040 Style "WinOps" NoButton 2, NoButton 4, Sticky
1041 Style "Tools" Title, NoHandles, BorderWidth 0
1042 Style "Tools" NoButton 2, NoButton 4, Sticky
1043 ##########################################################
1045 DestroyModuleConfig FvwmButtons: *
1046 *FvwmButtons: Fore Black
1047 *FvwmButtons: Back rgb:90/80/90
1048 *FvwmButtons: Geometry -135-5
1049 *FvwmButtons: Rows 1
1050 *FvwmButtons: BoxSize smart
1051 *FvwmButtons: Font -*-helvetica-medium-r-*-*-12-*
1052 *FvwmButtons: Padding 2 2
1053 *FvwmButtons: (Title WinOps, Panel WinOps \
1055 "Module FvwmButtons -transientpanel WinOps")
1056 *FvwmButtons: (Title Tools, Panel Tools \
1057 "Module FvwmButtons -transientpanel Tools")
1058 *FvwmButtons: (Title Resize, Icon resize.xpm, Action Resize)
1060 *FvwmButtons: (Title Move, Icon arrows2.xpm, Action Move )
1061 *FvwmButtons: (Title Lower, Icon Down, Action Lower )
1062 *FvwmButtons: (Title Raise, Icon Up, Action Raise )
1063 *FvwmButtons: (Title Kill, Icon bomb.xpm, Action Destroy)
1064 *FvwmButtons: (1x1,Container(Rows 3,Frame 1))
1066 *FvwmButtons: (Title Dopey ,Action \
1067 `Exec "big_win" xterm -T big_win -geometry 80x50 &`)
1068 *FvwmButtons: (Title Snoopy, Font fixed, Action \
1069 `Exec "small_win" xterm -T small_win &`)
1070 *FvwmButtons: (Title Smokin')
1071 *FvwmButtons: (End)
1072 *FvwmButtons: (Title Xcalc, Icon rcalc.xpm, \
1074 Action `Exec "Calculator" xcalc &`)
1075 *FvwmButtons: (Title XMag, Icon magnifying_glass2.xpm, \
1076 Action `Exec "xmag" xmag &`)
1077 *FvwmButtons: (Title Mail, Icon mail2.xpm, \
1078 Action `Exec "xmh" xmh &`)
1079 *FvwmButtons: (4x1, Swallow "FvwmPager" `FvwmPager 0 3` \
1080 Frame 3)
1081 *FvwmButtons: (Swallow(UseOld,NoKill) "xload15" `Exec xload \
1083 -title xload15 -nolabel -bg rgb:90/80/90 -update 15 \
1084 -geometry -3000-3000 &`)
1085 The last lines are a little tricky - one spawns an FvwmPager module,
1088 and captures it to display in a quadruple width button. is used, the
1089 Pager will be as big as possible within the button's relief.
1090 The final line is even more magic. Note the combination of UseOld and
1092 NoKill, which will try to swallow an existing window with the name
1093 "xload15" when starting up (if failing: starting one with the specified
1094 command), which is un-swallowed when ending FvwmButtons. The swallowed
1095 application is started with "-geometry -3000-3000" so that it will not
1096 be visible until its swallowed.
1097 The other panels are specified after the root panel:
1099 ########## PANEL WinOps
1102 DestroyModuleConfig WinOps: *
1103 *WinOps: Back bisque2
1104 *WinOps: Geometry -3-3
1105 *WinOps: Columns 1
1106 *WinOps: (Title Resize, Icon resize.xpm, Action Resize)
1108 *WinOps: (Title Move, Icon arrows2.xpm, Action Move )
1109 *WinOps: (Title Lower, Icon Down, Action Lower )
1110 *WinOps: (Title Raise, Icon Up, Action Raise )
1111 ########## PANEL Tools
1113 DestroyModuleConfig Tools: *
1114 *Tools: Back bisque2
1115 *Tools: Geometry -1-1
1116 *Tools: Columns 1
1117 *Tools: (Title Kill, Icon bomb.xpm, Action Destroy)
1119 The color specification rgb:90/80/90 is actually the most correct way
1122 of specifying independent colors in X, and should be used instead of
1123 the older #908090. If the latter specification is used in your configu‐
1124 ration file, you should be sure to escape the hash in any of the com‐
1125 mands which will be executed, or fvwm will consider the rest of the
1126 line a comment.
1127 Note that with the x/y geometry specs you can easily build button win‐
1129 dows with gaps. Here is another example. You can not accomplish this
1130 without geometry specs for the buttons:
1131 ##########################################################
1133 # Another example
1134 ##########################################################
1135 # Make it titlebar-less, sticky, and give it an icon
1137 Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky
1138 DestroyModuleConfig FvwmButtons: *
1140 *FvwmButtons: Font 5x7
1141 *FvwmButtons: Back rgb:90/80/90
1142 *FvwmButtons: Fore black
1143 *FvwmButtons: Frame 1
1144 # 9x11 pixels per button, 4x4 pixels for the frame
1145 *FvwmButtons: Geometry 580x59+0-0
1146 *FvwmButtons: Rows 5
1147 *FvwmButtons: Columns 64
1148 *FvwmButtons: BoxSize fixed
1149 *FvwmButtons: Padding 1 1
1150 # Pop up a module menu directly above the button.
1152 *FvwmButtons: (9x1+3+0, Padding 0, Title "Modules", \
1153 Action `Menu Modulepopup rectangle \
1154 $widthx$height+$lleft+$top o+50 -100m`)
1155 # first row of buttons from left to right:
1157 *FvwmButtons: (3x2+0+1, Icon my_lock.xpm, Action `Exec xlock`)
1158 *FvwmButtons: (3x2+3+1, Icon my_recapture.xpm, Action Recapture)
1159 *FvwmButtons: (3x2+6+1, Icon my_resize.xpm, Action Resize)
1160 *FvwmButtons: (3x2+9+1, Icon my_move.xpm, Action Move)
1161 *FvwmButtons: (3x2+12+1, Icon my_fvwmconsole.xpm, \
1162 Action 'Module FvwmConsole')
1163 # second row of buttons from left to right:
1165 *FvwmButtons: (3x2+0+3, Icon my_exit.xpm, Action QuitSave)
1166 *FvwmButtons: (3x2+3+3, Icon my_restart.xpm, Action Restart)
1167 *FvwmButtons: (3x2+6+3, Icon my_kill.xpm, Action Destroy)
1168 *FvwmButtons: (3x2+9+3, Icon my_shell.xpm, Action 'Exec rxvt')
1169 # big items
1171 *FvwmButtons: (10x5, Swallow (NoKill, NoCLose) \
1172 "FvwmPager" 'FvwmPager * * -geometry 40x40-1024-1024')
1173 *FvwmButtons: (6x5, Swallow "FvwmXclock" `Exec xclock \
1174 -name FvwmXclock -geometry 40x40+0-3000 -padding 1 \
1175 -analog -chime -bg rgb:90/80/90`)
1176 *FvwmButtons: (13x5, Swallow (NoClose) \
1177 "FvwmIconMan" 'Module FvwmIconMan')
1178 *FvwmButtons: (20x5, Padding 0, Swallow "xosview" \
1179 `Exec /usr/X11R6/bin/xosview -cpu -int -page -net \
1180 -geometry 100x50+0-3000 -font 5x7`)
1181
1185 The action part of the Swallow option must be quoted if it contains any
1186 whitespace character.
1187
1190 The FvwmButtons program, and the concept for interfacing this module to
1191 the Window Manager, are all original work by Robert Nation.
1192 Copyright 1993, Robert Nation. No guarantees or warranties or anything
1194 are provided or implied in any way whatsoever. Use this program at your
1195 own risk. Permission to use this program for any purpose is given, as
1196 long as the copyright is kept intact.
1197 Further modifications and patching by Jarl Totland, copyright 1996.
1199 The statement above still applies.
1200
1203 Robert Nation. Somewhat enhanced by Jarl Totland, Jui-Hsuan Joshua
1204 Feng, Scott Smedley.
12053rd Berkeley Distribution 19 October 2022 (2.7.0) FvwmButtons(1)