yawn.md

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