Module: `wibox`

Box where widget can be displayed.

Info:

Copyright: 2010 Uli Schlachter
Originally authored by: Uli Schlachter
(Full contributors list available on our github project)

Static module functions

wibox.connect_signal (name, func)	Connect a global signal on the wibox class.
wibox.emit_signal (name, ...)	Emit a wibox signal.
wibox.disconnect_signal (name, func) -> boolean	Disconnect a signal from a source.

Object properties

border_width	integer	Border width.
border_color	string	Border color.
ontop	boolean	On top of other windows.
cursor	string or nil	The mouse cursor.
visible	boolean	Visibility.
opacity	number	The opacity of the wibox, between 0 and 1.
type	string	The window type (desktop, normal, dock, ...).
x	integer	The x coordinates.
y	integer	The y coordinates.
width	integer	The width of the wibox.
height	integer	The height of the wibox.
screen	screen	The wibox screen.
widget	widget or nil	The widget that the wibox displays.
window	string	The X window id.
shape_bounding	surface._native	The wibox's bounding shape as a (native) cairo surface.
shape_clip	surface._native	The wibox's clip shape as a (native) cairo surface.
shape_input	surface._native	The wibox's input shape as a (native) cairo surface.
shape	shape	The wibar's shape.
input_passthrough	boolean	Forward the inputs to the client below the wibox.
buttons	table	Get or set mouse buttons bindings to a wibox.
bg	color	The background of the wibox.
bgimage	image or nil	The background image of the drawable.
fg	color	The foreground (text) of the wibox.

Object methods

:geometry (geo) -> table	Get or set wibox geometry.
:struts (struts) -> ()	Get or set wibox struts.
:setup {[args]}	Set a declarative widget hierarchy description.
:find_widgets (x, y) -> table	Find a widget by a point.
:to_widget () -> widget	Create a widget that reflects the current state of this wibox.
:save_to_svg (path, context)	Save a screenshot of the wibox to `path`.
:draw (wibox)	Redraw a wibox.

Constructors

🔗 wibox.wibox {[args]}

Create a wibox.

Parameters:

Note: This constructors uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be wibox{}. This is a Lua shortcut syntax equivalent to wibox({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.

Name		Type(s)	Description	Default value
args	Optional	table		`nil`
border_width		integer	Border width.	Not applicable
border_color		string	Border color.	Not applicable
ontop	Optional	boolean	On top of other windows.	`false`
cursor		string	The mouse cursor.	Not applicable
visible		boolean	Visibility.	Not applicable
opacity	Optional	number	The opacity, between 0 and 1.	`1`
type		string	The window type (desktop, normal, dock, …).	Not applicable
x		integer	The x coordinates.	Not applicable
y		integer	The y coordinates.	Not applicable
width		integer	The width.	Not applicable
height		integer	The height.	Not applicable
screen		screen	The wibox screen.	Not applicable
widget		wibox.widget	The widget that the wibox displays.	Not applicable
shape_bounding			The wibox’s bounding shape as a (native) cairo surface.	Not applicable
shape_clip			The wibox’s clip shape as a (native) cairo surface.	Not applicable
shape_input			The wibox’s input shape as a (native) cairo surface.	Not applicable
bg		color	The background.	Not applicable
bgimage		surface	The background image of the drawable.	Not applicable
fg		color	The foreground (text) color.	Not applicable
shape		gears.shape	The shape.	Not applicable
input_passthrough	Optional	boolean	If the inputs are forward to the element below.	`false`

Returns:

wibox

Static module functions

🔗 wibox.connect_signal (name, func)

Connect a global signal on the wibox class.

Functions connected to this signal source will be executed when any wibox object emits the signal.

It is also used for some generic wibox signals such as request::geometry.

Parameters:

Name		Type(s)	Description
name		string	The name of the signal
func		function	The function to attach

Usage:

wibox.connect_signal("added", function(notif)
   -- do something
end)

🔗 wibox.emit_signal (name, ...)

Emit a wibox signal.

Parameters:

Name		Type(s)	Description
name		string	The signal name.
...			The signal callback arguments

🔗 wibox.disconnect_signal (name, func) -> boolean

Disconnect a signal from a source.

Parameters:

Name		Type(s)	Description
name		string	The name of the signal
func		function	The attached function

Returns:

boolean

Object properties

🔗 border_width integer · 1 signal

Border width.

Constraints:

Default value	: `0`
Unit	: pixel
Negative allowed	: false

Click to display more

Emit signals:

property::border_width When the border_width value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 border_color string · 1 signal

Border color.

Please note that this property only support string based 24 bit or 32 bit colors:

Red Blue
 _|  _|
#FF00FF
   T‾
 Green


Red Blue
 _|  _|
#FF00FF00
   T‾  ‾T
Green   Alpha

Constraints:

Default value : beautiful.fg_normal

Click to display more

Emit signals:

property::border_color When the border_color value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

Consumed theme variables:

Theme variable	Usage
beautiful.fg_normal

🔗 ontop boolean · 1 signal

On top of other windows.

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Click to display more

Emit signals:

property::ontop When the ontop value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 cursor string or nil · 1 signal

The mouse cursor.

Constraints:

Default value	: `nil`
Type description:
nil	: Do not change the mouse cursor.

Emit signals:

property::cursor When the cursor value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 visible boolean · 1 signal

Visibility.

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Click to display more

Emit signals:

property::visible When the visible value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 opacity number · 1 signal

The opacity of the wibox, between 0 and 1.

Constraints:

Default value	: `true`
Minimum value	: 0.0
Maximum value	: 1.0

Click to display more

Emit signals:

property::opacity When the opacity value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 type string · 1 signal

The window type (desktop, normal, dock, ...).

Constraints:

Default value : \"\"

Emit signals:

property::type When the type value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 x integer · 1 signal

The x coordinates.

Constraints:

Default value	: `0`
Unit	: pixel
Negative allowed	: true

Click to display more

Emit signals:

property::x When the x value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 y integer · 1 signal

The y coordinates.

Constraints:

Default value	: `0`
Unit	: pixel
Negative allowed	: true

Click to display more

Emit signals:

property::y When the y value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 width integer · 1 signal

The width of the wibox.

Constraints:

Default value	: `1`
Unit	: pixel
Minimum value	: 1
Negative allowed	: false

Click to display more

Emit signals:

property::width When the width value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 height integer · 1 signal

The height of the wibox.

Constraints:

Default value	: `1`
Unit	: pixel
Minimum value	: 1
Negative allowed	: false

Click to display more

Emit signals:

property::height When the height value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 screen screen · 1 signal

The wibox screen.

Constraints:

Default value	: The screen which contains `0x0`.
Type description:
screen	: A valid screen object such as retured by `awful.screen.focused()` or mouse.screen.
integer	: A screen global id. Avoid using this since they are unsorted.
string	: The `"primary"` value is also valid.

Click to display more

Emit signals:

property::screen When the screen value changes.

self wibox The object which changed (useful when connecting many object to the same callback).
new_value screen The new value affected to the property.

🔗 widget widget or nil · 1 signal

The widget that the wibox displays.

Constraints:

Default value : nil

Click to display more

Emit signals:

property::widget When the widget value changes.

self wibox The object which changed (useful when connecting many object to the same callback).
new_value widget The new value affected to the property.

🔗 window string · 1 signal

The X window id.

Constraints:

Default value

: Autogenerated.

Emit signals:

property::window When the window value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 shape_bounding surface._native · 1 signal

The wibox's bounding shape as a (native) cairo surface.

If you want to set a shape, let say some rounded corners, use the shape property rather than this. If you want something very complex, for example, holes, then use this.

Constraints:

Default value

: Fill all pixels.

Emit signals:

property::shape_bounding When the shape_bounding value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 shape_clip surface._native · 1 signal

The wibox's clip shape as a (native) cairo surface.

The clip shape is the shape of the window content rather than the outer window shape.

Constraints:

Default value

: Fill all pixels.

Emit signals:

property::shape_clip When the shape_clip value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 shape_input surface._native · 1 signal

The wibox's input shape as a (native) cairo surface.

The input shape allows to disable clicks and mouse events on part of the window. This is how input_passthrough is implemented.

Constraints:

Default value

: Fill all pixels.

Emit signals:

property::shape_input When the shape_input value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 shape shape · 1 signal

The wibar's shape.

Constraints:

Default value	: `gears.shape.rectangle`
Type description:
gears.shape	: Like gears.shape.circle
function:	: This can be used for custom shapes or to set parameters of existing shapes.
Function prototype:
Parameters:
cr (cairo.context)	: A Cairo context
width (number)	: The area width.
height (number)	: The area height.
Return	: The function returns nothing.

Emit signals:

property::shape When the shape value changes.

self wibox The object which changed (useful when connecting many object to the same callback).
new_value shape The new value affected to the property.

🔗 input_passthrough boolean · 1 signal

Forward the inputs to the client below the wibox.

This replace the shape_input mask with an empty area. All mouse and keyboard events are sent to the object (such as a client) positioned below this wibox. When used alongside compositing, it allows, for example, to have a subtle transparent wibox on top a fullscreen client to display important data such as a low battery warning.

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::input_passthrough When the input_passthrough value changes.

self wibox The object which changed (useful when connecting many object to the same callback).
new_value input_passthrough The new value affected to the property.

🔗 buttons table · 1 signal

Get or set mouse buttons bindings to a wibox.

Constraints:

Default value	: `{}`
Table content	: A list of awful.buttons.
Valid values	: A table of buttons objects, or nothing.

Click to display more

Emit signals:

property::buttons When the buttons value changes.

self wibox The object which changed (useful when connecting many object to the same callback).

🔗 bg color · 1 signal · 1 theme variable

The background of the wibox.

The background color can be transparent. If there is a compositing manager such as compton, then it will be real transparency and may include blur (provided by the compositor). When there is no compositor, it will take a picture of the wallpaper and blend it.

Constraints:

Default value	: `beautiful.bg_normal`
Type description:
string	: An hexadecimal color code, such as `"#ff0000"` for red.
string	: A color name, such as `"red"`.
table	: A gradient table.
cairo.pattern	: Any valid Cairo pattern.
cairo.pattern	: A texture build from an image by gears.color.create_png_pattern
Valid values	: The background to use. This must either be a cairo pattern object, nil or a string that gears.color() understands.

Emit signals:

property::bg When the bg value changes.

self wibox The object which changed (useful when connecting many object to the same callback).
new_value bg The new value affected to the property.

Consumed theme variables:

Theme variable	Usage
beautiful.bg_normal	The default (fallback) bg color.
beautiful.bg_normal

🔗 bgimage image or nil · 1 signal

The background image of the drawable.

If image is a function, it will be called with (context, cr, width, height) as arguments. Any other arguments passed to this method will be appended.

Constraints:

Default value	: `nil`
Type description:
string	: Interpreted as a path to an image file.
string	: A valid SVG content.
cairo	: A cairo image surface: Directly used as-is.
librsvg	: A librsvg handle object: Directly used as-is.
nil	: Unset the image.

Emit signals:

property::bgimage When the bgimage value changes.

self wibox The object which changed (useful when connecting many object to the same callback).
new_value bgimage The new value affected to the property.

🔗 fg color · 1 signal · 1 theme variable

The foreground (text) of the wibox.

Constraints:

Default value	: `beautiful.fg_normal`
Type description:
string	: An hexadecimal color code, such as `"#ff0000"` for red.
string	: A color name, such as `"red"`.
table	: A gradient table.
cairo.pattern	: Any valid Cairo pattern.
cairo.pattern	: A texture build from an image by gears.color.create_png_pattern

Emit signals:

property::fg When the fg value changes.

self wibox The object which changed (useful when connecting many object to the same callback).
new_value fg The new value affected to the property.

Consumed theme variables:

Theme variable	Usage
beautiful.fg_normal	The default (fallback) fg color.
beautiful.fg_normal

Object methods

🔗 :geometry (geo) -> table · 1 signal

Get or set wibox geometry. That's the same as accessing or setting the x, y, width or height properties of a wibox.

Parameters:

Name		Type(s)	Description	Default value
geo	Optional	table or nil	A table with coordinates to modify. If nothing is specified, it only returns the current geometry.	`nil`

Returns:

table

Click to display more

Emit signals:

property::geometry When the geometry change.

geo table The geometry table.

🔗 :struts (struts) -> () · 1 signal

Get or set wibox struts.

Struts are the area which should be reserved on each side of the screen for this wibox. This is used to make bars and docked displays. Note that awful.wibar implements all the required boilerplate code to make bar. Only use this if you want special type of bars (like bars not fully attached to the side of the screen).

Parameters:

Name		Type(s)	Description
struts		table	A table with new strut, or nothing.

Returns:

The wibox strut in a table.

Emit signals:

property::struts

🔗 :setup {[args]}

Set a declarative widget hierarchy description. See The declarative layout system

Parameters:

Name		Type(s)	Description
args			An array containing the widgets disposition

🔗 :find_widgets (x, y) -> table

Find a widget by a point. The wibox must have drawn itself at least once for this to work.

Parameters:

Name		Type(s)	Description
x		number	X coordinate of the point
y		number	Y coordinate of the point

Returns:

table

width

height

widget

🔗 :to_widget () -> widget

Create a widget that reflects the current state of this wibox.

Returns:

widget

🔗 :save_to_svg (path, context)

Save a screenshot of the wibox to path.

Parameters:

Name		Type(s)	Description	Default value
path		string	The path.	Not applicable
context	Optional	table	A widget context.	`nil`

🔗 :draw (wibox)

Redraw a wibox. You should never have to call this explicitely because it is automatically called when needed.

Parameters:

Name		Type(s)	Description
wibox

awesome

Contents

Popups and bars

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Utility libraries

Theme related libraries

Libraries

Sample files

Classes

Documentation

Module: wibox

Info:

Constructors

Static module functions

Object properties

Object methods

Constructors

Parameters:

Returns:

Static module functions

Parameters:

Usage:

Parameters:

Parameters:

Returns:

Object properties

Constraints:

Emit signals:

Constraints:

Emit signals:

Consumed theme variables:

Constraints:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

Emit signals:

Constraints:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

Emit signals:

Constraints:

Emit signals:

Constraints:

Emit signals:

Constraints:

Emit signals:

Constraints:

Emit signals:

Constraints:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

Emit signals:

Module: `wibox`