awesome

• Index

Contents

• Functions
• Object properties
• Theme variables
• Deprecated functions
• Methods

Classes

• awful.button
• awful.keygrabber
• awful.popup
• awful.titlebar
• awful.tooltip
• awful.wibar
• awful.widget.button
• awful.widget.calendar_popup
• awful.widget.clienticon
• awful.widget.common
• awful.widget.keyboardlayout
• awful.widget.launcher
• awful.widget.layoutbox
• awful.widget.layoutlist
• awful.widget.only_on_screen
• awful.widget.prompt
• awful.widget.taglist
• awful.widget.tasklist
• awful.widget.textclock
• awful.widget.watch
• button
• client
• drawable
• gears.cache
• gears.matrix
• gears.object
• gears.timer
• key
• menubar.icon_theme
• menubar.index_theme
• screen
• signals
• tag
• wibox
• wibox.container.arcchart
• wibox.container.background
• wibox.container.constraint
• wibox.container.margin
• wibox.container.mirror
• wibox.container.place
• wibox.container.radialprogressbar
• wibox.container.rotate
• wibox.container.scroll
• wibox.drawable
• wibox.layout.align
• wibox.layout.fixed
• wibox.layout.flex
• wibox.layout.grid
• wibox.layout.manual
• wibox.layout.ratio
• wibox.layout.stack
• wibox.widget
• wibox.widget.base
• 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
• xproperties

Libraries

• awesome
• awful.client
• awful.completion
• awful.ewmh
• awful.hotkeys_popup
• awful.hotkeys_popup.widget
• awful.key
• awful.layout
• awful.menu
• awful.mouse
• awful.placement
• awful.prompt
• awful.rules
• awful.screen
• awful.spawn
• awful.tag
• awful.util
• awful.wibox
• beautiful
• beautiful.gtk
• dbus
• gears.color
• gears.debug
• gears.filesystem
• gears.geometry
• gears.math
• gears.protected_call
• gears.shape
• gears.sort
• gears.string
• gears.surface
• gears.table
• gears.wallpaper
• menubar
• menubar.menu_gen
• menubar.utils
• mouse
• mousegrabber
• naughty
• naughty.dbus
• root
• selection
• wibox.hierarchy

Sample files

• rc.lua
• theme.lua

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

Class awful.wibar

Wibox module for awful.

This module allows you to easily create wibox and attach them to the edge of a screen.

Info:

• Copyright: 2016 Emmanuel Lepage Vallee
• Author: Emmanuel Lepage Vallee <[email protected]>

Functions

awful.wibar ([args=nil])

Create a new wibox and attach it to a screen edge.

Object properties

stretch	If the wibar needs to be stretched to fill the screen.
width	The wibar’s width.
height	The wibar’s height.
position	The wibox position.
stretch	Stretch the wibar.
border_width	Border width.
border_color	Border color.
ontop	On top of other windows.
cursor	The mouse cursor.
visible	Visibility.
opacity	The opacity of the wibox, between 0 and 1.
type	The window type (desktop, normal, dock, …).
x	The x coordinates.
y	The y coordinates.
width	The width of the wibox.
height	The height of the wibox.
screen	The wibox screen.
drawable	The wibox’s drawable.
widget	The widget that the wibox displays.
window	The X window id.
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.
shape	The wibar’s shape.
input_passthrough	Forward the inputs to the client below the wibox.
bg	The background of the wibox.
bgimage	The background image of the drawable.
fg	The foreground (text) of the wibox.

Theme variables

beautiful.wibar_stretch	If the wibar needs to be stretched to fill the screen.
beautiful.wibar_border_width	The wibar border width.
beautiful.wibar_border_color	The wibar border color.
beautiful.wibar_ontop	If the wibar is to be on top of other windows.
beautiful.wibar_cursor	The wibar’s mouse cursor.
beautiful.wibar_opacity	The wibar opacity, between 0 and 1.
beautiful.wibar_type	The window type (desktop, normal, dock, …).
beautiful.wibar_width	The wibar’s width.
beautiful.wibar_height	The wibar’s height.
beautiful.wibar_bg	The wibar’s background color.
beautiful.wibar_bgimage	The wibar’s background image.
beautiful.wibar_fg	The wibar’s foreground (text) color.
beautiful.wibar_shape	The wibar’s shape.
beautiful.bg_normal	The default background color.
beautiful.fg_normal	The default foreground (text) color.

Deprecated functions

awful.wibar.get_position [deprecated]	Get a wibox position if it has been set, or return top.
awful.wibar.set_position [deprecated]	Put a wibox on a screen at this position.
awful.wibar.attach [deprecated]	Attach a wibox to a screen.
awful.wibar.align [deprecated]	Align a wibox.
awful.wibox.stretch [deprecated]	Stretch a wibox so it takes all screen width or height.

Methods

awful.wibar:remove ()	Remove a wibar.
awful.wibar:buttons (buttons_table)	Get or set mouse buttons bindings to a wibox.
awful.wibar:geometry (A)	Get or set wibox geometry.
awful.wibar:struts (strut)	Get or set wibox struts.
awful.wibar:setup (args)	Set a declarative widget hierarchy description.
awful.wibar:find_widgets (x, y)	Find a widget by a point.

Functions

Methods

awful.wibar ([args=nil])

Create a new wibox and attach it to a screen edge. You can add also position key with value top, bottom, left or right. You can also use width or height in % and set align to center, right or left. You can also set the screen key with a screen number to attach the wibox. If not specified, the primary screen is assumed.

• args
  • position string The position.
  • stretch string If the wibar need to be stretched to fill the screen.
  • 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)

Returns:

The new wibar

See also:

wibox

Object properties

stretch

If the wibar needs to be stretched to fill the screen.

Type:

• stretch boolean

width

The wibar’s width.

Type:

• width integer

height

The wibar’s height.

Type:

• height integer

position

The wibox position.

Type:

• string Either “left”, right", “top” or “bottom”

stretch

Stretch the wibar.

Type:

• boolean (default true)

border_width

Border width.

Signal:

• property::border_width

Type:

• integer

border_color

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

Signal:

• property::border_color

Type:

• string

ontop

On top of other windows.

Signal:

• property::ontop

Type:

• boolean

cursor

The mouse cursor.

Signal:

• property::cursor

Type:

• string

See also:

mouse

visible

Visibility.

Signal:

• property::visible

Type:

• boolean

opacity

The opacity of the wibox, between 0 and 1.

Signal:

• property::opacity

Type:

• opacity number (between 0 and 1)

type

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

Signal:

• property::type

Type:

• string

See also:

client.type

x

The x coordinates.

Signal:

• property::x

Type:

• integer

y

The y coordinates.

Signal:

• property::y

Type:

• integer

width

The width of the wibox.

Signal:

• property::width

Type:

• width

height

The height of the wibox.

Signal:

• property::height

Type:

• height

screen

The wibox screen.

Type:

• screen

drawable

The wibox’s drawable.

Signal:

• property::drawable

Type:

• drawable drawable

widget

The widget that the wibox displays.

Type:

• widget

window

The X window id.

Signal:

• property::window

Type:

• string

See also:

client.window

shape_bounding

The wibox’s bounding shape as a (native) cairo surface.

Signal:

• property::shape_bounding

shape_clip

The wibox’s clip shape as a (native) cairo surface.

Signal:

• property::shape_clip

shape_input

The wibox’s input shape as a (native) cairo surface.

Signal:

• property::shape_input

shape

The wibar’s shape.

Signal:

• property::shape

Type:

• shape gears.shape

input_passthrough

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.

Signal:

• property::input_passthrough

Type:

• boolean (default false)

See also:

shape_input

bg

The background of the wibox.

Type:

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

See also:

gears.color

bgimage

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:

• image A background image or a function

See also:

gears.surface

fg

The foreground (text) of the wibox.

Type:

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

See also:

gears.color

Theme variables

beautiful.wibar_stretch

If the wibar needs to be stretched to fill the screen.

Type:

• stretch boolean

beautiful.wibar_border_width

The wibar border width.

Type:

• border_width integer

beautiful.wibar_border_color

The wibar border color.

Type:

• border_color string

beautiful.wibar_ontop

If the wibar is to be on top of other windows.

Type:

• ontop boolean

beautiful.wibar_cursor

The wibar’s mouse cursor.

Type:

• cursor string

beautiful.wibar_opacity

The wibar opacity, between 0 and 1.

Type:

• opacity number

beautiful.wibar_type

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

Type:

• type string

beautiful.wibar_width

The wibar’s width.

Type:

• width integer

beautiful.wibar_height

The wibar’s height.

Type:

• height integer

beautiful.wibar_bg

The wibar’s background color.

Type:

• bg color

beautiful.wibar_bgimage

The wibar’s background image.

Type:

• bgimage surface

beautiful.wibar_fg

The wibar’s foreground (text) color.

Type:

• fg color

beautiful.wibar_shape

The wibar’s shape.

Type:

• shape gears.shape

beautiful.bg_normal

The default background color.

See also:

bg

beautiful.fg_normal

The default foreground (text) color.

See also:

fg

Deprecated functions

awful.wibar.get_position [deprecated]

Get a wibox position if it has been set, or return top.

param:

• wb The wibox

awful.wibar.set_position [deprecated]

Put a wibox on a screen at this position.

param:

• wb The wibox to attach.
• position The position: top, bottom left or right.
• screen This argument is deprecated, use wb.screen directly.

awful.wibar.attach [deprecated]

Attach a wibox to a screen.

This function has been moved to the awful.placement module. Calling this no longer does anything.

param:

• wb The wibox to attach.
• position The position of the wibox: top, bottom, left or right.
• screen The screen to attach to

See also:

awful.placement

awful.wibar.align [deprecated]

Align a wibox.

Supported alignment are:

• top_left
• top_right
• bottom_left
• bottom_right
• left
• right
• top
• bottom
• centered
• center_vertical
• center_horizontal

param:

• wb The wibox.
• align The alignment
• screen This argument is deprecated. It is not used. Use wb.screen directly.

See also:

awful.placement.align

awful.wibox.stretch [deprecated]

Stretch a wibox so it takes all screen width or height.

This function has been removed.

See also:

• awful.placement
• awful.wibar.stretch

Methods

awful.wibar:remove ()

Remove a wibar.

awful.wibar:buttons (buttons_table)

Get or set mouse buttons bindings to a wibox.

• buttons_table A table of buttons objects, or nothing.

awful.wibar:geometry (A)

Get or set wibox geometry. That’s the same as accessing or setting the x, y, width or height properties of a wibox.

• A table with coordinates to modify.

Returns:

A table with wibox coordinates and geometry.

awful.wibar:struts (strut)

Get or set wibox struts.

• strut A table with new strut, or nothing

Returns:

The wibox strut in a table.

See also:

client.struts

awful.wibar:setup (args)

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

• args An array containing the widgets disposition

awful.wibar:find_widgets (x, y)

Find a widget by a point. The wibox must have drawn itself at least once for this to work.

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