NAME

XmText — the Text widget class.

SYNOPSIS

#include <Xm/Text.h>

DESCRIPTION

Text provides a single and multiline text editor for customizing both user and programmatic interfaces.  It can be used for single-line string entry, forms entry with verification procedures, and full-window editing.  It provides an application with a consistent editing system for textual data.  The screen’s textual data adjusts to the application writer’s needs. 

Text provides separate callback lists to verify movement of the insert cursor, modification of the text, and changes in input focus.  Each of these callbacks provides the verification function with the widget instance, the event that caused the callback, and a data structure specific to the verification type.  From this information the function can verify if the application considers this to be a legitimate state change and can signal the widget whether to continue with the action. 

The user interface tailors a new set of translations.  The default translations provide key bindings for insert cursor movement, deletion, insertion, and selection of text. 

Text allows the user to select regions of text.  Selection is based on the Interclient Communication Conventions (lCCC) selection model.  Text supports primary selection. 

Primitive’s resource XmNtraversalOn is always True in Text. 

Classes

Text inherits behavior and resources from Core and Primitive classes. 

The class pointer is xmTextWidgetClass. 

The class name is XmText. 

New Resources

The following table defines a set of widget resources used by the programmer to specify data.  The programmer can also set the resource values for the inherited classes to set attributes for this widget.  To reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC prefix and use the remaining letters.  To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters (in either lower case or upper case, but include any underscores between words).  The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 

XmNactivateCallback
Specifies the list of callbacks that is called when the user invokes an event that calls the Activate() function.  The structure returned by this callback is XmAnyCallbackStruct.  The reason sent by the callback is XmCR_ACTIVATE. 

XmNautoShowCursorPosition
Ensures that the visible text contains the insert cursor when set to True. If the insert cursor changes, the contents of Text may scroll in order to bring the insertion point into the window.

XmNcursorPosition
Indicates the position in the text where the current insert cursor is to be located.  Position is determined by the number of characters from the beginning of the text.

XmNeditable
Indicates that the user can edit the text string when set to True. A false value will prohibit the user from editing the text.

XmNeditMode
Specifies the set of keyboard bindings used in Text. The default keyboard bindings (XmSINGLE_LINE_EDIT) provides the set of key bindings to be used in editing single-line text.  The multiline bindings (XmMULTI_LINE_EDIT) provides the set of key bindings to be used in editing multiline text. 

XmNfocusCallback
Specifies the list of callbacks that is called before Text has accepted input focus.  The structure returned by this callback is XmAnyCallbackStruct.  The reason sent by the callback is XmCR_FOCUS. 

XmNlosingFocusCallback
Specifies the list of callbacks that is called before Text loses input focus. The structure returned by this callback is XmTextVerifyCallbackStruct.  The reason sent by the callback is XmCR_LOSING_FOCUS. 

XmNmarginHeight
Specifies the distance between the top edge of the widget window and the text, and the bottom edge of the widget window and the text. This resource is forced to True when the Text widget is placed in a ScrolledWindow with XmNscrollingPolicy set to XmAUTOMATIC. 

XmNmarginWidth
Specifies the distance between the left edge of the widget window and the text, and the right edge of the widget window and the text. This resource is forced to True when the Text widget is placed in a ScrolledWindow with XmNscrollingPolicy set to XmAUTOMATIC. 

XmNmaxLength
Specifies the maximum length of the text string that can be entered into text from the keyboard. Strings that are entered using the XmNvalue resource or the XmTextSetString function ignore this resource. 

XmNmodifyVerifyCallback
Specifies the list of callbacks that is called before text is deleted from or inserted into Text. The structure returned by this callback is XmTextVerifyCallbackStruct.  The reason sent by the callback is XmCR_MODIFYING_TEXT_VALUE. 

XmNmotionVerifyCallback
Specifies the list of callbacks that is called before the insert cursor is moved to a new position. The structure returned by this callback is XmTextVerifyCallbackStruct.  The reason sent  by the callback is XmCR_MOVING_INSERT_CURSOR. 

XmNtopPosition
Displays the position of text at the top of the window. Position is determined by the number of characters from the beginning of the text.

XmNvalue
Displays the string value.  XtGetValues returns the value of the internal buffer and XtSetValues copies the string values into the internal buffer. 

XmNvalueChangedCallback
Specifies the list of callbacks that is called after text is deleted from or inserted into Text. The structure returned by this callback is XmAnyCallbackStruct.  The reason sent by the callback is XmCR_VALUE_CHANGED. 

XmNpendingDelete
Indicates that pending delete mode is on when the Boolean is True. Pending deletion is defined as deletion of the selected text when an insertion is made.

XmNselectionArray
Defines the actions for multiple-mouse clicks.  Each mouse click performed within a half of a second of the previous mouse click will increment the index into this array and perform the defined action for that index. The possible actions are:

•XmSELECT_POSITIONS — resets the insert cursor position. 

•XmSELECT_WORD — selects a word. 

•XmSELECT_LINE — selects a line of text. 

•XmSELECT_ALL — selects all of the text. 

XmNselectThreshold
Specifies the number of pixels of motion that is required to select the next character when selection is performed using the click-drag mode of selection.

XmNblinkRate
Specifies the blink rate of the text cursor in milliseconds. The time indicated in the blink rate relates to the length of time the cursor is visible and the time the cursor is invisible (i.e., the time it will take to blink the insertion cursor on and off will be 2 times the blink rate).  The cursor will not blink when the blink rate is set to zero.

XmNcolumns
Specifies the initial width of the text window measured in character spaces.

XmNfontList
Specifies the font list to be used for Text.  See XmFontListCreate(3Xm) to create a font list. 

XmNinsertionPointVisible
Indicates that the insert cursor position is marked by a blinking text cursor when the Boolean is True.

XmNresizeHeight
Indicates that Text will attempt to resize its height to accommodate all the text contained in the widget when Boolean is True.  If set to True, the text will always be displayed starting from the first position in the source, even if instructed otherwise.  This attribute is ignored when using a ScrolledText widget and when XmNscrollVertical is True. 

XmNresizeWidth
Indicates that Text will attempt to resize its width to accommodate all the text contained in the widget when Boolean is True. This attribute is ignored if XmNwordWrap is True. 

XmNrows
Specifies the initial height of the text window measured in character heights. This attribute is ignored if the text widget resource XmNeditMode is XmSINGLE_LINE_EDIT. 

XmNwordWrap
Indicates that lines are to be broken at word breaks (i.e., the text does not go off the right edge of the window) when Boolean is True. Words are defined as a sequence of characters separated by white space.  White space is defined as a space, tab, or newline.  This attribute is ignored if the text widget resource XmNeditMode is XmSINGLE_LINE_EDIT. 

The following resources are only used when text is created in a ScrolledWindow.  See the man page for XmCreateScrolledText. 

XmNscrollHorizontal
Adds a ScrollBar that allows the user to scroll horizontally through text when Boolean is True. This attribute is ignored if the Text resource XmNeditMode is XmSINGLE_LINE_EDIT.  This resource is forced to False when the Text widget is placed in a ScrolledWindow with XmNscrollingPolicy set to XmAUTOMATIC. 

XmNscrollLeftSide
Indicates that the vertical ScrollBar should be placed on the left side of the scrolled text window when Boolean is True.  This attribute is ignored if XmNscrollVertical is False or the Text resource XmNeditMode is XmSINGLE_LINE_EDIT. 

XmNscrollTopSide
Indicates that the horizontal ScrollBar should be placed on the top side of the scrolled text window when Boolean is True.

XmNscrollVertical
Adds a ScrollBar that allows the user to scroll vertically through text when Boolean is True. This resource is forced to False when the Text widget is placed in a ScrolledWindow with XmNscrollingPolicy set to XmAUTOMATIC. 

Inherited Resources

Text inherits behavior and resources from the following superclasses.  For a complete description of these resources, refer to the man page for that superclass. 

Callback Information

The following structure is returned with each callback. 

typedef struct
{
intreason;
XEvent∗ event;
} XmAnyCallbackStruct;

reasonIndicates why the callback was invoked. 

eventPoints to the XEvent that triggered the callback. 

The Text widget defines a new callback structure for use with verification callbacks.  Note that not all of the fields are relevant for every callback reason.  The application must first look at the reason field and use only the structure members that are valid for the particular reason.  The following structure is returned with XmNlosingFocusCallbacks, XmNmodifyVerifyCallbacks, and XmNmotionVerifyCallbacks. 

typedef struct
{
intreason;
XEvent∗ event;
Booleandoit;
XmTextPosition  currInsert, newInsert;
XmTextPosition  startPos, endPos;
XmTextBlock text;
} XmTextVerifyCallbackStruct, ∗XmTextVerifyPtr;

reasonIndicates why the callback was invoked. 

eventPoints to the XEvent that triggered the callback. 

doitIndicates whether that action that invoked the callback will be performed.  Setting doit to False negates the action. 

currInsertIndicates the current position of the insert cursor. 

newInsertIndicates the position at which the user attempts to position the insert cursor. 

startPosIndicates the starting position of the text to modify.  If the callback is not a modify verification callback, this value is the same as currInsert. 

endPosIndicates the ending position of the text to modify.  If no text is replaced or deleted, then the value is the same as startPos.  If the callback is not a modify verification callback, this value is the same as currInsert. 

textPoints to a structure of type XmTextBlockRec.  This structure holds the textual information to be inserted. 

typedef struct
{
char∗ ptr;
intlength;
XmTextFormat format;
} XmTextBlockRec, ∗XmTextBlock;

ptrPoints to the text to be inserted. 

lengthSpecifies the length of the text to be inserted. 

formatSpecifies the format of the text (e.g., FMT8BIT). 

The following table describes the reasons for which the individual verification callback structure fields are valid:

Behavior

The behavior for the Text widget is determined by the XmNeditMode resource.  Depending on how this resource is set, some of the key bindings will perform different actions.  The possible values for XmNeditMode are XmSINGLE_LINE_EDIT and XmMULTI_LINE_EDIT.  The following describes the key bindings for these edit modes. 

Default Behavior (Single-line Text Edit)

<Btn1Down>:
This key binding performs the action defined in the selection array depending on the number of multiple mouse clicks. The default selection array ordering is one click to move the insertion cursor position, two clicks to select a word, and three clicks to select a line of text.

It also begins text selection.  Primary selected text that was previously selected becomes unselected. 

Button1 <PtrMoved>:
Text is selected in the direction of the pointer cursor movement.  While the pointer cursor is moved along the text, the text is selected from the point the mouse button 1 was pressed to the present position of the pointer cursor.  Moving the pointer cursor back over previously selected text while mouse button 1 is pressed deselects the text. Primary selected text is shown visibly by inverted text.

<Btn1Up>:
The selected text becomes the primary selection (i.e., the selection is committed).

Shift <Btn1Down>:
The end points of the selection move to the point where the pointer cursor is located when the shifted mouse button 1 is pressed.  If the pointer cursor is located at a position where text is already selected, the text following this position becomes unselected.

<Btn2Up>:
The text is copied from the primary selection to the insertion point located at the insert cursor. This is shown visibly by underlined text.

CTRL <Btn2Up>:
The text is copied and cut from the primary selection and is pasted to the insertion point located at the insert cursor.

<Key> Right:
The insert cursor moves one character to the right.

Shift <Key> Right:
The text character to the right of the insert cursor is selected and inverted (i.e., primary selection).  If there is already selected text to the right of the insert cursor, this text becomes unselected one character at a time.

CTRL <Key> Right:
The insert cursor moves to the end of the line.

<Key> Left:
The insert cursor moves one character to the left.

Shift <Key> Left:
The text character to the left of the insert cursor is selected and inverted. If there is already selected text to the left of the insert cursor, this text becomes unselected one character at a time.

CTRL <Key> Left:
The insert cursor moves to the beginning of the line.

<Key> Backspace:
The character of text immediately preceding the insert cursor is deleted.

<Key> Delete or <Key>DeleteChar (HP keyboard):
The character of text immediately following the insert cursor is deleted.

Any <Key>:
This key binding inserts the character, associated with the key pressed, into the text of the Text widget.

<Key> Return:
Calls the callbacks for XmNactivateCallback. 

Multiline Text Edit

Button1 <PtrMoved>:
Text is selected in the direction of the pointer cursor movement.  While the pointer cursor is moved along the text, the text is selected from the point that mouse button 1 was pressed to the present position of the pointer cursor.  Moving the cursor over several lines selects text to the end of each line passed over and up to the position of the pointer cursor on the current line.  Moving the pointer cursor back over previously selected text while mouse button 1 is pressed deselects the text.

<Key> Up:
The insert cursor moves to the line directly above the current line where the insert cursor is residing.

<Key> Down:
The insert cursor moves to the line directly below the current line where the insert cursor is residing.

<Key> Return:
Inserts a new line at the point where the insert cursor is positioned.

Default Translations

Default translations for Text are:

Shift<Key>Tab:prev-tab-group()
<Key>Tab:next-tab-group()
<Key>Up:traverse-prev()
<Key>Down:traverse-next()
<Key>Home:traverse-home()
Ctrl<Key>Right:forward-word()
Shift<Key>Right: key-select(right)
<Key>Right:forward-character()
Ctrl<Key>Left:backward-word()
Shift<Key>Left:key-select(left)
<Key>Left:backward-character()
Shift<Key>BackSpace: delete-previous-word()
<Key>BackSpace: delete-previous-character()
<Key>Return:activate()
<Key>:self-insert()
Shift<Btn1Down>: extend-start()
<Btn1Down>:grab-focus()
Button1<PtrMoved>: extend-adjust()
<Btn1Up>:extend-end()
Ctrl<Btn3Up>:move-to()
<Btn3Up>:copy-to()
<LeaveWindow>: leave()
<FocusIn>:focusIn()
<FocusOut>:focusOut()
<Unmap>:unmap()

If using an HP keyboard, the following are the default translations:

Shift<Key>DeleteChar: delete-next-word()
<Key>DeleteChar: delete-next-character()

If using a DIGITAL keyboard, the following are the default translations:

Shift<Key>Delete: delete-previous-word()
<Key>Delete:delete-previous-character()
Shift<Key>Linefeed: delete-next-word()
<Key>Linefeed:delete-next-character()
Shift<Key>F13:delete-next-word()
<Key>F13:delete-next-character()

If using other than an HP or DIGITAL keyboard, the following are the default translations:

Shift<Key>Delete: delete-next-word()
<Key>Delete:delete-next-character()

The following default translations override the above default translations when using Multiline Text Edit:

<Key>Tab:self-insert()
<Key>Up:previous-line()
<Key>Down:next-line()
<Key>Home:beginning-of-file()
<Key>Return:newline()

When changing from Multiline Text Edit to Single-line Text Edit, the following default translations override the Multiline Text Edit default translations.

<Key>Tab:next-tab-group()
<Key>Up:traverse-prev()
<Key>Down:traverse-next()
<Key>Home:traverse-home()
<Key>Return:activate()

Keyboard Traversal

Multiline Text Edit differs from standard traversal in the following manner:

Up or Down Arrow — moves the insert cursor between lines. 

Tab — inserts a tab. 

Home — moves the insert cursor to the first position (top) of the file. 

Return — adds a new line.  Both Single-line and Multiline Text Edit differs from standard traversal in the following manner:

Right or Left Arrows — moves the insert cursor to the right or to the left. 

For more information on keyboard traversal, see the man page for XmPrimitive(3Xm) and its sections on behavior and default translations. 

RELATED INFORMATION

Core(3Xm), XmCreateScrolledText(3Xm), XmCreateText(3Xm), XmFontListCreate(3Xm), XmPrimitive(3Xm), XmTextClearSelection(3Xm), XmTextGetEditable(3Xm), XmTextGetMaxLength(3Xm), XmTextGetSelection(3Xm), XmTextGetString(3Xm), XmTextReplace(3Xm), XmTextSetEditable(3Xm), XmTextSetMaxLength(3Xm), XmTextSetSelection(3Xm), and XmTextSetString(3Xm). 

7th Edition