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

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