# Module: `awful.hotkeys_popup.widget`

Popup widget which shows current hotkeys and their descriptions.

It's easy to add hotkeys for your favorite application. Below is how to add hotkeys for firefox to the previously created `hotkeys_popup` in rc.lua.

-- Create the rule that we will use to match for the application. local fire_rule = { class = { "firefox", "Firefox" } } for group_name, group_data in pairs({ ["Firefox: tabs"] = { color = "#009F00", rule_any = fire_rule } }) do hotkeys_popup.add_group_rules(group_name, group_data) end

-- Table with all of our hotkeys local firefox_keys = {

["Firefox: tabs"] = {{ modifiers = { "Mod1" }, keys = { ["1..9"] = "go to tab" } }, { modifiers = { "Ctrl" }, keys = { t = "new tab", w = 'close tab', ['Tab'] = "next tab" } }, { modifiers = { "Ctrl", "Shift" }, keys = { ['Tab'] = "previous tab" } }} }

hotkeys_popup.add_hotkeys(firefox_keys)

Example of having different types of hotkey popups:

awful.keyboard.append_global_keybindings({ awful.key({modkey}, "/", function() hotkeys_popup.show_help() end, nil, { description = "show help (all)", group="HELP" }), awful.key({"Shift", modkey}, "/", function() hotkeys_popup.show_help(nil, nil, {show_awesome_keys=false}) end, nil, { description = "show help for current app", group="HELP" }), awful.key({altkey, modkey}, "/", function() hotkeys_popup.show_help({}, nil, {show_awesome_keys=true}) end, nil, { description = "show help for awesome only", group="HELP" }) -- (more hotkeys go here) })

### Info:

- Copyright: 2014-2015 Yauheni Kirylau
- Originally authored by: Yauheni Kirylau <yawghen@gmail.com>
  (Full contributors list available on our github project)

## Constructors

awful.widget.hotkeys_popup.widget.new {[args]} | Create an instance of widget with hotkeys help. |

## Static module functions

awful.hotkeys_popup.widget.show_help (c, s, args) -> awful.keygrabber | Show popup with hotkeys help (default widget instance will be used). |
awful.hotkeys_popup.widget.add_hotkeys (hotkeys) | Add hotkey descriptions for third-party applications (default widget instance will be used). |
awful.hotkeys_popup.widget.add_group_rules (group, data) | Add hotkey group rules for third-party applications (default widget instance will be used). |

## Object methods

:show_help (c, s, show_args) -> awful.keygrabber | Show popup with hotkeys help. |
:add_hotkeys (hotkeys) | Add hotkey descriptions for third-party applications. |
:add_group_rules (group, data) | Add hotkey group rules for third-party applications. |

## Theme variables

beautiful.hotkeys_bg | color | Hotkeys widget background color. |
beautiful.hotkeys_fg | color | Hotkeys widget foreground color. |
beautiful.hotkeys_border_width | int | Hotkeys widget border width. |
beautiful.hotkeys_border_color | color | Hotkeys widget border color. |
beautiful.hotkeys_shape | gears.shape | Hotkeys widget shape. |
beautiful.hotkeys_modifiers_fg | color | Foreground color used for hotkey modifiers (Ctrl, Alt, Super, etc). |
beautiful.hotkeys_label_bg | color | Background color used for miscellaneous labels of hotkeys widget. |
beautiful.hotkeys_label_fg | color | Foreground color used for hotkey groups and other labels. |
beautiful.hotkeys_override_label_bgs | boolean | Override label background colors instead of cycling through xresources colors. |
beautiful.hotkeys_font | string or lgi.Pango.FontDescription | Main hotkeys widget font. |
beautiful.hotkeys_description_font | string or lgi.Pango.FontDescription | Font used for hotkeys' descriptions. |
beautiful.hotkeys_group_margin | int | Margin between hotkeys groups. |

## Tables

widget.modifier_sort_order | Sort order for the hotkey modifiers |
widget.labels | Labels used for displaying human-readable keynames. |

## Fields

awful.hotkeys_popup.widget.widget.hide_without_description | boolean | Don't show hotkeys without descriptions. |
awful.hotkeys_popup.widget.widget.merge_duplicates | boolean | Merge hotkey records into one if they have the same modifiers and description. |

## Constructors

🔗 awful.widget.hotkeys_popup.widget.new {[args]} · 16 theme variables
  Create an instance of widget with hotkeys help.

  ### Parameters:

  Note: This constructors 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.widget.hotkeys_popup.widget.new{}`. This is a Lua shortcut syntax equivalent to `awful.widget.hotkeys_popup.widget.new({})`. `args` is only a placeholder name for the "lone table argument" used in named parameters calls.

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  args | Optional | table | Configuration options for the widget.
  hide_without_description | Optional | boolean | Don't show hotkeys without descriptions.
  merge_duplicates | Optional | boolean | Merge hotkey records into one if they have the same modifiers and description. Records with five keys or more will abbreviate them.
  width | Optional | int | Widget width.
  height | Optional | int | Widget height.
  bg | Optional | color | Widget background color.
  fg | Optional | color | Widget foreground color.
  border_width | Optional | int | Border width.
  border_color | Optional | color | Border color.
  shape | Optional | gears.shape | Widget shape.
  font | Optional | string or lgi.Pango.FontDescription | Main widget font.
  description_font | Optional | string or lgi.Pango.FontDescription | Font used for hotkeys' descriptions.
  modifiers_fg | Optional | color | Foreground color used for hotkey modifiers (Ctrl, Alt, Super, etc).
  label_bg | Optional | color | Background color used for miscellaneous labels.
  label_fg | Optional | color | Foreground color used for group and other labels.
  override_label_bgs | Optional | boolean | Override label background colors instead of cycling through xresources colors.
  group_margin | Optional | int | Margin between hotkeys groups.
  labels | Optional | table | Labels used for displaying human-readable keynames.
  group_rules | Optional | table | Rules for showing 3rd-party hotkeys. @see `awful.hotkeys_popup.keys.vim`.

  ### Returns:

  Widget instance.
  Click to display more

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.hotkeys_fg |
  beautiful.hotkeys_bg |
  beautiful.hotkeys_border_width |
  beautiful.hotkeys_border_color |
  beautiful.hotkeys_shape |
  beautiful.hotkeys_modifiers_fg |
  beautiful.hotkeys_label_bg |
  beautiful.hotkeys_label_fg |
  beautiful.hotkeys_override_label_bgs |
  beautiful.hotkeys_font |
  beautiful.hotkeys_description_font |
  beautiful.hotkeys_group_margin |
  beautiful.bg_normal | Fallback.
  beautiful.fg_normal | Fallback.
  beautiful.fg_minimize | Fallback.
  `beautiful.border_width` | Fallback.

## Static module functions

🔗 awful.hotkeys_popup.widget.show_help (c, s, args) -> awful.keygrabber
  Show popup with hotkeys help (default widget instance will be used).

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  c | Optional | client | Client. | Undefined
  s | Optional | screen | Screen. | Undefined
  args | Optional | table | Additional arguments. | Undefined
  show_awesome_keys | Optional | boolean | Show AwesomeWM hotkeys. When set to `false` only app-specific hotkeys will be shown. | `true`

  ### Returns:

  awful.keygrabber The keybrabber used to detect when the key is released.
🔗 awful.hotkeys_popup.widget.add_hotkeys (hotkeys)
  Add hotkey descriptions for third-party applications (default widget instance will be used).

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  hotkeys |  | table | Table with bindings, see `awful.hotkeys_popup.key.vim` as an example.

🔗 awful.hotkeys_popup.widget.add_group_rules (group, data)
  Add hotkey group rules for third-party applications (default widget instance will be used).

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  group |  | string | Rule group name,
  data |  | table | Rule data for the group see `awful.hotkeys_popup.key.vim` as an example.

## Object methods

🔗 :show_help (c, s, show_args) -> awful.keygrabber
  Show popup with hotkeys help.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  c | Optional | client | Client. | `client.focus`
  s | Optional | screen | Screen. | `c.screen`
  show_args | Optional | table | Additional arguments. | `{}`
  show_awesome_keys | Optional | boolean | Show AwesomeWM hotkeys. When set to `false` only app-specific hotkeys will be shown. | `true`

  ### Returns:

  awful.keygrabber The keybrabber used to detect when the key is released.
🔗 :add_hotkeys (hotkeys)
  Add hotkey descriptions for third-party applications.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  hotkeys |  | table | Table with bindings, see `awful.hotkeys_popup.key.vim` as an example.

🔗 :add_group_rules (group, data)
  Add hotkey group rules for third-party applications.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  group |  | string | Hotkeys group name,
  data |  | table | Rule data for the group see `awful.hotkeys_popup.key.vim` as an example.

## Theme variables

🔗 beautiful.hotkeys_bg color
  Hotkeys widget background color.
  Click to display more

  ### Used by:

  - awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
🔗 beautiful.hotkeys_fg color
  Hotkeys widget foreground color.
  Click to display more

  ### Used by:

  - awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
🔗 beautiful.hotkeys_border_width int
  Hotkeys widget border width.
  Click to display more

  ### Used by:

  - awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
🔗 beautiful.hotkeys_border_color color
  Hotkeys widget border color.
  Click to display more

  ### Used by:

  - awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
🔗 beautiful.hotkeys_shape gears.shape
  Hotkeys widget shape.

  ### See also:

  gears.shape | Module dedicated to gather common shape painters. | module

  Click to display more

  ### Used by:

  - awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
🔗 beautiful.hotkeys_modifiers_fg color
  Foreground color used for hotkey modifiers (Ctrl, Alt, Super, etc).
  Click to display more

  ### Used by:

  - awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
🔗 beautiful.hotkeys_label_bg color
  Background color used for miscellaneous labels of hotkeys widget.
  Click to display more

  ### Used by:

  - awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
🔗 beautiful.hotkeys_label_fg color
  Foreground color used for hotkey groups and other labels.
  Click to display more

  ### Used by:

  - awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
🔗 beautiful.hotkeys_override_label_bgs boolean
  Override label background colors instead of cycling through xresources colors.
  Click to display more

  ### Used by:

  - awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
🔗 beautiful.hotkeys_font string or lgi.Pango.FontDescription
  Main hotkeys widget font.
  Click to display more

  ### Used by:

  - awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
🔗 beautiful.hotkeys_description_font string or lgi.Pango.FontDescription
  Font used for hotkeys' descriptions.
  Click to display more

  ### Used by:

  - awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
🔗 beautiful.hotkeys_group_margin int
  Margin between hotkeys groups.
  Click to display more

  ### Used by:

  - awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.

## Tables

🔗 widget.modifier_sort_order
  Sort order for the hotkey modifiers

  ### Fields:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  Alt |  | int | Alt key priority
  Ctrl |  | int | Ctrl key priority
  Shift |  | int | Shift key priority
  Super |  | int | Super key priority

  ### Usage:

      To use change the sorting order for hotkey modifiers, add the following line
      to your rc.lua file, after require("awful.hotkeys_popup"):

          hotkeys_popup.widget.modifier_sort_order = {
              Shift = 1,
              Ctrl  = 2,
              Super = 3,
              Alt   = 4,
          }

      Setting 2 or more modifiers to the same number will cause their relative
      sorting order to be undefined.

🔗 widget.labels
  Labels used for displaying human-readable keynames.

  ### Fields:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  Control | Optional | string |  | `"Ctrl"`
  Mod1 | Optional | string |  | `"Alt"`
  ISO_Level3_Shift | Optional | string |  | `"Alt Gr"`
  Mod4 | Optional | string |  | `"Super"`
  Insert | Optional | string |  | `"Ins"`
  Delete | Optional | string |  | `"Del"`
  Next | Optional | string |  | `"PgDn"`
  Prior | Optional | string |  | `"PgUp"`
  Left | Optional | string |  | `"←"`
  Up | Optional | string |  | `"↑"`
  Right | Optional | string |  | `"→"`
  Down | Optional | string |  | `"↓"`
  KP_End | Optional | string |  | `"Num1"`
  KP_Down | Optional | string |  | `"Num2"`
  KP_Next | Optional | string |  | `"Num3"`
  KP_Left | Optional | string |  | `"Num4"`
  KP_Begin | Optional | string |  | `"Num5"`
  KP_Right | Optional | string |  | `"Num6"`
  KP_Home | Optional | string |  | `"Num7"`
  KP_Up | Optional | string |  | `"Num8"`
  KP_Prior | Optional | string |  | `"Num9"`
  KP_Insert | Optional | string |  | `"Num0"`
  KP_Delete | Optional | string |  | `"Num."`
  KP_Divide | Optional | string |  | `"Num/"`
  KP_Multiply | Optional | string |  | `"Num*"`
  KP_Subtract | Optional | string |  | `"Num-"`
  KP_Add | Optional | string |  | `"Num+"`
  KP_Enter | Optional | string |  | `"NumEnter"`
  Escape | Optional | string |  | `"Esc"`
  Tab | Optional | string |  | `"Tab"`
  space | Optional | string |  | `"Space"`
  Return | Optional | string |  | `"Enter"`
  dead_acute | Optional | string |  | `"´"`
  dead_circumflex | Optional | string |  | `"^"`
  dead_grave | Optional | string |  | `"`"`
  XF86MonBrightnessUp | Optional | string |  | `"🔆+"`
  XF86MonBrightnessDown | Optional | string |  | `"🔅-"`
  XF86AudioRaiseVolume | Optional | string |  | `"🕩+"`
  XF86AudioLowerVolume | Optional | string |  | `"🕩-"`
  XF86AudioMute | Optional | string |  | `"🔇"`
  XF86AudioPlay | Optional | string |  | `"⏯"`
  XF86AudioPrev | Optional | string |  | `"⏮"`
  XF86AudioNext | Optional | string |  | `"⏭"`
  XF86AudioStop | Optional | string |  | `"⏹"`

## Fields

🔗 awful.hotkeys_popup.widget.widget.hide_without_description boolean
  Don't show hotkeys without descriptions.
🔗 awful.hotkeys_popup.widget.widget.merge_duplicates boolean
  Merge hotkey records into one if they have the same modifiers and description. Records with five or more keys will abbreviate them.

  This property only affects hotkey records added via awful.key keybindings. Cheatsheets for external programs are static and will present merged records regardless of the value of this property.

generated by LDoc 1.5.0