


XmbTextListToTextProperty(3X11)		      XmbTextListToTextProperty(3X11)
X11R5									X11R5



NAME
  XmbTextListToTextProperty, XwcTextListToTextProperty,	XmbTextPropertyTo-
  TextList, XwcTextPropertyToTextList, XwcFreeStringList, XDefaultString -
  convert text lists and text property structures

SYNTAX
  int XmbTextListToTextProperty(_d_i_s_p_l_a_y, _l_i_s_t, _c_o_u_n_t, _s_t_y_l_e,
  _t_e_x_t__p_r_o_p__r_e_t_u_r_n)
	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(_d_i_s_p_l_a_y, _l_i_s_t, _c_o_u_n_t, _s_t_y_l_e,
  _t_e_x_t__p_r_o_p__r_e_t_u_r_n)
	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 XmbTextPropertyToTextList(_d_i_s_p_l_a_y, _t_e_x_t__p_r_o_p, _l_i_s_t__r_e_t_u_r_n,
  _c_o_u_n_t__r_e_t_u_r_n)
	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(_d_i_s_p_l_a_y, _t_e_x_t__p_r_o_p, _l_i_s_t__r_e_t_u_r_n,
  _c_o_u_n_t__r_e_t_u_r_n)
	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;

  void XwcFreeStringList(_l_i_s_t)
	wchar_t	**_l_i_s_t;

  char *XDefaultString()

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	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 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.	 A final terminating null is stored at the end of the value
  field	of text_prop_return but	is not included	in the nitems member.

  The functions	set the	encoding field of text_prop_return to an Atom 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_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''.

  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 uncon-
  vertible 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	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 functions
  return a list	of text	strings	in the current locale representing the null-
  separated elements of	the specified _X_T_e_x_t_P_r_o_p_e_r_t_y structure.	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 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 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, 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 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 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 char-
  acters.  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
  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	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, 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_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y).	The default
  string is the	string in the current locale which is output when an uncon-
  vertible 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.

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:



  #define

	    _X_N_o_M_e_m_o_r_y

				  -1


  #define

	    _X_L_o_c_a_l_e_N_o_t_S_u_p_p_o_r_t_e_d

				  -2


  #define

	    _X_C_o_n_v_e_r_t_e_r_N_o_t_F_o_u_n_d

				  -3

  typedef enum {
	  XStringStyle,		  /* STRING */
	  XCompoundTextStyle,	  /* COMPOUND_TEXT */
	  XTextStyle,		  /* text in owner's encoding (current locale) */
	  XStdICCTextStyle	  /* STRING, else COMPOUND_TEXT	*/
  } 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








