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


Bashets is a user widget library (but really not only for widget-related things) powered by shell scripts (but more data sources to come).

Bashets is glue code which empowers you to fetch data somewhere, and put it somewhere. It is a distinct approach from Obvious or Vicious, which try to implement and package predefined widgets themselves.

Supported sources are:

  • Launch shell script for timed execution.
  • Launch shell script to provide data itself.
  • Listen to DBus signals and fetch data from them.
  • Fetch data from a user-provided function.

Supported destinations are:

  • A widget's content. The widget could be a textbox, imagebox, progressbar, or graph.
  • A callback function. You are able to catch data updates in your own way.

Note: Bashets is compatible with awesome 3.5 and greater.

Why you should use it[edit]

Unix-like systems have over 9000 terminal tools for data acquisition and processing. So, the simplest way to get data from somewhere is the shellscript.

If you choose a widget system, you really choose a mean of representing the processed data. For example, your CPU usage could be represented as: graph, progressbar, pie-diagram or plain text.

So, what should you do? Yes, you should write a shellscript to process data, and have a widget to represent the value.

And bashets is a small piece of glue code to simplify the task and abstract you from working with raw timers, awesome-client or dbus apis of awesome WM.

You should only write one bashets.register() call in your rc.lua per widget - and your counters and graphs should be alive.

What can be done with it[edit]

A real-world example

In the example to the right, you can see my current desktop with the following widgets:

  • Keyboard layout (textbox)
  • Battery charge (imagebox)
  • Music player widget with coverart display and progressbar (textbox + imagebox + progressbar combination).

Irony: Yes, Wicked widgets are the grandfather of all current awesome widget libraries and there should be a symphony in its honour.

Of course, I am able to held all routinous tasks myself: to create the timers for scheduled mpc/acpi calls, to create a shellscript to feed keyboard widget with data.

But instead, it costs me not more than 5 lines of lua code with the help of bashets.

Here's my old desktop, where I had 7 progressbars showing info from different sources. Without Bashets this could've been a nightmare or a birth of several separate widget modules, but with Bashets it took 7 lines of lua code.

How to use it[edit]

  1. Get bashets.lua and copy it to /usr/share/awesome/lib
  2. Add require("bashets") to the top of your rc.lua
  3. Create a widget:
    • Textbox:
      xkbw = wibox.widget.textbox()
    • Imagebox:
      batw = wibox.widget.imagebox()
    • Progress Bar:
      coverpg = awful.widget.progressbar()
    • Graph:
      cpugraph = awful.widget.graph()
  4. Register a data source to update the widget
    • A timed-execution shell script:
      bashets.register("", {widget = batw, separator = " ", update_time=1})
    • External shell script:
      bashets.register("", {widget = xkbw, update_time = 1, external = true, format = ' $1'})
    • DBus signal:
      bashets.register("org.freedesktop.Hal.Manager", {dbus = true, busname = "system", widget = datew, format="$3"})
  5. Edit format string and separator such as you need (by default, "$1" and space symbol are used).
  6. After all widget registrations, add the line: bashets.start()
  7. Add the line bashets.stop() adjacent to awesome.quit() if you use external shell scripts. Otherwise your terminal will be flooded with DBus errors.
  8. Enjoy!

A note about "timed-execution" vs "external" shell scripts:

  • Timed-execution scripts are launched every update_time period
  • External shell scripts launch with awesome and work in the background, they provide widgets with data through awesome-client

From the user's viewpoint, there should be no difference between the two. They should print several lines to stdout, nothing more.

To learn more, read the docs.

PS: The previous version of this page covers more of the design and ideology behind Bashets.

Get Bashets[edit]

Bashets is hosted at Gitorious, alongside thorough documentation. There's also an Arch Linux package in AUR.