polybar/man/polybar_config.5

130 lines
4.5 KiB
Groff
Raw Normal View History

2016-11-19 05:22:44 +00:00
.TH polybar_config 5 2016-10-18 "polybar 2.0.0" "User Configuration"
2016-06-23 08:08:14 +00:00
.SH NAME
2016-11-19 05:22:44 +00:00
.\" This man page will need lots of updating as documentation about polybar
2016-06-23 08:08:14 +00:00
.\" configuration improves.
2016-11-19 05:22:44 +00:00
\fBpolybar_config\fR \- Configuration for a \fBpolybar\fR(1) bar.
2016-06-23 08:08:14 +00:00
.SH SYNOPSIS
2016-11-19 05:22:44 +00:00
.BR $XDG_CONFIG_HOME/.config/polybar/config
2016-06-23 08:08:14 +00:00
.P
2016-11-19 05:22:44 +00:00
.BR ~/.config/polybar/config
2016-06-23 08:08:14 +00:00
.SH SYNTAX
.nf
2016-06-30 02:56:58 +00:00
.TP
The configuration syntax is based on the \fIini\fR file format.
.TP
A sample config section with various field types:
2016-06-23 08:08:14 +00:00
[section/name]
str = My string
2016-06-30 02:56:58 +00:00
; Quote the value to keep surrounding spaces
str = " My string"
2016-06-23 08:08:14 +00:00
bool = true
bool = on
int = 10
float = 10.0
2016-06-30 02:56:58 +00:00
.TP
Values defined in another section can be referenced using:
key = \fI${bar/top.foreground}\fR
.TP
2016-10-18 16:40:47 +00:00
Read the value of an environment variable using:
key = \fI${env:MYVAR}\fR
.TP
2016-06-30 02:56:58 +00:00
Use BAR to target the section of the current bar:
key = \fI${BAR.foreground}\fR
.TP
Most modules define a format-N field. The formats define a set of tags. For example, the mpd module defines the following formats:
\fIformat-online\fR = ... <label-song> <icon-play> ...
\fIformat-offline\fR = the server is offline
.TP
The modules will toggle between the formats and only show the one defined for the current module state.
.TP
Each format contains the following fields:
format[-NAME]-padding = N (unit: whitespaces)
format[-NAME]-margin = N (unit: whitespaces)
format[-NAME]-spacing = N (unit: whitespaces)
format[-NAME]-offset = N (unit: pixels)
format[-NAME]-foreground = #aa[rrggbb]
format[-NAME]-background = #aa[rrggbb]
format[-NAME]-underline = #aa[rrggbb]
format[-NAME]-overline = #aa[rrggbb]
.TP
The rest of the drawtypes follow the same pattern.
2016-06-23 08:08:14 +00:00
2016-06-30 02:56:58 +00:00
.\" TODO: Describe the drawtypes
2016-10-18 16:40:47 +00:00
label-NAME[-(foreground|background|(under|over)line|font|padding|maxlen|ellipsis)] = ?
2016-06-30 02:56:58 +00:00
icon-NAME[-(foreground|background|(under|over)line|font|padding)] = ?
ramp-NAME-[0-9]+[-(foreground|background|(under|over)line|font|padding)] = ?
animation-NAME-[0-9]+[-(foreground|background|(under|over)line|font|padding)] = ?
2016-06-23 08:08:14 +00:00
2016-06-30 02:56:58 +00:00
bar-NAME-width = N (unit: characters)
bar-NAME-format = (tokens: %fill% %indicator% %empty%)
bar-NAME-foreground-[0-9]+ = #aarrggbb
bar-NAME-indicator[-(foreground|background|(under|over)line|font|padding)] =
bar-NAME-fill[-(foreground|background|(under|over)line|font|padding)] =
bar-NAME-empty[-(foreground|background|(under|over)line|font|padding)] =
2016-06-23 08:08:14 +00:00
2016-10-18 16:40:47 +00:00
2016-06-23 08:08:14 +00:00
.fi
.SH APPLICATION SETTINGS
2016-10-18 16:40:47 +00:00
These settings should exist in the `settings` section within the configuration file.
2016-06-23 08:08:14 +00:00
.TP
2016-10-18 16:40:47 +00:00
\fBthrottle-limit\fR and \fBthrottle-ms\fR
Limit the amount of update events within a set timeframe. Allow at most \fIthrottle-limit\fR updates within \fIthrottle-ms\fR milliseconds.
2016-06-23 08:08:14 +00:00
.SH BAR SETTINGS
2016-06-30 02:56:58 +00:00
These settings should be defined in the [bar/\fIBAR\-NAME\fR] section.
2016-06-23 08:08:14 +00:00
.TP
.BR monitor
2016-10-18 16:40:47 +00:00
Which display to output the bar to. You can get a list of available outputs by using the command `xrandr -q | grep " connected" | cut -d ' ' -f1`.
If unspecified, the application will pick the first one it finds.
2016-06-23 08:08:14 +00:00
.TP
\fBwidth\fR, \fBheight\fR
2016-10-18 16:40:47 +00:00
How large the bar should be. You can specify the values as a percentage of the screen, for example `85%`, or omit the `%` and give the dimension(s) in pixels.
2016-06-23 08:08:14 +00:00
.TP
2016-10-18 16:40:47 +00:00
\fBoffset-x\fR, \fBoffset-y\fR
2016-06-23 08:08:14 +00:00
The window offset value in pixels.
.TP
.BR bottom
2016-10-18 16:40:47 +00:00
Put the bar at the bottom of the screen.
2016-06-23 08:08:14 +00:00
.TP
.BR dock
2016-10-18 16:40:47 +00:00
If this boolean is set to `true`, then force the X window to dock itself.
If you are using \fBi3\fR(1) it is recommended to use the default value.
2016-06-23 08:08:14 +00:00
.TP
.BR spacing
2016-06-30 02:56:58 +00:00
This integer value is used as a multiplier when adding spaces between elements.
2016-06-23 08:08:14 +00:00
.TP
.BR lineheight
How high underlines and overlines should be.
.TP
\fBbackground\fR, \fBforeground\fR, \fBlinecolor\fR
2016-10-18 16:40:47 +00:00
Specify the colors used to draw the bar.
2016-06-23 08:08:14 +00:00
.TP
2016-10-18 16:40:47 +00:00
\fBpadding-left\fR, \fBpadding-right\fR
2016-06-23 08:08:14 +00:00
Specify the number of spaces to add at the start or end of the entire bar.
.TP
2016-10-18 16:40:47 +00:00
\fBmodule-margin-left\fR, \fBmodule-margin-right\fR
2016-06-23 08:08:14 +00:00
Specify the number of spaces to add before or after each module.
.TP
.BR font\-\fIid\fR
2016-10-18 16:40:47 +00:00
Here you can specify which fonts you wish to use. You need to set \fIid\fR to be a positive integer. The font should be specified in the following format: `\fIFONT\-NAME\fR:size=\fIFONT\-SIZE\fR;\fIOFFSET\fR`. For example, you could set `font\-0` to be `NotoSans-Regular:size=8;0`.
2016-06-23 08:08:14 +00:00
.TP
2016-10-18 16:40:47 +00:00
.BR wm-name
2016-11-19 05:22:44 +00:00
The value to set \fIWM_NAME\fR to when running. This defaults to `polybar\-\fIBAR-NAME\fR_\fIMONITOR\fR`.
2016-06-23 08:08:14 +00:00
.TP
.BR locale
Which locale to use.
.TP
\fBmodules-left\fR, \fBmodules-center\fR, \fBmodules-right\fR
Define which modules to use in the bar.
.SH EXAMPLES
.\" TODO add examples
There are no examples yet.
.SH SEE ALSO
.TP
2016-11-19 05:22:44 +00:00
\fBpolybar\fR(1)