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