update README
This commit is contained in:
mutlusun
parent
edabd477e2
commit
171b69216e
108
README.md
108
README.md
|
|
@ -130,6 +130,15 @@ enable caching of values returned by a widget type
|
|||
|
||||
widget argument is a table with one or more widgets that will be updated
|
||||
|
||||
**Get data from a widget:**
|
||||
|
||||
```Lua
|
||||
vicious.call(wtype, format, warg)
|
||||
```
|
||||
|
||||
Fetch data from a widget to use it outside from the titlebar (see example
|
||||
section)
|
||||
|
||||
|
||||
Widget types
|
||||
------------
|
||||
|
|
@ -147,12 +156,10 @@ Supported platforms: Linux (required tools: `sysfs`), FreeBSD (required tools:
|
|||
- Arguments (per platform):
|
||||
* Linux: takes battery ID as an argument, i.e. `"BAT0"`
|
||||
* FreeBSD: takes optional battery ID as an argument, i.e. `"batt"` or `"0"`
|
||||
- Returns (per platform):
|
||||
* Linux: returns 1st value as state of requested battery, 2nd as charge
|
||||
level in percent, 3rd as remaining (charging or discharging) time, 4th
|
||||
as the wear level in percent and 5th value for the present dis-/charge
|
||||
rate in Watt.
|
||||
* FreeBSD: see Linux
|
||||
- Returns:
|
||||
* Returns 1st value as state of requested battery, 2nd as charge level in
|
||||
percent, 3rd as remaining (charging or discharging) time, 4th as the wear
|
||||
level in percent and 5th value for the present dis-/charge rate in Watt.
|
||||
|
||||
**vicious.widgets.cpu**
|
||||
|
||||
|
|
@ -162,7 +169,7 @@ Supported platforms: Linux, FreeBSD.
|
|||
- Arguments:
|
||||
* None
|
||||
- Returns:
|
||||
* returns 1st value as usage of all CPUs/cores, 2nd as usage of first
|
||||
* Returns 1st value as usage of all CPUs/cores, 2nd as usage of first
|
||||
CPU/core, 3rd as usage of second CPU/core etc.
|
||||
|
||||
**vicious.widgets.cpufreq**
|
||||
|
|
@ -188,7 +195,7 @@ Supported platforms: Linux.
|
|||
- Arguments:
|
||||
* None
|
||||
- Returns:
|
||||
* returns a table with string keys, using CPU ID as a base: `{cpu0 mhz}`,
|
||||
* Returns a table with string keys, using CPU ID as a base: `{cpu0 mhz}`,
|
||||
`{cpu0 ghz}`, `{cpu0 kb}`, `{cpu0 mb}`, `{cpu1 mhz}` etc.
|
||||
|
||||
**vicious.widgets.date**
|
||||
|
|
@ -198,10 +205,10 @@ format string - using regular date sequences.
|
|||
Supported platforms: platform independent.
|
||||
|
||||
- Arguments:
|
||||
* takes optional time offset, in seconds, as an argument for example to
|
||||
* Takes optional time offset, in seconds, as an argument for example to
|
||||
calculate time zone differences, otherwise current time is formatted
|
||||
- Returns:
|
||||
* returns the output of os.date, formatted by provided sequences
|
||||
* Returns the output of os.date, formatted by provided sequences
|
||||
|
||||
**vicious.widgets.dio**
|
||||
|
||||
|
|
@ -211,7 +218,7 @@ Supported platforms: Linux.
|
|||
- Arguments:
|
||||
* None
|
||||
- Returns:
|
||||
* returns a table with string keys: `{sda total_s}`, `{sda total_kb}`,
|
||||
* Returns a table with string keys: `{sda total_s}`, `{sda total_kb}`,
|
||||
`{sda total_mb}`, `{sda read_s}`, `{sda read_kb}`, `{sda read_mb}`, `{sda write_s}`,
|
||||
`{sda write_kb}`, `{sda write_mb}`, `{sda iotime_ms}`, `{sda iotime_s}`, `{sdb1 total_s}` etc.
|
||||
|
||||
|
|
@ -231,10 +238,10 @@ Provides usage of file system disk space.
|
|||
Supported platforms: platform independent.
|
||||
|
||||
- Arguments:
|
||||
* takes an (optional) argument which, if true, includes remote file systems,
|
||||
* Takes an (optional) argument which, if true, includes remote file systems,
|
||||
only local file systems are included by default
|
||||
- Returns:
|
||||
* returns a table with string keys, using mount points as a base:
|
||||
* Returns a table with string keys, using mount points as a base:
|
||||
`{/ size_mb}`, `{/ size_gb}`, `{/ used_mb}`, `{/ used_gb}`, `{/ used_p}`,
|
||||
`{/ avail_mb}`, `{/ avail_gb}`, `{/ avail_p}`, `{/home size_mb}` etc.
|
||||
|
||||
|
|
@ -250,11 +257,11 @@ This widget expects login information in your `~/.netrc` file, e. g.
|
|||
afterwards. BE AWARE THAT MAKING THESE SETTINGS IS A SECURITY RISK!
|
||||
|
||||
- Arguments:
|
||||
* takes an (optional) argument, if it's a number subject will be truncated,
|
||||
* Takes an (optional) argument, if it's a number subject will be truncated,
|
||||
if a table, with 1st field as maximum length and 2nd the widget name (i.e.
|
||||
"gmailwidget"), scrolling will be used
|
||||
- Returns:
|
||||
* returns a table with string keys: {count} and {subject}
|
||||
* Returns a table with string keys: {count} and {subject}
|
||||
|
||||
**vicious.widgets.hddtemp**
|
||||
|
||||
|
|
@ -262,9 +269,9 @@ Provides hard drive temperatures using the hddtemp daemon.
|
|||
Supported platforms: Linux (required tools: `hddtemp`, `curl`).
|
||||
|
||||
- Arguments:
|
||||
* takes the hddtemp listening port as an argument, or defaults to port 7634
|
||||
* Takes the hddtemp listening port as an argument, or defaults to port 7634
|
||||
- Returns:
|
||||
* returns a table with string keys, using hard drives as a base: `{/dev/sda}`
|
||||
* Returns a table with string keys, using hard drives as a base: `{/dev/sda}`
|
||||
and `{/dev/sdc}` for example
|
||||
|
||||
**vicious.widgets.mbox**
|
||||
|
|
@ -273,13 +280,13 @@ Provides the subject of last e-mail in a mbox file.
|
|||
Supported platforms: platform independent.
|
||||
|
||||
- Arguments:
|
||||
* takes the full path to the mbox as an argument, or a table with 1st field
|
||||
* Takes the full path to the mbox as an argument, or a table with 1st field
|
||||
as path, 2nd as maximum length and 3rd (optional) as widget name - if 3rd
|
||||
field is present scrolling will be used (note: the path will be escaped so
|
||||
special variables like `~` will not work, use `os.getenv("HOME").."mail"`
|
||||
instead to access environment variables)
|
||||
- Returns:
|
||||
* returns 1st value as the subject of the last e-mail
|
||||
* Returns 1st value as the subject of the last e-mail
|
||||
|
||||
**vicious.widgets.mboxc**
|
||||
|
||||
|
|
@ -287,9 +294,9 @@ Provides the count of total, old and new messages in mbox files.
|
|||
Supported platforms: platform independent.
|
||||
|
||||
- Arguments:
|
||||
* takes a table with full paths to mbox files as an argument
|
||||
* Takes a table with full paths to mbox files as an argument
|
||||
- Returns:
|
||||
* returns 1st value as the total count of messages, 2nd as the count of old
|
||||
* Returns 1st value as the total count of messages, 2nd as the count of old
|
||||
messages and 3rd as the count of new messages
|
||||
|
||||
**vicious.widgets.mdir**
|
||||
|
|
@ -299,9 +306,9 @@ structures/directories.
|
|||
Supported platforms: platform independent.
|
||||
|
||||
- Arguments:
|
||||
* takes a table with full paths to Maildir structures as an argument
|
||||
* Takes a table with full paths to Maildir structures as an argument
|
||||
- Returns:
|
||||
* returns 1st value as the count of new messages and 2nd as the count of
|
||||
* Returns 1st value as the count of new messages and 2nd as the count of
|
||||
"old" messages lacking the Seen flag
|
||||
|
||||
**vicious.widgets.mem**
|
||||
|
|
@ -326,12 +333,12 @@ Provides Music Player Daemon information.
|
|||
Supported platforms: platform independent (required tools: `curl`).
|
||||
|
||||
- Arguments:
|
||||
* takes a table as an argument, 1st field should be the password (or nil),
|
||||
* Takes a table as an argument, 1st field should be the password (or nil),
|
||||
2nd the hostname (or nil) and 3rd port (or nil) - if no argument is
|
||||
provided connection attempt will be made to localhost port 6600 with no
|
||||
password
|
||||
- Returns:
|
||||
* returns a table with string keys: `{volume}`, `{state}`, `{Artist}`, `{Title}`,
|
||||
* Returns a table with string keys: `{volume}`, `{state}`, `{Artist}`, `{Title}`,
|
||||
`{Album}`, `{Genre}` and optionally `{Name}` and `{file}`
|
||||
|
||||
**vicious.widgets.net**
|
||||
|
|
@ -360,10 +367,10 @@ Provides agenda statistics for Emacs org-mode.
|
|||
Supported platforms: platform independent.
|
||||
|
||||
- Arguments:
|
||||
* takes a table with full paths to agenda files, that will be parsed, as an
|
||||
* Takes a table with full paths to agenda files, that will be parsed, as an
|
||||
argument
|
||||
- Returns:
|
||||
* returns 1st value as count of tasks you forgot to do, 2nd as count of
|
||||
* Returns 1st value as count of tasks you forgot to do, 2nd as count of
|
||||
tasks for today, 3rd as count of tasks for the next 3 days and 4th as
|
||||
count of tasks to do in the week
|
||||
|
||||
|
|
@ -375,7 +382,7 @@ Supported platforms: platform independent.
|
|||
- Arguments:
|
||||
* None
|
||||
- Returns:
|
||||
* returns 1st value as the operating system in use, 2nd as the release
|
||||
* Returns 1st value as the operating system in use, 2nd as the release
|
||||
version, 3rd as your username, 4th the hostname, 5th as available system
|
||||
entropy and 6th value as available entropy in percent
|
||||
|
||||
|
|
@ -387,10 +394,10 @@ correct number of updates.
|
|||
Supported platforms: platform independent.
|
||||
|
||||
- Arguments:
|
||||
* takes the Linux or BSD distribution name as an argument, i.e. `"Arch"`,
|
||||
* Takes the Linux or BSD distribution name as an argument, i.e. `"Arch"`,
|
||||
`"FreeBSD"`
|
||||
- Returns:
|
||||
* returns 1st value as the count of available updates
|
||||
* Returns 1st value as the count of available updates
|
||||
|
||||
**vicious.widgets.raid**
|
||||
|
||||
|
|
@ -668,7 +675,6 @@ second argument, and will return the text/data to be used for the
|
|||
widget.
|
||||
|
||||
**Example**
|
||||
|
||||
```Lua
|
||||
mpdwidget = widget({ type = "textbox" })
|
||||
vicious.register(mpdwidget, vicious.widgets.mpd,
|
||||
|
|
@ -683,7 +689,6 @@ hides the mpd widget when no song is playing, updated every 2
|
|||
seconds (the default interval)
|
||||
|
||||
**Example**
|
||||
|
||||
```Lua
|
||||
uptimewidget = widget({ type = "textbox" })
|
||||
vicious.register(uptimewidget, vicious.widgets.uptime,
|
||||
|
|
@ -700,7 +705,6 @@ textbox widgets by changing their .width field (by default width is
|
|||
automatically adapted to text width).
|
||||
|
||||
**Example**
|
||||
|
||||
```Lua
|
||||
uptimewidget = widget({ type = "textbox" })
|
||||
uptimewidget.width, uptimewidget.align = 50, "right"
|
||||
|
|
@ -715,7 +719,6 @@ color index arguments elegantly. But they are not unusable, far from
|
|||
it.
|
||||
|
||||
**Example**
|
||||
|
||||
```Lua
|
||||
ctext = widget({ type = "textbox"})
|
||||
cgraph = awful.widget.graph()
|
||||
|
|
@ -739,6 +742,7 @@ A lot of users are not happy with default symbols used in volume,
|
|||
battery, cpufreq and other widget types. You can use your own symbols
|
||||
without any need to modify modules.
|
||||
|
||||
**Example**
|
||||
```Lua
|
||||
volumewidget = wibox.widget.textbox()
|
||||
vicious.register(volumewidget, vicious.widgets.volume,
|
||||
|
|
@ -751,6 +755,42 @@ without any need to modify modules.
|
|||
- uses a custom table map to modify symbols representing the mixer
|
||||
state; on or off/mute
|
||||
|
||||
How to get the data from a widget to use it outside from the taskbar? This
|
||||
could be useful for naughty notification and scripts.
|
||||
|
||||
**Example**
|
||||
```Lua
|
||||
-- Battery widget
|
||||
mybattery = wibox.widget.textbox()
|
||||
vicious.register(mybattery, vicious.widgets.bat, "$2%", 17, "0")
|
||||
mybattery:buttons(awful.util.table.join(
|
||||
awful.button({ }, 1, function()
|
||||
naughty.notify({ title = "Battery indicator",
|
||||
text = vicious.call(vicious.widgets.bat, "Remaining time: $3", "0") })
|
||||
end)
|
||||
))
|
||||
```
|
||||
|
||||
Format functions can be used as well:
|
||||
|
||||
**Example**
|
||||
```Lua
|
||||
-- Battery widget
|
||||
mybattery = wibox.widget.textbox()
|
||||
vicious.register(mybattery, vicious.widgets.bat, "$2%", 17, "0")
|
||||
mybattery:buttons(awful.util.table.join(
|
||||
awful.button({ }, 1, function()
|
||||
naughty.notify({ title = "Battery indicator",
|
||||
text = vicious.call(vicious.widgets.bat, function(widget, args)
|
||||
return string.format("%s: %10sh\n%s: %14d%%\n%s: %12dW",
|
||||
"Remaining time", args[3],
|
||||
"Wear level", args[4],
|
||||
"Present rate", args[5])
|
||||
end, "0") })
|
||||
end)
|
||||
))
|
||||
```
|
||||
|
||||
|
||||
Other
|
||||
-----
|
||||
|
|
|
|||
Loading…
Reference in New Issue