Volume 6A: Motif Programming Manual

The widgets also provide a wide−character version of the text modification callback,

XmN-modifyVerifyCallbackWcs. This callback is invoked before the value of the widget is modified, so an

application can use it to monitor changes in the widget. The callback is -passed a callback structure of type

XmTextVerifyCallbackStructWcs, which is defined as follows:

typedef struct {

int reason;

XEvent *event;

Boolean doit;

XmTextPosition currInsert, newInsert;

XmTextPosition startPos, endPos;

XmTextBlockWcs text;

} XmTextVerifyCallbackStructWcs;

With this structure the reason field has the value XmCR_MODIFYING_TEXT_VALUE. All of the fields have the

same meaning as the fields in the regular XmTextVerifyCallbackStruct, except that the text field is a

pointer of type XmTextBlockWcs. This structure is defined as follows:

typedef struct {

wchar_t *wcsptr;

int length;

} XmTextBlockRecWcs, *XmTextBlockWcs;

If callback routines are registered for both the XmN-modifyVerifyCallback and the

-XmNmodifyVerifyCallbackWcs, the routines for the XmNmodifyVerifyCallback are invoked first. The

resulting data, which may have been modified, is passed to the XmN-modifyVerifyCallbackWcs routines.

15.6.2 Text Output

The Text and TextField widgets do not use compound strings, so their text output functionality is based directly on

Xlib's internationalized text output capabilities. To support languages that use multiple charsets, X11R5 introduced

the XFontSet abstraction for its text output routines. An XFontSet contains all of the fonts necessary to display

text in the current locale. The new text output routines work with font sets, so they can render text for locales that

require multiple charsets. See Volume One, Xlib Programming Manual, for more information on internationalized

text output.

Each of the widgets has a XmNfontList resource for specifying the font that it uses. Since the widgets do not use

compound strings, they cannot use font list tags to display text using different fonts as decribed in Section #sfonttag.

However, the font list can specify a font set, so the widgets can display text using multiple character sets in a locale

that requires them. The widgets pick a font by searching the font list for a font set that has the tag

XmFONTLIST_DEFAULT_TAG. If the search finds such a font set, it is used. Otherwise, the widgets use the first font

set specified in the font list. If the font list does not contain a font set, the first font is used. If you specify a font list

entry with the tag XmFONTLIST_DEFAULT_TAG, make sure that it is appropriate for the encoding of the current

locale.

15.6.3 Text Input

Converting user keystrokes into text in the encoding of the current locale is the most difficult task of

internationalization. An internationalized program cannot assume any particular mapping between keystrokes and

input characters, since it must run in any locale on a single workstation, using a single keyboard. The mapping

between keystrokes and Japanese characters is very different and much more complex than the mapping between

keystrokes and Latin characters, for example. When there are more characters in the codeset of a locale than there are

15 Text Widgets 15.6.2 Text Output

427

keys on a keyboard, some sort of input method is required for mapping between multiple keystrokes and input

characters.

All of the characters for English can be entered using the standard keyboard; the SHIFT key makes it possible to enter

both lowercase and uppercase letters as well as the number and punctuation characters. For many European languages,

the most common accented characters may appear directly on a keyboard, but there are still a number of other

characters that cannot be entered with any single shifted or unshifted keystroke. In these cases, the input method is

typically implemented in the keyboard hardware using a special key that puts the keyboard in "compose" mode in

which one or more of the following keystrokes are combined into a single character.

The Asian ideographic languages are what make internationalized text input complicated. Japanese and Korean both

have phonetic alphabets that are small enough to be mapped onto a keyboard. While it is sometimes adequate to leave

text in this representation, the user usually wants the final text to be in the full ideographic language. Input methods

for these languages often have the user type the phonetic symbols for a particular word or words and then signal that

the composition or pre−editing is complete. At this point, the input method can look up the string of phonetic

characters in a dictionary and convert it to the equivalent character or characters in the ideographic language. Multiple

characters can have the same phonetic representation, so the user may still have to select the desired character.

Since input methods can be large and complex and they vary from locale to locale, it does not make sense to link

every application with a generic input method that is localized at runtime. The X Input Method (XIM) abstraction in

X11R5 supports the model of an input manager that is run as a separate process and that communicates with the X

server and with the application. An application that needs to use an input method calls XOpenIM() to establish a

connection to the input method that is appropriate for the current locale.

An input method needs to provide feedback to the user, so X defines three areas for interaction:

The status area is an output−only window that displays information about the state of the input method

interaction.

•

The pre−edit area displays the intermediate text while the user is composing a character.•

The auxiliary area is used to display any dialog boxes or popup menus that are needed by the input method.•

An application generally provides the status and pre−edit areas to the input method, which is responsible for their

contents. The auxiliary area is managed entirely by the input method. The location of the pre−edit area depends on the

interaction style used between the input method and the application. X defines the following four interaction styles:

The root−window style, where the input method displays the pre−edit data in a window that is a child of the

root window.

•

The off−the−spot style, in which the input method displays the data at a fixed location in the application

window, often at the bottom of the window.

•

The over−the−spot style, where the input method displays the data in a window of its own that is placed over

the current insertion point.

•

The on−the−spot style, in which the input method directs the application to display the pre−edit data, so the

application can display the data however it wants.

•

An application must choose an interaction style that is supported by the input method and it must provide the pre−edit

and status areas as required by that style.

Just as the X server can display multiple windows for a single client, an input method can maintain multiple input

contexts for an application. A text editor that supports multiple editing windows within a single top−level window

could create an input context for each window or share a single context among all of the windows. The function

XCreateIC() creates an X Input Context (XIC) that keeps track of information about the input context, such as the

15 Text Widgets 15.6.2 Text Output

428

interaction style, the windows used for the pre−edit and status areas, and the font set for the text.

When an application gets a KeyPress event, it needs to use that event in a call to XmbLookupString() or

XwcLookupString() to get the multibyte or wide−character string encoded in the current locale. These routines

are analogous to XLookupString(), but this routine can only return Latin−1 strings, so it is not appropriate for

internationalized input.

The support for input methods in Xlib is designed to be incorporated within toolkits and widgets. Accordingly, the

internationalized text input capabilities of the Motif Text and TextField widgets are layered on top of the input method

mechanism. Fortunately, the widgets encapsulate most of the lower−level functionality, so you don't need to

understand the details of the Xlib implementation. For a more complete description of the Xlib functionality, see

Volume One, Xlib Programming Manual.

Motif leaves it to the hardware vendors to supply input methods, so the toolkit does not provide any itself. If you need

to provide internationalized text input, consult the documentation for your system for information about the input

methods that it supports. Alternately, you can build one of the contributed input methods provided as part of X11R5.

R5 as shipped from MIT contains two separate implementations of the input method facilities. The Xsi

implementation is the default on all but Sony machines, which use the Ximp implementation. Each implementation

defines its own protocol for communication between Xlib and input methods. Ximp and Xsi each come with

contributed input methods that are not compatible with each other. For X11R6, the X Consortium is planning to

standardize the input method implementation, so you may want to enquire about the status of that effort before putting

any significant effort into a product that uses one of these implementations.

When you create an editable Text or TextField widget, it automatically provides a connection to the input method for

the current locale. The VendorShell widget plays a role in internationalization as it defines the XmNinputMethod

and XmNpreeditType resources for specifying the input method and the interaction style, respectively. A Text or

TextField widget is always created as an ancestor of a VendorShell, so the widget can access these resources to set up

the connection to the input method. The resources are defined by the VendorShell because it handles the geometry

management of the pre−edit and status areas for the input method.

The XmNinputMethod resource specifies the input method portion of the locale modifier that is set before an input

method is opened. The format of the value for this resource is vendor−defined. The XmNpreeditType resource sets

the interaction style used by the input method. The syntax, possible values, and default value of this resource are also

vendor−dependent.

Motif only supports the over−the−spot, off−the−spot, and root−window interaction styles. Under the off−the−spot

style, the VendorShell positions the pre−edit and status areas below the application's main window but inside the

shell. The VendorShell handles the geometry management for the areas and places a separator between the main

window and the input method area. If the application sets or gets the XmNheight of the shell using

XtVaSetValues() or XtVaGetValues(), the height includes the height of the input method area. With the

over−the−spot style, the VendorShell still displays the status area at the bottom of the application's top−level window,

but the pre−edit area is positioned over the insertion cursor in the Text widget. The Text widget passes the insertion

position to the input method, so that the pre−edit area moves as with the insertion cursor.

The Motif toolkit implements its internationalized text input functionality using the following undocumented public

routines:

XmImRegister()

XmImUnregister()

XmImSetFocusValues()

XmImSetValues()

XmImUnsetFocus()

15 Text Widgets 15.6.2 Text Output

429