Package:Apache

Awesome (Window Manager)

   Tip

We welcome improvements to this page. To edit this page, Create a Funtoo account. Then log in and then click here to edit this page. See our editing guidelines to becoming a wiki-editing pro.

About Awesome

Awesome is a highly configurable window manager distributed under GPL-2 license. It handles both tiling and floating layouts. You can go into a fine-grained customization to suit your needs with Lua scripting. As a window manager, awesome is an ideal choice if you plan to get rid of your mouse.

Vocabulary

Screen

A physical monitor plugged into your computer.

Client

A window.

Tag

A tag is something like a workspace or a desktop that you may find in other window managers. However, it is slightly more flexible as you can attach a client to multiple tags. Moreover, each screen has its own range of tags.

Layout

A layout is a way to arrange your clients in the current tag (eg. floating, horizontaly tiled, verticaly tiled, focused client full-screen, ...)

Widget

A widget is a box that can contain text, images or more advanced objects. It enables you to add pieces of information in the status bar (at the top-right of each screen) such as the time, the volume level or your battery load. You can also add widgets in the title bar of a client.

USE flags

Use flag	Default	Recommended	Description
dbus	Yes		Enables awesome to receive signals from dbus (eg. to trigger events on hotplug)
doc	No		Includes extra HTML documentation (using doxygen)
gnome	No	If you want to run Awesome in GNOME, yes. Otherwise, probably not.	Enables you to use awesome as gnome's window manager (See. Quickly Setting up Awesome with Gnome)

Installation

Just emerge it:

root # emerge -a awesome

Then you can add this line to your ~/.xinitrc:

   ~/.xinitrc

exec ck-launch-session dbus-launch --sh-syntax --exit-with-session awesome

And run xinit to launch awesome. You can also configure a display manager instead, but this is not covered in this document.

Getting Started

So, you should see a nice awesome background and a top bar which includes your tags on the left (from 1 to 9), the status bar (containing a clock widget) on the right and, on the very left, an icon representing the current layout.

You can switch against tags by typing Mod4 + [1..9] or Mod4 + Left/Right. Where Mod4 is the "Super" key and [1..9] any digit from 1 to 9. Mod4 is the default modifier for awesome key bindings, yet you can configure another one (See #Configuration).

To run a program, hit Mod4 + r. You will be prompted for a command to run (on the top left corner, next to the tags list). Open some clients (3 or 4) and hit Mod4 + Space. This will switch to the next layout. Go ahead and try available layouts (notice the layout icon on the top right corner). You can also switch to the previous layout by hitting Mod4 + Shift + Space. To understand how each layout is arranged, you might want to add some more clients to the current tag. You can also toggle full screen for the current focused client with Mod4 + f.

Here is some other interesting key bindings:

• Mod4 + h/l: Resize clients (this will not work on some layouts)
• Mod4 + Ctrl + r: Restart awesome (useful when you want to test the configuration file you just edited)
• Mod4 + Shift + q: Quit awesome (note that this will not exit your display manager if ever you have one)

There's plenty of other key bindings. We will see them, how to change them and how to create your own in the next section.

Configuration

Awesome user configuration files are located in ~/.config/awesome/. For now, a single file called rc.lua should lie in this directory. It contains the default configuration (including widgets, tags, key bindings, ...). Note that if you don't know Lua, you can still proceed some customization. As far as I'm concerned, I only had to learn Lua basics when I started to create my own widgets.

   Note

The system-wide configuration files are located in /etc/xdg/awesome/.

So, the first thing you might want to do is editing the default terminal (run when you hit Mod4 + Return). You can also change the fallback editor, but awesome uses $EDITOR to find your favorite one. This can be done on these lines:

   ~/.config/awesome/rc.lua (lua source code)

terminal = "xterm"
editor = os.getenv("EDITOR") or "nano"
editor_cmd = terminal .. " -e " .. editor

For strings, .. is the concatenation operator in Lua.

I think the modkey setting is well-documented enough, so next will be the layouts setting:

   ~/.config/awesome/rc.lua (lua source code)

local layouts =
{
    awful.layouts.suit.floating,
    awful.layouts.suit.tile,
    awful.layouts.suit.tile.left,
    awful.layouts.suit.tile.bottom,
    awful.layouts.suit.tile.top,
    awful.layouts.suit.fair,
    awful.layouts.suit.fair.horizontal,
    awful.layouts.suit.spiral,
    awful.layouts.suit.spiral.dwindle,
    awful.layouts.suit.max,
    awful.layouts.suit.max.fullscreen,
    awful.layouts.suit.magnifier
}

These are the default layouts, but you can download some others and create your own. You probably won't do it now, however you might want to change the order. Personally, I don't like to have the floating layout as the default one.

I won't go further about this file, so I would suggest you to go on browsing this file to fetch interesting settings to change. I think one of the most important section you want to check out is "Key bindings". You will see all existing mappings and what they do. As an example, find the following lines at the beginning of the "{{{ Key bindings" section:

   ~/.config/awesome/rc.lua (lua source code)

awful.key({modkey,           },  "j",
        function()
            awful.client.focus.byidx( 1)
            if client.focus then client.focus:raise() end
        end),
    awful.key({modkey,           },  "k",
        function()
            awful.client.focus.byidx(-1)
            if client.focus then client.focus:raise() end
        end),

This enables you to move the focus across the clients in this tag. You may be used to Alt + Tab and Alt + Shift + Tab for that. So why wouldn't you change it to suit what you are used to ?

   ~/.config/awesome/rc.lua (lua source code)

awful.key({"Mod1", "Shift"   },  "Tab", -- Notice the "Mod1" for Alt key instead of modkey (="Mod4")
        function()
            awful.client.focus.byidx( 1)
            if client.focus then client.focus:raise() end
        end),
    awful.key({"Mod1", "Shift"   },  "Tab",
        function()
            awful.client.focus.byidx(-1)
            if client.focus then client.focus:raise() end
        end),