popcorn/config.md

Configuration

Configuration file

Popcorn loads a single TOML configuration file from:

~/.config/candywidgets/popcorn/config.toml  

If the file is missing or incomplete, built-in defaults are used.

Tip: You can maintain multiple config files for different themes and symlink the one you want active.

General rules for config values

• Any missing or misconfigured field normally falls back to sane defaults.
• Values must be plain integers or strings.
  • No expressions or functions.
  • No unit suffixes like "px," "ms," etc.
• Dimensions and positions are positive integers in pixels.
• Colors are 8-digit "AARRGGBB" hex strings.
  • Leading '#' is ignored. So, "#675f5f5f" is equal to "675f5f5f".
  • Alpha (AA) determines transparency (00: Invisible, ff: Solid)
  • Invalid or short hex strings may cause Popcorn to exit with errors.
• Font names are strings.
  • If the font is missing or misconfigured, your system may use a fallback.
• Time values are positive integers in milliseconds.

Sections

The configuration file has 4 sections that control specific aspects of the popup:

• [window] - Popup placement and timeout settings.
• [ui] - Base UI geometry and colors.
• [percent_value] - Styling for percentage text.
• [icon] - Styling for icon glyph.

Section 1: [window]

This section controls popup position and how long it stays visible.

popup_timeout

• Auto-hide timeout in milliseconds.
• Default: 1300

pos_x

• Horizontal position of the popup.
• Default: 1146
• Adjust based on your screen resolution.
• Example: 1366px wide screen - 200px popup width - 20px offset = 1146px

pos_y

• Vertical position of the popup.
• Default: 36

Adjust pos_x and pos_y based on your screen resolution and popup width/height.

Section 2: [ui]

Basic popup appearance styling. Set the dimensions according to your screen resolution.

width

• Width of the popup.
• Default: 200
• If you resize the popup, you may need to update pos_x and pos_y to keep it where you expect.

height

• Height of the popup.
• Default: 50

border_radius

• Border radius of the popup.
• Default: 5
• Tip:
  • 0: Sharp corners, rectangular
  • height/2: Circular sides, pill shape
  • Between 0 & height/2: Rounded corners

padding

• Distance from the sides to the icon and the percent value.
• Default: 7

bg_col

• Background color of the popup.
• Default: "675f5f5f"

default_fill_color

• Fallback for no or invalid fill color is supplied via CLI arg --color
• Default: "ff397979"

Section 3: [percent_value]

Controls the percentage text style (for volume, brightness, battery, etc).

font_size

• Font size for the percent value.
• Default: 35

font_color

• Font color for the percentage value.
• Default: "ffffffff"

font

• Font family for the percentage value.
• Default: "Iosevka Extrabold"

Section 4: [icon]

Icon glyph styling configuration.

size

• Font size for the icon glyph.
• Default: 35

color

• Font color for the icon glyph.
• Default: "ffffffff"

font

• Font color for the icon glyph.
• Default: "IosevkaTermSlab Nerd Font Mono"
• Tip: Use Nerd Font icons or another icon font for best results.

default_icon

• Default glyph used when no or invalid icon is suppliedvia CLI arg --icon
• Default: ""

Example

Here's a full working configuration example:

[window]
popup_timeout = 1300
pos_x = 1146
pos_y = 36

[ui]
width = 200
height = 50
border_radius = 5
padding = 7
bg_col = "675f5f5f"
default_fill_color = "ff397979"

[percent_value]
font_size = 35
font_color = "ffffffff"
font = "Iosevka Extrabold"

[icon]
size = 35
color = "ffffffff"
font = "IosevkaTermSlab Nerd Font Mono"
default_icon = ""