Module: awful.menu

Create context menus, optionally with sub-menus.

Info:

Constructors

awful.menu.clients (args, item_args, filter) Build a popup menu with running clients and show it.
awful.menu.client_list (args, item_args, filter) Use menu.clients to build and open the client menu if it isn't already open.
awful.menu.entry (parent, args) Default awful.menu.entry constructor.
awful.menu (args, parent) Create a menu popup.

Object methods

:show {[args]} Show a menu.
:hide () Hide a menu popup.
:toggle {[args]} Toggle menu visibility.
:update () Update menu content.
:get_root () -> awful.menu Get the elder parent so for example when you kill it, it will destroy the whole family.
:add (args, index) -> table or nil Add a new menu entry.
:delete (num) Delete menu entry at given position.

Theme variables

beautiful.menu_submenu_icon string or gears.surface The icon used for sub-menus.
beautiful.menu_font string The menu text font.
beautiful.menu_height number The item height.
beautiful.menu_width number The default menu width.
beautiful.menu_border_color number The menu item border color.
beautiful.menu_border_width number The menu item border width.
beautiful.menu_fg_focus color The default focused item foreground (text) color.
beautiful.menu_bg_focus color The default focused item background color.
beautiful.menu_fg_normal color The default foreground (text) color.
beautiful.menu_bg_normal color The default background color.
beautiful.menu_submenu string The default sub-menu indicator if no menu_submenu_icon is provided.

Tables

awful.menu.menu_keys Key bindings for menu navigation.


Constructors

🔗 awful.menu.clients (args, item_args, filter) · 1 permission
Build a popup menu with running clients and show it.

Parameters:

Name Type(s) Description
args Optional table Menu table, see new() for more information.
item_args Optional table Table that will be merged into each item, see new() for more information.
filter Optional func A function taking a client as an argument and returning true or false to indicate whether the client should be included in the menu.

Returns:

    The menu.

Click to display more

Requested actions or permissions:

Class Permission Context Default Description
clientactivatemenu.clientsgrantedWhen clicking on a clients menu element.
🔗 awful.menu.client_list (args, item_args, filter)
Use menu.clients to build and open the client menu if it isn't already open. Close the client menu if it is already open. See awful.menu.clients for more information.

Parameters:

Name Type(s) Description
args Optional table Menu table, see new() for more information.
item_args Optional table Table that will be merged into each item, see new() for more information.
filter Optional func A function taking a client as an argument and returning true or false to indicate whether the client should be included in the menu.

Returns:

    The menu.
🔗 awful.menu.entry (parent, args)
Default awful.menu.entry constructor.

Parameters:

Name Type(s) Description
parent The parent menu (TODO: This is apparently unused)
args The item params

Returns:

    table With 'widget', 'cmd', 'akey' and all the properties the user wants to change
🔗 awful.menu (args, parent)
Create a menu popup.

Parameters:

Name Type(s) Description Default value
args table Table containing the menu information. Not applicable
auto_expand Optional boolean Controls the submenu auto expand behaviour. true
items table Table containing the displayed items. Each element is a table by default (when element 'new' is awful.menu.entry) containing: item name, triggered action (submenu table or function), item icon (optional). Not applicable
theme table Not applicable
theme.fg_normal Optional color beautiful.menu_fg_normal
theme.bg_normal Optional color beautiful.menu_bg_normal
theme.fg_focus Optional color beautiful.menu_fg_focus
theme.bg_focus Optional color beautiful.menu_bg_focus
theme.border Optional color beautiful.menu_border_color
theme.border_width Optional integer beautiful.menu_border_width
theme.height Optional integer beautiful.menu_height
theme.width Optional integer beautiful.menu_width
theme.font Optional string beautiful.menu_font
theme.submenu_icon Optional gears.surface or string beautiful.menu_submenu_icon
theme.submenu Optional string beautiful.menu_submenu
parent Specify the parent menu if we want to open a submenu, this value should never be set by the user. Not applicable

Usage:

    -- The following function builds and shows a menu of clients that match
-- a particular rule.
-- Bound to a key, it can be used to select from dozens of terminals open on
-- several tags.
-- When using ruled.client.match_any instead of ruled.client.match,
-- a menu of clients with different classes could be built.

function terminal_menu ()
  terms = {}
  for i, c in pairs(client.get()) do
    if ruled.client.match(c, {class = "URxvt"}) then
      terms[i] =
        {c.name,
         function()
           c.first_tag:view_only()
           client.focus = c
         end,
         c.icon
        }
    end
  end
  awful.menu(terms):show()
end

Click to display more

Consumed theme variables:

Theme variable Usage
beautiful.menu_fg_normal
beautiful.menu_bg_normal
beautiful.menu_fg_focus
beautiful.menu_bg_focus
beautiful.menu_border_color
beautiful.menu_border_width
beautiful.menu_height
beautiful.menu_width
beautiful.menu_font
beautiful.menu_submenu_icon
beautiful.menu_submenu

Object methods

🔗 :show {[args]}
Show a menu.

Parameters:

Note: This object methods 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 show{}. This is a Lua shortcut syntax equivalent to show({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description Default value
args Optional table The arguments {}
coords Optional table The menu position. A table with x and y as keys and position (in pixels) as values. mouse.coords
🔗 :hide ()
Hide a menu popup.
🔗 :toggle {[args]}
Toggle menu visibility.

Parameters:

Note: This object methods 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 toggle{}. This is a Lua shortcut syntax equivalent to toggle({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description Default value
args table The arguments. Not applicable
coords Optional table The menu position. A table with x and y as keys and position (in pixels) as values. mouse.coords
🔗 :update ()
Update menu content.
🔗 :get_root () -> awful.menu
Get the elder parent so for example when you kill it, it will destroy the whole family.

Returns:

    awful.menu The root menu.
🔗 :add (args, index) -> table or nil
Add a new menu entry. args.* params needed for the menu entry constructor.

Parameters:

Name Type(s) Description Default value
args table The item params. Not applicable
new Optional function The menu entry constructor. awful.menu.entry
theme Optional table The menu entry theme. Undefined
index Optional number The index where the new entry will inserted. Undefined

Returns:

    table or nil The new item.
🔗 :delete (num)
Delete menu entry at given position.

Parameters:

Name Type(s) Description
num table or number The index in the table of the menu entry to be deleted; can be also the menu entry itself.

Theme variables

🔗 beautiful.menu_submenu_icon string or gears.surface
The icon used for sub-menus.
Click to display more

Used by:
🔗 beautiful.menu_font string
The menu text font.

See also:

string

Click to display more

Used by:
🔗 beautiful.menu_height number
The item height.
Click to display more

Used by:
🔗 beautiful.menu_width number
The default menu width.
Click to display more

Used by:
🔗 beautiful.menu_border_color number
The menu item border color.
Click to display more

Used by:
🔗 beautiful.menu_border_width number
The menu item border width.
Click to display more

Used by:
🔗 beautiful.menu_fg_focus color
The default focused item foreground (text) color.

See also:

gears.color This module simplifies the creation of cairo pattern objects. module

Click to display more

Used by:
🔗 beautiful.menu_bg_focus color
The default focused item background color.

See also:

gears.color This module simplifies the creation of cairo pattern objects. module

Click to display more

Used by:
🔗 beautiful.menu_fg_normal color
The default foreground (text) color.

See also:

gears.color This module simplifies the creation of cairo pattern objects. module

Click to display more

Used by:
🔗 beautiful.menu_bg_normal color
The default background color.

See also:

gears.color This module simplifies the creation of cairo pattern objects. module

Click to display more

Used by:
🔗 beautiful.menu_submenu string
The default sub-menu indicator if no menu_submenu_icon is provided.

Type constraints:

Name Type(s) Description Default value
menu_submenu Optional string The sub-menu text. "▶"

See also:

beautiful.menu_submenu_icon The icon used for sub-menus. theme variables

Click to display more

Used by:

Tables

🔗 awful.menu.menu_keys
Key bindings for menu navigation. Keys are: up, down, exec, enter, back, close. Value are table with a list of valid keys for the action, i.e. menu_keys.up = { "j", "k" } will bind 'j' and 'k' key to up action. This is common to all created menu.

Fields:

Name Type(s) Description
up
k
generated by LDoc 1.5.0