Module: awful.menu

A menu for awful.

Info:

  • Copyright: 2008, 2011 Damien Leone, Julien Danjou, dodo
  • Originally authored by: Damien Leone <damien.leone@gmail.com>,Julien Danjou <julien@danjou.info>,dodo
    (Full contributors list available on our github project)

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 () Get the elder parent so for example when you kill it, it will destroy the whole family.
:add (args, index) 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 menusubmenuicon is provided.

Tables

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:

  • args table Menu table, see new() for more information. (optional)
  • item_args table Table that will be merged into each item, see new() for more information. (optional)
  • filter 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. (optional)

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:

  • args table Menu table, see new() for more information. (optional)
  • item_args table Table that will be merged into each item, see new() for more information. (optional)
  • filter 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. (optional)

Returns:

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

Parameters:

  • 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:

  • args

    Table containing the menu information.

    • Key items: 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).
    • Keys theme.[fg|bg][focus|normal], theme.bordercolor, theme.borderwidth, theme.submenuicon, theme.height and theme.width override the default display for your menu and/or of your menu entry, each of them are optional.
    • Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false.
  • parent Specify the parent menu if we want to open a submenu, this value should never be set by the user.

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 build.

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

Object methods

:show {[args]}
Show a menu.

Parameters:

  • args The arguments
    • coords Menu position defaulting to mouse.coords()
:hide ()
Hide a menu popup.
:toggle {[args]}
Toggle menu visibility.

Parameters:

  • args The arguments
    • coords Menu position {x,y}
:update ()
Update menu content.
:get_root ()
Get the elder parent so for example when you kill it, it will destroy the whole family.
:add (args, index)
Add a new menu entry. args.* params needed for the menu entry constructor.

Parameters:

  • args The item params
    • new (Default: awful.menu.entry) The menu entry constructor.
    • theme The menu entry theme. (optional)
  • index The index where the new entry will inserted. (optional)
:delete (num)
Delete menu entry at given position.

Parameters:

  • num The position 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.
beautiful.menu_font string
The menu text font.

See also:

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.

See also:

beautiful.menu_bg_focus color
The default focused item background color.

See also:

beautiful.menu_fg_normal color
The default foreground (text) color.

See also:

beautiful.menu_bg_normal color
The default background color.

See also:

beautiful.menu_submenu string
The default sub-menu indicator if no menusubmenuicon is provided.

Type constraints:

  • menu_submenu string The sub-menu text. (default "▶")

See also:

Tables

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:

  • up
  • k
generated by LDoc 1.4.6 Last updated 2021-11-13 00:35:50