# Module: `awful.menu`

Create context menus, optionally with sub-menus.

### 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 () -> 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
  --- | --- | --- | --- | ---
  client | activate | menu.clients | granted | When 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:

  - awful.menu Create a menu popup.
  - awful.menu Create a menu popup.
🔗 beautiful.menu_font string
  The menu text font.

  ### See also:

  string |  |

  Click to display more

  ### Used by:

  - awful.menu Create a menu popup.
  - awful.menu Create a menu popup.
🔗 beautiful.menu_height number
  The item height.
  Click to display more

  ### Used by:

  - awful.menu Create a menu popup.
  - awful.menu Create a menu popup.
🔗 beautiful.menu_width number
  The default menu width.
  Click to display more

  ### Used by:

  - awful.menu Create a menu popup.
  - awful.menu Create a menu popup.
🔗 beautiful.menu_border_color number
  The menu item border color.
  Click to display more

  ### Used by:

  - awful.menu Create a menu popup.
  - awful.menu Create a menu popup.
🔗 beautiful.menu_border_width number
  The menu item border width.
  Click to display more

  ### Used by:

  - awful.menu Create a menu popup.
  - awful.menu Create a menu popup.
🔗 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:

  - awful.menu Create a menu popup.
  - awful.menu Create a menu popup.
🔗 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:

  - awful.menu Create a menu popup.
  - awful.menu Create a menu popup.
🔗 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:

  - awful.menu Create a menu popup.
  - awful.menu Create a menu popup.
🔗 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:

  - awful.menu Create a menu popup.
  - awful.menu Create a menu popup.
🔗 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:

  - awful.menu Create a menu popup.
  - awful.menu Create a menu popup.

## 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