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 fvwm man page for details about colorsets.

       *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.

	      Top    The  contents  of the button is vertically	aligned	at the
		     top of the	button.	The default is	to  vertically	center
		     it.

	      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 fvwm man page	for details about col-
		     orsets.

	      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	one 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  '*Fvwm-
       Buttons'	 in your configuration file.  If you are not familiar with the
       Swallow option or if you	want to	learn more about how 'swallowing' pan-
       els 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 'sticky' you may want to
       make the	panel sticky too.  And probably	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 '(indicator)'
       after the 'Panel' keyword in the	example	above and the  Padding	option
       to  leave  a few	pixels between the arrow and the border	of the button.
       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 'Panel(down)'
       instead.	 To make the new panel vanish as soon as a button was selected
       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 commands	at  run	 time.
       This is achieved	using the fvwm command

       SendToModule FvwmButtons-Alias <action> <params>

       Supported actions:

       ChangeButton button_id options
	      can be used to change the	title or icon of a button at run time.
	      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 possible to spec-
	      ify  multiple  option pairs (name	with value) by delimiting them
	      using comma.   Currently	options	 include  Title,  ActiveTitle,
	      PressTitle, Colorset, Icon, ActiveIcon and PressIcon.  These op-
	      tions work like the configuration	options	of the same name.

       ExpandButtonVars	button_id command
	      replaces variables present in the	command	exactly	 like  in  the
	      Action  button  option  and then sends the command back to fvwm.
	      button_id	has the	 same  syntax  as  described  in  ChangeButton
	      above.

       PressButton button_id [mouse_button]
	      simulates	a mouse	click on a button.  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 the left mouse	button etc.  Quotes around the
	      number  are  not	necessary.  If mouse_button option is omitted,
	      mouse button 1 is	assumed.  This command behaves exactly	as  if
	      the  mouse  button  was pressed and released on the button on in
	      question.

       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  05 September	2019 (2.6.9)		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