home *** CD-ROM | disk | FTP | other *** search
- .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
- .sp 1
- .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.
- .De
- .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"
- .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
- destroyCallback Callback XtCallbackList NULL
- editType EditType EditMode NULL
- .sp 3p
- _
- .TE
- .ps 11
- .nr PS 11
- .vs 13
- .nr VS 13
- .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.
- .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
- 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
- .ps 11
- .nr PS 11
- .vs 13
- .nr VS 13
- .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 actual number of characters read from the
- text buffer. The function is not required to return \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).
-