hpux man page for xtconvertargproc

XtConvertArgProc()														XtConvertArgProc()

Name
  XtConvertArgProc - interface definition for procedure to obtain an argument for a resource converter.

Synopsis
  typedef void (*XtConvertArgProc)(Widget, Cardinal *, XrmValue *);
	 Widget object;
	 Cardinal *size;
	 XrmValue *value_return;

Inputs
  object      Specifies  the  object  for which the resource is being converted, or NULL if the converter was invoked by XtCallConverter() or
	      XtDirectConvert().  May be of class Object or any subclass thereof.

  size	      Specifies a pointer to the size field from the XtConvertArgRec structure.

Outputs
  value_return
	      Returns the address and size of the argument.

Availability
  Release 4 and later.

Description
  A procedure of type XtConvertArgProc gets an argument needed when calling a resource converter.  It is registered in the  address_id	field
  of an XtConvertArgRec structure with the address_mode field XtProcedureArg.  This XtConvertArgRec structure must be part of an XtConvertAr-
  gList array which is registered with a converter procedure with XtAppSetTypeConverter(), XtSetTypeConverter(), or XtAppAddConverter().

  When invoked, the XtConvertArgProc procedure must derive its argument value (generally from the specified object) and store the address and
  size	of the value in the XrmValue structure pointed to by its value_return argument.  The size argument is not assigned any meaning by the
  Intrinsics, and can be used like client_data to a callback procedure, if desired.

  To permit re-entry, XtConvertArgProc should return the address of storage whose lifetime is no shorter than the  lifetime  of  object.   If
  object  is  NULL,  the  lifetime  of the conversion argument must be no shorter than the lifetime of the resource with which the conversion
  argument is associated.  The Intrinsics do not guarantee to copy this storage, but they do guarantee not to reference it if the resource is
  removed from the conversion cache.

  If  the  XtConvertArgProc modifies the resource database, the changes affect any in-progress widget creation or XtGetApplicationResources()
  or XtGetSubresources() calls in an implementation-defined manner.  Insertion of new entries into the database and modification of  existing
  entries is allowed, however, and will not directly cause an error.

  See XtAppSetTypeConverter() for an explanation of how to declare an XtConvertArgList which will invoke an XtConvertArgProc.

Example
  The  XtConvertArgProc  used by the Intrinsics String-to-Cursor converter is shown below, along with the XtConvertArgList that registers it.
  It looks up the Display * of the specified widget, and places its address (a Display **) in value->addr.  (Note that DisplayOfScreen() is a
  macro, so the ampersand before it is legal.)

     /*ARGSUSED*/
     static void FetchDisplayArg(widget, size, value)
	 Widget widget;
	 Cardinal *size;
	 XrmValue* value;
     {
	 if (widget == NULL)
	     XtErrorMsg("missingWidget", "fetchDisplayArg", XtCXtToolkitError,
			"FetchDisplayArg called without a widget to reference",
			(String*)NULL, (Cardinal*)NULL);
	     /* can't return any useful Display and caller will de-ref NULL,
		so aborting is the only useful option */

	 value->size = sizeof(Display*);
	 value->addr = (XPointer)&DisplayOfScreen(XtScreenOfObject(widget));
     }

     static XtConvertArgRec Const displayConvertArg[] = {
	 {XtProcedureArg, (XtPointer)FetchDisplayArg, 0},
     };

  The  String-to-Cursor  converter  could now be registered with a call like the following.  Given the displayConvertArg array defined above,
  that converter would be invoked with args[0].addr, the address of the Display pointer that the converter should use.

     XtSetTypeConverter(XtQString,  XtQCursor, CvtStringToCursor,
			displayConvertArg, XtNumber(displayConvertArg),
			XtCacheByDisplay, FreeCursor);

See Also
  XtAppSetTypeConverter(1), XtAppAddConverter(1), XtSetTypeConverter(1),
  XtTypeConverter(2).

Xt - Resource Management													XtConvertArgProc()