209 lines
7.1 KiB
Plaintext
209 lines
7.1 KiB
Plaintext
.\" $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.
|