diff -urwb X11R6.6/xc/doc/specs/X11/CH01 release1/cvs-ro/xc/doc/specs/X11/CH01 --- X11R6.6/xc/doc/specs/X11/CH01 Thu Apr 13 09:38:14 2000 +++ release1/cvs-ro/xc/doc/specs/X11/CH01 Mon Nov 17 11:03:19 2003 @@ -1,4 +1,5 @@ .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" Copyright \(co 2000 The XFree86 Project, Inc. .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the @@ -40,6 +41,8 @@ .\" of this documentation for any purpose. .\" It is provided ``as is'' without express or implied warranty. .\" +.\" $XFree86: xc/doc/specs/X11/CH01,v 1.2 2000/11/28 18:49:17 dawes Exp $ +.\" .EH '\fBXlib \- C Library\fP''\fBX11, Release 6.4\fP' .OH '\fBXlib \- C Library\fP''\fBX11, Release 6.4\fP' .EF ''\fB % \fP'' @@ -601,6 +604,11 @@ .IP Latin-1, plus tab and newline. .IP \(bu 5 +UTF-8 Encoding +.IP +The ASCII compatible character encoding scheme defined by the ISO 10646-1 +standard. +.IP \(bu 5 POSIX Portable Filename Character Set .IP The set of 65 characters, diff -urwb X11R6.6/xc/doc/specs/X11/CH13 release1/cvs-ro/xc/doc/specs/X11/CH13 --- X11R6.6/xc/doc/specs/X11/CH13 Thu Apr 13 09:38:15 2000 +++ release1/cvs-ro/xc/doc/specs/X11/CH13 Mon Nov 17 11:03:19 2003 @@ -1,4 +1,5 @@ .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" Copyright \(co 2000 The XFree86 Project, Inc. .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the @@ -40,6 +41,8 @@ .\" of this documentation for any purpose. .\" It is provided ``as is'' without express or implied warranty. .\" +.\" $XFree86: xc/doc/specs/X11/CH13,v 1.5 2000/12/04 18:49:17 dawes Exp $ +.\" \& .sp 1 .ce 3 @@ -345,6 +348,9 @@ T} text (some WM_ property text in environment locale) + T{ +.PN Xutf8SetWMProperties +T} .sp 6p T{ .PN setlocale @@ -357,11 +363,17 @@ .PN XwcTextPropertyToTextList T} T{ +.PN Xutf8TextPropertyToTextList +T} + T{ .PN XmbTextListToTextProperty T} T{ .PN XwcTextListToTextProperty T} + T{ +.PN Xutf8TextListToTextProperty +T} .sp Text Input: .sp 6p @@ -407,6 +419,9 @@ T} T{ Encoding of returned text T} + T{ +.PN Xutf8LookupString +T} .sp Text Drawing: .sp 6p @@ -450,6 +465,12 @@ Locale of supplied text T} T{ +.PN Xutf8DrawText , +and so on +T} T{ +Locale-dependent metrics +T} + T{ .PN XExtentsOfFontSet , and so on T} T{ @@ -460,6 +481,9 @@ T} T{ .PN XwcTextExtents , +T} + T{ +.PN Xutf8TextExtents , and so on T} .sp @@ -747,7 +771,11 @@ for setting properties or features of the specified output method. This function returns NULL if it succeeds; otherwise, -it returns the name of the first argument that could not be obtained. +it returns the name of the first argument that could not be set. +Xlib does not attempt to set arguments from the supplied list that +follow the failed argument; +all arguments in the list preceding the failed argument have been set +correctly. .LP No standard arguments are currently defined by Xlib. .LP @@ -1828,7 +1856,7 @@ .PN XFontSet to font_set. .LP -When an Xmb/wc drawing or measuring function is called with an +When an Xmb/wc/utf8 drawing or measuring function is called with an .PN XFontSet that has missing charsets, some characters in the locale will not be drawable. @@ -1901,7 +1929,7 @@ .PN XFontsOfFontSet function returns a list of one or more .PN XFontStructs -and font names for the fonts used by the Xmb and Xwc layers +and font names for the fonts used by the Xmb/wc/utf8 layer for the given font set. A list of pointers to the .PN XFontStruct @@ -2080,9 +2108,10 @@ 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 -.PN XmbTextPerCharExtents +.PN XmbTextPerCharExtents , +.PN XwcTextPerCharExtents or -.PN XwcTextPerCharExtents . +.PN Xutf8TextPerCharExtents . .LP The drawing functions are allowed to implement context-dependent rendering, where the glyphs drawn for a string are not simply a @@ -2196,9 +2225,10 @@ the rectangles that bound the character glyph image drawn in the foreground color, relative to a constant origin. See -.PN XmbTextExtents -and +.PN XmbTextExtents , .PN XwcTextExtents +and +.PN Xutf8TextExtents for detailed semantics. .LP The max_logical_extent member gives the maximum extent, @@ -2217,9 +2247,10 @@ individual extent. .LP The rectangles for a given character in a string can be obtained from -.PN XmbPerCharExtents +.PN XmbPerCharExtents , +.PN XwcPerCharExtents or -.PN XwcPerCharExtents . +.PN Xutf8PerCharExtents . .LP .sp To obtain the maximum extents structure given an @@ -2241,7 +2272,7 @@ .PN XExtentsOfFontSet function returns an .PN XFontSetExtents -structure for the fonts used by the Xmb and Xwc layers +structure for the fonts used by the Xmb/wc/utf8 layer for the given font set. .LP The @@ -2257,11 +2288,13 @@ .sp To obtain the escapement in pixels of the specified text as a value, use -.PN XmbTextEscapement +.PN XmbTextEscapement , +.PN XwcTextEscapement or -.PN XwcTextEscapement . +.PN Xutf8TextEscapement . .IN "XmbTextEscapement" "" "@DEF@" .IN "XwcTextEscapement" "" "@DEF@" +.IN "Xutf8TextEscapement" "" "@DEF@" .sM .FD 0 int XmbTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) @@ -2281,6 +2314,15 @@ .br int \fInum_wchars\fP\^; .FN +.FD 0 +int Xutf8TextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.FN .IP \fIfont_set\fP 1i Specifies the font set. .IP \fIstring\fP 1i @@ -2292,9 +2334,10 @@ .LP .eM The -.PN XmbTextEscapement -and +.PN XmbTextEscapement , .PN XwcTextEscapement +and +.PN Xutf8TextEscapement functions return the escapement in pixels of the specified string as a value, using the fonts loaded for the specified font set. The escapement is the distance in pixels in the primary draw @@ -2305,15 +2348,23 @@ Regardless of the character rendering order, the escapement is always positive. .LP +The function +.PN Xutf8TextEscapement +is an XFree86 extension introduced in XFree86 4.0.2. Its presence is +indicated by the macro +.PN X_HAVE_UTF8_STRING . +.LP .sp To obtain the overall_ink_return and overall_logical_return arguments, the overall bounding box of the string's image, and a logical bounding box, use -.PN XmbTextExtents +.PN XmbTextExtents , +.PN XwcTextExtents or -.PN XwcTextExtents . +.PN Xutf8TextExtents . .IN "XmbTextExtents" "" "@DEF@" .IN "XwcTextExtents" "" "@DEF@" +.IN "Xutf8TextExtents" "" "@DEF@" .sM .FD 0 int XmbTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^) @@ -2342,6 +2393,19 @@ .br XRectangle *\fIoverall_logical_return\fP\^; .FN +.FD 0 +int Xutf8TextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.br + XRectangle *\fIoverall_ink_return\fP\^; +.br + XRectangle *\fIoverall_logical_return\fP\^; +.FN .IP \fIfont_set\fP 1i Specifies the font set. .IP \fIstring\fP 1i @@ -2358,17 +2422,19 @@ .LP .eM The -.PN XmbTextExtents -and +.PN XmbTextExtents , .PN XwcTextExtents +and +.PN Xutf8TextExtents functions set the components of the specified overall_ink_return and overall_logical_return arguments to the overall bounding box of the string's image and a logical bounding box for spacing purposes, respectively. They return the value returned by -.PN XmbTextEscapement +.PN XmbTextEscapement , +.PN XwcTextEscapement or -.PN XwcTextEscapement . +.PN Xutf8TextEscapement . These metrics are relative to the drawing origin of the string, using the fonts loaded for the specified font set. .LP @@ -2409,14 +2475,22 @@ the client should not assume that it can redraw the character by itself and get the same rendering. .LP +The function +.PN Xutf8TextExtents +is an XFree86 extension introduced in XFree86 4.0.2. Its presence is +indicated by the macro +.PN X_HAVE_UTF8_STRING . +.LP .sp To obtain per-character information for a text string, use -.PN XmbTextPerCharExtents +.PN XmbTextPerCharExtents , +.PN XwcTextPerCharExtents or -.PN XwcTextPerCharExtents . +.PN Xutf8TextPerCharExtents . .IN "XmbTextPerCharExtents" "" "@DEF@" .IN "XwcTextPerCharExtents" "" "@DEF@" +.IN "Xutf8TextPerCharExtents" "" "@DEF@" .sM .FD 0 Status XmbTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIink_array_return\fP\^, @@ -2464,6 +2538,29 @@ .br XRectangle *\fIoverall_logical_return\fP\^; .FN +.FD 0 +Status Xutf8TextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIink_array_return\fP\^, +.br + \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.br + XRectangle *\fIink_array_return\fP\^; +.br + XRectangle *\fIlogical_array_return\fP\^; +.br + int \fIarray_size\fP\^; +.br + int *\fInum_chars_return\fP\^; +.br + XRectangle *\fIoverall_ink_return\fP\^; +.br + XRectangle *\fIoverall_logical_return\fP\^; +.FN .IP \fIfont_set\fP 1i Specifies the font set. .IP \fIstring\fP 1i @@ -2489,9 +2586,10 @@ .LP .eM The -.PN XmbTextPerCharExtents -and +.PN XmbTextPerCharExtents , .PN XwcTextPerCharExtents +and +.PN Xutf8TextPerCharExtents functions 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_array_return and logical_array_return @@ -2534,14 +2632,22 @@ Otherwise, the functions return a nonzero value. .LP If the overall_ink_return or overall_logical_return argument is non-NULL, -.PN XmbTextPerCharExtents -and +.PN XmbTextPerCharExtents , .PN XwcTextPerCharExtents +and +.PN Xutf8TextPerCharExtents return the maximum extent of the string's metrics to overall_ink_return or overall_logical_return, as returned by -.PN XmbTextExtents +.PN XmbTextExtents , +.PN XwcTextExtents or -.PN XwcTextExtents . +.PN Xutf8TextExtents . +.LP +The function +.PN Xutf8TextPerCharExtents +is an XFree86 extension introduced in XFree86 4.0.2. Its presence is +indicated by the macro +.PN X_HAVE_UTF8_STRING . .NH 3 Drawing Text Using Font Sets .XS @@ -2557,6 +2663,8 @@ .PN XDrawImageString except that they work with font sets instead of single fonts and interpret the text based on the locale of the font set +(for functions whose name starts with Xmb or Xwc) or as UTF-8 encoded +text (for functions whose name starts with Xutf8), instead of treating the bytes of the string as direct font indexes. See section 8.6 for details of the use of Graphics Contexts (GCs) and possible protocol errors. @@ -2570,9 +2678,10 @@ No validation that all fonts conform to some width rule is performed. .LP The text functions -.PN XmbDrawText -and +.PN XmbDrawText , .PN XwcDrawText +and +.PN Xutf8DrawText use the following structures: .LP .IN "XmbTextItem" "" "@DEF@" @@ -2603,11 +2712,13 @@ .eM .sp To draw text using multiple font sets in a given drawable, use -.PN XmbDrawText +.PN XmbDrawText , +.PN XwcDrawText or -.PN XwcDrawText . +.PN Xutf8DrawText . .IN "XmbDrawText" "" "@DEF@" .IN "XwcDrawText" "" "@DEF@" +.IN "Xutf8DrawText" "" "@DEF@" .sM .FD 0 void XmbDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^) @@ -2639,6 +2750,21 @@ .br int \fInitems\fP\^; .FN +.FD 0 +void Xutf8DrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + XmbTextItem *\fIitems\fP\^; +.br + int \fInitems\fP\^; +.FN .IP \fIdisplay\fP 1i Specifies the connection to the X server. .IP \fId\fP 1i @@ -2658,9 +2784,10 @@ .LP .eM The -.PN XmbDrawText -and +.PN XmbDrawText , .PN XwcDrawText +and +.PN Xutf8DrawText functions allow 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 @@ -2675,18 +2802,19 @@ .PN None will not be drawn. .LP -.PN XmbDrawText -and +.PN XmbDrawText , .PN XwcDrawText +and +.PN Xutf8DrawText do not perform any context-dependent rendering between text segments. Clients may compute the drawing metrics by passing each text segment to -.PN XmbTextExtents -and -.PN XwcTextExtents +.PN XmbTextExtents , +.PN XwcTextExtents , +.PN Xutf8TextExtents or -.PN XmbTextPerCharExtents -and +.PN XmbTextPerCharExtents , .PN XwcTextPerCharExtents . +.PN Xutf8TextPerCharExtents . When the .PN XFontSet has missing charsets, each unavailable character is drawn @@ -2694,13 +2822,21 @@ .PN XCreateFontSet . The behavior for an invalid codepoint is undefined. .LP +The function +.PN Xutf8DrawText +is an XFree86 extension introduced in XFree86 4.0.2. Its presence is +indicated by the macro +.PN X_HAVE_UTF8_STRING . +.LP .sp To draw text using a single font set in a given drawable, use -.PN XmbDrawString +.PN XmbDrawString , +.PN XwcDrawString or -.PN XwcDrawString . +.PN Xutf8DrawString . .IN "XmbDrawString" "" "@DEF@" .IN "XwcDrawString" "" "@DEF@" +.IN "Xutf8DrawString" "" "@DEF@" .sM .FD 0 void XmbDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) @@ -2736,6 +2872,23 @@ .br int \fInum_wchars\fP\^; .FN +.FD 0 +void Xutf8DrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + XFontSet \fIfont_set\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.FN .IP \fIdisplay\fP 1i Specifies the connection to the X server. .IP \fId\fP 1i @@ -2759,9 +2912,10 @@ .LP .eM The -.PN XmbDrawString -and +.PN XmbDrawString , .PN XwcDrawString +and +.PN Xutf8DrawString functions draw the specified text with the foreground pixel. When the .PN XFontSet @@ -2770,13 +2924,21 @@ .PN XCreateFontSet . The behavior for an invalid codepoint is undefined. .LP +The function +.PN Xutf8DrawString +is an XFree86 extension introduced in XFree86 4.0.2. Its presence is +indicated by the macro +.PN X_HAVE_UTF8_STRING . +.LP .sp To draw image text using a single font set in a given drawable, use -.PN XmbDrawImageString +.PN XmbDrawImageString , +.PN XwcDrawImageString or -.PN XwcDrawImageString . +.PN Xutf8DrawImageString . .IN "XmbDrawImageString" "" "@DEF@" .IN "XwcDrawImageString" "" "@DEF@" +.IN "Xutf8DrawImageString" "" "@DEF@" .sM .FD 0 void XmbDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) @@ -2812,6 +2974,23 @@ .br int \fInum_wchars\fP\^; .FN +.FD 0 +void Xutf8DrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + XFontSet \fIfont_set\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.FN .IP \fIdisplay\fP 1i Specifies the connection to the X server. .IP \fId\fP 1i @@ -2835,15 +3014,17 @@ .LP .eM The -.PN XmbDrawImageString -and +.PN XmbDrawImageString , .PN XwcDrawImageString +and +.PN Xutf8DrawImageString functions 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 -.PN XmbTextExtents -or +.PN XmbTextExtents , .PN XwcTextExtents +or +.PN Xutf8TextExtents for the same text and .PN XFontSet . .LP @@ -2853,6 +3034,12 @@ with the default string returned by .PN XCreateFontSet . The behavior for an invalid codepoint is undefined. +.LP +The function +.PN Xutf8TextExtents +is an XFree86 extension introduced in XFree86 4.0.2. Its presence is +indicated by the macro +.PN X_HAVE_UTF8_STRING . .NH 2 Input Methods .XS @@ -3195,9 +3382,10 @@ .LP To obtain characters from an input method, a client must call the function -.PN XmbLookupString -or +.PN XmbLookupString , .PN XwcLookupString +or +.PN Xutf8LookupString with an input context created from that input method. Both a locale and display are bound to an input method when it is opened, and an input context inherits this locale and display. @@ -3205,7 +3393,9 @@ .PN XmbLookupString or .PN XwcLookupString -will be encoded in that locale. +will be encoded in that locale. Strings returned by +.PN Xutf8LookupString +are encoded in UTF-8. .NH 4 Focus Management .XS @@ -3213,9 +3403,10 @@ .XE .LP For each text entry area in which the -.PN XmbLookupString -or +.PN XmbLookupString , .PN XwcLookupString +or +.PN Xutf8LookupString functions are used, there will be an associated input context. .LP @@ -3347,9 +3538,10 @@ A filtering mechanism is provided to allow input methods to capture X events transparently to clients. It is expected that toolkits (or clients) using -.PN XmbLookupString -or +.PN XmbLookupString , .PN XwcLookupString +or +.PN Xutf8LookupString will call this filter at some point in the event processing mechanism to make sure that events needed by an input method can be filtered by that input method. @@ -3386,9 +3578,10 @@ .LP When the user enters a keystroke, the client calls -.PN XmbLookupString +.PN XmbLookupString , +.PN XwcLookupString or -.PN XwcLookupString . +.PN Xutf8LookupString . At this point, in the on-the-spot case, the echo of the keystroke in the preedit has not yet been done. Before returning to the client logic that handles the input characters, @@ -3436,9 +3629,10 @@ preediting, which supports a type of preprocessor input composition. In this case, composition consists of interpreting a sequence of key events and returning a committed string via -.PN XmbLookupString +.PN XmbLookupString , +.PN XwcLookupString or -.PN XwcLookupString . +.PN Xutf8LookupString . This provides the basics for input methods. .LP In addition to preediting based on key events, a general framework @@ -3509,9 +3703,10 @@ .sp For this reason, an input method supporting this type of conversion should take notice of when the client calls -.PN XmbResetIC +.PN XmbResetIC , +.PN XwcResetIC or -.PN XwcResetIC , +.PN Xutf8ResetIC , which is usually an indication of a context change. .LP Context-sensitive conversions just need a copy of the client's text, @@ -3519,9 +3714,10 @@ to achieve the reconversion or transliteration. Yet in all cases the result of a conversion, either immediately or via preediting, is returned by the -.PN XmbLookupString -and +.PN XmbLookupString , .PN XwcLookupString +and +.PN Xutf8LookupString functions. .LP String conversion support is dependent on the availability of the @@ -4688,11 +4884,13 @@ .LP .sp To reset the state of an input context to its initial state, use -.PN XmbResetIC +.PN XmbResetIC , +.PN XwcResetIC or -.PN XwcResetIC . +.PN Xutf8ResetIC . .IN "XmbResetIC" "" "@DEF@" .IN "XwcResetIC" "" "@DE@" +.IN "Xutf8ResetIC" "" "@DE@" .sM .FD 0 char * XmbResetIC\^(\^\fIic\fP\^) @@ -4704,6 +4902,11 @@ .br XIC \fIic\fP\^; .FN +.FD 0 +char * Xutf8ResetIC\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN .IP \fIic\fP 1i Specifies the input context. .LP @@ -4712,9 +4915,10 @@ .PN XNResetState is set to .PN XIMInitialState , -.PN XmbResetIC -and +.PN XmbResetIC , .PN XwcResetIC +and +.PN Xutf8ResetIC reset an input context to its initial state; when .PN XNResetState @@ -4725,14 +4929,21 @@ The input method is required to clear the preedit area, if any, and update the status accordingly. Calling -.PN XmbResetIC -or +.PN XmbResetIC , .PN XwcResetIC +or +.PN Xutf8ResetIC does not change the focus. .LP The return value of .PN XmbResetIC is its current preedit string as a multibyte string. +The return value of +.PN XwcResetIC +is its current preedit string as a wide character string. +The return value of +.PN Xutf8ResetIC +is its current preedit string as an UTF-8 string. If there is any preedit text drawn or visible to the user, then these procedures must return a non-NULL string. If there is no visible preedit text, @@ -4742,6 +4953,12 @@ The client should free the returned string by calling .PN XFree . .LP +The function +.PN Xutf8ResetIC +is an XFree86 extension introduced in XFree86 4.0.2. Its presence is +indicated by the macro +.PN X_HAVE_UTF8_STRING . +.LP .sp To get the input method associated with an input context, use .PN XIMOfIC . @@ -5276,9 +5493,10 @@ The .PN XNResetState argument specifies the state the input context will return to after calling -.PN XmbResetIC +.PN XmbResetIC , +.PN XwcResetIC or -.PN XwcResetIC . +.PN Xutf8ResetIC . .LP The XIC state may be set to its initial state, as specified by the .PN XNPreeditState @@ -5319,9 +5537,10 @@ If .PN XIMInitialState is set, then -.PN XmbResetIC -and +.PN XmbResetIC , .PN XwcResetIC +and +.PN Xutf8ResetIC will return to the initial .PN XNPreeditState state of the XIC. @@ -5329,9 +5548,10 @@ If .PN XIMPreserveState is set, then -.PN XmbResetIC -and +.PN XmbResetIC , .PN XwcResetIC +and +.PN Xutf8ResetIC will preserve the current state of the XIC. .LP If @@ -5805,9 +6025,10 @@ the .PN XNPreeditState value specified at the creation time will be reflected as the initial state for -.PN XmbResetIC +.PN XmbResetIC , +.PN XwcResetIC and -.PN XwcResetIC . +.PN Xutf8ResetIC . .LP Because this XIC value is optional, a client should call .PN XGetIMValues @@ -7004,11 +7225,13 @@ .LP To get composed input from an input method, use -.PN XmbLookupString +.PN XmbLookupString , +.PN XwcLookupString or -.PN XwcLookupString . +.PN Xutf8LookupString . .IN "XmbLookupString" "" "@DEF@" .IN "XwcLookupString" "" "@DEF@" +.IN "Xutf8LookupString" "" "@DEF@" .sM .FD 0 int XmbLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^) @@ -7040,6 +7263,21 @@ .br Status *\fIstatus_return\fP\^; .FN +.FD 0 +int Xutf8LookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^) +.br + XIC \fIic\fP\^; +.br + XKeyPressedEvent *\fIevent\fP; +.br + char *\fIbuffer_return\fP\^; +.br + int \fIbytes_buffer\fP\^; +.br + KeySym *\fIkeysym_return\fP\^; +.br + Status *\fIstatus_return\fP\^; +.FN .IP \fIic\fP 1i Specifies the input context. .ds Ev key event to be used @@ -7060,9 +7298,10 @@ .LP .eM The -.PN XmbLookupString -and +.PN XmbLookupString , .PN XwcLookupString +and +.PN Xutf8LookupString functions return the string from the input method specified in the buffer_return argument. If no string is returned, @@ -7075,7 +7314,9 @@ the KeySym value does not necessarily correspond to the string returned. .LP .PN XmbLookupString -returns the length of the string in bytes, and +and +.PN Xutf8LookupString +return the length of the string in bytes, and .PN XwcLookupString returns the length of the string in characters. Both @@ -7083,7 +7324,9 @@ and .PN XwcLookupString return text in the encoding of the locale bound to the input method -of the specified input context. +of the specified input context, and +.PN Xutf8LookupString +returns text in UTF-8 encoding. .LP Each string returned by .PN XmbLookupString @@ -7092,13 +7335,14 @@ begins in the initial state of the encoding of the locale (if the encoding of the locale is state-dependent). .NT -To insure proper input processing, +To ensure proper input processing, it is essential that the client pass only .PN KeyPress events to -.PN XmbLookupString +.PN XmbLookupString , +.PN XwcLookupString and -.PN XwcLookupString . +.PN Xutf8LookupString . Their behavior when a client passes a .PN KeyRelease event is undefined. @@ -7106,7 +7350,7 @@ .LP Clients should check the status_return argument before using the other returned values. -These two functions both return a value to status_return +These three functions each return a value to status_return that indicates what has been returned in the other arguments. The possible values returned are: .TS @@ -7115,9 +7359,10 @@ .PN XBufferOverflow T} T{ The input string to be returned is too large for the supplied buffer_return. -The required size -.Pn ( XmbLookupString -in bytes; +The required size (for +.PN XmbLookupString , +.PN Xutf8LookupString +in bytes; for .PN XwcLookupString in characters) is returned as the value of the function, and the contents of buffer_return and keysym_return are not modified. @@ -7135,9 +7380,9 @@ .PN XLookupChars T} T{ Some input characters have been composed. -They are placed in the buffer_return argument, +They are placed in the buffer_return argument, using the encoding +described above, and the string length is returned as the value of the function. -The string is encoded in the locale bound to the input context. The content of the keysym_return argument is not modified. T} T{ @@ -7160,16 +7405,24 @@ .TE .LP It does not make any difference if the input context passed as an argument to -.PN XmbLookupString -and +.PN XmbLookupString , .PN XwcLookupString +and +.PN Xutf8LookupString is the one currently in possession of the focus or not. Input may have been composed within an input context before it lost the focus, and that input may be returned on subsequent calls to -.PN XmbLookupString -or +.PN XmbLookupString , .PN XwcLookupString +or +.PN Xutf8LookupString even though it does not have any more keyboard focus. +.LP +The function +.PN Xutf8LookupString +is an XFree86 extension introduced in XFree86 4.0.2. Its presence is +indicated by the macro +.PN X_HAVE_UTF8_STRING . .NH 3 Input Method Conventions .XS @@ -7202,9 +7455,10 @@ .PN KeyPress event with a KeyCode of zero is used exclusively as a signal that an input method has composed input that can be returned by -.PN XmbLookupString +.PN XmbLookupString , +.PN XwcLookupString or -.PN XwcLookupString . +.PN Xutf8LookupString . No other use is made of a .PN KeyPress event with KeyCode of zero. diff -urwb X11R6.6/xc/doc/specs/X11/CH14 release1/cvs-ro/xc/doc/specs/X11/CH14 --- X11R6.6/xc/doc/specs/X11/CH14 Thu Apr 13 09:38:15 2000 +++ release1/cvs-ro/xc/doc/specs/X11/CH14 Mon Nov 17 11:03:19 2003 @@ -1,4 +1,5 @@ .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" Copyright \(co 2000 The XFree86 Project, Inc. .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the @@ -40,6 +41,8 @@ .\" of this documentation for any purpose. .\" It is provided ``as is'' without express or implied warranty. .\" +.\" $XFree86: xc/doc/specs/X11/CH14,v 1.2 2000/11/28 18:49:19 dawes Exp $ +.\" \& .sp 1 .ce 3 @@ -499,21 +502,29 @@ XStringStyle, /* STRING */ XCompoundTextStyle, /* COMPOUND_TEXT */ XTextStyle, /* text in owner's encoding (current locale) */ - XStdICCTextStyle /* STRING, else COMPOUND_TEXT */ + XStdICCTextStyle, /* STRING, else COMPOUND_TEXT */ + XUTF8StringStyle /* UTF8_STRING */ } XICCEncodingStyle; .De .LP .eM -.sp +The value +.PN XUTF8StringStyle +is an XFree86 extension introduced in XFree86 4.0.2. Its presence is +indicated by the macro +.PN X_HAVE_UTF8_STRING . .LP +.sp To convert a list of text strings to an .PN XTextProperty structure, use -.PN XmbTextListToTextProperty +.PN XmbTextListToTextProperty , +.PN XwcTextListToTextProperty or -.PN XwcTextListToTextProperty . +.PN Xutf8TextListToTextProperty . .IN "XmbTextListToTextProperty" "" "@DEF@" .IN "XwcTextListToTextProperty" "" "@DEF@" +.IN "Xutf8TextListToTextProperty" "" "@DEF@" .sM .FD 0 int XmbTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^) @@ -541,6 +552,19 @@ .br XTextProperty *\fItext_prop_return\fP\^; .FN +.FD 0 +int Xutf8TextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char **\fIlist\fP\^; +.br + int \fIcount\fP\^; +.br + XICCEncodingStyle \fIstyle\fP\^; +.br + XTextProperty *\fItext_prop_return\fP\^; +.FN .IP \fIdisplay\fP 1i Specifies the connection to the X server. .IP \fIlist\fP 1i @@ -556,15 +580,20 @@ .LP .eM The -.PN XmbTextListToTextProperty -and +.PN XmbTextListToTextProperty , .PN XwcTextListToTextProperty +and +.PN Xutf8TextListToTextProperty functions set the specified .PN 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. +of the specified list of null-terminated text strings. The input text +strings must be given in the current locale encoding (for +.PN XmbTextListToTextProperty +and +.PN XwcTextListToTextProperty ), +or in UTF-8 encoding (for +.PN Xutf8TextListToTextProperty ). .LP The functions set the encoding field of text_prop_return to an .PN Atom @@ -579,6 +608,12 @@ is specified, this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively. If the style +.PN XUTF8StringStyle +is specified, +this encoding is ``UTF8_STRING''. (This is an XFree86 extension introduced in +XFree86 4.0.2. Its presence is indicated by the macro +.PN X_HAVE_UTF8_STRING .) +If the style .PN XTextStyle is specified, this encoding is the encoding of the current locale. @@ -587,6 +622,8 @@ is specified, this encoding is ``STRING'' if the text is fully convertible to STRING, else ``COMPOUND_TEXT''. +A final terminating null byte is stored at the end of the value field +of text_prop_return but is not included in the nitems member. .LP If insufficient memory is available for the new value string, the functions return @@ -614,16 +651,24 @@ .LP To free the storage for the value field, use .PN XFree . +.LP +The function +.PN Xutf8TextListToTextProperty +is an XFree86 extension introduced in XFree86 4.0.2. Its presence is +indicated by the macro +.PN X_HAVE_UTF8_STRING . .sp .LP To obtain a list of text strings from an .PN XTextProperty structure, use -.PN XmbTextPropertyToTextList +.PN XmbTextPropertyToTextList , +.PN XwcTextPropertyToTextList or -.PN XwcTextPropertyToTextList . +.PN Xutf8TextPropertyToTextList . .IN "XmbTextPropertyToTextList" "" "@DEF@" .IN "XwcTextPropertyToTextList" "" "@DEF@" +.IN "Xutf8TextPropertyToTextList" "" "@DEF@" .sM .FD 0 int XmbTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^) @@ -647,6 +692,17 @@ .br int *\fIcount_return\fP\^; .FN +.FD 0 +int Xutf8TextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XTextProperty *\fItext_prop\fP\^; +.br + char ***\fIlist_return\fP\^; +.br + int *\fIcount_return\fP\^; +.FN .IP \fIdisplay\fP 1i Specifies the connection to the X server. .IP \fItext_prop\fP 1i @@ -661,13 +717,20 @@ .LP .eM The -.PN XmbTextPropertyToTextList -and +.PN XmbTextPropertyToTextList , .PN XwcTextPropertyToTextList -functions return a list of text strings in the current locale representing the +and +.PN Xutf8TextPropertyToTextList +functions return a list of text strings representing the null-separated elements of the specified .PN XTextProperty -structure. +structure. The returned strings are encoded using the current locale encoding +(for +.PN XmbTextPropertyToTextList +and +.PN XwcTextPropertyToTextList ) +or in UTF-8 (for +.PN Xutf8TextPropertyToTextList ). The data in text_prop must be format 8. .LP Multiple elements of the property (for example, the strings in a disjoint @@ -676,9 +739,10 @@ any terminating null should not be included in text_prop.nitems. .LP If insufficient memory is available for the list and its elements, -.PN XmbTextPropertyToTextList -and +.PN XmbTextPropertyToTextList , .PN XwcTextPropertyToTextList +and +.PN Xutf8TextPropertyToTextList return .PN XNoMemory . If the current locale is not supported, @@ -689,7 +753,7 @@ the functions return .PN XConverterNotFound . For supported locales, -existence of a converter from COMPOUND_TEXT, STRING +existence of a converter from COMPOUND_TEXT, STRING, UTF8_STRING or the encoding of the current locale is guaranteed if .PN XSupportsLocale returns @@ -701,14 +765,15 @@ the functions do not set any return values. .LP Otherwise, -.PN XmbTextPropertyToTextList -and +.PN XmbTextPropertyToTextList , .PN XwcTextPropertyToTextList +and +.PN Xutf8TextPropertyToTextList return the list of null-terminated text strings to list_return and the number of text strings to count_return. .LP -If the value field of text_prop is not fully convertible to the encoding of -the current locale, +If the value field of text_prop is not fully convertible to the +encoding of the current locale, the functions return the number of unconvertible characters. Each unconvertible character is converted to a string in the current locale that is specific to the current locale. @@ -716,14 +781,17 @@ use .PN XDefaultString . Otherwise, -.PN XmbTextPropertyToTextList -and +.PN XmbTextPropertyToTextList , .PN XwcTextPropertyToTextList +and +.PN Xutf8TextPropertyToTextList return .PN Success . .LP To free the storage for the list and its contents returned by -.PN XmbTextPropertyToTextList , +.PN XmbTextPropertyToTextList +or +.PN Xutf8TextPropertyToTextList , use .PN XFreeStringList . To free the storage for the list and its contents returned by @@ -730,6 +798,12 @@ .PN XwcTextPropertyToTextList , use .PN XwcFreeStringList . +.LP +The function +.PN Xutf8TextPropertyToTextList +is an XFree86 extension introduced in XFree86 4.0.2. Its presence is +indicated by the macro +.PN X_HAVE_UTF8_STRING . .sp .LP To free the in-memory data associated with the specified @@ -901,7 +975,8 @@ The .PN XFreeStringList function releases memory allocated by -.PN XmbTextPropertyToTextList +.PN XmbTextPropertyToTextList , +.PN Xutf8TextPropertyToTextList and .PN XTextPropertyToStringList and the missing charset list allocated by @@ -2680,7 +2755,9 @@ .LP The .PN XmbSetWMProperties -function stores the standard set of window manager properties, +and +.PN Xutf8SetWMProperties +functions store the standard set of window manager properties, with text properties in standard encodings for internationalized text communication. The standard window manager properties for a given window are @@ -2687,6 +2764,7 @@ WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME. .IN "XmbSetWMProperties" "" "@DEF@" +.IN "Xutf8SetWMProperties" "" "@DEF@" .sM .FD 0 void XmbSetWMProperties\^(\^\fIdisplay\fP\^, \fIw\fP\^, \fIwindow_name\fP\^, \fIicon_name\fP\^, \fIargv\fP\^, \fIargc\fP\^, @@ -2711,6 +2789,29 @@ .br XClassHint *\fIclass_hints\fP\^; .FN +.FD 0 +void Xutf8SetWMProperties\^(\^\fIdisplay\fP\^, \fIw\fP\^, \fIwindow_name\fP\^, \fIicon_name\fP\^, \fIargv\fP\^, \fIargc\fP\^, +.br + \fInormal_hints\fP\^, \fIwm_hints\fP\^, \fIclass_hints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + char *\fIwindow_name\fP\^; +.br + char *\fIicon_name\fP\^; +.br + char *\fIargv\fP\^[]; +.br + int \fIargc\fP\^; +.br + XSizeHints *\fInormal_hints\fP\^; +.br + XWMHints *\fIwm_hints\fP\^; +.br + XClassHint *\fIclass_hints\fP\^; +.FN .IP \fIdisplay\fP 1i Specifies the connection to the X server. .IP \fIw\fP 1i @@ -2739,19 +2840,22 @@ .eM The .PN XmbSetWMProperties -convenience function provides a simple programming interface +and +.PN Xutf8SetWMProperties +convenience functions provide a simple programming interface for setting those essential window properties that are used for communicating with other clients (particularly window and session managers). .LP If the window_name argument is non-NULL, -.PN XmbSetWMProperties -sets the WM_NAME property. +they set the WM_NAME property. If the icon_name argument is non-NULL, +they set the WM_ICON_NAME property. +The window_name and icon_name arguments are null-terminated strings, for .PN XmbSetWMProperties -sets the WM_ICON_NAME property. -The window_name and icon_name arguments are null-terminated strings -in the encoding of the current locale. +in the encoding of the current locale, for +.PN Xutf8SetWMProperties +in UTF-8 encoding. 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, @@ -2759,18 +2863,24 @@ .LP If the normal_hints argument is non-NULL, .PN XmbSetWMProperties -calls +and +.PN Xutf8SetWMProperties +call .PN XSetWMNormalHints , which sets the WM_NORMAL_HINTS property (see section 14.1.7). If the wm_hints argument is non-NULL, .PN XmbSetWMProperties -calls +and +.PN Xutf8SetWMProperties +call .PN XSetWMHints , which sets the WM_HINTS property (see section 14.1.6). .LP If the argv argument is non-NULL, .PN XmbSetWMProperties -sets the WM_COMMAND property from argv and argc. +and +.PN Xutf8SetWMProperties +set the WM_COMMAND property from argv and argc. An argc of zero indicates a zero-length command. .LP The hostname of the machine is stored using @@ -2779,7 +2889,9 @@ .LP If the class_hints argument is non-NULL, .PN XmbSetWMProperties -sets the WM_CLASS property. +and +.PN Xutf8SetWMProperties +set the WM_CLASS property. If the res_name member in the .PN XClassHint structure is set to the NULL pointer and the RESOURCE_NAME @@ -2792,24 +2904,34 @@ .LP It is assumed that the supplied class_hints.res_name and argv, the RESOURCE_NAME environment variable, and the hostname of the machine -are in the encoding of the locale announced for the LC_CTYPE category -(on POSIX-compliant systems, the LC_CTYPE, else LANG environment variable). +are in the encoding of the current locale. The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties are typed according to the local host locale announcer. -No encoding conversion is performed prior to storage in the properties. +No encoding conversion is performed for these strings prior to storage +in the properties. .LP For clients that need to process the property text in a locale, .PN XmbSetWMProperties -sets the WM_LOCALE_NAME property to be the name of the current locale. +and +.PN Xutf8SetWMProperties +set 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. .LP .PN XmbSetWMProperties +and +.PN Xutf8SetWMProperties can generate .PN BadAlloc and .PN BadWindow errors. +.LP +The function +.PN Xutf8SetWMProperties +is an XFree86 extension introduced in XFree86 4.0.2. Its presence is +indicated by the macro +.PN X_HAVE_UTF8_STRING . .sp .LP To set a window's standard window manager properties diff -urwb X11R6.6/xc/doc/specs/X11/abstract.t release1/cvs-ro/xc/doc/specs/X11/abstract.t --- X11R6.6/xc/doc/specs/X11/abstract.t Thu Apr 13 09:38:16 2000 +++ release1/cvs-ro/xc/doc/specs/X11/abstract.t Wed Nov 26 14:48:18 2003 @@ -1,3 +1,4 @@ +.\" $XFree86: xc/doc/specs/X11/abstract.t,v 1.2 2003/07/09 15:27:26 tsi Exp $ .EH '''' .OH '''' .EF '''' @@ -11,7 +12,7 @@ \s+1\fBX Consortium Standard\fP\s-1 -\s+1\fBX Version 11, Release 6.4\fP\s-1 +\s+1\fBX Version 11, Release 6.7\fP\s-1 .sp 6 .ce 4 \s-1James Gettys @@ -33,7 +34,7 @@ .sp 1 Vania Joloboff, Open Software Foundation .sp 1 -Hideki Hiura, SunSoft, Inc. +Hideki Hiura, Sun Microsystems, Inc. .sp 1 Bill McMahon, Hewlett-Packard Company .sp 1 @@ -50,12 +51,13 @@ .nr PS 9 .sp 8 .LP -The X Window System is a trademark of X Consortium, Inc. +The X Window System is a trademark of The Open Group. .LP TekHVC is a trademark of Tektronix, Inc. .sp 2 .LP -Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994,1996 X Consortium +Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2002 +The Open Group .LP Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -76,10 +78,10 @@ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. .LP -Except as contained in this notice, the name of the X Consortium shall +Except as contained in this notice, the name of The Open Group shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization -from the X Consortium. +from The Open Group. .sp 3 .LP Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by diff -urwb X11R6.6/xc/doc/specs/X11/glossary release1/cvs-ro/xc/doc/specs/X11/glossary --- X11R6.6/xc/doc/specs/X11/glossary Thu Apr 13 09:38:16 2000 +++ release1/cvs-ro/xc/doc/specs/X11/glossary Mon Nov 17 11:03:19 2003 @@ -1,3 +1,6 @@ +.\" +.\" $XFree86: xc/doc/specs/X11/glossary,v 1.2 2000/11/28 18:49:19 dawes Exp $ +.\" \& .sp 1 .ce 1 @@ -402,7 +405,7 @@ The representations do not have to be of uniform length. 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. +sets, the X Compound Text encoding, and the UTF-8 ISO10646/Unicode encoding. .IP In X, encodings are identified by a string which appears as: the