1FvwmButtons(1)                   Fvwm Modules                   FvwmButtons(1)
2
3
4

NAME

6       FvwmButtons - the fvwm buttonbox module
7

SYNOPSIS

9       Module FvwmButtons [-g geometry] [-transient | -transientpanel] [name[configfile]]
10
11       FvwmButtons  can  only  be invoked by fvwm.  Command line invocation of
12       the FvwmButtons module will not work.
13
14

DESCRIPTION

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
21       The  buttonbox  can  be  of any configuration or geometry, and can have
22       monochrome or color icons to represent the actions which would  be  in‐
23       voked.  Even other applications can be 'swallowed' by the button bar.
24
25       Panels that are opened on a button press are available too.  See CREAT‐
26       ING PANELS section for details.
27
28

OPTIONS

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
34       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
43       The  -transientpanel option does roughly the same as the -transient op‐
44       tion, but instead of closing the whole button bar, the window is merely
45       hidden.  This is very useful if the button bar is started as a subpanel
46       of another button bar because it avoids that it must be  started  again
47       when something is selected.
48
49

INVOCATION

51       FvwmButtons  is  spawned  by  fvwm, so command line invocation will not
52       work.
53
54       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
60       When invoked with the OptionalName argument, the OptionalName  is  used
61       to find configuration commands.  For example:
62
63       AddToFunc StartFunction Module FvwmButtons MyButtonBox
64
65       FvwmButtons  will then use only the lines starting with "*MyButtonBox",
66       instead of the default "*FvwmButtons".
67
68

CONFIGURATION OPTIONS

70       The following commands are understood by FvwmButtons:
71
72
73       *FvwmButtons: Back color
74              Specifies the background color for the buttons. The  relief  and
75              shadow color are calculated from the background color.
76
77
78       *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
83              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
88              If smart is used FvwmButtons enlarges the  box  so  all  buttons
89              have  a  chance to fit. The number of columns is increased to at
90              least the width of the widest button and new rows are added  un‐
91              til all buttons are placed. For the best tolerance of configura‐
92              tion errors use the smart option.
93
94              dumb is neither fixed nor smart.  This is the default.
95
96
97       *FvwmButtons: Colorset colorset
98              Tells the module to use colorset colorset for the  window  back‐
99              ground.  Refer to the fvwm man page for details about colorsets.
100
101
102       *FvwmButtons: ActiveColorset colorset
103              Tells  the  module  to  use colorset colorset for the background
104              color/image and/or title color of a button  when  the  mouse  is
105              hovering above a button.
106
107
108       *FvwmButtons: PressColorset colorset
109              Tells  the  module  to  use colorset colorset for the background
110              color/image and/or title color of a button when it is pressed.
111
112
113       *FvwmButtons: Columns columns
114              Specifies the number of columns of buttons to be created. If un‐
115              specified, the number of columns is set to the number of buttons
116              requested, divided by the number of rows. If both the  rows  and
117              columns  are  specified,  but the number of buttons is more than
118              the rows and columns allow for, the columns specification is ig‐
119              nored unless the BoxSize option is fixed.
120
121
122       *FvwmButtons: File filename
123              Specifies that the configuration for this button is found in the
124              file filename. Filename can be a full pathname, or is assumed to
125              be in fvwm's startup directory. The configuration file is in the
126              same format as fvwm's configuration file, but each line is  read
127              as if prefixed by "*FvwmButtons". Comments are given by starting
128              a line with "#". Line continuation is done by ending a line with
129              a "\".
130
131
132       *FvwmButtons: Font font
133              Specifies the font to be used for labeling the buttons, or None.
134
135
136       *FvwmButtons: Fore color
137              Specifies  the  color  used for button label text and monochrome
138              icons.
139
140
141       *FvwmButtons: Frame width
142              Specifies the width of the relief around each button. If this is
143              a negative number, the relief is inverted. This makes the button
144              sunken normally and raised when activated.
145
146
147       *FvwmButtons: Geometry geometry
148              Specifies the FvwmButtons window location and size.  The  geome‐
149              try is a standard X11 window geometry specification.
150
151
152       *FvwmButtons: ButtonGeometry geometry
153              This  option works like the Geometry option except that the size
154              is the size of a single button.  The size of the whole  FvwmBut‐
155              tons window is calculated by multiplying the button dimension by
156              the number of rows and columns.
157
158
159       *FvwmButtons: Padding width height
160              This option specifies the default horizontal padding to be width
161              pixels, and the vertical padding to be height pixels. The amount
162              of free space between the relief of the button and its  contents
163              is  normally 2 pixels on the sides and 4 pixels above and below,
164              except for swallowed  windows  and  containers,  which  are  not
165              padded at all, unless this option is used.
166
167
168       *FvwmButtons: Pixmap pixmapfile
169              Specifies  a  background pixmap to use.  Specify "none" (without
170              the double quotes) for a transparent background.
171
172
173       *FvwmButtons: Rows rows
174              Specifies the number of rows of buttons to be created.  The  de‐
175              fault is 2 rows.
176
177
178       *FvwmButtons: (options) [title icon command]
179              Specifies the contents of a button in the buttonbox. The follow‐
180              ing options, separated by commas or whitespace, can be  given  a
181              button:
182
183              geometry
184                     Specifies  the size and position of the button within the
185                     FvwmButtons window or container. The geometry is a  stan‐
186                     dard  X11  window  geometry  specification. The button is
187                     width times the normal button width and height times  the
188                     normal  button  height.  If values for x and y are given,
189                     the button is placed x (y) button  units  from  the  left
190                     (top)  of  the  container  if x (y) is positive and x (y)
191                     units from the right (bottom) if x (y) is negative.  But‐
192                     tons  with position arguments (x and y) are placed before
193                     those without them. If two or more buttons are forced  to
194                     overlap by this, FvwmButtons exits with an error message.
195
196
197              Action [(options)] command
198                     Specifies  an fvwm command to be executed when the button
199                     is activated by pressing return or a  mouse  button.  The
200                     command  needs  to  be quoted if it contains a comma or a
201                     closing parenthesis.
202
203                     The current options of the Action are: Mouse n - this ac‐
204                     tion  is only executed for mouse button n. One action can
205                     be defined for each mouse button, in addition to the gen‐
206                     eral action.
207
208                     In  the  command part, you can use a number of predefined
209                     variables: $left, $right, $top and  $bottom  are  substi‐
210                     tuted  by  the left, right, top and bottom coordinates of
211                     the button pressed. $-left, $-right, $-top  and  $-bottom
212                     are  substituted likewise, but the coordinates are calcu‐
213                     lated from the bottom or the right edge of the screen in‐
214                     stead  (for a button that is 5 pixels away from the right
215                     screen border, $-right will be 5). $width and $height are
216                     replaced  by the width or height of the button. The vari‐
217                     ables $fg and $bg are replaced with the name of the fore‐
218                     ground  or background color set with the Back or Fore op‐
219                     tion (see below). All this  is  done  regardless  of  any
220                     quoting  characters.  To get a literal '$' use the string
221                     '$$'.
222
223                     Example:
224
225
226                       *FvwmButtons: (Title xload, Action (Mouse 1) \
227                         `Exec exec xload -fg $fg -bg $bg -geometry -3000-3000`)
228
229
230                     Note: With fvwm versions prior to  2.5.0,  actions  could
231                     not be assigned to a button that swallowed an application
232                     window (see Swallow option).  Such  actions  worked  only
233                     when  the  border around the button was clicked.  This is
234                     now possible, but to get back the old behavior,  the  Ac‐
235                     tionIgnoresClientWindow can be used on the button:
236
237
238                       *FvwmButtons: (Action beep, ActionIgnoresClientWindow, \
239                          Swallow xeyes "Exec exec xeyes")
240
241
242                     In  this  example,  the  action is only executed when you
243                     click on the border of the button or the transparent part
244                     of the xeyes window, but not on the xeyes window itself.
245
246
247              ActionIgnoresClientWindow
248                     See the note in the description of Action above.
249
250
251              ActionOnPress
252                     Usually  the action is executed on the button release ex‐
253                     cept for the Popup action.  This option changes this  be‐
254                     havior, the action is executed on the button press.  This
255                     may be good, for example, with Menu or SendToModule  that
256                     generates popups, or when Frame is 0 and the button would
257                     look unresponsive otherwise.
258
259
260              Back color
261                     Specifies the background color to be  used  drawing  this
262                     box.  A  relief  color  and a shadow color are calculated
263                     from this.
264
265
266              Center The contents of the button is  centered  on  the  button.
267                     This is the default but may be changed by Left or Right.
268
269
270              Top    The  contents  of the button is vertically aligned at the
271                     top of the button. The default is  to  vertically  center
272                     it.
273
274
275              Colorset colorset
276                     The given colorset can be applied to a container, a swal‐
277                     lowed application and a simple button.  To apply it to  a
278                     button or container, simply put the option in a line with
279                     a button or container description.   Drawing  backgrounds
280                     for  individual buttons and containers with colorsets re‐
281                     quires a lot of communication with the X server.   So  if
282                     you  are  not content with the drawing speed of dozens of
283                     buttons with colorset backgrounds, do not  use  colorsets
284                     here.   Setting  colorsets as the background of swallowed
285                     applications does not have this restriction  but  depends
286                     entirely  on  the  swallowed application.  It may work as
287                     you wish, but since it involves fiddling with  other  ap‐
288                     plications'  windows  there is no guarantee for anything.
289                     I have tested three applications:  xosview  works  nicely
290                     with a colorset background, xload works only with a VGra‐
291                     dient or solid background and an analog xclock  leaves  a
292                     trail painted in the background color after its hands.
293
294                     If  the  swallowed  window  is  an  fvwm  module (see the
295                     (No)FvwmModule option to Swallow), then the  colorset  is
296                     not  applied  to the swallowed module. You should use the
297                     colorset in the module configuration.  If  the  swallowed
298                     module  has  a  transparent colorset background, then the
299                     FvwmButtons background (and not the button  colorset)  is
300                     seen  by  transparency of the background of the swallowed
301                     module. Refer to the fvwm man page for details about col‐
302                     orsets.
303
304
305              ActiveColorset colorset
306                     Use  colorset  colorset  for  the  background color/image
307                     and/or title color of the button when the mouse is hover‐
308                     ing above it.
309
310
311              PressColorset colorset
312                     Use  colorset  colorset  for  the  background color/image
313                     and/or title color of the button when it is pressed.
314
315
316              Container [(options)]
317                     Specifies that this button will contain a miniature  but‐
318                     tonbox, equivalent to swallowing another FvwmButtons mod‐
319                     ule. The options are the same as can be given for a  sin‐
320                     gle  button,  but  they affect all the contained buttons.
321                     Options available for this  use  are  Back,  Font,  Fore,
322                     Frame  and  Padding.  Flags for Title and Swallow options
323                     can be set  with  Title(flags)  and  Swallow(flags).  You
324                     should  also  specify  either  "Columns  width"  or "Rows
325                     height", or "Rows 2" will be assumed. For an example, see
326                     the Sample configuration section.
327
328                     The  container button itself (separate from the contents)
329                     can take format options like Frame and Padding, and  com‐
330                     mands  can be bound to it. This means you can make a sen‐
331                     sitive relief around a container, like
332
333                       *FvwmButtons: (2x2, Frame 5, Padding 2 2, Action Beep,\
334                           Container(Frame 1))
335
336                     Typically you will want to at least give the container  a
337                     size setting widthxheight.
338
339
340              End    Specifies  that  no more buttons are defined for the cur‐
341                     rent container, and further buttons will be  put  in  the
342                     container's parent. This option should be given on a line
343                     by itself, i.e
344
345                       *FvwmButtons: (End)
346
347
348
349              Font fontname
350                     Specifies that the font fontname is to be used for label‐
351                     ing this button.
352
353
354              Fore color
355                     Specifies the foregound color of the title and monochrome
356                     icons in this button.
357
358
359              Frame width
360                     The relief of the button will be width  pixels  wide.  If
361                     width  is  given  as a negative number, the relief is in‐
362                     verted. This makes the button sunken normally and  raised
363                     when activated.
364
365
366              Icon filename
367                     The name of an image file, containing the icon to display
368                     on the button.  FvwmButtons  searches  through  the  path
369                     specified  in  the  fvwm  ImagePath configuration item to
370                     find the icon file.
371
372
373              ActiveIcon filename
374                     The name of an image file, containing an alternative icon
375                     to display on the button when the mouse is hovering above
376                     the button. If no  ActiveIcon  is  specified,  the  image
377                     specified by Icon is displayed (if there is one).
378
379
380              PressIcon filename
381                     The name of an image file, containing an alternative icon
382                     to display on the button when the button is  pressed.  If
383                     no PressIcon is specified, the image specified by Icon is
384                     displayed (if there is one).
385
386
387              Id id  The id to be used to identify  this  button.   The  first
388                     character  of  the id should be alphabetic.  See also the
389                     "DYNAMICAL ACTIONS" section.
390
391
392              Left   The contents of the button are aligned to the  left.  The
393                     default is to center the contents on the button.
394
395
396              NoSize This  option  specifies that this button will not be con‐
397                     sidered at all when making the  initial  calculations  of
398                     button  sizes. Useful for the odd button that gets just a
399                     couple of pixels too large to keep in line, and therefore
400                     blows  up your whole buttonbox. "NoSize" is equivalent to
401                     "Size 0 0".
402
403
404              Padding width height
405                     The amount of free space between the relief of the button
406                     and  its contents is normally 2 pixels to the sides and 4
407                     pixels above and below, except for swallowed windows  and
408                     containers,  which are by default not padded at all. This
409                     option sets the horizontal padding to width and the  ver‐
410                     tical padding to height.
411
412
413              Panel [ (options) ] hangon command
414                     Panels  can  be  swallowed exactly like windows are swal‐
415                     lowed by buttons with the Swallow command below, but they
416                     are  not  displayed  within the button.  Instead they are
417                     hidden until the user presses the panel's  button.   Then
418                     the panel (the window of the swallowed application) opens
419                     with a sliding animation.  The options can be any of  the
420                     flags  described  for the Swallow command.  In addition a
421                     direction 'left', 'right', 'up' or 'down' can be used  to
422                     specify the sliding direction.
423
424                     The  steps  animation-steps  option defines the number of
425                     animation steps.
426
427                     The delay ms option sets the delay between the  steps  of
428                     the  animation  in  milliseconds.  Use zero for no delay.
429                     The maximum delay is 10 seconds (10000). It doesn't  make
430                     any sense to use the delay option unless you also use the
431                     smooth option.
432
433                     The smooth option causes the panel  to   redraw   between
434                     the steps of the animation.  The sliding animation may be
435                     smoother this way, it depends  on  the  application,  and
436                     display  speed.   The  application may appear to grow in‐
437                     stead of sliding out.  The animation may be slower.
438
439                     The Hints option causes FvwmButtons to use  the  applica‐
440                     tions  size  hints to calculate the size of the animation
441                     steps.  Hints is the default.  If the number of steps  is
442                     not what you want, try using NoHints.
443
444                     The  noborder option tells FvwmButtons to ignore the bor‐
445                     ders of the window when calculating positions for the an‐
446                     imation  (equivalent  to set noplr and noptb in the posi‐
447                     tion option).
448
449                     With the indicator option set, FvwmButtons  will  draw  a
450                     small triangle in the button that will open a panel.  The
451                     triangle points in the direction where the panel will pop
452                     up.   The indicator keyword may be followed by a positive
453                     integer that specifies the maximum width  and  height  of
454                     the  indicator.   Without this size FvwmButtons will make
455                     the indicator fit the button. You will probably  want  to
456                     use  the Padding option to leave a few pixels between the
457                     indicator and the frame of the button.
458
459                     The position option allows one to place  the  panel.  The
460                     syntax is:
461
462                     position [context-window] [pos] [x y] [border-opts]
463
464                     The argument context-window can be one of: Button, Module
465                     or Root. The  context-window is  the  window  from  which
466                     panel percentage offsets are calculated. Button specifies
467                     the panel's button, Module specifies FvwmButtons  itself,
468                     and  Root  specifies a virtual screen. The context-window
469                     together with the sliding direction define a line segment
470                     which  is  one  of the borders of the context-window: the
471                     top/bottom/left/right      border       for       sliding
472                     up/down/left/right.
473
474                     The  pos  argument  can  be one of: center, left or right
475                     (for sliding up or a down) or top or bottom (for  sliding
476                     left  or  right). It defines the vertical (sliding up and
477                     down) or the horizontal (sliding left and right) position
478                     of  the  Panel  on  the  line segment. For example, for a
479                     sliding up if you use a left pos, then the  left  borders
480                     of the panel and of the context-window will be aligned.
481
482                     The  offset  values  x and y specify how far the panel is
483                     moved from it's default position. By default, the numeric
484                     value given is interpreted as a percentage of the context
485                     window's width (height). A trailing "p" changes  the  in‐
486                     terpretation  to  mean  "pixels". All offset calculations
487                     are relative to the buttons location, even when  using  a
488                     root context.
489
490                     The  border-opts are: mlr, mtb, noplr and noptb. They de‐
491                     fine which border widths are taken  in  account.  By  de‐
492                     fault,  the  borders  of FvwmButtons are not taken in ac‐
493                     count. mlr reverses this default for  the  left  and  the
494                     right  border  and  mtb reverses this default for the top
495                     and the bottom border. Conversely, by default the borders
496                     of  the  Panel  are taken in account. noplr reverses this
497                     default for the left and the right border and  noptb  re‐
498                     verses this default for the top and the bottom border.
499
500                     The  defaults  are  sliding  up with a delay of five mil‐
501                     liseconds and twelve animation steps. To post  the  panel
502                     without  any  animation, set the number of steps to zero.
503                     The default position is 'Button center'.
504
505                     Please refer to the CREATING PANELS section  for  further
506                     information on panels.
507
508                     Example:
509
510                       # To include the panel in a button
511                       *FvwmButtons: (Panel(down, delay 0, steps 16) \
512                         SubPanel "Module FvwmButtons SubPanel")
513
514                       # To define the panel as an instance of
515                       # FvwmButtons with a different name:
516                       *SubPanel: (Icon my_lock.xpm, Action Exec xlock)
517                       *SubPanel: (Icon my_move.xpm, Action Move)
518                       ...
519
520
521
522              Right  The  contents of the button are aligned to the right. The
523                     default is to center the contents on the button.
524
525
526              Size width height
527                     Specifies that the contents of this button require  width
528                     by  height  pixels,  regardless  of what size FvwmButtons
529                     calculates from the icon and the title. A button bar with
530                     only  swallowed  windows  will not get very large without
531                     this option specified, as FvwmButtons does  not  consider
532                     sizes for swallowing buttons. Note that this option gives
533                     the minimum space assured; other  buttons  might  require
534                     the buttonbox to use larger sizes.
535
536
537              Swallow [(flags)] hangon command
538                     Causes  FvwmButtons to execute command, and when a window
539                     with a name, class or resource matching  hangon  appears,
540                     it  is  captured  and  swallowed  into  this button.  The
541                     hangon string may contain wildcard characters ('*')  that
542                     match  any substring.  Swallow replaces the variables $fg
543                     and $bg as described above for the Action option (but  if
544                     you use the UseOld and NoClose options the application is
545                     not be restarted when FvwmButtons is restarted  and  thus
546                     does  not  get the new colors - if you changed them).  An
547                     example:
548
549                       *FvwmButtons: (Swallow XClock 'Exec xclock -geometry -3000-3000 &')
550
551                     takes the first window whose name, class, or resource  is
552                     "XClock"  and  displays it in the button.  If no matching
553                     window is found, the "Exec" command creates one.  The ar‐
554                     gument  "-geometry -3000-3000" is used so that the window
555                     is first drawn out of sight  before  its  swallowed  into
556                     FvwmButtons.
557
558                     Modules can be swallowed by specifying the module instead
559                     of 'Exec whatever', like:
560
561                       *FvwmButtons: (Swallow "FvwmPager" "FvwmPager 0 0")
562
563                     The flags that can be given to swallow are:
564
565                     NoClose / Close - Specifies whether the swallowed program
566                     in  this button will be un-swallowed or closed when Fvwm‐
567                     Buttons exits cleanly. "NoClose"  can  be  combined  with
568                     "UseOld"  to have windows survive a restart of the window
569                     manager. The default setting is "Close".
570
571                     NoHints / Hints - Specifies whether hints from the  swal‐
572                     lowed program in this button will be ignored or not, use‐
573                     ful in forcing a window to resize itself to fit its  but‐
574                     ton. The default value is "Hints".
575
576                     NoKill  /  Kill - Specifies whether the swallowed program
577                     will be closed by killing it or by sending a  message  to
578                     it.  This  can  be useful in ending programs that doesn't
579                     accept window manager  protocol.  The  default  value  is
580                     "NoKill". This has no effect if "NoClose" is specified.
581
582                     NoRespawn  / Respawn / SwallowNew - Specifies whether the
583                     swallowed program is to be respawned  (restarted)  if  it
584                     dies. If "Respawn" is specified, the program is respawned
585                     using the original command. Use this  option  with  care,
586                     the  program  might  have a legitimate reason to die.  If
587                     "SwallowNew" is given, the program is not respawned,  but
588                     if  a  new  window with the specified name appears, it is
589                     swallowed.
590
591                     NoOld / UseOld - Specifies whether the button will try to
592                     swallow  an  existing window matching the hangon name be‐
593                     fore spawning one itself with command.  The hangon string
594                     may contain wildcard characters ('*') that match any sub‐
595                     string.The default value is "NoOld". "UseOld" can be com‐
596                     bined  with "NoKill" to have windows survive a restart of
597                     the window manager. If you want FvwmButtons to swallow an
598                     old  window, and not spawn one itself if failing, let the
599                     command be "Nop":
600
601                       *FvwmButtons: (Swallow (UseOld) "Console" Nop)
602
603                     If you want to be able to start it yourself,  combine  it
604                     with an action:
605
606                       *FvwmButtons: (Swallow (UseOld) "Console" Nop, \
607                                    Action `Exec "Console" console &`)
608
609                     NoTitle  /  UseTitle - Specifies whether the title of the
610                     button will be taken from the swallowed window's title or
611                     not.  If  "UseTitle"  is  given,  the title on the button
612                     changes dynamically to reflect the window name.  The  de‐
613                     fault is "NoTitle".
614
615                     NoFvwmModule  /  FvwmModule  -  By  default,  FvwmButtons
616                     treats the swallowed window as an fvwm module  window  if
617                     the  4  first  letters  of the command is "Fvwm" or the 6
618                     first letters of the command is  "Module".   NoFvwmModule
619                     and FvwmModule override this logic.
620
621
622              Title [(options)] name
623                     Specifies  the  title to be written on the button. White‐
624                     space can be included in the title by quoting  it.  If  a
625                     title at any time is too long for its buttons, characters
626                     are chopped of one at a time until it fits. If justify is
627                     "Right",  the  head is removed, otherwise its tail is re‐
628                     moved. These options can be given to Title:
629
630                     Center - The title is centered horizontally. This is  the
631                     default.
632
633                     Left - The title is justified to the left side.
634
635                     Right - The title is justified to the right side.
636
637                     Side  - Causes the title to appear on the right hand side
638                     of any icon or swallowed window, instead of  below  which
639                     is  the default. If you use small icons, and combine this
640                     with the "Left" or "Right" option, you  can  get  a  look
641                     similar to fvwm's menus.
642
643
644              ActiveTitle name
645                     Specifies  the title to be written on the button when the
646                     mouse is hovering above the button. If no ActiveTitle  is
647                     specified,  the  text specified by Title is displayed (if
648                     there is any).
649
650
651              PressTitle name
652                     Specifies the title to be written on the button when  the
653                     button  is  pressed.  If  no PressTitle is specified, the
654                     text specified by Title is displayed (if there is any).
655
656
657              Legacy fields [title icon command]
658                     These fields are kept  for  compatibility  with  previous
659                     versions  of  FvwmButtons,  and their use is discouraged.
660                     The title field is similar to the option Title  name.  If
661                     the  title  field is "-", no title is displayed. The icon
662                     field is similar to the option Icon filename. If the icon
663                     field  is  "-" no icon is displayed. The command field is
664                     similar to the option  Action  command  or  alternatively
665                     Swallow "hangon" command.
666
667              The command
668                     Any  fvwm  command  is  recognized  by  FvwmButtons.  See
669                     fvwm(1) for more information.
670
671                     The Exec command has a small extension when used  in  Ac‐
672                     tions, its syntax is:
673
674                       Exec ["hangon"] command
675
676                     Example:
677
678                       *FvwmButtons: (Action Exec "xload" xload)
679
680                     The  hangon  string  must  be  enclosed in double quotes.
681                     When FvwmButtons finds such an Exec command,  the  button
682                     remains pushed in until a window whose name, class or re‐
683                     source matches the quoted portion of the command  is  en‐
684                     countered.   This  is intended to provide visual feedback
685                     to the user that the action he has requested will be per‐
686                     formed.   The  hangon string may contain wildcard charac‐
687                     ters ('*') that match any substring. If the  quoted  por‐
688                     tion contains no characters, then the button will pop out
689                     immediately.  Note that users can continue  pressing  the
690                     button,  and re-executing the command, even when it looks
691                     pressed in.
692
693
694              Quoting
695                     Any string which contains whitespace must be quoted. Con‐
696                     trary  to  earlier versions commands no longer need to be
697                     quoted. In this case any quoting character will be passed
698                     on  to  the  application  untouched.  Only commas ',' and
699                     closing parentheses ')' have to be quoted inside  a  com‐
700                     mand. Quoting can be done with any of the three quotation
701                     characters; single quote:
702
703                       'This is a "quote"',
704
705                     double quote:
706
707                       "It's another `quote'",
708
709                     and back quote:
710
711                       `This is a strange quote`.
712
713                     The back quoting is unusual but used on purpose,  if  you
714                     use  a  preprocessor like FvwmCpp and want it to get into
715                     your commands, like this:
716
717                       #define BG gray60
718                       *FvwmButtons: (Swallow "xload" `Exec xload -bg BG &`)
719
720                     Any single character can be quoted with a preceding back‐
721                     slash '\'.
722

CREATING PANELS

724       Former  versions  of FvwmButtons (fvwm 2.0.46 to 2.3.6) had a different
725       way of handling panels.  You can not use your old  panel  configuration
726       with the new panel feature.  Read "CONVERTING OLD PANEL CONFIGURATIONS"
727       for more information.
728
729
730
731   HOW TO CREATE NEW PANELS
732       Any program that can be launched from within fvwm and that has a window
733       can be used as a panel.  A terminal window could be your panel, or some
734       application like xload or xosview or  another  fvwm  module,  including
735       FvwmButtons itself.  All you need to know is how to start your applica‐
736       tion from fvwm.
737
738       The button that invokes the panel is as easily configured as any  other
739       button.  Essentially you need nothing more than the Panel option:
740
741
742       *FvwmButtons: (Panel my_first_panel \
743         "Module FvwmButtons -g -30000-30000 my_first_panel")
744       *FvwmButtons: (Panel my_second_panel \
745         "Exec exec xterm -g -30000-30000 -n my_second_panel")
746
747
748       This  works like the Swallow option.  The difference is that the appli‐
749       cation is not put into the button when it starts up but instead  hidden
750       from  view.   When you press the button for the panel the window slides
751       into view.  The '-g -30000-30000' option tells the application that  it
752       should  be created somewhere very far to the top and left of your visi‐
753       ble screen.  Otherwise you would see it  flashing  for  a  moment  when
754       FvwmButtons  starts  up.   Some applications do not work well with this
755       kind of syntax so you may have to live with the short flashing  of  the
756       window.   If you want to make a panel from another instance of FvwmBut‐
757       tons  you  can  do  so,  but  you  must  give  it  a   different   name
758       ('my_first_panel'  in above example).  If you run FvwmButtons under the
759       same name, new panels are created recursively until  your  system  runs
760       out  of resources and FvwmButtons crashes! To configure a second button
761       bar with a different name, simply put '*new_name' in place  of  '*Fvwm‐
762       Buttons'  in your configuration file.  If you are not familiar with the
763       Swallow option or if you want to learn more about how 'swallowing' pan‐
764       els works, refer to the description of the Swallow option.
765
766       Now  that  your  panel  basically works you will want to tune it a bit.
767       You may not want a window title on the panel.  To disable the title use
768       the fvwm Style command.  If your button bar is 'sticky' you may want to
769       make the panel sticky too.  And probably the panel window  should  have
770       no icon in case it is iconified.
771
772
773       Style name_of_panel_window NoTitle, Sitcky, NoIcon
774
775
776       You may want your panel to stay open only until you select something in
777       it.  You can give FvwmButtons the -transientpanel option after  the  -g
778       option in the command. FvwmPager has a similar option '-transient'.
779
780       Last,  but not least, you can now put an icon, a title or a small arrow
781       in the button so that you can see what it is for. A title or  icon  can
782       be  specified  as usual.  To activate the arrow, just add '(indicator)'
783       after the 'Panel' keyword in the example above and the  Padding  option
784       to  leave  a few pixels between the arrow and the border of the button.
785       An optional direction in which the panel is opened can be given too:
786
787
788       *FvwmButtons: (Padding 2, Panel(down, indicator) my_first_panel \
789         "Module FvwmButtons -g -30000-30000 -transientpanel my_first_panel")
790
791
792       There are several more options to configure how your panel  works,  for
793       example the speed and smoothness of the sliding animation. Please refer
794       to the description of the Panel option for further details.
795
796
797   CONVERTING OLD PANEL CONFIGURATIONS
798       This section describes how to convert a pretty old syntax used in 2.2.x
799       versions.  You may skip it if your syntax is more recent.
800
801       With  the  old  panel  feature you first had one or more lines defining
802       panels in your main FvwmButtons configuration:
803
804
805       ...
806       *FvwmButtons(Title WinOps,Panel WinOps)
807       *FvwmButtons(Title Tools ,Panel Tools)
808       ...
809
810
811       After the last configuration line for the main panel the  configuration
812       of  the  first  panel  followed,  introduced with a line beginning with
813       *FvwmButtonsPanel:
814
815
816       *FvwmButtonsPanel WinOps
817       *FvwmButtonsBack bisque2
818       ...
819
820       *FvwmButtonsPanel Tools
821       *FvwmButtonsBack bisque2
822       ...
823
824
825       And perhaps you had style commands for you panels:
826
827
828       Style FvwmButtonsPanel Title, NoHandles, BorderWidth 0
829       Style FvwmButtonsPanel NoButton 2, NoButton 4, Sticky
830
831
832       The new configuration looks much the same, but now the configuration of
833       the  main  panel is independent of the configuration of the sub panels.
834       The lines invoking the panels use the same syntax as  the  Swallow  op‐
835       tion,  so  you  simply add the name of the window to use as a panel and
836       the command to execute instead of the panel name.  Note that  you  give
837       the new instance of FvwmButtons a different name.
838
839
840       *FvwmButtons: (Title WinOps, Panel WinOps \
841         "Module FvwmButtons WinOps")
842       *FvwmButtons: (Title Tools , Panel Tools \
843         "Module FvwmButtons Tools")
844
845
846       If  you used something like 'Panel-d' you now have to use 'Panel(down)'
847       instead.  To make the new panel vanish as soon as a button was selected
848       start FvwmButtons with the '-transientpanel' option:
849
850
851       *FvwmButtons: (Title Tools , Panel(down) Tools \
852         "Module FvwmButtons -transientpanel Tools")
853
854
855       The rest of the configuration is very easy to change.  Delete the lines
856       '*FvwmButtonsPanel <name>' and add <name> to all of the following  con‐
857       figuration lines for the panel instead. Use the same name in your Style
858       commands:
859
860
861       *WinOps: Back bisque2
862       ...
863       *Tools: Back bisque2
864       ...
865       Style "WinOps" Title, NoHandles, BorderWidth 0
866       Style "WinOps" NoButton 2, NoButton 4, Sticky
867       Style "Tools" Title, NoHandles, BorderWidth 0
868       Style "Tools" NoButton 2, NoButton 4, Sticky
869
870
871       That's it.  The new panels are much more  flexible.   Please  refer  to
872       other parts of this documentation for details.
873
874
875   WHY WAS THE PANEL FEATURE REWRITTEN?
876       There  are several reasons.  The most important one is that the program
877       code implementing the panels was very disruptive and caused  a  lot  of
878       problems.   At  the same time it made writing new features for FvwmBut‐
879       tons difficult at best.  The second reason is that most users were sim‐
880       ply  unable  to make it work - it was way too complicated.  Even I (the
881       author of the new code) had to spend several  hours  before  I  got  it
882       working  the  first  time.  The third reason is that the new panels are
883       more versatile.  Any application can be a  panel  in  FvwmButtons,  not
884       just  other  instances of FvwmButtons itself.  So I sincerely hope that
885       nobody is angry about the change. Yes - you have to change your config‐
886       uration, but the new feature is much easier to configure, especially if
887       you already know how the Swallow option works.
888
889

ARRANGEMENT ALGORITHM

891       FvwmButtons tries to arrange its buttons as best it can, by  using  re‐
892       cursively,  on  each container including the buttonbox itself, the fol‐
893       lowing algorithm.
894
895       Getting the size right
896              First it calculates the number of  button  unit  areas  it  will
897              need,  by  adding  the width times the height in buttons of each
898              button. Containers are for the moment considered a  normal  but‐
899              ton.  Then it considers the given rows and columns arguments. If
900              the number of rows is given, it will calculate how many  columns
901              are  needed,  and  stick  to  that, unless columns is larger, in
902              which case you will get some empty space at the  bottom  of  the
903              buttonbox.  If the number of columns is given, it calculates how
904              many rows it needs to fit all the buttons. If neither is  given,
905              it  assumes  you  want two rows, and finds the number of columns
906              from that. If the BoxSize option is set to smart  at  least  the
907              height/width  of  the  tallest/widest  button  is used while the
908              fixed value prevents the box from getting resized if  both  rows
909              and columns have been set to non-zero.
910
911       Shuffling buttons
912              Now it has a large enough area to place the buttons in, all that
913              is left is to place them right. There are two kinds of  buttons:
914              fixed  and  floating buttons. A fixed button is forced to a spe‐
915              cific slot in the button box by a  x/y  geometry  argument.  All
916              other  buttons are considered floating. Fixed buttons are placed
917              first. Should a fixed button overlap another  one  or  shall  be
918              place  outside the buttons window, FvwmButtons exits with an er‐
919              ror message. After that the floating buttons are placed. The al‐
920              gorithm  tries  to  place the buttons in a left to right, top to
921              bottom western fashion. If a button fits at the suggested  posi‐
922              tion it is placed there, if not the current slot stays empty and
923              the slot to the right will be considered. After the  button  has
924              been  placed,  the next button is tried to be placed in the next
925              slot and so on until all buttons are placed. Additional rows are
926              added  below  the  bottom  line of buttons until all buttons are
927              placed if necessary if the BoxSize option smart is used.
928
929       Containers
930              Containers are arranged by the same algorithm, in fact they  are
931              shuffled recursively as the algorithm finds them.
932
933       Clarifying example
934              An example might be useful here: Suppose you have 6 buttons, all
935              unit sized except number two, which is 2x2.  This  makes  for  5
936              times  1 plus 1 times 4 equals 9 unit buttons total area. Assume
937              you have requested 3 columns.
938
939              1) +---+---+---+   2) +---+---+---+   3) +---+---+---+
940                 | 1 |       |      | 1 |       |      | 1 |       |
941                 +---+       +      +---+   2   +      +---+   2   +
942                 |           |      |   |       |      | 3 |       |
943                 +           +      +   +---+---+      +---+---+---+
944                 |           |      |           |      |   |   |   |
945                 +-----------+      +---+-------+      +---+---+---+
946
947              4) +---+---+---+   5) +---+-------+   6) +---+-------+
948                 | 1 |       |      | 1 |       |      | 1 |       |
949                 +---+   2   +      +---+   2   |      +---+   2   |
950                 | 3 |       |      | 3 |       |      | 3 |       |
951                 +---+---+---+      +---+---+---+      +---+-------+
952                 | 4 |       |      | 4 | 5 |   |      | 4 | 5 | 6 |
953                 +---+---+---+      +---+---+---+      +---+---+---+
954
955
956       What size will the buttons be?
957              When FvwmButtons has read the icons and fonts that are  required
958              by  its  configuration, it can find out which size is needed for
959              every non-swallowing button. The unit button size of a container
960              is set to be large enough to hold the largest button in it with‐
961              out squeezing it. Swallowed windows are simply  expected  to  be
962              comfortable with the button size they get from this scheme. If a
963              particular configuration requires more  space  for  a  swallowed
964              window,  it can be set in that button's configuration line using
965              the option "Size width height". This will  tell  FvwmButtons  to
966              give  this button at least width by height pixels inside the re‐
967              lief and padding.
968
969

DYNAMICAL ACTIONS

971       A running FvwmButtons instance may receive some commands at  run  time.
972       This is achieved using the fvwm command
973
974       SendToModule FvwmButtons-Alias <action> <params>
975
976       Supported actions:
977
978
979       ChangeButton button_id options
980              can be used to change the title or icon of a button at run time.
981              button_id is the id of the button to change as  specified  using
982              the Id button option.  It may also be a number, in this case the
983              button with the given number is assumed.  And finally, button_id
984              may be in the form +x+y, where x and y are a column number and a
985              row number of the button to be changed.  It is possible to spec‐
986              ify  multiple  option pairs (name with value) by delimiting them
987              using comma.   Currently  options  include  Title,  ActiveTitle,
988              PressTitle, Colorset, Icon, ActiveIcon and PressIcon.  These op‐
989              tions work like the configuration options of the same name.
990
991
992       ExpandButtonVars button_id command
993              replaces variables present in the command exactly  like  in  the
994              Action  button  option  and then sends the command back to fvwm.
995              button_id has the  same  syntax  as  described  in  ChangeButton
996              above.
997
998
999       PressButton button_id [mouse_button]
1000              simulates a mouse click on a button.  button_id is the id of the
1001              button to press as specified using  the  Id  button  option  and
1002              mouse_button  is the number of mouse button used to click on the
1003              button e.g "1" for the left mouse button etc.  Quotes around the
1004              number  are  not  necessary.  If mouse_button option is omitted,
1005              mouse button 1 is assumed.  This command behaves exactly  as  if
1006              the  mouse  button  was pressed and released on the button on in
1007              question.
1008
1009
1010       Silent This prefix may be specified before other actions.  It  disables
1011              all possible error and warning messages.
1012
1013
1014       Example:
1015
1016              *FvwmButtons: (Id note1, Title "13:30 - Dinner", Icon clock1.xpm)
1017
1018              SendToModule FvwmButtons Silent \
1019                ChangeButton note1 Icon clock2.xpm, Title "18:00 - Go Home"
1020
1021
1022

SAMPLE CONFIGURATION

1024       The following are excerpts from a .fvwm2rc file which describe FvwmBut‐
1025       tons initialization commands:
1026
1027
1028       ##########################################################
1029       # Load any modules which should be started during fvwm
1030       # initialization
1031
1032       # Make sure FvwmButtons is always there.
1033       AddToFunc StartFunction  "I" Module FvwmButtons
1034
1035       # Make it titlebar-less, sticky, and give it an icon
1036       Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky
1037
1038       # Make the menu/panel look like CDE
1039       Style "WinOps" Title, NoHandles, BorderWidth 0
1040       Style "WinOps" NoButton 2, NoButton 4, Sticky
1041       Style "Tools" Title, NoHandles, BorderWidth 0
1042       Style "Tools" NoButton 2, NoButton 4, Sticky
1043
1044       ##########################################################
1045       DestroyModuleConfig FvwmButtons: *
1046       *FvwmButtons: Fore Black
1047       *FvwmButtons: Back rgb:90/80/90
1048       *FvwmButtons: Geometry -135-5
1049       *FvwmButtons: Rows 1
1050       *FvwmButtons: BoxSize smart
1051       *FvwmButtons: Font -*-helvetica-medium-r-*-*-12-*
1052       *FvwmButtons: Padding 2 2
1053
1054       *FvwmButtons: (Title WinOps, Panel WinOps \
1055         "Module FvwmButtons -transientpanel WinOps")
1056       *FvwmButtons: (Title Tools, Panel Tools   \
1057         "Module FvwmButtons -transientpanel Tools")
1058
1059       *FvwmButtons: (Title Resize, Icon resize.xpm,  Action Resize)
1060       *FvwmButtons: (Title Move,   Icon arrows2.xpm, Action Move  )
1061       *FvwmButtons: (Title Lower,  Icon Down,        Action Lower )
1062       *FvwmButtons: (Title Raise,  Icon Up,          Action Raise )
1063       *FvwmButtons: (Title Kill,   Icon bomb.xpm,    Action Destroy)
1064
1065       *FvwmButtons: (1x1,Container(Rows 3,Frame 1))
1066       *FvwmButtons: (Title Dopey ,Action                          \
1067           `Exec "big_win" xterm -T big_win -geometry 80x50 &`)
1068       *FvwmButtons: (Title Snoopy, Font fixed, Action             \
1069           `Exec "small_win" xterm -T small_win &`)
1070       *FvwmButtons: (Title Smokin')
1071       *FvwmButtons: (End)
1072
1073       *FvwmButtons: (Title Xcalc, Icon rcalc.xpm,                 \
1074                    Action `Exec "Calculator" xcalc &`)
1075       *FvwmButtons: (Title XMag, Icon magnifying_glass2.xpm,      \
1076                    Action `Exec "xmag" xmag &`)
1077       *FvwmButtons: (Title Mail, Icon mail2.xpm,                  \
1078                    Action `Exec "xmh" xmh &`)
1079       *FvwmButtons: (4x1, Swallow "FvwmPager" `FvwmPager 0 3`     \
1080                    Frame 3)
1081
1082       *FvwmButtons: (Swallow(UseOld,NoKill) "xload15" `Exec xload \
1083            -title xload15 -nolabel -bg rgb:90/80/90 -update 15    \
1084            -geometry -3000-3000 &`)
1085
1086
1087       The last lines are a little tricky - one spawns  an  FvwmPager  module,
1088       and  captures  it  to display in a quadruple width button. is used, the
1089       Pager will be as big as possible within the button's relief.
1090
1091       The final line is even more magic. Note the combination of  UseOld  and
1092       NoKill,  which  will  try  to  swallow an existing window with the name
1093       "xload15" when starting up (if failing: starting one with the specified
1094       command),  which is un-swallowed when ending FvwmButtons. The swallowed
1095       application is started with "-geometry -3000-3000" so that it will  not
1096       be visible until its swallowed.
1097
1098       The other panels are specified after the root panel:
1099
1100
1101       ########## PANEL WinOps
1102       DestroyModuleConfig WinOps: *
1103       *WinOps: Back bisque2
1104       *WinOps: Geometry -3-3
1105       *WinOps: Columns 1
1106
1107       *WinOps: (Title Resize, Icon resize.xpm,  Action Resize)
1108       *WinOps: (Title Move,   Icon arrows2.xpm, Action Move  )
1109       *WinOps: (Title Lower,  Icon Down,        Action Lower )
1110       *WinOps: (Title Raise,  Icon Up,          Action Raise )
1111
1112       ########## PANEL Tools
1113       DestroyModuleConfig Tools: *
1114       *Tools: Back bisque2
1115       *Tools: Geometry -1-1
1116       *Tools: Columns 1
1117
1118       *Tools: (Title Kill,    Icon bomb.xpm,    Action Destroy)
1119
1120
1121       The  color  specification rgb:90/80/90 is actually the most correct way
1122       of specifying independent colors in X, and should be  used  instead  of
1123       the older #908090. If the latter specification is used in your configu‐
1124       ration file, you should be sure to escape the hash in any of  the  com‐
1125       mands  which  will  be  executed, or fvwm will consider the rest of the
1126       line a comment.
1127
1128       Note that with the x/y geometry specs you can easily build button  win‐
1129       dows  with  gaps.  Here is another example. You can not accomplish this
1130       without geometry specs for the buttons:
1131
1132       ##########################################################
1133       # Another example
1134       ##########################################################
1135
1136       # Make it titlebar-less, sticky, and give it an icon
1137       Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky
1138
1139       DestroyModuleConfig FvwmButtons: *
1140       *FvwmButtons: Font        5x7
1141       *FvwmButtons: Back rgb:90/80/90
1142       *FvwmButtons: Fore        black
1143       *FvwmButtons: Frame       1
1144       # 9x11 pixels per button, 4x4 pixels for the frame
1145       *FvwmButtons: Geometry    580x59+0-0
1146       *FvwmButtons: Rows        5
1147       *FvwmButtons: Columns     64
1148       *FvwmButtons: BoxSize     fixed
1149       *FvwmButtons: Padding     1 1
1150
1151       # Pop up a module menu directly above the button.
1152       *FvwmButtons: (9x1+3+0, Padding 0, Title "Modules",   \
1153         Action `Menu Modulepopup rectangle \
1154         $widthx$height+$lleft+$top o+50 -100m`)
1155
1156       # first row of buttons from left to right:
1157       *FvwmButtons: (3x2+0+1, Icon my_lock.xpm, Action `Exec xlock`)
1158       *FvwmButtons: (3x2+3+1, Icon my_recapture.xpm, Action Recapture)
1159       *FvwmButtons: (3x2+6+1, Icon my_resize.xpm, Action Resize)
1160       *FvwmButtons: (3x2+9+1, Icon my_move.xpm, Action Move)
1161       *FvwmButtons: (3x2+12+1, Icon my_fvwmconsole.xpm,     \
1162         Action 'Module FvwmConsole')
1163
1164       # second row of buttons from left to right:
1165       *FvwmButtons: (3x2+0+3, Icon my_exit.xpm, Action QuitSave)
1166       *FvwmButtons: (3x2+3+3, Icon my_restart.xpm, Action Restart)
1167       *FvwmButtons: (3x2+6+3, Icon my_kill.xpm, Action Destroy)
1168       *FvwmButtons: (3x2+9+3, Icon my_shell.xpm, Action 'Exec rxvt')
1169
1170       # big items
1171       *FvwmButtons: (10x5, Swallow (NoKill, NoCLose)        \
1172         "FvwmPager" 'FvwmPager * * -geometry 40x40-1024-1024')
1173       *FvwmButtons: (6x5, Swallow "FvwmXclock" `Exec xclock \
1174         -name FvwmXclock -geometry 40x40+0-3000 -padding 1  \
1175         -analog -chime -bg rgb:90/80/90`)
1176       *FvwmButtons: (13x5, Swallow (NoClose)                \
1177       "FvwmIconMan" 'Module FvwmIconMan')
1178       *FvwmButtons: (20x5, Padding 0, Swallow "xosview"     \
1179         `Exec /usr/X11R6/bin/xosview -cpu -int -page -net   \
1180         -geometry 100x50+0-3000 -font 5x7`)
1181
1182
1183

BUGS

1185       The action part of the Swallow option must be quoted if it contains any
1186       whitespace character.
1187
1188

COPYRIGHTS

1190       The FvwmButtons program, and the concept for interfacing this module to
1191       the Window Manager, are all original work by Robert Nation.
1192
1193       Copyright 1993, Robert Nation. No guarantees or warranties or  anything
1194       are provided or implied in any way whatsoever. Use this program at your
1195       own risk. Permission to use this program for any purpose is  given,  as
1196       long as the copyright is kept intact.
1197
1198       Further  modifications  and  patching  by Jarl Totland, copyright 1996.
1199       The statement above still applies.
1200
1201

AUTHOR

1203       Robert Nation.  Somewhat enhanced by  Jarl  Totland,  Jui-Hsuan  Joshua
1204       Feng, Scott Smedley.
1205
1206
1207
12083rd Berkeley Distribution   19 October 2022 (2.7.0)             FvwmButtons(1)
Impressum