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_normalFallback.
beautiful.fg_normalFallback.
beautiful.fg_minimizeFallback.
beautiful.border_widthFallback.

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:
🔗 beautiful.hotkeys_fg color
Hotkeys widget foreground color.
Click to display more

Used by:
🔗 beautiful.hotkeys_border_width int
Hotkeys widget border width.
Click to display more

Used by:
🔗 beautiful.hotkeys_border_color color
Hotkeys widget border color.
Click to display more

Used by:
🔗 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:
🔗 beautiful.hotkeys_modifiers_fg color
Foreground color used for hotkey modifiers (Ctrl, Alt, Super, etc).
Click to display more

Used by:
🔗 beautiful.hotkeys_label_bg color
Background color used for miscellaneous labels of hotkeys widget.
Click to display more

Used by:
🔗 beautiful.hotkeys_label_fg color
Foreground color used for hotkey groups and other labels.
Click to display more

Used by:
🔗 beautiful.hotkeys_override_label_bgs boolean
Override label background colors instead of cycling through xresources colors.
Click to display more

Used by:
🔗 beautiful.hotkeys_font string or lgi.Pango.FontDescription
Main hotkeys widget font.
Click to display more

Used by:
🔗 beautiful.hotkeys_description_font string or lgi.Pango.FontDescription
Font used for hotkeys' descriptions.
Click to display more

Used by:
🔗 beautiful.hotkeys_group_margin int
Margin between hotkeys groups.
Click to display more

Used by:

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