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 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 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.
keygroups The default definitions of keygroups.


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.
  • fkeys: The keys F1 through F12 located at the topmost row of any keyboard, plus F13 through F35 on specialist keyboards.
  • numpad: The number keys on the keypad to the right of the letters and the arrow keys. Not present in every keyboard.
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 description of the function run from a key binding.

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

name string
The key name.

This can be useful when searching for keybindings by keywords.

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

This is used, for example, by awful.hotkeys_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
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 acessed internally by Awesome. Users will usually use key bindings with the property keygroup instead of accessing this table directly.

Fields:

  • numrow
generated by LDoc 1.4.6 Last updated 2030-01-01 00:00:00