Send your remarks, comments or wishes to doc team
Subject:
Message:
Your name:
Your email:

JBoss.org Community Documentation

- Prev
- Next

## 6.58. < rich:hotKey >

### 6.58.1. Description

The <rich:hotKey> component allows to register hot keys for the page or particular elements and to define client side processing functions for these keys.

### 6.58.2. Key Features

- Includes all features of the Javascript jQuery Hotkeys Plugin

- Hot key registration by request through JavaScript API

- Possibility to attach <rich:hotKey> to a whole page or to a particular element using "selector" attribute

- Hot key registration timing

- Enabling/disabling the <rich:hotKey> using JavaScript API

Table 6.243. rich : hotKey attributes

Attribute Name | Description
--- | ---
binding | The attribute takes a value-binding expression for a component property of a backing bean
checkParent | Defines the hotkey handling of events generated by child components nested into the parent component to which the <rich:hotKey> is attached.
disableInInput | Disables the hotkeys activated on input elements when the value of this attribute is "true".
disableInInputTypes | Defines the types of the inputs not to be influenced with hotKey component. Possible values: buttons, texts and all (default). By default it is empty and this means ALL the types.
handler | Defines the JavaScript function name which is called on hotkey activation
id | Every component may have a unique id that is automatically created if omitted
key | Defines the hotkey itself
rendered | If "false", this component is not rendered
selector | Defines a selector for query
timing | Defines the time when the hotkey is registered. Possible values are "immediate" (by default), "onload", and "onregistercall".
type | Defines the type of a keyboard event (onkeyup, onkeypress, etc.)

Table 6.244. Component identification parameters

Name | Value
--- | ---
component-type | org.richfaces.HotKey
component-class | org.richfaces.component.html.HtmlHotKey
component-family | org.richfaces.HotKey
renderer-type | org.richfaces.HotKeyRenderer

### 6.58.3. Creating the Component with a Page Tag

To create the simplest variant on a page use the following syntax:

Example:

    ...

    <rich:hotKey key="alt+a" handler="alert('alt+A is pressed')" />

    ...

### 6.58.4. Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmlHotKey;

    ...

    HtmlHotKey myHotKey = new HtmlHotKey();

    ...

### 6.58.5. Details of Usage

There are two ways to register <rich:hotKey> :

- just place it anywhere on the page. In this case the <rich:hotKey> component is attached to the whole page (html[0] element). This is default scenario.

- attach it with "selector" attribute to all the elements defined using this selector. This attribute uses defined by w3c consortium syntax for CSS rule selector with some jQuery extensions.

The "key" attribute defines the hot key itself which is processed by the component.

After the hot key has been registered and defined you could set the "handler" attribute which determines a JavaScript function to be called every time when corresponding keys are pressed.

Example:

    ...

    <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()"/>

    ...

In the example above the "selector" attribute is used. So the keys work only if <rich:listShuttle> component is focused.

You could press Right or Left keys in order to move some selected items between lists. You could press Home or End buttons in order to move all items between lists.

With the help of the "timing" attribute you could manage <rich:hotKey> registration timing. There are three possible values of this attribute:

- "immediate" - the component is rendered in browser immediately (by default)

- "onload" - the component is rendered after the page is fully loaded

- "onregistercall" - the component is rendered only after JavaScript API for the key registration is used.

The "type" attribute defines the type of keyboard event. Possible values are: "onkeyup", "onkeypress" and "onkeydown".

The "disableInInput" attribute disables the <rich:hotKey> if it is activated on input elements and the value of this attribute is "true".

The "checkParent" attribute defines the hotkey handling of events generated by child components nested into the parent component to which the <rich:hotKey> is attached.

The <rich:hotKey> component also provides a number of JavaScript API functions. There is an example below.

Example:

    ...

    <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>

    ...

In the example above the Ctrl+G is registered as a global hotkey, so if you press this key combination the alert window with the "Ctrl+G is pressed" text appears. With the help of enable(), disable() JavaScript API fucntions you could enable or disable registered hotkey.

### 6.58.6. JavaScript API

Table 6.245. JavaScript API

Function | Description
--- | ---
add(selector, key, handler) | Adds the hotkey(from key param) for elements targeted by selector. it assigns a handler function to the key
remove() | Removes hotkey registration
enable() | Enables registered hotkey
disable() | Disables registered hotkey

### 6.58.7. Look-and-Feel Customization

<rich:hotKey> has no skin parameters and custom style classes, as the component isn't visual.

### 6.58.8. Relevant Resources Links

Here you can see an example of <rich:hotKey> usage and sources for the given example.

- Prev6.57. < rich:virtualEarth >
- Top of page
- Front page
- Next6.59. < rich:inplaceInput >