<?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>
		 just 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 (<property>html[0] element</property>). This is default scenario.
		        </para>
		    </listitem>
		    <listitem>
		        <para>
		attach 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 (by default) 
                </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>
	<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>
	<para>
		<emphasis role="bold">Example:</emphasis>
	</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 <property>Ctrl+G</property> is registered as a global hotkey, 
		so if you press this key combination the alert window with the <property>&quot;Ctrl+G is pressed&quot;</property> text appears. With the help
		of <property>enable()</property>, <property>disable()</property> JavaScript API fucntions you could enable or disable registered hotkey.
	</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. 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>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">On RichFaces LiveDemo page </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>