# Module: `awful.key`

Create easily new key objects ignoring certain modifiers.

A key object can be used by awful.keyboard and client to define keybindings.

Use awful.key to define a keybinding ---

This example shows how to define a basic key object:

awful.key({ "Mod4", "Shift" }, "a", function () print("The `Mod4` + `Shift` + `a` combo is pressed") end, function () print("The `Mod4` + `Shift` + `a` combo is released") end)

This example shows how to define the same basic key object with the declarative pattern:

awful.key { modifiers = { "Mod4", "Shift" }, key = 'a', on_press = function () print("The `Mod4` + `Shift` + `a` combo is pressed") end, on_release = function () print("The `Mod4` + `Shift` + `a` combo is released") end }

This second example of a key definition uses the numrow keygroup. In this example, we define a key object, that select the tag to show according to the key index from the numrow.

local show_tag_by_numrow_index = awful.key { modifiers = { "Mod4" }, keygroup = awful.key.keygroup.NUMROW, description = "only view tag", group = "tag", on_press = function (index) local screen = awful.screen.focused() local tag = screen.tags[index] if tag then tag:view_only() end end }

### Info:

- Copyright: 2018 Emmanuel Lepage Vallee
- Originally authored by: Julien Danjou <julien@danjou.info>,Emmanuel Lepage Vallee <elv1313@gmail.com>
  (Full contributors list available on our github project)

## Constructors

awful.key (mod, _key, press, release, data) | Create a new key binding (alternate constructor). |
awful.key {[args]} | Create a new key binding. |

## Object properties

key | string | The keyboard key used to trigger this keybinding. |
modifiers | table | The table of modifier keys. |
description | string | The description of the function run from a key binding. |
name | string | The key name. |
group | string | The key group bound to a function in a key binding. |
on_press | function or nil | The callback when this key is pressed. |
on_release | function or nil | The callback when this key is released. |

## Object methods

:trigger () | Execute this keybinding. |
:match (pressed_mod, pressed_key) -> boolean | Compare a key object with modifiers and key. |

## Deprecated functions

awful.key.execute (mod, k) | Execute a key combination. | Deprecated

## Tables

awful.key.keygroup | The keygroups names. |
awful.key.ignore_modifiers | Modifiers to ignore. |
awful.key.keygroups | The default definitions of keygroups. |

## Constructors

🔗 awful.key (mod, _key, press, release, data)
  Create a new key binding (alternate constructor).

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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. It can be the character itself of `#+keycode`.
  press |  | function | Callback for when the key is pressed.
  release | Optional | function | Callback for when the key is released.
  data | Optional | table | User data for key, for example {description="select next tag", group="tag"}.

  ### Returns:

  table A table with one or several key objects.
🔗 awful.key {[args]}
  Create a new key binding.

  ### Parameters:

  Note: This ldoc_skip uses named parameters calling convention. It means you call it with `{}` and omit the parantheses. For example, calling this will all default argument would be `awful.key{}`. This is a Lua shortcut syntax equivalent to `awful.key({})`. `args` is only a placeholder name for the "lone table argument" used in named parameters calls.

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  args |  | table |
  key |  | string | The key to trigger an event. It can be the character itself of `#+keycode`.
  keygroup | Optional | string | The keygroup to trigger an event. This parameter must be used as a replacement for the key parameter. See awful.key.keygroup.
  modifiers |  | table | A list of modifier keys. Valid modifiers are: `Any`, `Mod1`, Mod2`,` Mod3`,` Mod4`,` Mod5`,` Shift`,` Lock`and` Control`.
  on_press |  | function | Callback for when the key is pressed.
  on_release |  | function | Callback for when the key is released.

## Object properties

🔗 key string
  The keyboard key used to trigger this keybinding.

  It can be the key symbol, such as `space`, the character, such as `` or the keycode such as `#65`.

  ### Constraints:

  Default value | : Set in the constructor.

🔗 modifiers table
  The table of modifier keys.

  A modifier, such as `Control` are a predetermined set of keys that can be used to implement keybindings. Note that this list is fix and cannot be extended using random key names, code or characters.

  Common modifiers are:

  Name | Description
  --- | ---
  Mod1 | Usually called Alt on PCs and Option on Macs
  Mod4 | Also called Super, Windows and Command ⌘
  Mod5 | Also called AltGr or ISO Level 3
  Shift | Both left and right shift keys
  Control | Also called CTRL on some keyboards

  Please note that Awesome ignores the status of "Lock" and "Mod2" (Num Lock).

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of modifier names in no specific order.

🔗 description string
  The description of the function run from a key binding.

  This is used, for example, by awful.hotkeys_popup.

  ### Constraints:

  Default value | : `""`

🔗 name string
  The key name.

  This can be useful when searching for keybindings by keywords.

  ### Constraints:

  Default value | : `""`

🔗 group string
  The key group bound to a function in a key binding.

  This is used, for example, by awful.hotkeys_popup.

  ### Constraints:

  Default value | : `""`

🔗 on_press function or nil
  The callback when this key is pressed.

  ### Constraints:

  Default value | : `nil`
  Function prototype:
  Parameters: | : The function has no parameters
  Return | : The function returns nothing.

🔗 on_release function or nil
  The callback when this key is released.

  ### Constraints:

  Default value | : `nil`
  Function prototype:
  Parameters: | : The function has no parameters
  Return | : The function returns nothing.

## Object methods

🔗 :trigger ()
  Execute this keybinding.
🔗 :match (pressed_mod, pressed_key) -> boolean
  Compare a key object with modifiers and key.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  pressed_mod |  | table | The modifiers to compare with.
  pressed_key |  | string | The key to compare with.

  ### Returns:

  boolean If the key and modifier match.

## Deprecated functions

🔗 awful.key.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.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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 | Send fake keyboard or mouse events. (root) | static module functions

## Tables

🔗 awful.key.keygroup
  The keygroups names.

  It can be used instead of keygroup names.

  Values associated to each property of this table are string:

  - **NUMROW** = `"numrow"`: The row above the letters in the US PC-105/PC-104 keyboards and its derivative. This is usually the number 1-9 followed by 0.

  - **ARROWS** = `"arrows"`: The Left/Right/Top/Bottom keys usually located right of the spacebar.

  - **FKEYS** = `"fkeys"`: The keys F1 through F12 located at the topmost row of any keyboard, plus F13 through F35 on specialist keyboards.

  - **NUMPAD** = `"numpad"`: The number keys on the keypad to the right of the letters and the arrow keys. Not present in every keyboard.

  ### Fields:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  NUMROW |  |  | The number row.
  ARROWS |  |  | The directionnal arrows.
  FKEYS |  |  | The function keys.
  NUMPAD |  |  | The numpad keys.

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

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  Lock |  |  |
  Mod2 |  |  |

🔗 awful.key.keygroups
  The default definitions of keygroups.

  A definition for a keygroup (say, **arrows**) can be accessed by indexing this table (e.g. `awful.key.keygroups.arrows`).

  Every definition is given as an array, where every element is another array with the following structure:

  * The first element is a string representing a key, in any format the property key will allow. * The second element is a value. Key bindings created by awful.key and a keygroup are bound to a 1-parameter function, whose parameter is this second element.

  As an example, **arrows** is currently defined thus:

  arrows = { {"Left" , "Left" }, {"Right" , "Right" }, {"Up" , "Up" }, {"Down" , "Down" }, }

  This table is accessed internally by Awesome. Users will usually use key bindings with the property keygroup instead of accessing this table directly.

  ### Fields:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  numrow |  |  |

generated by LDoc 1.5.0