awesome

• Index

Contents

• Constructors
• Functions
• Object properties
• Deprecated object properties
• Object methods
• Signals

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

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

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 layouts

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

Popups and bars

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

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.ewmh
• awful.hotkeys_popup
• awful.layout
• 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.widget.common
• gears.cache
• gears.matrix
• menubar.icon_theme
• menubar.index_theme
• signals
• wibox.drawable
• wibox.hierarchy
• wibox.widget.base
• xproperties

Documentation

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

Module: wibox.container.background

A container capable of changing the background color, foreground color widget shape.

Info:

• Copyright: 2010 Uli Schlachter
• Author: Uli Schlachter

Constructors

wibox.container.background ([widget[, bg[, shape]]])

Returns a new background container.

Functions

wibox.container.background.add_button (button)

Add a new awful.button to this widget.

Object properties

widget	widget	The widget displayed in the background widget.
bg	bg	The background color/pattern/gradient to use.
fg	fg	The foreground (text) color/pattern/gradient to use.
shape	shape	The background shape.
border_width	number	Add a border of a specific width.
border_color	fg	Set the color for the border.
border_strategy	string	How the border width affects the contained widget.
bgimage	image	The background image to use If image is a function, it will be called with (context, cr, width, height) as arguments.
children	table	Get or set the children elements.
all_children	table	Get all direct and indirect children widgets.
forced_height	number or nil	Force a widget height.
forced_width	number or nil	Force a widget width.
opacity	number	The widget opacity (transparency).
visible	boolean	The widget visibility.
buttons	table	The widget buttons.

Deprecated object properties

shape_border_width	number	When a shape is set, also draw a border.
shape_border_color	fg	When a shape is set, also draw a border.

Object methods

:set_shape (shape)	Set the background shape.
:setup {[args]}	Set a declarative widget hierarchy description.
:emit_signal_recursive (signal_name, ...)	Emit a signal and ensure all parent widgets in the hierarchies also forward the signal.
:emit_signal (name, ...)	Emit a signal.
:connect_signal (name, func)	Connect to a signal.
:weak_connect_signal (name, func)	Connect to a signal weakly.

Signals

widget::layout_changed	When the layout (size) change.
widget::redraw_needed	When the widget content changed.
button::press	When a mouse button is pressed over the widget.
button::release	When a mouse button is released over the widget.
mouse::enter	When the mouse enter a widget.
mouse::leave	When the mouse leave a widget.

Constructors

wibox.container.background ([widget[, bg[, shape]]])

Returns a new background container.

A background container applies a background and foreground color to another widget.

Parameters:

• widget The widget to display. (optional)
• bg The background to use for that widget. (optional)
• shape A gears.shape compatible shape function (optional)

Functions

wibox.container.background.add_button (button)

Add a new awful.button to this widget.

Parameters:

• button awful.button The button to add.

Object properties

widget (widget)

The widget displayed in the background widget.

Type constraints:

• widget widget The widget to be disaplayed inside of the background area

bg (bg)

The background color/pattern/gradient to use.

Type constraints:

• bg A color string, pattern or gradient

See also:

gears.color

Usage:

local text_widget = {
    text   = 'Hello world!',
    widget = wibox.widget.textbox
}
parent : setup {
    {
        text_widget,
        bg     = '#ff0000',
        widget = wibox.container.background
    },
    {
        text_widget,
        bg     = '#00ff00',
        widget = wibox.container.background
    },
    {
        text_widget,
        bg     = '#0000ff',
        widget = wibox.container.background
    },
    spacing = 10,
    layout  = wibox.layout.fixed.vertical
}

fg (fg)

The foreground (text) color/pattern/gradient to use.

Type constraints:

• fg A color string, pattern or gradient

See also:

gears.color

Usage:

local text_widget = {
    text   = 'Hello world!',
    widget = wibox.widget.textbox
}
parent : setup {
    {
        text_widget,
        fg     = '#ff0000',
        widget = wibox.container.background
    },
    {
        text_widget,
        fg     = '#00ff00',
        widget = wibox.container.background
    },
    {
        text_widget,
        fg     = '#0000ff',
        widget = wibox.container.background
    },
    spacing = 10,
    layout  = wibox.layout.fixed.vertical
}

shape (shape)

The background shape.

Use set_shape to set additional shape paramaters.

Type constraints:

• shape A function taking a context, width and height as arguments

See also:

• gears.shape
• set_shape

Usage:

parent : setup {
    {
        -- Adding a shape without margin may result in cropped output
        {
            text   = 'Hello world!',
            widget = wibox.widget.textbox
        },
        shape              = gears.shape.hexagon,
        bg                 = beautiful.bg_normal,
        shape_border_color = beautiful.border_color,
        shape_border_width = beautiful.border_width,
        widget             = wibox.container.background
    },
    {
        -- To solve this, use a margin
        {
            {
                text   = 'Hello world!',
                widget = wibox.widget.textbox
            },
            left   = 10,
            right  = 10,
            top    = 3,
            bottom = 3,
            widget = wibox.container.margin
        },
        shape        = gears.shape.hexagon,
        bg           = beautiful.bg_normal,
        border_color = beautiful.border_color,
        border_width = beautiful.border_width,
        widget       = wibox.container.background
    },
    spacing = 10,
    layout  = wibox.layout.fixed.vertical
}

border_width (number)

Add a border of a specific width.

If the shape is set, the border will also be shaped.

See wibox.container.background.shape for an usage example.

Type constraints:

• width number The border width. (default 0)

See also:

border_color

border_color (fg)

Set the color for the border.

See wibox.container.background.shape for an usage example.

Type constraints:

• fg The border color, pattern or gradient (default self._private.foreground)

See also:

• gears.color
• border_width

border_strategy (string)

How the border width affects the contained widget.

The valid values are:

• none: Just apply the border, do not affect the content size (default).
• inner: Squeeze the size of the content by the border width.

bgimage (image)

The background image to use If image is a function, it will be called with (context, cr, width, height) as arguments. Any other arguments passed to this method will be appended.

Type constraints:

• image A background image or a function

See also:

gears.surface

children (table)

Get or set the children elements.

Type constraints:

• The table children

all_children (table)

Get all direct and indirect children widgets. This will scan all containers recursively to find widgets Warning: This method it prone to stack overflow id the widget, or any of its children, contain (directly or indirectly) itself.

Type constraints:

• The table children

forced_height (number or nil)

Force a widget height.

Type constraints:

• height number or nil The height (nil for automatic)

forced_width (number or nil)

Force a widget width.

Type constraints:

• width number or nil The width (nil for automatic)

opacity (number)

The widget opacity (transparency).

Type constraints:

• opacity number The opacity (between 0 and 1) (default 1)

visible (boolean)

The widget visibility.

buttons (table)

The widget buttons.

The table contains a list of awful.button objects.

See also:

awful.button

Deprecated object properties

shape_border_width (number)

When a shape is set, also draw a border.

See wibox.container.background.shape for an usage example.

Type constraints:

• width number The border width

See also:

border_width

shape_border_color (fg)

When a shape is set, also draw a border.

See wibox.container.background.shape for an usage example.

Type constraints:

• fg The border color, pattern or gradient (default self._private.foreground)

See also:

• gears.color
• border_color

Object methods

:set_shape (shape)

Set the background shape.

Any other arguments will be passed to the shape function

Parameters:

• shape A function taking a context, width and height as arguments

See also:

• gears.shape
• shape

:setup {[args]}

Set a declarative widget hierarchy description. See The declarative layout system

Parameters:

• args An array containing the widgets disposition

:emit_signal_recursive (signal_name, ...)

Emit a signal and ensure all parent widgets in the hierarchies also forward the signal. This is useful to track signals when there is a dynamic set of containers and layouts wrapping the widget.

Parameters:

• signal_name string
• ... Other arguments

:emit_signal (name, ...)

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)

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)

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.

Signals

widget::layout_changed

When the layout (size) change. This signal is emitted when the previous results of :layout() and :fit() are no longer valid. Unless this signal is emitted, :layout() and :fit() must return the same result when called with the same arguments.

See also:

widget::redraw_needed

widget::redraw_needed

When the widget content changed. This signal is emitted when the content of the widget changes. The widget will be redrawn, it is not re-layouted. Put differently, it is assumed that :layout() and :fit() would still return the same results as before.

See also:

widget::layout_changed

button::press

When a mouse button is pressed over the widget.

Arguments:

• lx number The horizontal position relative to the (0,0) position in the widget.
• ly number The vertical position relative to the (0,0) position in the widget.
• button number The button number.
• mods table The modifiers (mod4, mod1 (alt), Control, Shift)
• find_widgets_result The entry from the result of wibox.drawable:find_widgets for the position that the mouse hit.
  • drawable wibox.drawable The drawable containing the widget.
  • widget widget The widget being displayed.
  • hierarchy wibox.hierarchy The hierarchy managing the widget’s geometry.
  • x number An approximation of the X position that the widget is visible at on the surface.
  • y number An approximation of the Y position that the widget is visible at on the surface.
  • width number An approximation of the width that the widget is visible at on the surface.
  • height number An approximation of the height that the widget is visible at on the surface.
  • widget_width number The exact width of the widget in its local coordinate system.
  • widget_height number The exact height of the widget in its local coordinate system.

See also:

mouse

button::release

When a mouse button is released over the widget.

Arguments:

• lx number The horizontal position relative to the (0,0) position in the widget.
• ly number The vertical position relative to the (0,0) position in the widget.
• button number The button number.
• mods table The modifiers (mod4, mod1 (alt), Control, Shift)
• find_widgets_result The entry from the result of wibox.drawable:find_widgets for the position that the mouse hit.
  • drawable wibox.drawable The drawable containing the widget.
  • widget widget The widget being displayed.
  • hierarchy wibox.hierarchy The hierarchy managing the widget’s geometry.
  • x number An approximation of the X position that the widget is visible at on the surface.
  • y number An approximation of the Y position that the widget is visible at on the surface.
  • width number An approximation of the width that the widget is visible at on the surface.
  • height number An approximation of the height that the widget is visible at on the surface.
  • widget_width number The exact width of the widget in its local coordinate system.
  • widget_height number The exact height of the widget in its local coordinate system.

See also:

mouse

mouse::enter

When the mouse enter a widget.

Arguments:

• find_widgets_result The entry from the result of wibox.drawable:find_widgets for the position that the mouse hit.
  • drawable wibox.drawable The drawable containing the widget.
  • widget widget The widget being displayed.
  • hierarchy wibox.hierarchy The hierarchy managing the widget’s geometry.
  • x number An approximation of the X position that the widget is visible at on the surface.
  • y number An approximation of the Y position that the widget is visible at on the surface.
  • width number An approximation of the width that the widget is visible at on the surface.
  • height number An approximation of the height that the widget is visible at on the surface.
  • widget_width number The exact width of the widget in its local coordinate system.
  • widget_height number The exact height of the widget in its local coordinate system.

See also:

mouse

mouse::leave

When the mouse leave a widget.

Arguments:

• find_widgets_result The entry from the result of wibox.drawable:find_widgets for the position that the mouse hit.
  • drawable wibox.drawable The drawable containing the widget.
  • widget widget The widget being displayed.
  • hierarchy wibox.hierarchy The hierarchy managing the widget’s geometry.
  • x number An approximation of the X position that the widget is visible at on the surface.
  • y number An approximation of the Y position that the widget is visible at on the surface.
  • width number An approximation of the width that the widget is visible at on the surface.
  • height number An approximation of the height that the widget is visible at on the surface.
  • widget_width number The exact width of the widget in its local coordinate system.
  • widget_height number The exact height of the widget in its local coordinate system.

See also:

mouse