Form(1.8) Form(1.8)
NAME
Form - the Afterstep input-form module
SYNOPSIS
Form [-f config_file] [-v | --version] [-h | --help] name
Although Form can be run from the command line, it is nor
mally spawned by afterstep from within an afterstep menu
file by 'Form':
% cat "~/GNUstep/Library/AfterStep/start/Modules/Form"
Module "Form" Form FormName
MiniPixmap "mini-as.xpm"
DESCRIPTION
Form 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 Afterstep 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. Form accepts Emacs-style
cursor movement keys. No copying or 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 fol
lowed 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 com
mands to Afterstep. Form will do variable substitutions
in the command text to reflect the user's input.
OPTIONS
-f config_file
Use config_file instead of the default configura
tion file.
-h | --help
Print a usage message and exit successfully.
Form Feb 7 2000 1
Form(1.8) Form(1.8)
-v | --version
Print version information and exit successfully.
INITIALIZATION
During initialization, Form will search for a configura
tion file which contains the form stanzas. This file will
be the one specified by the -f option (if given). Else,
the ~/GNUstep/Library/AfterStep/forms file will be used if
it exists. Else, /usr/local/share/afterstep/forms will be
used.
To use Form for multiple input forms, simply create sym
bolic links with different names, and they will be treated
as different modules. Or, you can invoke Form with an
optional parameter, which it will use as the name instead
(e.g. 'Module Form QuitVerify'). That way you don't even
have to make a symbolic link for it!
INVOCATION
AfterStep will search through the directories specified in
the ModulePath configuration in the base.#bpp (where # is
your colordepth) to attempt to locate Form.
When Form is invoked with a window context, e.g. from a
window menu, all commands it sends to Afterstep will have
that window context.
CONFIGURATION OPTIONS
Form reads the forms file when it starts up, searches for
the form stanza name (as specified on the command line),
and prompts the user for input.
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.
*FormGrabServer
This option makes Form grab the mouse pointer on
startup. This feature is useful for things like
logout verification.
*FormWarpPointer
This option makes Form warp the mouse pointer into its
window on startup. It saves the user some mouse-trav
elling.
*FormPosition x y
Puts the Form 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.
Form Feb 7 2000 2
Form(1.8) Form(1.8)
If this option is omitted, Form will start at the cen
ter of the screen.
*FormBack color
Specifies the background color of the Form window.
*FormFore color
Specifies the foreground color for displaying plain
text.
*FormItemBack color
Specifies the background color for the text input win
dows, and the buttons.
*FormItemFore color
Specifies the foreground color for the text input
strings and button markers.
*FormFont font
Specifies the font for displaying plain text.
*FormButtonFont font
Specifies the font for text marked in the action but
tons.
*FormInputfont font
Specifies the font for text input. This font must
have fixed width.
*FormLine justification
Starts a new line. A line can contain an arbitrary
number of items whose options should follow. A Form
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 win
dow.
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 justified
to fill the whole width of the window.
*FormText string
Displays string as plain text. Line breaks must be
Form Feb 7 2000 3
Form(1.8) Form(1.8)
achieved by multiple *FormLine and *FormText options.
Blanks may be used to provide extra padding between
items.
*FormInput name size init_string
Specifies a text input item with name name. A subwin
dow of size characters width will be used for edit
ting. If init_string is present, it will be the ini
tial string when Form starts or resets itself. The
default initial string is "".
*FormSelection 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.
*FormChoice 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 Form starts or resets.
Note that if the selections are mutually exclusive,
Form 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, Form will assure only one is selected.
*FormButton type string [key]
This option specifies an action button. The button
has string as a label, and excutes a set of Afterstep
command when it is activated. The commands should be
specified using the *FormCommand option.
The optional key specifies a keyboard shortcut that
activates the button. It is either a control charac
ter, 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 Form will resume execution after sending
the commands.
restart After sending the commands, Form will
Form Feb 7 2000 4
Form(1.8) Form(1.8)
reset all the values to the initial ones,
and then resume execution.
quit Form will quit after sending the commands.
*FormCommand command
This option specifies an Afterstep command associated
with the current button. Commands that appear before
any *FormButton option will be executed at start-up
time. This is usually a beep that gets the user's
attention.
Before sending each command to Afterstep, Form recog
nizes 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.
All non-alphanumeric characters will be
preceded by a backslash, to prevent incor
rect interpretation by the shell.
If name corresponds to a choice, the
result is the value of the choice (as
specified in *FormChoice) 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 val
ues 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 substi
tution 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 vari
able 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
Form Feb 7 2000 5
Form(1.8) Form(1.8)
*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
# Afterstep window style
Style "QuitVerify" NoTitle, NoHandles, BorderWidth 3
EXAMPLE 2 - Remote Login
This example lets the user type in a hostname, and option
ally 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 $HOSTDIS
PLAY &
*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*
Form Feb 7 2000 6
Form(1.8) Form(1.8)
*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 hardhead@underworld.net.
AUTHORS
Thomas Zuwei Feng.
Takanori Kubota
Michael Beam
David Mihm <dmihm@swbell.net> [Man page]
SEE ALSO
afterstep(1)
Form Feb 7 2000 7
Man(1) output converted with
man2html