NAME

Text widget − text-editing widget. 

SYNOPSIS

Public Headers:<X11/StringDefs.h> <X11/Xaw/AsciiText.h> <X11/Xaw/Text.h> <X11/Xaw/TextSrc.h> <X11/Xaw/TextSink.h> <X11/Xaw/AsciiSrc.h> <X11/Xaw/AsciiSink.h>

Private Header:<X11/Xaw/TextP.h> <X11/Xaw/TextSrcP.h> <X11/Xaw/TextSinkP.h> <X11/Xaw/AsciiTextP.h> <X11/Xaw/AsciiSrcP.h> <X11/Xaw/AsciiSinkP.h>

Class Name:AsciiText

Class Pointer:asciiTextWidgetClass

Instantiation:widget = XtCreateWidget(name, asciiTextShellWidgetClass, ...) 

CLASS HIERARCHY

Core → Simple → Text → AsciiText

DESCRIPTION

A Text widget is a window that provides a way for an application to display one or more lines of text.  The displayed text can reside in a file on disk or in a string in memory.  An option also lets an application display a vertical Scrollbar in the Text window, letting the user scroll through the displayed text.  Other options allow an application to let the user modify the text in the window or search for a specific string. 

The Text widget is divided into three parts:

•Source object

•Sink object

•Text widget

The idea is to separate the storage of the text (source) from the painting of the text (sink).  The Text widget proper coordinates the sources and sinks.  The AsciiText widget is a subclass of the Text widget that automatically creates the source and sink for the client.  By default, the AsciiText widget uses a string in memory as the source; setting the asciiSrc.type resource to XawAsciiFile specifies use of a disk file.  The AsciiText’s sink is a single-font, single-color ASCII sink.  A client can, if it so chooses, explicitly create the source and sink before creating the Text widget. 

The source stores and manipulates the text, and determines what editing functions may be performed on the text. 

The sink obtains the fonts and the colors in which to paint the text.  The sink also computes what text can fit on each line. 

If a string in memory is used as the source, the application must allocate the amount of space needed.  If a disk source is used, the file will not be updated until a call to XawAsciiSave() is made.  When a disk source is being used, the useStringInPlace resource is ignored.  Three types of edit mode are available:

•Append-only

•Read-only

•Editable

Append-only mode lets the user enter text into the window, while read-only mode does not.  Text may be entered only if the insertion point is after the last character in the window.  Editable mode lets the user place the cursor anywhere in the text and modify the text at that position.  The text cursor position can be modified by using the keystrokes or pointer buttons defined by the event bindings.  (See Translations and Actions below.) 

RESOURCES

When creating a Text widget instance, the following resources are retrieved from the argument list or from the resource database:

Name (XtN...)	Type	Default	Description
XtNaccelerators	Accelerator-   Table	NULL	List of event-to-action bindings to be executed by this widget, even though the event occurred in another widget.
XtNancestor−   Sensitive	Boolean	True	(D) Sensitivity state of the ancestors of this widget: a widget is insensitive if either it or any of its ancestors is insensitive.
XtNautoFill	Boolean	False	Specifies whether the Text widget will automatically break a line when the user attempts to type into the right margin.
XtNbackground	Pixel	XtDefault−   Background	Window background color.
XtNbackground−   Pixmap	Pixmap	None	Window background pixmap.
XtNborderColor	Pixel	XtDefault−   Foreground	Window border color.
XtNborderPixmap	Pixmap	None	Window border pixmap.
XtNborderWidth	Dimension	4	Border width in pixels.
XtNbottomMargin	Position	2	Amount of space, in pixels,  between the edge of the window and the edge of the text within the window.
AsciiText.XtNcall-   back	XtCallback-   List	NULL	List of callbacks called every time the text buffer changes.
XtNcolormap	Colormap	Parent’s colormap.	Colormap that this widget will use.
XtNcursor	Cursor	XC_xterm	Pointer cursor.
XtNdataCompression	Boolean	True	If True, the AsciiSrc will compress its data to the minimum size required every time the text string is saved, or the value of the string is queried.
XtNdepth	int	Parent’s depth.	(C) Depth of this widget’s window.
XtNdestroyCallback	XtCallback-   List	NULL	Callbacks for XtDestroyWidget().
XtNdisplayCaret	Boolean	True	Whether to display the text caret.
AsciiText.XtNdisplay−   Nonprinting	Boolean	True	Whether to display a nonprintable character as the string ^@: if False, it will be printed as a blank.
XtNdisplayPosition	int	0	Character position of first line.
AsciiText.XtNecho	Boolean	True	Whether or not to echo characters to the screen.
AsciiText.XtNedit-   Type	XawTextEdit-   Type∗	XawtextRead	Edit mode.†
AsciiSink.XtNfore-   ground	Pixel	Black	Foreground color.
AsciiText.XtNfont	XFontStruct∗	Fixed	Fontname.
AsciiText.XtNfore-   ground	Pixel	XtDefault-   Foreground	Pixel value which indexes the Text widget’s colormap to derive the foreground color used by the text sink.
XtNheight	Dimension	Font height.	(A) Height of widget.
XtNinsensitive-   Border	Pixmap	Gray pixmap.	Pixmap will be tiled into the widget’s border if the widget becomes insensitive.
XtNinsertPosition	int	0	Character position of caret.
XtNleftMargin	Dimension	2	Left margin in pixels.
AsciiText.XtNlength	int	String length.	(A) Size of the string buffer.
XtNmappedWhenManaged	Boolean	TRUE	Whether XtMapWidget() is automatic.
AsciiText.XtNpiece-   Size	XawText-   Position	BUFSIZ	Size of the internal chunks into which the text buffer is broken down for memory management.
XtNresize	XawTextResize-   Mode	XawtextResize-   Never	Whether the widget should attempt to resize to its preferred dimensions whenever its resources are modified with XtSetValues().

______________
†XawTextEditType (R5) was XawEditType in R4.

Name (XtN...)	Type	Default	Description
XtNrightMargin	Position	2	Amount of space, in pixels, between the edge of the window and the corresponding edge of the text within the window.
XtNscreen	Screen	Parent’s screen.	(R) Screen on which this widget is displayed.
XtNscrollHorizontal	XawTextScroll-   Mode	XawtextScroll-   Never	See XtNscrollVertical.
XtNscrollVertical	XawTextScroll-   Mode	XawtextScroll-   Never	Control the placement of scrollbars on the left and bottom edge of the text widget: these resources accept the values XawtextScrollAlways, XawtextScrollWhenNeeded, and XawtextScrollNever.
XtNselectTypes	XawTextSelect-   Type∗	See below.	Selection units for multi-click.
XtNsensitive	Boolean	TRUE	Whether widget receives input.
AsciiText.XtNstring	String	NULL	String for the text source.
XtNtextSink	Widget	None	See below.
XtNtextSource	Widget	None	See below.
XtNtopMargin	Position	2	Amount of space, in pixels, between the edge of the window and the corresponding edge of the text within the window.
XtNtranslations	Translation-   Table	See above.	Event-to-action translations.
XtNtype	AsciiType	XawAsciiString	May be either XawAsciiString or XawAsciiFile.
(R5) XtNunrealize-   Callback	XtCallback-   List	NULL	Called when unrealized.
XtNuseStringInPlace	Boolean	False	If True, will disable the memory management provided by the Text widget, updating the string resource in place.
XtNwidth	Dimension	100	Width of widget (pixels).

Name (XtN...)	Type	Default	Description
AsciiText.XtNwrap	WrapMode	XawtextWrap-   Never	Accepted values are XawtextWrapNever, XawtextWrapLine, and XawtextWrapWord: with XawtextWrapLine, all text that is beyond the right edge of the window will be displayed on the next line; with XawtextWrapWord, the same action occurs but the text is broken at a word boundary if possible.  If no wrapping is enabled, then the text will extend off the edge of the window and a small rectangle will be painted in the right margin to alert the user that this line is too long.
XtNx	Position	0	x coordinate in pixels.
XtNy	Position	0	y coordinate in pixels.

The AsciiSrc can be either of two types: XawAsciiFile or XawAsciiString. 

AsciiSrc objects of type XawAsciiFile read the text from a file and store it into an internal buffer.  This buffer may then be modified, provided the text widget is in the correct edit mode, just as if it were a source of type XawAsciiString.  Unlike R3 and earlier versions of the AsciiSrc, it is now possible to specify an editable disk source. 

AsciiSrc objects of type XawAsciiString have the text buffer implemented as a string.  The string owner is responsible for allocating and managing storage for the string.  In the default case for AsciiSrc objects of type XawAsciiString, the resource useStringInPlace is false, and the widget owns the string.  The initial value of the string resource, and any update made by the application programmer to the string resource with XtSetValues(), is copied into memory private to the widget, and managed internally by the widget.  The application writer does not need to worry about running out of buffer space (subject to the total memory available to the application).  The performance does not decay linearly as the buffer grows large, as is necessarily the case when the text buffer is used in place.   The application writer must use XtGetValues() to determine the contents of the text buffer, which will return a copy of the widget’s text buffer as it existed at the time of the XtGetValues() call.   This copy is not affected by subsequent updates to the text buffer, i.e., it is not updated as the user types input into the text buffer.  This copy is freed upon the next call to XtGetValues to retrieve the string resource; however, to conserve memory, there is a convenience routine, XawAsciiSrcFreeString, allowing the application programmer to direct the widget to free the copy. 

When the resource useStringInPlace is true and the AsciiSrc object is of type XawAsciiString, the application is the string owner.  The widget will take the value of the string resource as its own text buffer, and the length resource indicates the buffer size.   In this case the buffer contents change as the user types at the widget; it is not necessary to call XtGetValues() on the string resource to determine the contents of the buffer—it will simply return the address of the application’s implementation of the text buffer. 

Note that:

1.The XtNeditType attribute has one of the values XawtextAppend, XawtextEdit, or XawtextRead. 

2.The value of the XtNtype resource determines whether the XtNstring resource contains the name of a file to be opened or a buffer to be displayed by the Text widget.  A converter has been registered for this resource and accepts the values string and file. 

Selections

XtNselectionTypes is an array of entries of type XawTextSelectType and is used for multiclick.  As the pointer button is clicked in rapid succession, each click highlights the next "type" described in the array. 

XawselectAllSelects the contents of the entire buffer. 

XawselectChar
Selects text characters as the pointer moves over them.

XawselectLine
Selects the entire line.

XawselectNull
Indicates the end of the selection array.

XawselectParagraph
Selects the entire paragraph (delimited by newline characters).

XawselectPosition
Selects the current pointer position.

XawselectWord
Selects whole words (delimited by whitespace) as the pointer moves onto them.

The default selectType array is:

{XawselectPosition, XawselectWord, XawselectLine, XawselectParagraph, XawselectAll, XawselectNull}

For the default case, two rapid pointer clicks highlight the current word, three clicks highlight the current line, four clicks highlight the current paragraph, and five clicks highlight the entire text.  If the timeout value is exceeded, the next pointer click returns to the first entry in the selection array.  The selection array is not copied by the Text widget.  The client must allocate space for the array and cannot deallocate or change it until the Text widget is destroyed or until a new selection array is set. 

To modify the selections, a programmer must construct a XawTextSelectType array (called the selection array) containing the selections desired and pass this as the new value for the XtNselectionTypes resource.  The selection array may also be modified using the XawTextSetSelectionArray() function.  All selection arrays must end with the value XawselectNull.  The selectionTypes resource has no converter registered and cannot be modified through the resource manager. 

The array contains a list of entries that will be called when the user attempts to select text in rapid succession with the select-start action (usually by clicking a pointer button).  The first entry in the selection array will be used when the select-start action is initially called.  The next entry will be used when select-start is called again, and so on.  If a timeout value (1/10 of a second) is exceeded, the next select-start action will begin at the top of the selection array.  When XawselectNull is reached, the array is recycled beginning with the first element. 

TRANSLATIONS AND ACTIONS

Many standard keyboard editing facilities are supported by the event bindings.  The following actions are supported:

Cursor Movement Actions	Delete Actions
Forward-character	Delete-next-character
Backward-character	Delete-previous-character
Forward-word	Delete-next-word
Backward-word	Delete-previous-word
Forward-paragraph	Delete-selection
Backward-paragraph
Beginning-of-line	Selection Actions
End-of-line	Insert-selection
Next-line	Select-word
Previous-line	Select-all
Next-page	Select-start
Previous-page	Select-adjust
Beginning-of-file	Select-end
End-of-file	Extend-start
Scroll-one-line-up	Extend-adjust
Scroll-one-line-down	Extend-end
New Line Actions	Miscellaneous Actions
Newline-and-indent	Redraw-display
Newline-and-backup	Insert-file
Newline	Insert-char
	Display-caret
Kill Actions	Focus-in
Kill-word	Focus-out
Backward-kill-word	Search
Kill-selection	Multiply
Kill-to-end-of-line	Form-paragraph
Kill-paragraph	No-op
Kill-to-end-of-paragraph	Transpose-characters

•A page corresponds to the size of the Text window.  For example, if the Text window is 50 lines in length, scrolling forward one page is the same as scrolling forward 50 lines. 

•The delete action deletes a text item.  The kill action deletes a text item and puts the item in the kill buffer (X cut buffer 1). 

•The insert-selection action retrieves the value of a specified X selection or cut buffer, with fall-back to alternative selections or cut buffers. 

Cursor Movement Actions

forward-character()

backward-character()
These actions move the insertion point forward or backward one character in the buffer.  If the insertion point is at the end (or beginning) of a line, this action moves the insertion point to the next (or previous) line.

forward-word()

backward-word()
These actions move the insertion point to the next or previous word boundary. A word boundary is defined as a space, a tab, or a carriage return.

forward-paragraph()

backward-paragraph()
These actions move the insertion point to the next or previous paragraph boundary. A paragraph boundary is defined as two carriage returns in a row with only spaces or tabs between them.

beginning-of-line()

end-of-line()
These actions move to the beginning or end of the current line.  If the insertion point is already at the end or beginning of the line, no action is taken.

next-line()

previous-line()
These actions move the insertion point up or down one line.  If the insert point is currently n characters from the beginning of the line then it will be n characters from the beginning of the next or previous line.  If n is past the end of the line, the insertion point is placed at the end of the line. 

next-page()

previous-page()
These actions move the insertion point up or down one page in the file. One page is defined as the current height of the text widget. These actions always place the insertion point at the first character of the top line.

beginning-of-file()

end-of-file()
These actions place the insertion point at the beginning or end of the current text buffer.  The text widget is then scrolled the minimum amount necessary to make the new insertion point location visible.

scroll-one-line-up()

scroll-one-line-down()
These actions scroll the current text field up or down by one line. They do not move the insertion point.  Other than the scrollbars, this is the only way that the insertion point may be moved off of the visible text area.  The widget will be scrolled so that the insertion point is back on the screen as soon as some other action is executed.

Delete Actions

delete-next-character()

delete-previous-character()
These actions remove the character immediately after or before the insertion point.  If a carriage return is removed, the next line is appended to the end of the current line.

delete-next-word()

delete-previous-word()
These actions remove all characters between the insertion point location and the next word boundary.  A word boundary is defined as a space, a tab or a carriage return.

delete-selection()
This action removes all characters in the current selection. The selection can be set with the selection actions.

Selections Actions

select-word()
This action selects the word in which the insertion point is currently located. If the insertion point is between words, it will select the previous word.

select-all()
This action selects the entire text buffer.

select-start()
This action sets the insertion point to the current pointer location, where a selection then begins.  If many of these selection actions occur quickly in succession then the selection count mechanism will be invoked.

select-adjust()
This action allows a selection started with the select-start action to be modified, as described above. 

select-end(name[,name,...])
This action ends a text selection that began with the select-start action, and asserts ownership of the selection or selections specified.  A name can be a selection (e.g., PRIMARY) or a cut buffer (e.g., CUT_BUFFER0).  Note that case is important.  If no names are specified, PRIMARY is asserted. 

extend-start()
This action finds the nearest end of the current selection, and moves it to the current pointer location.

extend-adjust()
This action allows a selection started with an extend-start action to be modified. 

extend-end(name[,name,...])
This action ends a text selection that began with the extend-start action, and asserts ownership of the selection or selections specified.  A name can be a selection (e.g., PRIMARY) or a cut buffer (e.g., CUT_BUFFER0).  Note that case is important.  If no name is given, PRIMARY is asserted. 

insert-selection(name[,name,...])
This action retrieves the value of the first (left-most) named selection that exists or the cut buffer that is not empty.  This action then inserts it into the Text widget at the current insertion point location. A name can be a selection (e.g., PRIMARY) or a cut buffer (e.g., CUT_BUFFER0).  Note that case is important. 

New Line Actions

newline-and-indent()
This action inserts a newline into the text and adds spaces to that line to indent it to match the previous line.  (Note: this action still has a few bugs.)

newline-and-backup()
This action inserts a newline into the text after the insertion point. 

newline()
This action inserts a newline into the text before the insertion point. 

Kill Actions

kill-word()

backward-kill-word()
These actions act exactly like the delete-next-word and delete-previous-word actions, but they store the word that was killed into the kill buffer (CUT_BUFFER_1). 

kill-selection()
This action deletes the current selection and stores the deleted text into the kill buffer (CUT_BUFFER_1). 

kill-to-end-of-line()
This action deletes the entire line to the right of the insertion point, and stores the deleted text into the kill buffer (CUT_BUFFER_1). 

kill-paragraph()
This action deletes the current paragraph.  If the insertion point is between paragraphs, it deletes the paragraph above the insertion point, and stores the deleted text into the kill buffer (CUT_BUFFER_1). 

kill-to-end-of-paragraph()
This action deletes everything between the current insertion point and the next paragraph boundary, and puts the deleted text into the kill buffer (CUT_BUFFER_1). 

Miscellaneous Actions

redraw-display()
This action recomputes the location of all the text lines on the display, scrolls the text to center vertically the line containing the insertion point on the screen, clears the entire screen, and then redisplays it.

insert-file([filename])
This action activates the insert file popup.  The filename option specifies the default filename to put in the filename buffer of the popup.  If no filename is specified the buffer is empty at startup. 

insert-char()
This action may be attached only to a key event. It calls XLookupString() to translate the event into a (rebindable) Latin-1 character (sequence) and inserts that sequence into the text at the insertion point. 

insert-string(string[,string,...])
This action inserts each string into the text at the insertion point location.  Any string beginning with the characters "0x" and containing only valid hexadecimal digits in the remainder is interpreted as a hexadecimal constant and the corresponding single character is inserted instead. 

display-caret(state,when)
This action allows the insertion point to be turned on and off.  The state argument specifies the desired state of the insertion point.  This value may be any of the string values accepted for Boolean resources (e.g., on, True, off, False, etc.).  If no arguments are specified, the default value is True.  The when argument specifies, for EnterNotify or LeaveNotify events, whether or not the focus field in the event is to be examined.  If the second argument is not specified, or specified as something other than always, then if the action is bound to an EnterNotify or LeaveNotify event, the action will be taken only if the focus field is True.  An augmented binding that might be useful is: ∗Text.Translations: #override \
     <FocusIn>:display-caret(on) \n\
     <FocusOut>:display-caret(off)

focus-in()

focus-out()
These actions do not currently do anything.

search(direction,[string])
This action activates the search popup.  The direction must be specified as either forward or backward.  The string is optional and is used as an initial value for the "Search for:" string. 

multiply(value)
The multiply action allows the user to multiply the effects of many of the text actions.  Thus the following action sequence: multiply(10) delete-next-word() will delete 10 words.  It does not matter whether these actions take place in one event or many events.  Using the default translations the key sequence Control-u, Control-d will delete 4 characters.  Multiply actions can be chained; thus, multiply(5) multiply(5) is the same as multiply(25) If the string reset is passed to the multiply action the effects of all previous multiplies are removed and a beep is sent to the display. 

form-paragraph()
This action removes all the carriage returns from the current paragraph and reinserts them so that each line is as long as possible, while still fitting on the current screen.  Lines are broken at word boundaries if at all possible.  This action currently works only on Text widgets that use ASCII text.

transpose-characters()
This action will switch the positions of the character to the left of the insertion point and the character to the right of the insertion point.  The insertion point will then be advanced one character.

no-op([action])
The no-op action makes no change to the text widget, and is used mainly to override translations.  This action takes one optional argument.  If this argument is RingBell then a beep is sent to the display. 

Event Bindings

The default event bindings for the Text widget are: char defaultTextTranslations[] = "  Ctrl<Key>F: forward-character() \n  Ctrl<Key>B: backward-character() \n  Ctrl<Key>D: delete-next-character() \n  Ctrl<Key>A: beginning-of-line() \n  Ctrl<Key>E: end-of-line() \n  Ctrl<Key>H: delete-previous-character() \n  Ctrl<Key>J: newline-and-indent() \n  Ctrl<Key>K: kill-to-end-of-line() \n  Ctrl<Key>L: redraw-display() \n  Ctrl<Key>M: newline() \n  Ctrl<Key>N: next-line() \n  Ctrl<Key>O: newline-and-backup() \n  Ctrl<Key>P: previous-line() \n  Ctrl<Key>V: next-page() \n  Ctrl<Key>W: kill-selection() \n  Ctrl<Key>Y: unkill() \n  Ctrl<Key>Z: scroll-one-line-up() \n  Meta<Key>F: forward-word() \n  Meta<Key>B: backward-word() \n  Meta<Key>I: insert-file() \n  Meta<Key>K: kill-to-end-of-paragraph() \n  Meta<Key>V: previous-page() \n  Meta<Key>Y: stuff() \n  Meta<Key>Z: scroll-one-line-down() \n  :Meta<Key>d: delete-next-word() \n  :Meta<Key>D: kill-word() \n  :Meta<Key>h: delete-previous-word() \n  :Meta<Key>H: backward-kill-word() \n  :Meta<Key><: beginning-of-file() \n  :Meta<Key>>: end-of-file() \n  :Meta<Key>]: forward-paragraph() \n  :Meta<Key>[: backward-paragraph() \n  ~Shift Meta<Key>Delete: delete-previous-word() \n   Shift Meta<Key>Delete: backward-kill-word() \n  ~Shift Meta<Key>Backspace: delete-previous-word() \n   Shift Meta<Key>Backspace: backward-kill-word() \n  <Key>Right: forward-character() \n  <Key>Left: backward-character() \n  <Key>Down: next-line() \n  <Key>Up: previous-line() \n  <Key>Delete: delete-previous-character() \n  <Key>BackSpace: delete-previous-character() \n  <Key>Linefeed: newline-and-indent() \n  <Key>Return: newline() \n  <Key>: insert-char() \n  <FocusIn>: focus-in() \n  <FocusOut>: focus-out() \n  <Btn1Down>: select-start() \n  <Btn1Motion>: extend-adjust() \n  <Btn1Up>: extend-end(PRIMARY, CUT_BUFFER0) \n  <Btn2Down>: insert-selection(PRIMARY, CUT_BUFFER0) \n  <Btn3Down>: extend-start() \n  <Btn3Motion>: extend-adjust() \n  <Btn3Up>: extend-end(PRIMARY, CUT_BUFFER0)"; A user-supplied resource entry can use application-specific bindings, a subset of the supplied default bindings, or both. The following is an example of a user-supplied resource entry that uses a subset of the default bindings: Xmh∗Text.Translations: \  <Key>Right: forward-character() \n\  <Key>Left: backward-character() \n\   Meta<Key>F: forward-word() \n\   Meta<Key>B: backward-word() \n\  :Meta<Key>]: forward-paragraph() \n\  :Meta<Key>[: backward-paragraph() \n\  <Key>: insert-char()

An augmented binding that is useful with the xclipboard utility is: ∗Text.Translations: #override \  Button1 <Btn2Down>: extend-end(CLIPBOARD) The Text widget fully supports the X selection and cut buffer mechanisms.  The following actions can be used to specify button bindings that will cause Text to assert ownership of one or more selections, to store the selected text into a cut buffer, and to retrieve the value of a selection or cut buffer and insert it into the text value. 

insert-selection(name[,name,...])
Retrieves the value of the first (left-most) named selection that exists or the cut buffer that is not empty and inserts it into the input stream. The specified name can be that of any selection (for example, PRIMARY or SECONDARY) or a cut buffer (i.e., CUT_BUFFER0 through CUT_BUFFER7).  Note that case matters. 

select-start()
Unselects any previously selected text and begins selecting new text.

select-adjust()

extend-adjust()
Continues selecting text from the previous start position.

start-extend()
Begins extending the selection from the farthest (left or right) edge.

select-end(name[,name,...])

extend-end(name[,name,...])
Ends the text selection, asserts ownership of the specified selection(s), and stores the text in the specified cut buffer(s). The specified name can be that of a selection (for example, PRIMARY or SECONDARY) or a cut buffer (i.e., CUT_BUFFER0 through CUT_BUFFER7).  Note that case is significant.  If CUT_BUFFER0 is listed, the cut buffers are rotated before storing into buffer 0. 

XawWMProtocols([wm_protocol_name])
This action is written specifically for the transient shells instantiated by the Text widget, which are the file insertion and the search and replace dialog boxes.  This action is attached to those shells by the Text widget, in order to handle ClientMessage events with the WM_PROTOCOLS atom in the detail field.  This action supports WM_DELETE_WINDOW on the Text widget popups, and may support other window manager protocols if necessary in the future.  The popup will be dismissed if the window manager sends a WM_DELETE_WINDOW request and there are no parameters in the action call, which is the default.  The popup will also be dismissed if the parameters include the string "wm_delete_window", and the event is a ClientMessage event requesting dismissal or is not a ClientMessage event.  This action is not sensitive to the case of the strings passed as parameters. 

PUBLIC FUNCTIONS

A Text widget lets both the user and the application take control of the text being displayed.  The user takes control with the scroll bar or with key strokes defined by the event bindings.  The scroll bar option places the scroll bar on the left side of the window and can be used with any editing mode.  The application takes control with procedure calls to the Text widget to:

•Display text at a specified position. 

•Highlight specified text areas. 

•Replace specified text areas. 

The text that is selected within a Text window may be assigned to an X selection or copied into a cut buffer and can be retrieved by the application with the Intrinsics XtGetSelectionValue() or the Xlib XFetchBytes() functions, respectively.  Several standard selection schemes (e.g., character/word/paragraph with multiclick) are supported through the event bindings. 

AsciiTextWidgetClass is actually a source and a sink along with a textWidgetClass.  If you want to create an instance of the class textWidgetClass separately, you must provide a source and a sink when the widget is created.  The Text widget cannot be instantiated without both. 

•To enable an application to select a piece of text, use XawTextSetSelection(): void XawTextSetSelection(w, left, right)
     Widget w;
     XawTextPosition left, right; where:

wSpecifies the window ID. 

leftSpecifies the character position at which the selection begins. 

rightSpecifies the character position at which the selection ends. 

If redisplay is enabled, this function highlights the text and makes it the PRIMARY selection.  This function does not have any effect on CUT_BUFFER0.  XawTextPosition is defined as follows: typedef long XawTextPosition; Character positions in the Text widget begin at 0 and end at n+1, where n is the number of characters in the Text source widget. 

•To unhighlight previously highlighted text in a window, use XawTextUnsetSelection(): void XawTextUnsetSelection(w)
     Widget w; where w specifies the window ID. 

•To enable the application to get the character positions of the selected text, use XawTextGetSelectionPos(): void XawTextGetSelectionPos(w, begin_return, end_return)
     Widget w;
     XawTextPosition ∗begin_return, ∗end_return; where:

wSpecifies the window ID. 

begin_return
Specifies a pointer to the location to which the beginning character position of the selection is returned.

end_returnSpecifies a pointer to the location to which the ending character position of the selection is returned. 

If the returned values are equal, there is no current selection. 

•To enable an application to replace text, use XawTextReplace(): int XawTextReplace(w, start_pos, end_pos, text)
     Widget w;
     XawTextPosition start_pos, end_pos;
     XawTextBlock ∗text; where:

wSpecifies the window ID. 

start_posSpecifies the starting character position of the text replacement. 

end_posSpecifies the ending character position of the text replacement. 

textSpecifies the text to be inserted into the file.  This function cannot replace text in read-only Text widgets, and it can only append text to an append-only Text widget. 

The XawTextReplace() function deletes text in the specified range (startPos, endPos) and inserts the new text at start_pos.  The return value is XawEditDone if the replacement is successful, XawPositionError if the edit mode is XawtextAppend and start_pos is not the position of the last character of the source, or XawEditError if either the source was read-only or the range to be deleted is larger than the length of the source.  The XawTextBlock structure (defined in <X11/Xaw/Text.h>) contains:

typedef struct { int firstPos;  int length;  char ∗ptr;  Atom format; } XawTextBlock, ∗XawTextBlockPtr, ∗TextBlockPtr;
                                         /∗ last for R4 compat ∗/

The firstPos field is the starting point to use within the ptr field.  The value is usually zero.  The length field is the number of characters that are transferred from the ptr field.  The number of characters transferred is usually the number of characters in ptr, which is the string to insert into the Text widget.  The format field is not currently used, but should be specified as FMT8BIT.  The XawTextReplace() arguments start_pos and end_pos represent the text source character positions for the existing text that is to be replaced by the text in the XawTextBlock structure.  The characters from start_pos up to but not including end_pos are deleted, and the characters that are specified by the text block are inserted in their place.  If start_pos and end_pos are equal, no text is deleted and the new text is inserted after start_pos.  Only Latin-1 text is currently supported, and only one font can be used for each Text widget.

•To search for a string in the Text widget, use XawTextSearch(): XawTextPosition XawTextSearch(w, dir, text)
      Widget w;
      XawTextScanDirection dir;
      XawTextBlock ∗ text;
 
where:

wSpecifies the window ID. 

dirSpecifies the direction to search in.  Legal values are XawsdLeft and XawsdRight. 

textSpecifies a text block structure (see XawTextReplace() for the definition) that contains the text to search for. 

The XawTextSearch() function will begin at the insertion point and search in the direction specified for a string that matches the one passed in text.  If the string is found, the location of the first character in the string is returned.  If the string could not be found, then the value XawTextSearchError is returned. 

•To redisplay a range of characters, use XawTextInvalidate(): void XawTextInvalidate(w, from, to)
      Widget w;
      XawTextPosition from, to; where:

wSpecifies the window ID. 

fromSpecifies the starting character to be displayed. 

toSpecifies the last character to be displayed. 

The XawTextInvalidate() function causes the specified range of characters to be redisplayed immediately if redisplay is enabled, or the next time that redisplay is enabled. 

•To enable redisplay, use XawTextEnableRedisplay(): void XawTextEnableRedisplay(w)
      Widget w; where w specifies the window ID.  XawTextEnableRedisplay() flushes any changes due to batched updates when XawTextDisableRedisplay() was called and allows future changes to be reflected immediately. 

•To disable redisplay while making several changes, use XawTextDisableRedisplay(): void XawTextDisableRedisplay(w)
       Widget w; where w specifies the window ID.  The XawTextDisableRedisplay() function causes all changes to be batched until XawTextDisplay() or XawTextEnableRedisplay() is called. 

•To display batched updates, use XawTextDisplay(): void XawTextDisplay(w)
     Widget w; where w specifies the window ID.  The XawTextDisplay() function forces any accumulated updates to be displayed. 

The following procedures are convenience procedures that replace calls to XtSetValues() or XtGetValues() when only a single resource is to be modified or retrieved. 

•To obtain the character position of the leftmost character on the first line displayed in the widget (that is, the value of XtNdisplayPosition), use XawTextTopPosition().  XawTextPosition XawTextTopPosition(w)
      Widget w; where w specifies the Text widget. 

•To assign a new selection array to a text widget use XawTextSetSelectionArray(): void XawTextSetSelectionArray(w, sarray)
      Widget w;
      XawTextSelectType ∗ sarray;

wSpecifies the Text widget. 

sarraySpecifies a selection array. 

Calling this function is equivalent to setting the value of the XtNselectionTypes resource. 

•To move the insertion caret to the specified source position, use XawTextSetInsertionPoint(): void XawTextSetInsertionPoint(w, position)
      Widget w;
      XawTextPosition position; where:

wSpecifies the Text widget. 

positionSpecifies the position to which to move the insertion caret. 

The text will be scrolled vertically, if necessary, to make the line containing the insertion point visible.  The result is equivalent to setting the XtNinsertPosition resource. 

•To obtain the current position of the insertion caret, use XawTextGetInsertionPoint(): XawTextPosition XawTextGetInsertionPoint(w)
      Widget w; where w specifies the Text widget. 

The result is equivalent to retrieving the value of the XtNinsertPosition resource. 

•To replace the text source in the specified widget, use XawTextSetSource(): void XawTextSetSource(w, source, position)
      Widget w;
      Widget source;
      XawTextPosition position; where:

wSpecifies the Text widget. 

sourceSpecifies the source widget. 

positionSpecifies the location to place the replacement text. 

A display update will be performed if redisplay has not been disabled. 

•To obtain the current text source for the specified widget, use XawTextGetSource(): XawTextSource XawTextGetSource(w)
      Widget w; where w specifies the Text widget. 

•To enable and disable the insertion point, use XawTextDisplayCaret(): void XawTextDisplayCaret(w, visible)
      Widget w;
      Boolean visible;

wSpecifies the Text widget. 

visibleSpecifies whether caret should be displayed. 

If visible is False, the insertion point will be disabled.  The marker can be re-enabled either by setting visible to True, by calling XtSetValues(), or by executing the display-caret action routine. 

CREATING SOURCES AND SINKS

The following functions for creating and destroying text sources and sinks are called automatically by asciiTextClass, and it is therefore necessary for the client to use them only when creating an instance of textWidgetClass. 

•To create a new ASCII text sink, use XtCreateWidget() and specify the class variable asciiSinkObjectClass.  The resources required by the sink are qualified by the name and class of the parent and the sub-part name XtNtextSink and class XtCTextSink. 

•To deallocate an ASCII text sink, use XtDestroyWidget() and specify the widget of the AsciiSink widget.  The sink must not be in use by any widget or an error will result. 

•To create a new text source, use XtCreateWidget() and specify the class variable asciiSourceObjectClass.  The resources required by the source are qualified by the name and class of the parent and the sub-part name XtNtextSource and class XtCTextSource. 

•To deallocate a text disk source, use XtDestroyWidget() and specify the widget of the AsciiSource widget.  The sink must not be in use by any widget or an error will result.