getgui(1)

This page contains these sections:     Description     A few examples     Environment     Command line options         Message text and title         Specifiying GUI control type         Managing user's selection         Detail options

See also:      Welcome       What's new       Download

Description

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

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

See also the getgui illustrated examples page.

An interactive demo is included with all distributions in the ./examples directory.

Environment

getgui requires X11 and uses xlib. Standard x11 command line args such as -geometry or -bg are not supported.

Command line options

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)

-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).

Buttons can't be initialized. There are some additional detail options for buttons. Example: -buttons "Yes|No|Maybe".

-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).

If user types nothing, result can be zero-length, and application should be prepared for this. An initial default value may be supplied using -initval . There are some additional detail options for key entry field. Example: -keyin Example: -keyin 20

-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).

If user selects nothing, result can be zero-length, and application should be prepared for this. Single-choice line mode is the default selection mode, but see -multichoice, -wordselect, and chunkselect. Alternate result representations are available, see -shortpick and -ipick. An initial default value may be supplied using -initval. -selectbox 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 select boxes. Example: -selectbox "choice1\nchoice2\nchoice3"

-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

-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

-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

-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

-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

-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

-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

Author

Send bug reports and correspondence to scg at jax dot org