Module: wibox

Info:

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

Constructors

wibox.wibox {[args]} Create a wibox.

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 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 width The width of the wibox.
height height The height of the wibox.
screen screen The wibox screen.
drawable drawable The wibox's drawable.
widget widget The widget that the wibox displays.
window string The X window id.
shape_bounding N/A The wibox's bounding shape as a (native) cairo surface.
shape_clip N/A The wibox's clip shape as a (native) cairo surface.
shape_input N/A The wibox's input shape as a (native) cairo surface.
shape gears.shape The wibar's shape.
input_passthrough boolean Forward the inputs to the client below the wibox.
buttons buttons_table Get or set mouse buttons bindings to a wibox.
bg c The background of the wibox.
bgimage gears.suface or string or function The background image of the drawable.
fg color The foreground (text) of the wibox.

Object methods

:geometry (A) -> () Get or set wibox geometry.
:struts (strut) -> () 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=nil]) Save a screenshot of the wibox to path.
:draw (wibox) Redraw a wibox.

Theme variables

beautiful.bg_normal color The default background color.
beautiful.fg_normal color The default foreground (text) color.


Constructors

wibox.wibox {[args]}
Create a wibox.

Parameters:

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

Returns:

    wibox The new 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 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 string The signal name.
  • ... The signal callback arguments
wibox.disconnect_signal (name, func) -> boolean
Disconnect a signal from a source.

Parameters:

  • name string The name of the signal
  • func function The attached function

Returns:

    boolean If the disconnection was successful

Object properties

border_width integer · 1 signal
Border width.
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

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).
ontop boolean · 1 signal
On top of other windows.
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 · 1 signal
The mouse cursor.

See also:


Click to display more

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

Type constraints:

  • opacity number (between 0 and 1)

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, ...).

See also:


Click to display more

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.
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.
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 width · 1 signal
The width of the wibox.
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 height · 1 signal
The height of the wibox.
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.
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.
drawable drawable · 1 signal
The wibox's drawable.
Click to display more

Emit signals:

  • property::drawable When the drawable value changes.
    • self wibox The object which changed (useful when connecting many object to the same callback).
widget widget · 1 signal
The widget that the wibox displays.
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.

See also:


Click to display more

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 N/A · 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.

See also:


Click to display more

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 N/A · 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.

See also:


Click to display more

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 N/A · 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.

See also:


Click to display more

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 gears.shape · 1 signal
The wibar's shape.

See also:


Click to display more

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.

See also:


Click to display more

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 boolean The new value affected to the property.
buttons buttons_table · 1 signal
Get or set mouse buttons bindings to a wibox.

Type constraints:

  • buttons_table 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 c · 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.

Type constraints:

  • The c background to use. This must either be a cairo pattern object, nil or a string that gears.color() understands.

See also:


Click to display more

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 The The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.bg_normalThe default (fallback) bg color.
bgimage gears.suface or string or function · 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.

Type constraints:

  • image gears.suface, string or function A background image or a function.

See also:


Click to display more

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 image The new value affected to the property.
fg color · 1 signal · 1 theme variable
The foreground (text) of the wibox.

Type constraints:

  • c color The foreground to use. This must either be a cairo pattern object, nil or a string that gears.color() understands.
  • color

See also:


Click to display more

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 c The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.fg_normalThe default (fallback) fg color.

Object methods

:geometry (A) -> () · 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:

  • A table with coordinates to modify.

Returns:

    A table with wibox coordinates and geometry.

Click to display more

Emit signals:

  • property::geometry When the geometry change.
    • geo table The geometry table.
:struts (strut) -> () · 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:

  • strut A table with new strut, or nothing

Returns:

    The wibox strut in a table.

See also:


Click to display more

Emit signals:

  • property::struts
:setup {[args]}
Set a declarative widget hierarchy description. See The declarative layout system

Parameters:

  • 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:

  • x number X coordinate of the point
  • y number Y coordinate of the point

Returns:

    table A sorted table of widgets positions. The first element is the biggest container while the last is the topmost widget. The table contains x, y, width, height and widget.
:to_widget () -> widget
Create a widget that reflects the current state of this wibox.

Returns:

    widget A new widget.
:save_to_svg (path[, context=nil])
Save a screenshot of the wibox to path.

Parameters:

  • path string The path.
  • context table A widget context. (default nil)
:draw (wibox)
Redraw a wibox. You should never have to call this explicitely because it is automatically called when needed.

Parameters:

  • wibox

Theme variables

beautiful.bg_normal color
The default background color.

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.

See also:

beautiful.fg_normal color
The default foreground (text) color.

See also:

generated by LDoc 1.4.6 Last updated 2021-11-13 00:35:50