Xlib Changes for Internationalization:
X Locale Management
and
Localized Text Drawing
Public Review Draft - November, 1990
(Send comments to i18n@expo.lcs.mit.edu)
Glenn Widener
Tektronix, Inc.
Copyright 1990 by Tektronix, Inc., and the Massachusetts Institute of
Technology.
Permission to use, copy, modify, and distribute this documentation for
any purpose and without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
Tektronix and MIT make no representations about the suitability for any
purpose of the information in this document. It is provided "as is"
without express or implied warranty. This document is only a draft
standard of the MIT X Consortium and is therefore subject to change.
Table of Contents
1. Introduction (mostly in the XIM document for now)
2. Glossary
3. Managing a Localized X Client
3.1. X Locale Management
3.1.1. Locale and X Modifier Announcement
3.1.2. Locale and X Modifier usage by Xlib functions
3.2. Basic X Locale Functions
3.2.1. Validating X Locale Support
o XSupportsLocale
3.2.2. Setting the X Locale Modifiers
o XSetLocaleModifiers
3.3. X Resource Primitive Functions
3.3.1 Utilities for Managing Localized Resource Databases
o XrmSetDatabase
o XrmGetDatabase
o XrmLocaleOfDatabase
3.3.2. Respecification of Existing Xrm Primitive Functions
o XrmStringToQuark
o XrmStringToQuarkList
o XrmStringToBindingQuarkList
o XrmQuarkToString
o XrmGetFileDatabase
o XrmGetStringDatabase
o XrmPutLineResource
o XrmPutFileDatabase
o XrmPutResource
o XrmQPutResource
o XrmPutStringResource
o XrmQPutStringResource
o XrmGetResource
o XrmMergeDatabases
o XResourceManagerString
o XrmParseCommand
o XGetDefault
3.4. Setting Localized Window Manager and Text Properties
3.4.1. WM Property Convenience Function
o XmbSetWMProperties
3.4.2. Utilities for Conversion of Localized Text to/from an XTextProperty
o XStringListToTextProperty
o XTextPropertyToStringList
o Xmb/wcTextListToTextProperty
o Xmb/wcTextPropertyToTextList
o XDefaultString
3.5. Finding Locale-Specific Files
o XFindFile
o XResolvePathname
3.6. String Encoding Changes to R4 Functions
3.6.1. Draw Functions
o XDrawImageString
o XDrawString
o XQueryTextExtents
o XTextExtents
o XTextWidth
o XTextItem
o XChar2b
3.6.2. Display Functions
o XServerVendor
o XOpenDisplay
o XDisplayName
o XDisplayString
3.6.3. Color Functions
o XAllocNamedColor
o XLookupColor
o XStoreNamedColor
o XParseColor
3.6.4. Font Functions
o XLoadFont
o XLoadQueryFont
o XListFonts
o XListFontsWithInfo
o XSetFontPath
o XGetFontPath
3.6.5. Geometry Functions
o XParseGeometry
o XGeometry
o XWMGeometry
3.6.6. Atom Functions
o XInternAtom
o XGetAtomName
3.6.7. Keysym Functions
o XStringToKeysym
o XKeysymToString
3.6.8. Extension Functions
o XListExtensions
o XInitExtension
o XQueryExtension
3.6.9. Bitmap File Functions
o XReadBitmapFile
o XWriteBitmapFile
3.6.10. Cut Buffer Functions
o XStoreBytes
o XStoreBuffer
o XFetchBytes
o XFetchBuffer
3.6.11. Error Message Functions
o XGetErrorDatabaseText
o XGetErrorText
3.6.12. Window Manager Functions
o XSetWMProperties
o XSetStandardProperties
o XStoreName
o XSetIconName
o XSetCommand
o XSetClassHint
o XFetchName
o XGetIconName
o XGetCommand
o XGetClassHint
4. Internationalized Text Input (to be taken from the IM spec)
4.1. Obtaining a Localized String from the Keyboard
o XRebindKeysym
5. Internationalized Text Drawing
5.1. Creating and Freeing a Font Set
o XCreateFontSet
o XFreeFontSet
o XFreeStringList
5.2. Obtaining Text Drawing Information and Metrics
5.2.1. Obtaining Font Set Information
o XFontsOfFontSet
o XBaseFontNameListOfFontSet
o XLocaleOfFontSet
5.2.2. Obtaining Font Set Metrics
o XExtentsOfFontSet
5.2.3. Computing Character String Drawing Metrics
o Xmb/wcTextEscapement
o Xmb/wcTextExtents
o Xmb/wcTextPerCharExtents
5.2.4 Computing New Character Context Dependencies
o Xmb/wcComputeTextRedraw
5.3. Drawing Internationalized Text
o Xmb/wcDrawText
o Xmb/wcDrawString
o Xmb/wcDrawImageString
1. Introduction
The following specification defines a set of routines that are to be added
to Xlib for Release 5 to support development of internationalized X clients.
They support localized text imaging, localized text input, localized
resource file management, and the locale mechanism which controls all
locale-dependent Xlib functions.
This interface is designed to be upward compatible with R4 Xlib, although
client code must be modified to use the new routines to implement
internationalization.
(ed. note - the XIM introduction will be split between here and the
section 4, Internationalized Text Input.)
Many thanks to Tom McFarland and Bill McMahon of HP, who reviewed earlier
drafts of this proposal, and to Frank Rojas of IBM, for his multibyte text
drawing and X localedef proposals on which this proposal is based. Plus,
all the creative minds of the "mltalk" members who have contributed their
ideas to the goals, architecture, and design of international X, and their
cooperative efforts to put aside their own ideas in the interest of
gaining consensus on a core standard for X internationalization.
2. Glossary
The following terms are used in this specification. They are derived in
part from the ISO2022 and XPG3 specifications. Comma-separated terms are
synonymous.
base font name: a font name used to select a family of fonts whose
members may be encoded in various charsets. The CharSetRegistry and
CharSetEncoding fields of an XLFD name identify the charset of the font.
A base font name may be a full XLFD name, with all fourteen '-'
delimiters, or an abbreviated XLFD name containing only the first 13
fields of an XLFD name, up to but not including CharSetRegistry, with or
without the thirteenth '-'. Any XLFD fields may contain wild cards.
Otherwise, the base font name is treated as a non-XLFD name.
When creating an XFontSet, Xlib accepts from the client a list of one or
more base font names which select one or more font families. They are
combined with charset names obtained from the codeset of the locale to
load the fonts required to render text.
character: A member of a set of elements used for the organization,
control, or representation of text (ISO2022, as adapted by XPG3). Note
that in ISO2022 terms, a character is not bound to a coded value until it
is identified as part of a coded character set.
character glyph: the abstract graphical symbol for a character in a
codeset. Character glyphs may or may not map one-to-one to font glyphs,
and may be context-dependent, varying with the adjacent characters.
Multiple characters may map to a single character glyph.
character set: a collection of characters
charset: an encoding with a uniform, state-independent mapping from
characters to codepoints. In the ISO2022 framework, this means a coded
character set that does not use any shift sequences, i.e. is not a
compound encoding. An encoding which uses single shifts is
state-independent, but not "uniform".
For display in X there can be a direct mapping from a charset to one font,
if the width of all characters in the charset is either one or two octets.
A text string encoded in an encoding such as Shift-JIS cannot be passed
directly to the X server, because the text imaging requests accept only
single-width charsets (either 8 or 16 bits). Charsets which meet these
restrictions can serve as "font charsets" or "X charsets". Font charsets
strictly speaking map "font indices" to "font glyphs", not characters to
"character glyphs".
Note that a given font charset may also be used as a codeset, e.g.,
ISO8859-1. The distinction between codeset and font charset is primarily
based on the usage of the encoding.
In X, encodings (font charsets and codesets) are identified by a string
which appears as the CharSetRegistry-CharSetEncoding components of an XLFD
name, as the name of a charset of the locale for which a font could not be
found, or as an atom which identifies the encoding of a text property or
which names an encoding for a text selection target type. Encoding names
should be composed of characters from the X Portable Character Set.
coded character: a character bound to a codepoint.
coded character set: A set of unambiguous rules that establishes a
character set and the one-to-one relationship between each character of
the set and its bit representation. (ISO2022, as adapted by XPG3) A
definition of a one-to-one mapping of a set of characters to a set of
codepoints. Some encodings, such as Compound Text, have more than one
bit representation for a given character, and thus are not considered
coded character sets.
codepoint: the coded representation of a single character in a coded
character set.
codeset: a coded character set that is used to encode all the characters
in some locale.
codeset of the locale: the codeset used for processing text in the
locale. It is identified by a system-dependent name, which may be part of
the full locale name.
compound encoding: An encoding that supports a set of encodings which are
invoked at arbitrary positions in the text by a pre-defined invocation
syntax. Any ISO2022 encoding which uses shift sequences. Compound
encodings cannot be directly imaged using a single X font in current X
implementations. X Compound Text is an example of a compound encoding.
encoding: A set of unambiguous rules that establishes a character set and
a relationship between the characters and their bit representations. The
character set does not have to be fixed to a finite pre-defined set of
characters. Examples are an ISO2022 graphic set, a state-independent or
state-dependent combination of graphic sets, possibly including control
sets, and the X Compound Text encoding.
font glyph: the abstract graphical symbol for an index into a
font.
glyph, graphic symbol: An identified abstract graphical symbol
independent of any actual image. (ISO/IEC/DIS 9541-1) An abstract visual
representation of a graphic character (not bound to a codepoint).
glyph image: An image of a glyph, as obtained from a glyph representation
displayed on a presentation surface. (ISO/IEC/DIS 9541-1)
host: The operating system and execution environment in which the Xlib
functions are implemented and invoked.
Host Portable Character Encoding: the encoding of the X Portable Character
Set on the host. The encoding itself is not defined by this standard, but
the encoding must be the same in all locales supported by Xlib on the host.
If a string is said to be in the Host Portable Character Encoding, then it
only contains characters from the X Portable Character Set, in the host
encoding.
internationalization: The provision within a computer program of the
capability of making itself adaptable to the requirements of different
native languages, local customs and coded character sets. (XPG3) In
simpler, more practical terms, making a computer program adaptable to
different locales without program source modifications or recompilation.
ISO2022: ISO standard for code extension techniques for 7-bit and 8-bit
coded character sets.
Latin-1: The coded character set defined by ISO8859-1.
Latin Portable Character Encoding: the encoding of the X Portable Character
Set using the Latin-1 codepoints. If a string is said to be in the Latin
Portable Character Encoding, then it is in the Latin-1 encoding but only
contains characters from the X Portable Character Set.
locale: The international environment of a computer program defining the
"localized" behavior of that program at run-time. This information can be
established from one or more sets of localization data. (XPG3) A
definition of the processing characteristics of a specific locality:
language, territory, and codeset. An internationalized application
responds appropriately when the user changes the locale definition. ANSI
C defines locale-specific processing by C system library calls. See ANSI
C and the X/Open Portability Guide specifications for more details. In
this specification, on implementations that conform to the ANSI C library,
the "current locale" is the current setting of the LC_CTYPE setlocale
category. The current locale may affect Xlib in its:
- codeset of input text and input method
- selection of resource files to load
- the codeset of resource values
- imaging of text strings
- inter-client text communication
localization: the process of establishing information within a computer
system specific to the operation of particular native languages, local
customs and coded character sets. (XPG3)
locale name: the identifier used to select the desired locale for the
host C library and X library functions. On ANSI C library compliant
systems, the locale argument to the setlocale function.
multi-octet, multibyte: a character whose codepoint is stored in more
than one byte; any encoding which can contain multibyte characters; text
in a multibyte encoding. The "char *" NULL-terminated string datatype in
ANSI C. Note that references in this document to multibyte strings
imply only that the strings MAY contain multibyte characters.
octet: (ISO2022) an 8-bit value; a byte.
POSIX Portable Filename Character Set: The set of characters which can be
used in naming files on a POSIX-compliant host that are correctly processed
in all locales. The set is
a..z A..Z 0..9 ._-
shift sequence: ISO2022 defines control characters and escape sequences
which temporarily (single shift) or permanently (locking shift) cause a
different character set to be in effect ("invoking" a character set).
state-dependent encoding: A compound encoding in which invocation of an
charset spans multiple characters. A state-dependent encoding begins in
an "initial state" and enters other "shift states" when specific
"shift sequences" are encountered in the byte sequence (Multibyte Support
Extension). In ISO2022 terms, this means use of locking shifts, not
single shifts.
state-independent encoding: any encoding in which the invocations of the
charsets are fixed, or span only a single character (ISO2022
single-shifts).
STRING encoding: the Latin-1 encoding, plus tab and newline.
X Portable Character Set: A basic set of characters which must exist in all
locales supported by Xlib. This set contains the following characters:
a..z A..Z 0..9
!"%&'()*+,-./:;<=>?_
<space>, <tab>, and <newline>
This is the ISO646-invariant printable character set, plus <space>, <tab>,
and <newline>, or the set of printable characters in ASCII, plus <space>,
<tab>, and <newline>, minus the ISO646-variant characters:
#$@[\]^`{|}~
The encoding of these characters on the host is system dependent; see the
Host Portable Character Encoding.
XLFD: The X Logical Font Description Conventions that define a standard
syntax for structured font names.
whitespace: Any spacing character. On implementations that conform to the
ANSI C library, whitespace is any character for which isspace() returns
true.
References:
ANSI Draft Proposed C Standard: ANSI C X3J11/88-159, ANSI C X3J11 committee
(December 7, 1988).
"Draft Proposed Multibyte Extension of ANSI C, Draft 1.1, November 30,
1989 SC22/C WG/SWG IPSJ/ITSCJ Japan.
X/Open Portability Guide, Issue 3, December 1988 (XPG3), X/Open Company,
Ltd, xpg3@xopen.co.uk, Prentice-Hall, Inc. 1989. ISBN 0-13-685835-8.
(See especially Volume 3: XSI Supplementary Definitions)
IEEE Standard Portable Operating System Interface for Computer
Environments (POSIX), IEEE Std. 1003.1-1988, New York, New York:IEEE.
ISO2022: Information processing - ISO 7-bit and 8-bit coded character
sets - Code extension techniques
Text of ISO/IEC/DIS 9541-1, Information Processing - Font Information
Interchange - Part 1: Architecture
3. Managing a Localized X Client
The following routines support processing of single or multibyte and wide
character text encoded in the codeset of the current locale. There is a
variety of convenience and utility functions for initializing the locale,
for creating and using localized resource databases, storing and
retrieving localized text properties, interconverting text
representations, and retrieving locale-specific files.
On implementations that conform to the ANSI C library, the setlocale
function configures Xlib and the host C library to operate in the desired
locale. The XSetLocaleModifiers function configures Xlib locale modifiers
for the selected locale. Locale modifiers control locale-dependent Xlib
functions which can be configured in different ways for a given locale.
The primary defined use for this capability is selecting one of several
styles of keyboard input method.
The resource manager functions have been internationalized. A resource
database can contain localized text, and a localized resource database can
be associated with a display.
The XmbSetWMProperties convenience function stores the standard set of
window manager properties, with text properties encoded in the standard
codesets for internationalized text communication. Functions are provided
to convert localized text to/from an XTextProperty structure, for storing
and retrieving text properties.
The XResolvePathname function finds the first available file from a list
of filenames that is computed from a path and substitution strings.
Some substitution strings are obtained from the current locale.
3.1. X Locale Management
X supports a list of one or more of the system-defined languages, or
"locales", from which a client selects one or more locales. X is not
required to support all the locales supported by the host. To determine
if the current locale is supported by X, use the function
XSupportsLocale().
The client is responsible for selecting its locale and X modifiers.
Clients should provide a means for the user to override the clients'
locale selection at client invocation.
3.1.1. Locale and X Modifier Announcement
On implementations that conform to the ANSI C library, the recommended
procedure for clients initializing their locale and modifiers is to
separately obtain locale and modifier announcers from one of the following
prioritized sources, in order to pass them to the locale name argument of
setlocale(LC_ALL, "locale name"):
1) a command line option
2) a resource
3) the empty string ("")
The first of these that is defined should be passed to setlocale,
overriding subsequent announcers. Note that when a locale command line
option or locale resource is defined, the effect should be to set all
categories to the specified locale, overriding any category-specific
settings in the local host environment.
On implementations that do not conform to the ANSI C library, the
locale announcement method is Xlib implementation-dependent.
The mechanism by which the Xlib semantics of a locale are defined is
Xlib implementation-dependent.
3.1.2. Locale and X Modifier usage by Xlib functions
The internationalized Xlib functions operate in the current locale
configured by the host environment and X locale modifiers set by
XSetLocaleModifiers, or in the locale and modifiers configured at the time
some object supplied to the function was created. For each
locale-dependent function, the following table describes the locale (and
modifiers) dependency:
locale from... Affects the function... in the...
--------------------------------------------------------------------------
Locale Query/Configuration:
setlocale XSupportsLocale locale queried
XSetLocaleModifiers locale modified
Resources:
setlocale XrmGetFileDatabase locale of XrmDatabase
XrmGetStringDatabase
XrmDatabase XrmPutFileDatabase locale of XrmDatabase
XrmLocaleOfDatabase
Setting Standard Properties:
setlocale XmbSetWMProperties codeset of supplied/returned
text (some WM_ property
text in environment locale)
setlocale Xmb/wcTextPropertyToTextList codeset of supplied/returned
Xmb/wcTextListToTextProperty text
File Finding:
setlocale XResolvePathname path substitutions
Text Input:
setlocale XOpenIM XIM input method selection
XIM XCreateIC IC input method configuration
XLocaleOfIM, etc. queried locale
IC Xmb/wcLookupText keyboard layout,
codeset of returned text
Text Drawing:
setlocale XCreateFontSet charsets of fonts in XFontSet
XFontSet Xmb/wcDrawText, etc. locale of supplied text,
XExtentsOfFontSet, etc. locale-dependent metrics
Xmb/wcTextExtents, etc.
Xlib Errors:
setlocale XGetErrorDatabaseText locale of error message
XGetErrorText
Clients may assume that a locale-encoded text string returned by an X
routine can be passed to a C-library routine, or vice-versa, if the locale
is the same at the two calls.
All text strings processed by internationalized Xlib functions are assumed
to begin in the initial state of the codeset of the locale, if the codeset
is state-dependent.
All Xlib routines behave as if they do not change the current locale
or X modifier setting. (This means that if they do change locale or
call XSetLocaleModifiers with a non-NULL argument, they must save and
restore the current state on entry and exit.) Also, Xlib functions on
implementations that conform to the ANSI C library do not alter the
global state associated with the ANSI C functions mblen, mbtowc, wctomb,
and strtok.
The R4 Xlib specification defined many functions to deal with strings
strictly in the Latin-1 encoding. This was particularly true of strings
used to name things. In the revised specification, the general rule for
almost all such functions is that strings which consists entirely of
characters from the X Portable Character Set "work correctly", and the
semantics for other strings is implementation dependent. Details are
given throughout this document.
Release 4 Xlib applications are source and binary compatible and can be
relinked with the internationalized Xlib if they do not set the locale to any
value other than "C" when invoking Xlib functions, and either
they use (pass in to Xlib and receive from the X server) only characters
from the X Portable Character Set;
or
they use only 7-bit ASCII, and otherwise conform to the R4 specification,
and the codeset of the "C" locale is a superset of ASCII;
or
they use only Latin-1 plus ASCII control characters, and this matches the
codeset of the "C" locale.
If these conditions are not met, the application and the implementation-
dependent attributes of the Xlib implementation must be examined carefully to
determine the effects of relinking to the internationalized Xlib.
3.2. Basic Locale Functions
Most single-display X clients operate in a single locale for both X and
the host processing environment. They will configure the locale by
calling three functions: the host locale configuration function,
XSupportsLocale, and XSetLocaleModifiers.
On implementations that conform to the ANSI C library, the local host
locale configuration function is setlocale, and the "current locale" that
affects Xlib functions is the current setting of the LC_CTYPE setlocale
category.
3.2.1. Validating X Locale Support
To determine if X supports the current locale, use XSupportsLocale.
Bool XSupportsLocale()
This routine returns True if Xlib functions are capable of operating under
the current locale. If this routine returns False, Xlib locale-dependent
functions for which the LocaleNotSupported return status is defined will
return LocaleNotSupported. Other Xlib locale-dependent routines will
operate in the "C" locale.
3.2.2. Setting the X Locale Modifiers
To configure Xlib locale options for the current locale, use
XSetLocaleModifiers. The primary defined use for this capability is
selecting one of several styles of keyboard input method.
char *
XSetLocaleModifiers(modifier_list)
char *modifier_list;
This routine provides the X analog of the X/Open XPG3 locale category
modifier strings. Various sets of X internationalization capabilities,
each associated with a function or set of functions, can be configured by
setting the modifier for the associated category. Modifiers are Xlib
implementation-dependent and locale-specific strings.
XSetLocaleModifiers sets the X modifiers for the current locale setting.
Modifier_list is a NULL-terminated string of the form
"{@category=[value]}", that is, having one or more concatenated
"@category=value" entries. Category is a category name, and value is the
name of the setting for the category. The modifier_list is encoded in the
current locale. Category names are restricted to the POSIX Portable
Filename Character Set.
The local host X locale modifiers announcer (on POSIX-compliant systems,
the XMODIFIERS environment variable) is appended to the modifier_list to
provide default values on the local host. If a given category appears
more than once in the list, the first setting in the list is used. If a
given category is not included in the full modifier list, the category is
set to an implementation-dependent default for the current locale. An
empty value field explicitly specifies the implementation-dependent
default.
If the function is successful, it returns a pointer to a copy of
modifier_list. This string may be used in a subsequent call to
XSetLocaleModifiers to restore the modifiers. If modifier_list is a NULL
pointer, XSetLocaleModifiers returns a copy of the most recently supplied
modifier_list, and the current locale modifiers are not changed.
If any modifier selection is invalid, a NULL pointer is returned, and the
current modifiers are not changed.
The initial current locale modifier string prior to calling
XSetLocaleModifiers with a non-NULL modifier_list, or after setting the
locale but before calling XSetLocaleModifiers, is undefined. Clients
should always call XSetLocaleModifiers with a non-NULL modifier_list after
setting the locale, before they call any locale-dependent Xlib
routine.
The only standard modifier category currently defined is "im", which
identifies the desired input method. Multiple input methods may be
specified in a single im value string, in an implementation-dependent
manner. A single locale may use multiple input methods, switching input
method under user control. The modifier may specify the initial input
method in effect, or an ordered list of input methods.
The values for input method are not currently standardized. The X
Consortium will maintain and publish a register of modifier category names
and values; Xlib implementors are encouraged to register the categories
and values that they define.
The returned modifiers string is owned by Xlib and should not be modified
or freed by the client. It may be freed after the current locale or
modifiers is changed. Until freed, it will not be modified by Xlib.
3.3. X Resource Primitive Functions
The existing R4 Xlib resource manager functions are vague as to the
codeset of the function arguments. This section clarifies the behavior of
the existing functions, redefining many to process localized resource
values. Routines to associate a resource database with a display
and a routine to load resources from an opened file are added.
3.3.1. Utilities for Managing Localized Resource Databases
X provides the ability to associate a resource database with a display.
It is the client's responsibility to create a localized resource database
and associate it with the display. This database may be used by Xlib
functions such as XOpenInputMethod to obtain localized resource values.
To set the localized resource database of a display, use
XrmSetDatabase.
void
XrmSetDatabase(display, database)
Display *display;
XrmDatabase database;
The resource database of the specified display is set to the supplied
resource database. Clients should obtain their localized resources from
this database.
Any database previously associated with the display is not destroyed. The
database is set to NULL when the display is opened. If the database of
the display is set to NULL, Xlib functions which use the database of the
display operate as if they have an empty database.
To get the resource database of a display, use XrmGetDatabase.
XrmDatabase
XrmGetDatabase(display)
Display *display;
XrmGetDatabase returns the database associated with the specified
display. It returns NULL if the database has not yet been set.
The following routine obtains the locale name of an XrmDatabase:
char *
XrmLocaleOfDatabase(database)
XrmDatabase database; /* In: database */
This routine returns the name of the locale bound to the specified
XrmDatabase, as a NULL-terminated string.
The returned locale name string is owned by Xlib and should not be
modified or freed by the client. It may be freed by a call to
XrmDestroyDatabase with the associated XrmDatabase. Until freed, it will
not be modified by Xlib.
3.3.3. Respecification of Existing Xrm Primitive Functions
The following changes will be made to the specifications of these functions:
XrmStringToQuark, XrmStringToQuarkList, and XrmStringToBindingQuarkList:
The strings are assumed to be in the Host Portable Character Encoding.
Otherwise, the result is implementation dependent.
XrmQuarkToString: The returned string is byte-for-byte equal to the original
(sub)string passed to one of the string-to-quark routines.
XrmGetFileDatabase: The file is parsed in the current locale, and the
database is created in the current locale.
XrmGetStringDatabase: The string is parsed in the current locale, and the
database is created in the current locale.
XrmPutLineResource: The string is parsed in the locale of the database.
The ResourceName and colon are assumed to be in the Host Portable Character
Encoding. Otherwise, the result is implementation dependent.
XrmPutFileDatabase: The file is written in the locale of the database.
Entries containing resource names that are not in the Host Portable Character
Encoding, or containing values that are not in the codeset of the database
locale, are written in an implementation-dependent manner.
XrmPutResource: The specifier and type are assumed to be in the Host
Portable Character Encoding. Otherwise, the result is implementation
dependent. The value is stored without modification.
XrmQPutResource: The value is stored without modification.
XrmPutStringResource: The specifier is assumed to be in the Host Portable
Character Encoding. Otherwise, the result is implementation dependent.
The type is set to "String" (in the Host Portable Character Encoding). The
value is stored without modification.
XrmQPutStringResource: The type is set to "String" (in the Host Portable
Character Encoding). The value is stored without modification.
XrmGetResource: The name and class are assumed to be in the Host Portable
Character Encoding. Otherwise, the result is implementation dependent.
XrmMergeDatabases: The database entries are merged without changing values
or types, regardless of the locales of the databases. The locale of the
target database is not modified.
XResourceManagerString: The RESOURCE_MANAGER property is converted from
type STRING to the current locale. The conversion is identical to that
produced by XmbTextPropertyToTextList for a singleton STRING property.
The returned string is owned by Xlib, and should not be freed. For
maximum interoperability, the property should be in the Latin Portable
Character Encoding.
XrmParseCommand: The option specification strings in the table argument
are compared byte-for-byte to arguments in argv_in_out, independent of
any locale. The name argument and the resource specifier strings in the
table are assumed to be in the Host Portable Character Encoding. Otherwise,
the result is implementation dependent. The resource values given in the
table are stored in the resource database without modification. All
resource database entries are created with type "String" (in the Host
Portable Character Encoding). If a database is created, it is created in
the current locale.
XGetDefault: This function will be moved to an appendix, and deprecated.
If a database has been set with XrmSetDatabase, that database is used.
Otherwise, a database is created as described in the R4 Xlib specification,
and this is set in the display (as if by calling XrmSetDatabase). The
database is created in the current locale.
3.4. Setting Localized Window Manager and Text Properties
3.4.1. WM Property Convenience Function
Add to Xlib Section 9.1.13:
The XmbSetWMProperties function stores the standard set of window manager
properties, with text properties encoded in the standard codesets for
internationalized text communication.
void XmbSetWMProperties(display, w, window_name, icon_name, argc, argv,
normal_hints, wm_hints, class_hints)
Display *display;
Window w;
char *window_name;
char *icon_name;
int argc;
char *argv[];
XSizeHints *normal_hints;
XWMHints *wm_hints;
XClassHint *class_hints;
display Specifies the connection to the X server.
w Specifies the window.
window_name Specifies the window name, as a null-terminated string
in the codeset of the current locale.
icon_name Specifies the icon name, as a null-terminated string
in the codeset of the current locale.
argc Specifies a pointer to the number of command line
parameters.
argv Specifies the command line parameters, in the codeset
of the locale announced by the local host environment.
normal_hints Specifies the size hints for the window in its normal
state.
wm_hints Specifies the XWMHints structure to be used.
class_hints Specifies the XClassHint structure to be used, which
contains the client resource name and resource class.
The XmbSetWMProperties convenience function provides a simple
programming interface for setting those essential window properties that
are used for communicating with other clients (particularly window and
session managers).
If the window_name argument is non-null, XmbSetWMProperties sets the
WM_NAME property. If the icon_name argument is non-null,
XmbSetWMProperties sets the WM_ICON_NAME property. The window_name and
icon_name arguments are NULL-terminated strings in the codeset of the
current locale. If the arguments can be fully converted to the STRING
encoding, the properties are created with type "STRING", otherwise, the
arguments are converted to Compound Text, and the properties are created
with type "COMPOUND_TEXT".
If the normal_hints argument is non-null, XmbSetWMProperties calls
XSetWMNormalHints, which sets the WM_NORMAL_HINTS property (see section
9.1.7). If the wm_hints argument is non-null, XmbSetWMProperties calls
XSetWMHints, which sets the WM_HINTS property (see section 9.1.6).
If the argv argument is non-null, XmbSetWMProperties sets the WM_COMMAND
property from argv and argc. Note that an argc of 0 indicates a
zero-length command.
The hostname of this machine is stored using XSetWMClientMachine (see
section 9.2.2).
If the class_hints argument is non-null, XmbSetWMProperties sets the
WM_CLASS property. If the res_name member in the XClassHint structure is
set to the null pointer and the RESOURCE_NAME environment variable is set,
the value of the environment variable is substituted for res_name. If the
res_name member is null, the environment variable is not set, and argv and
argv[0] are set, then the value of argv[0], stripped of any directory
prefixes, is substituted for res_name.
It is assumed that the supplied class_hints.res_name and argv, the
RESOURCE_NAME environment variable, and the hostname of this machine are
encoded in the codeset of the locale announced for the LC_CTYPE
category (On POSIX-compliant systems, the LC_CTYPE, else LANG environment
variable). The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE
properties are typed as the X codeset of the local host locale announcer.
No codeset conversion is performed prior to storage in the properties.
For clients that need to process the property text in a locale,
XmbSetWMProperties sets the WM_LOCALE_NAME property to be the name of the
current locale. The name is assumed to be in the Host Portable Character
Encoding, and is converted to STRING for storage in the property.
XmbSetWMProperties can generate BadAlloc and BadWindow errors.
3.4.2. Utilities for Conversion of Localized Text to/from an XTextProperty
Add to Xlib Section 9.1.2, Converting String and Text Lists:
Xlib provides functions that you can use to convert between XTextProperty
structures and lists of pointers to localized strings. These functions
convert the localized text to or from encodings which support the
inter-client communication conventions for text.
Clients are encouraged to replace use of XStringListToTextProperty and
XTextPropertyToStringList with the new functions XmbTextListToTextProperty
and XmbTextPropertyToTextList. XStringListToTextProperty and
XTextPropertyToStringList only support communication of STRING text.
XStringListToTextProperty does not verify that the supplied text is in the
STRING encoding.
Correction to XGetTextProperty:
...It stores the data in the value field, the type of data in the encoding
field, the format of the data in the format field, and the number of items
in the nitems field. /+ An extra byte containing NULL (which is not
included in the nitems member) is stored at the end of the value field of
text_prop_return. +/
New Functions
Xlib codeset conversion functions return a signed
integer error status which encodes Success as zero, specific error
conditions as negative numbers, and partial conversion or font
availability as a count of unconvertible characters or unavailable fonts.
#define Success 0
#define NoMemory -1
#define LocaleNotSupported -2
#define ConverterNotFound -3
typedef enum {
String, /* STRING */
CompoundText, /* COMPOUND_TEXT */
Text, /* text in owner's encoding (current locale) */
StdICCText /* STRING, else COMPOUND_TEXT */
} XICCEncodingStyle;
To convert a list of text strings to an XTextProperty structure, use
XmbTextListToTextProperty or XwcTextListToTextProperty.
int
XmbTextListToTextProperty(display, list, count, style, text_prop_return)
Display *display;
char **list;
int count;
enum XICCEncodingStyle style;
XTextProperty *text_prop_return;
int
XwcTextListToTextProperty(display, list, count, style, text_prop_return)
Display *display;
wchar_t **list;
int count;
enum XICCEncodingStyle style;
XTextProperty *text_prop_return;
list Specifies a list of null-terminated text strings.
count Specifies the number of text strings.
style Specifies the manner in which the property is encoded.
text_prop_return Returns the XTextProperty structure.
These functions set the specified XTextProperty 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 String or CompoundText is
specified, this encoding is "STRING" or "COMPOUND_TEXT", respectively. If
the style Text is specified, this encoding is the codeset of the current
locale. If the style StdICCText 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 NoMemory. If the current locale is not supported, the
functions return LocaleNotSupported. In both of these error cases, the
functions do not set text_prop_return.
Use XSupportsLocale() to determine if the functions are guaranteed not to
return LocaleNotSupported.
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
Success. Note that full convertibility to all styles except String is
guaranteed.
To free the storage for the value field, use XFree.
To obtain a list of text strings from an XTextProperty structure, use
XmbTextPropertyToTextList or XwcTextPropertyToTextList.
int
XmbTextPropertyToTextList(display, text_prop, list_return, count_return)
Display *display;
XTextProperty *text_prop;
char ***list_return;
int *count_return;
int
XwcTextPropertyToTextList(display, text_prop, list_return, count_return)
Display *display;
XTextProperty *text_prop;
wchar_t ***list_return;
int *count_return;
text_prop Specifies the XTextProperty structure to be used.
list_return Returns a list of null-terminated text strings.
count_return Returns the number of text strings.
The XmbTextPropertyToTextList and XwcTextPropertyToTextList functions
return a list of text strings in the current locale representing the
null-separated elements of the specified XTextProperty 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 (encoding 0). 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,
XmbTextPropertyToTextList and XwcTextPropertyToTextList return NoMemory.
If the current locale is not supported, the functions return
LocaleNotSupported. Otherwise, if the encoding field of text_prop is not
convertible to the codeset of the current locale, the functions return
ConverterNotFound. For supported locales, existence of a converter from
COMPOUND_TEXT, STRING, or the codeset 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 implementation-dependent. In all of these error cases, the functions
do not set any return values.
Otherwise, XmbTextPropertyToTextList and XwcTextPropertyToTextList 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 codeset 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. See
XDefaultString() to obtain the value of this string. Otherwise,
XmbTextPropertyToTextList and XwcTextPropertyToTextList return Success.
To free the storage for the list and its contents, use XFreeStringList.
The following routine obtains the default string for text conversion in the
current locale:
char *
XDefaultString()
This routine returns the default string used by Xlib for codeset
conversion (e.g. in XmbTextListToTextProperty). The default string is
the string in the current locale which is output when an unconvertible
character is found during codeset 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 current
locale is changed. Until freed, it will not be modified by Xlib.
3.5. Finding Locale-Specific Files
[The following functions are intended to match the Xt functions XtFindFile
and XtResolvePathname.]
Xlib provides procedures to look for a file by name using string
substitutions in a list of file specifications. There are two routines
provided: XFindFile and XResolvePathname. XFindFile uses an arbitrary set
of client-specified substitutions and XResolvePathname uses a set of
standard substitutions corresponding to the X/Open Portability Guide
language localization conventions. Most applications should use
XResolvePathname.
A string substitution is defined by a list of Substitution entries.
typedef struct {
char match;
char *substitution;
} XSubstitution;
File name evaluation is handled in an operating-system dependent fashion
by a predicate:
typedef Bool (*predicate)(char *);
char *filename;
filename Specifies a potential filename.
A file predicate procedure will be called with a string that is
potentially a file name. It should return True if this string specifies a
file that is appropriate for the intended use and False otherwise.
To search for a file using substitutions in a path list, use XFindFile.
char *XFindFile(path, substitutions, num_substitutions, predicate)
char *path;
XSubstitution *substitutions;
int num_substitutions;
Bool (*predicate)(char *);
path Specifies a path of file names including
substitution characters.
substitutions Specifies a list of substitutions to make into the path.
num_substitutions Specifies the number of substitutions passed in.
predicate Specifies a procedure called to judge each
potential file name.
The path parameter specifies a string that consists of a series of
potential file names separated by colons. Within each name, the percent
character specifies a string substitution controlled by the following
character. The character sequence "%:" specifies a colon that is not a
separator; the sequence is replaced by a single colon. The character
sequence "%%" specifies a percent character that does not introduce a
substitution; the sequence is replaced by a single percent character. If
a percent character is followed by any other character, XFindFile looks
through the specified substitutions from first to last for that character
in the match field and if found replaces the percent and match characters
with the string in the corresponding substitution field. The path is
scanned left-to-right, however each file in the path is scanned
right-to-left for substitutions. If a substitution is not defined, it is
removed from the path. A substitution string entry of NULL is equivalent
to a pointer to an empty string.
On a host which has a single homogeneous filename syntax, and which does
not interpret consecutive embedded name separators in the path (i.e. "/"
in POSIX) the same way as a single separator, XFindFile will collapse
consecutive separators into a single separator after performing all string
substitutions.
For a path or substitution string argument to XFindFile to be portable
across POSIX-compliant systems, it should consist only of characters from
the POSIX portable filename character set, plus slash and percent sign,
encoded in the Host Portable Character Encoding. The treatment of other
characters on POSIX-compliant systems and the encoding of these arguments
for non-POSIX-compliant systems are not defined in this specification.
Each resulting string is passed to the predicate procedure until a string
is found for which the procedure returns True; this string is the return
value for XFindFile. If no string yields a True return from the predicate,
XFindFile returns NULL as a value.
If the predicate parameter is NULL, an internal procedure that checks if
the file exists, is readable, and (on POSIX-compliant systems) is not a
directory will be used.
It is the responsibility of the client to free the returned string using
XFree when it is no longer needed.
To search for a file using standard substitutions in a path list, use
XResolvePathname.
char *XResolvePathname(display, type, filename, suffix, path,
substitutions, num_substitutions, predicate)
Display *display;
char *type, *filename, *suffix, *path;
XSubstitution *substitutions;
int num_substitutions;
Bool (*predicate)(char *);
display Specifies the display to use to find the language
for language substitutions.
type Specify values to substitute into the path, or NULL
filename
suffix
path Specifies the path of file specifications, or NULL.
substitutions Specifies a list of additional substitutions
to make into the path, or NULL.
num_substitutions Specifies the number of entries in substitutions.
predicate Specifies a procedure called to judge each potential
file name, or NULL.
XResolvePathname calls XFindFile with the following substitutions in
addition to any passed by the client and returns the value returned by
XFindFile:
%N The value of the filename parameter.
%T The value of the type parameter.
%S The value of the suffix parameter.
%L The current locale name.
%l The language part of the current locale name.
%t The territory part of the current locale name, if any, else null.
%c The codeset part of the current locale name, if any, else null.
The %L, %l, %t, and %c substitutions specified by XResolvePathname are
determined from the value of the current locale name. On implementations
that conform to the ANSI C library, this is the locale name for the
LC_CTYPE category, minus any modifiers. Xlib obtains this string in an
implementation-dependent manner.
The manner in which the locale name is parsed to obtain substitution
strings for %l, %t, and %c is implementation-dependent. No interpretation
of the parts of the locale name is done other than to use them in
substitutions. On many systems, a locale name is specified in four parts:
three of which are optional: the language, the territory, the codeset,
and, for individual categories, category-specific modifiers. These parts
are combined into a single string as
language[_territory[.codeset]][@modifier]; the parts consist of arbitrary
strings of "C" locale letters and numbers. The modifier, if any, is
ignored.
On implementations that conform to the ANSI C library, if the current
locale is "C", the null string is used by XResolvePathname for the %L, %l,
%t, and %c substitutions used to construct file paths.
The type parameter is intended to be a category of files, usually being
translated into a directory in the pathname. Possible values might
include "app-defaults", "help", and "bitmaps".
The filename parameter is the name of the file.
The suffix parameter is intended to be appended to the file name.
Possible values might include ".txt", ".dat", and ".bm".
If type, filename, or suffix is NULL, the empty string is used.
If a path is passed to XResolvePathname it will be passed along to
XFindFile. If path is NULL, the value of the XFILESEARCHPATH environment
variable will be passed to XFindFile. If XFILESEARCHPATH is not defined,
an implementation-dependent default path will be passed which on
POSIX-compliant systems contains at least /usr/lib/X11/%T/%N%S.
If the path begins with a colon, it will be preceded by %N%S. If the path
includes two adjacent colons, %N%S will be inserted between them.
A suggested value for the default path on POSIX-based systems is
/usr/lib/X11/%L/%T/%N%S:/usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S
Using this example, if the user has specified a language, it will be used
as a subdirectory of /usr/lib/X11 that will be searched for other files.
If the desired file is not found there, the lookup will be tried again using
just the language part of the locale name. If the file is not there it will
be looked for in /usr/lib/X11. The type parameter is used as a subdirectory
of the language directory or of /usr/lib/X11, and the suffix is appended to
the file name.
It is the responsibility of the client to free the returned string using
XFree when it is no longer needed.
3.6. String Encoding Changes to R4 Functions
3.6.1. Draw Functions
The string encoding used in draw functions remain unchanged:
XDrawImageString, XDrawString, XQueryTextExtents, XTextExtents, and
XTextWidth: The "character" data in the "strings" is always treated as
glyph indexes, independent of locale.
XTextItem, XChar2b: The "character" data in these structures is always
treated as glyph indexes, independent of locale.
3.6.2. Display Functions
The string encoding used in display functions has been changed as follows:
XServerVendor: A single string is returned, independent of locale. If the
data returned by the server is in the Latin Portable Character Encoding, then
the string is in the Host Portable Character Encoding. Otherwise, the
contents of the string are implementation dependent.
XOpenDisplay, XDisplayName, and XDisplayString: The encoding and
interpretation of the strings is implementation-dependent. Strings in
the Host Portable Character Encoding are supported; support for other
characters is implementation dependent.
3.6.3. Color Functions
The string encoding used in color functions has been changed as follows:
XAllocNamedColor, XLookupColor, XStoreNamedColor, and XParseColor: The color
name is assumed to be in the Host Portable Character Encoding. Otherwise,
the result is implementation dependent. Xlib is permitted, but not required,
to lookup the color name in a global or locale-specific database, in order
to translate it into a color name or value suitable to send to the X server.
3.6.4. Font Functions
The string encoding used in font functions has been changed as follows:
XLoadFont and XLoadQueryFont: The font name is assumed to be in the Host
Portable Character Encoding. Otherwise, the result is implementation
dependent.
XListFonts and XListFontsWithInfo: The font pattern is assumed to be in the
Host Portable Character Encoding. Otherwise, the result is implementation
dependent. If the data returned by the server is in the Latin Portable
Character Encoding, then the returned strings are in the Host Portable
Character Encoding. Otherwise, the result is implementation dependent.
XSetFontPath and XGetFontPath: The encoding and interpretation of the
strings is implementation dependent.
3.6.5. Geometry Functions
The string encoding used in geometry functions has been changed as follows:
XParseGeometry, XGeometry, and XWMGeometry: The geometry strings are assumed
to be in the Host Portable Character Encoding. Otherwise, the result is
implementation dependent.
3.6.6. Atom Functions
The string encoding used in atom functions has been changed as follows:
XInternAtom: The atom name is assumed to be in the Host Portable Character
Encoding. Otherwise, the result is implementation dependent.
XGetAtomName: If the data returned by the server is in the Latin Portable
Character Encoding, then the returned string is in the Host Portable
Character Encoding. Otherwise, the result is implementation dependent.
3.6.7. Keysym Functions
The string encoding used in keysym functions has been changed as follows:
XStringToKeysym: The keysym name is assumed to be in the Host Portable
Character Encoding. Otherwise, the result is implementation dependent.
XKeysymToString: The returned string is in the Host Portable Character
Encoding.
3.6.8. Extension Functions
The string encoding used in extension functions has been changed as follows:
XListExtensions: If the data returned by the server is in the Latin Portable
Character Encoding, then the returned strings are in the Host Portable
Character Encoding. Otherwise, the result is implementation dependent.
XInitExtension and XQueryExtension: The extension name is assumed to be
in the Host Portable Character Encoding. Otherwise, the result is
implementation dependent.
3.6.9. Bitmap File Functions
The string encoding used in bitmap file functions has been changed as
follows:
XReadBitmapFile: The file is parsed in the encoding of the current locale.
XWriteBitmapFile: The file is written in the encoding of the current locale.
3.6.10. Cut Buffer Functions
The string encoding used in cut buffer functions has been changed as follows:
XFetchBytes, XFetchBuffer, XStoreBytes, and XStoreBuffer: The data is
treated as uninterpreted bytes, no conversions are performed. The property
type STRING continues to be used.
3.6.11. Error Functions
The string encoding used in error functions has been changed as follows:
XGetErrorDatabaseText: The name and message are assumed to be in the Host
Portable Character Encoding. Otherwise, the result is implementation
dependent. The default_string is assumed to be in the current locale. The
buffer_return text is in the current locale.
XGetErrorText: The buffer_return text is in the current locale. The source
of the text is implementation dependent, there is no requirement to use
the database /usr/lib/X11/XErrorDB on POSIX-conformant systems.
3.6.12. Window Manager Functions
The string encoding used in window manager functions has been changed as
follows:
XSetWMProperties, XSetStandardProperties, XStoreName, XSetIconName,
XSetCommand, and XSetClassHint: The strings are assumed to be in the Host
Portable Character Encoding, and are used to create properties of type
STRING. Otherwise, the result is implementation dependent.
XFetchName, XGetIconName, XGetCommand, XGetClassHint: If the data returned
by the server is in the Latin Portable Character Encoding, then the returned
strings are in the Host Portable Character Encoding. Otherwise, the result
is implementation dependent.
4. Internationalized Text Input
(ed. note: Most of this section is in the Input Method Specifications, by
Vania Joloboff, and will incorporated here when the specifications are
merged.)
4.1. Obtaining a Localized String from the Keyboard
The R4 Xlib specification does not specify the encoding of the string
argument to XRebindKeysym. This will be changed as follows:
XLookupString will return this string when the appropriate set of modifier
keys are pressed and when the KeySym would have been used for the
translation. /+ No codeset conversions are performed; the client is
responsible for supplying Latin-1 strings, compatible with XLookupString. +/
XRebindKeysym and XLookupString will be moved to an appendix, and deprecated.
5. Internationalized Text Drawing
The following routines support drawing of text in a locale-based
environment. The supplied text may be in multibyte or wchar_t form.
All text strings processed by internationalized Xlib functions are assumed
to begin in the initial state of the codeset of the locale, if the codeset
is state-dependent.
Xwc and Xmb are equivalent except for the form of the text argument. Xmb
functions take char * multibyte text. Xwc functions take wchar_t text in
the form supported by the host C language environment.
5.1. Creating and Freeing a Font Set
Xlib international text drawing is done using a set of one or more fonts,
as needed for the locale of the text. Fonts are loaded according to a
list of base font names supplied by the client, and the charsets required
by the locale. The XFontSet is an opaque type.
To create an international text drawing font set, use XCreateFontSet.
XFontSet
XCreateFontSet(display, base_font_name_list, missing_charset_list,
missing_charset_count, def_string)
Display *display;
char *base_font_name_list; /* In: base font name list */
char **missing_charset_list; /* Out: names of missing charsets */
int *missing_charset_count; /* Out: number of missing charsets */
char **def_string; /* Out: drawn for missing charset */
This routine creates a font set for the specified display. The font set
is bound to the current locale when XCreateFontSet is called. The
font_set may be used in subsequent calls to obtain font and character
information, and to image text in the locale of the font_set.
Base_font_name_list is a list of base font names which Xlib uses to load
the fonts needed for the locale. The base font names are a
comma-separated and NULL-terminated list. The string is assumed to be in the
Host Portable Character Encoding, otherwise the result is implementation
dependent. Whitespace immediately on either side of a separating comma
is ignored.
Use of XLFD font names permits Xlib to obtain the fonts needed for a
variety of locales from a single locale-independent base font name. The
single base font name should name a family of fonts whose members are
encoded in the various charsets needed by the locales of interest.
An XLFD base font name can explicitly name a charset needed for the
locale. This allows the user to specify an exact font for use with a
charset required by a locale, fully controlling the font selection.
If a base font name is not an XLFD name, Xlib will attempt to obtain an
XLFD name from the font properties for the font specified by the base
name, replacing the CharSetRegistry-CharSetEncoding fields with wild
cards. If this action is successful in obtaining an XLFD name, the
XBaseFontNameListOfFontSet function will return this XLFD name instead of
the client-supplied name.
The following algorithm is used to select the fonts that will be used to
display text with the XFontSet:
For each X charset required by the locale, the base font name list is
searched for the first one of the following cases that names a set of
fonts that exist at the server:
1) The first XLFD-conforming base font name that specifies the required
charset or a superset of the required charset in its CharSetRegistry
and CharSetEncoding fields. The implementation may use a base font
name whose specified charset is a superset of the required charset,
for example, an ISO8859-1 font for an ASCII charset.
2) The first set of one or more XLFD-conforming base font names that
specify one or more charsets that can be remapped to support the
required charset. The Xlib implementation may recognize various
mappings from a required charset to one or more other charsets, and
use the fonts for those charsets. For example, JIS Roman is ASCII with
tilde and backslash replaced by yen and overbar; Xlib may load an
ISO8859-1 font to support this character set, if a JIS Roman font is
not available.
3) The first XLFD-conforming font name, or the first non-XLFD font name
for which an XLFD font name can be obtained, combined with the
required charset (replacing the CharSetRegistry and CharSetEncoding
fields in the XLFD font name). As in case 1), the implementation may
use a charset which is a superset of the required charset.
4) The first font name that can be mapped in some implementation-dependent
manner to one or more fonts that support imaging text in the
charset.
For example, assume a locale required the charsets:
ISO8859-1
JISX0208.1983
JISX0201.1976
GB2312-1980.0
The user could supply a base_font_name_list which explicitly specifies the
charsets, insuring that specific fonts get used if they exist:
"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\
-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
Or he could supply a base_font_name_list which omits the charsets, letting
Xlib select fonts for each required codeset:
"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
Or he could simply supply a single base font name which allows Xlib to
select from all available fonts which meet certain minimum XLFD property
requirements:
"-*-*-*-R-Normal--*-180-100-100-*-*"
If XCreateFontSet is unable to create the font set, either because there
is insufficient memory or because the current locale is not supported,
XmlCreateFontSet returns NULL, missing_charset_list is set to NULL, and
missing_charset_count is set to zero. If fonts exist for all of the
charsets required by the current locale, XCreateFontSet returns a valid
XFontSet, missing_charset_list is set to NULL, and missing_charset_count
is set to zero.
If no font exists for one or more of the required charsets,
XCreateFontSet returns to missing_charset_list a NULL-separated and
NULL-terminated list of one or more charset names for which no font
exists, and returns the number of missing fonts to missing_charset_count.
The charsets are from the list of the required charsets for
the codeset of the locale, and do not include any charsets to which Xlib
may be able to remap a required charset.
If no font exists for any of the required charsets, or if the locale
definition in Xlib requires that a font exist for a particular charset and
a font is not found for that charset, XCreateFontSet returns NULL.
Otherwise, XCreateFontSet returns a valid XFontSet to font_set.
When an Xmb/wc drawing or measuring function is called with an XFontSet
that has missing charsets, some characters in the locale will not be
drawable. If def_string is non-NULL, XCreateFontSet returns a pointer to
a string which represents the glyph(s) which are drawn with this XFontSet
when the charsets of the available fonts do not include all font glyph(s)
required to draw a codepoint. The string does not necessarily consist of
valid characters in the current locale, and is not necessarily drawn with
the fonts loaded for the font set, but the client can draw and measure the
"default glyphs" by including this string in a string being drawn or
measured with the XFontSet.
If the string returned to def_string is the empty string ("") no glyphs
are drawn, and the escapement is zero. The returned string is
NULL-terminated. It is owned by Xlib and should not be modified or freed
by the client. It will be freed by a call to XFreeFontSet with the
associated XFontSet. Until freed, its contents will not be modified by
Xlib.
The client is responsible for constructing an error message from the
missing charset and def_string information, and may choose to continue
operation in the case that some fonts did not exist.
The returned XFontSet and missing charset list should be freed with
XFreeFontSet and XFreeStringList. The client-supplied base_font_name_list
may be freed by the client after calling XCreateFontSet.
void
XFreeFontSet(display, font_set)
Display *display;
XFontSet font_set; /* In: font set to free */
This routine frees the specified font set. The associated base font name
list, font name list, XFontStruct list, and XFontSetExtents, if any, are
freed.
void
XFreeStringList(list)
char **list;
The XFreeStringList function frees memory allocated by
XTextPropertyToStringList /+, and the missing charset list allocated by
XCreateFontSet +/.
5.2. Obtaining Text Drawing Information and Metrics
The internationalized text drawing layers may use multiple fonts at the
server to image text in a given codeset. Xlib provides functions which
return information about the fonts that are used by the text drawing
layers. Information provided includes a list of the XFontStructs for the
fonts, an XFontSetExtents structure which contains overall metrics for all
the characters in all the fonts, the full names of the fonts, and the
locale name of the font set.
The client may need access to the base XLFD font names used to load
the fonts or the actual full names of the fonts, for error handling or
other purposes.
In order to obtain per-character information, functions are provided to
map each character in a string to the per-character metrics for the
effective character glyph that is drawn.
5.2.1. Obtaining Font Set Information
The following routine obtains a list of XFontStructs and full font names
given an XFontSet:
int
XFontsOfFontSet(display, font_set, font_struct_list, font_name_list)
Display *display;
XFontSet font_set; /* In: font set */
XFontStruct **font_struct_list; /* Out: list of font structs */
char **font_name_list; /* names of fonts */
This routine returns a list of one or more XFontStructs and font names for
the fonts used by the Xmb and Xwc layers, for the given font set. A list
of pointers to XFontStructs is returned to font_struct_list. A list of
pointers to NULL-terminated fully specified font name strings in the
locale of the font set is returned to font_name_list. The font_name_list
order corresponds to the font_struct_list order. The number of
XFontStructs and font names is returned as the value of the function.
Because it is not guaranteed that a given character will be imaged using a
single font glyph, there is no provision for mapping a character or
default string to the font properties, font ID, or direction hint for the
font for the character. The client may access the XFontStructSet to
obtain these values for all the fonts currently in use.
It is not required that fonts be loaded from the server at the creation of
an XFontSet. Xlib may choose to cache font data, loading it only as
needed to draw text or compute text dimensions. Therefore, existence of
the per_char metrics in the XFontStructs in the XFontStructSet is undefined.
Also, note that all properties in the XFontStructs are in the Latin-1
encoding.
The XFontStruct and font name lists are owned by Xlib and should not be
modified or freed by the client. They will be freed by a call to
XFreeFontSet with the associated XFontSet. Until freed, its contents will
not be modified by Xlib.
The following routines obtain the base font name list and the selected
font name list given an XFontSet:
char *
XBaseFontNameListOfFontSet(display, font_set)
Display *display;
XFontSet font_set; /* In: font set */
This routine returns the original base font name list supplied by the
client when the XFontSet was created. A NULL-terminated list of
comma-separated font names is returned as the value of the function.
If XCreateFontSet obtained an XLFD name from the font properties for the
font specified by a non-XLFD base name, the XBaseFontNameListOfFontSet
function will return the XLFD name instead of the non-XLFD base name.
The base font name list is owned by Xlib and should not be modified or
freed by the client. It will be freed by a call to XFreeFontSet with the
associated XFontSet. Until freed, its contents will not be modified by
Xlib.
The following routine obtains the locale name given an XFontSet:
char *
XLocaleOfFontSet(display, font_set)
Display *display;
XFontSet font_set; /* In: font set */
This routine returns the name of the locale bound to the specified
XFontSet, as a NULL-terminated string.
The returned locale name string is owned by Xlib and should not be
modified or freed by the client. It may be freed by a call to
XFreeFontSet with the associated XFontSet. Until freed, it will
not be modified by Xlib.
5.2.2. Obtaining Font Set Metrics
Metrics for the internationalized text drawing functions are defined in
terms of a primary draw direction, which is the default direction in which
the character origin advances for each succeeding character in the string.
The Xlib interface is currently defined to support only a left-to-right
primary draw direction. The drawing origin is the position passed to the
drawing function when the text is drawn. The baseline is a line drawn
through the drawing origin parallel to the primary draw direction.
Character ink is the pixels painted in the foreground color, and does not
include interline or intercharacter spacing or image text background
pixels.
The drawing functions are allowed to implement implicit text
directionality control, reversing the order in which characters are
rendered along the primary draw direction in response to locale-specific
lexical analysis of the string.
Regardless of the character rendering order, the origins of all characters
are on the primary draw direction side of the drawing origin. The screen
location of a particular character image may be determined with
Xmb/wcTextPerCharExtents.
The drawing functions are allowed to implement context-dependent
rendering, where the glyphs drawn for a string are not simply a
concatenation of the glyphs that represent each individual character. A
string of two characters drawn with XmbDrawString may render differently
than if the two characters were drawn with separate calls to
XmbDrawString. If the client appends or inserts a character in a
previously drawn string, the client may need to redraw some adjacent
characters in order to obtain proper rendering.
Clients may assume that there are no context dependencies before or after
a whitespace character, and may call XmbTextComputeTextRedraw to determine
if a given character is context-dependent.
The drawing functions do not interpret newline, tab, or other "cursor
positioning" characters. The behavior when non-printing characters other
than space are drawn is implementation-dependent. It is the client's
responsibility to interpret control characters in a text stream.
The maximum character extents for the fonts that are used by the text
drawing layers may be accessed by the XFontSetExtents structure:
typedef struct {
XRectangle max_ink_extent; /* over all drawable characters */
XRectangle max_logical_extent; /* over all drawable characters */
} XFontSetExtents;
The XRectangles used to return font set metrics are the usual Xlib
screen-oriented XRectangles, with x, y giving the upper left corner, and
width and height always positive.
Max_ink_extent gives the maximum extent, over all drawable characters, of
the rectangles which bound the character glyph image drawn in the
foreground color, relative to a constant origin. See Xmb/wcTextExtents
for detailed semantics.
Max_logical_extent gives the maximum extent, over all drawable characters,
of the rectangles which specify minimum spacing to other graphical
features, relative to a constant origin. Other graphical features drawn
by the client, for example, a border surrounding the text, should not
intersect this rectangle. Max_logical_extent should be used to compute
minimum inter-line spacing and the minimum area which must be allowed in a
text field to draw a given number of arbitrary characters.
Due to context-dependent rendering, appending a given character to a
string may increase the string's extent by an amount which exceeds the
font's max extent:
max possible added extent = (max_extent * <total # chars>) - prev_string_extent
The rectangles for a given character in a string can be obtained from
Xmb/wcPerCharExtents.
The following routine obtains the maximum extents structure given an
XFontSet:
XFontSetExtents *
XExtentsOfFontSet(display, font_set)
Display *display;
XFontSet font_set; /* In: font set */
This routine returns an XFontSetExtents structure for the fonts used by the
Xmb and Xwc layers, for the given font set.
The XFontSetExtents structure is owned by Xlib and should not be modified
or freed by the client. It will be freed by a call to XFreeFontSet with
the associated XFontSet. Until freed, its contents will not be modified by
Xlib.
5.2.3. Computing Character String Drawing Metrics
int
XmbTextEscapement(display, font_set, text, bytes_text)
Display *display;
XFontSet font_set; /* In: font set to measure with */
char *text; /* In: text string to draw */
int bytes_text; /* In: length of text in bytes */
int
XwcTextEscapement(display, font_set, text, num_wchars)
Display *display;
XFontSet font_set; /* In: font set to measure with */
wchar_t *text; /* In: wide char text string */
int num_wchars; /* In: length of text in wchars */
int
XmbTextExtents(display, font_set, text, bytes_text, overall_return)
Display *display;
XFontSet font_set; /* In: font set to measure with */
char *text; /* In: text string to draw */
int bytes_text; /* In: length of text in bytes */
XRectangle *overall_ink_return; /* Out: overall ink dimensions */
XRectangle *overall_logical_return; /* Out: overall logical dimensions */
int
XwcTextExtents(display, font_set, text, num_wchars, overall_return)
Display *display;
XFontSet font_set; /* In: font set to measure with */
wchar_t *text; /* In: wide char text string */
int num_wchars; /* In: length of text in wchars */
XRectangle *overall_ink_return; /* Out: overall ink dimensions */
XRectangle *overall_logical_return; /* Out: overall logical dimensions */
XmbTextEscapement and XwcTextEscapement return the escapement in pixels of
the specified text as a value, using the fonts loaded for the specified
font set. The escapement is the distance in pixels in the primary draw
direction from the drawing origin to the origin of the next character to
be drawn, assuming that the rendering of the next character is not
dependent on the supplied previous text. Clients may assume that there
are no context dependencies before or after a whitespace character.
Regardless of the character rendering order, the escapement is always
positive.
To determine the effective drawing origin for a character in a drawn
string, the client should call XmbTextPerCharExtents on the entire string,
then on the character, and subtract the x values of the returned
XRectangles for the character. This is useful to redraw portions of a
line of text or to justify words, but due to context-dependent rendering
the client should not assume that it can redraw the character by itself
and get the same rendering, unless the character is surrounded by
whitespace.
XmbTextExtents and XwcTextExtents return to the overall_ink_return and
overall_logical_return arguments, respectively, the overall bounding box
of the string's image, and a logical bounding box for spacing purposes.
They return the value returned by Xmb/wcTextEscapement. These metrics are
relative to the drawing origin of the string, using the fonts loaded for
the specified font set.
If the overall_ink_return argument is non-NULL, it is set to the bounding
box of the string's character ink. Note that the overall_ink_return for a
non-descending horizontally drawn Latin character is entirely above the
baseline, i.e. overall_ink_return.height <= -overall_ink_return.y, and
that the overall_ink_return for a nonkerned character is entirely at and
to the right of the origin, i.e. overall_ink_return.x >= 0. A character
consisting of a single pixel at the origin would set overall_ink_return
fields y = 0, x = 0, width = 1, height = 1.
If the overall_logical_return argument is non-NULL, it is set to the
bounding box which provides minimum spacing to other graphical features
for the string. Other graphical features, for example, a border
surrounding the text, should not intersect this rectangle.
When the XFontSet has missing charsets, metrics for each unavailable
character are taken from the default string returned by XCreateFontSet, so
that the metrics represent the text as it will actually be drawn. The
behavior for an invalid codepoint is undefined.
The following routines are provided to obtain per-character information
for a text string:
#define BufferOverflow -4
int
XmbTextPerCharExtents(display, font_set, text, bytes_text, ink_extents_buffer,
logical_extents_buffer, buffer_size, num_chars, overall_return)
Display *display;
XFontSet font_set; /* In: font set to measure with */
char *text; /* In: text string to draw */
int bytes_text; /* In: length of text in bytes */
XRectangle *ink_extents_buffer; /* Out: per-char ink dimensions */
XRectangle *logical_extents_buffer; /* Out: per-char logical dimensions */
int buffer_size; /* In: size of both buffers */
int *num_chars; /* Out: number of XRectangles set */
XRectangle *overall_ink_return; /* Out: overall ink dimensions */
XRectangle *overall_logical_return; /* Out: overall logical dimensions */
int
XwcTextPerCharExtents(display, font_set, text, bytes_text, ink_extents_buffer,
logical_extents_buffer, buffer_size, num_wchars, overall_return)
Display *display;
XFontSet font_set; /* In: font set to measure with */
wchar_t *text; /* In: wide char text string */
int num_wchars; /* In: length of text in wchars */
XRectangle *ink_extents_buffer; /* Out: per-char ink dimensions */
XRectangle *logical_extents_buffer; /* Out: per-char logical dimensions */
int buffer_size; /* In: size of both buffers */
int *num_chars; /* Out: number of XRectangles set */
XRectangle *overall_ink_return; /* Out: overall ink dimensions */
XRectangle *overall_logical_return; /* Out: overall logical dimensions */
XmbTextPerCharExtents and XwcTextPerCharExtents return the text dimensions
of each character of the specified text, using the fonts loaded for the
specified font set. Each successive element of ink_extents_buffer and
logical_extents_buffer is set to the successive character's drawn metrics,
relative to the drawing origin of the string, one XRectangle for each
character in the supplied text string. The number of elements of
ink_extents_buffer and logical_extents_buffer that have been set is
returned to num_chars.
Each element of ink_extents_buffer is set to the bounding box of the
corresponding character's drawn foreground color. Each element of
logical_extents_buffer is set to the bounding box which provides minimum
spacing to other graphical features for the corresponding character.
Other graphical features should not intersect any of the
logical_extents_buffer rectangles.
Note that an XRectangle represents the effective drawing dimensions of the
character, regardless of the number of font glyphs that are used to draw
the character, or the direction in which the character is drawn. If
multiple characters map to a single character glyph, the dimensions of all
the XRectangles of those characters are the same.
When the XFontSet has missing charsets, metrics for each unavailable
character are taken from the default string returned by XCreateFontSet, so
that the metrics represent the text as it will actually be drawn. The
behavior for an invalid codepoint is undefined.
If the buffer_size is too small for the number of characters in the
supplied text, the functions return BufferOverflow, and num_chars is set
to the number of XRectangles required. Otherwise, the routines return
Success.
If the overall_ink_return or overall_logical_return argument is non-NULL,
XmbTextPerCharExtents and XwcTextPerCharExtents return the maximum extent
of the string's metrics to overall_ink_return or overall_logical_return,
as returned by XmbTextExtents or XwcTextExtents.
5.2.4. Computing New Character Context Dependencies
(ed. note: This function is an attempt to address a class of problems
that is not yet fully understood by the X Consortium membership.
Since we believe that by itself it is inadequate to address most locales
that need context-dependent rendering, it will most likely be removed from
the specification. Comments on the adequacy and appropriateness of this
interface are particularly requested.)
If the client appends or inserts a character in a previously drawn string,
the client may need to redraw some adjacent characters in order to obtain
proper rendering. To compute which characters need to be redrawn, use
XmbComputeTextRedraw or XwcComputeTextRedraw.
#define NoContextDependencies 0
#define IsContextDependent -1
XmbComputeTextRedraw(display, font_set, text, text_len, del_start, del_len,
rep_text, rep_len, change_start_return, change_len_return)
Display *display;
XFontSet font_set;
char *text;
int bytes_text, del_start, bytes_del;
char *rep_text;
int bytes_rep;
int *change_start_return, *change_len_return;
XwcComputeTextRedraw(display, font_set, text, text_len, del_start, del_len,
rep_text, rep_len, change_start_return, change_len_return)
Display *display;
XFontSet font_set;
wchar_t *text;
int num_wchars, del_start, num_wchars_del;
wchar_t *rep_text;
int num_wchars_rep;
int *change_start_return, *change_len_return;
XmbComputeTextRedraw or XwcComputeTextRedraw takes a previously drawn
string, specified by text and bytes_text or num_wchars, and computes the
substring that must be drawn if the substring of text which starts at
del_start and runs for bytes_del or num_wchars_del is replaced by the
string rep_text of length bytes_rep or num_wchars_rep. They return to
change_start_return the position in the resulting new string of the first
character that must be drawn, and return to change_len_return the number
of bytes or characters in the resulting new string that must be drawn.
A change_len_return of zero means that no text drawing is required. If
change_start_return == del_start and change_len_return == bytes_rep then
there are no context dependencies, and no characters must be redrawn.
Note that the characters in the previously drawn string after the replaced
segment may still have to be moved on the screen (e.g. using XCopyArea
and XClearArea), due to changes in position caused by insertion or
deletion of text. The client should subtract the escapement of the
replaced+redrawn string from the the escapement of the string specified by
change_start_return and change_len_return to determine the shift in the
drawing origin for the moved substring, and then call XmbTextExtents or
XwcTextExtents on the moved string to determine the area that must be
copied and possibly cleared.
The XFontSet specifies the locale and fonts which determine the context
dependencies.
If the client supplies a NULL string to text, XmbComputeTextRedraw or
XwcComputeTextRedraw returns NoContextDependencies to change_start_return
if there is no context-dependent rendering in the current locale, else
they return IsContextDependent to change_start_return.
Clients may assume that there are no context dependencies before or after
a whitespace character. To obtain a complete computation of the
characters that must be redrawn, the client should pass the entire
non-whitespace string that surrounds the text change to
XmbComputeTextRedraw or XwcComputeTextRedraw.
5.3. Drawing Internationalized Text
typedef struct {
char *chars; /* pointer to string */
int nchars; /* number of characters */
int delta; /* pixel delta between strings */
XFontSet font_set; /* fonts, None don't change */
} XmbTextItem;
typedef struct {
wchar_t *text; /* In: wide char text string to draw */
int num_wchars; /* In: length of text in wchars */
int delta; /* pixel delta between strings */
XFontSet font_set; /* fonts, None don't change */
} XwcTextItem;
void
XmbDrawText(display, d, gc, x, y, text_items, nitems)
Display *display;
Drawable d; /* In: what to draw in */
GC gc; /* In: gc to use */
int x, y; /* In: where to draw */
XmbTextItem **text_items; /* In: array of text items to draw */
int nitems; /* In: number of text items */
void
XwcDrawText(display, d, gc, x, y, items, nitems)
Display *display;
Drawable d; /* In: what to draw in */
GC gc; /* In: gc to use */
int x, y; /* In: where to draw */
XwcTextItem *items; /* In: array of text items to draw */
int nitems; /* In: number of text items */
void
XmbDrawString(display, d, font_set, gc, x, y, text, bytes_text)
Display *display;
Drawable d; /* In: what to draw in */
XFontSet font_set; /* In: font set to draw with */
GC gc; /* In: gc to use */
int x, y; /* In: where to draw */
char *text; /* In: text string to draw */
int bytes_text; /* In: length of text in bytes */
void
XwcDrawString(display, d, font_set, gc, x, y, text, num_wchars)
Display *display;
Drawable d; /* In: what to draw in */
XFontSet font_set; /* In: font set to draw with */
GC gc; /* In: gc to use */
int x, y; /* In: where to draw */
wchar_t *text; /* In: wide char text string to draw */
int num_wchars; /* In: length of text in wchars */
void
XwcDrawImageString(display, d, font_set, gc, x, y, text, num_wchars)
Display *display;
Drawable d; /* In: what to draw in */
XFontSet font_set; /* In: font set to draw with */
GC gc; /* In: gc to use */
int x, y; /* In: where to draw */
wchar_t *text; /* In: wide char text string to draw */
int num_wchars; /* In: length of text in wchars */
void
XmbDrawImageString(display, d, font_set, gc, x, y, text, bytes_text)
Display *display;
Drawable d; /* In: what to draw in */
XFontSet font_set; /* In: font set to draw with */
GC gc; /* In: gc to use */
int x, y; /* In: where to draw */
char *text; /* In: text string to draw */
int bytes_text; /* In: length of text in bytes */
These routines draw the specified text at the specified location in the
specified drawable. See XDrawText, XDrawString, and XDrawImageString for
details of the use of GC's and possible protocol errors. If a BadFont
error is generated, characters prior to the offending character may have
been drawn.
The text is drawn using the fonts loaded for the specified font set; the
font in the GC is ignored, and may be modified by the routines. No
validation that all fonts conform to some width rule is performed.
Xmb/wcDrawText allows complex spacing and font set shifts between text
strings. Each text item is processed in turn, with the origin of a text
element advanced in the primary draw direction by the escapement of the
previous text item. A text item delta specifies an additional escapement
of the text item drawing origin in the primary draw direction. A font_set
member other than None in an item causes the font to be used for this and
subsequent text items in the text_items list. The first text item must
have a non-None font_set member, or it will not be drawn.
Xmb/wcDrawText do not perform any context-dependent rendering between text
segments. Clients may compute the drawing metrics by passing each text
segment to Xmb/wcTextExtents or Xmb/wcTextPerCharExtents.
Xmb/wcDrawImageString fill a destination rectangle with the background
pixel defined in the GC, and then paint the text with the foreground
pixel. The filled rectangle is the rectangle returned to
overall_logical_return by XmbTextExtents or XwcTextExtents for the same
text and XFontSet.
When the XFontSet has missing charsets, each unavailable character is
drawn with the default string returned by XCreateFontSet. The behavior
for an invalid codepoint is undefined.