]> git.madduck.net Git - etc/awesome.git/blob - Layouts.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

045c2c97b8c8884713c62e944cb17fb482bd3c88
[etc/awesome.git] / Layouts.md
1 Currently, there are **8** layouts.
2
3     lain/layout
4     .
5     |-- termfair
6     |-- centerfair
7     |-- cascade
8     |-- cascadetile
9     |-- centerwork
10     |-- uselessfair
11     |-- uselesspiral
12     `-- uselesstile
13
14 Just add your favourites to ``layouts`` table:
15
16     layouts =
17     {
18         ...
19         lain.layout.termfair,
20         lain.layout.uselesstile,
21         ...
22     }
23
24 Or set them on specific tags like this:
25
26         awful.layout.set(lain.layout.uselessfair, tags[1][7])
27
28 How do layouts work?
29 =========================
30
31 termfair
32 --------
33
34 I do a lot of work on terminals. The common tiling algorithms usually
35 maximize windows, so you'll end up with a terminal that has about 200
36 columns or more. That's way too much. Have you ever read a manpage in a
37 terminal of this size?
38
39 This layout restricts the size of each window. Each window will have the
40 same width but is variable in height. Furthermore, windows are
41 left-aligned. The basic workflow is as follows (the number above the
42 screen is the number of open windows, the number in a cell is the fixed
43 number of a client):
44
45              (1)                (2)                (3)
46         +---+---+---+      +---+---+---+      +---+---+---+
47         |   |   |   |      |   |   |   |      |   |   |   |
48         | 1 |   |   |  ->  | 2 | 1 |   |  ->  | 3 | 2 | 1 |  ->
49         |   |   |   |      |   |   |   |      |   |   |   |
50         +---+---+---+      +---+---+---+      +---+---+---+
51
52              (4)                (5)                (6)
53         +---+---+---+      +---+---+---+      +---+---+---+
54         | 4 |   |   |      | 5 | 4 |   |      | 6 | 5 | 4 |
55         +---+---+---+  ->  +---+---+---+  ->  +---+---+---+
56         | 3 | 2 | 1 |      | 3 | 2 | 1 |      | 3 | 2 | 1 |
57         +---+---+---+      +---+---+---+      +---+---+---+
58
59 The first client will be located in the left column. When opening
60 another window, this new window will be placed in the left column while
61 moving the first window into the middle column. Once a row is full,
62 another row above it will be created.
63
64 Default number of columns and rows are respectively taken from `nmaster`
65 and `ncol` values in `awful.tag`, but you can set your own.
66
67 For example, this sets `termfair` to 3 columns and at least 1 row:
68
69     lain.layout.termfair.nmaster = 3
70     lain.layout.termfair.ncol = 1
71
72 centerfair
73 ----------
74
75 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.
76
77             (1)                (2)                (3)
78        +---+---+---+      +-+---+---+-+      +---+---+---+
79        |   |   |   |      | |   |   | |      |   |   |   |
80        |   | 1 |   |  ->  | | 1 | 2 | | ->   | 1 | 2 | 3 |  ->
81        |   |   |   |      | |   |   | |      |   |   |   |
82        +---+---+---+      +-+---+---+-+      +---+---+---+
83
84             (4)                (5)
85        +---+---+---+      +---+---+---+
86        |   |   | 3 |      |   | 2 | 4 |
87        + 1 + 2 +---+  ->  + 1 +---+---+
88        |   |   | 4 |      |   | 3 | 5 |
89        +---+---+---+      +---+---+---+
90
91 Like `termfair`, default number of columns and rows are respectively taken from `nmaster`
92 and `ncol` values in `awful.tag`, but you can set your own.
93
94 For example:
95
96     lain.layout.centerfair.nmaster = 3
97     lain.layout.centerfair.ncol = 1
98
99 cascade
100 -------
101
102 Cascade all windows of a tag.
103
104 You can control the offsets by setting these two variables:
105
106         lain.layout.cascade.cascade_offset_x = 64
107         lain.layout.cascade.cascade_offset_y = 16
108
109 The following reserves space for 5 windows:
110
111         lain.layout.cascade.nmaster = 5
112
113 That is, no window will get resized upon the creation of a new window,
114 unless there's more than 5 windows.
115
116 cascadetile
117 -----------
118
119 Similar to `awful.layout.suit.tile` layout, however, clients in the slave
120 column are cascaded instead of tiled.
121
122 Left column size can be set, otherwise is controlled by `mwfact` of the
123 tag. Additional windows will be opened in another column on the right.
124 New windows are placed above old windows.
125
126 Whether the slave column is placed on top of the master window or not is
127 controlled by the value of `ncol`. A value of 1 means "overlapping slave column"
128 and anything else means "don't overlap windows".
129
130 Usage example:
131
132         lain.layout.cascadetile.cascade_offset_x = 2
133         lain.layout.cascadetile.cascade_offset_y = 32
134         lain.layout.cascadetile.extra_padding = 5
135     lain.layout.cascadetile.nmaster = 5
136     lain.layout.ncol = 1
137
138 `extra_padding` reduces the size of the master window if "overlapping
139 slave column" is activated. This allows you to see if there are any
140 windows in your slave column.
141
142 Setting `cascade_offset_x` to a very small value or even 0 is reccommended to avoid wasting space.
143
144 centerwork
145 ----------
146
147 You start with one window, centered horizontally:
148
149         +--------------------------+
150         |       +----------+       |
151         |       |          |       |
152         |       |          |       |
153         |       |          |       |
154         |       |   MAIN   |       |
155         |       |          |       |
156         |       |          |       |
157         |       |          |       |
158         |       |          |       |
159         |       +----------+       |
160         +--------------------------+
161
162 This is your main working window. You do most of the work right here.
163 Sometimes, you may want to open up additional windows. They're put in
164 the following four slots:
165
166         +--------------------------+
167         | +---+ +----------+ +---+ |
168         | |   | |          | |   | |
169         | | 0 | |          | | 1 | |
170         | |   | |          | |   | |
171         | +---+ |   MAIN   | +---+ |
172         | +---+ |          | +---+ |
173         | |   | |          | |   | |
174         | | 2 | |          | | 3 | |
175         | |   | |          | |   | |
176         | +---+ +----------+ +---+ |
177         +--------------------------+
178
179 Yes, the number "four" is fixed. In total, you can only have five open
180 windows with this layout. Additional windows are not managed and set to
181 floating mode. **This is intentional**.
182
183 You can set the order of the four auxiliary windows. This is the default
184 configuration:
185
186         lain.layout.centerwork.top_left = 0
187         lain.layout.centerwork.top_right = 1
188         lain.layout.centerwork.bottom_left = 2
189         lain.layout.centerwork.bottom_right = 3
190
191 This means: The bottom left slot will be occupied by the third window
192 (not counting the main window). Suppose you want your windows to appear
193 in this order:
194
195         +--------------------------+
196         | +---+ +----------+ +---+ |
197         | |   | |          | |   | |
198         | | 3 | |          | | 0 | |
199         | |   | |          | |   | |
200         | +---+ |   MAIN   | +---+ |
201         | +---+ |          | +---+ |
202         | |   | |          | |   | |
203         | | 2 | |          | | 1 | |
204         | |   | |          | |   | |
205         | +---+ +----------+ +---+ |
206         +--------------------------+
207
208 This would require you to use these settings:
209
210         lain.layout.centerwork.top_left = 3
211         lain.layout.centerwork.top_right = 0
212         lain.layout.centerwork.bottom_left = 2
213         lain.layout.centerwork.bottom_right = 1
214
215 *Please note:* If you use Awesome's default configuration, navigation in
216 this layout may be very confusing. How do you get from the main window
217 to satellite ones depends on the order in which the windows are opened.
218 Thus, use of `awful.client.focus.bydirection()` is suggested.
219 Here's an example:
220
221         globalkeys = awful.util.table.join(
222         ...
223             awful.key({ modkey }, "j",
224                 function()
225                     awful.client.focus.bydirection("down")
226                     if client.focus then client.focus:raise() end
227                 end),
228             awful.key({ modkey }, "k",
229                 function()
230                     awful.client.focus.bydirection("up")
231                     if client.focus then client.focus:raise() end
232                 end),
233             awful.key({ modkey }, "h",
234                 function()
235                     awful.client.focus.bydirection("left")
236                     if client.focus then client.focus:raise() end
237                 end),
238             awful.key({ modkey }, "l",
239                 function()
240                     awful.client.focus.bydirection("right")
241                     if client.focus then client.focus:raise() end
242                 end),
243             ...
244         )
245
246 uselessfair, uselesspiral & uselesstile
247 ---------------------------------------
248 These are duplicates of the stock `fair`, `spiral` and `tile` layouts.
249
250 However, "useless gaps" (see below) have been added.
251
252 Useless gaps
253 ============
254
255 Useless gaps are gaps between windows. They are "useless" because they
256 serve no special purpose despite increasing overview. I find it easier
257 to recognize window boundaries if windows are set apart a little bit.
258
259 The `uselessfair` layout, for example, looks like this:
260
261         +================+
262         #                #
263         #  +---+  +---+  #
264         #  | 1 |  |   |  #
265         #  +---+  |   |  #
266         #         | 3 |  #
267         #  +---+  |   |  #
268         #  | 2 |  |   |  #
269         #  +---+  +---+  #
270         #                #
271         +================+
272
273 All of lain layouts provide useless gaps. To set the width of the gaps,
274 you have to add an item called `useless_gap_width` in your `theme.lua`.
275 If it doesn't exist, the width will default to 0.
276 Example:
277
278         theme.useless_gap_width = 10
279
280 What about layout icons?
281 ========================
282
283 They are located in ``lain/icons/layout``.
284
285 To use them, add lines to your ``theme.lua`` like this:
286
287         theme.lain_icons         = os.getenv("HOME") .. "/.config/awesome/lain/icons/layout/default/"
288         theme.layout_termfair    = theme.lain_icons .. "termfairw.png"
289         theme.layout_cascade     = theme.lain_icons .. "cascadew.png"
290         theme.layout_cascadetile = theme.lain_icons .. "cascadetilew.png"
291         theme.layout_centerwork  = theme.lain_icons .. "centerworkw.png"
292
293 Credits goes to [Nicolas Estibals](https://github.com/nestibal) for creating
294 layout icons for default theme.
295
296 You can use them as a template for your custom versions.
297
298 [<- home](https://github.com/copycat-killer/lain/wiki)