If you are using Awesome as your Windows Manager tells about you that you a like lightweight and productivity focused working environments. But when you have to stare at your monitor for 10+ hours a day, some pleasant design doesn’t hurt - especially if it makes your WM even more functional.
A big design part of Awesome are the widgets located in the top (or bottom) bar. They display your current tag, your opened programs, your sys-tray icons, your clock, and so on. The nice thing is, everything can be customized.
However, before we start doing so, we should understand the default configuration we get out of the box. Therefore, I will give you a breakdown of the widget-section in the default
You can find the default configuration file under
/etc/xdg/awesome/rc.lua. It is entirely written in Lua and basically controls every aspect of the desktop environment. If you coded before in any language, you should be able to understand and manipulate the default lua configuration with ease. If you want a little head-start regarding the syntax take a look at the official guide.
Otherwise, let’s get started.
The Wibox Section
If you open the the default config file with your favorite text-editor, you should see that it is divided in separate parts, always starting and ending with a comment like this:
Before we look at the Wibox section, where all the Widgets are defined, take a look at the beginning of the file. There you can find a list of require statements. Particular important are
These lines load the
awful library, which handles basically everything in Awesome and the
Wibox library, which is used to create all visible elements.
Let’s go to the Wibox section starting with the aforementioned comment. In there all the elements of the top wibox (topbar) are created and than put together.
The basic elements are:
- Launcher (little icon, that opens shortcutmenu)
- Promptbox (textlauncher triggered by
- Layoutbox (little icon that shows the current layout)
The config starts by creating the textclockwidget.
As all the other default widgets, the textclock is a predefined widget and can therefore be found in the
awful.widget module. For a complete list, as well as the available configuration options, check the API-reference. For example, for the textclock you can pass a string that defines the format of the output (“%H:%M” -> 10:12).
In general, a widget is created by calling a construction module or function, which returns the widget. Configuration are passed as arguments (inside the brackets) to the function or module.This does not add the widget to the screen, however. We will cover this part later.
After that first widget five empty tables get created:
This seems a little bit odd at first, but they are used later to store multiple instances of the same widget (mytaglist stores multiple taglists and so on). Multiple instances of the same widget are needed in multimonitor setups as each screen gets its own bar. We will see how this is done later.
For the taglist and the tasklist, there is also a set of buttons created. Buttons accociated with widgets can come in quit handy. It is basically a secondary set of hotkeys which are only active if your mouse hovers the respective widget. In this case however, the buttons are not directly assigned to any widget because
mytasklist are not widgets, but empty tables. We have to connect the buttons to the widgets later on for each screen individually.
Creating a list of buttons, always works by using the
awful.util.table.join() method and passing a list of
awful.button instances to it.
awful.button takes three arguments:
- a table of modifier keys (in curly brackets)
- the actual button
- the function which should be activated on button-press
The button number 1 to 5 resemble the mouse buttons (left, middle, right, scroll-up, scroll-down) respectively. To see all the build-in function that can be used - again - take a look at the API-reference.
From top to bottom, the taglist buttons trigger the following actions:
- activate a tag by clicking on it
- move the currently active client to another tag by holding down the mod key and clicking on respective tag
- create a combined few of multiple tags by clicking multiple of them with the right mouse button
- show the currently active client on multiple tags by holding down the modkey and clicking the respective tags with the right mouse button.
- switching to the next or previous tag by scrolling up and down while hovering over taglist
The tasklist buttons seem to be a little bit more complicated. They will change the action, depending on a certain condition.
From top to bottom, the tasklist buttons trigger the following actions:
- toggle minimize when clicking on client in the taskbar
- toggle a menu showing all clients when right clicking the taskbar
- bring the next or previous client in focus by scrolling up and down while hovering over the taskbar
After that, all the dynamics widgets are created once for each screen and than put together into one topbar. To do so, a for-loop is used, which loops over all screens.
Other than tags, screens are not referenced as objects, but by actual numbers.
Now, the empty tables from earlier get filled with one instance of each widget per screen. Most widgets show screen specific information. Therefore they take the screen reference as argument. For the tag and tasklist, it is explicitly specified what they should show:
- awful.widget.taglist.filter.all –> function that returns a list of all tags
- awful.widget.tasklist.filter.currenttags –> function that returns the clients on the current active tag)
The buttons specified earlier are passed as third argument.
A way to attach buttons to a widget after its creation is show for the layoutbox. Using the
:button method, the following actions are attached to the widget:
- switch the next or previous layout using the left and right mouse button
- switch the next or previous layout scrolling up and down while hovering over the widget
The thing missing, is the actual bar itself. An empty bar on top is added by
To add the created widgets to the bar, they are grouped in layouts. The order in which they are added defines there position. A fixed layout is used for the left and right part. This means, that the widgets don’t try to stretch, but rather only take the space they need. If you take a closer look to the
right_layout, you can see, a sys-tray widget is added to the first screen, too.
Because the tasklist in the middle should take up all the remaining space, a align layout is used to bring everything together.
Finally all the widgets are added to the wibox (bar) using the
And we are done with the widget section. Now, that you understand every line of code in there, you should be able to do simple things like removing elements you don’t like or even adding widgets you found in someone’s config files. In the second part I will cover how to create a widget from scratch which displays whatever information you want.