Awesome 3.4 to 3.5

From awesome
Jump to: navigation, search

This page summarizes changes which Awesome has undergone between 3.4 and 3.5. You should use it as a guideline for updating your widgets and configuration files.

If you want to test your config without restarting (and potentially breaking) your current running instance of awesome, you can use Xephyr.

New Runtime-Only Dependency[edit]

Awesome 3.5 uses LGI for accessing some libraries. This package provides Lua GObject Introspection, which is used for accessing the Cairo and Pango libraries.

However, this a not a build dependency, which means that building and installing Awesome may still succeed even if you don't have LGI installed. This makes it easy to miss this dependency.

If you are unsure whether you have LGI and the needed introspection files, you can run the following command:

$ lua -e 'lgi = require("lgi") print(lgi.cairo, lgi.Pango, lgi.PangoCairo)'
table: 0xe74160    table: 0xf40830    table: 0xf168e0

The above is what this looks like if everything goes well. However, if you don't have lgi, you will see an error message like this:

$ lua -e 'lgi = require("lgi") print(lgi.cairo, lgi.Pango, lgi.PangoCairo)'
lua: (command line):1: module 'lgi' not found:
[long error message here]

Please note that you need LGI 0.6.1 or newer, because older versions don't have the necessary Cairo bindings. The above test should detect whether this is a problem.

Ubuntu 13.04 (raring)[edit]

To perform the above test on Ubuntu, you will need to have the lua interpreter installed:

$ sudo apt-get install lua5.2

To pull all the required runtime dependencies (LGI and the necessary typelibs for pango and cairo) using apt, the following command should do the trick (note that the cairo introspection stuff gets pulled as a dependency):

$ sudo apt-get install lua-lgi gir1.2-pango-1.0

Lua 5.2 Compatibility[edit]

In Lua 5.2, the module() function was deprecated. This has an effect on user configs. You now have to explicitely assign modules to variables when you load them:

naughty = require("naughty")

Signals[edit]

You should replace all calls of the add_signal function with connect_signal. Similarly, remove_signal becomes disconnect_signal.

To do signal and module() replacements and keep backup of awesome config this snippet can be handy:

export AWCONF=/etc/xdg/awesome/rc.lua; \
for pattern in 's/add_signal/connect_signal/' 's/remove_signal/disconnect_signal/' \
's/^require\("(naughty|beautiful|awful)"\)/\1 = \0/'; \
do sed -r "$pattern" < $AWCONF > $AWCONF.new;done

(in case there is a better way or place to put this, please go ahead --Kardan)
If Kardan recommendation is true, and generalizing last pattern, the code should be:

export AWCONF=/etc/xdg/awesome/rc.lua; \
sed -i.bak -r -e 's/add_signal/connect_signal/' \
              -e 's/remove_signal/disconnect_signal/' \
              -e 's/^require\("([^"]*)"\)/\1 = \0/' $AWCONF

"widget" Library Changes[edit]

"widget" Library Replacement[edit]

There is no longer a thing like widget in the API, so different widgets which were provided by its type parameter can be found in different places.

One of them is a new module named wibox. Please note that wibox is no longer a part of the standard API, so you need to require("wibox") to use it.

textbox
Migrated to wibox.widget.textbox()
imagebox
Migrated to wibox.widget.imagebox()
systray
Migrated to wibox.widget.systray()

Textbox Text Assignment[edit]

You should no longer simply assign text to the text property of the textbox widget. Instead you should use the following functions:

yourbox:set_markup(text)
Set the text content, with support for pango markup.
yourbox:set_text(text)
Set the text content, with no pango markup.

Imagebox Image Assignment[edit]

Similar things apply to the imagebox. However, you can now also give a file name to the imagebox widget directly.

box:set_image(image)

"awful" Library Changes[edit]

awful.taglist[edit]

The second argument to awful.widget.taglist, the tags labels should now be accessed using a widget taglist filter method.

The old default config did this :

   mytaglist[s] = awful.widget.taglist(s, awful.widget.taglist.label.all, mytaglist.buttons)

Now :

   mytaglist[s] = awful.widget.taglist(s, awful.widget.taglist.filter.all, mytaglist.buttons)


awful.tasklist[edit]

The first argument to awful.widget.tasklist is now the screen that the tasklist is for.

The old default config did this:

    mytasklist[s] = awful.widget.tasklist(function(c) return awful.widget.tasklist.label.currenttags(c, s) end, mytasklist.buttons)

The new default config instead creates its tasklist like this:

   mytasklist[s] = awful.widget.tasklist(s, awful.widget.tasklist.filter.currenttags, mytasklist.buttons)

awful.menu[edit]

awful.menu module has undergone a lot of changes. One of them is the modified method of setting the size of the entries. You no longer set it as:

  mymenu = awful.menu({ items = { ..... },
                        width = 300, height = 30 })

but it is rather like:

  mymenu = awful.menu({ items = { ...... },
                        theme = { width = 300, height = 30 } })

awful.menu_keys[edit]

A new key enter has been added to awful.menu_keys. So if you redefine the default menu_keys in your rc.lua, you will need to update it to include the new entry, like this:

awful.menu.menu_keys = { up    = { "k", "Up" },
                         down  = { "j", "Down" },
                         exec  = { "l", "Return", "Right" },
                         -- the new item
                         enter = { "Right" },
                         --
                         back  = { "h", "Left" },
                         close = { "q", "Escape" },
                       }

Writing Your Own Widgets[edit]

There is a separate guide which explains how to implement your own widgets. It can be found here.

Small Prettifications[edit]

Gradients[edit]

You may think that widget gradients for, say, progressbars are not supported in 3.5. False!

Now it is just one kind of pattern, which can be used as a background or foreground colour, or indeed any colour except for window borders. See the gears.color module documentation for details.

For example, where previously you had the following:

 cpubar:set_gradient_colors({ "#ff0000", "#00ff00", "#0000ff" })

With 3.5 you would do this instead:

 cpubar:set_color({ type = "linear", from = { 0, 0 }, to = { 0, 20 }, stops = { { 0, "#ff0000" }, { 0.5, "#00ff00" }, { 1, "#0000ff" } }})

For more information about linear (and other) gradients in cairo, you can take a look at [1] and [2].

Widget Borders[edit]

Indeed, there's no textbox.border_width = 1 or anything similar in 3.5 (as of Dec 10th 2012). Here's what psychon has to say about implementing it yourself; this page describes the functions used there.

Updating Your rc.lua via 3-Way Merge[edit]

If your rc.lua for 3.4 isn't terribly different from the default version, you can use a three-way merging tool like kdiff3 (Qt) or meld (GTK):

$ kdiff3 stock_3.4_rc.lua your_3.4_rc.lua stock_3.5_rc.lua -o your_3.5_rc.lua

or

$ meld stock_3.4_rc.lua your_3.4_rc.lua stock_3.5_rc.lua

It will detect changes made to the config since 3.4.x, both by you and Awesome developers, and help you merge them into a new version.