## 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:  

```toml  
[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 = ""
```