NAME

XmbTextListToTextProperty, XwcTextListToTextProperty, Xutf8TextListToTextProperty, XmbTextPropertyToTextList, XwcTextPropertyToTextList, Xutf8TextPropertyToTextList, XwcFreeStringList, XDefaultString - convert text lists and text property structures

SYNTAX

int XmbTextListToTextProperty(Display *_d_i_s_p_l_a_y, char **_l_i_s_t, int _c_o_u_n_t, XICCEncodingStyle _s_t_y_l_e, XTextProperty *_t_e_x_t___p_r_o_p___r_e_t_u_r_n); int XwcTextListToTextProperty(Display *_d_i_s_p_l_a_y, wchar_t **_l_i_s_t, int _c_o_u_n_t, XICCEncodingStyle _s_t_y_l_e, XTextProperty *_t_e_x_t___p_r_o_p___r_e_t_u_r_n); int Xutf8TextListToTextProperty(Display *_d_i_s_p_l_a_y, char **_l_i_s_t, int _c_o_u_n_t, XICCEncodingStyle _s_t_y_l_e, XTextProperty *_t_e_x_t___p_r_o_p___r_e_t_u_r_n); int XmbTextPropertyToTextList(Display *_d_i_s_p_l_a_y, XTextProperty *_t_e_x_t___p_r_o_p, char ***_l_i_s_t___r_e_t_u_r_n, int *_c_o_u_n_t___r_e_t_u_r_n); int XwcTextPropertyToTextList(Display *_d_i_s_p_l_a_y, XTextProperty *_t_e_x_t___p_r_o_p, wchar_t ***_l_i_s_t___r_e_t_u_r_n, int *_c_o_u_n_t___r_e_t_u_r_n); int Xutf8TextPropertyToTextList(Display *_d_i_s_p_l_a_y, XTextProperty *_t_e_x_t___p_r_o_p, char ***_l_i_s_t___r_e_t_u_r_n, int *_c_o_u_n_t___r_e_t_u_r_n); void XwcFreeStringList(wchar_t **_l_i_s_t); char *XDefaultString(void)

ARGUMENTS

_d_i_s_p_l_a_y Specifies the connection to the X server.
_l_i_s_t Specifies a list of null-terminated character strings.
_c_o_u_n_t Specifies the number of strings specified.
_s_t_y_l_e Specifies the manner in which the property is encoded.
_t_e_x_t___p_r_o_p___r_e_t_u_r_n Returns the
_X_T_e_x_t_P_r_o_p_e_r_t_y structure.
_t_e_x_t___p_r_o_p Specifies the
_X_T_e_x_t_P_r_o_p_e_r_t_y structure to be used.
_l_i_s_t___r_e_t_u_r_n Returns a list of null-terminated character strings.
_c_o_u_n_t___r_e_t_u_r_n Returns the number of strings.
_l_i_s_t Specifies the list of strings to be freed.

DESCRIPTION

The _X_m_b_T_e_x_t_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y, _X_w_c_T_e_x_t_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y and _X_u_t_f_8_T_e_x_t_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y functions set the specified _X_T_e_x_t_P_r_o_p_e_r_t_y value to a set of null-separated elements representing the concatenation of the specified list of null-terminated text strings. The input text strings must be given in the current locale encoding (for _X_m_b_T_e_x_t_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y and _X_w_c_T_e_x_t_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y), or in UTF-8 encoding (for _X_u_t_f_8_T_e_x_t_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y).

The functions set the encoding field of text_prop_return to an _A_t_o_m for the specified display naming the encoding determined by the specified style and convert the specified text list to this encoding for storage in the text_prop_return value field. If the style _X_S_t_r_i_n_g_S_t_y_l_e or _X_C_o_m_p_o_u_n_d_T_e_x_t_S_t_y_l_e is specified, this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively. If the style _X_U_T_F_8_S_t_r_i_n_g_S_t_y_l_e is specified, this encoding is ``UTF8_STRING''. (This is an extension introduced by The XFree86 Project, Inc. in their 4.0.2 release. Its presence is indicated by the macro _X___H_A_V_E___U_T_F_8___S_T_R_I_N_G.) If the style _X_T_e_x_t_S_t_y_l_e is specified, this encoding is the encoding of the current locale. If the style _X_S_t_d_I_C_C_T_e_x_t_S_t_y_l_e is specified, this encoding is ``STRING'' if the text is fully convertible to STRING, else ``COMPOUND_TEXT''. A final terminating null byte is stored at the end of the value field of text_prop_return but is not included in the nitems member.

If insufficient memory is available for the new value string, the functions return _X_N_o_M_e_m_o_r_y. If the current locale is not supported, the functions return _X_L_o_c_a_l_e_N_o_t_S_u_p_p_o_r_t_e_d. In both of these error cases, the functions do not set text_prop_return.

To determine if the functions are guaranteed not to return _X_L_o_c_a_l_e_N_o_t_S_u_p_p_o_r_t_e_d, use _X_S_u_p_p_o_r_t_s_L_o_c_a_l_e.

If the supplied text is not fully convertible to the specified encoding, the functions return the number of unconvertible characters. Each unconvertible character is converted to an implementation-defined and encoding-specific default string. Otherwise, the functions return _S_u_c_c_e_s_s. Note that full convertibility to all styles except _X_S_t_r_i_n_g_S_t_y_l_e is guaranteed.

To free the storage for the value field, use _X_F_r_e_e.

The _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t, _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t and _X_u_t_f_8_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t functions return a list of text strings representing the null-separated elements of the specified _X_T_e_x_t_P_r_o_p_e_r_t_y structure. The returned strings are encoded using the current locale encoding (for _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t and _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t) or in UTF-8 (for _X_u_t_f_8_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t). The data in text_prop must be format 8.

Multiple elements of the property (for example, the strings in a disjoint text selection) are separated by a null byte. The contents of the property are not required to be null-terminated; any terminating null should not be included in text_prop.nitems.

If insufficient memory is available for the list and its elements, _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t, _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t and _X_u_t_f_8_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t return _X_N_o_M_e_m_o_r_y. If the current locale is not supported, the functions return _X_L_o_c_a_l_e_N_o_t_S_u_p_p_o_r_t_e_d. Otherwise, if the encoding field of text_prop is not convertible to the encoding of the current locale, the functions return _X_C_o_n_v_e_r_t_e_r_N_o_t_F_o_u_n_d. For supported locales, existence of a converter from COMPOUND_TEXT, STRING, UTF8_STRING or the encoding of the current locale is guaranteed if _X_S_u_p_p_o_r_t_s_L_o_c_a_l_e returns _T_r_u_e for the current locale (but the actual text may contain unconvertible characters). Conversion of other encodings is implementation-dependent. In all of these error cases, the functions do not set any return values.

Otherwise, _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t, _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t and _X_u_t_f_8_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t return the list of null-terminated text strings to list_return and the number of text strings to count_return.

If the value field of text_prop is not fully convertible to the encoding of the current locale, the functions return the number of unconvertible characters. Each unconvertible character is converted to a string in the current locale that is specific to the current locale. To obtain the value of this string, use _X_D_e_f_a_u_l_t_S_t_r_i_n_g. Otherwise, _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t, _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t and _X_u_t_f_8_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t return _S_u_c_c_e_s_s.

To free the storage for the list and its contents returned by _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t or _X_u_t_f_8_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t, use _X_F_r_e_e_S_t_r_i_n_g_L_i_s_t. To free the storage for the list and its contents returned by _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t, use _X_w_c_F_r_e_e_S_t_r_i_n_g_L_i_s_t.

The _X_w_c_F_r_e_e_S_t_r_i_n_g_L_i_s_t function frees memory allocated by _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t.

The _X_D_e_f_a_u_l_t_S_t_r_i_n_g function returns the default string used by Xlib for text conversion (for example, in _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t). The default string is the string in the current locale that is output when an unconvertible character is found during text conversion. If the string returned by _X_D_e_f_a_u_l_t_S_t_r_i_n_g is the empty string (""), no character is output in the converted text. _X_D_e_f_a_u_l_t_S_t_r_i_n_g does not return NULL.

The string returned by _X_D_e_f_a_u_l_t_S_t_r_i_n_g is independent of the default string for text drawing; see _X_C_r_e_a_t_e_F_o_n_t_S_e_t to obtain the default string for an _X_F_o_n_t_S_e_t.

The behavior when an invalid codepoint is supplied to any Xlib function is undefined.

The returned string is null-terminated. It is owned by Xlib and should not be modified or freed by the client. It may be freed after the current locale is changed. Until freed, it will not be modified by Xlib.

The functions _X_u_t_f_8_T_e_x_t_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y and _X_u_t_f_8_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t are extensions introduced by The XFree86 Project, Inc. in their 4.0.2 release. Their presence is indicated by the macro _X___H_A_V_E___U_T_F_8___S_T_R_I_N_G.

STRUCTURES

The _X_T_e_x_t_P_r_o_p_e_r_t_y structure contains:


typedef struct {
     unsigned char *value;/* property data */
     Atom encoding;      /* type of property */
     int format;         /* 8, 16, or 32 */
     unsigned long nitems;/* number of items in value */
} XTextProperty;


The _X_I_C_C_E_n_c_o_d_i_n_g_S_t_y_l_e structure contains:

lw(.5i) lw(2i) lw(2.5i).
T{
#define
T}   T{
_X_N_o_M_e_m_o_r_y
T}   T{
-1
T}
T{
#define
T}   T{
_X_L_o_c_a_l_e_N_o_t_S_u_p_p_o_r_t_e_d
T}   T{
-2
T}
T{
#define
T}   T{
_X_C_o_n_v_e_r_t_e_r_N_o_t_F_o_u_n_d
T}   T{
-3
T}

typedef enum {
     XStringStyle,       /* STRING */
     XCompoundTextStyle, /* COMPOUND_TEXT */
     XTextStyle,         /* text in owner's encoding (current locale) */
     XStdICCTextStyle,   /* STRING, else COMPOUND_TEXT */
     XUTF8StringStyle    /* UTF8_STRING */
} XICCEncodingStyle;


SEE ALSO

XSetTextProperty(3X11), XStringListToTextProperty(3X11)
_X_l_i_b _- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e