Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XmbTextListToTextProperty(3)	XLIB FUNCTIONS	  XmbTextListToTextProperty(3)

NAME
       XmbTextListToTextProperty,  XwcTextListToTextProperty, Xutf8TextListTo-
       TextProperty,   XmbTextPropertyToTextList,   XwcTextPropertyToTextList,
       Xutf8TextPropertyToTextList,  XwcFreeStringList,	 XDefaultString	- con-
       vert text lists and text	property structures

SYNTAX
       int XmbTextListToTextProperty(Display *display, char **list, int	count,
	      XICCEncodingStyle	style, XTextProperty *text_prop_return);

       int  XwcTextListToTextProperty(Display  *display,  wchar_t  **list, int
	      count,  XICCEncodingStyle	 style,	 XTextProperty	*text_prop_re-
	      turn);

       int  Xutf8TextListToTextProperty(Display	 *display,  char  **list,  int
	      count,  XICCEncodingStyle	 style,	 XTextProperty	*text_prop_re-
	      turn);

       int  XmbTextPropertyToTextList(Display  *display, _Xconst XTextProperty
	      *text_prop, char ***list_return, int *count_return);

       int XwcTextPropertyToTextList(Display *display,	_Xconst	 XTextProperty
	      *text_prop, wchar_t ***list_return, int *count_return);

       int Xutf8TextPropertyToTextList(Display *display, _Xconst XTextProperty
	      *text_prop, char ***list_return, int *count_return);

       void XwcFreeStringList(wchar_t **list);

       char *XDefaultString(void)

ARGUMENTS
       display	 Specifies the connection to the X server.

       list	 Specifies a list of null-terminated character strings.

       count	 Specifies the number of strings specified.

       style	 Specifies the manner in which the property is encoded.

       text_prop_return
		 Returns the XTextProperty structure.

       text_prop Specifies the XTextProperty structure to be used.

       list_return
		 Returns a list	of null-terminated character strings.

       count_return
		 Returns the number of strings.

       list	 Specifies the list of strings to be freed.

DESCRIPTION
       The    XmbTextListToTextProperty,     XwcTextListToTextProperty	   and
       Xutf8TextListToTextProperty  functions  set the specified XTextProperty
       value to	a set of null-separated	elements representing  the  concatena-
       tion  of	the specified list of null-terminated text strings.  The input
       text strings must be given in the current  locale  encoding  (for  Xmb-
       TextListToTextProperty  and XwcTextListToTextProperty), or in UTF-8 en-
       coding (for Xutf8TextListToTextProperty).

       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 XStringStyle or
       XCompoundTextStyle is specified,	this encoding  is  "STRING"  or	 "COM-
       POUND_TEXT", respectively.  If the style	XUTF8StringStyle 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 in-
       dicated by the macro X_HAVE_UTF8_STRING.)  If the style	XTextStyle  is
       specified, this encoding	is the encoding	of the current locale.	If the
       style XStdICCTextStyle 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 func-
       tions return XNoMemory.	If the current locale is  not  supported,  the
       functions  return  XLocaleNotSupported.	 In both of these error	cases,
       the functions do	not set	text_prop_return.

       To determine if the functions are guaranteed not	to return  XLocaleNot-
       Supported, use XSupportsLocale.

       If  the	supplied text is not fully convertible to the specified	encod-
       ing, 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 Suc-
       cess.   Note that full convertibility to	all styles except XStringStyle
       is guaranteed.

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

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

       Multiple	elements of the	property (for example, the strings in  a  dis-
       joint  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, Xmb-
       TextPropertyToTextList, XwcTextPropertyToTextList and  Xutf8TextProper-
       tyToTextList return XNoMemory.  If the current locale is	not supported,
       the functions return XLocaleNotSupported.  Otherwise, if	 the  encoding
       field  of  text_prop  is	not convertible	to the encoding	of the current
       locale, the functions return  XConverterNotFound.   For	supported  lo-
       cales, 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 the actual text may contain
       unconvertible characters).  Conversion of other encodings is  implemen-
       tation-dependent.   In  all  of these error cases, the functions	do not
       set any return values.

       Otherwise,  XmbTextPropertyToTextList,  XwcTextPropertyToTextList   and
       Xutf8TextPropertyToTextList  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	encod-
       ing  of	the  current locale, the functions return the number of	uncon-
       vertible	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  XDefaultString.   Otherwise,
       XmbTextPropertyToTextList, XwcTextPropertyToTextList and	Xutf8TextProp-
       ertyToTextList return Success.

       To free the storage for the list	and  its  contents  returned  by  Xmb-
       TextPropertyToTextList	   or	  Xutf8TextPropertyToTextList,	   use
       XFreeStringList.	 To free the storage for the list and its contents re-
       turned by XwcTextPropertyToTextList, use	XwcFreeStringList.

       The XwcFreeStringList function frees memory allocated by	XwcTextProper-
       tyToTextList.

       The XDefaultString function returns the default string used by Xlib for
       text  conversion	 (for example, in XmbTextPropertyToTextList).  The de-
       fault 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 XDefaultString is the empty string (""),  no	 character  is
       output in the converted text.  XDefaultString does not return NULL.

       The  string  returned  by  XDefaultString is independent	of the default
       string for text drawing;	 see  XCreateFontSet  to  obtain  the  default
       string for an XFontSet.

       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 cur-
       rent locale is changed.	Until freed, it	will not be modified by	Xlib.

       The  functions  Xutf8TextListToTextProperty  and	  Xutf8TextPropertyTo-
       TextList	 are  extensions  introduced  by The XFree86 Project, Inc., in
       their  4.0.2  release.	Their  presence	 is  indicated	by  the	 macro
       X_HAVE_UTF8_STRING.

STRUCTURES
       The XTextProperty 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 XICCEncodingStyle structure contains:

       #de-    XNoMemory	      -1
       fine
       #de-    XLocaleNotSupported    -2
       fine
       #de-    XConverterNotFound     -3
       fine
       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(3), XStringListToTextProperty(3)
       Xlib - C	Language X Interface

X Version 11			 libX11	1.6.12	  XmbTextListToTextProperty(3)

NAME | SYNTAX | ARGUMENTS | DESCRIPTION | STRUCTURES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XmbTextListToTextProperty&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help