332 lines
10 KiB
Plaintext
332 lines
10 KiB
Plaintext
.\" $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).
|