 home page
|
Manual page for getgui(1)(TDH)
getgui(1)
See also:
Welcome
What's new
Download
Description
getgui is a standalone x11 utility that is used for easily adding a degree of graphical user interface
functionality to shell scripts or other programs. getgui can display informational messages and in-progress
messages, or it can be used to get user input via dialog boxes, keyboard input fields, pulldown menus or select
boxes. "Wizard"-type procedural interfaces can be implemented using a series of getgui invocations.
Each invocation of getgui produces
one GUI box, and can return one user response. User response is
written to stdout (or in some cases user response can be conveyed
via getgui's exit code). In its simplest form it is used like this:
-
-
getgui "Welcome to getgui 2.0"
When invoked getgui automatically creates a layout of text and controls based on what is specified
in the command line arguments, crops the graphic appropriately, and displays the GUI box centered on the X11 screen
(by default), thus no position coordinates need to be specified. getgui pays attention to mouse button
presses and keyboard key presses. There is no scrolling capability anywhere, except horizontal scrolling of key
entry fields. getgui is small and lightweight, implemented using xlib with no other dependencies.
This manual page is for getgui 2.00 and higher and is intended as a concise summary of
the getgui command line options.
For further information, see
http://getgui.sf.net.
A few examples
getgui "The action has been completed."
getgui "Do you wish to continue?" -buttons "Yes|No"
getgui "Filename:" -keyin 20 -horiz
getgui -filepick -updir -dir /home/scg/myphotos
getgui "Password:" -password 8 -horiz
getgui "Select one:" -selectbox "red\ngreen\nblue\nyellow" \
-buttons "OK|Cancel"
getgui "Copying files.." -progress -clrfile tmpclr
alarmclock
(Note: alarmclock is an interactive getgui-based popup alarm clock reminder
available in versions 2.02+)
An example where user input is captured into a shell variable (/bin/sh) using backquotes:
file=` getgui "Filename:" -keyin 20 -buttons "OK|Cancel" `
if [ "$file" = "Cancel" ]; then
exit
fi
An interactive demo is included with all distributions in the ./examples directory.
Environment
DISPLAY - names the X11 display
getgui requires X11 and uses xlib.
Standard x11 command line args such as -geometry or -bg are not supported.
Command line options
Options can be given in any order. If one option overrides another, it should be specified to the right of
the one it is overriding.
If the leftmost (first) option does not begin with a dash, it is taken as the message text (-msg).
Message text and title
-msg
messagetext
-
-
The prompt / message text. Can be one line or multiple lines.
Newlines can be represented using the characters \n.
Text lines will be presented as specified; getgui does not perform its own text wrapping.
getgui uses only one font, with no provision for inline size, font, super/subscripts, or color changes.
There are some
additional detail options for message text.
Example: -msg "Enter password"
|  |
-title
titletext
-
-
Optional title text. The title will appear above the prompt/message text
in a larger font. A horizontal rule will appear below the title.
Can be one line or multiple lines.
Text lines will be presented as specified; getgui does not perform its own text wrapping.
Newlines can be represented using the characters \n.
Example: -title "Welcome"
Specifying GUI control type(s)
One of the following GUI control types may be specified. In addition, -buttons
can be combined with any of the other controls. No other combinations are permitted.
-buttons
labellist
-
-
Display one or more buttons. labellist contains the text for the labels,
with each button label delimited by a pipe symbol (|). Buttons can be used alone, or combined with
one of the other control types.
Result (by default) is the text of the selected button label (see also
-shortpick and -ipick).
-keyin
[charwidth]
-
-
Indicates that the GUI box will be a keyboard input field.
If charwidth is specified, the field will be that many characters wide (default is 15 chars wide).
Input beyond this length is accomodated by scrolling, up to a max of 128.
-buttons (one of which should be OK) may also be specified.
Input is terminated when user presses Enter, Tab, or clicks on a button.
The result value will be the text that the user typed, or a button label if the user
presses a button other than "OK" (see also
-okstr).
-password
[charwidth]
Same as -keyin, but typed characters are masked.
Example: -password 8
|  |
-selectbox
choices
-
-
Indicates that the GUI box will be a select box.
The 'choices' argument specifies the menu choices. It may be literal text with each line delimited with a newline,
or it may be a unix command prefixed with an exclamation mark (!).
(Newlines can be represented using the characters \n in literals.)
-buttons (one of which should be OK) may also be specified;
if none are specified an "OK" button is automatically supplied.
The result value will be the text of the user's selection, or a button label if the user
presses a button other than "OK" (see also
-okstr).
-pulldown
choices
Same as -selectbox but the GUI will function as a pulldown menu. -multichoice not supported.
If no -buttons specified GUI returns immediately after user makes a selection.
-pulldown does not have scrolling capability and thus won't be ideal when number of selections grows to be too large.
There are some
additional detail options for pulldowns.
|  |
-filepick
[filepat]
-
-
Indicates that the GUI box will be a file select box.
A default prompt and buttons are supplied (these may be overridden).
Operates in the current directory unless
-dir is specified. -updir may be used to enable "Go up one level" functionality.
The result value will be the selected filename, or a button label if the user
presses a button other than "OK" button (see also -okstr).
Implemented by capturing the result of
unix command ls -C, or if filepat is given, ls -C filepat;
this may be overridden using -content.
-filepick does not have scrolling capability, thus it won't be ideal for
directories having a large number of files (say > 300 or so).
More about -dir -updir and -content
Example: getgui -filepick
-progress
-
-
Indicates that the GUI box will be an in-progress type message, and an asynchronous process.
The getgui command should be run in the background.
No output will be written to standard output.
Should be used with -clrfile so box can be removed after some period of time.
Another possible option is to retain the asynchonous process' id and kill it later.
-buttons may be supplied for asynchronous actions (see -btnfile).
More about -clrfile and -btnfile
Example: -progress
|  |
Options pertaining to managing user selection
-initval
value
-
-
When used with -keyin, -filepick, -selectbox, or -pulldown, it specifies a
value that will initially appear as selected, to provide the user with a default value.
If -shortpick or -ipick are used this value should conform to these modes.
Example: -initval "generic1"
-okstr
tag
-
-
When buttons are used along with other types of controls, a button labeled OK
has special connotations associated with it.. when the user
presses OK it indicates that the selected or keyed value is to be written to
standard output rather than the text "OK". -okstr allows you to specify
some other button label to operate this way.
Example: -okstr Next
-shortpick
-
-
When used with -buttons, -selectbox, or -pulldown, this specifies
that the result value will consist of only the first whitespace-delimited token of the label,
rather than the entire label text.
This makes handling the selected result more convenient when multiword labels are used.
Not compatible with -ipick.
-ipick
-
-
When used with -buttons, -selectbox, or -pulldown, this specifies
that the result value will be the ordinal position of the selection, rather than the
label text. For instance
if the leftmost button is selected, the result will be 1. This value also becomes
getgui's exit code.
Not compatible with -shortpick.
-omitn
-
-
Omit the trailing newline on response result.
Detail options - layout and window appearance
-horiz
-
-
Specifies that the GUI box layout will be horizontal, with title and message text
to the left, and buttons (etc.) to the right.
-horiz is useful in setting up "wizard"-type interfaces.
Example: -horiz
-winname
name
-
-
The name for getgui's X11 window. If not specified a reasonable default will be supplied.
Example: -winname "Select a node"
-winx
pixel_loc
-winy
pixel_loc
-
-
Explicitly specify X and/or Y location in pixels for upper left corner of getgui X11 window.
Default is for getgui window to be centered on the X11 screen.
To position the getgui window closer to the top of the screen yet still horizontally centered,
specify -winy but not -winx.
Pixel location origin is upper left corner.
Example: -winy 180
Example: -winx 650 -winy 10
-winfixw
width
-winfixh
height
-
-
Set a fixed window width and height in inches. Normally the getgui window is sized automatically based on content,
but fixed sizing may be useful in certain situations, eg. where other application windows need to remain fully visible.
Content will be centered in window, and clipped to window.
Both -winfixw and -winfixh must be specified in order to get a fixed size window.
Example: -winfixw 3.5 -winfixh 2.5
-bgcolor
color
-
-
Background color for the getgui window.
Color specifications
Example: -bgcolor xrgb:a0a0ff
-winmarg
margin
-
-
Amount of margin to supply on all four sides when rendering the getgui window, in inches.
Not compatible with winfixw / winfixh.
Example: -winmarg 0.3
Detail options - message and title
These detail options pertain to
-msg
and in some cases, -title.
-msgsize
pointsize
-
-
Point size for the message text. Title text will always be a couple of pointsizes larger.
Example: msgsize: 12
-msgalign
left|center|right
-
-
Alignment of message text. Default is center, or left with -horiz.
Example: -msgalign left
-msgcolor
color
-
-
Color for the message text.
Color specifications
Example: -msgcolor red
Detail options - buttons
These detail options pertain to
-buttons
-btnwrap
nchars
-
-
If specified, a set of buttons will wrap to an additional tier when the length exceeds nchars.
Default is 60.
Example: -btnwrap 30
-btnsize
pointsize
-
-
Point size for the button label text. This also influences the overall size of the buttons.
Example: -btnsize 14
-btncolor
color | colorlist | multi
-
-
Color for the buttons. May be one color, a bar-delimited list of colors, or the special
symbol multi. If there are more
buttons than colors specified, the last color will repeat for the remaining buttons.
Color specifications
multi gives a preselected set of button colors.
Example: -btncolor "gray:0.9"
Example: -btncolor "gray:0.7|tan1"
Example: -btncolor multi
-btnalign
left|center|right
-
-
Alignment of a set of buttons. Default is center, or right with -horiz.
Example: -btnalign left
-btnsep
distance
-
-
If specified, individual buttons will be separated by this distance in inches.
Example: -btnsep 0.1
-btndress
outline|bevel|drop
Specifies the dressing to be added to buttons, either a simple outline, a bevel (the default), or
a drop shadow.
Example: -btndress outline
|  |
Options related to -keyin
These detail options pertain to
-keyin
controls.
-keymax
nchars
-
-
Specify the maximum number of characters that can be entered. Default is 128.
If nchars is greater than the field width, the field will scroll horizontally to
accomodate longer input.
-keysize
pointsize
-
-
Point size for the -keyin text.
-keyend
-
-
If specified, the GUI box will terminate when user presses Enter or Tab, even if
buttons are present. New in version 2.01.
-keycursor n
-
-
Control the initial position of cursor, when an -initval is given.
Default is for initial cursor position to be at end of content.
Use -keycursor 0 to position cursor at beginning of content. New in 2.02.
Detail options - select boxes and pulldowns
These detail options pertain to
-selectbox
and
-pulldown
controls.
-multichoice
When used with -selectbox, specifies that multiple choices be permitted.
Example: -multi
|  |
-commalist
-
-
Express the result of a -multichoice -selectbox as a comma-delimited list, rather
than a list of one selection per line.
-wordselect
When used with -selectbox, specifies that each whitespace-delimited "word" in
the selection area is to be managed as a separate choice. Programmer may need to pad with
tabs or spaces so that the choices form straight columns.
Example: -wordselect
|  |
-chunkselect
-
-
Same as -wordselect except that choices are delimited by two or more whitespace characters.
This allows a choice to contain embedded singleton spaces.
-pullorient
top|bottom|center
-
-
Specifies the direction that the pulldown menu will extend when deployed. top = upward,
bottom = downward, and center causes the pulldown choices to be centered.
Main purpose is to allow programmer to specify center when the number of choices is large,
so that they all fit on the screen.
-selsize
pointsize
-
-
Point size for the -selectbox and -pulldown entries. Also influences the overall size.
Detail options for -filepick
These detail options pertain to
-filepick
controls.
-dir
pathname
-
-
Specifies a directory to operate in when listing files.
Example: -dir /home/scg/photos
-updir
-
-
If specified, allows user to select Go up one level, which prints a result of ../.
By default this is not enabled.
Example: -updir
-content
text
-
-
Specifies an alternative to the default ls -C command for filling the filepick selection area.
May be a unix command prefaced by an exclamation point (!), or literal text content.
Example: -content "!myprog"
Detail options for in-progress messages
These detail options pertain to
-progress
messages.
-clrfile
filename
-
-
After a -progress message is displayed, getgui will repeatedly check for the
existence of the specified file several times per second. The invoking application should
create this file (as a semaphore) when it is time for the in-progress message to go away.
When this file is detected, getgui will remove the GUI window.
The file will be automatically deleted by getgui.
-btnfile
filename
-
-
This option is used with -progress messages that include -buttons.
When the user selects a button, a file by this name is created (as a semaphore) and
the button label value written into it. The invoking application should check
for the existence of this file from time to time as it does its work, and when
it finds it, take some action. Typical use is for a "Cancel" button that will
abort the operation.
Misc.
-echoargs
-
-
If specified, the complete command line is copied to stderr, for illustrative/training purposes.
-sleepmin
n
-
-
If specified, getgui will sleep for n minutes before doing anything (new in 2.01),
allowing getgui to be used as a popup reminder.
-async
-
-
If specified, getgui will output a line of text containing the string !waiting!
to stdout every 1/2 second. This allows C programs that are invoking getgui
to use popen() and fgets() and still do other things while awaiting getgui user response.
(new in 2.01)
See also
xmessage(1)
an early X11 utility still present in some releases that presents user with text and buttons.
getgui is an xmessage alternative, an alternative to xmessage.
getgui is an xmessage replacement, a replacement for xmessage.
xedit(1) a simple editor that may serve as a way to get multiline text responses,
something that's no longer provided with getgui.
Author
Steve Grubb
2004.
getgui home page is
http://getgui.sf.net
Send bug reports and correspondence to scg at jax dot org
|

Copyright Steve Grubb
|