Added libXaw

1 files changed, 331 insertions, 0 deletions

diff --git a/libXaw/spec/TextSource b/libXaw/spec/TextSource
new file mode 100644
index 000000000..852db2dd3
--- /dev/null
+++ b/libXaw/spec/TextSource
@@ -0,0 +1,331 @@
+.\" $Xorg: TextSource,v 1.3 2000/08/17 19:42:28 cpqbld Exp $
+.NH 2
+TextSrc Object
+.LP
+.XS
+	TextSrc Object
+.XE
+.IN "TextSrc object" "" "@DEF@"
+.LP
+.Ds 0
+.TA 2.0i
+.ta 2.0i
+Application Header file	<X11/Xaw/TextSrc.h>
+.IN "TextSrc.h" ""
+Class Header file	<X11/Xaw/TextSrcP.h>
+.IN "TextSrcP.h" ""
+Class		textSrcObjectClass
+.IN "textSrcObjectClass" ""
+Class Name	TextSrc
+.IN "TextSrc object" "class name"
+Superclass	Object
+.De
+.LP
+The TextSrc object is the root object for all text sources.  Any new text
+source objects should be subclasses of the TextSrc Object.  The
+TextSrc Class contains all methods the Text widget expects a text
+source to export.
+.LP
+Since all text sources will have some resources in common the
+TextSrc defines a few new resources.
+.NH 3
+Resources
+.LP
+When creating an TextSrc object instance, the following resources are
+retrieved from the argument list or from the resource database:
+.LP
+.IN "TextSrc 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
+destroyCallback	Callback	XtCallbackList		NULL
+editType	EditType	EditMode		NULL
+.sp 3p
+_
+.TE
+.Dc
+.Oe Bold
+.NH 3
+Subclassing the TextSrc
+.IN "TextSrc object" "subclassing" "@DEF@"
+.LP
+The only purpose of the TextSrc Object is to be subclassed.  It contains
+the minimum set of class methods that all text sources must have.  All
+class methods of the TextSrc must be defined, as the Text widget uses
+them all.  While all may be inherited, the direct descendant of TextSrc
+\fBmust\fP specify some of them as TextSrc does not contain enough
+information to be a valid text source by itself.  Do not try to use the
+TextSrc as a valid source for the Text widget; it is not intended to be
+used as a source by itself and bad things will probably happen.
+.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
+Read	XtInheritRead	XawTextSourceRead	yes
+.IN "XtInheritRead" ""
+.IN "XawTextSourceRead" ""
+Replace	XtInheritReplace	XawTextSourceReplace	no
+.IN "XtInheritReplace" ""
+.IN "XawTextSourceReplace" ""
+Scan	XtInheritScan	XawTextSourceScan	yes
+.IN "XtInheritScan" ""
+.IN "XawTextSourceScan" ""
+Search	XtInheritSearch	XawTextSourceSearch	no
+.IN "XtInheritSearch" ""
+.IN "XawTextSourceSearch" ""
+SetSelection	XtInheritSetSelection	XawTextSourceSetSelection	no
+.IN "XtInheritSetSelection" ""
+.IN "XawTextSourceSetSelection" ""
+ConvertSelection	XtInheritConvertSelection	XawTextSourceConvertSelection	no
+.IN "XtInheritConvertSelection" ""
+.IN "XawTextSourceConvertSelection" ""
+_
+.TE
+.NH 4
+Reading Text.
+.LP
+To read the text in a text source use the \fBRead\fP function:
+.IN "TextSrc object" "Read" "@DEF@"
+.FD 0
+XawTextPosition Read(\fIw\fP, \fIpos\fP, \fItext_return\fP, \fIlength\fP)
+.br
+Widget \fIw\fP;
+.br
+XawTextPosition \fIpos\fP;
+.br
+XawTextBlock \fI*text_return\fP;
+.br
+int \fIlength\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the TextSrc object.
+.IP \fIpos\fP 1i
+Specifies the position of the first character to be read from the text buffer.
+.IP \fItext\fP 1i
+Returns the text read from the source.
+.IP \fIlength\fP 1i
+Specifies the maximum number of characters the TextSrc should
+return to the application in \fItext_return\fP.
+.LP
+This function returns the text position immediately after the
+characters read from the
+text buffer.  The function is not required to read \fIlength\fP
+characters if that many characters are in the file, it may break at
+any point that is convenient to the internal structure of the
+source.  It may take several calls to \fBRead\fP before the desired
+portion of the text buffer is fully retrieved.
+.NH 4
+Replacing Text.
+.LP
+To replace or edit the text in a text buffer use the \fBReplace\fP function:
+.FD 0
+XawTextPosition Replace(\fIw\fP, \fIstart\fP, \fIend\fP, \fItext\fP)
+.IN "TextSrc object" "Replace" @DEF@
+.br
+Widget \fIw\fP;
+.br
+XawTextPosition \fIstart\fP, \fIend\fP;
+.br
+XawTextBlock \fI*text\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the TextSrc object.
+.IP \fIstart\fP 1i
+Specifies the position of the first character to be removed from the text
+buffer.  This is also the location to begin inserting the new text.
+.IP \fIend\fP 1i
+Specifies the position immediately after the last character to be
+removed from the text buffer.
+.IP \fItext\fP 1i
+Specifies the text to be added to the text source.
+.LP
+This function can return any of the following values:
+.IP \fBXawEditDone\fP 1.25i
+.IN "XawEditDone" ""
+The text replacement was successful.
+.IP \fBXawPositionError\fP 1.25i
+.IN "XawPositionError" ""
+The edit mode is \fBXawtextAppend\fP and \fIstart\fP is not the last
+character of the source.
+.IP \fBXawEditError\fP 1.25i
+.IN "XawEditError" ""
+Either the Source was read-only or the range to be deleted is larger
+than the length of the Source.
+.LP
+The \fBReplace\fP arguments \fIstart\fP and \fIend\fP represent the
+text source character positions for the existing text that is to be
+replaced by the text in the text block.  The characters from
+\fIstart\fP up to but not including \fIend\fP are deleted, and the
+buffer specified by the text block is inserted in their
+place.  If \fIstart\fP and \fIend\fP are equal, no text is deleted and
+the new text is inserted after \fIstart\fP.
+.NH 4
+Scanning the TextSrc
+.LP
+To search the text source for one of the predefined boundary types use
+the \fBScan\fP function:
+.FD 0
+XawTextPosition Scan(\fIw\fP, \fIposition\fP, \fItype\fP, \fIdir\fP, \fIcount\fP, \fIinclude\fP)
+.IN "TextSrc object" "Scan" @DEF@
+.br
+Widget \fIw\fP;
+.br
+XawTextPosition \fIposition\fP;
+.br
+XawTextScanType \fItype\fP;
+.br
+XawTextScanDirection \fIdir\fP;
+.br
+int \fIcount\fP;
+.br
+Boolean \fIinclude\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the TextSrc object.
+.IP \fIposition\fP 1i
+Specifies the position to begin scanning the source.
+.IP \fItype\fP 1i
+Specifies the type of boundary to scan for, may be one of:
+\fBXawstPosition\fP, \fBXawstWhiteSpace\fP, \fBXawstEOL\fP,
+.IN "XawstPositions" ""
+.IN "XawstWhiteSpace" ""
+.IN "XawstEOL" ""
+\fBXawstParagraph\fP, \fBXawstAll\fP.  The exact meaning of these
+.IN "XawstParagraph" ""
+.IN "XawstAll" ""
+boundaries is left up to the individual text source.
+.IP \fIdir\fP 1i
+Specifies the direction to scan, may be either \fBXawsdLeft\fP to search
+.IN "XawsdLeft" ""
+backward, or \fBXawsdRight\fP to search forward.
+.IN "XawsdRight" ""
+.IP \fIcount\fP 1i
+Specifies the number of boundaries to scan for.
+.IP \fIinclude\fP 1i
+Specifies whether the boundary itself should be included in the scan.
+.LP
+The \fBScan\fP function returns the position in the text source of the desired
+boundary.  It is expected to return a valid address for
+all calls made to it, thus if a particular request is made that would take
+the text widget beyond the end of the source it must return the
+position of that end.
+.NH 4
+Searching through a TextSrc
+.LP
+To search for a particular string use the \fBSearch\fP function.
+.FD 0
+XawTextPosition Search(\fIw\fP, \fIposition\fP, \fIdir\fP, \fItext\fP)
+.IN "TextSrc object" "Search" @DEF@
+.br
+Widget \fIw\fP;
+.br
+XawTextPosition \fIposition\fP;
+.br
+XawTextScanDirection \fIdir\fP;
+.br
+XawTextBlock \fI*text\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the TextSrc object.
+.IP \fIposition\fP 1i
+Specifies the position to begin the search.
+.IP \fIdir\fP 1i
+Specifies the direction to search, may be either \fBXawsdLeft\fP to search
+.IN "XawsdLeft" ""
+backward, or \fBXawsdRight\fP to search forward.
+.IN "XawsdRight" ""
+.IP \fItext\fP 1i
+Specifies a text block containing the text to search for.
+.LP
+This function will search through the text buffer attempting to find a
+match for the string in the text block.  If a match is found in the
+direction specified, then the character location of the first character
+in the string is returned.  If no text was found then
+\fBXawTextSearchError\fP is returned.
+.IN "XawTextSearchError" ""
+.NH 4
+Text Selections
+.LP
+While many selection types are handled by the Text widget, text sources
+may have selection types unknown to the Text widget.  When a selection
+conversion is requested by the X server the Text widget will first call
+the \fBConvertSelection\fP function, to attempt the selection
+conversion.
+.FD 0
+Boolean ConvertSelections(\fIw\fP, \fIselection\fP, \fItarget\fP, \fItype\fP, \fIvalue_return\fP, \fIlength_return\fP, \fIformat_return\fP)
+.IN "Text widget" "ConvertSelection" @DEF@
+.br
+Widget \fIw\fP;
+.br
+Atom \fI*selection\fP, \fI*target\fP, \fI*type\fP;
+.br
+caddr_t \fI*value_return\fP;
+.br
+unsigned long \fI*length_return\fP;
+.br
+int \fI*format_return\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the TextSrc object.
+.IP \fIselection\fP 1i
+Specifies the type of selection that was requested (e.g. \fBPRIMARY\fP).
+.IP \fItarget\fP 1i
+Specifies the type of the selection that has been requested, which
+indicates the desired information about the selection (e.g. Filename,
+Text, Window).
+.IP \fItype\fP 1i
+Specifies a pointer to the atom into which the property type of the converted
+value of the selection is to be stored.  For instance, either file
+name or text might have property type \fBXA_STRING\fP.
+.IP \fIvalue_return\fP 1i
+Returns a pointer into which a pointer to the converted value of the
+selection
+is to be stored.  The selection owner is responsible for allocating
+this storage.  The memory is considered owned by the toolkit, and is
+freed by XtFree when the Intrinsics selection mechanism is done with it.
+.IP \fIlength_return\fP 1i
+Returns a pointer into which the number of elements in value is to be stored.
+The size of each element is determined by \fIformat\fP.
+.IP \fIformat_return\fP 1i
+Returns a pointer into which the size in bits of the data elements of the
+selection value is to be stored.
+.LP
+If this function returns \fBTrue\fP then the Text widget will assume
+that the source has taken care of converting the selection, Otherwise the
+Text widget will attempt to convert the selection itself.
+.LP
+.sp
+If the source needs to know when the text selection is modified it
+should define a \fBSetSelection\fP procedure:
+.FD 0
+void SetSelection(\fIw\fP, \fIstart\fP, \fIend\fP, \fIselection\fP)
+Widget \fIw\fP;
+.IN "SetSelection" "" @DEF@
+.br
+XawTextPosition \fIstart\fP, \fIend\fP;
+.br
+Atom \fIselection\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the TextSrc object.
+.IP \fIstart\fP 1i
+Specifies the character position of the beginning of the new text selection.
+.IP \fIend\fP
+Specifies the character position of the end of the new text selection.
+.IP \fIselection\fP 1i
+Specifies the type of selection that was requested (e.g. \fBPRIMARY\fP).