diff options
Diffstat (limited to 'libXaw/specs/AsciiSource.xml')
| -rw-r--r-- | libXaw/specs/AsciiSource.xml | 368 |
1 files changed, 368 insertions, 0 deletions
diff --git a/libXaw/specs/AsciiSource.xml b/libXaw/specs/AsciiSource.xml new file mode 100644 index 000000000..bd51f990a --- /dev/null +++ b/libXaw/specs/AsciiSource.xml @@ -0,0 +1,368 @@ +<sect1 id="Ascii_Source_Object_and_Multi_Source_Object"> +<title>Ascii Source Object and Multi Source Object</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- AsciiSrc Object --> +<!-- .XE --> +<!-- .IN "AsciiSrc object" "" "@DEF@" --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .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 +</literallayout> +</para> +<para> +<!-- .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 <function>international</function> 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. +</para> +<para> +<!-- .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 +</para> +<para> +<!-- .LP --> +The AsciiSrc can be either of two types: <function>XawAsciiFile</function> +or <function>XawAsciiString</function>. +</para> +<para> +<!-- .LP --> +AsciiSrc objects of type <function>XawAsciiFile</function> 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 <function>XawAsciiString</function>. 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 <function>XawAsciiSave</function> is made. When the +source is in this mode the <function>useStringInPlace</function> resource is ignored. +</para> +<para> +<!-- .LP --> +AsciiSrc objects of type <function>XawAsciiString</function> have the text buffer +implemented as a string. +\fIMultiSrc objects of type <function>XawAsciiString</function> have the text buffer +implemented as a wide character string.\fP +The string owner is responsible for allocating and managing storage for the +string. +</para> +<para> +<!-- .LP --> +In the default case for AsciiSrc objects of type <function>XawAsciiString</function>, +the resource <function>useStringInPlace</function> 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 <function>XtSetValues</function>, 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 <function>XtGetValues</function> 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 <function>XtGetValues</function> 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, <function>XawAsciiSourceFreeString</function>, allowing the +application programmer to direct the widget to free the copy. +</para> +<para> +<!-- .LP --> +When the resource <function>useStringInPlace</function> is true and the AsciiSrc object +is of type <function>XawAsciiString</function>, the application +is the string owner. The widget will take the value +of the string resource as its own text buffer, and the <function>length</function> +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 <function>XtGetValues</function> 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. +</para> +<sect2 id="asciisource_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating an AsciiSrc object instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "AsciiSrc object" "resources" --> +<informaltable> + <tgroup cols='5' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <colspec colname='c5'/> + <thead> + <row> + <entry>Name</entry> + <entry>Class</entry> + <entry>Type</entry> + <entry>Notes</entry> + <entry>Default Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>callback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>dataCompression</entry> + <entry>DataCompression</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>destroyCallback</entry> + <entry>Callback</entry> + <entry>Callback</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>editType</entry> + <entry>EditType</entry> + <entry>EditMode</entry> + <entry></entry> + <entry>XawtextRead</entry> + </row> + <row> + <entry>length</entry> + <entry>Length</entry> + <entry>Int</entry> + <entry>A</entry> + <entry>length of <function>string</function></entry> + </row> + <row> + <entry>pieceSize</entry> + <entry>PieceSize</entry> + <entry>Int</entry> + <entry></entry> + <entry>BUFSIZ</entry> + </row> + <row> + <entry>string</entry> + <entry>String</entry> + <entry>String</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>type</entry> + <entry>Type</entry> + <entry>AsciiType</entry> + <entry></entry> + <entry>XawAsciiString</entry> + </row> + <row> + <entry>useStringInPlace</entry> + <entry>UseStringInPlace</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</entry> + </row> + <row> + <entry>_</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .Oc Bold --> +<!-- .Dc --> +<!-- .Od Bold --> +<!-- .Oe --> +<!-- .Ol Bold --> +<!-- .Op Bold --> +<!-- .Os Bold --> +<!-- .Ot Bold --> +<!-- .Ou Bold --> +</para> +</sect2> +<sect2 id="asciisource_convenience_routines"> +<title>Convenience Routines</title> +<para> +<!-- .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. +</para> +<sect3 id="Conserving_Memory"> +<title>Conserving Memory</title> +<para> +<!-- .LP --> +When the AsciiSrc widget is not in <function>useStringInPlace</function> mode +space must be allocated whenever the file is saved, or the string is +requested with a call to <function>XtGetValues</function>. 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 <function>XawAsciiSourceFreeString</function>. +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawAsciiSourceFreeString</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the AsciiSrc object. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function will free the memory that contains the string pointer returned +by <function>XtGetValues</function>. This will normally happen automatically when +the next call to <function>XtGetValues</function> occurs, or when the widget is destroyed. +</para> +</sect3> +<sect3 id="Saving_Files"> +<title>Saving Files</title> +<para> +<!-- .LP --> +To save the changes made in the current text source into a file use +<function>XawAsciiSave</function>. +<funcsynopsis> +<funcprototype> + <funcdef>Boolean<function> XawAsciiSave</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the AsciiSrc object. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<function>XawAsciiSave</function> returns <function>True</function> if the save was successful. +It will update the file named in the <function>string</function> resource. +If the buffer has not been changed, no action will be taken. This function +only works on an AsciiSrc of type <function>XawAsciiFile</function>. +</para> +<para> +<!-- .LP --> +<!-- .sp 1 --> +To save the contents of the current text buffer into a named file use +<function>XawAsciiSaveAsFile</function>. +<funcsynopsis> +<funcprototype> + <funcdef>Boolean<function> XawAsciiSaveAsFile</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>String<parameter> name</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the AsciiSrc object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>name</emphasis> + </term> + <listitem> + <para> +The name of the file to save the current buffer into. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function returns <function>True</function> if the save was successful. +<function>XawAsciiSaveAsFile</function> will work with a buffer of either type +<function>XawAsciiString</function> or type <function>XawAsciiFile</function>. +</para> +</sect3> +<sect3 id="Seeing_if_the_Source_has_Changed"> +<title>Seeing if the Source has Changed</title> +<para> +<!-- .LP --> +To find out if the text buffer in an AsciiSrc object has changed +since the last time it was saved with <function>XawAsciiSave</function> or queried +<!-- .IN "XawAsciiSave" "" --> +use <function>XawAsciiSourceChanged</function>. +<funcsynopsis> +<funcprototype> + <funcdef>Boolean<function> XawAsciiSourceChanged</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the AsciiSrc object. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function will return <function>True</function> 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 <function>XtGetValues</function> or the +buffer is saved via <function>XawAsciiSave</function>. + +</para> +</sect3> +</sect2> +</sect1> |