FvwmForm(1)                                                        FvwmForm(1)



NAME
       FvwmForm - input form module for Fvwm

SYNOPSIS
       FvwmForm must be spawned by Fvwm.  It will not work from the command
       line.

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

INITIALIZATION
       FvwmForm 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.

COPYRIGHT
       FvwmForm 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
