This wiki will shut down!

Please note that this wiki will be made read-only and eventually be taken offline.

A replacement is being discussed at We'd be happy to have more input for that discussion and volunteers who help us migrate the content of this wiki to its replacement.

From awesome
Jump to: navigation, search is an awful module to allow creation of popup menus with an arborescence of sub-menus.

This module is designed for awesome 3

Setting up[edit]

The module is automatically loaded at startup, as long as you have the following line on top of your config file:


Basically you feed your menu with a table containing another table for each item of your menu. The first element of the item table is the label, then the triggered action which can be a string or a menu table, setting a menu table as an item will result as a sub-menu. The third element is an optional path to an icon.

There is an example in the default awesomerc.lua:

myawesomemenu = {
   { "manual", terminal .. " -e man awesome" },
   { "edit config", terminal .. " -e nano ~/.config/awesome/rc.lua" },
   { "restart", awesome.restart },
   { "quit", awesome.quit }

mymainmenu ={ items = { { "awesome", myawesomemenu, beautiful.awesome_icon },
                                        { "open terminal", terminal }

Since awesome 3.4.x labels support access keys configuration: you have to prepend an & to the desired key eg.

{ "&firefox", "firefox", awful.util.getdir("config") .. "/firefox.png" },

Will allow you to press Mod4 + W (default key binding) to bring the menu up and then "f" to launch firefox.

We first create a table myawesomemenu, we will use it as a sub-menu, then we create a mymainmenu with two items of which one is our myawesomemenu table, this is how we get sub-menus working.

Now we want to display our menu, we have two ways.

Using a launcher widget:

mylauncher = awful.widget.launcher({ image = image(beautiful.awesome_icon),
                                     menu = mymainmenu

Using a binding:

    button({ }, 3, function () mymainmenu:toggle() end),
    button({ }, 4, awful.tag.viewnext),
    button({ }, 5, awful.tag.viewprev)

Note that the first argument of the function is a table allowing the following elements:

  • auto_expand: a boolean controlling the auto expand behaviour which is true by default;
  • [fg|bg]_[normal|focus], border_[color|width], submenu_icon, height, width: custom theme overriding beautiful, all these elements are optional;
  • items: the items table as seen above;

Menus behaviour[edit]

  • A left click triggers the action associated with the item or toggle the menu opened/closed state if menu_toggle parameter is set to true.
  • A right click destroys the menu and all its childs, meaning that if you want to destroy a sub-menu that opened another sub-menu it will destroy the two sub-menus but not the parent.


  • You can use pango format to display labels, meaning that you can bold, underline or decorate your label the way you want.
  • The triggered action associated to an item can be nil, meaning that if you click that item nothing will happen, the menu will not be destroyed, this can be used to create separators, categories or whatever.
  • You can theme your menus using Beautiful.
  • For Debian users, you can put following scripts under ~/.menu-methods then run update-menus to generate Debian menus
# this file has to be executable
# put under ~/.menu-methods
# will run by update-menus
# default generate ~/.config/awesome/menu.lua
# you need to require("menu") to use menu.debian_menu


!include menu.h

outputencoding= "UTF-8";

function q($s) = "\"" esc($s,"\\\"") "\"";
function s($s) = replacewith(replacewith($s,"/","_"), " ", "_");
function findicon($filename)= 
       ifelsefile($filename, q($filename),
        iffile("/usr/share/pixmaps/" $filename,
                   q("/usr/share/pixmaps/" $filename)));
function x11menu()= "\t{"q(title())","q($command) ifnempty($icon, ","findicon($icon))"},\n";
function textmenu()= "\t{"q(title())", \"x-terminal-emulator -e \".."q($command) ifnempty($icon, ","findicon($icon))"},\n";

    x11= x11menu();
    text= textmenu();

startmenu=      s($section)" = {\n";
endmenu=        "}\n";
submenutitle=   "\t{"q(title())","s($section)"},\n";
genmenu=        "menu.lua";
rootsection=    "debian_menu";
userprefix=     "/.config/awesome/";
preoutput=      "-- automatically generated file. Do not edit (see /usr/share/doc/menu/html)\n\nmodule(\"menu\")\n\n";