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:
extern void gain_focus();
text_w = XmCreateScrolledText(...);
XtAddCallback(text_w, XmNfocusCallback, gain_focus, NULL);
gain_focus(text_w, client_data, 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
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
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
15 Text Widgets 15.5.4 Focus Callbacks