Skip to main content
Version: 2.2 (dev)

Common properties and signals

Every class in wibox.widget, wibox.container and wibox.layout is built on wibox.widget.base, and so are the awful.widget classes. The per-class pages list only what a class adds; everything here applies to all of them.

Properties​

PropertyTypeDefaultWhat it doesIn SomeWM
visiblebooleantrueA hidden widget is not drawn and takes no space.
opacitynumber10 is transparent, 1 is opaque.Applies to each fill the widget draws, so overlapping fills add up.
forced_widthnumber or nilnilA width in pixels. nil lets the layout decide.A forced size is the size Clay solves the widget at, whatever its content. See sizing.
forced_heightnumber or nilnilA height in pixels.
buttonstable{}The awful.button bindings that fire on a click.
childrentable{}The direct children. Setting it replaces them on classes that hold children.
all_childrentable{}Every descendant, found by walking children. Read only.
animationtable, false or nilnilDurations by property for animated changes, false to disable animation in this subtree. See the animation reference.

Setting any property, here or on a class page, emits property::<name> with the new value.

Methods​

MethodWhat it does
:add_button(button)Appends an awful.button to buttons.
:animate { property = value, duration = seconds, ... }Sets target values and animates this change with the required duration. Leaves the persistent policy unchanged. With animation disabled the values apply at once. See one change with :animate.
:get_children_by_id(id)Returns the list of descendants declared with that id. Only on the root returned by wibox.widget { ... } or :setup.
:setup { ... }Replaces the widget's children from a declarative table.
:index(widget, recursive)Returns the position of widget among the children, the parent, and the path to it.
:emit_signal_recursive(name, ...)Emits a signal on the widget and on every ancestor in the tree.
:connect_signal(name, fn), :disconnect_signal(name, fn), :emit_signal(name, ...)Signals, from gears.object. fn receives the widget first, then the signal's arguments.

Signals​

SignalArguments after the widgetWhen
property::<name>the new valueA property was set.
button::press, button::releaselx, ly, button, mods, hitA mouse button went down or up over the widget. lx, ly are relative to the widget's box, button is 1 to 5, mods the modifier names. hit is the entry described below.
mouse::enter, mouse::leavehitThe pointer moved onto or off the widget.
widget::layout_changedThe widget's size may have changed. SomeWM relayouts its subtree.
widget::redraw_neededThe widget's look changed.

A hit entry has widget, drawable, x, y, width, height (the widget's box in the wibox), and widget_width and widget_height (the same box; they differed under a rotate in AwesomeWM). The hierarchy field of AwesomeWM is gone with wibox.hierarchy.

awful.button bindings are the usual way to react to clicks:

w:add_button(awful.button({}, 1, function() naughty.notification { message = "clicked" } end))
w:connect_signal("mouse::enter", function(self) self.bg = "#333333" end)