Reference

# Module `awful.menu`

Creation of menus.

Authors:

Damien Leone <damien.leone@gmail.com>
Julien Danjou <julien@danjou.info>

Copyright© 2008 Damien Leone, Julien Danjou

Release: v3.4.11

## Functions

clients (menu, args, args.keygrabber) | Build a popup menu with running clients and shows it.
hide (menu) | Hide a menu popup.
new (menu, parent, num) | Open a menu popup.
show (menu, args, args.keygrabber, args.coords) | Show a menu.
toggle (menu, args, args.keygrabber, args.coords) | Toggle menu visibility.

## Tables

menu_keys | Key bindings for menu navigation.

## Functions

clients (menu, args, args.keygrabber)
  Build a popup menu with running clients and shows it.

  ### Parameters

  - menu: Menu table, see new() function for more informations
  - args:
  - args.keygrabber: A boolean enabling or not the keyboard navigation.

  ### Return value:

  The menu.
hide (menu)
  Hide a menu popup.

  ### Parameters

  - menu: The menu to hide.
new (menu, parent, num)
  Open a menu popup.

  ### Parameters

  - menu: Table containing the menu informations.
    - Key items: Table containing the displayed items. Each element is a table containing: item name, triggered action, submenu table or function, item icon (optional).
    - Keys [fg|bg]_[focus|normal], border, border_width, submenu_icon, height and width override the default display for your menu, 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.
  - num: Specify the parent's clicked item number 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 for example be used to select from dozens of terminals open on several tags. With the use of `match_any` instead of `match`, menu of clients with different classes can also 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()
  awful.tag.viewonly(c:tags()[1])
  client.focus = c
  end,
  c.icon
  }
  end
  end
  m = awful.menu({items = terms})
  m:show({keygrabber=true})
  return m
  end
  `

show (menu, args, args.keygrabber, args.coords)
  Show a menu.

  ### Parameters

  - menu: The menu to show.
  - args:
  - args.keygrabber: A boolean enabling or not the keyboard navigation.
  - args.coords: Menu position defaulting to mouse.coords()
toggle (menu, args, args.keygrabber, args.coords)
  Toggle menu visibility.

  ### Parameters

  - menu: The menu to show if it's hidden, or to hide if it's shown.
  - args:
  - args.keygrabber: A boolean enabling or not the keyboard navigation.
  - args.coords: Menu position {x,y}

## Tables

menu_keys
  Key bindings for menu navigation. Keys are: up, down, exec, 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.