Module: awful.key

Create easily new key objects ignoring certain modifiers.

Info:

Constructors

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

Static module functions

awful.key.match (_key, pressed_mod, pressed_key) Compare a key object with modifiers and key.

Object properties

key string The keyboard key used to trigger this keybinding.
keygroup N/A A group of keys.
modifiers table The table of modifier keys.
description string The key description.
name string The key name.
group string The key group.
on_press function The callback when this key is pressed.
on_release function The callback when this key is released.

Object methods

:trigger () Execute this keybinding.

Deprecated functions

awful.key.execute [deprecated] Execute a key combination.

Tables

ignore_modifiers Modifiers to ignore.


Constructors

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

Parameters:

  • 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 function Callback for when the key is released. (optional)
  • data table User data for key, for example {description=“select next tag”, group=“tag”}. (optional)

Returns:

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

Parameters:

  • args
    • key function The key to trigger an event. It can be the character itself of #+keycode (mandatory).
    • modifiers function A list of modifier keys. Valid modifiers are: Any, Mod1, Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control`. This argument is (mandatory).
    • on_press function Callback for when the key is pressed.
    • on_release function Callback for when the key is released.

Static module functions

awful.key.match (_key, pressed_mod, pressed_key)
Compare a key object with modifiers and key.

Parameters:

  • _key The key object.
  • pressed_mod The modifiers to compare with.
  • pressed_key The key to compare with.

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.

keygroup (N/A)

A group of keys.

The valid keygroups are:

  • 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: The Left/Right/Top/Bottom keys usually located right of the spacebar.
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
Mod1Usually called Alt on PCs and Option on Macs
Mod4Also called Super, Windows and Command ⌘
Mod5Also called AltGr or ISO Level 3
ShiftBoth left and right shift keys
ControlAlso called CTRL on some keyboards

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

description (string)
The key description.

This is used, for example, by the awful.hotkey_popup.

name (string)
The key name.

This can be useful when searching for keybindings by keywords.

group (string)
The key group.

This is used, for example, by the awful.hotkey_popup.

on_press (function)
The callback when this key is pressed.
on_release (function)
The callback when this key is released.

Object methods

:trigger ()
Execute this keybinding.

Deprecated functions

awful.key.execute [deprecated]
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:

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

See also:

Tables

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.4.6 Last updated 2030-01-01 00:00:00