home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xlib / CH13 < prev    next >
Encoding:
Text File  |  1991-08-27  |  126.8 KB  |  4,684 lines
  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBChapter 13\fP\s-1
  5.  
  6. \s+1\fBLocales and Internationalized Text Functions\fP\s-1
  7. .sp 2
  8. .nr H1 13
  9. .nr H2 0
  10. .nr H3 0
  11. .nr H4 0
  12. .nr H5 0
  13. .na
  14. .LP
  15. .XS
  16. Chapter 13: Locales and Internationalized Text Functions
  17. .XE
  18. An internationalized application is one which is adaptable to the requirements
  19. of different native languages, local customs, and character string encodings.
  20. The process of adapting the operation to a particular native language,
  21. local custom, or string encoding is called localizaton.
  22. A goal of internationalization is to permit localization
  23. without program source modifications or recompilation.
  24. .LP
  25. Internationalization in X is based on the concept of a \fIlocale\fP.
  26. A locale defines the ``localized'' behavior of a program at run-time.
  27. Locales affect Xlib in its:
  28. .IP \(bu 5
  29. Encoding and processing of input method text
  30. .IP \(bu 5
  31. Encoding of resource files and values
  32. .IP \(bu 5
  33. Encoding and imaging of text strings
  34. .IP \(bu 5
  35. Encoding and decoding for inter-client text communication
  36. .LP
  37. Characters from various languages are represented in a computer
  38. using an encoding.
  39. Different languages have different encodings,
  40. and there are even different encodings for the same characters
  41. in the same language.
  42. .LP
  43. This chapter defines support for localized text imaging and text input,
  44. and the locale mechanism which controls all locale-dependent Xlib functions.
  45. Sets of functions are provided for multibyte (char *) text as well as
  46. wide character (wchar_t) text in the form supported 
  47. by the host C language environment.
  48. The multibyte and wide character functions
  49. are equivalent except for the form of the text argument.
  50. .LP
  51. The Xlib internationalization functions are not meant to provide
  52. support for multilingual applications (mixing multiple languages
  53. within a single piece of text), but they make it possible to
  54. implement applications that work in limited fashion with more than
  55. one language in independent contexts.
  56. .NH 2
  57. X Locale Management
  58. .XS
  59. \*(SN X Locale Management
  60. .XE
  61. .LP
  62. X supports a one or more of the locales defined by the host environment.
  63. On implementations that conform to the ANSI C library,
  64. the locale announcement method is
  65. .PN setlocale .
  66. This function configures the locale operation of both
  67. the host C library and Xlib.
  68. The operation of Xlib is governed by the LC_CTYPE category;
  69. this is called the \fIcurrent locale\fP.
  70. An implementation is permitted to provide implementation-dependent
  71. mechanisms for announcing the locale in addition to
  72. .PN setlocale .
  73. .LP
  74. On implementations that do not conform to the ANSI C library, 
  75. the locale announcement method is Xlib implementation-dependent.
  76. .LP
  77. The mechanism by which the semantic operation of Xlib is defined
  78. for a specific locale is implementation-dependent.
  79. .LP
  80. .sp
  81. X is not required to support all the locales supported by the host.
  82. To determine if the current locale is supported by X, 
  83. use
  84. .PN XSupportsLocale .
  85. .IN "XSupportsLocale" "" "@DEF@"
  86. .\" Start marker code here
  87. .FD 0
  88. Bool XSupportsLocale\^(\|)
  89. .FN
  90. .\" End marker code here
  91. .LP
  92. The 
  93. .PN XSupportsLocale
  94. function returns 
  95. .PN True
  96. if Xlib functions are capable of operating under the current locale.
  97. If it returns 
  98. .PN False ,
  99. Xlib locale-dependent functions for which the 
  100. .PN XLocaleNotSupported 
  101. return status is defined will return 
  102. .PN XLocaleNotSupported .
  103. Other Xlib locale-dependent routines will operate in the ``C'' locale.
  104. .LP
  105. The client is responsible for selecting its locale and X modifiers.
  106. Clients should provide a means for the user to override the clients'
  107. locale selection at client invocation.
  108. Most single-display X clients operate in a single locale 
  109. for both X and the host processing environment.
  110. They will configure the locale by calling three functions: 
  111. the host locale configuration function,
  112. .PN XSupportsLocale ,
  113. and 
  114. .PN XSetLocaleModifiers .
  115. .LP
  116. The semantics of certain categories of X internationalization capabilities
  117. can be configured by setting modifiers.
  118. Modifiers are named by implementation-dependent and locale-specific strings.
  119. The only standard use for this capability at present
  120. is selecting one of several styles of keyboard input method.
  121. .LP
  122. .sp
  123. To configure Xlib locale modifiers for the current locale, use
  124. .PN XSetLocaleModifiers .
  125. .IN "XSetLocaleModifiers" "" "@DEF@"
  126. .\" Start marker code here
  127. .FD 0
  128. char *XSetLocaleModifiers\^(\^\fImodifier_list\fP\^)
  129. .br
  130.       char *\fImodifier_list\fP\^;
  131. .FN
  132. .IP \fImodifier_list\fP 1i
  133. Specifies the modifiers.
  134. .\" End marker code here
  135. .LP
  136. .PN XSetLocaleModifiers
  137. sets the X modifiers for the current locale setting.
  138. The modifier_list argument is a null-terminated string of the form
  139. ``{@\^\fIcategory\fP\^=\^\fIvalue\fP\^}'', that is,
  140. having zero or more concatenated ``@\^\fIcategory\fP\^=\^\fIvalue\fP\^''
  141. entries where \fIcategory\fP is a category name 
  142. and \fIvalue\fP is the (possibly empty) setting for that category.
  143. The values are encoded in the current locale.
  144. Category names are restricted to the POSIX Portable Filename Character Set.
  145. .LP
  146. The local host X locale modifiers announcer (on POSIX-compliant systems,
  147. the XMODIFIERS environment variable) is appended to the modifier_list to
  148. provide default values on the local host.
  149. If a given category appears more than once in the list,
  150. the first setting in the list is used.
  151. If a given category is not included in the full modifier list,
  152. the category is set to an implementation-dependent default for the current locale.
  153. An empty value for a category explicitly specifies the
  154. implementation-dependent default.
  155. .LP
  156. If the function is successful, it returns a pointer to a string.  The contents
  157. of the string are such that a subsequent call with that string (in the same
  158. locale) will restore the modifiers to the same settings.  If modifier_list is
  159. a NULL pointer,
  160. .PN XSetLocaleModifiers
  161. also returns a pointer to such a string,
  162. and the current locale modifiers are not changed.
  163. .LP
  164. If invalid values are given for one or more modifier categories supported by
  165. the locale, a NULL pointer is returned, and none of the
  166. current modifiers are changed.
  167. .LP
  168. At program startup the modifiers that are in effect are unspecified until
  169. the first successful call to set them.  Whenever the locale is changed, the
  170. modifiers that are in effect become unspecified until the next successful call
  171. to set them.
  172. Clients should always call
  173. .PN XSetLocaleModifiers
  174. with a non-NULL modifier_list after setting the locale,
  175. before they call any locale-dependent Xlib routine.
  176. .LP
  177. The only standard modifier category currently defined is ``im'',
  178. which identifies the desired input method.
  179. The values for input method are not standardized.
  180. A single locale may use multiple input methods,
  181. switching input method under user control.
  182. The modifier may specify the initial input method in effect, 
  183. or an ordered list of input methods.
  184. Multiple input methods may be specified in a single im value string
  185. in an implementation-dependent manner.
  186. .LP
  187. The returned modifiers string is owned by Xlib and should not be modified or
  188. freed by the client.
  189. It may be freed by Xlib after the current locale or modifiers is changed.
  190. Until freed, it will not be modified by Xlib.
  191. .LP
  192. The recommended procedure for clients initializing their locale and modifiers
  193. is to obtain locale and modifier announcers separately from
  194. one of the following prioritized sources:
  195. .IP \(bu 5
  196. A command line option
  197. .IP \(bu 5
  198. A resource
  199. .IP \(bu 5
  200. The empty string ("")
  201. .LP
  202. The first of these that is defined should be used.
  203. Note that when a locale command line option or locale resource is defined,
  204. the effect should be to set all categories to the specified locale,
  205. overriding any category-specific settings in the local host environment.
  206. .NH 2
  207. Locale and Modifier Dependencies
  208. .XS
  209. \*(SN Locale and Modifier Dependencies
  210. .XE
  211. .LP
  212. The internationalized Xlib functions operate in the current locale
  213. configured by the host environment and X locale modifiers set by
  214. .PN XSetLocaleModifiers , 
  215. or in the locale and modifiers configured at the time
  216. some object supplied to the function was created.
  217. For each locale-dependent function,
  218. the following table describes the locale (and modifiers) dependency:
  219. .TS H
  220. lw(1.25i) lw(2.5i) lw(2i).
  221. _
  222. .sp 6p
  223. .B
  224. locale from...    Affects the function...    in the...
  225. .sp 6p
  226. _
  227. .sp 6p
  228. .TH
  229. .R
  230.     Locale Query/Configuration:
  231. .sp 6p
  232. T{
  233. .PN setlocale
  234. T}    T{
  235. .PN XSupportsLocale
  236. T}    T{
  237. locale queried
  238. T}
  239.     T{
  240. .PN XSetLocaleModifiers
  241. T}    T{
  242. locale modified
  243. T}
  244. .sp
  245.     Resources:
  246. .sp 6p
  247. T{
  248. .PN setlocale
  249. T}    T{
  250. .PN XrmGetFileDatabase
  251. T}    T{
  252. locale of 
  253. .PN XrmDatabase
  254. T}
  255.     T{
  256. .PN XrmGetStringDatabase
  257. T}
  258. T{
  259. .PN XrmDatabase
  260. T}    T{
  261. .PN XrmPutFileDatabase
  262. T}    T{
  263. locale of 
  264. .PN XrmDatabase
  265. T}
  266.     T{
  267. .PN XrmLocaleOfDatabase
  268. T}
  269. .sp
  270.     Setting Standard Properties:
  271. .sp 6p
  272. T{
  273. .PN setlocale
  274. T}    T{
  275. .PN XmbSetWMProperties
  276. T}    T{
  277. encoding of supplied/returned
  278. T}
  279.         text (some WM_ property
  280.         text in environment locale)
  281. .sp 6p
  282. T{
  283. .PN setlocale
  284. T}    T{
  285. .PN XmbTextPropertyToTextList
  286. T}    T{
  287. encoding of supplied/returned text
  288. T}
  289.     T{
  290. .PN XwcTextPropertyToTextList
  291. T}
  292.     T{
  293. .PN XmbTextListToTextProperty
  294. T}
  295.     T{
  296. .PN XwcTextListToTextProperty
  297. T}
  298. .sp
  299.     Text Input:
  300. .sp 6p
  301. T{
  302. .PN setlocale
  303. T}    T{
  304. .PN XOpenIM
  305. T}    T{
  306. XIM input method selection
  307. T}
  308. T{
  309. .PN XIM
  310. T}    T{
  311. .PN XCreateIC
  312. T}    T{
  313. XIC input method configuration
  314. T}
  315.     T{
  316. .PN XLocaleOfIM , 
  317. etc.
  318. T}    T{
  319. queried locale
  320. T}
  321. T{
  322. .PN XIC
  323. T}    T{
  324. .PN XmbLookupText
  325. T}    T{
  326. keyboard layout,
  327. T}
  328.     T{
  329. .PN XwcLookupText
  330. T}    T{
  331. encoding of returned text
  332. T}
  333. .sp
  334.     Text Drawing:
  335. .sp 6p
  336. T{
  337. .PN setlocale
  338. T}    T{
  339. .PN XCreateFontSet
  340. T}    T{
  341. charsets of fonts in 
  342. .PN XFontSet
  343. T}
  344. T{
  345. .PN XFontSet
  346. T}    T{
  347. .PN XmbDrawText ,
  348. T}    T{
  349. locale of supplied text,
  350. T}
  351.     T{
  352. .PN XwcDrawText ,
  353. etc.
  354. T}    T{
  355. locale of supplied text,
  356. T}
  357.     T{
  358. .PN XExtentsOfFontSet ,
  359. etc.
  360. T}    T{
  361. locale-dependent metrics
  362. T}
  363.     T{
  364. .PN XmbTextExtents ,
  365. T}
  366.     T{
  367. .PN XwcTextExtents , 
  368. etc.
  369. T}
  370. .sp
  371.     Xlib Errors:
  372. .sp 6p
  373. T{
  374. .PN setlocale
  375. T}    T{
  376. .PN XGetErrorDatabaseText
  377. T}    T{
  378. locale of error message
  379. T}
  380.     T{
  381. .PN XGetErrorText
  382. T}
  383. .sp 6p
  384. _
  385. .TE
  386. .LP
  387. Clients may assume that a locale-encoded text string returned 
  388. by an X routine can be passed to a C-library routine, or vice-versa,
  389. if the locale is the same at the two calls.
  390. .LP
  391. All text strings processed by internationalized Xlib functions are assumed
  392. to begin in the initial state of the encoding of the locale, if the encoding
  393. is state-dependent.
  394. .LP
  395. All Xlib routines behave as if they do not change the current locale
  396. or X modifier setting.
  397. (This means that if they do change locale or call 
  398. .PN XSetLocaleModifiers
  399. with a non-NULL argument, they must save and restore the current state on
  400. entry and exit.)
  401. Also, Xlib functions on implementations that conform to the ANSI C library do
  402. not alter the global state associated with the ANSI C functions 
  403. .PN mblen , 
  404. .PN mbtowc , 
  405. .PN wctomb ,
  406. and 
  407. .PN strtok .
  408. .NH 2
  409. Creating and Freeing a Font Set
  410. .XS
  411. \*(SN Creating and Freeing a Font Set
  412. .XE
  413. .LP
  414. Xlib international text drawing is done using a set of one or more fonts,
  415. as needed for the locale of the text.
  416. Fonts are loaded according to a list of base font names 
  417. supplied by the client, and the charsets required by the locale.
  418. The 
  419. .PN XFontSet
  420. is an opaque type.
  421. .LP
  422. .sp
  423. To create an international text drawing font set, use 
  424. .PN XCreateFontSet .
  425. .IN "XCreateFontSet" "" "@DEF@"
  426. .\" Start marker code here
  427. .FD 0
  428. XFontSet XCreateFontSet\^(\^\fIdisplay\fP\^, \fIbase_font_name_list\fP\^, \fImissing_charset_list_return\fP\^,
  429. .br
  430.                \fImissing_charset_count_return\fP\^, \fIdef_string_return\fP\^)
  431. .br
  432.       Display *\fIdisplay\fP\^;
  433. .br
  434.       char *\fIbase_font_name_list\fP\^;
  435. .br
  436.       char ***\fImissing_charset_list_return\fP\^;
  437. .br
  438.       int *\fImissing_charset_count_return\fP\^;
  439. .br
  440.       char **\fIdef_string_return\fP\^;
  441. .FN
  442. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  443. .IP \fIdisplay\fP 1i
  444. Specifies the connection to the X server.
  445. .IP \fIbase_font_name_list\fP 1i
  446. Specifies the base font names.
  447. .IP \fImissing_charset_list_return\fP 1i
  448. Returns the missing charsets.
  449. .IP \fImissing_charset_count_return\fP 1i
  450. Returns the number of missing charsets.
  451. .IP \fIdef_string_return\fP 1i
  452. Returns the string drawn for missing charsets.
  453. .\" End marker code here
  454. .LP
  455. The 
  456. .PN XCreateFontSet
  457. function creates a font set for the specified display.
  458. The font set is bound to the current locale when 
  459. .PN XCreateFontSet
  460. is called.
  461. The font_set may be used in subsequent calls to obtain font
  462. and character information, and to image text in the locale of the font_set.
  463. .LP
  464. The base_font_name_list argument is a list of base font names which Xlib uses
  465. to load the fonts needed for the locale.
  466. The base font names are a comma-separated list.  The string is null-terminated,
  467. and is assumed to be in the Host Portable Character Encoding; 
  468. otherwise, the result is implementation dependent.
  469. Whitespace immediately on either side of a separating comma is ignored.
  470. .LP
  471. Use of XLFD font names permits Xlib to obtain the fonts needed for a
  472. variety of locales from a single locale-independent base font name.
  473. The single base font name should name a family of fonts whose members
  474. are encoded in the various charsets needed by the locales of interest.
  475. .LP
  476. An XLFD base font name can explicitly name a charset needed for the locale.
  477. This allows the user to specify an exact font for use with a charset required
  478. by a locale, fully controlling the font selection.
  479. .LP
  480. If a base font name is not an XLFD name,
  481. Xlib will attempt to obtain an XLFD name from the font properties
  482. for the font.
  483. If this action is successful in obtaining an XLFD name, the
  484. .PN XBaseFontNameListOfFontSet
  485. function will return this XLFD name instead of the client-supplied name.
  486. .LP
  487. The following algorithm is used to select the fonts that will be used to
  488. display text with the 
  489. .PN XFontSet :
  490. .LP
  491. For each font charset required by the locale,
  492. the base font name list is searched for the first one 
  493. of the following cases that names a set of fonts that exist at the server:
  494. .IP 1. 5
  495. The first XLFD-conforming base font name that specifies the required
  496. charset or a superset of the required charset in its 
  497. .PN CharSetRegistry
  498. and 
  499. .PN CharSetEncoding
  500. fields.
  501. The implementation may use a base font name whose specified charset
  502. is a superset of the required charset, for example,
  503. an ISO8859-1 font for an ASCII charset.
  504. .IP 2. 5
  505. The first set of one or more XLFD-conforming base font names
  506. that specify one or more charsets that can be remapped to support the
  507. required charset.
  508. The Xlib implementation may recognize various mappings 
  509. from a required charset to one or more other charsets,
  510. and use the fonts for those charsets.
  511. For example, JIS Roman is ASCII with tilde and backslash replaced 
  512. by yen and overbar;
  513. Xlib may load an ISO8859-1 font to support this character set,
  514. if a JIS Roman font is not available.
  515. .IP 3. 5
  516. The first XLFD-conforming font name, or the first non-XLFD font name
  517. for which an XLFD font name can be obtained, combined with the
  518. required charset (replacing the 
  519. .PN CharSetRegistry
  520. and
  521. .PN CharSetEncoding
  522. fields in the XLFD font name).
  523. As in case 1,
  524. the implementation may use a charset which is a superset
  525. of the required charset.
  526. .IP 4. 5
  527. The first font name that can be mapped in some implementation-dependent
  528. manner to one or more fonts that support imaging text in the charset.
  529. .LP
  530. For example, assume a locale required the charsets:
  531. .LP
  532. .Ds 0
  533. ISO8859-1
  534. JISX0208.1983
  535. JISX0201.1976
  536. GB2312-1980.0
  537. .De
  538. .LP
  539. The user could supply a base_font_name_list which explicitly specifies the
  540. charsets, insuring that specific fonts get used if they exist:
  541. .LP
  542. .Ds 0
  543. "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\
  544. -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\
  545. -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\
  546. -Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
  547. .De
  548. .LP
  549. Or he could supply a base_font_name_list which omits the charsets,
  550. letting Xlib select font charsets required for the locale:
  551. .LP
  552. .Ds 0
  553. "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
  554. -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\
  555. -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
  556. -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
  557. .De
  558. .LP
  559. Or he could simply supply a single base font name which allows Xlib
  560. to select from all available fonts which meet certain minimum XLFD
  561. property requirements:
  562. .LP
  563. .Ds 0
  564. "-*-*-*-R-Normal--*-180-100-100-*-*"
  565. .De
  566. .LP
  567. If 
  568. .PN XCreateFontSet
  569. is unable to create the font set, 
  570. either because there is insufficient memory or because the current locale
  571. is not supported,
  572. .PN XCreateFontSet
  573. returns NULL, missing_charset_list_return is set to NULL,
  574. and missing_charset_count_return
  575. is set to zero.
  576. If fonts exist for all of the charsets required by the current locale,
  577. .PN XCreateFontSet
  578. returns a valid
  579. .PN XFontSet ,
  580. missing_charset_list_return is set to NULL,
  581. and missing_charset_count_return is set to zero.
  582. .LP
  583. If no font exists for one or more of the required charsets,
  584. .PN XCreateFontSet
  585. sets missing_charset_list_return to a
  586. list of one or more null-terminated charset names for which no font exists, 
  587. and sets missing_charset_count_return to the number of missing fonts.
  588. The charsets are from the list of the required charsets for
  589. the encoding of the locale, and do not include any charsets to which Xlib
  590. may be able to remap a required charset.
  591. .LP
  592. If no font exists for any of the required charsets,
  593. or if the locale definition in Xlib requires that a font exist
  594. for a particular charset and a font is not found for that charset, 
  595. .PN XCreateFontSet
  596. returns NULL.
  597. Otherwise, 
  598. .PN XCreateFontSet
  599. returns a valid 
  600. .PN XFontSet
  601. to font_set.
  602. .LP
  603. When an Xmb/wc drawing or measuring function is called with an
  604. .PN XFontSet
  605. that has missing charsets, some characters in the locale will not be
  606. drawable.
  607. If def_string_return is non-NULL,
  608. .PN XCreateFontSet
  609. returns a pointer to a string which represents the glyph(s)
  610. which are drawn with this 
  611. .PN XFontSet
  612. when the charsets of the available fonts do not include all font glyph(s)
  613. required to draw a codepoint.
  614. The string does not necessarily consist of valid characters 
  615. in the current locale and is not necessarily drawn with
  616. the fonts loaded for the font set,
  617. but the client can draw and measure the ``default glyphs'' 
  618. by including this string in a string being drawn or measured with the 
  619. .PN XFontSet .
  620. .LP
  621. If the string returned to def_string_return is the empty string (""),
  622. no glyphs are drawn, and the escapement is zero.
  623. The returned string is null-terminated.
  624. It is owned by Xlib and should not be modified or freed by the client.
  625. It will be freed by a call to 
  626. .PN XFreeFontSet
  627. with the associated 
  628. .PN XFontSet .
  629. Until freed, its contents will not be modified by Xlib.
  630. .LP
  631. The client is responsible for constructing an error message from the
  632. missing charset and default string information, and may choose to continue
  633. operation in the case that some fonts did not exist.
  634. .LP
  635. The returned 
  636. .PN XFontSet
  637. and missing charset list should be freed with 
  638. .PN XFreeFontSet
  639. and
  640. .PN XFreeStringList ,
  641. respectively.
  642. The client-supplied base_font_name_list may be freed 
  643. by the client after calling 
  644. .PN XCreateFontSet .
  645. .LP
  646. .sp
  647. To obtains a list of 
  648. .PN XFontStruct
  649. structures and full font names given an 
  650. .PN XFontSet ,
  651. use
  652. .PN XFontsOfFontSet .
  653. .IN "XFontsOfFontSet" "" "@DEF@"
  654. .\" Start marker code here
  655. .FD 0
  656. int XFontsOfFontSet\^(\^\fIfont_set\fP\^, \fIfont_struct_list_return\fP\^, \fIfont_name_list_return\fP\^)
  657. .br
  658.        XFontSet \fIfont_set\fP\^;
  659. .br
  660.        XFontStruct ***\fIfont_struct_list_return\fP\^;
  661. .br
  662.        char ***\fIfont_name_list_return\fP\^;
  663. .FN
  664. .\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
  665. .IP \fIfont_set\fP 1i
  666. Specifies the font set.
  667. .IP \fIfont_struct_list_return\fP 1i
  668. Returns the list of font structs.
  669. .IP \fIfont_name_list_return\fP 1i
  670. Returns the list of font names.
  671. .\" End marker code here
  672. .LP
  673. The
  674. .PN XFontsOfFontSet
  675. function returns a list of one or more 
  676. .PN XFontStructs
  677. and font names for the fonts used by the Xmb and Xwc layers,
  678. for the given font set.
  679. A list of pointers to the
  680. .PN XFontStruct
  681. structures is returned to font_struct_list_return.
  682. A list of pointers to null-terminated fully specified font name strings
  683. in the locale of the font set is returned to font_name_list_return.
  684. The font_name_list order corresponds to the font_struct_list order.
  685. The number of
  686. .PN XFontStruct
  687. structures and font names is returned as the value of the function.
  688. .LP
  689. Because it is not guaranteed that a given character will be imaged using a
  690. single font glyph,
  691. there is no provision for mapping a character or default string 
  692. to the font properties, font ID, or direction hint for the font 
  693. for the character.
  694. The client may access the 
  695. .PN XFontStruct
  696. list to obtain these values for all the fonts currently in use.
  697. .LP
  698. It is not required that fonts be loaded from the server at the creation of an 
  699. .PN XFontSet .
  700. Xlib may choose to cache font data, loading it only as needed to draw text 
  701. or compute text dimensions.
  702. Therefore, existence of the per_char metrics in the 
  703. .PN XFontStruct
  704. structures in the
  705. .PN XFontStructSet
  706. is undefined.
  707. Also, note that all properties in the 
  708. .PN XFontStruct
  709. structures are in the STRING encoding.
  710. .LP
  711. The 
  712. .PN XFontStruct
  713. and font name lists are owned by Xlib 
  714. and should not be modified or freed by the client.
  715. They will be freed by a call to
  716. .PN XFreeFontSet
  717. with the associated
  718. .PN XFontSet .
  719. Until freed, its contents will not be modified by Xlib.
  720. .LP
  721. .sp
  722. To obtain the base font name list and the selected font name list given an
  723. .PN XFontSet ,
  724. use
  725. .PN XBaseFontNameListOfFontSet .
  726. .IN "XBaseFontNameListOfFontSet" "" "@DEF@"
  727. .\" Start marker code here
  728. .FD 0
  729. char *XBaseFontNameListOfFontSet\^(\^\fIfont_set\fP\^)
  730. .br
  731.       XFontSet \fIfont_set\fP\^;
  732. .FN
  733. .\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
  734. .IP \fIfont_set\fP 1i
  735. Specifies the font set.
  736. .\" End marker code here
  737. .LP
  738. The
  739. .PN XBaseFontNameListOfFontSet
  740. function returns the original base font name list supplied
  741. by the client when the 
  742. .PN XFontSet
  743. was created.
  744. A null-terminated string containing a list of
  745. comma-separated font names is returned
  746. as the value of the function.
  747. Whitespace may appear immediately on either side of separating commas.
  748. .LP
  749. If 
  750. .PN XCreateFontSet
  751. obtained an XLFD name from the font properties for the font specified
  752. by a non-XLFD base name, the
  753. .PN XBaseFontNameListOfFontSet
  754. function will return the XLFD name instead of the non-XLFD base name.
  755. .LP
  756. The base font name list is owned by Xlib and should not be modified or
  757. freed by the client.
  758. It will be freed by a call to 
  759. .PN XFreeFontSet
  760. with the associated 
  761. .PN XFontSet .
  762. Until freed, its contents will not be modified by Xlib.
  763. .LP
  764. .sp
  765. To obtain the locale name given an 
  766. .PN XFontSet ,
  767. use
  768. .PN XLocaleOfFontSet .
  769. .IN "XLocaleOfFontSet" "" "@DEF@"
  770. .\" Start marker code here
  771. .FD 0
  772. char *XLocaleOfFontSet\^(\^\fIfont_set\fP\^)
  773. .br
  774.       XFontSet \fIfont_set\fP\^;
  775. .FN
  776. .\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
  777. .IP \fIfont_set\fP 1i
  778. Specifies the font set.
  779. .\" End marker code here
  780. .LP
  781. The
  782. .PN XLocaleOfFontSet
  783. function
  784. returns the name of the locale bound to the specified
  785. .PN XFontSet ,
  786. as a null-terminated string.
  787. .LP
  788. The returned locale name string is owned by Xlib
  789. and should not be modified or freed by the client.
  790. It may be freed by a call to
  791. .PN XFreeFontSet
  792. with the associated 
  793. .PN XFontSet .
  794. Until freed, it will not be modified by Xlib.
  795. .LP
  796. .sp
  797. To free a font set, use
  798. .PN XFreeFontSet .
  799. .IN "XFreeFontSet" "" "@DEF@"
  800. .\" Start marker code here
  801. .FD 0
  802. void XFreeFontSet\^(\^\fIdisplay\fP\^, \fIfont_set\fP\^)
  803. .br
  804.       Display *\fIdisplay\fP\^;
  805. .br
  806.       XFontSet \fIfont_set\fP\^;
  807. .FN
  808. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  809. .IP \fIdisplay\fP 1i
  810. Specifies the connection to the X server.
  811. .\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
  812. .IP \fIfont_set\fP 1i
  813. Specifies the font set.
  814. .\" End marker code here
  815. .LP
  816. The
  817. .PN XFreeFontSet
  818. function frees the specified font set.
  819. The associated base font name list, font name list, 
  820. .PN XFontStruct
  821. list, and 
  822. .PN XFontSetExtents , 
  823. if any, are freed.
  824. .NH 2
  825. Obtaining Font Set Metrics
  826. .XS
  827. \*(SN Obtaining Font Set Metrics
  828. .XE
  829. .LP
  830. Metrics for the internationalized text drawing functions 
  831. are defined in terms of a primary draw direction, 
  832. which is the default direction in which the character origin advances
  833. for each succeeding character in the string.
  834. The Xlib interface is currently defined to support only a left-to-right
  835. primary draw direction.
  836. The drawing origin is the position passed to the drawing function 
  837. when the text is drawn.
  838. The baseline is a line drawn through the drawing origin parallel
  839. to the primary draw direction.
  840. Character ink is the pixels painted in the foreground color 
  841. and does not include interline or intercharacter spacing 
  842. or image text background pixels.
  843. .LP
  844. The drawing functions are allowed to implement implicit text
  845. directionality control, reversing the order in which characters are
  846. rendered along the primary draw direction in response to locale-specific
  847. lexical analysis of the string.
  848. .LP
  849. Regardless of the character rendering order,
  850. the origins of all characters are on the primary draw direction side
  851. of the drawing origin.
  852. The screen location of a particular character image may be determined with
  853. .PN XmbTextPerCharExtents
  854. or
  855. .PN XwcTextPerCharExtents .
  856. .LP
  857. The drawing functions are allowed to implement context-dependent
  858. rendering, where the glyphs drawn for a string are not simply a
  859. concatenation of the glyphs that represent each individual character.
  860. A string of two characters drawn with 
  861. .PN XmbDrawString
  862. may render differently than if the two characters 
  863. were drawn with separate calls to
  864. .PN XmbDrawString.
  865. If the client appends or inserts a character 
  866. in a previously drawn string,
  867. the client may need to redraw some adjacent characters 
  868. in order to obtain proper rendering.
  869. .LP
  870. .sp
  871. To find out about context-dependent rendering, use
  872. .PN XContextDependentDrawing .
  873. .IN "XContextDependentDrawing" "" "@DEF@"
  874. .\" Start marker code here
  875. .FD 0
  876. Bool XContextDependentDrawing\^(\^\fIfont_set\fP\^)
  877. .br
  878.       XFontSet \fIfont_set\fP\^;
  879. .FN
  880. .\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
  881. .IP \fIfont_set\fP 1i
  882. Specifies the font set.
  883. .\" End marker code here
  884. .LP
  885. The
  886. .PN XContextDependentDrawing
  887. function returns
  888. .PN True
  889. if text drawn with the font_set might include context-dependent drawing.
  890. .LP
  891. The drawing functions do not interpret newline, tab, or other control
  892. characters.
  893. The behavior when non-printing characters other than space are drawn
  894. is implementation-dependent.
  895. It is the client's responsibility to interpret control characters
  896. in a text stream.
  897. .LP
  898. The maximum character extents for the fonts that are used by the text
  899. drawing layers may be accessed by the 
  900. .PN XFontSetExtents
  901. structure:
  902. .IN "XFontSetExtents" "" "@DEF@"
  903. .LP
  904. .Ds 0
  905. .TA .5i 3i
  906. .ta .5i 3i
  907. typedef struct {
  908.     XRectangle max_ink_extent;    /* over all drawable characters */
  909.     XRectangle max_logical_extent;    /* over all drawable characters */
  910. } XFontSetExtents;
  911. .De
  912. .LP
  913. The 
  914. .PN XRectangles
  915. used to return font set metrics are the usual Xlib screen-oriented 
  916. .PN XRectangles ,
  917. with x, y giving the upper left corner, and width and height always positive.
  918. .LP
  919. The max_ink_extent member gives the maximum extent, over all drawable characters, of
  920. the rectangles which bound the character glyph image drawn in the
  921. foreground color, relative to a constant origin.
  922. See 
  923. .PN XmbTextExtents
  924. and
  925. .PN XwcTextExtents
  926. for detailed semantics.
  927. .LP
  928. The max_logical_extent member gives the maximum extent,
  929. over all drawable characters, of the rectangles 
  930. which specify minimum spacing to other graphical features,
  931. relative to a constant origin.
  932. Other graphical features drawn by the client, for example,
  933. a border surrounding the text, should not intersect this rectangle.
  934. The max_logical_extent member should be used to compute minimum 
  935. inter-line spacing and the minimum area which must be allowed
  936. in a text field to draw a given number of arbitrary characters.
  937. .LP
  938. Due to context-dependent rendering,
  939. appending a given character to a string may increase 
  940. the string's extent by an amount which exceeds the font's max extent:
  941. .LP
  942. .Ds 0
  943. max possible added extent = (max_extent * <total # chars>) \- prev_string_extent
  944. .De
  945. .LP
  946. The rectangles for a given character in a string can be obtained from
  947. .PN XmbPerCharExtents
  948. or
  949. .PN XwcPerCharExtents .
  950. .LP
  951. .sp
  952. To obtain the maximum extents structure given an
  953. .PN XFontSet ,
  954. use
  955. .PN XExtentsOfFontSet .
  956. .IN "XExtentsOfFontSet" "" "@DEF@"
  957. .\" Start marker code here
  958. .FD 0
  959. XFontSetExtents *XExtentsOfFontSet\^(\^\fIfont_set\fP\^)
  960. .br
  961.        XFontSet \fIfont_set\fP\^;
  962. .FN
  963. .\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
  964. .IP \fIfont_set\fP 1i
  965. Specifies the font set.
  966. .\" End marker code here
  967. .LP
  968. The
  969. .PN XExtentsOfFontSet
  970. function returns an
  971. .PN XFontSetExtents
  972. structure for the fonts used by the Xmb and Xwc layers,
  973. for the given font set.
  974. .LP
  975. The 
  976. .PN XFontSetExtents
  977. structure is owned by Xlib and should not be modified
  978. or freed by the client.
  979. It will be freed by a call to 
  980. .PN XFreeFontSet
  981. with the associated 
  982. .PN XFontSet .
  983. Until freed, its contents will not be modified by Xlib.
  984. .LP
  985. .sp
  986. To obtain the escapement in pixels of the specified text as a value,
  987. use
  988. .PN XmbTextEscapement
  989. or 
  990. .PN XwcTextEscapement .
  991. .IN "XmbTextEscapement" "" "@DEF@"
  992. .IN "XwcTextEscapement" "" "@DEF@"
  993. .\" Start marker code here
  994. .FD 0
  995. int XmbTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
  996. .br
  997.       XFontSet \fIfont_set\fP\^;
  998. .br
  999.       char *\fIstring\fP\^;
  1000. .br
  1001.       int \fInum_bytes\fP\^;
  1002. .FN
  1003. .FD 0
  1004. int XwcTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
  1005. .br
  1006.       XFontSet \fIfont_set\fP\^;
  1007. .br
  1008.       wchar_t *\fIstring\fP\^;
  1009. .br
  1010.       int \fInum_wchars\fP\^;
  1011. .FN
  1012. .\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
  1013. .IP \fIfont_set\fP 1i
  1014. Specifies the font set.
  1015. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  1016. .IP \fIstring\fP 1i
  1017. Specifies the character string.
  1018. .IP \fInum_bytes\fP 1i
  1019. Specifies the number of bytes in the string argument.
  1020. .IP \fInum_wchars\fP 1i
  1021. Specifies the number of characters in the string argument.
  1022. .\" End marker code here
  1023. .LP
  1024. The
  1025. .PN XmbTextEscapement
  1026. and
  1027. .PN XwcTextEscapement
  1028. functions return the escapement in pixels of the specified string as a value,
  1029. using the fonts loaded for the specified font set.
  1030. The escapement is the distance in pixels in the primary draw
  1031. direction from the drawing origin to the origin of the next character to
  1032. be drawn, assuming that the rendering of the next character is not
  1033. dependent on the supplied string.
  1034. .LP
  1035. Regardless of the character rendering order,
  1036. the escapement is always positive.
  1037. .LP
  1038. .sp
  1039. To obtain the overall_ink_return and overall_logical_return arguments,
  1040. the overall bounding box of the string's image, and a logical bounding box,
  1041. use
  1042. .PN XmbTextExtents
  1043.  or
  1044. .PN XwcTextExtents .
  1045. .IN "XmbTextExtents" "" "@DEF@"
  1046. .IN "XwcTextExtents" "" "@DEF@"
  1047. .\" Start marker code here
  1048. .FD 0
  1049. int XmbTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIoverall_return\fP\^)
  1050. .br
  1051.       XFontSet \fIfont_set\fP\^;
  1052. .br
  1053.       char *\fIstring\fP\^;
  1054. .br
  1055.       int \fInum_bytes\fP\^;
  1056. .br
  1057.       XRectangle *\fIoverall_ink_return\fP\^;
  1058. .br
  1059.       XRectangle *\fIoverall_logical_return\fP\^;
  1060. .FN
  1061. .FD 0
  1062. int XwcTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, \fIoverall_return\fP\^)
  1063. .br
  1064.       XFontSet \fIfont_set\fP\^;
  1065. .br
  1066.       wchar_t *\fIstring\fP\^;
  1067. .br
  1068.       int \fInum_wchars\fP\^;
  1069. .br
  1070.       XRectangle *\fIoverall_ink_return\fP\^;
  1071. .br
  1072.       XRectangle *\fIoverall_logical_return\fP\^;
  1073. .FN
  1074. .\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
  1075. .IP \fIfont_set\fP 1i
  1076. Specifies the font set.
  1077. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  1078. .IP \fIstring\fP 1i
  1079. Specifies the character string.
  1080. .IP \fInum_bytes\fP 1i
  1081. Specifies the number of bytes in the string argument.
  1082. .IP \fInum_wchars\fP 1i
  1083. Specifies the number of characters in the string argument.
  1084. .ds Ov dimensions
  1085. .IP \fIoverall_ink_return\fP 1i
  1086. Returns the overall ink \*(Ov.
  1087. .IP \fIoverall_logical_return\fP 1i
  1088. Returns the overall logical \*(Ov.
  1089. .\" End marker code here
  1090. .LP
  1091. The
  1092. .PN XmbTextExtents
  1093. and
  1094. .PN XwcTextExtents
  1095. functions set the components of the specified overall_ink_return and
  1096. overall_logical_return
  1097. arguments to the overall bounding box of the string's image,
  1098. and a logical bounding box for spacing purposes, respectively.
  1099. They return the value returned by 
  1100. .PN XmbTextEscapement
  1101. or
  1102. .PN XwcTextEscapement .
  1103. These metrics are relative to the drawing origin of the string,
  1104. using the fonts loaded for the specified font set.
  1105. .LP
  1106. If the overall_ink_return argument is non-NULL,
  1107. it is set to the bounding box of the string's character ink.
  1108. Note that the overall_ink_return for a non-descending horizontally drawn
  1109. Latin character is conventionally entirely above the baseline, that is,
  1110. overall_ink_return.height <= -overall_ink_return.y.
  1111. The overall_ink_return for a nonkerned character
  1112. is entirely at and to the right of the origin, that is,
  1113. overall_ink_return.x >= 0.
  1114. A character consisting of a single pixel at the origin
  1115. would set overall_ink_return fields y = 0, x = 0, width = 1, height = 1.
  1116. .LP
  1117. If the overall_logical_return argument is non-NULL,
  1118. it is set to the bounding box which provides minimum spacing
  1119. to other graphical features for the string.
  1120. Other graphical features, for example, a border surrounding the text,
  1121. should not intersect this rectangle.
  1122. .LP
  1123. When the 
  1124. .PN XFontSet
  1125. has missing charsets,
  1126. metrics for each unavailable character are taken 
  1127. from the default string returned by 
  1128. .PN XCreateFontSet 
  1129. so that the metrics represent the text as it will actually be drawn.
  1130. The behavior for an invalid codepoint is undefined.
  1131. .LP
  1132. To determine the effective drawing origin for a character in a drawn string,
  1133. the client should call 
  1134. .PN XmbTextPerCharExtents
  1135. on the entire string, then on the character,
  1136. and subtract the x values of the returned 
  1137. .PN XRectangles
  1138. for the character.
  1139. This is useful to redraw portions of a line of text
  1140. or to justify words, but for context-dependent rendering
  1141. the client should not assume that it can redraw the character by itself
  1142. and get the same rendering.
  1143. .LP
  1144. .sp
  1145. To obtain per-character information for a text string,
  1146. use
  1147. .PN XmbTextPerCharExtents
  1148. or
  1149. .PN XwcTextPerCharExtents .
  1150. .IN "XmbTextPerCharExtents" "" "@DEF@"
  1151. .IN "XwcTextPerCharExtents" "" "@DEF@"
  1152. .\" Start marker code here
  1153. .FD 0
  1154. Status XmbTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIink_array_return\fP\^,
  1155. .br
  1156.            \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_return\fP\^)
  1157. .br
  1158.       XFontSet \fIfont_set\fP\^;
  1159. .br
  1160.       char *\fIstring\fP\^;
  1161. .br
  1162.       int \fInum_bytes\fP\^;
  1163. .br
  1164.       XRectangle *\fIink_array_return\fP\^;
  1165. .br
  1166.       XRectangle *\fIlogical_array_return\fP\^;
  1167. .br
  1168.       int \fIarray_size\fP\^;
  1169. .br
  1170.       int *\fInum_chars_return\fP\^;
  1171. .br
  1172.       XRectangle *\fIoverall_ink_return\fP\^;
  1173. .br
  1174.       XRectangle *\fIoverall_logical_return\fP\^;
  1175. .FN
  1176. .FD 0
  1177. Status XwcTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, \fIink_array_return\fP\^,
  1178. .br
  1179.           \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_return\fP\^)
  1180. .br
  1181.       XFontSet \fIfont_set\fP\^;
  1182. .br
  1183.       wchar_t *\fIstring\fP\^;
  1184. .br
  1185.       int \fInum_wchars\fP\^;
  1186. .br
  1187.       XRectangle *\fIink_array_return\fP\^;
  1188. .br
  1189.       XRectangle *\fIlogical_array_return\fP;
  1190. .br
  1191.       int \fIarray_size\fP\^;
  1192. .br
  1193.       int *\fInum_chars_return\fP\^;
  1194. .br
  1195.       XRectangle *\fIoverall_ink_return\fP\^;
  1196. .br
  1197.       XRectangle *\fIoverall_logical_return\fP\^;
  1198. .FN
  1199. .\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
  1200. .IP \fIfont_set\fP 1i
  1201. Specifies the font set.
  1202. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  1203. .IP \fIstring\fP 1i
  1204. Specifies the character string.
  1205. .IP \fInum_bytes\fP 1i
  1206. Specifies the number of bytes in the string argument.
  1207. .IP \fInum_wchars\fP 1i
  1208. Specifies the number of characters in the string argument.
  1209. .IP \fIink_array_return\fP 1i
  1210. Returns the ink dimensions for each character.
  1211. .IP \fIlogical_array_return\fP 1i
  1212. Returns the logical dimensions for each character.
  1213. .IP \fIarray_size\fP 1i
  1214. Specifies the size of ink_array_return and logical_array_return.
  1215. Note that the caller must pass in arrays of this size.
  1216. .IP \fInum_chars_return\fP 1i
  1217. Returns the number characters in the string argument.
  1218. .ds Ov extents of the entire string
  1219. .IP \fIoverall_ink_return\fP 1i
  1220. Returns the overall ink \*(Ov.
  1221. .IP \fIoverall_logical_return\fP 1i
  1222. Returns the overall logical \*(Ov.
  1223. .\" End marker code here
  1224. .LP
  1225. The
  1226. .PN XmbTextPerCharExtents
  1227. and
  1228. .PN XwcTextPerCharExtents
  1229. return the text dimensions of each character of the specified text,
  1230. using the fonts loaded for the specified font set.
  1231. Each successive element of ink_array_return and logical_array_return
  1232. is set to the successive character's drawn metrics,
  1233. relative to the drawing origin of the string, one 
  1234. .PN XRectangle
  1235. for each character in the supplied text string.
  1236. The number of elements of ink_array_return and logical_array_return
  1237. that have been set is returned to num_chars_return.
  1238. .LP
  1239. Each element of ink_array_return is set to the bounding box 
  1240. of the corresponding character's drawn foreground color.
  1241. Each element of logical_array_return is set to the bounding box 
  1242. which provides minimum spacing to other graphical features
  1243. for the corresponding character.
  1244. Other graphical features should not intersect any of the
  1245. logical_array_return rectangles.
  1246. .LP
  1247. Note that an 
  1248. .PN XRectangle
  1249. represents the effective drawing dimensions of the character,
  1250. regardless of the number of font glyphs that are used to draw
  1251. the character, or the direction in which the character is drawn.
  1252. If multiple characters map to a single character glyph,
  1253. the dimensions of all the 
  1254. .PN XRectangles
  1255. of those characters are the same.
  1256. .LP
  1257. When the 
  1258. .PN XFontSet
  1259. has missing charsets, metrics for each unavailable
  1260. character are taken from the default string returned by 
  1261. .PN XCreateFontSet ,
  1262. so that the metrics represent the text as it will actually be drawn.
  1263. The behavior for an invalid codepoint is undefined.
  1264. .LP
  1265. If the array_size is too small for the number of characters in the
  1266. supplied text, the functions return zero
  1267. and num_chars_return is set to the number of rectangles required.
  1268. Otherwise, the routines return a non-zero value.
  1269. .LP
  1270. If the overall_ink_return or overall_logical_return argument is non-NULL,
  1271. .PN XmbTextPerCharExtents
  1272. and 
  1273. .PN XwcTextPerCharExtents
  1274. return the maximum extent of the string's metrics to overall_ink_return
  1275. or overall_logical_return, as returned by 
  1276. .PN XmbTextExtents
  1277. or 
  1278. .PN XwcTextExtents .
  1279. .NH 2
  1280. Drawing Text Using Font Sets
  1281. .XS
  1282. \*(SN Drawing Text Using Font Sets
  1283. .XE
  1284. .LP
  1285. The routines defined in this section
  1286. draw text at a specified location in a drawable.
  1287. They are similar to the functions
  1288. .PN XDrawText ,
  1289. .PN XDrawString ,
  1290. and
  1291. .PN XDrawImageString
  1292. except that they work with font sets instead of single fonts,
  1293. and interpret the text based on the locale of the font set
  1294. instead of treating the bytes of the string as direct font indexes.
  1295. See section 8.6 for details of the use of GCs and possible protocol errors.
  1296. If a 
  1297. .PN BadFont
  1298. error is generated,
  1299. characters prior to the offending character may have been drawn.
  1300. .LP
  1301. The text is drawn using the fonts loaded for the specified font set;
  1302. the font in the GC is ignored, and may be modified by the routines.
  1303. No validation that all fonts conform to some width rule is performed.
  1304. .LP
  1305. The text functions
  1306. .PN XmbDrawText
  1307. and
  1308. .PN XwcDrawText
  1309. use the following structures.
  1310. .IN "XmbTextItem" "" "@DEF@"
  1311. .\" Start marker code here
  1312. .Ds 0
  1313. .TA .5i 2.5i
  1314. .ta .5i 2.5i
  1315. typedef struct {
  1316.     char *chars;    /* pointer to string */
  1317.     int nchars;    /* number of characters */
  1318.     int delta;    /* pixel delta between strings */
  1319.     XFontSet font_set;     /* fonts, None means don't change */
  1320. } XmbTextItem;
  1321. .De
  1322. .LP
  1323. .IN "XwcTextItem" "" "@DEF@"
  1324. .Ds 0
  1325. .TA .5i 2.5i
  1326. .ta .5i 2.5i
  1327. typedef struct {
  1328.     wchar_t *chars;    /* pointer to wide char string */
  1329.     int nchars;    /* number of wide characters */
  1330.     int delta;    /* pixel delta between strings */
  1331.     XFontSet font_set;    /* fonts, None means don't change */
  1332. } XwcTextItem;
  1333. .De
  1334. .\" End marker code here
  1335. .LP
  1336. .sp
  1337. To draw text using multiple font sets in a given drawable, use
  1338. .PN XmbDrawText
  1339. or
  1340. .PN XwcDrawText .
  1341. .IN "XmbDrawText" "" "@DEF@"
  1342. .IN "XwcDrawText" "" "@DEF@"
  1343. .\" Start marker code here
  1344. .FD 0
  1345. void XmbDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
  1346. .br
  1347.       Display *\fIdisplay\fP\;
  1348. .br
  1349.       Drawable \fId\fP\^;
  1350. .br
  1351.       GC \fIgc\fP\^;
  1352. .br
  1353.       int \fIx\fP\^, \fIy\fP\^;
  1354. .br
  1355.       XmbTextItem *\fIitems\fP\^;
  1356. .br
  1357.       int \fInitems\fP\^;
  1358. .FN
  1359. .FD 0
  1360. void XwcDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
  1361. .br
  1362.       Display *\fIdisplay\fP\^;
  1363. .br
  1364.       Drawable \fId\fP\^;
  1365. .br
  1366.       GC \fIgc\fP\^;
  1367. .br
  1368.       int \fIx\fP\^, \fIy\fP\^;
  1369. .br
  1370.       XwcTextItem *\fIitems\fP\^;
  1371. .br
  1372.       int \fInitems\fP\^;
  1373. .FN
  1374. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1375. .IP \fIdisplay\fP 1i
  1376. Specifies the connection to the X server.
  1377. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  1378. .IP \fId\fP 1i
  1379. Specifies the drawable. 
  1380. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1381. .IP \fIgc\fP 1i
  1382. Specifies the GC.
  1383. .ds Xy
  1384. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  1385. .IP \fIx\fP 1i
  1386. .br
  1387. .ns
  1388. .IP \fIy\fP 1i
  1389. Specify the x and y coordinates\*(Xy.
  1390. .\" $Header: items.a,v 1.1 88/02/26 10:28:21 mento Exp $
  1391. .IP \fIitems\fP 1i
  1392. Specifies an array of text items.
  1393. .\" $Header: nitems.a,v 1.1 88/02/26 10:29:33 mento Exp $
  1394. .IP \fInitems\fP 1i
  1395. Specifies the number of text items in the array.
  1396. .\" End marker code here
  1397. .LP
  1398. .PN XmbDrawText
  1399. and 
  1400. .PN XwcDrawText 
  1401. allow complex spacing and font set shifts between text strings.
  1402. Each text item is processed in turn, with the origin of a text
  1403. element advanced in the primary draw direction by the escapement of the
  1404. previous text item.
  1405. A text item delta specifies an additional escapement of the text item
  1406. drawing origin in the primary draw direction.
  1407. A font_set member other than 
  1408. .PN None
  1409. in an item causes the font set to be used for this and subsequent text items
  1410. in the text_items list.
  1411. Leading text items with font_set member set to
  1412. .PN None
  1413. will not be drawn.
  1414. .LP
  1415. .PN XmbDrawText
  1416. and
  1417. .PN XwcDrawText
  1418. do not perform any context-dependent rendering between text segments.
  1419. Clients may compute the drawing metrics by passing each text segment to
  1420. .PN XmbTextExtents
  1421. and XwcTextExtents
  1422. or 
  1423. .PN XmbTextPerCharExtents
  1424. and
  1425. .PN XwcTextPerCharExtents .
  1426. When the 
  1427. .PN XFontSet
  1428. has missing charsets, each unavailable character is drawn 
  1429. with the default string returned by 
  1430. .PN XCreateFontSet .
  1431. The behavior for an invalid codepoint is undefined.
  1432. .LP
  1433. .sp
  1434. To draw text using a single font set in a given drawable, use
  1435. .PN XmbDrawString
  1436. or
  1437. .PN XwcDrawString .
  1438. .IN "XmbDrawString" "" "@DEF@"
  1439. .IN "XwcDrawString" "" "@DEF@"
  1440. .\" Start marker code here
  1441. .FD 0
  1442. void XmbDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
  1443. .br
  1444.       Display *\fIdisplay\fP\^;
  1445. .br
  1446.       Drawable \fId\fP\^;
  1447. .br
  1448.       XFontSet \fIfont_set\fP\^;
  1449. .br
  1450.       GC \fIgc\fP\^;
  1451. .br
  1452.       int \fIx\fP\^, \fIy\fP\^;
  1453. .br
  1454.       char *\fIstring\fP\^;
  1455. .br
  1456.       int \fInum_bytes\fP\^;
  1457. .FN
  1458. .FD 0
  1459. void XwcDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
  1460. .br
  1461.       Display *\fIdisplay\fP\^;
  1462. .br
  1463.       Drawable \fId\fP\^;
  1464. .br
  1465.       XFontSet \fIfont_set\fP\^;
  1466. .br
  1467.       GC \fIgc\fP\^;
  1468. .br
  1469.       int \fIx\fP\^, \fIy\fP\^;
  1470. .br
  1471.       wchar_t *\fIstring\fP\^;
  1472. .br
  1473.       int \fInum_wchars\fP\^;
  1474. .FN
  1475. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1476. .IP \fIdisplay\fP 1i
  1477. Specifies the connection to the X server.
  1478. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  1479. .IP \fId\fP 1i
  1480. Specifies the drawable. 
  1481. .\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
  1482. .IP \fIfont_set\fP 1i
  1483. Specifies the font set.
  1484. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1485. .IP \fIgc\fP 1i
  1486. Specifies the GC.
  1487. .ds Xy
  1488. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  1489. .IP \fIx\fP 1i
  1490. .br
  1491. .ns
  1492. .IP \fIy\fP 1i
  1493. Specify the x and y coordinates\*(Xy.
  1494. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  1495. .IP \fIstring\fP 1i
  1496. Specifies the character string.
  1497. .IP \fInum_bytes\fP 1i
  1498. Specifies the number of bytes in the string argument.
  1499. .IP \fInum_wchars\fP 1i
  1500. Specifies the number of characters in the string argument.
  1501. .\" End marker code here
  1502. .LP
  1503. .PN XmbDrawString
  1504. and
  1505. .PN XwcDrawString
  1506. draw the specified text with the foreground pixel.
  1507. When the 
  1508. .PN XFontSet
  1509. has missing charsets, each unavailable character is drawn 
  1510. with the default string returned by 
  1511. .PN XCreateFontSet .
  1512. The behavior for an invalid codepoint is undefined.
  1513. .LP
  1514. .sp
  1515. To draw image text using a single font set in a given drawable, use
  1516. .PN XmbDrawImageString
  1517. or
  1518. .PN XwcDrawImageString .
  1519. .IN "XmbDrawImageString" "" "@DEF@"
  1520. .IN "XwcDrawImageString" "" "@DEF@"
  1521. .\" Start marker code here
  1522. .FD 0
  1523. void XmbDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
  1524. .br
  1525.       Display *\fIdisplay\fP\^;
  1526. .br
  1527.       Drawable \fId\fP\^;
  1528. .br
  1529.       XFontSet \fIfont_set\fP\^;
  1530. .br
  1531.       GC \fIgc\fP\^;
  1532. .br
  1533.       int \fIx\fP\^, \fIy\fP\^;
  1534. .br
  1535.       char *\fIstring\fP\^;
  1536. .br
  1537.       int \fInum_bytes\fP\^;
  1538. .FN
  1539. .FD 0
  1540. void XwcDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
  1541. .br
  1542.       Display *\fIdisplay\fP\^;
  1543. .br
  1544.       Drawable \fId\fP\^;
  1545. .br
  1546.       XFontSet \fIfont_set\fP\^;
  1547. .br
  1548.       GC \fIgc\fP\^;
  1549. .br
  1550.       int \fIx\fP\^, \fIy\fP\^;
  1551. .br
  1552.       wchar_t *\fIstring\fP\^;
  1553. .br
  1554.       int \fInum_wchars\fP\^;
  1555. .FN
  1556. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1557. .IP \fIdisplay\fP 1i
  1558. Specifies the connection to the X server.
  1559. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  1560. .IP \fId\fP 1i
  1561. Specifies the drawable. 
  1562. .\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
  1563. .IP \fIfont_set\fP 1i
  1564. Specifies the font set.
  1565. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1566. .IP \fIgc\fP 1i
  1567. Specifies the GC.
  1568. .ds Xy
  1569. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  1570. .IP \fIx\fP 1i
  1571. .br
  1572. .ns
  1573. .IP \fIy\fP 1i
  1574. Specify the x and y coordinates\*(Xy.
  1575. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  1576. .IP \fIstring\fP 1i
  1577. Specifies the character string.
  1578. .IP \fInum_bytes\fP 1i
  1579. Specifies the number of bytes in the string argument.
  1580. .IP \fInum_wchars\fP 1i
  1581. Specifies the number of characters in the string argument.
  1582. .\" End marker code here
  1583. .LP
  1584. .PN XmbDrawImageString
  1585. and
  1586. .PN XwcDrawImageString
  1587. fill a destination rectangle with the background pixel defined in the GC 
  1588. and then paint the text with the foreground pixel.
  1589. The filled rectangle is the rectangle returned to overall_logical_return by
  1590. .PN XmbTextExtents
  1591. or 
  1592. .PN XwcTextExtents
  1593. for the same text and 
  1594. .PN XFontSet .
  1595. .LP
  1596. When the 
  1597. .PN XFontSet
  1598. has missing charsets, each unavailable character is drawn 
  1599. with the default string returned by 
  1600. .PN XCreateFontSet .
  1601. The behavior for an invalid codepoint is undefined.
  1602. .NH 2 
  1603. Input Method Overview
  1604. .XS
  1605. \*(SN Input Method Overview
  1606. .XE
  1607. .LP
  1608. This section provides definitions for terms and concepts used
  1609. for internationalized text input and a brief overview of the
  1610. intended use of the mechanisms provided by Xlib.
  1611. .LP
  1612. A large number of languages in the world use alphabets
  1613. consisting of a small set of symbols (letters) to form words.
  1614. To enter text into a computer in an alphabetic language,
  1615. a user usually has a keyboard on which there exists key symbols corresponding
  1616. to the alphabet.
  1617. Sometimes, a few characters of an alphabetic language are missing
  1618. on the keyboard.
  1619. Many computer users, who speak a Latin alphabet based language 
  1620. only have a English-based keyboard.
  1621. They need to hit a combination of keystrokes in order 
  1622. to enter a character that does not exist directly on the keyboard.
  1623. A number of algorithms have been developed for entering such characters,
  1624. known as European input methods, the compose input method, 
  1625. or the dead-keys input method.
  1626. .LP
  1627. Japanese is an example of a language with a phonetic symbol set,
  1628. where each symbol represents a specific sound.
  1629. There are two phonetic symbol sets in Japanese:  Katakana and Hiragana.
  1630. In general,
  1631. Katakana is used for words that are of foreign origin,
  1632. and hiragana for writing native Japanese words.
  1633. Collectively, the two systems are called Kana.
  1634. Each set consists of 48 characters.
  1635. .LP
  1636. Korean also has a phonetic symbol set, called Hangul.
  1637. Each of the 24 basic phonetic symbols (14 consonants and 10 vowels)
  1638. represents a specific sound.
  1639. A syllable is composed of two or three parts: 
  1640. the initial consonants, the vowels, and the optional last consonants.
  1641. With Hangul,
  1642. syllables can be treated as the basic units on which text processing is done.
  1643. For example,
  1644. a delete operation may work on a phonetic symbol or a syllable.
  1645. Korean code sets include several thousands of these syllables.
  1646. A user types the phonetic symbols that make up the syllables of the words
  1647. to be entered.
  1648. The display may change as each phonetic symbol is entered.
  1649. For example,
  1650. when the second phonetic symbol of a syllable is entered,
  1651. the first phonetic symbol may change its shape and size.
  1652. Likewise, when the third phonetic symbol is entered,
  1653. the first two phonetic symbols may change their shape and size.
  1654. .LP
  1655. Not all languages rely solely on alphabetic or phonetic systems.
  1656. Some languages, including Japanese and Korean, employ an
  1657. ideographic writing system.
  1658. In an ideographic system, rather than taking a small set of
  1659. symbols and combining them in different ways to create words,
  1660. each word consists of one unique symbol (or, occasionally, several symbols).
  1661. The number of symbols may be very large: 
  1662. approximately 50,000 have been identified in Hanzi,
  1663. the Chinese ideographic system.
  1664. .LP
  1665. There are two major aspects of ideographic systems for their computer
  1666. usage.
  1667. First, the standard computer character sets in Japan, China, and Korea
  1668. include roughly 8,000 characters,
  1669. while sets in Taiwan have between 15,000 and 30,000 characters,
  1670. which make it necessary to use more than one byte to represent a character.
  1671. Second, it obviously is impractical to have a keyboard that includes
  1672. all of a given language's ideographic symbols.
  1673. Therefore a mechanism is required for entering characters
  1674. so that a keyboard with a reasonable number of keys can be used.
  1675. Those input methods are usually based on phonetics,
  1676. but there also exist methods based on the graphical properties of
  1677. characters.
  1678. .LP
  1679. In Japan, both Kana and Kanji are used.
  1680. In Korea, Hangul and sometimes Hanja are used.
  1681. Now consider entering ideographs in Japan, Korea, China, and Taiwan.
  1682. .LP
  1683. In Japan, either Kana or English characters are typed and then a region
  1684. is selected (sometimes automatically) for conversion to Kanji.
  1685. Several Kanji characters may have the same phonetic representation.
  1686. If that is the case with the string entered,
  1687. a menu of characters is presented and
  1688. the user must choose the appropriate one.
  1689. If no choice is necessary or a preference has been established,
  1690. the input method does the substitution directly.
  1691. When Latin characters are converted to Kana or Kanji,
  1692. it is called a romaji conversion.
  1693. .LP
  1694. In Korea, it is usually acceptable to keep Korean text in Hangul form,
  1695. but some people may choose to write Hanja-originated words in Hanja
  1696. rather than in Hangul.
  1697. To change Hangul to Hanja,
  1698. a region is selected for conversion
  1699. and then the same basic method as described for Japanese is followed.
  1700. .LP
  1701. Probably because there are well-accepted phonetic writing systems
  1702. for Japanese and Korean,
  1703. computer input methods in these countries for entering ideographs 
  1704. are fairly standard.
  1705. Keyboard keys have both English characters and phonetic symbols
  1706. engraved on them, and the user can switch between the two sets.
  1707. .LP
  1708. The situation is different for Chinese.
  1709. While there is a phonetic system called Pinyin promoted by authorities,
  1710. there is no consensus for entering Chinese text.
  1711. Some vendors use a phonetic decomposition (Pinyin or another),
  1712. others use ideographic decomposition of Chinese words,
  1713. with various implementations and keyboard layouts. 
  1714. There are about 16 known methods, none of which is a clear standard. 
  1715. .LP
  1716. Also, there are actually two ideographic sets used:
  1717. Traditional Chinese (the original written Chinese)
  1718. and Simplified Chinese.
  1719. Several years ago,
  1720. the People's Republic Of China launched a campaign to simplify
  1721. some ideographic characters and eliminate redundancies altogether.
  1722. Under the plan, 
  1723. characters would be streamlined every five years.
  1724. Characters have been revised several times now, 
  1725. resulting in the smaller, simpler set that makes up Simplified Chinese.
  1726. .NH 3
  1727. Input Method Architecture
  1728. .XS
  1729. \*(SN Input Method Architecture
  1730. .XE
  1731. .LP
  1732. As shown in the previous section,
  1733. there are many different input methods in use today,
  1734. each varying with language, culture, and history. 
  1735. A common feature of many input methods is that the user may type
  1736. multiple keystrokes in order to compose a single character (or set
  1737. of characters).
  1738. The process of composing characters from keystrokes is called
  1739. \fIpreediting\fP.
  1740. It may require complex algorithms and large dictionaries 
  1741. involving substantial computer resources.
  1742. .LP
  1743. Input methods may require one or more areas in which to show the
  1744. feedback of the actual keystrokes, to propose disambiguation to the
  1745. user, to list dictionaries, and so on.
  1746. The input method areas of concern are as follows.
  1747. .IP \(bu 5
  1748. The \fIStatus\fP area is intended to be a logical extension of the
  1749. LEDs that exist on the physical keyboard.
  1750. It is a window which is intended to present the internal state
  1751. of the input method that is critical to the user.
  1752. The status area may consist of text data and bitmaps or some combination.
  1753. .IP \(bu 5
  1754. The \fIPreedit\fP area is intended to display the
  1755. intermediate text for those languages that are composing prior to 
  1756. the client handling the data.   
  1757. .IP \(bu 5
  1758. The \fIAuxiliary\fP area is used for pop-up menus and customizing
  1759. dialogs that may be required for an input method.
  1760. There may be multiple Auxiliary areas for any input method.
  1761. Auxiliary areas are managed by the input method independent of the client.
  1762. Auxiliary areas are assumed to be a separate dialog which is maintained
  1763. by the input method.
  1764. .LP
  1765. There are various user interaction styles used for preediting.
  1766. The ones supported by Xlib are as follows.
  1767. .IP \(bu 5
  1768. For \fIon-the-spot\fP input methods,
  1769. preediting data will be displayed directly in the application window.
  1770. Application data is moved to allow preedit data to be displayed
  1771. at the point of insertion.
  1772. .IP \(bu 5
  1773. \fIOver-the-spot\fP preediting means that the data is displayed in
  1774. a preedit window that is placed over the point of insertion.
  1775. .IP \(bu 5
  1776. \fIOff-the-spot\fP preediting means that the preedit window is
  1777. inside the application window but not at the point of insertion.
  1778. Often, this type of window is placed at the bottom of the application window.
  1779. .IP \(bu 5
  1780. \fIRoot-window\fP preediting refers to input methods that use a preedit
  1781. window that is the child of 
  1782. .PN RootWindow .
  1783. .LP
  1784. It would require a lot of computing resources if portable applications
  1785. had to include input methods for all the languages in the world.
  1786. To avoid this,
  1787. a goal of the Xlib design is to allow an application 
  1788. to communicate with an input method placed in a separate process.
  1789. Such a process is called an \fIinput server\fR.
  1790. The server to which the application should connect is dependent on
  1791. the environment when the application is started up:
  1792. what is the user language, the actual encoding to be used for it.
  1793. The input method connection is said to be \fIlocale dependent\fR.
  1794. It is also user dependent: 
  1795. for a given language, the user can choose to some extent
  1796. the user interface style of input method (if choice is possible among
  1797. several).
  1798. .LP
  1799. Using an input server implies communication overhead,
  1800. but applications can be migrated without relinking.
  1801. Input methods can be implemented either as a
  1802. stub communicating to an input server or as a local library.
  1803. .LP
  1804. An input method may be based on a \fIfront-end\fR or a \fIback-end\fR
  1805. architecture.
  1806. In front-end, there are two separate connections to the X server:
  1807. keystrokes go directly from X server to the input method on
  1808. one connection, other events to the regular client connection.
  1809. The input method is then acting as a filter, and sends composed strings
  1810. to the client.
  1811. Front-end requires synchronization between the two connections 
  1812. to avoid lost key events or locking issues.
  1813. .LP
  1814. In back-end,
  1815. a single X server connection is used.
  1816. A dispatching mechanism must decide on this channel to delegate appropriate
  1817. keystrokes to the input method.
  1818. For instance,
  1819. it may retain a Help keystroke for its own purpose.
  1820. In the case where the input method is a separate process (that is, a server),
  1821. there must be a special communication protocol between the back-end client
  1822. and the input server.
  1823. .LP
  1824. Front-end introduces synchronization issues and filtering mechanism
  1825. for non-character keystrokes (Functions, Help, and so on).
  1826. Back-end sometimes implies more communication overhead and more process
  1827. switching.
  1828. If all three processes are running on a single workstation
  1829. (X server, input server, client), 
  1830. there are two process switches for each keystroke in back-end, 
  1831. but there is only one in frontend.
  1832. .LP
  1833. The abstraction used by a client to communicate with an input method
  1834. is an opaque data structure represented by the 
  1835. .PN XIM
  1836. data type.
  1837. This data structure is returned by the 
  1838. .PN XOpenIM
  1839. function, which opens an input method on a given display.
  1840. Subsequent operations on this data structure encapsulate all communication
  1841. between client and input method.
  1842. There is no need for an X client to use any networking library 
  1843. or natural language package in order to use an input method.
  1844. .LP
  1845. A single input server may be used for one or more languages,
  1846. supporting one or more encoding schemes.
  1847. But the strings returned from an input method will always be encoded
  1848. in the (single) locale associated with
  1849. .PN XIM
  1850. object.
  1851. .NH 3
  1852. Input Contexts
  1853. .XS
  1854. \*(SN Input Contexts
  1855. .XE
  1856. .LP
  1857. Xlib provides the ability to manage a multithreaded state for text input.
  1858. A client may be using multiple windows,
  1859. each window with multiple text entry areas,
  1860. and the user possibly switching among them at any time.
  1861. The abstraction for representing state of a particular input thread
  1862. is called an \fIinput context\fR.
  1863. The Xlib representation of an input context is an 
  1864. .PN XIC .
  1865. .LP
  1866. An input context is the abstraction retaining the state, properties,
  1867. and semantics of communication between a client and an input method.
  1868. An input context is a combination of an input method, a locale
  1869. specifying the encoding of the character strings to be returned,
  1870. a client window, internal state information
  1871. and various layout or appearance characteristics.
  1872. The input context concept somewhat matches for input the graphics context
  1873. abstraction defined for graphics output.
  1874. .LP
  1875. One input context belongs to exactly one input method.
  1876. Different input contexts may be associated with the same input method,
  1877. possibly with the same client window.
  1878. An 
  1879. .PN XIC
  1880. is created with the
  1881. .PN XCreateIC
  1882. function, providing an 
  1883. .PN XIM
  1884. argument,
  1885. affiliating the input context to the input method for its lifetime. 
  1886. When an input method is closed with 
  1887. .PN XCloseIM ,
  1888. all of its affiliated input contexts should not be used any more
  1889. (and should preferably be destroyed before closing the input method).
  1890. .LP
  1891. Considering the example of a client window with multiple text entry areas,
  1892. the application programmer could for example choose to implement:
  1893. .IP \(bu 5
  1894. As many input contexts are created as text entry areas and the client
  1895. will get the input accumulated on each context each time it will
  1896. lookup that context.
  1897. .IP \(bu 5
  1898. A single context is created for a top level window in the application.
  1899. If such window contains several text entry areas, 
  1900. each time the user moves to another text entry area,
  1901. the client has to indicate changes in the context.
  1902. .LP
  1903. A range of choices can be made by application designers to use
  1904. either a single or multiple input contexts,
  1905. according to the needs of their application.
  1906. .NH 3
  1907. Getting Keyboard Input
  1908. .XS
  1909. \*(SN Getting Keyboard Input
  1910. .XE
  1911. .LP
  1912. In order to obtain characters from an input method a client must call
  1913. the function
  1914. .PN XmbLookupString
  1915. or 
  1916. .PN XwcLookupString
  1917. with an input context created from that input method.
  1918. Both a locale and display are bound to an input method when it is opened,
  1919. and an input context inherits this locale and display.
  1920. Any strings returned by 
  1921. .PN XmbLookupString
  1922. or
  1923. .PN XwcLookupString
  1924. will be encoded in that locale. 
  1925. .NH 3 
  1926. Focus Management
  1927. .XS
  1928. \*(SN Focus Management
  1929. .XE
  1930. .LP
  1931. For each text entry area in which the
  1932. .PN XmbLookupString
  1933. or
  1934. .PN XwcLookupString
  1935. routines are used there will be an associated input context.
  1936. .LP
  1937. When the application focus moves to a text entry area,
  1938. the application must set the input context focus to the
  1939. input context associated with that area.
  1940. The input context focus is set by calling 
  1941. .PN XSetICFocus
  1942. with the appropriate input context.
  1943. .LP
  1944. Also, when the application focus moves out of a text entry area, the
  1945. application should unset the focus for the associated input context
  1946. by calling
  1947. .PN XUnsetICFocus .
  1948. As an optimization, if
  1949. .PN XSetICFocus
  1950. is called successively on two different input contexts,
  1951. setting the focus on the second 
  1952. will automatically unset the focus on the first.
  1953. .LP
  1954. Note that in order to set and unset the input context focus correctly,
  1955. it will be necessary to track application-level focus changes.
  1956. Such focus changes do not necessarily correspond to X server focus changes.
  1957. .LP
  1958. If a single input context
  1959. is being used to do input for
  1960. multiple text entry areas, it will also be necessary
  1961. to set the focus window of the
  1962. input context whenever the focus window changes
  1963. (see 
  1964. .PN XNFocusWindow
  1965. under 
  1966. .PN XSetICValues ).
  1967. .NH 3 
  1968. Geometry Management
  1969. .XS
  1970. \*(SN Geometry Management
  1971. .XE
  1972. .LP
  1973. In most input method architectures 
  1974. (on-the-spot being the notable exception),
  1975. the input method will perform the display of its own data.
  1976. In order to provide better visual locality,
  1977. it is often desirable to have the input method areas embedded within a client.
  1978. In order to do this the client may need to allocate space for an input method.
  1979. Xlib provides support that allows the size and position of input method
  1980. areas to be provided by a client.
  1981. The input method areas that are supported for geometry management
  1982. are the Status area and the Preedit area.
  1983. .LP
  1984. The fundamental concept on which geometry management for input method windows
  1985. is based is the proper division of responsibilities between the
  1986. client (or toolkit) and the input method.
  1987. The division of responsibilities is as follows:
  1988. .IP \(bu 5
  1989. The client is responsible for the geometry of the input method window.
  1990. .IP \(bu 5
  1991. The input method is responsible for the contents of the input method window.
  1992. .LP
  1993. An input method is able to suggest a size to the client,
  1994. but it cannot suggest a placement.
  1995. Also the input method can only suggest a size.
  1996. It does not determine the size,
  1997. and it must accept the size it is given.
  1998. .LP
  1999. Before a client provides geometry management for an input method,
  2000. it must determine if geometry management is needed.
  2001. The input method indicates the need for geometry management 
  2002. by setting 
  2003. .PN XIMPreeditArea
  2004. or 
  2005. .PN XIMStatusArea
  2006. in its 
  2007. .PN XIMStyles
  2008. value returned by 
  2009. .PN XGetIMValues .
  2010. When a client has decided that it will provide geometry management
  2011. for an input method, 
  2012. it indicates that decision by setting the
  2013. .PN XNInputStyle
  2014. value in the 
  2015. .PN XIC .
  2016. .LP
  2017. After a client has established with the input method
  2018. that it will will do geometry management,
  2019. the client must negotiate the geometry with the input method.
  2020. The geometry is negotiated by the following steps.
  2021. .IP \(bu 5
  2022. The client suggests an area to the input method by setting the
  2023. .PN XNAreaNeeded
  2024. value for that area.  
  2025. If the client has no constraints 
  2026. for the input method it either
  2027. will not suggest an area or
  2028. will set the width and height to zero. Otherwise it will set one of
  2029. the values.
  2030. .IP \(bu 5
  2031. The client will get the XIC value 
  2032. .PN XNAreaNeeded .
  2033. The input method will return its suggested size in this value.
  2034. The input method should pay attention to any constraints suggested by the client.
  2035. .IP \(bu 5
  2036. The client sets the XIC value
  2037. .PN XNArea
  2038. to inform the input method of the geometry of its window.  
  2039. The client should try to honor the geometry requested by the input method.
  2040. The input method must accept this geometry.
  2041. .LP
  2042. Clients doing geometry management must be aware that setting other
  2043. IC values may affect the geometry desired by an input method.
  2044. For example, 
  2045. .PN XNFontSet
  2046. and
  2047. .PN XNLineSpacing
  2048. may change the geometry desired by the the input method.  
  2049. .LP
  2050. The table of XIC values (see section 13.10)
  2051. indicates the values that can cause the desired geometry to change
  2052. when they are set.
  2053. It is the responsibility of the client to renegotiate the geometry
  2054. of the input method window when it is needed.
  2055. .LP
  2056. In addition,
  2057. a geometry management callback is provided
  2058. by which an input method can initiate a geometry change.
  2059. .NH 3
  2060. Event Filtering
  2061. .XS
  2062. \*(SN Event Filtering
  2063. .XE
  2064. .LP
  2065. A filtering mechanism is provided to allow input methods
  2066. to capture X events transparently to clients.
  2067. It is expected that toolkits (or clients) using
  2068. .PN XmbLookupString
  2069. or
  2070. .PN XwcLookupString 
  2071. will call this filter at some point in the event processing mechanism
  2072. to make sure that events needed by an input method can be filtered
  2073. by that input method.
  2074. .LP
  2075. If there were no filter,
  2076. a client could receive and discard events that are necessary
  2077. for the proper functioning of an input method.
  2078. The following provides a few examples of such events:
  2079. .IP \(bu 5
  2080. Expose events on preedit window in local mode.
  2081. .IP \(bu 5
  2082. Events may be used by an input method to communicate with an input server.
  2083. Such input server protocol related events have to be intercepted
  2084. if one does not want to disturb client code.
  2085. .IP \(bu 5
  2086. Key events can be sent to a filter before they are bound
  2087. to translations such as Xt provides.
  2088. .LP
  2089. Clients are expected to get the XIC value 
  2090. .PN XNFilterEvents
  2091. and augment the event mask for the client window with that event mask.
  2092. This mask may be zero.
  2093. .NH 3
  2094. Callbacks
  2095. .XS
  2096. \*(SN Callbacks
  2097. .XE
  2098. .LP
  2099. When an on-the-spot input method is implemented,
  2100. only the client can insert or delete preedit data in place
  2101. and possibly scroll existing text.
  2102. This means the echo of the keystrokes has to be achieved 
  2103. by the client itself, tightly coupled with the input method logic.
  2104. .LP
  2105. When a keystroke is entered,
  2106. the client calls
  2107. .PN XmbLookupString
  2108. or
  2109. .PN XwcLookupString .
  2110. At this point, in the on-the-spot case,
  2111. the echo of the keystroke in the preedit has not yet been done.
  2112. Before returning to the client logic that handles the input characters,
  2113. the lookup function
  2114. must call the echoing logic for inserting the new keystroke.
  2115. If the keystrokes entered so far make up a character,
  2116. the keystrokes entered need to be deleted,
  2117. and the composed character will be returned.
  2118. Hence, what happens is that, while being called by client code,
  2119. input method logic has to call back to the client before it returns.
  2120. The client code, that is, a callback routine,
  2121. is called from the input method logic.
  2122. .LP
  2123. There are a number of cases where the input method logic has to
  2124. call back the client.
  2125. Each of those cases is associated with a well-defined callback action.
  2126. It is possible for the client to specify, for each input context,
  2127. what callback is to be called for each action.
  2128. .LP
  2129. There are also callbacks provided for feedback of status information
  2130. and a callback to initiate a geometry request for an input method.
  2131. .NH 2
  2132. Variable Argument Lists
  2133. .XS
  2134. \*(SN Variable Argument Lists
  2135. .XE
  2136. .LP
  2137. Several input method functions have arguments which conform to ANSI C variable
  2138. argument list calling convention.
  2139. Each function denoted with a ``...'' argument takes 
  2140. a variable length list of name and value pairs where each name is a
  2141. string and each value is of type 
  2142. .PN XPointer .
  2143. The end of the list is identified by a name argument containing NULL. 
  2144. .LP
  2145. A variable length argument list may contain a nested list.
  2146. If the name 
  2147. .PN XVaNestedList
  2148. is specified in place of an argument name,
  2149. then the following value is interpreted as a 
  2150. .PN XVaNestedList
  2151. value which specifies a list of values logically inserted into the
  2152. original list at the point of declaration.
  2153. The end of a nested list is identified with a NULL.
  2154. .LP
  2155. .sp
  2156. To allocate a nested variable argument list dynamically, use
  2157. .PN XVaCreateNestedList .
  2158. .IN "XVaCreateNestedList" "" @DEF@"
  2159. .\" Start marker code here
  2160. .FD 0
  2161. typedef void * XVaNestedList;
  2162.  
  2163. XVaNestedList XVaCreateNestedList\^(\^\fIdummy\fP\^, ...)
  2164. .br
  2165.       int \fIdummy\fP\^; 
  2166. .FN
  2167. .IP \fIdummy\fP 1i
  2168. Unused argument (required by ANSI C).
  2169. .ds Al
  2170. .IP ... 1i
  2171. Specifies the variable length argument list\*(Al.
  2172. .\" End marker code here
  2173. .LP
  2174. The
  2175. .PN XVaCreateNestedList
  2176. function allocates memory and copies its arguments into
  2177. a single list pointer which may be used as value for arguments
  2178. requiring a list value.
  2179. Any entries are copied as specified.
  2180. Data passed by reference is not copied;
  2181. the caller must ensure data remains valid for the lifetime
  2182. of the nested list.
  2183. The list should be freed using
  2184. .PN XFree
  2185. when it is no longer needed.
  2186. .NH 2 
  2187. Input Method Functions
  2188. .XS
  2189. \*(SN Input Method Functions
  2190. .XE
  2191. .LP
  2192. To open a connection, use
  2193. .PN XOpenIM .
  2194. .IN "XOpenIM" "" "@DEF@"
  2195. .\" Start marker code here
  2196. .FD 0
  2197. XIM XOpenIM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^)
  2198. .br
  2199.       Display *\fIdisplay\fP\^;
  2200. .br
  2201.       XrmDataBase \fIdb\fP\^;
  2202. .br
  2203.       char *\fIres_name\fP\^;
  2204. .br
  2205.       char *\fIres_class\fP\^;
  2206. .FN
  2207. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2208. .IP \fIdisplay\fP 1i
  2209. Specifies the connection to the X server.
  2210. .IP \fIdb\fP 1i
  2211. Specifies a pointer to the resource database.
  2212. .IP \fIres_name\fP 1i
  2213. Specifies the full resource name of the application.
  2214. .IP \fIres_class\fP 1i
  2215. Specifies the full class name of the application.
  2216. .\" End marker code here
  2217. .LP
  2218. The
  2219. .PN XOpenIM
  2220. function opens an input method, 
  2221. matching the current locale and modifiers specification.
  2222. Current locale and modifiers are bound to the input method at opening time.
  2223. The locale associated with an input method cannot be changed dynamically.
  2224. This implies the strings returned by
  2225. .PN XmbLookupString
  2226. or
  2227. .PN XwcLookupString ,
  2228. for any input context affiliated with a given input method,
  2229. will be encoded in the locale current at the time input method is opened.
  2230. .LP
  2231. The specific input method to which this call will be routed
  2232. is identified on the basis of the current locale. 
  2233. .PN XOpenIM
  2234. will identify a default input method corresponding to the
  2235. current locale.
  2236. That default can be modified using 
  2237. .PN XSetLocaleModifiers
  2238. for the input method modifier.
  2239. .LP
  2240. The db argument is the resource database to be used by the input method
  2241. for looking up resources that are private to the input method.
  2242. It is not intended that this database be used to look
  2243. up values that can be set as IC values in an input context.
  2244. If db is NULL,
  2245. no data base is passed to the input method.
  2246. .LP
  2247. The res_name and res_class arguments specify the resource name 
  2248. and class of the application. 
  2249. They are intended to be used as prefixes by the input method
  2250. when looking up resources that are common to all input contexts
  2251. that may be created for this input method.
  2252. The characters used for resource names and classes must be in the
  2253. X portable character set.
  2254. The resources looked up are not fully specified
  2255. if res_name or res_class is NULL.
  2256. .LP
  2257. The res_name and res_class arguments are not assumed to exist beyond
  2258. the call to
  2259. .PN XOpenIM .
  2260. The specified resource database is assumed to exist for the lifetime
  2261. of the input method.
  2262. .LP
  2263. .PN XOpenIM
  2264. returns NULL if no input method could be opened.
  2265. .LP
  2266. .sp
  2267. To close a connection, use
  2268. .PN XCloseIM .
  2269. .IN "XCloseIM" "" "@DEF@"
  2270. .\" Start marker code here
  2271. .FD 0
  2272. Status XCloseIM\^(\^\fIim\fP\^)
  2273. .br
  2274.       XIM \fIim\fP\^;
  2275. .FN
  2276. .IP \fIim\fP 1i
  2277. Specifies the input method.
  2278. .\" End marker code here
  2279. .LP
  2280. The
  2281. .PN XCloseIM
  2282. function closes the specified input method.
  2283. .LP
  2284. .sp
  2285. To query an input method, use 
  2286. .PN XGetIMValues .
  2287. .IN "XGetIMValues" "" "@DEF@"
  2288. .\" Start marker code here
  2289. .FD 0
  2290. char * XGetIMValues\^(\^\fIim\fP\^, ...)
  2291. .br
  2292.       XIM \fIim\fP\^; 
  2293. .FN
  2294. .IP \fIim\fP 1i
  2295. Specifies the input method.
  2296. .ds Al \ to get XIM values
  2297. .IP ... 1i
  2298. Specifies the variable length argument list\*(Al.
  2299. .\" End marker code here
  2300. .LP
  2301. The
  2302. .PN XGetIMValues
  2303. function presents a variable argument list programming interface
  2304. for querying properties or features of the specified input method.
  2305. This function returns NULL if it succeeds;
  2306. otherwise,
  2307. it returns the name of the first argument that could not be obtained.
  2308. .LP
  2309. Only one standard argument is defined by Xlib:
  2310. .PN XNQueryInputStyle ,
  2311. which must be used to query about input styles supported by the input method.
  2312. .LP
  2313. A client should always query the input method to determine which styles
  2314. are supported.
  2315. The client should then find an input style it is capable of supporting.
  2316. .LP
  2317. If the client cannot find an input style that it can support
  2318. it should negotiate with the user the continuation of the program
  2319. (exit, choose another input method, and so on).
  2320. .LP
  2321. The argument value must be a pointer to a location
  2322. where the returned value will be stored.
  2323. The returned value is a pointer to a structure of type
  2324. .PN XIMStyles .
  2325. Clients are responsible for freeing the 
  2326. .PN XIMStyles
  2327. data structure.
  2328. To do so, use
  2329. .PN XFree .
  2330. .LP
  2331. The
  2332. .PN XIMStyles
  2333. structure is defined as follows.
  2334. .IN "XIMStyle" "" "@DEF@"
  2335. .IN "XIMPreeditArea" "" "@DEF@"
  2336. .IN "XIMPreeditCallbacks" "" "@DEF@"
  2337. .IN "XIMPreeditPosition" "" "@DEF@"
  2338. .IN "XIMPreeditNothing" "" "@DEF@"
  2339. .IN "XIMPreeditNone" "" "@DEF@"
  2340. .IN "XIMStatusArea" "" "@DEF@"
  2341. .IN "XIMStatusCallbacks" "" "@DEF@"
  2342. .IN "XIMStatusNothing" "" "@DEF@"
  2343. .IN "XIMStatusNone" "" "@DEF@"
  2344. .IN "XIMStyles" "" "@DEF@"
  2345. .\" Start marker code here
  2346. .Ds 0
  2347. typedef unsigned long XIMStyle;
  2348. .De
  2349. .TS
  2350. lw(.5i) lw(2i) lw(2.5i).
  2351. T{
  2352. #define
  2353. T}    T{
  2354. .PN XIMPreeditArea
  2355. T}    T{
  2356. 0x0001L
  2357. T}
  2358. T{
  2359. #define
  2360. T}    T{
  2361. .PN XIMPreeditCallbacks
  2362. T}    T{
  2363. 0x0002L
  2364. T}
  2365. T{
  2366. #define
  2367. T}    T{
  2368. .PN XIMPreeditPosition
  2369. T}    T{
  2370. 0x0004L
  2371. T}
  2372. T{
  2373. #define
  2374. T}    T{
  2375. .PN XIMPreeditNothing
  2376. T}    T{
  2377. 0x0008L
  2378. T}
  2379. T{
  2380. #define
  2381. T}    T{
  2382. .PN XIMPreeditNone
  2383. T}    T{
  2384. 0x0010L
  2385. T}
  2386. .sp
  2387. T{
  2388. #define
  2389. T}    T{
  2390. .PN XIMStatusArea
  2391. T}    T{
  2392. 0x0100L
  2393. T}
  2394. T{
  2395. #define
  2396. T}    T{
  2397. .PN XIMStatusCallbacks
  2398. T}    T{
  2399. 0x0200L
  2400. T}
  2401. T{
  2402. #define
  2403. T}    T{
  2404. .PN XIMStatusNothing
  2405. T}    T{
  2406. 0x0400L
  2407. T}
  2408. T{
  2409. #define
  2410. T}    T{
  2411. .PN XIMStatusNone
  2412. T}    T{
  2413. 0x0800L
  2414. T}
  2415. .TE
  2416. .Ds 0
  2417. .TA .5i 2.5i
  2418. .ta .5i 2.5i
  2419. typedef struct {
  2420.     unsigned short count_styles;
  2421.     XIMStyle * supported_styles;
  2422. } XIMStyles;
  2423. .De
  2424. .\" End marker code here
  2425. .LP
  2426. An 
  2427. .PN XIMStyles
  2428. structure contains in its field count_styles,
  2429. the number of input styles supported.
  2430. This is also the size of the array in the field supported_styles.
  2431. .LP
  2432. The supported styles is a list of bit mask combinations,
  2433. which indicate the combination of styles for each of the areas supported.
  2434. These areas are described below.
  2435. Each element in the list should select one of the bit mask values for
  2436. each area.
  2437. The list describes the complete set of combinations supported.
  2438. Only these combinations are supported by the input method.
  2439. .LP
  2440. The Preedit category defines what type of support is provided
  2441. by the input method for preedit information:
  2442. .IN "XIMPreeditArea" "" "@DEF@"
  2443. .IN "XIMPreeditPosition" "" "@DEF@"
  2444. .IN "XIMPreeditCallbacks" "" "@DEF@"
  2445. .IN "XIMPreeditNothing" "" "@DEF@"
  2446. .IN "XIMPreeditNone" "" "@DEF@"
  2447. .TS
  2448. lw(1.5i) lw(4.25i).
  2449. T{
  2450. .PN XIMPreeditArea 
  2451. T}    T{
  2452. If chosen,
  2453. the input method would require the client to provide some area values
  2454. for it to do its preediting.
  2455. Refer to XIC values 
  2456. .PN XNArea
  2457. and
  2458. .PN XNAreaNeeded .
  2459. T}
  2460. T{
  2461. .PN XIMPreeditPosition
  2462. T}    T{
  2463. If chosen,
  2464. the input method would require the client to provide positional values. 
  2465. Refer to XIC values 
  2466. .PN XNSpotLocation
  2467. and
  2468. .PN XNFocusWindow .
  2469. T}
  2470. T{
  2471. .PN XIMPreeditCallbacks
  2472. T}    T{
  2473. If chosen,
  2474. the input method would require the client to define the set of preedit callbacks.
  2475. Refer to XIC values 
  2476. .PN XNPreeditStartCallback ,
  2477. .PN XNPreeditDoneCallback , 
  2478. .PN XNPreeditDrawCallback ,
  2479. and
  2480. .PN XNPreeditCaretCallback .
  2481. T}
  2482. T{
  2483. .PN XIMPreeditNothing
  2484. T}    T{
  2485. If chosen, the input method can function without any Preedit values.
  2486. T}
  2487. T{
  2488. .PN XIMPreeditNone
  2489. T}    T{
  2490. The input method does not provide any Preedit feedback.
  2491. Any Preedit value is ignored.
  2492. This style is mutually exclusive with the other Preedit styles.
  2493. T}
  2494. .TE
  2495. .LP
  2496. The Status category defines what type of support is provided
  2497. by the input method for status information:
  2498. .IN "XIMStatusArea" "" "@DEF@"
  2499. .IN "XIMStatusCallbacks" "" "@DEF@"
  2500. .IN "XIMStatusNothing" "" "@DEF@"
  2501. .IN "XIMStatusNone" "" "@DEF@"
  2502. .TS
  2503. lw(1.5i) lw(4.25i).
  2504. T{
  2505. .PN XIMStatusArea
  2506. T}    T{
  2507. The input method requires the client to provide
  2508. some area values for it to do its Status feedback.
  2509. See
  2510. .PN XNArea
  2511. and
  2512. .PN XNAreaNeeded .
  2513. T}
  2514. T{
  2515. .PN XIMStatusCallbacks
  2516. T}    T{
  2517. The input method requires the client to define the set of status callbacks;
  2518. .PN XNStatusStartCallback , 
  2519. .PN XNStatusDoneCallback ,
  2520. and
  2521. .PN XNStatusDrawCallback .
  2522. T}
  2523. T{
  2524. .PN XIMStatusNothing
  2525. T}    T{
  2526. The input method can function without any Status values.
  2527. T}
  2528. T{
  2529. .PN XIMStatusNone
  2530. T}    T{
  2531. The input method does not provide any Status feedback.
  2532. If chosen, any Status value is ignored.
  2533. This style is mutually exclusive with the other Status styles.
  2534. T}
  2535. .TE
  2536. .LP
  2537. .sp
  2538. To obtain the display associated with an input method, use
  2539. .PN XDisplayOfIM .
  2540. .IN "XDisplayOfIM" "" "@DEF@"
  2541. .\" Start marker code here
  2542. .FD 0
  2543. Display * XDisplayOfIM\^(\^\fIim\fP\^)
  2544. .br
  2545.     XIM \fIim\fP\^;
  2546. .FN
  2547. .IP \fIim\fP 1i
  2548. Specifies the input method.
  2549. .\" End marker code here
  2550. .LP
  2551. The
  2552. .PN XDisplayOfIM
  2553. function returns the display associated with the specified input method.
  2554. .LP
  2555. .sp
  2556. To get the locale associated with an input method, use
  2557. .PN XLocaleOfIM .
  2558. .IN "XLocaleOfIM" "" "@DEF@"
  2559. .\" Start marker code here
  2560. .FD 0
  2561. char * XLocaleOfIM\^(\^\fIim\fP\^)
  2562. .br
  2563.       XIM \fIim\fP\^; 
  2564. .FN
  2565. .IP \fIim\fP 1i
  2566. Specifies the input method.
  2567. .\" End marker code here
  2568. .LP
  2569. The
  2570. .PN XLocaleOfIM
  2571. returns the locale associated with the specified input method.
  2572. .NH 2
  2573. Input Context Functions
  2574. .XS
  2575. \*(SN Input Context Functions
  2576. .XE
  2577. .LP
  2578. An input context is an abstraction that is used to contain both the data
  2579. required (if any) by an input method and the information required
  2580. to display that data.
  2581. There may be multiple input contexts for one input method.
  2582. The programming interfaces for creating, reading, or modifying
  2583. an input context use a variable argument list.
  2584. The name elements of the argument lists are referred to as XIC values.
  2585. It is intended that input methods be controlled by these XIC values.
  2586. As new XIC values are created they should be registered
  2587. with the X Consortium.
  2588. .LP
  2589. .sp
  2590. To create an input context use
  2591. .PN XCreateIC .
  2592. .IN "XCreateIC" "" "@DEF@"
  2593. .\" Start marker code here
  2594. .FD 0
  2595. XIC XCreateIC\^(\^\fIim\fP\^, ...)
  2596. .br
  2597.       XIM \fIim\fP\^;
  2598. .FN
  2599. .IP \fIim\fP 1i
  2600. Specifies the input method.
  2601. .ds Al \ to set XIC values
  2602. .IP ... 1i
  2603. Specifies the variable length argument list\*(Al.
  2604. .\" End marker code here
  2605. .LP
  2606. The
  2607. .PN XCreateIC 
  2608. function creates a context within the specified input method.
  2609. .LP
  2610. Some of the arguments are mandatory at creation time, and
  2611. the input context will not be created if they are not provided.
  2612. Those arguments are the input style and the set of text callbacks
  2613. (if the input style selected requires callbacks).
  2614. All other input context values can be set later.
  2615. .LP
  2616. .PN XCreateIC
  2617. returns a NULL value if no input context could be created.
  2618. A NULL value could be returned for any of the following reasons:
  2619. .IP \(bu 5
  2620. A required argument was not set.
  2621. .IP \(bu 5
  2622. A read-only argument was set (for example,
  2623. .PN XNFilterEvents ).
  2624. .IP \(bu 5
  2625. The argument name is not recognized.
  2626. .IP \(bu 5
  2627. The input method encountered an input method implementation dependent error.
  2628. .LP
  2629. .PN XCreateIC
  2630. can generate
  2631. .PN BadAtom ,
  2632. .PN BadColor ,
  2633. .PN BadPixmap ,
  2634. and
  2635. .PN BadWindow
  2636. errors.
  2637. .LP
  2638. .sp
  2639. To destroy an input context, use
  2640. .PN XDestroyIC .
  2641. .IN "XDestroyIC" "" "@DEF@"
  2642. .\" Start marker code here
  2643. .FD 0
  2644. void XDestroyIC\^(\^\fIic\fP\^)
  2645. .br
  2646.       XIC \fIic\fP\^;
  2647. .FN
  2648. .IP \fIic\fP 1i
  2649. Specifies the input context.
  2650. .\" End marker code here
  2651. .LP
  2652. .PN XDestroyIC
  2653. destroys the specified input context.
  2654. .LP
  2655. .sp
  2656. To communicate to and synchronize with input method
  2657. for any changes in keyboard focus from the client side,
  2658. use 
  2659. .PN XSetICFocus
  2660. and
  2661. .PN XUnsetICFocus .
  2662. .IN "XSetICFocus" "" "@DEF@"
  2663. .\" Start marker code here
  2664. .FD 0
  2665. void XSetICFocus\^(\^\fIic\fP\^)
  2666. .br
  2667.       XIC \fIic\fP\^; 
  2668. .FN
  2669. .IP \fIic\fP 1i
  2670. Specifies the input context.
  2671. .\" End marker code here
  2672. .LP
  2673. The
  2674. .PN XSetICFocus
  2675. function allows a client to notify an input method that the focus window
  2676. attached to the specified input context has received keyboard focus.
  2677. The input method should take action to provide appropriate feedback.
  2678. Complete feedback specification is a matter of user interface policy.
  2679. .LP
  2680. .sp
  2681. .IN "XUnsetICFocus" "" "@DEF@"
  2682. .\" Start marker code here
  2683. .FD 0
  2684. void XUnsetICFocus\^(\^\fIic\fP\^)
  2685. .br
  2686.       XIC \fIic\fP\^;
  2687. .FN
  2688. .IP \fIic\fP 1i
  2689. Specifies the input context.
  2690. .\" End marker code here
  2691. .LP
  2692. The
  2693. .PN XUnsetICFocus
  2694. function allows a client to notify an input method that the specified input context
  2695. has lost the keyboard focus and that no more input is expected on the focus window
  2696. attached to that input context.
  2697. The input method should take action to provide appropriate feedback.
  2698. Complete feedback specification is a matter of user interface policy.
  2699. .LP
  2700. .sp
  2701. To reset the state of an input context to initial state, use
  2702. .PN XmbResetIC
  2703. or
  2704. .PN XwcResetIC .
  2705. .IN "XmbResetIC" "" "@DEF@"
  2706. .IN "XwcResetIC" "" "@DE@"
  2707. .\" Start marker code here
  2708. .FD 0
  2709. char * XmbResetIC\^(\^\fIic\fP\^)
  2710. .br
  2711.       XIC \fIic\fP\^;
  2712. .FN
  2713. .FD 0
  2714. wchar_t * XwcResetIC\^(\^\fIic\fP\^)
  2715. .br
  2716.       XIC \fIic\fP\^; 
  2717. .FN
  2718. .IP \fIic\fP 1i
  2719. Specifies the input context.
  2720. .\" End marker code here
  2721. .LP
  2722. The
  2723. .PN XmbResetIC
  2724. and
  2725. .PN XwcResetIC
  2726. functions reset input context to initial state.
  2727. Any input pending on that context is deleted.
  2728. Input method is required to clear preedit area, if any,
  2729. and update status accordingly.
  2730. Calling 
  2731. .PN XmbResetIC
  2732. or
  2733. .PN XwcResetIC
  2734. does not change the focus.
  2735. .LP
  2736. The return value of
  2737. .PN XmbResetIC
  2738. is its current preedit string as a multibyte string.
  2739. The return value of
  2740. .PN XwcResetIC
  2741. is its current preedit string as a wide character string.
  2742. It is input method implementation dependent whether
  2743. these routines return a non-NULL string or NULL.
  2744. .LP
  2745. The client should free the returned string by calling
  2746. .PN XFree .
  2747. .LP
  2748. .sp
  2749. To get the input method associated with an input context, use
  2750. .PN XIMOfIC .
  2751. .IN "XIMOfIC" "" "@DEF@"
  2752. .\" Start marker code here
  2753. .FD 0
  2754. XIM XIMOfIC\^(\^\fIic\fP\^)
  2755. .br
  2756.       XIC \fIic\fP\^; 
  2757. .FN
  2758. .IP \fIic\fP 1i
  2759. Specifies the input context.
  2760. .\" End marker code here
  2761. .LP
  2762. The
  2763. .PN XIMOfIC
  2764. function returns the input method associated with the specified input context.
  2765. .LP
  2766. .sp
  2767. Xlib provides two functions for setting and reading XIC values, respectively:
  2768. .PN XSetICValues
  2769. and
  2770. .PN XGetICValues .
  2771. Both functions have a variable length argument list.
  2772. In that argument list, any XIC value's name must be denoted
  2773. with a character string using the X Portable Character Set.
  2774. .LP
  2775. .sp
  2776. To set XIC values, use
  2777. .PN XSetICValues .
  2778. .IN "XSetICValues" "" "@DEF@"
  2779. .\" Start marker code here
  2780. .FD 0
  2781. char * XSetICValues\^(\^\fIic\fP\^, ...)
  2782. .br
  2783.       XIC \fIic\fP\^;
  2784. .FN
  2785. .IP \fIic\fP 1i
  2786. Specifies the input context.
  2787. .ds Al \ to set XIC values
  2788. .IP ... 1i
  2789. Specifies the variable length argument list\*(Al.
  2790. .\" End marker code here
  2791. .LP
  2792. The
  2793. .PN XSetICValues
  2794. function returns NULL if no error occurred; 
  2795. otherwise,
  2796. it returns the name of the first argument that could not be set.
  2797. An argument could be not set for any of the following reasons:
  2798. .IP \(bu 5
  2799. A read-only argument was set (for example,
  2800. .PN XNFilterEvents ).
  2801. .IP \(bu 5
  2802. The argument name is not recognized.
  2803. .IP \(bu 5
  2804. The input method encountered an input method implementation dependent error.
  2805. .LP
  2806. Each value to be set must be an appropriate datum,
  2807. matching the data type imposed by the semantics of the argument.
  2808. .LP
  2809. .PN XSetICValues
  2810. can generate
  2811. .PN BadAtom ,
  2812. .PN BadColor ,
  2813. .PN BadCursor ,
  2814. .PN BadPixmap ,
  2815. and
  2816. .PN BadWindow 
  2817. errors.
  2818. .LP
  2819. .sp
  2820. To obtain XIC values, use
  2821. .PN XGetICValues .
  2822. .IN "XGetICValues" "" "@DEF@"
  2823. .\" Start marker code here
  2824. .FD 0
  2825. char * XGetICValues\^(\^\fIic\fP\^, ...)
  2826. .br
  2827.       XIC \fIic\fP\^;
  2828. .FN
  2829. .IP \fIic\fP 1i
  2830. Specifies the input context.
  2831. .ds Al \ to get XIC values
  2832. .IP ... 1i
  2833. Specifies the variable length argument list\*(Al.
  2834. .\" End marker code here
  2835. .LP
  2836. The
  2837. .PN XGetICValues
  2838. function returns NULL if no error occurred; otherwise,
  2839. it returns the name of the first argument that could not be obtained.
  2840. An argument could be not obtained for any of the following reasons:
  2841. .IP \(bu 5
  2842. The argument name is not recognized.
  2843. .IP \(bu 5
  2844. The input method encountered an implementation dependent error.
  2845. .LP
  2846. Each argument value
  2847. (following a name) must point to a location where the value is to be stored.
  2848. .PN XGetICValues
  2849. allocates memory to store the values, and client is responsible for
  2850. freeing each value by calling
  2851. .PN XFree .
  2852. .NH 2 
  2853. XIC Value Arguments
  2854. .XS
  2855. \*(SN XIC Value Arguments
  2856. .XE
  2857. .LP
  2858. The following tables describe how XIC values are interpreted
  2859. by an input method depending on the input style chosen by the 
  2860. user.
  2861. .LP
  2862. The first column lists the XIC values.
  2863. The second column indicates which values are involved in affecting,
  2864. negotiating, and setting the geometry of the input method windows.
  2865. The subentries under the third column indicate the different
  2866. input styles that are supported.
  2867. Each of these columns indicates how each of the XIC values 
  2868. are treated by that input style.
  2869. .LP
  2870. The following \fBKeys\fR apply to these tables.
  2871. .TS H
  2872. lw(1i) lw(4.75i).
  2873. .sp 6p
  2874. .B
  2875. Keys    Explanation
  2876. .sp 6p
  2877. .TH
  2878. .R
  2879. C    T{
  2880. This value must be set with 
  2881. .PN XCreateIC .
  2882. T}
  2883. D    T{
  2884. This value may be set using 
  2885. .PN XCreateIC .
  2886. If it is not set,
  2887. a default is provided.
  2888. T}
  2889. G    T{
  2890. This value may be read using 
  2891. .PN XGetICValues .
  2892. T}
  2893. GN    T{
  2894. This value may cause geometry negotiation when its value is set by means of
  2895. .PN XCreateIC
  2896. or
  2897. .PN XSetICValues .
  2898. T}
  2899. GR    T{
  2900. This value will be the response of the input method when any 
  2901. GN value is changed.
  2902. T}
  2903. GS    T{
  2904. This value will cause the geometry of the input method window to be set.
  2905. T}
  2906. O    T{
  2907. This value must be set once and only once.
  2908. It need not be set at create time.
  2909. T}
  2910. S    T{
  2911. This value may be set with
  2912. .PN XSetICValues .
  2913. T}
  2914. ignored    T{
  2915. This value is ignored by the input method for the given input style.
  2916. T}
  2917. .TE
  2918. .LP
  2919. .TS H
  2920. c c c s s s s
  2921. l c c c c c c
  2922. c c c c c c c
  2923. l c c c c c c.
  2924. _
  2925. .sp 6p
  2926. .B
  2927.         Input Style            
  2928. XIC Value    Geometry    Preedit    Preedit    Preedit    Preedit    Preedit
  2929.     Management    Callback    Position    Area    Nothing    None
  2930. .sp 6p
  2931. _
  2932. .sp 6p
  2933. .TH
  2934. .R
  2935. Input Style        C-G    C-G    C-G    C-G    C-G
  2936. Client Window        O-G    O-G    O-G    ignored    ignored
  2937. Focus Window    GN    D-S-G    D-S-G    D-S-G    D-S-G    ignored
  2938. Resource Name        ignored    D-S-G    D-S-G    D-S-G    ignored
  2939. Resource Class        ignored    D-S-G    D-S-G    D-S-G    ignored
  2940. Geometry Callback        ignored    ignored    D-S-G    ignored    ignored
  2941. FilterEvents        G    G    G    G    ignored
  2942. .sp 6p
  2943. \fBPreedit\fP
  2944. Area    GS    ignored    D-S-G    D-S-G    ignored    ignored
  2945. AreaNeeded    GN-GR    ignored    ignored    S-G    ignored    ignored
  2946. SpotLocation        ignored    C-S-G    ignored    ignored    ignored
  2947. Colormap        ignored    D-S-G    D-S-G    D-S-G    ignored
  2948. Foreground        ignored    D-S-G    D-S-G    D-S-G    ignored
  2949. Background        ignored    D-S-G    D-S-G    D-S-G    ignored
  2950. Background Pixmap        ignored    D-S-G    D-S-G    D-S-G    ignored
  2951. FontSet    GN    ignored    C-S-G    C-S-G    D-S-G    ignored
  2952. LineSpacing    GN    ignored    D-S-G    D-S-G    D-S-G    ignored
  2953. Cursor        ignored    D-S-G    D-S-G    D-S-G    ignored
  2954. Preedit Callbacks        C-S-G    ignored    ignored    ignored    ignored
  2955. .sp 6p
  2956. _
  2957. .TE
  2958. .TS H
  2959. c c c s s s
  2960. l c c c c c
  2961. c c c c c c 
  2962. l c c c c c.
  2963. _
  2964. .sp 6p
  2965. .B
  2966.         Input Style            
  2967. XIC Value    Geometry    Status    Status    Status    Status
  2968.     Management    Callback    Area    Nothing    None
  2969. .sp 6p
  2970. _
  2971. .sp 6p
  2972. .TH
  2973. .R
  2974. Input Style        C-G    C-G    C-G    C-G
  2975. Client Window        O-G    O-G    O-G    ignored
  2976. Focus Window    GN    D-S-G    D-S-G    D-S-G    ignored
  2977. Resource Name        ignored    D-S-G    D-S-G    ignored
  2978. Resource Class        ignored    D-S-G    D-S-G    ignored
  2979. Geometry Callback        ignored    D-S-G    ignored    ignored
  2980. FilterEvents        G    G    G    G
  2981. .sp 6p
  2982. \fBStatus\fR                    
  2983. Area    GS    ignored    D-S-G    ignored    ignored
  2984. AreaNeeded    GN-GR    ignored    S-G    ignored    ignored
  2985. Colormap        ignored    D-S-G    D-S-G    ignored
  2986. Foreground        ignored    D-S-G    D-S-G    ignored
  2987. Background        ignored    D-S-G    D-S-G    ignored
  2988. Background Pixmap        ignored    D-S-G    D-S-G    ignored
  2989. FontSet    GN    ignored    C-S-G    D-S-G    ignored
  2990. LineSpacing    GN    ignored    D-S-G    D-S-G    ignored
  2991. Cursor        ignored    D-S-G    D-S-G    ignored
  2992. Status Callbacks        C-S-G    ignored    ignored    ignored
  2993. .sp 6p
  2994. _
  2995. .TE
  2996. .NH 3 
  2997. Input Style
  2998. .XS
  2999. \*(SN Input Style
  3000. .XE
  3001. .LP
  3002. The
  3003. .PN XNInputStyle
  3004. argument specifies the input style to be used.
  3005. The value of this argument must be one of the values returned by the
  3006. .PN XGetIMValues
  3007. function with the
  3008. .PN XNQueryInputStyle
  3009. argument specified in the supported_styles list.
  3010. .LP
  3011. Note that this argument must be set at creation time
  3012. and cannot be changed.
  3013. .NH 3 
  3014. Client Window
  3015. .XS
  3016. \*(SN Client Window
  3017. .XE
  3018. .LP
  3019. .IN "XNClientWindow" "" "@DEF@"
  3020. The
  3021. .PN XNClientWindow
  3022. argument specifies to the input method the client window in
  3023. which the input method
  3024. can display data or create subwindows.
  3025. Geometry values for input method areas are given with respect to the client
  3026. window.
  3027. Dynamic change of client window is not supported.
  3028. Note that this argument may be set only once and
  3029. should be set before any input is done using this input context.
  3030. If it is not set the input method may not operate correctly.
  3031. .LP
  3032. If an attempt is made to set this value a second time with
  3033. .PN XSetICValues ,
  3034. the string
  3035. .PN XNClientWindow
  3036. will be returned by
  3037. .PN XSetICValues ,
  3038. and the client window will not be changed.
  3039. .LP
  3040. If the client window is not a valid window ID on the display
  3041. attached to the input method,
  3042. a 
  3043. .PN BadWindow 
  3044. error can be generated when this value is used by the input method.
  3045. .NH 3 
  3046. Focus Window
  3047. .XS
  3048. \*(SN Focus Window
  3049. .XE
  3050. .LP
  3051. .IN "XNFocusWindow" "" "@DEF@"
  3052. The
  3053. .PN XNFocusWindow
  3054. argument specifies the focus window.
  3055. The primary purpose of the 
  3056. .PN XNFocusWindow
  3057. is to identify the window that will receive the key event when input
  3058. is composed.
  3059. In addition, the input method may possibly affect the focus window
  3060. as follows:
  3061. .IP \(bu 5
  3062. Select events on it
  3063. .IP \(bu 5
  3064. Send events to it
  3065. .IP \(bu 5
  3066. Modify its properties
  3067. .IP \(bu 5
  3068. Grab keyboard within that window  
  3069. .LP
  3070. The value associated to the argument must be of type 
  3071. .PN Window .
  3072. If the focus window is not a valid window ID on the display 
  3073. attached to the input method,
  3074. a 
  3075. .PN BadWindow
  3076. error can be generated when this value is used by the input method.
  3077. .LP
  3078. When this XIC value is left unspecified,
  3079. the input method will default focus window to client window.
  3080. .NH 3
  3081. Resource Name and Class
  3082. .XS
  3083. \*(SN Resource Name and Class
  3084. .XE
  3085. .LP
  3086. .IN "XNResourceName" "" "@DEF@"
  3087. .IN "XNResourceClass" "" "@DEF@"
  3088. The
  3089. .PN XNResourceName
  3090. and
  3091. .PN XNResourceClass
  3092. arguments are strings that specify the full name and class
  3093. used by the client to obtain resources for the client window. 
  3094. These values should be used as prefixes for name and class
  3095. when looking up resources that may vary according to the input context.
  3096. If these values are not set,
  3097. the resources will not be fully specified.
  3098. .LP
  3099. It is not intended that values which can be set as XIC values be
  3100. set as resources.
  3101. .NH 3
  3102. Geometry Callback
  3103. .XS
  3104. \*(SN Geometry Callback
  3105. .XE
  3106. .LP
  3107. .IN "XNGeometryCallback" "" "@DEF@"
  3108. The 
  3109. .PN XNGeometryCallback
  3110. argument is a structure of type 
  3111. .PN XIMCallback 
  3112. (see section 13.10.7.10).
  3113. .LP
  3114. The 
  3115. .PN XNGeometryCallback
  3116. argument specifies the geometry callback which a client can set.
  3117. This callback is not required for correct operation of either 
  3118. an input method or a client.
  3119. It can be set for a client whose user interface policy permits
  3120. an input method to request the dynamic change of that input 
  3121. methods window.
  3122. An input method that does dynamic change will need to filter any
  3123. events that it uses to initiate the change.
  3124. .NH 3
  3125. Filter Events
  3126. .XS
  3127. \*(SN Filter Events
  3128. .XE
  3129. .LP
  3130. .IN "XNFilterEvents" "" "@DEF@"
  3131. The 
  3132. .PN XNFilterEvents
  3133. argument returns the event mask that an input methods needs
  3134. to have selected for.
  3135. The client is expected to augment its own event mask 
  3136. for the client window with this one.
  3137. .LP
  3138. Note that this argument is read-only,
  3139. is set by the input method at create time,
  3140. and is never changed.
  3141. .LP
  3142. Note also that the type of this argument is "unsigned long".
  3143. Setting this value will cause an error.
  3144. .NH 3
  3145. Preedit and Status Attributes
  3146. .XS
  3147. \*(SN Preedit and Status Attribute
  3148. .XE
  3149. .LP
  3150. .IN "XNPreeditAttributes" "" "@DEF@"
  3151. .IN "XNStatusAttributes" "" "@DEF@"
  3152. The
  3153. .PN XNPreeditAttributes
  3154. and
  3155. .PN XNStatusAttributes
  3156. arguments specify to input method the attributes to be used for the 
  3157. Preedit and Status areas,
  3158. if any.
  3159. Those attributes are passed to 
  3160. .PN XSetICValues
  3161. or
  3162. .PN XGetICValues
  3163. as a nested variable length list.
  3164. The names to be used in these lists are as described in the following sections.
  3165. .NH 4 
  3166. Area
  3167. .XS
  3168. \*(SN Area
  3169. .XE
  3170. .LP
  3171. .IN "XNArea" "" "@DEF@"
  3172. The value of the
  3173. .PN XNArea
  3174. argument must be a pointer to a structure of type
  3175. .PN XRectangle.
  3176. The interpretation of the
  3177. .PN XNArea
  3178. argument is dependent on the input method style that has been set.
  3179. .LP
  3180. If the input method style is 
  3181. .PN XIMPreeditPosition ,
  3182. .PN XNArea
  3183. specifies the clipping region within which preediting will take place.
  3184. If the focus window has been set,
  3185. the coordinates are assumed to be relative to the focus window.
  3186. Otherwise, the coordinates are assumed to be relative to the client window.
  3187. If neither has been set,
  3188. the results are undefined.
  3189. If 
  3190. .PN XNArea
  3191. is not specified,
  3192. the input method will default the clipping region
  3193. to the geometry of the
  3194. .PN XNFocusWindow .
  3195. If the area specified is NULL or invalid,
  3196. the results are undefined.
  3197. .LP
  3198. If the input style is 
  3199. .PN XIMPreeditArea
  3200. or 
  3201. .PN XIMStatusArea ,
  3202. .PN XNArea
  3203. specifies the geometry provided by the client to the input method.
  3204. The input method may use this area to display its data,
  3205. either Preedit or Status depending on the area designated.
  3206. The input method may create a window as a child of the client window
  3207. with dimensions that fit the
  3208. .PN XNArea .
  3209. The coordinates are relative to the client window.
  3210. If the client window has not been set yet,
  3211. the input method should save these values 
  3212. and apply them when the client window is set.
  3213. If 
  3214. .PN XNArea
  3215. is not specified, is set to NULL or is invalid,
  3216. the results are undefined.
  3217. .NH 4
  3218. Area Needed
  3219. .XS
  3220. \*(SN Area Needed
  3221. .XE
  3222. .LP
  3223. .IN "XNAreaNeeded" "" "@DEF@"
  3224. When set, the
  3225. .PN XNAreaNeeded
  3226. argument specifies the geometry suggested by the client for this area
  3227. (Preedit or Status).
  3228. The value associated with the argument must be a pointer to a 
  3229. structure of type 
  3230. .PN XRectangle .
  3231. Note that the x, y values are not used
  3232. and that non-zero values for width or height are the constraints 
  3233. that the client wishes the input method to respect.
  3234. .LP
  3235. When read, the
  3236. .PN XNAreaNeeded
  3237. argument specifies the preferred geometry desired by the input method
  3238. for the area.
  3239. .LP
  3240. This argument is only valid if the input style is 
  3241. .PN XIMPreeditArea
  3242. or 
  3243. .PN XIMStatusArea .
  3244. It is used for geometry negotiation between the client and the input method
  3245. and has no other effect upon the input method 
  3246. (see section 13.6.5).
  3247. .NH 4 
  3248. Spot Location
  3249. .XS
  3250. \*(SN Spot Location
  3251. .XE
  3252. .LP
  3253. .IN "XNSpotLocation" "" "@DEF@"
  3254. The
  3255. .PN XNSpotLocation
  3256. argument specifies to the input method the coordinates of the ``spot''
  3257. to be used by an input method executing with 
  3258. .PN XNInputStyle 
  3259. set to 
  3260. .PN XIMPreeditPosition .
  3261. When specified to any input method other than 
  3262. .PN XIMPreeditPosition ,
  3263. this XIC value is ignored.
  3264. .LP
  3265. The x coordinate specifies the position where the next character
  3266. would be inserted.
  3267. The y coordinate is the position of the baseline used by current text line
  3268. in the focus window.
  3269. The x and y coordinates are relative to the focus window, if it has been set;
  3270. otherwise, they are relative to the client window.
  3271. If neither the focus window nor the client window has been set,
  3272. the results are undefined.
  3273. .LP
  3274. Note that the value of the argument is a pointer to a structure of type
  3275. .PN XPoint .
  3276. .NH 4
  3277. Colormap
  3278. .XS
  3279. \*(SN Colormap
  3280. .XE
  3281. .LP
  3282. Two different arguments can be used to indicate what colormap the input method
  3283. should use to allocate colors:
  3284. a colormap ID,
  3285. or a standard colormap name.
  3286. .LP
  3287. .IN "XNColormap" "" "@DEF@"
  3288. The
  3289. \fBXNColormap\fR
  3290. argument is used to specify a colormap ID.
  3291. The argument value is of type
  3292. .PN Colormap .
  3293. An invalid argument may generate a 
  3294. .PN BadColor error
  3295. when it is used by the input method.
  3296. .LP
  3297. .IN "XNStdColormap" "" "@DEF@"
  3298. The
  3299. .PN XNStdColormap
  3300. argument is used to indicate the name of the standard colormap
  3301. in which input method should to allocate colors.
  3302. The argument value is an 
  3303. .PN Atom
  3304. that should be a valid atom for calling
  3305. .PN XGetRGBColormaps .
  3306. An invalid argument may generate a
  3307. .PN BadAtom
  3308. error when it is used by the input method.
  3309. .LP
  3310. If colormap is left unspecified, it is defaulted to client window colormap.
  3311. .NH 4
  3312. Foreground and Background
  3313. .XS
  3314. \*(SN Foreground and Background
  3315. .XE
  3316. .LP
  3317. .IN "XNForeground" "" "@DEF@"
  3318. .IN "XNBackground" "" "@DEF@"
  3319. The
  3320. .PN XNForeground
  3321. and
  3322. .PN XNBackground
  3323. arguments specify the foreground and background pixel, respectively.
  3324. The argument value is of type "unsigned long".
  3325. It must be a valid pixel in the input method colormap.
  3326. .LP
  3327. If these values are left unspecified,
  3328. the default is determined by the input method.
  3329. .NH 4
  3330. Background Pixmap
  3331. .XS
  3332. \*(SN Background Pixmap
  3333. .XE
  3334. .LP
  3335. The
  3336. .PN XNBackgroundPixmap
  3337. argument specifies a background pixmap to be used as the background of the
  3338. window.
  3339. The value must be of type 
  3340. .PN Pixmap .
  3341. An invalid argument may generate a
  3342. .PN BadPixmap
  3343. error when it is used by the input method.
  3344. .LP
  3345. If this value is left unspecified,
  3346. the default is determined by the input method.
  3347. .NH 4
  3348. FontSet
  3349. .XS
  3350. \*(SN FontSet
  3351. .XE
  3352. .LP
  3353. .IN "XNFontSet" "" "@DEF@"
  3354. The
  3355. .PN XNFontSet
  3356. argument specifies to the input method what fontset is to be used.
  3357. The argument value is of type
  3358. .PN XFontSet .
  3359. .LP
  3360. If this value is left unspecified,
  3361. the default is determined by the input method.
  3362. .NH 4
  3363. Line Spacing
  3364. .XS
  3365. \*(SN Line Spacing
  3366. .XE
  3367. .LP
  3368. The
  3369. .PN XNLineSpace
  3370. argument specifies to the input method what line spacing is to be used
  3371. in preedit window if more than one line is to be used.
  3372. This argument is of type "int".
  3373. .LP
  3374. If this value is left unspecified,
  3375. the default is determined by the input method.
  3376. .NH 4
  3377. Cursor
  3378. .XS
  3379. \*(SN Cursor
  3380. .XE
  3381. .LP
  3382. .IN "XNCursor" "" "DEF@"
  3383. The
  3384. .PN XNCursor
  3385. argument specifies to the input method what cursor is to be used
  3386. in the specified window.
  3387. This argument is of type 
  3388. .PN Cursor .
  3389. .LP
  3390. An invalid argument may generate a
  3391. .PN BadCursor
  3392. error when it is used by the input method.
  3393. If this value is left unspecified,
  3394. the default is determined by the input method.
  3395. .NH 4
  3396. Preedit and Status Callbacks
  3397. .XS
  3398. \*(SN Preedit and Status Callbacks
  3399. .XE
  3400. .LP
  3401. A client that wishes to support the input style
  3402. .PN XIMPreeditCallbacks
  3403. must provide a set of preedit callbacks to the input method.
  3404. The set of preedit callbacks are as follows:
  3405. .IN "XNPreeditStartCallback" "" "@DEF@"
  3406. .IN "XNPreeditDoneCallback" "" "@DEF@"
  3407. .IN "XNPreeditDrawCallback" "" "@DEF@"
  3408. .IN "XNPreeditCaretCallback" "" "@DEF@"
  3409. .TS
  3410. lw(1.75i) lw(4i).
  3411. T{
  3412. .PN XNPreeditStartCallback
  3413. T}    T{
  3414. This is called when the input method starts preedit.
  3415. T}
  3416. T{
  3417. .PN XNPreeditDoneCallback
  3418. T}    T{
  3419. This is called when the input method stops preedit.
  3420. T}
  3421. T{
  3422. .PN XNPreeditDrawCallback
  3423. T}    T{
  3424. This is called when a number preedit keystrokes should be echoed.
  3425. T}
  3426. T{
  3427. .PN XNPreeditCaretCallback
  3428. T}    T{
  3429. This is called to move text insertion point within preedit string
  3430. T}
  3431. .TE
  3432. .LP
  3433. A client that wishes to support the input style
  3434. .PN XIMStatusCallbacks
  3435. must provide a set of status callbacks to the input method.
  3436. The set of status callbacks are as follows:
  3437. .IN "XNStatusStartCallback" "" "@DEF@"
  3438. .IN "XNStatusDoneCallback" "" "@DEF@"
  3439. .IN "XNStatusDrawCallback" "" "@DEF@"
  3440. .TS
  3441. lw(1.75i) lw(4i).
  3442. T{
  3443. .PN XNStatusStartCallback
  3444. T}    T{
  3445. This is called when the input method initializes status area.
  3446. T}
  3447. T{
  3448. .PN XNStatusDoneCallback
  3449. T}    T{
  3450. This is called when the input method no longer needs status area.
  3451. T}
  3452. T{
  3453. .PN XNStatusDrawCallback
  3454. T}    T{
  3455. This is called when updating the status area is required.
  3456. T}
  3457. .TE
  3458. .LP
  3459. The value of any status or preedit argument is a pointer
  3460. to a structure of type
  3461. .PN XIMCallback .
  3462. .IN "XIMProc" "" "@DEF@"
  3463. .IN "XIMCallback" "" "@DEF@"
  3464. .\" Start marker code here
  3465. .LP
  3466. .Ds 0
  3467. .TA .5i 2.5i
  3468. .ta .5i 2.5i
  3469. typedef void (*XIMProc)();
  3470.  
  3471. typedef struct {
  3472.     XPointer client_data;
  3473.     XIMProc callback;
  3474. } XIMCallback;
  3475. .De
  3476. .\" End marker code here
  3477. .LP
  3478. Each callback has some particular semantics and will carry the data
  3479. that expresses the environment necessary to the client 
  3480. into a specific data structure.
  3481. This paragraph only describes the arguments to be used to set
  3482. the callback.
  3483. For a complete description of the semantics,
  3484. see section 13.11.
  3485. .LP
  3486. Note that setting any of these values while doing preedit
  3487. may cause unexpected results.
  3488. .NH 2
  3489. Callback Semantics
  3490. .XS
  3491. \*(SN Callback Semantics
  3492. .XE
  3493. .LP
  3494. Callbacks are functions defined by clients or text drawing packages
  3495. that are to be called from the input method when selected events occur.
  3496. Most clients will use a text editing package or a toolkit
  3497. and, hence, will not need to define such callbacks.
  3498. This section defines the callback semantics, when they are triggered,
  3499. and what their arguments are.
  3500. Note that this information is mostly useful for X toolkit implementors.
  3501. .LP
  3502. Callbacks are mostly provided so that clients (or text editing
  3503. packages) can implement on-the-spot preediting in their own window.
  3504. In that case,
  3505. the input method needs to communicate and synchronize with the client.
  3506. Input method needs to communicate changes in the preedit window 
  3507. when it is under control of the client.
  3508. Those callbacks allow the client to initialize the preedit area,
  3509. display a new preedit string, move the text insertion point inside preedit,
  3510. terminate preedit, or update the status area.
  3511. .LP
  3512. All callback functions follow the generic prototype:
  3513. .IN "CallbackPrototype" "" "@DEF@"
  3514. .\" Start marker code here
  3515. .FD 0
  3516. void CallbackPrototype\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
  3517. .br
  3518.       XIC \fIic\fP\^;
  3519. .br
  3520.       XPointer \fIclient_data\fP\^;    
  3521. .br
  3522.       SomeType \fIcall_data\fP\^;
  3523. .FN
  3524. .IP \fIic\fP 1i
  3525. Specifies the input context.
  3526. .IP \fIclient_data\fP 1i
  3527. Specifies the additional client data.
  3528. .IP \fIcall_data\fP 1i
  3529. Specifies data specific to the callback.
  3530. .\" End marker code here
  3531. .LP
  3532. The call_data argument is a structure that expresses the arguments needed
  3533. to achieve the semantics;
  3534. that is,
  3535. it is a a specific data structure appropriate to the callback.
  3536. In cases where no data is needed in the callback,
  3537. this call_data argument is NULL.
  3538. The client_data argument is a closure that has been initially specified
  3539. by the client when specifying the callback and passed back.
  3540. It may serve, for example, to inherit application context in the callback.
  3541. .LP
  3542. The following paragraphs describe the programming semantics
  3543. and specific data structure associated with the different reasons.
  3544. .NH 3
  3545. Geometry Callback
  3546. .XS
  3547. \*(SN Geometry Callback
  3548. .XE
  3549. .LP
  3550. The geometry callback is triggered by the input method 
  3551. to indicate that it wants the client to negotiate geometry.
  3552. The generic prototype is as follows:
  3553. .IN "GeometryCallback" "" "@DEF@"
  3554. .\" Start marker code here
  3555. .FD 0
  3556. void GeometryCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
  3557. .br
  3558.       XIC \fIic\fP\^;
  3559. .br
  3560.       XPointer \fIclient_data\fP\^;
  3561. .br
  3562.       XPointer \fIcall_data\fP\^;
  3563. .FN
  3564. .IP \fIic\fP 1i
  3565. Specifies the input context.
  3566. .IP \fIclient_data\fP 1i
  3567. Specifies the additional client data.
  3568. .IP \fIcall_data\fP 1i
  3569. Not used for this callback, always passed as NULL.
  3570. .\" End marker code here
  3571. .LP
  3572. Note that a GeometryCallback
  3573. is called with a NULL call_data argument.
  3574. .NH 3
  3575. Preedit State Callbacks
  3576. .XS
  3577. \*(SN Preedit State Callbacks
  3578. .XE
  3579. .LP
  3580. When the input method turns input conversion on or off,
  3581. a PreeditStartCallback or PreeditDoneCallback
  3582. callback is triggered in order to let the toolkit do the setup
  3583. or the cleanup for the preedit region.
  3584. .IN "PreeditStartCallback" "" "@DEF@"
  3585. .\" Start marker code here
  3586. .FD 0
  3587. int PreeditStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
  3588. .br
  3589.       XIC \fIic\fP\^;
  3590. .br
  3591.       XPointer \fIclient_data\fP\^;
  3592. .br
  3593.       XPointer \fIcall_data\fP\^;
  3594. .FN
  3595. .IP \fIic\fP 1i
  3596. Specifies the input context.
  3597. .IP \fIclient_data\fP 1i
  3598. Specifies the additional client data.
  3599. .IP \fIcall_data\fP 1i
  3600. Not used for this callback, always passed as NULL.
  3601. .\" End marker code here
  3602. .LP
  3603. When preedit starts on the specified input context,
  3604. the callback is called with a NULL call_data argument.
  3605. PreeditStartCallback will return the maximum size of the preedit string.
  3606. Note that a positive number indicates the maximum number of bytes allowed
  3607. in the preedit string, 
  3608. and a value of \-1 indicates there is no limit.
  3609. .IN "PreeditDoneCallback" "" "@DEF@"
  3610. .\" Start marker code here
  3611. .FD 0
  3612. void PreeditDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
  3613. .br
  3614.       XIC \fIic\fP\^;
  3615. .br
  3616.       XPointer \fIclient_data\fP\^;
  3617. .br
  3618.       XPointer \fIcall_data\fP\^;
  3619. .FN
  3620. .IP \fIic\fP 1i
  3621. Specifies the input context.
  3622. .IP \fIclient_data\fP 1i
  3623. Specifies the additional client data.
  3624. .IP \fIcall_data\fP 1i
  3625. Not used for this callback, always passed as NULL.
  3626. .\" End marker code here
  3627. .LP
  3628. When preedit stops on the specified input context,
  3629. the callback is called with a NULL call_data argument.
  3630. The client can release the data allocated by
  3631. PreeditStartCallback.
  3632. .LP
  3633. PreeditStartCallback should initialize appropriate data needed for
  3634. displaying preedit information and for handling further 
  3635. PreeditDrawCallback calls.
  3636. Once PreeditStartCallback
  3637. is called, it will not be called again before
  3638. PreeditDoneCallback has been called.
  3639. .NH 3
  3640. PreeditDraw Callback
  3641. .XS
  3642. \*(SN PreeditDraw Callback
  3643. .XE
  3644. .LP
  3645. This callback is triggered to draw and insert, delete or replace,
  3646. preedit text in the preedit region.
  3647. The preedit text may include unconverted input text such as Japanese kana,
  3648. converted text such as Japanese Kanji characters, or characters of both kinds.
  3649. That string is either a multibyte or wide character string, 
  3650. whose encoding matches the locale bound to the input context.
  3651. The callback prototype
  3652. is as follows:
  3653. .IN "PreeditDrawCallback" "" "@DEF@"
  3654. .\" Start marker code here
  3655. .FD 0
  3656. void PreeditDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
  3657. .br
  3658.       XIC \fIic\fP\^;
  3659. .br
  3660.       XPointer \fIclient_data\fP\^;
  3661. .br
  3662.       XIMPreeditDrawCallbackStruct *\fIcall_data\fP\^;
  3663. .FN
  3664. .IP \fIic\fP 1i
  3665. Specifies the input context.
  3666. .IP \fIclient_data\fP 1i
  3667. Specifies the additional client data.
  3668. .IP \fIcall_data\fP 1i
  3669. Specifies the preedit drawing information.
  3670. .\" End marker code here
  3671. .LP
  3672. The callback is passed a 
  3673. .PN XIMPreeditDrawCallbackStruct
  3674. structure in the call_data argument.
  3675. The text member of this structure contains the text to be drawn.
  3676. After the string has been drawn,
  3677. the caret should be moved to the specified location.
  3678. .LP
  3679. The 
  3680. .PN XIMPreeditDrawCallbackStruct
  3681. structure is defined as follows:
  3682. .LP
  3683. .IN "XIMPreeditDrawCallbackStruct" "" "@DEF@"
  3684. .\" Start marker code here
  3685. .Ds 0
  3686. .TA .5i 2.5i
  3687. .ta .5i 2.5i
  3688. typedef struct _XIMPreeditDrawCallbackStruct {
  3689.     int caret;    /* Cursor offset within preedit string */
  3690.     int chg_first;    /* Starting change position */
  3691.     int chg_length;    /* Length of the change in character count */
  3692.     XIMText *text;
  3693. } XIMPreeditDrawCallbackStruct;
  3694. .De
  3695. .\" End marker code here
  3696. .LP
  3697. The client must keep updating a buffer of the preedit text,
  3698. the callback arguments referring to indexes in that buffer.
  3699. The call_data fields have specific meanings according to the operation:
  3700. .IP \(bu 5
  3701. To indicate text deletion, 
  3702. the call_data specifies a NULL text field.
  3703. The text to be deleted is then the current text in buffer 
  3704. from position chg_first (starting at zero) on a (character) length
  3705. of chg_length.
  3706. .IP \(bu 5
  3707. When text is non-NULL,
  3708. it indicates insertion or replacement of text in the buffer.
  3709. .IP
  3710. A positive chg_length indicates that the characters starting
  3711. from chg_first to ch_first+chg_length must be deleted
  3712. and must be replaced by text, whose length is specified in the 
  3713. .PN XIMText
  3714. structure.
  3715. .IP
  3716. A chg_length value of zero indicates that text must be inserted
  3717. right at the position specified by chg_first.
  3718. A value of zero for chg_first specifies the first character in the buffer.
  3719. .IP \(bu 5
  3720. The caret member is an index in the the preedit text buffer
  3721. that specifies the character after which the cursor should move
  3722. after text has been drawn or deleted.
  3723. .LP
  3724. .IN "XIMText" "" @DEF@"
  3725. .\" Start marker code here
  3726. .Ds
  3727. .TA .5i 1.5i 3i
  3728. typedef struct _XIMText {
  3729.     unsigned short length;
  3730.     XIMFeedback * feedback;
  3731.     Bool encoding_is_wchar; 
  3732.     union {
  3733.         char * multi_byte;
  3734.         wchar_t * wide_char;
  3735.         } string; 
  3736. } XIMText;
  3737. .De
  3738. .\" End marker code here
  3739. .LP
  3740. The text string passed is actually a structure specifying:
  3741. .IP \(bu 5
  3742. The length member is the text length in characters.
  3743. .IP \(bu 5
  3744. The encoding_is_wchar member ia a value that indicates 
  3745. if the text string is encoded in wide character or multibyte format.
  3746. This value should be set by the client when it sets the callback.
  3747. .IP \(bu 5
  3748. The string member is the text string.
  3749. .IP \(bu 5
  3750. The feedback member indicates rendering type.
  3751. .LP
  3752. The feedback member express the types of rendering feedback
  3753. the callback should apply when drawing text.
  3754. Rendering of the text to be drawn is specified either in generic ways
  3755. (for example, primary, secondary) or in specific ways (reverse, underline).
  3756. When generic indications are given,
  3757. the client is free to choose the rendering style.
  3758. It is necessary however that primary and secondary are mapped 
  3759. to two distinct rendering styles.
  3760. .LP
  3761. The feedback member also specifies how the rendering of the text argument
  3762. should be achieved.
  3763. If feedback is NULL,
  3764. then rendering is assumed to be the same as rendering of other characters
  3765. in the text entry.
  3766. Otherwise, it specifies an array defining the rendering of each
  3767. character of the string (hence the length of the array is length).
  3768. .LP
  3769. If an input method wishes to indicate that it is only updating the feedback of
  3770. the preedit text without changing the content of it, 
  3771. the
  3772. .PN XIMText
  3773. structure should contain a NULL value for the string field,
  3774. the number of characters affected in the length field,
  3775. and the feedback field should point to an array of 
  3776. .PN XIMFeedback .
  3777. .LP
  3778. Each element in the array is a bit mask represented by a value of type
  3779. .PN XIMFeedback .
  3780. The valid masks names are as follows:
  3781. .LP
  3782. .IN "XIMReverse" "" "@DEF@"
  3783. .IN "XIMUnderline" "" "@DEF@"
  3784. .IN "XIMHighlight" "" "@DEF@"
  3785. .IN "XIMPrimary" "" "@DEF@"
  3786. .IN "XIMSecondary" "" "@DEF@"
  3787. .IN "XIMTertiary" "" "@DEF@"
  3788. .\" Start marker code here
  3789. .LP
  3790. .Ds 0
  3791. typedef unsigned long XIMFeedback;
  3792. .De
  3793. .TS
  3794. lw(.5i) lw(2i) lw(2i).
  3795. T{
  3796. #define
  3797. T}    T{
  3798. .PN XIMReverse
  3799. T}    T{
  3800. 1
  3801. T}
  3802. T{
  3803. #define
  3804. T}    T{
  3805. .PN XIMUnderline
  3806. T}    T{
  3807. (1L<<1) 
  3808. T}
  3809. T{
  3810. #define
  3811. T}    T{
  3812. .PN XIMHighlight
  3813. T}    T{
  3814. (1L<<2)
  3815. T}
  3816. T{
  3817. #define
  3818. T}    T{
  3819. .PN XIMPrimary
  3820. T}    T{
  3821. (1L<<3)
  3822. T}
  3823. T{
  3824. #define
  3825. T}    T{
  3826. .PN XIMSecondary
  3827. T}    T{
  3828. (1L<<4)
  3829. T}
  3830. T{
  3831. #define
  3832. T}    T{
  3833. .PN XIMTertiary
  3834. T}    T{
  3835. (1L<<5)
  3836. T}
  3837. .TE
  3838. .\" End marker code here
  3839. .NH 3
  3840. PreeditCaretCallback
  3841. .XS
  3842. \*(SN PreeditCaretCallback
  3843. .XE
  3844. .LP
  3845. An input method may have its own ``navigation keys'' to allow the user
  3846. to move the text insertion point in the preedit area 
  3847. (for example, to move backward or forward). 
  3848. Consequently, input method needs to indicate to the client that it
  3849. should move the text insertion point.
  3850. It then calls the PreeditCaretCallback.
  3851. .IN "PreeditCaretCallback" "" "@DEF@"
  3852. .\" Start marker code here
  3853. .FD 0
  3854. void PreeditCaretCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
  3855. .br
  3856.       XIC \fIic\fP\^;
  3857. .br
  3858.       XPointer \fIclient_data\fP\^;
  3859. .br
  3860.       XIMPreeditCaretCallbackStruct *\fIcall_data\fP\^;
  3861. .FN
  3862. .IP \fIic\fP 1i
  3863. Specifies the input context.
  3864. .IP \fIclient_data\fP 1i
  3865. Specifies the additional client data.
  3866. .IP \fIcall_data\fP 1i
  3867. Specifies the preedit caret information.
  3868. .\" End marker code here
  3869. .LP
  3870. The input method will trigger PreeditCaretCallback
  3871. to move the text insertion point during preedit.
  3872. The call_data argument contains a pointer to an 
  3873. .PN XIMPreeditCaretCallbackStruct
  3874. structure,
  3875. which indicates where the caret should be moved.
  3876. The callback must move the insertion point to its new location
  3877. and return, in field position, the new offset value from initial position.  
  3878. .LP
  3879. The
  3880. .PN XIMPreeditCaretCallbackStruct
  3881. structure is defined as follows:
  3882. .IN "XIMPreeditCaretCallbackStruct" "" "@DEF@"
  3883. .LP
  3884. .\" Start marker code here
  3885. .Ds 0
  3886. .TA .5i 2.5i
  3887. .ta .5i 2.5i
  3888. typedef struct _XIMPreeditCaretCallbackStruct {
  3889.     int position;    /* Caret offset within preedit string */
  3890.     XIMCaretDirection direction;    /* Caret moves direction */
  3891.     XIMCaretStyle style;    /* Feedback of the caret */
  3892. } XIMPreeditCaretCallbackStruct;
  3893. .De
  3894. .\" End marker code here
  3895. .LP
  3896. The
  3897. .PN XIMCaretStyle
  3898. structure is defined as follows:
  3899. .LP
  3900. .IN "XIMCaretStyle" "" "@DEF@"
  3901. .\" Start marker code here
  3902. .Ds 0
  3903. .TA .5i 2.5i
  3904. .ta .5i 2.5i
  3905. typedef enum {
  3906.     XIMIsInvisible,    /* Disable caret feedback */ 
  3907.     XIMIsPrimary,    /* UI defined caret feedback */
  3908.     XIMIsSecondary,    /* UI defined caret feedback */
  3909. } XIMCaretStyle;
  3910. .De
  3911. .\" End marker code here
  3912. .LP
  3913. The
  3914. .PN XIMCaretDirection
  3915. structure is defined as follows:
  3916. .IN "XIMCaretDirection" "" "@DEF@"
  3917. .LP
  3918. .\" Start marker code here
  3919. .Ds 0
  3920. .TA .5i 2.5i
  3921. .ta .5i 2.5i
  3922. typedef enum {
  3923.     XIMForwardChar, XIMBackwardChar,
  3924.     XIMForwardWord, XIMBackwardWord,
  3925.     XIMCaretUp, XIMCaretDown,
  3926.     XIMNextLine, XIMPreviousLine,
  3927.     XIMLineStart, XIMLineEnd, 
  3928.     XIMAbsolutePosition,
  3929.     XIMDontChange,
  3930.  } XIMCaretDirection;
  3931. .De
  3932. .\" End marker code here
  3933. .LP
  3934. The meaning of these values are defined as follows:
  3935. .IN "XIMForwardChar" "" "@DEF@"
  3936. .IN "XIMBackwardChar" "" "@DEF@"
  3937. .IN "XIMForwardWord" "" "@DEF@"
  3938. .IN "XIMBackwardWord" "" "@DEF@"
  3939. .IN "XIMCaretUp" "" "@DEF@"
  3940. .IN "XIMCaretDown" "" "@DEF@"
  3941. .TS
  3942. lw(1.5i) lw(4.25i).
  3943. T{
  3944. .PN XIMForwardChar
  3945. T}    T{
  3946. Move caret forward one character position.
  3947. T}
  3948. T{
  3949. .PN XIMBackwardChar
  3950. T}    T{
  3951. Move caret backward one character position.
  3952. T}
  3953. T{
  3954. .PN XIMForwardWord
  3955. T}    T{
  3956. Move caret forward one word position.
  3957. T}
  3958. T{
  3959. .PN XIMBackwardWord
  3960. T}    T{
  3961. Move caret backward one word position.
  3962. T}
  3963. T{
  3964. .PN XIMCaretUp
  3965. T}    T{
  3966. Move caret up one line keeping current offset.
  3967. T}
  3968. T{
  3969. .PN XIMCaretDown
  3970. T}    T{
  3971. Move caret down one line keeping current offset.
  3972. T}
  3973. T{
  3974. .PN XIMPreviousLine
  3975. T}    T{
  3976. Move caret up one line.
  3977. T}
  3978. T{
  3979. .PN XIMNextLine
  3980. T}    T{
  3981. Move caret down one line.
  3982. T}
  3983. T{
  3984. .PN XIMLineStart
  3985. T}    T{
  3986. Move caret to the beginning of the current display line 
  3987. that contains the caret.
  3988. T}
  3989. T{
  3990. .PN XIMLineEnd
  3991. T}    T{
  3992. Move caret to the end of the current display line 
  3993. that contains the caret.
  3994. T}
  3995. T{
  3996. .PN XIMAbsolutePosition
  3997. T}    T{
  3998. The callback must move to the location specified by the position field
  3999. of the callback data, indicated in characters, starting from the beginning
  4000. of the preedit text.
  4001. Hence, a value of zero means move back to beginning of the preedit text.
  4002. T}
  4003. T{
  4004. .PN XIMDontChange
  4005. T}    T{
  4006. The caret position does not change.
  4007. T}
  4008. .TE
  4009. .IN "XIMNextLine" "" "@DEF@"
  4010. .IN "XIMPreviousLine" "" "@DEF@"
  4011. .IN "XIMLineStart" "" "@DEF@"
  4012. .IN "XIMLineEnd" "" "@DEF@"
  4013. .IN "XIMAbsolutePosition" "" "@DEF@"
  4014. .IN "XIMDontChange" "" "@DEF@"
  4015. .NH 3
  4016. Status Callbacks
  4017. .XS
  4018. \*(SN Status Callbacks
  4019. .XE
  4020. .LP
  4021. An input method may communicate changes in the status of an input context
  4022. (for example, created, destroyed, or focus changes) with three status
  4023. callbacks:  StatusStartCallback, StatusDoneCallback, and StatusDrawCallback.
  4024. .LP
  4025. .sp
  4026. When the input context is created or gains focus, 
  4027. the input method calls the StatusStartCallback callback.
  4028. .IN "StatusStartCallback" "" "@DEF@"
  4029. .\" Start marker code here
  4030. .FD 0
  4031. void StatusStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
  4032. .br
  4033.       XIC \fIic\fP\^;
  4034. .br
  4035.       XPointer \fIclient_data\fP\^;
  4036. .br
  4037.       XPointer \fIcall_data\fP\^;
  4038. .FN
  4039. .IP \fIic\fP 1i
  4040. Specifies the input context.
  4041. .IP \fIclient_data\fP 1i
  4042. Specifies the additional client data.
  4043. .IP \fIcall_data\fP 1i
  4044. Not used for this callback, always passed as NULL.
  4045. .\" End marker code here
  4046. .LP
  4047. The callback should initialize appropriate data for displaying status
  4048. and be prepared to further StatusDrawCallback calls.  
  4049. Once StatusStartCallback is called,
  4050. it will not be called again before StatusDoneCallback has been called.
  4051. .LP
  4052. .sp
  4053. When an input context
  4054. is destroyed or when it loses focus, the input method calls StatusDoneCallback.
  4055. .IN "StatusDoneCallback" "" "@DEF@"
  4056. .\" Start marker code here
  4057. .FD 0
  4058. void StatusDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
  4059. .br
  4060.       XIC \fIic\fP\^;
  4061. .br
  4062.       XPointer \fIclient_data\fP\^;
  4063. .br
  4064.       XPointer \fIcall_data\fP\^;
  4065. .FN
  4066. .IP \fIic\fP 1i
  4067. Specifies the input context.
  4068. .IP \fIclient_data\fP 1i
  4069. Specifies the additional client data.
  4070. .IP \fIcall_data\fP 1i
  4071. Not used for this callback, always passed as NULL.
  4072. .\" End marker code here
  4073. .LP
  4074. The callback may release any data allocated on 
  4075. .PN StatusStart .
  4076. .LP
  4077. .sp
  4078. When an input context status has to be updated, the input method calls
  4079. .PN StatusDrawCallback .
  4080. .IN "StatusDrawCallback" "" "@DEF@"
  4081. .\" Start marker code here
  4082. .FD 0
  4083. void StatusDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
  4084. .br
  4085.       XIC \fIic\fP\^;
  4086. .br
  4087.       XPointer \fIclient_data\fP\^;
  4088. .br
  4089.       XIMStatusDrawCallbackStruct *\fIcall_data\fP\^;
  4090. .FN
  4091. .IP \fIic\fP 1i
  4092. Specifies the input context.
  4093. .IP \fIclient_data\fP 1i
  4094. Specifies the additional client data.
  4095. .IP \fIcall_data\fP 1i
  4096. Specifies the status drawing information.
  4097. .\" End marker code here
  4098. .LP
  4099. The callback should update the status area by either drawing a string,
  4100. or imaging a bitmap in the status area.
  4101. .LP
  4102. The
  4103. .PN XIMStatusDataType
  4104. and
  4105. .PN XIMStatusDrawCallbackStruct
  4106. structures are defined as follows:
  4107. .IN "XIMStatusDataType" "" "@DEF@"
  4108. .IN "XIMStatusDrawCallbackStruct" "" "@DEF@"
  4109. .LP
  4110. .\" Start marker code here
  4111. .Ds 0
  4112. .TA .5i 1i 3i
  4113. .ta .5i 1i 3i
  4114. typedef enum {
  4115.     XIMTextType,
  4116.     XIMBitmapType,
  4117. } XIMStatusDataType;
  4118.  
  4119. typedef struct _XIMStatusDrawCallbackStruct {
  4120.     XIMStatusDataType type;
  4121.     union {
  4122.         XIMText *text;
  4123.         Pixmap  bitmap;
  4124.     } data;
  4125. } XIMStatusDrawCallbackStruct;
  4126. .De
  4127. .\" End marker code here
  4128. .NH 2
  4129. Event Filtering
  4130. .XS
  4131. \*(SN Event Filtering
  4132. .XE
  4133. .LP
  4134. Xlib provides the ability for an input method
  4135. to register a filter internal to Xlib.
  4136. This filter is called by a client (or toolkit) by calling
  4137. .PN XFilterEvent
  4138. after calling 
  4139. .PN XNextEvent .
  4140. Any client that uses the 
  4141. .PN XIM
  4142. interface should call
  4143. .PN XFilterEvent
  4144. to allow input methods to process their events without knowledge
  4145. of the client's dispatching mechanism.
  4146. A client's user interface policy may determine the priority
  4147. of event filters with respect to other event handling mechanisms
  4148. (for example, modal grabs).
  4149. .LP
  4150. Clients may not know how many filters there are, if any,
  4151. and what they do.
  4152. They may only know if an event has been filtered on return of 
  4153. .PN XFilterEvent .
  4154. Clients should discard filtered events.
  4155. .IN "XFilterEvent" "" "@DEF@"
  4156. .\" Start marker code here
  4157. .FD 0
  4158. Bool XFilterEvent\^(\^\fIevent\fP\^, \fIw\fP\^)
  4159. .br
  4160.       XEvent *\fIevent\fP\^;
  4161. .br
  4162.       Window \fIw\fP\^;
  4163. .FN
  4164. .ds Ev event to filter
  4165. .IP \fIevent\fP 1i
  4166. Specifies the \*(Ev.
  4167. .ds Wi for which the filter is to be applied
  4168. .\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
  4169. .IP \fIw\fP 1i
  4170. Specifies the window \*(Wi.
  4171. .\" End marker code here
  4172. .LP
  4173. If the window argument is
  4174. .PN None ,
  4175. .PN XFilterEvent 
  4176. applies the filter to the window specified in the
  4177. .PN XEvent
  4178. structure.
  4179. The window argument is provided so that layers above Xlib
  4180. that do event redirection can indicate to which window an event
  4181. has been redirected.
  4182. .LP
  4183. If
  4184. .PN XFilterEvent
  4185. returns
  4186. .PN True ,
  4187. then some input method has filtered the event,
  4188. and the client should discard the event.
  4189. If
  4190. .PN XFilterEvent
  4191. returns
  4192. .PN False ,
  4193. then the client should continue processing the event.
  4194. .LP
  4195. If a grab has occurred in the client, and
  4196. .PN XFilterEvent
  4197. returns
  4198. .PN True ,
  4199. the client should ungrab the keyboard.
  4200. .NH 2
  4201. Getting Keyboard Input
  4202. .XS
  4203. \*(SN Getting Keyboard Input
  4204. .XE
  4205. .LP
  4206. To get composed input from an input method,
  4207. use
  4208. .PN XmbLookupString
  4209. or
  4210. .PN XwcLookupString .
  4211. .IN "XmbLookupString" "" "@DEF@"
  4212. .IN "XwcLookupString" "" "@DEF@"
  4213. .\" Start marker code here
  4214. .FD 0
  4215. int XmbLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^)
  4216. .br
  4217.       XIC \fIic\fP\^;
  4218. .br
  4219.       XKeyPressedEvent *\fIevent\fP;
  4220. .br
  4221.       char *\fIbuffer_return\fP\^;
  4222. .br
  4223.       int \fIbytes_buffer\fP\^;
  4224. .br
  4225.       KeySym *\fIkeysym_return\fP\^;
  4226. .br
  4227.       Status *\fIstatus_return\fP\^;
  4228. .FN
  4229. .FD 0
  4230. int XwcLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^)
  4231. .br
  4232.       XIC \fIic\fP\^;
  4233. .br
  4234.       XKeyPressedEvent *\fIevent\fP\^;
  4235. .br
  4236.       wchar_t *\fIbuffer_return\fP\^;
  4237. .br
  4238.       int \fIwchars_buffer\fP\^;
  4239. .br
  4240.       KeySym *\fIkeysym_return\fP\^;
  4241. .br
  4242.       Status *\fIstatus_return\fP\^;
  4243. .FN
  4244. .IP \fIic\fP 1i
  4245. Specifies the input context.
  4246. .ds Ev key event to be used
  4247. .IP \fIevent\fP 1i
  4248. Specifies the \*(Ev.
  4249. .IP \fIbuffer_return\fP 1i
  4250. Returns a multibyte string or wide character string (if any)
  4251. from the input method.
  4252. .IP \fIbytes_buffer\fP 1i
  4253. .br
  4254. .ns
  4255. .IP \fIwchars_buffer\fP 1i
  4256. Specifies space available in return buffer.
  4257. .IP \fIkeysym_return\fP 1i
  4258. Returns the KeySym computed from the event if this argument is not NULL.
  4259. .IP \fIstatus_return\fP 1i
  4260. Returns a value indicating what kind of data is returned.
  4261. .\" End marker code here
  4262. .LP
  4263. The
  4264. .PN XmbLookupString
  4265. and
  4266. .PN XwcLookupString
  4267. functions return the string from the input method specified
  4268. in the buffer_return argument.
  4269. If no string is returned,
  4270. the buffer_return argument is unchanged.
  4271. .LP
  4272. The KeySym into which the KeyCode from the event was mapped is returned
  4273. in the keysym_return argument if it is non-NULL and the status_return
  4274. argument indicates that a KeySym was returned.
  4275. If both a string and a KeySym are returned,
  4276. the KeySym value does not necessarily correspond to the string returned.
  4277. .LP
  4278. Note that
  4279. .PN XmbLookupString
  4280. returns the length of the string in bytes and that
  4281. .PN XwcLookupString
  4282. returns the length of the string in characters.
  4283. .LP
  4284. .PN XmbLookupString
  4285. and
  4286. .PN XwcLookupString
  4287. return text in the encoding of the locale bound to the input method
  4288. of the specified input context.
  4289. .LP
  4290. Note that each string returned by
  4291. .PN XmbLookupString
  4292. and
  4293. .PN XwcLookupString
  4294. begins in the initial state of the encoding of the locale
  4295. (if the encoding of the locale is state-dependent).
  4296. .NT
  4297. In order to insure proper input processing,
  4298. it is essential that the client pass only 
  4299. .PN KeyPress
  4300. events to
  4301. .PN XmbLookupString
  4302. and
  4303. .PN XwcLookupString .
  4304. Their behavior when a client passes a 
  4305. .PN KeyRelease
  4306. event is undefined.
  4307. .NE
  4308. .LP
  4309. Clients should check the status_return argument before
  4310. using the other returned values.
  4311. These two functions both return a value to status_return 
  4312. that indicates what has been returned in the other arguments.
  4313. The possible values returned are:
  4314. .TS
  4315. lw(1.5i) lw(4.3i).
  4316. T{
  4317. .PN XBufferOverflow
  4318. T}    T{
  4319. The input string to be returned is too large for the supplied buffer_return.
  4320. The required size
  4321. .Pn ( XmbLookupString
  4322. in bytes;
  4323. .PN XwcLookupString
  4324. in characters) is returned as the value of the function,
  4325. and the contents of buffer_return and keysym_return are not modified.
  4326. The client should recall the function with the same event
  4327. and a buffer of adequate size in order to obtain the string.
  4328. T}
  4329. T{
  4330. .PN XLookupNone
  4331. T}    T{
  4332. No consistent input has been composed so far.
  4333. The contents of buffer_return and keysym_return are not modified, 
  4334. and the function returns zero.
  4335. T}
  4336. T{
  4337. .PN XLookupChars
  4338. T}    T{
  4339. Some input characters have been composed.
  4340. They are placed in the buffer_return argument,
  4341. and the string length is returned as the value of the function.
  4342. The string is encoded in the locale bound to the input context.
  4343. The contents of the keysym_return argument is not modified.
  4344. T}
  4345. T{
  4346. .PN XLookupKeySym
  4347. T}    T{
  4348. A KeySym has been returned instead of a string
  4349. and is returned in keysym_return.
  4350. The contents of the buffer_return argument is not modified,
  4351. and the function returns zero.
  4352. T}
  4353. T{
  4354. .PN XLookupBoth
  4355. T}    T{
  4356. Both a KeySym and a string are returned;
  4357. .PN XLookupChars
  4358. and
  4359. .PN XLookupKeySym
  4360. occur simultaneously.
  4361. T}
  4362. .TE
  4363. .LP
  4364. It does not make any difference if the input context passed as an argument to
  4365. .PN XmbLookupString
  4366. and
  4367. .PN XwcLookupString
  4368. is the one currently in possession of the focus or not.
  4369. Input may have been composed within an input context before it lost the focus,
  4370. and that input may be returned on subsequent calls to
  4371. .PN XmbLookupString
  4372. or
  4373. .PN XwcLookupString ,
  4374. even though it does not have any more keyboard focus.
  4375. .NH 2
  4376. Input Method Conventions
  4377. .XS
  4378. \*(SN Input Method Conventions
  4379. .XE
  4380. .LP
  4381. The input method architecture is transparent to the client.
  4382. However, clients should respect a number of conventions in order
  4383. to work properly.
  4384. Clients must also be aware of possible effects of synchronization
  4385. between input method and library in the case of a remote input server.
  4386. .NH 3 
  4387. Client Conventions
  4388. .XS
  4389. \*(SN Client Conventions
  4390. .XE
  4391. .LP
  4392. A well-behaved client (or toolkit) should first query the input method style.
  4393. If the client cannot satisfy the requirements of the supported styles
  4394. (in terms of geometry management or callbacks),
  4395. it should negotiate with the user continuation of the program
  4396. or raise an exception or error of some sort.
  4397. .NH 3 
  4398. Synchronization Conventions
  4399. .XS
  4400. \*(SN Synchronization Conventions
  4401. .XE
  4402. .LP
  4403. A 
  4404. .PN KeyPress
  4405. event with a KeyCode of zero is used exclusively as a
  4406. signal that an input method has composed input which can be
  4407. return by
  4408. .PN XmbLookupString
  4409. or
  4410. .PN XwcLookupString .
  4411. No other use is made of a 
  4412. .PN KeyPress
  4413. event with KeyCode of zero.
  4414. .LP
  4415. Such an event may be generated by either a front-end
  4416. or a back-end input method in an implementation dependent manner.
  4417. Some possible ways to generate this event include:
  4418. .IP \(bu 5
  4419. A synthetic event sent by an input method server
  4420. .IP \(bu 5
  4421. An artificial event created by a input method filter and pushed
  4422. onto a client's event queue
  4423. .IP \(bu 5
  4424. A 
  4425. .PN KeyPress
  4426. event whose KeyCode value is modified by an input method filter
  4427. .LP
  4428. When callback support is specified by client,
  4429. input methods will not take action unless they explicitly
  4430. called back the client and obtained no response
  4431. (the callback is not specified or returned invalid data).
  4432. .NH 2
  4433. String Constants
  4434. .XS
  4435. \*(SN String Constants
  4436. .XE
  4437. .LP
  4438. The following symbols for string constants are defined in
  4439. .Pn < X11/Xlib.h >.
  4440. Although they are shown here with particular macro definitions,
  4441. they may be implemented as macros, as global symbols, or as a
  4442. mixture of the two.  The string pointer value itself
  4443. is not significant; clients must not assume that inequality of two
  4444. values implies inequality of the actual string data.
  4445. .IN "XNVaNestedList" "" "@DEF@"
  4446. .IN "XNQueryInputStyle" "" "@DEF@"
  4447. .IN "XNClientWindow" "" "@DEF@"
  4448. .IN "XNInputStyle" "" "@DEF@"
  4449. .IN "XNFocusWindow" "" "@DEF@"
  4450. .IN "XNResourceName" "" "@DEF@"
  4451. .IN "XNResourceClass" "" "@DEF@"
  4452. .IN "XNGeometryCallback" "" "@DEF@"
  4453. .IN "XNFilterEvents" "" "@DEF@"
  4454. .IN "XNPreeditStartCallback" "" "@DEF@"
  4455. .IN "XNPreeditDoneCallback" "" "@DEF@"
  4456. .IN "XNPreeditDrawCallback" "" "@DEF@"
  4457. .IN "XNPreeditCaretCallback" "" "@DEF@"
  4458. .IN "XNPreeditAttributes" "" "@DEF@"
  4459. .TS
  4460. lw(.5i) lw(2i) lw(2i).
  4461. T{
  4462. #define
  4463. T}    T{
  4464. .PN XNVaNestedList
  4465. T}    T{
  4466. "XNVaNestedList"
  4467. T}
  4468. T{
  4469. #define
  4470. T}    T{
  4471. .PN XNQueryInputStyle
  4472. T}    T{
  4473. "queryInputStyle"
  4474. T}
  4475. T{
  4476. #define
  4477. T}    T{
  4478. .PN XNClientWindow
  4479. T}    T{
  4480. "clientWindow"
  4481. T}
  4482. T{
  4483. #define
  4484. T}    T{
  4485. .PN XNInputStyle
  4486. T}    T{
  4487. "inputStyle"
  4488. T}
  4489. T{
  4490. #define
  4491. T}    T{
  4492. .PN XNFocusWindow
  4493. T}    T{
  4494. "focusWindow"
  4495. T}
  4496. T{
  4497. #define
  4498. T}    T{
  4499. .PN XNResourceName
  4500. T}    T{
  4501. "resourceName"
  4502. T}
  4503. T{
  4504. #define
  4505. T}    T{
  4506. .PN XNResourceClass
  4507. T}    T{
  4508. "resourceClass"
  4509. T}
  4510. T{
  4511. #define
  4512. T}    T{
  4513. .PN XNGeometryCallback
  4514. T}    T{
  4515. "geometryCallback"
  4516. T}
  4517. T{
  4518. #define
  4519. T}    T{
  4520. .PN XNFilterEvents
  4521. T}    T{
  4522. "filterEvents"
  4523. T}
  4524. T{
  4525. #define
  4526. T}    T{
  4527. .PN XNPreeditStartCallback
  4528. T}    T{
  4529. "preeditStartCallback"
  4530. T}
  4531. T{
  4532. #define
  4533. T}    T{
  4534. .PN XNPreeditDoneCallback
  4535. T}    T{
  4536. "preeditDoneCallback"
  4537. T}
  4538. T{
  4539. #define
  4540. T}    T{
  4541. .PN XNPreeditDrawCallback
  4542. T}    T{
  4543. "preeditDrawCallback"
  4544. T}
  4545. T{
  4546. #define
  4547. T}    T{
  4548. .PN XNPreeditCaretCallback
  4549. T}    T{
  4550. "preeditCaretCallback"
  4551. T}
  4552. T{
  4553. #define
  4554. T}    T{
  4555. .PN XNPreeditAttributes
  4556. T}    T{
  4557. "preeditAttributes"
  4558. T}
  4559. .TE
  4560. .sp -1
  4561. .TS
  4562. lw(.5i) lw(2i) lw(2i).
  4563. T{
  4564. #define
  4565. T}    T{
  4566. .PN XNStatusStartCallback
  4567. T}    T{
  4568. "statusStartCallback"
  4569. T}
  4570. T{
  4571. #define
  4572. T}    T{
  4573. .PN XNStatusDoneCallback
  4574. T}    T{
  4575. "statusDoneCallback"
  4576. T}
  4577. T{
  4578. #define
  4579. T}    T{
  4580. .PN XNStatusDrawCallback
  4581. T}    T{
  4582. "statusDrawCallback"
  4583. T}
  4584. T{
  4585. #define
  4586. T}    T{
  4587. .PN XNStatusAttributes
  4588. T}    T{
  4589. "statusAttributes"
  4590. T}
  4591. T{
  4592. #define
  4593. T}    T{
  4594. .PN XNArea
  4595. T}    T{
  4596. "area"
  4597. T}
  4598. T{
  4599. #define
  4600. T}    T{
  4601. .PN XNAreaNeeded
  4602. T}    T{
  4603. "areaNeeded"
  4604. T}
  4605. T{
  4606. #define
  4607. T}    T{
  4608. .PN XNSpotLocation
  4609. T}    T{
  4610. "spotLocation"
  4611. T}
  4612. T{
  4613. #define
  4614. T}    T{
  4615. .PN XNColormap
  4616. T}    T{
  4617. "colorMap"
  4618. T}
  4619. T{
  4620. #define
  4621. T}    T{
  4622. .PN XNStdColormap
  4623. T}    T{
  4624. "stdColorMap"
  4625. T}
  4626. T{
  4627. #define
  4628. T}    T{
  4629. .PN XNForeground
  4630. T}    T{
  4631. "foreground"
  4632. T}
  4633. T{
  4634. #define
  4635. T}    T{
  4636. .PN XNBackground
  4637. T}    T{
  4638. "background"
  4639. T}
  4640. T{
  4641. #define
  4642. T}    T{
  4643. .PN XNBackgroundPixmap
  4644. T}    T{
  4645. "backgroundPixmap"
  4646. T}
  4647. T{
  4648. #define
  4649. T}    T{
  4650. .PN XNFontSet
  4651. T}    T{
  4652. "fontSet"
  4653. T}
  4654. T{
  4655. #define
  4656. T}    T{
  4657. .PN XNLineSpace
  4658. T}    T{
  4659. "lineSpace"
  4660. T}
  4661. T{
  4662. #define
  4663. T}    T{
  4664. .PN XNCursor
  4665. T}    T{
  4666. "cursor"
  4667. T}
  4668. .TE
  4669. .IN "XNStatusStartCallback" "" "@DEF@"
  4670. .IN "XNStatusDoneCallback" "" "@DEF@"
  4671. .IN "XNStatusDrawCallback" "" "@DEF@"
  4672. .IN "XNStatusAttributes" "" "@DEF@"
  4673. .IN "XNArea" "" "@DEF@"
  4674. .IN "XNAreaNeeded" "" "@DEF@"
  4675. .IN "XNSpotLocation" "" "@DEF@"
  4676. .IN "XNColormap" "" "@DEF@"
  4677. .IN "XNStdColormap" "" "@DEF@"
  4678. .IN "XNForeground" "" "@DEF@"
  4679. .IN "XNBackground" "" "@DEF@"
  4680. .IN "XNFontSet" "" "@DEF@"
  4681. .IN "XNLineSpace" "" "@DEF@"
  4682. .IN "XNCursor" "" "@DEF@"
  4683. .bp
  4684.