Volume 6A: Motif Programming Manual

15.5.4 Focus Callbacks

The XmNfocusCallback and XmNlosingFocusCallback callback routines can be used to monitor when a

Text widget gains and loses the keyboard focus. A Text widget can receive the input focus if the user intentionally

shifts the focus to the widget or if the application moves the focus using XmProcessTraversal(). When a

widget gains the input focus and the insertion cursor is not visible, we can make it visible and cause the widget to

automatically scroll to the current cursor location by installing an XmNfocusCallback routine that calls

XmTextShowCursorPosition(), as shown in the following code fragment:

{

Widget text_w;

extern void gain_focus();

...

text_w = XmCreateScrolledText(...);

XtAddCallback(text_w, XmNfocusCallback, gain_focus, NULL);

...

}

void

gain_focus(text_w, client_data, call_data)

Widget text_w;

XtPointer client_data;

XtPointer call_data;

{

XmTextShowCursorPosition (text_w, XmTextGetCursorPosition (text_w));

}

The XmNfocusCallback is passed a callback structure of type XmAnyCallbackStruct with the callback

reason set to XmCR_FOCUS.

The XmNlosingFocusCallback callback can be used to monitor when the Text widget loses its focus. The

callback structure passed to the callback function is an XmTextVerifyCallbackStruct. All of the fields except

the text field are valid, and the reason field is set to XmCR_LOSING_FOCUS.

15.6 Text Widget Internationalization

In Motif 1.2, the Text and TextField widgets have been modified to support internationalized input and output. The

internationalization capabilities of the widgets are layered on top of the functionality provided in X11R5, which is

based on the ANSI−C locale model. An internationalized application uses a library that reads a locale database at

runtime to get information about the user's language environment. An application that uses the X Toolkit establishes

its language environment (or locale) by registering a language procedure using XtSetLanguageProc(), as

explained in Section #slangproc. See Volume Four, X Toolkit Intrinsics Programming Manual, for more information

on the localization of an Xt−based application.

15.6.1 Text Representation

One of the important characteristics of a locale is the encoding used to represent the character set for the locale. A

character set is simply a set of characters, while an encoding is a numeric representation of these characters. A charset

(not the same as a character set) is an encoding in which all of the characters use the same number of bits. The

Latin−1 charset (ISO8859−1) defines an encoding for all of the characters used in Western languages. However, not

all languages can be represented by a single charset. Japanese text commonly contains words written using the Latin

alphabet, as well as phonetic characters from the katakana and hirigana alphabets, and ideographic kanji characters.

15 Text Widgets 15.5.4 Focus Callbacks

425

Each of these character sets has its own charset. The phonetic and Latin charsets are 8−bits wide, while the

ideographic charset is 16−bits wide. Since the charsets must be combined into a single encoding for Japanese text, the

encoding uses shift sequences to specify the character set for each character in a string.

When an encoding contains shift sequences and characters of nonuniform width, strings can still be stored in a

standard NULL−terminated array of characters; this representation is known as a multibyte string. Strings can also be

stored using a wide−character type (wchar_t in ANSI−C) in which each character has a fixed size and occupies one

array element. ANSI−C provides functions that convert between multibyte and wide−character strings and the text

output routines in X11R5 support both types of strings. Multibyte strings are usually more compact than

wide−character strings, but wide−character strings are easier to work with. If an internationalized application performs

any text manipulation, it must take care to handle all strings properly. Fortunately, many applications can do

internationalized text input and output without performing any manipulations on the text.

Multibyte strings are NULL−terminated, while there is no single convention for the termination of wide−character

strings. The following C string−handling routines are safe to use with multibyte strings: strcat(), strcmp(),

strcpy(), strlen(), and strncmp(). The string comparison routines are only useful to check for

byte−for−byte equality; use strcoll() to compare strings for sorting. None of the C string−handling routines work

with wide−character strings.

Multibyte strings can be written to a file or an output stream. If the terminal is operating in the current locale, printing

a multibyte string to stdout or stderr causes the correct text to be displayed. Multibyte strings can also be read

from a file or the stdin input stream. If the file is encoded in the current locale, or the terminal is operating in the

current locale, the strings that are read are meaningful. For a more complete description of working with multibyte

and wide−character strings, see Volume One, Xlib Programming Manual.

The Motif 1.2 Text and TextField widgets provide two resources for specifying their textual data: XmNvalue and

XmNvalueWcs. The XmNvalue resource specifies the text string as a char * value, so it can be used to set the

value of the widget to a multibyte string. XmN-valueWcs specifies the string as a wchar_t * value, so it is used to

set the value to a wide−character string. This resource cannot be specified in a resource file. If XmNvalue and

XmNvalueWcs are both defined, the value of XmNvalueWcs takes precedence.

Regardless of which resource you set, the widgets store the text internally as a multibyte string. The widgets take care

of converting between multibyte strings and wide−character strings when necessary. As a result, you can set the text

string using the XmNvalue resource and retrieve it with XtVaGetValues() using the XmNvalueWcs resource.

The Text widget provides the following convenience routines for manipulating the text value as a wide−character

string:

XmTextFindStringWcs()

XmTextGetSelectionWcs()

XmTextGetStringWcs()

XmTextGetSubstringWcs()

XmTextInsertWcs()

XmTextReplaceWcs()

XmTextSetStringWcs()

These routines work for both Text and TextField widgets. The TextField also provides corresponding functions that

only work with TextField widgets. All of these routines function identically to their regular character string

counterparts, except that they take or return wide−character string values. If you have specified the text string using

XmNvalue, you can still use the wide−character string routines because they handle any necessary string

conversions. For more information on the different wide−character routines, see Volume Six B, Motif Reference

Manual.

15 Text Widgets 15.5.4 Focus Callbacks

426