Module: awful.wibar

Wibox module for awful.

This module allows you to easily create wibox and attach them to the edge of a screen.

Info:

  • Copyright: 2016 Emmanuel Lepage Vallee
  • Author: Emmanuel Lepage Vallee <[email protected]>

Constructors

awful.wibar {[args]} Create a new wibox and attach it to a screen edge.

Object properties

stretch boolean If the wibar needs to be stretched to fill the screen.
width integer The wibar’s width.
height integer The wibar’s height.
position string The wibox position.
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.
bg c The background of the wibox.
bgimage image The background image of the drawable.
fg c The foreground (text) of the wibox.

Object methods

:remove () Remove a wibar.
:buttons (buttons_table) Get or set mouse buttons bindings to a wibox.
: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) Find a widget by a point.

Theme variables

beautiful.wibar_stretch boolean If the wibar needs to be stretched to fill the screen.
beautiful.wibar_border_width integer The wibar border width.
beautiful.wibar_border_color string The wibar border color.
beautiful.wibar_ontop boolean If the wibar is to be on top of other windows.
beautiful.wibar_cursor string The wibar’s mouse cursor.
beautiful.wibar_opacity number The wibar opacity, between 0 and 1.
beautiful.wibar_type string The window type (desktop, normal, dock, …).
beautiful.wibar_width integer The wibar’s width.
beautiful.wibar_height integer The wibar’s height.
beautiful.wibar_bg color The wibar’s background color.
beautiful.wibar_bgimage surface The wibar’s background image.
beautiful.wibar_fg color The wibar’s foreground (text) color.
beautiful.wibar_shape gears.shape The wibar’s shape.
beautiful.bg_normal color The default background color.
beautiful.fg_normal color The default foreground (text) color.

Deprecated functions

awful.wibar.get_position [deprecated] Get a wibox position if it has been set, or return top.
awful.wibar.set_position [deprecated] Put a wibox on a screen at this position.
awful.wibar.attach [deprecated] Attach a wibox to a screen.
awful.wibar.align [deprecated] Align a wibox.
awful.wibox.stretch [deprecated] Stretch a wibox so it takes all screen width or height.


Constructors

awful.wibar {[args]}
Create a new wibox and attach it to a screen edge. You can add also position key with value top, bottom, left or right. You can also use width or height in % and set align to center, right or left. You can also set the screen key with a screen number to attach the wibox. If not specified, the primary screen is assumed.

Parameters:

  • args
    • position string The position.
    • stretch string If the wibar need to be stretched to fill the screen.
    • 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:

    The new wibar

See also:

Object properties

stretch (boolean)
If the wibar needs to be stretched to fill the screen.
width (integer)
The wibar’s width.
height (integer)
The wibar’s height.
position (string)
The wibox position.

Type constraints:

  • string Either “left”, right", “top” or “bottom”
border_width (integer)

Border width.

Signal:

  • property::border_width
border_color (string)

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

Signal:

  • property::border_color
ontop (boolean)

On top of other windows.

Signal:

  • property::ontop
cursor (string)

The mouse cursor.

Signal:

  • property::cursor

See also:

visible (boolean)

Visibility.

Signal:

  • property::visible
opacity (number)

The opacity of the wibox, between 0 and 1.

Signal:

  • property::opacity

Type constraints:

  • opacity number (between 0 and 1)
type (string)

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

Signal:

  • property::type

See also:

x (integer)

The x coordinates.

Signal:

  • property::x
y (integer)

The y coordinates.

Signal:

  • property::y
width (width)

The width of the wibox.

Signal:

  • property::width
height (height)

The height of the wibox.

Signal:

  • property::height
screen (screen)
The wibox screen.
drawable (drawable)

The wibox’s drawable.

Signal:

  • property::drawable
widget (widget)
The widget that the wibox displays.
window (string)

The X window id.

Signal:

  • property::window

See also:

shape_bounding (N/A)

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

Signal:

  • property::shape_bounding
shape_clip (N/A)

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

Signal:

  • property::shape_clip
shape_input (N/A)

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

Signal:

  • property::shape_input
shape (gears.shape)

The wibar’s shape.

Signal:

  • property::shape
input_passthrough (boolean)

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.

Signal:

  • property::input_passthrough

See also:

bg (c)
The background of the wibox.

Type constraints:

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

See also:

bgimage (image)
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 A background image or a function

See also:

fg (c)
The foreground (text) of the wibox.

Type constraints:

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

See also:

Object methods

:remove ()
Remove a wibar.
:buttons (buttons_table)
Get or set mouse buttons bindings to a wibox.

Parameters:

  • buttons_table A table of buttons objects, or nothing.
:geometry (A)
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.
:struts (strut)
Get or set wibox struts.

Parameters:

  • strut A table with new strut, or nothing

Returns:

    The wibox strut in a table.

See also:

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

Theme variables

beautiful.wibar_stretch (boolean)
If the wibar needs to be stretched to fill the screen.
beautiful.wibar_border_width (integer)
The wibar border width.
beautiful.wibar_border_color (string)
The wibar border color.
beautiful.wibar_ontop (boolean)
If the wibar is to be on top of other windows.
beautiful.wibar_cursor (string)
The wibar’s mouse cursor.
beautiful.wibar_opacity (number)
The wibar opacity, between 0 and 1.
beautiful.wibar_type (string)
The window type (desktop, normal, dock, …).
beautiful.wibar_width (integer)
The wibar’s width.
beautiful.wibar_height (integer)
The wibar’s height.
beautiful.wibar_bg (color)
The wibar’s background color.
beautiful.wibar_bgimage (surface)
The wibar’s background image.
beautiful.wibar_fg (color)
The wibar’s foreground (text) color.
beautiful.wibar_shape (gears.shape)
The wibar’s shape.
beautiful.bg_normal (color)
The default background color.

See also:

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

See also:

Deprecated functions

awful.wibar.get_position [deprecated]
Get a wibox position if it has been set, or return top.

Parameters:

  • wb The wibox

Returns:

    The wibox position.
awful.wibar.set_position [deprecated]
Put a wibox on a screen at this position.

Parameters:

  • wb The wibox to attach.
  • position The position: top, bottom left or right.
  • screen This argument is deprecated, use wb.screen directly.
awful.wibar.attach [deprecated]
Attach a wibox to a screen.

This function has been moved to the awful.placement module. Calling this no longer does anything.

Parameters:

  • wb The wibox to attach.
  • position The position of the wibox: top, bottom, left or right.
  • screen The screen to attach to

See also:

awful.wibar.align [deprecated]

Align a wibox.

Supported alignment are:

  • top_left
  • top_right
  • bottom_left
  • bottom_right
  • left
  • right
  • top
  • bottom
  • centered
  • center_vertical
  • center_horizontal

Parameters:

  • wb The wibox.
  • align The alignment
  • screen This argument is deprecated. It is not used. Use wb.screen directly.

See also:

awful.wibox.stretch [deprecated]
Stretch a wibox so it takes all screen width or height.

This function has been removed.

See also:

generated by LDoc 1.4.6 Last updated 2030-01-01 00:00:00