hpux man page for xtappaddconverter

XtAppAddConverter()													       XtAppAddConverter()

Name
  XtAppAddConverter - register an "old-style" resource converter.

Synopsis
  void XtAppAddConverter(app_context, from_type, to_type, converter, convert_args, num_args)
	 XtAppContext app_context;
	 String from_type;
	 String to_type;
	 XtConverter converter;
	 XtConvertArgList convert_args;
	 Cardinal num_args;

Inputs
  app_context Specifies the application context.

  from_type   Specifies the source type of the resource to be converted.

  to_type     Specifies the destination type to which the resource is to be converted.

  converter   Specifies the converter procedure.  See XtConverter(2).

  convert_args
	      Specifies how to obtain additional arguments needed for the conversion; if no arguments are provided, this should be NULL.  See
	      the Structures section below for a detailed description of the format of convert_args.

  num_args    Specifies the number of additional arguments to the converter or zero.

Description
  XtAppAddConverter() registers converter in application context 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.

  See XtConverter(2) for an explanation of how to write an "old-style" converter.

Usage
  XtAppAddConverter()  registers  an  "old-style"  converter.	This kind of converter is still in common use, but are not as flexible as the
  (incompatible) "new-style" converter added in Release 4.  If you must register an existing old-style	converter,  use  XtAppAddConverter(),
  but if you are writing a converter of your own, consider using a new-style converter.  See XtAppSetTypeConverter().

  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 String-to-Widget converter from the Xmu library with the following:

     static XtConvertArgRec parentCvtArg[] = {
	 {XtBaseOffset, (XtPointer)XtOffset(Widget, core.parent), sizeof(Widget)}
     };

     XtAppAddConverter(app, XtRString, XtRWidget, XmuCvtStringToWidget,
		       parentCvtArg, XtNumber(parentCvtArg));

Background
  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.

Structures
  The XtConvertArgRec structure and the related XtAddressMode type are shown in the "Background" section above.

See Also
  XtAppSetTypeConverter(1), XtCallConverter(1), XtConvertandStore, XtDirectConvert(1), XtSetTypeConverter(1),
  XtConverter(2), XtTypeConverter(2), XtConvertArgProc(2),
  XmuCvtStringToMisc(6).

Xt - Resource Management												       XtAppAddConverter()