XmText(3Xm)

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).

XmText Resource Set
Name | Class | Type | Default | Access
XmNactivateCallback | XmCCallback | XtCallbackList | NULL | C
XmNautoShowCursorPosition | XmCAutoShowCursorPosition | Boolean | True | CSG
XmNcursorPosition | XmCCursorPosition | XmTextPosition | 0 | CSG
XmNeditable | XmCEditable | Boolean | True | CSG
XmNeditMode | XmCEditMode | int | XmSINGLE_LINE_EDIT | CSG
XmNfocusCallback | XmCCallback | XtCallbackList | NULL | C
XmNlosingFocusCallback | XmCCallback | XtCallbackList | NULL | C
XmNmarginHeight | XmCMarginHeight | short | 3 | CSG
XmNmarginWidth | XmCMarginWidth | short | 3 | CSG
XmNmaxLength | XmCMaxLength | int | MAXINT | CSG
XmNmodifyVerifyCallback | XmCCallback | XtCallbackList | NULL | C
XmNmotionVerifyCallback | XmCCallback | XtCallbackList | NULL | C
XmNtopPosition | XmCTextPosition | XmTextPosition | 0 | CSG
XmNvalue | XmCValue | String | "" | CSG
XmNvalueChangedCallback | XmCCallback | XtCallbackList | NULL | C

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.

    XmText Input Resource Set
    Name | Class | Type | Default | Access
    XmNpendingDelete | XmCPendingDelete | Boolean | True | CSG
    XmNselectionArray | XmCSelectionArray | Pointer | sarray | CSG
    XmNselectThreshold | XmCSelectThreshold | int | 5 | CSG

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.

    XmText Output Resource Set
    Name | Class | Type | Default | Access
    XmNblinkRate | XmCBlinkRate | int | 500 | CSG
    XmNcolumns | XmCColumns | short | 20 | CSG
    XmNcursorPositionVisible | XmCCursorPositionVisible | Boolean | True | CSG
    XmNfontList | XmCFontList | XmFontList | fixed | CSG
    XmNresizeHeight | XmCResizeHeight | Boolean | False | CSG
    XmNresizeWidth | XmCResizeWidth | Boolean | False | CSG
    XmNrows | XmCRows | short | 1 | CSG
    XmNwordWrap | XmCWordWrap | Boolean | False | CSG

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.

    XmText ScrolledText Resource Set
    Name | Class | Type | Default | Access
    XmNscrollHorizontal | XmCScroll | Boolean | True | CG
    XmNscrollLeftSide | XmCScrollSide | Boolean | False | CG
    XmNscrollTopSide | XmCScrollSide | Boolean | False | CG
    XmNscrollVertical | XmCScroll | Boolean | True | CG

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.

XmPrimitive Resource Set
Name | Class | Type | Default | Access
XmNbottomShadowColor | XmCForeground | Pixel | dynamic | CSG
XmNbottomShadowPixmap | XmCBottomShadowPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG
XmNforeground | XmCForeground | Pixel | dynamic | CSG
XmNhelpCallback | XmCCallback | XtCallbackList | NULL | CSG
XmNhighlightColor | XmCForeground | Pixel | Black | CSG
XmNhighlightOnEnter | XmCHighlightOnEnter | Boolean | False | CSG
XmNhighlightPixmap | XmCHighlightPixmap | Pixmap | dynamic | CSG
XmNhighlightThickness | XmCHighlightThickness | short | 0 | CSG
XmNshadowThickness | XmCShadowThickness | short | 2 | CSG
XmNtopShadowColor | XmCBackground | Pixel | dynamic | CSG
XmNtopShadowPixmap | XmCTopShadowPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG
XmNtraversalOn | XmCTraversalOn | Boolean | True | N/A
XmNunitType | XmCUnitType | unsigned char | XmPIXELS | CSG
XmNuserData | XmCUserData | caddr_t | NULL | CSG

Core Resource Set
Name | Class | Type | Default | Access
XmNaccelerators | XmCAccelerators | XtTranslations | NULL | CSG
XmNancestorSensitive | XmCSensitive | Boolean | True | G
XmNbackground | XmCBackground | Pixel | dynamic | CSG
XmNbackgroundPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG
XmNborderColor | XmCBorderColor | Pixel | Black | CSG
XmNborderPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG
XmNborderWidth | XmCBorderWidth | Dimension | 0 | CSG
XmNcolormap | XmCColormap | Colormap | XtCopyFromParent | CG
XmNdepth | XmCDepth | int | XtCopyFromParent | CG
XmNdestroyCallback | XmCCallback | XtCallbackList | NULL | C
XmNheight | XmCHeight | Dimension | 0 | CSG
XmNmappedWhenManaged | XmCMappedWhenManaged | Boolean | True | CSG
XmNscreen | XmCScreen | Pointer | XtCopyScreen | CG
XmNsensitive | XmCSensitive | Boolean | True | CSG
XmNtranslations | XmCTranslations | XtTranslations | NULL | CSG
XmNwidth | XmCWidth | Dimension | 0 | CSG
XmNx | XmCPosition | Position | 0 | CSG
XmNy | XmCPosition | Position | 0 | CSG

  Callback Information
The following structure is returned with each callback.

typedef struct
{
	int	reason;
	XEvent	* event;
} XmAnyCallbackStruct;

reason
    Indicates why the callback was invoked.

event
    Points 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
    {
    	int	reason;
    	XEvent	* event;
    	Boolean	doit;
    	XmTextPosition 	currInsert, newInsert;
    	XmTextPosition 	startPos, endPos;
    	XmTextBlock 	text;
    } XmTextVerifyCallbackStruct, *XmTextVerifyPtr;

reason
    Indicates why the callback was invoked.

event
    Points to the XEvent that triggered the callback.

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

currInsert
    Indicates the current position of the insert cursor.

newInsert
    Indicates the position at which the user attempts to position the insert cursor.

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

endPos
    Indicates 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.

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

    typedef struct
    {
    	char	* ptr;
    	int	length;
    	XmTextFormat	format;
    } XmTextBlockRec, *XmTextBlock;

ptr Points to the text to be inserted.

length
    Specifies the length of the text to be inserted.

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

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

    Reason | Valid Fields
    XmCR_LOSING_FOCUS | reason, event, doit, currInsert, newInsert, startPos, endPos
    XmCR_MODIFYING_TEXT_VALUE | reason, event, doit, currInsert, newInsert, startPos, endPos, text
    XmCR_MOVING_TEXT_CURSOR | reason, event, doit, currInsert, newInsert

  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).