Name

XtCallConverter — explicitly invoke resource conversions. 

Synopsis

Boolean XtCallConverter(display, converter, args, num_args, from, to_in_out, cache_ref_return)

      Display ∗display;
      XtTypeConverter converter;
      XrmValuePtr args;
      Cardinal num_args;
      XrmValuePtr from;
      XrmValuePtr to_in_out;
      XtCacheRef ∗cache_ref_return;

Arguments

displaySpecifies the display with which the conversion is to be associated. 

converterSpecifies the new-style conversion procedure to be called. 

argsSpecifies the additional conversion arguments needed to perform the conversion, or specifies NULL. 

num_argsSpecifies the count of additional arguments, or specifies zero. 

fromSpecifies a descriptor for the source value. 

to_in_outReturns the converted value. 

cache_ref_return
Returns a conversion cache ID.

Description

XtCallConverter looks up the specified type converter in the application context associated with the display.  If the converter was not registered or was registered with cache type XtCacheAll or XtCacheByDisplay, XtCallConverter looks in the conversion cache to see whether this conversion procedure has been called with the specified arguments.  If so, XtCallConverter checks the success status of the prior call.  If the conversion failed, XtCallConverter returns False immediately; otherwise it checks the size specified in the to_in_out argument. 

If this size is greater than or equal to the size stored in the cache, XtCallConverter:

•Copies the information stored in the cache to the location specified by the to_in_out argument. 

•Stores the cache size in to_in_out->size. 

•Returns True. 

If the size specified in the to_in_out argument is smaller than the size stored in the cache, XtCallConverter copies the cache size into to->size and returns False.  If the converter was registered with cache type XtCacheNone or if no value was found in the conversion cache, XtCallConverter calls the converter and if it was not registered with cache type XtCacheNone enters the result in the cache.  XtCallConverter then returns what the converter returned. 

cache_ref_return specifies storage allocated by the caller in which an opaque value will be stored.  If the type converter has been registered with the XtCacheRefCount modifier and if the value returned in cache_ref_return is non-NULL then the caller should store the cache_ref_return value in order to decrement the reference count when the converted value is no longer required.  cache_ref_return should be specified as NULL if the caller is unwilling or unable to store the value. 

See Also

XtConvertAndStore(1), XtSetTypeConverter(1),
XtTypeConverter(2).