# Module `awful.key`

Create easily new key objects ignoring certain modifiers.

### Info:

- Copyright: 2009 Julien Danjou
- Author: Julien Danjou <julien@danjou.info>

## Functions

execute (mod, k) | Execute a key combination.
new (mod, _key, press[, release], data) | Create a new key to use as binding.
match (_key, pressed_mod, pressed_key) | Compare a key object with modifiers and key.

## Tables

awful.key.ignore_modifiers | Modifiers to ignore.

## Functions

Methods

execute (mod, k)
  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.

  - mod table A modified table. Valid modifiers are: Any, Mod1, Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control.
  - k string The key

  ### See also:

  root.fake_input
new (mod, _key, press[, release], data)
  Create a new key to use as binding. This function is useful to create several keys from one, because it will use the ignore_modifier variable to create several keys with and without the ignored modifiers activated. For example if you want to ignore CapsLock in your keybinding (which is ignored by default by this function), creating a key binding with this function will return 2 key objects: one with CapsLock on, and another one with CapsLock off.
  - mod table A list of modifier keys. Valid modifiers are: Any, Mod1, Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control.
  - _key string The key to trigger an event.
  - press function Callback for when the key is pressed.
  - release function Callback for when the key is released. (optional)
  - data table User data for key, for example {description="select next tag", group="tag"}.

  ### Returns:

  table A table with one or several key objects.

  ### See also:

  key.key
match (_key, pressed_mod, pressed_key)
  Compare a key object with modifiers and key.
  - _key The key object.
  - pressed_mod The modifiers to compare with.
  - pressed_key The key to compare with.

## Tables

awful.key.ignore_modifiers
  Modifiers to ignore. By default this is initialized as { "Lock", "Mod2" } so the Caps Lock or Num Lock modifier are not taking into account by awesome when pressing keys.

  ### Fields:

  - Lock
  - Mod2

generated by LDoc 1.5.0 Last updated 2025-09-26 21:04:17