3 [Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
7 Provides current weather status widgets and X-days forecast popup notifications.
9 Powered by [OpenWeatherMap](http://openweathermap.org/api) API.
11 By default, it uses [current](http://openweathermap.org/current) for current weather data and [forecast16](http://openweathermap.org/forecast16) for forecasts.
14 local myweather = lain.widget.weather()
19 Variable | Meaning | Type | Default
21 `timeout` | Refresh timeout seconds for current weather status | number | 900 (15 min)
22 `timeout_forecast` | Refresh timeout seconds for forecast notification | number | 86400 (24 hrs)
23 `current_call` | Command to fetch weather status data from the API | string | see `default_current_call`
24 `forecast_call` | Command to fetch forecast data from the API | string | see `default_forecast_call`
25 `city_id` | API city code | number | not set
26 `utc_offset` | UTC time offset | function | see [here](https://github.com/lcpz/lain/blob/master/widget/weather.lua#L35-L39)
27 `units` | Temperature units system | string | "metric"
28 `lang` | API data localization | string | "en"
29 `cnt` | Forecast days interval | integer | 5
30 `date_cmd` | Forecast notification format style | string | "date -u -d @%d +'%%a %%d'"
31 `icons_path` | Icons path | string | `lain/icons/openweathermap`
32 `notification_preset` | Preset for notifications | table | empty table
33 `notification_text_fun` | Function to format forecast notifications | function | see `notification_text_fun` below
34 `weather_na_markup` | Markup to be used when weather textbox is not available | text | " N/A "
35 `followtag` | Display the notification on currently focused screen | boolean | false
36 `showpopup` | Display popups with mouse hovering | string, possible values: "on", "off" | "on"
37 `settings` | User settings | function | empty function
39 - ``default_current_call``
41 `"curl -s 'http://api.openweathermap.org/data/2.5/weather?id=%s&units=%s&lang=%s'"`
43 You can rewrite it using any fetcher solution you like, or you can modify it in order to fetch data by city name, instead of ID: just replace `id` with `q`:
45 `"curl -s 'http://api.openweathermap.org/data/2.5/weather?q=%s&units=%s&lang=%s'"`
47 and set `city_id` with your city name, for instance `city_id = "London,UK"`.
49 - ``default_forecast_call``
51 `"curl -s 'http://api.openweathermap.org/data/2.5/forecast/daily?id=%s&units=%s&lang=%s&cnt=%s'"`
54 If you want to use [forecast5](http://openweathermap.org/forecast5), use this API call string:
55 `http://api.openweathermap.org/data/2.5/forecast?id=%s&units=%s&lang=%s&cnt=%s`
59 An integer that defines the OpenWeatherMap ID code of your city.
60 To obtain it go to [OpenWeatherMap](http://openweathermap.org/) and query for your city in the top search bar. The link will look like this:
62 http://openweathermap.org/city/2643743
64 your `city_id` is the number at the end.
68 - For temperature in Fahrenheit use `units = "imperial"`
69 - For temperature in Celsius use `units = "metric"` (Lain default)
70 - For temperature in Kelvin use `units = "standard"` (OpenWeatherMap default)
74 See *Multilingual Support* section [here](http://openweathermap.org/current).
78 Determines how many days to show in the forecast notification. Up to 16 if you use [forecast16](http://openweathermap.org/forecast16) (default), and up to 5 if you use [forecast5](http://openweathermap.org/forecast5).
82 OpenWeatherMap time is in UNIX format, so this variable uses `date` to determine how each line in the forecast notification is formatted. Default looks like this:
84 day #daynumber: forecast, temp_min - temp_max
86 see `man date` for your customizations.
90 You can set your own icons path if you don't wish to use `lain/icons/openweathermap`. Just be sure that your icons are PNGs and named exactly like [OpenWeatherMap ones](http://openweathermap.org/weather-conditions).
92 - ``notification_preset``
94 Notifications preset table. See [here](https://awesomewm.org/doc/api/libraries/naughty.html#notify) for the details.
96 - ``notification_text_fun``
99 local day = string.gsub(read_pipe(string.format(date_cmd, wn["dt"])), "\n", "")
100 local tmin = math.floor(wn["temp"]["min"])
101 local tmax = math.floor(wn["temp"]["max"])
102 local desc = wn["weather"][1]["description"]
104 return string.format("<b>%s</b>: %s, %d - %d ", day, desc, tmin, tmax)
107 See [here](https://github.com/lcpz/lain/issues/186#issuecomment-203400918) for a complete customization example.
111 With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
115 In your `settings` function, you can use `widget` variable to refer to the textbox, and the dictionary `weather_now` to refer to data retrieved by `current_call`. The dictionary is built with [dkjson library](http://dkolf.de/src/dkjson-lua.fsl/home), and its structure is defined [here](http://openweathermap.org/weather-data).
116 For instance, you can retrieve current weather status and temperature in this way:
118 descr = weather_now["weather"][1]["description"]:lower()
119 units = math.floor(weather_now["main"]["temp"])
124 Variable | Meaning | Type
126 `widget` | The widget | `wibox.widget.textbox`
127 `icon` | The icon | `wibox.widget.imagebox`
128 `update` | Update `widget` | function
129 `timer` | The widget timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html)
130 `timer_forecast` | The forecast notification timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html)
134 You can attach the forecast notification to any widget like this:
137 myweather.attach(obj)
140 Hovering over ``obj`` will display the notification.
144 You can create a keybinding for the weather popup like this:
147 awful.key( { "Mod1" }, "w", function () myweather.show(5) end )
150 where ``show`` argument is an integer defining timeout seconds.