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>