Athena Widget Set - C Language Interface - X Consortium ... - X.Org

Text WidgetsResourcesSuperclass TextSourceThe AsciiSrc or MultiSrc object is used by a text widget to read the text from afile or string in memory. Depending on its international resource, an AsciiTextwidget will create one or the other of these when the AsciiText itself is created. Bothtypes are nearly identical; the following discussion applies to both, with MultiSrcdifferences noted only as they occur.The AsciiSrc understands all Latin1 characters plus Tab and Carriage Return.\fIThe MultiSrc understands any set of character sets that the underlying Ximplementation's internationalization handles.\fPThe 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 aninternal buffer. This buffer may then be modified, provided the text widget is in thecorrect edit mode, just as if it were a source of type XawAsciiString. Unlike R3 andearlier 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 thesource is in this mode the useStringInPlace resource is ignored.AsciiSrc objects of type XawAsciiString have the text buffer implemented as astring. \fIMultiSrc objects of type XawAsciiString have the text buffer implementedas a wide character string.\fP The string owner is responsible for allocating andmanaging storage for the string.In the default case for AsciiSrc objects of type XawAsciiString, the resourceuseStringInPlace is false, and the widget owns the string. The initial value of thestring resource, and any update made by the application programmer to the stringresource with XtSetValues, is copied into memory private to the widget, and managedinternally by the widget. The application writer does not need to worry aboutrunning 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 necessarilythe case when the text buffer is used in place. The application writer mustuse XtGetValues to determine the contents of the text buffer, which will return acopy 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 updatedas the user types input into the text buffer. This copy is freed upon the nextcall to XtGetValues to retrieve the string resource; however, to conserve memory,there is a convenience routine, XawAsciiSourceFreeString, allowing the applicationprogrammer to direct the widget to free the copy.When the resource useStringInPlace is true and the AsciiSrc object is of typeXawAsciiString, the application is the string owner. The widget will take the valueof the string resource as its own text buffer, and the length resource indicates thebuffer 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 thecontents of the buffer-it will simply return the address of the application's implementationof the text buffer.When creating an AsciiSrc object instance, the following resources are retrievedfrom the argument list or from the resource database:94