.\" $Xorg: TextSink,v 1.3 2000/08/17 19:42:28 cpqbld Exp $ .NH 2 TextSink Object .LP .XS TextSink Object .XE .IN "TextSink object" "" "@DEF@" .LP .Ds 0 .TA 2.0i .ta 2.0i Application Header file .IN "TextSink.h" "" Class Header file .IN "TextSinkP.h" "" Class textSinkObjectClass .IN "textSinkObjectClass" "" Class Name TextSink .IN "TextSink object" "class name" Superclass Object .De .LP 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. .LP Since all text sinks will have some resources in common, the TextSink defines a few new resources. .NH 3 Resources .LP When creating an TextSink object instance, the following resources are retrieved from the argument list or from the resource database: .LP .IN "AsciiSink object" "resources" .TS H lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i). _ .sp 3p .TB Name Class Type Notes Default Value .sp 3p _ .TH .R .sp 3p background Background Pixel XtDefaultBackground destroyCallback Callback XtCallbackList NULL foreground Foreground Pixel XtDefaultForeground .sp 3p _ .TE .Bg Bold .Dc .Sg Bold .NH 3 Subclassing the TextSink .IN "TextSink object" "subclassing" "@DEF@" .LP The only purpose of the TextSink Object is to be subclassed. It contains the minimum set of class methods that all text sinks must have. While all may be inherited, the direct descendant of TextSink \fBmust specify\fP some of them as TextSink does contain enough information to be a valid text sink by itself. Do not try to use the TextSink as a valid sink for the Text widget; it is not intended to be used as a sink by itself. .TS H lw(1i) lw(1.5i) lw(2i) lw(1i). _ .sp 3p .TB Function Inherit with Public Interface must specify .sp 3p _ .TH .R .sp 3p DisplayText XtInheritDisplayText XawTextSinkDisplayText yes .IN "XtInheritDisplayText" "" .IN "XawTextSinkDisplayText" "" InsertCursor XtInheritInsertCursor XawTextSinkInsertCursor yes .IN "XtInheritInsertCursor" "" .IN "XawTextSinkInsertCursor" "" ClearToBackground XtInheritClearToBackground XawTextSinkClearToBackground no .IN "XtInheritClearToBackground" "" .IN "XawTextSinkClearToBackground" "" FindPosition XtInheritFindPosition XawTextSinkFindPosition yes .IN "XtInheritFindPosition" "" .IN "XawTextSinkFindPosition" "" FindDistance XtInheritFindDistance XawTextSinkFindDistance yes .IN "XtInheritFindDistance" "" .IN "XawTextSinkFindDistance" "" Resolve XtInheritResolve XawTextSinkResolve yes .IN "XtInheritResolve" "" .IN "XawTextSinkResolve" "" MaxLines XtInheritMaxLines XawTextSinkMaxLines no .IN "XtInheritMaxLines" "" .IN "XawTextSinkMaxLines" "" MaxHeight XtInheritMaxHeight XawTextSinkMaxHeight no .IN "XtInheritMaxHeight" "" .IN "XawTextSinkMaxHeight" "" SetTabs XtInheritSetTabs XawTextSinkSetTabs no .IN "XtInheritSetTabs" "" .IN "XawTextSinkSetTabs" "" GetCursorBounds XtInheritGetCursorBounds XawTextSinkGetCursorBounds yes .IN "XtInheritGetCursorBounds" "" .IN "XawTextSinkGetCursorBounds" "" _ .TE .NH 4 Displaying Text .LP To display a section of the text buffer contained in the text source use the function \fBDisplayText\fP: .IN "TextSink object" "DisplayText" "@DEF@" .FD 0 void DisplayText(\fIw\fP, \fIx\fP, \fIy\fP, \fIpos1\fP, \fIpos2\fP, \fIhighlight\fP) .br Widget \fIw\fP; .br Position \fIx\fP, \fIy\fP; .br XawTextPosition \fIpos1\fP, \fIpos2\fP; .br Boolean \fIhighlight\fP; .FN .IP \fIw\fP 1i Specifies the TextSink object. .IP \fIx\fP 1i Specifies the x location to start drawing the text. .IP \fIy\fP 1i Specifies the y location to start drawing text. .IP \fIpos1\fP 1i Specifies the location within the text source of the first character to be printed. .IP \fIpos2\fP 1i Specifies the location within the text source of the last character to be printed. .IP \fIhighlight\fP 1i Specifies whether or not to paint the text region highlighted. .LP 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. \fIx\fP and \fIy\fP denote the upper left hand corner of the first character to be displayed. .NH 4 Displaying the Insert Point .LP The function that controls the display of the text cursor is \fBInsertCursor\fP. This function will be called whenever the text widget desires to change the state of, or move the insert point. .FD 0 void InsertCursor(\fIw\fP, \fIx\fP, \fIy\fP, \fIstate\fP) .IN "TextSink object" "InsertCursor" "@DEF@" .br Widget \fIw\fP; .br Position \fIx\fP, \fIy\fP; .br XawTextInsertState \fIstate\fP; .FN .IP \fIw\fP 1i Specifies the TextSink object. .IP \fIx\fP 1i Specifies the x location of the cursor in Pixels. .IP \fIy\fP 1i Specifies the y location of the cursor in Pixels. .IP \fIstate\fP 1i Specifies the state of the cursor, may be one of \fBXawisOn\fP or \fBXawisOff\fP. .LP \fIX\fP and \fIy\fP denote the upper left hand corner of the insert point. .NH 4 Clearing Portions of the Text window .LP To clear a portion of the Text window to its background color, the Text widget will call \fBClearToBackground\fP. The TextSink object already defines this function as calling \fBXClearArea\fP on the region passed. This behavior will be used if you specify \fBXtInheritClearToBackground\fP for this method. .IN "XtInheritClearToBackground" "" .IN "TextSink object" "ClearToBackground" "@DEF@" .FD 0 void ClearToBackground(\fIw\fP, \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP) .br Widget \fIw\fP; .br Position \fIx\fP, \fIy\fP; .br Dimension \fIwidth\fP, \fIheight\fP; .FN .IP \fIw\fP 1i Specifies the TextSink object. .IP \fIx\fP 1i Specifies the x location, in pixels, of the Region to clear. .IP \fIy\fP 1i Specifies the y location, in pixels, of the Region to clear. .IP \fIwidth\fP 1i Specifies the width, in pixels, of the Region to clear. .IP \fIheight\fP 1i Specifies the height, in pixels, of the Region to clear. .LP \fIX\fP and \fIy\fP denote the upper left hand corner of region to clear. .NH 4 Finding a Text Position Given Pixel Values .LP To find the text character position that will be rendered at a given x location the Text widget uses the function \fBFindPosition\fP: .IN "TextSink object" "FindPosition" "@DEF@" .FD 0 void FindPosition(\fIw\fP, \fIfromPos\fP, \fIfromX\fP, \fIwidth\fP, \fIstopAtWordBreak\fP, \fIpos_return\fP, \fIwidth_return\fP, \fIheight_return\fP) .br Widget \fIw\fP; .br XawTextPosition \fIfromPos\fP; .br int \fIfromX\fP, \fIwidth\fP; .br Boolean \fIstopAtWordBreak\fP; .br XawTextPosition \fI*pos_return\fP; .br int \fI*width_return\fP, \fI*height_return\fP; .FN .IP \fIw\fP 1.25i Specifies the TextSink object. .IP \fIfromPos\fP 1.25i Specifies a reference position, usually the first character in this line. This character is always to the left of the desired character location. .IP \fIfromX\fP 1.25i Specifies the distance that the left edge of \fIfromPos\fP is from the left edge of the window. This is the reference x location for the reference position. .IP \fIwidth\fP 1.25i Specifies the distance, in pixels, from the reference position to the desired character position. .IP \fIstopAtWordBreak\fP 1.25i Specifies whether or not the position that is returned should be forced to be on a word boundary. .IP \fIpos_return\fP 1.25i Returns the character position that corresponds to the location that has been specified, or the work break immediately to the left of the position if \fIstopAtWordBreak\fP is \fBTrue\fP. .IP \fIwidth_return\fP 1.25i Returns the actual distance between \fIfromPos\fP and \fIpos_return\fI. .IP \fIheight_return\fP 1.25i Returns the maximum height of the text between \fIfromPos\fP and \fIpos_return\fI. .LP This function need make no attempt to deal with line feeds. The text widget will only call it one line at a time. .LP .sp Another means of finding a text position is provided by the \fBResolve\fP function: .IN "TextSink object" "Resolve" "@DEF@" .FD 0 void Resolve(\fIw\fP, \fIfromPos\fP, \fIfromX\fP, \fIwidth\fP, \fIpos_return\fP) .br Widget \fIw\fP; .br XawTextPosition \fIfromPos\fP; .br int \fIfromX\fP, \fIwidth\fP; .br XawTextPosition \fI*pos_return\fP; .FN .IP \fIw\fP 1i Specifies the TextSink object. .IP \fIfromPos\fP 1i Specifies a reference position, usually the first character in this line. This character is always to the left of the desired character location. .IP \fIfromX\fP 1i Specifies the distance that the left edge of \fIfromPos\fP is from the left edge of the window. This is the reference x location for the reference position. .IP \fIwidth\fP 1i Specifies the distance, in pixels, from the reference position to the desired character position. .IP \fIpos_return\fP 1i Returns the character position that corresponds to the location that has been specified, or the word break immediately to the left if \fIstopAtWordBreak\fP is \fBTrue\fP. .LP 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 \fBFindPosition\fP function, and provides a subset of its functionality. .IN "FindPosition" "" .NH 4 Finding the Distance Between two Text Positions .LP To find the distance in pixels between two text positions on the same line use the function \fBFindDistance\fP. .IN "TextSink object" "FindDistance" "@DEF@" .FD 0 void FindDistance(\fIw\fP, \fIfromPos\fP, \fIfromX\fP, \fItoPos\fP, \fIwidth_return\fP, \fIpos_return\fP, \fIheight_return\fP) .br Widget \fIw\fP; .br XawTextPosition \fIfromPos\fP, \fItoPos\fP; .br int \fIfromX\fP; .br XawTextPosition \fI*pos_return\fP; .br int \fI*width_return\fP, \fI*height_return\fP; .FN .IP \fIw\fP 1i Specifies the TextSink object. .IP \fIfromPos\fP 1i Specifies the text buffer position, in characters, of the first position. .IP \fIfromX\fP 1i Specifies the distance that the left edge of \fIfromPos\fP is from the left edge of the window. This is the reference x location for the reference position. .IP \fItoPos\fP 1i Specifies the text buffer position, in characters, of the second position. .IP \fIresWidth\fP 1i Return the actual distance between \fIfromPos\fP and \fIpos_return\fI. .IP \fIresPos\fP 1i Returns the character position that corresponds to the actual character position used for \fItoPos\fP in the calculations. This may be different than \fItoPos\fP, for example if \fIfromPos\fP and \fItoPos\fP are on different lines in the file. .IP \fIheight_return\fP 1i Returns the maximum height of the text between \fIfromPos\fP and \fIpos_return\fP. .LP This function need make no attempt to deal with line feeds. The Text widget will only call it one line at a time. .NH 4 Finding the Size of the Drawing area .LP To find the maximum number of lines that will fit into the current Text widget, use the function \fBMaxLines\fP. The TextSink already defines this function to compute the maximum number of lines by using the height of \fBfont\fP. .IN "TextSink object" "MaxLines" "@DEF@" .FD 0 int MaxLines(\fIw\fP, \fIheight\fP) .br Widget \fIw\fP; .br Dimension \fIheight\fP; .FN .IP \fIw\fP 1i Specifies the TextSink object. .IP \fIheight\fP 1i Specifies the height of the current drawing area. .LP Returns the maximum number of lines that will fit in \fIheight\fP. .LP .sp To find the height required for a given number of text lines, use the function \fBMaxHeight\fP. The TextSink already defines this function to compute the maximum height of the window by using the height of \fBfont\fP. .IN "TextSink object" "MaxHeight" "@DEF@" .FD 0 int MaxHeight(\fIw\fP, \fIlines\fP) .br Widget \fIw\fP; .br int \fIlines\fP; .FN .IP \fIw\fP 1i Specifies the TextSink object. .IP \fIheight\fP 1i Specifies the height of the current drawing area. .LP Returns the height that will be taken up by the number of lines passed. .NH 4 Setting the Tab Stops .LP To set the tab stops for a text sink use the \fBSetTabs\fP 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 \fBfont\fP. .IN "TextSink object" "SetTabs" "@DEF@" .FD 0 void SetTabs(\fIw\fP, \fItab_count\fP, \fItabs\fP) .br Widget \fIw\fP; .br int \fItab_count\fP, \fI*tabs\fP; .FN .IP \fIw\fP 1i Specifies the TextSink object. .IP \fItab_count\fP 1i Specifies the number of tabs passed in \fItabs\fP. .IP \fItabs\fP 1i Specifies the position, in characters, of the tab stops. .LP This function is responsible for the converting character positions passed to it into whatever internal positions the TextSink uses for tab placement. .NH 4 Getting the Insert Point's Size and Location .LP To get the size and location of the insert point use the \fBGetCursorBounds\fP function. .IN "TextSink object" "GetCursorBounds" "@DEF@" .FD 0 void GetCursorBounds(\fIw\fP, \fIrect_return\fP) .br Widget \fIw\fP; .br XRectangle \fI*rect_return\fP; .FN .IP \fIw\fP 1i Specifies the TextSinkObject. .IP \fIrect_return\fP 1i Returns the location and size of the insert point. .LP \fIRect\fP will be filled with the current size and location of the insert point.