.config/awesome/lain/wiki/fs.md

   1 ## Usage
   2
   3 [Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
   4
   5 ### Description
   6
   7 Shows file systems informations.
   8
   9 If a partition is given in input, a notification will be displayed when it is almost full.
  10
  11 ```lua
  12 local mypartition = lain.widget.fs()
  13 ```
  14
  15 ## Input table
  16
  17 Variable | Meaning | Type | Default
  18 --- | --- | --- | ---
  19 `timeout` | Refresh timeout (in seconds) | integer | 600
  20 `partition` | (Optional) Partition to watch: a notification will be displayed when full | string | `nil`
  21 `threshold` | Percentage threshold at which the notification is triggered | integer | 99
  22 `notification_preset` | Notification preset | table | See [default `notification_preset`](https://github.com/lcpz/lain/wiki/fs#default-notification_preset)
  23 `followtag` | Display the notification on currently focused screen | boolean | false
  24 `showpopup` | Display popups with mouse hovering | string, possible values: "on", "off" | "on"
  25 `settings` | User settings | function | empty function
  26
  27 `settings` can use the table `fs_now`, which contains a string entry for each file system path available. For instance, root infos are located in the variable `fs_now["/"]`. Every entry in this table have the following variables:
  28
  29 Variable | Meaning | Type
  30 --- | --- | ---
  31 `units` | (multiple of) units used | string ("Kb", "Mb", "Gb", and so on)
  32 `percentage` | the used percentage | integer
  33 `size` | size in `units` of the given fs | float
  34 `used` | amount of space used in the given fs, expressed in `units` | float
  35 `free` | amount of free space in the given fs, expressed in `units` | float
  36
  37 Usage example:
  38
  39 ```lua
  40 -- shows used (percentage) and remaining space in home partition
  41 local fsroothome = lain.widget.fs({
  42     settings  = function()
  43         widget:set_text("/home: " ..  fs_now["/home"].percentage .. "% (" ..
  44         fs_now["/home"].free .. " " .. fs_now["/home"].units .. " left)")
  45     end
  46 })
  47 -- output example: "/home: 37% (239.4 Gb left)"
  48 ```
  49
  50 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.
  51
  52 ### Default `notification_preset`
  53
  54 ```lua
  55 notification_preset = {
  56     font = "Monospace 10",
  57     fg   = "#FFFFFF",
  58     bg   = "#000000"
  59 }
  60 ```
  61
  62 ## Output table
  63
  64 Variable | Meaning | Type
  65 --- | --- | ---
  66 `widget` | The widget | `wibox.widget.textbox`
  67 `show` | The notification | function
  68
  69 You can display the notification with a key binding like this:
  70
  71 ```lua
  72 awful.key({ altkey }, "h", function () mypartition.show(seconds, scr) end),
  73 ```
  74
  75 where ``altkey = "Mod1"`` and ``show`` arguments, both optionals, are:
  76
  77 * `seconds`, notification time in seconds
  78 * `scr`, screen which to display the notification in
  79
  80 ## Note
  81
  82 Naughty notifications require `notification_preset.font` to be **monospaced**, in order to correctly display the output.