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