home page
   
Manual page for getgui(1)(TDH)

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

    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/jimmy/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
    

    See also the getgui illustrated examples page.

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

    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

    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/jimmy/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.


        2004.     getgui home page is http://getgui.sf.net


    Copyright statement


    Markup created by unroff 1.0,    April 21, 2005.