diff options
Diffstat (limited to 'libXaw/spec/AsciiSource')
| -rw-r--r-- | libXaw/spec/AsciiSource | 208 |
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. |