NAME

gs − get a text string from a dialogue box

SYNOPSIS

gs [ −z ] [ −r width height ] [ −t timeout ] [ −n title ] [ −standard X Toolkit options ...  ] [ text to be displayed ]

DESCRIPTION

Gs is a utility designed for use in shell scripts for obtaining short text responses from users. 

Gs opens a window containing a box to display the text passed on the command line.  If the −r option is present, another box is created into which the user may enter a reply (the maximum number characters that may be entered is given by widthxheight fields from the −r option).  The reply box allows simple character editing (such as cursor movement, character insertion and deletion).  The window can be closed and any text typed by the user sent to standard output by clicking the ‘Finished’ button with the mouse.  The window is also closed and any text sent if a timeout has been specified (see the −t option) and this has been exceeded. 

Gs can take the following options:

−z No Zoom.  Gs will attempt to bypass the window manager and appear immediately, rather than going through the window manager’s placement and sizing scheme. 

−r width height
A reply box of width characters wide and height characters high will be created (if the window manager or screen size allows).  The maximum number of characters the user may enter is always widthxheight characters.  The text in the reply box may be scrolled if the box cannot be made large enough or lots of short lines have been entered. 

−n title or −title title
Specifies the title for the gs window.  The default, if this option is not supplied, is ‘Get string’. 

−t number
Specifies a timeout value (in seconds) in which the user must enter a reply. If the time limit is exceeded, any text already typed will be sent to s’ standard output and gs will exit. 

Gs additionally recognizes the following standard X Toolkit command line arguments:

−bg colour or −background colour
This option specifies the colour to use for the background of the window and widgets.  The default is ‘white.’

−bd colour or −bordercolor colour
This option specifies the colour to use for the border of the main window. The default is ‘black.’

−bw number or −borderwidth number
This option specifies the width in pixels of the border surrounding the main window.

−fg colour or −foreground colour
This option specifies the colour to use for the text.  The default is ‘black’.

−fn font
This option specifies the font to be used for displaying the text warning message.  The default is ‘serif10’.

−name name
This option specifies the application name under which resources are to be obtained, rather than the default executable file name, ‘gs’.

−geometry geometry
This option specifies the preferred size and position of the gs window; see X(1);

−display display
This option specifies the X server to contact; see X(1). 

−xrm resourcestring
This option specifies a resource string to be used.  This is especially useful for setting resources that do not have separate command line options.

X DEFAULTS

Gs is implemented using the Athena widgets.  Each widget can individually or in groups have various visual and operational aspects changed via a ‘.Xdefaults’ file on the client machine or the ‘RESOURCE_MANAGER’ property on the server.  All widgets have a common set of resources (background, backgroundPixmap, etc.) and resources unique to each type of widget; a ‘command button’ widget, for example, also has a cursor resource.  For a full list see the document X Toolkit Widgets - C Language X Interface. 

The path names and types of all widgets used by gs are as follows:

XXX.gsbox
The widget that is a child of root.  All the other widgets used by the gs box are children or grand children of this widget.

XXX.gsbox.contents
A form widget that manages the layout of the gs box.  Normally completely covers the ‘gsbox’ widget.

XXX.gsbox.contents.message
A widget to display and format the text message.

XXX.gsbox.contents.Finished
A command button widget that when clicked causes gs to write any text entered by the user to standard output and exit. 

XXX.gsbox.contents.reply
A text widget where the user can type a reply.

Additionally, the following item is also fetched from the resource database:

backgroundPixmap.foreground
One of two colours (the other is the widget’s background colour) required when converting a bitmap file into a pixmap for use as the widget’s background pixmap.

RETURN CODES

0 − Termination via the tick box or the timeout value being exceeded. 

2 − Termination due to some internal error. 

ENVIRONMENT

DISPLAY - the default host and display number of the X server. 

XENVIRONMENT - the name of the Xdefaults file to use (normally
$HOME/.Xdefaults).

EXAMPLES

gs -r 40 1 Please enter the name of a file to edit

Will open an gs box with the title Get string and containing a box displaying the text Please enter the name of a and another box where the user may type upto 40 characters. 

FILES

$HOME/.Xdefaults /usr/lib/X11/app-defaults/Xopentop

SEE ALSO

alert(1), yorn(1)

BUGS

If the font is too large or the message too long, the text will be clipped and the window will have to be scrolled before the whole message may be read. 

The title may not be displayed if the window manager does not provide title bars around windows or the −z option is used. 

AUTHOR

Gary Henderson & Mark E. Howells, Torch Computers Ltd. 

X Version 11  —  3 October 1988