Module: awful.menu

A menu for awful

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 () 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 menu_submenu_icon is provided.

Tables

menu_keys Key bindings for menu navigation.


Constructors

awful.menu.clients ([args[, item_args[, filter]]])
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.
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 informations.

    • 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.border_color, theme.border_width, theme.submenu_icon, 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 awful.rules.match_any instead of awful.rules.match,
    -- a menu of clients with different classes could be build.
    
    function terminal_menu ()
      terms = {}
      for i, c in pairs(client.get()) do
        if awful.rules.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 menu_submenu_icon 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 2030-01-01 00:00:00