| FVWMFORM(1) | Fvwm Modules | FVWMFORM(1) |
FvwmForm - input form module for Fvwm
Module FvwmForm [ Alias ]
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.
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.
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.
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.
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 Separator 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
*FvwmForm: WarpPointer
*FvwmForm: Geometry geometry
*FvwmForm: Position x y
If this option is omitted, FvwmForm starts at the center of the screen.
*FvwmForm: Colorset n
*FvwmForm: Back color
*FvwmForm: Fore color
*FvwmForm: ItemColorset n
*FvwmForm: ItemBack color
*FvwmForm: ItemFore color
*FvwmForm: Font font
*FvwmForm: ButtonFont font
*FvwmForm: InputFont font
*FvwmForm: TimeoutFont font
*FvwmForm: Line justification
Justification of items in the line is specified by justification, which can be one of the following:
left
right
center
expand
*FvwmForm: Message
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
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
*FvwmForm: Title string
*FvwmForm: Input name size init_string
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
single
multiple
*FvwmForm: Separator
*FvwmForm: Choice name value on | off string
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]
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
restart
quit
*FvwmForm: Command command
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 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 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)
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
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
*FvwmForm: ButtonInPointer pointername
*FvwmForm: InputPointer pointername
*FvwmForm: ButtonPointerFore|Back color
*FvwmForm: ButtonInPointerFore|Back color
*FvwmForm: InputPointerFore|Back color
*FvwmForm: Timeout tenth_of_seconds command "text"
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
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 200 Quit "Automatic logout will occur in %% tenth of seconds."
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 x term@$(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
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"
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
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.
FvwmForm is original work of Thomas Zuwei Feng ( <ztfeng@math.princeton.edu>).
Copyright 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.
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.
| 2023-01-17 |