aboutsummaryrefslogtreecommitdiff
path: root/libXaw/specs/List.xml
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2011-03-25 15:37:13 +0000
committermarha <marha@users.sourceforge.net>2011-03-25 15:37:13 +0000
commit41a502478a2972358dec934d82ee401c61a5cd36 (patch)
tree3fda8100e6da9b4a2863789e393016a750502067 /libXaw/specs/List.xml
parent81aeaf653a832c4054d9a40b1cc796911521a739 (diff)
parent272e57235cd60a2e65ac8258d96a02eb3939b687 (diff)
downloadvcxsrv-41a502478a2972358dec934d82ee401c61a5cd36.tar.gz
vcxsrv-41a502478a2972358dec934d82ee401c61a5cd36.tar.bz2
vcxsrv-41a502478a2972358dec934d82ee401c61a5cd36.zip
svn merge ^/branches/released .
Diffstat (limited to 'libXaw/specs/List.xml')
-rw-r--r--libXaw/specs/List.xml872
1 files changed, 872 insertions, 0 deletions
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>