# Keyboard events

## Availability

* UNTIL Orbeon Forms 2018.2
  * `keypress`
* SINCE Orbeon Forms 2019.1
  * `keypress`, `keydown` and `keyup`

## Rationale

The main idea behind supporting keyboard events is to allow creating keyboard shortcuts.

## Basic usage

You can, by listening to the `keypress`, `keydown` and `keyup` events, run actions as users type a certain key combination. Your listener can be registered on:

* **The whole document**, in which case it will run whenever users press the key combination you specified. You can register a listener on the whole document either by declaring your listener directly under the `xh:body` as in:

  ```xml
  <xh:body>
      <xf:action 
          event="keydown" 
          xxf:modifiers="ctrl" 
          xxf:text="y">
          ...
      </xf:action>
      ...
  </xh:body>
  ```

  Or you can declare it anywhere in your form with an observer set to `#document`, as in:

  ```xml
  <xf:action 
      event="keydown" 
      observer="#document" 
      xxf:modifiers="ctrl"
      xxf:text="y">
      ...
  </xf:action>
  ```
* **Part of the document**, in which case you set your actions to listen on a XForms control such as a `xf:group` or an `xf:input`. Note that in this case, your listener will be called only if a form control (either the one you have specified, or form control inside the one you have specified for container form controls) has the focus when users press the key combination.
* **A dialog**, in which case your listener will be called only when users press the key combination while the dialog is open. In this case, the only requirement for the listener to be called is for the dialog to be open; the focus does not necessarily need to be on a form control inside the dialog.

You specify what key stroke(s) you want to listen to with the following two attributes:

* `xxf:text`:
  * mandatory for `keypress`, `keydown` and `keyup` handlers
  * the key you want to listen to
  * SINCE Orbeon Forms 2019.1
    * special keys are supported: `backspace`, `tab`, `enter`, `return`, `capslock`, `esc`, `escape`, `space`, `pageup`, `pagedown`, `end`, `home`, `left`, `up`, `right`, `down`, `ins`, `del`, `plus`
* `xxf:modifier`
  * optional
  * space-separated list of key modifiers that need to be pressed in addition to the key
  * UNTIL Orbeon Forms 2018.2
    * values can be `Control`, `Shift`, and `Alt`
  * SINCE Orbeon Forms 2019.1
    * values are no longer case-sensitive, but lowercase is recommended
    * `shift`, `ctrl` (`control` is supported for backward compatibility), `alt`/`option`, `meta`/`command`

*NOTE: When using modifiers, the event name should be `keydown`. For backward compatibility, `keypress` is still supported but translated to `keydown`.*

## See also

* [Standard support](/xforms/events/events-standard.md)
* [UI refresh events](/xforms/events/events-refresh.md)
* [Extension events](/xforms/events/events-extensions-events.md)
* [Extension context information](/xforms/events/events-extensions-context.md)
* [Other event extensions](/xforms/events/events-extensions-other.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.orbeon.com/xforms/events/events-extensions-keyboard.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.