Application Header file		<X11/Xaw/AsciiSrc.h> or <X11/Xaw/MultiSrc.h>
Class Header file		<X11/Xaw/AsciiSrcP.h> or <X11/Xaw/MultiSrcP.h>
Class		asciiSrcObjectClass or multiSrcObjectClass
Class Name		AsciiSrc or MultiSrc
Superclass		TextSource

The AsciiSrc or MultiSrc object is used by a text widget to read the text from a file or string in memory. Depending on its international resource, an AsciiText widget will create one or the other of these when the AsciiText itself is created. Both types are nearly identical; the following discussion applies to both, with MultiSrc differences noted only as they occur.

The AsciiSrc understands all Latin characters plus Tab and Carriage Return. The MuXtiSrc understands any set of character sets that the underlying X implementation's internationalization handles.

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. The file is not updated, however, until a call to XawAsciiSave is made. When the source is in this mode the useStringInPlace resource is ignored.

AsciiSrc objects of type XawAsciiString have the text buffer implemented as a string. MultiSrc objects of type XawAsciiString have the text buffer implemented as a wide character 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 useStringlnPlace 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.

5.6.1. Resources

callback	The callbacks registered on this resource will be called every time the text buffer changes, after the text has been updated.
destroyCallback	All functions on this list are called when this widget is destroyed.
dataCompression	The AsciiSrc uses an algorithm that may cause the text buffer to grow to about twice the size of the actual text over time, as the text is edited. On systems where CPU cycles are cheaper than memory, it is helpful to spend some extra time to compress this buffer back to its minimum size. If this resource is 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.
editType	This is the type of editing that will be allowed in this text widget. Legal values are XawtextRead, XawtextEdit, and XawtextAppend. A converter is registered for this resource that will convert the following strings: read, edit, and append.
length	If the uscStringlnPlace resource is False this attribute has no effect. If that resource is True, however, then the length resource specifies the length of the buffer passed to the text widget in the string resource.
pieceSize	This is the size of the internal chunks into which the text buffer is broken down for memory management. The larger this value the less segmented your memory will be, but the slower your editing will be. The text widgets will always allocate a chunk of memory this size to stuff the string into, so when using small strings, having this buffer large can waste memory. This resource has no effect if useStringlnPlace is True.
string	If type is XawAsciiString then this string contains the buffer to be displayed in the widget. If type is XawAsciiFile then the string contains the name of the file to be displayed. This string is normally copied by the text widget into internal memory, but may be used in place by setting the useStringlnPlace resource. As of XllR4 this is a settable resource. When the string resource is queried, using XtGetValues, and useStringlnPlace is false, the value returned is valid until the next time the string resource is queried, or until the application writer calls XawAsci iSrcFreeString. If useStringlnPlace is true, a pointer to the actual string is returned. See also section 5.6.
type	his resource may be either XawAsciiString or XawAsciiFile. The value of this resource determines whether the string 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.
useStringlnPlace	Stting this resource to True will disable the memory management provided by the Text widget, updating the string resource in place. Using the string in place can be much more efficient for text widgets that display static data, or where the programmer wishes to impose strict constraints on the contents of the string. When using the string in place be sure that: the length of the string is specified by setting the length resource, the type of the Text widget is XawAsciiString, and that the string exists for the lifetime of the text widget, or until it has been reset. Note: Since the MultiSrc and AsciiSrc have different data formats, use of this resource forces application code to be cognisant as to which of the two is being used. Application programming is simplified when use of this resource is avoided.

5.6.2. Convenience Routines

5.6.2.1. Conserving Memory

void XawAsciiSourceFreeString(w)

Widget w;

w	Specifies the AsciiSrc object.

This function will free the memory that contains the string pointer returned by XtGetValues. This will normally happen automatically when the next call to XtGetValues occurs, or when the widget is destroyed.

5.6.2.2. Saving Files

Boolean XawAsciiSave(w) Widget w;

w	Specifies the AsciiSrc object.

XawAsciiSave returns True if the save was successful. It will update the file named in the string resource. If the buffer has not been changed, no action will be taken. This function only works on an AsciiSrc of type XawAsciiFile.

To save the contents of the current text buffer into a named file use XawAsciiSaveAsFile.

Boolean XawAsciiSaveAsFile(w, name)

Widget w;
String name;

w	Specifies the AsciiSrc object.
name	The name of the file to save the current buffer into.

This function returns True if the save was successful. XawAsciiSaveAsFile will work with a buffer of either type XawAsciiString or type XawAsciiFile.

5.6.2.3. Seeing if the Source has Changed

The AsciiSink or MultiSink object is used by a text widget to render the text. Depending on its international resource, a AsciiText widget will create one or the other of these when the AsciiText itself is created. Both types are nearly identical; the following discussion applies to both, with MultiSink differences noted only as they occur. The AsciiSink will display all printing characters in an 8 bit font, along with handling Tab and Carriage Return. The name has been left as "AsciiSink" for compatibility. The MultiSink will display all printing characters in a font set, along with handling Tab and Carriage Return. The source object also reports the text window metrics to the text widgets.

5.7.1. Resources

background	A pixel value which indexes the widget's colormap to derive the back ground color of the widget's window. This resource is retrieved by the AsciiSink instead of being copied from the Text widget.
destroyCallback	All functions on this list are called when this widget is destroyed.
displayNonprinting	If this resource is True, the Text widget will display all non-printable characters as the string ^@. If False, the Text widget will just leave a blank space where a non-printable character exists in the text buffer.
echo	Whether or not to echo characters to the screen. The buffer can still be edited, but nothing is displayed. This mode can be useful for entering passwords and other sensitive information.
font	The text font to use when displaying the string. (This resource is present in the AsciiSink, but not the MultiSink.)
fontSet	The text font set to use when displaying the string. (This resource is present in the MultiSink, but not the AsciiSink.)

5.8. Customizing the Text Widget

The Text widget is made up of a number of different pieces, with the Text widget as the base widget class. It and the AsciiText widget are the only true "widgets" in the Text widget family. The other pieces (sources and sinks) are X Toolkit objects and have no window associated with them. No source or sink is useful unless assigned to a Text widget.

Each of the following pieces of the Text widget has a specific purpose, and will be, or has been, discussed in detail in this chapter:

Text	This is the glue that binds everything else together. This widget reads the text data from the source, and displays the information in the sink. All translations and actions are handled in the Text widget itself.
TextSink	This object is responsible for displaying and clearing the drawing area. It also reports the configuration of the window that contains the drawing area The TextSink does not have its own window; instead it does its drawing on the Text widget's window.
TextSrc	This object is responsible for reading, editing and searching through the text buffer.
AsciiSink	This object is a subclass of the TextSink and knows how to display ASCII text. Support has been added to display any 8-bit character set, given the font.
MultiSink	This object is a subclass of the TextSink and knows how to display font sets.
AsciiSrc	This object is a subclass of the TextSrc and knows how to read strings and files.
MultiSrc	This object is a subclass of the TextSrc and knows how to read strings and multibyte files, converting them to wide characters based on locale.
AsciiText	This widget is a subclass of the Text widget. When created, the AsciiText automatically creates and attaches either an AsciiSrc and AsciiSink, or a MultiSrc and MultiSink, to itself. The AsciiText provides the simplest interface to the Athena Text widgets.

The Text widget is the glue that binds all the other pieces together, it maintains the internal state of the displayed text, and acts as a mediator between the source and sink.

This section lists the resources that are actually part of the Text widget, and explains the functionality provided by each.

5.9.1. Resources

Name	Class	Type	Notes	Dcfault Value
accelerators	Accelerators	AcceleratorTable		NULL
ancestorSensitive	AncestorSensitive	Boolean	D	True
autoFill	AutoFill	Boolean		False
background	Background	Pixel		XtDefaultBackground
backgroundPixmap	Pixmap	Pixmap		XtUnspecifiedPixmap
borderColor	BorderColor	Pixel		XtDcraultForeground
borderPixmap	Pixmap	Pixmap		XtUnspecifiedPixmap
borderWidth	BorderWidth	Dimension		1
bottomMargin	Margin	Position		2
colormap	Colormap	Colormap		Parent's ColorMap
cursor	Cursor	Cursor		XC_xterm
cursorName	Cursor	String		NULL
depth	Depth	int	C	Parent's Depth
destroyCallback	Callback	XtCallbackList		NULL
displayCaret	Output	Boolean		True
displayPosilion	TextPosition	XawTextPosition		0
height	Hight	Dimension	A	Font height + margins
insensitiveBorder	Insensitive	Pixmap		GreyPixmap
insertPosition	TextPosition	int		0
leftMargin	Margin	Position		2
mappedWhenManaged	MappedWhenManaged	Boolean		True
pointerColor	Foreground	Pixel		XtDefaultForeground
pointerColorBackground	Background	Pixel		XtDefaultBackground
resize	Resize	XawTextResizeMode		XawtextResizcNever
rightMargin	Margin	Position		4
screen	Screen	Pointer	R	Parent's Screen
scrollHorizontal	Scroll	ScrollMode		XawtextScollNever
scrollVertical	Scroll	XawTextScrollMode		XawtextScrollNever
selectTypes	SelectTypes	XawTextSelectType*		See above
sensitive	Sensitive	Boolean		True
textSink	TextSink	Widget		NULL
textSource	TextSource	Widget		NULL
topMargin	Margin	Position		2
translations	Translations	TranslationTable		See above
unrealizeCallback	Callback	XtCallbackList		NULL
width	Width	Dimension		100
wrap	Wrap	WrapMode		XawtextWrapNever
x	Position	Position		0
y	Position	Position		0

accelerators	A list of event to action bindings to be executed by this widget, even though the event occurred in another widget. (See the X Toolkit Intrinsics-C Language Interface for details).
ancestorSensitive	The sensitivity state of the ancestors of this widget. A widget is incense tie if either it or any of its ancestors is insensitive. This resource should not be changed with XtSetValues, although it may be queried.
autoFill	If this resource is True the text widget will automatically break a line when the user attempts to type into the right margin. The attribute has no effect on files or text inserted into the text widget. It only checks to see if the action should be taken when a user enters a new character via the insert-character action.
background	A pixel value which indexes the widget's colormap to derive the back ground color of the widget's window.
backgroundPixmap	The background pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the background color.
borderColor	A pixel value which indexes the widget's colormap to derive the border color of the widget's window.
borderPixmap	The border pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the border color.
borderWidth	The width of this widget's window border.
bottomMargin
leftMargin
rightMargin
topMargin	The amount of space, in pixels, between the edge of the window and the corresponding edge of the text within the window. If there is a scrollbar active on this edge, then this is the space between the text and the scrollbar.
colormap	The colormap that this widget will use.
cursor	The image that will be displayed as the pointer cursor whenever it is in this widget. The use of this resource is deprecated in favor of cursorName.
cursorName	The name of the symbol to use to represent the pointer cursor. This resource will override the cursor resource if both are specified. (See 2.5.1)
depth	The depth of this widget's window.
destroyCallback	All functions on this list are called when this widget is destroyed.
displayCaret	Whether or not to display the text insert point.
displayPosition	The position in the text buffer of the character that is currently displayed in the upper left hand corner of the text display.
height
width	The height and width of this widget in pixels.
insensitiveBorder	This pixmap will be tiled into the widget's border if the widget becomes insensitive.
insertPosition	This is the location of the insert point. It is expressed in characters from the beginning of the file. The cursor will always be forced to be on the screen. This resource may therefore be used to scroll the text display to a certain character position.
mappedWhenManaged	If this resource is True, then the widget's window will automatically be mapped by the Toolkit when it is realized and managed.
pointerColor	A pixel value which indexes the widget's colormap to derive the foreground color of the pointer symbol specified by the cursorName resource.
pointerColorBackground	A pixel value which indexes the widget's colormap to derive the background color of the pointer symbol specified by the cursorName resource.
resize	Controls whether or not the Text widget attempts to resize itself when it is no longer able to display the full text buffer in the associated window. Any attempt by the Text widget to resize itself is always subject to the constraints imposed by its parent. The values XawtextResizeNever, XawtextResizeWidth, XawtextResizeHeight, and XawtextResizeBoth are all acceptable for this resource. A converter is registered for this resource that will convert the following strings: never, height, width, and both.
screen	The screen on which this widget is displayed. This is not a settable resource.
ScrollHorizontal
scrollVertical	These resources control the placement of scrollbars on the left and bottom edge of the text widget. These resources accept the values XawtextScrollAlways, XawtextScrollWhenNeeded, and XawtextScrollNever. A converter is registered for this resource that will convert the following strings: always, never, and whenNeeded. If XawtextScrollWhenNeeded is specified, the appropriate scrollbar will only appear when there is text in the buffer that is not able to fit within the bounds of the current window. The scrollbar will disappear when the text once again fits within the window.
selectTypes	Specifies the selection type array that is used when multi-click is activated (see Text Selections for Application Programmers for details). This resource is used in place, and must not be freed until the widget is destroyed. There is no type converter registered for this resource, so it may not be set from the resource manager.
sensitive	Whether or not the toolkit should pass user events to this widget. The widget will not get input events if either ancestorSensitive or sensitive is False.
textSink
textSource	These are the TextSink or TextSource objects used by this widget. When using the Text widget these MUST be set by the application programmer. the AsciiText widget initializes these resources to point to an MultiSink and MultiSrc respectively. the AsciiText widget initializes these resources to point to an AsciiSink and AsciiSrc respectively.
translations	The event bindings associated with this widget.
wrap	When the text in any one line is wider than the window there are several possible actions. This resource allows the user to decide what will happen. The accepted values for this resource are XawtextWrapNever, XawtextWrapLine, and XawtextWrapWord. With XawtextWrap Line 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. A converter is registered for this resource that will convert the following strings: never, word, and line.
unrealizeCallback	A list of callback functions which will be executed when the Text widget is unrealized.
x
y	The location of the upper left outside corner of this widget in its parent.

The TextSrc object is the root object for all text sources. Any new text source objects should be subclasses of the TextSrc Object. The TextSrc Class contains all methods the Text widget expects a text source to export.
Since all text sources will have some resources in common the TextSrc defines a few new resources.

5.10.1. Resources

destroyCallback	All functions on this list are called when this widget is destroyed.
editType	This is the type of editing that will be allowed in this text widget. Legal values are XawtextRead, XawtextEdit, and XawtextAppend. A converter is registered for this resource that will convert the following strings: read, edit, and append.

5.10.2. Subclassing the TextSrc

Function	Inherit with	Publie InterFase	must specify
Read	XtinheritRead	XawTextSoureeRead	yes
Replace	XtInheritReplace	XawTextSoureeReplace	no
Sean	XtinheritScan	XawTextSourceSean	yes
Search	XtInheritSearch	XawTextSoureeSearch	no
SetSeleetion	XtinheritSetSelection	XawTextSourceSetSeleetion	no
Convertselecon	XtInheritConvertSelection	XawTextSourceConvertSelection	no

5.10.2.1. Reading Text.

XawTextPosition Read(w, pos, text_return, length)

Widget w;
XawTextPosition pos;
XawTextBlock *text_return;
int length;

w	Specifies the TextSrc object.
pos	Specifies the position of the first character to be read from the text buffer.
text	Returns the text read from the source.
length	Specifies the maximum number of characters the TextSrc should return to the application in text_return.

This function returns the actual number of characters read from the text buffer. The function is not required to return length characters if that many characters are in the file, it may break at any point that is convenient to the internal structure of the source. It may take several calls to Read before the desired portion of the text buffer is fully retrieved.

5.10.2.2. Replacing Text.

XawTextPosition Replace(w, start, end, text)

Widget w;
XawTextPosition start, end;
XawTextBlock *text;

w	Specifies the TextSrc object.
start	Specifies the position of the first character to be removed from the text buffer. This is also the location to begin inserting the new text.
end	Specifies the position immediately after the last character to be removed from the text buffer.
text	Specifies the text to be added to the text source.

This function can return any of the following values:

XawEditDone	The text replacement was successful.
XawPositionError	The edit mode is XawtextAppend and start is not the last character of the source.
XawEditError	Either the Source was read-only or the range to be deleted is larger than the length of the Source.

The Replace arguments start and end represent the text source character positions for the existing text that is to be replaced by the text in the text block. The characters from start up to but not including end are deleted, and the buffer specified by the text block is inserted in their place. If start and end are equal, no text is deleted and the new text is inserted after start.

5.10.2.3. Scanning the TextSrc

XawTextPosition Scan(w, position, type, dir, count, include)

Widget w;
XawTextPosition position;
XawTextScanType type;
XawTextScanDirection dir;
int count;
Boolean include;

w	Specifies the TextSrc object.
position	Specifies the position to begin scanning the source.
type	Specifies the type of boundary to scan for, may be one of: XawstPosition, XawstWhiteSpace, XawstEOL, XawstParagraph, XawstAll. The exact meaning of these boundaries is left up to the individual text source.
dir	Specifies the direction to scan, may be either XawsdLeft to search backward, or XawsdRight to search forward.
count	Specifies the number of boundaries to scan for.
include	Specifies whether the boundary itself should be included in the scan.

The Scan function returns the position In the text source of the desired boundary. It is expected to return a valid address for all calls made to it, thus if a particular request is made that would take the text widget beyond the end of the source it must return the position of that end.

5.10.2.4. Searching through a TextSrc

XawTextPosition Search(w, position, dir, text)

Widget w;
XawTextPosition position;
XawTextScanDirection dir;
XawTextBlock *text;

w	Specifies the TextSrc object.
position	Specifies the position to begin the search.
dir	Specifies the direction to search, may be either XawsdLeft to search backward, or XawsdRight to search forward.
text	Specifies a text block containing the text to search for.

This function will search through the text buffer attempting to find a match for the string in the text block. If a match is found in the direction specified, then the character location of the first character in the string is returned. If no text was found then XawTextSearchError is returned.

5.10.2.5. Text Selections

Boolean ConvenSelections(w, selection, target, type, value_return, length_return, format_return)

Widget w;
Atom *selection, *target, *type;
caddr_t *value_return;
unsigned long *length_return;
int *format_return;

w	Specifies the TextSrc object.
selection	Specifies the type of selection that was requested (e.g. PRIMARY).
target	Specifies the type of the selection that has been requested, which indicates the desired information about the selection (e.g. Filename, Text, Window).
type	Specifies a pointer to the atom into which the property type of the converted value of the selection is to be stored. For instance, either file name or text might have property type XA_STRING.
value_return	Returns a pointer into which a pointer to the converted value of the selection is to be stored. The selection owner is responsible for allocating this storage. The memory is considered owned by the toolkit, and is freed by XtFree when the Intrinsics selection mechanism is done with it.
length_return	Retums a pointer into which the number of elements in value is to be stored. The size of each element is determined by format.
format_return	Returns a pointer into which the size in bits of the data elements of the selection value is to be stored.

If this function returns True then the Text widget will assume that the source has taken care of convening the selection, Otherwise the Text widget will attempt to convert the selection itself.

If the source needs to know when the text selection is modified it should define a SetSelection procedure:

void SetSelection(w, start, end, selection)

Widget w;
XawTextPosition start, end;
Atom selection;

w	Specifies the TextSrc object.
start	Specifies the character position of the beginning of the new text selection.
end	Specifies the character position of the end of the new text selection.
selection	Specifies the type of selection that was requested (e.g. PRIMARY).

The TextSink object is the root object for all text sinks. Any new text sink objects should be subclasses of the TextSink Object. The TextSink Class contains all methods that the Text widget expects a text sink to export.

Since all text sinks will have some resources in common, the TextSink defines a few new resources.

5.11.1. Resources

background	A pixel value which indexes the widget's colormap to derive the back ground color of the widget's window.
destroyCallback	All functions on this list are called when this widget is destroyed.
foreground	A pixel value which indexes the Text widget's colormap to derive the foreground color used by the text sink.

5.11.2. Subclassing the TextSink

5.11.2.1. Displaying Text

void DisplayText(w, x, y, pos1, pos2, highlight)

Widget w;
Position x, y;
XawTextPosition pos1, pos2;
Boolean highlight;

w	Specifies the TextSink object.
x	Specifies the x location to start drawing the text.
y	Specifies the y location to start drawing text.
pos1	Specifies the location within the text source of the first character to be printed.
pos2	Specifies the location within the text source of the last character to be printed.
highlight	Specifies whether or not to paint the text region highlighted.

The Text widget will only pass one line at a time to the text sink, so this function does not need to know how to line feed the text. It is acceptable for this function to just ignore Carriage Returns.
x and y denote the upper left hand corner of the first character to be displayed.

5.11.2.2. Displaying the Insert Point

void InsertCursor(w, x, y, state)

Widget w;
Position x, y;
XawTextlnsertState state;

w	Specifies the TextSink object.
x	Specifies the x location of the cursor in Pixels.
y	Specifies the y location of the cursor in Pixels.
state	Specifies the state of the cursor, may be one of XawisOn or XawisOff.

X and y denote the upper left hand corner of the insert point.

5.11.2.3. Clearing Portions of the Text window

void ClearToBackground(w, x, y, width, height)

Widget w;
Position x, y;
Dimension width, height;

w	Specifies the TextSink object.
x	Specifies the x location, in pixels, of the Region to clear.
y	Specifies the y location, in pixels, of the Region to clear.
width	Specifies the width, in pixels, of the Region to clear.
height	Specifies the height, in pixels, of the Region to clear.

X and y denote the upper left hand corner of region to clear.

5.11.2.4. Finding a Text Position Given Pixel Values

void FindPosition(w, fromPos, fromX, width, stopAtWordBreak, pos_return, width_return, height_return)

Widget w;
XawTextPosition fromPos;
int fromX, width;
Boolean stopAtWordBreak;
XawTextPosition *pos_return;
int *width_returnI, *height_return;