awesome

• Index

Contents

• Constructors
• Object properties
• Object methods
• Theme variables

Popups and bars

• awful.hotkeys_popup.widget
• awful.menu
• awful.popup
• awful.titlebar
• awful.tooltip
• awful.wallpaper
• awful.wibar
• awful.widget.calendar_popup
• menubar
• naughty.layout.box
• naughty.layout.legacy
• wibox

Core components

• awesome
• awful.keygrabber
• client and awful.client
• drawable
• gears.timer
• mousegrabber
• naughty.action
• naughty.notification
• root
• screen and awful.screen
• tag and awful.tag

Input handling

• awful.button
• awful.key
• awful.keyboard
• mouse

Declarative rules

• ruled.client
• ruled.notifications

Widgets

• awful.widget.button
• awful.widget.clienticon
• awful.widget.keyboardlayout
• awful.widget.launcher
• awful.widget.layoutbox
• awful.widget.layoutlist
• awful.widget.prompt
• awful.widget.taglist
• awful.widget.tasklist
• awful.widget.watch
• naughty.list.actions
• naughty.list.notifications
• naughty.widget.icon
• naughty.widget.message
• naughty.widget.title
• wibox.widget.calendar
• wibox.widget.checkbox
• wibox.widget.graph
• wibox.widget.imagebox
• wibox.widget.piechart
• wibox.widget.progressbar
• wibox.widget.separator
• wibox.widget.slider
• wibox.widget.systray
• wibox.widget.textbox
• wibox.widget.textclock

Widget containers

• awful.widget.only_on_screen
• naughty.widget.background
• wibox.container.arcchart
• wibox.container.background
• wibox.container.constraint
• wibox.container.margin
• wibox.container.mirror
• wibox.container.place
• wibox.container.radialprogressbar
• wibox.container.rotate
• wibox.container.scroll
• wibox.container.tile

Widget layouts

• wibox.layout.align
• wibox.layout.fixed
• wibox.layout.flex
• wibox.layout.grid
• wibox.layout.manual
• wibox.layout.ratio
• wibox.layout.stack

Utility libraries

• gears.debug
• gears.filesystem
• gears.geometry
• gears.math
• gears.object
• gears.protected_call
• gears.sort
• gears.string
• gears.table
• gears.wallpaper

Theme related libraries

• beautiful
• gears.color
• gears.shape

Libraries

• awful.completion
• awful.hotkeys_popup
• awful.layout
• awful.permissions
• awful.placement
• awful.prompt
• awful.rules
• awful.spawn
• awful.util
• dbus
• gears.matcher
• gears.surface
• menubar.menu_gen
• menubar.utils
• naughty
• selection
• wibox.widget

Sample files

• rc.lua
• theme.lua

Classes

• awful.screenshot
• awful.widget.common
• gears.cache
• gears.matrix
• menubar.icon_theme
• menubar.index_theme
• wibox.hierarchy
• wibox.widget.base
• xproperties

Documentation

• Authors
• Readme
• Contributing
• The Widget system
• Creating new widget
• Default configuration file documentation
• Change Awesome appearance
• My first Awesome
• The AwesomeWM client layout system
• Startup options
• Building and Testing
• Using Cairo and LGI
• Tips for upgrading your configuration
• NEWS
• FAQ

Module: awful.tooltip

Tooltip module for awesome objects.

A tooltip is a small hint displayed when the mouse cursor hovers over a specific item. In awesome, a tooltip can be linked with almost any object having a :connect_signal() method and receiving mouse::enter and mouse::leave signals.

How to create a tooltip?

local mytextclock = wibox.widget.textclock()

local myclock_t = awful.tooltip {
    objects        = { mytextclock },
    timer_function = function()
        return os.date("Today is %A %B %d %Y\nThe time is %T")
    end,
}

Alternatively, you can use mouse::enter signal:

local mytextclock = wibox.widget.textclock()

local myclock_t = awful.tooltip { }

myclock_t:add_to_object(mytextclock)

mytextclock:connect_signal("mouse::enter", function()
    myclock_t.text = os.date("Today is %A %B %d %Y\nThe time is %T")
end)

How to create a tooltip without objects?

local tt = awful.tooltip {
    text = "A tooltip!",
    visible = true,
}

tt.bg = beautiful.bg_normal

How to add the same tooltip to multiple objects?

myclock_t:add_to_object(obj1)
myclock_t:add_to_object(obj2)

Now the same tooltip is attached to myclock, obj1, obj2.

How to remove a tooltip from several objects?

myclock_t:remove_from_object(obj1)
myclock_t:remove_from_object(obj2)

Now the same tooltip is only attached to myclock.

Constructors

Object properties

Object methods

Theme variables

Constructors

🔗 awful.tooltip {[args]}

Create a new tooltip and link it to a widget. Tooltips emit property::visible when their visibility changes.

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 awful.tooltip{}. This is a Lua shortcut syntax equivalent to awful.tooltip({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.

Name		Type(s)	Description	Default value
args		table	Arguments for tooltip creation.	Not applicable
timer_function		function	A function to dynamically set the tooltip text. Its return value will be passed to wibox.widget.textbox.set_markup.	Not applicable
timeout	Optional	number	The timeout value for timer_function.	1
objects	Optional	table	A list of objects linked to the tooltip.	Undefined
delay_show	Optional	number	Delay showing the tooltip by this many seconds.	Undefined
margin_leftright	Optional	integer	The left/right margin for the text.	apply_dpi(5)
margin_topbottom	Optional	integer	The top/bottom margin for the text.	apply_dpi(3)
shape	Optional	gears.shape	The shape.	nil
bg	Optional	string	The background color.	beautiful.tooltip_bg
fg	Optional	string	The foreground color.	beautiful.tooltip_fg
border_color	Optional	string	The tooltip border color.	beautiful.tooltip_border_color
border_width	Optional	number	The tooltip border width.	beautiful.tooltip_border_width
align	Optional	string	The horizontal alignment.	Undefined
font	Optional	string	The tooltip font.	beautiful.tooltip_font
opacity	Optional	number	The tooltip opacity.	beautiful.tooltip_opacity
gaps	Optional	table or number	The tooltip margins.	beautiful.tooltip_gaps

Returns:

awful.tooltip The created tooltip.

See also:

add_to_object	Add tooltip to an object.	object methods
timeout	Change the tooltip's update interval.	object properties
text	Change displayed text.	object properties
markup	Change displayed markup.	object properties
align	The horizontal alignment.	object properties

Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.tooltip_bg
beautiful.tooltip_fg
beautiful.tooltip_border_color
beautiful.tooltip_border_width
beautiful.tooltip_font
beautiful.tooltip_opacity
beautiful.tooltip_gaps

Object properties

🔗 wibox wibox

The wibox containing the tooltip widgets.

Constraints:

Default value	: Autogenerated.

🔗 visible boolean · 1 signal

Is the tooltip visible?

Constraints:

Default value	: true
Valid values	: true or false.

Click to display more

Emit signals:

• property::visible When the visible value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value visible The new value affected to the property.

🔗 align string or nil · 1 signal · 1 theme variable

The horizontal alignment.

This is valid for the mouse mode only. For the outside mode, use preferred_positions.

Constraints:

Default value	: "right"
Type description:
nil	: Fallback to the current value of beautiful.tooltip_align.
Valid values:
"top_left"
"left"
"bottom_left"
"right"
"top_right"
"bottom_right"
"bottom"
"top"

See also:

mode	Set the tooltip positioning mode.	object properties
preferred_positions	The preferred positions when in outside mode.	object properties

Click to display more

Emit signals:

• property::align When the align value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value align The new value affected to the property.

Consumed theme variables:

Theme variable	Usage
beautiful.tooltip_align	Fallback when align isn't set.

🔗 shape shap or nil · 1 signal · 1 theme variable

The shape of the tooltip window.

Constraints:

Default value	: gears.shape.rectangle
Type description:
nil	: Fallback to the current value of beautiful.tooltip_shape.

See also:

gears.shape	Module dedicated to gather common shape painters.	module

Click to display more

Emit signals:

• property::shape When the shape value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value shape The new value affected to the property.

Consumed theme variables:

Theme variable	Usage
beautiful.tooltip_shape	Fallback when shape isn't set.

🔗 mode string · 1 signal

Set the tooltip positioning mode. This affects how the tooltip is placed. By default, the tooltip is aligned close to the mouse cursor. It is also possible to place the tooltip relative to the widget geometry.

mouse:

outside:

Constraints:

Default value	: "mouse"
Valid values:
"mouse"	: Next to the mouse cursor.
"outside"	: Outside of the widget.

Click to display more

Emit signals:

• property::mode When the mode value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value mode The new value affected to the property.

🔗 preferred_positions table · 1 signal

The preferred positions when in outside mode.

If the tooltip fits on multiple sides of the drawable, then this defines the priority.

The valid table values are:

• "top"
• "right"
• "left"
• "bottom"

Constraints:

Default value	: {"top", "right", "left", "bottom"}
Table content	: A list of strings.
Valid values	: The position, ordered by priorities

See also:

align	The horizontal alignment.	object properties
mode	Set the tooltip positioning mode.	object properties
preferred_alignments	The preferred alignment when using the outside mode.	object properties

Click to display more

Emit signals:

• property::preferred_positions When the preferred_positions value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value preferred_positions The new value affected to the property.

🔗 preferred_alignments table · 1 signal

The preferred alignment when using the outside mode.

The values of the table are ordered by priority, the first one that fits will be used.

front:

middle:

back:

The valid table values are:

• "front"
• "middle"
• "back"

Constraints:

Default value	: {"front", "back", "middle"}
Table content	: A list of strings.

See also:

preferred_positions	The preferred positions when in outside mode.	object properties

Click to display more

Emit signals:

• property::preferred_alignments When the preferred_alignments value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value preferred_alignments The new value affected to the property.

🔗 text string · 1 signal

Change displayed text.

Constraints:

Default value	: ""
Valid values	: New tooltip text, passed to wibox.widget.textbox.set_text.

See also:

wibox.widget.textbox	A widget to display either plain or HTML text.	module

Click to display more

Emit signals:

• property::text When the text value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value text The new value affected to the property.

🔗 markup string · 1 signal

Change displayed markup.

Constraints:

Default value	: ""
Valid values	: New tooltip markup, passed to wibox.widget.textbox.set_markup.

See also:

wibox.widget.textbox	A widget to display either plain or HTML text.	module

Click to display more

Emit signals:

• property::markup When the markup value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value markup The new value affected to the property.

🔗 timeout number · 1 signal

Change the tooltip's update interval.

Constraints:

Default value	: 1
Unit	: second
Negative allowed	: false

Click to display more

Emit signals:

• property::timeout When the timeout value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value timeout The new value affected to the property.

🔗 margins number or table · 1 signal

Set all margins around the tooltip textbox.

Constraints:

Default value	: 0
Type description:
number	: A single value for each sides.
table:	: A different value for each side.
top (number)
bottom (number)
left (number)
right (number)
Unit	: pixel
Negative allowed	: true

Click to display more

Emit signals:

• property::margins When the margins value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value margins The new value affected to the property.

🔗 border_width number or nil · 1 signal · 1 theme variable

The border width.

Constraints:

Default value	: 0
Type description:
nil	: Fallback to the current value of beautiful.tooltip_border_width.
Unit	: pixel
Negative allowed	: false

Click to display more

Emit signals:

• property::border_width When the border_width value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value border_width The new value affected to the property.

Consumed theme variables:

Theme variable	Usage
beautiful.tooltip_border_width	Fallback when border_width isn't set.

🔗 border_color color or nil · 1 signal · 1 theme variable

The border color.

Constraints:

Default value	: beautiful.tooltip_border_color or beautiful.border_color_normal or 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
nil	: Fallback to the current value of beautiful.tooltip_border_color.

Click to display more

Emit signals:

• property::border_color When the border_color value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value border_color The new value affected to the property.

Consumed theme variables:

Theme variable	Usage
beautiful.tooltip_border_color
beautiful.border_color_normal
beautiful.fg_normal

Consumed theme variables:

Theme variable	Usage
beautiful.tooltip_border_color	Fallback when border_color isn't set.

🔗 margins_leftright number · 1 signal

Set the margins around the left and right of the tooltip textbox.

Constraints:

Default value	: 0
Unit	: pixel
Negative allowed	: true

See also:

margins	Set all margins around the tooltip textbox.	object properties
margins_topbottom	Set the margins around the top and bottom of the tooltip textbox.	object properties

Click to display more

Emit signals:

• property::margins_leftright When the margins_leftright value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value margins_leftright The new value affected to the property.

🔗 margins_topbottom number · 1 signal

Set the margins around the top and bottom of the tooltip textbox.

Constraints:

Default value	: 0
Unit	: pixel
Negative allowed	: true

See also:

margins	Set all margins around the tooltip textbox.	object properties
margins_leftright	Set the margins around the left and right of the tooltip textbox.	object properties

Click to display more

Emit signals:

• property::margins_topbottom When the margins_topbottom value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value margins_topbottom The new value affected to the property.

🔗 gaps number or table or nil · 1 signal · 1 theme variable

Set the margins between the tooltip and its parent.

Constraints:

Default value	: 0
Type description:
number	: A single value for each sides.
table:	: A different value for each side.
top (number)
bottom (number)
left (number)
right (number)
nil	: Fallback to the current value of beautiful.tooltip_gaps.
Unit	: pixel
Negative allowed	: true

Click to display more

Emit signals:

• property::gaps When the gaps value changes.
• self awful.tooltip The object which changed (useful when connecting many object to the same callback).
• new_value gaps The new value affected to the property.

Consumed theme variables:

Theme variable	Usage
beautiful.tooltip_gaps	Fallback when gaps isn't set.

🔗 ontop boolean · Inherited from wibox · 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 · Inherited from wibox · 1 signal

The mouse cursor.

Constraints:

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

See also:

mouse	Manipulate and inspect the mouse cursor.	module

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

🔗 opacity number · Inherited from wibox · 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 · Inherited from wibox · 1 signal

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

Constraints:

Default value	: \"\"

See also:

client.type	The window type. (client)	object properties

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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 1 signal

The X window id.

Constraints:

Default value	: Autogenerated.

See also:

client.window	The X window id. (client)	object properties

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 surface._native · Inherited from wibox · 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.

See also:

shape	The wibar's shape.	object properties

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 surface._native · Inherited from wibox · 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.

See also:

shape	The wibar's shape.	object properties

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 surface._native · Inherited from wibox · 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.

See also:

input_passthrough	Forward the inputs to the client below the wibox.	object properties

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

🔗 input_passthrough boolean · Inherited from wibox · 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.

See also:

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

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

🔗 buttons table · Inherited from wibox · 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 · Inherited from wibox · 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.

See also:

gears.color	This module simplifies the creation of cairo pattern objects.	module

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 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 · Inherited from wibox · 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.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

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

🔗 fg color · Inherited from wibox · 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

See also:

gears.color	This module simplifies the creation of cairo pattern objects.	module

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

🔗 :add_to_object (obj)

Add tooltip to an object.

Parameters:

Name		Type(s)	Description
obj		gears.object	An object with mouse::enter and mouse::leave signals.

🔗 :remove_from_object (obj)

Remove tooltip from an object.

Parameters:

Name		Type(s)	Description
obj		gears.object	An object with mouse::enter and mouse::leave signals.

🔗 :emit_signal (name, ...) · Inherited from gears.object

Emit a signal.

Parameters:

Name		Type(s)	Description
name		string	The name of the signal.
...			Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal().

🔗 :connect_signal (name, func) · Inherited from gears.object

Connect to a signal.

Parameters:

Name		Type(s)	Description
name		string	The name of the signal.
func		function	The callback to call when the signal is emitted.

🔗 :weak_connect_signal (name, func) · Inherited from gears.object

Connect to a signal weakly.

This allows the callback function to be garbage collected and automatically disconnects the signal when that happens.

Warning: Only use this function if you really, really, really know what you are doing.

Parameters:

Name		Type(s)	Description
name		string	The name of the signal.
func		function	The callback to call when the signal is emitted.

🔗 :geometry (geo) -> table · Inherited from wibox · 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 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 (struts) -> () · Inherited from wibox · 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.

See also:

client.struts	Return client struts (reserved space at the edge of the screen). (client)	object methods

Click to display more

Emit signals:

• property::struts

🔗 :setup {[args]} · Inherited from wibox

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 · Inherited from wibox

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 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 · Inherited from wibox

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

Returns:

widget A new widget.

🔗 :save_to_svg (path, context) · Inherited from wibox

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) · Inherited from 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

Theme variables

🔗 beautiful.tooltip_border_color color

The tooltip border color.
Click to display more

Used by:

• awful.tooltip Create a new tooltip and link it to a widget.
• awful.tooltip Create a new tooltip and link it to a widget.
• border_color The border color.
• border_color The border color.
• border_color The border color.

🔗 beautiful.tooltip_bg color

The tooltip background color.
Click to display more

Used by:

• awful.tooltip Create a new tooltip and link it to a widget.
• awful.tooltip Create a new tooltip and link it to a widget.

🔗 beautiful.tooltip_fg color

The tooltip foregound (text) color.
Click to display more

Used by:

• awful.tooltip Create a new tooltip and link it to a widget.
• awful.tooltip Create a new tooltip and link it to a widget.

🔗 beautiful.tooltip_font string

The tooltip font.
Click to display more

Used by:

• awful.tooltip Create a new tooltip and link it to a widget.
• awful.tooltip Create a new tooltip and link it to a widget.

🔗 beautiful.tooltip_border_width number

The tooltip border width.
Click to display more

Used by:

• awful.tooltip Create a new tooltip and link it to a widget.
• awful.tooltip Create a new tooltip and link it to a widget.
• border_width The border width.

🔗 beautiful.tooltip_opacity number

The tooltip opacity.

Type constraints:

Name		Type(s)	Description
opacity		number	Between 0 and 1

Click to display more

Used by:

• awful.tooltip Create a new tooltip and link it to a widget.
• awful.tooltip Create a new tooltip and link it to a widget.

🔗 beautiful.tooltip_gaps table

The tooltip margins.
Click to display more

Used by:

• awful.tooltip Create a new tooltip and link it to a widget.
• awful.tooltip Create a new tooltip and link it to a widget.
• gaps Set the margins between the tooltip and its parent.

🔗 beautiful.tooltip_shape gears.shape

The default tooltip shape. The default shape for all tooltips is a rectangle. However, by setting this variable they can default to rounded rectangle or stretched octagons.

Type constraints:

Name		Type(s)	Description	Default value
shape	Optional	gears.shape	A gears.shape compatible function	gears.shape.rectangle

See also:

shape	The shape of the tooltip window.	object properties
gears.shape	Module dedicated to gather common shape painters.	module

Click to display more

Used by:

• shape The shape of the tooltip window.

🔗 beautiful.tooltip_align string

The default tooltip alignment.

See also:

align	The horizontal alignment.	object properties

Click to display more

Used by:

• align The horizontal alignment.