Added libXaw-1.0.7

1 files changed, 397 insertions, 0 deletions

diff --git a/libXaw/spec/TextFuncs b/libXaw/spec/TextFuncs
new file mode 100644
index 000000000..ea26068a5
--- /dev/null
+++ b/libXaw/spec/TextFuncs
@@ -0,0 +1,397 @@
+.\" $Xorg: TextFuncs,v 1.3 2000/08/17 19:42:28 cpqbld Exp $
+.NH 2
+Text Functions
+.XS
+	Text Functions
+.XE
+.LP
+The following functions are provided as convenience routines for use with
+the Text widget.  Although many of these actions can be performed by
+modifying resources, these interfaces are frequently more efficient.
+.LP
+These data structures are defined in the Text widget's public header file,
+<X11/Xaw/Text.h>.
+.LP
+.IN "XawTextPosition" "" "@DEF@"
+typedef long XawTextPosition;
+.sp
+.LP
+Character positions in the Text widget begin at 0 and end at n, where
+n is the number of characters in the Text source widget.
+.LP
+.IN "XawTextBlock" "" "@DEF@"
+.Ds 0
+.TA .5i 1.5i 2.25i
+.ta .5i 1.5i 2.25i
+typedef struct {
+	int \fIfirstPos\fP;
+	int \fIlength\fP;
+	char *\fIptr\fP;
+	unsigned long \fIformat\fP;
+} XawTextBlock, *XawTextBlockPtr;
+.De
+.LP
+.IN "XawTextBlockPtr" ""
+.IP \fIfirstPos\fP 1.0i
+The first position, or index, to use within the \fIptr\fP field.
+The value is commonly zero.
+.IP \fIlength\fP 1.0i
+The number of characters to be used from the \fIptr\fP field.
+The number of characters used is commonly the number of characters
+in \fIptr\fP, and must not be greater than the length of the string
+in \fIptr\fP.
+.IP \fIptr\fP 1.0i
+Contains the string to be referenced by the Text widget.
+.IP \fIformat\fP 1.0i
+This flag indicates whether the data pointed to by \fBptr\fP is char
+or wchar_t.  When the associated widget has \fBinternational\fP set
+to \fBfalse\fP this field must be XawFmt8Bit.  When the associated
+widget has \fBinternational\fP set to \fBtrue\fP this field must be
+either XawFmt8Bit or XawFmtWide.
+.LP
+Note: Previous versions of Xaw used
+.PN FMT8BIT ,
+which has been retained for backwards compatibility. \fBFMT8BIT\fP is
+deprecated and will eventually be removed from the implementation.
+.NH 3
+Selecting Text
+.LP
+To select a piece of text, use
+.PN XawTextSetSelection :
+.IN "XawTextSetSelection" "" "@DEF@"
+.FD 0
+void XawTextSetSelection(\fIw\fP, \fIleft\fP, \fIright\fP)
+.br
+     Widget \fIw\fP;
+.br
+     XawTextPosition \fIleft\fP, \fIright\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.IP \fIleft\fP 1i
+Specifies the character position at which the selection begins.
+.IP \fIright\fP 1i
+Specifies the character position at which the selection ends.
+.LP
+See section 5.4 for a description of \fBXawTextPosition\fP.
+If redisplay is enabled, this function highlights the text and
+makes it the \fBPRIMARY\fP selection.  This function does not have any
+effect on \fBCUT_BUFFER0\fP.
+.LP
+.NH 3
+Unhighlighting Text
+.LP
+To unhighlight previously highlighted text in a widget, use
+\fBXawTextUnsetSelection\fP:
+.IN "XawTextUnsetSelection" "" "@DEF@"
+.FD 0
+void XawTextUnsetSelection(\fIw\fP)
+.br
+     Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.NH 3
+Getting Current Text Selection
+.LP
+To retrieve the text that has been selected by this
+text widget use \fBXawTextGetSelectionPos\fP:
+.IN "XawTextGetSelectionPos" "" "@DEF@"
+.FD 0
+void XawTextGetSelectionPos(\fIw\fP, \fIbegin_return\fP, \fIend_return\fP)
+.br
+     Widget \fIw\fP;
+.br
+     XawTextPosition *\fIbegin_return\fP, *\fIend_return\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.IP \fIbegin_return\fP 1i
+Returns the beginning of the text selection.
+.IP \fIend_return\fP 1i
+Returns the end of the text selection.
+.LP
+See section 5.4 for a description of \fBXawTextPosition\fP.
+If the returned values are equal, no text is currently selected.
+.NH 3
+Replacing Text
+.LP
+To modify the text in an editable Text widget use \fBXawTextReplace\fP:
+.IN "XawTextReplace" "" "@DEF@"
+.FD 0
+int XawTextReplace(\fIw\fP, \fIstart\fP, \fIend\fP, \fItext\fP)
+.br
+     Widget \fIw\fP;
+.br
+     XawTextPosition \fIstart\fP, \fIend\fP;
+.br
+     XawTextBlock *\fItext\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.IP \fIstart\fP 1i
+Specifies the starting character position of the text replacement.
+.IP \fIend\fP 1i
+Specifies the ending character position of the text replacement.
+.IP \fItext\fP 1i
+Specifies the text to be inserted into the file.
+.LP
+This function will not
+be able to replace text in read-only text widgets.  It will also only
+be able to append text to an append-only text widget.
+.LP
+See section 5.4 for a description of \fBXawTextPosition\fP and
+\fBXawTextBlock\fP.
+.LP
+This function may return 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 position of
+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 \fBXawTextReplace\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 characters
+specified on the text block are 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 3
+Searching for Text
+.LP
+To search for a string in the Text widget, use
+\fBXawTextSearch\fP:
+.IN "XawTextSearch" "" "@DEF@"
+.FD 0
+XawTextPosition XawTextSearch(\fIw\fP, \fIdir\fP, \fItext\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XawTextScanDirection \fIdir\fP;
+.br
+      XawTextBlock * \fItext\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.IP \fIdir\fP 1i
+Specifies the direction to search in.  Legal values are
+\fBXawsdLeft\fP and \fBXawsdRight\fP.
+.IP \fItext\fP 1i
+Specifies a text block structure that contains the text to search for.
+.LP
+See section 5.4 for a description of \fBXawTextPosition\fP and \fBXawTextBlock\fP.
+The \fBXawTextSearch\fP function will begin at the insertion point
+and search in the
+direction specified for a string that matches the one passed in
+\fItext\fP.  If the string is found the location of the first
+character in the string is returned.  If the string could not be
+found then the value \fBXawTextSearchError\fP is returned.
+.NH 3
+Redisplaying Text
+.LP
+To redisplay a range of characters, use \fBXawTextInvalidate\fP:
+.IN "XawTextInvalidate" "" "@DEF@"
+.FD 0
+void XawTextInvalidate(\fIw\fP, \fIfrom\fP, \fIto\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XawTextPosition \fIfrom\fP, \fIto\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.IP \fIfrom\fP 1i
+Specifies the start of the text to redisplay.
+.IP \fIto\fP 1i
+Specifies the end of the text to redisplay.
+.LP
+See section 5.4 for a description of \fBXawTextPosition\fP.
+The \fBXawTextInvalidate\fP
+function causes the specified range of characters to be redisplayed
+immediately if redisplay is enabled or the next time that redisplay is
+enabled.
+.LP
+.sp 1
+To enable redisplay, use \fBXawTextEnableRedisplay\fP:
+.IN "XawTextEnableRedisplay" "" "@DEF@"
+.FD 0
+void XawTextEnableRedisplay(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.LP
+The \fBXawTextEnableRedisplay\fP function flushes any changes due to
+batched updates when \fBXawTextDisableRedisplay\fP
+was called and allows future changes to be reflected immediately.
+.LP
+.sp 1
+To disable redisplay while making several changes, use
+\fBXawTextDisableRedisplay\fP.
+.IN "XawTextDisableRedisplay" "" "@DEF@"
+.FD 0
+void XawTextDisableRedisplay(\fIw\fP)
+.br
+       Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.LP
+The \fBXawTextDisableRedisplay\fP function causes all changes to be
+batched until either \fBXawTextDisplay\fP or \fBXawTextEnableRedisplay\fP
+is called.
+.LP
+.sp 1
+To display batched updates, use \fBXawTextDisplay\fP:
+.IN "XawTextDisplay" "" "@DEF@"
+.FD 0
+void XawTextDisplay(\fIw\fP)
+.br
+     Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.LP
+The \fBXawTextDisplay\fP function forces any accumulated updates to be
+displayed.
+.NH 3
+Resources Convenience Routines
+.LP
+To obtain the character position of the left-most character on the
+first line displayed in the widget (the value of the
+\fBdisplayPosition\fP resource), use \fBXawTextTopPosition\fP.
+.IN "XawTextTopPosition" "" @DEF@"
+.FD 0
+XawTextPosition XawTextTopPosition(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.LP
+.sp 1
+To assign a new selection array to a text widget use
+\fBXawTextSetSelectionArray\fP:
+.IN "XawTextSetSelectionArray" "" "@DEF@"
+.FD 0
+void XawTextSetSelectionArray(\fIw\fP, \fIsarray\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XawTextSelectType * \fIsarray\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.IP \fIsarray\fP 1i
+Specifies a selection array as defined in the section called \fBText
+Selections for Application Programmers\fP.
+.LP
+Calling this function is equivalent to setting the value of the
+\fBselectionTypes\fP resource.
+.LP
+.sp 1
+To move the insertion point to the specified source position, use
+\fBXawTextSetInsertionPoint\fP:
+.IN "XawTextSetInsertionPoint" "" "@DEF@"
+.FD 0
+void XawTextSetInsertionPoint(\fIw\fP, \fIposition\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XawTextPosition \fIposition\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.IP \fIposition\fP 1i
+Specifies the new position for the insertion point.
+.LP
+See section 5.4 for a description of \fBXawTextPosition\fP.
+The text will be scrolled vertically if necessary to make the line
+containing the insertion point visible.  Calling this function is
+equivalent to setting the \fBinsertPosition\fP resource.
+.LP
+.sp 1
+To obtain the current position of the insertion point, use
+\fBXawTextGetInsertionPoint\fP:
+.IN "XawTextGetInsertionPoint" "" "@DEF@"
+.FD 0
+XawTextPosition XawTextGetInsertionPoint(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.LP
+See section 5.4 for a description of \fBXawTextPosition\fP.
+The result is equivalent to retrieving the value of the
+\fBinsertPosition\fP resource.
+.LP
+.sp 1
+To replace the text source in the specified widget, use
+\fBXawTextSetSource\fP:
+.IN "XawTextSetSource" "" "@DEF@"
+.FD 0
+void XawTextSetSource(\fIw\fP, \fIsource\fP, \fIposition\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Widget \fIsource\fP;
+.br
+      XawTextPosition \fIposition\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.IP \fIsource\fP 1i
+Specifies the text source object.
+.IP \fIposition\fP 1i
+Specifies character position that will become the upper left hand corner
+of the displayed text.  This is usually set to zero.
+.LP
+See section 5.4 for a description of \fBXawTextPosition\fP.
+A display update will be performed if redisplay is enabled.
+.LP
+.sp 1
+To obtain the current text source for the specified widget, use
+\fBXawTextGetSource\fP:
+.IN "XawTextGetSource" "" "@DEF@"
+.FD 0
+Widget XawTextGetSource(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.LP
+This function returns the text source that this Text widget is currently
+using.
+.LP
+.sp
+To enable and disable the insertion point, use
+\fBXawTextDisplayCaret\fP:
+.IN "XawTextDisplayCaret" "" "@DEF@"
+.FD 0
+void XawTextDisplayCaret(\fIw\fP, \fIvisible\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Boolean \fIvisible\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Text widget.
+.IP \fIvisible\fP 1i
+Specifies whether or not the caret should be displayed.
+.LP
+If \fIvisible\fP is \fBFalse\fP the insertion point will be disabled.
+The marker is re-enabled either by setting \fIvisible\fP to \fBTrue\fP, by
+calling \fBXtSetValues\fP, or by executing the \fIdisplay-caret\fP
+action routine.