# Module: `awful.button`

Create easily new buttons objects ignoring certain modifiers.

### Info:

- Copyright: 2018 Emmanuel Lepage Vallee,2009 Julien Danjou
- Originally authored by: Julien Danjou <julien@danjou.info>,Emmanuel Lepage Vallee <elv1313@gmail.com>
  (Full contributors list available on our github project)

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

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of modifier names in no specific order.

🔗 button integer
  The mouse button identifier.

  ![Mouse buttons](../images/mouse.svg)

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