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

- Copyright: 2008 Julien Danjou
- Originally authored by: Julien Danjou <julien@danjou.info>
  (Full contributors list available on our github project)

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

generated by LDoc 1.5.0