]> git.madduck.net Git - etc/awesome.git/blob - widgets/yawn/README.rst

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:

readme updated
[etc/awesome.git] / widgets / yawn / README.rst
1 =========================================
2 Yahoo's Awesome (WM) Weather Notification
3 =========================================
4
5 ----------------
6 Lain integration
7 ----------------
8
9 :Author: Luke Bonham <dada [at] archlinux [dot] info>
10 :License: WTFPLv2_
11 :Version: 2.0-git
12
13 Description
14 -----------
15
16 Yawn is a module for Awesome WM providing brief and compact
17 weather notification via Naughty and Yahoo! Weather API.
18
19 Originally a port of perceptive_, it became a completely new module after various improvements and style changes.
20
21 -----
22 Usage
23 -----
24
25 You can ``register`` Yawn to get a set of widgets, or ``attach`` it to
26 an existent widget.
27
28 register
29 ^^^^^^^^
30
31 Call: ::
32
33     lain.widgets.yawn(id, args)
34
35 Arguments:
36
37 ``id``
38     An integer that defines the WOEID code of your city.
39     To obtain it you can google 'yahoo weather %CITYNAME%' and follow the first link.
40     It will look like::
41
42         http://weather.yahoo.com/united-states/california/san-diego-2487889/
43
44     and the last number in that link will be the ID you need.
45 ``args``
46     An optional table which can contain the following settings:
47         ``u``
48             Units. Type: string. Possible values: "c" (Celsius), "f" (Fahrenheit). Default: "c".
49
50         ``toshow``
51             What to show. Type: string. Possible values: "units", "forecast", "both".
52             Default: "forecast".
53
54         ``units_color``
55             Color of units text. Type: string. Possible values: hexadecimal color
56             codes.
57
58         ``forecast_color``
59             Color of forecast text. Type: string. Possible values: hexadecimal color
60             codes.
61
62         ``notification_color``
63             Color of notification text. Type: string. Possible values: hexadecimal color
64             codes.
65
66         ``spr``
67             A separator. Type: string. You can define it when ``toshow`` is set to "both".
68
69         ``footer``
70             A footer. Type: string. You can define it when ``toshow`` is set to
71             "both".
72
73 The function creates an imagebox icon and a textbox widget. Add them to you wibox like this: ::
74
75     right_layout:add(lain.widgets.yawn.icon)
76     right_layout:add(lain.widgets.yawn.widget)
77
78 Hovering over ``yawn.icon`` will display the notification.
79
80 attach
81 ^^^^^^
82
83 Call: ::
84
85     lain.widgets.yawn.attach(widget, id, args)
86
87 Arguments:
88
89 ``widget``
90     The widget which you want to attach yawn to.
91 ``id``
92     same as in ``register``
93 ``args``
94     same as in ``register``
95
96 Hovering over ``widget`` will display the notification.
97
98 --------------
99 Popup shortcut
100 --------------
101
102 You can also create a keybinding for the weather popup like this: ::
103
104     globalkeys = awful.util.table.join(
105         ...
106         awful.key( { "Mod1" }, "w", function () lain.widgets.yawn.show(5) end )
107         ...
108
109 where ``show`` argument is an integer defining timeout seconds.
110
111 ------------
112 Localization
113 ------------
114
115 Default language is English, but Yawn can be localized.
116 Move to ``localizations`` subdirectory and fill ``localization_template``.
117
118 Once you're done, rename it like your locale id. In my case: ::
119
120     $ lua
121     Lua 5.2.2  Copyright (C) 1994-2013 Lua.org, PUC-Rio
122     > print(os.getenv("LANG"):match("(%S*$*)[.]"))
123     it_IT
124     >
125
126 hence I named my file "it_IT" (Italian localization).
127
128 **NOTE:** If you create a localization, feel free to send me! I will add it.
129
130 .. _WTFPLv2: http://www.wtfpl.net
131 .. _perceptive: https://github.com/ioga/perceptive
132 .. _Tamsyn: http://www.fial.com/~scott/tamsyn-font/
133 .. _Rainbow: https://github.com/copycat-killer/awesome-copycats>