The text in a Text widget can be multiline or constrained to be a single line, depending on the value of the XmNeditMode resource. In multiline Text, pressing KUp moves the insertion cursor, the point at which new text is inserted, to the previous line, and pressing KDown moves the insertion cursor to the next line. Other actions move the insertion cursor forward and backward by paragraphs. Pressing KSpace, KTab, or KEnter causes the corresponding character to be inserted into the text. For this reason, some virtual key bindings are different in Text from those in other widgets, as shown in the following table:

In a single-line widget, pressing KSpace still inserts a space into the text. However, KUp and KDown now move keyboard focus to the previous or next traversable widget, and KTab traverses to the next tab group. KEnter invokes the XmNactivateCallback callbacks. The actions for moving by paragraphs have no effect. In other words, a single-line Text widget acts more as a simple control than a field control.

A TextField is essentially the same as a Text widget in single-line mode, except that its performance is optimized for single-line text operations. Although TextField has a complete set of convenience routines of its own, the widget argument to the Text convenience routines can be either a Text or a TextField widget.

Both Text and TextField allow the user to cut, copy, and paste text using the clipboard, primary transfer, or secondary transfer. The user can also drag and drop text within a widget, between widgets, or from a Label or List widget to a Text or TextField widget. In all cases, the user first selects text in some widget and then inserts the selected text into a Text or TextField widget.

This section explains how selection works in Text and TextField. Understanding selection requires understanding of several concepts: primary selection, secondary selection, clipboard selection, the destination widget, the insertion cursor, the selection anchor, and pending delete.

Selections are the primary means of exchanging data between X clients. A selection is a piece of data. Each display may have several kinds of selections, but only one selection of each kind can exist at any time on the display. A client owns each selection, and the selection is attached to a window. Clients can acquire or give up ownership of a selection and can request that the owner convert the selection into some data type and place the results on a property of a particular window. This mechanism makes it possible to select and then cut, copy, or paste data from one client to another. Selections are discussed in detail in the X Window System Inter-Client Communication Conventions Manual (ICCCM).

Text and TextField support transfers using the three kinds of selection common to all X clients:

The destination is the widget that, at any particular time, would receive the selection if the user were to invoke a move, copy, or paste operation. A Text or TextField widget must be both sensitive and editable to become the destination. When the XmNkeyboardFocusPolicy of the shell is XmEXPLICIT, an editable widget becomes the destination when it receives keyboard focus. When the XmNkeyboardFocusPolicy is XmPOINTER, an editable widget becomes the destination when it receives any mouse button or keyboard input. If the destination widget becomes insensitive or uneditable, there is no destination widget.

The insertion cursor is an I-beam cursor that shows where text, including a selection, would be inserted in a Text or TextField widget. The insertion cursor appears as a solid I-beam when the widget is in normal mode (explained below) and when it is either the widget with keyboard focus or the destination widget. Otherwise, the insertion cursor appears as a stippled I-beam.

The anchor is a position in the text of a widget that marks one boundary of a selection or a potential selection. For example, the user can select a range of text by pressing, dragging, and releasing BSelect. The anchor is set at the point of the button press, and the selection extends to the point of the button release. When the user takes an action to extend an existing selection, Motif first adjusts the anchor using a balance-beam method: it moves the anchor to the end of the existing selection that is farthest from the point of the button or key press that initiates the extend action.

Text and TextField have an XmNpendingDelete resource. When the value of this resource is True, as it is by default, some user actions cause a selection to be deleted. When a selection exists and the insertion cursor is not disjoint from it, an operation that inserts text, including a transfer of the secondary or clipboard selection, deletes the primary selection before inserting the text. Also, when a selection exists and the insertion cursor is not disjoint from it, an operation that deletes text deletes the primary selection instead of the text that would otherwise be removed. When XmNpendingDelete is False, these operations do not delete the selection.

Text has a number of callback lists for communication with the application. Text invokes callbacks whenever the widget gains or loses focus, when it gains or loses the primary selection, before the insertion cursor is moved or text is modified, and when the text string changes or the activate() action is invoked.

Text passes these callbacks a pointer to either an XmAnyCallbackStruct or an XmTextVerifyCallbackStruct (or XmTextVerifyCallbackStructWcs) structure. The two verification structures contain the current and new positions of the insertion cursor, the starting and ending positions of the text to be modified, a pointer to an XmTextBlockRec (or XmTextBlockRecWcs) structure with information about the text to be modified, and a Boolean in/out doit member that the callback procedure can set to tell the widget whether or not to go ahead with the modification.

Following is a summary of the callbacks:

These callbacks provide a great deal of flexibility for an application to alter the behavior of the Text widget. For example, an application can prevent text from being inserted, as when the user types a password, using the XmNmodifyVerifyCallback or XmNmodifyVerifyCallbackWcs callbacks. The application can prevent any text from appearing by setting the doit member of the XmTextVerifyCallbackStruct (or XmTextVerifyCallbackStructWcs) to False. The application can also alter the text that will appear by creating a new text string and setting the ptr member of the XmTextBlockRec structure (or the wcsptr member of the XmTextBlockRecWcs structure) to the new string.

Following is an example of an XmNmodifyVerifyCallback that substitutes a string of characters for any text a user enters. Because the XmNmodifyVerifyCallback procedures are most commonly invoked after the user enters a character, this routine usually substitutes the replacement string for each character the user types. This example could be used with a single-line Text widget as part of a simple password-entry program. In this case, the XmNmodifyVerifyCallback procedure would need additional code to save the characters the user types, and the program would need an XmNactivateCallback procedure to check whether the saved characters match the password.

/* XmNmodifyVerifyCallback procedure that
 * replaces text the user enters
 * with a replacement string passed in as
 * application data. */
void ModifyVerifyCB(Widget w, XtPointer app_data,
         XtPointer widget_data)
{
  char *replace_string = (char *) app_data;
  XmTextVerifyCallbackStruct *widget_info =
    (XmTextVerifyCallbackStruct *) widget_data;
  if (widget_info->text->length > 0) {
    widget_info->text->length = strlen(replace_string);
    widget_info->text->ptr = replace_string;
  }
}

Text and TextField differ from most other Motif widgets in that calling some convenience routines and setting some resources causes the widget to invoke callback procedures. In general

If the application needs to distinguish between callbacks invoked as a result of user action and callbacks invoked as a result of application action (such as setting a resource or calling a convenience routine), it needs to set a flag before taking the application action and clear the flag afterward.

In addition to the resources discussed in the previous section, Text has many others, including the following:

In addition, Text and TextField have several resources that determine the geometry of the widget:

XmNresizeWidth is initialized to False when XmNscrollHorizontal is True or XmNwordWrap is True. XmNresizeHeight is initialized to False when XmNscrollVertical is True.

If the user or application initializes or sets a specific height (XmNheight) or width (XmNwidth), that value is used as the corresponding dimension of the widget. In addition, if a height is specified, XmNrows is recalculated based on that height, and if a width is specified, XmNcolumns is recalculated based on that width.

If the user or application initializes or sets XmNrows but not XmNheight, the geometry calculation depends on the value of XmNresizeHeight. If XmNresizeHeight is True, the height of the widget is the greater of the height needed to display XmNrows of text and the height needed to display all the text. If XmNresizeHeight is False, as it is by default, the height of the widget is the height needed to display all the text. The same relations hold for XmNcolumns, XmNwidth, and XmNresizeWidth.

If the user or application does not initialize either XmNrows or XmNheight, the geometry calculation depends on the value of XmNresizeHeight. If XmNresizeHeight is True, the height of the widget is the height needed to display all the text. If XmNresizeHeight is False, the height of the widget is the height needed to display the default for XmNrows, which is one row of text. The same relations hold for XmNcolumns, XmNwidth, and XmNresizeWidth, except that the default number of columns is 20.

If the contents of the text (XmNvalue or XmNvalueWcs) change, as a result of user editing or an action by the application, the geometry calculation depends on the value of XmNresizeHeight. If XmNresizeHeight is True, the height of the widget is the height needed to display all the text. If XmNresizeHeight is False, the height of the widget does not change. The same relations hold for XmNvalue, XmNvalueWcs, XmNresizeWidth, and the width of the widget.

If the application sets another resource that affects the height needed by the widget, such as XmNmarginHeight or XmNfontList, the geometry calculation depends on the value of XmNresizeHeight. If XmNresizeHeight is True, the height of the widget is the height needed to display all the text with the new resource values. If XmNresizeHeight is False, the height of the widget is the height needed to display XmNrows of text using the new resources. The same relations hold for these resources, XmNresizeWidth, XmNcolumns, and the width of the widget.

Text has convenience routines to permit the application to perform many functions, including these:

ScrolledText is a Text widget inside a ScrolledWindow. The application can use XmCreateScrolledText to create one. This routine creates both Text and ScrolledWindow widgets and forces the following initial values for ScrolledWindow resources:

A common requirement of many text editors is the ability to read text from a file, allow the user to edit the text, and then store the text in a file. An application usually obtains pathnames from the user by means of a FileSelectionBox, often invoked as a dialog from a MenuBar File Menu. Following are very simple routines that use ANSI C input/output facilities to read text from a file into a Text widget and save text from a Text widget into a file:

void ReadTextFromFile(Widget w, char *filename)
{
  FILE           *file;
  char            buffer[MAXSIZE];
  char           *ptr, *end;
  XmTextPosition  last_pos;
  if (file = fopen(filename, "r")) {
    XmTextSetString(w, "");
    ptr = buffer;
    end = buffer + MAXSIZE - 1;
    while((val = getc(file)) != EOF) {
      if (ptr < end) {
        *ptr++ = (char) val;
      } else {
        *ptr = '\0';
        last_pos = XmTextGetLastPosition(w);
        XmTextReplace(w, last_pos, last_pos, buffer);
        ptr = buffer;
      }
    }
    if (ptr > buffer) {
      *ptr = '\0';
      last_pos = XmTextGetLastPosition(w);
      XmTextReplace(w, last_pos, last_pos, buffer);
    }
    (void) fclose(file);
  }
}
void SaveTextToFile(Widget w, char *filename)
{
  FILE     *file;
  char     *text;
  if (file = fopen(filename, "w")) {
    text = XmTextGetString(w);
    (void) fputs(text, file);
    (void) fclose(file);
    XtFree(text);
  }
}

Each Text widget has a data structure of type XmTextSource that functions as the source and sink of text for the widget. The source is the value of the XmNsource resource.

Two or more Text widgets can share the same source. In this case, editing of Text in one widget changes the text of the source and therefore the text of all widgets that share that source. For example, an application might use a PanedWindow with multiple text widgets, each functioning as a "window" onto a single text source. Editing changes in one pane are reflected in all Text panes that share the same source.

An application creates a Text source by creating a Text widget. The program uses XmTextGetSource or XtGetValues for the XmNsource resource to obtain that widget's source. The application then creates another Text widget, supplying the source obtained from the first widget using XmTextSetSource, the initialization argument list, or XtSetValues of the XmNsource resource.

Setting a Text source destroys the existing source of the widget if no other widgets are sharing that source. To replace a Text source but keep it for later use, the application can create an unmanaged Text widget and set its source to the Text source the program wants to keep.

If the application does not supply a source, Text creates a default string source.