hpux man page for xtdestructor

XtDestructor()															    XtDestructor()

Name
  XtDestructor - 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
  XtSetTypeConverter().  It is called when a resource returned by that converter 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 deallo-
  cate 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  mem-
  ory  (if the resource value is a pointer type, for example, the Intrinsics will only free the memory that holds the pointer, not the struc-
  ture 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
  arguments to callback and other procedures, and can be used to identify other memory that must be freed, X resources that must  be  deallo-
  cated, 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 conversion 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 Intrinsics String-to-Pixel converter.  It deallocates the Pixel,  which  is
  an  X  server  resource.   Note that it does not free the memory that the cursor 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  con-
  verter procedure 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 Also
  XtAppSetTypeConverter(1), XtSetTypeConverter(1),
  XtTypeConverter(2).

Xt - Resource Management													    XtDestructor()