diff --git a/Documentation/FvwmModules/FvwmAnimate.txt b/Documentation/FvwmModules/FvwmAnimate.txt new file mode 100644 index 000000000..8326abd1e --- /dev/null +++ b/Documentation/FvwmModules/FvwmAnimate.txt @@ -0,0 +1,194 @@ +FvwmAnimate +----------- + +The *FvwmAnimate* module animates iconification and de-iconification or +on command. There are currently 6 different animation effects. + +*FvwmAnimate* can only be invoked by fvwm. Command line invocation of +the *FvwmAnimate* module will not work. + +From within the .fvwm2rc file, *FvwmAnimate* is spawned as follows: + +------ +Module FvwmAnimate [ModuleAlias] +------ + +or from within an fvwm pop-up menu: + +------ +DestroyMenu Module-Popup +AddToMenu Module-Popup "Modules" Title ++ "Fvwm Animate Icons" Module FvwmAnimate ModuleAlias +------ + + +INVOCATION +~~~~~~~~~~ +*FvwmAnimate* must be invoked by the fvwm window manager. When invoked +with the 'OptionalName' argument, the 'ModuleAlias' is used to find +configuration commands, configuration files, and name the internally +generated menus and forms instead of "+FvwmAnimate+". + +During startup, *FvwmAnimate* defines menus and forms for configuring +and controlling *FvwmAnimate*. The default menu name is "+MenuFvwmAnimate+" +and the form name is "+FormFvwmAnimate+". If the optional name is used, +the menu would be "+Menu+" and the form would be "+Form+". + +Assuming you already had a builtin menu called "+Module-Popup+", you could +use *FvwmAnimate* by configuring it like this: + +------ +AddToFunc "StartFunction" "I" Module FvwmAnimate +AddToMenu "Module-Popup" "Control Animation" Popup MenuFvwmAnimate +------ + + +CONFIGURATION OPTIONS +~~~~~~~~~~~~~~~~~~~~~ +Since the pop up menu "+MenuFvwmAnimate+" allows complete control of the +*FvwmAnimate* module, you don't really have to know what any of the +configuration commands are. This section describes them anyway. + +*FvwmAnimate* gets configuration info from fvwm's module configuration +database (see *fvwm*(1), section *MODULE COMMANDS*). In addition, +*FvwmAnimate* reads the file $HOME/.FvwmAnimate, and accepts commands +from fvwm and its modules as it runs. + +If '+ModuleAlias+' is used to start *FvwmAnimate*, the optional name is +used in all commands, messages, menus and forms generated by +*FvwmAnimate* and in the configuration file name. Unlike other fvwm +modules, there is little reason to use the optional name. + +*FvwmAnimate: Color 'color':: ++ +Tells *FvwmAnimate* what color to draw with. The color is XOR'ed +(exclusive ORed) onto the background. Depending on the display type you +are using, the effect this causes will vary. Especially on 8-bit displays, +it helps if the background is a solid color. You have to experiment with +this to see how it works. ++ +The default color is not really a color and can be entered as +"+Black^White+", or more simply "+None+". This is the same as the default +XOR mask used by fvwm for move and resize frames. ++ +Other colors can be specified using standard X color notation. Ie. color +names like "+LightBlue+", or RGB values like "+#FFFFFF+". + + +*FvwmAnimate: Pixmap 'pixmap':: ++ +Tells *FvwmAnimate* to use 'pixmap' to draw with. This can be useful if +"+*FvwmAnimate: Color+" gives poor results. + + +*FvwmAnimate: Delay 'msecs':: ++ +Tells *FvwmAnimate* how many milliseconds to sleep between frames of +animation. + + +*FvwmAnimate: Iterations 'iterations':: ++ +Tells *FvwmAnimate* how many steps to break the animation into. + + +*FvwmAnimate: Twist 'twist':: ++ +Tells *FvwmAnimate* how many revolutions to twist the iconification frame. + + +*FvwmAnimate: Width 'width':: ++ +Tells *FvwmAnimate* how wide a line to draw with. The default width of +0 (zero) is a fast line of Width 1. + + +*FvwmAnimate: Effect 'mode':: ++ +Tells *FvwmAnimate* which animation effect to use. Currently the effects +are: 'Frame', 'Lines', 'Flip', 'Turn', 'Zoom3D', 'Twist' 'Random', and +'None'. 'None' is normally set in the configuration file, in-case +*FvwmAnimate* is started automatically, but an individual user doesn't +want it running. + + +*FvwmAnimate: Stop:: ++ +Tells *FvwmAnimate* to stop. + + +*FvwmAnimate: Save:: ++ +Tells *FvwmAnimate* to save the current configuration in a file named +"+.FvwmAnimate+" in the users home directory. This same file is read +automatically by *FvwmAnimate* during startup. + + +COMMANDS +~~~~~~~~ +*FvwmAnimate* can be asked to produce an animation thru the *SendToModule* +command. The format of the command is: + +------ +SendToModule FvwmAnimate animate sx sy sw sh dx dy dw dh +------ + +The second word must match the name *FvwmAnimate* is started with. The +8 fields after 'animate' must be numbers. The first 4 are for the source +(or starting) location of the animation. The last 4 are for the destination +of the animation. The 2 pairs of 4 numbers, represent rectangles. The +first 2 numbers are the x and y location of the upper right corner. The +next 2 numbers are the width and height. One or more spaces can separate +the fields in the command. + +Modules can use the *SendToModule* command to animate "+NoIcon+" windows, +or you can think up your own ways to have all kinds of fun with this +command. + +Additional available commands are: 'pause', 'play', 'push', 'pop' and +'reset'. These may be space separated. + +'pause' causes a module to not temporarily produce any animations. 'play' +causes a module to produce an animation again. 'push' stores the current +playing state for a future and 'pop' restores it. 'reset' removes all +stored states and sets playing on. + +Suppose, we don't want to wait for all 40 xterms to be animated: + +------ +SendToModule FvwmAnimate pause +All (XTerm) Iconify on +------ + +And if we don't want to damage the current playing state, then: + +------ +SendToModule FvwmAnimate push pause +All (XTerm) Iconify on +SendToModule FvwmAnimate pop +------ + + +ORIGIN +~~~~~~ + +*FvwmAnimate* is based on the Animate module from Afterstep 1.5pre6. +Porting to fvwm and lots of other changes were done by Dan Espen +. Below are the original author and acknowledgments. + + +AUTHOR +~~~~~~ + +Alfredo Kengi Kojima + + +ACKNOWLEDGMENTS +~~~~~~~~~~~~~~~ + +These people have contributed to *FvwmAnimate*: + +Kaj Groner :: +Twisty iconification, configuration file parsing, man page. + +Frank Scheelen diff --git a/Documentation/FvwmModules/FvwmAuto.txt b/Documentation/FvwmModules/FvwmAuto.txt new file mode 100644 index 000000000..4e7ac17de --- /dev/null +++ b/Documentation/FvwmModules/FvwmAuto.txt @@ -0,0 +1,139 @@ +FvwmAuto +-------- + +The *FvwmAuto* module is most often used to automatically raise focused +windows. + +*FvwmAuto* can only be invoked by fvwm. Command line invocation of the +*FvwmAuto* will not work. + + +INVOCATION +~~~~~~~~~~ + +The correct syntax is: + +------ +Module FvwmAuto Timeout [-passid] [-menter|-menterleave|-mfocus] [EnterCommand [LeaveCommand]] +------ + +Example: + +------ +AddToMenu Modules ++ "Auto Raise (300 ms)" Module FvwmAuto 300 ++ "Auto Raise/Lower" Module FvwmAuto 300 "Silent Raise" "Silent Lower" +------ + +The 'Timeout' argument is required. It specifies how long a window must +retain the keyboard input focus before the command is executed. The delay +is measured in milliseconds, and any integer greater than zero is valid. + +If the literal option '-passid' is given, the window id of the window +just entered or left is appended to the command that is sent to fvwm. +This can be used with the WindowId command of fvwm. + +The options '-menter', '-menterleave' and '-mfocus' influence the actions +*FvwmAuto* reacts to. No more than one of the options can be chosen. In +'-mfocus' mode, *FvwmAuto* raises the window that has the focus. In +'-menter' mode, *FvwmAuto* raises the window under the pointer when the +pointer enters a window. The 'LeaveCommand' is executed on the window +that was below the pointer before it entered the new window. When the +pointer leaves a window and enters the root window, the 'EnterCommand' +is executed too, but without a window to operate on. In '-menterleave' +mode, *FvwmAuto* works just like in '-menter' mode, but the 'LeaveCommand' +is also executed if the pointer moves out of a window but does not enter +a new window. The latter two modes of operation are useful with windows +that do not accept the focus. + +[NOTE] +'-menterleave' mode can interfere with popup windows of some applications. +One example is the zoom menu of Ghostview. Please do not complain about +this to us - it is a bug in Ghostview. + +'EnterCommand' and 'LeaveCommand' are optional. 'EnterCommand' is executed +Timeout milliseconds after a window gets the input focus, 'LeaveCommand' +is executed Timeout milliseconds after the window has lost focus. Note +that you always should use the \'+Silent+' keyword before the command +itself. *FvwmAuto* prepends "+Silent+" to the command string on its own +if yor forget this. Without this prefix fvwm would ask you for a window +to act on if the window has died before the command sent by *FvwmAuto* +has been processed by fvwm. This can for example happen with popup menus. + +"Silent Raise" is the default for 'EnterCommand', but any fvwm function +is allowed. I would not use "+Close+" or "+Destroy+" with a low timeout, +though. The 'LeaveCommand' can be handy for a tidy desktop. + +Experiment with: +------ +Module FvwmAuto 0 Nop "Silent Lower" +Module FvwmAuto 0 Nop "Silent Iconify" +------ + +An example for auto raising windows with ClickToFocus: +------ +Style * ClickToFocus +FvwmAuto 0 -menter "Silent Raise" +------ + +An example for auto raising and lowering only some windows: + +To start FvwmAuto: +------ +FvwmAuto 0 -passid -menter \ +"Silent selective_raiselower raise" \ +"Silent selective_raiselower lower" +------ + +And put this in your .fvwm2rc: +------ +AddToFunc selective_raiselower ++ I WindowId $1 (FvwmIconMan) $0 ++ I WindowId $1 (FvwmButtons) $0 ++ I WindowId $1 (xclock) $0 +------ + +More complex example (three FvwmAuto's are running): +------ +DestroyFunc RestoreIconified +AddToFunc RestoreIconified ++ I Current (Iconic) Iconify false + +DestroyFunc RegisterFocus +AddToFunc RegisterFocus ++ I Exec date +"%T $n focused" >>/tmp/focus-stats.txt + +DestroyFunc RegisterUnfocus +AddToFunc RegisterUnfocus ++ I Exec date +"%T $n unfocused" >>/tmp/focus-stats.txt + +KillModule FvwmAuto +Module FvwmAuto 250 Raise Nop +Module FvwmAuto 800 RestoreIconified Nop +Module FvwmAuto 0 RegisterFocus RegisterUnfocus +------ + + +NOTES +~~~~~ + +There is a special Raise/Lower support in *FvwmAuto*. It was added to +improve Raise/Lower callbacks, since most of *FvwmAuto* usages is +auto-raising or auto-lowering. This improvement includes locking on ++M_RAISE_WINDOW+ and +M_LOWER_WINDOW+ packets and not raising/lowering +explicitly raised windows. The special Raise/Lower support is enabled +only when either 'EnterCommand' or 'LeaveCommand' contain substring +"+Raise+" or "+Lower+". You can use this fact to enable/disable any special +support by renaming these commands, if *FvwmAuto* does not automatically +do want you expect it to do. + +Using *FvwmAuto* in conjunction with 'EdgeCommand' can be even more +powerful. There is a short example in the fvwm man page. + + +AUTHOR +~~~~~~ + +*FvwmAuto* just appeared one day, nobody knows how. + +*FvwmAuto* was simply rewritten 09/96, nobody knows by whom. diff --git a/Documentation/FvwmModules/FvwmBacker.txt b/Documentation/FvwmModules/FvwmBacker.txt new file mode 100644 index 000000000..74d837335 --- /dev/null +++ b/Documentation/FvwmModules/FvwmBacker.txt @@ -0,0 +1,175 @@ +FvwmBacker +---------- + +The *FvwmBacker* module provides functionality to change the background +when changing desktops. Any command can be executed to change the +backgrounds. Actually, any arbitrary command can be sent to fvwm to +execute, so you could also do things such as changing window border +colors, etc. + +*FvwmBacker* can only be invoked by fvwm. Command line invocation of the +*FvwmBacker* module will not work. + +From within the .fvwm2rc file, *FvwmBacker* is spawned as follows: + +------ +Module FvwmBacker +------ + + +COPYRIGHTS +~~~~~~~~~~ +The *FvwmBacker* module is the original work of Mike Finger. + +Copyright (C) 1994, Mike Finger. The author makes no guarantees or warranties +of any kind about the use of this module. Use this module at your own risk. +You may freely use this module or any portion of it for any purpose as +long as the copyright is kept intact. + + +INITIALIZATION +~~~~~~~~~~~~~~ + +During initialization, *FvwmBacker* gets config info from fvwm\'s module +configuration database (see *fvwm*(1), section *MODULE COMMANDS*). +Available options are discussed in a later section. + + +INVOCATION +~~~~~~~~~~ + +*FvwmBacker* can be invoked by fvwm during initialization by inserting +the line + +------ +AddToFunc StartFunction I Module FvwmBacker +------ + +in the .fvwm2rc file. + +*FvwmBacker* can be started using a \'+Module FvwmBacker+' command or +stopped using a \'+KillModule FvwmBacker+' command at any time when fvwm +is running. + +*FvwmBacker* must reside in a directory that is listed in the 'ModulePath' +option of fvwm for it to be executed by fvwm. + + +CONFIGURATION OPTIONS +~~~~~~~~~~~~~~~~~~~~~ + +The following options can be placed in the .fvwm2rc file + + +*FvwmBacker: Command ('Desk' 'd', 'Page' 'x' 'y') 'command':: ++ +Specifies the 'command' to execute when the viewport matches the arguments +for the 'desk' 'd', 'page' 'x' coordinate and 'y' coordinate. Any or all +of these three numeric arguments can be replaced with an asterisk (*) to +indicate that any value matches, in this case 'Desk' or 'Page' parts can +be skipped. ++ +If either the 'Desk' or the 'Page' parts are omitted, the 'command' is not +executed if only the desk or the page is switched. If neither is given, +the 'command' is executed only once when the module is started. This is +not the same as using asterisks for the numeric arguments: +if asterisks are used, the 'command' is always executed when only the desk +or page changes, if the corresponding part is omitted, the 'command' is +never executed when only the desk or page changes. ++ +If the 'command' is '-solid' *FvwmBacker* uses the next argument as a +color in the X database and sets the background to that color without +generating a system call to 'xsetroot' (only single word color names may +be used). ++ +If the 'command' is 'colorset' *FvwmBacker* uses the background specified +in 'colorset' 'n' for the given desk. Please refer to the man page of the +*FvwmTheme* module for details about colorsets. ++ +Otherwise the command is sent to fvwm to execute. + + +*FvwmBacker: RetainPixmap:: ++ +Causes *FvwmBacker* to retain and publish the Pixmap with which the +background has been set. This works only for the '-solid' or 'colorset' +commands. This is useful for applications which want to use the root +Pixmap on the background to simulate transparency (for example, Eterm +and Aterm use this method). This option should also be used for the +'RootTransparent' colorset option (see the *FvwmTheme* man page). ++ +[NOTE] +with a colorset background this command may add a lot of memory to the +X server. For example, this adds the pixmap width times height bytes +with a TiledPixmap image, screen_width times screen_height bytes with a +Pixmap image or a C,B,D,R,S or Y Gradient and screen_width bytes with a +VGradient or screen height bytes with an HGradient. + + +*FvwmBacker: DoNotRetainPixmap:: +Cancels the effect of the previous option. This is the default. + + +RUN-TIME CONFIGURATION +~~~~~~~~~~~~~~~~~~~~~~ + +It it possible to replace *FvwmBacker*'s configuration at run-time, +although it is not yet possible to remove existing configuration lines. +This is done by simply removing the old configuration from withing fvwm +and then read a new one. This can be done in many ways, for example by +using an fvwm function or one of the modules *FvwmCommand* or *FvwmConsole*. + +Example: + +------ +DestroyModuleConfig FvwmBacker* +*FvwmBacker: Command (Desk 0) -solid black +*FvwmBacker: Command (Desk 1) -solid blue +------ + + +OLD-STYLE OPTIONS +~~~~~~~~~~~~~~~~~ + +There is continued support for the now deprecated option: + +*FvwmBacker: Desk d command:: ++ +It is functionally equivalent to omitting the page coordinates with '*FvwmBacker:' 'Command': ++ +------ +*FvwmBacker: Command (Desk Id) command +------ + + +SAMPLE CONFIGURATION +~~~~~~~~~~~~~~~~~~~~ + +The following are excerpts from an .fvwm2rc file which describe *FvwmBacker* initialization commands: + +------ +#### +# Set Up Backgrounds for different desktop pages (2 desks, 3x2 pages). +#### +*FvwmBacker: Command (Page 2 *) -solid steelblue +*FvwmBacker: Command (Desk 0, Page 0 0) Exec fvwm-root $[HOME]/bg2.xpm +*FvwmBacker: Command (Desk 0, Page 0 1) -solid midnightblue +*FvwmBacker: Command (Desk 0, Page 1 *) -solid yellow +*FvwmBacker: Command (Desk 1, Page * 0) -solid navy +*FvwmBacker: Command (Desk 1, Page * 1) Colorset 5 +------ + + + +AUTHOR +~~~~~~ + +Mike Finger , , + doodman on IRC, check the #linux channel + +Modified by:: +Andrew Davison ++ +Michael Han ++ +Mikhael Goikhman diff --git a/Documentation/FvwmModules/FvwmBanner.txt b/Documentation/FvwmModules/FvwmBanner.txt new file mode 100644 index 000000000..d0c1f38ef --- /dev/null +++ b/Documentation/FvwmModules/FvwmBanner.txt @@ -0,0 +1,65 @@ +FvwmBanner +---------- + +*FvwmBanner* displays an Fvwm Logo in the center of the screen for 3 seconds. + +*FvwmBanner* can only be invoked by fvwm. Command line invocation of the +*FvwmBanner* module will not work. + +From within the .fvwm2rc file, *FvwmBanner* is spawned as follows: + +------ +Module FvwmBanner +------ + + +COPYRIGHTS +~~~~~~~~~~ + +None. + + +INITIALIZATION +~~~~~~~~~~~~~~ + +Nothing interesting. + + +INVOCATION +~~~~~~~~~~ + +*FvwmBanner* can be invoked by the command \'+Module FvwmBanner+'. This +can be bound to a menu or key-stroke in the .fvwm2rc file, but more +likely you would do this in the *StartFunction* or *InitFunction*, for example: + +------ +AddToFunc InitFunction "I" Module FvwmBanner +------ + +You can also give it an optional file parameter, like \'+FvwmBanner +doomface.xpm+' or specify an alternate default pixmap via configuration +options (see "*FvwmBanner: Pixmap" below). Fvwm will search the +ImagePath to find the image, or you can use the full path to the image. + + +CONFIGURATION OPTIONS +~~~~~~~~~~~~~~~~~~~~~ + +*FvwmBanner: NoDecor:: ++ +Tells *FvwmBanner* to create a window that fvwm will not manage and +not decorate. + +*FvwmBanner: Pixmap 'file':: ++ +Tells *FvwmBanner* to display file instead of the built in pixmap. + + +*FvwmBanner: Timeout 'sec':: +Tells *FvwmBanner* to display for sec seconds instead of default of 3 seconds. + + +AUTHOR +~~~~~~ + +Robert Nation diff --git a/Documentation/FvwmModules/FvwmButtons.txt b/Documentation/FvwmModules/FvwmButtons.txt new file mode 100644 index 000000000..f348a769a --- /dev/null +++ b/Documentation/FvwmModules/FvwmButtons.txt @@ -0,0 +1,1181 @@ +FvwmButtons +----------- + +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* can only be invoked by fvwm. Command line invocation of +the *FvwmButtons* module will not work. + +From within the .fvwm2rc file, *FvwmButtons* is spawned as follows: + +------ +Module FvwmButtons [-g geometry] [-transient | -transientpanel] [name[configfile]] +------ + +The buttonbox can be of any configuration or geometry, and can have +monochrome or color icons to represent the actions which would be invoked. +Even other applications can be \'swallowed' by the button bar. + +Panels that are opened on a button press are available too. See *CREATING 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' +option, 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 +*StartFunction* 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 columns specified. +If the box is too small to accommodate all buttons 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 until all buttons are placed. +For the best tolerance of configuration 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 background. +Refer to the 'FvwmTheme' 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 unspecified, +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 ignored 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 geometry 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 *FvwmButtons* 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 default is 2 rows. + +*FvwmButtons: ('options') ['title' 'icon' 'command']:: ++ +Specifies the contents of a button in the buttonbox. The following +'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 standard 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. Buttons 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 action is only +executed for mouse button 'n'. One action can be defined for each mouse +button, in addition to the general action. ++ +In the 'command' part, you can use a number of predefined variables: +'$left', '$right', '$top' and '$bottom' are substituted by the left, +right, top and bottom coordinates of the button pressed. '$-left', +'$-right', '$-top' and '$-bottom' are substituted likewise, but the +coordinates are calculated from the bottom or the right edge of the +screen instead (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 variables '$fg' and '$bg' are +replaced with the name of the foreground or background color set with +the 'Back' or 'Fore' option (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 +'ActionIgnoresClientWindow' 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 except for the +*Popup* action. This option changes this behavior, 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 swallowed 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 requires +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 applications' windows there is no guarantee for +anything. I have tested three applications: xosview works nicely with a +colorset background, xload works only with a VGradient 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 hovering 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 buttonbox, equivalent +to swallowing another *FvwmButtons* module. The options are the same as +can be given for a single 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 commands can be bound to it. +This means you can make a sensitive 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 +'width' x 'height'. ++ +End:::: ++ +Specifies that no more buttons are defined for the current 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 labeling 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 inverted. 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 considered 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 vertical padding to 'height'. ++ +Panel [('options')] 'hangon' 'command':::: +Panels can be swallowed exactly like windows are swallowed 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 +instead of sliding out. The animation may be slower. ++ +The 'Hints' option causes *FvwmButtons* to use the applications 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 borders of the +window when calculating positions for the animation (equivalent to set +\'noplr' and \'noptb' in the position 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 interpretation 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 define +which border widths are taken in account. By default, the borders of +*FvwmButtons* are not taken in account. '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' reverses this default for the top and +the bottom border. ++ +The defaults are sliding up with a delay of five milliseconds 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 argument "-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 *FvwmButtons* 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 swallowed program +in this button will be ignored or not, useful in forcing a window to +resize itself to fit its button. 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 before spawning one itself with +command. The hangon string may contain wildcard characters (\'\*\') that +match any substring. The default value is 'NoOld'. 'UseOld' can be +combined 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 default 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. Whitespace 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 removed. ++ +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 Actions, 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 resource matches the quoted portion of the 'command' +is encountered. This is intended to provide visual feedback to the user +that the action he has requested will be performed. The 'hangon' string +may contain wildcard characters (\'*') that match any substring. If +the quoted portion 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. Contrary 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 command. 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 backslash \'\'. + + +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 application +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 application +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 visible 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 *FvwmButtons* 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 \'swallowing' 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' 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' +option, 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 +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 +' and add ++ to all of the following +configuration 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 *FvwmButtons* +difficult at best. The second reason is that most users were simply +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 configuration, 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 +recursively, on each container including the buttonbox itself, the +following 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 button. 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 specific 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 error message. After that the floating buttons are placed. The algorithm +tries to place the buttons in a left to right, top to bottom western +fashion. If a button fits at the suggested position 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 without 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 relief and padding. + + +DYNAMICAL ACTIONS +~~~~~~~~~~~~~~~~~ + +A running FvwmButtons instance may receive some dynamical actions. +This is achived using the fvwm command + +------ +SendToModule FvwmButtons-Alias +------ + +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 possible to specify multiple option +pairs (name with value) by delimiting them using comma. Currently +options include *Title*, *ActiveTitle*, *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 +*FvwmButtons* 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 configuration +file, you should be sure to escape the hash in any of the commands 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 windows +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 (C) 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 (C) 1996. +The statement above still applies. + + +AUTHOR +~~~~~~ + +Robert Nation. Somewhat enhanced by Jarl Totland, Jui-Hsuan Joshua Feng, +Scott Smedley. diff --git a/Documentation/FvwmModules/FvwmCommand.txt b/Documentation/FvwmModules/FvwmCommand.txt new file mode 100644 index 000000000..467915c1c --- /dev/null +++ b/Documentation/FvwmModules/FvwmCommand.txt @@ -0,0 +1,424 @@ +FvwmCommand +----------- + +*FvwmCommand* lets you monitor fvwm transaction and issue fvwm command +from a shell command line or scripts. The syntax is: + +------ +FvwmCommand [-cmrvw] [-S name] [-i level] [-f name] [-F level] [command...] +------ + +*FvwmCommand* takes each argument as a fvwm command. Quotes can be used to send +commands including spaces. + +------ +FvwmCommand 'FvwmPager 0 1' +------ + + +INVOCATION +~~~~~~~~~~ +*FvwmCommandS* should be spawned once by fvwm, either in .fvwm2rc file, +from menu, or from *FvwmConsole*. From then on, *FvwmCommand* can be +called from a shell or script to execute fvwm commands. + +From within .fvwm2rc file: + +------ +Module FvwmCommandS +------ + +or + +------ +AddToFunc StartFunction "I" Module FvwmCommandS +------ + +Then, in script file or from shell: + +------ +FvwmCommand 'popup Utilities' +------ + + +OPTIONS +~~~~~~~ + +'-c':: ++ +Informs *FvwmCommand* to read multiple commands from the standard input +instead of the one command specified in the command line arguments. +This disables '-m' or '-i'. ++ +------ +(echo "Exec xload"; echo "Beep") | FvwmCommand -c +------ + +'-F' '':: ++ +Specifies the 'level' of fvwm window flags *FvwmCommand* outputs. ++ +0::: No window flags will be printed. ++ +2::: Full window flags will be printed if information level ('-i' option) +is +2+ or +3+. + +'-f' '':: ++ +Specifies an alternative FIFO set to communicate with a server. The +default FIFO set is /var/tmp/FvwmCommand-${DISPLAY}C, in which +*FvwmCommand..C* is used to send commands and *FvwmCommand..M* is to +receive messages. If that path is unusable ${FVWM_USERDIR}/FvwmCommand-${DISPLAY} +will be used instead. *FvwmCommandS* must have been invoked with the +same as its first argument prior to *FvwmCommand* invocation. +Alternatively, option '-S' can be used. Refer option '-S'. This option +'-f' is useful when a dedicated connection is necessary to run a background +job while another connection is kept for interactive use. + +'-i' '':: Specifies the level of information that *FvwmCommand* outputs. ++ +0::: Error messages only ++ +------ +FvwmCommand -i0 FvwmBanner +------ ++ +will show a banner without any output. On the other hand, ++ +------ +FvwmCommand -i 0 foobar +------ ++ +will return ++ +------ +[fvwm][executeModule]: <> No such module +foobar in ModulePath '/usr/lib/X11/fvwm' +------ ++ +Note that Fvwm doesn't return any error messages in cases like below +since 'windowid' itself is a valid command. ++ +------ +FvwmCommand -i 0 'windowid foo bar' +------ ++ +1::: Errors, replies and window configuration information. This is the default. ++ +------ +FvwmCommand send_windowlist +------ ++ +Information like below will show up. ++ +------ +0x02000014 window FvwmConsole +0x02000014 icon FvwmConsole +0x02000014 class XTerm +0x02000014 resource FvwmConsole +0x01c00014 window console +0x01c00014 icon console +0x01c00014 class XTerm +0x01c00014 resource console +0x01000003 window Fvwm Pager +0x01000003 icon +0x01000003 class FvwmModule +0x01000003 resource FvwmPager +0x00c0002c window emacs: FvwmCommand.man +0x00c0002c icon FvwmCommand.man +0x00c0002c icon file xemacs.xpm +0x00c0002c class Emacs +0x00c0002c resource emacs +end windowlist +------ ++ +The first column shows the window ID number, which can be used in +'windowid' command. The second column shows the information types. The +last column shows the information contents. If no information is +returned, add '-w' '