yawn.rest

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