aboutsummaryrefslogtreecommitdiff
path: root/libXaw/specs
diff options
context:
space:
mode:
Diffstat (limited to 'libXaw/specs')
-rw-r--r--libXaw/specs/AsciiSink.xml141
-rw-r--r--libXaw/specs/AsciiSource.xml368
-rw-r--r--libXaw/specs/AsciiText.xml450
-rw-r--r--libXaw/specs/Box.xml346
-rw-r--r--libXaw/specs/CH1.xml725
-rw-r--r--libXaw/specs/CH2.xml1891
-rw-r--r--libXaw/specs/CH3.xml123
-rw-r--r--libXaw/specs/CH4.xml102
-rw-r--r--libXaw/specs/CH5.xml397
-rw-r--r--libXaw/specs/CH6.xml117
-rw-r--r--libXaw/specs/CH7.xml167
-rw-r--r--libXaw/specs/Command.xml525
-rw-r--r--libXaw/specs/Dialog.xml692
-rw-r--r--libXaw/specs/Form.xml531
-rw-r--r--libXaw/specs/Grip.xml357
-rw-r--r--libXaw/specs/Label.xml345
-rw-r--r--libXaw/specs/List.xml872
-rw-r--r--libXaw/specs/Makefile.am106
-rw-r--r--libXaw/specs/MenuButton.xml567
-rw-r--r--libXaw/specs/Paned.xml1213
-rw-r--r--libXaw/specs/Panner.xml734
-rw-r--r--libXaw/specs/Porthole.xml306
-rw-r--r--libXaw/specs/Repeater.xml558
-rw-r--r--libXaw/specs/Scrollbar.xml884
-rw-r--r--libXaw/specs/Simple.xml252
-rw-r--r--libXaw/specs/SimpleMenu.xml790
-rw-r--r--libXaw/specs/Sme.xml207
-rw-r--r--libXaw/specs/SmeBSB.xml310
-rw-r--r--libXaw/specs/SmeLine.xml148
-rw-r--r--libXaw/specs/StripChart.xml435
-rw-r--r--libXaw/specs/TPage_Credits.xml90
-rw-r--r--libXaw/specs/Template.xml407
-rw-r--r--libXaw/specs/Template_private_header_file.xml87
-rw-r--r--libXaw/specs/Template_public_header_file.xml112
-rw-r--r--libXaw/specs/Template_widget_source_file.xml208
-rw-r--r--libXaw/specs/Text.xml326
-rw-r--r--libXaw/specs/TextActions.xml976
-rw-r--r--libXaw/specs/TextActions_default_translation_bindings.xml85
-rw-r--r--libXaw/specs/TextActions_text_widget_actions.xml891
-rw-r--r--libXaw/specs/TextCustom.xml123
-rw-r--r--libXaw/specs/TextFuncs.xml856
-rw-r--r--libXaw/specs/TextSink.xml915
-rw-r--r--libXaw/specs/TextSource.xml620
-rw-r--r--libXaw/specs/Toggle.xml773
-rw-r--r--libXaw/specs/Tree.xml404
-rw-r--r--libXaw/specs/Viewport.xml391
-rw-r--r--libXaw/specs/libXaw.xml88
47 files changed, 22011 insertions, 0 deletions
diff --git a/libXaw/specs/AsciiSink.xml b/libXaw/specs/AsciiSink.xml
new file mode 100644
index 000000000..06bc87dc4
--- /dev/null
+++ b/libXaw/specs/AsciiSink.xml
@@ -0,0 +1,141 @@
+<sect1 id="Ascii_Sink_Object_and_Multi_Sink_Object">
+<title>Ascii Sink Object and Multi Sink Object</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- AsciiSink Object -->
+<!-- .XE -->
+<!-- .IN "AsciiSink object" "" "@DEF@" -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+Application Header file &lt;X11/Xaw/AsciiSink.h&gt;
+<!-- .IN "AsciiSink.h" "" -->
+Class Header file &lt;X11/Xaw/AsciiSinkP.h&gt;
+<!-- .IN "AsciiSinkP.h" "" -->
+Class asciiSinkObjectClass
+<!-- .IN "asciiSinkObjectClass" "" -->
+Class Name AsciiSink
+<!-- .IN "AsciiSink object" "class name" -->
+Superclass TextSink
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The AsciiSink or MultiSink object is used by a text widget to render the text.
+Depending on its <function>international</function> resource, a
+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 MultiSink differences noted only as they occur.
+The AsciiSink
+will display all printing characters in an 8 bit font, along with handling Tab
+and Carriage Return. The name has been left as ``AsciiSink'' for compatibility.
+\fIThe MultiSink will display all printing characters in a font set, along with
+handling Tab and Carriage
+Return.\fP The source object also reports the text window metrics to the
+text widgets.
+</para>
+<sect2 id="asciisink_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating an AsciiSink object instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "AsciiSink 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>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>displayNonprinting</entry>
+ <entry>Output</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>echo</entry>
+ <entry>Output</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>font</entry>
+ <entry>Font</entry>
+ <entry>XFontStruct*</entry>
+ <entry></entry>
+ <entry>XtDefaultFont</entry>
+ </row>
+ <row>
+ <entry>fontSet</entry>
+ <entry>FontSet</entry>
+ <entry>XFontSet</entry>
+ <entry></entry>
+ <entry>XtDefaultFontSet</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Bg Bold -->
+This resource is retrieved by the AsciiSink instead of being copied
+from the Text widget.
+<!-- .Dc -->
+<!-- .Sd Bold -->
+<!-- .Sh Bold -->
+</para>
+<para>
+<!-- .IP <function>font</function> 1.5i -->
+The text font to use when displaying the <function>string</function>.
+(This resource is present in the AsciiSink, but not the MultiSink.)
+<!-- .IP <function>fontSet</function> 1.5i -->
+</para>
+<para>
+The text font set to use when displaying the <function>string</function>.
+(This resource is present in the MultiSink, but not the AsciiSink.)
+</para>
+</sect2>
+</sect1>
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>
diff --git a/libXaw/specs/AsciiText.xml b/libXaw/specs/AsciiText.xml
new file mode 100644
index 000000000..1a336d6c8
--- /dev/null
+++ b/libXaw/specs/AsciiText.xml
@@ -0,0 +1,450 @@
+<sect1 id="Ascii_Text_Widget">
+<title>Ascii Text Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- AsciiText Widget -->
+<!-- .XE -->
+<!-- .IN "AsciiText widget" "" "@DEF@" -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+Application Header file &lt;X11/Xaw/AsciiText.h&gt;
+<!-- .IN "AsciiText.h" "" -->
+ClassHeader file &lt;X11/Xaw/AsciiTextP.h&gt;
+<!-- .IN "AsciiTextP.h" "" -->
+Class asciiTextWidgetClass
+<!-- .IN "asciiTextWidgetClass" "" -->
+Class Name Text
+<!-- .IN "AsciiText widget" "class name" -->
+Superclass Text
+Sink Name textSink
+Source Name textSource
+</literallayout>
+<!-- .sp 1 -->
+</para>
+<para>
+<!-- .LP -->
+For the ease of internationalization, the AsciiText widget class name has not
+been changed, although it is actually able to support non-ASCII locales.
+The AsciiText widget is really a collection of smaller parts. It
+includes the Text widget itself, a ``Source'' (which supports memory management),
+and a ``Sink'' (which handles the display). There are currently two supported
+sources, the AsciiSrc and MultiSrc, and two supported sinks, the AsciiSink and
+<!-- .IN "AsciiSrc object" "" -->
+<!-- .IN "AsciiSink object" "" -->
+<!-- .IN "MultiSrc object" "" -->
+<!-- .IN "MultiSink object" "" -->
+MultiSink. Some of
+the resources listed below are not actually resources of the
+AsciiText, but belong to the associated source or sink. This is
+is noted in the explanation of each resource where it applies. When
+specifying these resources in a resource file it is necessary to use
+<emphasis remap='I'>*AsciiText*resource_name</emphasis> instead of
+<emphasis remap='I'>*AsciiText.resource_name</emphasis>, since they actually belong to the
+children of the AsciiText widget, and not the AsciiText widget itself.
+However, these resources may be set directly on the AsciiText widget at
+widget creation time, or via <function>XtSetValues</function>.
+</para>
+<sect2 id="asciitext_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating an AsciiText widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "AsciiText widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>autoFill</entry>
+ <entry>AutoFill</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>bottomMargin</entry>
+ <entry>Margin</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>callback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>XC_xterm</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</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>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>displayCaret</entry>
+ <entry>Output</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>displayNonprinting</entry>
+ <entry>Output</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>displayPosition</entry>
+ <entry>TextPosition</entry>
+ <entry>XawTextPosition</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>echo</entry>
+ <entry>Output</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>editType</entry>
+ <entry>EditType</entry>
+ <entry>XawTextEditType</entry>
+ <entry></entry>
+ <entry>XawtextRead</entry>
+ </row>
+ <row>
+ <entry>font</entry>
+ <entry>Font</entry>
+ <entry>XFontStruct*</entry>
+ <entry></entry>
+ <entry>XtDefaultFont</entry>
+ </row>
+ <row>
+ <entry>fontSet</entry>
+ <entry>FontSet</entry>
+ <entry>XFontSet</entry>
+ <entry></entry>
+ <entry>XtDefaultFontSet</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Font height + margins</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>insertPosition</entry>
+ <entry>TextPosition</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>leftMargin</entry>
+ <entry>Margin</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>2</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>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>pieceSize</entry>
+ <entry>PieceSize</entry>
+ <entry>XawTextPosition</entry>
+ <entry></entry>
+ <entry>BUFSIZ</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>resize</entry>
+ <entry>Resize</entry>
+ <entry>XawTextResizeMode</entry>
+ <entry></entry>
+ <entry>XawtextResizeNever</entry>
+ </row>
+ <row>
+ <entry>rightMargin</entry>
+ <entry>Margin</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>scrollHorizontal</entry>
+ <entry>Scroll</entry>
+ <entry>XawTextScrollMode</entry>
+ <entry></entry>
+ <entry>XawtextScrollNever</entry>
+ </row>
+ <row>
+ <entry>scrollVertical</entry>
+ <entry>Scroll</entry>
+ <entry>XawTextScrollMode</entry>
+ <entry></entry>
+ <entry>XawtextScrollNever</entry>
+ </row>
+ <row>
+ <entry>selectTypes</entry>
+ <entry>SelectTypes</entry>
+ <entry>XawTextSelectType*</entry>
+ <entry></entry>
+ <entry>See above</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>string</entry>
+ <entry>String</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>textSink</entry>
+ <entry>TextSink</entry>
+ <entry>Widget</entry>
+ <entry></entry>
+ <entry>An AsciiSink</entry>
+ </row>
+ <row>
+ <entry>textSource</entry>
+ <entry>TextSource</entry>
+ <entry>Widget</entry>
+ <entry></entry>
+ <entry>An AsciiSrc</entry>
+ </row>
+ <row>
+ <entry>topMargin</entry>
+ <entry>Margin</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>See above</entry>
+ </row>
+ <row>
+ <entry>type</entry>
+ <entry>Type</entry>
+ <entry>XawAsciiType</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>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>100</entry>
+ </row>
+ <row>
+ <entry>wrap</entry>
+ <entry>Wrap</entry>
+ <entry>WrapMode</entry>
+ <entry></entry>
+ <entry>XawtextWrapNever</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Box.xml b/libXaw/specs/Box.xml
new file mode 100644
index 000000000..fe93b42d3
--- /dev/null
+++ b/libXaw/specs/Box.xml
@@ -0,0 +1,346 @@
+<sect1 id="Box_Widget">
+<title>Box Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Box Widget -->
+<!-- .XE -->
+<!-- .IN "Box widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file &lt;X11/Xaw/Box.h&gt;
+<!-- .IN "Box.h" "" -->
+Class Header file &lt;X11/Xaw/BoxP.h&gt;
+<!-- .IN "BoxP.h" "" -->
+Class boxWidgetClass
+<!-- .IN "boxWidgetClass" "" -->
+Class Name Box
+<!-- .IN "Box widget" "class name" -->
+Superclass Composite
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The Box widget provides geometry management of arbitrary widgets in a
+box of a specified dimension. The children are rearranged when
+resizing events occur either on the Box or its children, or when
+children are managed or unmanaged. The Box widget always attempts to
+pack its children as tightly as possible within the geometry allowed by
+its parent.
+</para>
+<para>
+<!-- .LP -->
+Box widgets are commonly used to manage a related set of buttons and
+are often called ButtonBox widgets, but the children are not
+limited to buttons. The Box's children are arranged on a background that
+has its own specified dimensions and color.
+</para>
+<sect2 id="box_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Box widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "Box widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>children</entry>
+ <entry>ReadOnly</entry>
+ <entry>WidgetList</entry>
+ <entry>R</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>see <function>Layout Semantics</function></entry>
+ </row>
+ <row>
+ <entry>hSpace</entry>
+ <entry>HSpace</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>numChildren</entry>
+ <entry>ReadOnly</entry>
+ <entry>Cardinal</entry>
+ <entry>R</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>orientation</entry>
+ <entry>Orientation</entry>
+ <entry>Orientation</entry>
+ <entry></entry>
+ <entry>XtorientVertical</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>vSpace</entry>
+ <entry>VSpace</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>see <function>Layout Semantics</function></entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Ch -->
+<!-- .Cm -->
+<!-- .Dp -->
+<!-- .Dc -->
+<!-- .Hw -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>hSpace</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>vSpace</function>
+ </term>
+ <listitem>
+ <para>
+The amount of space, in pixels, to leave between the children. This
+resource specifies the amount of space left between the outermost
+children and the edge of the box.
+<!-- .Mm -->
+<!-- .Nc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>orientation</function>
+ </term>
+ <listitem>
+ <para>
+Specifies whether the preferred shape of the box (i.e. the result
+returned by the query_geometry class method) is tall and narrow
+<function>XtorientVertical</function> or short and wide <function>XtorientHorizontal</function>.
+<!-- .IN "XtorientVertical" "" -->
+<!-- .IN "XtorientHorizontal" "" -->
+<!-- .IN "conversions" "Orientation" -->
+When the Box is a child of a parent which enforces width constraints, it
+is usually better to specify <function>XtorientVertical</function> (the default).
+When the parent enforces height constraints, it is usually better to
+specify <function>XtorientHorizontal</function>.
+<!-- .Rs "horizontal \fPand\fB vertical" -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Layout_Semantics">
+<title>Layout Semantics</title>
+<!-- .IN "Box widget" "layout semantics" -->
+<para>
+<!-- .LP -->
+Each time a child is managed or unmanaged, the Box widget will attempt
+to reposition the remaining children to compact the box. Children are
+positioned in order left to right, top to bottom. The packing
+algorithm used depends on the <function>orientation</function> of the Box.
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>XtorientVertical</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "XtorientVertical" "" @DEF@ -->
+When the next child does not fit on the current row, a new row is
+started. If a child is wider than the width of the box, the box will
+request a larger width from its parent and will begin the layout
+process from the beginning if a new width is granted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>XtorientHorizontal</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "XtorientHorizontal" "" @DEF@ -->
+When the next child does not fit on the current row, the Box widens if
+possible (so as to keep children on a single row); otherwise a new row is
+started.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+After positioning all children, the Box widget attempts to shrink its
+own size to the minimum dimensions required for the layout.
+
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/CH1.xml b/libXaw/specs/CH1.xml
new file mode 100644
index 000000000..a4fb08c2d
--- /dev/null
+++ b/libXaw/specs/CH1.xml
@@ -0,0 +1,725 @@
+<chapter id="athena_widgets_and_the_intrinsics">
+<title>Athena Widgets and The Intrinsics</title>
+<para>
+The X Toolkit is made up of two distinct pieces, the Xt Intrinsics and a
+widget set. The Athena widget set is a sample implementation of a
+widget set built upon the Intrinsics. In the X Toolkit, a widget is the
+combination of an X window or subwindow and its associated input and
+output semantics.
+</para>
+<para>
+Because the Intrinsics provide the same basic functionality to all widget
+sets it may be possible to use widgets from the Athena widget set with
+other widget sets based upon the Intrinsics. Since widget sets may also
+implement private protocols, all functionality may not be available when
+mixing and matching widget sets. For information about the Intrinsics, see
+the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+</para>
+<para>
+The Athena widget set is a library package layered on top of the Intrinsics
+and Xlib that provides a set of user interface tools sufficient to build
+a wide variety of applications. This layer extends the basic
+abstractions provided by X and provides the next layer of functionality
+primarily by supplying a cohesive set of sample widgets. Although the
+Intrinsics are a Consortium standard, there is no standard widget set.
+</para>
+
+<para>
+To the extent possible, the Intrinsics are "policy-free". The application
+environment and widget set, not the Intrinsics, define, implement, and
+enforce:
+</para>
+
+<itemizedlist>
+ <listitem><para>Policy</para></listitem>
+ <listitem><para>Consistency</para></listitem>
+ <listitem><para>Style</para></listitem>
+</itemizedlist>
+
+<para>
+Each individual widget implementation defines its own policy. The X Toolkit
+design allows for, but does not necessarily encourage, the free mixing
+of radically differing widget implementations.
+</para>
+
+<sect1 id="Introduction_to_the_tk">
+<title>Introduction to the X Toolkit</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Introduction to the X Toolkit -->
+<!-- .XE -->
+<!-- .IN "introduction" "" "@DEF@" -->
+The X Toolkit provides tools that simplify the design of
+application user interfaces in the X Window System programming environment.
+It assists application programmers by providing a set of common
+underlying user-interface functions. It also lets widget programmers
+modify existing widgets, by subclassing, or add new widgets. By using
+the X Toolkit in their applications, programmers can present a similar
+user interface across applications to all workstation users.
+</para>
+<para>
+<!-- .LP -->
+The X Toolkit consists of:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A set of Intrinsics functions for building widgets
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An architectural model for constructing widgets
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A widget set for application programming
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+While the majority of the Intrinsics functions are intended
+for the widget programmer,
+a subset of the Intrinsics functions are to be used by application programmers
+(see <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>).
+The architectural model lets the widget programmer design new widgets
+by using the Intrinsics and by combining other widgets.
+The application interface layers built on top of the X Toolkit include a
+coordinated set of widgets and composition policies.
+Some of these widgets and policies are specific to a single
+application domain, and others are common to a variety of
+applications.
+</para>
+<para>
+<!-- .LP -->
+The remainder of this chapter discusses the X Toolkit and Athena widget set:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Terminology
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Model
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Conventions used in this manual
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Format of the Widget Reference Chapters
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Terminology">
+<title>Terminology</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Terminology -->
+<!-- .XE -->
+</para>
+<para>
+<!-- .LP -->
+In addition to the terms already defined for X programming (see
+<emphasis remap='I'>Xlib - C Language Interface</emphasis>),
+the following terms are specific to the Intrinsics and Athena widget set
+and used throughout this document.
+</para>
+<para>
+<!-- .LP -->
+<function>Application programmer</function>
+<!-- .IN "application programmer" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A programmer who uses the X Toolkit to produce an application user interface.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Child</function>
+<!-- .IN "child" "" "@DEF" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A widget that is contained within another "parent" widget.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Class</function>
+<!-- .IN "class" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The general group to which a specific object belongs.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Client</function>
+<!-- .IN "client" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A function that uses a widget in an application or for composing
+other widgets.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>FullName</function>
+<!-- .IN "FullName" "" "@DEF" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The name of a widget instance appended to the full name of its parent.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Instance</function>
+<!-- .IN "instance" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A specific widget object as opposed to a general widget class.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Method</function>
+<!-- .IN "method" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A function or procedure implemented by a widget class.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Name</function>
+<!-- .IN "name" "widget" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The name that is specific to an instance of a widget for a given client.
+This name is specified at creation time and cannot be modified.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Object</function>
+<!-- .IN "object" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A data abstraction consisting of private data and private and public
+functions that operate on the private data.
+Users of the abstraction can interact with the object only through calls
+to the object's public functions.
+In the X Toolkit,
+some of the object's public functions are called directly by the application,
+while others are called indirectly when the application calls the common
+Intrinsics functions.
+In general, if a function is common to all widgets,
+an application uses a single Intrinsics function to invoke the function for all
+types of widgets.
+If a function is unique to a single widget type,
+the widget exports the function.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Parent</function>
+<!-- .IN "parent" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A widget that contains at least one other ("child") widget.
+A parent widget is also known as a composite widget.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Resource</function>
+<!-- .IN "resource" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A named piece of data in a widget that can be set by a client,
+by an application, or by user defaults.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Superclass</function>
+<!-- .IN "superclass" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A larger class of which a specific class is a member.
+All members of a class are also members of the superclass.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>User</function>
+<!-- .IN "user" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A person interacting with a workstation.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Widget</function>
+<!-- .IN "widget" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+An object providing a user-interface abstraction (for example, a Scrollbar
+widget).
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Widget class</function>
+<!-- .IN "widget class" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The general group to which a specific widget belongs,
+otherwise known as the type of the widget.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Widget programmer</function>
+<!-- .IN "widget programmer" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A programmer who adds new widgets to the X Toolkit.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Underlying_Model">
+<title>Underlying Model</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Underlying Model -->
+<!-- .XE -->
+<!-- .IN "underlying model" "" "@DEF@" -->
+The underlying architectural model is based on the following premises:
+<!-- .KS -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Every user-interface widget is associated with an X window.
+The X window ID for a widget is readily available from the widget.
+Standard Xlib calls can be used by widgets for many of their input and
+output operations.
+<!-- .KE -->
+<!-- .KS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The data for every widget is private to the widget and its subclasses.
+That is, the data is neither directly accessible
+nor visible outside of the module implementing the widget.
+All program interaction with the widget is performed by a set of operations
+(methods) that are defined for the widget.
+<!-- .KE -->
+<!-- .KS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Widget semantics are clearly separated from widget layout geometry.
+Widgets are concerned with implementing specific user-interface
+semantics. They have little control over issues such as their size or
+placement relative to other widget peers. Mechanisms are provided for
+associating geometric managers with widgets and for widgets to make
+suggestions about their own geometry.
+<!-- .KE -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Conventions_Used_in_this_Manual">
+<title>Conventions Used in this Manual</title>
+<itemizedlist>
+ <listitem>
+ <para>
+<!-- .IN "conventions" "used in manual" "@DEF@" -->
+All resources available to the widgets are listed with each widget. Many
+of these are available to more than one widget class due to the object
+oriented nature of the Intrinsics. The new resources for each widget are
+listed in bold text, and the inherited resources are listed in plain text.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Global symbols are printed in <function>bold</function> and can be function names,
+symbols defined in include files, or structure names. Arguments are
+printed in <emphasis remap='I'>italics</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Each function is introduced by a general discussion that distinguishes
+it from other functions. The function declaration itself follows, and
+each argument is specifically explained. General discussion of the
+function, if any is required, follows the arguments. Where
+applicable, the last paragraph of the explanation lists the return values
+of the function.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To eliminate any ambiguity between those arguments that you pass and
+those that a function returns to you, the explanations for all
+arguments that you pass start with the word <emphasis remap='I'>specifies</emphasis> or, in the
+case of multiple arguments, the word <emphasis remap='I'>specify</emphasis>. The explanations
+for all arguments that are returned to you start with the word
+<emphasis remap='I'>returns</emphasis> or, in the case of multiple arguments, the word
+<emphasis remap='I'>return</emphasis>. The explanations for all arguments that you can pass
+and are returned start with the words <emphasis remap='I'>specifies and returns</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Any pointer to a structure that is used to return a value is
+designated as such by the <emphasis remap='I'>_return</emphasis> suffix as part of its name.
+All other pointers passed to these functions are used for reading
+only. A few arguments use pointers to structures that are used for
+both input and output and are indicated by using the <emphasis remap='I'>_in_out</emphasis>
+suffix.
+<!-- .IN "_return" "" "@DEF@" -->
+<!-- .IN "_in_out" "" "@DEF@" -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Format_of_the_Widget_Reference_Chapters">
+<title>Format of the Widget Reference Chapters</title>
+<para>
+<!-- .LP -->
+<!-- .IN "conventions" "chapter format" "@DEF@" -->
+<!-- .IN "chapter format" "" "@DEF@" -->
+The majority of this document is a reference guide for the Athena
+widget set. Chapters three through six give the programmer all
+information necessary to use the widgets. The layout of the chapters
+follows a specific pattern to allow the programmer to easily find the
+desired information.
+</para>
+<para>
+<!-- .LP -->
+The first few pages of every chapter give an overview of the widgets
+in that section. Widgets are grouped into chapters by functionality.
+<variablelist>
+ <varlistentry>
+ <term>
+ "Chapter <!-- xref -->
+ </term>
+ <listitem>
+ <para>
+Simple Widgets
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ "Chapter <!-- xref -->
+ </term>
+ <listitem>
+ <para>
+Menus
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ "Chapter <!-- xref -->
+ </term>
+ <listitem>
+ <para>
+Text Widgets
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ "Chapter <!-- xref -->
+ </term>
+ <listitem>
+ <para>
+Composite and Constraint Widget
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+Following the introduction will be a description of each widget in that
+chapter. When no functional grouping is obvious the widgets are listed
+in alphabetical order, such as in chapters three and six.
+</para>
+<para>
+<!-- .LP -->
+The first section of each widget's description is a table that
+contains general information about this widget class. Here is the
+table for the Box widget, and an explanation of all the entries.
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file &lt;X11/Xaw/Box.h&gt;
+Class Header file &lt;X11/Xaw/BoxP.h&gt;
+Class boxWidgetClass
+Class Name Box
+Superclass Composite
+<!-- .sp -->
+</literallayout>
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>Application Header File</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "application header file" "" "@DEF@" -->
+This file must be included when an application uses this widget.
+It usually contains the class definition, and some resource macros.
+This is often called the ``public'' header file.
+<!-- .IN "class header file" "" "@DEF@" -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Class Header File</function>
+ </term>
+ <listitem>
+ <para>
+This file will only be used by widget programmers. It will need to be
+included by any widget that subclasses this widget. This is often
+called the ``private'' header file.
+<!-- .IN "class" "" "@DEF@" -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Class</function>
+ </term>
+ <listitem>
+ <para>
+This is the widget class of this widget. This global symbol is passed to
+<function>XtCreateWidget</function> so that the Intrinsics will know which type of widget
+to create.
+<!-- .IN "class name" "" "@DEF@" -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Class Name</function>
+ </term>
+ <listitem>
+ <para>
+This is the resource name of this class. This name can be used in
+a resource file to match any widget of this class.
+<!-- .IN "superclass" "" -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Superclass</function>
+ </term>
+ <listitem>
+ <para>
+This is the superclass that this widget class is descended from. If
+you understand how the superclass works it will allow you to more quickly
+understand what this widget does, since much of its functionality may be
+inherited from its superclass.
+<!-- .sp -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+After this table follows a general description of the default behavior of
+this widget, as seen by the user. In many cases this functionality
+may be overridden by the application programmer, or by the user.
+</para>
+<para>
+<!-- .LP -->
+The next section is a table showing the
+name, class, type and default value of each resource that is available
+to this widget. There is also a column containing notes describing
+special restrictions placed upon individual resources.
+<!-- .IN "notes" "" "@DEF@" -->
+<!-- .IN "A, note" "" "@DEF@" -->
+<!-- .IN "D, note" "" "@DEF@" -->
+<!-- .IN "C, note" "" "@DEF@" -->
+<!-- .IN "R, note" "" "@DEF@" -->
+<variablelist>
+ <varlistentry>
+ <term>
+ A
+ </term>
+ <listitem>
+ <para>
+This resource may be automatically adjusted when another
+resource is changed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ C
+ </term>
+ <listitem>
+ <para>
+This resource is only settable at widget creation time, and may not
+be modified with <function>XtSetValues</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ D
+ </term>
+ <listitem>
+ <para>
+Do not modify this resource. While setting this resource will
+work, it can cause unexpected behavior. When this symbol appears
+there is another, preferred, interface provided by the X Toolkit.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ R
+ </term>
+ <listitem>
+ <para>
+This resource is READ-ONLY, and may not be modified.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+After the resource table is a detailed description of every resource
+available to that widget. Many of these are redundant, but printing
+them with each widget saves page flipping. The names of the resources
+that are inherited are printed in plain text, while the names of the
+resources that are new to this class are printed in <function>bold</function>.
+If you have already read the description of the superclass you need
+only pay attention to the resources printed in bold.
+</para>
+<para>
+<!-- .LP -->
+For each composite widget there is a section on layout semantics that
+follows the resource description. This section will describe the
+effect of constraint resources on the layout of the children, as well
+as a general description of where it prefers to place its children.
+</para>
+<para>
+<!-- .LP -->
+Descriptions of default translations and action routines come next, for
+widgets to which they apply. The last item in each widget's
+documentation is the description of all convenience routines provided by
+the widget.
+</para>
+</sect1>
+<sect1 id="Input_Focus">
+<title>Input Focus</title>
+<!-- .XS -->
+<!-- Input Focus -->
+<!-- .XE -->
+<!-- .IN "input focus" "" "@DEF@" -->
+<!-- .IN "input" "" "@DEF@" -->
+<!-- .IN "XtNinput" "" "@DEF@" -->
+<para>
+<!-- .LP -->
+The Intrinsics define a resource on all Shell widgets that interact with
+the window manager called <function>input</function>. This resource requests the
+assistance of window manager in acquiring the input focus. The
+resource defaults to <function>False</function> in the Intrinsics, but is redefined to
+default to <function>True</function> when an application is using the Athena widget
+set. An application programmer may override this default and set the
+resource back to <function>False</function> if the application does not need the window
+manager to give it the input focus. See the
+<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis> for details
+on the <emphasis remap='I'>input</emphasis> resource.
+
+</para>
+</sect1>
+</chapter>
diff --git a/libXaw/specs/CH2.xml b/libXaw/specs/CH2.xml
new file mode 100644
index 000000000..08f0ff569
--- /dev/null
+++ b/libXaw/specs/CH2.xml
@@ -0,0 +1,1891 @@
+<chapter><title>Using Widgets</title>
+<sect1 id="using_widgets">
+<title>Using Widgets</title>
+<para>
+Widgets serve as the primary tools for building a user interface or
+application environment. The Athena widget set consists of primitive
+widgets that contain no children (for example, a command button) and
+composite widgets which may contain one or more widget children (for
+example, a Box widget).
+</para>
+<para>
+The remaining chapters explain the widgets that are provided
+by the Athena widget set.
+These user-interface components serve as an interface for
+application programmers who do not want to implement their own widgets.
+In addition, they serve as a starting point
+for those widget programmers who, using the Intrinsics mechanisms,
+want to implement alternative application programming interfaces.
+</para>
+<para>
+This chapter is a brief introduction to widget programming. The
+examples provided use the Athena widgets, though most of the concepts
+will apply to all widget sets. Although there are several programming
+interfaces to the X Toolkit, only one is described here. A full
+description of the programming interface is provided in the document
+<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+</para>
+<sect2 id="Setting_the_Locale">
+<title>Setting the Locale</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Setting the Locale -->
+<!-- .XE -->
+If it is desirable that the application take advantage of
+internationalization (i18n), you must establish locale with
+<function>XtSetLanguageProc</function>
+before <function>XtDisplayInitialize</function> or <function>XtAppInitialize</function>
+is called. For full details, please refer to the document
+<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>, section 2.2. However, the following simplest-case
+call is sufficient in many or most applications.
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "internationalization" "" "" -->
+<!-- .IN "XtSetLanguageProc" "" "@DEF@" -->
+<!-- .IN "locale" "" "" -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2i -->
+<!-- .ta .5i 2i -->
+ XtSetLanguageProc(NULL, NULL, NULL);
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Most notably, this will affect the Standard C locale, determine which
+resource files will be loaded, and what fonts will be required of FontSet
+specifications. In many cases, the addition of this line is the only source change
+required to internationalize Xaw programs, and will not disturb the function
+of programs in the default "C" locale.
+</para>
+</sect2>
+<sect2 id="Initializing_the_Toolkit">
+<title>Initializing the Toolkit</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Initializing the Toolkit -->
+<!-- .XE -->
+You must call a toolkit initialization function before invoking any
+other toolkit routines (besides locale setting, above).
+<function>XtAppInitialize</function>
+opens the X server connection, parses the command line,
+and creates an initial widget that will serve as the root of
+a tree of widgets created by this application.
+<!-- .IN "initialization" "" "@DEF@" -->
+<!-- .IN "toolkit initialization" "" "@DEF@" -->
+<!-- .IN "XtAppInitialize" "" "@DEF@" -->
+<!-- .IN "fallback resources" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Widget<function> XtAppInitialize</function></funcdef>
+ <paramdef>XtAppContext<parameter> app_context_return</parameter></paramdef>
+ <paramdef>String<parameter> application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescRec<parameter> options</parameter></paramdef>
+ <paramdef>Cardinal<parameter> num_options</parameter></paramdef>
+ <paramdef>int<parameter> *argc_in_out</parameter></paramdef>
+ <paramdef>String<parameter> *argv_in_out</parameter></paramdef>
+ <paramdef>String<parameter> *fallback_resources</parameter></paramdef>
+ <paramdef>ArgList<parameter> args</parameter></paramdef>
+ <paramdef>Cardinal<parameter> num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_con_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application context of this application, if non-NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class name of this application,
+which is usually the generic name for all instances of this application.
+A useful convention is to form the class name by capitalizing the
+first letter of the application name. For example, the application named
+``xman'' has a class name of ``Xman''.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies how to parse the command line for any application-specific
+resources.
+The options argument is passed as a parameter to
+<function>XrmParseCommand</function> .
+For further information,
+see <emphasis remap='I'>Xlib - C Language Interface</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the options list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the number of command line parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fallback_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies resource values to be used if the site-wide application class
+defaults file cannot be opened, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to use when creating the Application shell.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments in <emphasis remap='I'>args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function will remove the command line arguments that the toolkit
+reads from <emphasis remap='I'>argc_in_out</emphasis>, and <emphasis remap='I'>argv_in_out</emphasis>. It will then
+attempt to open the display. If the display cannot be opened, an error
+message is issued and XtAppInitialize terminates the application. Once
+the display is opened, all resources are read from the locations
+specified by the Intrinsics. This function returns an ApplicationShell
+widget to be used as the root of the application's widget tree.
+</para>
+</sect2>
+<sect2 id="Creating_a_Widget">
+<title>Creating a Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Creating a Widget -->
+<!-- .XE -->
+<!-- .IN "widget creation" "" "@DEF@" -->
+<!-- .IN "creating widgets" "" "@DEF@" -->
+<!-- .IN "XtRealizeWidget" "" "" -->
+Creating a widget is a three-step process. First, the widget instance
+is allocated, and various instance-specific attributes are set by
+using <function>XtCreateWidget</function>. Second, the widget's parent is informed
+of the new child by using <function>XtManageChild</function>. Finally, X windows are
+created for the parent and all its children by using <function>XtRealizeWidget</function>
+and specifying the top-most widget. The first two steps can be
+combined by using <function>XtCreateManagedWidget</function>. In addition,
+<function>XtRealizeWidget</function> is automatically called when the child becomes
+managed if the parent is already realized.
+</para>
+<para>
+<!-- .LP -->
+To allocate, initialize, and manage a widget, use
+<function>XtCreateManagedWidget .</function>
+<!-- .IN "XtCreateManagedWidget" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Widget<function> XtCreateManagedWidget</function></funcdef>
+ <paramdef>String<parameter> name</parameter></paramdef>
+ <paramdef>WidgetClass<parameter> widget_class</parameter></paramdef>
+ <paramdef>Widget<parameter> parent</parameter></paramdef>
+ <paramdef>ArgList<parameter> args</parameter></paramdef>
+ <paramdef>Cardinal<parameter> num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the instance name for the created widget that is used for retrieving
+widget resources.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class pointer for the created widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parent widget ID.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list. The argument list is a variable-length
+list composed of name and value pairs that contain information
+pertaining to the specific widget instance being created. For further
+information, see Section 2.7.2. <!-- xref> -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments in the argument list.
+If the num_args is zero, the argument list is never referenced.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+When a widget instance is successfully created, the widget identifier
+is returned to the application. If an error is encountered, the
+<function>XtError</function>
+routine is invoked to inform the user of the error.
+<!-- .IN "XtError" "" "" -->
+</para>
+<para>
+<!-- .LP -->
+For further information, see <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+</para>
+</sect2>
+<sect2 id="Common_Resources">
+<title>Common Resources</title>
+<!-- .XS -->
+<!-- Common Resources -->
+<!-- .XE -->
+<!-- .IN "resource" "" -->
+<para>
+<!-- .LP -->
+Although a widget can have unique arguments that it understands, all
+widgets have common arguments that provide some regularity of operation.
+The common arguments allow arbitrary widgets to be managed by
+higher-level components without regard for the individual widget type.
+Widgets will ignore any argument that they do not understand.
+</para>
+<para>
+<!-- .LP -->
+The following resources are retrieved from the argument list
+or from the resource database by all of the Athena widgets:
+<informaltable>
+ <tgroup cols='4' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Type</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry><emphasis remap='I'>widget dependent</emphasis></entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry><emphasis remap='I'>widget dependent</emphasis></entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry><emphasis remap='I'>widget dependent</emphasis></entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .IN "XtDefaultForeground" "" "" -->
+<!-- .IN "XtDefaultBackground" "" "" -->
+</para>
+<para>
+<!-- .LP -->
+The following additional resources are retrieved from the argument list
+or from the resource database by many of the Athena widgets:
+<informaltable>
+ <tgroup cols='4' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Type</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>callback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry><emphasis remap='I'>widget dependent</emphasis></entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .IN "XtDefaultForeground" "" "" -->
+</para>
+</sect2>
+<sect2 id="Resource_Conversions">
+<title>Resource Conversions</title>
+<!-- .XS -->
+<!-- Resource Conversions -->
+<!-- .XE -->
+<!-- .IN "conversions" "" "@DEF@" -->
+<!-- .IN "string conversions" "" "@DEF@" -->
+<!-- .IN "type conversions" "" "@DEF@" -->
+<para>
+<!-- .LP -->
+Most resources in the Athena widget set have a converter registered that
+will translate the string in a resource file to the correct internal
+representation. While some are obvious (string to integer, for example),
+others need specific mention of the allowable values. Three general
+converters are described here:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Cursor
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Pixel
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Bitmap
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Many widgets have defined special converters that apply only to that
+widget. When these occur, the documentation section for that widget
+will describe the converter.
+</para>
+<sect3 id="Cursor_Conversion">
+<title>Cursor Conversion</title>
+<!-- .IN "conversions" "ColorCursor" "@DEF@" -->
+<!-- .IN "conversions" "Cursor" "@DEF@" -->
+<!-- .IN "cursor" "" "" -->
+<para>
+<!-- .LP -->
+The value for the <function>cursorName</function> resource is specified in the resource
+database as a string, and is of the following forms:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A standard X cursor name from <function>&lt; X11/cursorfont.h &gt;</function>.
+The names in <function>cursorfont.h</function> each describe a specific cursor. The
+resource names for these cursors are exactly like the names in this file
+except the <function>XC_</function> is not used. The cursor definition <function>XC_gumby</function>
+has a resource name of <function>gumby</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Glyphs, as in <emphasis remap='I'>FONT font-name glyph-index [[ font-name ] glyph-index ]</emphasis>.
+The first font and glyph specify the cursor source pixmap.
+The second font and glyph specify the cursor mask pixmap.
+The mask font defaults to the source font,
+and the mask glyph index defaults to the source glyph index.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A relative or absolute file name.
+If a relative or absolute file name is specified, that file is used to
+create the source pixmap. Then the string "Mask" is appended to
+locate the cursor mask pixmap. If the "Mask" file does not exist, the
+suffix "msk" is tried. If "msk" fails, no cursor mask will be used.
+If the filename does not start with '/' or './' the the bitmap
+file path is used (see section 2.4.3). <!-- xref -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect3>
+<sect3 id="Pixel_Conversion">
+<title>Pixel Conversion</title>
+<para>
+<!-- .LP -->
+<!-- .IN "conversions" "Pixel" "@DEF@" -->
+<!-- .IN "pixel" "" "" -->
+<!-- .IN "rgb.txt" "" "" -->
+<!-- .IN "XtDefaultForeground" "" "" -->
+<!-- .IN "XtDefaultBackground" "" "" -->
+The string-to-pixel converter takes any name that is acceptable to
+XParseColor (see <emphasis remap='I'>Xlib - C Language Interface</emphasis>). In addition this routine understands
+the special toolkit symbols `XtDefaultForeground' and
+`XtDefaultBackground', described in <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. In short the acceptable
+pixel names are:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Any color name for the rgb.txt file (typically in the directory
+/usr/lib/X11 on POSIX systems).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A numeric specification of the form #&lt;red&gt;&lt;green&gt;&lt;blue&gt; where these
+numeric values are hexadecimal digits (both upper and lower case).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The special strings `XtDefaultForeground' and `XtDefaultBackground'
+ </para>
+ </listitem>
+</itemizedlist>
+</sect3>
+<sect3 id="Bitmap_Conversion">
+<title>Bitmap Conversion</title>
+<!-- .IN "bitmap conversions" "" "@DEF@" -->
+<!-- .IN "conversions" "Bitmap" "@DEF@" -->
+<!-- .IN "bitmapFilePath" "" "@DEF@" -->
+<!-- .IN "BitmapFilePath" "" "@DEF@" -->
+<!-- .IN "/usr/include/X11/bitmaps" "" "" -->
+<para>
+<!-- .LP -->
+The string-to-bitmap converter attempts to locate a file containing
+bitmap data whose name is specified by the input string. If the file
+name is relative (i.e. does not begin with / or ./), the directories to
+be searched are specified in the <function>bitmapFilePath</function> resource--class
+<function>BitmapFilePath</function>. This resource specifies a colon (:) separated
+list of directories that will be searched for the named bitmap or
+cursor glyph (see section 2.4.1). The <function>bitmapFilePath</function> resource is
+global to the application, and may <function>not</function> be specified differently
+for each widget that wishes to convert a cursor to bitmap. In addition
+to the directories specified in the <function>bitmapFilePath</function> resource a
+default directory is searched. When using POSIX the default
+directory is
+<function>/usr/include/X11/bitmaps .</function>
+</para>
+</sect3>
+</sect2>
+<sect2 id="Realizing_a_Widget">
+<title>Realizing a Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Realizing a Widget -->
+<!-- .XE -->
+<!-- .IN "realizing widgets" "" "@DEF@" -->
+The
+<function>XtRealizeWidget</function>
+function performs two tasks:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Calculates the geometry constraints of all managed descendants
+of this widget. The actual calculation is put off until realize time
+for performance reasons.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Creates an X window for the widget and, if it is a composite widget,
+realizes each of its managed children.
+<!-- .IN "XtRealizeWidget" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XtRealizeWidget</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+For further information about this function,
+see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+</para>
+</sect2>
+<sect2 id="Processing_Events">
+<title>Processing Events</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Processing Events -->
+<!-- .XE -->
+<!-- .IN "events" "" "" -->
+<!-- .IN "XtAppInitialize" "" "" -->
+Now that the application has created, managed and realized its
+widgets, it is ready to process the events that will be delivered by the
+X Server to this client. A function call that will process the
+events is <function>XtAppMainLoop</function>.
+<!-- .IN "XtAppMainLoop" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XtAppMainLoop</function></funcdef>
+ <paramdef>XtAppContext<parameter> app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context of this application. The value is
+normally returned by <function>XtAppInitialize</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function never returns: it is an infinite loop that processes the
+X events. User input can be handled through callback procedures and
+application defined action routines. More details are provided in
+<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+</para>
+</sect2>
+<sect2 id="Standard_Widget_Manipulation_Functions">
+<title>Standard Widget Manipulation Functions</title>
+<!-- .XS -->
+<!-- Standard Widget Manipulation Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+After a widget has been created, a client can interact with that
+widget by calling one of the standard widget manipulation routines
+provided by the Intrinsics, or a widget class-specific manipulation routine.
+</para>
+<para>
+<!-- .LP -->
+The Intrinsics provide generic routines to give the application programmer
+access to a set of standard widget functions. The common widget
+routines let an application or composite widget perform the following
+operations on widgets without requiring explicit knowledge of the widget
+type.
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Control the mapping of widget windows
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Destroy a widget instance
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Obtain an argument value
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set an argument value
+ </para>
+ </listitem>
+</itemizedlist>
+<sect3 id="Mapping_Widgets">
+<title>Mapping Widgets</title>
+<para>
+<!-- .LP -->
+By default,
+widget windows are mapped (made viewable) automatically by
+<function>XtRealizeWidget</function>. This behavior can be disabled by using
+<function>XtSetMappedWhenManaged</function>, making the client responsible for calling
+<function>XtMapWidget</function> to make the widget viewable.
+<!-- .IN "XtSetMappedWhenManaged" "" "@DEF@" -->
+<!-- .IN "XtMapWidget" "" "" -->
+<!-- .IN "XtRealizeWidget" "" "" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XtSetMappedWhenManaged</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Boolean<parameter> map_when_managed</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>map_when_managed</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new value.
+If map_when_managed is <function>True</function>, the widget is mapped automatically
+when it is realized. If map_when_managed is <function>False</function>, the client
+must call
+<function>XtMapWidget</function>
+or make a second call to
+<function>XtSetMappedWhenManaged</function>
+to cause the child window to be mapped.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The definition for
+<function>XtMapWidget</function>
+is:
+<!-- .IN "XtMapWidget" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XtMapWidget</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+When you are creating several children in sequence for a previously
+realized common parent it is generally more efficient to construct a
+list of children as they are created (using <function>XtCreateWidget</function>) and
+then use <function>XtManageChildren</function> to request that their parent managed
+them all at once. By managing a list of children at one time, the
+parent can avoid wasteful duplication of geometry processing and the
+associated ``screen flash''.
+<!-- .IN "XtManageChildren" "" "@DEF@" -->
+<!-- .IN "XtCreateWidget" "" "" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XtManageChildren</function></funcdef>
+ <paramdef>WidgetList<parameter> children</parameter></paramdef>
+ <paramdef>Cardinal<parameter> num_children</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of children to add.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of children to add.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+If the parent is already visible on the screen, it is especially
+important to batch updates so that the minimum amount of visible window
+reconfiguration is performed.
+</para>
+<para>
+<!-- .LP -->
+For further information about these functions,
+see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+</para>
+</sect3>
+<sect3 id="Destroying_Widgets">
+<title>Destroying Widgets</title>
+<para>
+<!-- .LP -->
+To destroy a widget instance of any type, use
+<function>XtDestroyWidget</function>
+<!-- .IN "XtDestroyWidget" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XtDestroyWidget</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<function>XtDestroyWidget</function>
+destroys the widget and recursively destroys any children that it may have,
+including the windows created by its children.
+After calling
+<function>XtDestroyWidget ,</function>
+no further references should be made to the widget or any children
+that the destroyed widget may have had.
+</para>
+</sect3>
+<sect3 id="Retrieving_Widget_Resource_Values">
+<title>Retrieving Widget Resource Values</title>
+<para>
+<!-- .LP -->
+To retrieve the current value of a resource attribute associated
+with a widget instance, use
+<function>XtGetValues .</function>
+<!-- .IN "XtGetValues" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XtGetValues</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>ArgList<parameter> args</parameter></paramdef>
+ <paramdef>Cardinal<parameter> num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a variable-length argument list of name and <function>address</function>
+pairs that contain the resource name and the address into which the
+resource value is stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+The arguments and values passed in the argument list are dependent on
+the widget. Note that the caller is responsible for providing space
+into which the returned resource value is copied; the <function>ArgList</function>
+contains a pointer to this storage (e.g. x and y must be
+allocated as Position). For further information, see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+</para>
+</sect3>
+<sect3 id="Modifying_Widget_Resource_Values">
+<title>Modifying Widget Resource Values</title>
+<para>
+<!-- .LP -->
+To modify the current value of a resource attribute associated with a
+widget instance, use
+<function>XtSetValues .</function>
+<!-- .IN "XtSetValues" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XtSetValues</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>ArgList<parameter> args</parameter></paramdef>
+ <paramdef>Cardinal<parameter> num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of name and <function>value</function> pairs that contain the
+arguments to be modified and their new values.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+The arguments and values that are passed will depend on the widget
+being modified. Some widgets may not allow certain resources to be
+modified after the widget instance has been created or realized.
+No notification is given if any part of a <function>XtSetValues</function> request is
+ignored.
+</para>
+<para>
+<!-- .LP -->
+For further information about these functions, see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+<!-- .IN "XtGetValues" "" "" -->
+<!-- .IN "XtSetValues" "" "" -->
+<!-- .NT -->
+The argument list entry for
+<function>XtGetValues</function>
+specifies the address to which the caller wants the value copied. The
+argument list entry for
+<function>XtSetValues ,</function>
+however, contains the new value itself, if the size of value is less than
+sizeof(XtArgVal) (architecture dependent, but at least sizeof(long));
+otherwise, it is a pointer to the value. String resources are always
+passed as pointers, regardless of the length of the string.
+<!-- .NE -->
+</para>
+</sect3>
+</sect2>
+<sect2 id="Using_the_Client_Callback_Interface">
+<title>Using the Client Callback Interface</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Using the Client Callback Interface -->
+<!-- .XE -->
+<!-- .IN "callbacks" "" "" -->
+Widgets can communicate changes in their state to their clients
+by means of a callback facility.
+The format for a client's callback handler is:
+<!-- .IN "CallbackProc" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> CallbackProc</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XtPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies widget for which the callback is registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies arbitrary client-supplied data that the widget should pass
+back to the client when the widget executes the client's callback
+procedure. This is a way for the client registering the callback to
+also register client-specific data: a pointer to additional information
+about the widget, a reason for invoking the callback, and so on. If no
+additional information is necessary, NULL may be passed as this argument.
+This field is also frequently known as the <emphasis remap='I'>closure</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any callback-specific data the widget wants to pass to the client.
+For example, when Scrollbar executes its <function>jumpProc</function> callback list,
+it passes the current position of the thumb in <emphasis remap='I'>call_data</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+Callbacks can be registered either by creating an argument containing
+the callback list described below or by using the special convenience
+routines <function>XtAddCallback</function> and <function>XtAddCallbacks</function>. When the widget
+is created, a pointer to a list of callback procedure and data pairs can
+be passed in the argument list to
+<function>XtCreateWidget .</function>
+The list is of type
+<function>XtCallbackList :</function>
+<!-- .IN "XtCallbackProc" -->
+<!-- .IN "XtAddCallbacks" -->
+<!-- .IN "XtAddCallback" -->
+<!-- .IN "XtCallbackList" "" "@DEF@" -->
+<!-- .IN "XtCallbackRec" "" "@DEF@" -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ XtCallbackProc callback;
+ XtPointer closure;
+} XtCallbackRec, *XtCallbackList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The callback list must be allocated and initialized before calling
+<function>XtCreateWidget .</function>
+<!-- .IN "XtCreateWidget" -->
+The end of the list is identified by an entry containing NULL in
+callback and closure. Once the widget is created, the client can change
+or de-allocate this list; the widget itself makes no further reference
+to it. The closure field contains the client_data passed to the
+callback when the callback list is executed.
+</para>
+<para>
+<!-- .LP -->
+The second method for registering callbacks is to use
+<function>XtAddCallback</function>
+after the widget has been created.
+<!-- .IN "XtAddCallback" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XtAddCallback</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>String<parameter> callback_name</parameter></paramdef>
+ <paramdef>XtCallbackProc<parameter> callback</parameter></paramdef>
+ <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget to add the callback to.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback list within the widget to append to.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback procedure to add.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the data to be passed to the callback when it is invoked.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<function>XtAddCallback</function>
+adds the specified callback to the list for the named widget.
+</para>
+<para>
+<!-- .LP -->
+All widgets provide a callback list named
+<function>destroyCallback</function>
+<!-- .IN "destroyCallback" "" "@DEF@" -->
+where clients can register procedures that are to be executed when the
+widget is destroyed. The destroy callbacks are executed when the widget
+or an ancestor is destroyed. The <emphasis remap='I'>call_data</emphasis> argument is unused for
+destroy callbacks.
+</para>
+</sect2>
+<sect2 id="Programming_Considerations">
+<title>Programming Considerations</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Programming Considerations -->
+<!-- .XE -->
+This section provides some guidelines on how to set up an application
+program that uses the X Toolkit.
+</para>
+<sect3 id="Writing_Applications">
+<title>Writing Applications</title>
+<para>
+<!-- .LP -->
+<!-- .IN "writing applications" -->
+<!-- .IN "StringDefs.h" -->
+<!-- .IN "Intrinsic.h" -->
+When writing an application that uses the X Toolkit,
+you should make sure that your application performs the following:
+</para>
+<orderedlist>
+ <listitem>
+ <para>
+Include
+<function>&lt; X11/Intrinsic.h &gt;</function>
+in your application programs.
+This header file automatically includes
+<function>&lt; X11/Xlib.h &gt;,</function>
+so all Xlib functions also are defined.
+It may also be necessary to include <function>&lt; X11/StringDefs.h &gt;</function> when setting
+up argument lists, as many of the XtN<emphasis remap='I'>something</emphasis> definitions are
+only defined in this file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Include the widget-specific header files for each widget type
+that you need to use.
+For example,
+<function>&lt; X11/Xaw/Label.h &gt;</function>
+and
+<function>&lt; X11/Xaw/Command.h &gt;.</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Call the
+<function>XtAppInitialize</function>
+<!-- .IN "XtAppInitialize" -->
+function before invoking any other toolkit or Xlib functions.
+For further information,
+see Section 2.1 and the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To pass attributes to the widget creation routines that will override
+any site or user customizations, set up argument lists. In this
+document, a list of valid argument names is provided in the discussion
+of each widget. The names each have a global symbol defined that begins
+with <function>XtN</function> to help catch spelling errors. For example,
+<function>XtNlabel</function> is defined for the <function>label</function> resource of many widgets.
+<!-- .IN "XtN" "" "@DEF@" -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+For further information, see Section 2.9.2.2. <!-- xref -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the argument list is set up, create the widget with the
+<function>XtCreateManagedWidget</function> function. For further information, see
+Section 2.2 and the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+<!-- .IN "XtCreateManagedWidget" -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the widget has any callback routines, set by the
+<function>XtNcallback</function>
+argument or the
+<function>XtAddCallback</function>
+function, declare these routines within the application.
+<!-- .IN "XtAddCallback" -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+After creating the initial widget hierarchy, windows must be created
+for each widget by calling
+<function>XtRealizeWidget</function>
+on the top level widget.
+<!-- .IN "XtRealizeWidget" -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Most applications now sit in a loop processing events using
+<function>XtAppMainLoop ,</function>
+for example:
+<!-- .IN "XtAppMainLoop" -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literallayout class="monospaced">
+XtCreateManagedWidget(<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>class</emphasis>, <emphasis remap='I'>parent</emphasis>, <emphasis remap='I'>args</emphasis>, <emphasis remap='I'>num_args</emphasis>);
+XtRealizeWidget(<emphasis remap='I'>shell</emphasis>);
+XtAppMainLoop(<emphasis remap='I'>app_context</emphasis>);
+</literallayout>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+For information about this function, see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Link your application with
+<function>libXaw</function>
+(the Athena widgets),
+<function>libXmu</function>
+(miscellaneous utilities),
+<function>libXt</function>
+(the X Toolkit Intrinsics),
+<function>libSM</function>
+(Session Management),
+<function>libICE</function>
+(Inter-Client Exchange),
+<function>libXext</function>
+(the extension library needed for the shape extension code which allows
+rounded Command buttons), and
+<function>libX11</function>
+(the core X library).
+The following provides a sample command line:
+<!-- .IN "libXaw" -->
+<!-- .IN "libXmu" -->
+<!-- .IN "libXt" -->
+<!-- .IN "libSM" -->
+<!-- .IN "libICE" -->
+<!-- .IN "libXext" -->
+<!-- .IN "libX11" -->
+<!-- .IN "linking applications" -->
+<!-- .IN "compiling applications" -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literallayout class="monospaced">
+cc -o <emphasis remap='I'>application</emphasis> <emphasis remap='I'>application</emphasis>.c \-lXaw \-lXmu \-lXt \
+\-lSM \-lICE \-lXext \-lX11
+</literallayout>
+ </para>
+ </listitem>
+</orderedlist>
+</sect3>
+<sect3 id="Changing_Resource_Values">
+<title>Changing Resource Values</title>
+<!-- .IN "resource" "" -->
+<para>
+<!-- .LP -->
+The Intrinsics support two methods of changing the default resource
+values; the resource manager, and an argument list passed into
+XtCreateWidget. While resources values will get updated no matter
+which method you use, the two methods provide slightly different
+functionality.
+<variablelist>
+ <varlistentry>
+ <term>Resource Manager</term>
+ <listitem>
+ <para>
+This method picks up resource definitions described in <emphasis remap='I'>Xlib - C Language Interface</emphasis> from
+many different locations at run time. The locations most important to
+the application programmer are the <emphasis remap='I'>fallback resources</emphasis> and the
+<emphasis remap='I'>app-defaults</emphasis> file, (see <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis> for the complete list).
+Since these resource are loaded at run time, they can be overridden by
+the user, allowing an application to be customized to fit the
+particular needs of each individual user. These values can also be
+modified without the need to rebuild the application, allowing rapid
+prototyping of user interfaces. Application programmers should use
+resources in preference to hard-coded values whenever possible.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Argument Lists</term>
+ <listitem>
+ <para>
+The values passed into the widget at creation time via an argument list
+cannot be modified by the user, and allow no opportunity for
+customization. It is used to set resources that cannot be specified as
+strings (e.g. callback lists) or resources that should not be
+overridden (e.g. window depth) by the user.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<sect4 id="Specifying_Resources">
+<title>Specifying Resources</title>
+<para>
+<!-- .LP -->
+It is important for all X Toolkit application programmers to
+understand how to use the X Resource Manager to specify resources for
+widgets in an X application. This section will describe the most common
+methods used to specify these resources, and how to use the X Resource
+manager.
+<!-- .IN "xrdb" -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>Xrdb</function>
+ </term>
+ <listitem>
+ <para>
+The <function>xrdb</function> utility may be used to load a file containing
+resources into the X server. Once the resources are loaded, the
+resources will affect any new applications started on the display that
+they were loaded onto.
+<!-- .IN "application defaults" -->
+<!-- .IN "app-defaults" -->
+<!-- .IN "/usr/lib/X11/app-defaults" -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Application Defaults</term>
+ <listitem>
+ <para>
+The application defaults (app-defaults) file (normally in
+/usr/lib/X11/app-defaults/<emphasis remap='I'>classname</emphasis>) for an application is loaded
+whenever the application is started.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+The resource specification has two colon-separated parts, a name, and
+a value. The <emphasis remap='I'>value</emphasis> is a string whose format is dependent on the
+resource specified by <emphasis remap='I'>name</emphasis>. <emphasis remap='I'>Name</emphasis> is constructed by
+appending a resource name to a full widget name.
+</para>
+<para>
+<!-- .LP -->
+The full widget name is a list of the name of every ancestor of the
+desired widget separated by periods (.). Each widget also has a class
+associated with it. A class is a type of widget (e.g. Label or
+Scrollbar or Box). Notice that class names, by convention, begin with
+capital letters and instance names begin with lower case letters. The
+class of any widget may be used in place of its name in a resource
+specification. Here are a few examples:
+<variablelist>
+ <varlistentry>
+ <term>
+ xman.form.button1
+ </term>
+ <listitem>
+ <para>
+This is a fully specified resource name, and will affect only widgets
+called button1 that are children of widgets called form that are
+children of
+applications named xman. (Note that while typically two widgets that
+are siblings will have different names, it is not prohibited.)
+
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ Xman.Form.Command
+ </term>
+ <listitem>
+ <para>
+This will match any Command widget that is a child of a Form widget
+that is itself a child of an application of class <emphasis remap='I'>Xman</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ Xman.Form.button1
+ </term>
+ <listitem>
+ <para>
+This is a mixed resource name with both widget names and classes specified.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This syntax allows an application programmer to specify any widget
+in the widget tree. To match more than one widget (for example a user
+may want to make all Command buttons blue), use an asterisk (*)
+instead of a period. When an asterisk is used, any number of widgets
+(including zero) may exist between the two widget names. For example:
+<variablelist>
+ <varlistentry>
+ <term>
+ Xman*Command
+ </term>
+ <listitem>
+ <para>
+This matches all Command widgets in the Xman application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ Foo*button1
+ </term>
+ <listitem>
+ <para>
+This matches any widget in the Foo application that is named <emphasis remap='I'>button1</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+The root of all application widget trees is the widget returned by
+<function>XtAppInitialize</function>. Even though this is actually an
+ApplicationShell widget, the toolkit replaces its widget class with the
+class name of the application. The name of this widget is either
+the name used to invoke the application (<function>argv[0]</function>) or the name of
+the application specified using the standard <emphasis remap='I'>-name</emphasis> command line
+option supported by the Intrinsics.
+</para>
+<para>
+<!-- .LP -->
+The last step in constructing the resource name is to append the name of
+the resource with either a period or asterisk to the full or partial
+widget name already constructed.
+<variablelist>
+ <varlistentry>
+ <term>
+ *foreground:Blue
+ </term>
+ <listitem>
+ <para>
+Specifies that all widgets in all applications will have a foreground
+color of blue.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ Xman*borderWidth:10
+ </term>
+ <listitem>
+ <para>
+Specifies that all widgets in an application whose class is Xman will
+have a border width of 10 (pixels).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ xman.form.button1.label:Testing
+ </term>
+ <listitem>
+ <para>
+Specifies that a particular widget in the xman application will have a
+label named <emphasis remap='I'>Testing</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+An exclamation point (!) in the first column of a line indicates
+that the rest of the line should be treated as a comment.
+</para>
+<para>
+<!-- .LP -->
+<function>Final Words</function>
+</para>
+<para>
+<!-- .LP -->
+The Resource manager is a powerful tool that can be used very
+effectively to customize X Toolkit applications at run time by either the
+application programmer or the user. Some final points to note:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+An application programmer may add new resources to their
+application. These resources are associated with the global
+application, and not any particular widget. The X Toolkit function used for
+adding the application resources is <function>XtGetApplicationResources</function>.
+<!-- .IN "XtGetApplicationResources" -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Be careful when creating resource files. Since widgets will
+ignore resources that they do not understand, any spelling
+errors will cause a resource to have no effect.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Only one resource line will match any given resource. There is a set
+of precedence rules, which take the following general stance.
+<!-- .ta 10n -->
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+More specific overrides less specific, thus period always overrides asterisk.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Names on the left are more specific and override names on the right.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When resource specifications are exactly the same, user defaults
+will override program defaults.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+For a complete explanation of the rules of precedence, and
+other specific topics see <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis> and <emphasis remap='I'>Xlib - C Language Interface</emphasis>.
+</para>
+</sect4>
+<sect4 id="Creating_Argument_Lists">
+<title>Creating Argument Lists</title>
+<!-- .IN "argument lists" "" "@DEF@" -->
+<para>
+<!-- .LP -->
+To set up an argument list for the inline specification of widget attributes,
+you may use any of the four approaches discussed in this section.
+Each resource name has a global symbol associated with it. This
+global symbol has the form XtN<emphasis remap='I'>resource name</emphasis>. For example, the
+symbol for ``foreground'' is <function>XtNforeground</function>. For further information,
+see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+</para>
+<para>
+<!-- .LP -->
+Argument are specified by using the following structure:
+<!-- .IN "ArgList" "" "@DEF@" -->
+<!-- .IN "Arg" "" "@DEF@" -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i -->
+<!-- .ta .5i 1.5i -->
+typedef struct {
+ String name;
+ XtArgVal value;
+} Arg, *ArgList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The first approach is to statically initialize the argument list.
+For example:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+static Arg arglist[] = {
+ {XtNwidth, (XtArgVal) 400},
+ {XtNheight, (XtArgVal) 300},
+};
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+This approach is convenient for lists that do not need to be computed
+at runtime and makes adding or deleting new elements easy.
+The
+<!-- .IN "XtNumber" -->
+<function>XtNumber</function>
+macro is used to compute the number of elements in the argument list,
+preventing simple programming errors:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+XtCreateWidget(<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>class</emphasis>, <emphasis remap='I'>parent</emphasis>, <emphasis remap='I'>arglist</emphasis>, XtNumber(<emphasis remap='I'>arglist</emphasis>));
+</literallayout>
+<!-- .IN "XtSetArg" "" "@DEF@" -->
+</para>
+<para>
+<!-- .LP -->
+The second approach is to use the
+<function>XtSetArg</function>
+macro.
+For example:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+Arg arglist[10];
+XtSetArg(arglist[1], XtNwidth, 400);
+XtSetArg(arglist[2], XtNheight, 300);
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+To make it easier to insert and delete entries,
+you also can use a variable index:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+Arg arglist[10];
+Cardinal i=0;
+XtSetArg(arglist[i], XtNwidth, 400); i++;
+XtSetArg(arglist[i], XtNheight, 300); i++;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The i variable can then be used as the argument list count in the widget
+create function.
+In this example,
+<!-- .IN "XtNumber" -->
+<function>XtNumber</function>
+would return 10, not 2, and therefore is not useful.
+<!-- .NT -->
+You should not use auto-increment or auto-decrement
+within the first argument to
+<function>XtSetArg .</function>
+As it is currently implemented,
+<function>XtSetArg</function>
+is a macro that dereferences the first argument twice.
+<!-- .NE -->
+</para>
+<para>
+<!-- .LP -->
+The third approach is to individually set the elements of the
+argument list array:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+Arg arglist[10];
+arglist[0].name = XtNwidth;
+arglist[0].value = (XtArgVal) 400;
+arglist[1].name = XtNheight;
+arglist[1].value = (XtArgVal) 300;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Note that in this example, as in the previous example,
+<!-- .IN "XtNumber" -->
+<function>XtNumber</function>
+would return 10, not 2, and therefore would not be useful.
+</para>
+<para>
+<!-- .LP -->
+The fourth approach is to use a mixture of the first and third approaches:
+you can statically define the argument list but modify some entries at runtime.
+For example:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+static Arg arglist[] = {
+ {XtNwidth, (XtArgVal) 400},
+ {XtNheight, (XtArgVal) NULL},
+};
+arglist[1].value = (XtArgVal) 300;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+In this example,
+<!-- .IN "XtNumber" -->
+<function>XtNumber</function>
+can be used, as in the first approach, for easier code maintenance.
+</para>
+</sect4>
+</sect3>
+</sect2>
+<sect2 id="Example_Programs">
+<title>Example Programs</title>
+<!-- .XS -->
+<!-- Example Programs -->
+<!-- .XE -->
+<!-- .IN "examples" -->
+<para>
+<!-- .LP -->
+The best way to understand how to use any programming library is by
+trying some simple examples. A collection of example programs that
+introduces each of the widgets in that Athena widget set, as well as many
+important toolkit programming concepts, is available in the X11R6
+release as distributed by the X Consortium. It can be found in the
+distribution directory <function>contrib/examples/mit/Xaw</function>, but see your
+site administrator for the exact location of these files on your system.
+See the README file from that directory for a guide to the examples.
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/libXaw/specs/CH3.xml b/libXaw/specs/CH3.xml
new file mode 100644
index 000000000..8fdefcc7b
--- /dev/null
+++ b/libXaw/specs/CH3.xml
@@ -0,0 +1,123 @@
+<chapter id="simple_widgets">
+<title>Simple Widgets</title>
+
+<!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH3.intro.xml"/> -->
+<para>
+Each of these widgets performs a specific user interface function. They
+are <emphasis remap='I'>simple</emphasis> because they cannot have widget children\(emthey may only
+be used as leaves of the widget tree. These widgets display information or
+take user input.
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><function>Command</function></term>
+ <listitem>
+ <para>
+A push button that, when selected, may cause a specific action
+to take place. This widget can display a multi-line string or a bitmap or pixmap image.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>Grip</function></term>
+ <listitem>
+ <para>
+A rectangle that, when selected, will cause an action to take place.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>Label</function></term>
+ <listitem>
+ <para>
+A rectangle that can display a multi-line string or a bitmap or pixmap image.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><function>List</function></term>
+ <listitem>
+ <para>
+A list of text strings presented in row column format that may be
+individually selected. When an element is selected an action may take
+place.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><function>Panner</function></term>
+ <listitem>
+ <para>
+A rectangular area containing a <emphasis remap='I'>slider</emphasis> that may be moved in two
+dimensions. Notification of movement may be continuous or discrete.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><function>Repeater</function></term>
+ <listitem>
+ <para>
+A push button that triggers an action at an increasing rate when selected.
+This widget can display a multi-line string or a bitmap or pixmap image.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><function>Scrollbar</function></term>
+ <listitem>
+ <para>
+A rectangular area containing a <emphasis remap='I'>thumb</emphasis> that when slid along one
+dimension may cause a specific action to take place. The Scrollbar may
+be oriented horizontally or vertically.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><function>Simple</function></term>
+ <listitem>
+ <para>
+The base class for most of the simple widgets. Provides a rectangular
+area with a settable mouse cursor and special border.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><function>StripChart</function></term>
+ <listitem>
+ <para>
+A real time data graph that will automatically update and scroll.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><function>Toggle</function></term>
+ <listitem>
+ <para>
+A push button that contains state information. Toggles
+may also be used as "radio buttons" to implement a "one of many" or
+"zero or one of many" group
+of buttons. This widget can display a multi-line string or a bitmap or pixmap image.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<!-- End of CH3.Intr -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Command.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Grip.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Label.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="List.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Panner.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Repeater.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Scrollbar.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Simple.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="StripChart.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Toggle.xml"/>
+</chapter>
diff --git a/libXaw/specs/CH4.xml b/libXaw/specs/CH4.xml
new file mode 100644
index 000000000..00c89f78e
--- /dev/null
+++ b/libXaw/specs/CH4.xml
@@ -0,0 +1,102 @@
+<chapter id="menus">
+<title>Menus</title>
+<para>
+The Athena widget set provides support for single paned non-hierarchical
+popup and pulldown menus. Since menus are such a common user interface
+tool, support for them must be provided in even the most basic widget
+sets. In menuing as in other areas, the Athena Widget Set provides only
+basic functionality.
+</para>
+<para>
+Menus in the Athena widget set are implemented as a menu container (the
+SimpleMenu widget) and a collection of objects that comprise the
+menu entries. The SimpleMenu widget is itself a direct subclass of the
+OverrideShell widget class, so no other shell is necessary when
+creating a menu. The managed children of a SimpleMenu must be
+subclasses of the Sme (Simple Menu Entry) object.
+</para>
+<para>
+The Athena widget set provides three classes of Sme objects that may be
+used to build menus.
+</para>
+<para>
+<variablelist>
+ <varlistentry>
+ <term>Sme</term>
+ <listitem>
+ <para>
+The base class of all menu entries. It may be used as a menu entry
+itself to provide blank space in a menu. "Sme" means "Simple Menu
+Entry."
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SmeBSB</term>
+ <listitem>
+ <para>
+This menu entry provides a selectable entry containing a text string.
+A bitmap may also be placed in the left and right margins. "BSB" means
+"Bitmap String Bitmap."
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SmeLine</term>
+ <listitem>
+ <para>
+This menu entry provides an unselectable entry containing a separator line.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+The SimpleMenu widget informs the window manager that it should ignore
+its window by setting the <function>Override Redirect</function> flag. This is the
+correct behavior for the press-drag-release style of menu operation. If
+click-move-click or "pinable" menus are desired it is the
+responsibility of the application programmer, using the SimpleMenu
+resources, to inform the window manager of the menu.
+</para>
+<para>
+To allow easy creation of pulldown menus, a MenuButton widget is
+also provided as part of the Athena widget set.
+</para>
+<sect1 id="Using_the_Menus">
+<title>Using the Menus</title>
+<!-- .XS -->
+<!-- Using the Menus -->
+<!-- .XE -->
+<!-- .IN "Menus" "using" -->
+<para>
+<!-- .LP -->
+The default configuration for the menus is press-drag-release.
+The menus will typically be
+activated by clicking a pointer button while the pointer is over a
+MenuButton, causing the menu to appear in a fixed location relative to
+that button; this is a <function>pulldown</function> menu. Menus may also be activated
+<!-- .IN "Menus" "pulldown" -->
+when a specific pointer and/or key sequence is used anywhere in the
+application; this is a <function>popup</function> menu (e.g. clicking Ctrl-&lt;pointer
+<!-- .IN "Menus" "popup" -->
+button 1&gt; in the common application <function>xterm</function>). In this
+case the menu should be positioned under
+the cursor. Typically menus will be placed so the pointer cursor is on
+the first menu entry, or the last entry selected by the user.
+</para>
+<para>
+<!-- .LP -->
+The menu remains on the screen as long as the pointer button is held
+down. Moving the pointer will highlight different menu items.
+If the pointer leaves the menu, or moves over an entry that cannot
+be selected then no menu entry will highlighted. When the desired menu
+entry has been highlighted, releasing the pointer button removes the menu,
+and causes any mechanism associated with this entry to be invoked.
+
+</para>
+</sect1>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Sme.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="SmeBSB.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="SmeLine.xml"/>
+</chapter>
diff --git a/libXaw/specs/CH5.xml b/libXaw/specs/CH5.xml
new file mode 100644
index 000000000..eb3f2fb3e
--- /dev/null
+++ b/libXaw/specs/CH5.xml
@@ -0,0 +1,397 @@
+<chapter id="text_widgets">
+<title>Text Widgets</title>
+
+<para>
+The Text widget provides a window that will allow an application
+to display and edit one or more lines of text. Options are provided to
+allow the user to add Scrollbars to its window, search for a specific
+string, and modify the text in the buffer.
+</para>
+<para>
+The Text widget is made up of a number of pieces; it was modularized to
+ease customization. The AsciiText widget class (actually not limited to
+ASCII but so named for compatibility) is be general enough to most
+needs. If more flexibility, special features, or extra functionality is
+needed, they can be added by implementing a new TextSource or TextSink, or
+by subclassing the Text Widget (See Section 5.8 for customization
+details.) <!-- xref -->
+</para>
+<para>
+The words <emphasis remap='I'>insertion point</emphasis> are used in this chapter to refer to the text
+caret. This is the symbol that is displayed between two characters in
+the file. The insertion point marks the location where any new characters
+will be added to the file. To avoid confusion the pointer cursor will
+always be referred to as the <emphasis remap='I'>pointer</emphasis>.
+</para>
+<para>
+The text widget supports three edit modes, controlling the types of
+modifications a user is allowed to make:
+</para>
+<para>
+<itemizedlist>
+ <listitem><para>Append-only</para></listitem>
+ <listitem><para>Editable</para></listitem>
+ <listitem><para>Read-only</para></listitem>
+</itemizedlist>
+</para>
+<para>
+Read-only mode does not allow the user or the programmer to modify the text
+in the widget. While the entire string may be reset in
+read-only mode with <function>XtSetValues</function>, it cannot be modified via
+with <function>XawTextReplace</function>. Append-only and editable modes allow
+the text at the insertion point to be modified. The only difference is
+that text may only be added to or removed from the end of a buffer in
+append-only mode.
+</para>
+<sect1 id="Text_Widget_for_Users">
+<title>Text Widget for Users</title>
+<!-- .IN "Text widget" "User's Guide to the Text widget" -->
+<!-- .XS -->
+<!-- Text Widget for Users -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The Text widget provides many of the common keyboard editing commands.
+These commands allow users to move around and edit the buffer. If an
+illegal operation is attempted, (such as deleting characters in a
+read-only text widget), the X server will beep.
+</para>
+<sect2 id="Default_Key_Bindings">
+<title>Default Key Bindings</title>
+<!-- .IN "Text widget" "default key bindings" -->
+<para>
+<!-- .LP -->
+The default key bindings are patterned after those in the EMACS text editor:
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .TA 1.0i 3.0i 4.5i -->
+<!-- .ta 1.0i 3.0i 4.5i -->
+Ctrl-a Beginning Of Line Meta-b Backward Word
+Ctrl-b Backward Character Meta-f Forward Word
+Ctrl-d Delete Next Character Meta-i Insert File
+Ctrl-e End Of Line Meta-k Kill To End Of Paragraph
+Ctrl-f Forward Character Meta-q Form Paragraph
+Ctrl-g Multiply Reset Meta-v Previous Page
+Ctrl-h Delete Previous Character Meta-y Insert Current Selection
+Ctrl-j Newline And Indent Meta-z Scroll One Line Down
+Ctrl-k Kill To End Of Line Meta-d Delete Next Word
+Ctrl-l Redraw Display Meta-D Kill Word
+Ctrl-m Newline Meta-h Delete Previous Word
+Ctrl-n Next Line Meta-H Backward Kill Word
+Ctrl-o Newline And Backup Meta-&lt; Beginning Of File
+Ctrl-p Previous Line Meta-&gt; End Of File
+Ctrl-r Search/Replace Backward Meta-] Forward Paragraph
+Ctrl-s Search/Replace Forward Meta-[ Backward Paragraph
+Ctrl-t Transpose Characters
+Ctrl-u Multiply by 4 Meta-Delete Delete Previous Word
+Ctrl-v Next Page Meta-Shift Delete Kill Previous Word
+Ctrl-w Kill Selection Meta-Backspace Delete Previous Word
+Ctrl-y Unkill Meta-Shift Backspace Kill Previous Word
+Ctrl-z Scroll One Line Up
+Ctrl-\\ Reconnect to input method
+Kanji Reconnect to input method
+</literallayout>
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+In addition, the pointer may be used to cut and paste text:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.0i -->
+<!-- .ta .5i 2.0i -->
+ Button 1 Down Start Selection
+ Button 1 Motion Adjust Selection
+ Button 1 Up End Selection (cut)
+
+ Button 2 Down Insert Current Selection (paste)
+
+ Button 3 Down Extend Current Selection
+ Button 3 Motion Adjust Selection
+ Button 3 Up End Selection (cut)
+
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Since all of these key and pointer bindings are set through the
+translations and resource manager, the user and the application
+programmer can modify them by changing the Text widget's
+<function>translations</function> resource.
+<!-- .\" -->
+</para>
+</sect2>
+<sect2 id="Search_and_Replace">
+<title>Search and Replace</title>
+<!-- .IN "Text widget" "search" -->
+<!-- .IN "Text widget" "query replace" -->
+<para>
+<!-- .LP -->
+The Text widget provides a search popup that can be used to search for a
+string within the current Text widget. The popup can be activated by
+typing either <emphasis remap='I'>Control-r</emphasis> or <emphasis remap='I'>Control-s</emphasis>. If <emphasis remap='I'>Control-s</emphasis> is
+used the search will be forward in the file from the current location of the
+insertion point; if <emphasis remap='I'>Control-r</emphasis> is used the search will be backward. The
+activated popup is placed under the pointer. It has a number of buttons
+that allow both text searches and text replacements to be performed.
+</para>
+<para>
+<!-- .LP -->
+At the top of the search popup are two toggle buttons labeled
+<emphasis remap='I'>backward</emphasis> and <emphasis remap='I'>forward</emphasis>. One of these buttons will always be
+highlighted; this is the direction in which the search will be
+performed. The user can change the direction at any time by clicking on
+the appropriate button.
+</para>
+<para>
+<!-- .LP -->
+Directly under the buttons there are two text areas, one labeled
+<emphasis remap='I'>Search for:</emphasis> and the other labeled <emphasis remap='I'>Replace with:</emphasis>. If this is
+a read-only Text widget the <emphasis remap='I'>Replace with:</emphasis> field will be insensitive
+and no replacements will be allowed. After each of these labels will be
+a text field. This field will allow the user to enter a string to
+search for and the string to replace it with. Only one of these text
+fields will have a window border around it; this is the active text
+field. Any key presses that occur when the focus in in the search popup
+will be directed to the active text field. There are also a few special
+key sequences:
+<literallayout class="monospaced">
+<!-- .TA 1.75i -->
+<!-- .ta 1.75i -->
+<function>Carriage Return</function>: Execute the action, and pop down the search widget.
+<function>Tab</function>: Execute the action, then move to the next field.
+<function>Shift Carriage Return</function>: Execute the action, then move to the next field.
+<function>Control-q Tab</function>: Enter a Tab into a text field.
+<function>Control-c</function>: Pop down the search popup.
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Using these special key sequences should allow simple
+searches without ever removing one's hands from the keyboard.
+</para>
+<para>
+<!-- .LP -->
+Near the bottom of the search popup is a row of buttons. These buttons
+allow the same actions to to be performed as the key sequences, but the
+buttons will leave the popup active. This can be quite useful if many
+searches are being performed, as the popup will be left on the display.
+Since the search popup is a transient window, it may be picked
+up with the window manager and pulled off to the side for use
+at a later time.
+</para>
+<variablelist>
+ <varlistentry>
+ <term>Search</term>
+ <listitem>
+ <para>
+Search for the specified string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Replace</term>
+ <listitem>
+ <para>
+Replace the currently highlighted string with the string in the
+<emphasis remap='I'>Replace with</emphasis> text field, and move onto the next occurrence of the
+<emphasis remap='I'>Search for</emphasis> text field. The functionality is commonly referred to as
+query-replace.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ReplaceAll</term>
+ <listitem>
+ <para>
+Replace all occurrences of the search string with the replace string from
+the current insertion point position to the end (or beginning) of the
+file. There is no key sequence to perform this action.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ReplaceAll</term>
+ <listitem>
+ <para>
+Remove the search popup from the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+Finally, when <function>international</function> resource is <function>true</function>, there may be a
+pre-edit buffer below the button row, for composing input. Its presence
+is determined by the X locale in use and the VendorShell's <function>preeditType</function>
+resource.
+</para>
+<para>
+<!-- .LP -->
+The widget hierarchy for the search popup is show below, all widgets
+are listed by class and instance name.
+<!-- .sp -->
+<!-- .nf -->
+<!-- .ta .5i 1.0i 1.5i 2.0i 2.5i -->
+<literallayout class="monospaced">
+Text &lt;name of Text widget&gt;
+ TransientShell search
+ Form form
+ Label label1
+ Label label2
+ Toggle backwards
+ Toggle forwards
+ Label searchLabel
+ Text searchText
+ Label replaceLabel
+ Text replaceText
+ Command search
+ Command replaceOne
+ Command replaceAll
+ Command cancel
+</literallayout>
+<!-- .fi -->
+</para>
+</sect2>
+<sect2 id="File_Insertion">
+<title>File Insertion</title>
+<para>
+<!-- .LP -->
+<!-- .IN "Text widget" "file insertion" -->
+To insert a file into a text widget, type the key sequence <emphasis remap='I'>Meta-i</emphasis>,
+which will activate the file insert popup. This popup will appear under
+the pointer, and any text typed while the focus is in this popup will be
+redirected to the text field used for the filename. When the desired
+filename has been entered, click on <emphasis remap='I'>Insert File</emphasis>, or type
+<emphasis remap='I'>Carriage Return</emphasis>. The named file will then be inserted in the text
+widget beginning at the insertion point position. If an error occurs when
+opening the file, an error message will be printed, prompting the user
+to enter the filename again. The file insert may be aborted by clicking
+on <emphasis remap='I'>Cancel</emphasis>. If <emphasis remap='I'>Meta-i</emphasis> is typed at a text widget that is
+read-only, it will beep, as no file insertion is allowed.
+</para>
+<para>
+<!-- .LP -->
+The widget hierarchy for the file insert popup is show below; all widgets
+are listed by class and instance name.
+<!-- .sp -->
+<!-- .nf -->
+<!-- .ta .5i 1.0i 1.5i 2.0i 2.5i -->
+<literallayout class="monospaced">
+Text &lt;name of Text widget&gt;
+ TransientShell insertFile
+ Form form
+ Label label
+ Text text
+ Command insert
+ Command cancel
+</literallayout>
+<!-- .fi -->
+</para>
+</sect2>
+<sect2 id="Text_Selections_for_Users">
+<title>Text Selections for Users</title>
+<para>
+<!-- .LP -->
+<!-- .IN "Text widget" "Text Selections for Users" -->
+The text widgets have a text selection mechanism that allows
+the user to copy pieces of the text into the <function>PRIMARY</function> selection,
+and paste
+into the text widget some text that another application (or text
+widget) has put in the <function>PRIMARY</function> selection.
+</para>
+<para>
+<!-- .LP -->
+One method of selecting text is to press pointer button 1
+on the beginning of the text to be selected, drag the pointer until all
+of the desired text is highlighted, and then release the button to
+activate the selection. Another method is to click pointer button 1 at
+one end of the text to be selected, then click pointer button 3 at the
+other end.
+</para>
+<para>
+<!-- .LP -->
+To modify a currently active selection, press pointer button 3 near
+either the end of the selection that you want to
+adjust. This end of the selection may be moved while holding down pointer
+button 3. When the proper area has been highlighted release the pointer
+button to activate the selection.
+</para>
+<para>
+<!-- .LP -->
+The selected text may now be pasted into another application, and
+will remain active until some other client makes a selection.
+To paste text that some other application has
+put into the <function>PRIMARY</function> selection use pointer button 2.
+First place the insertion point where you would like the text to be inserted,
+then click and release pointer button 2.
+</para>
+<para>
+<!-- .LP -->
+Rapidly clicking pointer button 1 the following number of times will adjust
+the selection as described.
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>Two</function>
+ </term>
+ <listitem>
+ <para>
+Select the word under the pointer. A word boundary is defined by the
+Text widget to be a Space, Tab, or Carriage Return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Three</function>
+ </term>
+ <listitem>
+ <para>
+Select the line under the pointer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Four</function>
+ </term>
+ <listitem>
+ <para>
+Select the paragraph under the pointer. A paragraph boundary is
+defined by the text widget as two Carriage Returns in a row with only
+Spaces or Tabs between them.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Five</function>
+ </term>
+ <listitem>
+ <para>
+Select the entire text buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+To unset the text selection, click pointer button 1 without moving it.
+</para>
+</sect2>
+</sect1>
+
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextActions_text_widget_actions.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextActions_default_translation_bindings.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextFuncs.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextCustom.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Text.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextSink.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextSource.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AsciiSink.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AsciiSource.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AsciiText.xml"/>
+</chapter>
diff --git a/libXaw/specs/CH6.xml b/libXaw/specs/CH6.xml
new file mode 100644
index 000000000..e8009afb6
--- /dev/null
+++ b/libXaw/specs/CH6.xml
@@ -0,0 +1,117 @@
+<chapter id="composite_and_constraint_widgets">
+<title>Composite and Constraint Widgets</title>
+<para>
+These widgets may contain arbitrary widget children. They implement a
+policy for the size and location of their children.
+</para>
+<para>
+<variablelist>
+ <varlistentry>
+ <term>Box</term>
+ <listitem>
+ <para>
+This widget will pack its children as tightly as possible in non-overlapping rows.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Dialog</term>
+ <listitem>
+ <para>
+An implementation of a commonly used interaction semantic to prompt for
+auxiliary input from the user, such as a filename.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Form</term>
+ <listitem>
+ <para>
+A more sophisticated layout widget that allows the children to specify
+their positions relative to the other children, or to the edges of the Form.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Paned</term>
+ <listitem>
+ <para>
+Allows children to be tiled vertically or horizontally. Controls are
+also provided to allow the user to dynamically resize the individual panes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Porthole</term>
+ <listitem>
+ <para>
+Allows viewing of a managed child which is as large as, or larger than its
+parent, typically under control of a Panner widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Tree</term>
+ <listitem>
+ <para>
+Provides geometry management of widgets arranged in a directed, acyclic graph.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Viewport</term>
+ <listitem>
+ <para>
+Consists of a frame, one or two scrollbars, and an inner window. The
+inner window can contain all the data that is to be displayed. This inner
+window will be clipped by the frame with the scrollbars controlling
+which section of the inner window is currently visible.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<note>
+<para>
+<!-- .LP -->
+The geometry management semantics provided by the X Toolkit give full
+control of the size and position of a widget to the parent of that
+widget. While the children are allowed to request a certain size or
+location, it is the parent who makes the final decision. Many of the
+composite widgets here will deny any geometry request from their
+children by default. If a child widget is not getting the expected size
+or location, it is most likely the parent disallowing a request, or
+implementing semantics slightly different than those expected by the
+application programmer.
+</para>
+<para>
+<!-- .LP -->
+If the application wishes to change the size or location of
+any widget it should make a call to <function>XtSetValues</function>. This will
+<!-- .IN "XtSetValues" "" -->
+allow the widget to ask its parent for the new size or location.
+As noted above the parent is allowed to refuse this request,
+and the child must live with the result. If the
+application is unable to achieve the desired semantics, then perhaps it
+should use a different composite widget. Under no circumstances
+should an application programmer resort to <function>XtMoveWidget</function> or
+<!-- .IN "XtMoveWidget" "" -->
+<function>XtResizeWidget</function>; these functions are exclusively for the use of
+<!-- .IN "XtResizeWidget" "" -->
+Composite widget implementors.
+</para>
+<para>
+<!-- .LP -->
+For more information on geometry management consult the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+</para>
+</note>
+
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Box.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Dialog.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Form.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Paned.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Porthole.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Tree.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Viewport.xml"/>
+
+</chapter>
diff --git a/libXaw/specs/CH7.xml b/libXaw/specs/CH7.xml
new file mode 100644
index 000000000..4c491704b
--- /dev/null
+++ b/libXaw/specs/CH7.xml
@@ -0,0 +1,167 @@
+<chapter id="creating_new_widgets__subclassing_">
+<title>Creating New Widgets (Subclassing)</title>
+<para>
+Although the task of creating a new widget may at first appear a little
+daunting, there is a basic simple pattern that all widgets follow. The
+Athena Widget library contains a special widget called the
+<emphasis remap='I'>Template</emphasis> widget that is intended to assist
+the novice widget programmer in writing a custom widget.
+</para>
+<para>
+Reasons for wishing to write a custom widget include:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Providing a graphical interface not currently supported by any existing
+widget set.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Convenient access to resource management procedures to obtain fonts,
+colors, etc., even if user customization is not desired.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Convenient access to user input dispatch and translation management procedures.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Access to callback mechanism for building higher-level application libraries.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Customizing the interface or behavior of an existing widget to suit a
+special application need.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Desire to allow user customization of resources such as fonts, colors,
+etc., or to allow convenient re-binding of keys and buttons to internal
+functions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Converting a non-Toolkit application to use the Toolkit.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+In each of these cases, the operation needed to create a new widget is
+to "subclass" an existing one. If the desired semantics of the new
+widget are similar to an existing one, then the implementation of the
+existing widget should be examined to see how much work would be
+required to create a subclass that will then be
+able to share the existing class methods. Much time will be saved in
+writing the new widget if an existing widget class Expose, Resize and/or
+GeometryManager method can be used by the subclass.
+</para>
+<para>
+Note that some trivial uses of a ``bare-bones'' widget may be achieved by
+simply creating an instance of the Core
+widget. The class variable to use when creating a Core widget is
+<function>widgetClass</function>.
+The geometry of the Core widget is determined entirely by the parent
+widget.
+</para>
+<para>
+It is very often the case than an application will have a special need
+for a certain set of functions and that many copies of these functions
+will be needed. For example, when converting an older application to use
+the Toolkit, it may be desirable to have a "Window Widget" class that
+might have the following semantics:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Allocate 2 drawing colors in addition to a background color.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Allocate a text font.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Execute an application-supplied function to handle exposure events.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Execute an application-supplied function to handle user input events.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+It is obvious that a completely general-purpose WindowWidgetClass could
+be constructed that would export all class methods as callbacks lists,
+but such a widget would be very large and would have to choose some
+arbitrary number of resources such as colors to allocate. An application
+that used many instances of the general-purpose widget would therefore
+un-necessarily waste many resources.
+</para>
+<para>
+In this section, an outline will be given of the procedure to follow to
+construct a special-purpose widget to address the items listed above.
+The reader should refer to the appropriate sections of the
+<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>
+for complete details of the material outlined here. Section 1.4 of
+the <emphasis remap='I'>Intrinsics</emphasis> should be read in
+conjunction with this section.
+</para>
+<para>
+All Athena widgets have three separate files associated with them:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A "public" header file containing declarations needed by applications programmers
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A "private" header file containing additional declarations needed by the
+widget and any subclasses
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A source code file containing the implementation of the widget
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+This separation of functions into three files is suggested for all
+widgets, but nothing in the Toolkit actually requires this format. In
+particular, a private widget created for a single application may easily
+combine the "public" and "private" header files into a single file, or
+merge the contents into another application header file. Similarly, the
+widget implementation can be merged into other application code.
+</para>
+
+<para>
+In the following example, the public header file
+<function>&lt; X11/Xaw/Template.h &gt;</function>,
+the private header file
+<function>&lt; X11/Xaw/TemplateP.h &gt;</function>
+and the source code file
+<function>&lt; X11/Xaw/Template.c &gt;</function>
+will be modified to produce the "WindowWidget" described above.
+In each case, the files have been designed so that a global string
+replacement of "Template" and "template"
+with the name of your new widget, using
+the appropriate case, can be done.
+</para>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Template_public_header_file.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Template_private_header_file.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Template_widget_source_file.xml"/>
+</chapter>
diff --git a/libXaw/specs/Command.xml b/libXaw/specs/Command.xml
new file mode 100644
index 000000000..92d1b7253
--- /dev/null
+++ b/libXaw/specs/Command.xml
@@ -0,0 +1,525 @@
+<sect1 id="Command_Widget">
+<title>Command Widget</title>
+<!-- .XS -->
+<!-- Command Widget -->
+<!-- .XE -->
+<!-- .IN "Command widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application header file &lt;X11/Xaw/Command.h&gt;
+<!-- .IN "Command.h" "" -->
+Class header file &lt;X11/Xaw/CommandP.h&gt;
+<!-- .IN "CommandP.h" "" -->
+Class commandWidgetClass
+<!-- .IN "commandWidgetClass" "" -->
+Class Name Command
+<!-- .IN "Command widget" "class name" -->
+Superclass Label
+<!-- .sp -->
+</literallayout>
+<para>
+<!-- .LP -->
+The Command widget is an area, often rectangular, that contains text
+or a graphical image. Command widgets are often referred to as
+``push buttons.'' When the pointer is over a Command widget, the
+widget becomes highlighted by drawing a rectangle around its perimeter.
+This highlighting indicates that the widget is ready for selection.
+When mouse button 1 is pressed, the Command widget indicates that
+it has been selected by reversing its foreground and background colors.
+When the mouse button is released, the Command widget's <function>notify</function>
+action is invoked, calling all functions on its callback list. If
+the pointer is moved off of the widget before the pointer button is
+released, the widget reverts to its normal foreground and background
+colors, and releasing the pointer button has no effect. This behavior
+allows the user to cancel an action.
+</para>
+<sect2 id="Resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Command widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "Command widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>bitmap</entry>
+ <entry>Bitmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>callback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cornerRoundPercent</entry>
+ <entry>CornerRoundPercent</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>25</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>encoding</entry>
+ <entry>Encoding</entry>
+ <entry>UnsignedChar</entry>
+ <entry></entry>
+ <entry>XawTextEncoding8bit</entry>
+ </row>
+ <row>
+ <entry>font</entry>
+ <entry>Font</entry>
+ <entry>XFontStruct</entry>
+ <entry></entry>
+ <entry>XtDefaultFont</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>graphic height + 2 * <function>internalHeight</function></entry>
+ </row>
+ <row>
+ <entry>highlightThickness</entry>
+ <entry>Thickness</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>2 (0 if Shaped)</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>internalHeight</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>internalWidth</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>justify</entry>
+ <entry>Justify</entry>
+ <entry>Justify</entry>
+ <entry></entry>
+ <entry>XtJustifyCenter (center)</entry>
+ </row>
+ <row>
+ <entry>label</entry>
+ <entry>Label</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>name of widget</entry>
+ </row>
+ <row>
+ <entry>leftBitmap</entry>
+ <entry>LeftBitmap</entry>
+ <entry>Bitmap</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>resize</entry>
+ <entry>Resize</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>shapeStyle</entry>
+ <entry>ShapeStyle</entry>
+ <entry>ShapeStyle</entry>
+ <entry></entry>
+ <entry>Rectangle</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>See below</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>graphic width + 2 * <function>internalWidth</function></entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+\" Resource Descriptions
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bm -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Cb Bold -->
+<!-- .Cm -->
+<!-- .Cr Bold -->
+<!-- .Cu -->
+<!-- .Cn -->
+<!-- .Dp -->
+<!-- .Dc -->
+<!-- .Le -->
+<!-- .Lf -->
+<!-- .Ls -->
+<!-- .Lg -->
+<!-- .Hw -->
+<!-- .Ht Bold -->
+<!-- .Ib -->
+<!-- .Ih -->
+<!-- .In -->
+<!-- .Ju -->
+<!-- .La -->
+<!-- .Ll -->
+<!-- .Mm -->
+<!-- .Pf -->
+<!-- .Pb -->
+<!-- .Re -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Ss Bold -->
+<!-- .Tr -->
+<!-- .Xy -->
+</para>
+</sect2>
+<sect2 id="Command_Actions">
+<title>Command Actions</title>
+<!-- .IN "Command widget" "actions" -->
+<para>
+<!-- .LP -->
+The Command widget supports the following actions:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Switching the button's interior between the foreground and background
+colors with <function>set</function>, <function>unset</function>, and <function>reset</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Processing application callbacks with <function>notify</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Switching the internal border between highlighted
+and unhighlighted states with <function>highlight</function> and <function>unhighlight</function>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<!-- .IN "Command widget" "translation bindings" -->
+The following are the default translation bindings used by the
+Command widget:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+ &lt;EnterWindow&gt;: highlight(\|)
+ &lt;LeaveWindow&gt;: reset(\|)
+ &lt;Btn1Down&gt;: set(\|)
+ &lt;Btn1Up&gt;: notify(\|) unset(\|)
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The full list of actions supported by Command is:
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>highlight</function>(<function>condition</function>)
+ </term>
+ <listitem>
+ <para>
+Displays the internal highlight border in the color (<function>foreground</function>
+or <function>background</function> ) that contrasts with the interior color of the
+Command widget. The conditions <function>WhenUnset</function> and <function>Always</function> are
+understood by this action procedure. If no argument is passed,
+<function>WhenUnset</function> is assumed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>unhighlight</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Displays the internal highlight border in the color (<function>foreground</function>
+or <function>background</function> ) that matches the interior color of the
+Command widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>set</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Enters the <function>set</function> state, in which <function>notify</function> is possible. This
+action causes the button to display its interior in the
+<function>foreground</function> color. The label or bitmap is displayed in the
+<function>background</function> color.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>unset</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Cancels the <emphasis remap='I'>set</emphasis> state and displays the interior of the button in the
+<function>background</function> color. The label or bitmap is displayed in the
+<function>foreground</function> color.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>reset</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Cancels any <emphasis remap='I'>set</emphasis> or <emphasis remap='I'>highlight</emphasis> and displays the interior of the
+button in the <function>background</function> color, with the label or bitmap displayed
+in the <function>foreground</function> color.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>notify</function>(\|)
+ </term>
+ <listitem>
+ <para>
+When the button is in the <function>set</function> state this action calls all functions in
+the callback list named by the <function>callback</function> resource. The value of
+the <emphasis remap='I'>call_data</emphasis> argument passed to these functions is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+A very common alternative to registering callbacks is to augment a
+Command's translations with an action performing the desired
+function. This often takes the form of:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+*Myapp*save.translations: #augment &lt;Btn1Down&gt;,&lt;Btn1Up&gt;: Save()
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .NT -->
+When a bitmap of depth greater that one (1) is specified the
+<emphasis remap='I'>set</emphasis>(), <emphasis remap='I'>unset</emphasis>(), and <emphasis remap='I'>reset</emphasis>() actions have no effect,
+since there are no foreground and background colors used in a
+multi-plane pixmap.
+<!-- .NE -->
+
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Dialog.xml b/libXaw/specs/Dialog.xml
new file mode 100644
index 000000000..f77006c6a
--- /dev/null
+++ b/libXaw/specs/Dialog.xml
@@ -0,0 +1,692 @@
+<sect1 id="Dialog_Widget">
+<title>Dialog Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Dialog Widget -->
+<!-- .XE -->
+<!-- .IN "Dialog widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file &lt;X11/Xaw/Dialog.h&gt;
+<!-- .IN "Dialog.h" "" -->
+Class Header file &lt;X11/Xaw/DialogP.h&gt;
+<!-- .IN "DialogP.h" "" -->
+Class dialogWidgetClass
+<!-- .IN "dialogWidgetClass" "" -->
+Class Name Dialog
+<!-- .IN "Dialog widget" "class name" -->
+Superclass Form
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The Dialog widget implements a commonly used interaction semantic to
+prompt for auxiliary input from a user. For example, you can use a
+Dialog widget when an application requires a small piece of information,
+such as a filename, from the user. A Dialog widget, which is simply a
+special case of the Form widget, provides a convenient way to create a
+preconfigured form.
+</para>
+<para>
+<!-- .LP -->
+The typical Dialog widget contains three areas. The first line
+contains a description of the function of the Dialog widget, for
+example, the string <emphasis remap='I'>Filename:</emphasis>. The second line contains an area
+into which the user types input. The third line can contain buttons
+that let the user confirm or cancel the Dialog input. Any of these
+areas may be omitted by the application.
+</para>
+<sect2 id="dialog_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Dialog widget instance, the following resources are
+retrieved from the argument list or the resource database:
+<!-- .IN "Dialog widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>children</entry>
+ <entry>ReadOnly</entry>
+ <entry>WidgetList</entry>
+ <entry>R</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>defaultDistance</entry>
+ <entry>Thickness</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Enough space to contain all children</entry>
+ </row>
+ <row>
+ <entry>icon</entry>
+ <entry>Icon</entry>
+ <entry>Bitmap</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>label</entry>
+ <entry>Label</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>"label"</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>numChildren</entry>
+ <entry>ReadOnly</entry>
+ <entry>Cardinal</entry>
+ <entry>R</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>value</entry>
+ <entry>Value</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>no value widget</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Enough space to contain all children</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Ch -->
+<!-- .Cm -->
+<!-- .Dd -->
+<!-- .Dp -->
+<!-- .Dc -->
+<!-- .Hw -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>icon</function>
+ </term>
+ <listitem>
+ <para>
+A pixmap image to be displayed immediately to the left of the
+Dialog widget's label.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>label</function>
+ </term>
+ <listitem>
+ <para>
+A string to be displayed at the top of the Dialog widget.
+<!-- .Mm -->
+<!-- .Nc -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>value</function>
+ </term>
+ <listitem>
+ <para>
+An initial value for the string field that the user will enter text
+into. By default, no text entry field is available to the user.
+Specifying an initial value for <function>value</function> activates the text entry
+field. If string input is desired, but no initial value is to be
+specified then set this resource to "" (empty string).
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Constraint_Resources">
+<title>Constraint Resources</title>
+<para>
+<!-- .LP -->
+<!-- .IN "Dialog widget" "constraint resources" -->
+Each child of the Dialog widget may request special layout resources
+be applied to it. These <emphasis remap='I'>constraint</emphasis> resources allow the Dialog
+widget's children to specify individual layout requirements.
+</para>
+<para>
+<!-- .LP -->
+<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>bottom</entry>
+ <entry>Edge</entry>
+ <entry>XawEdgeType</entry>
+ <entry></entry>
+ <entry>XawRubber</entry>
+ </row>
+ <row>
+ <entry>fromHoriz</entry>
+ <entry>Widget</entry>
+ <entry>Widget</entry>
+ <entry></entry>
+ <entry>NULL (left edge of Dialog)</entry>
+ </row>
+ <row>
+ <entry>fromVert</entry>
+ <entry>Widget</entry>
+ <entry>Widget </entry>
+ <entry></entry>
+ <entry>NULL (top edge of Dialog)</entry>
+ </row>
+ <row>
+ <entry>horizDistance</entry>
+ <entry>Thickness</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry><function>defaultDistance</function> resource</entry>
+ </row>
+ <row>
+ <entry>left</entry>
+ <entry>Edge</entry>
+ <entry>XawEdgeType</entry>
+ <entry></entry>
+ <entry>XawRubber</entry>
+ </row>
+ <row>
+ <entry>resizable</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>FALSE</entry>
+ </row>
+ <row>
+ <entry>right</entry>
+ <entry>Edge</entry>
+ <entry>XawEdgeType</entry>
+ <entry></entry>
+ <entry>XawRubber</entry>
+ </row>
+ <row>
+ <entry>top</entry>
+ <entry>Edge</entry>
+ <entry>XawEdgeType</entry>
+ <entry></entry>
+ <entry>XawRubber</entry>
+ </row>
+ <row>
+ <entry>vertDistance</entry>
+ <entry>Thickness</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry><function>defaultDistance</function> resource</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<literallayout class="monospaced">
+bottom
+left
+right
+top What to do with this edge of the child when
+ the parent is resized. This resource may be
+ any edgeType. See Layout Semantics for
+ details.
+
+fromHoriz
+fromVert Which widget this child should be placed
+ underneath (or to the right of). If a value
+ of NULL is specified then this widget will be
+ positioned relative to the edge of the par-
+ ent.
+
+horizDistance
+vertDistance The amount of space, in pixels, between this
+ child and its left or upper neighbor.
+
+resizable If this resource is False then the parent
+ widget will ignore all geometry request made
+ by this child. The parent may still resize
+ this child itself, however.
+</literallayout>
+<!-- .Bt -->
+<!-- .Fh -->
+<!-- .Hd -->
+<!-- .Rl -->
+</para>
+</sect2>
+<sect2 id="dialog_layout_semantics">
+<title>Layout Semantics</title>
+<!-- .IN "Dialog widget" "layout semantics" -->
+<para>
+The Dialog widget uses two different sets of layout seman-
+tics. One is used when initially laying out the children.
+The other is used when the Dialog is resized.
+</para>
+<para>
+The first layout method uses the <function>fromVert</function> mand <function>fromHoriz</function>
+resources to place the children of the Dialog. A single
+pass is made through the Dialog widget's children in the
+order that they were created. Each child is then placed in
+the Dialog widget below or to the right of the widget speci-
+fied by the <function>fromVert</function> mand <function>fromHoriz</function> mresources. The distance
+the new child is placed from its left or upper neighbor is
+determined by the <function>horizDistance</function> mand <function>vertDistance</function> mresources.
+This implies some things about how the order of creation
+affects the possible placement of the children. The Form
+widget registers a string to widget converter which does not
+postpone conversion and does not cache conversion results.
+</para>
+<para>
+
+The second layout method is used when the Dialog is resized.
+It does not matter what causes this resize, and it is possi-
+ble for a resize to happen before the widget becomes visible
+(due to constraints imposed by the parent of the Dialog).
+This layout method uses the <function>bottom</function> ,
+<function>top</function> , <function>left</function> , and
+<function>right</function>
+resources. These resources are used to determine what will
+happen to each edge of the child when the Dialog is resized.
+If a value of <function>XawChain</function>
+<emphasis remap='I'>&lt;something&gt;</emphasis>
+ is specified, the the edge
+of the child will remain a fixed distance from the <emphasis remap='I'>chain</emphasis>
+edge of the Dialog. For example if <function>XawChainLeft</function>
+mis specified for the <function>right</function> mresource of a child
+then the right edge
+of that child will remain a fixed distance from the left
+edge of the Dialog widget. If a value of <function>XawRubber</function> mis spec-
+ified, that edge will grow by the same percentage that the
+Dialog grew. For instance if the Dialog grows by 50% the
+left edge of the child (if specified as <function>XawRubber</function> mwill be
+50% farther from the left edge of the Dialog). One must be
+very careful when specifying these resources, for when they
+are specified incorrectly children may overlap or completely
+occlude other children when the Dialog widget is resized.
+</para>
+
+<para>
+<!-- .LP -->
+<informaltable>
+ <tgroup cols='3' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Edge Type</entry>
+ <entry>Resource Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XawChainBottom</entry>
+ <entry>ChainBottom</entry>
+ <entry>Edge remains a fixed distance from bottom of Dialog</entry>
+ </row>
+ <row>
+ <entry>XawChainLeft</entry>
+ <entry>ChainLeft</entry>
+ <entry>Edge remains a fixed distance from left of Dialog</entry>
+ </row>
+ <row>
+ <entry>XawChainRight</entry>
+ <entry>ChainRight</entry>
+ <entry>Edge remains a fixed distance from right of Dialog</entry>
+ </row>
+ <row>
+ <entry>XawChainTop</entry>
+ <entry>ChainTop</entry>
+ <entry>Edge remains a fixed distance from top of Dialog</entry>
+ </row>
+ <row>
+ <entry>XawRubber</entry>
+ <entry>Rubber</entry>
+ <entry>Edges will move a proportional distance</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<sect3 id="Example">
+<title>Example</title>
+<para>
+<!-- .LP -->
+If you wish to force the Dialog to never resize one or more of its children
+then set <function>left</function> and <function>right</function> to <function>XawChainLeft</function> and
+<function>top</function> and <function>bottom</function> to <function>XawChainTop</function>. This will cause
+the child to remain a fixed distance from the top and left
+edges of the Dialog, and to never resize.
+</para>
+</sect3>
+<sect3 id="Special_Considerations">
+<title>Special Considerations</title>
+<!-- .IN "Dialog widget" "special considerations" -->
+<para>
+<!-- .LP -->
+The Dialog widget automatically sets the <function>top</function> and <function>bottom</function>
+resources for all Children that are subclasses of the Command widget,
+as well as the widget children that are used to contain the <function>label</function>,
+<function>value</function>, and <function>icon</function>. This policy allows the buttons at the
+bottom of the Dialog to interact correctly with the predefined children,
+and makes it possible for a client to simply create and manage a new
+Command button without having to specify its constraints.
+</para>
+<para>
+<!-- .LP -->
+The Dialog will also set <function>fromLeft</function> to the last button in the
+<!-- .IN "fromLeft" "" -->
+Dialog for each new button added to the Dialog widget.
+</para>
+<para>
+<!-- .LP -->
+The automatically added constraints cannot be overridden, as they are
+policy decisions of the Dialog widget. If a more flexible Dialog is
+desired, the application is free to use the Form widget to create its
+own Dialog policy.
+</para>
+</sect3>
+</sect2>
+<sect2 id="Automatically_Created_Children_">
+<title>Automatically Created Children.</title>
+<!-- .IN "Dialog widget" "automatically created children" -->
+<para>
+<!-- .LP -->
+The Dialog uses Label widgets to contain the <function>label</function> and <function>icon</function>.
+These widgets are named <emphasis remap='I'>label</emphasis> and <emphasis remap='I'>icon</emphasis> respectively. The
+Dialog <function>value</function> is contained in an AsciiText widget whose name is
+<function>value</function>. Using <function>XtNameToWidget</function> the application can change
+<!-- .IN "XtNameToWidget" "" -->
+those resources associated with each of these widgets that are not
+available through the Dialog widget itself.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect2>
+<sect2 id="dialog_convenience_routines">
+<title>Convenience Routines</title>
+<para>
+<!-- .LP -->
+To return the character string in the text field, use
+<!-- .PN XawDialogGetValueString . -->
+<!-- .IN "XawDialogGetValueString" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>String<function> XawDialogGetValueString</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Dialog widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function returns a copy of the value string of the Dialog
+widget. This string is allocated by the AsciiText widget and will
+remain valid and unchanged until another call to
+<function>XawDialogGetValueString</function> or an <function>XtGetValues</function> call on the
+<function>value</function> widget, when the string will be automatically freed, and
+a new string is returned. This string may be freed earlier by calling
+the function <function>XawAsciiSourceFreeString</function>.
+<!-- .IN "XawAsciiSourceFreeString" "" -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a new button to the Dialog widget use
+<function>XawDialogAddButton</function>.
+<!-- .IN "XawDialogAddButton" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawDialogAddButton</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>String<parameter> name</parameter></paramdef>
+ <paramdef>XtCallbackProc<parameter> func</parameter></paramdef>
+ <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Dialog widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the new Command button to be added to the Dialog.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>func</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a callback function to be called when this button is activated. If
+NULL is specified then no callback is added.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the client_data to be passed to the <emphasis remap='I'>func</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function is merely a shorthand for the code sequence:
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .SM -->
+<!-- .TA 1i 2i -->
+<!-- .ta 1i 2i -->
+{
+ Widget button = XtCreateManagedWidget(name, commandWidgetClass, w, NULL, ZERO);
+ XtAddCallback(button, XtNcallback, func, client_data);
+}
+<!-- .NL -->
+</literallayout>
+<!-- .sp -->
+
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Form.xml b/libXaw/specs/Form.xml
new file mode 100644
index 000000000..13cc36a5a
--- /dev/null
+++ b/libXaw/specs/Form.xml
@@ -0,0 +1,531 @@
+<sect1 id="Form_Widget">
+<title>Form Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Form Widget -->
+<!-- .XE -->
+<!-- .IN "Form widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file &lt;X11/Xaw/Form.h&gt;
+<!-- .IN "Form.h" "" -->
+Class Header file &lt;X11/Xaw/FormP.h&gt;
+<!-- .IN "FormP.h" "" -->
+Class formWidgetClass
+<!-- .IN "formWidgetClass" "" -->
+Class Name Form
+<!-- .IN "Form widget" "class name" -->
+Superclass Constraint
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The Form widget can contain an arbitrary number of children or
+subwidgets. The Form provides geometry management for its children,
+which allows individual control of the position of each child. Any
+combination of children can be added to a Form. The initial positions
+of the children may be computed relative to the positions of previously
+created children. When the Form is resized, it computes new positions and
+sizes for its children. This computation is based upon information
+provided when a child is added to the Form.
+</para>
+<para>
+<!-- .LP -->
+The default width of the Form is the minimum width needed to
+enclose the children after computing their initial layout, with a
+margin of <function>defaultDistance</function>
+at the right and bottom edges. If a width and height is assigned
+to the Form that is too small for the layout, the children will
+be clipped by the right and bottom edges of the Form.
+</para>
+<sect2 id="form_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Form widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "Form widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>children</entry>
+ <entry>ReadOnly</entry>
+ <entry>WidgetList</entry>
+ <entry>R</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>defaultDistance</entry>
+ <entry>Thickness</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Enough space to contain all children</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>numChildren</entry>
+ <entry>ReadOnly</entry>
+ <entry>Cardinal</entry>
+ <entry>R</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Enough space to contain all children</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Ch -->
+<!-- .Cm -->
+<!-- .Dd Bold -->
+<!-- .Dp -->
+<!-- .Dc -->
+<!-- .Hw -->
+<!-- .Mm -->
+<!-- .Nc -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+<!-- .Xy -->
+</para>
+</sect2>
+<sect2 id="form_constraint_resources">
+<title>Constraint Resources</title>
+<para>
+<!-- .LP -->
+<!-- .IN "Form widget" "constraint resources" -->
+Each child of the Form widget may request special layout resources
+be applied to it. These <emphasis remap='I'>constraint</emphasis> resources allow the Form
+widget's children to specify individual layout requirements.
+</para>
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+<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>bottom</entry>
+ <entry>Edge</entry>
+ <entry>XawEdgeType</entry>
+ <entry></entry>
+ <entry>XawRubber</entry>
+ </row>
+ <row>
+ <entry>fromHoriz</entry>
+ <entry>Widget</entry>
+ <entry>Widget</entry>
+ <entry></entry>
+ <entry>NULL (left edge of Form)</entry>
+ </row>
+ <row>
+ <entry>fromVert</entry>
+ <entry>Widget</entry>
+ <entry>Widget </entry>
+ <entry></entry>
+ <entry>NULL (top edge of Form)</entry>
+ </row>
+ <row>
+ <entry>horizDistance</entry>
+ <entry>Thickness</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry><function>defaultDistance</function> resource</entry>
+ </row>
+ <row>
+ <entry>left</entry>
+ <entry>Edge</entry>
+ <entry>XawEdgeType</entry>
+ <entry></entry>
+ <entry>XawRubber</entry>
+ </row>
+ <row>
+ <entry>resizable</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>FALSE</entry>
+ </row>
+ <row>
+ <entry>right</entry>
+ <entry>Edge</entry>
+ <entry>XawEdgeType</entry>
+ <entry></entry>
+ <entry>XawRubber</entry>
+ </row>
+ <row>
+ <entry>top</entry>
+ <entry>Edge</entry>
+ <entry>XawEdgeType</entry>
+ <entry></entry>
+ <entry>XawRubber</entry>
+ </row>
+ <row>
+ <entry>vertDistance</entry>
+ <entry>Thickness</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry><function>defaultDistance</function> resource</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Bt Bold -->
+<!-- .Fh Bold -->
+<!-- .Hd Bold -->
+<!-- .Rl Bold -->
+</para>
+<literallayout class="monospaced">
+bottom
+left
+right
+top What to do with this edge of the child when
+ the parent is resized. This resource may be
+ any edgeType. See Layout Semantics for
+ details.
+
+fromHoriz
+fromVert Which widget this child should be placed
+ underneath (or to the right of). If a value
+ of NULL is specified then this widget will be
+ positioned relative to the edge of the par-
+ ent.
+
+horizDistance
+vertDistance The amount of space, in pixels, between this
+ child and its left or upper neighbor.
+
+resizable If this resource is False then the parent
+ widget will ignore all geometry request made
+ by this child. The parent may still resize
+ this child itself, however.
+</literallayout>
+<!-- .Bt -->
+</sect2>
+<sect2 id="form_layout_semantics">
+<title>Layout Semantics</title>
+<para>
+The Form widget uses two different sets of layout semantics.
+One is used when initially laying out the children. The
+other is used when the Form is resized.
+</para>
+<para>
+The first layout method uses the <function>fromVert</function>
+and <function>fromHoriz</function>
+resources to place the children of the Form. A single pass
+is made through the Form widget's children in the order that
+they were created. Each child is then placed in the Form
+widget below or to the right of the widget specified by the
+<function>fromVert</function> and <function>fromHoriz</function>
+resources. The distance the new
+child is placed from its left or upper neighbor is deter-
+mined by the <function>horizDistance</function> and
+<function>vertDistance</function> resources. This
+implies some things about how the order of creation affects
+the possible placement of the children. The Form widget
+registers a string to widget converter which does not post-
+pone conversion and does not cache conversion results.
+</para>
+<para>
+The second layout method is used when the Form is resized.
+It does not matter what causes this resize, and it is possi-
+ble for a resize to happen before the widget becomes visible
+(due to constraints imposed by the parent of the Form).
+This layout method uses the <function>bottom</function>,
+<function>top</function>, <function>left</function>, and
+<function>right</function>
+resources. These resources are used to determine what will
+happen to each edge of the child when the Form is resized.
+If a value of <function>XawChain</function>
+&lt;<emphasis remap='I'>something</emphasis>&gt; is specified, the the edge
+of the child will remain a fixed distance from the
+<emphasis remap='I'>chain</emphasis>
+edge of the Form. For example if <function>XawChainLeft</function> is specified
+for the <function>right</function> resource of a child then the right edge of
+that child will remain a fixed distance from the left edge
+of the Form widget. If a value of <function>XawRubber</function> is specified,
+that edge will grow by the same percentage that the Form
+grew. For instance if the Form grows by 50% the left edge
+of the child (if specified as <function>XawRubber</function> will be 50% farther
+from the left edge of the Form). One must be very careful
+when specifying these resources, for when they are specified
+incorrectly children may overlap or completely occlude other
+children when the Form widget is resized.
+<!-- .LP -->
+<!-- .Lt Form -->
+</para>
+<para>
+<!-- .LP -->
+<informaltable>
+ <tgroup cols='3' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Edge Type</entry>
+ <entry>Resource Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XawChainBottom</entry>
+ <entry>ChainBottom</entry>
+ <entry>Edge remains a fixed distance from bottom of Form</entry>
+ </row>
+ <row>
+ <entry>XawChainLeft</entry>
+ <entry>ChainLeft</entry>
+ <entry>Edge remains a fixed distance from left of Form</entry>
+ </row>
+ <row>
+ <entry>XawChainRight</entry>
+ <entry>ChainRight</entry>
+ <entry>Edge remains a fixed distance from right of Form</entry>
+ </row>
+ <row>
+ <entry>XawChainTop</entry>
+ <entry>ChainTop</entry>
+ <entry>Edge remains a fixed distance from top of Form</entry>
+ </row>
+ <row>
+ <entry>XawRubber</entry>
+ <entry>Rubber</entry>
+ <entry>Edges will move a proportional distance</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<sect3 id="form_example">
+<title>Example</title>
+<para>
+<!-- .LP -->
+If you wish to force the Form to never resize one or more of its
+children, then set <function>left</function> and <function>right</function> to <function>XawChainLeft</function> and
+<function>top</function> and <function>bottom</function> to <function>XawChainTop</function>. This will cause the
+child to remain a fixed distance from the top and left edges of the
+Form, and never to resize.
+</para>
+</sect3>
+</sect2>
+<sect2 id="form_convenience_routines">
+<title>Convenience Routines</title>
+<para>
+<!-- .LP -->
+To force or defer a re-layout of the Form, use
+<!-- .PN XawFormDoLayout . -->
+<!-- .IN "Form widget" "re-layout" -->
+<!-- .IN "XawFormDoLayout" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawFormDoLayout</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Boolean<parameter> do_layout</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Form widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>do_layout</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether the layout of the Form widget is enabled (<function>True</function>)
+or disabled (<function>False</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+When making several changes to the children of a Form widget
+after the Form has been realized, it is a good idea to disable
+relayout until after all changes have been made.
+
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Grip.xml b/libXaw/specs/Grip.xml
new file mode 100644
index 000000000..4e49d5ba0
--- /dev/null
+++ b/libXaw/specs/Grip.xml
@@ -0,0 +1,357 @@
+<sect1 id="Grip_Widget">
+<title>Grip Widget</title>
+<!-- .XS -->
+<!-- Grip Widget -->
+<!-- .XE -->
+<!-- .IN "Grip widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application header file &lt;X11/Xaw/Grip.h&gt;
+<!-- .IN "Grip.h" "" -->
+Class header file &lt;X11/Xaw/GripP.h&gt;
+<!-- .IN "GripP.h" "" -->
+Class gripWidgetClass
+<!-- .IN "gripWidgetClass" "" -->
+Class Name Grip
+<!-- .IN "Grip widget" "class name" -->
+Superclass Simple
+<!-- .sp -->
+</literallayout>
+<para>
+<!-- .LP -->
+The Grip widget provides a small rectangular region in which user input
+events (such as ButtonPress or ButtonRelease) may be handled. The most
+common use for the Grip widget is as an attachment point for visually
+repositioning an object, such as the pane border in a Paned widget.
+</para>
+<sect2 id="grip_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Grip widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "Grip widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>callback</entry>
+ <entry>Callback</entry>
+ <entry>Callback</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>callback</function>
+ </term>
+ <listitem>
+ <para>
+All routines on this list are called whenever the <function>GripAction</function>
+action routine is invoked. The <emphasis remap='I'>call_data</emphasis> contains all
+information passed to the action routine. A detailed description
+is given below in the <function>Grip Actions</function> section.
+<!-- .Cm -->
+<!-- .Cu -->
+<!-- .Cn -->
+<!-- .Dp -->
+<!-- .Dc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>foreground</function>
+ </term>
+ <listitem>
+ <para>
+A pixel value which indexes the widget's colormap to derive the color
+used to flood fill the entire Grip widget.
+<!-- .Hw -->
+<!-- .Ib -->
+<!-- .Ix -->
+<!-- .Mm -->
+<!-- .Pf -->
+<!-- .Pb -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Grip_Actions">
+<title>Grip Actions</title>
+<!-- .IN "Grip widget" "actions" -->
+<para>
+<!-- .LP -->
+The Grip widget does not declare any default event translation bindings,
+but it does declare a single action routine named <function>GripAction</function>. The
+<!-- .IN "Grip widget" "GripAction routine" -->
+client specifies an arbitrary event translation table, optionally giving
+parameters to the <function>GripAction</function> routine.
+</para>
+<para>
+<!-- .LP -->
+The <function>GripAction</function> routine executes the callbacks on the
+<function>callback</function> list, passing as <function>call_data</function> a pointer to a
+<function>XawGripCallData</function> structure, defined in the Grip widget's application
+header file.
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+<!-- .IN "XawGripCallData" "" "@DEF@" -->
+<!-- .IN "XawGripCallDataRec" "" "@DEF@" -->
+<!-- .sp -->
+typedef struct _XawGripCallData {
+ XEvent *event;
+ String *params;
+ Cardinal num_params;
+} XawGripCallDataRec, *XawGripCallData,
+ GripCallDataRec, *GripCallData; /* supported for R4 compatibility */
+<!-- .IN "XawGripCallDataRec" "" -->
+<!-- .IN "XawGripCallData" "" -->
+<!-- .IN "GripCallData" "" -->
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+In this structure, the <emphasis remap='I'>event</emphasis> is a pointer to the input event that
+triggered the action. <emphasis remap='I'>params</emphasis> and <emphasis remap='I'>num_params</emphasis> give the string
+parameters specified in the translation table for the particular event
+binding.
+<!-- .IN "Grip widget" "GripAction table" -->
+</para>
+<para>
+<!-- .LP -->
+The following is an example of a translation table that uses the GripAction:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+<!-- .sp -->
+ &lt;Btn1Down&gt;: GripAction(press)
+ &lt;Btn1Motion&gt;: GripAction(move)
+ &lt;Btn1Up&gt;: GripAction(release)
+<!-- .sp -->
+</literallayout>
+For a complete description of the format of translation tables, see the
+<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Label.xml b/libXaw/specs/Label.xml
new file mode 100644
index 000000000..68962b5bd
--- /dev/null
+++ b/libXaw/specs/Label.xml
@@ -0,0 +1,345 @@
+<sect1 id="Label_Widget">
+<title>Label Widget</title>
+<!-- .XS -->
+<!-- Label Widget -->
+<!-- .XE -->
+<!-- .IN "Label widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application header file &lt;X11/Xaw/Label.h&gt;
+<!-- .IN "Label.h" "" -->
+Class header file &lt;X11/Xaw/LabelP.h&gt;
+<!-- .IN "LabelP.h" "" -->
+Class labelWidgetClass
+<!-- .IN "labelWidgetClass" "" -->
+Class Name Label
+<!-- .IN "Label widget" "class name" -->
+Superclass Simple
+<!-- .sp -->
+</literallayout>
+<para>
+<!-- .LP -->
+A Label widget holds a graphic displayed within a
+rectangular region of the screen. The graphic may be a
+text string containing multiple lines of characters in an
+8 bit or 16 bit character set (to be displayed with a
+<emphasis remap='I'>font</emphasis>), or in a multi-byte encoding (for use with a
+<emphasis remap='I'>fontset</emphasis>). The graphic may also be a bitmap or
+pixmap. The Label widget will allow its graphic to be
+left, right, or center justified. Normally, this widget
+can be neither selected nor directly edited by the user.
+It is intended for use as an output device only.
+</para>
+<sect2 id="label_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Label widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "Label widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>bitmap</entry>
+ <entry>Bitmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>encoding</entry>
+ <entry>Encoding</entry>
+ <entry>UnsignedChar</entry>
+ <entry></entry>
+ <entry>XawTextEncoding8bit</entry>
+ </row>
+ <row>
+ <entry>font</entry>
+ <entry>Font</entry>
+ <entry>XFontStruct</entry>
+ <entry></entry>
+ <entry>XtDefaultFont</entry>
+ </row>
+ <row>
+ <entry>fontSet</entry>
+ <entry>FontSet</entry>
+ <entry>XFontSet</entry>
+ <entry></entry>
+ <entry>XtDefaultFontSet</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>graphic height + 2 * <function>internalHeight</function></entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>internalHeight</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>internalWidth</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>justify</entry>
+ <entry>Justify</entry>
+ <entry>Justify</entry>
+ <entry></entry>
+ <entry>XtJustifyCenter (center)</entry>
+ </row>
+ <row>
+ <entry>label</entry>
+ <entry>Label</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>name of widget</entry>
+ </row>
+ <row>
+ <entry>leftBitmap</entry>
+ <entry>LeftBitmap</entry>
+ <entry>Bitmap</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>resize</entry>
+ <entry>Resize</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>See above</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>graphic width + 2 * <function>internalWidth</function></entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bm Bold -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Cm -->
+<!-- .Cu -->
+<!-- .Cn -->
+<!-- .Dp -->
+<!-- .Dc -->
+<!-- .Le Bold -->
+<!-- .Lf Bold -->
+<!-- .Ls Bold -->
+<!-- .Lg Bold -->
+<!-- .Hw -->
+<!-- .Ib -->
+<!-- .Ih Bold -->
+<!-- .In -->
+<!-- .Ju Bold -->
+<!-- .La Bold -->
+<!-- .Ll Bold -->
+<!-- .Mm -->
+<!-- .Pf -->
+<!-- .Pb -->
+<!-- .Re Bold -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+<!-- .Xy -->
+
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/List.xml b/libXaw/specs/List.xml
new file mode 100644
index 000000000..0bad43dde
--- /dev/null
+++ b/libXaw/specs/List.xml
@@ -0,0 +1,872 @@
+<sect1 id="List_Widget">
+<title>List Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- List Widget -->
+<!-- .XE -->
+<!-- .IN "List widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application header file &lt;X11/Xaw/List.h&gt;
+<!-- .IN "List.h" "" -->
+Class header file &lt;X11/Xaw/ListP.h&gt;
+<!-- .IN "ListP.h" "" -->
+Class listWidgetClass
+<!-- .IN "listWidgetClass" "" -->
+Class Name List
+<!-- .IN "List widget" "class name" -->
+Superclass Simple
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+
+The List widget contains a list of strings formatted into rows and
+columns. When one of the strings is selected, it is highlighted, and the
+List widget's <function>Notify</function> action is invoked, calling all routines on
+its callback list. Only one string may be selected at a time.
+</para>
+<sect2 id="list_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a List widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "List widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>callback</entry>
+ <entry>Callback</entry>
+ <entry>Callback</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>columnSpacing</entry>
+ <entry>Spacing</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>6</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>XC_left_ptr</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>defaultColumns</entry>
+ <entry>Columns</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>font</entry>
+ <entry>Font</entry>
+ <entry>FontStruct</entry>
+ <entry></entry>
+ <entry>XtDefaultFont</entry>
+ </row>
+ <row>
+ <entry>fontSet</entry>
+ <entry>FontSet</entry>
+ <entry>XFontSet</entry>
+ <entry></entry>
+ <entry>XtDefaultFontSet</entry>
+ </row>
+ <row>
+ <entry>forceColumns</entry>
+ <entry>Columns</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Enough space to contain the list</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>internalHeight</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>internalWidth</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>list</entry>
+ <entry>List</entry>
+ <entry>Pointer</entry>
+ <entry></entry>
+ <entry>name of widget</entry>
+ </row>
+ <row>
+ <entry>longest</entry>
+ <entry>Longest</entry>
+ <entry>int</entry>
+ <entry>A</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>numberStrings</entry>
+ <entry>NumberStrings</entry>
+ <entry>int</entry>
+ <entry>A</entry>
+ <entry>computed for NULL terminated list</entry>
+ </row>
+ <row>
+ <entry>pasteBuffer</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>rowSpacing</entry>
+ <entry>Spacing</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>See below</entry>
+ </row>
+ <row>
+ <entry>verticalList</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Enough space to contain the list</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>callback</function>
+ </term>
+ <listitem>
+ <para>
+All functions on this list are called whenever the <function>notify</function> action is
+invoked. The <emphasis remap='I'>call_data</emphasis> argument contains information about the element
+selected and is described in detail in the <function>List Callbacks</function> section.
+<!-- .Cm -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>columnSpacing</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>rowSpacing</function>
+ </term>
+ <listitem>
+ <para>
+The amount of space, in pixels, between each of the rows and columns
+in the list.
+<!-- .Cu -->
+<!-- .Cn -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>defaultColumns</function>
+ </term>
+ <listitem>
+ <para>
+The default number of columns. This value is used when neither the
+width nor the height of the List widget is specified or when
+<function>forceColumns</function> is <function>True</function>.
+<!-- .Dp -->
+<!-- .Dc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>font</function>
+ </term>
+ <listitem>
+ <para>
+The text font to use when displaying the <function>list</function>, when the
+<function>international</function> resource is <function>false</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>fontSet</function>
+ </term>
+ <listitem>
+ <para>
+The text font set to use when displaying the <function>list</function>, when the
+<function>international</function> resource is <function>true</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>forceColumns</function>
+ </term>
+ <listitem>
+ <para>
+Forces the default number of columns to be used regardless of the
+List widget's current size.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>foreground</function>
+ </term>
+ <listitem>
+ <para>
+A pixel value which indexes the widget's colormap to derive the color
+used to paint the text of the list elements.
+<!-- .Hw -->
+<!-- .Ib -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ \fPinternalHeight\fP
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ \fPinternalWidth\fP
+ </term>
+ <listitem>
+ <para>
+The margin, in pixels, between the edges of the list and the
+corresponding edge of the List widget's window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>list</function>
+ </term>
+ <listitem>
+ <para>
+An array of text strings displayed in the List widget. If
+<function>numberStrings</function> is zero (the default) then the <function>list</function> must be
+NULL terminated. If a value is not specified for the <function>list</function>, then
+<function>numberStrings</function> is set to 1, and the name of the widget is used as
+the <function>list</function>, and <function>longest</function> is set to the length of the name of the
+widget. The <function>list</function> is used in place, and must be available
+to the List widget for the lifetime of this widget, or until it is
+changed with <function>XtSetValues</function> or <function>XawListChange</function>.
+<!-- .In -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>longest</function>
+ </term>
+ <listitem>
+ <para>
+Specifies the width, in pixels, of the longest string in the current
+list. The List widget will compute this value if zero (the default)
+is specified. If this resource is set by hand, entries longer than this
+will be clipped to fit.
+<!-- .Mm -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>numberStrings</function>
+ </term>
+ <listitem>
+ <para>
+The number of strings in the current list. If a value of zero (the
+default) is specified, the List widget will compute it. When computing
+the number of strings the List widget assumes that the <function>list</function> is NULL
+terminated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>pasteBuffer</function>
+ </term>
+ <listitem>
+ <para>
+If this resource is set to <function>True</function> then the name of the currently
+selected list element will be put into <function>CUT_BUFFER_0</function>.
+<!-- .Pf -->
+<!-- .Pb -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>verticalList</function>
+ </term>
+ <listitem>
+ <para>
+If this resource is set to <function>True</function> then the list elements will be
+presented in column major order.
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="List_Actions">
+<title>List Actions</title>
+<!-- .IN "List widget" "actions" -->
+<para>
+<!-- .LP -->
+The List widget supports the following actions:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Highlighting and unhighlighting the list element under the
+pointer with <function>Set</function> and <function>Unset</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Processing application callbacks with <function>Notify</function>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The following is the default translation table used by the List Widget:
+<!-- .IN "List widget" "default translation table" -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+&lt;Btn1Down&gt;,&lt;Btn1Up&gt;: Set(\|) Notify(\|)
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The full list of actions supported by List widget is:
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>Set</function>(\|)
+ </term>
+ <listitem>
+ <para>
+<emphasis remap='I'>Sets</emphasis> the list element that is currently under the pointer. To
+inform the user that this element is currently set, it is drawn with
+foreground and background colors reversed. If this action is called when
+there is no list element under the cursor, the currently <emphasis remap='I'>set</emphasis>
+element will be <emphasis remap='I'>unset</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Unset</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Cancels the <emphasis remap='I'>set</emphasis> state of the element under the pointer,
+and redraws it with normal foreground and background colors.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Notify</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Calls all callbacks on the List widget's callback list. Information
+about the currently selected list element is passed in the
+<emphasis remap='I'>call_data</emphasis> argument (see <function>List Callbacks</function> below).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="List_Callbacks">
+<title>List Callbacks</title>
+<!-- .IN "List widget" "callbacks" -->
+<para>
+<!-- .LP -->
+All procedures on the List widget's callback list will have a
+<function>XawListReturnStruct</function> passed to them as <emphasis remap='I'>call_data</emphasis>. The
+structure is defined in the List widget's application header file.
+</para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+<!-- .IN "XawListReturnStruct" "" "@DEF@" -->
+typedef struct _XawListReturnStruct {
+ String string; /* string shown in the list. */
+ int list_index; /* index of the item selected. */
+} XawListReturnStruct;
+<!-- .IN "XawListReturnStruct" "" -->
+<!-- .NT -->
+</literallayout>
+<note><para>
+The <emphasis remap='I'>list_index</emphasis> item used to be called simply <emphasis remap='I'>index</emphasis>.
+Unfortunately, this name collided with a global name defined on some
+operating systems, and had to be changed.
+</para></note>
+<!-- .NE -->
+</sect2>
+<sect2 id="Changing_the_List">
+<title>Changing the List</title>
+<para>
+<!-- .LP -->
+To change the list that is displayed, use
+<function>XawListChange .</function>
+<!-- .IN "XawListChange" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawListChange</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>String*<parameter> list</parameter></paramdef>
+ <paramdef>intnitems,<parameter> longest</parameter></paramdef>
+ <paramdef>Boolean<parameter> resize</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the List widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new list for the List widget to display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nitems</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of items in the <emphasis remap='I'>list</emphasis>. If a value less than 1
+is specified, <emphasis remap='I'>list</emphasis> must be NULL terminated, and the number of
+items will be calculated by the List widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>longest</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of the longest item in the <emphasis remap='I'>list</emphasis> in pixels.
+If a value less than 1 is specified, the List widget will calculate the
+value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resize</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that if <function>True</function> indicates that the
+List widget should try to resize itself after making the change.
+The constraints of the List widget's parent are always enforced,
+regardless of the value specified here.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<function>XawListChange</function>
+will <emphasis remap='I'>unset</emphasis> all list elements that are currently <function>set</function> before
+the list is actually changed. The <emphasis remap='I'>list</emphasis> is used in place, and must
+remain usable for the lifetime of the List widget, or until <emphasis remap='I'>list</emphasis>
+has been changed again with this function or with <function>XtSetValues</function>.
+</para>
+</sect2>
+<sect2 id="Highlighting_an_Item">
+<title>Highlighting an Item</title>
+<para>
+<!-- .LP -->
+To highlight an item in the list, use
+<function>XawListHighlight .</function>
+<!-- .IN "XawListHighlight" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawListHighlight</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> item</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the List widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>item</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an index into the current list that indicates the item to be
+highlighted.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+Only one item can be highlighted at a time.
+If an item is already highlighted when
+<function>XawListHighlight</function>
+is called,
+the highlighted item is unhighlighted before the new item is highlighted.
+</para>
+</sect2>
+<sect2 id="Unhighlighting_an_Item">
+<title>Unhighlighting an Item</title>
+<para>
+<!-- .LP -->
+To unhighlight the currently highlighted item in the list, use
+<function>XawListUnhighlight .</function>
+<!-- .IN "XawListUnhighlight" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawListUnhighlight</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the List widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Retrieving_the_Currently_Selected_Item">
+<title>Retrieving the Currently Selected Item</title>
+<para>
+<!-- .LP -->
+To retrieve the list element that is currently <emphasis remap='I'>set</emphasis>, use
+<function>XawListShowCurrent .</function>
+<!-- .IN "XawListShowCurrent" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XawListReturnStruct<function> *XawListShowCurrent</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the List widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<function>XawListShowCurrent</function>
+returns a pointer to an
+<function>XawListReturnStruct</function>
+structure,
+containing the currently highlighted item.
+If the value of the index member is XAW_LIST_NONE,
+<!-- .IN "XAW_LIST_NONE" -->
+the string member is undefined, and no item is currently selected.
+</para>
+</sect2>
+<sect2 id="Restrictions">
+<title>Restrictions</title>
+<para>
+<!-- .LP -->
+Many programmers create a ``scrolled list'' by putting a List
+widget with many entries as a child of a Viewport widget. The
+List continues to create a window as big as its contents, but
+that big window is only visible where it intersects the parent
+Viewport's window. (I.e., it is ``clipped.'')
+</para>
+<para>
+<!-- .LP -->
+While this is a useful technique, there is a serious drawback.
+X does not support windows above 32,767 pixels in width or
+height, but this height limit will be exceeded by a List's
+window when the List has many entries (i.e., with a 12 point
+font, about 3000 entries would be too many.)
+</para>
+<para>
+<!-- .LP -->
+
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Makefile.am b/libXaw/specs/Makefile.am
new file mode 100644
index 000000000..ebdbd729f
--- /dev/null
+++ b/libXaw/specs/Makefile.am
@@ -0,0 +1,106 @@
+#
+# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice (including the next
+# paragraph) shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+#
+
+if ENABLE_SPECS
+doc_sources = libXaw.xml
+dist_doc_DATA = $(doc_sources) \
+ AsciiSink.xml \
+ AsciiSource.xml \
+ AsciiText.xml \
+ Box.xml \
+ CH1.xml \
+ CH2.xml \
+ CH3.xml \
+ CH4.xml \
+ CH5.xml \
+ CH6.xml \
+ CH7.xml \
+ Command.xml \
+ Dialog.xml \
+ Form.xml \
+ Grip.xml \
+ Label.xml \
+ List.xml \
+ MenuButton.xml \
+ Paned.xml \
+ Panner.xml \
+ Porthole.xml \
+ Repeater.xml \
+ Scrollbar.xml \
+ SimpleMenu.xml \
+ Simple.xml \
+ SmeBSB.xml \
+ SmeLine.xml \
+ Sme.xml \
+ StripChart.xml \
+ Template_private_header_file.xml \
+ Template_public_header_file.xml \
+ Template_widget_source_file.xml \
+ Template.xml \
+ TextActions_default_translation_bindings.xml \
+ TextActions_text_widget_actions.xml \
+ TextActions.xml \
+ TextCustom.xml \
+ TextFuncs.xml \
+ TextSink.xml \
+ TextSource.xml \
+ Text.xml \
+ Toggle.xml \
+ TPage_Credits.xml \
+ Tree.xml \
+ Viewport.xml
+
+if HAVE_XMLTO
+doc_DATA = $(doc_sources:.xml=.html)
+
+if HAVE_FOP
+doc_DATA += $(doc_sources:.xml=.ps) $(doc_sources:.xml=.pdf)
+endif
+
+if HAVE_XMLTO_TEXT
+doc_DATA += $(doc_sources:.xml=.txt)
+endif
+
+if HAVE_STYLESHEETS
+XMLTO_FLAGS = -m $(XSL_STYLESHEET) \
+ --stringparam html.stylesheet=$(STYLESHEET_SRCDIR)/xorg.css
+endif
+
+CLEANFILES = $(doc_DATA)
+
+SUFFIXES = .xml .ps .pdf .txt .html
+
+%.txt: %.xml $(dist_doc_DATA)
+ $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $<
+
+%.html: %.xml $(dist_doc_DATA)
+ $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $<
+
+%.pdf: %.xml $(dist_doc_DATA)
+ $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $<
+
+%.ps: %.xml $(dist_doc_DATA)
+ $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $<
+
+endif HAVE_XMLTO
+endif ENABLE_SPECS
diff --git a/libXaw/specs/MenuButton.xml b/libXaw/specs/MenuButton.xml
new file mode 100644
index 000000000..b907fefb5
--- /dev/null
+++ b/libXaw/specs/MenuButton.xml
@@ -0,0 +1,567 @@
+<sect2 id="MenuButton_Widget">
+<title>MenuButton Widget</title>
+<!-- .XS -->
+<!-- MenuButton Widget -->
+<!-- .XE -->
+<!-- .IN "MenuButton widget" "" "@DEF@" -->
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+Application Header file &lt;X11/Xaw/MenuButton.h&gt;
+<!-- .IN "MenuButton.h" "" -->
+Class Header file &lt;X11/Xaw/MenuButtonP.h&gt;
+<!-- .IN "MenuButtonP.h" "" -->
+Class menuButtonWidgetClass
+<!-- .IN "menuButtonWidgetClass" "" -->
+Class Name MenuButton
+<!-- .IN "MenuButton widget" "class name" -->
+Superclass Command
+</literallayout>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The MenuButton widget is an area, often rectangular,
+that displays a graphic. The graphic may be a text
+string containing multiple lines of characters in an 8
+bit or 16 bit character set (to be displayed with a
+<emphasis remap='I'>font</emphasis>), or in a multi-byte encoding (for use with
+a <emphasis remap='I'>fontset</emphasis>). The graphic may also be a bitmap or
+pixmap.
+</para>
+<para>
+<!-- .LP -->
+When the pointer cursor is on a MenuButton widget, the
+MenuButton becomes highlighted by drawing a rectangle
+around its perimeter. This highlighting indicates
+that the MenuButton is ready for selection. When a
+pointer button is pressed, the MenuButton widget will
+pop up the menu named in the <function>menuName</function> resource.
+</para>
+<sect3 id="Resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a MenuButton widget instance,
+the following resources are retrieved from the argument list
+or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "MenuButton widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>bitmap</entry>
+ <entry>Bitmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>callback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cornerRoundPercent</entry>
+ <entry>CornerRoundPercent</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>25</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>encoding</entry>
+ <entry>Encoding</entry>
+ <entry>UnsignedChar</entry>
+ <entry></entry>
+ <entry>XawTextEncoding8bit</entry>
+ </row>
+ <row>
+ <entry>font</entry>
+ <entry>Font</entry>
+ <entry>XFontStruct</entry>
+ <entry></entry>
+ <entry>XtDefaultFont</entry>
+ </row>
+ <row>
+ <entry>fontSet</entry>
+ <entry>FontSet</entry>
+ <entry>XFontSet</entry>
+ <entry></entry>
+ <entry>XtDefaultFontSet</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>graphic height + 2 * <function>internalHeight</function></entry>
+ </row>
+ <row>
+ <entry>highlightThickness</entry>
+ <entry>Thickness</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>2 (0 if Shaped)</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>internalHeight</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>internalWidth</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>justify</entry>
+ <entry>Justify</entry>
+ <entry>Justify</entry>
+ <entry></entry>
+ <entry>XtJustifyCenter (center)</entry>
+ </row>
+ <row>
+ <entry>label</entry>
+ <entry>Label</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>name of widget</entry>
+ </row>
+ <row>
+ <entry>leftBitmap</entry>
+ <entry>LeftBitmap</entry>
+ <entry>Bitmap</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>menuName</entry>
+ <entry>MenuName</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>"menu"</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>resize</entry>
+ <entry>Resize</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>shapeStype</entry>
+ <entry>ShapeStyle</entry>
+ <entry>ShapeStyle</entry>
+ <entry></entry>
+ <entry>Rectangle</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>See below</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>graphic width + 2 * <function>internalWidth</function></entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bm -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Cb -->
+<!-- .Cm -->
+<!-- .Cr -->
+<!-- .Cu -->
+<!-- .Cn -->
+<!-- .Dp -->
+<!-- .Dc -->
+<!-- .Lf -->
+<!-- .Ls -->
+<!-- .Lg -->
+<!-- .Hw -->
+<!-- .Ht -->
+<!-- .Ib -->
+<!-- .Ih -->
+<!-- .In -->
+<!-- .Ju -->
+<!-- .La -->
+<!-- .Mm -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>menuName</function>
+ </term>
+ <listitem>
+ <para>
+The name of a popup shell to popup as a menu. The MenuButton
+will search for this name using <function>XtNameToWidget</function> starting
+with itself as the reference widget. If the search is
+unsuccessful the widget will continue up the widget tree using
+each of its ancestors as the reference widget passed to
+<function>XtNameToWidget</function>. If no widget of called <function>menuName</function> is
+found by this algorithm, the widget will print a warning message
+and give up. When the menu is found it will be popped up
+exclusive and spring_loaded. The MenuButton widget does not
+copy the value of this resource into newly allocated memory. The
+application programmer must pass the resource value in
+nonvolatile memory.
+<!-- .Pf -->
+<!-- .Pb -->
+<!-- .Re -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Ss -->
+<!-- .Tr -->
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect3>
+<sect3 id="MenuButton_Actions">
+<title>MenuButton Actions</title>
+<!-- .IN "MenuButton widget" "actions" -->
+<para>
+<!-- .LP -->
+The MenuButton widget supports the following actions:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Switching the button between the foreground and background
+colors with <function>set</function> and <function>unset</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Processing application callbacks with <function>notify</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Switching the internal border between highlighted
+and unhighlighted states with <function>highlight</function> and <function>unhighlight</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Popping up a menu with <function>PopupMenu</function>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The following are the default translation bindings used by the
+MenuButton widget:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+ &lt;EnterWindow&gt;: highlight(\|)
+ &lt;LeaveWindow&gt;: reset(\|)
+ &lt;BtnDown&gt;: reset(\|) PopupMenu(\)
+</literallayout>
+</para>
+</sect3>
+<sect3 id="MenuButton_Actions_b">
+<title>MenuButton Actions_b</title>
+<para>
+<!-- .LP -->
+The full list of actions supported by MenuButton is:
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>highlight</function>(<function>condition</function>)
+ </term>
+ <listitem>
+ <para>
+Displays the internal highlight border in the color (<function>foreground</function>
+or <function>background</function> ) that contrasts with the interior color of the
+Command widget. The conditions <function>WhenUnset</function> and <function>Always</function> are
+understood by this action procedure. If no argument is passed,
+<function>WhenUnset</function> is assumed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>unhighlight</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Displays the internal highlight border in the color (<function>XtNforeground</function>
+or <function>background</function> ) that matches the interior color of the
+MenuButton widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>set</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Enters the <function>set</function> state, in which <function>notify</function> is possible. This
+action causes the button to display its interior in the
+<function>foreground</function> color. The label or bitmap is displayed in the
+<function>background</function> color.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>unset</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Cancels the <emphasis remap='I'>set</emphasis> state and displays the interior of the button in the
+<function>background</function> color. The label or bitmap is displayed in the
+<function>foreground</function> color.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>reset</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Cancels any <function>set</function> or <function>highlight</function> and displays the interior of the
+button in the <function>background</function> color, with the label displayed in the
+<function>foreground</function> color.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>notify</function>(\|)
+ </term>
+ <listitem>
+ <para>
+When the button is in the <function>set</function> state this action calls all functions in
+the callback list named by the <function>callback</function> resource. The value of
+the call_data argument in these callback functions is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>PopupMenu</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Pops up the menu specified by the <function>menuName</function> resource.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+The MenuButton widget does not place a server grab on itself.
+Instead, PopupMenu is registered as a grab action.
+As a result, clients which popup menus without using XtMenuPopup
+or MenuPopup or PopupMenu in translations will fail to have a grab active.
+They should make a call to XtRegisterGrabAction on the appropriate action
+in the application initialization routine, or use a different translation.
+<!-- .bp -->
+
+</para>
+</sect3>
+</sect2>
diff --git a/libXaw/specs/Paned.xml b/libXaw/specs/Paned.xml
new file mode 100644
index 000000000..90c3809cc
--- /dev/null
+++ b/libXaw/specs/Paned.xml
@@ -0,0 +1,1213 @@
+<sect1 id="Paned_Widget">
+<title>Paned Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Paned Widget -->
+<!-- .XE -->
+<!-- .IN "Paned widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file &lt;X11/Xaw/Paned.h&gt;
+<!-- .IN "Paned.h" "" -->
+Class Header file &lt;X11/Xaw/PanedP.h&gt;
+<!-- .IN "PanedP.h" "" -->
+Class panedWidgetClass
+<!-- .IN "panedWidgetClass" "" -->
+Class Name Paned
+<!-- .IN "Paned widget" "class name" -->
+Superclass Constraint
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The Paned widget manages children in a vertically or horizontally
+tiled fashion. The panes may be dynamically resized by the user by
+using the <emphasis remap='I'>grips</emphasis> that appear near the right or bottom edge of the
+border between two panes.
+</para>
+<para>
+<!-- .LP -->
+The Paned widget may accept any widget class as a pane <function>except</function>
+Grip. Grip widgets have a special meaning for the Paned widget, and
+adding a Grip as its own pane will confuse the Paned widget.
+</para>
+<sect2 id="Using_the_Paned_Widget">
+<title>Using the Paned Widget</title>
+<!-- .IN "Paned widget" "using" -->
+<para>
+<!-- .LP -->
+The grips allow the panes to be resized by the user. The semantics of
+how these panes resize is somewhat complicated, and warrants further
+explanation here. When the mouse pointer is positioned on a grip and
+pressed, an arrow is displayed that indicates the pane that is to be to
+be resized. While keeping the mouse button down, the user can move the
+grip up and down (or left and right). This, in turn, changes the size
+of the pane. The size of the Paned widget will not change. Instead,
+it chooses another pane (or panes) to resize. For more details on which
+pane it chooses to resize, see <function>Layout Semantics</function>.
+</para>
+<para>
+<!-- .LP -->
+One pointer binding allows the border between two panes to be moved,
+without affecting any of the other panes. When this occurs the pointer
+will change to an arrow that points along the pane border.
+</para>
+<para>
+<!-- .LP -->
+The default bindings for the Paned widget's grips are:
+<informaltable>
+ <tgroup cols='3' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Mouse button</entry>
+ <entry>Pane to Resize - Vertical</entry>
+ <entry>Pane to Resize - Horizontal</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>1 (left)</entry>
+ <entry>above the grip</entry>
+ <entry>left of the grip</entry>
+ </row>
+ <row>
+ <entry>2 (middle)</entry>
+ <entry>adjust border</entry>
+ <entry>adjust border</entry>
+ </row>
+ <row>
+ <entry>3 (right)</entry>
+ <entry>below the grip</entry>
+ <entry>right of the grip</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+</sect2>
+<sect2 id="paned_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Paned widget instance, the following resources are
+retrieved from the argument list or the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "Paned widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>betweenCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry>A</entry>
+ <entry>Depends on orientation</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>children</entry>
+ <entry>ReadOnly</entry>
+ <entry>WidgetList</entry>
+ <entry>R</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>gripCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry>A</entry>
+ <entry>Depends on orientation</entry>
+ </row>
+ <row>
+ <entry>gripIndent</entry>
+ <entry>GripIndent</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>10</entry>
+ </row>
+ <row>
+ <entry>gripTranslations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>see below</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Depends on orientation</entry>
+ </row>
+ <row>
+ <entry>horizontalBetweenCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>sb_up_arrow</entry>
+ </row>
+ <row>
+ <entry>horizontalGripCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>sb_h_double_arrow</entry>
+ </row>
+ <row>
+ <entry>internalBorderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>internalBorderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>leftCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>sb_left_arrow</entry>
+ </row>
+ <row>
+ <entry>lowerCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>sb_down_arrow</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>numChildren</entry>
+ <entry>ReadOnly</entry>
+ <entry>Cardinal</entry>
+ <entry>R</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>orientation</entry>
+ <entry>Orientation</entry>
+ <entry>Orientation</entry>
+ <entry></entry>
+ <entry>XtorientVertical</entry>
+ </row>
+ <row>
+ <entry>refigureMode</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>rightCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>sb_right_arrow</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>upperCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>sb_up_arrow</entry>
+ </row>
+ <row>
+ <entry>verticalBetweenCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>sb_left_arrow</entry>
+ </row>
+ <row>
+ <entry>verticalGripCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>sb_v_double_arrow</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Depends on orientation</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Paned</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Paned</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Ch -->
+<!-- .Cm -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>cursor</function>
+ </term>
+ <listitem>
+ <para>
+The cursor to use when the mouse pointer is over the Paned widget, but
+not in any of its children (children may also inherit this cursor). It
+should be noted that the internal borders are actually part of the Paned
+widget, not the children.
+<!-- .Dp -->
+<!-- .Dc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>gripCursor</function>
+ </term>
+ <listitem>
+ <para>
+The cursor to use when the grips are not active. The default value is
+<function>verticalGripCursor</function> or <function>horizontalGripCursor</function> depending on
+the orientation of the Paned widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>gripIndent</function>
+ </term>
+ <listitem>
+ <para>
+The amount of space left between the right (or bottom) edge of the
+Paned widget and all the grips.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>gripTranslation</function>
+ </term>
+ <listitem>
+ <para>
+Translation table that will be applied to all grips.
+<!-- .Hw -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>horizontalBetweenCursor</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>verticalBetweenCursor</function>
+ </term>
+ <listitem>
+ <para>
+The cursor to be used for the grip when changing the boundary between
+two panes. These resources allow the cursors to be different
+depending on the orientation of the Paned widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>horizontalGripCursor</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>verticalGripCursor</function>
+ </term>
+ <listitem>
+ <para>
+The cursor to be used for the grips when they are not active. These
+resources allow the cursors to be different depending on the
+orientation of the Paned widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>internalBorderColor</function>
+ </term>
+ <listitem>
+ <para>
+A pixel value which indexes the widget's colormap to derive the internal
+border color of the widget's window. The class name of this resource
+allows <emphasis remap='I'>Paned*BorderColor: blue</emphasis> to set the internal border color
+for the Paned widget. An optimization is invoked if
+<function>internalBorderColor</function> and <function>background</function> are the same, and the
+internal borders are not drawn. <function>internalBorderWidth</function> is still left
+between the panes, however.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>internalBorderWidth</function>
+ </term>
+ <listitem>
+ <para>
+The width of the internal borders. This is the amount of space left
+between the panes. The class name of this resource allows
+<emphasis remap='I'>Paned*BorderWidth: 3</emphasis> to set the internal border width for the
+Paned widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>leftCursor</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>rightCursor</function>
+ </term>
+ <listitem>
+ <para>
+The cursor used to indicate which is the <emphasis remap='I'>important</emphasis> pane to resize
+when the Paned widget is oriented horizontally.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>lowerCursor</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>upperCursor</function>
+ </term>
+ <listitem>
+ <para>
+The cursor used to indicate which is the <emphasis remap='I'>important</emphasis> pane to resize
+when the Paned widget is oriented vertically.
+<!-- .Mm -->
+<!-- .Nc -->
+This is not the same as the number of panes, since this also contains a
+grip for some of the panes, use <function>XawPanedGetNumSub</function> to retrieve the
+number of panes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>orientation</function>
+ </term>
+ <listitem>
+ <para>
+The orientation to stack the panes. This value can be either
+<function>XtorientVertical</function> or <function>XtorientHorizontal</function>.
+<!-- .IN "XtorientVertical" "" -->
+<!-- .IN "XtorientHorizontal" "" -->
+<!-- .IN "conversions" "Orientation" -->
+<!-- .Rs "vertical \fPand\fB horizontal" -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>refigureMode</function>
+ </term>
+ <listitem>
+ <para>
+This resource allows pane layout to be suspended. If this value is
+<function>False</function>, then no layout actions will be taken. This may improve
+efficiency when adding or removing more than one pane from the Paned
+widget.
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="paned_constraint_resources">
+<title>Constraint Resources</title>
+<para>
+<!-- .LP -->
+<!-- .IN "Paned widget" "constraint resources" -->
+Each child of the Paned widget may request special layout resources
+be applied to it. These <emphasis remap='I'>constraint</emphasis> resources allow the Paned
+widget's children to specify individual layout requirements.
+</para>
+<para>
+<!-- .LP -->
+<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>allowResize</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>max</entry>
+ <entry>Max</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>Infinity</entry>
+ </row>
+ <row>
+ <entry>min</entry>
+ <entry>Min</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>Height of Grips</entry>
+ </row>
+ <row>
+ <entry>preferredPaneSize</entry>
+ <entry>PreferredPaneSize</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>ask child</entry>
+ </row>
+ <row>
+ <entry>resizeToPreferred</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>showGrip</entry>
+ <entry>ShowGrip</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>skipAdjust</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>allowResize</function>
+ </term>
+ <listitem>
+ <para>
+If this value is <function>False</function> the the Paned widget will disallow all
+geometry requests from this child.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>max</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>min</function>
+ </term>
+ <listitem>
+ <para>
+The absolute maximum or minimum size for this pane. These values will
+never be overridden by the Paned widget. This may cause some panes to be
+pushed off the bottom (or right) edge of the paned widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>preferredPaneSize</function>
+ </term>
+ <listitem>
+ <para>
+Normally the paned widget makes a QueryGeometry call on a child to
+determine the preferred size of the child's pane. There are times
+when the application programmer or the user has a better idea of the
+preferred size of a pane. Setting this resource causes the value
+passed to be interpreted as the preferred size, in pixels, of this pane.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>resizeToPreferred</function>
+ </term>
+ <listitem>
+ <para>
+Determines whether or not to resize each pane to its preferred size
+when the Paned widget is resized. See <function>Layout Semantics</function> for details.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>showGrip</function>
+ </term>
+ <listitem>
+ <para>
+If <function>True</function> then a grip will be shown for this pane. The grip
+associated with a pane is either below or to the right of the pane. No
+grip is ever shown for the last pane.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>skipAdjust</function>
+ </term>
+ <listitem>
+ <para>
+This resource is used to determine which pane is forced to be resized.
+Setting this value to <function>True</function> makes this pane less likely to be
+forced to be resized. See <function>Layout Semantics</function> for details.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="paned_layout_semantics">
+<title>Layout Semantics</title>
+<para>
+<!-- .LP -->
+<!-- .IN "Paned widget" "layout semantics" -->
+In order to make effective use of the Paned widget it is helpful to know
+the rules it uses to determine which child will be resized in any given
+situation. There are three rules used to determine which child is
+resized. While these rules are always the same, the panes that are
+searched can change depending upon what caused the relayout.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<function>Layout Rules</function>
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>1</function>
+ </term>
+ <listitem>
+ <para>
+Do not let a pane grow larger than its <function>max</function> or smaller than its
+<function>min</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>2</function>
+ </term>
+ <listitem>
+ <para>
+Do not adjust panes with <function>skipAdjust</function> set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>3</function>
+ </term>
+ <listitem>
+ <para>
+Do not adjust panes away from their preferred size, although moving one
+closer to its preferred size is fine.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+When searching the children the Paned widget looks for panes that
+satisfy all the rules, and if unsuccessful then it eliminates rule 3
+and then 2. Rule 1 is always enforced.
+</para>
+<para>
+<!-- .LP -->
+If the relayout is due to a resize or change in management then the
+panes are searched from bottom to top. If the relayout is due to grip
+movement then they are searched from the grip selected in the direction
+opposite the pane selected.
+</para>
+<sect3 id="Resizing_Panes_from_a_Grip_Action">
+<title>Resizing Panes from a Grip Action</title>
+<para>
+<!-- .LP -->
+The pane above the grip is resized by invoking the GripAction with
+<function>UpLeftPane</function> specified. The panes below the grip are each checked
+against all rules, then rules 2 and 1 and finally against rule 1 only.
+No pane above the chosen pane will ever be resized.
+</para>
+<para>
+<!-- .LP -->
+The pane below the grip is resized by invoking the GripAction with
+<function>LowRightPane</function> specified. The panes above the grip are each
+checked in this case. No pane below the chosen pane will ever be resized.
+</para>
+<para>
+<!-- .LP -->
+Invoking GripAction with <function>ThisBorderOnly</function> specified just moves the
+border between the panes. No other panes are ever resized.
+</para>
+</sect3>
+<sect3 id="Resizing_Panes_after_the_Paned_widget_is_resized_">
+<title>Resizing Panes after the Paned widget is resized.</title>
+<para>
+<!-- .LP -->
+When the Pane widget is resized it must determine a new size for each
+pane. There are two methods of doing this. The Paned widget can either
+give each pane its preferred size and then resize the panes to fit, or
+it can use the current sizes and then resize the panes to fit. The
+<function>resizeToPreferred</function> resource allows the application to tell the
+Paned widget whether to query the child about its preferred size
+(subject to the the <function>preferredPaneSize</function>) or to use the current size
+when refiguring the pane locations after the pane has been resized.
+</para>
+<para>
+<!-- .LP -->
+There is one special case. All panes assume they should resize to
+their preferred size until the Paned widget becomes visible to the user.
+</para>
+</sect3>
+<sect3 id="Managing_Children_and_Geometry_Management">
+<title>Managing Children and Geometry Management</title>
+<para>
+<!-- .LP -->
+The Paned widget always resizes its children to their preferred sizes when
+a new child is managed, or a geometry management request is honored.
+The Paned widget will first attempt to resize itself to contain its
+panes exactly. If this is not possible then it will hunt through the
+children, from bottom to top (right to left), for a pane to resize.
+</para>
+</sect3>
+<sect3 id="paned_special_considerations">
+<title>Special Considerations</title>
+<para>
+<!-- .LP -->
+When a user resizes a pane with the grips, the Paned widget assumes that
+this new size is the preferred size of the pane.
+</para>
+</sect3>
+</sect2>
+<sect2 id="Grip_Translations">
+<title>Grip Translations</title>
+<para>
+<!-- .LP -->
+The Paned widget has no action routines of its own, as all actions are
+handled through the grips. The grips are each assigned a default
+Translation table.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+ &lt;Btn1Down&gt;: GripAction(Start, UpLeftPane)
+<!-- .IN "GripAction" "" -->
+ &lt;Btn2Down&gt;: GripAction(Start, ThisBorderOnly)
+ &lt;Btn3Down&gt;: GripAction(Start, LowRightPane)
+ &lt;Btn1Motion&gt;: GripAction(Move, UpLeftPane)
+ &lt;Btn2Motion&gt;: GripAction(Move, ThisBorderOnly)
+ &lt;Btn3Motion&gt;: GripAction(Move, LowRightPane)
+ Any&lt;BtnUp&gt;: GripAction(Commit)
+</literallayout>
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+The Paned widget interprets the <function>GripAction</function> as taking two arguments.
+<!-- .IN "GripAction" "" -->
+The first argument may be any of the following:
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>Start</function>
+ </term>
+ <listitem>
+ <para>
+Sets up the Paned widget for resizing and changes the cursor of the
+grip. The second argument determines which pane will be resized, and
+can take on any of the three values shown above.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Move</function>
+ </term>
+ <listitem>
+ <para>
+The internal borders are drawn over the current pane locations to
+animate where the borders would actually be placed if you were to move
+this border as shown. The second argument must match the second argument
+that was passed to the <function>Start</function> action, that began this process. If
+these arguments are not passed, the behavior is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Commit</function>
+ </term>
+ <listitem>
+ <para>
+This argument causes the Paned widget to commit the changes selected
+by the previously started action. The cursor is changed back to the
+grip's inactive cursor. No second argument is needed in this case.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="paned_convenience_routines">
+<title>Convenience Routines</title>
+<para>
+<!-- .LP -->
+<!-- .IN "Paned widget" "enable pane resizing" -->
+<!-- .IN "Paned widget" "disable pane resizing" -->
+To enable or disable a child's request for pane resizing,
+use
+<function>XawPanedAllowResize :</function>
+<!-- .IN "XawPanedAllowResize" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawPanedAllowResize</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Boolean<parameter> allow_resize</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the child pane.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>allow_resize</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether or not resizing requests for this child will be
+granted by the Paned widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+If allow_resize is <function>True</function>, the Paned widget allows geometry
+requests from the child to change the pane's height. If allow_resize
+is <function>False</function>, the Paned widget ignores geometry requests from the
+child to change the pane's height. The default state is <function>True</function>
+before the Pane is realized and <function>False</function> after it is realized.
+This procedure is equivalent to changing the <function>allowResize</function>
+constraint resource for the child.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .IN "Paned widget" "change height settings" -->
+To change the minimum and maximum height settings for a pane, use
+<function>XawPanedSetMinMax :</function>
+<!-- .IN "XawPanedSetMinMax" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawPanedSetMinMax</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>intmin,<parameter> max</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the child pane.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>min</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new minimum height of the child, expressed in pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>max</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies new maximum height of the child, expressed in pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This procedure is equivalent to setting the <function>min</function> and <function>max</function>
+constraint resources for the child.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .IN "Paned widget" "get height settings" -->
+To retrieve the minimum and maximum height settings for a pane, use
+<function>XawPanedGetMinMax :</function>
+<!-- .IN "XawPanedGetMinMax" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawPanedGetMinMax</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>int*min_return,<parameter> *max_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the child pane.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>min_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the minimum height of the child, expressed in pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>max_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the maximum height of the child, expressed in pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This procedure is equivalent to getting the <function>min</function> and <function>max</function>
+resources for this child child.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .IN "Paned widget" "enable auto-reconfiguring" -->
+<!-- .IN "Paned widget" "disable auto-reconfiguring" -->
+To enable or disable automatic recalculation of pane sizes and positions,
+use
+<function>XawPanedSetRefigureMode :</function>
+<!-- .IN "XawPanedSetRefigureMode" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawPanedSetRefigureMode</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Boolean<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Paned widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether the layout of the Paned widget is enabled (<function>True</function>)
+or disabled (<function>False</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+When making several changes to the children of a Paned widget
+after the Paned has been realized, it is a good idea to disable
+relayout until after all changes have been made.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .IN "Paned widget" "getting the number of children" -->
+To retrieve the number of panes in a paned widget use
+<function>XawPanedGetNumSub</function>:
+<!-- .IN "XawPanedGetNumSub" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XawPanedGetNumSub</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Paned widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function returns the number of panes in the Paned widget. This is
+<function>not</function> the same as the number of children, since the grips are also
+children of the Paned widget.
+
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Panner.xml b/libXaw/specs/Panner.xml
new file mode 100644
index 000000000..a04bb1a96
--- /dev/null
+++ b/libXaw/specs/Panner.xml
@@ -0,0 +1,734 @@
+<sect1 id="Panner_Widget">
+<title>Panner Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Panner Widget -->
+<!-- .XE -->
+<!-- .IN "Panner widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application header file &lt;X11/Xaw/Panner.h&gt;
+<!-- .IN "Panner.h" "" -->
+Class header file &lt;X11/Xaw/PannerP.h&gt;
+<!-- .IN "PannerP.h" "" -->
+Class pannerWidgetClass
+<!-- .IN "pannerWidgetClass" "" -->
+Class Name Panner
+<!-- .IN "Panner widget" "class name" -->
+Superclass Simple
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+A Panner widget is a rectangle, called the
+``canvas,'' on which another rectangle, the ``slider,'' moves in two
+dimensions. It is often used with a Porthole widget to move, or
+``scroll,'' a third widget in two dimensions, in which case the
+slider's size and position gives feedback as to what portion of
+the third widget is visible.
+</para>
+<para>
+<!-- .LP -->
+The slider may be scrolled around the canvas by pressing,
+dragging, and releasing Button1; the default translation also
+enables scrolling via arrow keys and some other keys. While
+scrolling is in progress, the application receives notification
+through callback procedures. Notification may be done either
+continuously whenever the slider moves or discretely whenever the
+slider has been given a new location.
+</para>
+<sect2 id="panner_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Panner widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "Panner widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>allowOff</entry>
+ <entry>AllowOff</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>backgroundStipple</entry>
+ <entry>BackgroundStipple</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>canvasHeight</entry>
+ <entry>CanvasHeight</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>canvasWidth</entry>
+ <entry>CanvasWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>defaultScale</entry>
+ <entry>DefaultScale</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>depends on orientation</entry>
+ </row>
+ <row>
+ <entry>internalSpace</entry>
+ <entry>InternalSpace</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>lineWidth</entry>
+ <entry>LineWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>reportCallback</entry>
+ <entry>ReportCallback</entry>
+ <entry>Callback</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>resize</entry>
+ <entry>Resize</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>rubberBand</entry>
+ <entry>RubberBand</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>shadowColor</entry>
+ <entry>ShadowColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>shadowThickness</entry>
+ <entry>ShadowThickness</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>sliderX</entry>
+ <entry>SliderX</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>sliderY</entry>
+ <entry>SliderY</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>sliderHeight</entry>
+ <entry>SliderHeight</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>sliderWidth</entry>
+ <entry>SliderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>See below</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>depends on orientation</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<!-- .Ac -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>allowOff</function>
+ </term>
+ <listitem>
+ <para>
+Whether to allow the edges of the slider to go off the edges of the canvas.
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>backgroundStipple</function>
+ </term>
+ <listitem>
+ <para>
+The name of a bitmap pattern to be used as the background for
+the area representing the canvas.
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>canvasHeight</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>canvasWidth</function>
+ </term>
+ <listitem>
+ <para>
+The size of the canvas.
+<!-- .Cm -->
+<!-- .Cu -->
+<!-- .Cn -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>defaultScale</function>
+ </term>
+ <listitem>
+ <para>
+The percentage size that the Panner widget should have relative
+to the size of the canvas.
+<!-- .Dp -->
+<!-- .Dc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>foreground</function>
+ </term>
+ <listitem>
+ <para>
+A pixel value which indexes the widget's colormap to derive the color
+used to draw the slider.
+<!-- .Hw -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>internalSpace</function>
+ </term>
+ <listitem>
+ <para>
+The width of internal border in pixels between a slider representing the
+full size of the canvas
+and the edge of the Panner widget.
+<!-- .Ix -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>lineWidth</function>
+ </term>
+ <listitem>
+ <para>
+The width of the lines in the rubberbanding rectangle when rubberbanding
+is in effect instead of continuous scrolling. The default is 0.
+<!-- .Mm -->
+<!-- .Pf -->
+<!-- .Pb -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>reportCallback</function>
+ </term>
+ <listitem>
+ <para>
+All functions on this callback list are called when the
+<function>notify</function> action is invoked. See the <function>Panner Actions</function> section
+for details.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>resize</function>
+ </term>
+ <listitem>
+ <para>
+Whether or not to resize the panner whenever the canvas size is changed so
+that the <function>defaultScale</function> is maintained.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>rubberBand</function>
+ </term>
+ <listitem>
+ <para>
+Whether or not scrolling should be discrete (only moving a rubberbanded
+rectangle until the scrolling is done) or continuous (moving the slider
+itself). This controls whether or not the <function>move</function> action procedure also
+invokes the <function>notify</function> action procedure.
+<!-- .Sc -->
+<!-- .Se -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>shadowColor</function>
+ </term>
+ <listitem>
+ <para>
+The color of the shadow underneath the slider.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>shadowThickness</function>
+ </term>
+ <listitem>
+ <para>
+The width of the shadow underneath the slider.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>sliderX</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>sliderY</function>
+ </term>
+ <listitem>
+ <para>
+The location of the slider in the coordinates of the canvas.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>sliderHeight</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>sliderWidth</function>
+ </term>
+ <listitem>
+ <para>
+The size of the slider.
+<!-- .Tr -->
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect2>
+<sect2 id="Panner_Actions">
+<title>Panner Actions</title>
+<!-- .IN "Panner widget" "actions" -->
+<para>
+<!-- .LP -->
+The actions supported by the Panner widget are:
+</para>
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>start</function>()
+ </term>
+ <listitem>
+ <para>
+This action begins movement of the slider.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>stop</function>()
+ </term>
+ <listitem>
+ <para>
+This action ends movement of the slider.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>abort</function>()
+ </term>
+ <listitem>
+ <para>
+This action ends movement of the slider and restores it to the position it
+held when the <function>start</function> action was invoked.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>move</function>()
+ </term>
+ <listitem>
+ <para>
+This action moves the outline of the slider (if the <function>rubberBand</function> resource
+is True) or the slider itself (by invoking the <function>notify</function>
+action procedure).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>page</function>(<function>xamount</function>,<function>yamount</function>)
+ </term>
+ <listitem>
+ <para>
+This action moves the slider by the specified amounts. The format
+for the amounts is a signed or unsigned floating-point number (e.g., +1.0
+or \-.5) followed
+by either <function>p</function> indicating pages (slider sizes), or <function>c</function> indicating
+canvas sizes. Thus, <emphasis remap='I'>page(+0,+.5p)</emphasis> represents vertical movement down
+one-half the height of the slider and <emphasis remap='I'>page(0,0)</emphasis> represents moving to
+the upper left corner of the canvas.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>notify</function>()
+ </term>
+ <listitem>
+ <para>
+This action informs the application of the slider's current position by
+invoking the <function>reportCallback</function> functions registered by the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>set</function>(<function>what</function>,<function>value</function>)
+ </term>
+ <listitem>
+ <para>
+This action changes the behavior of the Panner. The <emphasis remap='I'>what</emphasis> argument
+must currently be the string <function>rubberband</function> and controls the value of
+the <function>rubberBand</function> resource. The <function>value</function> argument
+may have one of the values <function>on</function>, <function>off</function>, or <function>toggle</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The default bindings for Panner are:
+<!-- .IN "Panner widget" "default translation table" -->
+</para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.75i -->
+<!-- .ta .5i 1.75i -->
+ &lt;Btn1Down&gt;: start(\|)
+ &lt;Btn1Motion&gt;: move(\|)
+ &lt;Btn1Up&gt;: notify(\|) stop(\|)
+ &lt;Btn2Down&gt;: abort(\|)
+ &lt;Key&gt;KP_Enter: set(rubberband,toggle)
+ &lt;Key&gt;space: page(+1p,+1p)
+ &lt;Key&gt;Delete: page(\-1p,\-1p)
+ &lt;Key&gt;BackSpace: page(\-1p,\-1p)
+ &lt;Key&gt;Left: page(\-.5p,+0)
+ &lt;Key&gt;Right: page(+.5p,+0)
+ &lt;Key&gt;Up: page(+0,\-.5p)
+ &lt;Key&gt;Down: page(+0,+.5p)
+ &lt;Key&gt;Home: page(0,0)
+</literallayout>
+</sect2>
+
+<sect2 id="Panner_Callbacks">
+<title>Panner Callbacks</title>
+<!-- .IN "Panner widget" "callbacks" -->
+<para>
+<!-- .LP -->
+The functions registered on the <function>reportCallback</function> list are invoked by
+the <function>notify</function> action as follows:
+<!-- .IN "ReportProc" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> ReportProc</function></funcdef>
+ <paramdef>Widget<parameter> panner</parameter></paramdef>
+ <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XtPointer<parameter> report</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+ </para>
+<para>
+<variablelist>
+ <varlistentry>
+ <term>panner</term>
+ <listitem>
+ <para>
+<!-- .IP <emphasis remap='I'>panner</emphasis> 1i -->
+Specifies the Panner widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>panner</term>
+ <listitem>
+ <para>
+<!-- .IP <emphasis remap='I'>client_data</emphasis> 1i -->
+Specifies the client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>panner</term>
+ <listitem>
+ <para>
+<!-- .IP <emphasis remap='I'>report</emphasis> 1i -->
+Specifies a pointer to an <function>XawPannerReport</function> structure containing
+the location and size of the slider and the size of the canvas.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Porthole.xml b/libXaw/specs/Porthole.xml
new file mode 100644
index 000000000..beda434ee
--- /dev/null
+++ b/libXaw/specs/Porthole.xml
@@ -0,0 +1,306 @@
+<sect1 id="Porthole_Widget">
+<title>Porthole Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Porthole Widget -->
+<!-- .XE -->
+<!-- .IN "Porthole widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file &lt;X11/Xaw/Porthole.h&gt;
+<!-- .IN "Porthole.h" "" -->
+Class Header file &lt;X11/Xaw/PortholeP.h&gt;
+<!-- .IN "PortholeP.h" "" -->
+Class portholeWidgetClass
+<!-- .IN "portholeWidgetClass" "" -->
+Class Name Porthole
+<!-- .IN "Porthole widget" "class name" -->
+Superclass Composite
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The Porthole widget provides geometry management of a list of arbitrary
+widgets, only one of which may be managed at any particular time.
+The managed child widget is reparented within the porthole and is moved around
+by the application (typically under the control of a Panner widget).
+</para>
+<sect2 id="porthole_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Porthole widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "Porthole widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>children</entry>
+ <entry>ReadOnly</entry>
+ <entry>WidgetList</entry>
+ <entry>R</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>see <function>Layout Semantics</function></entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>numChildren</entry>
+ <entry>ReadOnly</entry>
+ <entry>Cardinal</entry>
+ <entry>R</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>reportCallback</entry>
+ <entry>ReportCallback</entry>
+ <entry>Callback</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>see <function>Layout Semantics</function></entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Ch -->
+<!-- .Cm -->
+<!-- .Dp -->
+<!-- .Dc -->
+<!-- .Hw -->
+<!-- .Mm -->
+<!-- .Nc -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>reportCallback</function>
+ </term>
+ <listitem>
+ <para>
+A list of functions to invoke whenever the managed child widget changes
+size or position.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+<!-- .Xy -->
+</para>
+</sect2>
+<sect2 id="porthold_layout_semantics">
+<title>Layout Semantics</title>
+<!-- .IN "Porthole widget" "layout semantics" -->
+<para>
+<!-- .LP -->
+The Porthole widget allows its managed child to request any size
+that is as large
+or larger than the Porthole itself and any location so long as the child
+still obscures all of the Porthole. This widget typically is used with a
+Panner widget.
+</para>
+</sect2>
+<sect2 id="Porthole_Callbacks">
+<title>Porthole Callbacks</title>
+<!-- .IN "Porthole widget" "callbacks" -->
+<para>
+<!-- .LP -->
+The functions registered on the <function>reportCallback</function> list are invoked whenever
+the managed child changes size or position:
+<!-- .IN "ReportProc" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> ReportProc</function></funcdef>
+ <paramdef>Widget<parameter> porthole</parameter></paramdef>
+ <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XtPointer<parameter> report</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+</para>
+<variablelist>
+ <varlistentry>
+ <term>porthole</term>
+ <listitem>
+ <para>
+<!-- .IP <emphasis remap='I'>porthole</emphasis> 1i -->
+Specifies the Porthole widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>client_data</term>
+ <listitem>
+ <para>
+<!-- .IP <emphasis remap='I'>client_data</emphasis> 1i -->
+Specifies the client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>report</term>
+ <listitem>
+ <para>
+<!-- .IP <emphasis remap='I'>report</emphasis> 1i -->
+Specifies a pointer to an <function>XawPannerReport</function> structure containing
+the location and size of the slider and the size of the canvas.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Repeater.xml b/libXaw/specs/Repeater.xml
new file mode 100644
index 000000000..35cd69aee
--- /dev/null
+++ b/libXaw/specs/Repeater.xml
@@ -0,0 +1,558 @@
+<sect1 id="Repeater_Widget">
+<title>Repeater Widget</title>
+<!-- .XS -->
+<!-- Repeater Widget -->
+<!-- .XE -->
+<!-- .IN "Repeater widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application header file &lt;X11/Xaw/Repeater.h&gt;
+<!-- .IN "Repeater.h" "" -->
+Class header file &lt;X11/Xaw/RepeaterP.h&gt;
+<!-- .IN "RepeaterP.h" "" -->
+Class repeaterWidgetClass
+<!-- .IN "repeaterWidgetClass" "" -->
+Class Name Repeater
+<!-- .IN "Repeater widget" "class name" -->
+Superclass Command
+<!-- .sp -->
+</literallayout>
+<para>
+<!-- .LP -->
+The Repeater widget is a subclass of the Command widget; see the <!-- xref -->
+Command documentation for details. The difference is that the Repeater can call its
+registered callbacks repeatedly, at an increasing rate. The default translation
+does so for the duration the user holds down pointer button 1 while the pointer
+is on the Repeater.
+</para>
+<sect2 id="repeater_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Repeater widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "Repeater widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>bitmap</entry>
+ <entry>Bitmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>callback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cornerRoundPercent</entry>
+ <entry>CornerRoundPercent</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>25</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>decay</entry>
+ <entry>Decay</entry>
+ <entry>Int</entry>
+ <entry></entry>
+ <entry>5</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>encoding</entry>
+ <entry>Encoding</entry>
+ <entry>UnsignedChar</entry>
+ <entry></entry>
+ <entry>XawTextEncoding8bit</entry>
+ </row>
+ <row>
+ <entry>flash</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>font</entry>
+ <entry>Font</entry>
+ <entry>XFontStruct</entry>
+ <entry></entry>
+ <entry>XtDefaultFont</entry>
+ </row>
+ <row>
+ <entry>fontSet</entry>
+ <entry>FontSet</entry>
+ <entry>XFontSet</entry>
+ <entry></entry>
+ <entry>XtDefaultFontSet</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>graphic height + 2 * <function>internalHeight</function></entry>
+ </row>
+ <row>
+ <entry>highlightThickness</entry>
+ <entry>Thickness</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>2 (0 if Shaped)</entry>
+ </row>
+ <row>
+ <entry>initialDelay</entry>
+ <entry>Delay</entry>
+ <entry>Int</entry>
+ <entry></entry>
+ <entry>200</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>internalHeight</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>internalWidth</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>justify</entry>
+ <entry>Justify</entry>
+ <entry>Justify</entry>
+ <entry></entry>
+ <entry>XtJustifyCenter (center)</entry>
+ </row>
+ <row>
+ <entry>label</entry>
+ <entry>Label</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>name of widget</entry>
+ </row>
+ <row>
+ <entry>leftBitmap</entry>
+ <entry>LeftBitmap</entry>
+ <entry>Bitmap</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>minimumDelay</entry>
+ <entry>MinimumDelay</entry>
+ <entry>Int</entry>
+ <entry></entry>
+ <entry>10</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>repeatDelay</entry>
+ <entry>Delay</entry>
+ <entry>Int</entry>
+ <entry></entry>
+ <entry>50</entry>
+ </row>
+ <row>
+ <entry>resize</entry>
+ <entry>Resize</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Pointer</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>shapeStyle</entry>
+ <entry>ShapeStyle</entry>
+ <entry>ShapeStyle</entry>
+ <entry></entry>
+ <entry>Rectangle</entry>
+ </row>
+ <row>
+ <entry>startCallback</entry>
+ <entry>StartCallback</entry>
+ <entry>Callback</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>stopCallback</entry>
+ <entry>StopCallback</entry>
+ <entry>Callback</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>See below</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>graphic width + 2 * <function>internalWidth</function></entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+\" Resource Descriptions
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bm -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Cb -->
+<!-- .Cm -->
+<!-- .Cr -->
+<!-- .Cu -->
+<!-- .Cn -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>decay</function>
+ </term>
+ <listitem>
+ <para>
+The number of milliseconds that should be subtracted from each succeeding
+interval while the Repeater button is being held down until the interval
+has reached <function>minimumDelay</function> milliseconds.
+<!-- .Dp -->
+<!-- .Dc -->
+<!-- .Le -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>flash</function>
+ </term>
+ <listitem>
+ <para>
+Whether or not to flash the Repeater button whenever the timer goes off.
+<!-- .Lf -->
+<!-- .Ls -->
+<!-- .Lg -->
+<!-- .Hw -->
+<!-- .Ht -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>initialDelay</function>
+ </term>
+ <listitem>
+ <para>
+The number of milliseconds between the beginning of the Repeater button
+being held down and the first invocation of the <function>callback</function> function.
+<!-- .Ib -->
+<!-- .Ih -->
+<!-- .In -->
+<!-- .Ju -->
+<!-- .La -->
+<!-- .Ll -->
+<!-- .Mm -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>minimumDelay</function>
+ </term>
+ <listitem>
+ <para>
+The minimum time between callbacks in milliseconds.
+<!-- .Pf -->
+<!-- .Pb -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>repeatDelay</function>
+ </term>
+ <listitem>
+ <para>
+The number of milliseconds between each callback after the first (minus an
+increasing number of <function>decay</function>s).
+<!-- .Re -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Ss -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>startCallback</function>
+ </term>
+ <listitem>
+ <para>
+The list of functions to invoke by the <function>start</function> action (typically
+when the Repeater button is first pressed). The callback data parameter
+is set to NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>stopCallback</function>
+ </term>
+ <listitem>
+ <para>
+The list of functions to invoke by the <function>stop</function> action (typically
+when the Repeater button is released). The callback data parameter
+is set to NULL.
+<!-- .Tr -->
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Repeater_Actions">
+<title>Repeater Actions</title>
+<!-- .IN "Repeater widget" "actions" -->
+<para>
+<!-- .LP -->
+The Repeater widget supports the following actions beyond those of the Command
+button:
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>start</function>()
+ </term>
+ <listitem>
+ <para>
+This invokes the functions on the <function>startCallback</function> and <function>callback</function> lists
+and sets a timer to go off in <function>initialDelay</function> milliseconds. The timer
+will cause the <function>callback</function> functions to be invoked with increasing
+frequency until the <function>stop</function> action occurs.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>stop</function>()
+ </term>
+ <listitem>
+ <para>
+This invokes the functions on the <function>stopCallback</function> list and prevents any
+further timers from occuring until the next <function>start</function> action.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .IN "Repeater widget" "translation bindings" -->
+The following are the default translation bindings used by the
+Repeater widget:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+ &lt;EnterWindow&gt;: highlight(\|)
+ &lt;LeaveWindow&gt;: unhighlight(\|)
+ &lt;Btn1Down&gt;: set(\|) start(\|)
+ &lt;Btn1Up&gt;: stop(\|) unset(\|)
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Scrollbar.xml b/libXaw/specs/Scrollbar.xml
new file mode 100644
index 000000000..87f6d68eb
--- /dev/null
+++ b/libXaw/specs/Scrollbar.xml
@@ -0,0 +1,884 @@
+<sect1 id="Scrollbar_Widget">
+<title>Scrollbar Widget</title>
+
+<literallayout class="monospaced">
+Application header file &lt;X11/Xaw/Scrollbar.h&gt;
+Class header file &lt;X11/Xaw/ScrollbarP.h&gt;
+Class scrollbarWidgetClass
+Class Name Scrollbar
+Superclass Simple
+</literallayout>
+
+<para>
+A Scrollbar widget is a rectangle, called the ``canvas,'' on
+which another rectangle, the ``thumb,'' moves in one
+dimension, either vertically or horizontally. A Scrollbar
+can be used alone, as a value generator, or it can be used
+within a composite widget (for example, a Viewport). When a
+Scrollbar is used to move, or ``scroll,'' the contents of
+another widget, the size and the position of the thumb usually give
+feedback as to what portion of the other widget's contents
+are visible.
+</para>
+
+<para>
+Each pointer button invokes a specific action. Pointer
+buttons 1 and 3 do not move the thumb automatically.
+Instead, they return the pixel position of the cursor on the
+scroll region. When pointer button 2 is clicked, the thumb
+moves to the current pointer position. When pointer button
+2 is held down and the pointer is moved, the thumb follows
+the pointer.
+</para>
+
+<para>
+The pointer cursor in the scroll region changes depending on the current
+action. When no pointer button is pressed, the cursor appears as a
+double-headed arrow that points in the direction that scrolling can
+occur. When pointer button 1 or 3 is pressed, the cursor appears as a
+single-headed arrow that points in the logical direction that the thumb
+will move. When pointer button 2 is pressed, the cursor
+appears as an arrow that points to the top or the left of the thumb.
+</para>
+
+<para>
+When the user scrolls, the application receives notification
+through callback procedures. For both discrete scrolling actions, the
+callback returns the Scrollbar widget, the client_data, and the pixel
+position of the pointer when the button was released. For continuous
+scrolling, the callback routine returns the scroll bar widget, the
+client data, and the current relative position of the thumb. When the
+thumb is moved using pointer button 2, the callback procedure is invoked
+continuously. When either button 1 or 3 is pressed, the callback
+procedure is invoked only when the button is released and the client
+callback procedure is responsible for moving the thumb.
+</para>
+
+<sect2 id="scrollbar_resources">
+<title>Resources</title>
+
+<para>
+When creating a Scrollbar widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+
+<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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>depends on orientation</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>jumpProc</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>length</entry>
+ <entry>Length</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>minimumThumb</entry>
+ <entry>MinimumThumb</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>7</entry>
+ </row>
+ <row>
+ <entry>orientation</entry>
+ <entry>Orientation</entry>
+ <entry>Orientation</entry>
+ <entry></entry>
+ <entry>XtorientVertical (vertical)</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>parent's Screen</entry>
+ </row>
+ <row>
+ <entry>scrollDCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>XC_sb_down_arrow</entry>
+ </row>
+ <row>
+ <entry>scrollHCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>XC_sb_h_double_arrow</entry>
+ </row>
+ <row>
+ <entry>scrollLCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>XC_sb_left_arrow</entry>
+ </row>
+ <row>
+ <entry>scrollProc</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>scrollRCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>XC_sb_right_arrow</entry>
+ </row>
+ <row>
+ <entry>scrollUCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>XC_sb_up_arrow</entry>
+ </row>
+ <row>
+ <entry>scrollVCursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>XC_sb_v_arrow</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>shown</entry>
+ <entry>Shown</entry>
+ <entry>Float</entry>
+ <entry></entry>
+ <entry>0.0</entry>
+ </row>
+ <row>
+ <entry>thickness</entry>
+ <entry>Thickness</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>14</entry>
+ </row>
+ <row>
+ <entry>thumb</entry>
+ <entry>Thumb</entry>
+ <entry>Bitmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>thumbProc</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>topOfThumb</entry>
+ <entry>TopOfThumb</entry>
+ <entry>Float</entry>
+ <entry></entry>
+ <entry>0.0</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>See below</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>depends on orientation</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>foreground</function>
+ </term>
+ <listitem>
+ <para>
+A pixel value which indexes the widget's colormap to derive the color
+used to draw the thumb.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>jumpProc</function>
+ </term>
+ <listitem>
+ <para>
+All functions on this callback list are called when the
+<function>NotifyThumb</function> action is invoked. See the <function>Scrollbar
+Actions</function> section for details.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>length</function>
+ </term>
+ <listitem>
+ <para>
+The height of a vertical scrollbar or the width of a horizontal scrollbar.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>minimumThumb</function>
+ </term>
+ <listitem>
+ <para>
+The smallest size, in pixels, to which the thumb can shrink.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>orientation</function>
+ </term>
+ <listitem>
+ <para>
+The orientation is the direction that the thumb will be allowed to move.
+This value can be either <function>XtorientVertical</function> or
+<function>XtorientHorizontal</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>scrollDCursor</function>
+ </term>
+ <listitem>
+ <para>
+This cursor is used when scrolling backward in a vertical scrollbar.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>scrollHCursor</function>
+ </term>
+ <listitem>
+ <para>
+This cursor is used when a horizontal scrollbar is inactive.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>scrollLCursor</function>
+ </term>
+ <listitem>
+ <para>
+This cursor is used when scrolling forward in a horizontal scrollbar.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>scrollProc</function>
+ </term>
+ <listitem>
+ <para>
+All functions on this callback list may be called when the
+<function>NotifyScroll</function> action is invoked. See the \fBScrollbar
+Actions\fP section for details.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>scrollRCursor</function>
+ </term>
+ <listitem>
+ <para>
+This cursor is used when scrolling backward in a horizontal scrollbar,
+or when thumbing a vertical scrollbar.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>scrollUCursor</function>
+ </term>
+ <listitem>
+ <para>
+This cursor is used when scrolling forward in a vertical scrollbar, or when
+thumbing a horizontal scrollbar.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>scrollVCursor</function>
+ </term>
+ <listitem>
+ <para>
+This cursor is used when a vertical scrollbar is inactive.
+<!-- .Se -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>shown</function>
+ </term>
+ <listitem>
+ <para>
+This is the size of the thumb, expressed as a percentage (0.0 - 1.0)
+of the length of the scrollbar.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>thickness</function>
+ </term>
+ <listitem>
+ <para>
+The width of a vertical scrollbar or the height of a horizontal scrollbar.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>thumb</function>
+ </term>
+ <listitem>
+ <para>
+This pixmap is used to tile (or stipple) the thumb of the scrollbar. If
+no tiling is desired, then set this resource to <function>None</function>. This
+resource will accept either a bitmap or a pixmap that is the same depth
+as the window. The resource converter for this resource constructs
+bitmaps from the contents of files. (See <function>Converting Bitmaps</function> for
+details.)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>topOfThumb</function>
+ </term>
+ <listitem>
+ <para>
+The location of the top of the thumb, as a percentage (0.0 - 1.0)
+of the length of the scrollbar. This resource was called <function>top</function> in
+previous versions of the Athena widget set. The name collided with the
+a Form widget constraint resource, and had to be changed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="Scrollbar_Actions">
+<title>Scrollbar Actions</title>
+<para>
+<!-- .LP -->
+The actions supported by the Scrollbar widget are:
+</para>
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>StartScroll</function>(<emphasis remap='I'>value</emphasis>)
+ </term>
+ <listitem>
+ <para>
+The possible <emphasis remap='I'>values</emphasis> are Forward, Backward, or Continuous.
+This must be the first action to begin a new movement.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>NotifyScroll</function>(<emphasis remap='I'>value</emphasis>)
+ </term>
+ <listitem>
+ <para>
+The possible <emphasis remap='I'>values</emphasis> are Proportional or FullLength. If the
+argument to StartScroll was Forward or Backward, NotifyScroll executes
+the <function>scrollProc</function> callbacks and passes either; the position of the
+pointer, if <emphasis remap='I'>value</emphasis> is Proportional, or the full length of the
+scroll bar, if <emphasis remap='I'>value</emphasis> is FullLength. If the argument to
+StartScroll was Continuous, NotifyScroll returns without executing any
+callbacks.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>EndScroll</function>(\^)
+ </term>
+ <listitem>
+ <para>
+This must be the last action after a movement is complete.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>MoveThumb</function>(\^)
+ </term>
+ <listitem>
+ <para>
+Repositions the Scrollbar's thumb to the current pointer location.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>NotifyThumb</function>(\^)\
+ </term>
+ <listitem>
+ <para>
+Calls the
+<!-- .PN jumpProc -->
+callbacks and passes the relative position of the
+pointer as a percentage of the scroll bar length.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+The default bindings for Scrollbar are:
+<!-- .IN "Scrollbar widget" "default translation table" -->
+</para>
+
+<literallayout class="monospaced">
+ &lt;Btn1Down&gt;: StartScroll(Forward)
+ &lt;Btn2Down&gt;: StartScroll(Continuous) MoveThumb(\|) NotifyThumb(\|)
+ &lt;Btn3Down&gt;: StartScroll(Backward)
+ &lt;Btn2Motion&gt;: MoveThumb(\|) NotifyThumb(\|)
+ &lt;BtnUp&gt;: NotifyScroll(Proportional) EndScroll(\|)
+</literallayout>
+
+<para>
+Examples of additional bindings a user might wish to specify in a
+resource file are:
+</para>
+
+<literallayout class="monospaced">
+*Scrollbar.Translations: \\
+ ~Meta&lt;Key&gt;space: StartScroll(Forward) NotifyScroll(FullLength) \\n\\
+ Meta&lt;Key&gt;space: StartScroll(Backward) NotifyScroll(FullLength) \\n\\
+ EndScroll(\|)
+</literallayout>
+
+</sect2>
+
+<sect2 id="Scrollbar_Callbacks">
+<title>Scrollbar Callbacks</title>
+<!-- .IN "Scrollbar widget" "callbacks" -->
+<para>
+<!-- .LP -->
+There are two callback lists provided by the Scrollbar widget.
+The procedural interface for these functions is described here.
+</para>
+
+<para>
+<!-- .LP -->
+The calling interface to the <function>scrollProc</function> callback procedure is:
+<!-- .IN "ScrollProc" "" "@DEF@" -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> ScrollProc</function></funcdef>
+ <paramdef>Widget<parameter> scrollbar</parameter></paramdef>
+ <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XtPointer<parameter> position</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>scrollbar</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Scrollbar widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>position</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pixel position in integer form.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <function>scrollProc</function> callback is used for incremental scrolling
+and is called by the <function>NotifyScroll</function> action.
+The position argument is a signed quantity and should be cast to an int
+when used. Using the default button bindings, button 1 returns a
+positive value, and button 3 returns a negative value. In both cases,
+the magnitude of the value is the distance of the pointer in
+pixels from the top (or left) of the Scrollbar. The value will never
+be greater than the length of the Scrollbar.
+</para>
+
+<para>
+The calling interface to the <function>jumpProc</function> callback procedure is:
+</para>
+<!-- .IN "jumpProc" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> JumpProc</function></funcdef>
+ <paramdef>Widget<parameter> scrollbar</parameter></paramdef>
+ <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XtPointer<parameter> percent_ptr</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>scrollbar</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the ID of the scroll bar widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>percent_ptr</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the floating point position of the thumb (0.0 \- 1.0).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <function>jumpProc</function> callback is used to implement smooth scrolling and
+is called by the <function>NotifyThumb</function> action. Percent_ptr must be cast
+to a pointer to float before use; i.e.
+</para>
+
+<literallayout class="monospaced">
+ float percent = *(float*)percent_ptr;
+</literallayout>
+
+<para>
+With the default button bindings, button 2 moves the thumb interactively,
+and the <function>jumpProc</function> is called on each new position of the pointer,
+while the pointer button remains down. The value specified by
+<emphasis remap='I'>percent_ptr</emphasis> is the current location of the thumb (from the top or
+left of the Scrollbar) expressed as a percentage of the length of the
+Scrollbar.
+</para>
+
+</sect2>
+
+<sect2 id="Convenience_Routines">
+<title>Convenience Routines</title>
+<para>
+<!-- .IN "Scrollbar widget" "setting thumb values" -->
+To set the position and length of a Scrollbar thumb, use
+<!-- .PN XawScrollbarSetThumb . -->
+<!-- .IN "XawScrollbarSetThumb" "" "@DEF@" -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawScrollbarSetThumb</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>float<parameter> top</parameter></paramdef>
+ <paramdef>float<parameter> shown</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Scrollbar widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>top</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the position of the top of the thumb as a fraction of the
+length of the Scrollbar.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>shown</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of the thumb as a fraction of the total length
+of the Scrollbar.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XawScrollbarThumb</function>
+moves the visible thumb to a new position (0.0 \- 1.0) and length (0.0 \- 1.0).
+Either the top or shown arguments can be specified as \-1.0,
+in which case the current value is left unchanged.
+Values greater than 1.0 are truncated to 1.0.
+</para>
+
+<para>
+If called from <function>jumpProc</function>, <function>XawScrollbarSetThumb</function> has no effect.
+</para>
+
+</sect2>
+
+<sect2 id="Setting_Float_Resources">
+<title>Setting Float Resources</title>
+<!-- .IN "float resources" "setting" -->
+<para>
+The <function>shown</function> and <function>topOfThumb</function> resources are of type
+<emphasis remap='I'>float</emphasis>. These resources can be difficult to get into an
+argument list. The reason is that C performs an automatic cast of
+the float value to an integer value, usually truncating the important
+information. The following code fragment is one portable method of
+getting a float into an argument list.
+</para>
+<literallayout class="monospaced">
+ top = 0.5;
+ if (sizeof(float) &gt; sizeof(XtArgVal)) {
+ /*
+ \ * If a float is larger than an XtArgVal then pass this
+ \ * resource value by reference.
+ \ */
+ XtSetArg(args[0], XtNshown, &amp;top);
+ }
+ else {
+ /*
+ \ * Convince C not to perform an automatic conversion, which
+ \ * would truncate 0.5 to 0.
+ \ */
+ XtArgVal * l_top = (XtArgVal *) &amp;top;
+ XtSetArg(args[0], XtNshown, *l_top);
+ }
+</literallayout>
+
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Simple.xml b/libXaw/specs/Simple.xml
new file mode 100644
index 000000000..a21bc64f5
--- /dev/null
+++ b/libXaw/specs/Simple.xml
@@ -0,0 +1,252 @@
+<sect1 id="Simple_Widget">
+<title>Simple Widget</title>
+<!-- .XS -->
+<!-- Simple Widget -->
+<!-- .XE -->
+<!-- .IN "Simple widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file &lt;Xaw/Simple.h&gt;
+<!-- .IN "Simple.h" "" -->
+Class Header file &lt;Xaw/SimpleP.h&gt;
+<!-- .IN "SimpleP.h" "" -->
+Class simpleWidgetClass
+<!-- .IN "simpleWidgetClass" -->
+Class Name Simple
+<!-- .IN "Simple widget" "class name" -->
+Superclass Core
+<!-- .sp -->
+</literallayout>
+<para>
+<!-- .LP -->
+The Simple widget is not very useful by itself, as it has no semantics
+of its own. It main purpose is to be used as a common superclass for
+the other <emphasis remap='I'>simple</emphasis> Athena widgets. This widget adds six resources
+to the resource list provided by the Core widget and its superclasses.
+</para>
+<sect2 id="simple_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Simple widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "Simple widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Cm -->
+<!-- .Cu Bold -->
+<!-- .Cn Bold -->
+<!-- .Dp -->
+<!-- .Dc -->
+<!-- .Hw -->
+<!-- .Ib Bold -->
+<!-- .Ix Bold -->
+<!-- .Mm -->
+<!-- .Pf Bold -->
+<!-- .Pb Bold -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+<!-- .Xy -->
+
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/SimpleMenu.xml b/libXaw/specs/SimpleMenu.xml
new file mode 100644
index 000000000..84ba039e7
--- /dev/null
+++ b/libXaw/specs/SimpleMenu.xml
@@ -0,0 +1,790 @@
+<sect2 id="SimpleMenu_Widget">
+<title>SimpleMenu Widget</title>
+<!-- .XS -->
+<!-- SimpleMenu Widget -->
+<!-- .XE -->
+<!-- .IN "SimpleMenu widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file &lt;X11/Xaw/SimpleMenu.h&gt;
+<!-- .IN "SimpleMenu.h" "" -->
+Class Header file &lt;X11/Xaw/SimpleMenP.h&gt;
+<!-- .IN "SimpleMenP.h" "" -->
+Class simpleMenuWidgetClass
+<!-- .IN "simpleMenuWidgetClass" "" -->
+Class Name SimpleMenu
+<!-- .IN "SimpleMenu widget" "class name" -->
+Superclass OverrideShell
+<!-- .sp -->
+</literallayout>
+<para>
+<!-- .LP -->
+The SimpleMenu widget is a container for the menu entries. It is a
+direct subclass of shell, and is should be created with
+<function>XtCreatePopupShell</function>, not <function>XtCreateManagedWidget</function>. This is the
+only part of the menu that
+actually is associated with a window. The SimpleMenu serves as the glue to bind
+the individual menu entries together into a menu.
+</para>
+<sect3 id="Resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+<!-- .IN "SimpleMenu widget" "resources" -->
+</para>
+<para>
+<!-- .LP -->
+The resources associated with the SimpleMenu widget control aspects
+that will affect the entire menu.
+<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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>allowShellResize</entry>
+ <entry>AllowShellResize</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>backingStore</entry>
+ <entry>BackingStore</entry>
+ <entry>BackingStore</entry>
+ <entry></entry>
+ <entry>see below</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>bottomMargin</entry>
+ <entry>VerticalMargins</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>children</entry>
+ <entry>ReadOnly</entry>
+ <entry>WidgetList</entry>
+ <entry>R</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>createPopupChildProc</entry>
+ <entry>CreatePopupChildProc</entry>
+ <entry>Function</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>geometry</entry>
+ <entry>Geometry</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>Enough space to contain all entries</entry>
+ </row>
+ <row>
+ <entry>label</entry>
+ <entry>Label</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>labelClass</entry>
+ <entry>LabelClass</entry>
+ <entry>Pointer</entry>
+ <entry></entry>
+ <entry>SmeBSBObjectClass</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>menuOnScreen</entry>
+ <entry>MenuOnScreen</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>numChildren</entry>
+ <entry>ReadOnly</entry>
+ <entry>Cardinal</entry>
+ <entry>R</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>overrideRedirect</entry>
+ <entry>OverrideRedirect</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>popdownCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>popupCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>popupOnEntry</entry>
+ <entry>PopupOnEntry</entry>
+ <entry>Widget</entry>
+ <entry>A</entry>
+ <entry>Label or first entry</entry>
+ </row>
+ <row>
+ <entry>rowHeight</entry>
+ <entry>RowHeight</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>saveUnder</entry>
+ <entry>SaveUnder</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>topMargin</entry>
+ <entry>VerticalMargins</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>See below</entry>
+ </row>
+ <row>
+ <entry>visual</entry>
+ <entry>Visual</entry>
+ <entry>Visual</entry>
+ <entry></entry>
+ <entry>CopyFromParent</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>Width of widest entry</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>backingStore</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "conversions" "BackingStore" -->
+Determines what type of backing store will be used for the menu. Legal
+values for this resource are <function>NotUseful</function>, <function>WhenMapped</function>, and
+<function>Always</function>. These values are the backing-store integers defined in
+&lt;X11/X.h&gt;.
+<!-- .Rs "notUseful, whenMapped, always, \fPand\fP default" -->
+If <function>default</function> is specified (the default behavior) the server will use
+whatever it thinks is appropriate.
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>bottomMargin</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>topMargin</function>
+ </term>
+ <listitem>
+ <para>
+The amount of space between the top or bottom of the menu and the menu entry
+closest to that edge.
+<!-- .Ch -->
+<!-- .Cm -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>cursor</function>
+ </term>
+ <listitem>
+ <para>
+The shape of the mouse pointer whenever it is in this widget.
+<!-- .Dp -->
+<!-- .Dc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ geometry
+ </term>
+ <listitem>
+ <para>
+If this resource is specified it will override the x, y, width and
+height of this widget. The format of this string is
+[&lt;<emphasis remap='I'>width</emphasis>&gt;x&lt;<emphasis remap='I'>height</emphasis>&gt;][{+ -} &lt;<emphasis remap='I'>xoffset</emphasis>&gt; {+ -}&lt;<emphasis remap='I'>yoffset</emphasis>&gt;].
+<!-- .Hw -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>label</function>
+ </term>
+ <listitem>
+ <para>
+This label will be placed at the top of the SimpleMenu, and may not be
+highlighted. The name of the
+label object is <function>menuLabel</function>. Using this name it is possible to
+modify the label's attributes through the resource database. When the label
+is created, the <function>label</function> is hard coded to the value of <function>label</function>, and
+<function>justify</function> is hard coded as <function>XtJustifyCenter</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>labelClass</function>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of Sme object created as the menu label.
+<!-- .Mm -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>menuOnScreen</function>
+ </term>
+ <listitem>
+ <para>
+If the menu is automatically positioned under the cursor with the
+<function>XawPositionSimpleMenu</function> action, and this resource is <function>True</function>,
+then the menu will always be fully visible on the screen.
+<!-- .Nc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ overrideRedirect
+ </term>
+ <listitem>
+ <para>
+Determines the value of the override_redirect attribute of the
+SimpleMenu's window. The override_redirect attribute of a window
+determines whether or not a window manager may interpose itself between
+this window and the root window of the display. For more information
+see the <emphasis remap='I'>Interclient Communications Conventions Manual</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ popdownCallback
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ popupCallback
+ </term>
+ <listitem>
+ <para>
+These callback functions are called by the Xt Intrinsics whenever the
+shell is popped up or down (See <emphasis remap='I'>(xT</emphasis> for details).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>popupOnEntry</function>
+ </term>
+ <listitem>
+ <para>
+The <function>XawPositionSimpleMenu</function> action will, by default, popup the
+SimpleMenu with its label (or first entry) directly under the
+pointer. To popup the menu under
+another entry, set this resource to the menu entry that should be
+under the pointer, when the menu is popped up. This allows the
+application to offer the user a default menu entry that can be selected
+with out moving the pointer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>rowHeight</function>
+ </term>
+ <listitem>
+ <para>
+If this resources is zero (the default) then each menu entry will be
+given its desired height. If this resource has any other value then
+all menu entries will be forced to be <function>rowHeight</function> pixels high.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ saveUnder
+ </term>
+ <listitem>
+ <para>
+If this is <function>True</function> then save unders will be active on the menu's window.
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect3>
+<sect3 id="SimpleMenu_Actions">
+<title>SimpleMenu Actions</title>
+<!-- .IN "SimpleMenu widget" "actions" -->
+<para>
+<!-- .LP -->
+The SimpleMenu widget supports the following actions:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Switching the entry under the mouse pointer between
+the foreground and background colors with <function>highlight</function>
+and <function>unhighlight</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Processing menu entry callbacks with <function>notify</function>
+<!-- .sp -->
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<!-- .IN "SimpleMenu widget" "default translations" -->
+The following are the default translation bindings used
+by the SimpleMenu widget:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+ &lt;EnterWindow&gt;: highlight(\|)
+ &lt;LeaveWindow&gt;: unhighlight(\|)
+ &lt;BtnMotion&gt;: highlight(\|)
+ &lt;BtnUp&gt;: MenuPopdown(\|) notify(\|) unhighlight(\|)
+</literallayout>
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "SimpleMenu widget" "MenuPopdown routine" -->
+The user can pop down the menu without activating any of the callback
+functions by releasing the pointer button when no menu item is
+highlighted.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+The full list of actions supported by SimpleMenu is:
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>highlight</function>()
+ </term>
+ <listitem>
+ <para>
+Highlight the menu entry that is currently under the pointer.
+Only a item that is highlighted will be notified when the <function>notify</function>
+action is invoked. The look of a highlighted entry is determined by
+the menu entry.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>unhighlight</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Unhighlights the currently highlighted menu item, and returns it to
+its normal look.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>notify</function>(\|)
+ </term>
+ <listitem>
+ <para>
+Notifies the menu entry that is currently highlighted that is has been
+selected. It is the responsibility of the menu entry to take the
+appropriate action.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>MenuPopdown</function>(<emphasis remap='I'>menu</emphasis>)
+ </term>
+ <listitem>
+ <para>
+This action is defined in <emphasis remap='I'>(xT</emphasis>.
+<!-- .IN "SimpleMenu widget" "MenuPopdown routine" -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect3>
+<sect3 id="Positioning_the_SimpleMenu">
+<title>Positioning the SimpleMenu</title>
+<!-- .IN "XawPositionSimpleMenu" "" "@DEF@" -->
+<!-- .IN "SimpleMenu widget" "positioning" "@DEF@" -->
+<para>
+<!-- .LP -->
+If the SimpleMenu widget is to be used as a pulldown menu then the
+MenuButton widget, or some other outside means should be used to place
+the menu when it is popped up.
+</para>
+<para>
+<!-- .LP -->
+If popup menus are desired it will be necessary to add the
+<function>XawPositionSimpleMenu</function> and <function>MenuPopup</function> actions to the
+translation table of the widget that will be popping up the menu. The
+<function>MenuPopup</function> action is described in <emphasis remap='I'>(xT</emphasis>.
+<function>XawPositionSimpleMenu</function> is a global action procedure registered by
+the SimpleMenu widget when the first one is created or the convenience
+routine <function>XawSimpleMenuAddGlobalActions</function> is called.
+</para>
+<para>
+<!-- .LP -->
+Translation writers should be aware that Xt does not register grabs on
+``don't care'' modifiers, and therefore the left hand side of the
+production should be written to exclude unspecified modifiers.
+For example these are the translations needed to popup some of
+<function>xterm's</function> menus:
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+ !Ctrl&lt;Btn1Down&gt;: XawPositionSimpleMenu(xterm) MenuPopup(xterm)
+ !Ctrl&lt;Btn2Down&gt;: XawPositionSimpleMenu(modes) MenuPopup(modes)
+</literallayout>
+<!-- .sp 1 -->
+</para>
+<para>
+<!-- .LP -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>XawPositionSimpleMenu</function>(<emphasis remap='I'>menu</emphasis>)
+ </term>
+ <listitem>
+ <para>
+The <function>XawPositionSimpleMenu</function> routine will search for the menu name
+passed to it using <function>XtNameToWidget</function> starting with the widget
+invoking the action as the reference widget. If it is unsuccessful it
+will continue up the widget tree using each of the invoking widget's
+ancestors as the reference widget. If it is still unsuccessful it will
+print a warning message and give up. <function>XawPositionSimpleMenu</function> will
+position the menu directly under the pointer cursor. The menu will be
+placed so that the pointer cursor is centered on the entry named by the
+<function>popupOnEntry</function> resource. If the <function>menuOnScreen</function> resource is
+<function>True</function> then the menu will always be fully visible on the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect3>
+<sect3 id="Convenience_Routines">
+<title>Convenience Routines</title>
+<sect4 id="Registering_the_Global_Action_Routines">
+<title>Registering the Global Action Routines</title>
+<para>
+<!-- .LP -->
+<!-- .IN "XawPositionSimpleMenu" "" -->
+The <function>XawPositionSimpleMenu</function> action routine may often be invoked
+before any menus have been created. This can occur when an
+application uses dynamic menu creation. In these cases an application will
+need to register this global action routine by calling
+<function>XawSimpleMenuAddGlobalActions</function>:
+<!-- .IN "XawSimpleMenuAddGlobalActions" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawSimpleMenuAddGlobalActions</function></funcdef>
+ <paramdef>XtAppContext<parameter> app_con</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_con</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context in which this action should be registered.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function need only be called once per application and must be
+called before any widget that uses <function>XawPositionSimpleMenu</function> action
+is realized.
+</para>
+</sect4>
+<sect4 id="Getting_and_Clearing_the_Current_Menu_Entry">
+<title>Getting and Clearing the Current Menu Entry</title>
+<para>
+<!-- .LP -->
+To get the currently highlighted menu entry use
+<function>XawSimpleMenuGetActiveEntry</function>:
+<!-- .IN "XawSimpleMenuGetActiveEntry" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Widget<function> XawSimpleMenuGetActiveEntry</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the SimpleMenu widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function returns the menu entry that is
+currently highlighted, or NULL if no entry is highlighted.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To clear the SimpleMenu widget's internal information about the
+currently highlighted menu entry use
+<function>XawSimpleMenuClearActiveEntry</function>:
+<!-- .IN "XawSimpleMenuClearActiveEntry" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Widget<function> XawSimpleMenuClearActiveEntry</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the SimpleMenu widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function unsets all internal references to the currently
+highlighted menu entry. It does not <emphasis remap='I'>unhighlight</emphasis> or otherwise
+alter the appearance of the active entry. This function is primarily
+for use by implementors of menu entries.
+
+</para>
+</sect4>
+</sect3>
+</sect2>
diff --git a/libXaw/specs/Sme.xml b/libXaw/specs/Sme.xml
new file mode 100644
index 000000000..2d3d2f5f7
--- /dev/null
+++ b/libXaw/specs/Sme.xml
@@ -0,0 +1,207 @@
+<sect1 id="Sme_Object">
+<title>Sme Object</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Sme Object -->
+<!-- .XE -->
+<!-- .IN "Sme object" "" "@DEF@" -->
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+Application Header file &lt;X11/Xaw/Sme.h&gt;
+<!-- .IN "Sme.h" "" -->
+Class Header file &lt;X11/Xaw/SmeP.h&gt;
+<!-- .IN "SmeP.h" "" -->
+Class smeObjectClass
+<!-- .IN "smeObjectClass" "" -->
+Class Name Sme
+<!-- .IN "Sme object" "class name" -->
+Superclass RectObj
+</literallayout>
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+The Sme object is the base class for all menu entries. While this
+object is mainly intended to be subclassed, it may be used in a menu to
+add blank space between menu entries.
+</para>
+<sect2 id="sme_resources">
+<title>Resources</title>
+<!-- .IN "SmeLine object" "resources" -->
+<para>
+<!-- .LP -->
+The resources associated with the SmeLine object are defined in this
+section, and affect only the single menu entry specified by this object.
+There are no new resources added for this class, as it picks up all its
+resources from the RectObj class.
+</para>
+<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>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>callback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .As -->
+<!-- .Dc -->
+<!-- .Hw -->
+
+<para>
+Keep in mind that the SimpleMenu widget will force all menu items to
+be the width of the widest entry.
+<!-- .Ix Bold -->
+<!-- .Se -->
+</para>
+</sect2>
+<sect2 id="Subclassing_the_Sme_Object">
+<title>Subclassing the Sme Object</title>
+<!-- .IN "Sme object" "subclassing" "@DEF" -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To Create a new Sme object <emphasis remap='I'>class</emphasis> you will need to define three class methods.
+These methods allow the SimpleMenu to highlight and unhighlight the
+menu entry as the pointer cursor moves over it, as well as notify the
+entry when the user has selected it. All of
+these methods may be inherited from the Sme object, although the default
+semantics are not very interesting.
+</para>
+<para>
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>Highlight</function>(\|)
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "Sme object" "Highlight method" -->
+Called to put the menu entry into the highlighted state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Unhighlight</function>(\|)
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "Sme object" "Unhighlight method" -->
+Called to return the widget to its normal (unhighlighted) state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Notify</function>(\|)
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "Sme object" "Notify method" -->
+Called when the user selects this menu entry.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Other then these methods, creating a new object
+is straight forward. Here is some information that may help you
+avoid some common mistakes.
+</para>
+<orderedlist>
+ <listitem><para>Objects can be zero pixels high.</para></listitem>
+ <listitem>
+ <para>
+Objects draw on their parent's window, therefore the Drawing dimensions
+are different from those of widgets. For instance, y locations vary
+from <function>y</function> to <function>y + height</function>, not <function>0</function> to <function>height</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<!-- .IP 3) 3n -->
+XtSetValues calls may come from the application while the Sme is highlighted,
+and if the SetValues method returns True, will result in an expose event.
+The SimpleMenu may later call the menu entry's <function>unhighlight</function>
+procedure. However, due to the asynchronous nature of
+X, the expose event generated by <function>XtSetValues</function> will come <emphasis remap='I'>after</emphasis>
+this unhighlight.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Remember that your subclass of the Sme does not own the
+window. Share the space with other menu entries, and refrain
+from drawing outside the subclass's own section of the menu.
+ </para>
+ </listitem>
+</orderedlist>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/SmeBSB.xml b/libXaw/specs/SmeBSB.xml
new file mode 100644
index 000000000..539bdcb03
--- /dev/null
+++ b/libXaw/specs/SmeBSB.xml
@@ -0,0 +1,310 @@
+<sect1 id="SmeBSB_Object">
+<title>SmeBSB Object</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- SmeBSB Object -->
+<!-- .XE -->
+<!-- .IN "SmeBSB object" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file &lt;X11/Xaw/SmeBSB.h&gt;
+<!-- .IN "SmeBSB.h" "" -->
+Class Header file &lt;X11/Xaw/SmeBSBP.h&gt;
+<!-- .IN "SmeBSBP.h" "" -->
+Class smeBSBObjectClass
+<!-- .IN "smeBSBObjectClass" "" -->
+Class Name SmeBSB
+<!-- .IN "SmeBSB object" "class name" -->
+Superclass Sme
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The SmeBSB object is used to create a menu entry that contains a string,
+and optional bitmaps in its left and right margins. Since each menu
+entry is an independent object, the application is able to change the
+font, color, height, and other attributes of the menu entries, on an
+entry by entry basis. The format of the string may either be the encoding
+of the 8 bit <function>font</function> utilized, or in a multi-byte encoding for use with a
+<function>fontSet</function>.
+</para>
+<sect2 id="smebsb_resources">
+<title>Resources</title>
+<!-- .IN "SmeBSB object" "resources" -->
+<para>
+<!-- .LP -->
+The resources associated with the SmeBSB object are defined in this section,
+and affect only the single menu entry specified by this object.
+<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>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>callback</entry>
+ <entry>Callback</entry>
+ <entry>Callback</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>font</entry>
+ <entry>Font</entry>
+ <entry>FontStruct</entry>
+ <entry></entry>
+ <entry>XtDefaultFont</entry>
+ </row>
+ <row>
+ <entry>fontSet</entry>
+ <entry>FontSet</entry>
+ <entry>XFontSet</entry>
+ <entry></entry>
+ <entry>XtDefaultFontSet</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Font height + <function>vertSpace</function></entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>justify</entry>
+ <entry>Justify</entry>
+ <entry>Justify</entry>
+ <entry></entry>
+ <entry>XtjustifyLeft</entry>
+ </row>
+ <row>
+ <entry>label</entry>
+ <entry>Label</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>leftBitmap</entry>
+ <entry>LeftBitmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>leftMargin</entry>
+ <entry>leftMargin</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>rightBitmap</entry>
+ <entry>RightBitmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>rightMargin</entry>
+ <entry>rightMargin</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>vertSpace</entry>
+ <entry>VertSpace</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry>25</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>TextWidth + margins</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<!-- .As -->
+<variablelist>
+ <varlistentry>
+ <term>callback</term>
+ <listitem>
+ <para>
+All callback functions on this list are called when the SimpleMenu
+<emphasis remap='I'>notifies</emphasis> this entry that the user has selected it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>font</term>
+ <listitem>
+ <para>
+The text font to use when displaying the <function>label</function>, when the
+<function>international</function> resource is <function>false</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>fontSet</term>
+ <listitem>
+ <para>
+The text font set to use when displaying the <function>label</function>, when the
+<function>international</function> resource is <function>true</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>foreground</term>
+ <listitem>
+ <para>
+A pixel value which indexes the SimpleMenu's colormap to derive the
+foreground color of the menu entry's window. This color is also
+used to render all 1's in the left and right <function>bitmaps</function>.
+<!-- .Hw -->
+Keep in mind that the SimpleMenu widget will force the width of all
+menu entries to be the width of the longest entry.
+<!-- .In -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>justify</term>
+ <listitem>
+ <para>
+<!-- .IP <function>justify</function> 1.5i -->
+How the label is to be rendered between the left and right margins when
+the space is wider than the actual text. This resource may be
+specified with the values <function>XtJustifyLeft</function>, <function>XtJustifyCenter</function>,
+or <function>XtJustifyRight</function>. When specifying the justification from a
+resource file the values <function>left</function>, <function>center</function>, or <function>right</function> may be
+used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>label</term>
+ <listitem>
+ <para>
+This is a the string that will be displayed in the menu entry. The
+exact location of this string within the bounds of the menu entry is
+controlled by the <function>leftMargin</function>, <function>rightMargin</function>, <function>vertSpace</function>,
+and <function>justify</function> resources.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>leftBitmap</term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>rightBitmap</term>
+ <listitem>
+ <para>
+<!-- .IP <function>rightBitmap</function> 1.5i -->
+This is a name of a bitmap to display in the left or right margin of the
+menu entry. All 1's in the bitmap will be rendered in the foreground
+color, and all 0's will be drawn in the background color of the
+SimpleMenu widget. It is the
+programmers' responsibility to make sure that the menu entry is tall
+enough, and the appropriate margin wide enough to accept the bitmap.
+If care is not taken the bitmap may extend into another menu entry, or
+into this entry's label.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>leftMargin</term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>rightMargin</term>
+ <listitem>
+ <para>
+This is the amount of space (in pixels) that will be left between the
+edge of the menu entry and the label string.
+<!-- .Se -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>vertSpace</term>
+ <listitem>
+ <para>
+This is the amount of vertical padding, expressed as a percentage of
+the height of the font, that is to be placed around the label of a
+menu entry.. The label and bitmaps are always centered vertically
+within the menu. The default value for this
+resource (25) causes the default height to be 125% of the height of the
+font.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/SmeLine.xml b/libXaw/specs/SmeLine.xml
new file mode 100644
index 000000000..e53728c61
--- /dev/null
+++ b/libXaw/specs/SmeLine.xml
@@ -0,0 +1,148 @@
+<sect1 id="SmeLine_Object">
+<title>SmeLine Object</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- SmeLine Object -->
+<!-- .XE -->
+<!-- .IN "SmeLine object" "" "@DEF@" -->
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+Application Header file &lt;X11/Xaw/SmeLine.h&gt;
+<!-- .IN "SmeLine.h" "" -->
+Class Header file &lt;X11/Xaw/SmeLineP.h&gt;
+<!-- .IN "SmeLineP.h" "" -->
+Class smeLineObjectClass
+<!-- .IN "smeLineObjectClass" "" -->
+Class Name SmeLine
+<!-- .IN "SmeLine object" "class name" -->
+Superclass Sme
+</literallayout>
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+The SmeLine object is used to add a horizontal line or menu separator to
+a menu. Since each SmeLine is an independent object, the application
+is able to change the color, height, and other attributes of the SmeLine
+objects on an entry by entry basis. This object is not selectable, and
+will not highlight when the pointer cursor is over it.
+</para>
+<sect2 id="smeline_resources">
+<title>Resources</title>
+<!-- .IN "SmeLine object" "resources" -->
+<para>
+<!-- .LP -->
+The resources associated with the SmeLine object are defined in this section,
+and affect only the single menu entry specified by this object.
+<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>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry><function>lineWidth</function></entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>lineWidth</entry>
+ <entry>LineWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>stipple</entry>
+ <entry>Stipple</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Dc -->
+<variablelist>
+ <varlistentry>
+ <term>foreground</term>
+ <listitem>
+ <para>
+A pixel value which indexes the SimpleMenu's colormap to derive the
+foreground color used to draw the separator line.
+<!-- .Hw -->
+Keep in mind that the SimpleMenu widget will force all menu items to
+be the width of the widest entry. Thus, setting the width is generally not
+very important.
+<!-- .Ix -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>lineWidth</term>
+ <listitem>
+ <para>
+The width of the horizontal line that is to be displayed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>stipple</term>
+ <listitem>
+ <para>
+If a bitmap is specified for this resource, the line will be stippled
+through it. This allows the menu separator to be rendered as something
+more exciting than just a line. For instance, if you define a stipple
+that is a chain link, then your menu separators will look like chains.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/StripChart.xml b/libXaw/specs/StripChart.xml
new file mode 100644
index 000000000..f51f6fc83
--- /dev/null
+++ b/libXaw/specs/StripChart.xml
@@ -0,0 +1,435 @@
+<sect1 id="StripChart_Widget">
+<title>StripChart Widget</title>
+<!-- .XS -->
+<!-- StripChart Widget -->
+<!-- .XE -->
+<!-- .IN "StripChart widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file &lt;Xaw/StripChart.h&gt;
+<!-- .IN "StripChart.h" "" -->
+Class Header file &lt;Xaw/StripCharP.h&gt;
+<!-- .IN "StripCharP.h" "" -->
+Class stripChartWidgetClass
+<!-- .IN "stripChartWidgetClass" "" -->
+Class Name StripChart
+<!-- .IN "StripChart widget" "class name" -->
+Superclass Simple
+<!-- .sp -->
+</literallayout>
+<para>
+<!-- .LP -->
+The StripChart widget is used to provide a roughly real
+time graphical chart of a single value. For example,
+it is used by the common client program <function>xload</function>
+to provide a graph of processor load. The StripChart
+reads data from an application, and updates the chart
+at the <function>update</function> interval specified.
+</para>
+<sect2 id="stripchart_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a StripChart widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "StripChart widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>getValue</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>120</entry>
+ </row>
+ <row>
+ <entry>highlight</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>jumpScroll</entry>
+ <entry>JumpScroll</entry>
+ <entry>int</entry>
+ <entry>A</entry>
+ <entry>half the width of the widget</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>minScale</entry>
+ <entry>Scale</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Pointer</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>update</entry>
+ <entry>Interval</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry>10</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>120</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Cm -->
+<!-- .Cu -->
+<!-- .Cn -->
+<!-- .Dp -->
+<!-- .Dc -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>foreground</function>
+ </term>
+ <listitem>
+ <para>
+A pixel value which indexes the widget's colormap to derive the color
+that will be used to draw the graph.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>getValue</function>
+ </term>
+ <listitem>
+ <para>
+A list of callback functions to call every <function>update</function> seconds.
+This list should contain one function, which returns the
+value to be graphed by the StripChart widget. The following
+section describes the procedural interface. Behavior when this list has
+more than one function is undefined.
+<!-- .Hw -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>highlight</function>
+ </term>
+ <listitem>
+ <para>
+A pixel value which indexes the widget's colormap to derive the color
+that will be used to draw the scale lines on the graph.
+<!-- .Ib -->
+<!-- .Ix -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>jumpScroll</function>
+ </term>
+ <listitem>
+ <para>
+When the graph reaches the right edge of the window it must be
+scrolled to the left. This resource specifies the number of pixels
+it will jump. Smooth scrolling can be achieved by setting this resource
+to 1.
+<!-- .Mm -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>minScale</function>
+ </term>
+ <listitem>
+ <para>
+The minimum scale for the graph. The number of divisions on the graph
+will always be greater than or equal to this value.
+<!-- .Pf -->
+<!-- .Pb -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>update</function>
+ </term>
+ <listitem>
+ <para>
+The number of seconds between graph updates. Each update is
+represented on the graph as a 1 pixel wide line. Every <function>update</function> seconds
+the <function>getValue</function> procedure will be used to get a new graph point,
+and this point will be added to the right end of the StripChart.
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Getting_the_StripChart_Value">
+<title>Getting the StripChart Value</title>
+<!-- .IN "StripChart widget" "getting the value" -->
+<para>
+<!-- .LP -->
+The StripChart widget will call the application routine passed to it
+as the <function>getValue</function> callback function every <function>update</function> seconds to
+obtain another point for the StripChart graph.
+</para>
+<para>
+<!-- .LP -->
+The calling interface for the <function>getValue</function> callback is:
+<!-- .IN "StripChart widget" "getValue callback" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> void</function>(*getValueProc)</funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XtPointer<parameter> value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the StripChart widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a pointer to a double. The application should set the address
+pointed to by this argument to a double containing the value to be
+graphed on the StripChart.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function is used by the StripChart to call an application routine.
+The routine will pass the value to be graphed back to the the StripChart
+in the <function>value</function> field of this routine.
+
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/TPage_Credits.xml b/libXaw/specs/TPage_Credits.xml
new file mode 100644
index 000000000..bc07351ab
--- /dev/null
+++ b/libXaw/specs/TPage_Credits.xml
@@ -0,0 +1,90 @@
+<chapter>
+<title>Acknowledgments</title>
+
+<para>
+Many thanks go to Ralph Swick (Project Athena / Digital) who has
+contributed much time and effort to this widget set. Previous
+versions of the widget set are largely due to his time and effort.
+Many of the improvements that I have been able to make are because he
+provided a solid foundation to build upon. While much of the effort
+has been Ralph's, many other people have contributed to the code.
+</para>
+
+<literallayout class="monospaced">
+Mark Ackerman (formerly Project Athena)
+Donna Converse (MIT X Consortium)
+Jim Fulton (formerly MIT X Consortium)
+Loretta Guarino-Reid (Digital WSL)
+Charles Haynes (Digital WSL)
+Rich Hyde (Digital WSL)
+Mary Larson (Digital UEG)
+Joel McCormack (Digital WSL)
+Ron Newman (formerly Project Athena)
+Jeanne Rich (Digital WSL)
+Terry Weissman (formerly Digital WSL)
+</literallayout>
+
+<para>
+While not much remains of the X10 toolkit, many of the ideas for this
+widget set come from that original version. The design and
+implementation of the X10 toolkit were done by:
+</para>
+
+<literallayout class="monospaced">
+Mike Gancarz (formerly Digital UEG)
+Charles Haynes (Digital WSL)
+Phil Karlton (formerly Digital WSL)
+Kathleen Langone (Digital UEG)
+Mary Larson (Digital UEG)
+Ram Rao (Digital UEG)
+Smokey Wallace (formerly Digital WSL)
+Terry Weissman (formerly Digital WSL)
+</literallayout>
+
+<para>
+I have used the formatting ideas, and some of the words from previous
+versions of this document. The X11R3 Athena widget document was written by:
+</para>
+
+<literallayout class="monospaced">
+Ralph R. Swick (Project Athena/ Digital)
+Terry Weissman (formerly Digital WSL)
+Al Mento (Digital UEG)
+</literallayout>
+
+<para>
+Putting this manual together was a major task in and of itself. I
+would like to thank Ralph Swick, Donna Converse, and Jim Fulton for
+taking the time to help convert my technical knowledge into legible
+text. A special thanks to Jean Diaz (O'Reilly and Associates) for
+spending nearly a month with me working out all the annoying little
+details.
+</para>
+
+<literallayout class="monospaced">
+Chris D. Peterson
+MIT X Consortium 1989
+</literallayout>
+
+<para>
+The R5 edition of this document has been edited by the research staff of
+the MIT X Consortium, with significant contributions by Jim Fulton (NCD).
+</para>
+
+<literallayout class="monospaced">
+Donna Converse
+MIT X Consortium 1991
+</literallayout>
+
+<para>
+The R6 edition of this document has been edited to reflect changes
+brought about by research staff of the Omron Corporation, with special
+recognition to Li Yuhong, Seiji Kuwari, and Hiroshi Kuribayashi for
+the X11R5/contrib/lib/Xaw internationalization that inspired this version.
+</para>
+<literallayout class="monospaced">
+Frank Sheeran
+Omron Corporation 1994
+</literallayout>
+
+</chapter>
diff --git a/libXaw/specs/Template.xml b/libXaw/specs/Template.xml
new file mode 100644
index 000000000..2d94ca829
--- /dev/null
+++ b/libXaw/specs/Template.xml
@@ -0,0 +1,407 @@
+<sect2 id="Public_Header_File">
+<title>Public Header File</title>
+<para>
+The public header file contains declarations that will be required by any
+application module that needs to refer to the widget; whether to create
+an instance of the class, to perform an
+<function>XtSetValues</function>
+operation, or to call a public routine implemented by the widget class.
+</para>
+<para>
+<!-- .LP -->
+The contents of the Template public header file,
+<function>&lt; X11/Xaw/Template.h &gt;, </function>
+are:
+</para>
+<literallayout class="monospaced">
+..
+<!-- .CB -->
+<!-- .\".so ../../lib/Xaw/Template.h -->
+/* Copyright (c) X Consortium 1987, 1988 */
+
+#ifndef _Template_h
+#define _Template_h
+
+/****************************************************************
+ *
+ * Template widget
+ *
+ ****************************************************************/
+
+/* Resources:
+
+ Name Class RepType Default Value
+ ---- ----- ------- -------------
+ background Background Pixel XtDefaultBackground
+ border BorderColor Pixel XtDefaultForeground
+ borderWidth BorderWidth Dimension 1
+ destroyCallback Callback Pointer NULL
+ height Height Dimension 0
+ mappedWhenManaged MappedWhenManaged Boolean True
+ sensitive Sensitive Boolean True
+ width Width Dimension 0
+ x Position Position 0
+ y Position Position 0
+
+*/
+
+/* define any special resource names here that are not in &lt;X11/StringDefs.h&gt; */
+
+#define XtNtemplateResource "templateResource"
+
+#define XtCTemplateResource "TemplateResource"
+
+/* declare specific TemplateWidget class and instance datatypes */
+
+typedef struct _TemplateClassRec* TemplateWidgetClass;
+typedef struct _TemplateRec* TemplateWidget;
+
+/* declare the class constant */
+
+extern WidgetClass templateWidgetClass;
+
+#endif /* _Template_h */
+<!-- .CE -->
+</literallayout>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+You will notice that most of this file is documentation. The crucial
+parts are the last 8 lines where macros for any private resource names
+and classes are defined and where the widget class datatypes and class
+record pointer are declared.
+</para>
+<para>
+<!-- .LP -->
+For the "WindowWidget", we want 2 drawing colors, a callback list for
+user input and an
+<function>exposeCallback</function> callback list, and we will declare three
+convenience procedures, so we need to add
+</para>
+<literallayout class="monospaced">
+<!-- .LP -->
+<!-- .sp -->
+<!-- .CB -->
+/* Resources:
+ ...
+ callback Callback Callback NULL
+ drawingColor1 Color Pixel XtDefaultForeground
+ drawingColor2 Color Pixel XtDefaultForeground
+ exposeCallback Callback Callback NULL
+ font Font XFontStruct* XtDefaultFont
+ ...
+ */
+
+#define XtNdrawingColor1 "drawingColor1"
+#define XtNdrawingColor2 "drawingColor2"
+#define XtNexposeCallback "exposeCallback"
+
+extern Pixel WindowColor1(\|/* Widget */\|);
+extern Pixel WindowColor2(\|/* Widget */\|);
+extern Font\ \ WindowFont(\|/* Widget */\|);
+<!-- .CE -->
+</literallayout>
+<para>
+<!-- .LP -->
+Note that we have chosen to call the input callback list by the generic
+name, <function>callback</function>, rather than a specific name. If widgets that define
+a single user-input action all choose the same resource name then there
+is greater possibility for an application to switch between widgets of
+different types.
+</para>
+</sect2>
+<sect2 id="Private_Header_File">
+<title>Private Header File</title>
+<para>
+<!-- .LP -->
+The private header file contains the complete declaration of the class
+and instance structures for the widget and any additional private data
+that will be required by anticipated subclasses of the widget.
+Information in the private header file is normally hidden from the
+application and is designed to be accessed only through other public
+procedures; e.g.
+<function>XtSetValues .</function>
+</para>
+<para>
+<!-- .LP -->
+The contents of the Template private header file,
+<function>&lt; X11/Xaw/TemplateP.h &gt;, </function>
+are:
+</para>
+<!-- .CB -->
+<!-- .\".so ../../lib/Xaw/TemplateP.h -->
+<literallayout class="monospaced">
+/* Copyright (c) X Consortium 1987, 1988
+ */
+
+#ifndef _TemplateP_h
+#define _TemplateP_h
+
+#include &lt;X11/Xaw/Template.h&gt;
+/* include superclass private header file */
+#include &lt;X11/CoreP.h&gt;
+
+/* define unique representation types not found in &lt;X11/StringDefs.h&gt; */
+
+#define XtRTemplateResource "TemplateResource"
+
+typedef struct {
+ int empty;
+} TemplateClassPart;
+
+typedef struct _TemplateClassRec {
+ CoreClassPart core_class;
+ TemplateClassPart template_class;
+} TemplateClassRec;
+
+extern TemplateClassRec templateClassRec;
+
+typedef struct {
+ /* resources */
+ char* resource;
+ /* private state */
+} TemplatePart;
+
+typedef struct _TemplateRec {
+ CorePart core;
+ TemplatePart template;
+} TemplateRec;
+
+#endif /* _TemplateP_h */
+<!-- .CE -->
+</literallayout>
+<para>
+The private header file includes the private header file of its
+superclass, thereby exposing the entire internal structure of the widget.
+It may not always be advantageous to do this; your own project
+development style will dictate the appropriate level of detail to expose
+in each module.
+</para>
+<para>
+The "WindowWidget" needs to declare two fields in its instance structure to
+hold the drawing colors, a resource field for the font and a field for the
+expose and user input callback lists:
+</para>
+
+<literallayout class="monospaced">
+typedef struct {
+ /* resources */
+ Pixel color_1;
+ Pixel color_2;
+ XFontStruct* font;
+ XtCallbackList expose_callback;
+ XtCallbackList input_callback;
+ /* private state */
+ /* (none) */
+} WindowPart;
+</literallayout>
+
+</sect2>
+<sect2 id="Widget_Source_File">
+<title>Widget Source File</title>
+<para>
+<!-- .LP -->
+The source code file implements the widget class itself. The unique
+part of this file is the declaration and initialization of the
+widget class record structure and the declaration of all resources and
+action routines added by the widget class.
+</para>
+<para>
+<!-- .LP -->
+The contents of the Template implementation file,
+<function>&lt; X11/Xaw/Template.c &gt;,</function>
+are:
+</para>
+<!-- .CB -->
+<!-- .\".so ../../lib/Xaw/Template.c -->
+<literallayout class="monospaced">
+/* Copyright (c) X Consortium 1987, 1988
+ */
+
+#include &lt;X11/IntrinsicP.h&gt;
+#include &lt;X11/StringDefs.h&gt;
+#include "TemplateP.h"
+
+static XtResource resources[] = {
+#define offset(field) XtOffsetOf(TemplateRec, template.field)
+ /* {name, class, type, size, offset, default_type, default_addr}, */
+ { XtNtemplateResource, XtCTemplateResource, XtRTemplateResource,
+ sizeof(char*), offset(resource), XtRString, (XtPointer) "default" },
+#undef offset
+};
+
+static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */);
+
+static XtActionsRec actions[] =
+{
+ /* {name, procedure}, */
+ {"template", TemplateAction},
+};
+
+static char translations[] =
+" &lt;Key&gt;: template(\|) \\n\\
+";
+
+TemplateClassRec templateClassRec = {
+ { /* core fields */
+ /* superclass */ (WidgetClass) &amp;widgetClassRec,
+ /* class_name */ "Template",
+ /* widget_size */ sizeof(TemplateRec),
+ /* class_initialize */ NULL,
+ /* class_part_initialize */ NULL,
+ /* class_inited */ FALSE,
+ /* initialize */ NULL,
+ /* initialize_hook */ NULL,
+ /* realize */ XtInheritRealize,
+ /* actions */ actions,
+ /* num_actions */ XtNumber(actions),
+ /* resources */ resources,
+ /* num_resources */ XtNumber(resources),
+ /* xrm_class */ NULLQUARK,
+ /* compress_motion */ TRUE,
+ /* compress_exposure */ TRUE,
+ /* compress_enterleave */ TRUE,
+ /* visible_interest */ FALSE,
+ /* destroy */ NULL,
+ /* resize */ NULL,
+ /* expose */ NULL,
+ /* set_values */ NULL,
+ /* set_values_hook */ NULL,
+ /* set_values_almost */ XtInheritSetValuesAlmost,
+ /* get_values_hook */ NULL,
+ /* accept_focus */ NULL,
+ /* version */ XtVersion,
+ /* callback_private */ NULL,
+ /* tm_table */ translations,
+ /* query_geometry */ XtInheritQueryGeometry,
+ /* display_accelerator */ XtInheritDisplayAccelerator,
+ /* extension */ NULL
+ },
+ { /* template fields */
+ /* empty */ 0
+ }
+};
+
+WidgetClass templateWidgetClass = (WidgetClass)&amp;templateClassRec;
+</literallayout>
+<!-- .CE -->
+<para>
+The resource list for the "WindowWidget" might look like the following:
+</para>
+<!-- .CB -->
+<literallayout class="monospaced">
+static XtResource resources[] = {
+#define offset(field) XtOffsetOf(WindowWidgetRec, window.field)
+ /* {name, class, type, size, offset, default_type, default_addr}, */
+ { XtNdrawingColor1, XtCColor, XtRPixel, sizeof(Pixel),
+ offset(color_1), XtRString, XtDefaultForeground },
+ { XtNdrawingColor2, XtCColor, XtRPixel, sizeof(Pixel),
+ offset(color_2), XtRString, XtDefaultForeground },
+ { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*),
+ offset(font), XtRString, XtDefaultFont },
+ { XtNexposeCallback, XtCCallback, XtRCallback, sizeof(XtCallbackList),
+ offset(expose_callback), XtRCallback, NULL },
+ { XtNcallback, XtCCallback, XtRCallback, sizeof(XtCallbackList),
+ offset(input_callback), XtRCallback, NULL },
+#undef offset
+};
+</literallayout>
+<!-- .CE -->
+<para>
+<!-- .LP -->
+The user input callback will be implemented by an action procedure which
+passes the event pointer as call_data. The action procedure
+is declared as:
+<!-- .CB -->
+</para>
+<literallayout class="monospaced">
+/* ARGSUSED */
+static void InputAction(w, event, params, num_params)
+ Widget w;
+ XEvent *event;
+ String *params; /* unused */
+ Cardinal *num_params; /* unused */
+{
+ XtCallCallbacks(w, XtNcallback, (XtPointer)event);
+}
+
+static XtActionsRec actions[] =
+{
+ /* {name, procedure}, */
+ {"input", InputAction},
+};
+</literallayout>
+<!-- .CE -->
+<para>
+<!-- .LP -->
+and the default input binding will be to execute the input callbacks on
+<function>KeyPress</function> and <function>ButtonPress : </function>
+</para>
+<literallayout class="monospaced">
+static char translations[] =
+" &lt;Key&gt;: input(\|) \\n\\
+ &lt;BtnDown&gt;: input(\|) \\
+";
+</literallayout>
+<!-- .CE -->
+<para>
+In the class record declaration and initialization, the only field that
+is different from the Template is the expose procedure:
+</para>
+<!-- .CB -->
+<literallayout class="monospaced">
+/* ARGSUSED */
+static void Redisplay(w, event, region)
+ Widget w;
+ XEvent *event; /* unused */
+ Region region;
+{
+ XtCallCallbacks(w, XtNexposeCallback, (XtPointer)region);
+}
+
+WindowClassRec windowClassRec = {
+
+ ...
+
+ /* expose */ Redisplay,
+</literallayout>
+<!-- .CE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The "WindowWidget" will also declare three public procedures to return the
+drawing colors and the font id, saving the application the effort of
+constructing an argument list for a call to
+<function>XtGetValues :</function>
+</para>
+<!-- .LP -->
+<!-- .CB -->
+<literallayout class="monospaced">
+Pixel WindowColor1(w)
+ Widget w;
+{
+ return ((WindowWidget)w)->window.color_1;
+}
+
+Pixel WindowColor2(w)
+ Widget w;
+{
+ return ((WindowWidget)w)->window.color_2;
+}
+
+Font WindowFont(w)
+ Widget w;
+{
+ return ((WindowWidget)w)->window.font->fid;
+}
+</literallayout>
+
+<para>
+The "WindowWidget" is now complete. The application can retrieve the two
+drawing colors from the widget instance by calling either
+<function>XtGetValues ,</function>
+or the <function>WindowColor</function> functions. The actual window created for the
+"WindowWidget" is available by calling the
+<function>XtWindow</function> function.
+</para>
+</sect2>
diff --git a/libXaw/specs/Template_private_header_file.xml b/libXaw/specs/Template_private_header_file.xml
new file mode 100644
index 000000000..a26e92eef
--- /dev/null
+++ b/libXaw/specs/Template_private_header_file.xml
@@ -0,0 +1,87 @@
+<sect1 id="Private_Header_File">
+<title>Private Header File</title>
+<para>
+<!-- .LP -->
+The private header file contains the complete declaration of the class
+and instance structures for the widget and any additional private data
+that will be required by anticipated subclasses of the widget.
+Information in the private header file is normally hidden from the
+application and is designed to be accessed only through other public
+procedures; e.g.
+<function>XtSetValues .</function>
+</para>
+<para>
+<!-- .LP -->
+The contents of the Template private header file,
+<function>&lt; X11/Xaw/TemplateP.h &gt;, </function>
+are:
+</para>
+<!-- .CB -->
+<!-- .\".so ../../lib/Xaw/TemplateP.h -->
+<literallayout class="monospaced">
+/* Copyright (c) X Consortium 1987, 1988
+ */
+
+#ifndef _TemplateP_h
+#define _TemplateP_h
+
+#include &lt;X11/Xaw/Template.h&gt;
+/* include superclass private header file */
+#include &lt;X11/CoreP.h&gt;
+
+/* define unique representation types not found in &lt;X11/StringDefs.h&gt; */
+
+#define XtRTemplateResource "TemplateResource"
+
+typedef struct {
+ int empty;
+} TemplateClassPart;
+
+typedef struct _TemplateClassRec {
+ CoreClassPart core_class;
+ TemplateClassPart template_class;
+} TemplateClassRec;
+
+extern TemplateClassRec templateClassRec;
+
+typedef struct {
+ /* resources */
+ char* resource;
+ /* private state */
+} TemplatePart;
+
+typedef struct _TemplateRec {
+ CorePart core;
+ TemplatePart template;
+} TemplateRec;
+
+#endif /* _TemplateP_h */
+<!-- .CE -->
+</literallayout>
+<para>
+The private header file includes the private header file of its
+superclass, thereby exposing the entire internal structure of the widget.
+It may not always be advantageous to do this; your own project
+development style will dictate the appropriate level of detail to expose
+in each module.
+</para>
+<para>
+The "WindowWidget" needs to declare two fields in its instance structure to
+hold the drawing colors, a resource field for the font and a field for the
+expose and user input callback lists:
+</para>
+
+<literallayout class="monospaced">
+typedef struct {
+ /* resources */
+ Pixel color_1;
+ Pixel color_2;
+ XFontStruct* font;
+ XtCallbackList expose_callback;
+ XtCallbackList input_callback;
+ /* private state */
+ /* (none) */
+} WindowPart;
+</literallayout>
+
+</sect1>
diff --git a/libXaw/specs/Template_public_header_file.xml b/libXaw/specs/Template_public_header_file.xml
new file mode 100644
index 000000000..b17379677
--- /dev/null
+++ b/libXaw/specs/Template_public_header_file.xml
@@ -0,0 +1,112 @@
+<sect1 id="Public_Header_File">
+<title>Public Header File</title>
+<para>
+The public header file contains declarations that will be required by any
+application module that needs to refer to the widget; whether to create
+an instance of the class, to perform an
+<function>XtSetValues</function>
+operation, or to call a public routine implemented by the widget class.
+</para>
+<para>
+<!-- .LP -->
+The contents of the Template public header file,
+<function>&lt; X11/Xaw/Template.h &gt;, </function>
+are:
+</para>
+<literallayout class="monospaced">
+..
+<!-- .CB -->
+<!-- .\".so ../../lib/Xaw/Template.h -->
+/* Copyright (c) X Consortium 1987, 1988 */
+
+#ifndef _Template_h
+#define _Template_h
+
+/****************************************************************
+ *
+ * Template widget
+ *
+ ****************************************************************/
+
+/* Resources:
+
+ Name Class RepType Default Value
+ ---- ----- ------- -------------
+ background Background Pixel XtDefaultBackground
+ border BorderColor Pixel XtDefaultForeground
+ borderWidth BorderWidth Dimension 1
+ destroyCallback Callback Pointer NULL
+ height Height Dimension 0
+ mappedWhenManaged MappedWhenManaged Boolean True
+ sensitive Sensitive Boolean True
+ width Width Dimension 0
+ x Position Position 0
+ y Position Position 0
+
+*/
+
+/* define any special resource names here that are not in &lt;X11/StringDefs.h&gt; */
+
+#define XtNtemplateResource "templateResource"
+
+#define XtCTemplateResource "TemplateResource"
+
+/* declare specific TemplateWidget class and instance datatypes */
+
+typedef struct _TemplateClassRec* TemplateWidgetClass;
+typedef struct _TemplateRec* TemplateWidget;
+
+/* declare the class constant */
+
+extern WidgetClass templateWidgetClass;
+
+#endif /* _Template_h */
+<!-- .CE -->
+</literallayout>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+You will notice that most of this file is documentation. The crucial
+parts are the last 8 lines where macros for any private resource names
+and classes are defined and where the widget class datatypes and class
+record pointer are declared.
+</para>
+<para>
+<!-- .LP -->
+For the "WindowWidget", we want 2 drawing colors, a callback list for
+user input and an
+<function>exposeCallback</function> callback list, and we will declare three
+convenience procedures, so we need to add
+</para>
+<literallayout class="monospaced">
+<!-- .LP -->
+<!-- .sp -->
+<!-- .CB -->
+/* Resources:
+ ...
+ callback Callback Callback NULL
+ drawingColor1 Color Pixel XtDefaultForeground
+ drawingColor2 Color Pixel XtDefaultForeground
+ exposeCallback Callback Callback NULL
+ font Font XFontStruct* XtDefaultFont
+ ...
+ */
+
+#define XtNdrawingColor1 "drawingColor1"
+#define XtNdrawingColor2 "drawingColor2"
+#define XtNexposeCallback "exposeCallback"
+
+extern Pixel WindowColor1(\|/* Widget */\|);
+extern Pixel WindowColor2(\|/* Widget */\|);
+extern Font\ \ WindowFont(\|/* Widget */\|);
+<!-- .CE -->
+</literallayout>
+<para>
+<!-- .LP -->
+Note that we have chosen to call the input callback list by the generic
+name, <function>callback</function>, rather than a specific name. If widgets that define
+a single user-input action all choose the same resource name then there
+is greater possibility for an application to switch between widgets of
+different types.
+</para>
+</sect1>
diff --git a/libXaw/specs/Template_widget_source_file.xml b/libXaw/specs/Template_widget_source_file.xml
new file mode 100644
index 000000000..62ad1b69c
--- /dev/null
+++ b/libXaw/specs/Template_widget_source_file.xml
@@ -0,0 +1,208 @@
+<sect1 id="Widget_Source_File">
+<title>Widget Source File</title>
+<para>
+<!-- .LP -->
+The source code file implements the widget class itself. The unique
+part of this file is the declaration and initialization of the
+widget class record structure and the declaration of all resources and
+action routines added by the widget class.
+</para>
+<para>
+<!-- .LP -->
+The contents of the Template implementation file,
+<function>&lt; X11/Xaw/Template.c &gt;,</function>
+are:
+</para>
+<!-- .CB -->
+<!-- .\".so ../../lib/Xaw/Template.c -->
+<literallayout class="monospaced">
+/* Copyright (c) X Consortium 1987, 1988
+ */
+
+#include &lt;X11/IntrinsicP.h&gt;
+#include &lt;X11/StringDefs.h&gt;
+#include "TemplateP.h"
+
+static XtResource resources[] = {
+#define offset(field) XtOffsetOf(TemplateRec, template.field)
+ /* {name, class, type, size, offset, default_type, default_addr}, */
+ { XtNtemplateResource, XtCTemplateResource, XtRTemplateResource,
+ sizeof(char*), offset(resource), XtRString, (XtPointer) "default" },
+#undef offset
+};
+
+static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */);
+
+static XtActionsRec actions[] =
+{
+ /* {name, procedure}, */
+ {"template", TemplateAction},
+};
+
+static char translations[] =
+" &lt;Key&gt;: template(\|) \\n\\
+";
+
+TemplateClassRec templateClassRec = {
+ { /* core fields */
+ /* superclass */ (WidgetClass) &amp;widgetClassRec,
+ /* class_name */ "Template",
+ /* widget_size */ sizeof(TemplateRec),
+ /* class_initialize */ NULL,
+ /* class_part_initialize */ NULL,
+ /* class_inited */ FALSE,
+ /* initialize */ NULL,
+ /* initialize_hook */ NULL,
+ /* realize */ XtInheritRealize,
+ /* actions */ actions,
+ /* num_actions */ XtNumber(actions),
+ /* resources */ resources,
+ /* num_resources */ XtNumber(resources),
+ /* xrm_class */ NULLQUARK,
+ /* compress_motion */ TRUE,
+ /* compress_exposure */ TRUE,
+ /* compress_enterleave */ TRUE,
+ /* visible_interest */ FALSE,
+ /* destroy */ NULL,
+ /* resize */ NULL,
+ /* expose */ NULL,
+ /* set_values */ NULL,
+ /* set_values_hook */ NULL,
+ /* set_values_almost */ XtInheritSetValuesAlmost,
+ /* get_values_hook */ NULL,
+ /* accept_focus */ NULL,
+ /* version */ XtVersion,
+ /* callback_private */ NULL,
+ /* tm_table */ translations,
+ /* query_geometry */ XtInheritQueryGeometry,
+ /* display_accelerator */ XtInheritDisplayAccelerator,
+ /* extension */ NULL
+ },
+ { /* template fields */
+ /* empty */ 0
+ }
+};
+
+WidgetClass templateWidgetClass = (WidgetClass)&amp;templateClassRec;
+</literallayout>
+<!-- .CE -->
+<para>
+The resource list for the "WindowWidget" might look like the following:
+</para>
+<!-- .CB -->
+<literallayout class="monospaced">
+static XtResource resources[] = {
+#define offset(field) XtOffsetOf(WindowWidgetRec, window.field)
+ /* {name, class, type, size, offset, default_type, default_addr}, */
+ { XtNdrawingColor1, XtCColor, XtRPixel, sizeof(Pixel),
+ offset(color_1), XtRString, XtDefaultForeground },
+ { XtNdrawingColor2, XtCColor, XtRPixel, sizeof(Pixel),
+ offset(color_2), XtRString, XtDefaultForeground },
+ { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*),
+ offset(font), XtRString, XtDefaultFont },
+ { XtNexposeCallback, XtCCallback, XtRCallback, sizeof(XtCallbackList),
+ offset(expose_callback), XtRCallback, NULL },
+ { XtNcallback, XtCCallback, XtRCallback, sizeof(XtCallbackList),
+ offset(input_callback), XtRCallback, NULL },
+#undef offset
+};
+</literallayout>
+<!-- .CE -->
+<para>
+<!-- .LP -->
+The user input callback will be implemented by an action procedure which
+passes the event pointer as call_data. The action procedure
+is declared as:
+<!-- .CB -->
+</para>
+<literallayout class="monospaced">
+/* ARGSUSED */
+static void InputAction(w, event, params, num_params)
+ Widget w;
+ XEvent *event;
+ String *params; /* unused */
+ Cardinal *num_params; /* unused */
+{
+ XtCallCallbacks(w, XtNcallback, (XtPointer)event);
+}
+
+static XtActionsRec actions[] =
+{
+ /* {name, procedure}, */
+ {"input", InputAction},
+};
+</literallayout>
+<!-- .CE -->
+<para>
+<!-- .LP -->
+and the default input binding will be to execute the input callbacks on
+<function>KeyPress</function> and <function>ButtonPress : </function>
+</para>
+<literallayout class="monospaced">
+static char translations[] =
+" &lt;Key&gt;: input(\|) \\n\\
+ &lt;BtnDown&gt;: input(\|) \\
+";
+</literallayout>
+<!-- .CE -->
+<para>
+In the class record declaration and initialization, the only field that
+is different from the Template is the expose procedure:
+</para>
+<!-- .CB -->
+<literallayout class="monospaced">
+/* ARGSUSED */
+static void Redisplay(w, event, region)
+ Widget w;
+ XEvent *event; /* unused */
+ Region region;
+{
+ XtCallCallbacks(w, XtNexposeCallback, (XtPointer)region);
+}
+
+WindowClassRec windowClassRec = {
+
+ ...
+
+ /* expose */ Redisplay,
+</literallayout>
+<!-- .CE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The "WindowWidget" will also declare three public procedures to return the
+drawing colors and the font id, saving the application the effort of
+constructing an argument list for a call to
+<function>XtGetValues :</function>
+</para>
+<!-- .LP -->
+<!-- .CB -->
+<literallayout class="monospaced">
+Pixel WindowColor1(w)
+ Widget w;
+{
+ return ((WindowWidget)w)->window.color_1;
+}
+
+Pixel WindowColor2(w)
+ Widget w;
+{
+ return ((WindowWidget)w)->window.color_2;
+}
+
+Font WindowFont(w)
+ Widget w;
+{
+ return ((WindowWidget)w)->window.font->fid;
+}
+</literallayout>
+
+<para>
+The "WindowWidget" is now complete. The application can retrieve the two
+drawing colors from the widget instance by calling either
+<function>XtGetValues ,</function>
+or the <function>WindowColor</function> functions. The actual window created for the
+"WindowWidget" is available by calling the
+<function>XtWindow</function> function.
+</para>
+</sect1>
diff --git a/libXaw/specs/Text.xml b/libXaw/specs/Text.xml
new file mode 100644
index 000000000..3daf7d3e4
--- /dev/null
+++ b/libXaw/specs/Text.xml
@@ -0,0 +1,326 @@
+<sect1 id="Text_Widget_">
+<title>Text Widget</title>
+
+<literallayout class="monospaced">
+Application Header file &lt;X11/Xaw/Text.h&gt;
+Class Header file &lt;X11/Xaw/TextP.h&gt;
+Class textWidgetClass
+Class Name Text
+Superclass Simple
+</literallayout>
+
+
+<para>
+The Text widget is the glue that binds all the other pieces together, it
+maintains the internal state of the displayed text, and acts as a
+mediator between the source and sink.
+</para>
+
+<para>
+This section lists the resources that are actually part of the
+Text widget, and explains the functionality provided by each.
+</para>
+<sect2 id="Resources_">
+<title>Resources</title>
+
+<para>
+When creating a Text widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+
+<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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>autoFill</entry>
+ <entry>AutoFill</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>bottomMargin</entry>
+ <entry>Margin</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>XC_xterm</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>displayCaret</entry>
+ <entry>Output</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>displayPosition</entry>
+ <entry>TextPosition</entry>
+ <entry>XawTextPosition</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Font height + margins</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>insertPosition</entry>
+ <entry>TextPosition</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>leftMargin</entry>
+ <entry>Margin</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>resize</entry>
+ <entry>Resize</entry>
+ <entry>XawTextResizeMode</entry>
+ <entry></entry>
+ <entry>XawtextResizeNever</entry>
+ </row>
+ <row>
+ <entry>rightMargin</entry>
+ <entry>Margin</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Pointer</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>scrollHorizontal</entry>
+ <entry>Scroll</entry>
+ <entry>ScrollMode</entry>
+ <entry></entry>
+ <entry>XawtextScrollNever</entry>
+ </row>
+ <row>
+ <entry>scrollVertical</entry>
+ <entry>Scroll</entry>
+ <entry>XawTextScrollMode</entry>
+ <entry></entry>
+ <entry>XawtextScrollNever</entry>
+ </row>
+ <row>
+ <entry>selectTypes</entry>
+ <entry>SelectTypes</entry>
+ <entry>XawTextSelectType*</entry>
+ <entry></entry>
+ <entry>See above</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>textSink</entry>
+ <entry>TextSink</entry>
+ <entry>Widget</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>textSource</entry>
+ <entry>TextSource</entry>
+ <entry>Widget</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>topMargin</entry>
+ <entry>Margin</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>See above</entry>
+ </row>
+ <row>
+ <entry>unrealizeCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>100</entry>
+ </row>
+ <row>
+ <entry>wrap</entry>
+ <entry>Wrap</entry>
+ <entry>WrapMode</entry>
+ <entry></entry>
+ <entry>XawtextWrapNever</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+</sect2>
+</sect1>
diff --git a/libXaw/specs/TextActions.xml b/libXaw/specs/TextActions.xml
new file mode 100644
index 000000000..0af3bec48
--- /dev/null
+++ b/libXaw/specs/TextActions.xml
@@ -0,0 +1,976 @@
+<sect2 id="Text_Widget_Actions">
+<title>Text Widget Actions</title>
+<para>
+<!-- .LP -->
+<!-- .IN "Text widget" "actions" -->
+<!-- .XS -->
+<!-- Actions Supported by all Text Widgets -->
+<!-- .XE -->
+<!-- .IN "Text widget" "actions" "@DEF@" -->
+
+All editing functions are performed by translation manager actions that may
+be specified through the <function>translations</function> resource in the Text widget.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i 3i -->
+<!-- .ta .5i 2.5i 3i -->
+Insert Point Movement Delete
+ forward-character delete-next-character
+ backward-character delete-previous-character
+ forward-word delete-next-word
+ backward-word delete-previous-word
+ forward-paragraph delete-selection
+ backward-paragraph
+ beginning-of-line
+ end-of-line Selection
+ next-line select-word
+ previous-line select-all
+ next-page select-start
+ previous-page select-adjust
+ beginning-of-file select-end
+ end-of-file extend-start
+ scroll-one-line-up extend-adjust
+ scroll-one-line-down extend-end
+ insert-selection
+
+
+Miscellaneous New Line
+ redraw-display newline-and-indent
+ insert-file newline-and-backup
+ insert-char newline
+ insert-string
+ display-caret
+ focus-in Kill
+ focus-in kill-word
+ search backward-kill-word
+ multiply kill-selection
+ form-paragraph kill-to-end-of-line
+ transpose-characters kill-paragraph
+ no-op kill-to-end-of-paragraph
+ XawWMProtocols
+ reconnect-im
+</literallayout>
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+Most of the actions take no arguments, and unless otherwise noted you
+may assume this to be the case.
+</para>
+<para>
+<!-- .LP -->
+</para>
+<sect3 id="Cursor_Movement_Actions_fP">
+<title>Cursor Movement Actions\fP</title>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<variablelist>
+ <varlistentry>
+ <term>
+ forward-character()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ backward-character()
+ </term>
+ <listitem>
+ <para>
+These actions move the insert point forward or backward one character in
+the buffer. If the insert point is at the end or beginning of a line
+this action will move the insert point to the next (or previous) line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ forward-word()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ backward-word()
+ </term>
+ <listitem>
+ <para>
+These actions move the insert point to the next or previous word boundary.
+A word boundary is defined as a Space, Tab or Carriage Return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ forward-paragraph()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ backward-paragraph()
+ </term>
+ <listitem>
+ <para>
+These actions move the insert point to the next or previous paragraph boundary.
+A paragraph boundary is defined as two Carriage Returns in a row with only
+Spaces or Tabs between them.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ beginning-of-line()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ end-of-line()
+ </term>
+ <listitem>
+ <para>
+These actions move to the beginning or end of the current line. If the
+insert point is already at the end or beginning of the line then no action is taken.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ next-line()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ previous-line()
+ </term>
+ <listitem>
+ <para>
+These actions move the insert point up or down one line. If the insert
+point is currently N characters from the beginning of the line then it
+will be N characters from the beginning of the next or previous line.
+If N is past the end of the line, the insert point is placed at the end
+of the line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ next-page()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ previous-page()
+ </term>
+ <listitem>
+ <para>
+These actions move the insert point up or down one page in the file.
+One page is defined as the current height of the text widget. The
+insert point is always placed at the first character of the top line by
+this action.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ beginning-of-file()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ end-of-file()
+ </term>
+ <listitem>
+ <para>
+These actions place the insert point at the beginning or end of the
+current text buffer. The text widget is then scrolled the minimum
+amount necessary to make the new insert point location visible.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ scroll-one-line-up()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ scroll-one-line-down()
+ </term>
+ <listitem>
+ <para>
+These actions scroll the current text field up or down by one line.
+They do not move the insert point. Other than the scrollbars this is
+the only way that the insert point may be moved off of the visible text
+area. The widget will be scrolled so that the insert point is back on
+the screen as soon as some other action is executed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect3>
+<sect3 id="Delete_Actions">
+<title>Delete Actions</title>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<variablelist>
+ <varlistentry>
+ <term>
+ delete-next-character()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ delete-previous-character()
+ </term>
+ <listitem>
+ <para>
+These actions remove the character immediately before or after the
+insert point. If a Carriage Return is removed then the next line is
+appended to the end of the current line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ delete-next-word()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ delete-previous-word()
+ </term>
+ <listitem>
+ <para>
+These actions remove all characters between the insert point location and
+the next word boundary. A word boundary is defined as a Space, Tab or
+Carriage Return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ delete-selection()
+ </term>
+ <listitem>
+ <para>
+This action removes all characters in the current selection.
+The selection can be set with the selection actions.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect3>
+<sect3 id="Selection_Actions">
+<title>Selection Actions</title>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<variablelist>
+ <varlistentry>
+ <term>
+ select-word()
+ </term>
+ <listitem>
+ <para>
+This action selects the word in which the insert point is currently located.
+If the insert point is between words then it will select the previous word.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ select-all()
+ </term>
+ <listitem>
+ <para>
+This action selects the entire text buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ select-start()
+ </term>
+ <listitem>
+ <para>
+This action sets the insert point to the current pointer location (if
+triggered by a button event) or text cursor location (if triggered by
+a key event). It
+will then begin a selection at this location. If many of these
+selection actions occur quickly in succession then the selection count
+mechanism will be invoked (see the section titled \fBText Selections for
+Application Programmers\fP for details). <!-- xref -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ select-adjust()
+ </term>
+ <listitem>
+ <para>
+This action allows a selection started with the <emphasis remap='I'>select-start</emphasis>
+action to be modified, as described above.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ select-end(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...])
+ </term>
+ <listitem>
+ <para>
+This action ends a text selection that began with the <emphasis remap='I'>select-start</emphasis>
+action, and asserts ownership of the selection or selections specified.
+A <emphasis remap='I'>name</emphasis> can be a selection (e.g., <function>PRIMARY</function>) or a cut buffer
+(e.g., <function>CUT_BUFFER0</function>). Note that case is important. If no
+<emphasis remap='I'>names</emphasis> are specified, <function>PRIMARY</function> is asserted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ extend-start()
+ </term>
+ <listitem>
+ <para>
+This action finds the nearest end of the current selection, and moves it
+to the current pointer location (if triggered by a button event) or text
+cursor location (if triggered by a key event).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ extend-adjust()
+ </term>
+ <listitem>
+ <para>
+This action allows a selection started with an <emphasis remap='I'>extend-start</emphasis> action
+to be modified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ extend-end(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...])
+ </term>
+ <listitem>
+ <para>
+This action ends a text selection that began with the <emphasis remap='I'>extend-start</emphasis>
+action, and asserts ownership of the selection or selections specified.
+A <emphasis remap='I'>name</emphasis> can be a selection (e.g. <function>PRIMARY</function>) or a cut buffer
+(e.g <function>CUT_BUFFER0</function>). Note that case is important. If no names are
+given, <function>PRIMARY</function> is asserted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ insert-selection(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...])
+ </term>
+ <listitem>
+ <para>
+This action retrieves the value of the first (left-most) named selection
+that exists or the cut buffer that is not empty and inserts it into the
+Text widget at the current insert point location. A <emphasis remap='I'>name</emphasis> can be a
+selection (e.g. <function>PRIMARY</function>) or a cut buffer (e.g <function>CUT_BUFFER0</function>).
+Note that case is important.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect3>
+<sect3 id="The_New_Line_Actions">
+<title>The New Line Actions</title>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<variablelist>
+ <varlistentry>
+ <term>
+ newline-and-indent()
+ </term>
+ <listitem>
+ <para>
+This action inserts a newline into the text and adds spaces to
+that line to indent it to match the previous line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ newline-and-backup()
+ </term>
+ <listitem>
+ <para>
+This action inserts a newline into the text <emphasis remap='I'>after</emphasis> the insert point.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ newline()
+ </term>
+ <listitem>
+ <para>
+This action inserts a newline into the text <emphasis remap='I'>before</emphasis> the insert point.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect3>
+<sect3 id="Kill_and_Actions">
+<title>Kill and Actions</title>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<variablelist>
+ <varlistentry>
+ <term>
+ kill-word()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ backward-kill-word()
+ </term>
+ <listitem>
+ <para>
+These actions act exactly like the <emphasis remap='I'>delete-next-word</emphasis> and
+<emphasis remap='I'>delete-previous-word</emphasis> actions, but they stuff the word that was
+killed into the kill buffer (<function>CUT_BUFFER_1</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ kill-selection()
+ </term>
+ <listitem>
+ <para>
+This action deletes the current selection and stuffs the deleted text into
+the kill buffer (<function>CUT_BUFFER_1</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ kill-to-end-of-line()
+ </term>
+ <listitem>
+ <para>
+This action deletes the entire line to the right of the insert point position,
+and stuffs the deleted text into the kill buffer (<function>CUT_BUFFER_1</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ kill-paragraph()
+ </term>
+ <listitem>
+ <para>
+This action deletes the current paragraph, if between paragraphs it deletes
+the paragraph above the insert point, and stuffs the deleted text into
+the kill buffer (<function>CUT_BUFFER_1</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ kill-to-end-of-paragraph()
+ </term>
+ <listitem>
+ <para>
+This action deletes everything between the current insert point location and
+the next paragraph boundary, and stuffs the deleted text into the kill
+buffer (<function>CUT_BUFFER_1</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect3>
+<sect3 id="Miscellaneous_Actions">
+<title>Miscellaneous Actions</title>
+<para>
+<!-- .LP -->
+<!-- .sp 1 -->
+<variablelist>
+ <varlistentry>
+ <term>
+ redraw-display()
+ </term>
+ <listitem>
+ <para>
+This action recomputes the location of all the text lines on the
+display, scrolls the text to vertically center the line containing the insert point
+on the screen, clears the entire screen, and redisplays it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ insert-file([<emphasis remap='I'>filename</emphasis>])
+ </term>
+ <listitem>
+ <para>
+This action activates the insert file popup. The <emphasis remap='I'>filename</emphasis>
+option specifies the default filename to put in the filename buffer of
+the popup. If no <emphasis remap='I'>filename</emphasis> is specified the buffer is empty
+at startup.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ insert-char()
+ </term>
+ <listitem>
+ <para>
+This action may only be attached to a key event. When the
+<function>international</function> resource is <function>false</function>, this action
+calls XLookupString to translate the event into a (rebindable) Latin-1
+character (sequence) and inserts it into the text at the
+insert point. When the <function>international</function> resource is <function>true</function>,
+characters are passed to the input method via XwcLookupString, and any
+committed string returned is inserted into the text at the insert point.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ insert-string(<emphasis remap='I'>string</emphasis>[,<emphasis remap='I'>string</emphasis>,...])
+ </term>
+ <listitem>
+ <para>
+This action inserts each <emphasis remap='I'>string</emphasis> into the text
+at the insert point location. Any <emphasis remap='I'>string</emphasis>
+beginning with the characters "0x" followed by an even
+number of hexadecimal digits is
+interpreted as a hexadecimal constant and the
+corresponding string is inserted instead. This
+hexadecimal string may represent up to 50 8-bit characters.
+ When the<function>international</function> resource is
+<function>true</function>, a hexadecimal string is intrepeted as
+being in a multi-byte encoding, and a hexadecimal
+or regular string will result in an error message
+if it is not legal in the current locale.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ display-caret(<emphasis remap='I'>state</emphasis>,<emphasis remap='I'>when</emphasis>)
+ </term>
+ <listitem>
+ <para>
+This action allows the insert point to be turned on and off.
+The <emphasis remap='I'>state</emphasis> argument specifies the desired state of the insert point.
+This value may be any of the string
+values accepted for Boolean resources (e.g. <function>on</function>, <function>True</function>,
+<function>off</function>, <function>False</function>, etc.). If no arguments are specified, the
+default value is <function>True</function>.
+The <emphasis remap='I'>when</emphasis> argument specifies, for <function>EnterNotify</function> or <function>LeaveNotify</function>
+events whether or not the focus field in the event is to be examined.
+If the second argument is not specified, or specified as something other
+than <function>always</function> then if the action is bound to an <function>EnterNotify</function>
+or <function>LeaveNotify</function> event, the action will be taken only if the focus
+field is <function>True</function>. An augmented binding that might be useful is:
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i 2.5i 4.0i -->
+<!-- .ta 2.0i 2.5i 4.0i -->
+ *Text.Translations: #override \\
+ &lt;FocusIn&gt;: display-caret(on) \\n\\
+ &lt;FocusOut&gt;: display-caret(off)
+</literallayout>
+<variablelist>
+ <varlistentry>
+ <term>
+ focus-in()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ focus-out()
+ </term>
+ <listitem>
+ <para>
+These actions do not currently do anything.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ search(<emphasis remap='I'>direction</emphasis>,[<emphasis remap='I'>string</emphasis>])
+ </term>
+ <listitem>
+ <para>
+This action activates the search popup. The <emphasis remap='I'>direction</emphasis> must be
+specified as either <function>forward</function> or <function>backward</function>. The string is
+optional and is used as an initial value for the <emphasis remap='I'>Search for</emphasis>: string.
+For further explanation of the search widget see the section on
+<function>Text Searches</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ multiply(<emphasis remap='I'>value</emphasis>)
+ </term>
+ <listitem>
+ <para>
+The multiply action allows the user to multiply the effects of many of
+the text actions. Thus the following action sequence
+<emphasis remap='I'>multiply(10) delete-next-word()</emphasis> will delete 10 words. It does not
+matter whether these actions take place in one event or many events.
+Using the default translations the key sequence \fIControl-u,
+Control-d\fP will delete 4 characters.
+Multiply actions can be chained, thus \fImultiply(5)
+multiply(5)\fP is the same as <emphasis remap='I'>multiply(25)</emphasis>. If the string
+<function>reset</function> is passed to the multiply action the effects of all previous
+multiplies are removed and a beep is sent to the display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ form-paragraph()
+ </term>
+ <listitem>
+ <para>
+This action removes all the Carriage Returns from the current
+paragraph and reinserts them so that each line is as long as possible, while
+still fitting on the current screen. Lines are broken at word boundaries if
+at all possible. This action currently works only on Text widgets
+that use ASCII text.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ transpose-characters()
+ </term>
+ <listitem>
+ <para>
+This action will swap the position of the character to the left of the
+insert point with the character to the right of the insert point. The insert point will then
+be advanced one character.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ no-op([<emphasis remap='I'>action</emphasis>])
+ </term>
+ <listitem>
+ <para>
+The no-op action makes no change to the text widget, and is mainly used
+to override translations. This action takes one optional argument. If
+this argument is <emphasis remap='I'>RingBell</emphasis> then a beep is sent to the display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ XawWMProtocols([<emphasis remap='I'>wm_protocol_name</emphasis>])
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "XawWMProtocols" -->
+<!-- .sp -->
+This action is written specifically for the file insertion and the search
+and replace
+dialog boxes. This action is attached to those shells by the Text widget,
+in order to handle ClientMessage events with the WM_PROTOCOLS atom in the
+detail field. This action supports WM_DELETE_WINDOW on the Text widget
+popups, and may support other window manager protocols if necessary in
+the future. The popup will be dismissed if the window manager sends
+a WM_DELETE_WINDOW request and there are no parameters in the action
+call, which is the default. The popup will also be dismissed if the
+parameters include the string ``wm_delete_window,'' and the event is a
+ClientMessage event requesting dismissal or is not a ClientMessage event.
+This action is not sensitive to the case of the strings passed as parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ reconnect-im()
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "Input Method" -->
+When the <function>international</function> resource is <function>true</function>,
+input is usually passed to an input method, a separate
+process, for composing. Sometimes the connection to
+this process gets severed; this action will attempt to
+reconnect it. Causes for severage include network
+trouble, and the user explicitly killing one input
+method and starting a new one. This action may also
+establish first connection when the application is
+started before the input method.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect3>
+<sect3 id="Text_Selections_for_Application_Programmers">
+<title>Text Selections for Application Programmers</title>
+<!-- .IN "Text widget" "Text Selections for Application Programmers" -->
+<para>
+<!-- .LP -->
+The default behavior of the text selection array is described in the
+section called <function>Text Selections for Users</function>. To modify the selections
+a programmer must construct a <function>XawTextSelectType</function> array (called the
+selection array), containing the selections desired, and pass this as
+the new value for the <function>selectionTypes</function> resource. The selection
+array may also be modified using the <function>XawTextSetSelectionArray</function>
+<!-- .IN "XawTextSetSelectionArray" "" -->
+function. All selection arrays must end with the value
+<function>XawselectNull</function>. The <function>selectionTypes</function> resource has no converter
+registered and cannot be modified through the resource manager.
+</para>
+<para>
+<!-- .LP -->
+The array contains a list of entries that will be called when the user
+attempts to select text in rapid succession with the <emphasis remap='I'>select-start</emphasis>
+action (usually by clicking a pointer button). The first entry in the
+selection array will be used when the <emphasis remap='I'>select-start</emphasis> action is
+initially called. The next entry will be used when <emphasis remap='I'>select-start</emphasis>
+is called again, and so on. If a timeout value (1/10 of a second) is
+exceeded, the the next <emphasis remap='I'>select-start</emphasis> action will begin at the top
+of the selection array. When <function>XawselectNull</function> is reached the array
+is recycled beginning with the first element.
+
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>XawselectAll</function></entry>
+ <entry>Selects the contents of the entire buffer.</entry>
+ </row>
+ <row>
+ <entry><function>XawselectChar</function></entry>
+ <entry>Selects text characters as the pointer moves over them.</entry>
+ </row>
+ <row>
+ <entry><function>XawselectLine</function></entry>
+ <entry>Selects the entire line.</entry>
+ </row>
+ <row>
+ <entry><function>XawselectNull</function></entry>
+ <entry>Indicates the end of the selection array.</entry>
+ </row>
+ <row>
+ <entry><function>XawselectParagraph</function></entry>
+ <entry>Selects the entire paragraph.</entry>
+ </row>
+ <row>
+ <entry><function>XawselectPosition</function></entry>
+ <entry>Selects the current pointer position.</entry>
+ </row>
+ <row>
+ <entry><function>XawselectWord</function></entry>
+ <entry>Selects whole words as the pointer moves onto them.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<para>
+<!-- .LP -->
+The default selectType array is:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<literallayout class="monospaced">
+{XawselectPosition, XawselectWord, XawselectLine, XawselectParagraph, XawselectAll, XawselectNull}
+</literallayout>
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+The selection array is not copied by the text widgets. The
+application must allocate space for the array and cannot deallocate or
+change it until the text widget is destroyed or until a new selection
+array is set.
+</para>
+</sect3>
+</sect2>
+<sect2 id="Default_Translation_Bindings">
+<title>Default Translation Bindings</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Default Translation Bindings -->
+<!-- .XE -->
+<!-- .IN "Text widget" "default translations" -->
+The following translations are defaults built into every Text widget.
+They can be overridden, or replaced by specifying a new value for the
+Text widget's <function>translations</function> resource.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+ Ctrl&lt;Key&gt;A: beginning-of-line() \\n\\
+ Ctrl&lt;Key&gt;B: backward-character() \\n\\
+ Ctrl&lt;Key&gt;D: delete-next-character() \\n\\
+ Ctrl&lt;Key&gt;E: end-of-line() \\n\\
+ Ctrl&lt;Key&gt;F: forward-character() \\n\\
+ Ctrl&lt;Key&gt;G: multiply(Reset) \\n\\
+ Ctrl&lt;Key&gt;H: delete-previous-character() \\n\\
+ Ctrl&lt;Key&gt;J: newline-and-indent() \\n\\
+ Ctrl&lt;Key&gt;K: kill-to-end-of-line() \\n\\
+ Ctrl&lt;Key&gt;L: redraw-display() \\n\\
+ Ctrl&lt;Key&gt;M: newline() \\n\\
+ Ctrl&lt;Key&gt;N: next-line() \\n\\
+ Ctrl&lt;Key&gt;O: newline-and-backup() \\n\\
+ Ctrl&lt;Key&gt;P: previous-line() \\n\\
+ Ctrl&lt;Key&gt;R: search(backward) \\n\\
+ Ctrl&lt;Key&gt;S: search(forward) \\n\\
+ Ctrl&lt;Key&gt;T: transpose-characters() \\n\\
+ Ctrl&lt;Key&gt;U: multiply(4) \\n\\
+ Ctrl&lt;Key&gt;V: next-page() \\n\\
+ Ctrl&lt;Key&gt;W: kill-selection() \\n\\
+ Ctrl&lt;Key&gt;Y: insert-selection(CUT_BUFFER1) \\n\\
+ Ctrl&lt;Key&gt;Z: scroll-one-line-up() \\n\\
+ Ctrl&lt;Key&gt;\\: reconnect-im() \\n\\
+ Meta&lt;Key&gt;B: backward-word() \\n\\
+ Meta&lt;Key&gt;F: forward-word() \\n\\
+ Meta&lt;Key&gt;I: insert-file() \\n\\
+ Meta&lt;Key&gt;K: kill-to-end-of-paragraph() \\n\\
+ Meta&lt;Key&gt;Q: form-paragraph() \\n\\
+ Meta&lt;Key&gt;V: previous-page() \\n\\
+ Meta&lt;Key&gt;Y: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\
+ Meta&lt;Key&gt;Z: scroll-one-line-down() \\n\\
+ :Meta&lt;Key&gt;d: delete-next-word() \\n\\
+ :Meta&lt;Key&gt;D: kill-word() \\n\\
+ :Meta&lt;Key&gt;h: delete-previous-word() \\n\\
+ :Meta&lt;Key&gt;H: backward-kill-word() \\n\\
+ :Meta&lt;Key&gt;\\&lt;: beginning-of-file() \\n\\
+ :Meta&lt;Key&gt;\\&gt;: end-of-file() \\n\\
+ :Meta&lt;Key&gt;]: forward-paragraph() \\n\\
+ :Meta&lt;Key&gt;[: backward-paragraph() \\n\\
+ ~Shift Meta&lt;Key&gt;Delete: delete-previous-word() \\n\\
+ \ Shift Meta&lt;Key&gt;Delete: backward-kill-word() \\n\\
+ ~Shift Meta&lt;Key&gt;Backspace: delete-previous-word() \\n\\
+ \ Shift Meta&lt;Key&gt;Backspace: backward-kill-word() \\n\\
+ &lt;Key&gt;Right: forward-character() \\n\\
+ &lt;Key&gt;Left: backward-character() \\n\\
+ &lt;Key&gt;Down: next-line() \\n\\
+ &lt;Key&gt;Up: previous-line() \\n\\
+ &lt;Key&gt;Delete: delete-previous-character() \\n\\
+ &lt;Key&gt;BackSpace: delete-previous-character() \\n\\
+ &lt;Key&gt;Linefeed: newline-and-indent() \\n\\
+ &lt;Key&gt;Return: newline() \\n\\
+ &lt;Key&gt;: insert-char() \\n\\
+ &lt;Key&gt;Kanji: reconnect-im() \\n\\
+ &lt;FocusIn&gt;: focus-in() \\n\\
+ &lt;FocusOut&gt;: focus-out() \\n\\
+ &lt;Btn1Down&gt;: select-start() \\n\\
+ &lt;Btn1Motion&gt;: extend-adjust() \\n\\
+ &lt;Btn1Up&gt;: extend-end(PRIMARY, CUT_BUFFER0) \\n\\
+ &lt;Btn2Down&gt;: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\
+ &lt;Btn3Down&gt;: extend-start() \\n\\
+ &lt;Btn3Motion&gt;: extend-adjust() \\n\\
+ &lt;Btn3Up&gt;: extend-end(PRIMARY, CUT_BUFFER0) \\n
+</literallayout>
+
+
+</para>
+</sect2>
diff --git a/libXaw/specs/TextActions_default_translation_bindings.xml b/libXaw/specs/TextActions_default_translation_bindings.xml
new file mode 100644
index 000000000..731881104
--- /dev/null
+++ b/libXaw/specs/TextActions_default_translation_bindings.xml
@@ -0,0 +1,85 @@
+<sect1 id="Default_Translation_Bindings">
+<title>Default Translation Bindings</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Default Translation Bindings -->
+<!-- .XE -->
+<!-- .IN "Text widget" "default translations" -->
+The following translations are defaults built into every Text widget.
+They can be overridden, or replaced by specifying a new value for the
+Text widget's <function>translations</function> resource.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+ Ctrl&lt;Key&gt;A: beginning-of-line() \\n\\
+ Ctrl&lt;Key&gt;B: backward-character() \\n\\
+ Ctrl&lt;Key&gt;D: delete-next-character() \\n\\
+ Ctrl&lt;Key&gt;E: end-of-line() \\n\\
+ Ctrl&lt;Key&gt;F: forward-character() \\n\\
+ Ctrl&lt;Key&gt;G: multiply(Reset) \\n\\
+ Ctrl&lt;Key&gt;H: delete-previous-character() \\n\\
+ Ctrl&lt;Key&gt;J: newline-and-indent() \\n\\
+ Ctrl&lt;Key&gt;K: kill-to-end-of-line() \\n\\
+ Ctrl&lt;Key&gt;L: redraw-display() \\n\\
+ Ctrl&lt;Key&gt;M: newline() \\n\\
+ Ctrl&lt;Key&gt;N: next-line() \\n\\
+ Ctrl&lt;Key&gt;O: newline-and-backup() \\n\\
+ Ctrl&lt;Key&gt;P: previous-line() \\n\\
+ Ctrl&lt;Key&gt;R: search(backward) \\n\\
+ Ctrl&lt;Key&gt;S: search(forward) \\n\\
+ Ctrl&lt;Key&gt;T: transpose-characters() \\n\\
+ Ctrl&lt;Key&gt;U: multiply(4) \\n\\
+ Ctrl&lt;Key&gt;V: next-page() \\n\\
+ Ctrl&lt;Key&gt;W: kill-selection() \\n\\
+ Ctrl&lt;Key&gt;Y: insert-selection(CUT_BUFFER1) \\n\\
+ Ctrl&lt;Key&gt;Z: scroll-one-line-up() \\n\\
+ Ctrl&lt;Key&gt;\\: reconnect-im() \\n\\
+ Meta&lt;Key&gt;B: backward-word() \\n\\
+ Meta&lt;Key&gt;F: forward-word() \\n\\
+ Meta&lt;Key&gt;I: insert-file() \\n\\
+ Meta&lt;Key&gt;K: kill-to-end-of-paragraph() \\n\\
+ Meta&lt;Key&gt;Q: form-paragraph() \\n\\
+ Meta&lt;Key&gt;V: previous-page() \\n\\
+ Meta&lt;Key&gt;Y: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\
+ Meta&lt;Key&gt;Z: scroll-one-line-down() \\n\\
+ :Meta&lt;Key&gt;d: delete-next-word() \\n\\
+ :Meta&lt;Key&gt;D: kill-word() \\n\\
+ :Meta&lt;Key&gt;h: delete-previous-word() \\n\\
+ :Meta&lt;Key&gt;H: backward-kill-word() \\n\\
+ :Meta&lt;Key&gt;\\&lt;: beginning-of-file() \\n\\
+ :Meta&lt;Key&gt;\\&gt;: end-of-file() \\n\\
+ :Meta&lt;Key&gt;]: forward-paragraph() \\n\\
+ :Meta&lt;Key&gt;[: backward-paragraph() \\n\\
+ ~Shift Meta&lt;Key&gt;Delete: delete-previous-word() \\n\\
+ \ Shift Meta&lt;Key&gt;Delete: backward-kill-word() \\n\\
+ ~Shift Meta&lt;Key&gt;Backspace: delete-previous-word() \\n\\
+ \ Shift Meta&lt;Key&gt;Backspace: backward-kill-word() \\n\\
+ &lt;Key&gt;Right: forward-character() \\n\\
+ &lt;Key&gt;Left: backward-character() \\n\\
+ &lt;Key&gt;Down: next-line() \\n\\
+ &lt;Key&gt;Up: previous-line() \\n\\
+ &lt;Key&gt;Delete: delete-previous-character() \\n\\
+ &lt;Key&gt;BackSpace: delete-previous-character() \\n\\
+ &lt;Key&gt;Linefeed: newline-and-indent() \\n\\
+ &lt;Key&gt;Return: newline() \\n\\
+ &lt;Key&gt;: insert-char() \\n\\
+ &lt;Key&gt;Kanji: reconnect-im() \\n\\
+ &lt;FocusIn&gt;: focus-in() \\n\\
+ &lt;FocusOut&gt;: focus-out() \\n\\
+ &lt;Btn1Down&gt;: select-start() \\n\\
+ &lt;Btn1Motion&gt;: extend-adjust() \\n\\
+ &lt;Btn1Up&gt;: extend-end(PRIMARY, CUT_BUFFER0) \\n\\
+ &lt;Btn2Down&gt;: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\
+ &lt;Btn3Down&gt;: extend-start() \\n\\
+ &lt;Btn3Motion&gt;: extend-adjust() \\n\\
+ &lt;Btn3Up&gt;: extend-end(PRIMARY, CUT_BUFFER0) \\n
+</literallayout>
+
+
+</para>
+</sect1>
diff --git a/libXaw/specs/TextActions_text_widget_actions.xml b/libXaw/specs/TextActions_text_widget_actions.xml
new file mode 100644
index 000000000..238727698
--- /dev/null
+++ b/libXaw/specs/TextActions_text_widget_actions.xml
@@ -0,0 +1,891 @@
+<sect1 id="Text_Widget_Actions">
+<title>Text Widget Actions</title>
+<para>
+<!-- .LP -->
+<!-- .IN "Text widget" "actions" -->
+<!-- .XS -->
+<!-- Actions Supported by all Text Widgets -->
+<!-- .XE -->
+<!-- .IN "Text widget" "actions" "@DEF@" -->
+
+All editing functions are performed by translation manager actions that may
+be specified through the <function>translations</function> resource in the Text widget.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i 3i -->
+<!-- .ta .5i 2.5i 3i -->
+Insert Point Movement Delete
+ forward-character delete-next-character
+ backward-character delete-previous-character
+ forward-word delete-next-word
+ backward-word delete-previous-word
+ forward-paragraph delete-selection
+ backward-paragraph
+ beginning-of-line
+ end-of-line Selection
+ next-line select-word
+ previous-line select-all
+ next-page select-start
+ previous-page select-adjust
+ beginning-of-file select-end
+ end-of-file extend-start
+ scroll-one-line-up extend-adjust
+ scroll-one-line-down extend-end
+ insert-selection
+
+
+Miscellaneous New Line
+ redraw-display newline-and-indent
+ insert-file newline-and-backup
+ insert-char newline
+ insert-string
+ display-caret
+ focus-in Kill
+ focus-in kill-word
+ search backward-kill-word
+ multiply kill-selection
+ form-paragraph kill-to-end-of-line
+ transpose-characters kill-paragraph
+ no-op kill-to-end-of-paragraph
+ XawWMProtocols
+ reconnect-im
+</literallayout>
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+Most of the actions take no arguments, and unless otherwise noted you
+may assume this to be the case.
+</para>
+<para>
+<!-- .LP -->
+</para>
+<sect2 id="Cursor_Movement_Actions_fP">
+<title>Cursor Movement Actions\fP</title>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<variablelist>
+ <varlistentry>
+ <term>
+ forward-character()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ backward-character()
+ </term>
+ <listitem>
+ <para>
+These actions move the insert point forward or backward one character in
+the buffer. If the insert point is at the end or beginning of a line
+this action will move the insert point to the next (or previous) line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ forward-word()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ backward-word()
+ </term>
+ <listitem>
+ <para>
+These actions move the insert point to the next or previous word boundary.
+A word boundary is defined as a Space, Tab or Carriage Return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ forward-paragraph()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ backward-paragraph()
+ </term>
+ <listitem>
+ <para>
+These actions move the insert point to the next or previous paragraph boundary.
+A paragraph boundary is defined as two Carriage Returns in a row with only
+Spaces or Tabs between them.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ beginning-of-line()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ end-of-line()
+ </term>
+ <listitem>
+ <para>
+These actions move to the beginning or end of the current line. If the
+insert point is already at the end or beginning of the line then no action is taken.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ next-line()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ previous-line()
+ </term>
+ <listitem>
+ <para>
+These actions move the insert point up or down one line. If the insert
+point is currently N characters from the beginning of the line then it
+will be N characters from the beginning of the next or previous line.
+If N is past the end of the line, the insert point is placed at the end
+of the line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ next-page()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ previous-page()
+ </term>
+ <listitem>
+ <para>
+These actions move the insert point up or down one page in the file.
+One page is defined as the current height of the text widget. The
+insert point is always placed at the first character of the top line by
+this action.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ beginning-of-file()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ end-of-file()
+ </term>
+ <listitem>
+ <para>
+These actions place the insert point at the beginning or end of the
+current text buffer. The text widget is then scrolled the minimum
+amount necessary to make the new insert point location visible.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ scroll-one-line-up()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ scroll-one-line-down()
+ </term>
+ <listitem>
+ <para>
+These actions scroll the current text field up or down by one line.
+They do not move the insert point. Other than the scrollbars this is
+the only way that the insert point may be moved off of the visible text
+area. The widget will be scrolled so that the insert point is back on
+the screen as soon as some other action is executed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Delete_Actions">
+<title>Delete Actions</title>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<variablelist>
+ <varlistentry>
+ <term>
+ delete-next-character()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ delete-previous-character()
+ </term>
+ <listitem>
+ <para>
+These actions remove the character immediately before or after the
+insert point. If a Carriage Return is removed then the next line is
+appended to the end of the current line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ delete-next-word()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ delete-previous-word()
+ </term>
+ <listitem>
+ <para>
+These actions remove all characters between the insert point location and
+the next word boundary. A word boundary is defined as a Space, Tab or
+Carriage Return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ delete-selection()
+ </term>
+ <listitem>
+ <para>
+This action removes all characters in the current selection.
+The selection can be set with the selection actions.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Selection_Actions">
+<title>Selection Actions</title>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<variablelist>
+ <varlistentry>
+ <term>
+ select-word()
+ </term>
+ <listitem>
+ <para>
+This action selects the word in which the insert point is currently located.
+If the insert point is between words then it will select the previous word.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ select-all()
+ </term>
+ <listitem>
+ <para>
+This action selects the entire text buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ select-start()
+ </term>
+ <listitem>
+ <para>
+This action sets the insert point to the current pointer location (if
+triggered by a button event) or text cursor location (if triggered by
+a key event). It
+will then begin a selection at this location. If many of these
+selection actions occur quickly in succession then the selection count
+mechanism will be invoked (see the section titled \fBText Selections for
+Application Programmers\fP for details). <!-- xref -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ select-adjust()
+ </term>
+ <listitem>
+ <para>
+This action allows a selection started with the <emphasis remap='I'>select-start</emphasis>
+action to be modified, as described above.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ select-end(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...])
+ </term>
+ <listitem>
+ <para>
+This action ends a text selection that began with the <emphasis remap='I'>select-start</emphasis>
+action, and asserts ownership of the selection or selections specified.
+A <emphasis remap='I'>name</emphasis> can be a selection (e.g., <function>PRIMARY</function>) or a cut buffer
+(e.g., <function>CUT_BUFFER0</function>). Note that case is important. If no
+<emphasis remap='I'>names</emphasis> are specified, <function>PRIMARY</function> is asserted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ extend-start()
+ </term>
+ <listitem>
+ <para>
+This action finds the nearest end of the current selection, and moves it
+to the current pointer location (if triggered by a button event) or text
+cursor location (if triggered by a key event).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ extend-adjust()
+ </term>
+ <listitem>
+ <para>
+This action allows a selection started with an <emphasis remap='I'>extend-start</emphasis> action
+to be modified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ extend-end(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...])
+ </term>
+ <listitem>
+ <para>
+This action ends a text selection that began with the <emphasis remap='I'>extend-start</emphasis>
+action, and asserts ownership of the selection or selections specified.
+A <emphasis remap='I'>name</emphasis> can be a selection (e.g. <function>PRIMARY</function>) or a cut buffer
+(e.g <function>CUT_BUFFER0</function>). Note that case is important. If no names are
+given, <function>PRIMARY</function> is asserted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ insert-selection(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...])
+ </term>
+ <listitem>
+ <para>
+This action retrieves the value of the first (left-most) named selection
+that exists or the cut buffer that is not empty and inserts it into the
+Text widget at the current insert point location. A <emphasis remap='I'>name</emphasis> can be a
+selection (e.g. <function>PRIMARY</function>) or a cut buffer (e.g <function>CUT_BUFFER0</function>).
+Note that case is important.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="The_New_Line_Actions">
+<title>The New Line Actions</title>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<variablelist>
+ <varlistentry>
+ <term>
+ newline-and-indent()
+ </term>
+ <listitem>
+ <para>
+This action inserts a newline into the text and adds spaces to
+that line to indent it to match the previous line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ newline-and-backup()
+ </term>
+ <listitem>
+ <para>
+This action inserts a newline into the text <emphasis remap='I'>after</emphasis> the insert point.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ newline()
+ </term>
+ <listitem>
+ <para>
+This action inserts a newline into the text <emphasis remap='I'>before</emphasis> the insert point.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Kill_and_Actions">
+<title>Kill and Actions</title>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<variablelist>
+ <varlistentry>
+ <term>
+ kill-word()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ backward-kill-word()
+ </term>
+ <listitem>
+ <para>
+These actions act exactly like the <emphasis remap='I'>delete-next-word</emphasis> and
+<emphasis remap='I'>delete-previous-word</emphasis> actions, but they stuff the word that was
+killed into the kill buffer (<function>CUT_BUFFER_1</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ kill-selection()
+ </term>
+ <listitem>
+ <para>
+This action deletes the current selection and stuffs the deleted text into
+the kill buffer (<function>CUT_BUFFER_1</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ kill-to-end-of-line()
+ </term>
+ <listitem>
+ <para>
+This action deletes the entire line to the right of the insert point position,
+and stuffs the deleted text into the kill buffer (<function>CUT_BUFFER_1</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ kill-paragraph()
+ </term>
+ <listitem>
+ <para>
+This action deletes the current paragraph, if between paragraphs it deletes
+the paragraph above the insert point, and stuffs the deleted text into
+the kill buffer (<function>CUT_BUFFER_1</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ kill-to-end-of-paragraph()
+ </term>
+ <listitem>
+ <para>
+This action deletes everything between the current insert point location and
+the next paragraph boundary, and stuffs the deleted text into the kill
+buffer (<function>CUT_BUFFER_1</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Miscellaneous_Actions">
+<title>Miscellaneous Actions</title>
+<para>
+<!-- .LP -->
+<!-- .sp 1 -->
+<variablelist>
+ <varlistentry>
+ <term>
+ redraw-display()
+ </term>
+ <listitem>
+ <para>
+This action recomputes the location of all the text lines on the
+display, scrolls the text to vertically center the line containing the insert point
+on the screen, clears the entire screen, and redisplays it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ insert-file([<emphasis remap='I'>filename</emphasis>])
+ </term>
+ <listitem>
+ <para>
+This action activates the insert file popup. The <emphasis remap='I'>filename</emphasis>
+option specifies the default filename to put in the filename buffer of
+the popup. If no <emphasis remap='I'>filename</emphasis> is specified the buffer is empty
+at startup.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ insert-char()
+ </term>
+ <listitem>
+ <para>
+This action may only be attached to a key event. When the
+<function>international</function> resource is <function>false</function>, this action
+calls XLookupString to translate the event into a (rebindable) Latin-1
+character (sequence) and inserts it into the text at the
+insert point. When the <function>international</function> resource is <function>true</function>,
+characters are passed to the input method via XwcLookupString, and any
+committed string returned is inserted into the text at the insert point.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ insert-string(<emphasis remap='I'>string</emphasis>[,<emphasis remap='I'>string</emphasis>,...])
+ </term>
+ <listitem>
+ <para>
+This action inserts each <emphasis remap='I'>string</emphasis> into the text
+at the insert point location. Any <emphasis remap='I'>string</emphasis>
+beginning with the characters "0x" followed by an even
+number of hexadecimal digits is
+interpreted as a hexadecimal constant and the
+corresponding string is inserted instead. This
+hexadecimal string may represent up to 50 8-bit characters.
+ When the<function>international</function> resource is
+<function>true</function>, a hexadecimal string is intrepeted as
+being in a multi-byte encoding, and a hexadecimal
+or regular string will result in an error message
+if it is not legal in the current locale.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ display-caret(<emphasis remap='I'>state</emphasis>,<emphasis remap='I'>when</emphasis>)
+ </term>
+ <listitem>
+ <para>
+This action allows the insert point to be turned on and off.
+The <emphasis remap='I'>state</emphasis> argument specifies the desired state of the insert point.
+This value may be any of the string
+values accepted for Boolean resources (e.g. <function>on</function>, <function>True</function>,
+<function>off</function>, <function>False</function>, etc.). If no arguments are specified, the
+default value is <function>True</function>.
+The <emphasis remap='I'>when</emphasis> argument specifies, for <function>EnterNotify</function> or <function>LeaveNotify</function>
+events whether or not the focus field in the event is to be examined.
+If the second argument is not specified, or specified as something other
+than <function>always</function> then if the action is bound to an <function>EnterNotify</function>
+or <function>LeaveNotify</function> event, the action will be taken only if the focus
+field is <function>True</function>. An augmented binding that might be useful is:
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i 2.5i 4.0i -->
+<!-- .ta 2.0i 2.5i 4.0i -->
+ *Text.Translations: #override \\
+ &lt;FocusIn&gt;: display-caret(on) \\n\\
+ &lt;FocusOut&gt;: display-caret(off)
+</literallayout>
+<variablelist>
+ <varlistentry>
+ <term>
+ focus-in()
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ focus-out()
+ </term>
+ <listitem>
+ <para>
+These actions do not currently do anything.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ search(<emphasis remap='I'>direction</emphasis>,[<emphasis remap='I'>string</emphasis>])
+ </term>
+ <listitem>
+ <para>
+This action activates the search popup. The <emphasis remap='I'>direction</emphasis> must be
+specified as either <function>forward</function> or <function>backward</function>. The string is
+optional and is used as an initial value for the <emphasis remap='I'>Search for</emphasis>: string.
+For further explanation of the search widget see the section on
+<function>Text Searches</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ multiply(<emphasis remap='I'>value</emphasis>)
+ </term>
+ <listitem>
+ <para>
+The multiply action allows the user to multiply the effects of many of
+the text actions. Thus the following action sequence
+<emphasis remap='I'>multiply(10) delete-next-word()</emphasis> will delete 10 words. It does not
+matter whether these actions take place in one event or many events.
+Using the default translations the key sequence \fIControl-u,
+Control-d\fP will delete 4 characters.
+Multiply actions can be chained, thus \fImultiply(5)
+multiply(5)\fP is the same as <emphasis remap='I'>multiply(25)</emphasis>. If the string
+<function>reset</function> is passed to the multiply action the effects of all previous
+multiplies are removed and a beep is sent to the display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ form-paragraph()
+ </term>
+ <listitem>
+ <para>
+This action removes all the Carriage Returns from the current
+paragraph and reinserts them so that each line is as long as possible, while
+still fitting on the current screen. Lines are broken at word boundaries if
+at all possible. This action currently works only on Text widgets
+that use ASCII text.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ transpose-characters()
+ </term>
+ <listitem>
+ <para>
+This action will swap the position of the character to the left of the
+insert point with the character to the right of the insert point. The insert point will then
+be advanced one character.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ no-op([<emphasis remap='I'>action</emphasis>])
+ </term>
+ <listitem>
+ <para>
+The no-op action makes no change to the text widget, and is mainly used
+to override translations. This action takes one optional argument. If
+this argument is <emphasis remap='I'>RingBell</emphasis> then a beep is sent to the display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ XawWMProtocols([<emphasis remap='I'>wm_protocol_name</emphasis>])
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "XawWMProtocols" -->
+<!-- .sp -->
+This action is written specifically for the file insertion and the search
+and replace
+dialog boxes. This action is attached to those shells by the Text widget,
+in order to handle ClientMessage events with the WM_PROTOCOLS atom in the
+detail field. This action supports WM_DELETE_WINDOW on the Text widget
+popups, and may support other window manager protocols if necessary in
+the future. The popup will be dismissed if the window manager sends
+a WM_DELETE_WINDOW request and there are no parameters in the action
+call, which is the default. The popup will also be dismissed if the
+parameters include the string ``wm_delete_window,'' and the event is a
+ClientMessage event requesting dismissal or is not a ClientMessage event.
+This action is not sensitive to the case of the strings passed as parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ reconnect-im()
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "Input Method" -->
+When the <function>international</function> resource is <function>true</function>,
+input is usually passed to an input method, a separate
+process, for composing. Sometimes the connection to
+this process gets severed; this action will attempt to
+reconnect it. Causes for severage include network
+trouble, and the user explicitly killing one input
+method and starting a new one. This action may also
+establish first connection when the application is
+started before the input method.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Text_Selections_for_Application_Programmers">
+<title>Text Selections for Application Programmers</title>
+<!-- .IN "Text widget" "Text Selections for Application Programmers" -->
+<para>
+<!-- .LP -->
+The default behavior of the text selection array is described in the
+section called <function>Text Selections for Users</function>. To modify the selections
+a programmer must construct a <function>XawTextSelectType</function> array (called the
+selection array), containing the selections desired, and pass this as
+the new value for the <function>selectionTypes</function> resource. The selection
+array may also be modified using the <function>XawTextSetSelectionArray</function>
+<!-- .IN "XawTextSetSelectionArray" "" -->
+function. All selection arrays must end with the value
+<function>XawselectNull</function>. The <function>selectionTypes</function> resource has no converter
+registered and cannot be modified through the resource manager.
+</para>
+<para>
+<!-- .LP -->
+The array contains a list of entries that will be called when the user
+attempts to select text in rapid succession with the <emphasis remap='I'>select-start</emphasis>
+action (usually by clicking a pointer button). The first entry in the
+selection array will be used when the <emphasis remap='I'>select-start</emphasis> action is
+initially called. The next entry will be used when <emphasis remap='I'>select-start</emphasis>
+is called again, and so on. If a timeout value (1/10 of a second) is
+exceeded, the the next <emphasis remap='I'>select-start</emphasis> action will begin at the top
+of the selection array. When <function>XawselectNull</function> is reached the array
+is recycled beginning with the first element.
+
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>XawselectAll</function></entry>
+ <entry>Selects the contents of the entire buffer.</entry>
+ </row>
+ <row>
+ <entry><function>XawselectChar</function></entry>
+ <entry>Selects text characters as the pointer moves over them.</entry>
+ </row>
+ <row>
+ <entry><function>XawselectLine</function></entry>
+ <entry>Selects the entire line.</entry>
+ </row>
+ <row>
+ <entry><function>XawselectNull</function></entry>
+ <entry>Indicates the end of the selection array.</entry>
+ </row>
+ <row>
+ <entry><function>XawselectParagraph</function></entry>
+ <entry>Selects the entire paragraph.</entry>
+ </row>
+ <row>
+ <entry><function>XawselectPosition</function></entry>
+ <entry>Selects the current pointer position.</entry>
+ </row>
+ <row>
+ <entry><function>XawselectWord</function></entry>
+ <entry>Selects whole words as the pointer moves onto them.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<para>
+<!-- .LP -->
+The default selectType array is:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<literallayout class="monospaced">
+{XawselectPosition, XawselectWord, XawselectLine, XawselectParagraph, XawselectAll, XawselectNull}
+</literallayout>
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+The selection array is not copied by the text widgets. The
+application must allocate space for the array and cannot deallocate or
+change it until the text widget is destroyed or until a new selection
+array is set.
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/TextCustom.xml b/libXaw/specs/TextCustom.xml
new file mode 100644
index 000000000..7ca2d5f78
--- /dev/null
+++ b/libXaw/specs/TextCustom.xml
@@ -0,0 +1,123 @@
+<sect1 id="Customizing_the_Text_Widget">
+<title>Customizing the Text Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Customizing the Text Widget -->
+<!-- .XE -->
+<!-- .IN "Text widget" "customizing" "@DEF@" -->
+</para>
+<para>
+<!-- .LP -->
+The remainder of this chapter will describe customizing the Text
+widget. The Text widget may be customized by subclassing, or by
+creating new sources and sinks. Subclassing is described in
+detail in Chapter 7; this section will describe only those things that
+are specific to the Text widget. Attributes of the Text widget base
+class and creating new sources and sinks will be discussed.
+</para>
+<para>
+<!-- .LP -->
+The Text widget is made up of a number of different pieces, with the
+Text widget as the base widget class. It and the AsciiText widget are
+the only true "widgets" in the Text widget family. The other pieces
+(sources and sinks) are X Toolkit objects and have no window
+associated with them. No source or sink is useful unless assigned to
+a Text widget.
+</para>
+<para>
+<!-- .LP -->
+Each of the following pieces of the Text widget has a specific purpose,
+and will be, or has been, discussed in detail in this chapter:
+<!-- .IN "Text widget" "" -->
+</para>
+<para>
+<variablelist>
+ <varlistentry>
+ <term><function>Text</function></term>
+ <listitem>
+ <para>
+This is the glue that binds everything else together. This widget reads
+the text data from the source, and displays the information in the sink.
+All translations and actions are handled in the Text widget itself.
+ </para>
+ </listitem>
+ </varlistentry>
+<!-- .IN "TextSink object" "" -->
+ <varlistentry>
+ <term><function>TextSink</function></term>
+ <listitem>
+ <para>
+This object is responsible for displaying and clearing the drawing area.
+It also reports the configuration of the window that contains the
+drawing area. The TextSink does not have its own window; instead it does
+its drawing on the Text widget's window.
+ </para>
+ </listitem>
+ </varlistentry>
+<!-- .IN "TextSrc object" "" -->
+ <varlistentry>
+ <term><function>TextSrc</function></term>
+ <listitem>
+ <para>
+This object is responsible for reading, editing and searching through the
+text buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+<!-- .IN "AsciiSink object" "" -->
+ <varlistentry>
+ <term><function>AsciiSink</function></term>
+ <listitem>
+ <para>
+This object is a subclass of the TextSink and knows how to display
+ASCII text. Support has been added to display any 8-bit character set, given
+the font.
+ </para>
+ </listitem>
+ </varlistentry>
+<!-- .IN "MultiSink object" "" -->
+ <varlistentry>
+ <term><function>MultiSink</function></term>
+ <listitem>
+ <para>
+This object is a subclass of the TextSink and knows how to display
+font sets.
+ </para>
+ </listitem>
+ </varlistentry>
+<!-- .IN "AsciiSrc object" "" -->
+ <varlistentry>
+ <term><function>AsciiSrc</function></term>
+ <listitem>
+ <para>
+This object is a subclass of the TextSrc and knows how to read strings
+and files.
+ </para>
+ </listitem>
+ </varlistentry>
+<!-- .IN "MultiSrc object" "" -->
+ <varlistentry>
+ <term><function>MultiSrc</function></term>
+ <listitem>
+ <para>
+This object is a subclass of the TextSrc and knows how to read strings
+and multibyte files, converting them to wide characters based on locale.
+ </para>
+ </listitem>
+ </varlistentry>
+<!-- .IN "AsciiText widget" "" -->
+ <varlistentry>
+ <term><function>AsciiText</function></term>
+ <listitem>
+ <para>
+This widget is a subclass of the Text widget. When created, the AsciiText
+automatically creates and attaches either an AsciiSrc and AsciiSink, or a
+MultiSrc and MultiSink, to itself. The AsciiText provides the simplest
+interface to the Athena Text widgets.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect1>
diff --git a/libXaw/specs/TextFuncs.xml b/libXaw/specs/TextFuncs.xml
new file mode 100644
index 000000000..0d2ae8192
--- /dev/null
+++ b/libXaw/specs/TextFuncs.xml
@@ -0,0 +1,856 @@
+<sect1 id="Text_Functions">
+<title>Text Functions</title>
+<!-- .XS -->
+<!-- Text Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following functions are provided as convenience routines for use with
+the Text widget. Although many of these actions can be performed by
+modifying resources, these interfaces are frequently more efficient.
+</para>
+<para>
+<!-- .LP -->
+These data structures are defined in the Text widget's public header file,
+&lt;X11/Xaw/Text.h&gt;.
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "XawTextPosition" "" "@DEF@" -->
+typedef long XawTextPosition;
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+Character positions in the Text widget begin at 0 and end at n, where
+n is the number of characters in the Text source widget.
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "XawTextBlock" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i 2.25i -->
+<!-- .ta .5i 1.5i 2.25i -->
+typedef struct {
+ int <emphasis remap='I'>firstPos</emphasis>;
+ int <emphasis remap='I'>length</emphasis>;
+ char *<emphasis remap='I'>ptr</emphasis>;
+ unsigned long <emphasis remap='I'>format</emphasis>;
+} XawTextBlock, *XawTextBlockPtr;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "XawTextBlockPtr" "" -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>firstPos</emphasis>
+ </term>
+ <listitem>
+ <para>
+The first position, or index, to use within the <emphasis remap='I'>ptr</emphasis> field.
+The value is commonly zero.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+The number of characters to be used from the <emphasis remap='I'>ptr</emphasis> field.
+The number of characters used is commonly the number of characters
+in <emphasis remap='I'>ptr</emphasis>, and must not be greater than the length of the string
+in <emphasis remap='I'>ptr</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ptr</emphasis>
+ </term>
+ <listitem>
+ <para>
+Contains the string to be referenced by the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format</emphasis>
+ </term>
+ <listitem>
+ <para>
+This flag indicates whether the data pointed to by <function>ptr</function> is char
+or wchar_t. When the associated widget has <function>international</function> set
+to <function>false</function> this field must be XawFmt8Bit. When the associated
+widget has <function>international</function> set to <function>true</function> this field must be
+either XawFmt8Bit or XawFmtWide.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<note>
+<para>
+<!-- .LP -->
+Note: Previous versions of Xaw used
+<function>FMT8BIT ,</function>
+which has been retained for backwards compatibility. <function>FMT8BIT</function> is
+deprecated and will eventually be removed from the implementation.
+</para>
+</note>
+<sect2 id="Selecting_Text">
+<title>Selecting Text</title>
+<para>
+<!-- .LP -->
+To select a piece of text, use
+<function>XawTextSetSelection : </function>
+<!-- .IN "XawTextSetSelection" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawTextSetSelection</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPositionleft,<parameter> right</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>left</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character position at which the selection begins.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>right</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character position at which the selection ends.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
+If redisplay is enabled, this function highlights the text and
+makes it the <function>PRIMARY</function> selection. This function does not have any
+effect on <function>CUT_BUFFER0</function>.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect2>
+<sect2 id="Unhighlighting_Text">
+<title>Unhighlighting Text</title>
+<para>
+<!-- .LP -->
+To unhighlight previously highlighted text in a widget, use
+<function>XawTextUnsetSelection</function>:
+<!-- .IN "XawTextUnsetSelection" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawTextUnsetSelection</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Getting_Current_Text_Selection">
+<title>Getting Current Text Selection</title>
+<para>
+<!-- .LP -->
+To retrieve the text that has been selected by this
+text widget use <function>XawTextGetSelectionPos</function>:
+<!-- .IN "XawTextGetSelectionPos" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawTextGetSelectionPos</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPosition*begin_return,<parameter> *end_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>begin_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the beginning of the text selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>end_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the end of the text selection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
+If the returned values are equal, no text is currently selected.
+</para>
+</sect2>
+<sect2 id="Replacing_Text">
+<title>Replacing Text</title>
+<para>
+<!-- .LP -->
+To modify the text in an editable Text widget use <function>XawTextReplace</function>:
+<!-- .IN "XawTextReplace" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XawTextReplace</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPositionstart,<parameter> end</parameter></paramdef>
+ <paramdef>XawTextBlock<parameter> *text</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>start</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the starting character position of the text replacement.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>end</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the ending character position of the text replacement.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the text to be inserted into the file.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function will not
+be able to replace text in read-only text widgets. It will also only
+be able to append text to an append-only text widget.
+</para>
+<para>
+<!-- .LP -->
+See section 5.4 for a description of <function>XawTextPosition</function> and <!-- xref -->
+<function>XawTextBlock</function>.
+</para>
+<para>
+<!-- .LP -->
+This function may return the following values:
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>XawEditDone</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "XawEditDone" "" -->
+The text replacement was successful.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>XawPositionError</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "XawPositionError" "" -->
+The edit mode is <function>XawtextAppend</function> and <function>start</function> is not the position of
+the last character of the source.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>XawEditError</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "XawEditError" "" -->
+Either the Source was read-only or the range to be deleted is larger
+than the length of the Source.
+
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+The <function>XawTextReplace</function> arguments <function>start</function> and
+<emphasis remap='I'>end</emphasis> represent the text source character positions for the
+existing text that is to be replaced by the text in the text block.
+The characters from <emphasis remap='I'>start</emphasis> up to
+but not including <emphasis remap='I'>end</emphasis> are deleted, and the characters
+specified on the text block are inserted in their place. If
+<emphasis remap='I'>start</emphasis> and <emphasis remap='I'>end</emphasis> are equal, no text is deleted and the new
+text is inserted after <emphasis remap='I'>start</emphasis>.
+</para>
+</sect2>
+<sect2 id="Searching_for_Text">
+<title>Searching for Text</title>
+<para>
+<!-- .LP -->
+To search for a string in the Text widget, use
+<function>XawTextSearch</function>:
+<!-- .IN "XawTextSearch" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XawTextPosition<function> XawTextSearch</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextScanDirection<parameter> dir</parameter></paramdef>
+ <paramdef>XawTextBlock*<parameter> text</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dir</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the direction to search in. Legal values are
+<function>XawsdLeft</function> and <function>XawsdRight</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a text block structure that contains the text to search for.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+See section 5.4 for a description of <function>XawTextPosition</function> and <function>XawTextBlock</function>. <!-- xref -->
+The <function>XawTextSearch</function> function will begin at the insertion point
+and search in the
+direction specified for a string that matches the one passed in
+<emphasis remap='I'>text</emphasis>. If the string is found the location of the first
+character in the string is returned. If the string could not be
+found then the value <function>XawTextSearchError</function> is returned.
+</para>
+</sect2>
+<sect2 id="Redisplaying_Text">
+<title>Redisplaying Text</title>
+<para>
+<!-- .LP -->
+To redisplay a range of characters, use <function>XawTextInvalidate</function>:
+<!-- .IN "XawTextInvalidate" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawTextInvalidate</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPositionfrom,<parameter> to</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the start of the text to redisplay.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the end of the text to redisplay.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
+The <function>XawTextInvalidate</function>
+function causes the specified range of characters to be redisplayed
+immediately if redisplay is enabled or the next time that redisplay is
+enabled.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp 1 -->
+To enable redisplay, use <function>XawTextEnableRedisplay</function>:
+<!-- .IN "XawTextEnableRedisplay" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawTextEnableRedisplay</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+The <function>XawTextEnableRedisplay</function> function flushes any changes due to
+batched updates when <function>XawTextDisableRedisplay</function>
+was called and allows future changes to be reflected immediately.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp 1 -->
+To disable redisplay while making several changes, use
+<function>XawTextDisableRedisplay</function>.
+<!-- .IN "XawTextDisableRedisplay" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawTextDisableRedisplay</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+The <function>XawTextDisableRedisplay</function> function causes all changes to be
+batched until either <function>XawTextDisplay</function> or <function>XawTextEnableRedisplay</function>
+is called.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp 1 -->
+To display batched updates, use <function>XawTextDisplay</function>:
+<!-- .IN "XawTextDisplay" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawTextDisplay</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+The <function>XawTextDisplay</function> function forces any accumulated updates to be
+displayed.
+</para>
+</sect2>
+<sect2 id="Resources_Convenience_Routines">
+<title>Resources Convenience Routines</title>
+<para>
+<!-- .LP -->
+To obtain the character position of the left-most character on the
+first line displayed in the widget (the value of the
+<function>displayPosition</function> resource), use <function>XawTextTopPosition</function>.
+<!-- .IN "XawTextTopPosition" "" @DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XawTextPosition<function> XawTextTopPosition</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp 1 -->
+To assign a new selection array to a text widget use
+<function>XawTextSetSelectionArray</function>:
+<!-- .IN "XawTextSetSelectionArray" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawTextSetSelectionArray</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextSelectType*<parameter> sarray</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>sarray</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a selection array as defined in the section called \fBText
+Selections for Application Programmers\fP.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+Calling this function is equivalent to setting the value of the
+<function>selectionTypes</function> resource.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp 1 -->
+To move the insertion point to the specified source position, use
+<function>XawTextSetInsertionPoint</function>:
+<!-- .IN "XawTextSetInsertionPoint" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawTextSetInsertionPoint</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> position</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>position</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new position for the insertion point.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
+The text will be scrolled vertically if necessary to make the line
+containing the insertion point visible. Calling this function is
+equivalent to setting the <function>insertPosition</function> resource.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp 1 -->
+To obtain the current position of the insertion point, use
+<function>XawTextGetInsertionPoint</function>:
+<!-- .IN "XawTextGetInsertionPoint" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XawTextPosition<function> XawTextGetInsertionPoint</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
+The result is equivalent to retrieving the value of the
+<function>insertPosition</function> resource.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp 1 -->
+To replace the text source in the specified widget, use
+<function>XawTextSetSource</function>:
+<!-- .IN "XawTextSetSource" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawTextSetSource</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Widget<parameter> source</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> position</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the text source object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>position</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies character position that will become the upper left hand corner
+of the displayed text. This is usually set to zero.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
+A display update will be performed if redisplay is enabled.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp 1 -->
+To obtain the current text source for the specified widget, use
+<function>XawTextGetSource</function>:
+<!-- .IN "XawTextGetSource" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Widget<function> XawTextGetSource</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function returns the text source that this Text widget is currently
+using.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To enable and disable the insertion point, use
+<function>XawTextDisplayCaret</function>:
+<!-- .IN "XawTextDisplayCaret" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawTextDisplayCaret</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Boolean<parameter> visible</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Text widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>visible</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether or not the caret should be displayed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+If <function>visible</function> is <function>False</function> the insertion point will be disabled.
+The marker is re-enabled either by setting <function>visible</function> to <function>True</function>, by
+calling <function>XtSetValues</function>, or by executing the <function>display-caret</function>
+action routine.
+</para>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/TextSink.xml b/libXaw/specs/TextSink.xml
new file mode 100644
index 000000000..bafe557bd
--- /dev/null
+++ b/libXaw/specs/TextSink.xml
@@ -0,0 +1,915 @@
+<sect1 id="TextSink_Object">
+<title>TextSink Object</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- TextSink Object -->
+<!-- .XE -->
+<!-- .IN "TextSink object" "" "@DEF@" -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+Application Header file &lt;X11/Xaw/TextSink.h&gt;
+<!-- .IN "TextSink.h" "" -->
+Class Header file &lt;X11/Xaw/TextSinkP.h&gt;
+<!-- .IN "TextSinkP.h" "" -->
+Class textSinkObjectClass
+<!-- .IN "textSinkObjectClass" "" -->
+Class Name TextSink
+<!-- .IN "TextSink object" "class name" -->
+Superclass Object
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The TextSink object is the root object for all text sinks. Any new text
+sink objects should be subclasses of the TextSink Object. The TextSink
+Class contains all methods that the Text widget expects a text sink to
+export.
+</para>
+<para>
+<!-- .LP -->
+Since all text sinks will have some resources in common, the TextSink
+defines a few new resources.
+</para>
+<sect2 id="textsink_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating an TextSink object instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "AsciiSink 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>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Bg Bold -->
+<!-- .Dc -->
+<!-- .Sg Bold -->
+</para>
+</sect2>
+<sect2 id="Subclassing_the_TextSink">
+<title>Subclassing the TextSink</title>
+<!-- .IN "TextSink object" "subclassing" "@DEF@" -->
+<para>
+<!-- .LP -->
+The only purpose of the TextSink Object is to be subclassed. It
+contains the minimum set of class methods that all text sinks must have.
+While all may be inherited, the direct descendant of TextSink <function>must
+specify</function> some of them as TextSink does contain enough information to
+be a valid text sink by itself. Do not try to use
+the TextSink as a valid sink for the Text widget; it is not intended
+to be used as a sink by itself.
+<informaltable>
+ <tgroup cols='4' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <thead>
+ <row>
+ <entry>Function</entry>
+ <entry>Inherit with</entry>
+ <entry>Public Interface</entry>
+ <entry>must specify</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>DisplayText</entry>
+ <entry>XtInheritDisplayText</entry>
+ <entry>XawTextSinkDisplayText</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>InsertCursor</entry>
+ <entry>XtInheritInsertCursor</entry>
+ <entry>XawTextSinkInsertCursor</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>ClearToBackground</entry>
+ <entry>XtInheritClearToBackground</entry>
+ <entry>XawTextSinkClearToBackground</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>FindPosition</entry>
+ <entry>XtInheritFindPosition</entry>
+ <entry>XawTextSinkFindPosition</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>FindDistance</entry>
+ <entry>XtInheritFindDistance</entry>
+ <entry>XawTextSinkFindDistance</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>Resolve</entry>
+ <entry>XtInheritResolve</entry>
+ <entry>XawTextSinkResolve</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>MaxLines</entry>
+ <entry>XtInheritMaxLines</entry>
+ <entry>XawTextSinkMaxLines</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>MaxHeight</entry>
+ <entry>XtInheritMaxHeight</entry>
+ <entry>XawTextSinkMaxHeight</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>SetTabs</entry>
+ <entry>XtInheritSetTabs</entry>
+ <entry>XawTextSinkSetTabs</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>GetCursorBounds</entry>
+ <entry>XtInheritGetCursorBounds</entry>
+ <entry>XawTextSinkGetCursorBounds</entry>
+ <entry>yes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<sect3 id="Displaying_Text">
+<title>Displaying Text</title>
+<para>
+<!-- .LP -->
+To display a section of the text buffer contained in the text source
+use the function <function>DisplayText</function>:
+<!-- .IN "TextSink object" "DisplayText" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> DisplayText</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Positionx,<parameter> y</parameter></paramdef>
+ <paramdef>XawTextPositionpos1,<parameter> pos2</parameter></paramdef>
+ <paramdef>Boolean<parameter> highlight</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the x location to start drawing the text.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the y location to start drawing text.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pos1</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the location within the text source of the first character
+to be printed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pos2</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the location within the text source of the last character
+to be printed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>highlight</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether or not to paint the text region highlighted.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+The Text widget will only pass one line at a time to the text sink, so
+this function does not need to know how to line feed the text. It is
+acceptable for this function to just ignore Carriage Returns. <emphasis remap='I'>x</emphasis>
+and <emphasis remap='I'>y</emphasis> denote the upper left hand corner of the first character to
+be displayed.
+</para>
+</sect3>
+<sect3 id="Displaying_the_Insert_Point">
+<title>Displaying the Insert Point</title>
+<para>
+<!-- .LP -->
+The function that controls the display of the text cursor is
+<function>InsertCursor</function>. This function will be called whenever the text
+widget desires to change the state of, or move the insert point.
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> InsertCursor</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Positionx,<parameter> y</parameter></paramdef>
+ <paramdef>XawTextInsertState<parameter> state</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the x location of the cursor in Pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the y location of the cursor in Pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>state</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the state of the cursor, may be one of <function>XawisOn</function> or
+<function>XawisOff</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<emphasis remap='I'>X</emphasis> and <emphasis remap='I'>y</emphasis> denote the upper left hand corner of the insert point.
+</para>
+</sect3>
+<sect3 id="Clearing_Portions_of_the_Text_window">
+<title>Clearing Portions of the Text window</title>
+<para>
+<!-- .LP -->
+To clear a portion of the Text window to its background color, the Text
+widget will call <function>ClearToBackground</function>. The TextSink object already
+defines this function as calling <function>XClearArea</function> on the region passed.
+This behavior will be used if you specify
+<function>XtInheritClearToBackground</function> for this method.
+<!-- .IN "XtInheritClearToBackground" "" -->
+<!-- .IN "TextSink object" "ClearToBackground" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> ClearToBackground</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Positionx,<parameter> y</parameter></paramdef>
+ <paramdef>Dimensionwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the x location, in pixels, of the Region to clear.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the y location, in pixels, of the Region to clear.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the width, in pixels, of the Region to clear.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the height, in pixels, of the Region to clear.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<emphasis remap='I'>X</emphasis> and <emphasis remap='I'>y</emphasis> denote the upper left hand corner of region to clear.
+</para>
+</sect3>
+<sect3 id="Finding_a_Text_Position_Given_Pixel_Values">
+<title>Finding a Text Position Given Pixel Values</title>
+<para>
+<!-- .LP -->
+To find the text character position that will be rendered at a given x
+location the Text widget uses the function <function>FindPosition</function>:
+<!-- .IN "TextSink object" "FindPosition" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> FindPosition</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> fromPos</parameter></paramdef>
+ <paramdef>intfromX,<parameter> width</parameter></paramdef>
+ <paramdef>Boolean<parameter> stopAtWordBreak</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> *pos_return</parameter></paramdef>
+ <paramdef>int*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fromPos</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a reference position, usually the first character in this line.
+This character is always to the left of the desired character location.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fromX</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the distance that the left edge of <emphasis remap='I'>fromPos</emphasis> is from the
+left edge of the window. This is the reference x location for the
+reference position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the distance, in pixels, from the reference position to the
+desired character position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>stopAtWordBreak</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether or not the position that is returned should be forced
+to be on a word boundary.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pos_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the character position that corresponds to the location that has
+been specified, or the work break immediately to the left of the
+position if <emphasis remap='I'>stopAtWordBreak</emphasis> is <function>True</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the actual distance between <emphasis remap='I'>fromPos</emphasis> and <emphasis remap='I'>pos_return</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the maximum height of the text between <emphasis remap='I'>fromPos</emphasis> and
+<emphasis remap='I'>pos_return</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function need make no attempt to deal with line feeds. The text
+widget will only call it one line at a time.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Another means of finding a text position is provided by the <function>Resolve</function>
+function:
+<!-- .IN "TextSink object" "Resolve" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> Resolve</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> fromPos</parameter></paramdef>
+ <paramdef>intfromX,<parameter> width</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> *pos_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fromPos</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a reference position, usually the first character in this line.
+This character is always to the left of the desired character location.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fromX</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the distance that the left edge of <emphasis remap='I'>fromPos</emphasis> is from the
+left edge of the window. This is the reference x location for the
+reference position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the distance, in pixels, from the reference position to the
+desired character position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pos_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the character position that corresponds to the
+location that has been specified, or the word break immediately to the left
+if <emphasis remap='I'>stopAtWordBreak</emphasis> is <function>True</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function need make no attempt to deal with line feeds. The text
+widget will only call it one line at a time. This is a more convenient
+interface to the <function>FindPosition</function> function, and provides a subset of its
+functionality.
+<!-- .IN "FindPosition" "" -->
+</para>
+</sect3>
+<sect3 id="Finding_the_Distance_Between_two_Text_Positions">
+<title>Finding the Distance Between two Text Positions</title>
+<para>
+<!-- .LP -->
+To find the distance in pixels between two text positions on the same
+line use the function <function>FindDistance</function>.
+<!-- .IN "TextSink object" "FindDistance" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> FindDistance</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPositionfromPos,<parameter> toPos</parameter></paramdef>
+ <paramdef>int<parameter> fromX</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> *pos_return</parameter></paramdef>
+ <paramdef>int*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fromPos</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the text buffer position, in characters, of the first position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fromX</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the distance that the left edge of <emphasis remap='I'>fromPos</emphasis> is from the
+left edge of the window. This is the reference x location for the
+reference position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>toPos</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the text buffer position, in characters, of the second position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resWidth</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the actual distance between <emphasis remap='I'>fromPos</emphasis>
+and <emphasis remap='I'>pos_return</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resPos</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the character position that corresponds to the actual character
+position used for <emphasis remap='I'>toPos</emphasis> in the calculations. This may be
+different than <emphasis remap='I'>toPos</emphasis>, for example if <emphasis remap='I'>fromPos</emphasis> and <emphasis remap='I'>toPos</emphasis>
+are on different lines in the file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the maximum height of the text between <emphasis remap='I'>fromPos</emphasis> and
+<emphasis remap='I'>pos_return</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function need make no attempt to deal with line feeds. The Text
+widget will only call it one line at a time.
+</para>
+</sect3>
+<sect3 id="Finding_the_Size_of_the_Drawing_area">
+<title>Finding the Size of the Drawing area</title>
+<para>
+<!-- .LP -->
+To find the maximum number of lines that will fit into the current Text
+widget, use the function <function>MaxLines</function>. The TextSink already defines
+this function to compute the maximum number of lines by using the height
+of <function>font</function>.
+<!-- .IN "TextSink object" "MaxLines" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> MaxLines</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Dimension<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the height of the current drawing area.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+Returns the maximum number of lines that will fit in <emphasis remap='I'>height</emphasis>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To find the height required for a given number of text lines, use
+the function <function>MaxHeight</function>. The TextSink already defines this
+function to compute the maximum height of the window by using the
+height of <function>font</function>.
+<!-- .IN "TextSink object" "MaxHeight" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> MaxHeight</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> lines</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the height of the current drawing area.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+Returns the height that will be taken up by the number of lines passed.
+</para>
+</sect3>
+<sect3 id="Setting_the_Tab_Stops">
+<title>Setting the Tab Stops</title>
+<para>
+<!-- .LP -->
+To set the tab stops for a text sink use the <function>SetTabs</function> function.
+The TextSink already defines this function to set the tab x location in
+pixels to be the number of characters times the figure width of
+<function>font</function>.
+<!-- .IN "TextSink object" "SetTabs" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> SetTabs</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>inttab_count,<parameter> *tabs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>tab_count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of tabs passed in <emphasis remap='I'>tabs</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>tabs</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the position, in characters, of the tab stops.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function is responsible for the converting character positions passed
+to it into whatever internal positions the TextSink uses for tab placement.
+</para>
+</sect3>
+<sect3 id="Getting_the_Insert_Point_s_Size_and_Location">
+<title>Getting the Insert Point's Size and Location</title>
+<para>
+<!-- .LP -->
+To get the size and location of the insert point use the
+<function>GetCursorBounds</function> function.
+<!-- .IN "TextSink object" "GetCursorBounds" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> GetCursorBounds</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *rect_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSinkObject.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rect_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the location and size of the insert point.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<emphasis remap='I'>Rect</emphasis> will be filled with the current size and location of the
+insert point.
+
+</para>
+</sect3>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/TextSource.xml b/libXaw/specs/TextSource.xml
new file mode 100644
index 000000000..51b9ae0c3
--- /dev/null
+++ b/libXaw/specs/TextSource.xml
@@ -0,0 +1,620 @@
+<sect1 id="TextSrc_Object">
+<title>TextSrc Object</title>
+<literallayout class="monospaced">
+Application Header file &lt;X11/Xaw/TextSrc.h&gt;
+Class Header file &lt;X11/Xaw/TextSrcP.h&gt;
+Class textSrcObjectClass
+Class Name TextSrc
+Superclass Object
+</literallayout>
+
+<para>
+<!-- .LP -->
+The TextSrc object is the root object for all text sources. Any new text
+source objects should be subclasses of the TextSrc Object. The
+TextSrc Class contains all methods the Text widget expects a text
+source to export.
+</para>
+
+<para>
+<!-- .LP -->
+Since all text sources will have some resources in common the
+TextSrc defines a few new resources.
+</para>
+
+<sect2 id="textsource_resources">
+<title>Resources</title>
+<para>
+When creating an TextSrc object instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+
+<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>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>editType</entry>
+ <entry>EditType</entry>
+ <entry>EditMode</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</sect2>
+
+<sect2 id="Subclassing_the_TextSrc">
+<title>Subclassing the TextSrc</title>
+<para>
+The only purpose of the TextSrc Object is to be subclassed. It contains
+the minimum set of class methods that all text sources must have. All
+class methods of the TextSrc must be defined, as the Text widget uses
+them all. While all may be inherited, the direct descendant of TextSrc
+<function>must</function> specify some of them as TextSrc does not contain enough
+information to be a valid text source by itself. Do not try to use the
+TextSrc as a valid source for the Text widget; it is not intended to be
+used as a source by itself and bad things will probably happen.
+</para>
+
+<informaltable>
+ <tgroup cols='4' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <thead>
+ <row>
+ <entry>Function</entry>
+ <entry>Inherit with</entry>
+ <entry>Public Interface</entry>
+ <entry>must specify</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Read</entry>
+ <entry>XtInheritRead</entry>
+ <entry>XawTextSourceRead</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>Replace</entry>
+ <entry>XtInheritReplace</entry>
+ <entry>XawTextSourceReplace</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>Scan</entry>
+ <entry>XtInheritScan</entry>
+ <entry>XawTextSourceScan</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>Search</entry>
+ <entry>XtInheritSearch</entry>
+ <entry>XawTextSourceSearch</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>SetSelection</entry>
+ <entry>XtInheritSetSelection</entry>
+ <entry>XawTextSourceSetSelection</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>ConvertSelection</entry>
+ <entry>XtInheritConvertSelection</entry>
+ <entry>XawTextSourceConvertSelection</entry>
+ <entry>no</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<sect3 id="Reading_Text_">
+<title>Reading Text.</title>
+<para>
+<!-- .LP -->
+To read the text in a text source use the <function>Read</function> function:
+<!-- .IN "TextSrc object" "Read" "@DEF@" -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XawTextPosition<function> Read</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> pos</parameter></paramdef>
+ <paramdef>XawTextBlock<parameter> *text_return</parameter></paramdef>
+ <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSrc object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pos</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the position of the first character to be read from the text buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>text</emphasis></term>
+ <listitem>
+ <para>
+Returns the text read from the source.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the maximum number of characters the TextSrc should
+return to the application in <emphasis remap='I'>text_return</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This function returns the text position immediately after the
+characters read from the
+text buffer. The function is not required to read <emphasis remap='I'>length</emphasis>
+characters if that many characters are in the file, it may break at
+any point that is convenient to the internal structure of the
+source. It may take several calls to <function>Read</function> before the desired
+portion of the text buffer is fully retrieved.
+</para>
+</sect3>
+
+<sect3 id="Replacing_Text_">
+<title>Replacing Text.</title>
+<para>
+To replace or edit the text in a text buffer use the <function>Replace</function> function:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XawTextPosition<function> Replace</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPositionstart,<parameter> end</parameter></paramdef>
+ <paramdef>XawTextBlock<parameter> *text</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term><emphasis remap='I'>w</emphasis></term>
+ <listitem>
+ <para>
+Specifies the TextSrc object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>start</emphasis></term>
+ <listitem>
+ <para>
+Specifies the position of the first character to be removed from the text
+buffer. This is also the location to begin inserting the new text.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>end</emphasis></term>
+ <listitem>
+ <para>
+Specifies the position immediately after the last character to be
+removed from the text buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>text</emphasis></term>
+ <listitem>
+ <para>
+Specifies the text to be added to the text source.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This function can return any of the following values:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><function>XawEditDone</function></term>
+ <listitem>
+ <para>
+The text replacement was successful.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>XawPositionError</function></term>
+ <listitem>
+ <para>
+<!-- .IN "XawPositionError" "" -->
+The edit mode is <function>XawtextAppend</function> and <function>start</function> is not the last
+character of the source.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>XawEditError</function></term>
+ <listitem>
+ <para>
+<!-- .IN "XawEditError" "" -->
+Either the Source was read-only or the range to be deleted is larger
+than the length of the Source.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+The <function>Replace</function> arguments <function>start</function> and <function>end</function> represent the
+text source character positions for the existing text that is to be
+replaced by the text in the text block. The characters from
+<emphasis remap='I'>start</emphasis> up to but not including <emphasis remap='I'>end</emphasis> are deleted, and the
+buffer specified by the text block is inserted in their
+place. If <emphasis remap='I'>start</emphasis> and <emphasis remap='I'>end</emphasis> are equal, no text is deleted and
+the new text is inserted after <emphasis remap='I'>start</emphasis>.
+</para>
+</sect3>
+
+<sect3 id="Scanning_the_TextSrc">
+<title>Scanning the TextSrc</title>
+<para>
+To search the text source for one of the predefined boundary types use
+the <function>Scan</function> function:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XawTextPosition<function> Scan</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> position</parameter></paramdef>
+ <paramdef>XawTextScanType<parameter> type</parameter></paramdef>
+ <paramdef>XawTextScanDirection<parameter> dir</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+ <paramdef>Boolean<parameter> include</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term><emphasis remap='I'>w</emphasis></term>
+ <listitem>
+ <para>
+Specifies the TextSrc object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>position</emphasis></term>
+ <listitem>
+ <para>
+Specifies the position to begin scanning the source.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>type</emphasis></term>
+ <listitem>
+ <para>
+Specifies the type of boundary to scan for, may be one of:
+<function>XawstPosition</function>, <function>XawstWhiteSpace</function>, <function>XawstEOL</function>,
+<function>XawstParagraph</function>, <function>XawstAll</function>. The exact meaning of these
+boundaries is left up to the individual text source.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>dir</emphasis></term>
+ <listitem>
+ <para>
+Specifies the direction to scan, may be either <function>XawsdLeft</function> to search
+<!-- .IN "XawsdLeft" "" -->
+backward, or <function>XawsdRight</function> to search forward.
+<!-- .IN "XawsdRight" "" -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>count</emphasis></term>
+ <listitem>
+ <para>
+Specifies the number of boundaries to scan for.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>include</emphasis></term>
+ <listitem>
+ <para>
+Specifies whether the boundary itself should be included in the scan.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+The <function>Scan</function> function returns the position in the text source of the desired
+boundary. It is expected to return a valid address for
+all calls made to it, thus if a particular request is made that would take
+the text widget beyond the end of the source it must return the
+position of that end.
+</para>
+</sect3>
+
+<sect3 id="Searching_through_a_TextSrc">
+<title>Searching through a TextSrc</title>
+<para>
+To search for a particular string use the <function>Search</function> function.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XawTextPosition<function> Search</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> position</parameter></paramdef>
+ <paramdef>XawTextScanDirection<parameter> dir</parameter></paramdef>
+ <paramdef>XawTextBlock<parameter> *text</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term><emphasis remap='I'>w</emphasis></term>
+ <listitem>
+ <para>
+Specifies the TextSrc object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>position</emphasis></term>
+ <listitem>
+ <para>
+Specifies the position to begin the search.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>dir</emphasis></term>
+ <listitem>
+ <para>
+Specifies the direction to search, may be either <function>XawsdLeft</function> to search
+<!-- .IN "XawsdLeft" "" -->
+backward, or <function>XawsdRight</function> to search forward.
+<!-- .IN "XawsdRight" "" -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>text</emphasis></term>
+ <listitem>
+ <para>
+Specifies a text block containing the text to search for.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This function will search through the text buffer attempting to find a
+match for the string in the text block. If a match is found in the
+direction specified, then the character location of the first character
+in the string is returned. If no text was found then
+<function>XawTextSearchError</function> is returned.
+</para>
+
+</sect3>
+
+<sect3 id="Text_Selections">
+<title>Text Selections</title>
+
+<para>
+<!-- .LP -->
+While many selection types are handled by the Text widget, text sources
+may have selection types unknown to the Text widget. When a selection
+conversion is requested by the X server the Text widget will first call
+the <function>ConvertSelection</function> function, to attempt the selection
+conversion.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Boolean<function> ConvertSelections</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Atom*selection,*target,<parameter> *type</parameter></paramdef>
+ <paramdef>caddr_t<parameter> *value_return</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> *length_return</parameter></paramdef>
+ <paramdef>int<parameter> *format_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSrc object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of selection that was requested (e.g. <function>PRIMARY</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of the selection that has been requested, which
+indicates the desired information about the selection (e.g. Filename,
+Text, Window).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the atom into which the property type of the converted
+value of the selection is to be stored. For instance, either file
+name or text might have property type <function>XA_STRING</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a pointer into which a pointer to the converted value of the
+selection
+is to be stored. The selection owner is responsible for allocating
+this storage. The memory is considered owned by the toolkit, and is
+freed by XtFree when the Intrinsics selection mechanism is done with it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a pointer into which the number of elements in value is to be stored.
+The size of each element is determined by <emphasis remap='I'>format</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a pointer into which the size in bits of the data elements of the
+selection value is to be stored.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If this function returns <function>True</function> then the Text widget will assume
+that the source has taken care of converting the selection, Otherwise the
+Text widget will attempt to convert the selection itself.
+</para>
+
+<para>
+If the source needs to know when the text selection is modified it
+should define a <function>SetSelection</function> procedure:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> SetSelection</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPositionstart,<parameter> end</parameter></paramdef>
+ <paramdef>Atom<parameter> selection</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term><emphasis remap='I'>w</emphasis></term>
+ <listitem>
+ <para>
+Specifies the TextSrc object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>start</emphasis></term>
+ <listitem>
+ <para>
+Specifies the character position of the beginning of the new text selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>end</emphasis></term>
+ <listitem>
+ <para>
+Specifies the character position of the end of the new text selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>selection</emphasis></term>
+ <listitem>
+ <para>
+Specifies the type of selection that was requested (e.g. <function>PRIMARY</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect3>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Toggle.xml b/libXaw/specs/Toggle.xml
new file mode 100644
index 000000000..d5c239898
--- /dev/null
+++ b/libXaw/specs/Toggle.xml
@@ -0,0 +1,773 @@
+<sect1 id="Toggle_Widget">
+<title>Toggle Widget</title>
+<literallayout class="monospaced">
+Application Header file &lt;Xaw/Toggle.h&gt;
+Class Header file &lt;Xaw/ToggleP.h&gt;
+Class toggleWidgetClass
+Class Name Toggle
+Superclass Command
+</literallayout>
+
+<para>
+The Toggle widget is an area, often rectangular,
+that displays a graphic. The graphic may be a text
+string containing multiple lines of characters in an 8
+bit or 16 bit character set (to be displayed with a
+<emphasis remap='I'>font</emphasis>), or in a multi-byte encoding (for use with
+a <emphasis remap='I'>fontset</emphasis>). The graphic may also be a bitmap or
+pixmap.
+</para>
+
+<para>
+This widget maintains a Boolean state (e.g.
+True/False or On/Off) and changes state whenever it is selected. When
+the pointer is on the Toggle widget, the Toggle widget may become highlighted by
+drawing a rectangle around its perimeter. This highlighting indicates
+that the Toggle widget is ready for selection. When pointer button 1 is
+pressed and released, the Toggle widget indicates that it has changed
+state by reversing its foreground and background colors, and its
+<function>notify</function> action is invoked, calling all functions on its callback
+list. If the pointer is moved off of the widget before the pointer button is
+released, the Toggle widget reverts to its previous foreground and background
+colors, and releasing the pointer button has no effect. This behavior allows
+the user to cancel the operation.
+</para>
+
+<para>
+Toggle widgets may also be part of a ``radio group.'' A radio group is a
+list of at least two Toggle widgets in which no more than one Toggle may
+be set at
+any time. A radio group is identified by the widget ID of any one of
+its members. The convenience routine <function>XawToggleGetCurrent</function> will
+return information about the Toggle widget in the radio group.
+</para>
+
+<para>
+Toggle widget state is preserved across changes in sensitivity.
+</para>
+
+<sect2 id="toggle_resources">
+<title>Resources</title>
+<para>
+When creating a Toggle widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+
+<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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>bitmap</entry>
+ <entry>Bitmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>callback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cornerRoundPercent</entry>
+ <entry>CornerRoundPercent</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>25</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>encoding</entry>
+ <entry>Encoding</entry>
+ <entry>UnsignedChar</entry>
+ <entry></entry>
+ <entry>XawTextEncoding8bit</entry>
+ </row>
+ <row>
+ <entry>font</entry>
+ <entry>Font</entry>
+ <entry>XFontStruct</entry>
+ <entry></entry>
+ <entry>XtDefaultFont</entry>
+ </row>
+ <row>
+ <entry>fontSet</entry>
+ <entry>FontSet</entry>
+ <entry>XFontSet</entry>
+ <entry></entry>
+ <entry>XtDefaultFontSet</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>graphic height + 2 * <function>internalHeight</function></entry>
+ </row>
+ <row>
+ <entry>highlightThickness</entry>
+ <entry>Thickness</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>2 (0 if Shaped)</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>internalHeight</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>internalWidth</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>justify</entry>
+ <entry>Justify</entry>
+ <entry>Justify</entry>
+ <entry></entry>
+ <entry>XtJustifyCenter (center)</entry>
+ </row>
+ <row>
+ <entry>label</entry>
+ <entry>Label</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>name of widget</entry>
+ </row>
+ <row>
+ <entry>leftBitmap</entry>
+ <entry>LeftBitmap</entry>
+ <entry>Bitmap</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>radioData</entry>
+ <entry>RadioData</entry>
+ <entry>Pointer</entry>
+ <entry></entry>
+ <entry>Name of widget</entry>
+ </row>
+ <row>
+ <entry>radioGroup</entry>
+ <entry>Widget</entry>
+ <entry>Widget</entry>
+ <entry></entry>
+ <entry>No radio group</entry>
+ </row>
+ <row>
+ <entry>resize</entry>
+ <entry>Resize</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>shapeStype</entry>
+ <entry>ShapeStyle</entry>
+ <entry>ShapeStyle</entry>
+ <entry></entry>
+ <entry>Rectangle</entry>
+ </row>
+ <row>
+ <entry>state</entry>
+ <entry>State</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>Off</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>See below</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>graphic width + 2 * <function>internalWidth</function></entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>radioData</function>
+ </term>
+ <listitem>
+ <para>
+Specifies the data that will be returned by <function>XawToggleGetCurrent</function>
+when this is the currently <emphasis remap='I'>set</emphasis> widget in the radio group. This
+value is also used to identify the Toggle that will be set by a call to
+<function>XawToggleSetCurrent</function>. The value NULL will be returned by
+<function>XawToggleGetCurrent</function> if no widget in a radio group is currently
+set. Programmers must not specify NULL (or Zero) as <function>radioData</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>radioGroup</function>
+ </term>
+ <listitem>
+ <para>
+Specifies another Toggle widget that is in the radio group to which this
+Toggle widget should be added. A radio group is a group of at least two Toggle
+widgets, only one of which may be <emphasis remap='I'>set</emphasis> at a time. If this value is
+NULL (the default) then the Toggle will not be part of any radio group
+and can change state without affecting any other Toggle widgets. If the
+widget specified in this resource is not already in a radio group then a
+new radio group will be created containing these two Toggle widgets. No
+Toggle widget can be in multiple radio groups. The behavior of a radio
+group of one toggle is undefined. A converter is registered which will
+convert widget names to widgets without caching.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>state</function>
+ </term>
+ <listitem>
+ <para>
+Specifies whether the Toggle widget is set (<function>True</function>) or unset
+(<function>False</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect2>
+
+<sect2 id="Toggle_Actions">
+<title>Toggle Actions</title>
+<para>
+The Toggle widget supports the following actions:
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+Switching the Toggle widget between the foreground and background
+colors with <function>set</function> and <function>unset</function> and <function>toggle</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Processing application callbacks with <function>notify</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Switching the internal border between highlighted
+and unhighlighted states with <function>highlight</function> and <function>unhighlight</function>
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+The following are the default translation bindings used by the
+Toggle widget:
+</para>
+
+<literallayout class="monospaced">
+ &lt;EnterWindow&gt;: highlight(Always)
+ &lt;LeaveWindow&gt;: unhighlight()
+ &lt;Btn1Down&gt;,&lt;Btn1Up&gt;: toggle() notify()
+</literallayout>
+</sect2>
+
+<sect2 id="Toggle_Actions_b">
+<title>Toggle Actions_b</title>
+<para>
+The full list of actions supported by Toggle is:
+</para>
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>highlight</function>(<emphasis remap='I'>condition</emphasis>)
+ </term>
+ <listitem>
+ <para>
+Displays the internal highlight border in the color (<function>foreground</function>
+or <function>background</function> ) that contrasts with the interior color of the
+Toggle widget. The conditions <function>WhenUnset</function> and <function>Always</function> are
+understood by this action procedure. If no argument is passed then
+<function>WhenUnset</function> is assumed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>unhighlight</function>()
+ </term>
+ <listitem>
+ <para>
+Displays the internal highlight border in the color (<function>foreground</function>
+or <function>background</function> ) that matches the interior color of the
+Toggle widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>set</function>()
+ </term>
+ <listitem>
+ <para>
+Enters the <emphasis remap='I'>set</emphasis> state, in which <function>notify</function> is possible. This
+action causes the Toggle widget to display its interior in the
+<function>foreground</function> color. The label or bitmap is displayed in the
+<function>background</function> color.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>unset</function>()
+ </term>
+ <listitem>
+ <para>
+Cancels the <emphasis remap='I'>set</emphasis> state and displays the interior of the Toggle widget in the
+<function>background</function> color. The label or bitmap is displayed in the
+<function>foreground</function> color.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>toggle</function>()
+ </term>
+ <listitem>
+ <para>
+Changes the current state of the Toggle widget, causing to be set
+if it was previously unset, and unset if it was previously set.
+If the widget is to be set, and is in a radio group then this procedure may
+unset another Toggle widget causing all routines on its callback list
+to be invoked. The callback routines for the Toggle that
+is to be unset will be called before the one that is to be set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>reset</function>()
+ </term>
+ <listitem>
+ <para>
+Cancels any <function>set</function> or <function>highlight</function> and displays the interior of the
+Toggle widget in the <function>background</function> color, with the label displayed in the
+<function>foreground</function> color.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>notify</function>()
+ </term>
+ <listitem>
+ <para>
+When the Toggle widget is in the <function>set</function> state this action calls all functions in
+the callback list named by the <function>callback</function> resource. The value of
+the call_data argument in these callback functions is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+When a bitmap of depth greater that one (1) is specified the
+<emphasis remap='I'>set</emphasis>(), <emphasis remap='I'>unset</emphasis>(), and <emphasis remap='I'>reset</emphasis>() actions have no effect,
+since there are no foreground and background colors used in a
+multi-plane pixmap.
+</para>
+</sect2>
+
+<sect2 id="Radio_Groups">
+<title>Radio Groups</title>
+<para>
+There are typically two types of radio groups desired by applications.
+The default translations for the Toggle widget implement a "zero or one
+<!-- .IN "Radio groups" "zero or one of many" -->
+of many" radio group. This means that there may be no more than one
+Toggle widget active, but there need not be any Toggle widgets active.
+</para>
+
+<para>
+The other type of radio group is "one of many" and has the more strict
+policy that there will always be exactly one radio button active.
+Toggle widgets can be used to provide this interface with a slight
+modification to the translation table of each Toggle in the group.
+</para>
+
+<literallayout class="monospaced">
+ &lt;EnterWindow&gt;: highlight(Always)
+ &lt;LeaveWindow&gt;: unhighlight()
+ &lt;Btn1Down&gt;,&lt;Btn1Up&gt;: set() notify()
+</literallayout>
+
+<para>
+This translation table will not allow any Toggle to be <emphasis remap='I'>unset</emphasis>
+except as a result of another Toggle becoming <emphasis remap='I'>set</emphasis>. It is
+the application programmer's responsibility to choose an initial
+state for the radio group by setting the <function>state</function> resource of one of
+its member widgets to <function>True</function>.
+</para>
+</sect2>
+
+<sect2 id="toggle_convenience_routines">
+<title>Convenience Routines</title>
+<para>
+The following functions allow easy access to the Toggle widget's radio
+group functionality.
+</para>
+
+<sect3 id="Changing_the_Toggle_s_Radio_Group_">
+<title>Changing the Toggle's Radio Group.</title>
+<para>
+To enable an application to change the Toggle's radio group, add
+the Toggle to a radio group, or remove the Toggle from a radio group, use
+<function>XawToggleChangeRadioGroup</function>.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawToggleChangeRadioGroup</function></funcdef>
+ <paramdef>Widgetw,<parameter> radio_group</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Toggle widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>radio_group</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any Toggle in the new radio group. If NULL then the Toggle
+will be removed from any radio group of which it is a member.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+
+<para>
+If a Toggle is already <emphasis remap='I'>set</emphasis> in the new radio group,
+and the Toggle to be added is also <emphasis remap='I'>set</emphasis> then the previously
+<emphasis remap='I'>set</emphasis> Toggle in the radio group is <emphasis remap='I'>unset</emphasis> and its callback
+procedures are invoked.
+Finding the Currently selected Toggle in a radio group of Toggles
+</para>
+
+<para>
+To find the currently selected Toggle in a radio group of Toggle widgets
+use <function>XawToggleGetCurrent</function>.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XtPointer<function> XawToggleGetCurrent</function></funcdef>
+ <paramdef>XtPointer<parameter> XawToggleGetCurrent(radio_group)</parameter></paramdef>
+ <paramdef>Widget<parameter> radio_group</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>radio_group</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any Toggle widget in the radio group.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The value returned by this function is the
+<function>radioData</function>
+of the Toggle in this radio group that is currently set. The default
+value for <function>radioData</function>
+is the name of that Toggle widget. If no Toggle is set in the radio
+group specified then NULL is returned.
+Changing the Toggle that is set in a radio group.
+</para>
+
+<para>
+To change the Toggle that is currently set in a radio group use
+<function>XawToggleSetCurrent</function>.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawToggleSetCurrent</function></funcdef>
+ <paramdef>voidXawToggleSetCurrent(radio_group,<parameter> radio_data)</parameter></paramdef>
+ <paramdef>Widget<parameter> radio_group</parameter></paramdef>
+ <paramdef>XtPointer<parameter> radio_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>radio_group</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any Toggle widget in the radio group.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>radio_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>radioData</function>
+identifying the Toggle that should be set in the radio group specified
+by the <emphasis remap='I'>radio_group</emphasis> argument.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+<function>XawToggleSetCurrent</function> locates the Toggle widget to be set by
+matching <emphasis remap='I'>radio_data</emphasis> against the <function>radioData</function> for each Toggle in
+the radio group. If none match, <function>XawToggleSetCurrent</function> returns
+without making any changes. If more than one Toggle matches,
+<function>XawToggleSetCurrent</function> will choose a Toggle to set arbitrarily. If
+this causes any Toggle widgets to change state, all routines in their
+callback lists will be invoked. The callback routines for a Toggle that
+is to be unset will be called before the one that is to be set.
+Unsetting all Toggles in a radio group.
+</para>
+
+<para>
+To unset all Toggle widgets in a radio group use
+<function>XawToggleUnsetCurrent</function>.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawToggleUnsetCurrent</function></funcdef>
+ <paramdef>void<parameter> XawToggleUnsetCurrent(radio_group)</parameter></paramdef>
+ <paramdef>Widget<parameter> radio_group</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>radio_group</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any Toggle widget in the radio group.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If this causes a Toggle widget to change state, all routines on its
+callback list will be invoked.
+</para>
+</sect3>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Tree.xml b/libXaw/specs/Tree.xml
new file mode 100644
index 000000000..bb51e80d1
--- /dev/null
+++ b/libXaw/specs/Tree.xml
@@ -0,0 +1,404 @@
+<sect1 id="Tree_Widget">
+<title>Tree Widget</title>
+<literallayout class="monospaced">
+Application Header file &lt;X11/Xaw/Tree.h&gt;
+Class Header file &lt;X11/Xaw/TreeP.h&gt;
+Class treeWidgetClass
+Class Name Tree
+Superclass Constraint
+</literallayout>
+
+<para>
+The Tree widget provides geometry management of arbitrary widgets arranged
+in a directed, acyclic graph (i.e., a tree). The hierarchy is constructed
+by attaching a constraint resource called <function>treeParent</function> to each widget
+indicating which other node in the tree should be treated as the widget's
+superior. The structure of the tree is shown by laying out the nodes
+in the standard format for tree diagrams with lines drawn connecting each
+node with its children.
+</para>
+
+<para>
+The Tree sizes itself according to the needs of its children and is not
+intended to be resized by its parent. Instead, it should be placed inside
+another composite widget (such as the <function>Porthole</function> or <function>Viewport</function>)
+that can be used to scroll around in the tree.
+</para>
+
+<sect2 id="tree_resources">
+<title>Resources</title>
+<para>
+When creating a Tree widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+
+<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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>autoReconfigure</entry>
+ <entry>AutoReconfigure</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>children</entry>
+ <entry>ReadOnly</entry>
+ <entry>WidgetList</entry>
+ <entry>R</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>gravity</entry>
+ <entry>Gravity</entry>
+ <entry>XtGravity</entry>
+ <entry></entry>
+ <entry>WestGravity</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>see <function>Layout Semantics</function></entry> <!-- xref -->
+ </row>
+ <row>
+ <entry>hSpace</entry>
+ <entry>HSpace</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>lineWidth</entry>
+ <entry>LineWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>numChildren</entry>
+ <entry>ReadOnly</entry>
+ <entry>Cardinal</entry>
+ <entry>R</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>vSpace</entry>
+ <entry>VSpace</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>see <function>Layout Semantics</function></entry> <!-- xref -->
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<variablelist>
+ <varlistentry>
+ <term><function>autoReconfigure</function></term>
+ <listitem>
+ <para>
+Whether or not to layout the tree every time a node is added or removed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>gravity</function></term>
+ <listitem>
+ <para>
+Specifies the side of the widget from which the tree should grow. Valid
+values include <function>WestGravity</function>, <function>NorthGravity</function>, <function>EastGravity</function>, and
+<function>SouthGravity</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>hSpace</function></term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>vSpace</function></term>
+ <listitem>
+ <para>
+The amount of space, in pixels, to leave between the children. This
+resource specifies the amount of space left between the outermost
+children and the edge of the box.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>lineWidth</function></term>
+ <listitem>
+ <para>
+The width of the lines from nodes that do not have a <function>treeGC</function>
+constraint resource to their children.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="tree_constraint_resources">
+<title>Constraint Resources</title>
+<para>
+Each child of the Tree widget must specify its superior node in the tree. In
+addition, it may specify a GC to use when drawing a line between it and its
+inferior nodes.
+</para>
+
+<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>treeGC</entry>
+ <entry>TreeGC</entry>
+ <entry>GC</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>treeParent</entry>
+ <entry>TreeParent</entry>
+ <entry>Widget</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+
+
+<variablelist>
+ <varlistentry>
+ <term><function>treeGC</function></term>
+ <listitem>
+ <para>
+This specifies the GC to use when drawing lines between this widget and its
+inferiors in the tree. If this resource is not specified, the Tree's
+<function>foreground</function> and <function>lineWidth</function> will be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>treeParent</function></term>
+ <listitem>
+ <para>
+This specifies the superior node in the tree for this widget. The default is
+for the node to have no superior (and to therefore be at the top of the tree).
+
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect2>
+
+
+<sect2 id="tree_layout_semantics">
+<title>Layout Semantics</title>
+<para>
+Each time a child is managed or unmanaged, the Tree widget will attempt
+to reposition the remaining children to fix the shape of the tree if the
+<!-- .B autoReconfigure -->
+resource is set. Children at the top (most superior) of the tree are
+drawn at the side specified by the resource.
+</para>
+
+<para>
+After positioning all children, the Tree widget attempts to shrink its
+own size to the minimum dimensions required for the layout.
+</para>
+
+</sect2>
+
+<sect2 id="tree_convenience_routines">
+<title>Convenience Routines</title>
+<para>
+The most efficient way to layout a tree is to set
+<function>autoReconfigure</function>
+to False and then use the
+<function> XawTreeForceLayout</function>
+routine to arrange the children.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawTreeForceLayout</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>w</term>
+ <listitem>
+ <para>
+Specifies the Tree widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect2>
+</sect1>
diff --git a/libXaw/specs/Viewport.xml b/libXaw/specs/Viewport.xml
new file mode 100644
index 000000000..3b3703639
--- /dev/null
+++ b/libXaw/specs/Viewport.xml
@@ -0,0 +1,391 @@
+<sect1 id="Viewport_Widget">
+<title>Viewport Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Viewport Widget -->
+<!-- .XE -->
+<!-- .IN "Viewport widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file &lt;X11/Xaw/Viewport.h&gt;
+<!-- .IN "Viewport.h" "" -->
+Class Header file &lt;X11/Xaw/ViewportP.h&gt;
+<!-- .IN "ViewportP.h" "" -->
+Class viewportWidgetClass
+<!-- .IN "viewportWidgetClass" "" -->
+Class Name Viewport
+<!-- .IN "Viewport widget" "class name" -->
+Superclass Form
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The Viewport widget consists of a frame window, one or two Scrollbars,
+and an inner window. The size of the frame window is determined by the
+viewing size of the data that is to be displayed and the dimensions to
+which the Viewport is created. The inner window is the full size of the
+data that is to be displayed and is clipped by the frame window. The
+Viewport widget controls the scrolling of the data directly. No
+application callbacks are required for scrolling.
+</para>
+<para>
+<!-- .LP -->
+When the geometry of the frame window is equal in size to the inner
+window, or when the data does not require scrolling, the Viewport widget
+automatically removes any scrollbars. The <function>forceBars</function> option causes
+the Viewport widget to display all scrollbars permanently.
+</para>
+<sect2 id="viewport_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Viewport widget instance, the following resources are
+retrieved from the argument list or the resource database:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "Viewport widget" "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>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>allowHoriz</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>allowVert</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>children</entry>
+ <entry>ReadOnly</entry>
+ <entry>WidgetList</entry>
+ <entry>R</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>forceBars</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>height of the child</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>numChildren</entry>
+ <entry>ReadOnly</entry>
+ <entry>Cardinal</entry>
+ <entry>R</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>reportCallback</entry>
+ <entry>ReportCallback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>useBottom</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>useRight</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>width of the child</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>allowHoriz</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>allowVert</function>
+ </term>
+ <listitem>
+ <para>
+If these resources are <function>False</function> then the Viewport will never create
+a scrollbar in this direction. If it is <function>True</function> then the scrollbar will
+only appear when it is needed, unless <function>forceBars</function> is <function>True</function>.
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Ch -->
+<!-- .Cm -->
+<!-- .Dp -->
+<!-- .Dc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>forceBars</function>
+ </term>
+ <listitem>
+ <para>
+When <function>True</function> the scrollbars that have been <emphasis remap='I'>allowed</emphasis> will always be
+visible on the screen. If <function>False</function> the scrollbars will be visible only
+when the inner window is larger than the frame.
+<!-- .Hw -->
+<!-- .Mm -->
+<!-- .Nc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>reportCallback</function>
+ </term>
+ <listitem>
+ <para>
+These callbacks will be executed whenever the Viewport adjusts the viewed
+area of the child. The call_data parameter is a pointer to an XawPannerReport
+structure.
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>useBottom</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>useRight</function>
+ </term>
+ <listitem>
+ <para>
+By default the scrollbars appear on the left and top of the screen.
+These resources allow the vertical scrollbar to be placed on the right
+edge of the Viewport, and the horizontal scrollbar on the bottom edge of
+the Viewport.
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="viewport_layout_semantics">
+<title>Layout Semantics</title>
+<para>
+<!-- .LP -->
+<!-- .IN "Viewport widget" "layout semantics" -->
+The Viewport widget manages a single child widget. When the size of the
+child is larger than the size of the Viewport, the user can interactively
+move the child within the Viewport by repositioning the scrollbars.
+</para>
+<para>
+<!-- .LP -->
+The default size of the Viewport before it is realized is the width and/or
+height of the child. After it is realized, the Viewport will allow its
+child to grow vertically or horizontally if <function>allowVert</function> or
+<function>allowHoriz</function> are set, respectively. If the corresponding vertical
+or horizontal scrollbar is not enabled, the Viewport will propagate the
+geometry request to its own parent and the child will be allowed to change
+size only if the Viewport's parent allows it. Regardless of whether or not
+scrollbars are enabled in the corresponding direction, if the child requests
+a new size smaller than the Viewport size, the change will be allowed only
+if the parent of the Viewport allows the Viewport to shrink to the
+appropriate dimension.
+</para>
+<para>
+<!-- .LP -->
+The scrollbar children of the Viewport are named <function>horizontal</function> and
+<function>vertical</function>. By using these names the programmer can specify resources
+for the individual scrollbars. <function>XtSetValues</function> can be used to modify
+the resources dynamically once the widget ID has been obtained with
+<function>XtNameToWidget</function>.
+<!-- .IN "XtNameToWidget" "" -->
+<!-- .NT -->
+</para>
+<note><para>
+Although the Viewport is a Subclass of the Form, no resources for the Form
+may be supplied for any of the children of the Viewport. These constraints
+are managed internally and are not meant for public consumption.
+</para></note>
+<!-- .NE -->
+
+</sect2>
+</sect1>
diff --git a/libXaw/specs/libXaw.xml b/libXaw/specs/libXaw.xml
new file mode 100644
index 000000000..d8a0a35bc
--- /dev/null
+++ b/libXaw/specs/libXaw.xml
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<book id="libXaw">
+
+<bookinfo>
+ <title>Athena Widget Set - C Language Interface</title>
+ <subtitle>X Consortium Standard</subtitle>
+ <releaseinfo>X Version 11, Release 6.4</releaseinfo>
+ <authorgroup>
+ <author>
+ <firstname>Chris</firstname><surname>Peterson</surname>
+ </author>
+ </authorgroup>
+ <copyright><year>1985</year><holder>X Consortium</holder></copyright>
+ <copyright><year>1986</year><holder>X Consortium</holder></copyright>
+ <copyright><year>1987</year><holder>X Consortium</holder></copyright>
+ <copyright><year>1988</year><holder>X Consortium</holder></copyright>
+ <copyright><year>1989</year><holder>X Consortium</holder></copyright>
+ <copyright><year>1991</year><holder>X Consortium</holder></copyright>
+ <copyright><year>1994</year><holder>X Consortium</holder></copyright>
+ <releaseinfo>libXaw 1.0.7</releaseinfo>
+ <affiliation><orgname>formerly MIT X Consortium</orgname></affiliation>
+ <productnumber>X Version 11, Release 7</productnumber>
+
+<legalnotice>
+
+<para>
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files
+(the &ldquo;Software&rdquo;), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following
+conditions:
+</para>
+
+<para>
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+</para>
+
+<para>
+THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+</para>
+
+<para>
+Except as contained in this notice, the name of the X Consortium shall not
+be used in advertising or otherwise to promote the sale, use or other dealings
+in this Software without prior written authorization from the X Consortium.
+</para>
+
+<para>
+Permission to use, copy, modify and distribute this documentation for any
+purpose and without fee is hereby granted, provided that the above copyright
+notice appears in all copies and that both that copyright notice and this
+permission notice appear in supporting documentation, and that the name of
+Digital not be used in in advertising or publicity pertaining
+to distribution of the software without specific, written prior permission.
+Digital makes no representations about the suitability of the
+software described herein for any purpose.
+It is provided ``as is'' without express or implied warranty.
+</para>
+
+<para>
+Except as contained in this notice, the name of the X Consortium shall not be
+used in advertising or otherwise to promote the sale, use or other dealings
+in this Software without prior written authorization from the X Consortium.
+</para>
+</legalnotice>
+</bookinfo>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH1.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH2.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH3.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH4.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH5.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH6.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH7.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TPage_Credits.xml"/>
+</book>
+