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 !"%&'()*+,-./:;<=>?_ , , and This is the ISO646-invariant printable character set, plus , , and , or the set of printable characters in ASCII, plus , , and , 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 * ) - 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.