Added libXaw-1.0.7

1 files changed, 420 insertions, 0 deletions

diff --git a/libXaw/spec/TextSink b/libXaw/spec/TextSink
new file mode 100644
index 000000000..72ae3cf99
--- /dev/null
+++ b/libXaw/spec/TextSink
@@ -0,0 +1,420 @@
+.\" $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.