getgui home
Manual page for getgui(TDH)

getgui



SYNOPSIS

getgui -i other options


DESCRIPTION

getgui is a simple graphical user interface (GUI) box that can be invoked from the command line or from shell scripts to get user responses using buttons and/or key input. The user selection is written to standard output, where it may be captured by the calling script.

getgui may also be used from C programs via its simple C language API . In this mode, the user's selection is made available to the calling program in a variable. This API has some additional capabilities that the command line utility does not have.

Primary uses are as an "in progress" popup to keep users complacent while slow-to-start GUI apps are revving up, or as a pop-up alarm clock, or as a step-by-step procedural interface for "wizard" or process control applications.

Typing getgui with no arguments prints a usage message and shows a general idea of what the getgui box will look like.


AVAILABILITY

http://ploticus.sourceforge.net/getgui


SIMPLE EXAMPLE

Here's the easiest way to use getgui. Just type: getgui -i

You will be prompted for a message and a time (24 hour notation). The getgui box will then disappear, reappearing at the appointed time with the given message.


EXAMPLE - C PROGRAM API

See the included ggdemo program.


EXAMPLES - COMMAND LINE TOOL

For these examples, /bin/sh is assumed.


Example 1

The following getgui command creates a GUI box that includes a prompt and 3 buttons:

LNAME=`getgui -prompt "Please select a login" -buttons jim,sysman,faxserv `

When the user selects a button, its label is written to standard output, where the shell (/bin/sh) captures it into variable LNAME. Then the GUI box terminates.


Example 2

The following getgui command creates a GUI box that includes a prompt, a key input field of length 24 characters, and a Cancel button:

FILE=`getgui -prompt "Enter a file name" -keyinput 24 -buttons Cancel`

The user may type in a file name or click on the Cancel button. Either the typed result, or the word Cancel is written to standard output, where the shell captures it into variable FILE. Then the GUI box terminates.


Example 3

The following getgui command creates a GUI box that includes a prompt, an edit box that can hold up to 200 characters, and two buttons. The window size has been set to 5" wide by 3" high, in order to accomodate the editbox.

REMARK=`getgui -prompt "Enter your comments" -winsize 5,3 -editbox 200 -buttons OK,Cancel

The user may enter comments into the editbox, and edit using arrow keys, backspace, delete, ^K to delete a line, etc. (see KEYS below). Then, when finished, the user can press the OK key, in which case the typed comments will be written to standard output where they are captured by the shell (/bin/sh) into the variable REMARK. Or, if the user wishes to cancel without typing anything, the Cancel key may be pressed, which will cause the word ancel to be written to standard output.


OPTIONS

These command line options may be given in any order, and in any combination unless specifically prohibited:

-i

Interactive alarm clock mode.

-prompt s

Display s as the prompt string. The prompt can be one line or multiple lines.

-buttons blist

Display one or more buttons. blist is a comma delimited list of labels, for example:Red,Green,Blue. When the user clicks the mouse on one of the buttons, getgui terminates and the selected button's label is written to standard output without a newline (a button labeled OK, when used with a keyinput field or editbox, results in a "dismiss" action, and the results of the field or editbox are written to standard output). If neither -keyinput and -editbox are being used, buttons may wrap to a second row if the labels are long (or you can use \n in place of a comma in the button label list to force a break).

-keyinput nchars

Display a single-line key data entry field nchars wide. The user can type into the field until its maximum length is reached. When the user presses RETURN or TAB, getgui terminates and the contents of the field is written to standard output witout a newline. If desired, a default field value may be supplied using the -initvalue option.

-editbox nchars

Display a multi-line editbox. Max length of response is nchars, and the width and height of the editbox are determined automatically based on this. An OK button is always supplied. -editbox may be combined with additional user-specified -buttons. The user terminates input by clicking on a button. If the button is OK then the contents of the editbox is written to standard output with line breaks. If any other button is pressed, that button's label is written to standard output without a newline.

-initvalue s

s will be the initial value of the keyinput field or editbox.

-initfile f

s will load the initial value of the keyinput field or editbox from file f.

-winloc x,y

Position upper left corner of gui window at pixel location x,y. x,y may contain no embedded spaces.

-winsize w,h

Make gui window size w inches wide by h inches high. If this option is not specified, the window will be 4" wide by 3" high.

-promptfile f

Take the prompt text from file f.

-delaysec sec

Wait sec seconds before displaying the GUI box. This allows getgui to be used as a popup warning or reminder.

-attime hh:mm

Wait until time hh:mm before displaying. This allows getgui to be used as a popup warning or reminder.

-pw

Causes the characters typed into a keyinput box to be invisible. This may be useful in getting passwords.

-exec command

This may be used in order to display an 'in progress' type of message while a command is executing. Buttons or key entry cannot be used with this option. When command finishes, getgui terminates.

-set attribute value

Set various attributes.

ATTRIBUTE		DESCRIPTION 
textsize  	Prompt text point size.  Default is 12.
textalign		Alignment of prompt.  C=centered  L=flush left.
		Default is C.  L might be useful in displaying
		tabular text.
backcolor 	Background color.  Default is gray(0.8).
newlinemode	Processing of line breaks in -editbox result.  
		Default is everyline.  Choices are: 
		asis (keep newlines only where user pressed RETURN);
		everyline (put a newline at every line break);
		none (remove all newlines except the last one)
color1    	Color of buttons.  Default is yellow.
color2    	Flash color of selected button.  Default is orange.
color4    	Color of key entry field.  Default is pink.
flashtime 	Time in microseconds that button should flash when 
		selected.  Default is 150000.
buttonsize 	Point size of button label text.  Default is 12.
inputsize 	Point size of keyed characters.  Default is 14.
okstring  	String to be used to dismiss.  Default is OK.




NOTES

Buttons may be combined with either a key input field or an edit box if desired.

For consistent appearance it may be useful to store -winsize, -winloc, and any -set arguments in a shell variable and use for all invocations within a script.


KEYS

The key entry field and editbox support the VT100/xterm arrow keys and the standard editing keys used in netscape, pico, etc.
Arrow keys      move cursor
Home or Ctrl-A  cursor to beginning of line
End or Ctrl-E   cursor to end of line
Ctrl-K  delete to end of line
Ctrl-U  delete all of current line




COLORS

Colors may be specified by pre-defined name, by RGB specification, or by gray level specification. A number of named colors have been defined. These include:

white       black      red         magenta      tan1        tan2     
coral       claret     pink        orange       redorange   lightorange 
yellow      yellow2    dullyellow  yelloworange brightgreen green     
teal        drabgreen  kelleygreen yellowgreen  limegreen   brightblue  
blue        powderblue skyblue     cobaltblue   darkblue    oceanblue   
purple      lightpurple            lavender   

If none of the pre-named colors suit, a custom RGB specification in the form of rgb(R,G,B) may be used. R, G, B are values from 0.0 to 1.0 (1.0 is brightest) specify the red, green and blue components. No embedded spaces are allowed. Example: rgb(0.4,0.84,0.37)

It is also possible to specify a gray-level in the form of gray(G) or just G, where G is 0.0-1.0 grey level (1.0 is white). No embeddded spaces are allowed. Example: gray(0.8)


BUGS

If X11 color map is full, colors are usually displayed inaccurately.

For best results use an X window manager that does not require human interaction for placing new windows.

There is no scrolling listbox.


SEE ALSO

getguilib(3)


AUTHOR

Steve Grubb


Copyright Steve Grubb


Markup created by unroff 1.0,    August 15, 2003.