.config/awesome/lain/wiki/cal.md

   1 ## Usage
   2
   3 [Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
   4
   5 ### Description
   6
   7 Creates a calendar notification that can be attached to widgets.
   8
   9 This is a simpler but [faster](https://github.com/awesomeWM/awesome/issues/1861)
  10 alternative to [`awful.widget.calendar_popup`](https://awesomewm.org/doc/api/classes/awful.widget.calendar_popup.html), which emulates UNIX's `cal`.
  11
  12 ```lua
  13 local mycal = lain.widget.cal()
  14 ```
  15
  16 ## Input table
  17
  18 Variable | Meaning | Type | Default
  19 --- | --- | --- | ---
  20 `attach_to` | List of widgets | table | empty table
  21 `week_start` | First day of the week | integer | 2 (Monday)
  22 `three` | Display three months spanning the date | boolean | false
  23 `followtag` | Display the notification on currently focused screen | boolean | false
  24 `week_number` | Display the week number | string ("none", "left" or "right") | "none"
  25 `week_number_format` | Week number format | string | `"%3d \| "` for "left", `"\| %-3d"` for "right"
  26 `icons` | Path to calendar icons | string | [icons/cal/white/](https://github.com/lcpz/lain/tree/master/icons/cal/white)
  27 `notification_preset` | Notification preset | table | See [default `notification_preset`](https://github.com/lcpz/lain/wiki/calendar#default-notification_preset)
  28
  29 Set `attach_to` as the list of widgets to which you want to attach the calendar, like this:
  30
  31 ```lua
  32 local mycal = lain.widget.cal {
  33     attach_to = { mywidget1, mywidget2, ...  },
  34     -- [...]
  35 }
  36 ```
  37
  38 For every widget in `attach_to`:
  39
  40 - Left click / scroll down: switch to previous month.
  41 - Middle click show current month.
  42 - Right click / scroll up: switch to next month.
  43
  44 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.
  45
  46 ### Default `notification_preset`
  47
  48 ```lua
  49 notification_preset = {
  50     font = "Monospace 10",
  51     fg   = "#FFFFFF",
  52     bg   = "#000000"
  53 }
  54 ```
  55
  56 ## Output table
  57
  58 Variable | Meaning | Type
  59 --- | --- | ---
  60 `attach` | Attach the calendar to an input widget | function
  61 `show` | Show calendar | function
  62 `hide` | Hide calendar | function
  63
  64 `attach` takes as argument any widget you want to attach the calendar to, while
  65 `show` takes as optional argument an integer to indicate the seconds to timeout.
  66
  67 ## Keybinding
  68
  69 ```lua
  70 awful.key({ altkey }, "c", function () mycal.show(7) end)
  71 ```
  72
  73 Where `altkey = "Mod1"`.
  74
  75 ## Notes
  76
  77 * Naughty notifications require `notification_preset.font` to be **monospaced**, in order to correctly display the output.
  78 * If you want to [disable notification icon](https://github.com/lcpz/lain/pull/351), set `icons = ""` in the input table.
  79 * If you want to localise the calendar, put `os.setlocale(os.getenv("LANG"))` in your `rc.lua`.
  80 * If you want to get notifications [only with mouse clicks](https://github.com/lcpz/lain/issues/320) on a given widget, use this code:
  81   ```lua
  82   yourwidget:disconnect_signal("mouse::enter", mycal.hover_on)
  83   ```