TextSink Object

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.

New Resources

When creating an TextSink object instance, the following resources are retrieved from the argument list or from the resource database:

Name	Class	Type	Notes	Default Value
background	Background	Pixel		XtDefaultBackground
font	Font	XFontStruct*		XtDefaultFont
foreground	Foreground	Pixel		XtDefaultForeground

background	A pixel value which indexes the widget's colormap to derive the background color of the widget's window. One foreground color is provided in TextSink.
font	This is font for rendering all text and must be a character cell font.
foreground	A pixel value which indexes the widget's colormap to derive the foreground color of the widget's window. This color is also used to render all 1's in a bitmap one plane deep.

Subclassing the TextSink

Function	Inherit with	Public Interface	must specify
DisplayText	XtInheritDisplayText	XawTextSinkDisplayText	yes
InsertCursor	XtInheritInsertCursor	XawTextSinkInsertCursor	yes
ClearToBackground	XtInheritClearToBackground	XawTextSinkClearToBackground	no
FindPosition	XtInheritFindPosition	XawTextSinkFindPosition	yes
FindDistance	XtInheritFindDistance	XawTextSinkFindDistance	yes
Resolve	XtInheritResolve	XawTextSinkResolve	yes
MaxLines	XtInheritMaxLines	XawTextSinkMaxLines	no
MaxHeight	XtInheritMaxHeight	XawTextSinkMaxHeight	no
SetTabs	XtInheritSetTabs	XawTextSinkSetTabs	no
GetCursorBounds	XtInheritGetCursorBounds	XawTextSinkGetCursorBounds	yes

Convenient routines

Displaying Text

To display a section of the text buffer contained in the text source use the function DisplayText:

void DisplayText(w, x, y, pos1, pos2, highlight)
	Widget w;
	Position x, y;
	XawTextPosition pos1, pos2;
	Boolean highlight;

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.

Displaying the Insert Point

The function that controls the display of the text cursor is InsertCursor. This function will be called whenever the text widget desires to change the state of, or move the insert point.

void InsertCursor(w, x, y, state)
	Widget w;
	Position x, y;
	XawTextInsertState state;

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

Clearing Portions of the Text window

void ClearToBackground(w, x, y, width, height)
	Widget w;
	Position x, y;
	Dimension width, height;

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

Finding a Text Position Given Pixel Values

To find the text character position that will be rendered at a given x location the Text widget uses the function FindPosition:

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_return, *height_return;

This function need make no attempt to deal with line feeds. The text widget will only call it one line at a time.

Another means of finding a text position is provided by the Resolve function:

void Resolve(w, fromPos, fromX, width, pos_return)
	Widget w;
	XawTextPosition fromPos;
	int fromX, width;
	XawTextPosition *pos_return;

This function need make no attempt to deal with line feeds. The text widget will only call it one line at a time. This is a more convenient interface to the FindPosition function, and provides a subset of its functionality.

Finding the Distance Between two Text Positions

void FindDistance(w, fromPos, fromX, toPos, 
                  width_return, pos_return, height_return)
	Widget w;
	XawTextPosition fromPos, toPos;
	int fromX;
	XawTextPosition *pos_return;
	int *width_return, *height_return;

This function need make no attempt to deal with line feeds. The Text widget will only call it one line at a time.

Finding the Size of the Drawing area

To find the maximum number of lines that will fit into the current Text widget, use the function MaxLines. The TextSink already defines this function to compute the maximum number of lines by using the height of font.

int MaxLines(w, height)
	Widget w;
	Dimension height;

Returns the maximum number of lines that will fit in height.

To find the height required for a given number of text lines, use the function MaxHeight. The TextSink already defines this function to compute the maximum height of the window by using the height of font.

int MaxHeight(w, lines)
	Widget w;
	int lines;

Returns the height that will be taken up by the number of lines passed.

Setting the Tab Stops

To set the tab stops for a text sink use the SetTabs function. The TextSink already defines this function to set the tab x location in pixels to be the number of characters times the figure width of font.

void SetTabs(w, tab_count, tabs)
	Widget w;
	int tab_count, *tabs;

This function is responsible for the converting character positions passed to it into whatever internal positions the TextSink uses for tab placement.

Getting the Insert Point's Size and Location

To get the size and location of the insert point use the GetCursorBounds function.

void GetCursorBounds(w, rect_return)
	Widget w;
	XRectangle *rect_return;

Rect will be filled with the current size and location of the insert point.