--- name: "Form" section: "1x" platform: "linux" package: "afterstep" version: "1.8.11-5woody1" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/Form" --- # Form(1x) the Afterstep input-form module ## 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 normally 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 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 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 configuration file. - \-h \| --help Print a usage message and exit successfully. - \-v \| --version Print version information and exit successfully. ## INITIALIZATION During initialization, **Form** will search for a configuration 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/share/afterstep/forms will be used. To use **Form** for multiple input forms, simply create symbolic 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-travelling. - **\*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. 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, 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 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 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 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 justified to fill the whole width of the window. - **\*FormText *string*** Displays *string* as plain text. Line breaks must be 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 subwindow of *size* characters width will be used for editting. If *init\_string* is present, it will be the initial 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 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 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 executed at start-up time. This is usually a beep that gets the user's attention. Before sending each command to Afterstep, Form 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. All non-alphanumeric characters will be preceded by a backslash, to prevent incorrect 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 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 hardhead@underworld.net. ## AUTHORS Thomas Zuwei Feng. ``` Takanori Kubota Michael Beam David Mihm [Man page] ``` ## SEE ALSO **afterstep**(1)