.NH 1 "XVUTILS LIBRARY"
.XS
\s12\*(SN  XVUTILS LIBRARY\s0
.XE
.sp 2
.NH 2 "INTRODUCTION TO THE XVUTILS LIBRARY"
.XS
      \*(SN  INTRODUCTION
.XE
.sp 2
.PP
\fIxvutils\fP is the Khoros Library which contains all independent graphical 
user interface utilities.  Usually, but not always, the \fIxvutils\fP library
is used in conjunction with the \fIxvforms\fP library.  Note that all these 
routines use the X Toolkit and/or the Athena Widget set.  Routines available
include error widgets, warning widgets, exit widgets, inform widgets, help
widgets, query widgets, list widgets, browser widgets, and other miscellaneous
routines using the X Toolkit.
.sp 2
ALL programs that utilize these routines MUST link against: 
.sp
-lXaw -lXmu -lXt -lXext -lX11
.sp 2
ALL programs that utilize these routines MUST include the statement:
.sp
#include "xvutils.h"
.sp 3
.NH 2 " create_bitmap_image()"
.XS
      \*(SN   create_bitmap_image()
.XE
.sp
.LP
Creates a bitmap VIFF image from the current contents of the screen. 
The bitmap VIFF image will be padded to 8 bits, and is created from an
XImage, which may be padded to 4, 8, 16, or 32 bits.
.sp
.LP
=====================================================================
.B
.sp
struct xvimage *
.br
create_bitmap_image(display, screen_num, workspace, subimage,
.br
                              sub_x, sub_y, sub_width, sub_height)
.br
Display *display;  
.br
int     screen_num;
.br
Window  workspace;
.br
int     subimage, sub_x, sub_y, sub_width, sub_height;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP display: 10
The Display in which the desired window resides
.sp
.IP screen_num:
The screen number (inside the Display) in which the window resides
.sp
.IP workspace:
The window in which we are to create the VIFF image
.sp
.IP subimage:
An integer flag indicating if the image is to be extracted from a portion 
of the rootwindow or some other window.
.sp
.IP sub_x:
The x location (in pixels) of the screen from which to extract the image
.sp
.IP sub_y:
The y location (in pixels) of the screen from which to extract the image
.sp
.IP sub_width:
The width (in pixels) of the screen from which to extract the image
.sp
.IP sub_height:
The height (in pixels) of the screen from which to extract the image
.sp
.LP
Note that if \fIsubimage\fP is false, \fIsub_x, sub_y, sub_width\fP and
\fIsub_height\fP are unused.  In this case, \fIworkspace\fP should be set
to the Window that is desired as a bitmap.
.sp
.LP
=====================================================================
.bp
.sp
.LP
\fIEXAMPLE: 
.br
This example gets a bitmap subimage of size 512x512 from the contents of the
upper left hand corner of the screen, from the rootwindow. \fP
.sp
struct xvimage *image;
.br
Display *display;
.br
Window rootwindow;
.br
int screen_num, subimage, x, y, width, height;
.br
char *display_name;
.sp
display_name = xvf_strcpy("borris:0");
.br
display = XOpenDisplay(display_name);
.br
screen_num = XDefaultScreen(display);
.br
rootwindow = XDefaultRootWindow(display);
.br
subimage = true;
.br
x = 0;  y = 0;
.br
width = 512; height = 512;
.br
image = create_bitmap_image(display, screen_num, rootwindow,
.br
                            subimage, x, y, width, height);
.bp
.sp 3
.NH 2 " create_pixmap_image()"
.XS
      \*(SN   create_pixmap_image()
.XE
.sp
.LP
Very similar to create_bitmap_image(), which creates a bitmap image, 
create_pixmap_image() creates a pixmap khoros image from a current contents of
the screen.  The pixmap khoros image will be padded to 8 bits, 
and is created from an XImage, which may be padded to 4, 8, 16, or 32 bits.
.sp
.LP
=====================================================================
.B
.sp
struct xvimage *
.br
create_pixmap_image(display, screen_num, workspace, subimage,
.br
                    sub_x, sub_y, sub_width, sub_height)
.br
Display *display;  
.br
int     screen_num;
.br
Window  workspace;
.br
int     subimage, sub_x, sub_y, sub_width, sub_height;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP display: 10
The Display in which the desired window resides
.sp
.IP screen_num:
The screen number (inside the Display) in which the window resides
.sp
.IP workspace:
The window in which we are to create the khoros image
.sp
.IP subimage:
An integer flag indicating if the image is to be extracted from a portion 
of the rootwindow or some other window.
.sp
.IP sub_x:
The x location (in pixels) of the screen from which to extract the image
.sp
.IP sub_y:
The y location (in pixels) of the screen from which to extract the image
.sp
.IP sub_width:
The width (in pixels) of the screen from which to extract the image
.sp
.IP sub_height:
The height (in pixels) of the screen from which to extract the image
.sp
.LP
Note that if \fIsubimage\fP is false, \fIsub_x, sub_y, sub_width\fP and
\fIsub_height\fP are unused.  In this case, \fIworkspace\fP should be set
to the Window that is desired as a pixmap.
.sp
.LP
=====================================================================
.bp
.sp
.LP
\fIEXAMPLE: 
.br
This example gets a pixmap subimage of size 512x512 from the contents of the
upper left hand corner of the screen, from the rootwindow. \fP
.sp
struct xvimage *image;
.br
Display *display;
.br
Window rootwindow;
.br
int screen_num, subimage, x, y, width, height;
.br
char *display_name;
.sp
display_name = xvf_strcpy("borris:0");
.br
display = XOpenDisplay(display_name);
.br
screen_num = XDefaultScreen(display);
.br
rootwindow = XDefaultRootWindow(display);
.br
subimage = true;
.br
x = 0;  y = 0;
.br
width = 512; height = 512;
.br
image = create_pixmap_image(display, screen_num, rootwindow,
.br
                            subimage, x, y, width, height);
.bp
.sp 3
.NH 2 " xvf_run_browser()"
.XS
      \*(SN   xvf_run_browser()
.XE
.sp
.LP
Runs a browser widget, allowing the user to select a file from the directory 
listing,  browse through the directory structure for the desired file, or 
type in the desired path and file into the text widget provided at the bottom
of the browser.  NOTE: this routine will block processing of other X events
until the user correctly selects a file.
.sp
.LP
=====================================================================
.B
.sp
char *
.br
xvf_run_browser(prompt, label, directory)
.br
char	*prompt, *label, *directory;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP prompt: 10
Prompt string to display on browser 
.sp
.IP label:
Label for browser
.sp
.IP directory:
Full path to directory where browser will find files
.sp
.LP
=====================================================================
.sp
.LP
\fIEXAMPLE: 
.br
This example uses a browser widget to allow the user to specify filename. 
The contents of the browser begin in the current local "." directory. \fP
.sp
char *filename, *prompt, *label, *directory;
.sp
prompt = xvf_strcpy("Please select a File");
.br
label  = xvf_strcpy("Browser Example");
.br
directory = xvf_strcpy("./");
.sp
filename = xvf_run_browser(prompt, label, directory);
.bp
.sp 3
.NH 2 " xvf_detect_file()"
.XS
      \*(SN   xvf_detect_file()
.XE
.sp
.LP
Detects whether a file has been changed, or input has been provided to the file
via a file descriptor.  
.sp
.LP
=====================================================================
.B
.sp
int
.br
xvf_detect_file(filename, time, routine, clientData)
.sp
char	*filename;
.br
float   time;
.br
int	(*routine)();
.br
caddr_t clientData;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the file for which changes will be detected.
.sp
.IP time:
How often (in seconds) the file should be checked for any changes.
.sp
.IP routine:
The routine to be called when changes to the file are detected.
.sp
.IP clientData:
A pointer to the data which will be used as parameters to the routine
specified above.
.sp
.LP
=====================================================================
.sp
.LP
\fIEXAMPLE: 
.br
This example shows how xvf_detect_file() may be used to detect when changes
are made to a file named "input_file".  Checks of the file will be made every 
10 seconds. \fP
.sp
#define DELAY 10;
.sp
char *filename;
.br
int  detect_id; /* used to pass to xvf_delete_detect to stop detection process */
.br
caddr_t data;
.sp
filename = xvf_strcpy("input_file");
.sp
detect_id =  xvf_detect_file(filename, DELAY, update_input, data);
.sp
where the update_input() routine is defined as:
.sp
int update_input(id, fid, data)
.br
int  id;
.br
int  fid;
.br
caddr_t data;
.sp
.bp
.sp 3
.NH 2 " xvf_detect_fid()"
.XS
      \*(SN   xvf_detect_fid()
.XE
.sp
.LP
Detects whether some input has been provided through a file descriptor.
Note that this routine may be used on stdin, or on a file that uses a file
descriptor for reading. 
.sp
.LP
=====================================================================
.B
.sp
int
.br
xvf_detect_fid(file, routine, clientData)
.sp
int	fid;
.br
int	(*routine)();
.br
caddr_t clientData;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP fid: 10
The input file descriptor.
.sp
.IP routine:
The routine to be called when input to the file descriptor is detected.
.sp
.IP clientData:
A pointer to the data which will be used as parameters to the routine.
.sp
.LP
=====================================================================
.sp
.LP
\fIEXAMPLE: 
.br
This example shows how xvf_detect_fid() may be used to detect when input is
provided to stdin.\fP
.sp
int  detect_id;  /* used to pass to xvf_delete_detect to stop detection process */
.br
detect_id =  xvf_detect_fid(fileno(stdin), update_input, data);
.sp
where the update_input() routine is defined as:
.sp
int update_input(id, fid, data)
.br
int  id;
.br
int  fid;
.br
caddr_t data;
.bp
.sp 3
.NH 2 " xvf_delete_detect()"
.XS
      \*(SN   xvf_delete_detect()
.XE
.sp
.LP
Stops the detection process for either a file (initiated by xvf_detect_file)
or for input (initiated by xvf_detect_fid).
.sp
.LP
=====================================================================
.B
.sp
int
.br
xvf_delete_detect(id)
.sp
int	id;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP id: 10
The identification number of the detection process (this id number is returned 
by xvf_detect_file or xvf_detect_fid).
.sp
.LP
=====================================================================
.sp
.LP
\fIEXAMPLE: 
.br
This example shows how xvf_delete_detect() is used to stop detection of changes
on a file, previously initiated by xvf_detect_file(). \fP
.sp
int  detect_id;  /* was previously returned by xvf_detect_file */
.sp
xvf_delete_detect(detect_id);
.sp
.bp
.sp 3
.NH 2 " xvf_create_display_widget()"
.XS
      \*(SN   xvf_create_display_widget()
.XE
.sp
.LP
Creates a large read-only text widget in which an ascii file is displayed, 
until the user clicks on the "Quit" button.  May have the contents of the 
text widget updated with xvf_update_display_widget().  A scroll bar allows the
user to scroll through the text.  Will not block processing of other X events
while displayed.
.sp
.LP
=====================================================================
.B
.sp
DisplayWid_Data *
.br
xvf_create_display_widget(filename, display_label)
.br
char *filename;
.br
char *display_label;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the file to initially be displayed within the display widget
.sp
.IP display_label: 12
The label for the display widget
.sp
.LP
Note: The DisplayWid_Data structure should not be accessed by the application 
program;  it is returned to the application solely so it may later be passed 
to xvf_create_display_widget().
.LP
=====================================================================
.sp
\fIEXAMPLE: 
.br
The example for xvf_create_display_widget() will be combined with the
example for xvf_update_display_widget(), and appears on the next page.
.bp
.sp 3
.NH 2 " xvf_update_display_widget()"
.XS
      \*(SN   xvf_update_display_widget()
.XE
.sp
.LP
Updates or changes the file that is currently displayed in a display widget 
created by xvf_create_display_widget().
.sp
.LP
=====================================================================
.B
.sp
int
.br
xvf_update_display_widget(display_data, filename)
.br
DisplayWid_Data *display_data;
.br
char *filename;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP display_data: 10
A pointer to the DisplayWid_Data earlier returned by xvf_create_display_widget()
.sp
.IP filename:
The name of the new file to be displayed in the display widget
.sp
.LP
=====================================================================
.sp
\fIEXAMPLE: 
.br
This example shows how xvf_create_display_widget() is used to create a 
display widget, and how the file displayed in the display widget is updated
using xvf_update_display_widget(). Initially, the display widget will display
the contents of the file named "initial_file".  Later, the display widget
will update the display widget with the contents of "new_file".\fP
.sp
DisplayWid_Data *display_data;
.br
char *filename1, *filename2;
.br
char *display_label;
.sp
filename1 = xvf_strcpy("initial_file");
.br
filename2 = xvf_strcpy("new_file");
.br
display_label = xvf_strcpy("Display Widget");
.sp
display_data = xvf_create_display_widget(filename, display_label)
.br
if (display_data == NULL) /* print error message */
.sp
/* 
.br
 * as the program continues, we update the displayed file
.br
 * in response to some action by the user... 
.br
 */
.sp
xvf_update_display_widget(display_data, filename2)
.bp
.sp 3
.NH 2 " xvf_error_wait()"
.XS
      \*(SN   xvf_error_wait()
.XE
.sp
.LP
Creates a pop-up error message.  Error widget has one acknowledgment button,
which must be clicked on by the user before other X events will be processed.  
Caller may specify label for acknowledgment button; the default label is "ok".
.sp
.LP
=====================================================================
.B
.sp
int xvf_error_wait(error, label, button1)
.br
char *error;
.br
char *label;
.br
char *button1;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP error: 10
The error message to be displayed in the error widget -- it may contain 
carriage returns, but this is not necessary, as line breaks
will be put where necessary.  Error messages should be clear and concise.
Application programmers are encouraged to include the name of the routine
that is producing the error message as part of the message.
.sp
.IP label:
The label for the error widget.  As a rule of thumb, should be no longer than
35 characters; while there is no limit on label length, labels longer than
35 characters tend to look bulky. May be passed in as NULL, in which
case the default label will be "Error:".
.sp
.IP button1:
The label for the acknowledgment button.  May be passed in as NULL, in which
case the default label will be "ok".
.sp
.LP
=====================================================================
.sp
\fIEXAMPLE: 
.br
This example shows how xvf_error_wait() may be used to create an error widget
with the default title on the acknowledgment button, and a sarcastic message.\fP
.sp
char *error;
.br
char *label;
.sp
error = xvf_strcpy("name_of_routine: Doofus! Get A Life!");
.br
label = xvf_strcpy("Errors R Us");
.sp
xvf_error_wait(error, label, NULL);
.bp
.sp 3
.NH 2 " xvf_warn_wait()"
.XS
      \*(SN  xvf_warn_wait()
.XE
.sp
.LP
Creates a pop-up warning message.  Warning widget has two acknowledgment 
buttons, one of which must be clicked on by the user before other X events 
will be processed.  Returns status indicating which button was chosen 
(1 or 0).  Caller may specify labels for acknowledgment buttons.  
Default labels are "Yes" and "No", respectively.
.sp
.LP
=====================================================================
.B
.sp
int xvf_warn_wait(warning, label, button1, button2)
.br
char *warning;
.br
char *label;
.br
char *button1;
.br
char *button2;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP warning: 10
The warning message to be displayed in the warn widget -- it may contain 
the carriage returns, but this is not necessary, as line breaks
will be put where necessary.  Warning messages should be clear and concise.
Application programmers are encouraged to include the name of the routine
that is producing the warning message as part of the message.
.sp
.IP label:
The label for the warn widget.  As a rule of thumb, should be no longer than
35 characters; while there is no limit on label length, labels longer than
35 characters tend to look bulky. May be passed in as NULL, in which
case the default label will be "Error:".
.sp
.IP button1:
The label for the acknowledgment button that will return a status of 1.  
May be passed in as NULL, in which case the default label will be "Cont".
Note that the default title for button1 implies that it is the responsibility
of the application program to make sure that the program continues after the
warning if the user clicks on the "Cont" acknowledgment button.
.sp
.IP button0:
The label for the acknowledgment button that will return a status of 0.  
May be passed in as NULL, in which case the default label will be "Stop".
Note that the default title for button0 implies that it is the responsibility
of the application program to make sure that the program stops after the
warning if the user clicks on the "Stop" acknowledgment button.
.LP
=====================================================================
.bp
.sp
\fIEXAMPLE: 
.br
This example shows how xvf_warn_wait() may be used to create an warn widget
with default titles on the acknowledgment buttons. \fP
.sp
char *warning;
.br
char *label;
.sp
error = xvf_strcpy("name_of_routine: Warning - you have done something wrong!");
.br
label = xvf_strcpy("Our Warning Message");
.sp
if (!(xvf_warn_wait(warning, label, NULL, NULL))) exit(1);
.bp
.sp 3
.NH 2 " xvf_exit_wait()"
.XS
      \*(SN   xvf_exit_wait()
.XE
.sp
.LP
Creates a pop-up exit message.  Exit widget has three acknowledgment buttons,
one of which must be clicked on by the user before other X events will be
processed.  Returns status indicating which button was chosen (1, 0, or -1).
Caller may specify labels for acknowledgment buttons; default labels are
"Yes", "No", and "Cancel", respectively.
.sp
.LP
=====================================================================
.B
.sp
int xvf_exit_wait(exit_stmt, label, button1, button0, button_1)
.br
char *exit_stmt;
.br
char *label;
.br
char *button1;
.br
char *button0;
.br
char *button_1;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP exit_stmt: 10
The exit statement to be displayed in the exit widget -- it may contain 
the '\n' carriage return character, but this is not necessary, as line breaks
will be put where necessary.  Exit messages should be clear and concise.
Application programmers are encouraged to include the name of the program
that is producing the exit message as part of the message.
.sp
.IP label:
The label for the exit widget.  As a rule of thumb, should be no longer than
35 characters; while there is no limit on label length, labels longer than
35 characters tend to look bulky. May be passed in as NULL, in which
case the default label will be "EXITING:".
.sp
.IP button1:
The label for the acknowledgment button which returns a status of 1.  It
may be passed in as NULL, in which case the default label will be "Yes".
Note that the default title for button1 implies that it is the responsibility
of the application program to make sure that the program acts appropriately
when the user clicks on button1.
.sp
.IP button0:
The label for the acknowledgment button which returns a status of 0.  It
may be passed in as NULL, in which case the default label will be "No".
Note that the default title for button0 implies that it is the responsibility
of the application program to make sure that the program acts appropriately
when the user clicks on button0.
.sp
.IP button_1:
The label for the acknowledgment button which returns a status of -1.  It
may be passed in as NULL, in which case the default label will be "Cancel".
Note that the default title for button_1 implies that it is the responsibility
of the application program to make sure that the program acts appropriately
when the user clicks on button_1.
.sp
.LP
=====================================================================
.bp
.sp
\fIEXAMPLE: 
.br
This example shows how xvf_exit_wait() may be used to create an exit widget
with custom titles on the acknowledgment buttons. \fP
.sp
char *exit_statement;
.br
char *label;
.sp
error = xvf_strcpy("name_of_program: Save workspace before exiting?");
.br
.sp
if ((xvf_warn_wait(warning, label, "Save", "Don't Save", "Cancel")) == 1)
.br
    /* save the workspace & exit */
.sp
else if ((xvf_warn_wait(warning, label, "Save", "Don't Save", "Cancel")) == 0)
.br
    /* simply exit */
.sp
else
.br
    /* continue program normally */
.sp
.bp
.sp 3
.NH 2 " xvf_online_help_wait()"
.XS
      \*(SN   xvf_online_help_wait()
.XE
.sp
.LP
Creates a large read-only text widget in one or more ascii files (presumably 
help files) may be displayed, until the user clicks on the "Quit" button. 
If the path specified is an ascii file, that file is displayed.  If the path
specified is a directory, one button labeled with the name of each file in that
directory will appear at the top of the help widget; the user may click on the
buttons in order to view the contents of each file in the directory.  If the
directory specified contains the special file named "Overview", that file will
be displayed initially;  this file should contain a listing of the files in
the directory, and the subjects that they document.  A scroll bar 
allows the user to scroll through the text.  The help widget will not block 
processing of other X events while displayed.
.sp
.LP
=====================================================================
.B
.sp
int
.br
xvf_online_help_wait(path, label)
.br
char *path;
.br
char *label;
.R
.sp
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP path: 10
The path specifying the help file or help directory.  May contain a tilde "~" 
which will be expanded,  or may contain a reference to the KHOROS_HOME system
variable.  If the path specifies a directory, it is \fIhighly\fP recommended that
this directory be kept clean of all but pertinent help files, as every file in the
directory will be accessible via the online help widget.  Especially, the effect 
of the user attempting to view a non-ascii file via the help widget will be 
detrimental to the application program.
.sp
.IP label:
The label for the online help widget.  As a rule of thumb, should be no longer 
than 35 characters; while there is no limit on label length, labels longer than
35 characters tend to look bulky. May be passed in as NULL, in which
case the default label will be "Online Help Pages".
.sp
.LP
Note that most applications will have no need to call xvf_online_help_wait()
directly;  the use of the (-H) help line in the User Interface Specification
file (see documentation on the User Interface) will automatically create a 
help button with access to the online help specified by the path given on the
(-H) line.
.sp
.LP
=====================================================================
.bp
.sp
.LP
\fIEXAMPLE: 
.br
This example shows how xvf_online_help_wait() might be used to provide online
help for the user of the application program. \fP  
.sp
char *pathname;
.br
char *label;
.sp
pathname = xvf_strcpy("KHOROS_HOME/doc/your_directory/your_help_file");
.br
label = xvf_strcpy("Our Help Pages");
.br
xvf_online_help_wait(pathname, label);
.bp
.sp 3
.NH 2 " xvf_inform_wait()"
.XS
      \*(SN   xvf_inform_wait()
.XE
.sp
.LP
Creates a read-only text widget in which a set of strings is displayed, until
the user clicks on the "Quit" button. The Inform widget has one acknowledgment 
button, which must be clicked on by the user before other X events will be 
processed.  Caller may specify a label for the acknowledgment button; default 
label is "ok".  Primarily for use in displaying information that is not known 
until execution of the application is in process.
.sp
.LP
=====================================================================
.B
.sp
int
.br
xvf_inform_wait(strings, num_strings, label, button)
.br
char *strings[];
.br
int   num_strings;
.br
char *label;
.br
char *button;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP strings: 10
This is an array of the information strings which are to be displayed in 
the inform widget.  The strings array must be allocated and initialized by the
caller preceding the call to xvf_inform_wait().
.sp
.IP num_strings:
The number of strings in the \fIstrings\fP array.
.sp
.IP label:
The label for the inform widget.  As a rule of thumb, should be no longer than
35 characters; while there is no limit on label length, labels longer than
35 characters tend to look bulky. May be passed in as NULL, in which
case the default label will be "Information".
.sp
.IP button:
The label for the acknowledgment button.  May be passed in as NULL, in which
case the default label will be "Ok".
.sp
.LP
=====================================================================
.sp
\fIEXAMPLE: 
.br
This example shows how xvf_inform_wait() may be used to create an inform widget
to tell the user the values of three float values. \fP
.sp
char *strings[3], *label;
.sp
strings[0] = xvf_strcpy("The first computed value is 5.6");
.br
strings[1] = xvf_strcpy("The second computed value is 7.89");
.br
strings[2] = xvf_strcpy("The third computed value is 10.1");
.br
label = xvf_strcpy("Information For You");
.sp
xvf_inform_wait(strings, 3, label, NULL);
.bp
.sp 3
.NH 2 " xvf_run_list_wait()"
.XS
      \*(SN   xvf_run_list_wait()
.XE
.sp
.LP
Creates a list widget in which an array is strings is displayed.  The list
widget is popped up, and the user may select a single string from the list;  
a string must be chosen, or the "Cancel" button clicked on by the user before 
other X events will be processed.  Returns an XawListReturnStruct specifying
the choice made by the user.  If applicable, may also be called so that a 
text widget will appear at the bottom of the list widget, so that the user
may specify their own choice, if not one of the list provided.
.sp
.LP
=====================================================================
.B
.sp
XawListReturnStruct *
.br
xvf_run_list_wait(list, size, col_num, prompt, label, current, user_defined)
.sp
char *list[];
.br
int size;
.br
int col_num;
.br
char *prompt;
.br
char *label;
.br
int current;
.br
int user_defined;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP list: 10
The array of strings to be displayed as elements in the list
.sp
.IP size:
The number of elements in the \fIlist\fP array
.sp
.IP col_num:
The number of columns to in which to display elements of list
.sp
.IP prompt:
A prompt indicating action expected from user (e.g, "Choose a Color")
.sp
.IP label:
A label for the list widget
.sp
.IP current:
The currently-selected string in the list (NULL implies that no string is 
currently selected)
.sp
.IP user_defined:
Flag indicating if a text widget should be provided at the bottom of the list
widget so that the user will be allowed to enter a string that is not included as
one of the elements in the \fIlist\fP array.
.sp
.LP
=====================================================================
.bp
.sp
\fIEXAMPLE: 
.br
This example shows how xvf_run_list_wait() may be used to create a list widget
from which the user may choose one of six colors, or enter their own color. 
xvf_run_list_wait() will return an XawlistReturnStruct, from which we must 
get the choice of the user; if desired, the index of that choice may also be 
recorded. \fP
.sp
static char *colorlist[] = 
.br
		{"Red", "Blue", "Green", "Yellow", "Orange", "Purple"};
.sp
XawListReturnStruct *color_return;
.br
char *label, *prompt;
.br
char *new_color;
.br
int  col_num = 1, color_num = 6;
.br
int  new_color_list_index;
.sp
label = xvf_strcpy("Available Colors");
.br
prompt = xvf_strcpy("Pick a Color:");
.sp
color_return = xvf_run_list_wait(colorlist, col_num, color_num, 
.br
			prompt, label, NULL, true);
.sp
new_color = xvf_strcpy(color_return->string);  /* the new color */
.br
new_color_list_index = color_return->list_index;  /* list indices begin at 1 */
.bp
.sp 3
.NH 2 " xvf_run_list_multsel_wait()"
.XS
      \*(SN   xvf_run_list_multsel_wait()
.XE
.sp
.LP
Creates list widget in which an array of strings is displayed.  The list
widget is popped up, and the user may select one or more strings from the list;
the "Use" button, or the "Cancel" button must clicked on by the user before 
other X events will be processed.  Returns an array of XawListReturnStructs 
specifying the choices made by the user. If applicable, may also be called 
so that a text widget will appear at the bottom of the list widget, so that 
the user may specify their own choice, if not one of the list provided.
.sp 
.LP
=====================================================================
.sp
.B
XawListReturnStruct **
.br
xvf_run_list_multsel_wait(list, size, col_num, prompt, label, 
.br
				user_defined, duplicate_entries, num)
.sp
char *list[];
.br
int size;
.br
int col_num;
.br
char *prompt;
.br
char *label;
.br
int user_defined;
.br
int duplicate_entries;
.br
int *num;
.R
.sp
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP list: 10
The array of strings to be displayed as elements in the list
.sp
.IP size:
The number of elements in the \fIlist\fP array
.sp
.IP col_num:
The number of columns to in which to display elements of list
.sp
.IP prompt:
A prompt indicating action expected from user (e.g, "Choose Some Colors")
.sp
.IP label:
A label for the list widget
.sp
.IP user_defined:
Flag indicating if a text widget should be provided at the bottom of the list
widget so that the user will be allowed to enter a string that is not included as
one of the elements in the \fIlist\fP array.
.sp
.IP duplicate_entries: 15
Flag indicating if user should be allowed to choose the same element twice.
.sp
.IP num: 10
Returns the number of choices that the user selected.
.sp
.LP
=====================================================================
.bp
.sp
\fIEXAMPLE: 
.br
This example shows how xvf_run_list_multsel_wait() may be used to create a 
list widget from which the user may choose one or more of six fruits. The user
will not be allowed to enter the same fruits twice, or to enter their 
own fruit.  xvf_run_list_multsel_wait() will return an array of 
XawlistReturnStructs, from which we must get the choices of the user; if
desired, the indices of the choices may also be recorded.\fP
.sp
static char *fruitlist[] = 
.br
		{"Apple", "Orange", "Banana", "Mango", "Melon", "Papaya"};
.sp
XawListReturnStruct **fruit_list_return;
.br
char *label, *prompt;
.br
char *new_fruits[6];
.br
int new_fruit_indices[6];
.br
int num_fruits_chosen;
.br
int  col_num = 1, num_fruits = 6, duplicate_entries = false, user_defined = false;
.sp
label = xvf_strcpy("Available Fruits");
.sp
prompt = xvf_strcpy("Pick One or More Fruits:");
.sp
fruit_list_return = xvf_run_list_multsel_wait(fruitlist, num_fruits, col_num, 
.br
			prompt, label, user_defined, duplicate_entries, 
.br
			&num_fruits_chosen);
.sp
for (i = 0; i < num_fruits_chosen; i++)
.br
{
.br
     new_fruits[i] = xvf_strcpy(fruit_list_return->string);  
.br
     new_fruit_indices[i] = fruit_list_return->list_index;  /* indices begin at 1 */
.br
}
.sp
.bp
.sp 3
.NH 2 " xvf_run_multlist_multsel_wait()"
.XS
      \*(SN   xvf_run_multlist_multsel_wait()
.XE
.sp
.LP
This is a multilist widget: a hybrid of the list
utility, and the help widget when used with a directory path. To use
\fBxvf_run_multlist_multsel_wait()\fP, you must first have a special directory,
whose path is passed in as the first parameter.   The contents of this
directory is two or more files, each of which contains a list to appear
on the list widget.  When the multilist widget is initiated, it comes
up with the label specified.  Under the label is one buttons for each file
in the specified directory.  Each button is named after the corresponding 
file found in the specified directory, and each is labeled with the name 
of the file it corresponds to.  When the user
clicks on a button, the list made up of the contents of the items from
that list will appear.  The user may select one or more items from that
list, or may click on another button, which will bring up the next list.
User may select as many items as desired from as many lists as desired.
The \fBxvf_run_multlist_multsel_wait()\fP routine, like the
\fBxvf_run_multsel_wait()\fP, returns an array of pointers to
XawListReturnStruct's.  The list is returned according to order of selection
by the user;  there is no distintion in the returned list of which list the
items were selected from.
.sp 
.LP
=====================================================================
.sp
.B
XawListReturnStruct **
.br
xvf_run_multlist_multsel_wait(path, col_num, prompt, label, user_defined, 
.br
				duplicate_entries, num, default_filename)
.sp
char *path;
.br
int col_num;
.br
char *prompt;
.br
char *label;
.br
int user_defined;
.br
int duplicate_entries;
.br
int *num;
.br
char    *default_filename;
.sp
.R
.sp
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP path: 10
The path to the directory which contains the files in which the contents of
the list may be found.  Note that this directory must contain NO extraneous 
files.  For each file in the directory, one button of the same name will appear 
on the multilist widget.  When the user clicks on the button, the contents of
the file will appear as items for selection.
.sp
.IP col_num:
The number of columns to in which to display elements of list
.sp
.IP prompt:
A prompt indicating action expected from user (e.g, "Choose desired items from the following categories")
.sp
.IP label:
A label for the multilist widget
.sp
.IP user_defined:
Flag indicating if a text widget should be provided at the bottom of the list
widget so that the user will be allowed to enter a string that is not included as
one of the elements in the \fIlist\fP array.
.sp
.IP duplicate_entries: 15
Flag indicating if user should be allowed to choose the same element twice.
.sp
.IP num: 10
Returns the number of choices that the user selected.
.sp
.IP default_filename:
The name of the file whose contents should be displayed for selection when
the multilist widget is first mapped.
.sp
.LP
=====================================================================
.bp
.sp
\fIEXAMPLE: 
.br
This example shows how xvf_run_multlist_multsel_wait() may be used to create a 
list widget from which the user may choose one or more of their favorite items
from the Four Food Groups. The user will not be allowed to enter the same foods 
twice. xvf_run_multlist_multsel_wait() will return an array of 
XawlistReturnStructs, from which we must get the choices of the user; if
desired, the indices of the choices may also be recorded.\fP
.sp
/* 
.br
 * Note: the "food_groups" directory contains 4 files: "bread", "dairy", 
.br
 *       "fruit_n_vegs", and "meat".  In each of these files is a list of
.br
 *       appropriate food items, one food item per line and each starting in
.br  
 *       the first column.
.br
 */    
.sp
XawListReturnStruct **food_list_return;
.br
char *label, *prompt, *path;
.br
int num_foods_chosen;
.br
int  col_num = 1, duplicate_entries = true, user_defined = false;
.sp
path = vfullpath("./food_groups", NULL, NULL);
.sp
label = xvf_strcpy("The Four Basic Food Groups");
.sp
prompt = xvf_strcpy("Pick One or More Foods:");
.sp
food_list_return = xvf_run_multlist_multsel_wait(path, col_num, prompt, 
.br
			label, user_defined, duplicate_entries, 
.br
			&num_foods_chosen, "meat");
.bp
.sp 3
.NH 2 " xvf_query_wait()"
.XS
      \*(SN   xvf_query_wait()
.XE
.sp
.LP
Creates a query widget in which one or more pairs of prompts and answer 
widgets appears.  The query widget is popped up, and the user is expected
to provide a response for each of the prompt widgets in the answer text widget
provided.  Query widget has two acknowledgment buttons, labeled is "ok" and
"cancel". Returns the first of the answers, in string format.  Answers to 
prompts are returned in a string array to the caller.  There is no limit on the
number of prompt and answer pairs that made up the query widget;  when there are
more than 10 responses required, a scroll bar will be put on the query widget
so that the user may scroll through the query widget, providing responses to
prompts.
.sp 
.LP
=====================================================================
.B
.sp
char *
.br
xvf_query_wait(label, prompts, button, answers, num_prompts, size)
.br
char *label;
.br
char *prompts[];
.br
char *button;
.br
char *answers[];
.br
int num_prompts;
.br
int size;
.R
.sp
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP label: 10
The label for the query widget.  As a rule of thumb, should be no longer 
than 35 characters; while there is no limit on label length, labels longer than
35 characters tend to look bulky. May be passed in as NULL, in which
case the default label will be "Please Respond".
.IP prompts:
An array of strings that will serve as prompts for the user.  
.IP button:
Label for the acknowledgment button.  If NULL, default will be "Ok".
.IP answers:
An array of strings in which the responses to the prompts will be passed back to
the caller;  integer or float responses must be cast from a string to
their proper type before using.  The answers array is also used to provide 
default responses, if any; integer or float defaults must be cast to strings
before using.  \fINote:  it is the responsibility of the application to 
allocate enough space for responses in the answers array, when defaults are 
provided.  When the answers array is passed in as NULL (no defaults provided) 
an appropriate amount of space will be allocated for the user's responses.\fP
.IP num_prompts:
The number of prompts in the \fIprompts\fP array, as well as the size of 
the \fIanswers\fP array. 
.sp
.IP size:
Size to make each text widget for the user's response (in characters)
.sp
.LP
=====================================================================
.bp
.sp
\fIEXAMPLE: 
.br
This example shows how xvf_query_wait() might be used to get some strings
from the user. Note that each string will have a maximum length of 10 characters.
\fP  
.sp
#define NUM_STRINGS 5
.br
#define MAX_LENGTH 255
.sp
int i;
.br
char temp[MAX_LENGTH];
.br
char *prompts[NUM_STRINGS];
.br
char *answers[NUM_STRINGS];
.br
for (i = 0; i < NUM_STRINGS; i++)
.br
{
.br
     sprintf(temp, "Label Number %d: ", i+1);
.br
     prompts[i] = xvf_strcpy(temp);
.br
}
.sp
xvf_query_wait("Enter Labels (10 character Max)", prompts, NULL, answers, i, 10);
.LP
.bp
.sp 3
.NH 2 " xvf_select_wait()"
.XS
      \*(SN   xvf_select_wait()
.XE
.sp
.LP
Creates a select widget; the selection widget is a pop-up widget that appears
with label, text for prompting, and N acknowledgement buttons, plus a
"CANCEL" button.  Note that the error widget created with a call to 
\fIxvf_error_wait()\fP has one acknowledgment button,  the warn widget created
with a call to \fIxvf_warn_wait()\fP has two acknowledgement buttons, and the
exit widget created with a call to \fIxvf_exit_wait()\fP has three 
acknowlegement buttons;  the selection widget created with a call to 
\fIxvf_select_wait()\fP is for circumstances where the calling program needs
four or more acknowledgement buttons.  The status returned will be an integer
N, indicating which of the acknowledgement buttons was chosen by the user, 
where the buttons are numbered 1 to N depending on order of appearance in
the specification.  The select widget also has a CANCEL button created
automatically;  a status of zero (0) is returned when the user clicks on the
CANCEL button.
.sp 
.LP
=====================================================================
.B
.sp
int
.br
xvf_select_wait(stmt, label, button_labels, button_num)
.br
char *stmt;
.br
char *label;
.br
char **button_labels;
.br
int button_num;
.R
.sp
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP stmt: 10
The statement that will appear in the select widget, explaining the user's
choices.  It is recommended that the statement consist of a short sentence
explaining the operation of each button, and that these sentences be separated
with the "\n" carriage return control character.
.IP label:
Label for the top of the select widget.  If NULL, default will be "SELECT ONE:".
.IP button_labels:
An array of strings with which to label each button.  The first button on
the select widget will be labeled with the first string; \fIxvf_select_wait()\fP
will return (1) when the first button is selected by the user.  The second
button on the select widget will be labeled with the second string, and
\fIxvf_select_wait()\fP will return (2) when the second button is selected
by the user, and so on.
.IP button_num:
The number of buttons to appear on the select widget; also, the size of
the \fIbutton_labels\fP array. 
.sp
.LP
=====================================================================
.bp
.sp
\fIEXAMPLE: 
.br
This example shows how xvf_select_wait() might be used to get a decision
from the user, where the user has four choices aside from the CANCEL button.
\fP  
.sp
#define NUM_BUTTONS 4
.br
#define MAX_LENGTH 512
.sp
#define CANCEL_OBJ 0
.br
#define ADD_OBJ 1
.br
#define DELETE_OBJ 2
.br
#define MOVE_OBJ 3
.br
#define RESIZE_OBJ 4
.sp
char *button_labels[NUM_BUTTONS];
.br
char temp[MAX_LENGTH];
.br
int status;
.sp
button_labels[0] = xvf_strcpy("ADD");
.br
button_labels[1] = xvf_strcpy("DELETE");
.br
button_labels[2] = xvf_strcpy("MOVE");
.br
button_labels[2] = xvf_strcpy("RESIZE");
.sp
sprintf(temp, "Please indicate the action you would like to perform. \nADD to add a new object,\nDELETE to delete an object,\nMOVE to move an object,\nRESIZE to
resize an object.");
.sp
status = xvf_select_wait(temp, "Application Name", button_labels, NUM_BUTTONS);
.sp
/* cancel */
.br
if (status == CANCEL_OBJ) return;
.sp
else if (status == ADD_OBJ)
.br
{
.br
    /* add an object */
.br
}
.sp
else if (status == DELETE_OBJ)
.br
{
.br
    /* delete an object */
.br
}
.sp
else if (status == MOVE_OBJ)
.br
{
.br
    /* move an object */
.br
}
.sp
else if (status == RESIZE_OBJ)
.br
{
.br
    /* resize an object */
.br
}
.bp
.sp 3
.NH 2 " xvf_view_wait()"
.XS
      \*(SN   xvf_view_wait()
.XE
.sp
.LP
Creates a large read-only text widget in which any ascii file 
may be viewed, until the user clicks on the "Quit" button.  Contents
of the text widget may not be updated.  A scroll bar allows the
user to scroll through the text.  View widget has one acknowledgment button
which must be clicked on by the user before other X events will be processed.
Caller may specify a label for the acknowledgment button; the default label 
is "ok".  
.sp 
.LP
=====================================================================
.bp
.sp 3
.NH 2 " xvf_view_wait()"
.XS
      \*(SN   xvf_view_wait()
.XE
.sp
.LP
Creates a large read-only text widget in which any ascii file 
may be viewed, until the user clicks on the "Quit" button.  Contents
of the text widget may not be updated.  A scroll bar allows the
user to scroll through the text.  View widget has one acknowledgment button
which must be clicked on by the user before other X events will be processed.
Caller may specify a label for the acknowledgment button; the default label 
is "ok".  
.sp 
=====================================================================
.B
.sp
int xvf_view_wait(filename,label,glyph_label)
.sp
char *filename;
.br
char *label;
.br
char *glyph_label;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The file to be displayed in the view widget
.sp
.IP label:
The label of the view widget
.sp
.IP glyph_label:
The label for the view widget when it is in glyph form
.sp
.LP
=====================================================================
.sp
\fIEXAMPLE: 
.br
This example shows how xvf_view_wait() might be used to put up a view widget
which will display a file called "view_file".  \fP  
.sp
char *filename, *label, *glyph_label;
.sp
filename = xvf_strcpy("view_file");
.br
label = glyph_label = xvf_strcpy("Viewwer");
.sp
xvf_view_wait(filename,label,glyph_label);
.bp
.sp 3
.NH 2 " xvf_text_wait()"
.XS
      \*(SN   xvf_text_wait()
.XE
.sp
.LP
Creates a large read-write text widget which  may initially display a default 
string of unspecified length.  Allows the user to edit the string as desired. 
Text widget has two acknowledgment buttons, labeled "use" and "cancel", 
one of which must be clicked on by the user before other X events will be 
processed.  xvf_text_wait() will return the modified string to the caller 
when the user clicks on the "use" button; it will return NULL if the user 
deletes all text in the window before clicking on "use", or if the user 
clicks on the "cancel" button.
.sp 
.LP
=====================================================================
.B
.sp
char *xvf_text_wait(default_text,label,prompt)
.sp
char *default_text;
.br
char *label;
.br
char *prompt;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP default_text: 10
The string to be initially displayed in the text widget
.sp
.IP label:
The label of the text widget
.sp
.IP prompt:
Prompt for the user, appearing at top of text widget
.sp
.LP
=====================================================================
.sp
\fIEXAMPLE: 
.br
This example shows how xvf_text_wait() might be used to put up a text widget
which will initially contain a default string.  Each time the user updates
the text, the current text is printed out to the user's TTY; it will be saved 
to display as the default during the next use of the text widget. \fP
.sp
char  *prompt, *label, *current_string;
.br
static  char  *save_string;
.br
static  int    count = 0;
.sp
if (count == 0)
.br
   save_string = xvf_strcpy("begin string");
.sp
prompt = xvf_strcpy("Edit text as desired");
.br
label  = xvf_strcpy("Text Widget");
.sp
current_string = xvf_text_wait(save_string, label, prompt);
.br
if (current_string != NULL)  fprintf(stderr, "%s", current_string);
.br
if (current_string != NULL)  save_string = xvf_strcpy(current_string);
.br
else save_string = NULL;
.br
count++;
