diff options
Diffstat (limited to 'libXaw/spec/TextSource')
| -rw-r--r-- | libXaw/spec/TextSource | 331 |
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). |