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 Colorset colorset
272 The given colorset can be applied to a container, a swal‐
273 lowed application and a simple button. To apply it to a
274 button or container, simply put the option in a line with
275 a button or container description. Drawing backgrounds
276 for individual buttons and containers with colorsets
277 requires a lot of communication with the X server. So if
278 you are not content with the drawing speed of dozens of
279 buttons with colorset backgrounds, do not use colorsets
280 here. Setting colorsets as the background of swallowed
281 applications does not have this restriction but depends
282 entirely on the swallowed application. It may work as
283 you wish, but since it involves fiddling with other
284 applications' windows there is no guarantee for anything.
285 I have tested three applications: xosview works nicely
286 with a colorset background, xload works only with a VGra‐
287 dient or solid background and an analog xclock leaves a
288 trail painted in the background color after its hands.
289 If the swallowed window is an fvwm module (see the
291 (No)FvwmModule option to Swallow), then the colorset is
292 not applied to the swallowed module. You should use the
293 colorset in the module configuration. If the swallowed
294 module has a transparent colorset background, then the
295 FvwmButtons background (and not the button colorset) is
296 seen by transparency of the background of the swallowed
297 module. Refer to the man page of the FvwmTheme module for
298 details about colorsets.
299 ActiveColorset colorset
302 Use colorset colorset for the background color/image
303 and/or title color of the button when the mouse is hover‐
304 ing above it.
305 PressColorset colorset
308 Use colorset colorset for the background color/image
309 and/or title color of the button when it is pressed.
310 Container [(options)]
313 Specifies that this button will contain a miniature but‐
314 tonbox, equivalent to swallowing another FvwmButtons mod‐
315 ule. The options are the same as can be given for a sin‐
316 gle button, but they affect all the contained buttons.
317 Options available for this use are Back, Font, Fore,
318 Frame and Padding. Flags for Title and Swallow options
319 can be set with Title(flags) and Swallow(flags). You
320 should also specify either "Columns width" or "Rows
321 height", or "Rows 2" will be assumed. For an example, see
322 the Sample configuration section.
323 The container button itself (separate from the contents)
325 can take format options like Frame and Padding, and com‐
326 mands can be bound to it. This means you can make a sen‐
327 sitive relief around a container, like
328 *FvwmButtons: (2x2, Frame 5, Padding 2 2, Action Beep,\
330 Container(Frame 1))
331 Typically you will want to at least give the container a
333 size setting widthxheight.
334 End Specifies that no more buttons are defined for the cur‐
337 rent container, and further buttons will be put in the
338 container's parent. This option should be given on a line
339 by itself, i.e
340 *FvwmButtons: (End)
342 Font fontname
346 Specifies that the font fontname is to be used for label‐
347 ing this button.
348 Fore color
351 Specifies the foregound color of the title and monochrome
352 icons in this button.
353 Frame width
356 The relief of the button will be width pixels wide. If
357 width is given as a negative number, the relief is
358 inverted. This makes the button sunken normally and
359 raised when activated.
360 Icon filename
363 The name of an image file, containing the icon to display
364 on the button. FvwmButtons searches through the path
365 specified in the fvwm ImagePath configuration item to
366 find the icon file.
367 ActiveIcon filename
370 The name of an image file, containing an alternative icon
371 to display on the button when the mouse is hovering above
372 the button. If no ActiveIcon is specified, the image
373 specified by Icon is displayed (if there is one).
374 PressIcon filename
377 The name of an image file, containing an alternative icon
378 to display on the button when the button is pressed. If
379 no PressIcon is specified, the image specified by Icon is
380 displayed (if there is one).
381 Id id The id to be used to identify this button. The first
384 character of the id should be alphabetic. See also the
385 "DYNAMICAL ACTIONS" section.
386 Left The contents of the button are aligned to the left. The
389 default is to center the contents on the button.
390 NoSize This option specifies that this button will not be con‐
393 sidered at all when making the initial calculations of
394 button sizes. Useful for the odd button that gets just a
395 couple of pixels too large to keep in line, and therefor
396 blows up your whole buttonbox. "NoSize" is equivalent to
397 "Size 0 0".
398 Padding width height
401 The amount of free space between the relief of the button
402 and its contents is normally 2 pixels to the sides and 4
403 pixels above and below, except for swallowed windows and
404 containers, which are by default not padded at all. This
405 option sets the horizontal padding to width and the ver‐
406 tical padding to height.
407 Panel [ (options) ] hangon command
410 Panels can be swallowed exactly like windows are swal‐
411 lowed by buttons with the Swallow command below, but they
412 are not displayed within the button. Instead they are
413 hidden until the user presses the panel's button. Then
414 the panel (the window of the swallowed application) opens
415 with a sliding animation. The options can be any of the
416 flags described for the Swallow command. In addition a
417 direction 'left', 'right', 'up' or 'down' can be used to
418 specify the sliding direction.
419 The steps animation-steps option defines the number of
421 animation steps.
422 The delay ms option sets the delay between the steps of
424 the animation in milliseconds. Use zero for no delay.
425 The maximum delay is 10 seconds (10000). It doesn't make
426 any sense to use the delay option unless you also use the
427 smooth option.
428 The smooth option causes the panel to redraw between
430 the steps of the animation. The sliding animation may be
431 smoother this way, it depends on the application, and
432 display speed. The application may appear to grow
433 instead of sliding out. The animation may be slower.
434 The Hints option causes FvwmButtons to use the applica‐
436 tions size hints to calculate the size of the animation
437 steps. Hints is the default. If the number of steps is
438 not what you want, try using NoHints.
439 The noborder option tells FvwmButtons to ignore the bor‐
441 ders of the window when calculating positions for the
442 animation (equivalent to set noplr and noptb in the posi‐
443 tion option).
444 With the indicator option set, FvwmButtons will draw a
446 small triangle in the button that will open a panel. The
447 triangle points in the direction where the panel will pop
448 up. The indicator keyword may be followed by a positive
449 integer that specifies the maximum width and height of
450 the indicator. Without this size FvwmButtons will make
451 the indicator fit the button. You will probably want to
452 use the Padding option to leave a few pixels between the
453 indicator and the frame of the button.
454 The position option allows to place the panel. The syntax
456 is:
457 position [context-window] [pos] [x y] [border-opts]
459 The argument context-window can be one of: Button, Module
461 or Root. The context-window is the window from which
462 panel percentage offsets are calculated. Button specifies
463 the panel's button, Module specifies FvwmButtons itself,
464 and Root specifies a virtual screen. The context-window
465 together with the sliding direction define a line segment
466 which is one of the borders of the context-window: the
467 top/bottom/left/right border for sliding
468 up/down/left/right.
469 The pos argument can be one of: center, left or right
471 (for sliding up or a down) or top or bottom (for sliding
472 left or right). It defines the vertical (sliding up and
473 down) or the horizontal (sliding left and right) position
474 of the Panel on the line segment. For example, for a
475 sliding up if you use a left pos, then the left borders
476 of the panel and of the context-window will be aligned.
477 The offset values x and y specify how far the panel is
479 moved from it's default position. By default, the numeric
480 value given is interpreted as a percentage of the context
481 window's width (height). A trailing "p" changes the
482 interpretation to mean "pixels". All offset calculations
483 are relative to the buttons location, even when using a
484 root context.
485 The border-opts are: mlr, mtb, noplr and noptb. They
487 define which border widths are taken in account. By
488 default, the borders of FvwmButtons are not taken in
489 account. mlr reverses this default for the left and the
490 right border and mtb reverses this default for the top
491 and the bottom border. Conversely, by default the borders
492 of the Panel are taken in account. noplr reverses this
493 default for the left and the right border and noptb
494 reverses this default for the top and the bottom border.
495 The defaults are sliding up with a delay of five mil‐
497 liseconds and twelve animation steps. To post the panel
498 without any animation, set the number of steps to zero.
499 The default position is 'Button center'.
500 Please refer to the CREATING PANELS section for further
502 information on panels.
503 Example:
505 # To include the panel in a button
507 *FvwmButtons: (Panel(down, delay 0, steps 16) \
508 SubPanel "Module FvwmButtons SubPanel")
509 # To define the panel as an instance of
511 # FvwmButtons with a different name:
512 *SubPanel: (Icon my_lock.xpm, Action Exec xlock)
513 *SubPanel: (Icon my_move.xpm, Action Move)
514 ...
515 Right The contents of the button are aligned to the right. The
519 default is to center the contents on the button.
520 Size width height
523 Specifies that the contents of this button require width
524 by height pixels, regardless of what size FvwmButtons
525 calculates from the icon and the title. A button bar with
526 only swallowed windows will not get very large without
527 this option specified, as FvwmButtons does not consider
528 sizes for swallowing buttons. Note that this option gives
529 the minimum space assured; other buttons might require
530 the buttonbox to use larger sizes.
531 Swallow [(flags)] hangon command
534 Causes FvwmButtons to execute command, and when a window
535 with a name, class or resource matching hangon appears,
536 it is captured and swallowed into this button. The
537 hangon string may contain wildcard characters ('*') that
538 match any substring. Swallow replaces the variables $fg
539 and $bg as described above for the Action option (but if
540 you use the UseOld and NoClose options the application is
541 not be restarted when FvwmButtons is restarted and thus
542 does not get the new colors - if you changed them). An
543 example:
544 *FvwmButtons: (Swallow XClock 'Exec xclock -geometry -3000-3000 &')
546 takes the first window whose name, class, or resource is
548 "XClock" and displays it in the button. If no matching
549 window is found, the "Exec" command creates one. The
550 argument "-geometry -3000-3000" is used so that the win‐
551 dow is first drawn out of sight before its swallowed into
552 FvwmButtons.
553 Modules can be swallowed by specifying the module instead
555 of 'Exec whatever', like:
556 *FvwmButtons: (Swallow "FvwmPager" "FvwmPager 0 0")
558 The flags that can be given to swallow are:
560 NoClose / Close - Specifies whether the swallowed program
562 in this button will be un-swallowed or closed when Fvwm‐
563 Buttons exits cleanly. "NoClose" can be combined with
564 "UseOld" to have windows survive a restart of the window
565 manager. The default setting is "Close".
566 NoHints / Hints - Specifies whether hints from the swal‐
568 lowed program in this button will be ignored or not, use‐
569 ful in forcing a window to resize itself to fit its but‐
570 ton. The default value is "Hints".
571 NoKill / Kill - Specifies whether the swallowed program
573 will be closed by killing it or by sending a message to
574 it. This can be useful in ending programs that doesn't
575 accept window manager protocol. The default value is
576 "NoKill". This has no effect if "NoClose" is specified.
577 NoRespawn / Respawn / SwallowNew - Specifies whether the
579 swallowed program is to be respawned (restarted) if it
580 dies. If "Respawn" is specified, the program is respawned
581 using the original command. Use this option with care,
582 the program might have a legitimate reason to die. If
583 "SwallowNew" is given, the program is not respawned, but
584 if a new window with the specified name appears, it is
585 swallowed.
586 NoOld / UseOld - Specifies whether the button will try to
588 swallow an existing window matching the hangon name
589 before spawning one itself with command. The hangon
590 string may contain wildcard characters ('*') that match
591 any substring.The default value is "NoOld". "UseOld" can
592 be combined with "NoKill" to have windows survive a
593 restart of the window manager. If you want FvwmButtons to
594 swallow an old window, and not spawn one itself if fail‐
595 ing, let the command be "Nop":
596 *FvwmButtons: (Swallow (UseOld) "Console" Nop)
598 If you want to be able to start it yourself, combine it
600 with an action:
601 *FvwmButtons: (Swallow (UseOld) "Console" Nop, \
603 Action `Exec "Console" console &`)
604 NoTitle / UseTitle - Specifies whether the title of the
606 button will be taken from the swallowed window's title or
607 not. If "UseTitle" is given, the title on the button
608 changes dynamically to reflect the window name. The
609 default is "NoTitle".
610 NoFvwmModule / FvwmModule - By default, FvwmButtons
612 treats the swallowed window as an fvwm module window if
613 the 4 first letters of the command is "Fvwm" or the 6
614 first letters of the command is "Module". NoFvwmModule
615 and FvwmModule override this logic.
616 Title [(options)] name
619 Specifies the title to be written on the button. White‐
620 space can be included in the title by quoting it. If a
621 title at any time is too long for its buttons, characters
622 are chopped of one at a time until it fits. If justify is
623 "Right", the head is removed, otherwise its tail is
624 removed. These options can be given to Title:
625 Center - The title is centered horizontally. This is the
627 default.
628 Left - The title is justified to the left side.
630 Right - The title is justified to the right side.
632 Side - Causes the title to appear on the right hand side
634 of any icon or swallowed window, instead of below which
635 is the default. If you use small icons, and combine this
636 with the "Left" or "Right" option, you can get a look
637 similar to fvwm's menus.
638 ActiveTitle name
641 Specifies the title to be written on the button when the
642 mouse is hovering above the button. If no ActiveTitle is
643 specified, the text specified by Title is displayed (if
644 there is any).
645 PressTitle name
648 Specifies the title to be written on the button when the
649 button is pressed. If no PressTitle is specified, the
650 text specified by Title is displayed (if there is any).
651 Legacy fields [title icon command]
654 These fields are kept for compatibility with previous
655 versions of FvwmButtons, and their use is discouraged.
656 The title field is similar to the option Title name. If
657 the title field is "-", no title is displayed. The icon
658 field is similar to the option Icon filename. If the icon
659 field is "-" no icon is displayed. The command field is
660 similar to the option Action command or alternatively
661 Swallow "hangon" command.
662 The command
664 Any fvwm command is recognized by FvwmButtons. See
665 fvwm(1) for more information.
666 The Exec command has a small extension when used in
668 Actions, its syntax is:
669 Exec ["hangon"] command
671 Example:
673 *FvwmButtons: (Action Exec "xload" xload)
675 The hangon string must be enclosed in double quotes.
677 When FvwmButtons finds such an Exec command, the button
678 remains pushed in until a window whose name, class or
679 resource matches the quoted portion of the command is
680 encountered. This is intended to provide visual feedback
681 to the user that the action he has requested will be per‐
682 formed. The hangon string may contain wildcard charac‐
683 ters ('*') that match any substring. If the quoted por‐
684 tion contains no characters, then the button will pop out
685 immediately. Note that users can continue pressing the
686 button, and re-executing the command, even when it looks
687 pressed in.
688 Quoting
691 Any string which contains whitespace must be quoted. Con‐
692 trary to earlier versions commands no longer need to be
693 quoted. In this case any quoting character will be passed
694 on to the application untouched. Only commas ',' and
695 closing parentheses ')' have to be quoted inside a com‐
696 mand. Quoting can be done with any of the three quotation
697 characters; single quote:
698 'This is a "quote"',
700 double quote:
702 "It's another `quote'",
704 and back quote:
706 `This is a strange quote`.
708 The back quoting is unusual but used on purpose, if you
710 use a preprocessor like FvwmCpp and want it to get into
711 your commands, like this:
712 #define BG gray60
714 *FvwmButtons: (Swallow "xload" `Exec xload -bg BG &`)
715 Any single character can be quoted with a preceding back‐
717 slash '\'.
718
720 Former versions of FvwmButtons (fvwm 2.0.46 to 2.3.6) had a different
721 way of handling panels. You can not use your old panel configuration
722 with the new panel feature. Read "CONVERTING OLD PANEL CONFIGURATIONS"
723 for more information.
724 HOW TO CREATE NEW PANELS
728 Any program that can be launched from within fvwm and that has a window
729 can be used as a panel. A terminal window could be your panel, or some
730 application like xload or xosview or another fvwm module, including
731 FvwmButtons itself. All you need to know is how to start your applica‐
732 tion from fvwm.
733 The button that invokes the panel is as easily configured as any other
735 button. Essentially you need nothing more than the Panel option:
736 *FvwmButtons: (Panel my_first_panel \
739 "Module FvwmButtons -g -30000-30000 my_first_panel")
740 *FvwmButtons: (Panel my_second_panel \
741 "Exec exec xterm -g -30000-30000 -n my_second_panel")
742 This works like the Swallow option. The difference is that the appli‐
745 cation is not put into the button when it starts up but instead hidden
746 from view. When you press the button for the panel the window slides
747 into view. The '-g -30000-30000' option tells the application that it
748 should be created somewhere very far to the top and left of your visi‐
749 ble screen. Otherwise you would see it flashing for a moment when
750 FvwmButtons starts up. Some applications do not work well with this
751 kind of syntax so you may have to live with the short flashing of the
752 window. If you want to make a panel from another instance of FvwmBut‐
753 tons you can do so, but you must give it a different name
754 ('my_first_panel' in above example). If you run FvwmButtons under the
755 same name, new panels are created recursively until your system runs
756 out of resources and FvwmButtons crashes! To configure a second button
757 bar with a different name, simply put '*new_name' in place of familiar
758 with the Swallow option or if you want to learn more about how 'swal‐
759 lowing' panels works, refer to the description of the Swallow option.
760 Now that your panel basically works you will want to tune it a bit.
762 You may not want a window title on the panel. To disable the title use
763 the fvwm Style command. If your button bar is the panel window should
764 have no icon in case it is iconified.
765 Style name_of_panel_window NoTitle, Sitcky, NoIcon
768 You may want your panel to stay open only until you select something in
771 it. You can give FvwmButtons the -transientpanel option after the -g
772 option in the command. FvwmPager has a similar option '-transient'.
773 Last, but not least, you can now put an icon, a title or a small arrow
775 in the button so that you can see what it is for. A title or icon can
776 be specified as usual. To activate the arrow, just add the Padding
777 option to leave a few pixels between the arrow and the border of the
778 button. An optional direction in which the panel is opened can be
779 given too:
780 *FvwmButtons: (Padding 2, Panel(down, indicator) my_first_panel \
783 "Module FvwmButtons -g -30000-30000 -transientpanel my_first_panel")
784 There are several more options to configure how your panel works, for
787 example the speed and smoothness of the sliding animation. Please refer
788 to the description of the Panel option for further details.
789 CONVERTING OLD PANEL CONFIGURATIONS
792 This section describes how to convert a pretty old syntax used in 2.2.x
793 versions. You may skip it if your syntax is more recent.
794 With the old panel feature you first had one or more lines defining
796 panels in your main FvwmButtons configuration:
797 *FvwmButtons(Title WinOps,Panel WinOps)
800 *FvwmButtons(Title Tools ,Panel Tools)
801 After the last configuration line for the main panel the configuration
804 of the first panel followed, introduced with a line beginning with
805 *FvwmButtonsPanel:
806 *FvwmButtonsPanel WinOps
809 *FvwmButtonsBack bisque2
810 *FvwmButtonsPanel Tools
812 *FvwmButtonsBack bisque2
813 And perhaps you had style commands for you panels:
816 Style FvwmButtonsPanel Title, NoHandles, BorderWidth 0
819 Style FvwmButtonsPanel NoButton 2, NoButton 4, Sticky
820 The new configuration looks much the same, but now the configuration of
823 the main panel is independent of the configuration of the sub panels.
824 The lines invoking the panels use the same syntax as the Swallow
825 option, so you simply add the name of the window to use as a panel and
826 the command to execute instead of the panel name. Note that you give
827 the new instance of FvwmButtons a different name.
828 *FvwmButtons: (Title WinOps, Panel WinOps \
831 "Module FvwmButtons WinOps")
832 *FvwmButtons: (Title Tools , Panel Tools \
833 "Module FvwmButtons Tools")
834 If you used something like 'Panel-d' you now have to use button was
837 selected start FvwmButtons with the '-transientpanel' option:
838 *FvwmButtons: (Title Tools , Panel(down) Tools \
841 "Module FvwmButtons -transientpanel Tools")
842 The rest of the configuration is very easy to change. Delete the lines
845 '*FvwmButtonsPanel <name>' and add <name> to all of the following con‐
846 figuration lines for the panel instead. Use the same name in your Style
847 commands:
848 *WinOps: Back bisque2
851 *Tools: Back bisque2
852 Style "WinOps" Title, NoHandles, BorderWidth 0
853 Style "WinOps" NoButton 2, NoButton 4, Sticky
854 Style "Tools" Title, NoHandles, BorderWidth 0
855 Style "Tools" NoButton 2, NoButton 4, Sticky
856 That's it. The new panels are much more flexible. Please refer to
859 other parts of this documentation for details.
860 WHY WAS THE PANEL FEATURE REWRITTEN?
863 There are several reasons. The most important one is that the program
864 code implementing the panels was very disruptive and caused a lot of
865 problems. At the same time it made writing new features for FvwmBut‐
866 tons difficult at best. The second reason is that most users were sim‐
867 ply unable to make it work - it was way too complicated. Even I (the
868 author of the new code) had to spend several hours before I got it
869 working the first time. The third reason is that the new panels are
870 more versatile. Any application can be a panel in FvwmButtons, not
871 just other instances of FvwmButtons itself. So I sincerely hope that
872 nobody is angry about the change. Yes - you have to change your config‐
873 uration, but the new feature is much easier to configure, especially if
874 you already know how the Swallow option works.
875
878 FvwmButtons tries to arrange its buttons as best it can, by using
879 recursively, on each container including the buttonbox itself, the fol‐
880 lowing algorithm.
881 Getting the size right
883 First it calculates the number of button unit areas it will
884 need, by adding the width times the height in buttons of each
885 button. Containers are for the moment considered a normal but‐
886 ton. Then it considers the given rows and columns arguments. If
887 the number of rows is given, it will calculate how many columns
888 are needed, and stick to that, unless columns is larger, in
889 which case you will get some empty space at the bottom of the
890 buttonbox. If the number of columns is given, it calculates how
891 many rows it needs to fit all the buttons. If neither is given,
892 it assumes you want two rows, and finds the number of columns
893 from that. If the BoxSize option is set to smart at least the
894 height/width of the tallest/widest button is used while the
895 fixed value prevents the box from getting resized if both rows
896 and columns have been set to non-zero.
897 Shuffling buttons
899 Now it has a large enough area to place the buttons in, all that
900 is left is to place them right. There are two kinds of buttons:
901 fixed and floating buttons. A fixed button is forced to a spe‐
902 cific slot in the button box by a x/y geometry argument. All
903 other buttons are considered floating. Fixed buttons are placed
904 first. Should a fixed button overlap another one or shall be
905 place outside the buttons window, FvwmButtons exits with an
906 error message. After that the floating buttons are placed. The
907 algorithm tries to place the buttons in a left to right, top to
908 bottom western fashion. If a button fits at the suggested posi‐
909 tion it is placed there, if not the current slot stays empty and
910 the slot to the right will be considered. After the button has
911 been placed, the next button is tried to be placed in the next
912 slot and so on until all buttons are placed. Additional rows are
913 added below the bottom line of buttons until all buttons are
914 placed if necessary if the BoxSize option smart is used.
915 Containers
917 Containers are arranged by the same algorithm, in fact they are
918 shuffled recursively as the algorithm finds them.
919 Clarifying example
921 An example might be useful here: Suppose you have 6 buttons, all
922 unit sized except number two, which is 2x2. This makes for 5
923 times 1 plus 1 times 4 equals 9 unit buttons total area. Assume
924 you have requested 3 columns.
925 1) +---+---+---+ 2) +---+---+---+ 3) +---+---+---+
927 | 1 | | | 1 | | | 1 | |
928 +---+ + +---+ 2 + +---+ 2 +
929 | | | | | | 3 | |
930 + + + +---+---+ +---+---+---+
931 | | | | | | | |
932 +-----------+ +---+-------+ +---+---+---+
933 4) +---+---+---+ 5) +---+-------+ 6) +---+-------+
935 | 1 | | | 1 | | | 1 | |
936 +---+ 2 + +---+ 2 | +---+ 2 |
937 | 3 | | | 3 | | | 3 | |
938 +---+---+---+ +---+---+---+ +---+-------+
939 | 4 | | | 4 | 5 | | | 4 | 5 | 6 |
940 +---+---+---+ +---+---+---+ +---+---+---+
941 What size will the buttons be?
944 When FvwmButtons has read the icons and fonts that are required
945 by its configuration, it can find out which size is needed for
946 every non-swallowing button. The unit button size of a container
947 is set to be large enough to hold the largest button in it with‐
948 out squeezing it. Swallowed windows are simply expected to be
949 comfortable with the button size they get from this scheme. If a
950 particular configuration requires more space for a swallowed
951 window, it can be set in that button's configuration line using
952 the option "Size width height". This will tell FvwmButtons to
953 give this button at least width by height pixels inside the
954 relief and padding.
955
958 A running FvwmButtons instance may receive some dynamical actions.
959 This is achived using the fvwm command
960 SendToModule FvwmButtons-Alias <action> <params>
962 Supported actions:
964 ChangeButton button_id options
967 where button_id is the id of the button to change as specified
968 using the Id button option. It may also be a number, in this
969 case the button with the given number is assumed. And finally,
970 button_id may be in the form +x+y, where x and y are a column
971 number and a row number of the button to be changed. It is pos‐
972 sible to specify multiple option pairs (name with value) by
973 delimiting them using comma. Currently options include Title,
974 ActiveTitle, PressTitle, Icon, ActiveIcon and PressIcon.
975 ExpandButtonVars button_id command
978 where button_id has the same syntax as described in ChangeButton
979 above. Command may be any fvwm command with variables $var that
980 are expanded if supported.
981 PressButton button_id [mouse_button]
984 where button_id is the id of the button to press as specified
985 using the Id button option and mouse_button is the number of
986 mouse button used to click on the button e.g "1" for left mouse
987 button etc. Quotes around the number is not needed. If
988 mouse_button option is omitted "1" assumed. This command behaves
989 exactly like if the button in question was pressed using the
990 mouse.
991 Silent This prefix may be specified before other actions. It disables
994 all possible error and warning messages.
995 Example:
998 *FvwmButtons: (Id note1, Title "13:30 - Dinner", Icon clock1.xpm)
1000 SendToModule FvwmButtons Silent \
1002 ChangeButton note1 Icon clock2.xpm, Title "18:00 - Go Home"
1003
1007 The following are excerpts from a .fvwm2rc file which describe FvwmBut‐
1008 tons initialization commands:
1009 ##########################################################
1012 # Load any modules which should be started during fvwm
1013 # initialization
1014 # Make sure FvwmButtons is always there.
1016 AddToFunc StartFunction "I" Module FvwmButtons
1017 # Make it titlebar-less, sticky, and give it an icon
1019 Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky
1020 # Make the menu/panel look like CDE
1022 Style "WinOps" Title, NoHandles, BorderWidth 0
1023 Style "WinOps" NoButton 2, NoButton 4, Sticky
1024 Style "Tools" Title, NoHandles, BorderWidth 0
1025 Style "Tools" NoButton 2, NoButton 4, Sticky
1026 ##########################################################
1028 DestroyModuleConfig FvwmButtons: *
1029 *FvwmButtons: Fore Black
1030 *FvwmButtons: Back rgb:90/80/90
1031 *FvwmButtons: Geometry -135-5
1032 *FvwmButtons: Rows 1
1033 *FvwmButtons: BoxSize smart
1034 *FvwmButtons: Font -*-helvetica-medium-r-*-*-12-*
1035 *FvwmButtons: Padding 2 2
1036 *FvwmButtons: (Title WinOps, Panel WinOps \
1038 "Module FvwmButtons -transientpanel WinOps")
1039 *FvwmButtons: (Title Tools, Panel Tools \
1040 "Module FvwmButtons -transientpanel Tools")
1041 *FvwmButtons: (Title Resize, Icon resize.xpm, Action Resize)
1043 *FvwmButtons: (Title Move, Icon arrows2.xpm, Action Move )
1044 *FvwmButtons: (Title Lower, Icon Down, Action Lower )
1045 *FvwmButtons: (Title Raise, Icon Up, Action Raise )
1046 *FvwmButtons: (Title Kill, Icon bomb.xpm, Action Destroy)
1047 *FvwmButtons: (1x1,Container(Rows 3,Frame 1))
1049 *FvwmButtons: (Title Dopey ,Action \
1050 `Exec "big_win" xterm -T big_win -geometry 80x50 &`)
1051 *FvwmButtons: (Title Snoopy, Font fixed, Action \
1052 `Exec "small_win" xterm -T small_win &`)
1053 *FvwmButtons: (Title Smokin')
1054 *FvwmButtons: (End)
1055 *FvwmButtons: (Title Xcalc, Icon rcalc.xpm, \
1057 Action `Exec "Calculator" xcalc &`)
1058 *FvwmButtons: (Title XMag, Icon magnifying_glass2.xpm, \
1059 Action `Exec "xmag" xmag &`)
1060 *FvwmButtons: (Title Mail, Icon mail2.xpm, \
1061 Action `Exec "xmh" xmh &`)
1062 *FvwmButtons: (4x1, Swallow "FvwmPager" `FvwmPager 0 3` \
1063 Frame 3)
1064 *FvwmButtons: (Swallow(UseOld,NoKill) "xload15" `Exec xload \
1066 -title xload15 -nolabel -bg rgb:90/80/90 -update 15 \
1067 -geometry -3000-3000 &`)
1068 The last lines are a little tricky - one spawns an FvwmPager module,
1071 and captures it to display in a quadruple width button. is used, the
1072 Pager will be as big as possible within the button's relief.
1073 The final line is even more magic. Note the combination of UseOld and
1075 NoKill, which will try to swallow an existing window with the name
1076 "xload15" when starting up (if failing: starting one with the specified
1077 command), which is un-swallowed when ending FvwmButtons. The swallowed
1078 application is started with "-geometry -3000-3000" so that it will not
1079 be visible until its swallowed.
1080 The other panels are specified after the root panel:
1082 ########## PANEL WinOps
1085 DestroyModuleConfig WinOps: *
1086 *WinOps: Back bisque2
1087 *WinOps: Geometry -3-3
1088 *WinOps: Columns 1
1089 *WinOps: (Title Resize, Icon resize.xpm, Action Resize)
1091 *WinOps: (Title Move, Icon arrows2.xpm, Action Move )
1092 *WinOps: (Title Lower, Icon Down, Action Lower )
1093 *WinOps: (Title Raise, Icon Up, Action Raise )
1094 ########## PANEL Tools
1096 DestroyModuleConfig Tools: *
1097 *Tools: Back bisque2
1098 *Tools: Geometry -1-1
1099 *Tools: Columns 1
1100 *Tools: (Title Kill, Icon bomb.xpm, Action Destroy)
1102 The color specification rgb:90/80/90 is actually the most correct way
1105 of specifying independent colors in X, and should be used instead of
1106 the older #908090. If the latter specification is used in your configu‐
1107 ration file, you should be sure to escape the hash in any of the com‐
1108 mands which will be executed, or fvwm will consider the rest of the
1109 line a comment.
1110 Note that with the x/y geometry specs you can easily build button win‐
1112 dows with gaps. Here is another example. You can not accomplish this
1113 without geometry specs for the buttons:
1114 ##########################################################
1116 # Another example
1117 ##########################################################
1118 # Make it titlebar-less, sticky, and give it an icon
1120 Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky
1121 DestroyModuleConfig FvwmButtons: *
1123 *FvwmButtons: Font 5x7
1124 *FvwmButtons: Back rgb:90/80/90
1125 *FvwmButtons: Fore black
1126 *FvwmButtons: Frame 1
1127 # 9x11 pixels per button, 4x4 pixels for the frame
1128 *FvwmButtons: Geometry 580x59+0-0
1129 *FvwmButtons: Rows 5
1130 *FvwmButtons: Columns 64
1131 *FvwmButtons: BoxSize fixed
1132 *FvwmButtons: Padding 1 1
1133 # Pop up a module menu directly above the button.
1135 *FvwmButtons: (9x1+3+0, Padding 0, Title "Modules", \
1136 Action `Menu Modulepopup rectangle \
1137 $widthx$height+$lleft+$top o+50 -100m`)
1138 # first row of buttons from left to right:
1140 *FvwmButtons: (3x2+0+1, Icon my_lock.xpm, Action `Exec xlock`)
1141 *FvwmButtons: (3x2+3+1, Icon my_recapture.xpm, Action Recapture)
1142 *FvwmButtons: (3x2+6+1, Icon my_resize.xpm, Action Resize)
1143 *FvwmButtons: (3x2+9+1, Icon my_move.xpm, Action Move)
1144 *FvwmButtons: (3x2+12+1, Icon my_fvwmconsole.xpm, \
1145 Action 'Module FvwmConsole')
1146 # second row of buttons from left to right:
1148 *FvwmButtons: (3x2+0+3, Icon my_exit.xpm, Action QuitSave)
1149 *FvwmButtons: (3x2+3+3, Icon my_restart.xpm, Action Restart)
1150 *FvwmButtons: (3x2+6+3, Icon my_kill.xpm, Action Destroy)
1151 *FvwmButtons: (3x2+9+3, Icon my_shell.xpm, Action 'Exec rxvt')
1152 # big items
1154 *FvwmButtons: (10x5, Swallow (NoKill, NoCLose) \
1155 "FvwmPager" 'FvwmPager * * -geometry 40x40-1024-1024')
1156 *FvwmButtons: (6x5, Swallow "FvwmXclock" `Exec xclock \
1157 -name FvwmXclock -geometry 40x40+0-3000 -padding 1 \
1158 -analog -chime -bg rgb:90/80/90`)
1159 *FvwmButtons: (13x5, Swallow (NoClose) \
1160 "FvwmIconMan" 'Module FvwmIconMan')
1161 *FvwmButtons: (20x5, Padding 0, Swallow "xosview" \
1162 `Exec /usr/X11R6/bin/xosview -cpu -int -page -net \
1163 -geometry 100x50+0-3000 -font 5x7`)
1164
1168 The action part of the Swallow option must be quoted if it contains any
1169 whitespace character.
1170
1173 The FvwmButtons program, and the concept for interfacing this module to
1174 the Window Manager, are all original work by Robert Nation.
1175 Copyright 1993, Robert Nation. No guarantees or warranties or anything
1177 are provided or implied in any way whatsoever. Use this program at your
1178 own risk. Permission to use this program for any purpose is given, as
1179 long as the copyright is kept intact.
1180 Further modifications and patching by Jarl Totland, copyright 1996.
1182 The statement above still applies.
1183
1186 Robert Nation. Somewhat enhanced by Jarl Totland, Jui-Hsuan Joshua
1187 Feng, Scott Smedley.
11883rd Berkeley Distribution 24 November 2007 (2.5.24) FvwmButtons(1)