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

### Class Hierarchy

- wibox
- - awful.tooltip

### Info:

- Copyright: 2009 Sébastien Gross
- Originally authored by: Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org>
  (Full contributors list available on our github project)

## Constructors

awful.tooltip {[args]} | Create a new tooltip and link it to a widget. |

## Object properties

wibox | wibox | The wibox containing the tooltip widgets. |
visible | boolean | Is the tooltip visible? |
align | string or nil | The horizontal alignment. |
shape | shap or nil | The shape of the tooltip window. |
mode | string | Set the tooltip positioning mode. |
preferred_positions | table | The preferred positions when in `outside` mode. |
preferred_alignments | table | The preferred alignment when using the `outside` mode. |
text | string | Change displayed text. |
markup | string | Change displayed markup. |
timeout | number | Change the tooltip's update interval. |
margins | number or table | Set all margins around the tooltip textbox. |
border_width | number or nil | The border width. |
border_color | color or nil | The border color. |
margins_leftright | number | Set the margins around the left and right of the tooltip textbox. |
margins_topbottom | number | Set the margins around the top and bottom of the tooltip textbox. |
gaps | number or table or nil | Set the margins between the tooltip and its parent. |
ontop | boolean | On top of other windows. | Inherited from wibox
cursor | string or nil | The mouse cursor. | Inherited from wibox
opacity | number | The opacity of the wibox, between 0 and 1. | Inherited from wibox
type | string | The window type (desktop, normal, dock, ...). | Inherited from wibox
x | integer | The x coordinates. | Inherited from wibox
y | integer | The y coordinates. | Inherited from wibox
width | integer | The width of the wibox. | Inherited from wibox
height | integer | The height of the wibox. | Inherited from wibox
screen | screen | The wibox screen. | Inherited from wibox
widget | widget or nil | The widget that the wibox displays. | Inherited from wibox
window | string | The X window id. | Inherited from wibox
shape_bounding | surface._native | The wibox's bounding shape as a (native) cairo surface. | Inherited from wibox
shape_clip | surface._native | The wibox's clip shape as a (native) cairo surface. | Inherited from wibox
shape_input | surface._native | The wibox's input shape as a (native) cairo surface. | Inherited from wibox
input_passthrough | boolean | Forward the inputs to the client below the wibox. | Inherited from wibox
buttons | table | Get or set mouse buttons bindings to a wibox. | Inherited from wibox
bg | color | The background of the wibox. | Inherited from wibox
bgimage | image or nil | The background image of the drawable. | Inherited from wibox
fg | color | The foreground (text) of the wibox. | Inherited from wibox

## Object methods

:add_to_object (obj) | Add tooltip to an object. |
:remove_from_object (obj) | Remove tooltip from an object. |
:emit_signal (name, ...) | Emit a signal. | Inherited from gears.object
:connect_signal (name, func) | Connect to a signal. | Inherited from gears.object
:weak_connect_signal (name, func) | Connect to a signal weakly. | Inherited from gears.object
:geometry (geo) -> table | Get or set wibox geometry. | Inherited from wibox
:struts (struts) -> () | Get or set wibox struts. | Inherited from wibox
:setup {[args]} | Set a declarative widget hierarchy description. | Inherited from wibox
:find_widgets (x, y) -> table | Find a widget by a point. | Inherited from wibox
:to_widget () -> widget | Create a widget that reflects the current state of this wibox. | Inherited from wibox
:save_to_svg (path, context) | Save a screenshot of the wibox to `path`. | Inherited from wibox
:draw (wibox) | Redraw a wibox. | Inherited from wibox

## Theme variables

beautiful.tooltip_border_color | color | The tooltip border color. |
beautiful.tooltip_bg | color | The tooltip background color. |
beautiful.tooltip_fg | color | The tooltip foregound (text) color. |
beautiful.tooltip_font | string | The tooltip font. |
beautiful.tooltip_border_width | number | The tooltip border width. |
beautiful.tooltip_opacity | number | The tooltip opacity. |
beautiful.tooltip_gaps | table | The tooltip margins. |
beautiful.tooltip_shape | gears.shape | The default tooltip shape. |
beautiful.tooltip_align | string | The default tooltip alignment. |

## 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](../theme_related_libraries/gears.color.html).
  cairo.pattern | : Any valid [Cairo pattern](https://cairographics.org/manual/cairo-cairo-pattern-t.html).
  cairo.pattern | : A texture build from an image by [gears.color.create\_png\_pattern](../theme_related_libraries/gears.color.html#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](../theme_related_libraries/gears.color.html).
  cairo.pattern | : Any valid [Cairo pattern](https://cairographics.org/manual/cairo-cairo-pattern-t.html).
  cairo.pattern | : A texture build from an image by [gears.color.create\_png\_pattern](../theme_related_libraries/gears.color.html#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](../theme_related_libraries/gears.color.html).
  cairo.pattern | : Any valid [Cairo pattern](https://cairographics.org/manual/cairo-cairo-pattern-t.html).
  cairo.pattern | : A texture build from an image by [gears.color.create\_png\_pattern](../theme_related_libraries/gears.color.html#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](../documentation/03-declarative-layout.md.html)

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

generated by LDoc 1.5.0