xvforms(3)

NAME
xvforms - All routines for the graphical user interface.

DESCRIPTION
xvforms library containing all routines for the graphical user interface, except for independant utilities, which are found in the xvutils library. 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 xvforms 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 "xvforms.h"

AVAILABLE ROUTINES

xvf_strcpy()

This routine is a more robust version of strcpy(). It will allocate the necessary number of bytes for you. Passing a NULL string will cause a segmentation fault.

xvf_strcpy(string)
char *string;

xvf_strlen()

This routine is a more robust version on strlen(). It will return 0 if the string passed in is NULL.

xvf_strlen(string);
char *string;

xvf_initialize()

Does all necessary initializations in preparation for using the graphical user interface. Opens the workstation display for use with the X windowing system, version 11, release 4, and returns a pointer to the Display structure (see Xlib.h). It also creates an application context for the user interface to be created by xvforms and initializes various internal parameters. This routine MUST be called before any other calls to the xvforms library are made (excepting calls to xvf_strcpy and xvf_strlen).

Display *xvf_initialize(argc, argv, program_name)
unsigned int argc;
char *argv[];
char *program_name;

xvf_create_form()

Creates the internal abstract data structure that will be used for managing and maintaining the graphical user interface for the application program; also creates the physical representation of the graphical user interface through use of the Athena Widget set. Both are based on the specification provided in the user interface specification file passed in. The pointer to the xvf_form produced is returned for the application program to use with later calls to other xvform routines.

xvf_form *xvf_create_form(filename, argv, argc,
    glyph_type, callback_routine, x, y)
char *filename;
char **argv;
unsigned int argc;
int glyph_type;
void (* callback_routine)();
int x, y;

xvf_run_form()

This routine runs the graphical user interface. It gets events and dispatches them until some action by the user (e.g, a click on an action button, a <cr> in a live selection, etc) indicates that software control is to be returned to the application program. It returns a pointer to the current xvf_form structure (note that in a few very rare cases, an application may use more than one set of forms)

xvf_form *xvf_run_form()

xvf_change_active(}

Allows the applications programmer to specify "turn on" a form. Should be called after xvf_create_form(), but before xvf_run_wait(). During run-time, if a form is to be unmapped, a call should be made to xvf_change_active() with active = false.

xvf_change_active(form, active)
xvf_form *form;
int active;

xvf_change_unmap()

This routine lets the applications programmer specify if the form is to be unmapped when run_form_wait() is finished and control is returned to the application program.

xvf_change_unmap(form, unmap)
xvf_form *form;
int unmap;

xvf_add_entry()

Adds the specified form to the list of forms to be used. The specified routine will be called when the form would normally return to the application program.

xvf_add_entry (form, routine)
xvf_form *form;
void (*routine)();

xvf_delete_entry()

Removes the form from the list of forms to be used. The form is not destroyed.

xvf_delete_entry(form)
xvf_form *form;

xvf_change_input()

Allows the application program to change the appearance of its graphical user interface while it is running.

int xvf_change_input(formptr, index, change_code, string, max_strlen)
xvf_form *formptr;
int index;
int change_code;
char *string;
int max_strlen;

xvf_clear_selections()

Allows the application program to clear out the values of the graphical user interface before the next iteration of the loop whose first call is to xvf_run_form(). Should be the last line of code in the loop, specified as:
    xvf_clear_selections(form->db, form->line_num);
where form is the pointer to the xvf_form structure that was returned by xvf_create_form().

xvf_clear_selections(database, line_num);
char **database;
int line_num;