421 lines
13 KiB
Plaintext
421 lines
13 KiB
Plaintext
.\" $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 <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
|
|
.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.
|