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.

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

keygroup The keygroups names.
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 string The key to trigger an event. It can be the character itself of #+keycode.
    • keygroup string The keygroup to trigger an event. This parameter must be used as a replacement for the key parameter. See awful.key.keygroup. (optional)
    • 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.

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.

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

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:

  • NUMROW The number row.
  • ARROWS The directionnal arrows.
  • FKEYS The function keys.
  • NUMPAD The numpad keys.
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 accessed 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