Module: awful.button

Create easily new buttons objects ignoring certain modifiers.

Info:

Constructors

awful.button (mod, button, press, release) Create a new button to use as binding.
awful.button {[args]} Create a new button to use as binding.

Object properties

modifiers table The table of modifier keys.
button integer The mouse button identifier.
description string The button description.
name string The button name.
group string The button group.
on_press function or nil The callback when this button is pressed.
on_release function or nil The callback when this button is released.

Object methods

:trigger () Execute this mousebinding.

Tables

awful.button.ignore_modifiers Modifiers to ignore.
awful.button.names The mouse buttons names.


Constructors

🔗 awful.button (mod, button, press, release)
Create a new button to use as binding.

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. This argument is (mandatory).
button number The mouse button (it is recommended to use the awful.button.names constants.
press function Callback for when the button is pressed.
release function Callback for when the button is released.

Returns:

    table An awful.button object.
🔗 awful.button {[args]}
Create a new button to use as 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.button{}. This is a Lua shortcut syntax equivalent to awful.button({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description
args table
modifiers table A list of modifier keys. Valid modifiers are: Any, Mod1, Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control. This argument is (mandatory).
button number The mouse button (it is recommended to use the awful.button.names constants.
on_press function Callback for when the button is pressed.
on_release function Callback for when the button is released.

Returns:

    table An awful.button object.

Object properties

🔗 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.
🔗 button integer
The mouse button identifier.

Mouse buttons

Constraints:

Default value : Set in the constructor.
Unit : X11 mouse button codes.
Negative allowed : false
🔗 description string
The button description.

Constraints:

Default value : ""
🔗 name string
The button name.

Constraints:

Default value : ""
🔗 group string
The button group.

Constraints:

Default value : ""
🔗 on_press function or nil
The callback when this button 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 button is released.

Constraints:

Default value : nil
Function prototype:
Parameters: : The function has no parameters
Return : The function returns nothing.

Object methods

🔗 :trigger ()
Execute this mousebinding.

Tables

🔗 awful.button.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.button.names
The mouse buttons names.

It can be used instead of the button ids.

Fields:

Name Type(s) Description
LEFT The left mouse button.
MIDDLE The scrollwheel button.
RIGHT The context menu button.
SCROLL_UP A scroll up increment.
SCROLL_DOWN A scroll down increment.
generated by LDoc 1.5.0