awesome

• Index

Contents

• Static module functions
• Request handlers
• Theme variables
• Client layouts
• Fields

Libraries

• awful.completion
• awful.hotkeys_popup
• awful.layout
• awful.permissions
• awful.placement
• awful.prompt
• awful.rules
• awful.spawn
• awful.util
• dbus
• gears.matcher
• gears.surface
• menubar.menu_gen
• menubar.utils
• naughty
• selection
• wibox.widget

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

Declarative rules

• ruled.client
• ruled.notifications

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 containers

• awful.widget.only_on_screen
• naughty.widget.background
• wibox.container.arcchart
• wibox.container.background
• wibox.container.border
• wibox.container.constraint
• wibox.container.margin
• wibox.container.mirror
• wibox.container.place
• wibox.container.radialprogressbar
• wibox.container.rotate
• wibox.container.scroll
• wibox.container.tile

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

Sample files

• rc.lua
• theme.lua

Classes

• awful.screenshot
• awful.widget.common
• gears.cache
• gears.matrix
• menubar.icon_theme
• menubar.index_theme
• wibox.hierarchy
• wibox.widget.base
• xproperties

Documentation

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

Module: awful.layout

Deterministically lay the clients in a screen workarea.

The awful.layout module contains many sub-modules. Each of them contain one or more layout. awful.layout offers static layouts rather than tree based like other WMs. The layout have a small number of configuration variables:

• master_width_factor: The ratio between the main (master) section of the layout and a sub-section. For example, in the tile.left layout, the main (master) part contains master_count clients and the secondary part contains all other clients.
• master_count: The number of clients which belong to the main (master) area.
• column_count: The number of columns to store the clients in the secondary area.
• master_fill_policy: When the number of clients is below master_count, how is the remaining space used.
• gaps: The empty space between the clients.
• gap_single_client: Same as gap, but when there is a single client. Gaps are often useful as a visual cue to know where a client starts and ends. This makes no sense when there is only one.

Not all layouts make use of all variables. Having such an overloaded meaning to a small set of variable is useful to attach those values to keybindings without having special logic for each layouts. AwesomeWM keybindings are not modal, so such "limitation" actually improves usability.

Static module functions

awful.layout.get_tag_layout_index (t) -> nil or number	Return the tag layout index (from awful.layout.layouts).
awful.layout.get (screen) -> ()	Get the current layout.
awful.layout.inc (i, s, layouts)	Change the layout of the current tag.
awful.layout.set (l, t)	Set the layout function of the current tag.
awful.layout.parameters (t, screen) -> table	Get the layout parameters used for the screen This should give the same result as "arrange", but without the "geometries" parameter, as this is computed during arranging.
awful.layout.arrange (screen)	Arrange a screen using its current layout.
awful.layout.append_default_layout (to_add)	Append a layout to the list of default tag layouts.
awful.layout.remove_default_layout (to_remove) -> boolean	Remove a layout from the list of default layouts.
awful.layout.append_default_layouts (layouts)	Append many layouts to the list of default tag layouts.
awful.layout.getname (_layout) -> ()	Get the current layout name.

Request handlers

awful.layout.move_handler (c, context, hints)

Default handler for request::geometry signals for tiled clients with the "mouse.move" context.

Theme variables

beautiful.layout_cornernw	surface	The cornernw layout layoutbox icon.
beautiful.layout_cornerne	surface	The cornerne layout layoutbox icon.
beautiful.layout_cornersw	surface	The cornersw layout layoutbox icon.
beautiful.layout_cornerse	surface	The cornerse layout layoutbox icon.
beautiful.layout_fairh	surface	The fairh layout layoutbox icon.
beautiful.layout_fairv	surface	The fairv layout layoutbox icon.
beautiful.layout_floating	surface	The floating layout layoutbox icon.
beautiful.layout_magnifier	surface	The magnifier layout layoutbox icon.
beautiful.layout_max	surface	The max layout layoutbox icon.
beautiful.layout_fullscreen	surface	The fullscreen layout layoutbox icon.
beautiful.layout_spiral	surface	The spiral layout layoutbox icon.
beautiful.layout_dwindle	surface	The dwindle layout layoutbox icon.
beautiful.layout_tile	surface	The tile layout layoutbox icon.
beautiful.layout_tiletop	surface	The tile top layout layoutbox icon.
beautiful.layout_tilebottom	surface	The tile bottom layout layoutbox icon.
beautiful.layout_tileleft	surface	The tile left layout layoutbox icon.

Client layouts

awful.layout.suit.corner.nw	Corner layout.
awful.layout.suit.corner.ne	Corner layout.
awful.layout.suit.corner.sw	Corner layout.
awful.layout.suit.corner.se	Corner layout.
awful.layout.suit.fair	The fair layout.
awful.layout.suit.fair.horizontal	The horizontal fair layout.
awful.layout.suit.floating	The floating layout.
awful.layout.suit.magnifier	The magnifier layout.
awful.layout.suit.max	Maximized layout.
awful.layout.suit.max.fullscreen	Fullscreen layout.
awful.layout.suit.spiral.dwindle	Dwindle layout.
awful.layout.suit.spiral.name	Spiral layout.
awful.layout.suit.tile.right	The main tile algo, on the right.
awful.layout.suit.tile.left	The main tile algo, on the left.
awful.layout.suit.tile.bottom	The main tile algo, on the bottom.
awful.layout.suit.tile.top	The main tile algo, on the top.

Fields

awful.layout.layouts	N/A	The default list of layouts.
awful.layout.floating.resize_jump_to_corner	N/A	Jump mouse cursor to the client's corner when resizing it.
awful.layout.tile.resize_jump_to_corner	N/A	Jump mouse cursor to the client's corner when resizing it.

Static module functions

🔗 awful.layout.get_tag_layout_index (t) -> nil or number

Return the tag layout index (from awful.layout.layouts).

If the layout isn't part of awful.layout.layouts, this function returns nil.

Parameters:

Name		Type(s)	Description
t		tag	The tag.

Returns:

nil or number The layout index.

🔗 awful.layout.get (screen) -> ()

Get the current layout.

Parameters:

Name		Type(s)	Description
screen		screen	The screen.

Returns:

The layout function.

🔗 awful.layout.inc (i, s, layouts)

Change the layout of the current tag.

Parameters:

Name		Type(s)	Description	Default value
i		integer	Relative index.	Not applicable
s		screen	The screen.	Not applicable
layouts	Optional	table	A table of layouts.	s.selected_tag.layouts

🔗 awful.layout.set (l, t)

Set the layout function of the current tag.

Parameters:

Name		Type(s)	Description	Default value
l		layout or function	Layout object or function.	Not applicable
t	Optional	tag	The tag to modify.	mouse.screen.selected_tag

🔗 awful.layout.parameters (t, screen) -> table

Get the layout parameters used for the screen

This should give the same result as "arrange", but without the "geometries" parameter, as this is computed during arranging.

If t is given, screen is ignored, if none are given, the mouse screen is used.

Parameters:

Name		Type(s)	Description
t	Optional	tag	The tag to query
screen	Optional		The screen

Returns:

table A table with the workarea (x, y, width, height), the screen geometry (x, y, width, height), the clients, the screen and sometime, a "geometries" table with client as keys and geometry as value

🔗 awful.layout.arrange (screen)

Arrange a screen using its current layout.

Parameters:

Name		Type(s)	Description
screen		screen	The screen to arrange.

🔗 awful.layout.append_default_layout (to_add)

Append a layout to the list of default tag layouts.

Parameters:

Name		Type(s)	Description
to_add		layout	A valid tag layout.

See also:

awful.layout.layouts	The default list of layouts.	fields

🔗 awful.layout.remove_default_layout (to_remove) -> boolean

Remove a layout from the list of default layouts.

Usage example output:

Before: floating
Before: tile
Before: max
After:  floating
After:  max

Parameters:

Name		Type(s)	Description
to_remove		layout	A valid tag layout.

Returns:

boolean True if the layout was found and removed.

See also:

awful.layout.layouts	The default list of layouts.	fields

Usage:

awful.layout.append_default_layouts({
    awful.layout.suit.floating,
    awful.layout.suit.tile,
    awful.layout.suit.max,
})
for _, l in ipairs(awful.layout.layouts) do
    print("Before:", l.name)
end

awful.layout.remove_default_layout(awful.layout.suit.tile)

for _, l in ipairs(awful.layout.layouts) do
    print("After:", l.name)
end

🔗 awful.layout.append_default_layouts (layouts)

Append many layouts to the list of default tag layouts.

Parameters:

Name		Type(s)	Description
layouts		table	A table of valid tag layout.

See also:

awful.layout.layouts	The default list of layouts.	fields

🔗 awful.layout.getname (_layout) -> ()

Get the current layout name.

Parameters:

Name		Type(s)	Description
_layout			The layout.

Returns:

The layout name.

Request handlers

🔗 awful.layout.move_handler (c, context, hints)

Default handler for request::geometry signals for tiled clients with the "mouse.move" context.

Arguments:

Name		Type(s)	Description
c		client	The client
context		string	The context
hints		table	Additional hints

Theme variables

🔗 beautiful.layout_cornernw surface

The cornernw layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.corner.nw Corner layout.

🔗 beautiful.layout_cornerne surface

The cornerne layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.corner.ne Corner layout.

🔗 beautiful.layout_cornersw surface

The cornersw layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.corner.sw Corner layout.

🔗 beautiful.layout_cornerse surface

The cornerse layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.corner.se Corner layout.

🔗 beautiful.layout_fairh surface

The fairh layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.fair.horizontal The horizontal fair layout.

🔗 beautiful.layout_fairv surface

The fairv layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.fair The fair layout.

🔗 beautiful.layout_floating surface

The floating layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.floating The floating layout.

🔗 beautiful.layout_magnifier surface

The magnifier layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.magnifier The magnifier layout.

🔗 beautiful.layout_max surface

The max layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.max Maximized layout.

🔗 beautiful.layout_fullscreen surface

The fullscreen layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.max.fullscreen Fullscreen layout.

🔗 beautiful.layout_spiral surface

The spiral layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.spiral.name Spiral layout.

🔗 beautiful.layout_dwindle surface

The dwindle layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.spiral.dwindle Dwindle layout.

🔗 beautiful.layout_tile surface

The tile layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.tile.right The main tile algo, on the right.

🔗 beautiful.layout_tiletop surface

The tile top layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.tile.top The main tile algo, on the top.

🔗 beautiful.layout_tilebottom surface

The tile bottom layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.tile.bottom The main tile algo, on the bottom.

🔗 beautiful.layout_tileleft surface

The tile left layout layoutbox icon.

See also:

gears.surface	Utilities to integrate and manipulate Cairo drawing surfaces.	module

Click to display more

Used by:

• awful.layout.suit.tile.left The main tile algo, on the left.

Client layouts

🔗 awful.layout.suit.corner.nw · 1 theme variable

Corner layout. Display master client in a corner of the screen, and slaves in one column and one row around the master.
Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_cornernw

🔗 awful.layout.suit.corner.ne · 1 theme variable

Corner layout. Display master client in a corner of the screen, and slaves in one column and one row around the master.
Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_cornerne

🔗 awful.layout.suit.corner.sw · 1 theme variable

Corner layout. Display master client in a corner of the screen, and slaves in one column and one row around the master.
Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_cornersw

🔗 awful.layout.suit.corner.se · 1 theme variable

Corner layout. Display master client in a corner of the screen, and slaves in one column and one row around the master.
Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_cornerse

🔗 awful.layout.suit.fair · 1 theme variable

The fair layout. Try to give all clients the same size.
Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_fairv

🔗 awful.layout.suit.fair.horizontal · 1 theme variable

The horizontal fair layout. Try to give all clients the same size.
Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_fairh

🔗 awful.layout.suit.floating · 1 theme variable

The floating layout.
Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_floating

🔗 awful.layout.suit.magnifier · 1 theme variable

The magnifier layout.
Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_magnifier

🔗 awful.layout.suit.max · 1 theme variable

Maximized layout.
Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_max

🔗 awful.layout.suit.max.fullscreen · 1 theme variable

Fullscreen layout.
Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_fullscreen

🔗 awful.layout.suit.spiral.dwindle · 1 theme variable

Dwindle layout.
Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_dwindle

🔗 awful.layout.suit.spiral.name · 1 theme variable

Spiral layout.
Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_spiral

🔗 awful.layout.suit.tile.right · 1 theme variable

The main tile algo, on the right.

Parameters:

Name		Type(s)	Description
screen			The screen number to tile.

Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_tile

🔗 awful.layout.suit.tile.left · 1 theme variable

The main tile algo, on the left.

Parameters:

Name		Type(s)	Description
screen			The screen number to tile.

Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_tileleft

🔗 awful.layout.suit.tile.bottom · 1 theme variable

The main tile algo, on the bottom.

Parameters:

Name		Type(s)	Description
screen			The screen number to tile.

Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_tilebottom

🔗 awful.layout.suit.tile.top · 1 theme variable

The main tile algo, on the top.

Parameters:

Name		Type(s)	Description
screen			The screen number to tile.

Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.layout_tiletop

Fields

🔗 awful.layout.layouts N/A

The default list of layouts.

The default value is:

awful.layout.suit.floating,
awful.layout.suit.tile,
awful.layout.suit.tile.left,
awful.layout.suit.tile.bottom,
awful.layout.suit.tile.top,
awful.layout.suit.fair,
awful.layout.suit.fair.horizontal,
awful.layout.suit.spiral,
awful.layout.suit.spiral.dwindle,
awful.layout.suit.max,
awful.layout.suit.max.fullscreen,
awful.layout.suit.magnifier,
awful.layout.suit.corner.nw,
awful.layout.suit.corner.ne,
awful.layout.suit.corner.sw,
awful.layout.suit.corner.se,

🔗 awful.layout.floating.resize_jump_to_corner N/A

Jump mouse cursor to the client's corner when resizing it.

🔗 awful.layout.tile.resize_jump_to_corner N/A

Jump mouse cursor to the client's corner when resizing it.