<?xml version="1.0" encoding="UTF-8"?>
<section>
    <sectioninfo>
        <keywordset>
            <keyword>rich:hotKey</keyword>
            <keyword>hotKey</keyword>
        </keywordset>
    </sectioninfo>
    <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.HotKey</entry>
                </row>
                <row>
                    <entry>component-class</entry>
                    <entry>org.richfaces.component.html.HtmlHotKey</entry>
                </row>
                <row>
                    <entry>component-family</entry>
                    <entry>org.richfaces.HotKey</entry>
                </row>
                <row>
                    <entry>renderer-type</entry>
                    <entry>org.richfaces.HotKeyRenderer</entry>
                </row>
                 <!--row>
                    <entry>tag-class</entry>
                    <entry></entry>
                </row-->
            </tbody>
        </tgroup>
    </table>
    <section>
        <title>Creating the Component with a Page Tag</title>
        <para>To create the simplest variant on a page use the following syntax:</para>

        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[...
<rich:hotKey key="alt+a" handler="alert('alt+A is pressed')" />
...]]></programlisting>
    </section>
    <section>
        <title>Creating the Component Dynamically Using Java</title>

        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="JAVA"><![CDATA[import org.richfaces.component.html.HtmlHotKey;     
...
HtmlHotKey myHotKey = new HtmlHotKey();
...]]></programlisting>
    </section>
    <section>
		<title>Details of Usage</title>
		<para>
			There are two ways to register <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis>:
		</para>
		<itemizedlist>
		    <listitem>
		        <para>
		            by attaching it to the whole page (<property>html[0] element</property>). This is default scenario.
		        </para>
		    </listitem>
		    <listitem>
		        <para>
		            by attaching it with <emphasis><property>&quot;selector&quot;</property></emphasis> attribute to all the elements 
		            defined using this selector. 
		            This attribute uses defined by <ulink url="http://www.w3.org">w3c consortium</ulink> syntax for CSS rule selector 
		            with some jQuery extensions. 
		        </para>
		    </listitem>
		</itemizedlist>
        <para>
            The <emphasis><property>&quot;key&quot;</property></emphasis> attribute defines the hot key itself 
            which is processed by the component. 
        </para>
        <para>
            After the hot key has been registered and defined you could set the <emphasis><property>&quot;handler&quot;</property></emphasis> 
            attribute which determines a JavaScript function to be called every time when corresponding keys are pressed.   
        </para>
		<para>
			<emphasis role="bold">
				Example:
			</emphasis>
		</para>
		<programlisting role="XML"><![CDATA[...
<rich:listShuttle var="cap" sourceValue="#{capitalsBean.capitals}" id="ls">
	<rich:column>
		<f:facet name="header">
			<h:outputText value="State flag"/>
		</f:facet>
		<h:graphicImage value="#{cap.stateFlag}"/>
	</rich:column>
	<rich:column>
		<f:facet name="header">
			<h:outputText value="State name"/>
		</f:facet>
		<h:outputText value="#{cap.name}"/>
	</rich:column>
</rich:listShuttle>
<rich:hotKey selector="#ls" key="right" handler="#{rich:component('ls')}.copy()"/>
<rich:hotKey selector="#ls" key="left" handler="#{rich:component('ls')}.remove()"/>
<rich:hotKey selector="#ls" key="end" handler="#{rich:component('ls')}.copyAll()"/>
<rich:hotKey selector="#ls" key="home" handler="#{rich:component('ls')}.removeAll()"/>
...]]></programlisting>
        <para>
			In the example above the <emphasis><property>&quot;selector&quot;</property></emphasis> attribute is used. 
			So the keys work only if <emphasis role="bold"><property>&lt;rich:listShuttle&gt;</property></emphasis> component is focused. 
		</para>
		<para>
			You could press <property>Right</property> or <property>Left</property> keys in order to move some selected items between lists. 
			You could press <property>Home</property> or <property>End</property> buttons in order to move all items between lists. 
		</para>
        <para>
            With the help of the <emphasis><property>&quot;timing&quot;</property></emphasis> attribute
            you could manage <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis> registration timing. 
            There are three possible values of this attribute:
        </para>
        <itemizedlist>
            <listitem>
                <para>
                    &quot;immediate&quot; - the component is rendered in browser immediately  
                </para>
            </listitem>
            <listitem>
                <para>
                    &quot;onload&quot; - the component is rendered after the page is fully loaded
                </para>
            </listitem>
            <listitem>
                <para>
                    &quot;onregistercall&quot; - the component is rendered only after JavaScript API for the key registration is used.
                </para>
            </listitem>
        </itemizedlist>
        <para>
            The <emphasis><property>&quot;type&quot;</property></emphasis> attribute defines the type of keyboard event. Possible values are: 
            &quot;onkeyup&quot;, &quot;onkeypress&quot; and &quot;onkeydown&quot;.
        </para>
<!--EXAMPLE -->        
	<para>
	  The <emphasis><property>&quot;disableInInput&quot;</property></emphasis> attribute disables the <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis> if it is activated on input elements and the value of this attribute is &quot;true&quot;.
	</para>
    <para>
	  The <emphasis><property>&quot;checkParent&quot;</property></emphasis> attribute defines the hotkey handling of events generated by child components nested into the parent component to which the <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis> is attached.
	</para>
	</section>
    <section>
        <title>JavaScript API</title>
        <table>
            <title>JavaScript API</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Function</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>add(selector, key, handler)</entry>
                        <entry>
							Adds the hotkey(from key param) for elements targeted by selector. Assigns handler function to the key.
						</entry>
                    </row>
                    <row>
                        <entry>remove()</entry>
                        <entry>Removes hotkey registration</entry>
                    </row>
                    <row>
                        <entry>enable()</entry>
                        <entry>Enables registered hotkey</entry>
                    </row>
                    <row>
                        <entry>disable()</entry>
                        <entry>Disables registered hotkey</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </section>
  <section>
    <title>Look-and-Feel Customization</title>
    <para><emphasis role="bold">
      <property>&lt;rich:hotKey&gt;</property>
    </emphasis> has no skin parameters and custom <property>style classes</property>, as the
      component isn&apos;t visual.</para>
  </section>
  
    <section>
      <title>Relevant Resources Links</title>
	<para>
		<ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/hotKey.jsf?c=hotKey">Here</ulink> you can see an example of  
		<emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis> usage and sources for the given example. 
	</para>    
  </section>
</section>