DESIGN (xvforms) functions
LIBRARY ROUTINE
xvf_add_extra_call - add function call to GUI item
LIBRARY CALL
int xvf_add_extra_call(
kform_struct *kformstruct,
void (*routine)(kaddr),
kaddr client_data,
int call_location)
INPUT
- kformstruct - kform_struct associated with the GUI item,
to which the extra call is to be added.
Note that all candidates for this argument
will be found in the GUI Information structure,
which is automatically generated in the
"form_info.h" file.
- routine - The extra routine to call. This routine MUST
be declared as follows:
void routine(
kaddr client_data)
- client_data - Client data with which to call extra routine.
The client_data pointer is used when it is
necessary to pass arguments to a callback
routine. First, define a single structure
containing all the parameters needed. Declare
a pointer to the structure, dynamically
allocate the pointer, and initialize all the
fields with the values that you would have
given to the parameters before passing them to
the routine in a normal call. Pass the pointer
to your allocated, initialized structure to
xvf_add_extra_call() as the client_data.
Inside the callback, cast the client_data to
the appropriate structure type, as in:
my_struct *my_ptr = (my_struct *) client_data;
At that point, the fields may be accessed as
desired. They will hold the values to which
they were initialized.
- call_location - tells whether the specified routine should
be called before the "normal" operation of
the item is performed, after the "normal"
operation of the item is performed, or
instead of the "normal" operation of the
item.
One of: XVF_CALL_FIRST, XVF_CALL_LAST,
or XVF_CALL_SUBSTITUTE
OUTPUT
none
RETURN VALUE
TRUE on success, FALSE on failure
DESCRIPTION
Some items on the Khoros GUI perform a particular
function automatically, without ever returning flow
control to the application program; they cannot be
made "live" in order to force a return of flow control
to the application. These items include:
(1) subform buttons, which map a subform
(2) guide buttons, which map a pane
(3) quit buttons, which close the subform or exit the program
(4) help buttons, which put up a help page
(5) answer input files, which update the GUI according to a GUI answer file
(6) answer output files, which write out a GUI answer file
With these items, a mechanism is sometimes desired which
will allow the programmer to call a particular routine when
these items are used. For example, the programmer may want
a certain routine to be called before a subform is mapped,
after a pane is mapped, before the GUI is destroyed, or before
a help page is displayed. For situations like this,
xvf_add_extra_call() may be used to specify an additional
routine that will be called by the built-in callback for
the GUI item in question. xvf_add_extra_call() may be
called more than once, if calls to more than one extra
routine are needed.
ADDITIONAL INFORMATION
none
EXAMPLES
none
SIDE EFFECTS
none
RESTRICTIONS
This routine is only supported for kformstructs that are
associated with subform buttons, guide buttons, quit buttons,
help buttons, answer input file selections, or answer
output file selections. Other GUI items either return control
to the application program by their definition (as with Action
buttons) or can be made "live" (as with Toggles, Input Files,
Integer selections, etc); either case makes an additional
callback installation redundant.
MODIFICATION
none
FILES
$DESIGN/objects/library/xvforms/src/extra.c
SEE ALSO
xvforms(3)
COPYRIGHT
Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.