Skip to main content
Version: 2.2 (dev)

wibox

wibox provides the window that shows widgets, and the widgets, containers and layouts that go in it. The object model defines the terms.

SomeWM has three layers. Primitives are the objects C gives Lua: wibox, client, screen, tag, input and signals. Built-ins are everything Lua composes from them: the classes on this page, plus awful.popup, awful.wibar, awful.menu, naughty and the rest. Usability widgets are whole features built from built-ins and wired into the default configuration: the launcher, the hotkeys popup, the notification history. Everything SomeWM ships is built from the same parts you get, so you can take it as is, change it, or leave it out. This reference covers the built-ins in wibox.

Each class below has its own page with every property, method and signal, and what SomeWM does differently from AwesomeWM. Properties and signals shared by every class are on the common page. Every widget and container has a page. Layout pages wait for the Clay documentation, since a layout's behavior is a Clay sizing rule; until then the upstream page is the property list and the compatibility list has the SomeWM differences.

The animation reference covers frame transitions on wiboxes, popups and wibars, and property animations on their widgets.

Widgets​

Show content: text, an image, a value.

ClassShows
wibox.widget.calendarA month or a year, one cell per day
wibox.widget.checkboxA box that is checked or not
wibox.widget.graphA bar or line graph of values added over time
wibox.widget.imageboxAn image file, SVG or Cairo surface
wibox.widget.piechartA pie chart of named values
wibox.widget.progressbarA horizontal bar filled to a value
wibox.widget.separatorA line, or any shape, between other widgets
wibox.widget.sliderA draggable handle on a bar
wibox.widget.systrayThe tray icons of running applications
wibox.widget.textboxPlain or markup text
wibox.widget.textclockThe time, as a textbox that updates itself

The widgets that need the compositor live in awful.widget: taglist, tasklist, layoutbox, layoutlist, launcher, prompt, watch, clienticon, keyboardlayout, button, only_on_screen. Notification parts live in naughty.widget and naughty.list.

Containers​

Wrap one child and change how it looks or how much room it gets.

ClassDoes
wibox.container.arcchartDraws one or more values as arcs around the child
wibox.container.backgroundFill, text color, shape and border
wibox.container.constraintA minimum, maximum or exact size
wibox.container.marginSpace around the child, optionally colored
wibox.container.mirrorFlips the child horizontally or vertically
wibox.container.placeAligns the child inside the space it gets
wibox.container.radialprogressbarA ring filled to a value around the child
wibox.container.rotateTurns the child by a quarter, half or three quarters
wibox.container.scrollScrolls a child that is wider or taller than its box
wibox.container.tileDraws the child once; tiling is not applied in SomeWM

wibox.container.border is gone in SomeWM 2.1. Use background with border_width, border_color and shape.

Layouts​

Arrange several children.

ClassArranges children
wibox.layout.alignIn three slots: start, middle, end
wibox.layout.fixedIn order, each at its own size
wibox.layout.flexIn order, all the same size
wibox.layout.gridIn rows and columns
wibox.layout.manualAt positions you give
wibox.layout.overflowIn order, scrolling when they do not fit
wibox.layout.ratioIn order, each with a share of the space
wibox.layout.stackOn top of one another

align, fixed, flex, overflow and ratio come as .horizontal and .vertical. grid has .horizontal and .vertical too, naming the direction it grows in.

The window​

PageCovers
Wibar propertiesawful.wibar, a wibox on a screen edge

Writing a widget tree​

Widgets are declared as nested tables. widget or layout names the class, named fields are its properties, unnamed entries are its children:

wibox.widget {
{
{
text = "Hello",
widget = wibox.widget.textbox,
},
margins = 8,
widget = wibox.container.margin,
},
bg = "#333333",
shape = gears.shape.rounded_rect,
widget = wibox.container.background,
}

An id on a nested widget lets you reach it later from the root:

local w = wibox.widget {
{
id = "my_text",
text = "",
widget = wibox.widget.textbox,
},
widget = wibox.container.margin,
}

w:get_children_by_id("my_text")[1].text = "Updated"

Custom widgets compose these classes, register a Clay description, or display a Cairo image surface. See Create or port a custom widget. How widgets are laid out explains how a tree becomes sizes and positions.

Behavioral notes​

SomeWM uses the SNI (StatusNotifierItem) protocol for the system tray instead of X11's XEmbed. See Wayland vs X11.

A widget class with its own fit, draw or layout method is left out of the tree with a warning. See Upgrading from 2.0 to 2.1.