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.

Widgets in awesome

From awesome
Jump to: navigation, search

What are widgets[edit]

Widgets in awesome are objects you can add to any wibox (statusbars and titlebars), they can provide various information about your system, window manager and X clients right from your desktop. Widgets are simple to use and offer a great deal of flexibility.

Widget creation[edit]

For awesome 3.4

 mysystray = widget({ type = "systray" })
 myicon = widget({ type = "imagebox" })
 myicon.image = image(awful.util.getdir("config") .. "/myicon.png")
 mytextbox = widget({ type = "textbox" })

For awesome 3.5

 mysystray = wibox.widget.systray()
 myicon = wibox.widget.imagebox()
 myicon:set_image(awful.util.getdir("config") .. "/myicon.png")
 mytextbox = wibox.widget.textbox()

Widget types[edit]

The following widget types currently exist:


Displays the system tray, which follows the freedesktop specification. Programs can put their tray icons here.


Displays an image, of a format Imlib2 can handle (png, jpeg...). Combine it with textbox widgets to create launchers, icons and separators.


Textbox widgets display a piece of text, they are the most common widgets. By creating a textbox widget, as shown in the above example, the mytextbox now contains a widget object. You can set or change the text of this textbox widget by modifying its .text field in version 3.4 or using the set_text method in 3.5:

Awesome 3.4:

mytextbox.text = "Hello, world!"

Awesome 3.5:

mytextbox:set_text("Hello, world!")

This will set the text printed by the widget to Hello, world!. Some of you will now remember the awesome-client utility, and ask if it's possible to change widget text using it. The answer is yes, you only need to change the .text field or use the set_text method depending on your version of Awesome the and the widget will be updated:

Awesome 3.4:

 $ echo "mytextbox.text = \"Foo Bar!\"" | awesome-client

Awesome 3.5:

 $ echo "mytextbox:set_text(\"Foo Bar!\")" | awesome-client

However with awesome you don't have to use external scripts to feed your widgets with data. Awesome doesn't only allow writing system monitors in Lua but also provides the awesome timer API which will help you setup timers that periodically execute, and update, your widgets. Let's see a timer example:

Awesome 3.4:

 mytimer = timer({ timeout = 30 })
 mytimer:add_signal("timeout", function() mytextbox.text = "Hello awesome world!" end)

Awesome 3.5:

 mytimer = timer({ timeout = 30 })
 mytimer:connect_signal("timeout", function() mytextbox:set_text("Hello awesome world!") end)

One of the most frequently asked questions is about textbox widget colors. When talking about a textbox widget the color applies to the actual font, and in awesome you can change font properties by applying standard Pango markup. In 3.5 the markup will be ignored by the set_text method, instead use the set_markup method for the same effect

Awesome 3.4:

  mytextbox.text = '<span color="white">Sacrebleu, I have seen a ghost!</span> '

Awesome 3.5:

  mytextbox:set_markup( '<span color="white">Sacrebleu, I have seen a ghost!</span> ')

Changing the background can be achived by using a background widget

Awesome 3.5:

 local datewidget_text = wibox.widget.textbox()
 local datewidget = wibox.widget.background()

awful widget functions[edit]

Awesome is distributed with several widget function helpers, as part of the awful library, that use the above widget types to create complex widgets which provide irreplaceable functionality. Some examples of these are the awful.widget.taglist function - creating taglist widgets, and awful.widget.tasklist function - creating taskbar widgets. Other useful awful widget functions are the button, launcher, prompt and layoutbox.

awful widget types[edit]


The awful.widget.graph module creates and displays a graph with varying data over time.

Example graph configuration:

 mygraph = awful.widget.graph()
 mygraph:set_gradient_colors({ '#FF5656', '#88A175', '#AECF96' })

mygraph now contains a widget object, a graph, stored in its .widget field. You can add data to your graph using the add_value() function:



The awful.widget.progressbar module creates and displays progresssbar widgets.

Example progressbar configuration:

 myprogressbar = awful.widget.progressbar()
 myprogressbar:set_gradient_colors({ '#AECF96', '#88A175', '#FF5656' })

myprogressbar now contains a widget object, a progressbar, stored in its .widget field. You can add data to your progressbar using the set_value() function:


Remember the textbox example, awesome-client and timers. The same applies here, using the add_value() (graph) and set_value() (progressbar) functions you can dynamically fill these widgets by sending them numbers in range 0.1 - 1. You can find other available functions and progressbar/graph properties in the API documentation.

Widget buttons[edit]

You can attach button bindings to widgets, let's see an example:

   awful.button({ }, 1, function () awful.util.spawn("echo Left mouse button pressed.") end)

The following example shows how to add button bindings to progressbar and graph widgets, by attaching them to the actual widget object stored in its .widget field:

   awful.button({ }, 1, function () awful.util.spawn("echo Left mouse button pressed again.") end)

Controlling widgets[edit]

In previous sections we covered everything about widget initialization, but remember; a widget needs to be added to a wibox in order to be displayed. In your rc.lua a wibox is created by looping over each physical screen. You can control where your widget will be displayed by placing it on a particular wibox, and one widget can be added to multiple wibox' and screens.

You can also control on which screen the widget is placed on (by default they are placed on all screens on which the wibox is visible). One existing example of this functionality is the systray widget, which because of specification limitations can only be displayed once:

 s == 1 and mysystray or nil,

In the above example systray will only appear on screen 1. You can use the same code with other widgets:

 s == 2 and mytextbox or nil,

Like in the above buttons example, when adding progressbar and graph widgets to your wibox you need to reference the actual widget object:

 mytextclock,          -- awesome clock widget, textbox
 mygraph.widget,       -- users customized graph widget
 myprogressbar.widget, -- users customized prbar widget

Widget layouts[edit]

Widget layouts allow controlling the placement of widgets, from Lua, to a much bigger degree than with the "old" widget .align property. You should read the introduction to widget layouts and Widget Layouts to learn more.