.config/awesome/lain/wiki/Layouts.md

   1
   2     lain/layout
   3     .
   4     |-- termfair
   5     |-- termfair.center
   6     |-- cascade
   7     |-- cascade.tile
   8     |-- centerwork
   9     |-- centerwork.horizontal
  10
  11 Usage
  12 =====
  13
  14 As usual, specify your favourites in `awful.layout.layouts`, or set them on specific tags with [`awful.layout.set`](https://awesomewm.org/doc/api/libraries/awful.layout.html#set).
  15
  16 ```lua
  17 awful.layout.set(lain.layout.termfair, tag)
  18 ```
  19
  20 How do layouts work?
  21 ====================
  22
  23 `termfair`
  24 --------
  25
  26 This layout restricts the size of each window. Each window will have the
  27 same width but is variable in height. Furthermore, windows are
  28 left-aligned. The basic workflow is as follows (the number above the
  29 screen is the number of open windows, the number in a cell is the fixed
  30 number of a client):
  31
  32              (1)                (2)                (3)
  33         +---+---+---+      +---+---+---+      +---+---+---+
  34         |   |   |   |      |   |   |   |      |   |   |   |
  35         | 1 |   |   |  ->  | 2 | 1 |   |  ->  | 3 | 2 | 1 |  ->
  36         |   |   |   |      |   |   |   |      |   |   |   |
  37         +---+---+---+      +---+---+---+      +---+---+---+
  38
  39              (4)                (5)                (6)
  40         +---+---+---+      +---+---+---+      +---+---+---+
  41         | 4 |   |   |      | 5 | 4 |   |      | 6 | 5 | 4 |
  42         +---+---+---+  ->  +---+---+---+  ->  +---+---+---+
  43         | 3 | 2 | 1 |      | 3 | 2 | 1 |      | 3 | 2 | 1 |
  44         +---+---+---+      +---+---+---+      +---+---+---+
  45
  46 The first client will be located in the left column. When opening
  47 another window, this new window will be placed in the left column while
  48 moving the first window into the middle column. Once a row is full,
  49 another row above it will be created.
  50
  51 Default number of columns and rows are respectively taken from `nmaster`
  52 and `ncol` values in `awful.tag`, but you can set your own.
  53
  54 For example, this sets `termfair` to 3 columns and at least 1 row:
  55
  56 ```lua
  57 lain.layout.termfair.nmaster = 3
  58 lain.layout.termfair.ncol    = 1
  59 ```
  60
  61 `termfair.center`
  62 ----------
  63
  64 Similar to `termfair`, but with fixed number of vertical columns. Cols are centerded until there are `nmaster` columns, then windows are stacked as slaves, with possibly `ncol` clients per column at most.
  65
  66             (1)                (2)                (3)
  67        +---+---+---+      +-+---+---+-+      +---+---+---+
  68        |   |   |   |      | |   |   | |      |   |   |   |
  69        |   | 1 |   |  ->  | | 1 | 2 | | ->   | 1 | 2 | 3 |  ->
  70        |   |   |   |      | |   |   | |      |   |   |   |
  71        +---+---+---+      +-+---+---+-+      +---+---+---+
  72
  73             (4)                (5)
  74        +---+---+---+      +---+---+---+
  75        |   |   | 3 |      |   | 2 | 4 |
  76        + 1 + 2 +---+  ->  + 1 +---+---+
  77        |   |   | 4 |      |   | 3 | 5 |
  78        +---+---+---+      +---+---+---+
  79
  80 Like `termfair`, default number of columns and rows are respectively taken from `nmaster`
  81 and `ncol` values in `awful.tag`, but you can set your own.
  82
  83 For example, this sets `termfair.center` to 3 columns and at least 1 row:
  84
  85 ```lua
  86 lain.layout.termfair.center.nmaster = 3
  87 lain.layout.termfair.center.ncol    = 1
  88 ```
  89
  90 `cascade`
  91 -------
  92
  93 Cascade all windows of a tag.
  94
  95 You can control the offsets by setting these two variables:
  96
  97 ```lua
  98 lain.layout.cascade.offset_x = 64
  99 lain.layout.cascade.offset_y = 16
 100 ```
 101
 102 The following reserves space for 5 windows:
 103
 104 ```lua
 105 lain.layout.cascade.nmaster = 5
 106 ```
 107
 108 That is, no window will get resized upon the creation of a new window,
 109 unless there's more than 5 windows.
 110
 111 `cascade.tile`
 112 -----------
 113
 114 Similar to `awful.layout.suit.tile` layout, however, clients in the slave
 115 column are cascaded instead of tiled.
 116
 117 Left column size can be set, otherwise is controlled by `mwfact` of the
 118 tag. Additional windows will be opened in another column on the right.
 119 New windows are placed above old windows.
 120
 121 Whether the slave column is placed on top of the master window or not is
 122 controlled by the value of `ncol`. A value of 1 means "overlapping slave column"
 123 and anything else means "don't overlap windows".
 124
 125 Usage example:
 126
 127 ```lua
 128 lain.layout.cascade.tile.offset_x      = 2
 129 lain.layout.cascade.tile.offset_y      = 32
 130 lain.layout.cascade.tile.extra_padding = 5
 131 lain.layout.cascade.tile.nmaster       = 5
 132 lain.layout.cascade.tile.ncol          = 2
 133 ```
 134
 135 `extra_padding` reduces the size of the master window if "overlapping
 136 slave column" is activated. This allows you to see if there are any
 137 windows in your slave column.
 138
 139 Setting `offset_x` to a very small value or even 0 is recommended to avoid wasting space.
 140
 141 `centerwork`
 142 ----------
 143
 144 You start with one window, centered horizontally:
 145
 146         +--------------------------+
 147         |       +----------+       |
 148         |       |          |       |
 149         |       |          |       |
 150         |       |          |       |
 151         |       |   MAIN   |       |
 152         |       |          |       |
 153         |       |          |       |
 154         |       |          |       |
 155         |       |          |       |
 156         |       +----------+       |
 157         +--------------------------+
 158
 159 This is your main working window. You do most of the work right here.
 160 Sometimes, you may want to open up additional windows. They're put on left and right, alternately.
 161
 162         +--------------------------+
 163         | +---+ +----------+ +---+ |
 164         | |   | |          | |   | |
 165         | |   | |          | |   | |
 166         | |   | |          | |   | |
 167         | +---+ |   MAIN   | +---+ |
 168         | +---+ |          | +---+ |
 169         | |   | |          | |   | |
 170         | |   | |          | |   | |
 171         | |   | |          | |   | |
 172         | +---+ +----------+ +---+ |
 173         +--------------------------+
 174
 175 *Please note:* If you use Awesome's default configuration, navigation in
 176 this layout may be very confusing. How do you get from the main window
 177 to satellite ones depends on the order in which the windows are opened.
 178 Thus, use of `awful.client.focus.bydirection()` is suggested.
 179 Here's an example:
 180
 181 ```lua
 182 globalkeys = awful.util.table.join(
 183     -- [...]
 184     awful.key({ modkey }, "j",
 185         function()
 186             awful.client.focus.bydirection("down")
 187             if client.focus then client.focus:raise() end
 188         end),
 189     awful.key({ modkey }, "k",
 190         function()
 191             awful.client.focus.bydirection("up")
 192             if client.focus then client.focus:raise() end
 193         end),
 194     awful.key({ modkey }, "h",
 195         function()
 196             awful.client.focus.bydirection("left")
 197             if client.focus then client.focus:raise() end
 198         end),
 199     awful.key({ modkey }, "l",
 200         function()
 201             awful.client.focus.bydirection("right")
 202             if client.focus then client.focus:raise() end
 203         end),
 204     -- [...]
 205 )
 206 ```
 207
 208 `centerwork.horizontal`
 209 -----------
 210
 211 Same as `centerwork`, except that the main
 212 window expands horizontally, and the additional windows
 213 are put ontop/below it. Useful if you have a screen turned 90°.
 214
 215 Pre 4.0 `uselesstile` patches
 216 =============================
 217
 218 In branch 3.5, this module provided useless gaps layouts. Since useless gaps have been implemented in Awesome 4.0, those layouts have been removed.
 219
 220 Following are a couple of `uselesstile` variants that were not part of lain. They are kept only for reference and are not supported.
 221
 222 Xmonad-like
 223 -----------
 224
 225 If you want to have `awful.layout.suit.tile` behave like xmonad, with internal gaps two times wider than external ones, download [this](https://gist.github.com/lcpz/9e56dcfbe66bfe14967c) as `lain/layout/uselesstile`.
 226
 227 Inverted master
 228 ---------------
 229
 230 Want to invert master window position? Use [this](https://gist.github.com/lcpz/c59dc59c9f99d98218eb) version. You can set `single_gap` with `width` and `height` in your `theme.lua`, in order to define the window geometry when there's only one client, otherwise it goes maximized. An example:
 231
 232     theme.single_gap = { width = 600, height = 100 }
 233
 234 What about layout icons?
 235 ========================
 236
 237 They are located in ``lain/icons/layout``.
 238
 239 To use them, define new `layout_*` variables in your ``theme.lua``. For instance:
 240
 241 ```lua
 242 theme.lain_icons         = os.getenv("HOME") ..
 243                            "/.config/awesome/lain/icons/layout/default/"
 244 theme.layout_termfair    = theme.lain_icons .. "termfair.png"
 245 theme.layout_centerfair  = theme.lain_icons .. "centerfair.png"  -- termfair.center
 246 theme.layout_cascade     = theme.lain_icons .. "cascade.png"
 247 theme.layout_cascadetile = theme.lain_icons .. "cascadetile.png" -- cascade.tile
 248 theme.layout_centerwork  = theme.lain_icons .. "centerwork.png"
 249 theme.layout_centerworkh = theme.lain_icons .. "centerworkh.png" -- centerwork.horizontal
 250 ```
 251
 252 Credit goes to [Nicolas Estibals](https://github.com/nestibal) for creating
 253 layout icons for default theme.
 254
 255 You can use them as a template for your custom versions.