]> git.madduck.net Git - etc/awesome.git/blob - README.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:

first commit
[etc/awesome.git] / README.md
1 VAin agaIN
2 ==========
3
4 Author: Luke Bonham <dada [at] archlinux [dot] info>
5
6 Source: https://github.com/copycat-killer/vain
7
8 Version: 1.9.9
9
10 Release version: 2.0
11
12 **Please note**: until release version, this documentation will be not updated.
13
14 Foreword
15 --------
16
17 Based on a port of [awesome-vain](https://github.com/vain/awesome-vain), this
18 costantly evolving module provides new layouts, a set of widgets and
19 utility functions in order to improve Awesome usability and configurability.
20
21 This work is licensed under [GNU GPLv2 License](http://www.gnu.org/licenses/gpl-2.0.html).
22 Installation
23 ============
24
25 Simply clone this repository into your Awesome directory.
26
27 Widgets
28 =======
29
30 systemload
31 ----------
32
33 Show the current system load in a textbox. Read it directly from
34 `/proc/loadavg`.
35
36         mysysload = vain.widgets.systemload()
37
38 A click on the widget will call `htop` in your `terminal`.
39
40 The function takes a table as an optional argument. That table may
41 contain:
42
43 * `.refresh_timeout`: Default to 10 seconds.
44 * `.show_all`: Show all three values (`true`) or only the first one (`false`). Default to `false`.
45 * `.color`: Default to beautiful.bg_normal or "#FFFFFF".
46
47 cpu
48 --------
49
50 Shows the average CPU usage percent for a given amount of time.
51
52         mycpuusage = vain.widgets.cpu()
53
54 A click on the widget will call `htop` in your `terminal`.
55
56 The function takes a table as optional argument, which can contain:
57
58 Variable | Meaning | Type | Default
59 --- | --- | --- | ---
60 `refresh_timeout` | Refresh timeout seconds | int | 10
61 `header` | Text to show before value | string | " Vol "
62 `header_color` | Header color | string | `beautiful.fg_normal` or "#FFFFFF"
63 `color` | Value color | string | `beautiful.fg_focus` or "#FFFFFF"
64 `footer` | Text to show after value | string | "%"
65
66 **Note**: `footer` color is `color`.
67
68 memusage
69 --------
70
71 Show used memory and total memory in MiB.
72
73         mymem = vain.widgets.mem()
74
75
76 The function takes a table as an optional argument. That table may
77 contain:
78
79 Variable | Meaning | Type | Default
80 --- | --- | --- | ---
81 `refresh_timeout` | Refresh timeout seconds | int | 10
82 `show_swap` | Show amount of used swap space? | boolean | false
83 `show_total` | Show amout of total memory? | boolean | false
84 `header` | Text to show before value | string | " Vol "
85 `header_color` | Header color | string | `beautiful.fg_normal` or "#FFFFFF"
86 `color` | Value color | string | `beautiful.fg_focus` or "#FFFFFF"
87 `footer` | Text to show after value | string | "MB"
88
89 **Note**: `footer` color is `color`.
90
91 mailcheck
92 ---------
93 Checks maildirs and shows the result in a textbox.
94 Maildirs are structured as follows:
95
96         ~/Mail
97         .
98         |-- arch
99         |   |-- cur
100         |   |-- new
101         |   `-- tmp
102         |-- gmail
103         |   |-- cur
104         |   |-- new
105         |   `-- tmp
106         .
107         .
108         .
109
110 therefore `mailcheck` checks whether there are files in the `new`
111 directories. To do so, it calls `find`. If there's new mail, the textbox
112 will say something like "mail: bugs(3), system(1)", otherwise it says
113 "no mail".
114
115         mymailcheck = vain.widgets.mailcheck("/path/to/my/maildir")
116
117 The function takes a table as an optional argument. That table may
118 contain:
119
120 * `.mailprogram`: Your favourite mail program. Clicking on the widget will
121   spawn it. Default is `mutt`.
122 * `.refresh_timeout`: Default to 60 seconds.
123 * `.mailpath`: Path to your maildir, default is `~/Mail`.
124 * `.ignore_boxes`: Another table which lists boxes (just the last part,
125   like `lists`) to ignore. Default to an empty table.
126 * `.initial_update`: Check for mail when starting Awesome (`true`) or
127   wait for the first refresh timeout (`false`)? Default to `false`.
128 * `.header_text`: Text to show along with output, default is "Mail".
129 * `.header_text_color`: Default to "#9E9E9E".
130 * `.color_newmail`: Default to "#D4D4D4".
131 * `.color_nomail`: Default to "#9E9E9E".
132 * `.shadow`: Hides widget when there are no mails. Default is `false`.
133
134 imapcheck
135 ---------
136
137 Check new mails over imap protocol.
138
139 Dependencies:
140
141 * Python3
142
143 Since [luasec](https://github.com/brunoos/luasec/) is still not officially
144 supported in lua 5.2, writing a pure lua solution would have meant too many
145 hacks and dependencies, resulting in a very big and not efficient-proven submodule.
146
147 That's why I chose Python.
148
149 Python offers [imaplib](http://docs.python.org/2/library/imaplib.html), a simple yet powerful IMAP4 client library which provides encrypted communication over SSL sockets.
150
151 Basically, `imapcheck` calls ``vain/scripts/checkmail`` and parse its output in a widget. New mails are also notified through Naughty, with a popup like this:
152
153         +---------------------------------------------------+
154         | +---+                                             |
155         | |\ /| donald@disney.org has 3 new messages        |
156         | +---+                                             |
157         |       Latest From: Mickey Mouse <boss@disney.org> |
158     |       Subject: Re: Vacation Day                   |
159     |                                                   |
160     |       Not after what you did yesterday.           |
161     |       Daisy told me everything [...]              |
162         |                                                   |
163         +---------------------------------------------------+
164
165 Text will be cut if the mail is too long.
166
167         myimapcheck = vain.widgets.mailcheck(args)
168
169 The function takes a table as argument. Required table parameters are:
170
171 * `.server`: You email server. Example: `imap.gmail.com`.
172 * `.mail`: Your email.
173 * `.password`: Your email password.
174
175 while the optional are:
176
177 * `.port`: Imap port. Default is `993`.
178 * `.refresh_timeout`: Default to 60 seconds.
179 * `.notify_timeout`: Notification timeout. Default to 8 seconds.
180 * `.notify_position`: Notification position. Default is "top_left". Check
181   [Naughty position parameter](http://awesome.naquadah.org/doc/api/modules/naughty.html) for a list of other possible values.
182 * `.mailprogram`: Your favourite mail program. Clicking on the widget will
183   spawn it. Default is `mutt`.
184 * `.mail_encoding`: If you wish to set an encoding. Default is `nil`.
185 * `.initial_update`: Check for mail when starting Awesome (`true`) or
186   wait for the first refresh timeout (`false`)? Default to `false`.
187 * `.header_text`: Text to show along with output, default is "Mail".
188 * `.header_text_color`: Default to "#9E9E9E".
189 * `.color_newmail`: Default to "#D4D4D4".
190 * `.color_nomail`: Default to "#9E9E9E".
191 * `.shadow`: Hides widget when there are no mails. Default is `false`.
192 * `.maxlen`: Maximum mail length. If mail is longer, it will be cut. Default is
193   `100`.
194 * `.is_plain`: Define whether `.password` field is a plain password (`true`) or a function that retrieves it (`false`). Default to `false`.
195
196 Let's focus better on `.is_plain` parameter.
197
198 You can just easily set your password like this:
199
200     args.is_plain = false
201     args.password = "mypassword"
202
203 and you'll have the same security provided by `~/.netrc`. (In this case, it's
204 better to set your `rc.lua` permissions to 700 or 600)
205
206 **Or**, you can use a keyring, like gnome's:
207
208     args.password = "gnome-keyring-query get password"
209
210 (`gnome-keyring-query` is not in gnome-keyring pkg, you have to download it
211 separately)
212
213 or the very light [python keyring](https://pypi.python.org/pypi/keyring).
214
215 When `.is_plain` is `false`, it *executes* `.password` before using it, so you can also use whatever password fetching solution you want.
216
217 You can also define your icon for the naughty notification. Just set `vain_mail_notify` into your ``theme.lua``.
218
219
220
221 mpd
222 ---
223
224 Provides a `table` with 2 elements:
225
226 * `table["widget"]` is a textbox displaying current song in play.
227
228 * `table["force"]` is a function to *force* the widget to update, exactly
229   like `vicious.force()`.
230
231 Also, a notification is shown when a new song is playing.
232
233 Dependencies:
234
235 * libnotify
236 * imagemagick
237
238
239     mpdwidget = vain.widgets.mpd()
240     ...
241     right_layout:add(mpdwidget["widget"])
242
243 The function takes a table as an optional argument. That table may
244 contain:
245
246 * `.password`: Mpd password. Default is unset.
247 * `.host`: Mpd host. Default is "127.0.0.1" (localhost).
248 * `.port`: Mpd port. Default is "6600".
249 * `.music_dir`: Your music directory. Default is "~/Music". If you have to
250   change this, be sure to write the absolute path.
251 * `.refresh_timeout`: Widget refresh timeout. Default is `1`.
252 * `.notify_timeout`: Notification timeout. Default is `5`.
253 * `.color_artist`: Artist name color. Default is `#9E9E9E`.
254 * `.color_song`: Song name color. Default is `#EBEBFF`.
255 * `.musicplr`: Your favourite music player. Clicking on the widget will spawn
256   it. Default is `ncmpcpp`.
257 * `.shadow`: Hides widget when no song is playing. Default is `false`.
258
259 You can use `table["force"]` to make your mpd keybindings immediate.
260 Example usage:
261
262     globalkeys = awful.util.table.join(
263     ...
264         -- Music control
265         awful.key({ altkey, "Control" }, "Up", function ()
266                                                   awful.util.spawn_with_shell( "mpc toggle || ncmpcpp toggle || ncmpc toggle || pms toggle", false )
267                                                   mpdwidget["force"]()
268                                                end),
269         awful.key({ altkey, "Control" }, "Down", function ()
270                                                   awful.util.spawn_with_shell( "mpc stop || ncmpcpp stop || ncmpc stop || pms stop", false )
271                                                   mpdwidget["force"]()
272                                                  end ),
273         awful.key({ altkey, "Control" }, "Left", function ()
274                                                   awful.util.spawn_with_shell( "mpc prev || ncmpcpp prev || ncmpc prev || pms prev", false )
275                                                   mpdwidget["force"]()
276                                                  end ),
277         awful.key({ altkey, "Control" }, "Right", function ()
278                                                   awful.util.spawn_with_shell( "mpc next || ncmpcpp next || ncmpc next || pms next", false )
279                                                   mpdwidget["force"]()
280                                                   end ),
281
282 net
283 ---
284
285 Monitors network interfaces and shows current traffic in a textbox. If
286 the interface is not present or if there's not enough data yet, you'll
287 see `wlan0: -` or similar.  Otherwise, the current traffic is shown in
288 kilobytes per second as `eth0: ↑(00,010.2), ↓(01,037.8)` or similar.
289
290         neteth0 = vain.widgets.net()
291
292 The function takes a table as an optional argument. That table may
293 contain:
294
295 * `.iface`: Default to `eth0`.
296 * `.refresh_timeout`: Default to 2 seconds.
297 * `.color`: Default to beautiful.bg_normal or "#FFFFFF".
298
299 gitodo
300 ------
301
302 This is an integration of [gitodo](https://github.com/vain/gitodo) into
303 Awesome.
304
305         todolist = vain.widgets.gitodo()
306
307 The function takes a table as an optional argument. That table may
308 contain:
309
310 * `.refresh_timeout`: Default to 120 seconds.
311 * `.initial_update`: Check for todo items when starting Awesome (`true`)
312   or wait for the first refresh timeout (`false`)? Default to `true`.
313
314 `beautiful.gitodo_normal` is used as the color for non-outdated items,
315 `beautiful.gitodo_warning` for those items close to their deadline and
316 `beautiful.gitodo_outdated` is the color of outdated items.
317
318
319
320 Utility functions
321 =================
322
323 I'll only explain the more complex functions. See the source code for
324 the others.
325
326 menu\_clients\_current\_tags
327 ----------------------------
328
329 Similar to `awful.menu.clients()`, but this menu only shows the clients
330 of currently visible tags. Use it like this:
331
332         globalkeys = awful.util.table.join(
333             ...
334             awful.key({ "Mod1" }, "Tab", function()
335                 awful.menu.menu_keys.down = { "Down", "Alt_L", "Tab", "j" }
336                 awful.menu.menu_keys.up = { "Up", "k" }
337                 vain.util.menu_clients_current_tags({ width = 350 }, { keygrabber = true })
338             end),
339             ...
340         )
341
342 magnify\_client
343 ---------------
344
345 Set a client to floating and resize it in the same way the "magnifier"
346 layout does it. Place it on the "current" screen (derived from the mouse
347 position). This allows you to magnify any client you wish, regardless of
348 the currently used layout. Use it with a client keybinding like this:
349
350         clientkeys = awful.util.table.join(
351                 ...
352                 awful.key({ modkey, "Control" }, "m", vain.util.magnify_client),
353                 ...
354         )
355
356 If you want to "de-magnify" it, just reset the clients floating state to
357 `false` (hit `Mod4`+`CTRL`+`Space`, for example).
358
359 niceborder\_{focus, unfocus}
360 ----------------------------
361
362 By default, your `rc.lua` contains something like this:
363
364         client.connect_signal("focus", function(c) c.border_color = beautiful.border_focus end)
365         client.connect_signal("unfocus", function(c) c.border_color = beautiful.border_normal end)
366
367 You can change it to this:
368
369         client.connect_signal("focus", vain.util.niceborder_focus(c))
370         client.connect_signal("unfocus", vain.util.niceborder_unfocus(c))
371
372 Now, when a client is focused or unfocused, Awesome will look up its
373 nice value in `/proc/<pid>/stat`. If it's less than 0, the client is
374 classified as "high priority"; if it's greater than 0, the client is
375 classified as "low priority". If it's equal to 0, nothing special
376 happens.
377
378 This requires to define additional colors in your `theme.lua`. For example:
379
380         theme.border_focus_highprio  = "#FF0000"
381         theme.border_normal_highprio = "#A03333"
382
383         theme.border_focus_lowprio   = "#3333FF"
384         theme.border_normal_lowprio  = "#333366"
385
386 tag\_view\_nonempty
387 ------------------------------
388
389 This function lets you jump to the next/previous non-empty tag.
390 It takes two arguments:
391
392 * `direction`: `1` for next non-empty tag, `-1` for previous.
393 * `sc`: Screen in which the taglist is. Default is `mouse.screen` or `1`. This
394   argument is optional.
395
396 Usage example:
397
398         globalkeys = awful.util.table.join(
399                 ...
400         -- Non-empty tag browsing
401         awful.key({ altkey }, "Left", function () vain.util.tag_view_nonempty(-1)
402     end),
403         awful.key({ altkey }, "Right", function () vain.util.tag_view_nonempty(1) end),
404         ...
405
406 prompt\_rename\_tag
407 -------------------
408
409 This function enables you to dynamically rename the current tag you have
410 focused.
411 Usage example:
412
413         globalkeys = awful.util.table.join(
414             ..
415         -- Dynamic tag renaming
416                 awful.key({ modkey, "Shift" }, "r", function () vain.util.prompt_rename_tag(mypromptbox) end),
417                 ...
418
419 Credits goes to [minism](https://bbs.archlinux.org/viewtopic.php?pid=1315135#p1315135).