Volume 6A: Motif Programming Manual

The reference pages for the Text and TextField widgets (in Volume Six B, Motif Reference Manual; Section 2, Motif

and Xt Widget Classes) lists the default translations for the widgets. See Volume Four, X Toolkit Intrinsics

Programming Manual, for a description of how to programmatically alter translation tables; see Volume Three, X

Window System User's Guide, for a description of how a user can customize widget translations. See Chapter 17, The

Clipboard, for a discussion of the lower−level Motif clipboard functions.

15.2 Text Widget Basics

In order to understand the complexities of the Text and TextField widgets, you need to know about some of the basic

resources and functions that they provide. This section describes the fundamentals of working with text widgets,

including how to create the widgets, how to work with the textual data, and how to control simple aspects of

appearance and behavior. Applications that wish to use the Text widget need to include the file <Xm/Text.h>.

TextField widgets require the file <Xm/TextF.h>. You can create a Text widget using

XtVaCreateManagedWidget() as usual:

Widget text_w;

text_w = XtVaCreateManagedWidget("name",

xmTextWidgetClass, parent,

resource−value−list,

NULL);

To create a TextField widget instead, specify the class as xmTextFieldWidgetClass.

15.2.1 The Textual Data

The XmNvalue resource of the Text and TextField widgets provides the most basic means of access to the internal

text storage for the widgets. Unlike the other widgets in the Motif toolkit that use text, the text widgets do not use

compound strings for their values. Instead, the value is specified as a regular C string, as shown in the source code

XtSetLanguageProc() is only available in X11R5; there is no corresponding function in X11R4.

/* simple_text.c −− Create a minimally configured Text widget */

#include <Xm/Text.h>

main(argc, argv)

int argc;

char *argv[];

{

Widget toplevel;

XtAppContext app;

XtSetLanguageProc (NULL, NULL, NULL);

toplevel = XtVaAppInitialize (&app, "Demos",

NULL, 0, &argc, argv, NULL, NULL);

XtVaCreateManagedWidget ("text", xmTextWidgetClass, toplevel,

XmNvalue, "Now is the time...",

NULL);

XtRealizeWidget (toplevel);

XtAppMainLoop (app);

}

This short program simply creates a Text widget with the initial value shown in the figure.

15 Text Widgets 15.2 Text Widget Basics

381

Output of simple_text.c

In Motif 1.2, both widgets also provide the XmNvalueWcs resource for storing a wide−character representation of

the text value. For more information on using the text widgets in an internationalized application, see Section

#stexti18n. The initial value of the XmNvalue resource may be set either when the widget is created or by using

XtVaSetValues() after the widget has been created. The value of the resource always represents the entire text of

the widget. You can also use a Motif convenience routine, XmTextSetString(), to set the text value. This routine

takes the following form:

void

XmTextSetString(text_w, value)

Widget text_w;

char *value;

This routine works for both Text and TextField widgets. The TextField widget has a corresponding routine,

XmTextFieldSetString(), but it only works for TextField widgets. If you are using both types of text widgets

in an application, we recommend using the Text widget routines to manipulate all of the widgets. Since these routines

work with both types of widgets, you don't need to keep track of the widget types.

Although the convenience routine and XtVaSetValues() produce the same results, the convenience routine may

be more efficient since it accesses the internals of the widget directly, while the XtVaSetValues() method

involves going through Xt. On the other hand, if you are setting a number of resources at the same time, the

XtVaSetValues() method is better because all of the resources can be set in a single function call. Whichever

function you use, the text value is copied into the internals of the widget, and the displayed value is changed

accordingly.

If, for whatever reason, you are making multiple changes in a short period of time to the text in a Text widget, you

may have problems with visual flashing in the widget. With Motif 1.2, you can solve this problem by calling

XmTextDisableRedisplay() to turn off visual updating in the widget. After the call, the appearance of the

widget remains unchanged until XmTextEnableRedisplay() is called. You can access the textual data in a Text

widget using XtVaGetValues() or XmTextGetString(). XmTextGetString() allocates enough space

(using XtMalloc()) for all of the text in the widget and returns a pointer to the allocated data. You can modify the

returned data any way you like, and then you must free it using XtFree() when you are done. The code fragment

below demonstrates the use of XmTextGetString():

char *text;

if (text = XmTextGetString (text_w)) {

/* manipulate text in whatever way is necessary */

...

/* free text or there will be a memory leak */

XtFree (text);

}

XmTextGetString() works with both Text and TextField widgets, while the corresponding TextField routine,

XmTextFieldGetString(), only works with TextField widgets. In Motif 1.2, you can also use

15 Text Widgets 15.2 Text Widget Basics

382