Make the progress bars and graphs more configurable and themable
[delightful.git] / README.mdwn
1 # Delightful widgets for Awesome
2
3 This is Delightful, a set of widgets for [Awesome](http://awesome.naquadah.org)
4 3.5 window manager.
5
6 Delightful home page is at
7 <http://solitudo.net/software/awesome/delightful/>. Also Delightful page at
8 [Awesome wiki](https://awesome.naquadah.org/wiki/) is available at
9 <https://awesome.naquadah.org/wiki/Delightful>. Screenshots showing Delightful
10 in action are available at <https://awesome.naquadah.org/wiki/Glossy_theme>
11 and <https://awesome.naquadah.org/wiki/Darklooks_theme>.
12
13 ## Why?
14
15 Why another widget system for Awesome, you ask? We already have
16 [Vicious](https://awesome.naquadah.org/wiki/Vicious),
17 [Wicked](https://awesome.naquadah.org/wiki/Wicked),
18 [Obvious](https://awesome.naquadah.org/wiki/Obvious),
19 and [many others](https://awesome.naquadah.org/wiki/Category:Widgets).
20
21 ## Justifications
22
23 That is a valid question, let me try elaborating why Delightful was created.
24
25 ### Shiny colors
26
27 Your average Awesome widget is quite dull. Some might consider that a feature.
28 In this case, Delightful is probably not for you. Delightful try to add some
29 "bling" to the widgets. Not un-needed "bling" but something useful. Many
30 Delightful widgets provide a dynamically updated icon along with the widget
31 text. The icon might indicate the sound volume or battery level. Some of the
32 widgets use [Naughty](https://awesome.naquadah.org/wiki/Naughty) based pop-ups
33 and notifications to provide useful, additional information that doesn't fit
34 the Awesome wibox. Tooltips are used always when it makes sense.
35
36 You might find Delightful widgets to have resemblance to some of the old
37 GNOME 2 applets. This is not coincidental. Whether you find it a good or bad
38 thing is up to you.
39
40 ### Configurable
41
42 Delightful widgets are also very configurable outside of the widget code.
43 Besides usual configurable attributes, such as location where to display
44 weather information or which network devices to exclude from monitoring, you
45 also can tinker about every widget parameter, such as the widget update
46 interval, from your Awesome `rc.lua` without having to edit the widget code.
47 See the configuration section below for more information about configuring
48 Delightful widgets and the themeing section about changing widget's appearance.
49
50 Important note! In order to maintain speedy startup, you have to alter the
51 theme you're using when using Delightful widgets with icons. See the themeing
52 section below for more info.
53
54 ### Leveraging existing functionality
55
56 Delightful doesn't try to re-invent the wheel. Widgets depend heavily on
57 [Vicious](https://awesome.naquadah.org/wiki/Vicious) widget library.
58 A few of the widgets just extend an existing Vicious widget by providing
59 an icon and widget data display configuration for the Vicious widget
60 used under the hood. Some of the widgets provide features not available
61 in existing Vicious widgets by implementing the Vicious widget interface and
62 then add "the bling" on top of that.
63
64 # Included widgets
65
66 Delightful features the following widgets.
67
68 ## Battery widget
69
70 `delightful.widget.battery` shows a battery indicator as an icon and a progress
71 bar. Extends `vicious.widgets.bat` Vicious widget.
72
73 ## CPU widget
74
75 `delightful.widget.cpu` displays horizontal usage trend graph of all the CPUs
76 combined. Extends `vicious.widgets.cpu` Vicious widget.
77
78 ## Date and time widget
79
80 Shows current date and time. When mouse cursor hovers over the widget, calendar
81 is displayed as a popup. You can navigate between months by using mouse scroll
82 wheel.
83
84 ## IMAP widget
85
86 `delightful.widget.imap` monitors one or more IMAP accounts for incoming
87 messages. Multiple mailboxes can be monitored on each account. Number of unread
88 messages in each monitored mailbox is displayed in the widget. When new mail
89 arrives in one of the monitored mailboxes, some details about the message is
90 shown in a popup.  When mouse cursor hovers over the widget, details about each
91 mailbox is shown in a popup. Widget icon indicates the status whether there are
92 some unread mail in the monitored mailboxes. The IMAP widget implements
93 the Vicious widget interface.
94
95 ## Memory widget
96
97 `delightful.widget.memory` displays a progress bar indicating current memory
98 and swap usage. Extends `vicious.widgets.mem` Vicious widget.
99
100 ## Network widget
101
102 `delightful.widget.network` displays download and upload speeds of selected network
103 devices of the system. An icon indicates the type of the device (wired,
104 wireless or dialup). Extends `vicious.widgets.net` Vicious widget.
105
106
107 ## PulseAudio widget
108
109 `delightful.widget.pulseaudio` shows a PulseAudio mixer indicator as an icon
110 and a progress bar. Mouse clicks and scroll wheel actions can used to perform
111 various mixer-related functions such as muting the device and turn volume up
112 and down. PulseAudio widget implements the Vicious widget interface.
113
114 ## Weather widget
115
116 `delightful.widget.weather` monitors weather status of given locations. Widget
117 displays current temperature and an icon indicating the current weather
118 condition. Icon is updated dynamically according to the weather and time
119 changes. If the weather is clear, the icon indicates whether it's day or night
120 in the monitored location. When mouse cursor hovers over the widget, details
121 about the weather is shown in a popup. Weather widget implements the Vicious
122 widget interface.
123
124 # Dependencies
125
126 All widgets except the Date and time widget require
127 [Vicious](https://awesome.naquadah.org/wiki/Vicious). A tested and
128 found-to-be-working version of Vicious is provided in under the
129 `submodules/vicious` directory of the Delightful Git tree. See the downloading
130 and install sections below for more information about the bundled Vicious.
131 Using your existing Vicious installation or manually cloning the latest Vicious
132 sources from the [Git tree](http://git.sysphere.org/vicious/) will most likely
133 work, too.
134
135 All widgets except the Date and time widget require
136 [awesome-freedesktop](https://github.com/terceiro/awesome-freedesktop) for
137 icon support. A tested and found-to-be-working version of awesome-freedesktop
138 is provided in under the `submodules/awesome-freedesktop` directory of
139 the Delightful Git tree. See the downloading and install sections below for
140 more information about the bundled awesome-freedesktop. Using your existing awesome-freedesktop
141 installation or manually cloning the latest awesome-freedesktop sources from the
142 [Git tree](https://github.com/terceiro/awesome-freedesktop.git) will most
143 likely work, too.
144
145 All widgets except the Date and time widget can use icons. Using of icons is not
146 required, but highly recommended. See the section about themeing for more info.
147 On Debian/Ubuntu systems you can install the packages
148 `gnome-icon-theme gnome-icon-theme-full adwaita-icon-theme-full` in order
149 to get the common icons installed and additionally the package `mate-sensors-applet-common`
150 if you're planning to use the CPU or Memory widgets and the package
151 `libmateweather-common` if you're planning to use the Weather widget.
152
153 IMAP widget requires [`imap.lua`](https://github.com/dmj/misc/tree/master/lua/imap.lua).
154 A tested and found-to-be-working version of `imap.lua` is provided in under
155 the `submodules/imap` directory of the Delightful Git tree. See the downloading
156 and install sections below for more information about the bundled `imap.lua`.
157 `imap.lua` requires [LuaSocket](http://www.cs.princeton.edu/~diego/professional/luasocket/)
158 and [LuaSec](http://www.inf.puc-rio.br/~brunoos/luasec/). On Debian/Ubuntu systems you
159 can install the packages `lua-socket` and `lua-sec` in order to get
160 LuaSocket and LuaSec installed.
161
162 Weather widget requires [Lua weather library](http://solitudo.net/software/lua/weatherlib/)
163 and [Lua METAR parser](http://solitudo.net/software/lua/metar/). A tested and
164 found-to-be-working versions of these modules are provided under
165 the `submodules/weatherlib` and `submodules/metar` directories of the Delightful
166 Git tree. See the downloading and install sections below for more information
167 about these modules. The METAR parser requires
168 [LuaSocket](http://www.cs.princeton.edu/~diego/professional/luasocket/).
169 On Debian/Ubuntu systems you can install the package `lua-socket`
170 in order to get LuaSocket installed.
171
172 Weather widget can also use MateWeather XML location datafile to configure weather
173 report locations using city names instead of weather station code. See the
174 configuring section below for more information. If using this feature, also
175 [LuaExpat](http://www.keplerproject.org/luaexpat/) and
176 [lua\_zlip](https://github.com/brimworks/lua-zlib) need to be installed. On
177 Debian/Ubuntu systems you can install the packages
178 `libmateweather-common lua-expat lua-zlib` in order to get MateWeather XML
179 location datafile and required Lua libraries installed. Using MateWeather
180 support is highly recommended.
181
182 Calendar widget requires [`calendar2.lua`](https://awesome.naquadah.org/wiki/Calendar_widget#Module_for_3.4).
183 The module is included in this distribution. See the install section below for
184 more information.
185
186 # Downloading
187
188 Delightful can be downloaded by cloning the public Git repository at
189 `git://scm.solitudo.net/delightful.git`. Gitweb interface is available at
190 <http://scm.solitudo.net/gitweb/public/delightful.git>.
191
192 # Installation
193
194 1. Clone the Delightful Git tree
195         * $ `git clone git://scm.solitudo.net/delightful.git`
196 1. Download the submodules, i.e. bundled dependencies
197         * $ `git submodule init`
198         * $ `git submodule update`
199 1. Copy Delightful under your Awesome configuration directory
200         * $ `cp -a delightful/delightful ~/.config/awesome`
201 1. If you don't have an existing Vicious installation in your Awesome setup, copy Vicious under your Awesome configuration directory
202         * $ `cp -a delightful/submodules/vicious ~/.config/awesome`
203 1. If you don't have an existing awesome-freedesktop installation in your Awesome setup, copy awesome-freedesktop under your Awesome configuration directory
204         * $ `cp -a delightful/submodules/awesome-freedesktop/freedesktop ~/.config/awesome`
205 1. If you're planning to use the IMAP widget, copy the `imap.lua` module in your Awesome configuration directory
206         * $ `cp delightful/submodules/imap/lua/imap.lua/imap.lua ~/.config/awesome`
207 1. If you're planning to use the Weather widget, copy the Lua weather library and Lua METAR parser in your Awesome configuration directory
208         * $ `cp delightful/submodules/weatherlib/src/weatherlib.lua ~/.config/awesome`
209         * $ `cp delightful/submodules/metar/src/metar.lua ~/.config/awesome`
210 1. If you're planning to use the Date and time widget, copy the calendar module in your Awesome configuration directory
211         * $ `cp delightful/calendar2.lua ~/.config/awesome`
212 1. If running Debian/Ubuntu system, install the dependency for common icons
213         * $ `apt-get install gnome-icon-theme gnome-icon-theme-full adwaita-icon-theme-full`
214 1. If running Debian/Ubuntu system, and planning to use the CPU or Memory widgets, install the dependency for icons
215         * $ `apt-get install mate-sensors-applet-common`
216 1. If running Debian/Ubuntu system, and planning to use the IMAP widget, install the dependency packages
217         * $ `apt-get install lua-socket lua-sec`
218 1. If running Debian/Ubuntu system, and planning to use the Weather widget, install the dependency packages
219         * $ `apt-get install libmateweather-common lua-socket lua-expat lua-zlib`
220
221 # Configuration
222
223 This section documents the commonly used configuration options for each widget.
224 For full list of available configuration options for each widget, see
225 the comments at top of the each widget's source file under the directory
226 `delightful/widgets`.
227
228 Configuration options are defined as Lua tables with keys being the
229 configuration option name listed below and value being the configuration value.
230 See the section about using in Awesome for info on how to actually pass
231 the configuration to the widgets. 
232
233 ## Battery widget
234
235 * `battery`
236         * Battery name under the directory `/sys/class/power_supply/`. Defaults to `BAT1`. You probably don't have to change this.
237
238 ## CPU widget
239
240 Default configuration should work for most people.
241
242 ## Date and time widget
243
244 No configuration options available at all.
245
246 ## IMAP widget
247
248 You can configure multiple IMAP accounts to be monitored for messages. Each
249 account can monitor multiple mailboxes. Each account needs to be given as a Lua
250 table entry. For each account entry the most interesting configuration options
251 are the following.
252
253 * `user`
254         * User name of the IMAP account, mandatory
255 * `password`
256         * Password of the IMAP account, mandatory
257 * `host`
258         * Host name or IP address of the IMAP server, mandatory
259 * `port`
260         * Port of the IMAP server. 143 by default if SSL disabled, 993 if SSL enabled
261 * `ssl`
262         * `true` or `false` to enable or disable SSL for the IMAP connection. Note that only IMAPS is supported, not IMAP with STARTTLS. No SSL support by default.
263 * `mailboxes`
264         * A table defining which mailboxes to monitor. Defaults to `INBOX` so not needed to be defined is you only want to monitor the inbox.
265
266 ## Memory widget
267
268 Default configuration should work for most people.
269
270 ## Network widget
271
272 Default configuration should work for most people. But if the widget displays
273 status for unwanted network devices, the following configuration option is
274 handy.
275
276 * `excluded_devices`
277         * A table of [Lua patterns](http://www.lua.org/manual/5.1/manual.html#5.4.1) that match network devices that are not to be monitored. For instance, if you don't want to see the idle interface `eth1`, you could use the pattern `^eth1$`.
278
279 ## PulseAudio widget
280
281 Default configuration should work for most people. But if the widget displays
282 volume mixer for unwanted audio devices, the following configuration option is
283 handy.
284
285 * `sink_nums`
286         * A table of integers that reprsents the PulseAudio sink numbers to be used. To find out the sink number(s) you want to use, run command `pacmd list-sinks` and examine the output. Each line with the content `* index: <number>` shows a possible sink number that you can use in the `sink_nums` configuration option.
287
288
289 ## Weather widget
290
291 It is assumed that MateWeather XML location datafile is available. See the source
292 file `delightful/widgets/weather.lua` for more information about configuration
293 if you're not going to be using MateWeather XML location datafile support.
294
295 You can configure multiple locations for weather monitoring. Each location
296 needs to be given as a Lua table entry. For each location entry the most
297 interesting configuration options are the following.
298
299 * `city`
300         * The city and optional country to monitor as listed in the MateWeather XML location datafile. The format for full entry is `<country name>, <city name>`, for example `United Kingdom, London`. For London, UK, you have to use the full format since the MateWeather XML location datafile contains many cities named `London` and the first matching city is used. If the city name is globally unique, it's safe to use the simple format `<city name>`. For example, to monitor the capital of Finland, you can just use `Helsinki` as there's no two cities named `Helsinki` in the world.
301
302 This is really all that is needed if you're happy to use European style units.
303 If you want to display units commonly used in the US or elsewhere, you can
304 additionally use the following configuration options.
305
306 * `temperature_unit`
307         * The unit to use when displaying temperatures. Defaults to `c` for Celcius, other possible value is `f` for Fahrenheit.
308 * `wind_speed_unit`
309         * The unit to use when displaying wind speed. Defaults to `ms` for meters per second, other possible values are `kmh` for kilometers per hour, `mph` for miles per hour and `kn` for knots.
310 * `pressure_unit`
311         * The unit to use when displaying air pressure. Defaults to `hpa` for hectopascals, other possible values are `atm` for standard atmosphere and `inhg` for inches of Mercury.
312 * `visibility_unit`
313         * The unit to use when visibility distance. Defaults to `m` for meters, other possible values are `km` kilometers, `ft` for feet, `yd` for yards and `mi` for miles.
314
315 ## Configuration options common to all widgets
316
317 Well, all but the Date and time widget.
318
319 * `update_interval`
320         * How often the widget data is being updated. Default varies for each widget from CPU widget's one second to Weather widget's 20 minutes. Most likely the default is OK for each widget.
321 * `no_icon`
322         * `true` or `false` to disable or enable showing of widget icons. Default is to show icons for all widgets.
323
324 # Themeing
325
326 Delightful widgets can use various aspects of the current
327 [Beautiful](https://awesome.naquadah.org/wiki/Beautiful) theme, though
328 Delightful widgets should work with any unmodified theme. However, when using
329 unmodified themes, be aware of the default icon lookup related performance
330 notes below.
331
332 See the themes at [my Awesome themes page](http://solitudo.net/software/awesome/themes/)
333 for examples of themes with full Delightful support.
334
335 ## Icons
336
337 All widgets except the Date and time widget use various icons. 
338 For full list of available themable icons for each widget, see
339 the comments at top of the each widget's source file under the directory
340 `delightful/widgets`.
341
342 While icons are highly recommended, they are not mandatory. You can disable
343 showing of icons by two means. Either for each widget, set the `no_icon`
344 configuration option explained above to `true` or just don't install the
345 packages providing the default icons that are tried to lookup. The `no_icon`
346 way is recommended since this way you don't get the performance penalty with
347 the default icon lookup.
348
349 ## Text color
350
351 Battery, CPU, Memory, and PulseAudio widgets can use the following colors
352 defined in the theme to color bars, graphs, and text.
353
354 * `bg_widget`
355         * Widget background and border color, fallback to color `bg_normal` if `bg_widget` not defined
356 * `fg_widget`
357         * Widget foreground color, fallback to color `fg_normal` if `fg_widget` not defined
358 * `fg_center_widget`
359         * Middle part of the widget gradient color, fallback to color `fg_widget` and `fg_normal` if `fg_center_widget` not defined
360 * `fg_end_widget`
361         * End part of the widget gradient color, fallback to color `fg_widget` and `fg_normal` if `fg_end_widget` not defined
362
363 ## Font
364
365 IMAP and Weather widgets use the following font.
366
367 * `delightful_monospace_font`
368         * Font used when rendering text to popups. The setting should refer to a [monospaced font](http://en.wikipedia.org/wiki/Monospaced_font). Fallback to `monospace` if `delightful_monospace_font` not defined.
369
370 # Using in Awesome
371
372 This section shows what you need to add to your Awesome configuration in order
373 to get Delightful widgets added to your Awesome desktop. In this sample,
374 default configuration for Awesome 3.5.6 as shipped in Ubuntu 15.10 wily is
375 used. I'm sure you can apply this to newer default configurations or integrate
376 as part of your non-default configuration. Of course put something meaningful
377 in the IMAP widget configuration, remove unwanted widgets and so on.
378
379 In `rc.lua`, add the following section somewhere before the for loop that
380 iterates over each screen and sets up a wibox for the screen.
381
382 ---
383
384         -- Delightful widgets
385         require('delightful.widgets.battery')
386         require('delightful.widgets.cpu')
387         require('delightful.widgets.datetime')
388         require('delightful.widgets.imap')
389         require('delightful.widgets.memory')
390         require('delightful.widgets.network')
391         require('delightful.widgets.pulseaudio')
392         require('delightful.widgets.weather')
393
394         -- Which widgets to install?
395         -- This is the order the widgets appear in the wibox.
396         delightful_widgets = {
397             delightful.widgets.network,
398             delightful.widgets.cpu,
399             delightful.widgets.memory,
400             delightful.widgets.weather,
401             delightful.widgets.imap,
402             delightful.widgets.battery,
403             delightful.widgets.pulseaudio,
404             delightful.widgets.datetime,
405         }
406
407         -- Widget configuration
408         delightful_config = {
409             [delightful.widgets.cpu] = {
410                 command = 'gnome-system-monitor',
411             },
412             [delightful.widgets.imap] = {
413                 {
414                     user      = 'myuser',
415                     password  = 'mypassword',
416                     host      = 'mail.example.com',
417                     ssl       = true,
418                     mailboxes = { 'INBOX', 'awesome' },
419                     command   = 'evolution -c mail',
420                 },
421             },
422             [delightful.widgets.memory] = {
423                 command = 'gnome-system-monitor',
424             },
425             [delightful.widgets.weather] = {
426                 {
427                     city = 'Helsinki',
428                     command = 'gnome-www-browser http://ilmatieteenlaitos.fi/saa/Helsinki',
429                 },
430             },
431             [delightful.widgets.pulseaudio] = {
432                 mixer_command = 'pavucontrol',
433             },
434         }
435
436 ---
437
438 Then inside the wibox creating for loop, delete the lines
439
440 ---
441
442         if s == 1 then right_layout:add(wibox.widget.systray()) end
443         right_layout:add(mytextclock)
444
445 ---
446
447 and replace with
448
449 ---
450
451         if s == 1 then
452             right_layout:add(wibox.widget.systray())
453             delightful.utils.fill_wibox_container(delightful_widgets, delightful_config, right_layout)
454         end
455
456 ---
457
458 and you should be done.
459
460 This sample Delightful setup is also available as a patch file
461 `awesome-3.5.6-delightful-sample-configuration.diff` in the Delightful
462 distribution. The patch is against the stock Awesome 3.5.6 `rc.lua`.
463
464 # Contributing
465
466 If you would like to contribute patches or new widgets, you can contact the
467 author. See contact information below.
468
469 # Copyright and licensing
470
471 Copyright: © 2011-2016 Tuomas Jormola <tj@solitudo.net> <http://solitudo.net>
472
473 Licensed under the terms of the [GNU General Public License Version 2.0](http://www.gnu.org/licenses/gpl-2.0.html).
474 License terms are included in the file `COPYING`.
475
476 `calendar2.lua` included in this distribution was created by Bernd Zeimetz <bernd@bzed.de>
477 and modified by Marc Dequènes <Duck@DuckCorp.org>. `calendar2.lua` is released
478 to public domain.