Key bind behavior

Within the scope of a container object such as a form, bind a function or control key to an action and/or function. Pressing the function/control key invokes the action and/or function.

The Keybind behavior is used to execute an action or JavaScriptâ„¢ function whenever a function or control key is pressed while keyboard focus is within the component or any component within it. The scope of the binding depends on the kind of tag to which the behavior is assigned. If the behavior is bound to a container tag such as a form, div or body, whenever keyboard focus is within the container and the key is pressed, the action/function is run. If the behavior is bound to a non-container tag such as an input tag, then the binding applies only when that tag has keyboard focus.

When the specified key is pressed the function (if provided) is executed. If an action (or list of actions) is provided, the actions are executed next. If both a function and action are provided, the function can prevent execution of the action by returning false. In either case, the "default" behavior of the key is NOT executed. For example, if the F1 key is bound, the default browser behavior of displaying help does not happen when the F1 key is pressed.

JSF tags that emit the component

<hx:behaviorKeyPress>

Base HTML

Any HTML container tag such as a <form> or <div> or any HTML tag that accepts keyboard input such as <input>

Multiple keybinds can be attached to a tag.

JavaScript constructor

hX_5.addBehavior("id", "onkeydown", new hX_5.JSFBehaviorKeybind(attributes)); where

id

The ID of the HTML tag to which the component is attached.

attributes

Comma separated list of attributes where each attribute is a quoted string consisting of the attribute name and value separated by a colon, for example "label:MyLabel".

Supported events

Event

Description

onkeydown

Behavior can only be attached to key down events (not key press or key up).

Attributes

Table 1.

Attribute name

Description

keycode

The (decimal) number representing the key (for example 112 is function key 1).

modifier

Modifier key that must be pressed in conjunction with the key (for example SHIFT + F1).

action

An action (or a set of actions) to be performed when a click-able entity is clicked. A target for the action (or a set of targets) are normally required.

target

If supplied, the ID of an input type='text' field in the page. Whenever something is selected in the menu, the text of the menu item is set as the value of the specified field. This is normally only used when making a popup menu which is emulating a combo-box (that is you have an input field with an adjacent menu where the top-level of the menu is a single button, clicking the button displays the menu, choosing an item from the menu sets the value of the input field.)

function

A JavaScript function (or inline string of JavaScript) to perform when the key is pressed.

Sequencing

Runs after any other handlers provided for the event.

Stops the event continuing/bubbling after all the actions/function are executed.

API calls

Table 2. Keybind behavior API calls

API call

Description

object = setAttribute(attribute)

Sets an attribute or changes its value (if it was set previously).

string = getAttribute(attribute-name)

Retrieves the current value of an attribute.

Limitations

Keybind can only be used with the onkeydown event and it can only be used for non-alphanumeric keys.

Example code

Within a form, bind the F1 key so that it advances to the next field, Shift F1 so it advances to the previous field. Disable the tab key.

hX.addBehavior("form1", "onkeydown", new hX.JSFBehaviorKeybind ("keycode:112", "modifier:Shift", 
                 "action:prevTab"));
hX.addBehavior("form1", "onkeydown", new hX.JSFBehaviorKeybind ("keycode:112", 
                 "action:nextTab"));
hX.addBehavior("form1", "onkeydown", new hX.JSFBehaviorKeybind ("keycode:9", "modifier:Shift", 
                 "action:nothing"));
hX.addBehavior("form1", "onkeydown", new hX.JSFBehaviorKeybind ("keycode:9", 
                 "action:nothing"));

Feedback