10:30 p.m.
Author: SeanRogers
Date: 2010-10-19 23:30:01 -0400 (Tue, 19 Oct 2010)
New Revision: 19610
Modified:
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml
Log:
Draft of richselectOne complete
Modified:
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml
===================================================================
---
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml 2010-10-19
23:53:42 UTC (rev 19609)
+++
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml 2010-10-20
03:30:01 UTC (rev 19610)
@@ -787,14 +787,46 @@
The <sgmltag><rich:selectOne></sgmltag> component provides a
drop-down list box for selecting a single value from multiple options. The component
supports keyboard navigation and can optionally accept typed input as a combo-box.
</para>
+ <figure id="figu-Component_Reference-richselectOne-richselectOne">
+ <title><sgmltag><rich:selectOne></sgmltag></title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/figu-Component_Reference-richselectOne-richselectOne.png"
format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A <sgmltag><rich:selectOne></sgmltag> component used as a
combo-box.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+
<section id="sect-Component_Reference-richselectOne-Basic_usage">
<title>Basic usage</title>
<para>
Simple usage of the <sgmltag><rich:selectOne></sgmltag>
component does not need any attributes declared, but child tags to manage the list of
selections are required. An <sgmltag><f:selectItem></sgmltag>
tag manages the currently selected value, while an
<sgmltag><f:selectItems></sgmltag> tag points to the list of
selection items.
</para>
+ <example id="exam-Component_Reference-richselectOne-Selection_items">
+ <title>Selection items</title>
+ <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richselectOne-Selection_items.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ <para>
+ The arrow keys on a keyboard can be used to highlight different items in the list,
even if the list is closed with the control still focused. If the control loses focus or
the <keycap function="enter">Enter</keycap> key is pressed, the
highlighted option is chosen as the value and the list is closed. Pressing the <keycap
function="escape">Esc</keycap> key will close the list but not change
the value.
+ </para>
</section>
- <!--FIXME: finish draft -->
+ <section
id="sect-Component_Reference-richselectOne-Using_richselectOne_as_a_combo-box">
+ <title>Using <sgmltag><rich:selectOne></sgmltag> as a
combo-box</title>
+ <para>
+ Combo-boxes are drop-down lists that allow the user to type into a text field to
scroll through or filter the list. By default, the
<sgmltag><rich:selectOne></sgmltag> component functions as a
drop-down list. To add keyboard support to make it function like a combo-box, set
<code>enableManualInput="true"</code>.
+ </para>
+ <para>
+ Once the user begins typing, the first available matching option is highlighted. If
the typed text does not match any values in the list, no value is chosen and the drop-down
list displays as empty. Other keyboard interaction remains the same as the basic drop-down
list.
+ </para>
+ <para>
+ Typing text into a combo-box causes the list to scroll to the relevant item by
default. This behavior can be changed so that the typed text filters the contents of the
list instead, showing only those items that begin with the typed text. To use typed text
as a filter for combo-box lists, set
<code>filterOnUpdates="true"</code>.
+ </para>
+ </section>
<section id="sect-Component_Reference-richselectOne-Reference_data">
<title>Reference data</title>