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?

Usage example

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:

Usage example

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?

Usage example

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.

Info:

  • Copyright: 2009 Sébastien Gross
  • Author: Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org>

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 The horizontal alignment.
shape gears.shape 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 string 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 The border width.
border_color color 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 Set the margins between the tooltip and its parent.

Object methods

:add_to_object (self, obj) Add tooltip to an object.
:remove_from_object (self, 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

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:

  • args Arguments for tooltip creation.
    • timer_function function A function to dynamically set the tooltip text. Its return value will be passed to wibox.widget.textbox.set_markup.
    • timeout number The timeout value for timer_function. (default 1)
    • objects table A list of objects linked to the tooltip. (optional)
    • delay_show number Delay showing the tooltip by this many seconds. (optional)
    • margin_leftright integer The left/right margin for the text. (default apply_dpi(5))
    • margin_topbottom integer The top/bottom margin for the text. (default apply_dpi(3))
    • shape gears.shape The shape. (default nil)
    • bg string The background color. (optional)
    • fg string The foreground color. (optional)
    • border_color string The tooltip border color. (optional)
    • border_width number The tooltip border width. (optional)
    • align string The horizontal alignment. (optional)
    • font string The tooltip font. (optional)
    • opacity number The tooltip opacity. (optional)
    • gaps table or number The tooltip margins. (optional)

Returns:

    awful.tooltip The created tooltip.

See also:

Object properties

wibox wibox
The wibox containing the tooltip widgets.
visible boolean · 1 signal
Is the tooltip visible?
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 boolean The new value affected to the property.
align string · 1 signal · 1 theme variable

The horizontal alignment.

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

Usage example

Usage example

The following values are valid:

  • top_left
  • left
  • bottom_left
  • right
  • top_right
  • bottom_right
  • bottom
  • top

See also:


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

Consumed theme variables:

Theme variable Usage
beautiful.tooltip_alignFallback when align isn't set.
shape gears.shape · 1 signal · 1 theme variable
The shape of the tooltip window.

Usage example

See also:


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

Usage example

outside:

Usage example

Valid modes are:

  • “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 string The new value affected to the property.
preferred_positions table · 1 signal

The preferred positions when in outside mode.

Usage example

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

The valid table values are:

  • “top”
  • “right”
  • “left”
  • “bottom”

The default is:

{"top", "right", "left", "bottom"}

Type constraints:

  • preferred_positions table The position, ordered by priorities

See also:


Click to display more

Emit signals:

preferred_alignments string · 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:

Usage example

middle:

Usage example

back:

Usage example

The valid table values are:

  • front
  • middle
  • back

The default is:

{"front", "back", "middle"}

See also:


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 string The new value affected to the property.
text string · 1 signal
Change displayed text.

Type constraints:

  • text string New tooltip text, passed to wibox.widget.textbox.set_text.

See also:


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.

Type constraints:

  • text string New tooltip markup, passed to wibox.widget.textbox.set_markup.

See also:


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 text The new value affected to the property.
timeout number · 1 signal
Change the tooltip’s update interval.

Type constraints:

  • timeout number The timeout value.

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.

Usage example

Type constraints:

  • New number or table margins value.

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 New The new value affected to the property.
border_width number · 1 signal · 1 theme variable
The border width.

Usage example

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

Consumed theme variables:

Theme variable Usage
beautiful.tooltip_border_widthFallback when border_width isn't set.
border_color color · 1 signal
The border color.

Usage example

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 color The new value affected to the property.
margins_leftright number · 1 signal
Set the margins around the left and right of the tooltip textbox.

Usage example

Type constraints:

  • New number margins value.

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 New The new value affected to the property.
margins_topbottom number · 1 signal
Set the margins around the top and bottom of the tooltip textbox.

Usage example

Type constraints:

  • New number margins value.

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 New The new value affected to the property.
gaps number or table · 1 signal
Set the margins between the tooltip and its parent.

Usage example

Type constraints:

  • New number or table margins value.

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

Object methods

:add_to_object (self, obj)
Add tooltip to an object.

Parameters:

  • self tooltip The tooltip.
  • obj gears.object An object with mouse::enter and mouse::leave signals.
:remove_from_object (self, obj)
Remove tooltip from an object.

Parameters:

  • self tooltip The tooltip.
  • obj gears.object An object with mouse::enter and mouse::leave signals.
:emit_signal (name, ...) · Inherited from gears.object
Emit a signal.

Parameters:

  • 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 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 string The name of the signal.
  • func function The callback to call when the signal is emitted.

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.

Type constraints:

  • number opacity Between 0 and 1
beautiful.tooltip_gaps table
The tooltip margins.
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:

  • shape gears.shape A gears.shape compatible function (default gears.shape.rectangle)

See also:

beautiful.tooltip_align string
The default tooltip alignment.

See also:

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