.NH 2
Ascii 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>
.IN "AsciiSrc.h" ""
Class Header file	<X11/Xaw/AsciiSrcP.h>
.IN "AsciiSrcP.h" ""
Class		asciiSrcObjectClass
.IN "asciiSrcObjectClass" ""
Class Name	AsciiSrc
.IN "AsciiSrc object" "class name"
Superclass	TextSource
.sp 1
.LP
The AsciiSrc object is used by a text widget to read the text from a
file or string in memory.  It understands all Latin1 characters plus Tab
and Carriage Return.
.LP
The AsciiSrc can be either of two types:
.IP \fBXawAsciiFile\fP 1.25i
.IN "XawAsciiFile"
AsciiSrc objects of this type 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 previous versions of the AsciiSrc it
is now possible to specify an editable disk source.  The file is never
updated, however, until a call to \fBXawAsciiSave\fP is made.  When the
source is in this mode the \fBuseStringInPlace\fP resource is ignored.
.IP \fBXawAsciiString\fP 1.25i
.IN "XawAsciiString"
AsciiSrc objects of this type have the text buffer passed as a string.
This buffer normally will be copied and managed internally.  It is also
possible to use the string in place, by setting the
\fBuseStringInPlace\fP resource, and specifying the length of the
allocated buffer in the \fBlength\fP resource.
.LP
If the application chooses to allow the AsciiSrc to manage the string
internally (by default \fBuseStringInPlace\fP is \fBFalse\fP) then it
need not 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.  If this mode is used, the string passed
to the AsciiSrc at startup is not updated as the user types.  The only
way to get the latest version of the text string is with
\fBXtGetValues\fP.
.De
.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"
.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
callback	Callback	Callback		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
.ps 11
.nr PS 11
.vs 13
.nr VS 13
.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 \fBXawAsciiSrcFreeString\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.
