.\" Generated by scdoc 1.11.3 .\" Complete documentation for this program is not available as a GNU info page .ie \n(.g .ds Aq \(aq .el .ds Aq ' .nh .ad l .\" Begin generated content: .TH "waybar-custom" "5" "2024-09-15" .SH NAME .PP waybar - custom module .PP .SH DESCRIPTION .PP The \fBcustom\fR module displays either the output of a script or static text.\& To display static text, specify only the \fBformat\fR field.\& .PP .SH CONFIGURATION .PP Addressed by \fBcustom/\fR .PP \fBexec\fR: .br typeof: string .br The path to the script, which should be executed.\& .PP \fBexec-if\fR: .br typeof: string .br The path to a script, which determines if the script in \fBexec\fR should be executed.\& .br \fBexec\fR will be executed if the exit code of \fBexec-if\fR equals 0.\& .PP \fBhide-empty-text\fR: .br typeof: bool .br Disables the module when output is empty, but format might contain additional static content.\& .PP \fBexec-on-event\fR: .br typeof: bool .br default: true .br If an event command is set (e.\&g.\& \fBon-click\fR or \fBon-scroll-up\fR) then re-execute the script after executing the event command.\& .PP \fBreturn-type\fR: .br typeof: string .br See \fBreturn-type\fR .PP \fBinterval\fR: .br typeof: integer .br The interval (in seconds) in which the information gets polled.\& .br Use \fBonce\fR if you want to execute the module only on startup.\& .br You can update it manually with a signal.\& If no \fBinterval\fR or \fBsignal\fR is defined, it is assumed that the out script loops itself.\& .br If a \fBsignal\fR is defined then the script will run once on startup and will only update with a signal.\& .PP \fBrestart-interval\fR: .br typeof: integer .br The restart interval (in seconds).\& .br Can'\&t be used with the \fBinterval\fR option, so only with continuous scripts.\& .br Once the script exits, it'\&ll be re-executed after the \fBrestart-interval\fR.\& .PP \fBsignal\fR: .br typeof: integer .br The signal number used to update the module.\& .br The number is valid between 1 and N, where \fBSIGRTMIN+N\fR = \fBSIGRTMAX\fR.\& .br If no interval is defined then a signal will be the only way to update the module.\& .PP \fBformat\fR: .br typeof: string .br default: {} .br The format, how information should be displayed.\& On {} data gets inserted.\& .PP \fBformat-icons\fR: .br typeof: array .br Based on the set percentage, the corresponding icon gets selected.\& The order is \fBlow\fR to \fBhigh\fR.\& .PP \fBrotate\fR: .br typeof: integer .br Positive value to rotate the text label.\& .PP \fBmax-length\fR: .br typeof: integer .br The maximum length in character the module should display.\& .PP \fBmin-length\fR: .br typeof: integer .br The minimum length in characters the module should accept.\& .PP \fBalign\fR: .br typeof: float .br The alignment of the label within the module, where 0 is left-aligned and 1 is right-aligned.\& If the module is rotated, it will follow the flow of the text.\& .PP \fBjustify\fR: .br typeof: string .br The alignment of the text within the module'\&s label, allowing options '\&left'\&, '\&right'\&, or '\¢er'\& to define the positioning.\& .PP \fBon-click\fR: .br typeof: string .br Command to execute when clicked on the module.\& .PP \fBon-click-middle\fR: .br typeof: string .br Command to execute when middle-clicked on the module using mousewheel.\& .PP \fBon-click-right\fR: .br typeof: string .br Command to execute when you right-click on the module.\& .PP \fBon-update\fR: .br typeof: string .br Command to execute when the module is updated.\& .PP \fBon-scroll-up\fR: .br typeof: string .br Command to execute when scrolling up on the module.\& .PP \fBon-scroll-down\fR: .br typeof: string .br Command to execute when scrolling down on the module.\& .PP \fBsmooth-scrolling-threshold\fR: .br typeof: double .br Threshold to be used when scrolling.\& .PP \fBtooltip\fR: .br typeof: bool .br default: true .br Option to disable tooltip on hover.\& .PP \fBtooltip-format\fR: .br typeof: string .br The tooltip format.\& If specified, overrides any tooltip output from the script in \fBexec\fR.\& .br Uses the same format replacements as \fBformat\fR.\& .PP \fBescape\fR: .br typeof: bool .br default: false .br Option to enable escaping of script output.\& .PP \fBmenu\fR: .br typeof: string .br Action that popups the menu.\& .PP \fBmenu-file\fR: .br typeof: string .br Location of the menu descriptor file.\& There need to be an element of type .RS 4 GtkMenu with id \fBmenu\fR .PP .RE \fBmenu-actions\fR: .br typeof: array .br The actions corresponding to the buttons of the menu.\& .PP .SH RETURN-TYPE .PP When \fBreturn-type\fR is set to \fBjson\fR, Waybar expects the \fBexec\fR-script to output its data in JSON format.\& This should look like this: .PP .nf .RS 4 {"text": "$text", "tooltip": "$tooltip", "class": "$class", "percentage": $percentage } .fi .RE .PP The \fBclass\fR parameter also accepts an array of strings.\& .PP If nothing or an invalid option is specified, Waybar expects i3blocks style output.\& Values are \fBnewline\fR separated.\& This should look like this: .PP .nf .RS 4 $text\\n$tooltip\\n$class* .fi .RE .PP \fBclass\fR is a CSS class, to apply different styles in \fBstyle.\&css\fR .PP .SH FORMAT REPLACEMENTS .PP \fB{}\fR: Output of the script.\& .PP \fB{percentage}\fR Percentage which can be set via a json return type.\& .PP \fB{icon}\fR: An icon from '\&format-icons'\& according to percentage.\& .PP .SH EXAMPLES .PP .SS Spotify: .PP .nf .RS 4 "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", "return-type": "json" } .fi .RE .PP .SS mpd: .PP .nf .RS 4 "custom/mpd": { "format": "♪ {}", //"max-length": 15, "interval": 10, "exec": "mpc current", "exec-if": "pgrep mpd", "on-click": "mpc toggle", "on-click-right": "sonata" } .fi .RE .PP .SS cmus: .PP .nf .RS 4 "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 } .fi .RE .PP .SS Pacman .PP .nf .RS 4 "custom/pacman": { "format": "{} ", "interval": "once", "exec": "pacman_packages", "on-click": "update-system", "signal": 8 } .fi .RE .PP .SS Alternate Pacman .PP .nf .RS 4 "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 } .fi .RE .PP You can use the signal and update the number of available packages with \fBpkill -RTMIN+8 waybar\fR.\& .PP .SH STYLE .PP .PD 0 .IP \(bu 4 \fB#custom-\fR .IP \(bu 4 \fB#custom-.\&\fR .IP \(bu 4 \fB\fR can be set by the script.\& For more information see \fBreturn-type\fR