XtConvertAndStore(3)

✨ XtConvertAndStore — from the XT FUNCTIONS manual, section 3 🎀

okay bestie, gather round, because this one is literally the resource converter page and it's giving plumbing that makes the whole toolkit work. Two functions, one job: make the converter go brrr. 💅

---

🌸 NAME 🌸

XtConvertAndStore, XtCallConverter — invoke resource converters 💖

---

✨ SYNTAX ✨

#include <X11/Intrinsic.h>

Boolean XtConvertAndStore(Widget widget, const char *from_type,
       XrmValuePtr from, const char *to_type, XrmValuePtr to_in_out);

Boolean XtCallConverter(Display* dpy, XtTypeConverter converter,
       XrmValuePtr args, Cardinal num_args, XrmValuePtr from,
       XrmValuePtr to_in_out, XtCacheRef* cache_ref_return);

no cap, that's the whole vibe right there 👑 (copy it exactly, do not freestyle it, the compiler will find out)

---

🦋 ARGUMENTS 🦋

• args — the argument list holding all the extra lil arguments you need to actually pull off the conversion, or NULL if you're not about that life. 🫶
• converter — the conversion procedure that's getting called. the main character of this operation, fr fr.
• from — the value you're converting. the before picture. 💜
• from_type — the source type. where we're coming from, literally.
• num_args — how many extra arguments there are (often zero, because sometimes simplicity ate). ✨
• to_type — the destination type. where we're going, glow-up pending. 🌈
• to_in_out — returns the converted value. the after picture. 📸
• widget — the widget you use for extra arguments if any are needed, plus the destroy callback list. she's holding the context, iconic behaviour.
• dpy — the display this conversion is associated with. gotta know which screen we're serving. 🖥️

---

💖 DESCRIPTION 💖

so. the tea. ☕

🧚 XtConvertAndStore

XtConvertAndStore looks up the type converter registered to convert from_type to to_type, computes any additional arguments that are needed, and then calls XtCallConverter — (or XtDirectConvert if an old-style converter was registered with XtAddConverter or XtAppAddConverter) — handing it the from and to_in_out arguments. she's the project manager. she delegates. she slays. 💅

🎀 XtCallConverter

XtCallConverter looks up the specified type converter in the application context associated with the display and, if the converter was not registered or was registered with cache type XtCacheAll or XtCacheByDisplay, it peeks in the conversion cache to see if this conversion procedure has already been called with the specified conversion arguments. 👀

if it has, it checks the success status of the prior call:

• if the conversion failed, XtCallConverter returns False immediately — no second chances, she's done. 💀
• otherwise it checks the size specified in the to argument and, if that size is greater than or equal to the size stored in the cache, it copies the info stored in the cache into the location specified by to->addr, stores the cache size into to->size, and returns True. 🥳
• but if the size specified in the to argument is smaller than the size stored in the cache, XtCallConverter copies the cache size into to->size and returns False. bestie, the buffer was not big enough, tragic. 😭

and if the converter was registered with cache type XtCacheNone, or no value was found in the conversion cache at all, XtCallConverter calls the converter and — as long as it was not registered with cache type XtCacheNone — enters the result into the cache. then XtCallConverter returns whatever the converter returned. 🫡

🌟 the cache_ref_return field

the cache_ref_return field 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 the value returned in cache_ref_return is non-NULL, then the call should store the cache_ref_return value so it can decrement the reference count when the converted value is no longer required. 🔥

⚠️ and cache_ref_return should be NULL if the caller is unwilling or unable to store the value. no pretending. be honest with her. 🙈

---

👑 SEE ALSO 👑

• XtAppReleaseCacheRefs(3)
• X Toolkit Intrinsics - C Language Interface
• Xlib - C Language X Interface

---

okay that's the whole page, you ate that, go convert something 💖

this was brought to you by X Version 11 and libXt 1.3.1 — mwah, drink your water, and remember that XtConvertAndStore(3) is always in your corner 🎀✨🦋💜