xvutils(3)

NAME
xvutils - All independant graphical user interface utilities

DESCRIPTION
xvutils Library containing all independant graphical user interface utilities. Note that all these routines use the X Toolkit and/or the Athena Widget set.

For an explanation of all the following routines in greater detail, with explanations of all arguments to each routine, see the section on xvutils in the Khoros Programmer's Manual, chapter 8, Libraries.

ALL programs that utilize these routines MUST link against:
-lXaw -lXmu -lXt -lXext -lX11

ALL programs that utilize these routines MUST include the statement:
#include "xvutils.h"

AVAILABLE ROUTINES

create_bitmap_image()

Creates a bitmap khoros image from the current contents of the screen. The bitmap 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.

struct xvimage *create_bitmap_image(display, screen_num, workspace, subimage, sub_x, sub_y, sub_width, sub_height)
Display *display;
int screen_num;
Window workspace;
int subimage, sub_x, sub_y, sub_width, sub_height;

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

struct xvimage *create_pixmap_image(display, screen_num, workspace, subimage, sub_x, sub_y, sub_width, sub_height)
Display *display;
int screen_num;
Window workspace;
int subimage, sub_x, sub_y, sub_width, sub_height;

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

char * xvf_run_browser(prompt, label, directory)
char *prompt;
char *label;
char *directory;

xvf_detect_file()
Detects whether a file has been changed, or input has been provided to the file via a file descriptor.

int xvf_detect_file(filename, time, routine, clientData)
char *filename;
float time;
int (*routine)();
caddr_t clientData;

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

int xvf_detect_fid(file, routine, clientData)
int fid;
int (*routine)();
caddr_t clientData;

xvf_delete_detect()
Stops the detection process for either a file (initiated by xvf_detect_file) or for input (initiated by xvf_detect_fid).

int xvf_delete_detect(id)
int id;

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

DisplayWid_Data *xvf_create_display_widget(filename, display_label)
char *filename;
char *display_label;

xvf_update_display_widget()
Updates or changes the file that is currently displayed in a display widget created by xvf_create_display_widget().

int xvf_update_display_widget(display_data, filename)
DisplayWid_Data *display_data;
char *filename;

xvf_error_wait()
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".

int xvf_error_wait(error, label, button1)
char *error;
char *label;
char *button1;

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

int xvf_warn_wait(warning, label, button1, button2)
char *warning;
char *label;
char *button1;
char *button2;

xvf_exit_wait()
Creates a pop-up exit message. Exit widget has three acknowledment 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.

int xvf_exit_wait(exit_stmt, label, button1,
button0, button_1)
char *exit_stmt;
char *label;
char *button1;
char *button0;
char *button_1;

xvf_online_help_wait()
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 provide help for. A scroll bar allows the user to scroll through the text. The help widget will not block processing of other X events while displayed.

int xvf_online_help_wait(path, label)
char *path;
char *label;

xvf_inform_wait()
Creates a read-only text widget in which a set of strings is displayed, until the user clicks on the "Quit" button. Inform widget has one acknowledgment button, which must be clicked on by the user before other X events will be processed. Caller may specify labels for acknowledgment buttons. Default label is "ok". Primarily for use in displaying information that is not known until execution of the application is in process.

int xvf_inform_wait(strings, num_strings, label, button)
char *strings[];
int num_strings;
char *label;
char *button;

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

XawListReturnStruct *xvf_run_list_wait(list, size, col_num, prompt, label, current, user_defined)
char *list[];
int size;
int col_num;
char *prompt;
char *label;
int current;
int user_defined;

xvf_run_list_multsel_wait()
Creates list widget in which an array is 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.

XawListReturnStruct **xvf_run_list_multsel_wait(list, size, col_num, prompt, label, user_defined, duplicate_entries, num)
char *list[];
int size;
int col_num;
char *prompt;
char *label;
int user_defined;
int duplicate_entries;
int *num;

xvf_query_wait()
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, labelled 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.

char * xvf_query_wait(label, prompts, button, answers, num_prompts, size)
char *label;
char *prompts[];
char *button;
char *answers[];
int num_prompts;
int size;

xvf_select_wait()
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 xvf_error_wait() has one acknowledgment button, the warn widget created with a call to xvf_warn_wait() has two acknowledgement buttons, and the exit widget created with a call to xvf_exit_wait() has three acknowlegement buttons; the selection widget created with a call to xvf_select_wait() 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.

int xvf_select_wait(stmt, label, button_labels, button_num)
char *stmt;
char *label;
char **button_labels;
int button_num;

xvf_view_wait()
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 acknowledgement 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".

int xvf_xvf_view_wait(filename,label,glyph_label)
char *filename;
char *label;
char *glyph_label;

xvf_text_wait()
Creates a 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.

char *xvf_text_wait(default_text,label,prompt)
char *default_text;
char *label;
char *prompt;

For more information on the use of these utilities available via the xvutils library, see the documentation on xvutils found in the manual for khoros.

AUTHORS
Danielle Argiro
Stephanie Hallett
Mark Young

COPYRIGHT
Copyright 1990, University of New Mexico. All rights reserved.