HorlogeSkynet/SimpleConkyScript
1
0
Fork 0
Code Issues Pull Requests Releases Activity

Improves comments and publishes new documentation

Browse Source
This commit is contained in:
Samuel FORESTIER 2019-08-24 10:25:06 +02:00
parent eae8eb541a
commit 3307dabc84
2 changed files with 260 additions and 6 deletions

260
README.md

@ -37,13 +37,264 @@ luacheck .
## Configuration Documentation
<!-- TO DO -->
This project is fully-customizable from configuration. It means that you can _safely_ pull latest changes without tweaking any Lua code (:sunglasses:).
The main idea is to describe the content of two "columns", displayed on your screen (please refer to the screen-shot above).
To achieve this, you can either use pre-defined types of entity (detailed below) or tweak global settings.
<details>
<summary>Comprehensive documentation of the `config.json` file</summary>
<p>
<!-- JS syntax to allow comments in JSON ;-) -->
```javascript
{
"settings": {
"conky": {
// Specific settings related to Conky itself.
// You can read further information about them here : <https://github.com/brndnmtthws/conky/wiki/Configurations#settings>.
// Entries present by default are mostly mine, working against a Cinnamon setup.
},
"timers": {
// Number of iterations to wait before drawing anything on the screen.
// It allows Conky to initialize its internals and gather some data before rendering anything.
// You MAY lower this value at your own risks.
"startup_threshold": 3,
// Number of iterations to wait before checking the user configuration (and reloading Conky if it changed).
// Use `null` to disable this behavior (default).
"config_autoreload": null,
// Number of iterations to wait before gathering current screen resolutions (and reloading Conky if it changed).
// This option is very useful if you are used to plug your laptop on a dock or play with multiple screens.
"resolution_autodetect": null
},
"display": {
// The width (in pixels) of the two columns drawn on screen.
// You MAY lower this value, but don't forget about very long content that could be displayed (i.e. IPv6 addresses).
"columns_width": 460,
// A subcommand to be run in order to retrieve the current screen dimensions (output MUST be formatted as `${WIDTH}x${HEIGHT}`).
"resolution_exec": "xdpyinfo | grep dimensions | tr -s ' ' | cut -d ' ' -f 3"
},
"font": {
// The font size and family to be used when writing down text on the screen.
// The font family SHOULD be a "Monospaced" one (see <https://en.wikipedia.org/wiki/Monospaced_font>).
"size": 15,
"family": "Consolas"
},
"colors": {
// Below colors are defined as RGBA values.
// Keys speak for themselves.
"default": [1, 1, 1, 1],
"clock_second_hand": [1, 0, 0, 1],
"bar_background": [0.4, 0.4, 0.4, 1],
"graph_in": [0, 0.5, 0.66, 1],
"graph_out": [1, 0.5, 0, 1]
},
"temperature": {
// The temperature unit that will be employed.
// You can either specify `F` for Fahrenheit or `C` for Celsius (default).
"unit": "C",
// The degree symbol that should be set before the unit.
// Please be careful, the one set by default required you to use a font family supporting Unicode.
"degree": "°",
// The string that will be added to any temperature exceeding the set threshold (see `{drive,sensor}_temperature` entities below)
"warning": "/!\\"
}
},
"content": {
// Entities are represented by a list of objects, each one containing (at least) a `type`.
// This first list will describe entities set within the left column.
"left": [
{
// This entity will display a clock, as present on the screen-shot above.
"type": "clock"
},
{
// This entity will render the current date-time and output it as a 'text' object.
// This is a regular 'text' object underly, so you MAY tweak the `align_center` setting (see `text` entity below).
"type": "date_time",
"format": "%H:%M:%S, %A %d/%m/%Y",
"align_center": true
},
{
// This entity will display an horizontal line, allowing you to separate entities and thus creating "blocks".
"type": "separator"
},
{
// A typical entity that would evaluate `var` and `arg` through Conky and show the result as a 'text' object.
// For example, the lines below would produce : "Hostname: ${nodename}".
//
// `arg` is fully-optional and MAY be omitted.
//
// `align_center` is fully-optional and defaults to `false`.
"type": "text",
"var": "nodename",
"arg": "",
"name": "Hostname",
"align_center": false
},
{
// This is the most powerful entity currently available.
// It allows you to execute (synchronously though) a subcommand and show the (STDOUT) result as a 'text' object.
// For example, on Debian, the lines below MIGHT produce : "Updates: 42 available".
//
// `interval` represents the number of iterations to wait before executing the command again (the output is cached).
// Please be careful, with `update_interval` Conky setting set to 2 seconds, such a command would be executed each 3600 * 2 seconds, or 2 hours.
// You MAY set `interval` to `null` to completely disable value update (the first obtained output would be kept until reloading).
// Inversely, you MAY set `interval` to `0` (or even omit the entry) to update it during each iteration (use at your own risks).
//
// `pre_text` and `post_text` (fully-optional values) allow you to respectively set some texts before and after obtained output.
// `align_center` acts described above for `text` entities.
//
// When the command fails, `on_error` content will be displayed.
"type": "command",
"exec": "apt list --upgradable -qq 2> /dev/null | wc -l",
"name": "Updates",
"interval": 3600,
"pre_text": "",
"post_text": " available",
"align_center": false,
"on_error": "Not detected"
},
{
// A typical entity that would evaluate `var` and `arg` through Conky and show the result as a 'bar' object.
// `arg` is fully-optional and MAY be omitted.
//
// `show_percent` allows you to add the numerical percentage value next to the `name` of your 'bar' object (disabled by default).
//
// You MAY use `bar` with any variable evaluating to a valid percentage.
"type": "bar",
"var": "battery_percent",
"arg": "",
"name": "Battery",
"show_percent": false
},
{
// `brightness` is a very specific entity.
// Through `cur_file` and `max_file`, it computes a brightness percentage ratio and produces a 'bar' object.
// You SHOULD specify an `interval` to avoid opening and reading two files during each iteration.
//
// For this entity, `name` is fully-optional and defaults to "Brightness" when not specified.
//
// `show_percent` is also available and MAY be tweaked.
//
// Please be careful, set file paths below MAY NOT work on your system.
"type": "brightness",
"name": "Brightness",
"cur_file": "/sys/class/backlight/intel_backlight/actual_brightness",
"max_file": "/sys/class/backlight/intel_backlight/max_brightness",
"interval": 10,
"show_percent": false
},
{
// This entity allows you to show a 'top'-like output for processes, based on their CPU usage.
// `max_processes` MAY be set between `1` and `10` (defaults to `10`).
"type": "top_processes",
"max_processes": 5
},
{
/* ... */
}
],
// This second list will describe entities set within the right column.
"right": [
{
// This entity relies entirely on the LM-SENSORS program.
// It underly uses a `sensors` call to retrieve temperature information from a chip.
// The identifier of the `chip` to prompt MUST be specified and could be found by manually running `sensors -A`.
// The final displayed value correspond to the chip temperature inputs average.
//
// `interval` acts as described for `command` type entity (see above).
//
// `threshold` represents the maximum temperature value that could be reached before adding the symbol specified in `settings.temperature.warning` (see above).
// You can either specify Celsius or Fahrenheit, as long as it is consistent to the unit specified in `settings.temperature.unit` (see above too).
//
// When no temperature could be computed, `on_error` will be displayed.
"type": "sensor_temperature",
"name": "CPUs",
"chip": "coretemp-isa-0000",
"interval": 5,
"threshold": 70,
"on_error": "Not detected"
},
{
// This entity works as the `sensor_temperature` above, but relies on the HDDTEMP program.
// You'll have to specify the path to the targeted drive.
//
// `wake_up` allows you to force drive wake up if needed to measure its temperature (disabled by default).
//
// `interval`, `threshold` and `on_error` acts as described for `sensor_temperature` type entity (see above).
"type": "drive_temperature",
"drive": "/dev/sda",
"wake_up": false,
"interval": 5,
"threshold": 60,
"on_error": "Not detected"
},
{
// This entity is a handy wrapper to the 'bar' entity.
// By specifying any partition `mount_point`, it will display a 'bar' representing its usage.
// `show_percent` acts as described above for `bar` entities (see above).
"type": "partition_usage",
"mount_point": "/home/",
"show_percent": false
},
{
// This entity will display two graphs representing the I/O rate of the specified `drive`.
// To set graphs colors, please refer to `settings.colors.graph_{in,out}`.
"type": "drive_io",
"drive": "/dev/sda"
},
{
// This entity will display two graphs representing the I/O rate of the specified network `interface`.
// As `drive_io` above, please refer to `settings.colors.graph_{in,out}` to set graphs colors.
//
// Please be careful, such an entity will be skipped when the interface is down (see `if_up_strictness` for further information).
"type": "network_interface_io",
"interface": "enp0s25"
},
{
// This entity will display each IP addresses associated to the specified network `interface`.
// `hide_v6` allows you to hide any IPv6 address (disabled by default).
//
// Please be careful, such an entity will be skipped when the interface is down (see `if_up_strictness` for further information).
"type": "network_interface_addr",
"interface": "enp0s25",
"hide_v6": false
},
{
// This entity is a disguised 'text' object.
// It allows you to show Conky version, with `{pre,post}_text` (active as within the `command` entity).
//
// `align_center` is available and acting as described above.
//
// It could be very useful to give you credits on screen-shot for instance.
"type": "version",
"pre_text": "Horloge's script on ",
"post_text": "",
"align_center": true
},
{
/* ... */
}
]
}
}
```
</p>
</details>
## Frequently asked questions
### My Conky does not work, it <insert your very specific issue details>. What should I do ?
### My Conky does not work, it \[insert your very specific issue details here\]. What should I do ?
Please, refer to the [official Conky's FAQ](https://github.com/brndnmtthws/conky/wiki/FAQ) first.
Please, refer to the [official Conky's FAQ](https://github.com/brndnmtthws/conky/wiki/FAQ) first.
If you can't find anything helpful, please [contact me](mailto:dev+conky@samuel.domains) with Conky terminal output attached.
### Your script is cool but I'd like to install it elsewhere. How could I achieve that ?
@ -53,6 +304,9 @@ You'll have to tweak your `conky` execution with an additional environment varia
CONKY_PATH="/another/path/to/" conky -c /another/path/to/conky.lua
```
> Rationale : There is no way to fetch the project location from the configuration file itself (`conky.lua`).
> Fortunately for us, we may read Conky environment variables !
### How can I get the same background image ?
[There](https://unsplash.com/photos/44t1AZNIMIE) it is !

6
lua/loading.lua

@ -335,13 +335,13 @@ function loading.load_entities(display, number_of_updates)
CAIRO_FONT_SLANT_NORMAL, CAIRO_FONT_WEIGHT_NORMAL)
cairo_set_font_size(display, _settings.font.size)
-- Load entities in the left-column.
-- Load entities in the left column.
for _, entity in ipairs(_content.left) do _load_entity(entity) end
-- Reset the "cursor" position to draw on the right-column.
-- Reset the "cursor" position to draw on the right column.
x_pos, y_pos = (conky_window.width - _settings.display.columns_width), 0
-- Load entities in the right-column.
-- Load entities in the right column.
for _, entity in ipairs(_content.right) do _load_entity(entity) end
end