home *** CD-ROM | disk | FTP | other *** search
- .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 <X11/Xaw/TextSink.h>
- .IN "TextSink.h" ""
- Class Header file <X11/Xaw/TextSinkP.h>
- .IN "TextSinkP.h" ""
- Class textSinkObjectClass
- .IN "textSinkObjectClass" ""
- Class Name TextSink
- .IN "TextSink object" "class name"
- Superclass Object
- .sp 1
- .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.
- .De
- .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"
- .ps 9
- .nr PS 9
- .vs 11
- .nr VS 11
- .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
- font Font XFontStruct* XtDefaultFont
- foreground Foreground Pixel XtDefaultForeground
- .sp 3p
- _
- .TE
- .ps 11
- .nr PS 11
- .vs 13
- .nr VS 13
- .Bg Bold
- One foreground color is provided in TextSink.
- .Dc
- .Sf Bold
- .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 and bad things will probably happen.
- .ps 9
- .nr PS 9
- .vs 11
- .nr VS 11
- .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
- .ps 11
- .nr PS 11
- .vs 13
- .nr VS 13
- .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.
-