First steps with Awesome window manager

I finally decided to try out Awesome, the window manager all the cool kids are using. Awesome is a tiling window manager, like Wmii or Xmonad, and is very light and stable. In the past I have briefly experimented with Wmii and Xmonad, which I both liked but never found really practical for my needs. So far I’m rather liking Awesome.

My Awesome setup

There is plenty of good information available on Awesome. Shearn89‘s introduction to awesome on the Ubuntuforums, the Awesome Wiki, Calmar‘s files, and the documentation that comes with Awesome have been particularly helpful for me. I don’t intend to replicate here all of the information that those sources contain. The following only mentions (a) a few things I wanted to figure out, but didn’t find any info on, or (b) some things I did with Awesome. What follows is not meant as a guide, but just as a document explaining how I made my first slow steps with Awesome, that might be useful to others new to this window manager. Don’t expect a complete overview of Awesome, nor any revolutionary insights 😉

I installed Awesome 2.3.1, building it from source. All of what follows works with this version. The syntax of the configuration file tends to change with every release, so some of this may not work with earlier (or later) versions of Awesome. Only Awesome 2.0 is in the Hardy Ubuntu repositories; 2.3.1 is available in Intrepid.

Though tiling is neat and sometimes handy, I find it rather inconvenient to work with most of the time. I have a small screen and mainly use applications that are best viewed full-screen (Opera, OpenOffice, Stardict, etc.). I mainly control my window manager from the keyboard, and the tiling window managers offer great keyboard control, but I also look to work with the mouse. This determined the way I configured Awesome: I limit the tiling layout as default to one of my five tags, added window decorations and a root menu, and used some more ‘traditional’ keybindings for Awesome actions (Alt-Tab to switch windows, Ctrl+Alt+arrows to move between tags, etc.).

Awesomerc

The syntax of the ~/.awesomerc file is fairly straightforward, but can easily be intimidating for new users. If you are unsure of the options you can use, have a look at the commented default ~/.awesomerc on the Wiki (or if you know French, see this helpful page).

To give you an idea of what I did with it, I have uploaded my ~/.awesomerc file. The keybindings are largely those I use in other window managers (Ctrl+Alt + left and right arrows to move workspaces/tags; Alt-Tab to switch between windows; Ctrl+Alt+r to restart the window manager; Alt+F2 for gmrun; Alt+F3 for awesome-menu/dmenu; Windows+F1-12 to launch applications; Ctrl + up and down arrows to change the volume levels; Ctrl+Alt+space to play/pause mpd, etc.)

The structure of the configuration file is relatively simple:

<section> [name]
{
<option> = <value>

<section> [name]
{
<option> = <value>
…
}
…
}

Examples of a <section> are mouse, rules, keys, screen, etc. Most sections can have subsections: statusbar, for example, is a subsection of screen, tasklist is a subsection of statusbar, and in my configuration file tasklist has a mouse subsection. You can have more than one instance of some sections: if you use two screens, you can have two screen sections, if you want more than one statusbar you can add more statusbar sections, and if you use widgets, you’ll probably use more than one iconbox or textbox. If you can use more than one section of a kind, you’ll have to specify a name for the section: thus in the default configuration file, screen is called “0”, statusbar is called “mystatusbar”, etc. Some sections, like mouse, key, rules, or layout, can only have one of its kind and therefore do not need a name, though the mouse, key, and styles sections can also be added as subsections to other sections, to govern the style and the mouse and key behaviour of those sections (thus, if you’d want awesome to do xyz when you right click on the tasklist, you would add a mouse section to the tasklist, or if you want the taglist to have a blue background when unfocused, you would add a style section to the taglist section). Examples given below might clarify this more.

<option> and <value> configure the section they are in. They can be colour settings, mouse actions, key actions, position, etc, and are sometimes unique to the section they belong to. Have a look at the default configuration file for some idea of what these can be. All the options as well as all the (sub)sections must be placed within { }. Make sure you keep that structure intact or your configuration file won’t load.

It is easy to make a typo, accidentally delete a bracket, or misplace a particular option into the file. If your configuration file contains errors, Awesome will load the default configuration file when it restarts. You can check for errors in the file before you restart Awesome with the command awesome -k.

Most of the key and mouse bindings should be straightforward: you specify the modifier key(s) and the regular key or mouse button that trigger the actions. If you want to launch applications, use the command spawn with the argument exec application_name. If you want to use Awesome actions, you use whatever action you want to use as the command, possibly with an argument (e.g. command = “tag_setlayout” arg = “+1”, to cycle forwards through the tags), as shown in the keys and mouse section further down in the configuration file). If you want to perform more than one action with a single key (or mouse) press, you’d use the following syntax (as I did with mpc and osdsh):

key { modkey = {"mod keyname"} key = "keyname" command = "spawn" arg = "exec command_one|command_two" }

Autostarting applications

Awesome doesn’t have a session manager. When you login, Awesome is launched and that is it. If you want to autostart applications, you could add them to your ~/.xinitrc, or (if you use a display manager like GDM and regularly switch between window managers) create an autostart script. I modified the Awesome.desktop file (in /usr/share/xsessions/) to load a script that is saved in my home directory, where I can easily add whatever applications I’d like to autostart.

Here is what my /usr/share/xsessions/Awesome.desktop looks like:

[Desktop Entry]
Encoding=UTF-8
Name=Awesome
Comment=Awesome window manager
Exec=/home/urukrama/.awesome/awesome_start.sh
Icon=
Type=Application

The awesome_start.sh script is a simple bash script. Here is what it looks like:

#!/bin/bash
export OOO_FORCE_DESKTOP=gnome
nitrogen --restore &
/home/urukrama/.config/osdsh/osdsh_script_awesome &
#Status bar clock & remind
/home/urukrama/.awesome/awesome-clock.sh &
/home/urukrama/.awesome/awesome-remind.sh &
thunar --daemon &
unclutter -idle 8 -root &
exec /usr/local/bin/awesome

If you decide to use a similar method, make sure both files are executable. There is more info on the awesome-clock and awesome-remind scripts below.

Statusbar and widgets

I love what you can do with Awesome’s statusbar. If you’ve visited desktop threads on the Ubuntu or Arch forums long enough you’ve probably seen plenty of screenshots of Awesome showing statistics for network traffic, battery status, cpu and memory usage, weather, disk usage, mpd, and whatnot. A lot of this is adequately documented on the Awesome Wiki, so there is no need to repeat that information here. (Besides, I don’t find all those stats either useful or aesthetically pleasing, but to each his own).

The statusbar is relatively easy to edit, once you’ve understood the ~/.awesomerc syntax. Awesome comes by default with a single statusbar, position at the top of the screen, but you can easily add more or move that to the bottom, left or right of the screen. If you want to create an additional statusbar, just create an additional statusbar section in the configuration file, and populate it with the widgets you’d like it to display. Make sure you name it differently than the current statusbar (the default is named mystatusbar)!

By default Awesome displays the following widgets on the statusbar: the taglist, layoutinfo, tasklist, and the awesome logo (an iconbox). You can move these around as you please (or remove them, or move them to a different statusbar). The widgets are displayed on the statusbar in the order that they appear in the ~/.awesomerc file.

The widgets will follow the colour and font settings of the main style (defined in the “style” section, at the beginning of the config file), unless you specify different settings for a widget. To do so, add a line like this to the widget’s section:

style { fg = "#B23308" font = "nu 8"}

This will use the fg colour as well as the font specified here, and use the defaults for everything else. If you want to change the colours of a widget that can have both focused and normal colours (like the tasklist), add something like the following:

styles
{
normal { fg = "#ECDDA6" bg = "#000000" border = "#000000" }
focus { fg = "#B23308" bg = "#000000" border = "#000000" }
}

I wanted to add only two widgets to the statusbar: a clock and a widget that displays my reminders (using the application remind). Here is how I did it.

Clock and calendar

For the clock, I modified a script found on the Wiki, which I saved as ~/.awesome/awesome-clock (and made executable with chmod +x). Whatever script you use, and wherever you save it, make sure it is always called “awesome-name_of_the_widget_in_awesomerc“. I added the following lines to the very end of the statusbar section of my ~/.awesomerc (to have the clock display in the far right of the statusbar):

textbox clock
{
align = "right"
style { fg = "#B23308" bg = "#000000" }
}

With this in Awesome’s configuration file, whenever I load the script ~/.awesome/awesome-clock, the clock will load in the taskbar, at the position the above section occurs in the configuration file. To have it load whenever I log into awesome, I added the script to my Awesome autostart script (~/.awesome/awesome-clock &).

But I wanted more than this. Wouldn’t it be neat to have a calendar built into this clock widget? Sure, and luckily there is dzen2, which I used to get a script to launch a calendar. I added the following two lines to the clock widget in my ~/.awesomerc (make sure you keep the { } structure intact!):

textbox clock
{
align = "right"
style { fg = "#B23308" bg = "#000000" }

mouse {
button = “1”
command = “spawn”
arg = “exec /home/urukrama/.scripts/dzen_calendar_awesome” }
mouse {
button = “3”
command = “spawn”
arg = “exec osmo” }
}

This launches a dzen calendar script when I left click on the clock, and Osmo when I right click on it.

My calendar script

You can add such lines (with or without a key modifier such as Shift, Mod4, etc.) to any of the widgets (you’ll see that the tasklist and the layoutinfo widgets already have some).

Remind

I use remind to show today’s events of my religious calendar, and I wanted to show those reminders in the statusbar, next to the clock. To do so, I modified the above script to display today’s reminder, saved it as ~/.awesome/awesome-remind, made it executable, created a textbox widget called “remind” before my clock widget, and added the appropriate line to my autostart script.

I also wanted to see a list of upcoming reminders when I right click on today’s reminders, and created a script with dzen2 to accomplish this. This script shows the reminders for the coming four weeks, with today’s reminder in red (this page explaining how sed works was extremely useful to get this done!). Only ten lines are shown, but you can scroll up and down in the list to view the other lines. Right clicking on the list makes it disappear.

My reminders

This is what the appropriate section in my ~/.awesomerc looks like:

textbox remind {
align = "right"
style { fg = "#ECDDA6" bg = "#000000" }
mouse
{ button = "1"
command = "spawn"
arg = "exec /home/urukrama/.scripts/dzen_remind_awesome" }
}

Layouts and Tags

Awesome has a lot of different layouts: tiled, left tiled, top tiled, bottom tiled, spiral, floating, maximized and dwindle. I don’t have any use for many of these (I only use tiled, maximized, and float), and having them all can be rather annoying if you want to quickly switch between two layouts. If you don’t want to use a particular layout, you can remove them or comment them out from the “layout” section. Only the layouts that are specified in this section will be used by awesome. You can cycle through these layouts, either by clicking the layoutinfo widget in the statusbar or by pressing Mod4+space; the order in which you cycle through them is the order specified in this section of your ~/.awesomerc.

Tags are like virtual workspaces, but better. Each tag can be set with a default layout, in the “tag” section of your ~/.awesomerc, but their uses are greater than that. Within a tag all the windows that have that tag are shown. The great part of it is that you can assign more than one tag to an application or window, so that it shows up in both tags. If you want an application to appear in more than one tag, you have to set up a rule (in the rules section). This is what it would look like if you want to thunar to show on both tag ‘one’ and ‘five’:

rule { name = "thunar" tags = "one|five" }

I’ve also configured Awesome such that if I middle click on a tag name, the currently selected window is moved to that tag. Here is the relevant portion of my ~/.awesomerc (in the taglist section of the statusbar section):

mouse { button = "3" command = "tag_toggleview" }

If you want to view the windows of all tags in a single tag, use the action tag_view (assigned to Mod4+Print in my configuration). The action tag_toggleview works similarly, but doesn’t show the applications that are on the current tag. You can undo both actions by clicking on a tag name and triggering the action you have configured to that mouse action (thus, in my setup, middle clicking will move the active window to that tag; left clicking will just move to that tag; etc.)

To have an open window appear on all tags, use either the client_tag action, or the client_toggletag action if you want to be able to easily undo it.

You can easily create new tags whenever you want, with the tag_create action. Thus the following action creates a new tag called “six”:

key { modkey = {"Mod4", "Control"} key = "F6" command = "tag_create" arg = "six" }

Root menu

I’ve been using Openbox for way too long to be comfortable now in any window manager without a root menu that pops up when I right click on the desktop. 🙂

If you’d like a right-click root menu in Awesome, like you have in Openbox and Fluxbox, you can use 9menu, a component of 9wm that can be easily used with other window managers. To use it, you’ll need to create a menu file (here is mine), and launch it with the following command:

9menu -popup -bg "#000000" -fg "#F2EDD7" -font "-*-nu-*-*-*-*-*-*-*-*-*-*-*-*" -teleport -file /path/to/your/custom/9menurc

Change the bg and fg colours as well as the font to whatever you prefer. For more options with 9menu, check its man page.

To make things easier, create a script to launch this: create an empty file called 9menu_script (I keep it in ~/.awesome), add #!/bin/bash at the top of that file followed by the above command, save it, and make the script executable (chmod +x /path/to/9menu_script). (The advantage of using a script, rather than adding the command directly into your ~/.awesomerc, is that if you have multiple instances of it in your ~/.awesomerc, you will only have to change its settings once when you want to change its colours and/or font to match a different theme.)

To launch 9menu when you right click on the desktop, find the following in the mouse section of your ~/.awesomerc:

root { button = "3" command = "spawn" arg = "exec xterm" }

This launches an xterm when you right click on the desktop. Change that to this:

root { button = "3" command = "spawn" arg = "exec /path/to/your/9menu_script" }

9menu

If you’d also like to have the menu bound to Alt+F1, as some window managers have it, add the following to the keys section:

key { modkey = {"Mod1"} key = "F1" command = "spawn" arg = "exec /path/to/your/9menu_script" }

If you’d like the menu to launch from the Awesome icon on the statusbar, edit the “iconbox logo” section in the default configuration file as follows:

iconbox logo
{
image = "/usr/local/share/awesome/icons/awesome16.png"
mouse
{ button = "1"
command = "spawn"
arg = "exec /path/to/your/9menu_script" }
}

(The default launches Awesome’s man page: xterm -e man awesome).

You could also use dzen2 to create a root or panel menu (see here and here). It is a lot harder to accomplish this with dzen2 than it is with 9menu, but you can do a lot more with it: submenus, more colours, icons, etc. I tried it and had some success, but gave up as I didn’t think it worth the trouble.

Window decorations

By default, Awesome does not use window decorations, but you can easily add those. In the screen section, add something like the following:

titlebar
{
position = "top"
text_align = "left"
styles
{
normal { fg = "#ECDDA6" bg = "#000000" border = "#000000" }
focus { fg = "#B23308" bg = "#000000" border = "#000000" }
}
height = "13"
}

The position of the titlebar can be top, bottom, left or right.

If you want to disable the titlebar for some applications, or have some applications with the titlebar in a different position, you can specify that in the “rules” section: specify the application, and use the following option titlebar { position = off } (you can replace “off” with any position you’d like).

Awesome does not support buttons on the titlebar, like echinus does, but having the titlebar for some applications is handy when you are in floating mode, as it allows you to easily move windows around with the mouse. In the mouse section you can tell Awesome what to do when you press a particular mouse button on the titlebar. I make it close the window when I middle click on it, as well as toggle maximize fully, vertically and horizontally when I press Mod4 and left, middle or right click on it. Note that when you maximize a window with togglemax, it looses its window decorations until you unmaximize it again.

Awesome-menu

And finally, there is Awesome’s menu. It resembles dmenu, though it isn’t as refined: it doesn’t automatically select the first match of what you type, and doesn’t search for matches within a word (‘unar’ does not bring up ‘thunar’ for example, as it does in dmenu). Nevertheless, it is handy, and the Wiki explains some of its potential.

I initially used it, but have now gone back to the much loved dmenu.