Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FvwmButtons(1)			 FVWM Modules			FvwmButtons(1)

NAME
       FvwmButtons - the FVWM buttonbox	module

SYNOPSIS
       Module FvwmButtons [-g geometry]	[-transient | -transientpanel] [name[configfile]]

       FvwmButtons  can	 only  be invoked by fvwm.  Command line invocation of
       the FvwmButtons module will not work.

DESCRIPTION
       The FvwmButtons module provides a window	of buttons which sits on the X
       terminal's root window. The user	can press the buttons at any time, and
       trigger invocation of a user-specified command by the  window  manager.
       FvwmButtons only	works when fvwm	is used	as the window manager.

       The  buttonbox  can  be	of any configuration or	geometry, and can have
       monochrome or color icons to represent the actions which	would  be  in-
       voked.  Even other applications can be 'swallowed' by the button	bar.

       Panels that are opened on a button press	are available too.  See	CREAT-
       ING PANELS section for details.

OPTIONS
       The -g option specifies the geometry of the main	 window.  The  command
       line  option  takes  precedence over any	other geometry settings	in the
       configuration file.

       The -transient option tells FvwmButtons to terminate itself  after  the
       first  key  or  button  press  has been received	(presses to open a sub
       panel do	not count) or a	sub panel has been closed or  respawned.  This
       is  especially  useful for sub panels where you want to select a	single
       button and have it closed automatically.	 It could be  used  to	create
       two-dimensional	graphical menus.  Since	-transient is an option, not a
       configuration setting you can use the same configuration	for  transient
       and non transient button	bars.

       The  -transientpanel option does	roughly	the same as the	-transient op-
       tion, but instead of closing the	whole button bar, the window is	merely
       hidden.	This is	very useful if the button bar is started as a subpanel
       of another button bar because it	avoids that it must be	started	 again
       when something is selected.

INVOCATION
       FvwmButtons  is	spawned	 by  fvwm, so command line invocation will not
       work.

       FvwmButtons can be invoked by inserting the  line  'Module  FvwmButtons
       OptionalName' in	the .fvwm2rc file. This	should be placed in the	Start-
       Function	if FvwmButtons is to be	spawned	during fvwm's  initialization.
       This  can  be bound to a	menu or	mouse button or	keystroke to invoke it
       later.

       When invoked with the OptionalName argument, the	OptionalName  is  used
       to find configuration commands.	For example:

       AddToFunc StartFunction Module FvwmButtons MyButtonBox

       FvwmButtons  will then use only the lines starting with "*MyButtonBox",
       instead of the default "*FvwmButtons".

CONFIGURATION OPTIONS
       The following commands are understood by	FvwmButtons:

       *FvwmButtons: Back color
	      Specifies	the background color for the buttons. The  relief  and
	      shadow color are calculated from the background color.

       *FvwmButtons: BoxSize algorithm
	      This option specifies how	serious	FvwmButtons takes the Rows and
	      Columns options (see below). It can be one  of  dumb,  fixed  or
	      smart.

	      If  fixed	 is  used  and both Rows and Columns are specified and
	      non-zero,	FvwmButtons uses exactly the number of rows  and  col-
	      umns specified.  If the box is too small to accommodate all but-
	      tons the module will fail.

	      If smart is used FvwmButtons enlarges the	 box  so  all  buttons
	      have  a  chance to fit. The number of columns is increased to at
	      least the	width of the widest button and new rows	are added  un-
	      til all buttons are placed. For the best tolerance of configura-
	      tion errors use the smart	option.

	      dumb is neither fixed nor	smart.	This is	the default.

       *FvwmButtons: Colorset colorset
	      Tells the	module to use colorset colorset	for the	 window	 back-
	      ground.	Refer to the FvwmTheme man page	for details about col-
	      orsets.

       *FvwmButtons: ActiveColorset colorset
	      Tells the	module to use colorset	colorset  for  the  background
	      color/image  and/or  title  color	 of a button when the mouse is
	      hovering above a button.

       *FvwmButtons: PressColorset colorset
	      Tells the	module to use colorset	colorset  for  the  background
	      color/image and/or title color of	a button when it is pressed.

       *FvwmButtons: Columns columns
	      Specifies	the number of columns of buttons to be created.	If un-
	      specified, the number of columns is set to the number of buttons
	      requested,  divided  by the number of rows. If both the rows and
	      columns are specified, but the number of buttons	is  more  than
	      the rows and columns allow for, the columns specification	is ig-
	      nored unless the BoxSize option is fixed.

       *FvwmButtons: File filename
	      Specifies	that the configuration for this	button is found	in the
	      file filename. Filename can be a full pathname, or is assumed to
	      be in fvwm's startup directory. The configuration	file is	in the
	      same  format as fvwm's configuration file, but each line is read
	      as if prefixed by	"*FvwmButtons".	Comments are given by starting
	      a	line with "#". Line continuation is done by ending a line with
	      a	"\".

       *FvwmButtons: Font font
	      Specifies	the font to be used for	labeling the buttons, or None.

       *FvwmButtons: Fore color
	      Specifies	the color used for button label	 text  and  monochrome
	      icons.

       *FvwmButtons: Frame width
	      Specifies	the width of the relief	around each button. If this is
	      a	negative number, the relief is inverted. This makes the	button
	      sunken normally and raised when activated.

       *FvwmButtons: Geometry geometry
	      Specifies	 the FvwmButtons window	location and size.  The	geome-
	      try is a standard	X11 window geometry specification.

       *FvwmButtons: ButtonGeometry geometry
	      This option works	like the Geometry option except	that the  size
	      is  the size of a	single button.	The size of the	whole FvwmBut-
	      tons window is calculated	by multiplying the button dimension by
	      the number of rows and columns.

       *FvwmButtons: Padding width height
	      This option specifies the	default	horizontal padding to be width
	      pixels, and the vertical padding to be height pixels. The	amount
	      of  free space between the relief	of the button and its contents
	      is normally 2 pixels on the sides	and 4 pixels above and	below,
	      except  for  swallowed  windows  and  containers,	 which are not
	      padded at	all, unless this option	is used.

       *FvwmButtons: Pixmap pixmapfile
	      Specifies	a background pixmap to use.  Specify  "none"  (without
	      the double quotes) for a transparent background.

       *FvwmButtons: Rows rows
	      Specifies	 the  number of	rows of	buttons	to be created. The de-
	      fault is 2 rows.

       *FvwmButtons: (options) [title icon command]
	      Specifies	the contents of	a button in the	buttonbox. The follow-
	      ing  options,  separated by commas or whitespace,	can be given a
	      button:

	      geometry
		     Specifies the size	and position of	the button within  the
		     FvwmButtons  window or container. The geometry is a stan-
		     dard X11 window geometry  specification.  The  button  is
		     width  times the normal button width and height times the
		     normal button height. If values for x and	y  are	given,
		     the  button  is  placed  x	(y) button units from the left
		     (top) of the container if x (y) is	 positive  and	x  (y)
		     units  from the right (bottom) if x (y) is	negative. But-
		     tons with position	arguments (x and y) are	placed	before
		     those  without them. If two or more buttons are forced to
		     overlap by	this, FvwmButtons exits	with an	error message.

	      Action [(options)] command
		     Specifies an fvwm command to be executed when the	button
		     is	 activated  by	pressing return	or a mouse button. The
		     command needs to be quoted	if it contains a  comma	 or  a
		     closing parenthesis.

		     The current options of the	Action are: Mouse n - this ac-
		     tion is only executed for mouse button n. One action  can
		     be	defined	for each mouse button, in addition to the gen-
		     eral action.

		     In	the command part, you can use a	number	of  predefined
		     variables:	 $left,	 $right,  $top and $bottom are substi-
		     tuted by the left,	right, top and bottom  coordinates  of
		     the  button  pressed. $-left, $-right, $-top and $-bottom
		     are substituted likewise, but the coordinates are	calcu-
		     lated from	the bottom or the right	edge of	the screen in-
		     stead (for	a button that is 5 pixels away from the	 right
		     screen border, $-right will be 5).	$width and $height are
		     replaced by the width or height of	the button. The	 vari-
		     ables $fg and $bg are replaced with the name of the fore-
		     ground or background color	set with the Back or Fore  op-
		     tion  (see	 below).  All  this  is	done regardless	of any
		     quoting characters. To get	a literal '$' use  the	string
		     '$$'.

		     Example:

		       *FvwmButtons: (Title xload, Action (Mouse 1) \
			 `Exec exec xload -fg $fg -bg $bg -geometry -3000-3000`)

		     Note:  With  fvwm	versions prior to 2.5.0, actions could
		     not be assigned to	a button that swallowed	an application
		     window  (see  Swallow  option).  Such actions worked only
		     when the border around the	button was clicked.   This  is
		     now  possible,  but to get	back the old behavior, the Ac-
		     tionIgnoresClientWindow can be used on the	button:

		       *FvwmButtons: (Action beep, ActionIgnoresClientWindow, \
			  Swallow xeyes	"Exec exec xeyes")

		     In	this example, the action is  only  executed  when  you
		     click on the border of the	button or the transparent part
		     of	the xeyes window, but not on the xeyes window itself.

	      ActionIgnoresClientWindow
		     See the note in the description of	Action above.

	      ActionOnPress
		     Usually the action	is executed on the button release  ex-
		     cept  for the Popup action.  This option changes this be-
		     havior, the action	is executed on the button press.  This
		     may  be good, for example,	with Menu or SendToModule that
		     generates popups, or when Frame is	0 and the button would
		     look unresponsive otherwise.

	      Back color
		     Specifies	the  background	 color to be used drawing this
		     box. A relief color and a	shadow	color  are  calculated
		     from this.

	      Center The  contents  of	the  button is centered	on the button.
		     This is the default but may be changed by Left or Right.

	      Colorset colorset
		     The given colorset	can be applied to a container, a swal-
		     lowed  application	and a simple button.  To apply it to a
		     button or container, simply put the option	in a line with
		     a	button	or container description.  Drawing backgrounds
		     for individual buttons and	containers with	colorsets  re-
		     quires  a	lot of communication with the X	server.	 So if
		     you are not content with the drawing speed	of  dozens  of
		     buttons  with  colorset backgrounds, do not use colorsets
		     here.  Setting colorsets as the background	 of  swallowed
		     applications  does	 not have this restriction but depends
		     entirely on the swallowed application.  It	 may  work  as
		     you  wish,	 but since it involves fiddling	with other ap-
		     plications' windows there is no guarantee	for  anything.
		     I	have  tested  three applications: xosview works	nicely
		     with a colorset background, xload works only with a VGra-
		     dient  or	solid background and an	analog xclock leaves a
		     trail painted in the background color after its hands.

		     If	the swallowed  window  is  an  fvwm  module  (see  the
		     (No)FvwmModule  option  to	Swallow), then the colorset is
		     not applied to the	swallowed module. You should  use  the
		     colorset  in  the	module configuration. If the swallowed
		     module has	a transparent colorset	background,  then  the
		     FvwmButtons  background  (and not the button colorset) is
		     seen by transparency of the background of	the  swallowed
		     module. Refer to the man page of the FvwmTheme module for
		     details about colorsets.

	      ActiveColorset colorset
		     Use colorset  colorset  for  the  background  color/image
		     and/or title color	of the button when the mouse is	hover-
		     ing above it.

	      PressColorset colorset
		     Use colorset  colorset  for  the  background  color/image
		     and/or title color	of the button when it is pressed.

	      Container	[(options)]
		     Specifies	that this button will contain a	miniature but-
		     tonbox, equivalent	to swallowing another FvwmButtons mod-
		     ule.  The options are the same as can be given for	a sin-
		     gle button, but they affect all  the  contained  buttons.
		     Options  available	 for  this  use	 are Back, Font, Fore,
		     Frame and Padding.	Flags for Title	 and  Swallow  options
		     can  be  set  with	 Title(flags)  and Swallow(flags). You
		     should also  specify  either  "Columns  width"  or	 "Rows
		     height", or "Rows 2" will be assumed. For an example, see
		     the Sample	configuration section.

		     The container button itself (separate from	the  contents)
		     can  take format options like Frame and Padding, and com-
		     mands can be bound	to it. This means you can make a  sen-
		     sitive relief around a container, like

		       *FvwmButtons: (2x2, Frame 5, Padding 2 2, Action	Beep,\
			   Container(Frame 1))

		     Typically	you will want to at least give the container a
		     size setting widthxheight.

	      End    Specifies that no more buttons are	defined	for  the  cur-
		     rent  container,  and  further buttons will be put	in the
		     container's parent. This option should be given on	a line
		     by	itself,	i.e

		       *FvwmButtons: (End)

	      Font fontname
		     Specifies that the	font fontname is to be used for	label-
		     ing this button.

	      Fore color
		     Specifies the foregound color of the title	and monochrome
		     icons in this button.

	      Frame width
		     The  relief  of  the button will be width pixels wide. If
		     width is given as a negative number, the  relief  is  in-
		     verted.  This makes the button sunken normally and	raised
		     when activated.

	      Icon filename
		     The name of an image file,	containing the icon to display
		     on	 the  button.	FvwmButtons  searches through the path
		     specified in the fvwm  ImagePath  configuration  item  to
		     find the icon file.

	      ActiveIcon filename
		     The name of an image file,	containing an alternative icon
		     to	display	on the button when the mouse is	hovering above
		     the  button.  If  no  ActiveIcon  is specified, the image
		     specified by Icon is displayed (if	there is one).

	      PressIcon	filename
		     The name of an image file,	containing an alternative icon
		     to	 display  on the button	when the button	is pressed. If
		     no	PressIcon is specified,	the image specified by Icon is
		     displayed (if there is one).

	      Id id  The  id  to  be  used to identify this button.  The first
		     character of the id should	be alphabetic.	See  also  the
		     "DYNAMICAL	ACTIONS" section.

	      Left   The  contents  of the button are aligned to the left. The
		     default is	to center the contents on the button.

	      NoSize This option specifies that	this button will not  be  con-
		     sidered  at  all  when making the initial calculations of
		     button sizes. Useful for the odd button that gets just  a
		     couple  of	pixels too large to keep in line, and therefor
		     blows up your whole buttonbox. "NoSize" is	equivalent  to
		     "Size 0 0".

	      Padding width height
		     The amount	of free	space between the relief of the	button
		     and its contents is normally 2 pixels to the sides	and  4
		     pixels  above and below, except for swallowed windows and
		     containers, which are by default not padded at all.  This
		     option  sets the horizontal padding to width and the ver-
		     tical padding to height.

	      Panel [ (options)	] hangon command
		     Panels can	be swallowed exactly like  windows  are	 swal-
		     lowed by buttons with the Swallow command below, but they
		     are not displayed within the button.   Instead  they  are
		     hidden  until  the	user presses the panel's button.  Then
		     the panel (the window of the swallowed application) opens
		     with  a sliding animation.	 The options can be any	of the
		     flags described for the Swallow command.  In  addition  a
		     direction	'left',	'right', 'up' or 'down'	can be used to
		     specify the sliding direction.

		     The steps animation-steps option defines  the  number  of
		     animation steps.

		     The  delay	 ms option sets	the delay between the steps of
		     the animation in milliseconds.  Use zero  for  no	delay.
		     The  maximum delay	is 10 seconds (10000). It doesn't make
		     any sense to use the delay	option unless you also use the
		     smooth option.

		     The  smooth  option causes	the panel  to  redraw  between
		     the steps of the animation.  The sliding animation	may be
		     smoother  this  way,  it  depends on the application, and
		     display speed.  The application may appear	 to  grow  in-
		     stead of sliding out.  The	animation may be slower.

		     The  Hints	 option	causes FvwmButtons to use the applica-
		     tions size	hints to calculate the size of	the  animation
		     steps.   Hints is the default.  If	the number of steps is
		     not what you want,	try using NoHints.

		     The noborder option tells FvwmButtons to ignore the  bor-
		     ders of the window	when calculating positions for the an-
		     imation (equivalent to set	noplr and noptb	in  the	 posi-
		     tion option).

		     With  the	indicator  option set, FvwmButtons will	draw a
		     small triangle in the button that will open a panel.  The
		     triangle points in	the direction where the	panel will pop
		     up.  The indicator	keyword	may be followed	by a  positive
		     integer  that  specifies  the maximum width and height of
		     the indicator.  Without this size FvwmButtons  will  make
		     the  indicator  fit the button. You will probably want to
		     use the Padding option to leave a few pixels between  the
		     indicator and the frame of	the button.

		     The position option allows	to place the panel. The	syntax
		     is:

		     position [context-window] [pos] [x	y] [border-opts]

		     The argument context-window can be	one of:	Button,	Module
		     or	 Root.	The   context-window  is the window from which
		     panel percentage offsets are calculated. Button specifies
		     the  panel's button, Module specifies FvwmButtons itself,
		     and Root specifies	a virtual screen.  The	context-window
		     together with the sliding direction define	a line segment
		     which is one of the borders of  the  context-window:  the
		     top/bottom/left/right	 border	      for      sliding
		     up/down/left/right.

		     The pos argument can be one of:  center,  left  or	 right
		     (for  sliding up or a down) or top	or bottom (for sliding
		     left or right). It	defines	the vertical (sliding  up  and
		     down) or the horizontal (sliding left and right) position
		     of	the Panel on the line  segment.	 For  example,	for  a
		     sliding  up  if you use a left pos, then the left borders
		     of	the panel and of the context-window will be aligned.

		     The offset	values x and y specify how far	the  panel  is
		     moved from	it's default position. By default, the numeric
		     value given is interpreted	as a percentage	of the context
		     window's  width  (height).	A trailing "p" changes the in-
		     terpretation to mean "pixels".  All  offset  calculations
		     are  relative  to the buttons location, even when using a
		     root context.

		     The border-opts are: mlr, mtb, noplr and noptb. They  de-
		     fine  which  border  widths  are taken in account.	By de-
		     fault, the	borders	of FvwmButtons are not	taken  in  ac-
		     count.  mlr  reverses  this  default for the left and the
		     right border and mtb reverses this	default	 for  the  top
		     and the bottom border. Conversely,	by default the borders
		     of	the Panel are taken in account.	 noplr	reverses  this
		     default  for  the left and	the right border and noptb re-
		     verses this default for the top and the bottom border.

		     The defaults are sliding up with a	 delay	of  five  mil-
		     liseconds	and  twelve animation steps. To	post the panel
		     without any animation, set	the number of steps  to	 zero.
		     The default position is 'Button center'.

		     Please  refer  to the CREATING PANELS section for further
		     information on panels.

		     Example:

		       # To include the	panel in a button
		       *FvwmButtons: (Panel(down, delay	0, steps 16) \
			 SubPanel "Module FvwmButtons SubPanel")

		       # To define the panel as	an instance of
		       # FvwmButtons with a different name:
		       *SubPanel: (Icon	my_lock.xpm, Action Exec xlock)
		       *SubPanel: (Icon	my_move.xpm, Action Move)
		       ...

	      Right  The contents of the button	are aligned to the right.  The
		     default is	to center the contents on the button.

	      Size width height
		     Specifies	that the contents of this button require width
		     by	height pixels, regardless  of  what  size  FvwmButtons
		     calculates	from the icon and the title. A button bar with
		     only swallowed windows will not get  very	large  without
		     this  option  specified, as FvwmButtons does not consider
		     sizes for swallowing buttons. Note	that this option gives
		     the  minimum  space  assured; other buttons might require
		     the buttonbox to use larger sizes.

	      Swallow [(flags)]	hangon command
		     Causes FvwmButtons	to execute command, and	when a	window
		     with  a  name, class or resource matching hangon appears,
		     it	is captured  and  swallowed  into  this	 button.   The
		     hangon  string may	contain	wildcard characters ('*') that
		     match any substring.  Swallow replaces the	variables  $fg
		     and  $bg as described above for the Action	option (but if
		     you use the UseOld	and NoClose options the	application is
		     not  be  restarted	when FvwmButtons is restarted and thus
		     does not get the new colors - if you changed  them).   An
		     example:

		       *FvwmButtons: (Swallow XClock 'Exec xclock -geometry -3000-3000 &')

		     takes  the	first window whose name, class,	or resource is
		     "XClock" and displays it in the button.  If  no  matching
		     window is found, the "Exec" command creates one.  The ar-
		     gument "-geometry -3000-3000" is used so that the	window
		     is	 first	drawn  out  of sight before its	swallowed into
		     FvwmButtons.

		     Modules can be swallowed by specifying the	module instead
		     of	'Exec whatever', like:

		       *FvwmButtons: (Swallow "FvwmPager" "FvwmPager 0 0")

		     The flags that can	be given to swallow are:

		     NoClose / Close - Specifies whether the swallowed program
		     in	this button will be un-swallowed or closed when	 Fvwm-
		     Buttons  exits  cleanly.  "NoClose"  can be combined with
		     "UseOld" to have windows survive a	restart	of the	window
		     manager. The default setting is "Close".

		     NoHints  /	Hints -	Specifies whether hints	from the swal-
		     lowed program in this button will be ignored or not, use-
		     ful  in forcing a window to resize	itself to fit its but-
		     ton. The default value is "Hints".

		     NoKill / Kill - Specifies whether the  swallowed  program
		     will  be  closed by killing it or by sending a message to
		     it. This can be useful in ending  programs	 that  doesn't
		     accept  window  manager  protocol.	 The  default value is
		     "NoKill". This has	no effect if "NoClose" is specified.

		     NoRespawn / Respawn / SwallowNew -	Specifies whether  the
		     swallowed	program	 is  to	be respawned (restarted) if it
		     dies. If "Respawn"	is specified, the program is respawned
		     using  the	 original  command. Use	this option with care,
		     the program might have a legitimate reason	 to  die.   If
		     "SwallowNew"  is given, the program is not	respawned, but
		     if	a new window with the specified	name  appears,	it  is
		     swallowed.

		     NoOld / UseOld - Specifies	whether	the button will	try to
		     swallow an	existing window	matching the hangon  name  be-
		     fore spawning one itself with command.  The hangon	string
		     may contain wildcard characters ('*') that	match any sub-
		     string.The	default	value is "NoOld". "UseOld" can be com-
		     bined with	"NoKill" to have windows survive a restart  of
		     the window	manager. If you	want FvwmButtons to swallow an
		     old window, and not spawn one itself if failing, let  the
		     command be	"Nop":

		       *FvwmButtons: (Swallow (UseOld) "Console" Nop)

		     If	 you  want to be able to start it yourself, combine it
		     with an action:

		       *FvwmButtons: (Swallow (UseOld) "Console" Nop, \
				    Action `Exec "Console" console &`)

		     NoTitle / UseTitle	- Specifies whether the	title  of  the
		     button will be taken from the swallowed window's title or
		     not. If "UseTitle"	is given,  the	title  on  the	button
		     changes  dynamically  to reflect the window name. The de-
		     fault is "NoTitle".

		     NoFvwmModule  /  FvwmModule  -  By	 default,  FvwmButtons
		     treats  the  swallowed window as an fvwm module window if
		     the 4 first letters of the	command	is  "Fvwm"  or	the  6
		     first  letters  of	the command is "Module".  NoFvwmModule
		     and FvwmModule override this logic.

	      Title [(options)]	name
		     Specifies the title to be written on the  button.	White-
		     space  can	 be  included in the title by quoting it. If a
		     title at any time is too long for its buttons, characters
		     are chopped of one	at a time until	it fits. If justify is
		     "Right", the head is removed, otherwise its tail  is  re-
		     moved. These options can be given to Title:

		     Center  - The title is centered horizontally. This	is the
		     default.

		     Left - The	title is justified to the left side.

		     Right - The title is justified to the right side.

		     Side - Causes the title to	appear on the right hand  side
		     of	 any  icon or swallowed	window,	instead	of below which
		     is	the default. If	you use	small icons, and combine  this
		     with  the	"Left"	or  "Right" option, you	can get	a look
		     similar to	fvwm's menus.

	      ActiveTitle name
		     Specifies the title to be written on the button when  the
		     mouse  is hovering	above the button. If no	ActiveTitle is
		     specified,	the text specified by Title is	displayed  (if
		     there is any).

	      PressTitle name
		     Specifies	the title to be	written	on the button when the
		     button is pressed.	If no  PressTitle  is  specified,  the
		     text specified by Title is	displayed (if there is any).

	      Legacy fields [title icon	command]
		     These  fields  are	 kept  for compatibility with previous
		     versions of FvwmButtons, and their	 use  is  discouraged.
		     The  title	 field is similar to the option	Title name. If
		     the title field is	"-", no	title is displayed.  The  icon
		     field is similar to the option Icon filename. If the icon
		     field is "-" no icon is displayed.	The command  field  is
		     similar  to  the  option  Action command or alternatively
		     Swallow "hangon" command.

	      The command
		     Any  fvwm	command	 is  recognized	 by  FvwmButtons.  See
		     fvwm(1) for more information.

		     The  Exec	command	has a small extension when used	in Ac-
		     tions, its	syntax is:

		       Exec ["hangon"] command

		     Example:

		       *FvwmButtons: (Action Exec "xload" xload)

		     The hangon	string must  be	 enclosed  in  double  quotes.
		     When  FvwmButtons	finds such an Exec command, the	button
		     remains pushed in until a window whose name, class	or re-
		     source  matches  the quoted portion of the	command	is en-
		     countered.	 This is intended to provide  visual  feedback
		     to	the user that the action he has	requested will be per-
		     formed.  The hangon string	may contain  wildcard  charac-
		     ters  ('*')  that match any substring. If the quoted por-
		     tion contains no characters, then the button will pop out
		     immediately.   Note  that users can continue pressing the
		     button, and re-executing the command, even	when it	 looks
		     pressed in.

	      Quoting
		     Any string	which contains whitespace must be quoted. Con-
		     trary to earlier versions commands	no longer need	to  be
		     quoted. In	this case any quoting character	will be	passed
		     on	to the application  untouched.	Only  commas  ','  and
		     closing  parentheses  ')' have to be quoted inside	a com-
		     mand. Quoting can be done with any	of the three quotation
		     characters; single	quote:

		       'This is	a "quote"',

		     double quote:

		       "It's another `quote'",

		     and back quote:

		       `This is	a strange quote`.

		     The  back	quoting	is unusual but used on purpose,	if you
		     use a preprocessor	like FvwmCpp and want it to  get  into
		     your commands, like this:

		       #define BG gray60
		       *FvwmButtons: (Swallow "xload" `Exec xload -bg BG &`)

		     Any single	character can be quoted	with a preceding back-
		     slash '\'.

CREATING PANELS
       Former versions of FvwmButtons (fvwm 2.0.46 to 2.3.6) had  a  different
       way  of	handling panels.  You can not use your old panel configuration
       with the	new panel feature.  Read "CONVERTING OLD PANEL CONFIGURATIONS"
       for more	information.

   HOW TO CREATE NEW PANELS
       Any program that	can be launched	from within fvwm and that has a	window
       can be used as a	panel.	A terminal window could	be your	panel, or some
       application  like  xload	 or  xosview or	another	fvwm module, including
       FvwmButtons itself.  All	you need to know is how	to start your applica-
       tion from fvwm.

       The  button that	invokes	the panel is as	easily configured as any other
       button.	Essentially you	need nothing more than the Panel option:

       *FvwmButtons: (Panel my_first_panel \
	 "Module FvwmButtons -g	-30000-30000 my_first_panel")
       *FvwmButtons: (Panel my_second_panel \
	 "Exec exec xterm -g -30000-30000 -n my_second_panel")

       This works like the Swallow option.  The	difference is that the	appli-
       cation  is not put into the button when it starts up but	instead	hidden
       from view.  When	you press the button for the panel the	window	slides
       into  view.  The	'-g -30000-30000' option tells the application that it
       should be created somewhere very	far to the top and left	of your	 visi-
       ble  screen.   Otherwise	 you  would  see it flashing for a moment when
       FvwmButtons starts up.  Some applications do not	work  well  with  this
       kind  of	 syntax	so you may have	to live	with the short flashing	of the
       window.	If you want to make a panel from another instance of  FvwmBut-
       tons   you   can	 do  so,  but  you  must  give	it  a  different  name
       ('my_first_panel' in above example).  If	you run	FvwmButtons under  the
       same  name,  new	 panels	are created recursively	until your system runs
       out of resources	and FvwmButtons	crashes! To configure a	second	button
       bar  with a different name, simply put '*new_name' in place of familiar
       with the	Swallow	option or if you want to learn more about  how	'swal-
       lowing' panels works, refer to the description of the Swallow option.

       Now  that  your	panel  basically works you will	want to	tune it	a bit.
       You may not want	a window title on the panel.  To disable the title use
       the  fvwm Style command.	 If your button	bar is the panel window	should
       have no icon in case it is iconified.

       Style name_of_panel_window NoTitle, Sitcky, NoIcon

       You may want your panel to stay open only until you select something in
       it.   You  can give FvwmButtons the -transientpanel option after	the -g
       option in the command. FvwmPager	has a similar option '-transient'.

       Last, but not least, you	can now	put an icon, a title or	a small	 arrow
       in  the	button so that you can see what	it is for. A title or icon can
       be specified as usual.  To activate the arrow, just add the Padding op-
       tion to leave a few pixels between the arrow and	the border of the but-
       ton.  An	optional direction in which the	panel is opened	can  be	 given
       too:

       *FvwmButtons: (Padding 2, Panel(down, indicator)	my_first_panel \
	 "Module FvwmButtons -g	-30000-30000 -transientpanel my_first_panel")

       There  are  several more	options	to configure how your panel works, for
       example the speed and smoothness	of the sliding animation. Please refer
       to the description of the Panel option for further details.

   CONVERTING OLD PANEL	CONFIGURATIONS
       This section describes how to convert a pretty old syntax used in 2.2.x
       versions.  You may skip it if your syntax is more recent.

       With the	old panel feature you first had	one  or	 more  lines  defining
       panels in your main FvwmButtons configuration:

       *FvwmButtons(Title WinOps,Panel WinOps)
       *FvwmButtons(Title Tools	,Panel Tools)

       After  the last configuration line for the main panel the configuration
       of the first panel followed, introduced	with  a	 line  beginning  with
       *FvwmButtonsPanel:

       *FvwmButtonsPanel WinOps
       *FvwmButtonsBack	bisque2

       *FvwmButtonsPanel Tools
       *FvwmButtonsBack	bisque2

       And perhaps you had style commands for you panels:

       Style FvwmButtonsPanel Title, NoHandles,	BorderWidth 0
       Style FvwmButtonsPanel NoButton 2, NoButton 4, Sticky

       The new configuration looks much	the same, but now the configuration of
       the main	panel is independent of	the configuration of the  sub  panels.
       The  lines  invoking  the panels	use the	same syntax as the Swallow op-
       tion, so	you simply add the name	of the window to use as	 a  panel  and
       the  command  to	execute	instead	of the panel name.  Note that you give
       the new instance	of FvwmButtons a different name.

       *FvwmButtons: (Title WinOps, Panel WinOps \
	 "Module FvwmButtons WinOps")
       *FvwmButtons: (Title Tools , Panel Tools	\
	 "Module FvwmButtons Tools")

       If you used something like 'Panel-d' you	now have to use	button was se-
       lected start FvwmButtons	with the '-transientpanel' option:

       *FvwmButtons: (Title Tools , Panel(down)	Tools \
	 "Module FvwmButtons -transientpanel Tools")

       The rest	of the configuration is	very easy to change.  Delete the lines
       '*FvwmButtonsPanel <name>' and add <name> to all	of the following  con-
       figuration lines	for the	panel instead. Use the same name in your Style
       commands:

       *WinOps:	Back bisque2
       *Tools: Back bisque2
       Style "WinOps" Title, NoHandles,	BorderWidth 0
       Style "WinOps" NoButton 2, NoButton 4, Sticky
       Style "Tools" Title, NoHandles, BorderWidth 0
       Style "Tools" NoButton 2, NoButton 4, Sticky

       That's it.  The new panels are much more	 flexible.   Please  refer  to
       other parts of this documentation for details.

   WHY WAS THE PANEL FEATURE REWRITTEN?
       There  are several reasons.  The	most important one is that the program
       code implementing the panels was	very disruptive	and caused  a  lot  of
       problems.   At  the same	time it	made writing new features for FvwmBut-
       tons difficult at best.	The second reason is that most users were sim-
       ply  unable  to make it work - it was way too complicated.  Even	I (the
       author of the new code) had to spend several  hours  before  I  got  it
       working	the  first  time.  The third reason is that the	new panels are
       more versatile.	Any application	can be a  panel	 in  FvwmButtons,  not
       just  other  instances of FvwmButtons itself.  So I sincerely hope that
       nobody is angry about the change. Yes - you have	to change your config-
       uration,	but the	new feature is much easier to configure, especially if
       you already know	how the	Swallow	option works.

ARRANGEMENT ALGORITHM
       FvwmButtons tries to arrange its	buttons	as best	it can,	by  using  re-
       cursively,  on  each container including	the buttonbox itself, the fol-
       lowing algorithm.

       Getting the size	right
	      First it calculates the number of	 button	 unit  areas  it  will
	      need,  by	 adding	 the width times the height in buttons of each
	      button. Containers are for the moment considered a  normal  but-
	      ton.  Then it considers the given	rows and columns arguments. If
	      the number of rows is given, it will calculate how many  columns
	      are  needed,  and	 stick	to  that, unless columns is larger, in
	      which case you will get some empty space at the  bottom  of  the
	      buttonbox.  If the number	of columns is given, it	calculates how
	      many rows	it needs to fit	all the	buttons. If neither is	given,
	      it  assumes  you	want two rows, and finds the number of columns
	      from that. If the	BoxSize	option is set to smart	at  least  the
	      height/width  of	the  tallest/widest  button  is	used while the
	      fixed value prevents the box from	getting	resized	if  both  rows
	      and columns have been set	to non-zero.

       Shuffling buttons
	      Now it has a large enough	area to	place the buttons in, all that
	      is left is to place them right. There are	two kinds of  buttons:
	      fixed  and  floating buttons. A fixed button is forced to	a spe-
	      cific slot in the	button box by a	 x/y  geometry	argument.  All
	      other  buttons are considered floating. Fixed buttons are	placed
	      first. Should a fixed button overlap another  one	 or  shall  be
	      place  outside the buttons window, FvwmButtons exits with	an er-
	      ror message. After that the floating buttons are placed. The al-
	      gorithm  tries  to  place	the buttons in a left to right,	top to
	      bottom western fashion. If a button fits at the suggested	 posi-
	      tion it is placed	there, if not the current slot stays empty and
	      the slot to the right will be considered.	After the  button  has
	      been  placed,  the next button is	tried to be placed in the next
	      slot and so on until all buttons are placed. Additional rows are
	      added  below  the	 bottom	 line of buttons until all buttons are
	      placed if	necessary if the BoxSize option	smart is used.

       Containers
	      Containers are arranged by the same algorithm, in	fact they  are
	      shuffled recursively as the algorithm finds them.

       Clarifying example
	      An example might be useful here: Suppose you have	6 buttons, all
	      unit sized except	number two, which is 2x2.  This	 makes	for  5
	      times  1 plus 1 times 4 equals 9 unit buttons total area.	Assume
	      you have requested 3 columns.

	      1) +---+---+---+	 2) +---+---+---+   3) +---+---+---+
		 | 1 |	     |	    | 1	|	|      | 1 |	   |
		 +---+	     +	    +---+   2	+      +---+   2   +
		 |	     |	    |	|	|      | 3 |	   |
		 +	     +	    +	+---+---+      +---+---+---+
		 |	     |	    |		|      |   |   |   |
		 +-----------+	    +---+-------+      +---+---+---+

	      4) +---+---+---+	 5) +---+-------+   6) +---+-------+
		 | 1 |	     |	    | 1	|	|      | 1 |	   |
		 +---+	 2   +	    +---+   2	|      +---+   2   |
		 | 3 |	     |	    | 3	|	|      | 3 |	   |
		 +---+---+---+	    +---+---+---+      +---+-------+
		 | 4 |	     |	    | 4	| 5 |	|      | 4 | 5 | 6 |
		 +---+---+---+	    +---+---+---+      +---+---+---+

       What size will the buttons be?
	      When FvwmButtons has read	the icons and fonts that are  required
	      by  its  configuration, it can find out which size is needed for
	      every non-swallowing button. The unit button size	of a container
	      is set to	be large enough	to hold	the largest button in it with-
	      out squeezing it.	Swallowed windows are simply  expected	to  be
	      comfortable with the button size they get	from this scheme. If a
	      particular configuration requires	more  space  for  a  swallowed
	      window,  it can be set in	that button's configuration line using
	      the option "Size width height". This will	 tell  FvwmButtons  to
	      give  this button	at least width by height pixels	inside the re-
	      lief and padding.

DYNAMICAL ACTIONS
       A running FvwmButtons instance  may  receive  some  dynamical  actions.
       This is achived using the fvwm command

       SendToModule FvwmButtons-Alias <action> <params>

       Supported actions:

       ChangeButton button_id options
	      where  button_id	is the id of the button	to change as specified
	      using the	Id button option. It may also be  a  number,  in  this
	      case  the	button with the	given number is	assumed.  And finally,
	      button_id	may be in the form +x+y, where x and y	are  a	column
	      number and a row number of the button to be changed.  It is pos-
	      sible to specify multiple	option pairs (name with	value) by  de-
	      limiting	them using comma. Currently options include Title, Ac-
	      tiveTitle, PressTitle, Icon, ActiveIcon and PressIcon.

       ExpandButtonVars	button_id command
	      where button_id has the same syntax as described in ChangeButton
	      above.  Command may be any fvwm command with variables $var that
	      are expanded if supported.

       PressButton button_id [mouse_button]
	      where button_id is the id	of the button to  press	 as  specified
	      using  the  Id  button  option and mouse_button is the number of
	      mouse button used	to click on the	button e.g "1" for left	 mouse
	      button   etc.  Quotes  around  the  number  is  not  needed.  If
	      mouse_button option is omitted "1" assumed. This command behaves
	      exactly  like  if	 the  button in	question was pressed using the
	      mouse.

       Silent This prefix may be specified before other	actions.  It  disables
	      all possible error and warning messages.

       Example:

	      *FvwmButtons: (Id	note1, Title "13:30 - Dinner", Icon clock1.xpm)

	      SendToModule FvwmButtons Silent \
		ChangeButton note1 Icon	clock2.xpm, Title "18:00 - Go Home"

SAMPLE CONFIGURATION
       The following are excerpts from a .fvwm2rc file which describe FvwmBut-
       tons initialization commands:

       ##########################################################
       # Load any modules which	should be started during fvwm
       # initialization

       # Make sure FvwmButtons is always there.
       AddToFunc StartFunction	"I" Module FvwmButtons

       # Make it titlebar-less,	sticky,	and give it an icon
       Style "FvwmButtons" Icon	toolbox.xpm, NoTitle, Sticky

       # Make the menu/panel look like CDE
       Style "WinOps" Title, NoHandles,	BorderWidth 0
       Style "WinOps" NoButton 2, NoButton 4, Sticky
       Style "Tools" Title, NoHandles, BorderWidth 0
       Style "Tools" NoButton 2, NoButton 4, Sticky

       ##########################################################
       DestroyModuleConfig FvwmButtons:	*
       *FvwmButtons: Fore Black
       *FvwmButtons: Back rgb:90/80/90
       *FvwmButtons: Geometry -135-5
       *FvwmButtons: Rows 1
       *FvwmButtons: BoxSize smart
       *FvwmButtons: Font -*-helvetica-medium-r-*-*-12-*
       *FvwmButtons: Padding 2 2

       *FvwmButtons: (Title WinOps, Panel WinOps \
	 "Module FvwmButtons -transientpanel WinOps")
       *FvwmButtons: (Title Tools, Panel Tools	 \
	 "Module FvwmButtons -transientpanel Tools")

       *FvwmButtons: (Title Resize, Icon resize.xpm,  Action Resize)
       *FvwmButtons: (Title Move,   Icon arrows2.xpm, Action Move  )
       *FvwmButtons: (Title Lower,  Icon Down,	      Action Lower )
       *FvwmButtons: (Title Raise,  Icon Up,	      Action Raise )
       *FvwmButtons: (Title Kill,   Icon bomb.xpm,    Action Destroy)

       *FvwmButtons: (1x1,Container(Rows 3,Frame 1))
       *FvwmButtons: (Title Dopey ,Action			   \
	   `Exec "big_win" xterm -T big_win -geometry 80x50 &`)
       *FvwmButtons: (Title Snoopy, Font fixed,	Action		   \
	   `Exec "small_win" xterm -T small_win	&`)
       *FvwmButtons: (Title Smokin')
       *FvwmButtons: (End)

       *FvwmButtons: (Title Xcalc, Icon	rcalc.xpm,		   \
		    Action `Exec "Calculator" xcalc &`)
       *FvwmButtons: (Title XMag, Icon magnifying_glass2.xpm,	   \
		    Action `Exec "xmag"	xmag &`)
       *FvwmButtons: (Title Mail, Icon mail2.xpm,		   \
		    Action `Exec "xmh" xmh &`)
       *FvwmButtons: (4x1, Swallow "FvwmPager" `FvwmPager 0 3`	   \
		    Frame 3)

       *FvwmButtons: (Swallow(UseOld,NoKill) "xload15" `Exec xload \
	    -title xload15 -nolabel -bg	rgb:90/80/90 -update 15	   \
	    -geometry -3000-3000 &`)

       The last	lines are a little tricky - one	spawns	an  FvwmPager  module,
       and  captures  it  to display in	a quadruple width button. is used, the
       Pager will be as	big as possible	within the button's relief.

       The final line is even more magic. Note the combination of  UseOld  and
       NoKill,	which  will  try  to  swallow an existing window with the name
       "xload15" when starting up (if failing: starting	one with the specified
       command),  which	is un-swallowed	when ending FvwmButtons. The swallowed
       application is started with "-geometry -3000-3000" so that it will  not
       be visible until	its swallowed.

       The other panels	are specified after the	root panel:

       ########## PANEL	WinOps
       DestroyModuleConfig WinOps: *
       *WinOps:	Back bisque2
       *WinOps:	Geometry -3-3
       *WinOps:	Columns	1

       *WinOps:	(Title Resize, Icon resize.xpm,	 Action	Resize)
       *WinOps:	(Title Move,   Icon arrows2.xpm, Action	Move  )
       *WinOps:	(Title Lower,  Icon Down,	 Action	Lower )
       *WinOps:	(Title Raise,  Icon Up,		 Action	Raise )

       ########## PANEL	Tools
       DestroyModuleConfig Tools: *
       *Tools: Back bisque2
       *Tools: Geometry	-1-1
       *Tools: Columns 1

       *Tools: (Title Kill,    Icon bomb.xpm,	 Action	Destroy)

       The  color  specification rgb:90/80/90 is actually the most correct way
       of specifying independent colors	in X, and should be  used  instead  of
       the older #908090. If the latter	specification is used in your configu-
       ration file, you	should be sure to escape the hash in any of  the  com-
       mands  which  will  be  executed, or fvwm will consider the rest	of the
       line a comment.

       Note that with the x/y geometry specs you can easily build button  win-
       dows  with  gaps.  Here is another example. You can not accomplish this
       without geometry	specs for the buttons:

       ##########################################################
       # Another example
       ##########################################################

       # Make it titlebar-less,	sticky,	and give it an icon
       Style "FvwmButtons" Icon	toolbox.xpm, NoTitle, Sticky

       DestroyModuleConfig FvwmButtons:	*
       *FvwmButtons: Font	 5x7
       *FvwmButtons: Back rgb:90/80/90
       *FvwmButtons: Fore	 black
       *FvwmButtons: Frame	 1
       # 9x11 pixels per button, 4x4 pixels for	the frame
       *FvwmButtons: Geometry	 580x59+0-0
       *FvwmButtons: Rows	 5
       *FvwmButtons: Columns	 64
       *FvwmButtons: BoxSize	 fixed
       *FvwmButtons: Padding	 1 1

       # Pop up	a module menu directly above the button.
       *FvwmButtons: (9x1+3+0, Padding 0, Title	"Modules",   \
	 Action	`Menu Modulepopup rectangle \
	 $widthx$height+$lleft+$top o+50 -100m`)

       # first row of buttons from left	to right:
       *FvwmButtons: (3x2+0+1, Icon my_lock.xpm, Action	`Exec xlock`)
       *FvwmButtons: (3x2+3+1, Icon my_recapture.xpm, Action Recapture)
       *FvwmButtons: (3x2+6+1, Icon my_resize.xpm, Action Resize)
       *FvwmButtons: (3x2+9+1, Icon my_move.xpm, Action	Move)
       *FvwmButtons: (3x2+12+1,	Icon my_fvwmconsole.xpm,     \
	 Action	'Module	FvwmConsole')

       # second	row of buttons from left to right:
       *FvwmButtons: (3x2+0+3, Icon my_exit.xpm, Action	QuitSave)
       *FvwmButtons: (3x2+3+3, Icon my_restart.xpm, Action Restart)
       *FvwmButtons: (3x2+6+3, Icon my_kill.xpm, Action	Destroy)
       *FvwmButtons: (3x2+9+3, Icon my_shell.xpm, Action 'Exec rxvt')

       # big items
       *FvwmButtons: (10x5, Swallow (NoKill, NoCLose)	     \
	 "FvwmPager" 'FvwmPager	* * -geometry 40x40-1024-1024')
       *FvwmButtons: (6x5, Swallow "FvwmXclock"	`Exec xclock \
	 -name FvwmXclock -geometry 40x40+0-3000 -padding 1  \
	 -analog -chime	-bg rgb:90/80/90`)
       *FvwmButtons: (13x5, Swallow (NoClose)		     \
       "FvwmIconMan" 'Module FvwmIconMan')
       *FvwmButtons: (20x5, Padding 0, Swallow "xosview"     \
	 `Exec /usr/X11R6/bin/xosview -cpu -int	-page -net   \
	 -geometry 100x50+0-3000 -font 5x7`)

BUGS
       The action part of the Swallow option must be quoted if it contains any
       whitespace character.

COPYRIGHTS
       The FvwmButtons program,	and the	concept	for interfacing	this module to
       the Window Manager, are all original work by Robert Nation.

       Copyright 1993, Robert Nation. No guarantees or warranties or  anything
       are provided or implied in any way whatsoever. Use this program at your
       own risk. Permission to use this	program	for any	purpose	is  given,  as
       long as the copyright is	kept intact.

       Further	modifications  and  patching  by Jarl Totland, copyright 1996.
       The statement above still applies.

AUTHOR
       Robert Nation.  Somewhat	enhanced by  Jarl  Totland,  Jui-Hsuan	Joshua
       Feng, Scott Smedley.

3rd Berkeley Distribution (not released	yet) (2.5.20)		FvwmButtons(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | INVOCATION | CONFIGURATION OPTIONS | CREATING PANELS | ARRANGEMENT ALGORITHM | DYNAMICAL ACTIONS | SAMPLE CONFIGURATION | BUGS | COPYRIGHTS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=FvwmButtons&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help