XtDestructor()XtDestructor()NameXtDestructor - interface definition for procedure to destroy cached
resource data returned by a new-style resource converter.
Synopsis
typedef void (*XtDestructor) (XtAppContext, XrmValue *, XtPointer,
XrmValue *, Cardinal *);
XtAppContext app;
XrmValue *to;
XtPointer converter_data;
XrmValue *args;
Cardinal *num_args;
Inputs
app Specifies in application context in which the resource is
being freed.
to Specifies the address and size of the cached resource value
produced by the type converter.
converter_data
Specifies the converter_data returned by the type converter.
args Specifies the additional converter arguments as passed to the
type converter when the conversion was performed.
num_args Specifies the number of additional converter arguments.
Availability
Release 4 and later.
Description
An XtDestructor is optionally registered with an XtTypeConverter new-
style resource converter in a call to XtAppSetTypeConverter() or XtSet‐
TypeConverter(). It is called when a resource returned by that con‐
verter is freed from the cache. The Intrinsics automatically free the
memory occupied by the resource value (i.e., the memory pointed to by
to->addr), so the destructor should not do this but must deallocate the
resource itself if it is a shared resource (such as an open file, or a
Pixmap owned by the X server) and free any associated memory (if the
resource value is a pointer type, for example, the Intrinsics will only
free the memory that holds the pointer, not the structure pointed to by
the pointer).
The converter_data argument is data returned by the type converter in
its converter_data argument. This data may be of any type, cast to an
XtPointer by the converter, and cast back to the original type by the
destructor procedure. It serves a similar purpose to client_data argu‐
ments to callback and other procedures, and can be used to identify
other memory that must be freed, X resources that must be deallocated,
and so on.
The args and num_args arguments are the additional arguments passed to
the resource converter when the conversion was performed. These values
are also part of the resource cache, and can be used by the destructor
to figure out what must be freed. The destructor should not free the
args array; the Intrinsics will free it automatically.
See XtAppSetTypeConverter(1) for more information on resource conver‐
sion and caching. See XtTypeConverter(2) for more information on the
responsibilities of a resource converter procedure.
Example
The following procedure is the XtDestructor registered with the Intrin‐
sics String-to-Pixel converter. It deallocates the Pixel, which is an
X server resource. Note that it does not free the memory that the cur‐
sor is stored in. The converter_data argument (called closure here) is
used to indicate whether this Pixel should be freed, or whether it is
permanently allocated. See XtTypeConverter(2) for the converter proce‐
dure which accompanies this destructor.
/* ARGSUSED */
static void FreePixel(app, toVal, closure, args, num_args)
XtAppContext app;
XrmValuePtr toVal;
XtPointer closure;
XrmValuePtr args;
Cardinal *num_args;
{
Screen *screen;
Colormap colormap;
if (*num_args != 2) {
XtAppWarningMsg(app, XtNwrongParameters,"freePixel",XtCXtToolkitError,
"Freeing a pixel requires screen and colormap arguments",
(String *)NULL, (Cardinal *)NULL);
return;
}
screen = *((Screen **) args[0].addr);
colormap = *((Colormap *) args[1].addr);
if (closure) {
XFreeColors( DisplayOfScreen(screen), colormap,
(unsigned long*)toVal->addr, 1, (unsigned long)0);
}
}
Structures
The XrmValue structure is defined as follows:
typedef struct {
unsigned int size;
XPointer addr;
} XrmValue, *XrmValuePtr;
See AlsoXtAppSetTypeConverter(1), XtSetTypeConverter(1),
XtTypeConverter(2).
Xt - Resource Management XtDestructor()
