Added libXaw-1.0.7

1 files changed, 208 insertions, 0 deletions

diff --git a/libXaw/spec/AsciiSource b/libXaw/spec/AsciiSource
new file mode 100644
index 000000000..19b976562
--- /dev/null
+++ b/libXaw/spec/AsciiSource
@@ -0,0 +1,208 @@
+.\" $Xorg: AsciiSource,v 1.3 2000/08/17 19:42:26 cpqbld Exp $
+.NH 2
+Ascii Source Object and Multi Source Object
+.LP
+.XS
+	AsciiSrc Object
+.XE
+.IN "AsciiSrc object" "" "@DEF@"
+.LP
+.Ds 0
+.TA 2.0i
+.ta 2.0i
+Application Header file	<X11/Xaw/AsciiSrc.h> or <X11/Xaw/MultiSrc.h>
+.IN "AsciiSrc.h" ""
+Class Header file	<X11/Xaw/AsciiSrcP.h> or  <X11/Xaw/MultiSrcP.h>
+.IN "AsciiSrcP.h" ""
+Class		asciiSrcObjectClass or multiSrcObjectClass
+.IN "asciiSrcObjectClass" ""
+Class Name	AsciiSrc or MultiSrc
+.IN "AsciiSrc object" "class name"
+Superclass	TextSource
+.De
+.LP
+The AsciiSrc or MultiSrc object is used by a text widget to read the text from a
+file or string in memory.  Depending on its \fBinternational\fP resource, an
+AsciiText widget will create one or the other of these when the AsciiText
+itself is created.  Both types are nearly identical; the following discussion
+applies to both, with MultiSrc differences noted only as they occur.
+.LP
+The AsciiSrc understands all Latin1 characters plus Tab
+and Carriage Return.  \fIThe MultiSrc understands any set of character sets that
+the underlying X implementation's internationalization handles.\fP
+.LP
+The AsciiSrc can be either of two types: \fBXawAsciiFile\fP
+or \fBXawAsciiString\fP.
+.LP
+AsciiSrc objects of type \fBXawAsciiFile\fP read the text from a file and
+store it
+into an internal buffer.  This buffer may then be modified, provided the
+text widget is in the correct edit mode, just as if it were a source of
+type \fBXawAsciiString\fP.  Unlike R3 and earlier versions of the AsciiSrc,
+it is now possible to specify an editable disk source.  The file is not
+updated, however, until a call to \fBXawAsciiSave\fP is made.  When the
+source is in this mode the \fBuseStringInPlace\fP resource is ignored.
+.LP
+AsciiSrc objects of type \fBXawAsciiString\fP have the text buffer
+implemented as a string.
+\fIMultiSrc objects of type \fBXawAsciiString\fP have the text buffer
+implemented as a wide character string.\fP
+The string owner is responsible for allocating and managing storage for the
+string.
+.LP
+In the default case for AsciiSrc objects of type \fBXawAsciiString\fP,
+the resource \fBuseStringInPlace\fP is false,
+and the widget owns the string.  The initial value of the
+string resource, and any update made by the application
+programmer to the string resource with \fBXtSetValues\fP, is copied
+into memory private to the widget, and managed internally by the widget.
+The application writer
+does not need to worry about running out of buffer space
+(subject to the total memory available to the application).
+The performance does not decay linearly as the buffer grows
+large, as is necessarily the case when the text buffer is used
+in place.   The application writer must use \fBXtGetValues\fP to
+determine the contents of the text buffer, which will return
+a copy of the widget's text buffer as
+it existed at the time of the \fBXtGetValues\fP call.   This copy
+is not affected by subsequent updates to the text buffer, i.e.,
+it is not updated as the user types input into the text buffer.
+This copy is freed upon the next call to XtGetValues to
+retrieve the string resource; however, to conserve memory,
+there is a convenience routine, \fBXawAsciiSourceFreeString\fP, allowing the
+application programmer to direct the widget to free the copy.
+.LP
+When the resource \fBuseStringInPlace\fP is true and the AsciiSrc object
+is of type \fBXawAsciiString\fP, the application
+is the string owner.  The widget will take the value
+of the string resource as its own text buffer, and the \fBlength\fP
+resource indicates the buffer size.   In this case
+the buffer contents change as the user types at the widget;
+it is not necessary to call \fBXtGetValues\fP on the string
+resource to determine the contents of the buffer\*-it will
+simply return the address of the application's implementation
+of the text buffer.
+.NH 3
+Resources
+.LP
+When creating an AsciiSrc object instance, the following resources are
+retrieved from the argument list or from the resource database:
+.LP
+.IN "AsciiSrc 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
+callback	Callback	XtCallbackList		NULL
+dataCompression	DataCompression	Boolean		True
+destroyCallback	Callback	Callback		NULL
+editType	EditType	EditMode		XawtextRead
+length	Length	Int	A	length of \fBstring\fP
+pieceSize	PieceSize	Int		BUFSIZ
+string	String	String		NULL
+type	Type	AsciiType		XawAsciiString
+useStringInPlace	UseStringInPlace	Boolean		False
+.sp 3p
+_
+.TE
+.Oc Bold
+.Dc
+.Od Bold
+.Oe
+.Ol Bold
+.Op Bold
+.Os Bold
+.Ot Bold
+.Ou Bold
+.NH 3
+Convenience Routines
+.LP
+The AsciiSrc has a few convenience routines that allow the
+application programmer quicker or easier access to some of the
+commonly used functionality of the AsciiSrc.
+.NH 4
+Conserving Memory
+.LP
+When the AsciiSrc widget is not in \fBuseStringInPlace\fP mode
+space must be allocated whenever the file is saved, or the string is
+requested with a call to \fBXtGetValues\fP.  This memory is allocated on the
+fly, and remains valid until the next time a string needs to be allocated.
+You may save memory by freeing this string as soon as you are done
+with it by calling \fBXawAsciiSourceFreeString\fP.
+.FD 0
+void XawAsciiSourceFreeString(\fIw\fP)
+.IN "XawAsciiSourceFreeString" "" @DEF@
+.br
+Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the AsciiSrc object.
+.LP
+This function will free the memory that contains the string pointer returned
+by \fBXtGetValues\fP.  This will normally happen automatically when
+the next call to \fBXtGetValues\fP occurs, or when the widget is destroyed.
+.NH 4
+Saving Files
+.LP
+To save the changes made in the current text source into a file use
+\fBXawAsciiSave\fP.
+.FD 0
+Boolean XawAsciiSave(\fIw\fP)
+.IN "XawAsciiSave" "" @DEF@
+.br
+Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the AsciiSrc object.
+.LP
+\fBXawAsciiSave\fP returns \fBTrue\fP if the save was successful.
+It will update the file named in the \fBstring\fP resource.
+If the buffer has not been changed, no action will be taken.  This function
+only works on an AsciiSrc of type \fBXawAsciiFile\fP.
+.LP
+.sp 1
+To save the contents of the current text buffer into a named file use
+\fBXawAsciiSaveAsFile\fP.
+.FD 0
+Boolean XawAsciiSaveAsFile(\fIw\fP, \fIname\fP)
+.IN "XawAsciiSaveAsFile" "" @DEF@
+.br
+Widget \fIw\fP;
+.br
+String \fIname\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the AsciiSrc object.
+.IP \fIname\fP 1i
+The name of the file to save the current buffer into.
+.LP
+This function returns \fBTrue\fP if the save was successful.
+\fBXawAsciiSaveAsFile\fP will work with a buffer of either type
+\fBXawAsciiString\fP or type \fBXawAsciiFile\fP.
+.NH 4
+Seeing if the Source has Changed
+.LP
+To find out if the text buffer in an AsciiSrc object has changed
+since the last time it was saved with \fBXawAsciiSave\fP or queried
+.IN "XawAsciiSave" ""
+use \fBXawAsciiSourceChanged\fP.
+.FD 0
+Boolean XawAsciiSourceChanged(\fIw\fP)
+.IN "XawAsciiSourceChanged" "" @DEF@
+.br
+Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the AsciiSrc object.
+.LP
+This function will return \fBTrue\fP if the source has changed since
+the last time it was saved or queried.  The internal change flag is
+reset whenever the string is queried via \fBXtGetValues\fP or the
+buffer is saved via \fBXawAsciiSave\fP.