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.

Info:

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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.
generated by LDoc 1.5.0