xmText, xmScrolledText, and xmTextField

The xmScrolledText widget automatically displays scroll bars if it is larger than the allotted space on screen. These xmScrollBars enable the user to change the currently viewed portion of the text. Text selection is done with keyboard or mouse interactions, as described in the section "Actions and Translations".

A scrolled text widget is a composite widget that has the following children, where tw represents the text widget name:

tw.HorScrollBar    tw.VertScrollBar    tw.ClipWindow

xmScrolledText .txt managed
set rsrc_list [.txt.ClipWindow resources] 

tw setString txt

Change the current text to txt.

tw getString

Return the whole text as a result.

tw getSubString start len var

Get the substring starting at position start for len characters, and assign it to the Tcl variable var. If len is too large, only the first part of the text is set to var. This method returns either succeeded, truncated, or failed.

tw insert position string

Insert string in the text, starting at location position. Use zero to insert at the beginning of the text.

tw replace start stop string

Replace the portion of text between start and stop with the new string.

tw setSelection start stop

Set the current selection to the substring between start and stop.

tw getSelection

Return the primary text selection; if no text is selected, return nothing.

tw getSelectionPosition start stop

If something is selected, set the Tcl variables start and stop accordingly and return true, otherwise return false.

tw clearSelection

Deselect the current selection.

tw remove

Remove the currently selected part of text.

tw copy

Copy the current selection onto the clipboard.

tw cut

Copy the current selection onto the clipboard and remove from the text.

tw paste

Replace the current selection by the clipboard contents.

tw setAddMode bool

Set whether or not the text is in append (insert) mode. When in this mode, text insertion does not modify the current selection.

tw setHighlight start stop mode

Change the highlight appearance of text between start and stop, but not the selection; mode can be normal, selected, or secondary_selected.

tw findString start stop string dir pos

Search text for a string between the position start and stop. Direction dir may be either forward or backward. If the string is found, the position of its first occurrence is set to pos, and the method returns true, otherwise it returns false.

tw getInsertPosition

Return the position of the insert cursor, starting from zero.

tw setInsertPosition position

Set the cursor insertion point.

tw getLastPosition

Return the position of the last character in the text buffer, in other words, the length of the text.

tw scroll num

Scroll the text widget by num lines. A positive value means to scroll forward, while a negative value means to scroll backward.

tw showPosition position

Scroll the text so that position becomes visible.

tw getTopCharacter

Return the position of the first visible character of text in the widget.

tw setTopCharacter position

Scroll the text so that position is the first visible character in the widget.

tw disableRedisplay

The text is not redisplayed.

tw enableRedisplay

Redisplay the text automatically when it changes.

tw getEditable

Return true if the text is editable (the user can edit it), or false if not.

tw setEditable bool

Set the edit permission flag of the text widget.

tw setSource ref top ins

Set the text edited or displayed by this widget to the one that is also edited or displayed by the text widget variable ref. The text is scrolled so that the top character is first, with the insertion cursor positioned at ins.

xmText Resources

Resource Name	Default Value	Type or Legal Value
-autoShowCursorPosition	True	Boolean
-cursorPosition	0	Integer
-editable	True	Boolean
-editMode	single_line_edit	multiple_line_edi single_line_edit
-marginHeight	5	Integer
-marginWidth	5	Integer
-maxLength	maxint	Integer
-source	new source	Text Source
-topCharacter	0	Integer
-value	""	String
-verifyBell	True	Boolean

xmTextInput and xmTextOutput Resources

Resource Name	Default Value	Type or Legal Value
-pendingDelete	True	Boolean
-selectionArray	not supported
-selectionArrayCount	not supported
-selectThreshold	5	Integer
-blinkRate	500ms	Integer
-columns	computed from -width	Integer
-cursorPositionVisible	True	Boolean
-fontList	Inherited	Font list
-resizeHeight	False	Boolean
-resizeWidth	False	Boolean
-rows	computed from -height	Integer
-wordWrap	False	Boolean

The xmText widget inherits resources from two abstract classes, xmTextInput and xmTextOutput. The xmTextField widget uses the resource subset that corresponds to single-line text (it does not have an -editMode resource). The text source resource might be used to open multiple windows for editing a single text, as in the example below.

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmPanedWindow .top managed
xmScrolledText .top.a managed -editMode multi_line_edit \
    -rows 3 -columns 49 -value {
When ten low words oft in one dull line creep,
The reader's threatened, not in vain, with sleep.
                      --Alexander Pope}
xmScrolledText .top.b managed -editMode multi_line_edit \
    -rows 3 -columns 49
.top.b setSource .top.a 0 0
. realizeWidget
. mainLoop

Text Widget Inherited Resources

Resource Inherited	From		Resource Inherited	From
-accelerators	(Core)		-alignment	(Label)
-backgroundPixmap	(Core)		-background	(Core)
-borderColor	(Core)		-borderWidth	(Core)
-bottomShadowColor	(Primitive)		-bottomShadowPixmap	(Primitive)
-fontList	(Label)		-foreground	(Primitive)
-height	(Core)		-highlightColor	(Primitive)
-highlightOnEnter	(Primitive)		-highlightPixmap	(Primitive)
-highlightThickness	(Primitive)		-labelPixmap	(Label)
-labelString	(Label)		-labelType	(Label)
-mappedWhenManaged	(Core)		-marginBottom	(Label)
-marginLeft	(Label)		-marginRight	(Label)
-marginTop	(Label)		-navigationType	(Primitive)
-recomputeSize	(Label)		-sensitive	(Core)
-shadowThickness	(Primitive)		-stringDirection	(Label)
-topShadowColor	(Primitive)		-topShadowPixmap	(Primitive)
-translations	(Core)		-traversalOn	(Primitive)
-unitType	(Primitive)		-width	(Core)
-x	(Core)		-y	(Core)