path: root/libXaw/spec/AsciiSource

.\" $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.