MAN page from Old RedHat 5.X AfterStep-1.4-RH5.i386.rpm

Form

Section: Misc. Reference Manual Pages (1.0)
Index

NAME

Form - input form module for Afterstep

SYNOPSIS

Form must be spawned by Afterstep. It will not work from the command line.

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 and pasting functions exist.

A selection consists of several choices.The selection itself is a logical entity that doesn't have any displayfeature.Each choice is displayed as a push-button followed by a explanatorytext 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 toAfterstep.Form will do variable substitutions in the command text to reflectthe user's input.

INITIALIZATION

Form uses the form configuration file (usually ~/GNUstep/Library/AfterStep/form)To use Form for multiple input forms, simply create symbolic links withdifferent names, and they will be treated as different modules. Or, you caninvoke 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 makea symbolic link for it!

Be sure to set ModulePath in your base file to include Form's path.

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

The following options can be set in the form file.Note that the string "Form" should be changed if another module withdifferent 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.

*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-travelling.

*FormPosition x y

Puts the Form window at location (x, y) on the screen.By convention, a negative x (resp. y) value measuresdistance from the right (resp. bottom) of the screen.

If this option is omitted, Form will start at the center 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 windows, andthe buttons.

*FormItemFore color

Specifies the foreground color for the text input strings and buttonmarkers.

*FormFont font

Specifies the font for displaying plain text.

*FormButtonFont font

Specifies the font for text marked in the action buttons.

*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 shouldfollow.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 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 wholewidth of the window.

*FormText string

Displays string as plain text.Line breaks must be achieved by multiple *FormLine and *FormTextoptions.Blanks may be used to provide extra padding between items.

*FormInput 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 whenForm 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 buttonas 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 activatesthe 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 fieldscannot 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 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 executedat start-up time. This is usually a beep that gets the user's attention.

Before sending each command to Afterstep, Form recognizes variables of thefollowing 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 *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 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

# Afterstep 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 hardheadAATTunderworld.net.

AUTHORS

Thomas Zuwei Feng.

Takanori Kubota

Michael Beam

This document was created byman2html,using the manual pages.