# Module: `awful.keyboard`

Utilities related to the keyboard and keybindings.

### Info:

- Copyright: 2018-2019 Emmanuel Lepage Vallee
- Originally authored by: Emmanuel Lepage Vallee <elv1313@gmail.com>
  (Full contributors list available on our github project)

## Functions

awful.keyboard.append_global_keybindings (keys) | Add multiple awful.key based keybindings to the global set. |

## Static module functions

awful.keyboard.emulate_key_combination (modifiers, key) | Execute a key combination. |
awful.keyboard.append_global_keybinding (key) | Add an awful.key based keybinding to the global set. |
awful.keyboard.remove_global_keybinding (key) | Remove a keybinding from the global set. |
awful.keyboard.append_client_keybinding (key) | Add an awful.key to the default client keys. |
awful.keyboard.append_client_keybindings (keys) | Add a awful.keys to the default client keys. |
awful.keyboard.remove_client_keybinding (key) -> boolean | Remove a key from the default client keys. |
awful.keyboard.get_key_name () -> (string, nil) or (string, nil) | Get X11 keysym and a one-character representation from an Awesome keycode. |

## Functions

🔗 awful.keyboard.append_global_keybindings (keys)
  Add multiple awful.key based keybindings to the global set.

  A **global** keybinding is one which is always present, even when there is no focused client. If your intent is too add a keybinding which acts on the focused client do **not** use this

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  keys |  | table | A table of awful.key objects.
  group | Optional | string | If set, the `group` property will be set on all `awful.keys`objects.

  ### See also:

  awful.key | Create easily new key objects ignoring certain modifiers. | module
  awful.keyboard.append_global_keybinding | Add an awful.key based keybinding to the global set. | static module functions
  awful.keyboard.remove_global_keybinding | Remove a keybinding from the global set. | static module functions

## Static module functions

🔗 awful.keyboard.emulate_key_combination (modifiers, key)
  Execute a key combination.

  If an awesome keybinding is assigned to the combination, it should be executed.

  To limit the chances of accidentally leaving a modifier key locked when calling this function from a keybinding, make sure is attached to the release event and not the press event.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  modifiers |  | table | A modified table. Valid modifiers are: `Any`, `Mod1`, `Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`.
  key |  | string | The key.

  ### See also:

  root.fake_input | Send fake keyboard or mouse events. (root) | static module functions

🔗 awful.keyboard.append_global_keybinding (key)
  Add an awful.key based keybinding to the global set.

  A **global** keybinding is one which is always present, even when there is no focused client. If your intent is too add a keybinding which acts on the focused client do **not** use this.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  key |  | awful.key | The key object.

  ### See also:

  awful.key | Create easily new key objects ignoring certain modifiers. | module
  awful.keyboard.append_global_keybindings | Add multiple awful.key based keybindings to the global set. | functions
  awful.keyboard.remove_global_keybinding | Remove a keybinding from the global set. | static module functions

🔗 awful.keyboard.remove_global_keybinding (key)
  Remove a keybinding from the global set.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  key |  | awful.key | The key object.

  ### See also:

  awful.key | Create easily new key objects ignoring certain modifiers. | module
  awful.keyboard.append_global_keybinding | Add an awful.key based keybinding to the global set. | static module functions

🔗 awful.keyboard.append_client_keybinding (key) · 1 signal
  Add an awful.key to the default client keys.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  key |  | awful.key | The key.

  ### See also:

  awful.key | Create easily new key objects ignoring certain modifiers. | module
  awful.keyboard.append_client_keybindings | Add a awful.keys to the default client keys. | static module functions

  Click to display more

  ### Emit signals:

  - `client_keybinding::added`
  - `key` awful.key The key.
🔗 awful.keyboard.append_client_keybindings (keys) · 1 signal
  Add a awful.keys to the default client keys.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  keys |  | table | A table of awful.key objects.
  group | Optional | string | If set, the `group` property will be set on all `awful.keys`objects.

  ### See also:

  awful.key | Create easily new key objects ignoring certain modifiers. | module
  awful.keyboard.append_client_keybinding | Add an awful.key to the default client keys. | static module functions

  Click to display more

  ### Emit signals:

  - `client_keybinding::added`
  - `key` awful.key The key.
🔗 awful.keyboard.remove_client_keybinding (key) -> boolean
  Remove a key from the default client keys.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  key |  | awful.key | The key.

  ### Returns:

  boolean True if the key was removed and false if it wasn't found.

  ### See also:

  awful.keyboard.append_client_keybinding | Add an awful.key to the default client keys. | static module functions

🔗 awful.keyboard.get_key_name () -> (string, nil) or (string, nil)
  Get X11 keysym and a one-character representation from an Awesome keycode.

  A "one-character representation" is a single UTF-8 representing the typical output from that keysym in a text editor (e.g. " " for space, "ñ" for n_tilde, "Ā" for A_macron). It usually matches the main engraving of the key for level-0 symbols (but lowercase).

  Keycodes may be given in a string in any valid format for awful.key: "#" + keycode, the symkey name and the UTF-8 representation will all work.

  If no suitable keysym is found, or a malformed keycode is given as an argument, this function will return (nil, nil)

  ### Returns:

  1. string keysym The keysym name
  2. nil keysym If no valid keysym is found

  ### Or

  1. string printsymbol The xkb_keysym_to_utf8 result
  2. nil printsymbol If the keysym has no printable representation.

generated by LDoc 1.5.0