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:

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
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).

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.4.6