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
23 invoked. 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
44 option, but instead of closing the whole button bar, the window is
45 merely hidden. This is very useful if the button bar is started as a
46 subpanel of another button bar because it avoids that it must be
47 started again 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
91 until all buttons are placed. For the best tolerance of configu‐
92 ration 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 FvwmTheme man page for details about col‐
100 orsets.
101 *FvwmButtons: ActiveColorset colorset
104 Tells the module to use colorset colorset for the background
105 color/image and/or title color of a button when the mouse is
106 hovering above a button.
107 *FvwmButtons: PressColorset colorset
110 Tells the module to use colorset colorset for the background
111 color/image and/or title color of a button when it is pressed.
112 *FvwmButtons: Columns columns
115 Specifies the number of columns of buttons to be created. If
116 unspecified, the number of columns is set to the number of but‐
117 tons requested, divided by the number of rows. If both the rows
118 and columns are specified, but the number of buttons is more
119 than the rows and columns allow for, the columns specification
120 is ignored unless the BoxSize option is fixed.
121 *FvwmButtons: File filename
124 Specifies that the configuration for this button is found in the
125 file filename. Filename can be a full pathname, or is assumed to
126 be in fvwm's startup directory. The configuration file is in the
127 same format as fvwm's configuration file, but each line is read
128 as if prefixed by "*FvwmButtons". Comments are given by starting
129 a line with "#". Line continuation is done by ending a line with
130 a "\".
131 *FvwmButtons: Font font
134 Specifies the font to be used for labeling the buttons, or None.
135 *FvwmButtons: Fore color
138 Specifies the color used for button label text and monochrome
139 icons.
140 *FvwmButtons: Frame width
143 Specifies the width of the relief around each button. If this is
144 a negative number, the relief is inverted. This makes the button
145 sunken normally and raised when activated.
146 *FvwmButtons: Geometry geometry
149 Specifies the FvwmButtons window location and size. The geome‐
150 try is a standard X11 window geometry specification.
151 *FvwmButtons: ButtonGeometry geometry
154 This option works like the Geometry option except that the size
155 is the size of a single button. The size of the whole FvwmBut‐
156 tons window is calculated by multiplying the button dimension by
157 the number of rows and columns.
158 *FvwmButtons: Padding width height
161 This option specifies the default horizontal padding to be width
162 pixels, and the vertical padding to be height pixels. The amount
163 of free space between the relief of the button and its contents
164 is normally 2 pixels on the sides and 4 pixels above and below,
165 except for swallowed windows and containers, which are not
166 padded at all, unless this option is used.
167 *FvwmButtons: Pixmap pixmapfile
170 Specifies a background pixmap to use. Specify "none" (without
171 the double quotes) for a transparent background.
172 *FvwmButtons: Rows rows
175 Specifies the number of rows of buttons to be created. The
176 default is 2 rows.
177 *FvwmButtons: (options) [title icon command]
180 Specifies the contents of a button in the buttonbox. The follow‐
181 ing options, separated by commas or whitespace, can be given a
182 button:
183 geometry
185 Specifies the size and position of the button within the
186 FvwmButtons window or container. The geometry is a stan‐
187 dard X11 window geometry specification. The button is
188 width times the normal button width and height times the
189 normal button height. If values for x and y are given,
190 the button is placed x (y) button units from the left
191 (top) of the container if x (y) is positive and x (y)
192 units from the right (bottom) if x (y) is negative. But‐
193 tons with position arguments (x and y) are placed before
194 those without them. If two or more buttons are forced to
195 overlap by this, FvwmButtons exits with an error message.
196 Action [(options)] command
199 Specifies an fvwm command to be executed when the button
200 is activated by pressing return or a mouse button. The
201 command needs to be quoted if it contains a comma or a
202 closing parenthesis.
203 The current options of the Action are: Mouse n - this
205 action is only executed for mouse button n. One action
206 can be defined for each mouse button, in addition to the
207 general action.
208 In the command part, you can use a number of predefined
210 variables: $left, $right, $top and $bottom are substi‐
211 tuted by the left, right, top and bottom coordinates of
212 the button pressed. $-left, $-right, $-top and $-bottom
213 are substituted likewise, but the coordinates are calcu‐
214 lated from the bottom or the right edge of the screen
215 instead (for a button that is 5 pixels away from the
216 right screen border, $-right will be 5). $width and
217 $height are replaced by the width or height of the but‐
218 ton. The variables $fg and $bg are replaced with the name
219 of the foreground or background color set with the Back
220 or Fore option (see below). All this is done regardless
221 of any quoting characters. To get a literal '$' use the
222 string '$$'.
223 Example:
225 *FvwmButtons: (Title xload, Action (Mouse 1) \
228 `Exec exec xload -fg $fg -bg $bg -geometry -3000-3000`)
229 Note: With fvwm versions prior to 2.5.0, actions could
232 not be assigned to a button that swallowed an application
233 window (see Swallow option). Such actions worked only
234 when the border around the button was clicked. This is
235 now possible, but to get back the old behavior, the
236 ActionIgnoresClientWindow can be used on the button:
237 *FvwmButtons: (Action beep, ActionIgnoresClientWindow, \
240 Swallow xeyes "Exec exec xeyes")
241 In this example, the action is only executed when you
244 click on the border of the button or the transparent part
245 of the xeyes window, but not on the xeyes window itself.
246 ActionIgnoresClientWindow
249 See the note in the description of Action above.
250 ActionOnPress
253 Usually the action is executed on the button release
254 except for the Popup action. This option changes this
255 behavior, the action is executed on the button press.
256 This may be good, for example, with Menu or SendToModule
257 that generates popups, or when Frame is 0 and the button
258 would look unresponsive otherwise.
259 Back color
262 Specifies the background color to be used drawing this
263 box. A relief color and a shadow color are calculated
264 from this.
265 Center The contents of the button is centered on the button.
268 This is the default but may be changed by Left or Right.
269 Top The contents of the button is vertically aligned at the
272 top of the button. The default is to vertically center
273 it.
274 Colorset colorset
277 The given colorset can be applied to a container, a swal‐
278 lowed application and a simple button. To apply it to a
279 button or container, simply put the option in a line with
280 a button or container description. Drawing backgrounds
281 for individual buttons and containers with colorsets
282 requires a lot of communication with the X server. So if
283 you are not content with the drawing speed of dozens of
284 buttons with colorset backgrounds, do not use colorsets
285 here. Setting colorsets as the background of swallowed
286 applications does not have this restriction but depends
287 entirely on the swallowed application. It may work as
288 you wish, but since it involves fiddling with other
289 applications' windows there is no guarantee for anything.
290 I have tested three applications: xosview works nicely
291 with a colorset background, xload works only with a VGra‐
292 dient or solid background and an analog xclock leaves a
293 trail painted in the background color after its hands.
294 If the swallowed window is an fvwm module (see the
296 (No)FvwmModule option to Swallow), then the colorset is
297 not applied to the swallowed module. You should use the
298 colorset in the module configuration. If the swallowed
299 module has a transparent colorset background, then the
300 FvwmButtons background (and not the button colorset) is
301 seen by transparency of the background of the swallowed
302 module. Refer to the man page of the FvwmTheme module for
303 details about colorsets.
304 ActiveColorset colorset
307 Use colorset colorset for the background color/image
308 and/or title color of the button when the mouse is hover‐
309 ing above it.
310 PressColorset colorset
313 Use colorset colorset for the background color/image
314 and/or title color of the button when it is pressed.
315 Container [(options)]
318 Specifies that this button will contain a miniature but‐
319 tonbox, equivalent to swallowing another FvwmButtons mod‐
320 ule. The options are the same as can be given for a sin‐
321 gle button, but they affect all the contained buttons.
322 Options available for this use are Back, Font, Fore,
323 Frame and Padding. Flags for Title and Swallow options
324 can be set with Title(flags) and Swallow(flags). You
325 should also specify either "Columns width" or "Rows
326 height", or "Rows 2" will be assumed. For an example, see
327 the Sample configuration section.
328 The container button itself (separate from the contents)
330 can take format options like Frame and Padding, and com‐
331 mands can be bound to it. This means you can make a sen‐
332 sitive relief around a container, like
333 *FvwmButtons: (2x2, Frame 5, Padding 2 2, Action Beep,\
335 Container(Frame 1))
336 Typically you will want to at least give the container a
338 size setting widthxheight.
339 End Specifies that no more buttons are defined for the cur‐
342 rent container, and further buttons will be put in the
343 container's parent. This option should be given on a line
344 by itself, i.e
345 *FvwmButtons: (End)
347 Font fontname
351 Specifies that the font fontname is to be used for label‐
352 ing this button.
353 Fore color
356 Specifies the foregound color of the title and monochrome
357 icons in this button.
358 Frame width
361 The relief of the button will be width pixels wide. If
362 width is given as a negative number, the relief is
363 inverted. This makes the button sunken normally and
364 raised when activated.
365 Icon filename
368 The name of an image file, containing the icon to display
369 on the button. FvwmButtons searches through the path
370 specified in the fvwm ImagePath configuration item to
371 find the icon file.
372 ActiveIcon filename
375 The name of an image file, containing an alternative icon
376 to display on the button when the mouse is hovering above
377 the button. If no ActiveIcon is specified, the image
378 specified by Icon is displayed (if there is one).
379 PressIcon filename
382 The name of an image file, containing an alternative icon
383 to display on the button when the button is pressed. If
384 no PressIcon is specified, the image specified by Icon is
385 displayed (if there is one).
386 Id id The id to be used to identify this button. The first
389 character of the id should be alphabetic. See also the
390 "DYNAMICAL ACTIONS" section.
391 Left The contents of the button are aligned to the left. The
394 default is to center the contents on the button.
395 NoSize This option specifies that this button will not be con‐
398 sidered at all when making the initial calculations of
399 button sizes. Useful for the odd button that gets just a
400 couple of pixels too large to keep in line, and therefor
401 blows up your whole buttonbox. "NoSize" is equivalent to
402 "Size 0 0".
403 Padding width height
406 The amount of free space between the relief of the button
407 and its contents is normally 2 pixels to the sides and 4
408 pixels above and below, except for swallowed windows and
409 containers, which are by default not padded at all. This
410 option sets the horizontal padding to width and the ver‐
411 tical padding to height.
412 Panel [ (options) ] hangon command
415 Panels can be swallowed exactly like windows are swal‐
416 lowed by buttons with the Swallow command below, but they
417 are not displayed within the button. Instead they are
418 hidden until the user presses the panel's button. Then
419 the panel (the window of the swallowed application) opens
420 with a sliding animation. The options can be any of the
421 flags described for the Swallow command. In addition a
422 direction 'left', 'right', 'up' or 'down' can be used to
423 specify the sliding direction.
424 The steps animation-steps option defines the number of
426 animation steps.
427 The delay ms option sets the delay between the steps of
429 the animation in milliseconds. Use zero for no delay.
430 The maximum delay is 10 seconds (10000). It doesn't make
431 any sense to use the delay option unless you also use the
432 smooth option.
433 The smooth option causes the panel to redraw between
435 the steps of the animation. The sliding animation may be
436 smoother this way, it depends on the application, and
437 display speed. The application may appear to grow
438 instead of sliding out. The animation may be slower.
439 The Hints option causes FvwmButtons to use the applica‐
441 tions size hints to calculate the size of the animation
442 steps. Hints is the default. If the number of steps is
443 not what you want, try using NoHints.
444 The noborder option tells FvwmButtons to ignore the bor‐
446 ders of the window when calculating positions for the
447 animation (equivalent to set noplr and noptb in the posi‐
448 tion option).
449 With the indicator option set, FvwmButtons will draw a
451 small triangle in the button that will open a panel. The
452 triangle points in the direction where the panel will pop
453 up. The indicator keyword may be followed by a positive
454 integer that specifies the maximum width and height of
455 the indicator. Without this size FvwmButtons will make
456 the indicator fit the button. You will probably want to
457 use the Padding option to leave a few pixels between the
458 indicator and the frame of the button.
459 The position option allows to place the panel. The syntax
461 is:
462 position [context-window] [pos] [x y] [border-opts]
464 The argument context-window can be one of: Button, Module
466 or Root. The context-window is the window from which
467 panel percentage offsets are calculated. Button specifies
468 the panel's button, Module specifies FvwmButtons itself,
469 and Root specifies a virtual screen. The context-window
470 together with the sliding direction define a line segment
471 which is one of the borders of the context-window: the
472 top/bottom/left/right border for sliding
473 up/down/left/right.
474 The pos argument can be one of: center, left or right
476 (for sliding up or a down) or top or bottom (for sliding
477 left or right). It defines the vertical (sliding up and
478 down) or the horizontal (sliding left and right) position
479 of the Panel on the line segment. For example, for a
480 sliding up if you use a left pos, then the left borders
481 of the panel and of the context-window will be aligned.
482 The offset values x and y specify how far the panel is
484 moved from it's default position. By default, the numeric
485 value given is interpreted as a percentage of the context
486 window's width (height). A trailing "p" changes the
487 interpretation to mean "pixels". All offset calculations
488 are relative to the buttons location, even when using a
489 root context.
490 The border-opts are: mlr, mtb, noplr and noptb. They
492 define which border widths are taken in account. By
493 default, the borders of FvwmButtons are not taken in
494 account. mlr reverses this default for the left and the
495 right border and mtb reverses this default for the top
496 and the bottom border. Conversely, by default the borders
497 of the Panel are taken in account. noplr reverses this
498 default for the left and the right border and noptb
499 reverses this default for the top and the bottom border.
500 The defaults are sliding up with a delay of five mil‐
502 liseconds and twelve animation steps. To post the panel
503 without any animation, set the number of steps to zero.
504 The default position is 'Button center'.
505 Please refer to the CREATING PANELS section for further
507 information on panels.
508 Example:
510 # To include the panel in a button
512 *FvwmButtons: (Panel(down, delay 0, steps 16) \
513 SubPanel "Module FvwmButtons SubPanel")
514 # To define the panel as an instance of
516 # FvwmButtons with a different name:
517 *SubPanel: (Icon my_lock.xpm, Action Exec xlock)
518 *SubPanel: (Icon my_move.xpm, Action Move)
519 ...
520 Right The contents of the button are aligned to the right. The
524 default is to center the contents on the button.
525 Size width height
528 Specifies that the contents of this button require width
529 by height pixels, regardless of what size FvwmButtons
530 calculates from the icon and the title. A button bar with
531 only swallowed windows will not get very large without
532 this option specified, as FvwmButtons does not consider
533 sizes for swallowing buttons. Note that this option gives
534 the minimum space assured; other buttons might require
535 the buttonbox to use larger sizes.
536 Swallow [(flags)] hangon command
539 Causes FvwmButtons to execute command, and when a window
540 with a name, class or resource matching hangon appears,
541 it is captured and swallowed into this button. The
542 hangon string may contain wildcard characters ('*') that
543 match any substring. Swallow replaces the variables $fg
544 and $bg as described above for the Action option (but if
545 you use the UseOld and NoClose options the application is
546 not be restarted when FvwmButtons is restarted and thus
547 does not get the new colors - if you changed them). An
548 example:
549 *FvwmButtons: (Swallow XClock 'Exec xclock -geometry -3000-3000 &')
551 takes the first window whose name, class, or resource is
553 "XClock" and displays it in the button. If no matching
554 window is found, the "Exec" command creates one. The
555 argument "-geometry -3000-3000" is used so that the win‐
556 dow is first drawn out of sight before its swallowed into
557 FvwmButtons.
558 Modules can be swallowed by specifying the module instead
560 of 'Exec whatever', like:
561 *FvwmButtons: (Swallow "FvwmPager" "FvwmPager 0 0")
563 The flags that can be given to swallow are:
565 NoClose / Close - Specifies whether the swallowed program
567 in this button will be un-swallowed or closed when Fvwm‐
568 Buttons exits cleanly. "NoClose" can be combined with
569 "UseOld" to have windows survive a restart of the window
570 manager. The default setting is "Close".
571 NoHints / Hints - Specifies whether hints from the swal‐
573 lowed program in this button will be ignored or not, use‐
574 ful in forcing a window to resize itself to fit its but‐
575 ton. The default value is "Hints".
576 NoKill / Kill - Specifies whether the swallowed program
578 will be closed by killing it or by sending a message to
579 it. This can be useful in ending programs that doesn't
580 accept window manager protocol. The default value is
581 "NoKill". This has no effect if "NoClose" is specified.
582 NoRespawn / Respawn / SwallowNew - Specifies whether the
584 swallowed program is to be respawned (restarted) if it
585 dies. If "Respawn" is specified, the program is respawned
586 using the original command. Use this option with care,
587 the program might have a legitimate reason to die. If
588 "SwallowNew" is given, the program is not respawned, but
589 if a new window with the specified name appears, it is
590 swallowed.
591 NoOld / UseOld - Specifies whether the button will try to
593 swallow an existing window matching the hangon name
594 before spawning one itself with command. The hangon
595 string may contain wildcard characters ('*') that match
596 any substring.The default value is "NoOld". "UseOld" can
597 be combined with "NoKill" to have windows survive a
598 restart of the window manager. If you want FvwmButtons to
599 swallow an old window, and not spawn one itself if fail‐
600 ing, let the command be "Nop":
601 *FvwmButtons: (Swallow (UseOld) "Console" Nop)
603 If you want to be able to start it yourself, combine it
605 with an action:
606 *FvwmButtons: (Swallow (UseOld) "Console" Nop, \
608 Action `Exec "Console" console &`)
609 NoTitle / UseTitle - Specifies whether the title of the
611 button will be taken from the swallowed window's title or
612 not. If "UseTitle" is given, the title on the button
613 changes dynamically to reflect the window name. The
614 default is "NoTitle".
615 NoFvwmModule / FvwmModule - By default, FvwmButtons
617 treats the swallowed window as an fvwm module window if
618 the 4 first letters of the command is "Fvwm" or the 6
619 first letters of the command is "Module". NoFvwmModule
620 and FvwmModule override this logic.
621 Title [(options)] name
624 Specifies the title to be written on the button. White‐
625 space can be included in the title by quoting it. If a
626 title at any time is too long for its buttons, characters
627 are chopped of one at a time until it fits. If justify is
628 "Right", the head is removed, otherwise its tail is
629 removed. These options can be given to Title:
630 Center - The title is centered horizontally. This is the
632 default.
633 Left - The title is justified to the left side.
635 Right - The title is justified to the right side.
637 Side - Causes the title to appear on the right hand side
639 of any icon or swallowed window, instead of below which
640 is the default. If you use small icons, and combine this
641 with the "Left" or "Right" option, you can get a look
642 similar to fvwm's menus.
643 ActiveTitle name
646 Specifies the title to be written on the button when the
647 mouse is hovering above the button. If no ActiveTitle is
648 specified, the text specified by Title is displayed (if
649 there is any).
650 PressTitle name
653 Specifies the title to be written on the button when the
654 button is pressed. If no PressTitle is specified, the
655 text specified by Title is displayed (if there is any).
656 Legacy fields [title icon command]
659 These fields are kept for compatibility with previous
660 versions of FvwmButtons, and their use is discouraged.
661 The title field is similar to the option Title name. If
662 the title field is "-", no title is displayed. The icon
663 field is similar to the option Icon filename. If the icon
664 field is "-" no icon is displayed. The command field is
665 similar to the option Action command or alternatively
666 Swallow "hangon" command.
667 The command
669 Any fvwm command is recognized by FvwmButtons. See
670 fvwm(1) for more information.
671 The Exec command has a small extension when used in
673 Actions, its syntax is:
674 Exec ["hangon"] command
676 Example:
678 *FvwmButtons: (Action Exec "xload" xload)
680 The hangon string must be enclosed in double quotes.
682 When FvwmButtons finds such an Exec command, the button
683 remains pushed in until a window whose name, class or
684 resource matches the quoted portion of the command is
685 encountered. This is intended to provide visual feedback
686 to the user that the action he has requested will be per‐
687 formed. The hangon string may contain wildcard charac‐
688 ters ('*') that match any substring. If the quoted por‐
689 tion contains no characters, then the button will pop out
690 immediately. Note that users can continue pressing the
691 button, and re-executing the command, even when it looks
692 pressed in.
693 Quoting
696 Any string which contains whitespace must be quoted. Con‐
697 trary to earlier versions commands no longer need to be
698 quoted. In this case any quoting character will be passed
699 on to the application untouched. Only commas ',' and
700 closing parentheses ')' have to be quoted inside a com‐
701 mand. Quoting can be done with any of the three quotation
702 characters; single quote:
703 'This is a "quote"',
705 double quote:
707 "It's another `quote'",
709 and back quote:
711 `This is a strange quote`.
713 The back quoting is unusual but used on purpose, if you
715 use a preprocessor like FvwmCpp and want it to get into
716 your commands, like this:
717 #define BG gray60
719 *FvwmButtons: (Swallow "xload" `Exec xload -bg BG &`)
720 Any single character can be quoted with a preceding back‐
722 slash '\'.
723
725 Former versions of FvwmButtons (fvwm 2.0.46 to 2.3.6) had a different
726 way of handling panels. You can not use your old panel configuration
727 with the new panel feature. Read "CONVERTING OLD PANEL CONFIGURATIONS"
728 for more information.
729 HOW TO CREATE NEW PANELS
733 Any program that can be launched from within fvwm and that has a window
734 can be used as a panel. A terminal window could be your panel, or some
735 application like xload or xosview or another fvwm module, including
736 FvwmButtons itself. All you need to know is how to start your applica‐
737 tion from fvwm.
738 The button that invokes the panel is as easily configured as any other
740 button. Essentially you need nothing more than the Panel option:
741 *FvwmButtons: (Panel my_first_panel \
744 "Module FvwmButtons -g -30000-30000 my_first_panel")
745 *FvwmButtons: (Panel my_second_panel \
746 "Exec exec xterm -g -30000-30000 -n my_second_panel")
747 This works like the Swallow option. The difference is that the appli‐
750 cation is not put into the button when it starts up but instead hidden
751 from view. When you press the button for the panel the window slides
752 into view. The '-g -30000-30000' option tells the application that it
753 should be created somewhere very far to the top and left of your visi‐
754 ble screen. Otherwise you would see it flashing for a moment when
755 FvwmButtons starts up. Some applications do not work well with this
756 kind of syntax so you may have to live with the short flashing of the
757 window. If you want to make a panel from another instance of FvwmBut‐
758 tons you can do so, but you must give it a different name
759 ('my_first_panel' in above example). If you run FvwmButtons under the
760 same name, new panels are created recursively until your system runs
761 out of resources and FvwmButtons crashes! To configure a second button
762 bar with a different name, simply put '*new_name' in place of familiar
763 with the Swallow option or if you want to learn more about how 'swal‐
764 lowing' panels 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 the panel window should
769 have no icon in case it is iconified.
770 Style name_of_panel_window NoTitle, Sitcky, NoIcon
773 You may want your panel to stay open only until you select something in
776 it. You can give FvwmButtons the -transientpanel option after the -g
777 option in the command. FvwmPager has a similar option '-transient'.
778 Last, but not least, you can now put an icon, a title or a small arrow
780 in the button so that you can see what it is for. A title or icon can
781 be specified as usual. To activate the arrow, just add the Padding
782 option to leave a few pixels between the arrow and the border of the
783 button. An optional direction in which the panel is opened can be
784 given too:
785 *FvwmButtons: (Padding 2, Panel(down, indicator) my_first_panel \
788 "Module FvwmButtons -g -30000-30000 -transientpanel my_first_panel")
789 There are several more options to configure how your panel works, for
792 example the speed and smoothness of the sliding animation. Please refer
793 to the description of the Panel option for further details.
794 CONVERTING OLD PANEL CONFIGURATIONS
797 This section describes how to convert a pretty old syntax used in 2.2.x
798 versions. You may skip it if your syntax is more recent.
799 With the old panel feature you first had one or more lines defining
801 panels in your main FvwmButtons configuration:
802 *FvwmButtons(Title WinOps,Panel WinOps)
805 *FvwmButtons(Title Tools ,Panel Tools)
806 After the last configuration line for the main panel the configuration
809 of the first panel followed, introduced with a line beginning with
810 *FvwmButtonsPanel:
811 *FvwmButtonsPanel WinOps
814 *FvwmButtonsBack bisque2
815 *FvwmButtonsPanel Tools
817 *FvwmButtonsBack bisque2
818 And perhaps you had style commands for you panels:
821 Style FvwmButtonsPanel Title, NoHandles, BorderWidth 0
824 Style FvwmButtonsPanel NoButton 2, NoButton 4, Sticky
825 The new configuration looks much the same, but now the configuration of
828 the main panel is independent of the configuration of the sub panels.
829 The lines invoking the panels use the same syntax as the Swallow
830 option, so you simply add the name of the window to use as a panel and
831 the command to execute instead of the panel name. Note that you give
832 the new instance of FvwmButtons a different name.
833 *FvwmButtons: (Title WinOps, Panel WinOps \
836 "Module FvwmButtons WinOps")
837 *FvwmButtons: (Title Tools , Panel Tools \
838 "Module FvwmButtons Tools")
839 If you used something like 'Panel-d' you now have to use button was
842 selected start FvwmButtons with the '-transientpanel' option:
843 *FvwmButtons: (Title Tools , Panel(down) Tools \
846 "Module FvwmButtons -transientpanel Tools")
847 The rest of the configuration is very easy to change. Delete the lines
850 '*FvwmButtonsPanel <name>' and add <name> to all of the following con‐
851 figuration lines for the panel instead. Use the same name in your Style
852 commands:
853 *WinOps: Back bisque2
856 *Tools: Back bisque2
857 Style "WinOps" Title, NoHandles, BorderWidth 0
858 Style "WinOps" NoButton 2, NoButton 4, Sticky
859 Style "Tools" Title, NoHandles, BorderWidth 0
860 Style "Tools" NoButton 2, NoButton 4, Sticky
861 That's it. The new panels are much more flexible. Please refer to
864 other parts of this documentation for details.
865 WHY WAS THE PANEL FEATURE REWRITTEN?
868 There are several reasons. The most important one is that the program
869 code implementing the panels was very disruptive and caused a lot of
870 problems. At the same time it made writing new features for FvwmBut‐
871 tons difficult at best. The second reason is that most users were sim‐
872 ply unable to make it work - it was way too complicated. Even I (the
873 author of the new code) had to spend several hours before I got it
874 working the first time. The third reason is that the new panels are
875 more versatile. Any application can be a panel in FvwmButtons, not
876 just other instances of FvwmButtons itself. So I sincerely hope that
877 nobody is angry about the change. Yes - you have to change your config‐
878 uration, but the new feature is much easier to configure, especially if
879 you already know how the Swallow option works.
880
883 FvwmButtons tries to arrange its buttons as best it can, by using
884 recursively, on each container including the buttonbox itself, the fol‐
885 lowing algorithm.
886 Getting the size right
888 First it calculates the number of button unit areas it will
889 need, by adding the width times the height in buttons of each
890 button. Containers are for the moment considered a normal but‐
891 ton. Then it considers the given rows and columns arguments. If
892 the number of rows is given, it will calculate how many columns
893 are needed, and stick to that, unless columns is larger, in
894 which case you will get some empty space at the bottom of the
895 buttonbox. If the number of columns is given, it calculates how
896 many rows it needs to fit all the buttons. If neither is given,
897 it assumes you want two rows, and finds the number of columns
898 from that. If the BoxSize option is set to smart at least the
899 height/width of the tallest/widest button is used while the
900 fixed value prevents the box from getting resized if both rows
901 and columns have been set to non-zero.
902 Shuffling buttons
904 Now it has a large enough area to place the buttons in, all that
905 is left is to place them right. There are two kinds of buttons:
906 fixed and floating buttons. A fixed button is forced to a spe‐
907 cific slot in the button box by a x/y geometry argument. All
908 other buttons are considered floating. Fixed buttons are placed
909 first. Should a fixed button overlap another one or shall be
910 place outside the buttons window, FvwmButtons exits with an
911 error message. After that the floating buttons are placed. The
912 algorithm tries to place the buttons in a left to right, top to
913 bottom western fashion. If a button fits at the suggested posi‐
914 tion it is placed there, if not the current slot stays empty and
915 the slot to the right will be considered. After the button has
916 been placed, the next button is tried to be placed in the next
917 slot and so on until all buttons are placed. Additional rows are
918 added below the bottom line of buttons until all buttons are
919 placed if necessary if the BoxSize option smart is used.
920 Containers
922 Containers are arranged by the same algorithm, in fact they are
923 shuffled recursively as the algorithm finds them.
924 Clarifying example
926 An example might be useful here: Suppose you have 6 buttons, all
927 unit sized except number two, which is 2x2. This makes for 5
928 times 1 plus 1 times 4 equals 9 unit buttons total area. Assume
929 you have requested 3 columns.
930 1) +---+---+---+ 2) +---+---+---+ 3) +---+---+---+
932 | 1 | | | 1 | | | 1 | |
933 +---+ + +---+ 2 + +---+ 2 +
934 | | | | | | 3 | |
935 + + + +---+---+ +---+---+---+
936 | | | | | | | |
937 +-----------+ +---+-------+ +---+---+---+
938 4) +---+---+---+ 5) +---+-------+ 6) +---+-------+
940 | 1 | | | 1 | | | 1 | |
941 +---+ 2 + +---+ 2 | +---+ 2 |
942 | 3 | | | 3 | | | 3 | |
943 +---+---+---+ +---+---+---+ +---+-------+
944 | 4 | | | 4 | 5 | | | 4 | 5 | 6 |
945 +---+---+---+ +---+---+---+ +---+---+---+
946 What size will the buttons be?
949 When FvwmButtons has read the icons and fonts that are required
950 by its configuration, it can find out which size is needed for
951 every non-swallowing button. The unit button size of a container
952 is set to be large enough to hold the largest button in it with‐
953 out squeezing it. Swallowed windows are simply expected to be
954 comfortable with the button size they get from this scheme. If a
955 particular configuration requires more space for a swallowed
956 window, it can be set in that button's configuration line using
957 the option "Size width height". This will tell FvwmButtons to
958 give this button at least width by height pixels inside the
959 relief and padding.
960
963 A running FvwmButtons instance may receive some dynamical actions.
964 This is achived using the fvwm command
965 SendToModule FvwmButtons-Alias <action> <params>
967 Supported actions:
969 ChangeButton button_id options
972 where button_id is the id of the button to change as specified
973 using the Id button option. It may also be a number, in this
974 case the button with the given number is assumed. And finally,
975 button_id may be in the form +x+y, where x and y are a column
976 number and a row number of the button to be changed. It is pos‐
977 sible to specify multiple option pairs (name with value) by
978 delimiting them using comma. Currently options include Title,
979 ActiveTitle, PressTitle, Icon, ActiveIcon and PressIcon.
980 ExpandButtonVars button_id command
983 where button_id has the same syntax as described in ChangeButton
984 above. Command may be any fvwm command with variables $var that
985 are expanded if supported.
986 PressButton button_id [mouse_button]
989 where button_id is the id of the button to press as specified
990 using the Id button option and mouse_button is the number of
991 mouse button used to click on the button e.g "1" for left mouse
992 button etc. Quotes around the number is not needed. If
993 mouse_button option is omitted "1" assumed. This command behaves
994 exactly like if the button in question was pressed using the
995 mouse.
996 Silent This prefix may be specified before other actions. It disables
999 all possible error and warning messages.
1000 Example:
1003 *FvwmButtons: (Id note1, Title "13:30 - Dinner", Icon clock1.xpm)
1005 SendToModule FvwmButtons Silent \
1007 ChangeButton note1 Icon clock2.xpm, Title "18:00 - Go Home"
1008
1012 The following are excerpts from a .fvwm2rc file which describe FvwmBut‐
1013 tons initialization commands:
1014 ##########################################################
1017 # Load any modules which should be started during fvwm
1018 # initialization
1019 # Make sure FvwmButtons is always there.
1021 AddToFunc StartFunction "I" Module FvwmButtons
1022 # Make it titlebar-less, sticky, and give it an icon
1024 Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky
1025 # Make the menu/panel look like CDE
1027 Style "WinOps" Title, NoHandles, BorderWidth 0
1028 Style "WinOps" NoButton 2, NoButton 4, Sticky
1029 Style "Tools" Title, NoHandles, BorderWidth 0
1030 Style "Tools" NoButton 2, NoButton 4, Sticky
1031 ##########################################################
1033 DestroyModuleConfig FvwmButtons: *
1034 *FvwmButtons: Fore Black
1035 *FvwmButtons: Back rgb:90/80/90
1036 *FvwmButtons: Geometry -135-5
1037 *FvwmButtons: Rows 1
1038 *FvwmButtons: BoxSize smart
1039 *FvwmButtons: Font -*-helvetica-medium-r-*-*-12-*
1040 *FvwmButtons: Padding 2 2
1041 *FvwmButtons: (Title WinOps, Panel WinOps \
1043 "Module FvwmButtons -transientpanel WinOps")
1044 *FvwmButtons: (Title Tools, Panel Tools \
1045 "Module FvwmButtons -transientpanel Tools")
1046 *FvwmButtons: (Title Resize, Icon resize.xpm, Action Resize)
1048 *FvwmButtons: (Title Move, Icon arrows2.xpm, Action Move )
1049 *FvwmButtons: (Title Lower, Icon Down, Action Lower )
1050 *FvwmButtons: (Title Raise, Icon Up, Action Raise )
1051 *FvwmButtons: (Title Kill, Icon bomb.xpm, Action Destroy)
1052 *FvwmButtons: (1x1,Container(Rows 3,Frame 1))
1054 *FvwmButtons: (Title Dopey ,Action \
1055 `Exec "big_win" xterm -T big_win -geometry 80x50 &`)
1056 *FvwmButtons: (Title Snoopy, Font fixed, Action \
1057 `Exec "small_win" xterm -T small_win &`)
1058 *FvwmButtons: (Title Smokin')
1059 *FvwmButtons: (End)
1060 *FvwmButtons: (Title Xcalc, Icon rcalc.xpm, \
1062 Action `Exec "Calculator" xcalc &`)
1063 *FvwmButtons: (Title XMag, Icon magnifying_glass2.xpm, \
1064 Action `Exec "xmag" xmag &`)
1065 *FvwmButtons: (Title Mail, Icon mail2.xpm, \
1066 Action `Exec "xmh" xmh &`)
1067 *FvwmButtons: (4x1, Swallow "FvwmPager" `FvwmPager 0 3` \
1068 Frame 3)
1069 *FvwmButtons: (Swallow(UseOld,NoKill) "xload15" `Exec xload \
1071 -title xload15 -nolabel -bg rgb:90/80/90 -update 15 \
1072 -geometry -3000-3000 &`)
1073 The last lines are a little tricky - one spawns an FvwmPager module,
1076 and captures it to display in a quadruple width button. is used, the
1077 Pager will be as big as possible within the button's relief.
1078 The final line is even more magic. Note the combination of UseOld and
1080 NoKill, which will try to swallow an existing window with the name
1081 "xload15" when starting up (if failing: starting one with the specified
1082 command), which is un-swallowed when ending FvwmButtons. The swallowed
1083 application is started with "-geometry -3000-3000" so that it will not
1084 be visible until its swallowed.
1085 The other panels are specified after the root panel:
1087 ########## PANEL WinOps
1090 DestroyModuleConfig WinOps: *
1091 *WinOps: Back bisque2
1092 *WinOps: Geometry -3-3
1093 *WinOps: Columns 1
1094 *WinOps: (Title Resize, Icon resize.xpm, Action Resize)
1096 *WinOps: (Title Move, Icon arrows2.xpm, Action Move )
1097 *WinOps: (Title Lower, Icon Down, Action Lower )
1098 *WinOps: (Title Raise, Icon Up, Action Raise )
1099 ########## PANEL Tools
1101 DestroyModuleConfig Tools: *
1102 *Tools: Back bisque2
1103 *Tools: Geometry -1-1
1104 *Tools: Columns 1
1105 *Tools: (Title Kill, Icon bomb.xpm, Action Destroy)
1107 The color specification rgb:90/80/90 is actually the most correct way
1110 of specifying independent colors in X, and should be used instead of
1111 the older #908090. If the latter specification is used in your configu‐
1112 ration file, you should be sure to escape the hash in any of the com‐
1113 mands which will be executed, or fvwm will consider the rest of the
1114 line a comment.
1115 Note that with the x/y geometry specs you can easily build button win‐
1117 dows with gaps. Here is another example. You can not accomplish this
1118 without geometry specs for the buttons:
1119 ##########################################################
1121 # Another example
1122 ##########################################################
1123 # Make it titlebar-less, sticky, and give it an icon
1125 Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky
1126 DestroyModuleConfig FvwmButtons: *
1128 *FvwmButtons: Font 5x7
1129 *FvwmButtons: Back rgb:90/80/90
1130 *FvwmButtons: Fore black
1131 *FvwmButtons: Frame 1
1132 # 9x11 pixels per button, 4x4 pixels for the frame
1133 *FvwmButtons: Geometry 580x59+0-0
1134 *FvwmButtons: Rows 5
1135 *FvwmButtons: Columns 64
1136 *FvwmButtons: BoxSize fixed
1137 *FvwmButtons: Padding 1 1
1138 # Pop up a module menu directly above the button.
1140 *FvwmButtons: (9x1+3+0, Padding 0, Title "Modules", \
1141 Action `Menu Modulepopup rectangle \
1142 $widthx$height+$lleft+$top o+50 -100m`)
1143 # first row of buttons from left to right:
1145 *FvwmButtons: (3x2+0+1, Icon my_lock.xpm, Action `Exec xlock`)
1146 *FvwmButtons: (3x2+3+1, Icon my_recapture.xpm, Action Recapture)
1147 *FvwmButtons: (3x2+6+1, Icon my_resize.xpm, Action Resize)
1148 *FvwmButtons: (3x2+9+1, Icon my_move.xpm, Action Move)
1149 *FvwmButtons: (3x2+12+1, Icon my_fvwmconsole.xpm, \
1150 Action 'Module FvwmConsole')
1151 # second row of buttons from left to right:
1153 *FvwmButtons: (3x2+0+3, Icon my_exit.xpm, Action QuitSave)
1154 *FvwmButtons: (3x2+3+3, Icon my_restart.xpm, Action Restart)
1155 *FvwmButtons: (3x2+6+3, Icon my_kill.xpm, Action Destroy)
1156 *FvwmButtons: (3x2+9+3, Icon my_shell.xpm, Action 'Exec rxvt')
1157 # big items
1159 *FvwmButtons: (10x5, Swallow (NoKill, NoCLose) \
1160 "FvwmPager" 'FvwmPager * * -geometry 40x40-1024-1024')
1161 *FvwmButtons: (6x5, Swallow "FvwmXclock" `Exec xclock \
1162 -name FvwmXclock -geometry 40x40+0-3000 -padding 1 \
1163 -analog -chime -bg rgb:90/80/90`)
1164 *FvwmButtons: (13x5, Swallow (NoClose) \
1165 "FvwmIconMan" 'Module FvwmIconMan')
1166 *FvwmButtons: (20x5, Padding 0, Swallow "xosview" \
1167 `Exec /usr/X11R6/bin/xosview -cpu -int -page -net \
1168 -geometry 100x50+0-3000 -font 5x7`)
1169
1173 The action part of the Swallow option must be quoted if it contains any
1174 whitespace character.
1175
1178 The FvwmButtons program, and the concept for interfacing this module to
1179 the Window Manager, are all original work by Robert Nation.
1180 Copyright 1993, Robert Nation. No guarantees or warranties or anything
1182 are provided or implied in any way whatsoever. Use this program at your
1183 own risk. Permission to use this program for any purpose is given, as
1184 long as the copyright is kept intact.
1185 Further modifications and patching by Jarl Totland, copyright 1996.
1187 The statement above still applies.
1188
1191 Robert Nation. Somewhat enhanced by Jarl Totland, Jui-Hsuan Joshua
1192 Feng, Scott Smedley.
11933rd Berkeley Distribution 09 May 2010 (2.5.30) FvwmButtons(1)