# Module `awful.menu`

### Info:

- Copyright: 2008, 2011 Damien Leone, Julien Danjou, dodo
- Release: v3.5.4
- Author: Damien Leone <damien.leone@gmail.com>,Julien Danjou <julien@danjou.info>,dodo

## Functions

show () | Show a menu.
hide () | Hide a menu popup.
toggle (_menu) | 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.
clients (args, item_args) | Build a popup menu with running clients and shows it.
entry (parent, args) | Default awful.menu.entry constructor
new (args, parent) | Create a menu popup.

## Tables

menu_keys | Key bindings for menu navigation.

## Functions

show ()
  Show a menu.
hide ()
  Hide a menu popup.
toggle (_menu)
  Toggle menu visibility.

  ### Parameters:

  - _menu The menu to show if it's hidden, or to hide if it's shown.
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.new (Default: awful.menu.entry) The menu entry constructor. args.theme (Optional) The menu entry theme. args.* params needed for the menu entry constructor.

  ### Parameters:

  - args The item params
  - index (Optional) the index where the new entry will inserted
clients (args, item_args)
  Build a popup menu with running clients and shows it.

  ### Parameters:

  - args Menu table, see new() function for more informations
  - item_args Table that will be merged into each item, see new() for more informations.

  ### Returns:

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

  ### Parameters:

  - parent The parent menu
  - args the item params

  ### Returns:

  table with 'widget', 'cmd', 'akey' and all the properties the user wants to change
new (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 for example be used to select from
       dozens of terminals open on several tags. With the use of
       <code>match_any</code> instead of <code>match</code>, menu of clients with
       different classes can also be build.

       <p><code>
                           function terminal_menu ()                           <br/>
       &nbsp;                terms = {}                                        <br/>
       &nbsp;                for i, c in pairs(client.get()) do                <br/>
       &nbsp;&nbsp;            if awful.rules.match(c, {class = "URxvt"}) then <br/>
       &nbsp;&nbsp;&nbsp;        terms[i] =                                    <br/>
       &nbsp;&nbsp;&nbsp;          {c.name,                                    <br/>
       &nbsp;&nbsp;&nbsp;           function()                                 <br/>
       &nbsp;&nbsp;&nbsp;&nbsp;       awful.tag.viewonly(c:tags()[1])          <br/>
       &nbsp;&nbsp;&nbsp;&nbsp;       client.focus = c                         <br/>
       &nbsp;&nbsp;&nbsp;           end,                                       <br/>
       &nbsp;&nbsp;&nbsp;           c.icon                                     <br/>
       &nbsp;&nbsp;&nbsp;          }                                           <br/>
       &nbsp;&nbsp;            end                                             <br/>
       &nbsp;                end                                               <br/>
       &nbsp;                awful.menu(terms):show()                          <br/>
                           end                                                 <br/>
      </code></p>

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

generated by LDoc 1.4.2