Module: awful.popup

An auto-resized, free floating or modal wibox built around a widget.

This type of widget box (wibox) is auto closed when being clicked on and is automatically resized to the size of its main widget.

Note that the widget itself should have a finite size. If something like a wibox.layout.flex is used, then the size would be unlimited and an error will be printed. The wibox.layout.fixed, wibox.container.constraint, forced_width and forced_height are recommended.

Usage example

awful.popup {
    widget = {
        {
            {
                text   = 'foobar',
                widget = wibox.widget.textbox
            },
            {
                {
                    text   = 'foobar',
                    widget = wibox.widget.textbox
                },
                bg     = '#ff00ff',
                clip   = true,
                shape  = gears.shape.rounded_bar,
                widget = wibox.widget.background
            },
            {
                value         = 0.5,
                forced_height = 30,
                forced_width  = 100,
                widget        = wibox.widget.progressbar
            },
            layout = wibox.layout.fixed.vertical,
        },
        margins = 10,
        widget  = wibox.container.margin
    },
    border_color = '#00ff00',
    border_width = 5,
    placement    = awful.placement.top_left,
    shape        = gears.shape.rounded_rect,
    visible      = true,
}

Here is an example of how to create an alt-tab like dialog by leveraging the awful.widget.tasklist.

Usage example

awful.popup {
    widget = awful.widget.tasklist {
        screen   = screen[1],
        filter   = awful.widget.tasklist.filter.allscreen,
        buttons  = tasklist_buttons,
        style    = {
            shape = gears.shape.rounded_rect,
        },
        layout   = {
            spacing = 5,
            forced_num_rows = 2,
            layout = wibox.layout.grid.horizontal
        },
        widget_template = {
            {
                {
                    id     = 'clienticon',
                    widget = awful.widget.clienticon,
                },
                margins = 4,
                widget  = wibox.container.margin,
            },
            id              = 'background_role',
            forced_width    = 48,
            forced_height   = 48,
            widget          = wibox.container.background,
            create_callback = function(self, c, index, objects) --luacheck: no unused
                self:get_children_by_id('clienticon')[1].client = c
            end,
        },
    },
    border_color = '#777777',
    border_width = 2,
    ontop        = true,
    placement    = awful.placement.centered,
    shape        = gears.shape.rounded_rect
}

Info:

  • Copyright: 2016 Emmanuel Lepage Vallee
  • Author: Emmanuel Lepage Vallee

Constructors

awful.popup {[args]} Create a new popup build around a passed in widget.

Object properties

preferred_positions table or string Set the preferred popup position relative to its parent.
preferred_anchors table or string Set the preferred popup anchors relative to the parent.
current_position string The current position relative to the parent object.
current_anchor string Get the current anchor relative to the parent object.
hide_on_right_click boolean Hide the popup when right clicked.
minimum_width number The popup minimum width.
minimum_height number The popup minimum height.
maximum_width number The popup maximum width.
maximum_height number The popup maximum height.
offset table or number The distance between the popup and its parent (if any).
placement function or string or boolean Set the placement function.
border_width integer Border width. Inherited from wibox
border_color string Border color. Inherited from wibox
ontop boolean On top of other windows. Inherited from wibox
cursor string The mouse cursor. Inherited from wibox
visible boolean Visibility. 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 width The width of the wibox. Inherited from wibox
height height The height of the wibox. Inherited from wibox
screen screen The wibox screen. Inherited from wibox
drawable drawable The wibox’s drawable. Inherited from wibox
widget widget The widget that the wibox displays. Inherited from wibox
window string The X window id. Inherited from wibox
shape_bounding N/A The wibox’s bounding shape as a (native) cairo surface. Inherited from wibox
shape_clip N/A The wibox’s clip shape as a (native) cairo surface. Inherited from wibox
shape_input N/A The wibox’s input shape as a (native) cairo surface. Inherited from wibox
shape gears.shape The wibar’s shape. Inherited from wibox
input_passthrough boolean Forward the inputs to the client below the wibox. Inherited from wibox
buttons buttons_table Get or set mouse buttons bindings to a wibox. Inherited from wibox
bg c The background of the wibox. Inherited from wibox
bgimage gears.suface or string or function The background image of the drawable. Inherited from wibox
fg color The foreground (text) of the wibox. Inherited from wibox

Object methods

:move_next_to ([obj=mouse]) Move the wibox to a position relative to geo.
:bind_to_widget (widget[, button=1]) Bind the popup to a widget button press.
:unbind_to_widget (widget) Unbind the popup from a widget button.
:geometry (A) Get or set wibox geometry. Inherited from wibox
:struts (strut) Get or set wibox struts. Inherited from wibox
:setup {[args]} Set a declarative widget hierarchy description. Inherited from wibox
:find_widgets (x, y) Find a widget by a point. Inherited from wibox

Theme variables

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


Constructors

awful.popup {[args]}
Create a new popup build around a passed in widget.

Parameters:

  • args
    • border_width integer Border width.
    • border_color string Border color.
    • ontop boolean On top of other windows. (default false)
    • cursor string The mouse cursor.
    • visible boolean Visibility.
    • opacity number The opacity, between 0 and 1. (default 1)
    • type string The window type (desktop, normal, dock, …).
    • x integer The x coordinates.
    • y integer The y coordinates.
    • width integer The width.
    • height integer The height.
    • screen screen The wibox screen.
    • widget wibox.widget The widget that the wibox displays.
    • shape_bounding The wibox’s bounding shape as a (native) cairo surface.
    • shape_clip The wibox’s clip shape as a (native) cairo surface.
    • shape_input The wibox’s input shape as a (native) cairo surface.
    • bg color The background.
    • bgimage surface The background image of the drawable.
    • fg color The foreground (text) color.
    • shape gears.shape The shape.
    • input_passthrough boolean If the inputs are forward to the element below. (default false)
    • placement function The awful.placement function
    • preferred_positions string or table
    • preferred_anchors string or table
    • offset table or number The X and Y offset compared to the parent object
    • hide_on_right_click boolean Whether or not to hide the popup on right clicks.

Object properties

preferred_positions (table or string) · 1 signal

Set the preferred popup position relative to its parent.

This allows, for example, to have a submenu that goes on the right of the parent menu. If there is no space on the right, it tries on the left and so on.

Valid directions are:

  • left
  • right
  • top
  • bottom

The basic use case for this method is to give it a parent wibox:

Usage example

for _, v in ipairs {'left', 'right', 'bottom', 'top'} do
    local p2 = awful.popup {
        widget = wibox.widget {
            text   = 'On the '..v,
            widget = wibox.widget.textbox
        },
        border_color        = '#777777',
        border_width        = 2,
        preferred_positions = v,
        ontop               = true,
    }
    p2:move_next_to(p)
end

As demonstrated by this second example, it is also possible to use a widget as a parent object:

Usage example

for _, v in ipairs {'left', 'right'} do
    local p2 = awful.popup {
        widget = wibox.widget {
            text = 'On the '..v,
            forced_height = 100,
            widget = wibox.widget.textbox
        },
        border_color  = '#0000ff',
        preferred_positions = v,
        border_width  = 2,
    }
    p2:move_next_to(textboxinstance, v)
end

Type constraints:

  • preferred_positions table or string A position name or an ordered table of positions

See also:


Click to display more

Emit signals:

  • property::preferred_positions When the preferred_positions value changes.
    • self awful.popup 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_anchors (table or string) · 1 signal

Set the preferred popup anchors relative to the parent.

The possible values are:

  • front
  • middle
  • back

For details information, see the awful.placement.next_to documentation.

In this example, it is possible to see the effect of having a fallback preferred anchors when the popup would otherwise not fit:

Usage example

 local p2 = awful.popup {
     widget = wibox.widget {
         text   = 'A popup',
         forced_height = 100,
         widget = wibox.widget.textbox
     },
     border_color        = '#777777',
     border_width        = 2,
     preferred_positions = 'right',
     preferred_anchors   = {'front', 'back'},
 }
 local p4 = awful.popup {
     widget = wibox.widget {
         text   = 'A popup2',
         forced_height = 100,
         widget = wibox.widget.textbox
     },
     border_color        = '#777777',
     border_width        = 2,
     preferred_positions = 'right',
     preferred_anchors   = {'front', 'back'},
 }

Type constraints:

  • preferred_anchors table or string Either a single anchor name or a table ordered by priority.

See also:


Click to display more

Emit signals:

  • property::preferred_anchors When the preferred_anchors value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
    • new_value preferred_anchors The new value affected to the property.
current_position (string)
The current position relative to the parent object.

If there is a parent object (widget, wibox, wibar, client or the mouse), then this property returns the current position. This is determined using preferred_positions. It is usually the preferred position, but when there isn’t enough space, it can also be one of the fallback.

Type constraints:

  • current_position string Either “left”, “right”, “top” or “bottom”
current_anchor (string)
Get the current anchor relative to the parent object.

If there is a parent object (widget, wibox, wibar, client or the mouse), then this property returns the current anchor. The anchor is the “side” of the parent object on which the popup is based on. It will “grow” in the opposite direction from the anchor.

Type constraints:

  • current_anchor string Either “front”, “middle”, “back”
hide_on_right_click (boolean) · 1 signal
Hide the popup when right clicked.
Click to display more

Emit signals:

  • property::hide_on_right_click When the hide_on_right_click value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
    • new_value hide_on_right_click The new value affected to the property.
minimum_width (number) · 1 signal
The popup minimum width.

Type constraints:

  • minimum_width number The minimum width. (default 1)

Click to display more

Emit signals:

  • property::minimum_width When the minimum_width value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
    • new_value minimum_width The new value affected to the property.
minimum_height (number) · 1 signal
The popup minimum height.

Type constraints:

  • minimum_height number The minimum height. (default 1)

Click to display more

Emit signals:

  • property::minimum_height When the minimum_height value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
    • new_value minimum_height The new value affected to the property.
maximum_width (number) · 1 signal
The popup maximum width.

Type constraints:

  • maximum_width number The maximum width. (default 1)

Click to display more

Emit signals:

  • property::maximum_width When the maximum_width value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
    • new_value maximum_width The new value affected to the property.
maximum_height (number) · 1 signal
The popup maximum height.

Type constraints:

  • maximum_height number The maximum height. (default 1)

Click to display more

Emit signals:

  • property::maximum_height When the maximum_height value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
    • new_value maximum_height The new value affected to the property.
offset (table or number) · 1 signal

The distance between the popup and its parent (if any).

Here is an example of 5 popups stacked one below the other with an y axis offset (spacing).

Usage example

local previous = nil
for i=1, 5 do
    local p2 = awful.popup {
        widget = wibox.widget {
            text   = 'Hello world!  '..i..'  aaaa.',
            widget = wibox.widget.textbox
        },
        border_color        = beautiful.border_color,
        preferred_positions = 'bottom',
        border_width        = 2,
        preferred_anchors   = 'back',
        placement           = (not previous) and awful.placement.top or nil,
        offset = {
             y = 10,
        },
    }
    p2:move_next_to(previous)
    previous = p2
end

Type constraints:

  • offset An integer value or a {x=, y=} table.
    • x number The horizontal distance. (default offset)
    • y number The vertical distance. (default offset)

Click to display more

Emit signals:

  • property::offset When the offset value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
    • new_value offset The new value affected to the property.
placement (function or string or boolean) · 1 signal
Set the placement function.

Type constraints:

  • The function, string or boolean placement function or name (or false to disable placement) (default next_to)
  • function

See also:


Click to display more

Emit signals:

  • property::placement When the placement value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
    • new_value The The new value affected to the property.
border_width (integer) · Inherited from wibox · 1 signal
Border width.
Click to display more

Emit signals:

  • property::border_width When the border_width value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
border_color (string) · Inherited from wibox · 1 signal

Border color.

Please note that this property only support string based 24 bit or 32 bit colors:

Red Blue
 _|  _|
#FF00FF
   T‾
 Green


Red Blue
 _|  _|
#FF00FF00
   T‾  ‾T
Green   Alpha

Click to display more

Emit signals:

  • property::border_color When the border_color value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
ontop (boolean) · Inherited from wibox · 1 signal
On top of other windows.
Click to display more

Emit signals:

  • property::ontop When the ontop value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
cursor (string) · Inherited from wibox · 1 signal
The mouse cursor.

See also:


Click to display more

Emit signals:

  • property::cursor When the cursor value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
visible (boolean) · Inherited from wibox · 1 signal
Visibility.
Click to display more

Emit signals:

  • property::visible When the visible value changes.
    • self awful.popup 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.

Type constraints:

  • opacity number (between 0 and 1)

Click to display more

Emit signals:

  • property::opacity When the opacity value changes.
    • self awful.popup 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, …).

See also:


Click to display more

Emit signals:

  • property::type When the type value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
x (integer) · Inherited from wibox · 1 signal
The x coordinates.
Click to display more

Emit signals:

  • property::x When the x value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
y (integer) · Inherited from wibox · 1 signal
The y coordinates.
Click to display more

Emit signals:

  • property::y When the y value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
width (width) · Inherited from wibox · 1 signal
The width of the wibox.
Click to display more

Emit signals:

  • property::width When the width value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
height (height) · Inherited from wibox · 1 signal
The height of the wibox.
Click to display more

Emit signals:

  • property::height When the height value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
screen (screen) · Inherited from wibox · 1 signal
The wibox screen.
Click to display more

Emit signals:

  • property::screen When the screen value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
    • new_value screen The new value affected to the property.
drawable (drawable) · Inherited from wibox · 1 signal
The wibox’s drawable.
Click to display more

Emit signals:

  • property::drawable When the drawable value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
widget (widget) · Inherited from wibox · 1 signal
The widget that the wibox displays.
Click to display more

Emit signals:

  • property::widget When the widget value changes.
    • self awful.popup 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.

See also:


Click to display more

Emit signals:

  • property::window When the window value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
shape_bounding (N/A) · 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.

See also:


Click to display more

Emit signals:

  • property::shape_bounding When the shape_bounding value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
shape_clip (N/A) · 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.

See also:


Click to display more

Emit signals:

  • property::shape_clip When the shape_clip value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
shape_input (N/A) · 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.

See also:


Click to display more

Emit signals:

  • property::shape_input When the shape_input value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
shape (gears.shape) · Inherited from wibox · 1 signal
The wibar’s shape.

See also:


Click to display more

Emit signals:

  • property::shape When the shape value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
    • new_value shape The new value affected to the property.
input_passthrough (boolean) · 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.

See also:


Click to display more

Emit signals:

  • property::input_passthrough When the input_passthrough value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
    • new_value boolean The new value affected to the property.
buttons (buttons_table) · Inherited from wibox · 1 signal
Get or set mouse buttons bindings to a wibox.

Type constraints:

  • buttons_table A table of buttons objects, or nothing.

Click to display more

Emit signals:

  • property::buttons When the buttons value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
bg (c) · 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.

Type constraints:

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

See also:


Click to display more

Emit signals:

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

Consumed theme variables:

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

Type constraints:

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

See also:


Click to display more

Emit signals:

  • property::bgimage When the bgimage value changes.
    • self awful.popup The object which changed (useful when connecting many object to the same callback).
    • new_value image The new value affected to the property.
fg (color) · Inherited from wibox · 1 signal · 1 theme variable
The foreground (text) of the wibox.

Type constraints:

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

See also:


Click to display more

Emit signals:

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

Consumed theme variables:

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

Object methods

:move_next_to ([obj=mouse])
Move the wibox to a position relative to geo. This will try to avoid overlapping the source wibox and auto-detect the right direction to avoid going off-screen.

Parameters:

  • obj An object such as a wibox, client or a table entry returned by wibox:find_widgets(). (default mouse)

Returns:

    table The new geometry

See also:

:bind_to_widget (widget[, button=1])
Bind the popup to a widget button press.

Parameters:

  • widget widget The widget
  • button number The button index (default 1)
:unbind_to_widget (widget)
Unbind the popup from a widget button.

Parameters:

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

  • A table with coordinates to modify.

Returns:

    A table with wibox coordinates and geometry.

Click to display more

Emit signals:

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

  • strut A table with new strut, or nothing

Returns:

    The wibox strut in a table.

See also:


Click to display more

Emit signals:

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

Parameters:

  • args An array containing the widgets disposition
:find_widgets (x, y) · Inherited from wibox
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.bg_normal (color) · Inherited from wibox
The default background color.

The background color can be transparent. If there is a compositing manager such as compton, then it will be real transparency and may include blur (provided by the compositor). When there is no compositor, it will take a picture of the wallpaper and blend it.

See also:

beautiful.fg_normal (color) · Inherited from wibox
The default foreground (text) color.

See also:

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