From 4dbfd7c4f830b9f6dee81163b266158c6ed84dd9 Mon Sep 17 00:00:00 2001 From: Thomas Funk Date: Sun, 19 Feb 2012 23:07:51 +0100 Subject: [PATCH 01/16] new file: FvwmModules/FvwmAnimate.txt new file: FvwmModules/FvwmAuto.txt new file: FvwmModules/FvwmBacker.txt new file: FvwmModules/FvwmBanner.txt new file: FvwmModules/FvwmButtons.txt --- Documentation/FvwmModules/FvwmAnimate.txt | 211 ++++ Documentation/FvwmModules/FvwmAuto.txt | 158 +++ Documentation/FvwmModules/FvwmBacker.txt | 191 ++++ Documentation/FvwmModules/FvwmBanner.txt | 74 ++ Documentation/FvwmModules/FvwmButtons.txt | 1192 +++++++++++++++++++++ 5 files changed, 1826 insertions(+) create mode 100644 Documentation/FvwmModules/FvwmAnimate.txt create mode 100644 Documentation/FvwmModules/FvwmAuto.txt create mode 100644 Documentation/FvwmModules/FvwmBacker.txt create mode 100644 Documentation/FvwmModules/FvwmBanner.txt create mode 100644 Documentation/FvwmModules/FvwmButtons.txt diff --git a/Documentation/FvwmModules/FvwmAnimate.txt b/Documentation/FvwmModules/FvwmAnimate.txt new file mode 100644 index 000000000..02f2b81e2 --- /dev/null +++ b/Documentation/FvwmModules/FvwmAnimate.txt @@ -0,0 +1,211 @@ +FvwmAnimate(1) +================ +:doctype: manpage + +NAME +---- + +FvwmAnimate - the fvwm animate module + + +SYNOPSIS +-------- + +Module FvwmAnimate [ModuleAlias] + + +DESCRIPTION +----------- + +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 +------ + +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..0ce50edda --- /dev/null +++ b/Documentation/FvwmModules/FvwmAuto.txt @@ -0,0 +1,158 @@ +FvwmAuto(1) +=========== +:doctype: manpage + +NAME +---- + +FvwmAuto - the fvwm auto-raise module + + +SYNOPSIS +-------- + +Module FvwmAuto Timeout [-passid] [-menter|-menterleave|-mfocus] [EnterCommand [LeaveCommand]] + + +DESCRIPTION +----------- + +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..111b2db7e --- /dev/null +++ b/Documentation/FvwmModules/FvwmBacker.txt @@ -0,0 +1,191 @@ +FvwmBacker(1) +============= +:doctype: manpage + + +NAME +---- + +FvwmBacker - the fvwm background changer module + + +SYNOPSIS +-------- + +Module FvwmBacker + + +DESCRIPTION +----------- + +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. + + +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..baf6fa362 --- /dev/null +++ b/Documentation/FvwmModules/FvwmBanner.txt @@ -0,0 +1,74 @@ +FvwmBanner(1) +============= +:doctype: manpage + +NAME +---- + +FvwmBanner - the Fvwm Banner module + + +SYNOPSIS +-------- + +Module FvwmBanner + + +DESCRIPTION +----------- + +*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. + +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..ea32bfee5 --- /dev/null +++ b/Documentation/FvwmModules/FvwmButtons.txt @@ -0,0 +1,1192 @@ +FvwmButtons(1) +============== +:doctype: manpage + + +NAME +---- + +FvwmButtons - the fvwm buttonbox module + + +SYNOPSIS +-------- + +Module FvwmButtons [-g geometry] [-transient | -transientpanel] [name[configfile]] + + +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* can only be invoked by fvwm. Command line invocation of +the *FvwmButtons* module will not work. + +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. From b06e2f9c90c3b94a9b5080827f6ab126c3cd3950 Mon Sep 17 00:00:00 2001 From: Thomas Funk Date: Sat, 25 Feb 2012 14:22:20 +0100 Subject: [PATCH 02/16] New FvwmModules manpages A-D --- Documentation/FvwmModules/FvwmAnimate.txt | 44 ++-- Documentation/FvwmModules/FvwmAuto.txt | 23 +- Documentation/FvwmModules/FvwmBacker.txt | 35 ++- Documentation/FvwmModules/FvwmBanner.txt | 16 +- Documentation/FvwmModules/FvwmButtons.txt | 22 +- Documentation/FvwmModules/FvwmConsole.txt | 134 ++++++++++ Documentation/FvwmModules/FvwmConsoleC.txt | 280 ++++++++++++++++++++ Documentation/FvwmModules/FvwmCpp.txt | 292 +++++++++++++++++++++ Documentation/FvwmModules/FvwmDebug.txt | 125 +++++++++ 9 files changed, 897 insertions(+), 74 deletions(-) create mode 100644 Documentation/FvwmModules/FvwmConsole.txt create mode 100644 Documentation/FvwmModules/FvwmConsoleC.txt create mode 100644 Documentation/FvwmModules/FvwmCpp.txt create mode 100644 Documentation/FvwmModules/FvwmDebug.txt diff --git a/Documentation/FvwmModules/FvwmAnimate.txt b/Documentation/FvwmModules/FvwmAnimate.txt index 02f2b81e2..12631b779 100644 --- a/Documentation/FvwmModules/FvwmAnimate.txt +++ b/Documentation/FvwmModules/FvwmAnimate.txt @@ -43,14 +43,14 @@ 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". +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". +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 +Assuming you already had a builtin menu called "+Module-Popup+", you could use *FvwmAnimate* by configuring it like this: ------ @@ -61,65 +61,65 @@ AddToMenu "Module-Popup" "Control Animation" Popup MenuFvwmAnimate CONFIGURATION OPTIONS --------------------- -Since the pop up menu "MenuFvwmAnimate" allows complete control of the +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, +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 +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':: +*FvwmAnimate: Color 'color':: + -Tells *FvwmAnimate* what color to draw with. The color is "XOR'ed" +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 +"+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". +names like "+LightBlue+", or RGB values like "+#FFFFFF+". -\*FvwmAnimate: Pixmap 'pixmap':: +*FvwmAnimate: Pixmap 'pixmap':: + Tells *FvwmAnimate* to use 'pixmap' to draw with. This can be useful if -\**FvwmAnimate: Color* gives poor results. +"+*FvwmAnimate: Color+" gives poor results. -\*FvwmAnimate: Delay 'msecs':: +*FvwmAnimate: Delay 'msecs':: + Tells *FvwmAnimate* how many milliseconds to sleep between frames of animation. -\*FvwmAnimate: Iterations 'iterations':: +*FvwmAnimate: Iterations 'iterations':: + Tells *FvwmAnimate* how many steps to break the animation into. -\*FvwmAnimate: Twist 'twist':: +*FvwmAnimate: Twist 'twist':: + Tells *FvwmAnimate* how many revolutions to twist the iconification frame. -\*FvwmAnimate: Width 'width':: +*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':: +*FvwmAnimate: Effect 'mode':: + Tells *FvwmAnimate* which animation effect to use. Currently the effects are: 'Frame', 'Lines', 'Flip', 'Turn', 'Zoom3D', 'Twist' 'Random', and @@ -136,13 +136,13 @@ 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 +"+.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" +*FvwmAnimate* can be asked to produce an animation thru the *SendToModule* command. The format of the command is: ------ @@ -157,7 +157,7 @@ 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, +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. diff --git a/Documentation/FvwmModules/FvwmAuto.txt b/Documentation/FvwmModules/FvwmAuto.txt index 0ce50edda..5b3970a2b 100644 --- a/Documentation/FvwmModules/FvwmAuto.txt +++ b/Documentation/FvwmModules/FvwmAuto.txt @@ -1,4 +1,4 @@ -FvwmAuto(1) +qFvwmAuto(1) =========== :doctype: manpage @@ -20,7 +20,7 @@ DESCRIPTION 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* can only be invoked by fvwm. Command line invocation of the *FvwmAuto* will not work. @@ -30,8 +30,7 @@ INVOCATION The correct syntax is: ------ -Module FvwmAuto Timeout [-passid] [-menter|-menterleave|-mfocus] -[EnterCommand [LeaveCommand]] +Module FvwmAuto Timeout [-passid] [-menter|-menterleave|-mfocus] [EnterCommand [LeaveCommand]] ------ Example: @@ -64,23 +63,21 @@ 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 +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. +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, +"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: @@ -142,7 +139,7 @@ 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 +"+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. diff --git a/Documentation/FvwmModules/FvwmBacker.txt b/Documentation/FvwmModules/FvwmBacker.txt index 111b2db7e..a46e289c8 100644 --- a/Documentation/FvwmModules/FvwmBacker.txt +++ b/Documentation/FvwmModules/FvwmBacker.txt @@ -20,11 +20,11 @@ DESCRIPTION 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 +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* can only be invoked by fvwm. Command line invocation of the *FvwmBacker* module will not work. @@ -41,15 +41,15 @@ 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*). +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 +*FvwmBacker* can be invoked by fvwm during initialization by inserting the line ------ @@ -58,12 +58,12 @@ 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' +*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'. +option of fvwm for it to be executed by fvwm. CONFIGURATION OPTIONS @@ -83,13 +83,10 @@ 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: -+ ------- +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 @@ -108,18 +105,16 @@ Otherwise the command is sent to fvwm to execute. 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 +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:: @@ -129,11 +124,11 @@ 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, +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' +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*. +using an fvwm function or one of the modules *FvwmCommand* or *FvwmConsole*. Example: @@ -151,7 +146,7 @@ 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: +It is functionally equivalent to omitting the page coordinates with '*FvwmBacker:' 'Command': + ------ *FvwmBacker: Command (Desk Id) command diff --git a/Documentation/FvwmModules/FvwmBanner.txt b/Documentation/FvwmModules/FvwmBanner.txt index baf6fa362..8ffc033ff 100644 --- a/Documentation/FvwmModules/FvwmBanner.txt +++ b/Documentation/FvwmModules/FvwmBanner.txt @@ -19,7 +19,7 @@ DESCRIPTION *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* can only be invoked by fvwm. Command line invocation of the *FvwmBanner* module will not work. COPYRIGHTS @@ -37,18 +37,18 @@ Nothing interesting. INVOCATION ---------- -*FvwmBanner* can be invoked by the command \'Module FvwmBanner'. This +*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: +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. +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 @@ -56,7 +56,7 @@ CONFIGURATION OPTIONS *FvwmBanner: NoDecor:: + -Tells *FvwmBanner* to create a window that 'fvwm' will not manage and +Tells *FvwmBanner* to create a window that fvwm will not manage and not decorate. *FvwmBanner: Pixmap 'file':: diff --git a/Documentation/FvwmModules/FvwmButtons.txt b/Documentation/FvwmModules/FvwmButtons.txt index ea32bfee5..ac3f2b7ec 100644 --- a/Documentation/FvwmModules/FvwmButtons.txt +++ b/Documentation/FvwmModules/FvwmButtons.txt @@ -59,7 +59,7 @@ again when something is selected. INVOCATION ---------- -*FvwmButtons* is spawned by 'fvwm', so command line invocation will not work. +*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 @@ -135,7 +135,7 @@ Specifies that the configuration for this button is found in the file '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 "\". +"+#+". Line continuation is done by ending a line with a "+\+". *FvwmButtons: Font 'font':: + @@ -372,8 +372,8 @@ 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. +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:::: + @@ -619,12 +619,12 @@ The title is justified to the left side. + The title is justified to the right side. + -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. +similar to fvwm's menus. + ActiveTitle 'name':::: Specifies the title to be written on the button when the mouse is hovering @@ -695,7 +695,7 @@ and back 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: +like *FvwmCpp* and want it to get into your commands, like this: + ------ #define BG gray60 @@ -736,7 +736,7 @@ button. Essentially you need nothing more than the Panel option: 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 +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 @@ -795,7 +795,7 @@ panels in your main FvwmButtons configuration: After the last configuration line for the main panel the configuration of the first panel followed, introduced with a line beginning with -\*FvwmButtonsPanel: +*FvwmButtonsPanel: ------ *FvwmButtonsPanel WinOps @@ -826,7 +826,7 @@ new instance of *FvwmButtons* a different name. "Module FvwmButtons Tools") ------ -If you used something like \'Panel-d' you now have to use button was +If you used something like \'+Panel-d+' you now have to use button was selected start *FvwmButtons* with the '-transientpanel' option: ------ @@ -1074,7 +1074,7 @@ 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 +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: diff --git a/Documentation/FvwmModules/FvwmConsole.txt b/Documentation/FvwmModules/FvwmConsole.txt new file mode 100644 index 000000000..23d62d73b --- /dev/null +++ b/Documentation/FvwmModules/FvwmConsole.txt @@ -0,0 +1,134 @@ +FvwmConsole(1) +============== +:doctype: manpage + +NAME +---- + +FvwmConsole - an fvwm command input interface + + +SYNOPSIS +-------- + +Module FvwmConsole [options] + + +DESCRIPTION +----------- + +*FvwmConsole* allows the user to type fvwm configuration commands interactively, +and have them executed immediately. This tool is particularly useful for testing +new configuration ideas, or for implementing temporary changes to your environment. + +*FvwmConsole* can only be invoked by fvwm. Command line invocation of the +*FvwmConsole* module will not work. + + +INVOCATION +---------- + +*FvwmConsole* must be spawned as a module by fvwm. *FvwmConsole* takes all +*xterm*(1) options. + +*FvwmConsole* can be invoked by inserting the line \'+Module FvwmConsole+' in the +.fvwm2rc file. This can be placed on a line by itself, if *FvwmConsole* is to be +spawned during fvwm's initialization, or can be bound to a menu or mouse button +or keystroke to invoke it later. + + +CONFIGURATION OPTIONS +--------------------- + +*FvwmConsole* uses *xterm*(1). All resources set for xterm are inherited unless +overridden by command line options. + +------ +Module FvwmConsole -g 40x10 -fg black -bg green3 +------ + +A different terminal emulator can be specified with the '-terminal' option. +However, only terminal programs that understand the options '-name', '-title' +and '-e' can be used. + +------ +Module FvwmConsole -terminal rxvt +------ + +Previous versions of *FvwmConsole* supported a '-e' option to choose a different +frontend. Although this option is still provided for backwards compatibility +its use is discouraged unless you know exactly what you are doing. + +------ +Module FvwmConsole -e FvwmConsoleC.pl +------ + +(see *FvwmConsoleC.pl*(1)). + +Also X resources can be set in your ~/.Xdefaults file: + +------ +FvwmConsole*VT100*geometry: 40x4 +FvwmConsole*font: 7x14 +------ + + +COMMAND EDITING +--------------- + +There are a few options. If the GNU readline library is available, it can be used. + +If Perl5 is installed, *FvwmConsoleC.pl* can be used as a command editor. This +can be accomplished by either copying *FvwmConsoleC.pl* to fvwmlib directory as +*FvwmConsoleC* or invoking *FvwmConsole* with '-e' option. For example: + +------ +Module FvwmConsole -e FvwmConsoleC.pl +------ + +If neither one is installed, a simple input reading function which doesn't have +editing capabilities is used. + +GNU readline and *FvwmConsoleC.pl* have some frequent used commands in common as +default. These commands are similar to emacs. For more details, refer GNU +readline man and info pages, and *FvwmConsoleC.pl* man page. + +------ +Ctrl-A - beginning of line +Ctrl-B - previous char +Ctrl-D - delete char +Ctrl-E - end of line +Ctrl-F - next char +Ctrl-H - backspace +Ctrl-K - erase to the end of line +Ctrl-N - next line +Ctrl-P - previous line +Ctrl-R - search reverse +Ctrl-U - delete line +Meta-B - previous word +Meta-F - next word +Esc < - beginning of history +Esc > - end of history +------ + + +EXITING +------- + +*FvwmConsole* can be stopped by entering the EOF character (usually CTRL-D). + +[NOTE] +Do not use the "+quit+" command, as this is an fvwm builtin: typing +"+quit+" at the *FvwmConsole* command line will cause fvwm to exit. + + +SEE ALSO +-------- + +*xterm*(1), *FvwmConsoleC.pl*(1), GNU Readline library + + +AUTHOR +------ + +*FvwmConsole* is the original work of Toshi Isogai. diff --git a/Documentation/FvwmModules/FvwmConsoleC.txt b/Documentation/FvwmModules/FvwmConsoleC.txt new file mode 100644 index 000000000..7c0c33610 --- /dev/null +++ b/Documentation/FvwmModules/FvwmConsoleC.txt @@ -0,0 +1,280 @@ +FvwmConsoleC.pl(1) +================== +:doctype: manpage + + +NAME +---- + +FvwmConsoleC.pl - Command editor for fvwm command input interface + + +SYNOPSIS +-------- + +FvwmConsole -e /usr/X11/lib/fvwm/FvwmConsoleC.pl + + +COPYRIGHT +--------- + +Copyright (C) 1996, Toshi Isogai. No guarantees or warranties are provided. 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. + + +DESCRIPTION +----------- + +*FvwmConsoleC.pl* offers editing capabilities while the user is entering the line. +By default, the line editing commands are similar to those of emacs. It also offers +substitution , which replaces a pattern to a string before it sends the command. + + +FUNCTIONS +--------- + +Functions are bound to a key or key combination to be invoked. The followings are +functions available and their default key bindings. + +*bind*:: ++ +'Meta-k', 'Ctrl-x' 'Ctrl-b' ++ +List up key bindings and substitutions. + +*boh*:: ++ +Move to the beginning of history. + +*boh_ign_mode*:: ++ +'Esc-<' ++ +Move to the beginning of history. If it is in search mode, continue. + +*bol*:: ++ +'Home', 'Ctrl-a' ++ +Move cursor to the beginning of the line. + +*bs [(n)]*:: ++ +'BackSpace', 'Ctrl-h' ++ +Backspace n times. default of n is 1. + +*cancel*:: ++ +'Ctrl-x' 'Ctrl-k' ++ +Cancel the current input. + +*del_back_line*:: ++ +Delete the line from the beginning to the cursor. + +*del_back_word*:: ++ +'Ctrl-w' ++ +Delete the word from the beginning to the cursor. + +*del_char [(n)]*:: ++ +'Delete', 'Ctrl-d' ++ +Delete 'n' characters from the cursor to the right. Default of 'n' is 1. + +*del_forw_line*:: ++ +'Ctrl-k' ++ +Delete the line from the cursor to the end. + +*del_forw_word*:: ++ +'Meta-d' ++ +Delete the word from the cursor to the end. + +*del_line*:: ++ +'Ctrl-u' ++ +Delete the entire line. + +*enter*:: ++ +'Enter', 'Ctrl-j', 'Ctrl-m' ++ +Perform substitution if applicable and send the line to fvwm. + +*enter_wo_subst*:: ++ +'Meta-Enter' ++ +Send the line to fvwm without any substitution. + +*eoh*:: ++ +Move to the end of history. + +*eoh_ign_mode*:: ++ +'Esc\->' ++ +Move to the end of history. If it is in search mode, continue. + +*eol*:: ++ +'End', 'Ctrl-e' ++ +Move the cursor to the end of line. + +*ins_char (str)*:: ++ +Insert string at the cursor. + +*ins_last_word*:: ++ +'Esc-.' ++ +Insert the last argument of the previous command at the cursor. + +*ins_nth_word*:: ++ +'Meta-[1..9]' ++ +Insert the n-th argument of the previous command at the cursor. + +*list_func*:: ++ +'Meta-l' ++ +List up available editing functions. + +*next_char*:: ++ +'Right', 'Ctrl-f' ++ +Move the cursor to the next character. + +*next_line*:: ++ +'Down', 'Ctrl-n' ++ +Move to the next line in history. + +*next_word*:: ++ +'Meta-f' ++ +Move the cursor to the next word. + +*prefix*:: ++ +Wait for the next character typed in for multi-key binding. + +*prev_char*:: ++ +'Left', 'Ctrl-b' ++ +Move the cursor to the previous character. + +*prev_line*:: ++ +'Up', 'Ctrl-p' ++ +Move to the previous line in history. + +*prev_word*:: ++ +'Meta-b' ++ +Move the cursor to the previous word. + +*quote*:: ++ +'Ctrl-q' ++ +Insert the next character typed into the buffer literally. + +*search*:: ++ +'Ctrl-s' ++ +Search pattern in history. + +*search_rev*:: ++ +Ctrl-r ++ +Search pattern in history in reverse order. + +*subst*:: ++ +'Meta-s' ++ +Substitute all patterns to strings and reprint the line. The substitutions are +not nested and performed in the order that they are defined. + + +CONFIGURATION +------------- + +The key binding can be overridden or defined in fvwm module configuration. + +------ +*FvwmConsole: Key \ck prev_line +------ + +Non-space character sequence need not be quoted. In order to undefine, omit the +last argument. + +------ +*FvwmConsole: Key \ck +------ + +Note that non-meta character is case sensitive. \c means control key, \e means +escape, and \m is alt key. + +It also accepts Subst configuration. Users often input long fvwm command repeatedly. +Subst will replace particular input sequence to user defined string. Example: + +------ +*FvwmConsole: Subst '^bigx' 'Exec xterm -g 120x60+0+0 -fn 10x20 -fg black -bg lemonchiffon' +------ + +Typing 'bigx' in FvwmConsole will launch xterm. \'^' denotes the beginning +of line in regular expression. \'pl' in the middle of the command will not be +replaced. Although the format looks different, it takes Perl regular expression. +It just uses single or double quote as the delimiter. Single or double quotes +have no difference, although they have to match, and cannot include itself in +the string. + +------ +*FvwmConsole: Subst '^g\s*(\d+)' 'Desk 0 0\nGotoPage 0 $1\nFocus' +------ + +Entering \'g4' or \'g 4' will jump to desk 0 page 0 4 and focus. + + +INVOCATION +---------- + +*FvwmConsoleC.pl* should be invoked by *FvwmConsole*. + + +SEE ALSO +-------- + +*FvwmConsole*(1x), *perlre*(1) + + +AUTHOR +------ + +Toshi Isogai + diff --git a/Documentation/FvwmModules/FvwmCpp.txt b/Documentation/FvwmModules/FvwmCpp.txt new file mode 100644 index 000000000..8226ab994 --- /dev/null +++ b/Documentation/FvwmModules/FvwmCpp.txt @@ -0,0 +1,292 @@ +FvwmCpp(1) +========== +:doctype: manpage + + +NAME +---- + +FvwmCpp - the Fvwm Cpp pre-processor + + +SYNOPSIS +-------- + +Module FvwmCpp [options] filename + + +DESCRIPTION +----------- + +When fvwm executes the *FvwmCpp* module, *FvwmCpp* invokes the cpp +pre-processor on the file specified in its invocation, then *FvwmCpp* +causes fvwm to execute the commands in the resulting file. + +The *FvwmCpp* module can only be invoked by fvwm. Command line invocation +of the *FvwmCpp* module will not work. + + +INVOCATION +---------- + +*FvwmCpp* can be invoked as a module using an fvwm command, from the +.fvwm2rc file, a menu, mousebinding, or any of the many other ways fvwm +commands can be issued. + +If the user wants his entire .fvwm2rc file pre-processed with *FvwmCpp*, +then fvwm should be invoked as: + +------ +fvwm -cmd "Module FvwmCpp .fvwm2rc" +------ + +Note that the argument to the option '-cmd' should be enclosed in quotes, +and no other quoting should be used. + +When *FvwmCpp* runs as a module, it runs asynchronously from fvwm. If +*FvwmCpp* is invoked from the .fvwm2rc, the commands generated by +*FvwmCpp* may or may not be executed by the time fvwm processes the next +command in the .fvwm2rc. Invoke *FvwmCpp* this way for synchronous execution: + +------ +ModuleSynchronous FvwmCpp -lock filename +------ + + +OPTIONS +------- + +Some options can be specified following the modulename: + +'-cppopt' 'option':: ++ +Lets you pass an 'option' to the cpp program. Not really needed as any +unknown options will be passed on automatically. + +'-cppprog' 'name':: ++ +Instead of invoking "+/usr/lib/cpp+", fvwm will invoke 'name'. + +'-outfile' 'filename':: ++ +Instead of creating a random unique name for the temporary file for the +preprocessed rc file, this option will let you specify the name of the +temporary file it will create. Please note that *FvwmCpp* will attempt +to remove this file before writing to it, so don't point it at anything +important even if it has read-only protection. + +'-debug':: ++ +Causes the temporary file create by Cpp to be retained. This file is +usually called "+/tmp/fvwmrcXXXXXX+". + +'-lock':: ++ +If you want to use this option you need to start *FvwmCpp* with +'ModuleSynchronous'. This option causes fvwm to wait that the pre-process +finish and that *FvwmCpp* asks fvwm to Read the pre-processed file before +continuing. This may be useful at startup if you use a session manager +as Gnome. Also, this is useful if you want to process and run a Form in +a fvwm function. + +'-noread':: ++ +Causes the pre-processed file to be not read by fvwm. Useful to +pre-process a *FvwmScript* script with *FvwmCpp*. + + +CONFIGURATION OPTIONS +--------------------- + +*FvwmCpp* defines some values for use in the pre-processor file: + ++TWM_TYPE+:: ++ +Always set to "fvwm". + ++SERVERHOST+:: ++ +The name of the machine running the X Server. + ++CLIENTHOST+:: ++ +The name of the machine running fvwm. + ++HOSTNAME+:: ++ +The host name of the machine running fvwm. Generally the same as ++CLIENTHOST+. + ++OSTYPE+ ++ +The operating system for +CLIENTHOST+. + ++USER+:: ++ +The name of the person running fvwm. + ++HOME+:: ++ +The home directory of the person running fvwm. + ++VERSION+:: ++ +The X11 version. + ++REVISION+:: ++ +The X11 revision number. + ++VENDOR+:: ++ +The X server vendor. + ++RELEASE+:: ++ +The X server release number. + ++SCREEN+:: ++ +The screen number. + ++WIDTH+:: ++ +The screen width in pixels. + ++HEIGHT+:: ++ +The screen height in pixels. + ++X_RESOLUTION+:: ++ +Some distance/pixel measurement for the horizontal direction, I think. + ++Y_RESOLUTION+:: ++ +Some distance/pixel measurement for the vertical direction, I think. + ++PLANES+:: ++ +Number of color planes for the X server display + ++BITS_PER_RGB+:: ++ +Number of bits in each rgb triplet. + ++CLASS+:: ++ +The X11 default visual class, e.g. PseudoColor. + ++COLOR+:: ++ +Yes or No, Yes if the default visual class is neither 'StaticGrey' or 'GreyScale'. + ++FVWM_CLASS+:: ++ +The visual class that fvwm is using, e.g. TrueColor. + ++FVWM_COLOR+:: ++ +Yes or No, Yes if the +FVWM_CLASS+ is neither 'StaticGrey' or 'GreyScale'. + ++FVWM_VERSION+:: ++ +The fvwm version number, ie 2.0 + ++OPTIONS+:: ++ +Some combination of 'SHAPE', 'XPM', 'NO_SAVEUNDERS', and 'Cpp', as +defined in configure.h at compile time. + ++FVWM_MODULEDIR+:: ++ +The directory where fvwm looks for .fvwm2rc and modules by default, as +determined at compile time. + ++FVWM_USERDIR+:: ++ +The value of '$FVWM_USERDIR'. + ++SESSION_MANAGER+:: ++ +The value of '$SESSION_MANAGER'. Undefined if this variable is not set. + + +EXAMPLE PROLOG +-------------- + +------ +#define TWM_TYPE fvwm +#define SERVERHOST spx20 +#define CLIENTHOST grumpy +#define HOSTNAME grumpy +#define OSTYPE SunOS +#define USER nation +#define HOME /local/homes/dsp/nation +#define VERSION 11 +#define REVISION 0 +#define VENDOR HDS human designed systems, inc. (2.1.2-D) +#define RELEASE 4 +#define SCREEN 0 +#define WIDTH 1280 +#define HEIGHT 1024 +#define X_RESOLUTION 3938 +#define Y_RESOLUTION 3938 +#define PLANES 8 +#define BITS_PER_RGB 8 +#define CLASS PseudoColor +#define COLOR Yes +#define FVWM_VERSION 2.0 pl 1 +#define OPTIONS SHAPE XPM Cpp +#define FVWM_MODULEDIR /local/homes/dsp/nation/modules +#define FVWM_USERDIR /local/homes/dsp/nation/.fvwm +#define SESSION_MANAGER local/grumpy:/tmp/.ICE-unix/440,tcp/spx20:1025 +------ + + +BUGS +---- + +Module configurations do not become active until fvwm has restarted if +you use *FvwmCpp* on startup. *FvwmCpp* creates a temporary file and +passes this to fvwm, so you would have to edit this file too. There are +some problems with comments in your .fvwm2rc file. The comment sign \'#' +is misinterpreted by the preprocessor. This has usually no impact on +functionality but generates annoying warning messages. The sequence \'/\*' +is interpreted as the start of a C comment what is probably not what you +want in a filename. You might want to try \'/?\*' (for filenames only) or +\'/\\*' or "/\*" instead. Depending on your preprocessor you may have the +same problem with "//". Macros are not replaced within single (') or +double quotes ( back quotes (`) to circumvent this. Fvwm accepts back +quotes for quoting and at least *FvwmButtons* does too. The preprocessor +may place a space after a macro substitution, so with + +------ +#define MYCOMMAND ls "Exec "MYCOMMAND" -l" +------ + +you might get + +------ +"Exec "ls " -l" (two words) +------ + +and not + +------ +"Exec "ls" -l" (one word). +------ + +If you use gcc you can use this invocation to turn off \'//' comments: + +------ +FvwmCpp -Cppprog '/your/path/to/gcc -C -E -' +------ + + +AUTHOR +------ + +*FvwmCpp* is the result of a random bit mutation on a hard disk, +presumably a result of a cosmic-ray or some such thing. + diff --git a/Documentation/FvwmModules/FvwmDebug.txt b/Documentation/FvwmModules/FvwmDebug.txt new file mode 100644 index 000000000..8bfd2a3c9 --- /dev/null +++ b/Documentation/FvwmModules/FvwmDebug.txt @@ -0,0 +1,125 @@ +FvwmDebug(1) +============ +:doctype: manpage + +NAME +---- + +FvwmDebug - the fvwm module debugger + +SYNOPSIS +-------- + +*FvwmDebug* should be spawned by *fvwm*(1) for normal functionality. + +To run this module, place this command somewhere in the configuration: + +------ +Module FvwmDebug [optional-params] +------ + +To stop this module, execute: + +------ +KillModule FvwmDebug +------ + +DESCRIPTION +----------- + +This module persistently dumps all fvwm event details and optionally some other +information into the standard error stream or a file, good for debugging purposes. +The output may be optionally redirected to 'xconsole' or similar window. + +INVOCATION +---------- + +There are several command line switches: + +------ +FvwmDebug [ --args|--noargs ] [ --events|--noevents ] [ --log 'file' ] [ --xconsole ] [ --mask 'mask' ] + [ --xmask 'mask' ] [ --debug 'level' ] [ --track 'tracker-name' ] [ --send-configinfo ] [ --send-windowlist ] +------ + +Long switches may be abbreviated to shorter switches. + +'--noargs':: ++ +do not print all arguments of the event, just its name. '--args' is the default. + +'--noevents':: ++ +do not print even event names, implies '--noargs'. It is similar in effect to +setting both '--mask' and '--xmask' to 0, but the events are actually received +by the module, they are just not printed. ++ +This option may be useful if '--track' or/and '--debug' is used. ++ +The default is '--events' normally, and '--noevents' if one or more '--track' +options specified. + +'-l'|'--log' 'file':: ++ +specify the log file name instead of the standard error stream. If the log file +can't be open for writting, the default standard error stream is used. ++ +The file may start with a pipe \'|\', this is similar to the usual meaning of a +pipe, the output is piped to the specified command. See also '--xconsole' option. + +'-xc'|'--xconsole':: ++ +this is a shortcut for: ++ +------ +FvwmDebug --log '|xconsole -file /dev/stdin -geometry 600x400 -notify' +------ ++ +That shows the module output in the xconsole window rather than the standard +error stream. + +'-m'|'--mask' 'mask':: ++ +set the module mask, 31 bit integer. By default almost all events are monitored +(except for some flood events like +CONFIGURE_WINDOW+ or +FOCUS_WINDOW+. The +special value of -1 sets the maximal mask. + +'-x'|'--xmask' 'mask':: ++ +set the module extended mask, 31 bit integer. By default almost all events are +monitored (except for some flood events like +ENTER_WINDOW+ or +LEAVE_WINDOW+. +The special value of -1 sets the maximal extended mask. + +'-d'|'--debug' 'level':: ++ +use the Perl library debugging mechanism. The useful levels are 2 to 4. + +'-t'|'--track' 'tracker-name':: ++ +create the given Perl library tracker and observe its main observable. This +option may be specified multiple times. This options implies '--noevents' +unless explicitely overwritten. You may optionally try '--debug', for example: ++ +------ +FvwmDebug -xc --track PageInfo --track GlobalConfig --debug 3 +------ ++ +Run "+fvwm-perllib man+" to get the names of all existing trackers in your +installed Perl library. + +'-sc'|'--send-configinfo':: +send 'Send_ConfigInfo' command to fvwm on startup, this results in a lot of +events received. + +'-sw'|'--send-windowlist':: +send 'Send_WindowList' command to fvwm on startup, this results in a lot of +events received. + +SEE ALSO +-------- + +*FvwmGtkDebug* + +AUTHOR +------ + +Mikhael Goikhman . From 03869c4537e54d654f91346b8a996144b8e175a6 Mon Sep 17 00:00:00 2001 From: Thomas Funk Date: Sat, 25 Feb 2012 14:37:11 +0100 Subject: [PATCH 03/16] FvwmModules TODO list --- Documentation/FvwmModules/TODO | 35 ++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 Documentation/FvwmModules/TODO diff --git a/Documentation/FvwmModules/TODO b/Documentation/FvwmModules/TODO new file mode 100644 index 000000000..fd0d0e365 --- /dev/null +++ b/Documentation/FvwmModules/TODO @@ -0,0 +1,35 @@ +List of not converted Fvwm modules: + +FvwmCommand *in work* +FvwmConsole +FvwmConsoleC.pl +FvwmCpp +FvwmDragWell +FvwmEvent +FvwmForm +FvwmGtk (deprecated?) +FvwmGtkDebug (deprecated?) +FvwmIconBox (deprecated?) +FvwmIconMan +FvwmIdent +FvwmM4 +FvwmPager +FvwmPerl +FvwmProxy +FvwmRearrange +FvwmSave (deprecated?) +FvwmSaveDesk (deprecated?) +FvwmScript +FvwmScroll +FvwmTabs +FvwmTaskBar +FvwmTheme +FvwmWharf +FvwmWindowMenu +FvwmWinList +fvwm-bug +fvwm-config +fvwm-convert-2.2 +fvwm-convert-2.4 +fvwm-convert-2.6 +fvwm-root From ea3552dfedb6e5bfd31a413b65dc9d0e940b2f7b Mon Sep 17 00:00:00 2001 From: Thomas Funk Date: Sat, 25 Feb 2012 14:59:43 +0100 Subject: [PATCH 04/16] Add format conventions docu to use with creating manpages --- Documentation/format_conventions.txt | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 Documentation/format_conventions.txt diff --git a/Documentation/format_conventions.txt b/Documentation/format_conventions.txt new file mode 100644 index 000000000..5a5f546c2 --- /dev/null +++ b/Documentation/format_conventions.txt @@ -0,0 +1,28 @@ +manpage conventions + +For a consistent look the following convention should be used in the +asciidoc formated manpages: + +fvwm commands: bold with ** + +parameters/arguments: underlined with '' + +Constants: fixed size with ++ + +Notes: [NOTE] + + +Examples: ------ + * + +emails: + +manpage references: bold with **(1) + +commands or commandstrings +inside text: fixed size wthin apostrophes like + \'++' + From 9f596d1cdea346f19569c26887bdb61550248d83 Mon Sep 17 00:00:00 2001 From: Thomas Funk Date: Thu, 1 Mar 2012 23:47:24 +0100 Subject: [PATCH 05/16] New FvwmModules manpages E-T --- Documentation/FvwmModules/FvwmEvent.txt | 326 ++++++++ Documentation/FvwmModules/FvwmForm.txt | 800 ++++++++++++++++++++ Documentation/FvwmModules/FvwmIdent.txt | 98 +++ Documentation/FvwmModules/FvwmM4.txt | 263 +++++++ Documentation/FvwmModules/FvwmPager.txt | 450 +++++++++++ Documentation/FvwmModules/FvwmRearrange.txt | 211 ++++++ Documentation/FvwmModules/FvwmScroll.txt | 92 +++ Documentation/FvwmModules/FvwmTheme.txt | 533 +++++++++++++ Documentation/FvwmModules/TODO | 12 - 9 files changed, 2773 insertions(+), 12 deletions(-) create mode 100644 Documentation/FvwmModules/FvwmEvent.txt create mode 100644 Documentation/FvwmModules/FvwmForm.txt create mode 100644 Documentation/FvwmModules/FvwmIdent.txt create mode 100644 Documentation/FvwmModules/FvwmM4.txt create mode 100644 Documentation/FvwmModules/FvwmPager.txt create mode 100644 Documentation/FvwmModules/FvwmRearrange.txt create mode 100644 Documentation/FvwmModules/FvwmScroll.txt create mode 100644 Documentation/FvwmModules/FvwmTheme.txt diff --git a/Documentation/FvwmModules/FvwmEvent.txt b/Documentation/FvwmModules/FvwmEvent.txt new file mode 100644 index 000000000..56744fdea --- /dev/null +++ b/Documentation/FvwmModules/FvwmEvent.txt @@ -0,0 +1,326 @@ +FvwmEvent(1) +============ +:doctype: manpage + + +NAME +---- + +FvwmEvent - the fvwm event module + + +SYNOPSIS +-------- + +*FvwmEvent* is a more versatile replacement for *FvwmAudio*. It can in +general be used to hook any fvwm function or program to any window +manager event. E.g: Delete unwanted Netscape Pop ups or application error +pop ups as they appear, play sounds, log events to a file and the like. +Be creative, you'll find a use for it. + +*FvwmEvent* is spawned by fvwm, so no command line invocation will work. +From within the .fvwm2rc file, *FvwmEvent* is spawned as follows: + +------ +Module FvwmEvent +------ + +or from within an fvwm pop-up menu: + +------ +DestroyMenu Module-Popup +AddToMenu Module-Popup "Modules" Title ++ "Event" Module FvwmEvent ++ "Auto" Module FvwmAuto 200 ++ "Buttons" Module FvwmButtons ++ "Console" Module FvwmConsole ++ "Ident" Module FvwmIdent ++ "Banner" Module FvwmBanner ++ "Pager" Module FvwmPager 0 3 +------ + + +DESCRIPTION +----------- + +The *FvwmEvent* module communicates with the fvwm window manager to bind +'actions' to window manager 'events'. Different actions may be assigned +to distinct window manager events. + +*FvwmEvent* can be used to bind sound files to events like *FvwmAudio* + (RiP) did. It can be used for logging event traces to a log file, while debugging fvwm. + +*FvwmEvent* can also have builtin support for the *rplay* library. +(heritage of *FvwmAudio*) + + +INVOCATION +---------- + +The invocation method was shown in the *SYNOPSIS* section. No command +line invocation is possible. *FvwmEvent* must be invoked by the fvwm +window manager. *FvwmEvent* accepts a single argument: + +'-audio':: ++ +Enables FvwmAudio compatibility mode. + +'alias':: ++ +Makes *FvwmEvent* use 'alias' as its name. This affects which lines from +the user's configuration file are used. ++ +Invoking *FvwmEvent* as *FvwmAudio* (either by using an alias or creating +a symlink) enables *FvwmAudio* compatibility mode. + + +CONFIGURATION OPTIONS +--------------------- + +*FvwmEvent* gets config info from fvwm's module configuration database +(see *fvwm*(1), section *MODULE COMMANDS*), and looks for certain +configuration options: + +*FvwmEvent: Cmd 'command':: ++ +This determines the fvwm function that is to be called with the event +parameters. You might want to do one of the following (details below): ++ +------ +# play sounds +*FvwmEvent: Cmd 'builtin-rplay' + +# execute distinct fvwm functions +*FvwmEvent: Cmd + +# execute distinct external programs +*FvwmEvent: Cmd exec +------ ++ +This version of *FvwmEvent* has builtin rplay support which does not +need to invoke an external audio player to play sounds. The rplay support +is enabled when *FvwmEvent* is compiled with +HAVE_RPLAY+ defined and +when "+FvwmEvent: Cmd+" is set to 'builtin-rplay'. See remarks below if +*FvwmEvent* is invoked in *FvwmAudio* compatibility mode. ++ +For example: ++ +------ +*FvwmEvent: Cmd 'builtin-rplay' +*FvwmEvent: add_window drip.au +------ ++ +rplay can be obtained via anonymous ftp at ++ +ftp://ftp.sdsu.edu/pub/rplay or +ftp://ftp.x.org/contrib/Event/audio/rplay ++ +*FvwmEvent* also has support for any other external program. e.g: the +rsynth 'say' command: ++ +------ +*FvwmEvent: Cmd "Exec /rsynth/say" +*FvwmEvent: destroy_window "window closed" +------ ++ +You can also use fvwm's builtin *Echo* command as "+FvwmEvent: Cmd+" +to obtain debug output for fvwm events quietly. I used this setup to +debug *FvwmAuto*: ++ +------ +*FvwmEvent: Cmd Echo +*FvwmEvent: focus_change "focus change" +*FvwmEvent: raise_window "raise window" +------ ++ +You can even call different shell commands for each event just by setting ++ +------ +*FvwmEvent: Cmd exec +*FvwmEvent: add_window 'killname "APPL ERROR"' +------ + +*FvwmEvent: 'PassId':: ++ +Specifies that the event action will have an ID parameter added to the +end of the command line. Most events will have the windowID of the window +that the event refers to, 'new_desk' will have the new desk number. The +windowID is a hexadecimal string preceded by +0x+, desk numbers are decimal. + +*FvwmEvent: 'window-manager-event' 'action-or-filename':: ++ +Binds particular actions to window manager events. ++ +e.g. for audio-events: ++ +------ +*FvwmEvent: startup TaDa.au +*FvwmEvent: shutdown Elvis_Left.au +*FvwmEvent: unknown doh.au + +*FvwmEvent: new_page beam_trek.au +*FvwmEvent: new_desk beam_trek.au +*FvwmEvent: old_add_window drip.au +*FvwmEvent: raise_window swoosh.au +*FvwmEvent: lower_window swoosh.au +*FvwmEvent: old_configure_window hammer.au +*FvwmEvent: focus_change boing.au +*FvwmEvent: enter_window boing.au +*FvwmEvent: leave_window boing.au +*FvwmEvent: destroy_window explosion.au +*FvwmEvent: iconify ploop.au +*FvwmEvent: deiconify ploop.au +*FvwmEvent: window_name huh.au +*FvwmEvent: icon_name beep.au +*FvwmEvent: visible_icon_name beep.au +*FvwmEvent: res_class beep.au +*FvwmEvent: res_name beep.au +*FvwmEvent: end_windowlist twang.au + +*FvwmEvent: icon_location beep.au +*FvwmEvent: map beep.au +*FvwmEvent: error beep.au +*FvwmEvent: config_info beep.au +*FvwmEvent: end_config_info beep.au +*FvwmEvent: icon_file beep.au +*FvwmEvent: default_icon beep.au +*FvwmEvent: string plapper.au +*FvwmEvent: mini_icon beep.au +*FvwmEvent: windowshade beep.au +*FvwmEvent: dewindowshade beep.au + +*FvwmEvent: visible_name beep.au +*FvwmEvent: sendconfig beep.au +*FvwmEvent: restack beep.au +*FvwmEvent: add_window beep.au +*FvwmEvent: configure_window beep.au + +*FvwmEvent: visible_icon_name beep.au +*FvwmEvent: enter_window beep.au +*FvwmEvent: leave_window beep.au +*FvwmEvent: property_change beep.au +------ ++ +The window related event handlers are executed within a window context. +Previously PassId was used for this purpose, but now using 'PassId' is not +needed. ++ +[NOTE] +The 'enter_window' event is generated when the pointer enters a window. +With the '-passid' option, that window's id is passed to fvwm. An +'enter_window' event is generated too when the pointer leaves a window +and moves into the root window. In this case, the id passed is 0. ++ +[NOTE] +When the 'shutdown' event arrives, *FvwmEvent* may be killed before it +can trigger the associated action. ++ +Provided fvwm supports it (not yet), there's an additional event to +replace all fvwm beeps with a sound: ++ +------ +*FvwmEvent: beep beep.au +------ ++ +The toggle_paging event will be supported, as soon, as it's resurrected +by fvwm: ++ +------ +*FvwmEvent: toggle_paging fwop.au +------ + +*FvwmEvent: Delay '5':: ++ +Specifies that an event-action will only be executed if it occurs at +least 5 seconds after the previous event. Events that occur during the +delay period are ignored. This option is useful if you don't want +several sounds playing at the same time. The default delay is 0 which +disables the Event delay. + +*FvwmEvent: StartDelay 'delay':: ++ +Specifies that an event-action will only be executed if it occurs at +least delay seconds after the startup event. Events that occur during +the delay period are ignored. This option is useful when fvwm starts +and restarts using an audio player. The default delay is 0. + + +RPLAY OPTIONS +------------- + +The following options are only valid with builtin rplay support. i.e: +when *FvwmEvent* was compiled with +HAVE_RPLAY+ defined. They are used +only if "+FvwmEvent: Cmd+" is set to 'builtin-rplay'. + +*FvwmEvent: RplayHost 'hostname':: ++ +Specifies what host the rplay sounds will play on. The 'hostname' can +also be an environment variable such as +$HOSTDISPLAY+. + +*FvwmEvent: RplayPriority '0':: ++ +Specifies what priority will be assigned to the rplay sounds when they +are played. + +*FvwmEvent: RplayVolume '127':: ++ +Specifies what volume will be assigned to the sounds when they are played. + +FvwmAudio Compatibility Mode +---------------------------- + +When invoked in *FvwmAudio* compatibility mode (see above), *FvwmEvent* +accepts the following options to provide backwards compatibility for +*FvwmAudio*: + +*FvwmEvent: PlayCmd 'command':: ++ +This is equivalent to using "+\*FvwmEvent: Cmd+" to *Exec* commands. This +determines the independent audio player program that will actually play +the sounds. If the play command is set to 'builtin-rplay' then the builtin +rplay support will be used. + +*FvwmAudio: Dir 'directory':: ++ +Specifies the directory to look for the audio files. This option is +ignored when rplay is used. + + +BUGS +---- + +It's REALLY noisy when fvwm starts and restarts using an audio player. +You can use "+FvwmEvent: StartDelay+" to fix this problem. + + +COPYRIGHTS +---------- + +This module has evolved of *FvwmAudio*, which in term is heavily based +on a similar Fvwm module called *FvwmSound* by Mark Boyns. *FvwmAudio* +simply took Mark's original program and extended it to make it generic +enough to work with any audio player. Due to different requests to do +specific things on specific events, *FvwmEvent* took this one step +further and now calls any fvwm function, or 'builtin-rplay'. If fvwm's +*Exec* function is used, any external program can be called with any parameter. + +The concept for interfacing this module to the Window Manager, is +original work by Robert Nation. + +Copyright (C) 1998 Albrecht Kadlec. Copyright (C) 1994, Mark Boyns and +Mark Scott. No guarantees or warranties or anything are provided or +implied in any way whatsoever. Use this program at your own risk. +Permission to use and modify this program for any purpose is given, as +long as the copyright is kept intact. + + +AUTHORS +------- + +1994 FvwmSound Mark Boyns + +1994 FvwmAudio Mark Scott + +1996 FvwmAudio Albrecht Kadlec + +1998 FvwmEvent Albrecht Kadlec diff --git a/Documentation/FvwmModules/FvwmForm.txt b/Documentation/FvwmModules/FvwmForm.txt new file mode 100644 index 000000000..44ebda060 --- /dev/null +++ b/Documentation/FvwmModules/FvwmForm.txt @@ -0,0 +1,800 @@ +FvwmForm(1) +=========== +:doctype: manpage + + +NAME +---- + +FvwmForm - input form module for Fvwm + + +SYNOPSIS +-------- + +Module FvwmForm [ Alias ] + + +DESCRIPTION +----------- + +*FvwmForm* must be spawned by Fvwm. If invoked from the command line, +*FvwmForm* prints its version number and exits. + +*FvwmForm* provides a mechanism to get user input and act accordingly. +This is achieved by means of a form that the user can fill out, and from +which the user can select actions he wants Fvwm to take. A form consists +of five types of items: 'text labels', 'single-line text inputs', +'mutually-exclusive selections', 'multiple-choice selections', and 'action +buttons'. These items are arranged into several lines, with a very +flexible layout. + +A 'text label' only serves the purpose of explanation. It cannot accept +any input. + +A 'timeout entry' provides a mechanism for timing out the form and +performing a certain action when the timeout occurs. The countdown is +displayed similar to a text label except that it updates with the amount +of time left. + +A 'text input field' can be used to edit a single-line string. *FvwmForm* +accepts Emacs-style cursor movement keys. See FvwmFormInput for details. +Mouse copy is not supported, but you can paste. + +A 'selection' consists of several choices. + +The 'selection' itself is a logical entity that doesn't have any display +feature. + +Each 'choice' is displayed as a push-button followed by a explanatory text +label. When selected, an exclusive choice shows a circle in the middle, +while a multiple choice shows a check. + +An 'action button', when activated sends one or more commands to Fvwm or +executes shell commands. The shell commands can contain the content of +the input fields on the form and reflect the setting of choices on the +form. + +The 'action buttons' can be activated thru keyboard or mouse. + + +INITIALIZATION +-------------- + +*FvwmForm* invoked without an alias uses configuration commands starting +with "+*FvwmForm+". + +Normally you would invoke *FvwmForm* with an alias representing the name +of a form, its configuration commands and configuration file. For example, +the command "+Module FvwmForm Rlogin+" uses configuration commands +starting with "+*Rlogin+", and reads the optional configuration file \'Rlogin'. + +All forms, regardless of alias, scan first for configuration commands +that start with "+*FvwmFormDefault+". These commands normally come from +the builtin form "FvwmForm-Form" which saves commands to the file ".FvwmForm". + +The physical reading of the optional input file, ".FvwmForm", is done +only the first time *FvwmForm* is invoked, or after "FvwmForm-Form" +updates the file. + +When the file ".FvwmForm" is read, it is done by sending the command +"+Read .FvwmForm Quiet+" to fvwm. Because of the way the 'read' command +works, the file can reside in your personal fvwm user directory, or be +in the fvwm data directory. See the description of the 'read' command +in the fvwm man page for more information about the environment variable ++$FVWM_USERDIR+. + +Then *FvwmForm* reads the rest of the configuration fvwm has stored up. +Fvwm stores configuration on an ongoing basis. The initial configuration +comes from the .fvwm2rc file. Other sources, including 'Read' commands +can define a form. + +When letting *FvwmForm* and fvwm read files, remember that these files +contain commands that can execute shell commands, so you should be +careful about setting permissions on these files. + +When *FvwmForm* is invoked with a window context, e.g. from a window +menu, all commands it sends to Fvwm will have that window context. +This would allow *FvwmForm* to control the window it is invoked from. + +After all the configuration commands have been read, *FvwmForm* displays +the form defined by the commands. + + +DEFAULTS +-------- + +*FvwmForm* creates a built-in form named "FvwmForm-Form" that creates a +file called ".FvwmForm". This file contains saved default form colors +and fonts. Other forms use these defaults unless they are overridden +within the form. + +The default creating form would normally be invoked from a "module menu". +For example, if you call your module menu "Module-Popup", you would add +the line: + +------ +AddToMenu "Module-Popup" "FvwmForm Defaults" FvwmForm FvwmForm-Form +------ + +When you select "FvwmForm Defaults" from your module menu, a form is +displayed that shows the current defaults and allows you to change them. +If you activate the "Save Restart Me" button, the ".FvwmForm" file is +written and "FvwmForm-Form" exits and restarts to show the new defaults. + +An example of what this file might contain after a save is: + +------ +# This file last created by FvwmForm-Form on Sun Nov 28 11:18:26 EST 1999. +*FvwmFormDefault: Font 10x20 +*FvwmFormDefault: InputFont 8x13bold +*FvwmFormDefault: ButtonFont 10x20 +*FvwmFormDefault: TimeoutFont 10x20 +*FvwmFormDefault: Fore white +*FvwmFormDefault: Back cornflowerblue +*FvwmFormDefault: Colorset -1 +*FvwmFormDefault: ItemFore green +*FvwmFormDefault: ItemBack gray40 +*FvwmFormDefault: ItemColorset -1 +*FvwmFormDefault: ButtonPointer hand2 +*FvwmFormDefault: ButtonInPointer star +*FvwmFormDefault: InputPointer gumby +*FvwmFormDefault: ButtonPointerFore blue +*FvwmFormDefault: ButtonPointerBack gray +*FvwmFormDefault: ButtonInPointerFore gray +*FvwmFormDefault: ButtonInPointerBack blue +*FvwmFormDefault: InputPointerFore +*FvwmFormDefault: InputPointerBack +------ + +The commands in this file are just like any other *FvwmForm* command +except that they start with "*FvwmFormDefault". + +*FvwmForm* only reads the file ".FvwmForm" the first time it is started +or after the file is changed by "FvwmForm-Form". It does so by sending +the command "+\*FvwmFormDefault: Read x+". With "x" set to "y" or "n". +"n" makes *FvwmForm* send a "+read .FvwmForm quiet+" command to fvwm. + + +VARIABLE SUBSTITUTION +--------------------- + +If you supply variables and values on the command line used to start +*FvwmForm* (like this): + +------ +Module FvwmForm MyForm ACTION=Browse "TITLE=Browse Form" +------ + +Then all *FvwmForm* input commands undergo variable substitution. The +variables from the command line are exported. Then every command gets +expanded using the variables from the environment. For example, assuming +the above invocation of "MyForm", commands would be changed like this: + +*Before:*:: ++ +------ +*MyForm: Text "$TITLE, Home $HOME, Going to $ACTION" +------ + +*After:*:: ++ +------ +*MyForm: TEXT "Browse Form, Home /home/me, Going to Browse" +------ + +Using this facility should make it possible for one form to be used for +different sets of input data. + +CONFIGURATION +------------- + +The following commands can be set in the .fvwm2rc file or thru any of +the other ways that fvwm can accept commands. The simplest technique is +to create a file in the read-only architecture-independent data +directory, [PREFIX/share/fvwm] or your personal fvwm directory +[$HOME/.fvwm], that matches the form alias. + +In the following paragraphs the string "FvwmForm" would normally be the +form alias. + +*FvwmForm* reads commands before the form is ever displayed, and while +the form is being displayed. + +The following commands are accepted before the form is displayed: + +------ +Back +Button +ButtonFont +ButtonInPointer +ButtonInPointerFore +ButtonInPointerBack +ButtonPointer +ButtonPointerFore +ButtonPointerBack +Choice +Command +Colorset +Font +Fore +GrabServer +Input +InputFont +InputPointer +ItemBack +ItemColorset +ItemFore +InputPointerFore +InputPointerBack +Line +Message +PadVText +Position +Selection +Text +Timeout +TimeoutFont +Title +UseData +WarpPointer +------ + +The following commands are accepted while the form is displayed: + +------ +Map +Stop +UnMap +------ + +The 'Map', 'UnMap' and 'Stop' facility is under development and is +currently not explained in this document, since it is likely to change. + +The order of the options DOES matter. The first background text color, +"*FvwmFormBack", encountered before a displayable item sets the default +background color for the entire form. + +Other than that, colors, fonts, text, choices and buttons can be +intermixed in any order. The are no builtin limits on form size, number +of items on a form, or number of fonts or colors used. + +*FvwmForm: GrabServer:: ++ +This option makes *FvwmForm* grab the mouse pointer on startup. This +feature is useful for things like logout verification. + +*FvwmForm: WarpPointer:: ++ +This option makes *FvwmForm* warp the mouse pointer into its window on +startup. It saves the user some mouse-travelling. + +*FvwmForm: Geometry 'geometry':: ++ +Specifies the *FvwmForm* window location. This is similar to what the +Position option does but is more flexible. + +*FvwmForm: Position 'x' 'y':: ++ +Puts the *FvwmForm* window at location ('x', 'y') on the screen. By +convention, a negative 'x' ('y') value measures distance from the right +(bottom) of the screen. ++ +If this option is omitted, *FvwmForm* starts at the center of the screen. + +*FvwmForm: Colorset 'n':: ++ +Tells the module to use colorset 'n'. See *FvwmTheme*. + +*FvwmForm: Back 'color':: ++ +Specifies the background color of the *FvwmForm* window and any text in +the window. The first background color *FvwmForm* reads determines the +overall screen background color. Switches off the Colorset option. +See +DEFAULTS+. + +*FvwmForm: Fore 'color':: ++ +Specifies the foreground color for displaying text labels. Switches off +the Colorset option. See +DEFAULTS+. + +*FvwmForm: ItemColorset 'n':: ++ +Tells the module to use colorset 'n' for items. See *FvwmTheme*. + +*FvwmForm: ItemBack 'color':: ++ +Specifies the background color for the text input windows, and the +buttons. Buttons are displayed as 3D depressable buttons. Inputs are +displayed as 3D indented fields. Medium shade background colors work +best. Switches off the ItemColorset option. See +DEFAULTS+. + +*FvwmForm: ItemFore 'color':: ++ +Specifies the foreground color for the text input strings and button +text. Switches off the ItemColorset option. See +DEFAULTS+. + +*FvwmForm: Font 'font':: ++ +Specifies the font for displaying plain text. See +DEFAULTS+. + +*FvwmForm: ButtonFont 'font':: ++ +Specifies the font for text in the action buttons. See +DEFAULTS+. + +*FvwmForm: InputFont 'font':: ++ +Specifies the font for text input. See +DEFAULTS+. + +*FvwmForm: TimeoutFont 'font':: ++ +Specifies the font for display the timeout counter and related text. +See +DEFAULTS+. + +*FvwmForm: Line 'justification':: ++ +Starts a new line. A line can contain any number of text, input, buttons +and choice items. A *FvwmForm* window can have any number of lines. The +width of the window is that of the longest line. ++ +Justification of items in the line is specified by 'justification', which +can be one of the following: ++ +left::: Items are justified to the left of the window. ++ +right::: Items are justified to the right of the window. ++ +center::: Items are placed in the center of the window. ++ +expand::: If there is only one item in the line, the item is centered in +the window. If two or more items are present, they are spread to fill +the whole width of the window. + +*FvwmForm: Message:: ++ +Defines a text area on the form that contains the last error message +from fvwm. For purposes of determining form size, the message area is +considered to be 80 bytes long. Its actual length is the same as the +message received. If the message exceeds 80 bytes, you can see the rest +of the message by resizing the form. ++ +You should not attempt to put any text, buttons or input fields on the +same line after a message field. Messages greater than 80 bytes will +overlay the remainder of the line. + +*FvwmForm: PadVText 'Pixels':: ++ +The number of pixels used as vertical padding between text items, line +to line. The default is 6 which looks good on lines containing text +intermixed with input boxes, choices or buttons. ++ +For straight text, such as might appear on a help form, padding of zero +looks better. ++ +(There are lots of other padding values used in form layout which can't +currently be changed with commands.) + +*FvwmForm: Text 'string':: +Displays 'string' as plain text. Line breaks must be achieved by multiple +"+*FvwmForm: Line+" and "+*FvwmForm: Text+" options. Blanks may be used +to provide extra padding between items. + +*FvwmForm: Title 'string':: ++ +Displays 'string' as the window's title. The string must be enclosed in +double quotes. Using this command with anything other than a string +enclosed in quotes creates a blank title. If this command is not used, +the window title is the form alias. + +*FvwmForm: Input 'name' 'size' 'init_string':: ++ +Specifies a text input item with name 'name'. A sub window of 'size' +characters in width is used for editing. If 'init_string' is present, +it is the initial string when *FvwmForm* starts or resets itself. The +default initial string is "". ++ +You can mouse paste into an input field using button 2. Buttons 1 and 3 +move the cursor in an input field. ++ +Input fields are always in insert mode, overtyping is not supported. ++ +Emacs type keystrokes are supported. ++ +'Control-a', 'Home' and 'Begin' move to the front of an input field. +'Control-e' and 'End' move to the end of an input field. 'Control-b' and +'Left' move left in an input field. 'Control-f' and 'Right' move right +in an input field. 'Control-p', 'Up', and 'Shift-Tab' move to a previous +input field if any, if the form has one input field, recall previous +value. 'Control-n', 'Down', 'Return', 'Line-feed' and 'Tab' move to the +next input field if any, if the form has one input field, for 'control-n' +and 'Down', restore previous input value. 'Control-h' moves backward in +an input field erasing a character. 'Control-d' and 'Delete' delete the +next character in an input field. 'Control-k' erases for the cursor to +the end of an input field. 'Control-u' erases the entire input field. ++ +When a form executes a command, all the input values are saved in a ring +of input history 50 items deep. ++ +Meta(mod2)-"<" retrieves the previous value of an input field. +Meta(mod2)-">" retrieves the next value of an input field. ++ +(For forms with one input field, use the much easier arrow keys.) + +*FvwmForm: Selection 'name' 'type':: ++ +This option starts a selection item with name name. Its choices are +specified in following configuration commands. The option type is one +of the following: ++ +[horizontal] +single;; The selections are mutually exclusive. ++ +multiple;; This is a multiple-choice selection. + +*FvwmForm: Choice 'name' 'value' *on* | *off* 'string':: ++ +Specifies a choice for a proceeding selection. The choice item has a +'name' and a 'value' these are used in commands. See "+*FvwmForm: +Command+". The string is displayed to the right of the choice button as +a label. ++ +The choice assumes the specified initial state ("on" means selected) +when *FvwmForm* starts or resets. If the selections are mutually +exclusive, *FvwmForm* does NOT detect inconsistencies in the initial +states of the choices, i.e. two or none of the choices can be selected. +However, once the user selects a choice, *FvwmForm* assures only one is +selected. + +*FvwmForm: Button 'type' 'string' ['key']:: ++ +This option specifies an action button. The button has 'string' as a +label, and executes a set of Fvwm 'command' when it is activated. The +commands are the following *FvwmForm: Commands. ++ +The optional 'key' specifies a keyboard shortcut that activates the +button. It is in either a control character, specified as +\^@+, +\^A+, +..., +\^_+, or a function key, specified as +F1+, +F2+, ..., +F35+. +Control keys that are used for cursor movement in text input fields +cannot activate any buttons, with the exception of +TAB (\^I)+, ++RETURN (\^M)+, +LINEFEED (\^J)+, which can activate a button when the +cursor is in the last text input field. ++ +The behavior of the button is determined by 'type': ++ +continue::: ++ +*FvwmForm* continues execution after sending the commands. ++ +restart::: ++ +After sending the commands, *FvwmForm* resets all the values to the +initial ones, and then continues execution. ++ +quit::: ++ +*FvwmForm* quits after sending the commands. + +*FvwmForm: Command 'command':: ++ +This option specifies an Fvwm command associated with the current +button. There can be more than one command attached to a button. +Commands that appear before any *FvwmForm: Button option are executed +at start-up time. This is usually a beep that gets the user's attention. ++ +Commands starting with an exclamation mark (!) are executed by +*FvwmForm*, all other commands are sent to Fvwm for execution. Before +sending each command to Fvwm, *FvwmForm* recognizes variables of the +following forms, and supply values to them. ++ +$('name')::: ++ +If 'name' corresponds to a text input field, the result is the user's +input string. The special chars single-quote, double-quote and backslash +are preceded by a backslash. ++ +If 'name' corresponds to a choice, the result is the value of the choice +(as specified in *FvwmForm: Choice) if the choice is selected. If the +choice is not selected, the result is a blank string. ++ +If 'name' corresponds to a selection, the result will be a list of the +selected values of all its choices separated by spaces. ++ +$('name'?'string')::: ++ +If 'name' is a text input field and its value is not an empty 'string', +the result is string, with recursive variable substitution applied. If +the input value is empty, the result is empty. ++ +If 'name' is a choice and it is selected, the result is 'string', with +recursive variable substitution applied. If the choice is not selected, +the result is empty. ++ +$('name'!'string')::: ++ +The same as the above, except that the converse conditions are taken. ++ +When using the "?" and "!" forms to pass a string, the string is +delimited by a right parenthesis. If you need to put a right parenthesis +in a string, precede the right parenthesis with a backslash. + +*FvwmForm: UseData 'datafile' 'leading':: ++ +Tells *FvwmForm* to read a data file and extract data from module +commands that match the 'leading' argument and an input, choice, or +selection variable in a form. ++ +This lets a form display current fvwm module configuration data. For an +example of how this works, examine the file "FvwmForm-Rlogin" which is +installed in read-only architecture-independent data directory, +[PREFIX/share/fvwm] and shown below. ++ +For choices, the setting of the button is represented as the word "on", +all other values for a setting are treated as off. ++ +For selections, the setting of each choice button is determined by +matching the current value of the selection against each choice. +Currently, this only works correctly for selections that allow a +single choice. + +*FvwmForm: ButtonPointer 'pointername':: ++ +Change the default mouse pointer (hand2) used when hovering over a +button. The pointername must be one of the names defined in the include +file X11/cursorfont.h (without the +XC_+ prefix). See *DEFAULTS*. + +*FvwmForm: ButtonInPointer 'pointername':: ++ +Change the default mouse pointer (hand1) used while a button is pressed +in. The pointername must be one of the names defined in the include +file X11/cursorfont.h (without the +XC_+ prefix). See *DEFAULTS*. + +*FvwmForm: InputPointer 'pointername':: ++ +Change the default mouse pointer (xterm) used while the pointer is over +a text field. The pointername must be one of the names defined in the +include file X11/cursorfont.h (without the +XC_+ prefix). See *DEFAULTS*. + +*FvwmForm: ButtonPointerFore|Back 'color':: ++ +Change the default mouse pointer foreground and background colors used +when hovering over a button. See *DEFAULTS*. + +*FvwmForm: ButtonInPointerFore|Back 'color':: ++ +Change the default mouse pointer foreground and background colors used +while a button is pressed in. See *DEFAULTS*. + +*FvwmForm: InputPointerFore|Back 'color':: ++ +Change the default mouse pointer foreground and background colors used +while the pointer is over a text field. See *DEFAULTS*. + +*FvwmForm: Timeout 'seconds' 'command' "'text'":: ++ +Set up *FvwmForm* to time out after the amount of 'seconds' specified. +When the timer hits zero, 'command' executes. The 'text' field is +displayed much like a 'Text' field, except that a \'%%' in the line is +replaced automatically by the amount of time left on the timer. The +value gets updated every second as the timer counts down. There can +only be one timeout field per form. + +EXAMPLES +-------- + +All of the following "examples" are installed in the read-only +architecture-independent data directory, [PREFIX/share/fvwm], during +fvwm installation. + +The following commands create a menu to invoke the examples: + +------ +DestroyMenu Forms +AddToMenu Forms "&Q. QuitVerify" Module FvwmForm FvwmForm-QuitVerify +AddToMenu Forms "&C. Capture" Module FvwmForm FvwmForm-Capture +AddToMenu Forms "&R. Rlogin" Module FvwmForm FvwmForm-Rlogin +AddToMenu Forms "&T. Talk" Module FvwmForm FvwmForm-Talk +------ + + +EXAMPLE 1 - Quit Verify +~~~~~~~~~~~~~~~~~~~~~~~ + +This example simulates the mwm way of confirming logout. Return does +the logout, Escape cancels logout. It times out after 20 seconds and +performs the equivalent of the 'Logout' button. + +------ +DestroyModuleConfig FvwmForm-QuitVerify: * +*FvwmForm-QuitVerify: GrabServer +*FvwmForm-QuitVerify: WarpPointer +*FvwmForm-QuitVerify: Command Beep +*FvwmForm-QuitVerify: Line center +*FvwmForm-QuitVerify: Text "Do you really want to logout?" +*FvwmForm-QuitVerify: Line expand +*FvwmForm-QuitVerify: Button quit "Logout" ^M +*FvwmForm-QuitVerify: Command Quit +*FvwmForm-QuitVerify: Button restart "Restart" ^R +*FvwmForm-QuitVerify: Command Restart +*FvwmForm-QuitVerify: Button quit "Cancel" ^[ +*FvwmForm-QuitVerify: Command Nop +*FvwmForm-QuitVerify: Timeout 20 Quit "Automatic logout will occur in %% seconds." +------ + + +EXAMPLE 2 - Remote Login +~~~~~~~~~~~~~~~~~~~~~~~~ + +This example lets the user type in a host name, an optional user name, +and opens an xterm window from the remote host. + +------ +DestroyModuleConfig FvwmForm-Rlogin: * +*FvwmForm-Rlogin: WarpPointer +*FvwmForm-Rlogin: Line center +*FvwmForm-Rlogin: Text "Login to Remote Host" +*FvwmForm-Rlogin: Line center +*FvwmForm-Rlogin: Text "Host:" +*FvwmForm-Rlogin: Input HostName 20 "" +*FvwmForm-Rlogin: Line center +*FvwmForm-Rlogin: Selection UserSel single +*FvwmForm-Rlogin: Choice Default Default on "same user" +*FvwmForm-Rlogin: Choice Custom Custom off "user:" +*FvwmForm-Rlogin: Input UserName 10 "" +*FvwmForm-Rlogin: Line expand +*FvwmForm-Rlogin: Button quit "Login" ^M +*FvwmForm-Rlogin: Command Exec exec ssh $(Custom?-l $(UserName)) $(HostName) xterm -T xterm@$(HostName) -display $HOSTDISPLAY & +# Before saving the data, remove any previously saved data: +*FvwmForm-Rlogin: Command DestroyModuleConfig FvwmForm-RloginDefault: * +# The "Login" button causes a login and a saving of the current data: +*FvwmForm-Rlogin: Command !( /bin/echo \ +"# Created by FvwmForm-Rlogin on: `/bin/date`."; /bin/echo \ +'*FvwmForm-RloginDefault: HostName $(HostName)'; /bin/echo \ +'*FvwmForm-RloginDefault: UserName $(UserName)'; /bin/echo \ +'*FvwmForm-RloginDefault: Default $(Default?on)'; /bin/echo \ +'*FvwmForm-RloginDefault: Custom $(Custom?on)' \ +) > ${FVWM_USERDIR}/.FvwmForm-Rlogin +*FvwmForm-Rlogin: Button restart "Reset" +*FvwmForm-Rlogin: Button quit "Cancel" ^[ +*FvwmForm-Rlogin: Command Nop +# Tell FvwmForm to read vars from the .FvwmForm-RloginDefault file: +*FvwmForm-Rlogin: UseData .FvwmForm-Rlogin *FvwmForm-RloginDefault +------ + + +EXAMPLE 3 - Capture Window +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example provides a front-end to xwd, xwud, and xpr. + +------ +DestroyModuleConfig FvwmForm-Capture: * +*FvwmForm-Capture: Line center +*FvwmForm-Capture: Text "Capture Window" +*FvwmForm-Capture: Line left +*FvwmForm-Capture: Text "File: " +*FvwmForm-Capture: Input file 25 "/tmp/Capture" +*FvwmForm-Capture: Line left +*FvwmForm-Capture: Text "Printer: " +*FvwmForm-Capture: Input printer 20 "$PRINTER" +*FvwmForm-Capture: Line expand +*FvwmForm-Capture: Selection PtrType single +*FvwmForm-Capture: Choice PS ps on "PostScript" +*FvwmForm-Capture: Choice Ljet ljet off "HP LaserJet" +*FvwmForm-Capture: Line left +*FvwmForm-Capture: Text "xwd options:" +*FvwmForm-Capture: Line expand +*FvwmForm-Capture: Selection Options multiple +*FvwmForm-Capture: Choice Brd -nobdrs off "No border" +*FvwmForm-Capture: Choice Frm -frame on "With frame" +*FvwmForm-Capture: Choice XYZ -xy off "XY format" +*FvwmForm-Capture: Line expand +*FvwmForm-Capture: Button continue "Capture" ^M +*FvwmForm-Capture: Command Exec exec xwd -out $(file) $(Options) & +*FvwmForm-Capture: Button continue "Preview" +*FvwmForm-Capture: Command Exec exec xwud -in $(file) & +*FvwmForm-Capture: Button continue "Print" +*FvwmForm-Capture: Command Exec exec xpr -device $(PtrType) $(file) | lpr -P $(printer) & +*FvwmForm-Capture: Button quit "Quit" +------ + + +EXAMPLE 4 - Talk Form +~~~~~~~~~~~~~~~~~~~~~ + +This example provides a replacement for the module FvwmTalk. There are +2 forms, "FvwmForm-Talk." which executes commands, or sends commands to +fvwm for execution, and "FvwmForm-TalkHelp." which is a help form. + +In the help form, notice how vertical line spacing is changed. Normal +*FvwmForm* line spacing assumes text is intermixed with buttons, help +forms require different spacing. + +------ +# FvwmForm-Talk - Basic replacement for FvwmTalk +DestroyModuleConfig FvwmForm-Talk: * +*FvwmForm-Talk: WarpPointer +# Layout +*FvwmForm-Talk: Line center +*FvwmForm-Talk: Text "Talk to Fvwm" +*FvwmForm-Talk: Line left +*FvwmForm-Talk: Text "Command:" +*FvwmForm-Talk: Input Command 80 "" +*FvwmForm-Talk: Line left +*FvwmForm-Talk: Text "Msg:" +*FvwmForm-Talk: Message +*FvwmForm-Talk: Line center +# Buttons +*FvwmForm-Talk: Button restart "Return - Execute" ^M +*FvwmForm-Talk: Command $(Command) +*FvwmForm-Talk: Button continue "F1 - Help" F1 +*FvwmForm-Talk: Command Module FvwmForm FvwmForm-TalkHelp +*FvwmForm-Talk: Button restart "F3 - Reset input" F3 +*FvwmForm-Talk: Command Nop +*FvwmForm-Talk: Button quit "F4 - Dismiss" F4 +*FvwmForm-Talk: Command Nop +------ + +------ +# FvwmForm-TalkHelp - Help Text for FvwmForm-Talk +DestroyModuleConfig FvwmForm-TalkHelp: * +*FvwmForm-TalkHelp: WarpPointer +# Layout +*FvwmForm-TalkHelp: Line center +*FvwmForm-TalkHelp: Text "Talk to Fvwm - Help" +*FvwmForm-TalkHelp: Line left +*FvwmForm-TalkHelp: Text " " +*FvwmForm-TalkHelp: Line left +*FvwmForm-TalkHelp: PadVText 0 +*FvwmForm-TalkHelp: Text "Enter commands in the +*FvwmForm-TalkHelp: Line left +*FvwmForm-TalkHelp: Text "Commands beginning with +*FvwmForm-TalkHelp: Line left +*FvwmForm-TalkHelp: Text "shell as a sub-process of the form." +*FvwmForm-TalkHelp: Line left +*FvwmForm-TalkHelp: Text "All other commands are sent to fvwm for execution." +*FvwmForm-TalkHelp: Line left +*FvwmForm-TalkHelp: Text "" +*FvwmForm-TalkHelp: Line left +*FvwmForm-TalkHelp: Text "Fvwm error messages are shown on the +*FvwmForm-TalkHelp: Line left +*FvwmForm-TalkHelp: Text "" +# Buttons +*FvwmForm-TalkHelp: Line center +*FvwmForm-TalkHelp: Button quit "Return - Dismiss" ^M +*FvwmForm-TalkHelp: Command Nop +------ + + +BUGS AND LIMITATIONS +-------------------- + +*FvwmForm* is a fairly simple method of providing input. There is no +input validation facility. *FvwmForm* has no way of dealing with lists. + +Report bugs to the fvwm-workers list. + + +COPYRIGHTS +---------- + +*FvwmForm* is original work of Thomas Zuwei Feng . + +Copyright (C) Feb 1995, Thomas Zuwei Feng. No guarantees or warranties +are provided or implied in any way whatsoever. Use this program at your +own risk. Permission to use, modify, and redistribute this program is +hereby given, provided that this copyright is kept intact. + + +CHANGES +------- + +During the fall of 1998, Dan Espen removed all form size limits, added +unlimited font and color changing, form spacing control, configuration +file reading, global control of appearance, synchronous command execution, +Error message display, variable substitution, configurable pointers, +and lots of other damage. No additional copyright is imposed. + + + + + diff --git a/Documentation/FvwmModules/FvwmIdent.txt b/Documentation/FvwmModules/FvwmIdent.txt new file mode 100644 index 000000000..ea0c2a268 --- /dev/null +++ b/Documentation/FvwmModules/FvwmIdent.txt @@ -0,0 +1,98 @@ +FvwmIdent(1) +============ +:doctype: manpage + +NAME +---- + +FvwmIdent - the Fvwm identify-window module + + +SYNOPSIS +-------- + +*FvwmIdent* is spawned by fvwm, so no command line invocation will work. + + +DESCRIPTION +----------- + +The *FvwmIdent* module prompts the user to select a target window, if the module +was not launched from within a window context in Fvwm. After that, it pops up a +window with information about the window which was selected. + + +COPYRIGHTS +---------- + +The *FvwmIdent* program, and the concept for interfacing this module to the +Window Manager, are all original work by Robert Nation and Nobutaka Suzuki. + +Copyright (C) 1994, Robert Nation and Nobutaka Suzuki. 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. + + +INITIALIZATION +-------------- + +During initialization, *FvwmIdent* gets config info from fvwm's module +configuration database (see *fvwm*(1), section *MODULE COMMANDS*) to determine +which colors and font to use. + +If the *FvwmIdent* executable is linked to another name, ie "+ln -s FvwmIdent +MoreIdentify+", then another module called 'MoreIdentify' can be started, with +a completely different configuration than *FvwmIdent*, simply by changing the +keyword FvwmIdent to MoreIdentify. This way multiple clutter-reduction programs +can be used. + + +INVOCATION +---------- + +*FvwmIdent* can be invoked by binding the action \'+Module FvwmIdent+' to a menu +or key-stroke in the .fvwm2rc file. Fvwm will search directory specified in the +ModulePath configuration option to attempt to locate *FvwmIdent*. Although +nothing keeps you from launching *FvwmIdent* at start-up time, you probably don't +want to. Clicking into the *FvwmIdent* window or pressing a key while it has +focus closes *FvwmIdent*. Pressing mouse button 2 in the window restarts +*FvwmIdent* and asks for a new window to select. + + +CONFIGURATION OPTIONS +*FvwmIdent* reads the same .fvwm2rc file as fvwm reads when it starts up, and +looks for lines as listed below: + +*FvwmIdent: Colorset 'n':: ++ +Tells the module to use colorset 'n'. See *FvwmTheme*. + +*FvwmIdent: Fore 'color':: ++ +Tells the module to use 'color' instead of black for text. Switches off the +Colorset option. + +*FvwmIdent: Back 'color':: ++ +Tells the module to use 'color' instead of white for the window background. +Switches off the Colorset option. + +*FvwmIdent: Font 'fontname':: ++ +Tells the module to use 'fontname' instead of fixed for text. + +*FvwmIdent: MinimalLayer 'layer':: ++ +*FvwmIdent* places its window on the layer of a target window. But not below the +minimal layer. By default, the minimal layer is 4 just like the fvwm default +layer. If 'layer' is 0, the layer of the target window is always used. If 'layer' +is "default" or not specified, the default behavior is restored. If 'layer' is +"none", *FvwmIdent* is placed as a normal window even if the target window is +above it. + + +AUTHOR +------ + +Robert Nation and Nobutaka Suzuki . \ No newline at end of file diff --git a/Documentation/FvwmModules/FvwmM4.txt b/Documentation/FvwmModules/FvwmM4.txt new file mode 100644 index 000000000..8e1fe8a6b --- /dev/null +++ b/Documentation/FvwmModules/FvwmM4.txt @@ -0,0 +1,263 @@ +FvwmM4(1) +========= +:doctype: manpage + +NAME +---- + +FvwmM4 - the fvwm M4 pre-processor + + +SYNOPSIS +-------- + +Module FvwmM4 [options] filename + + +DESCRIPTION +----------- + +When fvwm executes the *FvwmM4* module, *FvwmM4* invokes the M4 pre-processor on +the file specified in its invocation, then *FvwmM4* causes fvwm to execute the +commands in the resulting file. + +The *FvwmM4* module can only be invoked by fvwm. Command line invocation of the +*FvwmM4* module will not work. + + +INVOCATION +---------- + +*FvwmM4* can be invoked as a module using an fvwm command, from the .fvwm2rc +file, a menu, mousebinding, or any of the many other ways fvwm commands can be +issued. + +If the user wants his entire .fvwm2rc file pre-processed with *FvwmM4*, then +fvwm should be invoked as: + +------ +fvwm -cmd "Module FvwmM4 .fvwm2rc" +------ + +[NOTE] +The argument to the option '-cmd' should be enclosed in quotes, and no +other quoting should be used. + +When *FvwmM4* runs as a module, it runs asynchronously from fvwm. If *FvwmM4* is +invoked from the .fvwm2rc, the commands generated by *FvwmM4* may or may not be +executed by the time fvwm processes the next command in the .fvwm2rc. Invoke +*FvwmM4* this way for synchronous execution: + +------ +ModuleSynchronous FvwmM4 -lock filename +------ + + +OPTIONS +------- + +Some options can be specified following the modulename: + +-m4-prefix:: ++ +I think this makes all the m4 directives require the prefix "m4_". + +-m4-prefix-defines:: ++ +Causes built-in defines to be prefixed with "m4_" (i.e., m4_HOME is defined +instead of HOME, etc.) + +-m4opt 'option':: ++ +Lets you pass an option to the m4 program. Not really needed as any unknown +options will be passed on automatically. + +-m4-squote 'character':: ++ +Lets you change the m4 start-of-quote character to 'character'. + +-m4-equote 'character':: ++ +Lets you change the m4 end-of-quote character to 'character'. + +-m4prog 'name':: ++ +Instead of invoking "m4", fvwm will invoke 'name'. + +-outfile 'filename':: ++ +Instead of creating a random unique name for the temporary file for the +preprocessed rc file, this option specifies the name of the temporary file +created. *FvwmM4* attempts to remove this file before writing to it, so don't +point it at anything important even if it has read-only protection. + +-debug:: ++ +Causes the temporary file created by m4 to be retained. This file is +usually called "/tmp/fvwmrcXXXXXX" + +-lock:: ++ +If you want to use this option you need to start *FvwmM4* with *ModuleSynchronous*. +This option causes fvwm to wait that the pre-process to finish and then *FvwmM4* +asks fvwm to Read the pre-processed file before continuing. This can be useful +at startup if you use a session manager like Gnome. Also, this is useful if you +want to process and run a Form in an fvwm function. + +-noread:: ++ +Causes the pre-processed file to be not read by fvwm. Useful for pre-processing +an *FvwmScript* script. + + +CONFIGURATION OPTIONS +--------------------- + +*FvwmM4* defines some values for use in the pre-processor file: + ++TWM_TYPE+:: ++ +Always set to "fvwm". + ++SERVERHOST+:: ++ +The name of the machine running the X Server. + ++CLIENTHOST+:: ++ +The name of the machine running fvwm. + ++HOSTNAME+:: ++ +The hostname of the machine running fvwm. Generally the same as +CLIENTHOST+. + ++OSTYPE+:: ++ +The operating system for +CLIENTHOST+. + ++USER+:: ++ +The name of the person running fvwm. + ++HOME+:: ++ +The home directory of the person running fvwm. + ++VERSION+:: ++ +The X11 version. + ++REVISION+:: ++ +The X11 revision number. + ++VENDOR+:: ++ +The X server vendor. + ++RELEASE+:: ++ +The X server release number. + ++SCREEN+:: ++ +The screen number. + ++WIDTH+:: ++ +The screen width in pixels. + ++HEIGHT+:: ++ +The screen height in pixels. + ++X_RESOLUTION+:: ++ +Some distance/pixel measurement for the horizontal direction, I think. + ++Y_RESOLUTION+:: ++ +Some distance/pixel measurement for the vertical direction, I think. + ++PLANES+:: ++ +Number of color planes for the X server display + ++BITS_PER_RGB+:: ++ +Number of bits in each rgb triplet. + ++CLASS+:: ++ +The X11 default visual class, e.g. 'PseudoColor'. + ++COLOR+:: ++ +Yes or No, Yes if the default visual class is neither 'StaticGrey' or 'GreyScale'. + ++FVWM_CLASS+:: ++ +The visual class that fvwm is using, e.g. 'TrueColor'. + ++FVWM_COLOR+:: ++ +Yes or No, Yes if the FVWM_CLASS is neither 'StaticGrey' or 'GreyScale'. + ++FVWM_VERSION+:: ++ +The fvwm version number, ie 2.0 + ++OPTIONS+:: ++ +Some combination of +SHAPE+, +XPM+, +NO_SAVEUNDERS+, and +M4+, as defined in configure.h at compile time. + ++FVWM_MODULEDIR+:: ++ +The directory where fvwm looks for .fvwm2rc and modules by default, as determined at compile time. + ++FVWM_USERDIR+:: ++ +The value of +$FVWM_USERDIR+. + ++SESSION_MANAGER+:: ++ +The value of +$SESSION_MANAGER+. Undefined if this variable is not set. + + +EXAMPLE PROLOG +-------------- + +------ +define(TWM_TYPE,"fvwm")dnl +define(SERVERHOST,"spx20")dnl +define(CLIENTHOST,"grumpy")dnl +define(HOSTNAME,"grumpy")dnl +define(OSTYPE,"SunOS")dnl +define(USER,"nation")dnl +define(HOME,"/local/homes/dsp/nation")dnl +define(VERSION,"11")dnl +define(REVISION,"0")dnl +define(VENDOR,"HDS human designed systems, inc. (2.1.2-D)")dnl +define(RELEASE,"4")dnl +define(SCREEN,"0")dnl +define(WIDTH,"1280")dnl +define(HEIGHT,"1024")dnl +define(X_RESOLUTION,"3938")dnl +define(Y_RESOLUTION,"3938")dnl +define(PLANES,"8")dnl +define(BITS_PER_RGB,"8")dnl +define(CLASS,"PseudoColor")dnl +define(COLOR,"Yes")dnl +define(FVWM_VERSION,"1.24l")dnl +define(OPTIONS,"SHAPE XPM M4 ")dnl +define(FVWM_MODULEDIR,"/local/homes/dsp/nation/modules")dnl +define(FVWM_USERDIR,"/local/homes/dsp/nation/.fvwm")dnl +define(SESSION_MANAGER,"local/grumpy:/tmp/.ICE-unix/440,tcp/spx20:1025")dnl +------ + + +AUTHORS +------- + +*FvwmM4* is the result of a random bit mutation on a hard disk, presumably a +result of a cosmic-ray or some such thing. diff --git a/Documentation/FvwmModules/FvwmPager.txt b/Documentation/FvwmModules/FvwmPager.txt new file mode 100644 index 000000000..01366e382 --- /dev/null +++ b/Documentation/FvwmModules/FvwmPager.txt @@ -0,0 +1,450 @@ +FvwmPager(1) +============ +:doctype: manpage + +NAME +---- + +FvwmPager - the Fvwm Pager module + + +SYNOPSIS +-------- + +FvwmPager [ -transient ] [ name ] [ first desk [ last desk ] ] + + +*FvwmPager* is spawned by fvwm, so no command line invocation will work. + +All desks with desk numbers between first desk and last desk are displayed. If +last desk is omitted only the first desk is shown. If both desk numbers are +omitted, the current desk is used instead. If you use an asterisk \'*' in place +of first desk the pager will always show the current desktop, even when you +switch desks. + +Example lines to put in your .fvwm2rc: + +------ +Module FvwmPager 0 3 +------ + +or + +------ +Module FvwmPager * +------ + +or from within an fvwm pop-up menu: + +------ +AddToMenu Module-Popup Modules Title ++ Audio Module FvwmAudio ++ Auto Module FvwmAuto 200 ++ Buttons Module FvwmButtons ++ Console Module FvwmConsole ++ Ident Module FvwmIdent ++ Banner Module FvwmBanner ++ Pager Module FvwmPager 0 3 +------ + +or + +------ ++ Pager Module FvwmPager * +------ + +If the pager is started with the '-transient' option, the next time a button is +released the pager is closed. Note that this option does only work if the window +style of the pager window is 'sticky' (see the fvwm man page). You should use +the 'StaysOnTop' style too. + +Example: + +------ +Style FvwmPager Sticky, StaysOnTop +*FvwmPager: Rows 1 +*FvwmPager: Columns 1 +Mouse 3 R C Module FvwmPager -transient +------ + +With this in your .fvwm2rc, if you press control and button 3 in the root window +the pager pops up under the mouse and while the viewport moves with the mouse. + + +DESCRIPTION +----------- + +The *FvwmPager* module shows a miniature view of the Fvwm desktops which are +specified in the command line. This is a useful reminder of where your active +windows are. Windows in the pager are shown in the same color as their fvwm +decorations. + +The pager can be used to change your viewport into the current desktop, to change +desktops, or to move windows around. + +Pressing mouse button 1 in the pager will cause you viewport to change to the +selected page of the selected desk. If you click with button 1 in the desk-label +area, you will switch desks but not pages within the desk. + +Dragging mouse button 2 on a miniature view of a window will cause that window +to be move to the location where you release the mouse button, but your viewport +will not change. If you drag the window out of the pager and onto your desktop, +a full size image of the window will appear for you to place. There is no way to +pick up a full size image of the window and move it into the pager, however. +Since some mice do not have button 2, I have made provisions to drag windows in +the pager by using pressing modifier-1 (usually Alt) and dragging with button 3. + +Clicking mouse button 3 on a location will cause the viewport to move to the +selected location and switch desks if necessary, but will not align the viewport +to a page boundary. Dragging button 3 will cause the viewport to move as you +drag but not switch desktops, even if the pointer moves to another desktop. + +With the *FvwmPager: SloppyFocus option the focus is transfered to the window +pointed at with the mouse when the pointer is inside the pager. + +When iconified, the pager will work as a fully functional current desk only +pager. Windows and viewports can be moved within the icon of the pager. Users +will want to make sure that they have no lines similar to + +------ +Icon "Fvwm Pager" whatever +------ + +in their .fvwm2rc files. + + +COPYRIGHTS +---------- + +The *FvwmPager* program, and the concept for interfacing this module to the +Window Manager, are all original work by Robert Nation. + +Copyright 1994, 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. + + +INITIALIZATION +-------------- + +During initialization, *FvwmPager* gets config info from fvwm's module +configuration database (see *fvwm*(1), section *MODULE COMMANDS*). + +To use *FvwmPager* with several different configurations, you can invoke +*FvwmPager* with an optional parameter, which it will use as its name instead +(e.g "+Module FvwmPager OtherPager+"). OtherPager will then read only the lines +in the configuration file starting with "+\*OtherPager+", and not the lines +belonging to *FvwmPager*. This way multiple pager instances may be used. + +[NOTE] +The old way to use the *FvwmPager* with several different configurations is to +link the executable to another name, i.e. + +------ +ln -s FvwmPager OtherPager +------ + +This may work, but this method is not supported. + + +KEYBOARD FOCUS CONTROL +---------------------- + +You can direct the keyboard focus to any window on the current desktop by +clicking with button 2 on its image in the pager. The window does not need to +be visible, but it does need to be on the current page. + + +INVOCATION +---------- + +The invocation method was shown in the synopsis section + + +CONFIGURATION OPTIONS +--------------------- + +*FvwmPager: Geometry 'geometry':: ++ +Completely or partially specifies the pager windows location and geometry, in +standard X11 notation. In order to maintain an undistorted aspect ratio, you +might want to leave out either the width or height dimension of the geometry +specification . + +*FvwmPager: Rows 'rows':: ++ +Tells fvwm how many rows of desks to use when laying out the pager window. + +*FvwmPager: Columns 'columns':: ++ +Tells fvwm how many columns of desks to use when laying out the pager window. + +*FvwmPager: IconGeometry 'geometry':: ++ +Specifies a 'size' (optional) and 'location' (optional) for the pager's icon window. +Since there is no easy way for *FvwmPager* to determine the height of the icon's +label, you will have to make an allowance for the icon label height when using +negative y-coordinates in the icon location specification (used to specify a +location relative to the bottom instead of the top of the screen). + +*FvwmPager: StartIconic:: ++ +Causes the pager to start iconified. + +*FvwmPager: NoStartIconic:: ++ +Causes the pager to start normally. Useful for canceling the effect of the +'StartIconic' option. + +*FvwmPager: LabelsBelow:: ++ +Causes the pager to draw desk labels below the corresponding desk. + +*FvwmPager: LabelsAbove:: ++ +Causes the pager to draw desk labels above the corresponding desk. Useful for +canceling the effect of the 'LabelsBelow' option. + +*FvwmPager: ShapeLabels:: ++ +Causes the pager to hide the labels of all but the current desk. This turns off +label hilighting. + +*FvwmPager: NoShapeLabels:: ++ +Causes the pager to show the labels of all visible desks. Useful for canceling +the effect of the 'ShapeLabels' option. + +*FvwmPager: Font 'font-name':: ++ +Specified a font to use to label the desktops. If font_name is "none" then no +desktop labels will be displayed. + +*FvwmPager: SmallFont 'font-name':: ++ +Specified a font to use to label the window names in the pager. If not specified, +the window labels will be omitted. Window labels seem to be fairly useless for +desktop scales of 32 or greater. If 'font_name' is "none" then no window names +will be displayed. + +*FvwmPager: Fore 'color':: ++ +Specifies the color to use to write the desktop labels, and to draw the +page-grid lines. + +*FvwmPager: Back 'color':: ++ +Specifies the background color for the window. + +*FvwmPager: Hilight 'color':: ++ +The active page and desk label will be highlighted by using this background +pattern instead of the normal background. + +*FvwmPager: HilightPixmap 'pixmap':: ++ +The active page will be highlighted by using this background pattern instead of +the normal background. + +*FvwmPager: DeskHilight:: ++ +Hilight the active page with the current hilight color/pixmap. Useful for +canceling the effect of the 'NoDeskHilight' option. + +*FvwmPager: NoDeskHilight:: ++ +Don't hilight the active page. + +*FvwmPager: WindowColors 'fore' 'back' 'hiFore' 'hiBack':: ++ +Change the normal/highlight colors of the windows. 'fore' and 'hiFore' specify +the colors as used for the font inside the windows. 'back' and 'hiBack' are used +to fill the windows with. + +*FvwmPager: WindowLabelFormat 'format':: ++ +This specifies a +printf()+ like format for the labels in the mini window. Possible +flags are: +%t+, +%i+, +%c+, and +%r+ for the window's title, icon, class, or +resource name, respectively. The default is "%i". + +*FvwmPager: Label 'desk' 'label':: ++ +Assigns the text 'label' to desk 'desk' (or the current desk if desk is "*") in +the pager window. Useful for assigning symbolic names to desktops, i.e. ++ +------ +*FvwmPager: Label 1 Mail +*FvwmPager: Label 2 Maker +*FvwmPager: Label * Matlab +------ ++ +[NOTE] +There is currently a much better way to specify desk names globally (and not +just in *FvwmPager*) using *DesktopName* command, so you should not use this +option anymore. + +*FvwmPager: DeskColor desk 'color':: ++ +Assigns the color 'color' to desk 'desk' (or the current desk if desk is "*") +in the pager window. This replaces the background color for the particular desk. +This only works when the pager is full sized. When Iconified, the pager uses the +color specified by "+*FvwmPager: Back+". ++ +[TIP] +Try using "+\*FvwmPager: DeskColor+" in conjunction with *FvwmCpp* (or *FvwmM4*) +and *FvwmBacker* to assign identical colors to your various desktops and the +pager representations. + +*FvwmPager: Pixmap 'pixmap':: ++ +Use pixmap as background for the pager. + +*FvwmPager: DeskPixmap desk 'pixmap':: ++ +Assigns the pixmap color to desk 'desk' (or the current desk if desk is "*") in +the pager window. This replaces the background pixmap for the particular desk. ++ +[TIP] +Try using "+\*FvwmPager: DeskPixmap+" in conjunction with *FvwmCpp* (or *FvwmM4*) +and *FvwmBacker* to assign identical pixmaps to your various desktops and the +pager representations. + +*FvwmPager: DeskTopScale 'number':: ++ +If the geometry is not specified, then a desktop reduction factor is used to +calculate the pager's size. Things in the pager window are shown at 1/number of +the actual size. + +*FvwmPager: MiniIcons:: ++ +Allow the pager to display a window's mini icon in the pager, if it has one, +instead of showing the window's name. + +*FvwmPager: MoveThreshold 'pixels':: ++ +Defines the 'distance' the pointer has to be moved before a window being dragged +with button 2 is actually moved. The default value is three pixels. If the +pointer moved less that this amount the window snaps back to its original +position when the button is released. If pixels is less than zero the default +value is used. The value set with the *MoveThreshold* command in fvwm is +inherited by *FvwmPager* but can be overridden with this option. + +*FvwmPager: SloppyFocus:: ++ +If the 'SloppyFocus' option is used, you do not need to click into the mini +window in the pager to give the real window the focus. Simply putting the +pointer over the window inside the pager is enough. ++ +[NOTE] +This option interferes slightly with the 'MouseFocus' and 'SloppyFocus' styles +of fvwm. Sometimes, if you click into the pager window to change pages or desks +and then move the pointer to a place on the screen where a window of the new +page will appear, this new window does not get the input focus. This may happen +if you drag the pointer over one of the mini windows in the pager. There is +nothing that can be done about this - except not using 'SloppyFocus' in the pager. + +*FvwmPager: SolidSeparators:: ++ +By default the pages of the virtual desktop are separated by dashed lines in the +pager window. This option causes *FvwmPager* to use solid lines instead. + +*FvwmPager: NoSeparators:: ++ +Turns off the lines separating the pages of the virtual desktop. + +*FvwmPager: Balloons ['type']:: ++ +Show a balloon describing the window when the pointer is moved into a window in +the pager. The default format (the window's icon name) can be changed using +'BalloonStringFormat'. If 'type' is "Pager" balloons are just shown for an +un-iconified pager; if 'type' is "Icon" balloons are just shown for an iconified +pager. If 'type' is anything else (or null) balloons are always shown. + +*FvwmPager: BalloonFore 'color':: ++ +Specifies the color for text in the balloon window. If omitted it defaults to +the foreground color for the window being described. + +*FvwmPager: BalloonBack 'color':: ++ +Specifies the background color for the balloon window. If omitted it defaults +to the background color for the window being described. + +*FvwmPager: BalloonFont 'font-name':: ++ +Specifies a font to use for the balloon text. Defaults to fixed. + +*FvwmPager: BalloonBorderWidth 'number':: ++ +Sets the width of the balloon window's border. Defaults to 1. + +*FvwmPager: BalloonBorderColor 'color':: ++ +Sets the color of the balloon window's border. Defaults to black. + +*FvwmPager: BalloonYOffset 'number':: ++ +The balloon window is positioned to be horizontally centered against the pager +window it is describing. The vertical position may be set as an offset. Negative +offsets of -n are placed n pixels above the pager window, positive offsets of +n +are placed n pixels below. Offsets of -1 and 1 represent the balloon window close +to the original window without a gap. Offsets of 0 are not permitted, as this +would permit direct transit from pager window to balloon window, causing an +event loop. Defaults to +3. The offset will change sign automatically, as needed, +to keep the balloon on the screen. + +*FvwmPager: BalloonStringFormat 'format':: ++ +The same as "+*FvwmPager: WindowLabelFormat+", it just specifies the string to +display in the balloons. The default is "%i". + +*FvwmPager: Colorset 'desk' 'colorset':: ++ +Tells the module to use colorset 'colorset' for 'desk'. If you use an asterisk +\'\*' in place of desk, the colorset is used on all desks. Please refer to the +man page of the *FvwmTheme* module for details about colorsets. + +*FvwmPager: BalloonColorset 'desk' 'colorset':: ++ +Tells the module to use colorset 'colorset' for balloons on 'desk'. If you use +an asterisk \'\*' in place of desk, the colorset is used on all desks. Please +refer to the man page of the *FvwmTheme* module for details about colorsets. + +*FvwmPager: HilightColorset 'desk' 'colorset':: ++ +Tells the module to use colorset 'colorset' for hilighting on 'desk'. If you use +an asterisk \'\*' in place of desk, the colorset is used on all desks. Please +refer to the man page of the *FvwmTheme* module for details about colorsets. + +*FvwmPager: WindowColorsets 'colorset' 'activecolorset':: ++ +Uses colorsets in the same way as "+\*FvwmPager: WindowColors+". Please refer +to the man page of the *FvwmTheme* module for details about colorsets. The +shadow and hilight colors of the colorset are only used for the window borders +if the "+*FvwmPager: Window3DBorders+" is specified too. + +*FvwmPager: WindowBorderWidth 'n':: ++ +Specifies the width of the border drawn around the mini windows. This also sets +the minimum size of the mini windows to (2 * n + 1). The default is 1. + +*FvwmPager: Window3DBorders:: ++ +Specifies that the mini windows should have a 3d borders based on the mini +window background. This option only works if "+*FvwmPager: WindowColorsets+" +is specified. + +*FvwmPager: UseSkipList:: ++ +Tells *FvwmPager* to not show the windows that are using the WindowListSkip style. + + +AUTHOR +------ + +Robert Nation +DeskColor patch contributed by Alan Wild +MiniIcons & WindowColors patch contributed by Rob Whapham +Balloons patch by Ric Lister +fvwm-workers: Dominik, Olivier, Hippo and others. + diff --git a/Documentation/FvwmModules/FvwmRearrange.txt b/Documentation/FvwmModules/FvwmRearrange.txt new file mode 100644 index 000000000..a60babbe2 --- /dev/null +++ b/Documentation/FvwmModules/FvwmRearrange.txt @@ -0,0 +1,211 @@ +FvwmRearrange(1) +================ +:doctype: manpage + +NAME +---- + +FvwmRearrange - rearrange fvwm windows + + +SYNOPSIS +-------- + +*FvwmRearrange* is spawned by fvwm, so no command line invocation will work. + + +DESCRIPTION +----------- + +This module can be called to tile or cascade windows. + +When tiling the module attempts to tile windows on the current screen subject +to certain constraints. Horizontal or vertical tiling is performed so that each +window does not overlap another, and by default each window is resized to its +nearest resize increment (note sometimes some space might appear between tiled +windows -- this is why). + +When cascading the module attempts to cascade windows on the current screen +subject to certain constraints. Layering is performed so consecutive windows +will have their window titles visible underneath the previous. + + +INVOCATION +---------- + +*FvwmRearrange* is best invoked from a menu, pop up or button. There are a +number of command line options which can be used to constrain the layering, +these are described below. As an example case, one could call *FvwmRearrange* +with the following arguments: + +------ +FvwmRearrange -tile -h 10 10 90 90 +------ + +or + +------ +FvwmRearrange -cascade -resize 10 2 80 70 +------ + +The first invocation will horizontally tile windows with a bounding box which +starts at 10 by 10 percent into and down the screen and ends at 90 by 90 percent +into and down the screen. + +The second invocation will cascade windows starting 10 by 2 percent into and +down the screen. Windows will be constrained to 80 by 70 percent of the screen +dimensions. Since the resize is also specified, windows will be resized to the +given constrained width and height. + +*FvwmRearrange* can be called as *FvwmTile* or *FvwmCascade*. This is +equivalent to providing the '-tile' or '-cascade' option. This form is obsolete +and supplied for backwards compatibility only. + +Command-line arguments passed to *FvwmRearrange* are described here. + +-a:: ++ +Causes all window types to be affected, even ones with the WindowListSkip style. + +-animate:: ++ +Attempt to do an animated move, this is ignored if -resize or -maximize are used. + +-cascade:: ++ +Cascade windows. This argument must be the first on the command line. This is +the default. + +-desk:: ++ +Causes all windows on the desk to be cascaded/tiled instead of the current +screen only. + +-flatx:: ++ +Inhibits border width increment. Only used when cascading. + +-flaty:: ++ +Inhibits border height increment. Only used when cascading. + +-h:: ++ +Tiles horizontally (default is to tile vertically). Used for tiling only. + +-incx 'arg':: ++ +Specifies a horizontal increment which is successively added to cascaded +windows. 'arg' is a percentage of screen width, or pixel value if a \'p' is +suffixed. Default is zero. Used only for cascading. + +-incy 'arg':: ++ +Specifies a vertical increment which is successively added to cascaded windows. +'arg' is a percentage of screen height, or pixel value if a \'p' is suffixed. +Default is zero. Used only for cascading. + +-m:: ++ +Causes maximized windows to also be affected (implied by '-a'). + +-maximize:: ++ +When moving/resizing a window, put it also into maximized state. + +-mn 'arg':: ++ +Tiles up to 'arg' windows in tile direction. If more windows exist, a new +direction row or column is created (in effect, a matrix is created). Used only +when tiling windows. + +-noanimate:: ++ +Do not attempt to do an animated move. + +-nomaximize:: ++ +Do not put windows into maximized state. + +-noraise:: ++ +Inhibits window raising, leaving the depth ordering intact. + +-noresize:: ++ +Inhibits window resizing, leaving window sizes intact. This is the default when +cascading windows. + +-nostretch:: ++ +If tiling: inhibits window growth to fit tile. Windows are shrunk to fit the +tile but not expanded. ++ +If cascading: inhibits window expansion when using the '-resize' option. Windows +will only shrink to fit the maximal width and height (if given). + +-r:: ++ +Reverses the window sequence. + +-resize:: ++ +Forces all windows to resize to the constrained width and height (if given). +This is the default when tiling windows. + +-s:: ++ +Causes sticky windows to also be affected (implied by '-a'). + +-sp:: ++ +Causes windows sticky across pages to also be affected (implied by '-a'). + +-sd:: ++ +Causes windows sticky across desks to also be affected (implied by '-a'). + +-t:: ++ +Causes transient windows to also be affected (implied by '-a'). + +-tile:: ++ +Tile windows. This argument must be the first on the command line. + +-u:: ++ +Causes untitled windows to also be affected (implied by '-a'). + +-ewmhiwa:: ++ +When rearranging windows, make the calculation ignore the working area, such as +'EwmhBaseStruts'; by default, *FvwmRearrange* will honour the working area. ++ +Up to four numbers can be placed on the command line that are not switches. +The first pair specify an x and y offset to start the first window (default +is 0, 0). The meaning of the second pair depends on operation mode: ++ +When tiling windows it specifies an absolute coordinate reference denoting the +lower right bounding box for tiling. ++ +When cascading it specifies a maximal width and height for the layered windows. +If an affected window exceeds either this width or height, it is resized to the +maximal width or height. ++ +If any number is suffixed with the letter \'p', then it is taken to be a pixel +value, otherwise it is interpreted as a screen percentage. Specifying zero for +any parameter is equivalent to not specifying it. + + +BUGS +---- + +It is probably not a good idea to delete windows while windows are being rearranged. + + +AUTHORS +------- + +Andrew Veliath (original *FvwmTile* and *FvwmCascade* modules) Dominik Vogt +(merged *FvwmTile* and *FvwmCascade* to *FvwmRearrange*) \ No newline at end of file diff --git a/Documentation/FvwmModules/FvwmScroll.txt b/Documentation/FvwmModules/FvwmScroll.txt new file mode 100644 index 000000000..e75007a88 --- /dev/null +++ b/Documentation/FvwmModules/FvwmScroll.txt @@ -0,0 +1,92 @@ +FvwmScroll(1) +============= +:doctype: manpage + +NAME +---- + +FvwmScroll - the fvwm scroll-bar module + + +SYNOPSIS +-------- + +*FvwmScroll* is spawned by fvwm, so no command line invocation will work. + + +DESCRIPTION +----------- + +The *FvwmScroll* module prompts the user to select a target window, if the module +was not launched from within a window context in Fvwm. After that, it adds +scroll bars to the selected window, to reduce the total desktop space consumed +by the window. + +*FvwmScroll* should not be used with windows which move or resize themselves, +nor should it be used with windows which set the +WM_COLORMAP_WINDOWS+ property. +Operation is fine with windows that have a private colormap. + + +COPYRIGHTS +---------- + +The *FvwmScroll* program, and the concept for interfacing this module to the +Window Manager, are all original work by Robert Nation. + +Copyright (C) 1994, 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. + + +INITIALIZATION +-------------- + +During initialization, *FvwmScroll* gets config info from fvwm's module +configuration database (see *fvwm*(1), section *MODULE COMMANDS*) to determine +which colors to use. + +If the *FvwmScroll* executable is linked to another name, ie "+ln -s FvwmScroll +MoreScroll+", then another module called 'MoreScroll' can be started, with a +completely different configuration than *FvwmScroll*, simply by changing the +keyword 'FvwmScroll' to 'MoreScroll'. + + +INVOCATION +---------- + +*FvwmScroll* can be invoked by binding the action "+Module FvwmScroll x y+" to +a menu or key-stroke in the .fvwm2rc file. The parameter x and y are either +integers or integers immediately followed by a p, which describe the horizontal +and vertical size modification of the window. An integer describe a size +reduction. An integer followed by a p describe a size as a percentage of the +height or the width of a full screen but the size is never larger than the +original window size (0p will do nothing). Fvwm will search directory specified +in the ModulePath configuration option to attempt to locate *FvwmScroll*. +Although nothing keeps you from launching *FvwmScroll* at start-up time, you +probably don't want to. + + +CONFIGURATION OPTIONS +--------------------- + +------ +*FvwmScroll: Colorset n + Tells the module to use colorset n. See FvwmTheme. + +*FvwmScroll: Back color + Tells the module to use color instead of black for the window background. Switches off the Colorset option. +------ + + +BUGS +---- + +When the scroll bars are removed by clicking on the button in the lower right +corner, the window does not restore its location correctly. + + +AUTHOR +------ + +Robert Nation diff --git a/Documentation/FvwmModules/FvwmTheme.txt b/Documentation/FvwmModules/FvwmTheme.txt new file mode 100644 index 000000000..861521d93 --- /dev/null +++ b/Documentation/FvwmModules/FvwmTheme.txt @@ -0,0 +1,533 @@ +FvwmTheme(1) +============ +:doctype: manpage + +NAME +---- + +FvwmTheme - an fvwm module for managing the appearance of fvwm and its modules + + +SYNOPSIS +-------- + +ModuleSynchronous Timeout 5 FvwmTheme + +*FvwmTheme* can only be invoked by fvwm. Command line invocation of the +*FvwmTheme* module will not work. + + +DESCRIPTION +----------- + +*FvwmTheme* creates appearance resources that may be shared by fvwm and other +modules. It reads an initial configuration and also reacts to configuration +commands and messages sent from fvwm so that the resources can be dynamically +changed. + + +INVOCATION +---------- + +Starting with 2.5.1, *FvwmTheme* is obsolete, please read fvwm man page about +the built-in colorsets solution. However, all options are still the same, so +this man page defines the exact Colorset syntax. + +*FvwmTheme* must be spawned as a module by fvwm. + +It is highly suggested that *FvwmTheme* is invoked before any other modules +that use the colorsets provided by *FvwmTheme*. Thus *FvwmTheme* has to be +invoked with the 'ModuleSynchronous' command by inserting the line +"+ModuleSynchronous Timeout 5 FvwmTheme+" in the .fvwm2rc file right after +the ImagePath has been defined. Invoking *FvwmTheme* from the *InitFunction*, +*StartFunction* or *RestartFunction* or later can cause excessive redrawing +of already running modules. It is highly suggested that the configuration +lines for *FvwmTheme* appear in the configuration file before *FvwmTheme* +is started. You can find a proper sample fvwm setup at the end of this +document. It is pointless to run more than one *FvwmTheme* so there is no +provision for using an alias name. + + +CONFIGURATION OPTIONS +--------------------- + +*FvwmTheme* supports some configuration options. + +*FvwmTheme: Colorset 'n' 'options':: ++ +Creates or modifies colorset 'n'. Each colorset has four colors, an optional +pixmap and an optional shape mask. The four colors are used by modules as the +foreground, background, highlight and shadow colors. When a colorset is +created it defaults to a foreground of black and background of gray. The +background and foreground are marked as 'average' and 'contrast' (see later) +so that just specifying a pixmap or gradient gives sensible results. ++ +[WARNING] +The highest colorset number used determines memory consumption. Thus if you +define "+Colorset 100000+", the memory for 100001 colorsets is used. Keep +your colorset numbers as small as possible. ++ +'options' is a comma separated list containing some of the keywords: fg, Fore, +Foreground, bg, Back, Background, hi, Hilite, Hilight, sh, Shade, Shadow, +fgsh, Pixmap, TiledPixmap, AspectPixmap, Transparent, RootTransparent, +Shape, TiledShape, AspectShape, NoShape, ?Gradient, Tint, fgTint, bgTint, +Alpha, fgAlpha, Dither, NoDither, IconTint, IconAlpha, NoShape and Plain. ++ +'fg', 'Fore' and 'Foreground'::: ++ +take a color name as an argument and set the +foreground color. The special name Contrast may be used to select a color that +'contrasts' well with the background color. To reset the foreground color to +the default value you can simply omit the color name. + +'bg', 'Back' and 'Background'::: ++ +take a color name as an argument and set the +background color. It also sets the highlight and shadow colors to values that +give a 3d effect unless these have been explicitly set with the options below. +The special name Average may be used to select a color that is the average +color of the pixmap. If the pixmap is tinted with the 'Tint' option, the tint +is not taken in account in the computation of the average color. You should +use the 'bgTint' option to get the "real" average color. The background color +is reset to the default value if the color name is omitted. ++ +'hi', 'Hilite' and 'Hilight'::: ++ +take a color name as an argument and set the +highlight color. If the highlight color is not explicitly set, the default is +to calculate it from the background color. To switch back to the default +behavior the color name can be omitted. ++ +'sh', 'Shade' and 'Shadow'::: ++ +take a color name as an argument and set the shadow +color. If the shadow color is not explicitly set, the default is to calculate +it from the background color. To switch back to the default behavior the color +name can be omitted. ++ +'fgsh'::: ++ +takes a color name as an argument and sets the color used by the +shadowing font effect. See the *FONT SHADOW EFFECTS* section of the fvwm man +page. By default this color is computed from the foreground and background +colors. To switch back to the default the color name can be omitted. ++ +'Pixmap', 'TiledPixmap' and 'AspectPixmap'::: ++ +take a file name as an argument, +search the 'ImagePath' and use it as the background pixmap. Any transparent +parts are filled with the background color. Not specifying a file name removes +any existing one from the colorset. 'TiledPixmap' produces repeated copies of +the image with no scaling, 'Pixmap' causes the image to be stretched to fit +whatever object the colorset is applied to and 'AspectPixmap' stretches to fit +but retains the image aspect ratio. ++ +'Transparent'::: ++ + +tries to create a transparent background pixmap. The pixmap may +be used as a window background to achieve root transparency. For this you +should use the 'ParentalRelativity' fvwm style. The root background change may +be detected or not, this depends on the program used to set the background. +If you use *fvwm-root*, xsetbg (xli), *FvwmBacker* with a solid or a colorset +colors or a recent version of Esetroot (>= 9.2) a background change should +be detected. If background changes are not detected (e.g., if you use xv or +xsetroot) you can force detection by using the '-d' option of *fvwm-root*: ++ +------ +xv -root -quit mybg.png; fvwm-root -d +------ ++ +Due to the way X implements transparency no guarantees can be made that the +desired effect can be achieved. The application may even crash. If you +experience any problems with this option, do not use it. ++ +Using outline move and resize (see the 'OpaqueMoveSize' command and the +'ResizeOpaque' style) as well as setting the 'WindowShadeShrinks' style may +help. The transparency achieved with 'Transparent' depends on whether the +colorset is applied to the foreground or the background of a window. In the +second case the transparency is relative to the parent window of the window on +which the colorset is defined. For example: ++ +------ +Colorset 12 VGradient 200 grey30 grey60 +Colorset 17 Transparent +*FvwmIconMan: Colorset 12 +*FvwmIconMan: PlainColorset 17 +------ ++ +gives an IconMan with a vertical 'greyv gradient background and the buttons +use the background (by transparency). To obtain a (root) transparent IconMan: ++ +------ +Colorset 12 Transparent +Colorset 17 Transparent +Colorset 18 Transparent +Colorset 19 Transparent +*FvwmIconMan: Colorset 12 +*FvwmIconMan: PlainColorset 17 +*FvwmIconMan: FocusColorset 18 +*FvwmIconMan: IconColorset 19 +------ ++ +'Colorset'::: ++ +The 'Colorset' IconMan option defines the IconMan window background, but the +'PlainColorset' and the 'FocusColorset' are drawn on the foreground. So, the +transparency of the IconMan buttons is achieved by drawing nothing. Now if +this IconMan is swallowed in an *FvwmButtons* as: ++ +------ +FvwmButtons:(Colorset 10, Swallow "FvwmIconMan" 'FvwmIconMan') +------ ++ +then, IconMan become a child of *FvwmButtons* and it is transparent relative to +*FvwmButtons*. So, in this case IconMan uses Colorset 10 as background. If you +want root transparency use the 'RootTransparent' option. *FvwmButtons*, +*FvwmIconMan*, *FvwmIdent*, *FvwmScroll* and *FvwmTaskBar* are relatively +simple. There is one main colorset option which defines the background of the +window and the other colorsets (if any) are drawn on the foreground. The case +of *FvwmWinList* and *FvwmProxy* are simpler. With *FvwmWinList* all the +colorsets are drawn on the foreground and with *FvwmProxy* the two colorsets +refer to the window backgrounds. *FvwmPager* is more complicated as almost +everything in the pager are windows with some parental relations (the mini +windows are the child and the desktops are the parents and all this is +complicated by the hilighted page). So, the colorsets apply to the background +of these windows. You should experiment. For *FvwmForm* and *FvwmScript* the +situation is similar. There is a main window (a child of the root window) which +corresponds to the main colorset and most of the widgets are windows which are +children of the main window. 'Tint' may work or not with the 'Transparent' +option. When the colorset is drawn on the foreground 'Tint' should work. In +the other cases, tinting works in some exceptional cases (and may be very slow). +Tinting may work with fvwm menu (without animation). In the other case tinting +may work if your X server has backing store enabled (try xdpyinfo to see if +this the case). But, there is a chance that the backing store support of your +X server does not work well with the terrible hack used to 'Tint' the +'ParentRelative' Pixmap. So, to get tinted root transparency it is more safe +to use the 'RootTransparent' option. ++ +'RootTransparent' [ 'buffer' ]::: ++ +creates a root transparent background. To make +this option work, you must use an Esetroot compatible program, *fvwm-root* with +the '--retain-pixmap' option or *FvwmBacker* with the 'RetainPixmap' option +(and 'colorset' or 'solid' backgrounds). The buffer keyword is useful only +when the 'Tint' option is used too. This speeds up creation of windows which +use the colorset (useful for fvwm menus) at the cost of memory usage. It also +speeds up opaque move and resize which can be unacceptably slow without buffer. +However, this option may add a lot of memory to your X server (depending on +the size of the image used to set the background). In summary, using outline +move and resize for modules which use such a colorset may be a good idea. ++ +'Shape', 'TiledShape' and 'AspectShape'::: ++ +take a file name as an argument, search +the ImagePath and use it as the shape bitmap. 'TiledShape' produces repeated +copies of the bitmap with no scaling, 'Shape' causes the bitmap to be stretched +to fit whatever object the colorset is applied to and 'AspectShape' stretches +to fit but retains the bitmap aspect ratio. If the file is a pixmap in xpm +format, the shape mask of the pixmap is used. ++ +[WARNING] +Due to the way X11 implements shapes and the implementation of the *FvwmTheme* +module you cannot take back making windows shaped. You may have to restart +fvwm or the shaped application. + +'?Gradient'::: ++ +\... creates a pixmap and stretches it to fit the window. '?Gradient' +may be one of HGradient, VGradient, DGradient, BGradient, SGradient, CGradient, +RGradient or YGradient. The gradient types are as follows: 'H' is horizontal; +'V' is vertical; 'D' is diagonal from top left to bottom right; 'B' is a +backwards diagonal from bottom left to top right; 'S' is concentric squares; +'C' is concentric circles; 'R' is a radar like pattern and 'Y' is a Yin Yang +style (but without the dots, we are not that mad). Please refer to the *COLOR +GRADIENTS* section in the fvwm man page for the syntax of gradients. ++ +'Tint'::: ++ +takes 2 arguments, a color and a percentage between 0 and 100. It +causes the image defined using '?Pixmap' or '?Gradient' to be tinted with the +specified color using the percentage. If the image is transparent 'Tint' tints +only the image part. Unfortunately, a colorset background specified using the +'Transparent' option can give strange results. See the 'Transparent' option +for details. With no arguments this option removes the tint. ++ +'fgTint'::: ++ +takes 2 arguments, a color and a percentage between 0 and 100. It +causes the color defined using 'fg' to be tinted with the specified color +using the percentage. With no arguments this option removes the tint. ++ +'bgTint'::: ++ +takes 2 arguments, a color and a percentage between 0 and 100. It +causes the color defined using 'bg' to be tinted with the specified color +using the percentage. If the 'sh' and 'hi' colors are not specified, they are +recomputed from the tinted 'bg' color. With no arguments this option removes +the tint. ++ +'Alpha'::: ++ +takes a percentage between 0 and 100 as an argument. It causes fvwm to +merge the image defined using '?Pixmap' or '?Gradient' with the 'bg' color +using the percentage. If the percentage is 0 the image is hidden and if it is +100 the image is displayed as usual (no merge). The default is 100 and it is +restored if no argument is given. ++ +'fgAlpha'::: ++ +takes a percentage between 0 and 100 as an argument. It causes fvwm +to merge the text and the colorset background using the percentage. If the +percentage is 0 the text is hidden and if it is 100 the text is displayed as +usual (no merge). This option has an effect only with fonts loaded by Xft, see +the *FONT NAMES AND FONT LOADING* section of fvwm man page. The default is 100 +and it is restored if no argument is given. ++ +'Dither'::: ++ +causes fvwm to dither the image defined using '?Pixmap' or '?Gradient'. +This is useful only with displays with depth less than or equal to 16 (i.e., +on displays which can only display less than 65537 colors at once). The +dithering effect lets you simulate having more colors available that you +actually have. 'NoDither' causes fvwm to do not dither the images. 'Dither' +is the default if the depth is less than or equal to 8 (a screen with 256 +colors or less). In depth 15 (32768 colors) and 16 (65536 colors), the default +is 'NoDither', however this effect can be useful with images which contain a +lot of close colors. For example a fine gradient will look more smooth. ++ +'IconTint'::: ++ +takes 2 arguments, a color and a percentage between 0 and 100. It +causes fvwm or a module to tint the "icons" which are rendered into the +colorset background with the specified color using a percentage. Here "icons" +means, fvwm Icons, fvwm menu icons, MiniIcons which represent applications in +various modules, images loaded by modules (e.g., images specified by the Icon +*FvwmButtons* button option) ...etc. With no arguments this option removes the +icon tint. ++ +'IconAlpha'::: ++ +takes a percentage between 0 and 100 as an argument. It causes +fvwm to merge the "icons" which are rendered into the colorset background +using this percentage. The default is 100 and it is restored if no argument +is given. ++ +[NOTE] +It is equivalent to use "Tint a_color rate" and "Alpha a" if a = 100 and the bg +color is a_color. This equivalence does not hold for IconAlpha and IconTint as +the background can be an image or a gradient (and not a uniform color +background). However, in some cases you can achieve (almost) the same effect +by using IconTint in the place of IconAlpha. This is preferable as, in general, +IconAlpha generates more redrawing than IconTint. ++ +'NoShape'::: ++ +removes the shape mask from the colorset while 'Plainv removes the +background pixmap or gradient. + + +COMMANDS +-------- + +The following fvwm command may be executed at any time to alter the colorsets. +It may be bound to a menu item or typed into a module such as FvwmConsole. + +------ +SendToModule FvwmTheme Colorset options +------ + +The syntax is the same as the configuration option. + + +EXAMPLES +-------- + +------ +*FvwmTheme: Colorset 3 fg wheat, bg navy +------ + +If necessary this creates colorsets 0, 1, 2 and 3 and then changes colorset 3 +to have a foreground of wheat, a background of navy. + +------ +*FvwmTheme: Colorset 3 bg "navy blue" +------ + +changes the background color of colorset 3 to navy blue. The foreground and +pixmap are unchanged. + +------ +*FvwmTheme: Colorset 3 AspectPixmap large_murky_dungeon.xpm +------ + +Causes depression. + +------ +*FvwmTheme: Colorset 3 bg Average +------ + +Sets the background color and the relief colors to match the background pixmap. +This is the default setting but it must be used if a background color was +specified and is now not required. + +------ +*FvwmTheme: Colorset 3 YGradient 200 3 \ + blue 1000 navy 1 blue 1000 navy +------ + +Adds a Yin Yang gradient background pixmap to colorset 3. If the background is +set to average it is recomputed along with the foreground if that is set to +contrast. + +------ +#!/bin/sh +FvwmCommand "SendToModule FvwmTheme Colorset 7 fg navy, bg gray" +while true +do + FvwmCommand "SendToModule FvwmTheme Colorset 7 fg gray" + sleep 1 + FvwmCommand "SendToModule FvwmTheme Colorset 7 fg navy" + sleep 1 +done +------ + +Makes colorset 7 blink. + +The color names used in colorsets can be substituted in any fvwm command. +Please refer to the *COMMAND EXPANSION* section in the fvwm man page and the +example below for a description. + + +SAMPLE FVWM CONFIGURATION +------------------------- + +Below you can find a fvwm configuration file that demonstrates the use of the +*FvwmTheme* module. The order in which *FvwmTheme* and the other modules are +configured and started is important. + +------ +# where your images are +ImagePath + +# +# FvwmTheme +# +# The FvwmTheme setup must be first in the config file, +# right after the paths are set. +# +# Instead of the *FvwmTheme: Colorset... lines below you +# could read in a file with these commands. So to change +# your color scheme you can simply copy a different file +# over your palette file and restart fvwm: +# +# Read /home/my_user_name/.fvwm/.fvwm_palette +# + +# 0 = Default colors +# 1 = Inactive windows +# 2 = Active windows +# 3 = Inactive menu entry and menu background +# 4 = Active menu entry +# 5 = greyed out menu entry (only bg used) +# 6 = module foreground and background +# 7 = hilight colors +*FvwmTheme: Colorset 0 fg black, bg rgb:b4/aa/94 +*FvwmTheme: Colorset 1 fg black, bg rgb:a1/b2/c8 +*FvwmTheme: Colorset 2 fg black, bg rgb:da/9a/68 +*FvwmTheme: Colorset 3 fg black, bg rgb:b4/aa/94, \ + VGradient 100 dtcolor5 rgb:b4/aa/94 +*FvwmTheme: Colorset 4 fg black, bg rgb:b4/aa/94 +*FvwmTheme: Colorset 5 fg rgb:d2/bf/a8, \ + bg rgb:b4/aa/94 +*FvwmTheme: Colorset 6 fg black, bg rgb:b4/aa/94, \ + VGradient 100 dtcolor5 rgb:b4/aa/94 +*FvwmTheme: Colorset 7 fg black, bg rgb:94/ab/bf + +# run FvwmTheme before anything else is done +ModuleSynchronous Timeout 5 FvwmTheme + +# +# general setup +# +Style * Colorset 1 +Style * HilightColorset 2 +MenuStyle * MenuColorset 3 +MenuStyle * ActiveColorset 4 +MenuStyle * GreyedColorset 5 + +# +# Applications +# +AddToFunc InitFunction ++ I Exec exec xterm -fg $[fg.cs0] -bg $[bg.cs0] + +# +# module setup +# + +# ... more FvwmPager config lines ... +*FvwmPager: Colorset * 6 +*FvwmPager: BalloonColorset * 6 +*FvwmPager: HilightColorset * 7 +*FvwmPager: WindowColorsets 1 2 + +# ... more FvwmIconMan config lines ... +*FvwmIconMan: Colorset 6 +*FvwmIconMan: FocusColorset 2 +*FvwmIconMan: FocusAndSelectColorset 2 +*FvwmIconMan: PlainColorset 6 +*FvwmIconMan: SelectColorset 6 +*FvwmIconMan: TitleColorset 6 + +# ... more FvwmButtons config lines ... +*FvwmButtons: Colorset 6 +# sample button passing color to xterm +*FvwmButtons: (Title xterm, \ + Action "Exec exec xterm -fg $[fg.cs6] -bg[bg.cs6]") + +# ... more FvwmWharf config lines ... +*FvwmWharf: Colorset 6 + +# ... more FvwmIdent config lines ... +*FvwmIdent: Colorset 6 + +# ... more FvwmWinList config lines ... +*FvwmWinList: Colorset 1 +*FvwmWinList: FocusColorset 2 +*FvwmWinList: IconColorset 1 + +# ... more FvwmTaskBar config lines ... +*FvwmTaskBar: Colorset 6 +*FvwmTaskBar: IconColorset 6 +*FvwmTaskBar: TipsColorset 0 +------ + +If you need to have more colors and don't want to reinvent the wheel, you may +use the convention used in fvwm-themes, it defines the meaning of the first 40 +colorsets for nearly all purposes: + +http://fvwm-themes.sourceforge.net/doc/colorsets + + +BUGS +---- + +Initialization of fvwm, *FvwmTheme* and the other modules is tricky. Please +pay close attention to the text in the *INVOCATION* section. The example above +demonstrates the proper way to get a *FvwmTheme* setup running. + + +AUTHOR +------ + +Prefers to remain anonymous. With help from Brad Giaccio and Dominik Vogt. + + +COPYRIGHT +--------- + +Copyright (C) 1999 Joey Shutup. 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. diff --git a/Documentation/FvwmModules/TODO b/Documentation/FvwmModules/TODO index fd0d0e365..3ccc1dc4d 100644 --- a/Documentation/FvwmModules/TODO +++ b/Documentation/FvwmModules/TODO @@ -1,29 +1,17 @@ List of not converted Fvwm modules: -FvwmCommand *in work* -FvwmConsole -FvwmConsoleC.pl -FvwmCpp FvwmDragWell -FvwmEvent -FvwmForm FvwmGtk (deprecated?) FvwmGtkDebug (deprecated?) FvwmIconBox (deprecated?) FvwmIconMan -FvwmIdent -FvwmM4 -FvwmPager FvwmPerl FvwmProxy -FvwmRearrange FvwmSave (deprecated?) FvwmSaveDesk (deprecated?) FvwmScript -FvwmScroll FvwmTabs FvwmTaskBar -FvwmTheme FvwmWharf FvwmWindowMenu FvwmWinList From 26ea5f3caee1002a68a4b21c8f978e3270d35064 Mon Sep 17 00:00:00 2001 From: Thomas Funk Date: Thu, 1 Mar 2012 23:50:40 +0100 Subject: [PATCH 06/16] New FvwmModule FvwmCommand --- Documentation/FvwmModules/FvwmCommand.txt | 434 ++++++++++++++++++++++ 1 file changed, 434 insertions(+) create mode 100644 Documentation/FvwmModules/FvwmCommand.txt diff --git a/Documentation/FvwmModules/FvwmCommand.txt b/Documentation/FvwmModules/FvwmCommand.txt new file mode 100644 index 000000000..1d0e9b475 --- /dev/null +++ b/Documentation/FvwmModules/FvwmCommand.txt @@ -0,0 +1,434 @@ +FvwmCommand(1) +============== +:doctype: manpage + +NAME +---- + +FvwmCommand - fvwm command external interface + + +SYNOPSIS +-------- + +FvwmCommand [-cmrvw] [-S name] [-i level] [-f name] [-F level] [command...] + + +DESCRIPTION +----------- + +*FvwmCommand* lets you monitor fvwm transaction and issue fvwm command +from a shell command line or scripts. *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' '