XMCVTTEXTPROPERTYTOXMSTRINGTABLE(3)

✨ NAME ✨

okay bestie, welcome to XmCvtTextPropertyToXmStringTable — she's a function that converts from a TextProperty Structure to a StringTable 💖 and yes that's a mouthful, we're gonna get through it together.

---

🌸 SYNOPSIS 🌸

#include <Xm/Xm.h>
int XmCvtTextPropertyToXmStringTable (display, text_prop, string_table_return, count_return)
        Display *display;
        XTextProperty   *text_prop;
        XmStringTable   *string_table_return;
        int     *count_return;
        (void)

periodt. now let's break it down 💅

---

🦋 DESCRIPTION 🦋

XmCvtTextPropertyToXmStringTable takes the XTextProperty structure you hand it and turns it into an XmStringTable, like so:

• If the encoding member of text_prop is the Atom STRING, every returned XmString gets a tag of "ISO8859-1" and a text type of XmCHARSET_TEXT. iconic.
• If the encoding member of text_prop is the encoding of the current locale, and that encoding is not STRING, then each returned XmString gets a tag of _MOTIF_DEFAULT_LOCALE and a text type of XmMULTIBYTE_TEXT. very demure, very locale-aware 💜
• If the encoding member of text_prop is anything other than STRING or the encoding of the current locale, then the contents of the returned compound strings are implementation dependent 🙈 (i.e. whatever your implementation feels like, no promises).

If the conversion depends on the locale and the current locale isn't supported, the function returns XLocaleNotSupported. If conversion to the encoding of the current locale is required, and the locale is supported but there's no converter available for the encoding specified in text_prop, the function returns XConverterNotFound. For supported locales, the existence of a converter from COMPOUND_TEXT, STRING, UTF8_STRING, or the encoding of the current locale is guaranteed if XSupportsLocale returns True for the current locale — but heads up, the actual text may still contain unconvertible characters 😭. Converting other encodings to the encoding of the current locale is implementation dependent. And in all of these error cases, the function does not set any return values. not even one. zero. nada.

Also! If an element of the value member of text_prop isn't convertible to XmString, the corresponding entry in the returned XmStringTable will be NULL, and XmCvtTextPropertyToXmStringTable still returns Success. she's forgiving like that 🫶

Now, about freeing — because bestie, memory doesn't free itself:

To free the storage for the XmStringTable and its count_return compound strings returned by this function, first free each XmString in the table using XmStringFree, and then free the XmStringTable itself using XtFree. In that order, no skipping, no shortcuts ✨

• display — Specifies the connection to the X server. hi X server 👋
• text_prop — Specifies a pointer to the XTextProperty. The format member of text_prop must be 8. that's a requirement, not a suggestion 💅
• string_table_return — Specifies the XmStringTable array into which the converted compound strings are placed. this is where the magic lands 💖
• count_return — Specifies the number of XmStrings returned by this function. the receipts, basically.

---

👑 RETURN VALUES 👑

Upon success, this function returns the set of XmStrings in string_table_return, and it returns the number of XmStrings in count_return, and returns Success. ate. otherwise, it returns the following:

• XLocaleNotSupported — Returned if conversion depends on the locale and the current locale is not supported. 😔
• XConverterNotFound — Returned if conversion to the encoding of the current locale is required and if the locale is supported but no converter is available for the encoding specified in text_prop. she looked everywhere, nothing. 💀

---

🌈 RELATED INFORMATION 🌈

XmCvtXmStringTableToTextProperty(3), XmText(3), and XmTextGetString(3). go read those too, iykyk 📚

---

and that's the whole page babes 💅 she lives in the (library call) manual, and ngl the footer doesn't hand over a date, so we're calling her timeless ✨ go forth and convert those TextProperties, you've got this 💖🎀🦋