FvwmForm(1)FvwmForm(1)NAMEFvwmForm - input form module for Fvwm
SYNOPSISFvwmForm must be spawned by Fvwm. It will not work from the command
line.
DESCRIPTIONFvwmForm 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 text input field can be used to edit a single-line
string. FvwmForm accepts Emacs-style cursor movement keys. No copying
and pasting functions exist.
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 clicked on, will send a set of commands to Fvwm.
FvwmForm will do variable substitutions in the command text to reflect
the user's input.
INITIALIZATIONFvwmForm uses the same configuration file (usually .fvwmrc in the
user's home directory) as Fvwm. To use FvwmForm for multiple input
forms, simply create symbolic links with different names, and they will
be treated as different modules. Or, you can invoke FvwmForm with an
optional parameter, which it will use as the name instead (e.g. 'Module
FvwmForm QuitVerify'). That way you don't even have to make a symbolic
link for it!
Be sure to set ModulePath in your .fvwmrc file to include FvwmForm's
path.
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.
CONFIGURATION
The following options can be set in the .fvwmrc file. Note that the
string "FvwmForm" should be changed if another module with different
name is used.
The order of the options DOES matter. In general, colors and fonts
should be specified first. Lines, text labels, and input items should
appear in their logical order.
*FvwmFormGrabServer
This option makes FvwmForm grab the mouse pointer on startup. This
feature is useful for things like logout verification.
*FvwmFormWarpPointer
This option makes FvwmForm warp the mouse pointer into its window
on startup. It saves the user some mouse-travelling.
*FvwmFormPosition x y
Puts the FvwmForm window at location (x, y) on the screen. By
convention, a negative x (resp. y) value measures distance from the
right (resp. bottom) of the screen.
If this option is omitted, FvwmForm will start at the center of the
screen.
*FvwmFormBack color
Specifies the background color of the FvwmForm window.
*FvwmFormFore color
Specifies the foreground color for displaying plain text.
*FvwmFormItemBack color
Specifies the background color for the text input windows, and the
buttons.
*FvwmFormItemFore color
Specifies the foreground color for the text input strings and
button markers.
*FvwmFormFont font
Specifies the font for displaying plain text.
*FvwmFormButtonFont font
Specifies the font for text marked in the action buttons.
*FvwmFormInputfont font
Specifies the font for text input. This font must have fixed
width.
*FvwmFormLine justification
Starts a new line. A line can contain an arbitrary number of items
whose options should follow. A FvwmForm window can have an
arbitrary 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 spreaded to fill the whole width of
the window.
*FvwmFormText string
Displays string as plain text. Line breaks must be achieved by
multiple *FvwmFormLine and *FvwmFormText options. Blanks may be
used to provide extra padding between items.
*FvwmFormInput name size init_string
Specifies a text input item with name name. A subwindow of size
characters in width will be used for editting. If init_string is
present, it will be the initial string when FvwmForm starts or
resets itself. The default initial string is "".
*FvwmFormSelection name type
This option starts a selection item with name name. Its choices
should be specified on the subsequent lines. The option type is
one of the following:
single The selections are mutually exclusive.
multiple This is a multiple-choice selection.
*FvwmFormChoice name value on | off string
Specifies a choice for a selection. The choice item has a name and
a value. The string will be displayed to the right of the choice
button as a label.
The choice will assume the specified initial state ("on" means
selected) when FvwmForm starts or resets. Note that if the
selections are mutually exclusive, FvwmForm will 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 will assure only one is selected.
*FvwmFormButton type string [key]
This option specifies an action button. The button has string as a
label, and excutes a set of Fvwm command when it is activated. The
commands should be specified using the *FvwmFormCommand option.
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, RETURN, LINEFEED,
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 will resume execution after sending the
commands.
restart After sending the commands, FvwmForm will reset all the
values to the initial ones, and then resume execution.
quit FvwmForm will quit after sending the commands.
*FvwmFormCommand command
This option specifies an Fvwm command associated with the current
button. Commands that appear before any *FvwmFormButton option
will be executed at start-up time. This is usually a beep that
gets the user's attention.
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. Special chars such as ",
', and will be preceded by a backslash.
If name corresponds to a choice, the result is the
value of the choice (as specified in *FvwmFormChoice)
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.
$(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.
EXAMPLE 1 - QuitVerify
This example simulates the mwm way of confirming logout.
*QuitVerifyGrabServer
*QuitVerifyWarpPointer
*QuitVerifyFont *helvetica*m*r*n*14*
*QuitVerifyButtonFont *helvetica*m*o*n*14*
*QuitVerifyFore Black
*QuitVerifyBack Light Gray
*QuitVerifyItemFore Wheat
*QuitVerifyItemBack Gray50
# begin items
*QuitVerifyCommand Beep
*QuitVerifyLine center
*QuitVerifyText "Do you really want to logout?"
*QuitVerifyLine expand
*QuitVerifyButton quit "Logout" ^M
*QuitVerifyCommand Quit
*QuitVerifyButton quit "Cancel" ^[
*QuitVerifyCommand Nop
# Fvwm window style
Style "QuitVerify" NoTitle, NoHandles, BorderWidth 3
EXAMPLE 2 - Remote Login
This example lets the user type in a hostname, and optionally a user
name on the remote machine, and opens an xterm window from the remote
host.
*RloginWarpPointer
*RloginFont *helvetica*m*r*n*14*
*RloginButtonFont *helvetica*m*o*n*14*
*RloginInputFont *cour*m*r*n*14*
*RloginFore Black
*RloginBack Light Gray
*RloginItemFore Wheat
*RloginItemBack Gray50
# begin items
*RloginLine center
*RloginText "Login to Remote Host"
*RloginLine center
*RloginText "Host:"
*RloginInput HostName 20 ""
*RloginLine center
*RloginSelection UserSel single
*RloginChoice Default Default on "same user"
*RloginChoice Custom Custom off "user:"
*RloginInput UserName 10 ""
*RloginLine expand
*RloginButton quit "Login" ^M
*RloginCommand Exec exec rsh $(Custom?-l $(UserName)) $(HostName) xterm
-T xterm@$(HostName) -display $HOSTDISPLAY &
*RloginButton restart "Clear"
*RloginButton quit "Cancel" ^[
*RloginCommand Nop
EXAMPLE 3 - Capture Window
This example provides a front-end to xwd, xwud, and xpr.
*CaptureFont *helvetica*m*r*n*14*
*CaptureButtonFont *helvetica*m*o*n*14*
*CaptureInputFont *cour*m*r*n*14*
*CaptureLine center
*CaptureText "Capture Window"
*CaptureLine left
*CaptureText "File: "
*CaptureInput file 25 "/tmp/Capture"
*CaptureLine left
*CaptureText "Printer: "
*CaptureInput printer 20 "ps1"
*CaptureLine expand
*CaptureSelection PtrType single
*CaptureChoice PS ps on "PostScript"
*CaptureChoice Ljet ljet off "HP LaserJet"
*CaptureLine left
*CaptureText "xwd options:"
*CaptureLine expand
*CaptureSelection Options multiple
*CaptureChoice Brd -nobdrs off "No border"
*CaptureChoice Frm -frame on "With frame"
*CaptureChoice XYZ -xy off "XY format"
*CaptureLine expand
*CaptureButton continue "Capture" ^M
*CaptureCommand Exec exec xwd -out $(file) $(Options) &
*CaptureButton continue "Preview"
*CaptureCommand Exec exec xwud -in $(file) &
*CaptureButton continue "Print"
*CaptureCommand Exec xpr -device $(PtrType) $(file) | lpr -P
$(printer) &
*CaptureButton quit "Quit"
BUGS AND LIMITATIONS
There is a hard-coded limit on the number of items.
Report bugs to ztfeng@math.princeton.edu.
COPYRIGHTFvwmForm is original work of Thomas Zuwei Feng.
Copyright Feb 1995, Thomas Zuwei Feng. No guarantees or warantees 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.
March 1, 2011
