yawn.md

   1 Yahoo's Awesome Weather notification
   2 -----------
   3
   4 Yawn provides brief and compact weather notification via Naughty and Yahoo! Weather API.
   5
   6 Usage
   7 -----
   8
   9 You can ``register`` Yawn to get a set of widgets, or ``attach`` it to
  10 an existent widget.
  11
  12 ### register
  13
  14     yawn = lain.widgets.yawn(id, args)
  15
  16 - ``id``
  17
  18     An integer that defines the WOEID code of your city.
  19     To obtain it you can google 'yahoo weather %CITYNAME%' and follow the first link.
  20     It will look like:
  21
  22         http://weather.yahoo.com/united-states/california/san-diego-2487889/
  23
  24     and the last number in that link will be the ID you need.
  25
  26 - ``args``
  27
  28     An optional table which can contain the following settings:
  29
  30     Variables | Meaning | Type | Possible values | Default value
  31     --- | --- | --- | --- | ---
  32     `u` | Units | string | "c" (Celsius), "f" (Fahrenheit) | "c"
  33     `toshow` | What to show | string | "forecast", "units", "both" | "forecast"
  34     `color` | ``yawn.widget`` color | string | hexadecimal colors |
  35
  36 The function creates an imagebox icon and a textbox widget. Add them to you wibox like this:
  37
  38     right_layout:add(yawn.icon)
  39     right_layout:add(yawn.widget)
  40
  41 Hovering over ``yawn.icon`` will display the notification.
  42
  43 ### attach
  44
  45     lain.widgets.yawn.attach(widget, id, args)
  46
  47 Arguments:
  48
  49 - ``widget``
  50
  51     The widget which you want to attach Yawn to.
  52
  53 - ``id``
  54
  55     Same as in ``register``.
  56
  57 - ``args``
  58
  59    Same as in ``register``.
  60
  61 Hovering over ``widget`` will display the notification.
  62
  63 Popup shortcut
  64 --------------
  65
  66 You can also create a keybinding for the weather popup like this: ::
  67
  68     awful.key( { "Mod1" }, "w", function () yawn.show(5) end )
  69
  70 where ``show`` argument is an integer defining timeout seconds.
  71
  72 Localization
  73 ------------
  74
  75 Default language is English, but Yawn can be localized.
  76
  77 Move to `localizations` subdirectory and fill `localization_template`.
  78
  79 Once you're done, rename it like your locale id. In my case:
  80
  81     $ lua
  82     Lua 5.2.2  Copyright (C) 1994-2013 Lua.org, PUC-Rio
  83     > print(os.getenv("LANG"):match("(%S*$*)[.]"))
  84     it_IT
  85     >
  86
  87 hence I named my file "it_IT" (Italian localization).
  88
  89 **NOTE:** If you create a localization, feel free to send me! I will add it.