Module: awful.key
Create easily new key objects ignoring certain modifiers.
Info:
- Copyright: 2018 Emmanuel Lepage Vallee
- Author: Julien Danjou <[email protected]>,Emmanuel Lepage Vallee <[email protected]>
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
andControl
. - _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.
- mod
table
A list of modifier keys. Valid modifiers are:
- 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,
Lockand
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.
- key
function
The key to trigger an event. It can be the character
itself of
- args
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#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 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).
- 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
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