Widgets in awesome

What are widgets
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
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
The following widget types currently exist:

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

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

textbox
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) mytimer:start

Awesome 3.5:

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

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 = ' Sacrebleu, I have seen a ghost! '

Awesome 3.5:

mytextbox:set_markup( ' Sacrebleu, I have seen a ghost! ')

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 datewidget:set_widget(datewidget_text) datewidget:set_bg("#df7401")

awful widget functions
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.

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

Example graph configuration: mygraph = awful.widget.graph mygraph:set_width(50) mygraph:set_background_color('#494B4F') mygraph:set_color('#FF5656') 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:

mygraph:add_value(0.5)

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

Example progressbar configuration: myprogressbar = awful.widget.progressbar myprogressbar:set_width(8) myprogressbar:set_height(10) myprogressbar:set_vertical(true) myprogressbar:set_background_color('#494B4F') myprogressbar:set_color('#AECF96') 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:

myprogressbar:set_value(0.5)

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
You can attach button bindings to widgets, let's see an example:

mytextbox:buttons(awful.util.table.join( 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: mygraph.widget:buttons(awful.util.table.join( awful.button({ }, 1, function awful.util.spawn("echo Left mouse button pressed again.") end) ))

Controlling widgets
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
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.