aboutsummaryrefslogtreecommitdiff
path: root/libXaw/specs/AsciiSource.xml
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2011-03-25 10:41:05 +0000
committermarha <marha@users.sourceforge.net>2011-03-25 10:41:05 +0000
commit272e57235cd60a2e65ac8258d96a02eb3939b687 (patch)
tree789d74bd6ec1cc468f1f81aab97d4e4dfdb2d5c5 /libXaw/specs/AsciiSource.xml
parentb39f063f74bf0163eaf34db03134f226d18142ec (diff)
downloadvcxsrv-272e57235cd60a2e65ac8258d96a02eb3939b687.tar.gz
vcxsrv-272e57235cd60a2e65ac8258d96a02eb3939b687.tar.bz2
vcxsrv-272e57235cd60a2e65ac8258d96a02eb3939b687.zip
git update until 25 Mar 2011
xserver fontconfig glproto libXau libXft libXmu libfontenc libxcb mesa mkfontscale pixman randrproto xkeyboard-config xtrans xwininfo updated following packages: xproto-7.0.21 xineramaproto-1.2.1 libXt-1.1.1 libxkbfile-1.0.7 libXpm-3.5.9 libXfont-1.4.3 libXaw-1.0.9 bdftopcf-1.0.3 encodings-1.0.4 fixesproto-5.0 font-adobe-100dpi-1.0.3 font-adobe-75dpi-1.0.3 font-adobe-utopia-100dpi-1.0.4 font-adobe-utopia-75dpi-1.0.4 font-adobe-utopia-type1-1.0.4 font-alias-1.0.3 font-arabic-misc-1.0.3 font-bh-100dpi-1.0.3 font-bh-75dpi-1.0.3 font-bh-lucidatypewriter-100dpi-1.0.3 font-bh-lucidatypewriter-75dpi-1.0.3 font-bh-ttf-1.0.3 font-bh-type1-1.0.3 font-bitstream-100dpi-1.0.3 font-bitstream-75dpi-1.0.3 font-bitstream-speedo-1.0.2 font-bitstream-type1-1.0.3 font-cronyx-cyrillic-1.0.3 font-cursor-misc-1.0.3 font-daewoo-misc-1.0.3 font-dec-misc-1.0.3 font-ibm-type1-1.0.3 font-isas-misc-1.0.3 font-jis-misc-1.0.3 font-micro-misc-1.0.3 font-misc-cyrillic-1.0.3 font-misc-ethiopic-1.0.3 font-misc-meltho-1.0.3 font-misc-misc-1.1.2 font-mutt-misc-1.0.3 font-schumacher-misc-1.1.2 font-screen-cyrillic-1.0.4 font-sony-misc-1.0.3 font-sun-misc-1.0.3 font-util-1.2.0 font-winitzki-cyrillic-1.0.3 font-xfree86-type1-1.0.4
Diffstat (limited to 'libXaw/specs/AsciiSource.xml')
-rw-r--r--libXaw/specs/AsciiSource.xml368
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>