diff options
Diffstat (limited to 'libXaw/spec/AsciiSource')
| -rw-r--r-- | libXaw/spec/AsciiSource | 208 |
1 files changed, 0 insertions, 208 deletions
diff --git a/libXaw/spec/AsciiSource b/libXaw/spec/AsciiSource deleted file mode 100644 index 19b976562..000000000 --- a/libXaw/spec/AsciiSource +++ /dev/null @@ -1,208 +0,0 @@ -.\" $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. |