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
|