hpux man page for xtappsettypeconverter

XtAppSetTypeConverter() 												   XtAppSetTypeConverter()

Name
  XtAppSetTypeConverter - register a "new-style" type converter in a single application context.

Synopsis
  void			 XtAppSetTypeConverter(app_context,		     from_type, 		 to_type,		   converter,
  convert_args, num_args, cache_type, destructor)
	   XtAppContext app_context;
	   String from_type;
	   String to_type;
	   XtTypeConverter converter;
	   XtConvertArgList convert_args;
	   Cardinal num_args;
	   XtCacheType cache_type;
	   XtDestructor destructor;

Inputs
  app_context
	    Specifies the application context.

  from_type Specifies the source type.

  to_type   Specifies the destination type.

  converter Specifies the resource type converter procedure.

  convert_args
	    Specifies additional conversion arguments, or NULL.

  num_args  Specifies the count of additional conversion arguments, or zero.

  cache_type
	    Specifies whether or not resources produced by this converter are sharable or display-specific and when they should be freed.

  destructor
	    Specifies a destroy procedure for resources produced by this conversion, or NULL if no additional action is required, to  deallo-
	    cate resources produced by converter.

Availability
  Release 4 and later.

Description
  XtAppSetTypeConverter()  registers  converter  in  app_context  as  a procedure to convert data of resource type from_type to resource type
  to_type.

  Each element of convert_args is an XtConvertArgRec.  It is not the argument actually passed to the converter procedure, but  specifies  how
  to  obtain  an XrmValue argument which will be passed to the converter.  The "Background" section below explains the XtConvertArgRec struc-
  ture in detail.

  Converted resource values returned by converter  will  automatically	be  cached  according  to  the	argument  cache_type,  which  can  be
  XtCacheNone,	XtCacheAll,  or XtCacheByDisplay.  The meanings of these types are described in the "Background" section below.  In addition,
  the qualifier XtCacheRefCount can be ORed with any of these values and specifies that references to cached values  produced  by  this  con-
  verter  should  be  counted,	and if the count ever drops to zero, the value should be removed from the cache, and the procedure destructor
  should be called to free any memory or resources associated with that value.

  If the same from_type and to_type are specified in multiple calls to XtAppSetTypeConverter(), the most recent overrides the previous ones.

  See XtTypeConverter(2) for an explanation of how to write a "new-style" converter.  See XtDestuctor(2) for an explanation of how to write a
  destructor procedure.  See XtCallConverter() for an explanation of how reference counting of cached values is performed.

Usage
  XtAppSetTypeConverter()  registers  a  resource converter of a type added to the Intrinsics in Release 4.  If you need to register an "old-
  style" converter which was written before Release 4, use XtAppAddConverter().

  XtSetTypeConverter() is identical to XtAppSetTypeConverter() except that it registers the converter in all application contexts,  including
  application contexts that are created in the future.

  If you write a widget that has a resource which is of some enumerated type, you should write a converter routine which will convert between
  the symbolic names of each value and the values themselves.  This converter should then be registered in your  widget's  class_initialize()
  method.

  If  you  are writing a programming library or an application that defines non-standard types, it may be useful to provide string converters
  for those types.  This allows resources of that type to be specified from a resource file.  An application that supported user-configurable
  popup menus, for example, might include a String-to-Menu converter.

  Some converters need additional arguments, such as a screen or colormap in order to correctly perform the conversion.  These converters are
  registered with an XtConvertArgList.	Generally the author of the converter will also define a static array of XtConvertArgRec to be regis-
  tered  with  the converter.  There are also two XtConvertArgLists predefined by the Intrinsics: screenConvertArg passes the widget's screen
  field to the converter in args[0], and colorConvertArgs passes the widget's screen field to the converter in args[0] and the widget's  col-
  ormap field in args[1].

  The Intrinsics define a number of standard converters which do not need to be registered.  See XtConvertAndStore() for a list of these pre-
  defined converters.  There are also a number of other useful converters defined in the Xmu library which do need to be  registered  explic-
  itly.  See XmuCvtStringToMisc(6).

Example
  You can register the XmuCvtStringToColorCursor from the Xmu library with the following:

     static XtConvertArgRec colorCursorConvertArgs[] = {
       {XtWidgetBaseOffset, (XtPointer) XtOffsetOf(WidgetRec, core.screen),
	 sizeof(Screen *)},
       {XtResourceString, (XtPointer) XtNpointerColor,sizeof(Pixel)},
       {XtResourceString, (XtPointer) XtNpointerColorBackground, sizeof(Pixel)},
       {XtWidgetBaseOffset, (XtPointer) XtOffsetOf(WidgetRec,core.colormap),
	 sizeof(Colormap)}
     };

     XtSetTypeConverter(XtRString, XtRColorCursor, XmuCvtStringToColorCursor,
			colorCursorConvertArgs, XtNumber(colorCursorConvertArgs),
			XtCacheByDisplay, NULL);

Background
Specifying Arguments to a Converter
  For  the  few type converters that need additional arguments, the Intrinsics conversion mechanism provides a method of specifying how these
  arguments should be computed.  Before a converter is called, each element of the XtConvertArgList is interpreted to determine the sizes and
  values  of the arguments.  These computed arguments are passed to the converter as an array of XrmValue.  The enumerated type XtAddressMode
  and the structure XtConvertArgRec specify how each argument is derived.

     typedef enum {
	  /* address mode     parameter representation */
	     XtAddress,       /* address */
	     XtBaseOffset,    /* offset */
	     XtImmediate,     /* constant */
	     XtResourceString,/* resource name string */
	     XtResourceQuark, /* resource name quark */
	     XtWidgetBaseOffset,/* offset */
	     XtProcedureArg   /* procedure to call */
     } XtAddressMode;

     typedef struct {
	  XtAddressMode address_mode;
	  XtPointer address_id;
	  Cardinal size;
     } XtConvertArgRec, *XtConvertArgList;

  The size field of an XtConvertArgRec specifies the length of the data in bytes.  The address_mode field specifies how the address_id	field
  should be interpreted.  The possible values of XtAddressMode have the following meanings:

  XtAddress
	 causes address_id to be interpreted as the address of the data.

  XtBaseOffset
	 causes address_id to be interpreted as the offset from the widget base.

  XtImmediate
	 causes address_id to be interpreted as a constant.

  XtResourceString
	 causes address_id to be interpreted as the name of a resource that is to be converted into an offset from the widget base.

  XtResourceQuark
	 causes address_id to be interpreted as the result of an XrmStringToQuark() conversion on the name of a resource, which is to be con-
	 verted into an offset from the widget base.

  XtWidgetBaseOffset
	 is similar to XtBaseOffset except that it searches for the closest windowed ancestor if the object is not of a subclass of Core.

  XtProcedureArg
	 specifies that address_id is a pointer to a procedure of type XtConvertArgProc to be invoked to return the conversion argument.  See
	 XtConvertArgProc(2) for an explanation of how to write a procedure of this type.

Caching Converted Values
  The possible values for the cache_type argument are as follows:

  XtCacheNone
	 Specifies  that  the  results	of a previous conversion may not be reused to satisfy any other resource requests; the specified con-
	 verter will be called each time the converted value is required.

  XtCacheAll
	 Specifies that the results of a previous conversion should be reused for any resource request that  depends  upon  the  same  source
	 value and conversion arguments.

  XtCacheByDisplay
	 Specifies  that  the results of a previous conversion should be used as for XtCacheAll but that the value should be removed from the
	 cache and the destructor, if any, should be called, when XtCloseDisplay() is called for the display connection associated  with  the
	 converted value.

  The qualifier XtCacheRefCount may be ORed with any of the above values.  If XtCacheRefCount is specified, calls to XtCreateWidget(), XtCre-
  ateManagedWidget(), XtGetApplicationResources() and XtGetSubresources() that use the converted value will be counted.  When a widget	using
  the  converted  value  is  destroyed,  the count is decremented, and if the count reaches zero, the destructor procedure destructor will be
  called and the converted value will be removed from the conversion cache.

Structures
  The XtConvertArgRec structure and the related XtAddressMode type are shown in the "Background" section above.  The XtCacheType type and its
  legal values are defined as follows:

     typedef int	     XtCacheType;

     #define		     XtCacheNone       0x001
     #define		     XtCacheAll        0x002
     #define		     XtCacheByDisplay  0x003
     #define		     XtCacheRefCount   0x100

See Also
  XtAppReleaseCacheRefs(1), XtCallbackReleaseCacheRef(1), XtCallbackReleaseCacheRefList(1), XtCallConverter(1), XtConvertAndStore(1), XtSet-
  TypeConverter(1),
  XtConvertArgProc(2), XtDestructor(2), XtTypeConverter(2).

Xt - Resource Management												   XtAppSetTypeConverter()