<section role="NotInToc" id="rich_comboBox">
   <title>
				&lt;
				rich:comboBox
				&gt;
				<emphasis role="since">
         <superscript> available since <emphasis role="version">3.2.0</emphasis>
         </superscript>
      </emphasis>
   </title>
   <section>
        <title>Description</title>
        <para>
              The <emphasis role="bold">
            <property>&lt;rich:comboBox&gt;</property>
         </emphasis> component allows to create a combobox element with the built-in Ajax capability.
        </para>
        <figure>
            <title>
            <emphasis role="bold">
               <property>&lt;rich:comboBox&gt;</property>
            </emphasis> component</title>
            <mediaobject> 
                <imageobject>
                    <imagedata fileref="images/comboBox_init.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        
    </section>
   <section>
        <title>Key Features</title>    
        <itemizedlist>
            <listitem>
                <para>Client-side suggestions</para>
            </listitem>
            <listitem>
                <para>Browser like selection</para>
            </listitem>
            <listitem>
                <para>Smart user-defined positioning</para>
            </listitem>
            <!--listitem>Possible to set the popup appearance delay through <emphasis><property>&quot;showDelay&quot;</property></emphasis> 
                or <emphasis><property>&quot;minChars&quot;</property></emphasis> attributes
                </listitem-->
            <listitem>
                <para>Seam entity converter support</para>
            </listitem>
            <listitem>
                <para>Highly customizable look and feel</para>
            </listitem>
            <listitem>
                <para>Disablement support</para>
            </listitem>
        </itemizedlist>
    </section>
   <section>
        <title>Details of Usage</title>
        <para>The <emphasis role="bold">
            <property>&lt;rich:comboBox&gt;</property>
        </emphasis> 
            is a simplified suggestion box component, that provides input with client-side suggestions.
            <!--
            component consists of an <property>input field</property>, the <property>button</property> and the <property>popup list</property> of suggestions 
            attached to input. If you want to see the popup list you can press the <property>button</property> or type the first letter of suggested word in the <property>input field</property>.
            -->
            
            The component could be in two states:
            
            <!-- NEED DESCRIPTION "HOW TO MANAGE THIS"-->
           
            <itemizedlist>
                <listitem>
               <para>Default - only input and button is shown</para>
            </listitem>
                <listitem>
               <para>Input, button and a popup list of suggestions attached to input is shown</para>
            </listitem>
            </itemizedlist>
        </para>
        <para>
            There are two ways to get values for the popup list of suggestions:
        </para>
            <itemizedlist>
                <listitem>
                    <para>Using the <emphasis>
                  <property>"suggestionValues"</property>
               </emphasis> attribute, that defines the suggestion collection</para>
                    <programlisting role="XML"><![CDATA[...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" />
...]]></programlisting>                        
                </listitem>
                <listitem>
                <para>
                Using the <emphasis role="bold">
                  <property>&lt;f:selectItem /&gt;</property>
               </emphasis> or <emphasis role="bold">
                    <property>&lt;f:selectItems /&gt;</property>
               </emphasis> JSF components.
                </para>

                	<programlisting role="XML"><![CDATA[...
<rich:comboBox value="#{bean.state}" valueChangeListener="#{bean.selectionChanged}">
        <f:selectItems  value="#{bean.selectItems}"/>
        <f:selectItem itemValue="Oregon"/>			  
        <f:selectItem itemValue="Pennsylvania"/>
        <f:selectItem itemValue="Rhode Island"/>
        <f:selectItem itemValue="South Carolina"/>
</rich:comboBox>            
...]]></programlisting> 
                    <note>
                        <title>Note:</title>
                        <para>
                            These JSF components consider only the <emphasis>
                     <property>"value"</property>
                  </emphasis> attribute for this component.
                        </para>
                    </note>
             </listitem>
            </itemizedlist>
        <para> Popup list content loads at page render time. No additional requests could be performed on the popup calling.
        </para>
        <para>
            The <emphasis>
            <property> "value"</property>
         </emphasis> attribute stores value from input after submit. 
        </para>
        <para>
            The <emphasis>
            <property> "directInputSuggestions"</property>
         </emphasis> attribute defines, how the first value from the suggested one appears in an input field. 
            If it's "true" the first value appears with the suggested part highlighted. 
        </para>
 
   	<programlisting role="XML"><![CDATA[...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" directInputSuggestions="true" />   
...]]></programlisting>        
        <para>This is a result:</para>
            <figure>
                <title>
            <emphasis role="bold">
                    <property>&lt;rich:comboBox&gt;</property>
                </emphasis> with <emphasis>
               <property> "directInputSuggestions"</property>
            </emphasis> attribute.</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="images/comboBox3.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            
        <para>
        The <emphasis>
            <property> "selectFirstOnUpdate"</property>
         </emphasis> attribute defines if the first value from suggested is selected in a popup list. 
        If it's "false" nothing is selected in the list before a user hovers some item with the mouse. 
        </para>

   	<programlisting role="XML"><![CDATA[...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" selectFirstOnUpdate="false" />           
...]]></programlisting>     
        <para>This is a result:</para>
            <figure>
                <title>
            <emphasis role="bold">
                    <property>&lt;rich:comboBox&gt;</property>
                </emphasis> with <emphasis>
               <property> "selectFirstOnUpdate"</property>
            </emphasis> attribute.</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="images/comboBox4.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
       
        <!--para>
            The <emphasis><property> &quot;filterNewValues&quot;</property></emphasis> attribute defines the appearance of values in the list.
            If it&apos;s &quot;true&quot; only the part of a list, which satisfies the prefix entered appears in a popup list.
            If it&apos;s &quot;false&quot; all values appear in the popup list and the list is scrolled to the first value that satisfies the prefix.            
            </para-->
        <para>
          The <emphasis>
            <property>"defaultLabel"</property>
         </emphasis> attribute defines the default label of the input element. Simple example is placed below.
        </para>

   	<programlisting role="XML"><![CDATA[...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" defaultLabel="Select a city..." />     
...]]></programlisting>     
        <para>This is a result:</para>
            <figure>
                <title>
            <emphasis role="bold">
                    <property>&lt;rich:comboBox&gt;</property>
                </emphasis> with <emphasis>
               <property> "defaultLabel"</property>
            </emphasis> attribute.</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="images/comboBox5.png"/>
                    </imageobject>
                </mediaobject>
            </figure>                                                                                                                                                                                                                                                                        
      <para>
                With the help of the <emphasis>
            <property>"disabled"</property>
         </emphasis> attribute you can disable the whole 
                <emphasis role="bold">
            <property>&lt;rich:comboBox&gt;</property>
         </emphasis> component. See the following example.
            </para>

   	<programlisting role="XML"><![CDATA[...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" defaultLabel="Select a city..." disabled="true" />       
...]]></programlisting>  
        <para>This is a result:</para>
                <figure>
                    <title>
            <emphasis role="bold">
                        <property>&lt;rich:comboBox&gt;</property>
                    </emphasis> with <emphasis>
               <property> "disabled"</property>
            </emphasis> attribute.</title>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="images/comboBox6.png"/>
                        </imageobject>
                    </mediaobject>
                </figure>      
        <para>
              The <emphasis>
            <property>"enableManualInput"</property>
         </emphasis> attribute enables/disables input field, so when <code>enableManualInput = "false"</code>,
      	user can only pick the value manually and has no possibility to type in the value (default value is "false").
      </para>
        <!--para>
        The <emphasis role="bold"><property>&lt;rich:comboBox&gt;</property></emphasis> component provides the possibility to use 
            specific event attribute <emphasis><property> &quot;onlistcall&quot;</property></emphasis> which is fired before the list opening.
        </para-->
        
        <para>
            The <emphasis role="bold">
            <property>&lt;rich:comboBox&gt;</property>
         </emphasis> component provides to use 
            specific event attributes:
            <itemizedlist>
            <listitem>
               <para>
                  <emphasis>
                     <property> "onlistcall"</property>
                  </emphasis>which is fired before the list opening and gives you a possibility to cancel list popup/update 
            </para>
            </listitem>
            <listitem>
               <para>
                  <emphasis>
                     <property> "onselect"</property>
                  </emphasis>which gives you a possibility to send Ajax request when item is selected 
            </para>
            </listitem>
            </itemizedlist>   
         </para>
        
        <para>
            The <emphasis role="bold">
            <property>&lt;rich:comboBox&gt;</property>
         </emphasis> component allows to use sizes attributes:
            <itemizedlist>
                <listitem>
               <para>
                    <emphasis>
                     <property> "listWidth"</property>
                  </emphasis> and <emphasis>
                     <property> "listHeight"</property>
                  </emphasis> attributes
                    specify popup list sizes with values in pixels
                </para>
            </listitem>
                <listitem>
               <para>
                    <emphasis>
                     <property> "width"</property>
                  </emphasis> attribute customizes the size of input element with values in pixels.
                </para>
            </listitem>
            </itemizedlist>  
        </para>
       <!-- <para>It&apos;s possible to handle events for comboBox from JavaScript code. A simplest example of usage JavaScript API is placed below:</para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[...
    <rich:comboBox defaultLabel="Enter some value" id="comboBoxID">
        ...
    </rich:comboBox>
...
<h:commandButton value="Enable" onclick="#{rich:component('comboBoxID')}.enable(event)"/>     
...]]></programlisting>  -->
        
          </section>
   <section>
      <title>Reference Data</title>
      <para>
         <ulink url="&tlddoc;rich/comboBox.html">Table of 
							&lt;rich:comboBox&gt; 
							 attributes</ulink>.
						</para>
      <table>
        <title>Component Identification Parameters</title>
        
        <tgroup cols="2">
            <thead>
                <row>
                    <entry>Name</entry>
                    <entry>Value</entry>
                </row>
            </thead>
            <tbody>
                <row>
                    <entry>component-type</entry>
                    <entry>org.richfaces.ComboBox</entry>
                </row>
                <row>
                    <entry>component-class</entry>
                    <entry>org.richfaces.component.html.HtmlComboBox</entry>
                </row>
                <row>
                    <entry>component-family</entry>
                    <entry>org.richfaces.ComboBox</entry>
                </row>
                <row>
                    <entry>renderer-type</entry>
                    <entry>org.richfaces.renderkit.ComboBoxRenderer</entry>
                </row>
                <row>
                    <entry>tag-class</entry>
                    <entry>org.richfaces.taglib.ComboBoxTag</entry>
                </row>
            </tbody>
        </tgroup>
      </table>
      <table>
            <title>JavaScript API</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Function</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>showList()</entry>
                        <entry>Shows the popup list</entry>
                    </row>
                    <row>
                        <entry>hideList()</entry>
                        <entry>Hides the popup list</entry>
                    </row>
                    <row>
                        <entry>   enable()</entry>
                        <entry> Enables the control for input</entry>
                    </row>
                    <row>
                        <entry>  disable()</entry>
                        <entry>Disables the control for input</entry>
                    </row>
                </tbody>
            </tgroup>
      </table>
		
   	<table>
   		<title>Style classes (selectors) with the corresponding skin parameters</title>
   		<tgroup cols="4">
   			<thead>
   				<row>
   					<entry>Class (selector) name</entry>
   					<entry>Description</entry>
   					<entry>Skin Parameter</entry>
   					<entry>CSS properties mapped</entry>
   				</row>
   			</thead>
   			<tbody>         
   				<row>
   					<entry>input.rich-combobox-button-background, input.rich-combobox-button-background-disabled, input.rich-combobox-button-background-inactive</entry>
   					<entry>Define styles for a background of the combobox button, disabled button and inactive button respectively</entry>
   					<entry>tabBackgroundColor</entry>
   					<entry>background-color</entry>
   				</row>
   				
   				<row>
   					<entry>input.rich-combobox-button-pressed-background</entry>
   					<entry>Define styles for a background of the pressed button</entry>
   					<entry>tabBackgroundColor</entry>
   					<entry>background-color</entry>
   				</row>
   				
   				<row>
   					<entry morerows="1">input.rich-combobox-button, input.rich-combobox-button-inactive, input.rich-combobox-button-disabled</entry>
   					<entry morerows="1">Define styles for the combobox button, disabled button and inactive button respectively</entry>
   					<entry>panelBorderColor</entry>
   					<entry>border-top-color</entry>
   				</row>
   				<row>
   					<entry>panelBorderColor</entry>
   					<entry>border-left-color</entry>
   				</row>
   				
   				<row>
   					<entry morerows="2">.rich-combobox-font, input.rich-combobox-font</entry>
   					<entry morerows="2">Define styles for a font</entry>
   					<entry>generalSizeFont</entry>
   					<entry>font-size</entry>
   				</row>
   				<row>
   					<entry>generalFamilyFont</entry>
   					<entry>font-family</entry>
   				</row>
   				<row>
   					<entry>generalTextColor</entry>
   					<entry>color</entry>
   				</row>
   				
   				<row>
   					<entry morerows="1">input.rich-combobox-font-disabled, .rich-combobox-font-disabled</entry>
   					<entry morerows="1">Defines styles for a disabled font</entry>
   					<entry>headerFamilyFont</entry>
   					<entry>font-family</entry>
   				</row>
   				<row>
   					<entry>headerSizeFont</entry>
   					<entry>font-size</entry>
   				</row>
   				
   				<row>
   					<entry morerows="2">input.rich-combobox-font-inactive, .rich-combobox-font-inactive</entry>
   					<entry morerows="2">Defines styles for an inactive font</entry>
   					<entry>generalSizeFont</entry>
   					<entry>font-size</entry>
   				</row>
   				<row>
   					<entry>generalFamilyFont</entry>
   					<entry>font-family</entry>
   				</row>
   				<row>
   					<entry>generalTextColor</entry>
   					<entry>color</entry>
   				</row>
   				
   				<row>
   					<entry morerows="2">.rich-combobox-item</entry>
   					<entry morerows="2">Defines styles for an item</entry>
   					<entry>generalSizeFont</entry>
   					<entry>font-size</entry>
   				</row>
   				<row>
   					<entry>generalFamilyFont</entry>
   					<entry>font-family</entry>
   				</row>
   				<row>
   					<entry>generalTextColor</entry>
   					<entry>color</entry>
   				</row>
   				
   				<row>
   					<entry morerows="2">.rich-combobox-input, .rich-combobox-input-disabled, .rich-combobox-input-inactive</entry>
   					<entry morerows="2">Define styles for an input field, a disabled input field, an inactive input field respectively</entry>
   					<entry>controlBackgroundColor</entry>
   					<entry>background-color</entry>
   				</row>
   				<row>
   					<entry>panelBorderColor</entry>
   					<entry>border-bottom-color</entry>
   				</row>
   				<row>
   					<entry>panelBorderColor</entry>
   					<entry>border-right-color</entry>
   				</row>
   				
   				<row>
   					<entry morerows="1">.rich-combobox-item-selected</entry>
   					<entry morerows="1">Defines styles for a selected item</entry>
   					<entry>headerBackgroundColor</entry>
   					<entry>background-color, border-color</entry>
   				</row>
   				<row>
   					<entry>headerTextColor</entry>
   					<entry>color</entry>
   				</row>
   				
   				<row>
   					<entry morerows="1">.rich-combobox-list-decoration</entry>
   					<entry morerows="1">Defines styles for a list decoration</entry>
   					<entry>panelBorderColor</entry>
   					<entry>border-color</entry>
   				</row>
   				<row>
   					<entry>tableBackgroundColor</entry>
   					<entry>background</entry>
   				</row>
   				
   				<row>
   					<entry>input.rich-combobox-button-hovered</entry>
   					<entry>Defines styles for a hovered button</entry>
   					<entry>selectControlColor</entry>
   					<entry>border-color</entry>
   				</row>   	
   			</tbody>
   		</tgroup>
   	</table>
   	
   	<table id="comboBoxC">
   		<title>Style classes (selectors) without skin parameters</title>
   		<tgroup cols="2">
   			<thead>
   				<row>
   					<entry>Class name</entry>
   					<entry>Description</entry>
   				</row>
   			</thead>
   			<tbody>
   				<row>
   					<entry>.rich-combobox-shell</entry>
   					<entry>Defines styles for a wrapper &lt;div&gt; element of a list</entry>
   				</row>
   				<row>
   					<entry>.rich-combobox-list-position</entry>
   					<entry>Defines position of a list</entry>
   				</row>              
   				<row>
   					<entry>.rich-combobox-list-scroll</entry>
   					<entry>Defines styles for a list scrolling</entry>
   				</row>
   				<row>
   					<entry>input.rich-combobox-button-icon</entry>
   					<entry>Defines styles for a button icon</entry>
   				</row>
   				<row>
   					<entry>input.rich-combobox-button-icon-inactive</entry>
   					<entry>Defines styles for an inactive button icon</entry>
   				</row>
   				<row>
   					<entry>input.rich-combobox-button-icon-disabled</entry>
   					<entry>Defines styles for a disabled button icon</entry>
   				</row>
   				<row>
   					<entry>.rich-combobox-shadow</entry>
   					<entry>Defines styles for a wrapper &lt;div&gt; element of a shadow</entry>
   				</row>
   				<row>
   					<entry>.rich-combobox-shadow-tl</entry>
   					<entry>Defines styles for a top-left element of a shadow</entry>
   				</row>
   				<row>
   					<entry>.rich-combobox-shadow-tr</entry>
   					<entry>Defines styles for a top-right element of a shadow</entry>
   				</row>
   				<row>
   					<entry>.rich-combobox-shadow-bl</entry>
   					<entry>Defines styles for a bottom-left element of a shadow</entry>
   				</row>
   				<row>
   					<entry>.rich-combobox-shadow-br</entry>
   					<entry>Defines styles for a bottom-right element of a shadow</entry>
   				</row>
   			</tbody>
   		</tgroup>
   	</table>
   	
   	<para>You can find all necessary information about style classes redefinition in 
						<link linkend="customstyles">Definition of Custom Style Classes</link> 
							section.</para>
						</section>
   <section>
        <title>Relevant Resources Links</title>
        <para>
              Visit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/comboBox.jsf?c=comboBox">ComboBox page</ulink> at  RichFaces LiveDemo for examples of component usage and their sources.
      </para>
    </section>
</section>
