getgui home
Manual page for getguilib(TDH)

getguilib - C API



DESCRIPTION

getguilib is a compact C function library of ten subroutines that implement a simple procedural graphical user interface . Also available is the getgui command line utility .


AVAILABILITY

http://ploticus.sourceforge.net/getgui


COMPILATION OF APPLICATIONS

A C compiler such as gcc is required. Applications should link against ./getguilib.a


FUNCTION LIBRARY

The following is a description of the getguilib C functions.

getgui_init( char *name, double width, double height, int x, int y )

Create a window where the GUI will appear. name is arbitrary and will appear as the window label. width and height are the size of the window in inches. x and y are the screen pixel location of the upper left corner of the window.
Example: getgui_init( "My Example", 7.0, 4.0, 100, 10 );
This would create a window 7 inches wide by 4 inches high.

getgui_buttons( char *prompt, char *buttons, char *result )

Present a prompt and labeled button(s), and wait for user to select a button. When the user clicks with mouse upon a button, the function returns. prompt may include embedded newlines; if so multiple lines will be displayed. buttons is a comma delimited list of labels to appear on the buttons. The user's button choice is returned in result. 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).
Example: getgui_buttons( "Please select a color", "Red,Green,Blue,Can't Decide", result );
This would display the prompt "Please select a color" and four buttons.

getgui_progress( char *txt, char *buttons )

Same as getgui_buttons() but returns immediately. Often used for "In progress" or "Running.. Please wait" messages. Buttons are optional (for no buttons, pass buttons as "" ). If buttons are included, a user click upon a button may be detected using getgui_poll().
Example: getgui_progress( "Running.. please wait", "" );

getgui_progressclear()

Clear the prompt left from previous getgui_progress().

getgui_keyinput( char *prompt, char *oldval, int *len, char *buttons, char *result );

Present a prompt and a one-line key entry area. User can enter text using the keyboard; when the user presses RETURN or clicks with the mouse somewhere outside the key entry area, the function returns. prompt may include embedded newlines; if so multiple lines will be displayed. oldval is the default value to appear in the key entry area (if none is desired, pass as ""). len is the maximum length, in characters, of the keyed input, and defines the size of the key entry area. An optional comma-separated list of buttons may be given (if no buttons are desired, "" should be passed). The user's key input is returned in result. Special keys and their uses are summarized under EDITING KEYS, below.

Example:

char userin[80], today[12];
strcpy( today, today's date );
getgui_keyinput( "Enter date of occurance", today, 20, "Unknown", userin );


getgui_editbox( char *prompt, int maxlen, char *newlinemode, char *buttons, char *result )

Present a user prompt, allow user to key text into a multi-line input box, and optionally some buttons. Long lines are automatically word-wrapped. When the user clicks with the mouse anywhere outside the input box, input is terminated and the function returns.
prompt may include embedded newlines; if so multiple lines will be displayed. maxlen is the maximum number of characters allowed; the box size will be based on this, and the result parameter should have at least this capacity. newlinemode is described below. buttons should contain a comma-delimited list of buttons. At least one button labelled OK must be supplied as this is the only way that the user can terminate key input. The user's key input (or button selection) is copied into the result parameter. A starting value may be supplied in result if desired. If there is no starting value, result should be set to "" before calling getgui_editbox().
Special editing keys and their uses are summarized under EDITING KEYS, below.
newlinemode specifies how newlines will be post-processed when the user is finished entering text. It may be one of:

asis =  leave newlines as user typed them
everyline = add newlines at word-wrap boundaries
none = remove all newlines

Example:

char userin[400];
getgui_editbox( "Enter you message:", 400, "asis", "OK,Cancel", userin );
printf( "%s", userin );


getgui_set( char *attribute, char *val )

Set an internal attribute. Attributes are listed below (default value in parentheses):

textsize = text point size (12)

backcolor = background color (gray(0.8)

color1 = color of buttons (yellow)

color2 = flash color of selected button (orange)

color3 = color of inactive key entry field (dimblue)

color4 = color of active key entry field (pink)

flashtime = time in microseconds that button should flash when selected (150000)

buttonsize = pt size of button label text (12)

inputsize = pt size of getgui_keyinput_changeme_ input field (14)

semfile = name of semaphore file name to use (see EXTERNAL EVENTS)

okstring = it may be desired to have a button labelled "OK" that the user may click on to signify that he is finished keying input via getgui_keyinput() or getgui_editbox(). Normally with these routines the button label becomes the result; the "OK" button is an exception. This attribute is the string that will be considered an "OK" button. (Default is "OK").

The following are always transient settings and must be set and then unset when desired:

textalign = alignment for prompts. C=centered L=flush left (C)

passwordmode = if 1, hide user's key entry input; if 0, don't

buttondefault = which button 1..n should be shown as "default choice" (0) none

Example:

getgui_set( "passwordmode", "1" );
getgui_buttons( "Select one", "Normal,Exception 1,Exception 2", userin );
getgui_set( "passwordmode", "0" );



CAPABILITIES AVAILABLE ONLY IN THE C API

getgui_poll( char *result )

Used with getgui_progress() to if any of the displayed buttons have been selected. If so, 1 is returned and the selected button is returned in result. If not, 0 is returned and result is "".
Typical use is with getgui_progress() in a loop. Example:

char userin[80];
getgui_progress( "In progress..", "Stop" );
while( 1 ) {
        if( getgui_poll( userin )) break;
	do some work here
        Eusleep( 150000 );
        }

getgui_key( char *result )

Used with getgui_progress() to wait for user to press a keyboard key or select a button. result is the key or button selection. Printable keys are represented as themselves; otherwise they are represented as !charN where N is the ASCII value of the key. For example, pressing the [A] key would yield "a"; pressing [Shift]+[A] would yield "A"; and pressing [Ctrl]+[A] would yield "!char1".

Example:

char key[10];
getgui_progress( "Press some keyboard keys", "Quit" );
while( 1 ) {
	getgui_key( key );
	if( strcmp( key, "Quit" )==0 ) break;
	else printf( "Key is %s\n", key );
	}

getgui_semfile()

Used with getgui_poll() in an asyncronous loop to check the semaphore file if any. Should not be called more than once per second or so. See EXTERNAL EVENTS.


KEYS

The key entry field and editbox support the VT100/xterm arrow keys and the standard editing keys used in netscape, pico, etc. See also getgui(1)


COLORS

Color specifications are described in getgui(1)


EXTERNAL EVENTS

The getgui window may be updated asynchronously in response to some external event. For example, you may want to display an indicator "light" in the GUI window immediatly when some other system process detects some condition. Or, you might want to show the current time, up to the minute. We use this feature in the SST study to notify users that certain forms have been received and processed via fax, while they are using the GUI for other things.

This works as follows. A "semaphore file" is defined using getgui_set( "semfile", filename );. Once this is done, getgui will check for the existance of filename every few seconds. Any other process running on the system may place content into this file. When getgui notices that this file has been created or updated, it reads and executes the contents, which typically cause draw operations to happen in the GUI window. The semaphore file should contain a series of draw commands (described here)


EXAMPLES

./ggdemo.c


SEE ALSO

getgui(1)


AUTHOR

Steve Grubb


Copyright Steve Grubb


Markup created by unroff 1.0,    August 15, 2003.