diff --git a/man/waybar-custom.5.scd b/man/waybar-custom.5.scd new file mode 100644 index 00000000..a427be38 --- /dev/null +++ b/man/waybar-custom.5.scd @@ -0,0 +1,190 @@ +waybar-custom(5) + +# NAME + +waybar - custom module + +# DESCRIPTION + +The *custom* module displays either the output of a script or static text. +To display static text, specify only the *format* field. + +# CONFIGURATION + +Addressed by *custom/* + +*exec*: ++ + typeof: string ++ + The path to the script, which should be executed. + +*exec-if*: ++ + typeof: string ++ + The path to a script, which determines if the script in *exec* should be executed. + *exec* will be executed if the exit code of *exec-if* equals 0. + +*return-type*: ++ + typeof: string ++ + See *return-type* + +*interval*: ++ + typeof: integer ++ + The interval (in seconds) in which the information gets polled. + Use *once* if you want to execute the module only on startup. + You can update it manually with a signal. If no *interval* is defined, + it is assumed that the out script loops it self. + +*signal*: ++ + typeof: integer ++ + The signal number used to update the module. + The number is valid between 1 and N, where *SIGRTMIN+N* = *SIGRTMAX*. + +*format*: ++ + typeof: string ++ + default: {} ++ + The format, how information should be displayed. On {} data gets inserted. + +*format-icons*: ++ + typeof: array ++ + Based on the set percentage, the corresponding icon gets selected. The order is *low* to *high*. + +*rotate*: ++ + typeof: integer ++ + Positive value to rotate the text label. + +*max-length*: ++ + typeof: integer ++ + The maximum length in character the module should display. + +*on-click*: ++ + typeof: string ++ + Command to execute when clicked on the module. + +*on-click-right*: ++ + typeof: string ++ + Command to execute when you right clicked on the module. + +*on-scroll-up*: ++ + typeof: string ++ + Command to execute when scrolling up on the module. + +*on-scroll-down*: ++ + typeof: string ++ + Command to execute when scrolling down on the module. + +*smooth-scrolling-threshold*: ++ + typeof: double ++ + Threshold to be used when scrolling. + +*tooltip*: ++ + typeof: bool ++ + default: true ++ + Option to disable tooltip on hover. + +*escape*: ++ + typeof: bool ++ + default: false ++ + Option to enable escaping of script output. + +# RETURN-TYPE + +When *return-type* is set to *json*, Waybar expects the *exec*-script to output its data in JSON format. +This should look like this: + +``` +{"text": "$text", "tooltip": "$tooltip", "class": "$class", "percentage": $percentage } +``` + +The *class* parameter also accepts an array of strings. + +If nothing or an invalid option is specified, Waybar expects i3blocks style output. Values are *newline* separated. +This should look like this: + +``` +$text\\n$tooltip\\n$class* +``` + +*class* is a CSS class, to apply different styles in *style.css* + +# FORMAT REPLACEMENTS + +*{}*: Output of the script. + +*{percentage}* Percentage which can be set via a json return-type. + +*{icon}*: An icon from 'format-icons' according to percentage. + +# EXAMPLES + +## Spotify: + +``` +"custom/spotify": { + "format": " {}", + "max-length": 40, + "interval": 30, // Remove this if your script is endless and write in loop + "exec": "$HOME/.config/waybar/mediaplayer.sh 2> /dev/null", // Script in resources folder + "exec-if": "pgrep spotify" +} +``` + +## mpd: + +``` +"custom/mpd": { + "format": "♪ {}", + //"max-length": 15, + "interval": 10, + "exec": "mpc current", + "exec-if": "pgrep mpd", + "on-click": "mpc toggle", + "on-click-right": "sonata" +} +``` + +## cmus: + +``` +"custom/cmus": { + "format": "♪ {}", + //"max-length": 15, + "interval": 10, + "exec": "cmus-remote -C \"format_print '%a - %t'\"", // artist - title + "exec-if": "pgrep cmus", + "on-click": "cmus-remote -u", //toggle pause + "escape": true //handle markup entities +} +``` + +## Pacman + +``` + +"custom/pacman": { + "format": "{} ", + "interval": "once", + "exec": "pacman_packages", + "on-click": "update-system", + "signal": 8 +} +``` + +## Alternate Pacman + +``` +"custom/pacman": { + "format": "{} ", + "interval": 3600, // every hour + "exec": "checkupdates | wc -l", // # of updates + "exec-if": "exit 0", // always run; consider advanced run conditions + "on-click": "termite -e 'sudo pacman -Syu'; pkill -SIGRTMIN+8 waybar", // update system + "signal": 8 +} +``` + +You can use the signal and update the number of available packages with *pkill -RTMIN+8 waybar*. + +# STYLE + +- *#custom-* +- *#custom-.* +- ** can be set by the script. For more information see *return-type* diff --git a/meson.build b/meson.build index d5ab199c..a3cf2edb 100644 --- a/meson.build +++ b/meson.build @@ -165,7 +165,7 @@ if scdoc.found() 'waybar-battery.5.scd', 'waybar-clock.5.scd', 'waybar-cpu.5.scd', - 'warbar-custom.5.scd', + 'waybar-custom.5.scd', ] foreach filename : man_files