| Application Header file | <Xraw/AsciiSrc.h> |
| Class Header file | <Xraw/AsciiSrcP.h> |
| Class | AsciiSrcObjectClass |
| Class Name | AsciiSrc |
| Superclass | TextSrc --> Object --> RectObj |
The AsciiSrc object is used by a text widget to read the text from a file or string in memory. It understands all Latin1 characters plus Tab and Carriage Return.
The AsciiSrc can be either of two types: XawAsciiFile or XawAsciiString.
AsciiSrc objects of type XawAsciiFile 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 XawAsciiString. 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 XawAsciiSave is made. When the source is in this mode the useStringInPlace resource is ignored.
AsciiSrc objects of type XawAsciiString have the text buffer implemented as a string. The string owner is responsible for allocating and managing storage for the string.
In the default case for AsciiSrc objects of type XawAsciiString, the resource useStringInPlace 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 XtSetValues, 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 XtGetValues 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 XtGetValues 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, XawAsciiSrcFreeString, allowing the application programmer to direct the widget to free the copy.
When the resource useStringInPlace is true and the AsciiSrc object is of type XawAsciiString, the application is the string owner. The widget will take the value of the string resource as its own text buffer, and the length 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 XtGetValues 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.
| Name | Class | Type | Notes | Default Value |
|---|---|---|---|---|
| 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 |
| callback | The callbacks registered on this resource will be called every time the text buffer changes, after the text has been updated. |
|---|---|
| destroyCallback | All functions on this list are called when this widget is destroyed. |
| dataCompression | The AsciiSrc uses an algorithm that may cause the text buffer to grow to about twice the size of the actual text over time, as the text is edited. On systems where CPU cycles are cheaper than memory, it is helpful to spend some extra time to compress this buffer back to its minimum size. If this resource is True, the AsciiSrc will compress its data to the minimum size required every time the text string is saved, or the value of the string is queried. |
| editType | This is the type of editing that will be allowed in this text widget. Legal values are XawtextRead, XawtextEdit, and XawtextAppend. A con verter is registered for this resource that will convert the following strings: read, edit, and append. |
| length | If the useStringInPlace resource is False this attribute has no effect. If that resource is True, however, then the length resource specifies the length of the buffer passed to the text widget in the string resource. |
| pieceSize | This is the size of the internal chunks into which the text buffer is broken down for memory management. The larger this value the less segmented your memory will be, but the slower your editing will be. The text wid gets will always allocate a chunk of memory this size to stuff the string into, so when using small strings, having this buffer large can waste memory. This resource has no effect if useStringInPlace is True. | string | If type is XawAsciiString then this string contains the buffer to be displayed in the widget. If type is XawAsciiFile then the string contains the name of the file to be displayed. This string is normally copied by the text widget into internal memory, but may be used in place by setting the useStringInPlace resource. As of X11R4 this is a settable resource. When the string resource is queried, using XtGetValues, and useStrin gInPlace is false, the value returned is valid until the next time the string resource is queried, or until the application writer calls XawAsci iSrcFreeString. If useStringInPlace is true, a pointer to the actual string is returned. See also section 5.6. |
| type | This resource may be either XawAsciiString or XawAsciiFile. The value of this resource determines whether the string resource contains the name of a file to be opened or a buffer to be displayed by the text widget. A converter has been registered for this resource and accepts the values string and file. |
| useStringInPlace | Setting this resource to True will disable the memory management pro vided by the Text widget, updating the string resource in place. Using the string in place can be much more efficient for text widgets that display static data, or where the programmer wishes to impose strict con straints on the contents of the string. When using the string in place be sure that: the length of the string is specified by setting the length resource, the type of the Text widget is XawAsciiString, and that the string exists for the lifetime of the text widget, or until it has been reset. |
void XawAsciiSourceFreeString(w)
Widget w;
| w | Specifies the AsciiSrc object. |
This function will free the memory that contains the string pointer returned by XtGetValues. This will normally happen automatically when the next call to XtGetValues occurs, or when the widget is destroyed.
To save the changes made in the current text source into a file use
XawAsciiSave.
Boolean XawAsciiSave(w)
Widget w;
| w | Specifies the AsciiSrc object. |
XawAsciiSave returns True if the save was successful.
It will update the file named in the string resource.
If the buffer has not been changed, no action will be taken. This function
only works on an AsciiSrc of type XawAsciiFile.
To save the contents of the current text buffer into a named file use
XawAsciiSaveAsFile.
Boolean XawAsciiSaveAsFile(w, name)
Widget w;
String name;
| w | Specifies the AsciiSrc object. |
| name | The name of the file to save the current buffer into. |
This function returns True if the save was successful.
XawAsciiSaveAsFile will work with a buffer of either type
XawAsciiString or type XawAsciiFile.
To find out if the text buffer in an AsciiSrc object has changed
since the last time it was saved with XawAsciiSave or queried
use XawAsciiSourceChanged.
Boolean XawAsciiSourceChanged(w)
Widget w;
| w | Specifies the AsciiSrc object. |
This function will return True 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 XtGetValues or the
buffer is saved via XawAsciiSave.