aboutsummaryrefslogtreecommitdiff
path: root/libXaw/spec/AsciiSource
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2009-11-06 06:59:46 +0000
committermarha <marha@users.sourceforge.net>2009-11-06 06:59:46 +0000
commitace7902333b6f61aab5a6035dbcb222763bff186 (patch)
tree28445e829d5f04c8d79bda2514be37d5fb29738e /libXaw/spec/AsciiSource
parentc9179017c7e70703b7cac46c2df8b950506319e0 (diff)
downloadvcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.tar.gz
vcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.tar.bz2
vcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.zip
Added libXaw-1.0.7
Diffstat (limited to 'libXaw/spec/AsciiSource')
-rw-r--r--libXaw/spec/AsciiSource208
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.