<section role="NotInToc" id="rich_hotKey">
      <title> &lt; rich:hotKey &gt; <emphasis role="since">
                  <superscript> available since <emphasis role="version">3.2.2</emphasis>
                  </superscript>
            </emphasis>
      </title>
      <section>
            <title>Description</title>
            <para>
                  The <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis> component allows to register hot keys for the page or particular elements and to define client-side processing functions for these keys.
            </para>
      </section>
      <section>
            <title>Key Features</title>
            <itemizedlist>
                  <listitem>
                        <para>Includes all features of the <ulink url="http://code.google.com/p/js-hotkeys/">Javascript jQuery Hotkeys Plugin</ulink>
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                              Hot key registration by request through JavaScript API
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                              Possibility to attach <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis> to a whole page or to a particular element using <emphasis><property>"selector"</property></emphasis> attribute
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                              Hot key registration timing
                        </para>
                  </listitem>

                  <listitem>
                        <para>
                              Enabling/disabling the <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis> using JavaScript API
                        </para>
                  </listitem>
            </itemizedlist>
      </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>
                              place it anywhere on the page. In this case the <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis> component is attached to the whole page (<code>html[0] element</code>). This is default scenario.
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                              attach it with <emphasis><property>"selector"</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>"key"</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>"handler"</property></emphasis> attribute which determines a JavaScript function to be called every time when corresponding keys are pressed.
            </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>"selector"</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>"timing"</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>
                              <code>immediate</code> — the component is rendered in browser immediately (default value);
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                              <code>onload</code> — the component is rendered after the page is fully loaded;
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                              <code>onregistercall</code> — the component is rendered only after JavaScript API for the key registration is used. 
                        </para>
                  </listitem>
            </itemizedlist>
            <para>The <emphasis><property>"type"</property></emphasis> attribute defines the type of keyboard event. Possible values are: <code>onkeyup</code>, <code>onkeypress</code> and <code>onkeydown</code>.
            </para>
            <!--EXAMPLE -->
            <para> The <emphasis>
                        <property>"disableInInput"</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 <code>true</code>. </para>
            <para> The <emphasis>
                        <property>"checkParent"</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>
            <para> The <emphasis role="bold">
                        <property>&lt;rich:hotKey&gt;</property>
                  </emphasis> component also provides a number of JavaScript API functions. There is an example below. </para>
            <programlisting role="XML"><![CDATA[<h:form id="myForm">
	<rich:hotKey id="myKey" key="ctrl+g" handler="alert('Ctrl+G is pressed')" />
	<button onclick="${rich:component('myKey')}.enable(); return false;">Turn Ctrl+G On</button>
	<button onclick="${rich:component('myKey')}.disable(); return false;">Turn Ctrl+G Off</button>
</h:form>]]></programlisting>
            <para>
                  In the example above the <code>Ctrl+G</code> is registered as a global hotkey, so if you press this key combination the alert window with the <code>"Ctrl+G is pressed"</code> text appears. 
                  With the help of <code>enable()</code>, <code>disable()</code> JavaScript API fucntions you could enable or disable registered hotkey.
            </para>
      </section>
      <section>
            <title>Reference Data</title>
            <para>
                  <ulink url="&tlddoc;rich/hotKey.html">Table of &lt;rich:hotKey&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.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>
            <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. it assigns a 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>Relevant Resources Links</title>
            <para>
                  Visit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/hotKey.jsf?c=hotKey">HotKey page</ulink> at RichFaces LiveDemo for examples of  component usage and their sources.
            </para>
      </section>
</section>
