svn merge ^/branches/released .

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	&lt;X11/Xaw/AsciiSrc.h&gt; or &lt;X11/Xaw/MultiSrc.h&gt;
+<!-- .IN "AsciiSrc.h" "" -->
+Class Header file	&lt;X11/Xaw/AsciiSrcP.h&gt; or  &lt;X11/Xaw/MultiSrcP.h&gt;
+<!-- .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>