119 lines
5.5 KiB
Markdown
119 lines
5.5 KiB
Markdown
# Desktop widgets
|
||
|
||
Clock and sticky-note widgets sit above the wallpaper and behind windows.
|
||
Drag the clock or a note's title to move it. Release to save, or press Escape to
|
||
cancel. Widgets stop at each other's edges on the same display.
|
||
|
||
Enable it in Settings → Desktop widgets or in your Ferese config:
|
||
|
||
```kdl
|
||
desktop-widgets {
|
||
clock enabled=#true anchor="top_left" margin-x=64 margin-y=80 {
|
||
style "pixel" // or "minimal"
|
||
outputs // every output; or outputs "DP-2"
|
||
width 440
|
||
height 320
|
||
font-family "" // style default; or "Comfortaa"
|
||
bold #false
|
||
time-size 128.0
|
||
date-size 18.0
|
||
time-format "%-I:%M %p" // use "%H:%M" for 24-hour time
|
||
date-format "%a, %b %-d"
|
||
time-zone "" // system zone; or "Africa/Lagos"
|
||
show-date #true
|
||
lowercase #true
|
||
color "" // theme primary text
|
||
date-color "" // theme muted text
|
||
opacity 0.9
|
||
alignment "center" // left, center, right
|
||
gap 4.0
|
||
padding 12.0
|
||
background "" // transparent; or "#10101080"
|
||
radius 16.0
|
||
}
|
||
}
|
||
```
|
||
|
||
Positions: `top_left`, `top_center`, `top_right`, `center_left`, `center`,
|
||
`center_right`, `bottom_left`, `bottom_center`, `bottom_right`.
|
||
Margins affect anchored axes only: a centered horizontal position ignores
|
||
`margin-x`; a centered vertical position ignores `margin-y`.
|
||
All geometry and text sizes use logical pixels and follow the output's scale.
|
||
Increase the widget width/height for longer formats or larger text.
|
||
|
||
Choose **Pixel** for stacked hours and minutes with alternating theme colors,
|
||
or **Minimal** for a plain time/date layout. Pixel zero-pads hours and hides am/pm.
|
||
Formats containing seconds or extra text use a single line. Both styles shrink
|
||
time text to fit. Select a different font in Settings, or set `font-family`.
|
||
|
||
Changes apply live. Colors and fonts follow the theme unless overridden.
|
||
Formatting uses [strftime-compatible formats](https://docs.rs/jiff/latest/jiff/fmt/strtime/index.html).
|
||
Use `%H:%M` for 24-hour time or `%-I:%M %p` for 12-hour time.
|
||
|
||
## Clock limits
|
||
|
||
Clock and note corners follow the shared shell radius. Their `radius` fields
|
||
are accepted for compatibility but do not override it.
|
||
|
||
All clock keys are optional. The example enables the clock (disabled by default);
|
||
the other values illustrate defaults or their empty-string equivalents.
|
||
`outputs` is an array of strings; `enabled`, `bold`, `show-date`, `lowercase` are
|
||
booleans; `width`, `height`, and margins are integers. Other sizes/opacity are numbers.
|
||
|
||
| Fields | Accepted range |
|
||
| --- | --- |
|
||
| `width`, `height` | 64–1600, 32–800 |
|
||
| `margin-x`, `margin-y` | 0–8192 |
|
||
| `time-size`, `date-size` | 8–240, 8–96 |
|
||
| `opacity` | 0–1 |
|
||
| `gap`, `padding`, `radius` | 0–64, 0–64, 0–128 |
|
||
| `font-family`, `time-format`, `date-format` | At most 128 bytes each |
|
||
| `outputs` | At most 32 exact output names, each 1–128 bytes |
|
||
|
||
Formats must be valid; `time-zone` must be empty or a recognized IANA name.
|
||
Colors are empty (inherit), `#RRGGBB` or `#RRGGBBAA`; all numeric values must be finite.
|
||
|
||
## Sticky notes
|
||
|
||
Settings → Desktop widgets → Add note creates a card. Drag its title to move it;
|
||
click Edit for its multiline editor, then Done to finish. Text autosaves after
|
||
500 ms without typing. Escape cancels a drag or finishes editing. Position saves
|
||
on release; dragging changes the anchor to `top_left` and saves pixel margins.
|
||
Title, size and style are also editable in Settings. Notes persist in the config.
|
||
Choose a note’s font in Settings or set `font-family "Comfortaa"` in its `note`
|
||
node. Without an override, notes use the interface font.
|
||
|
||
These are plain-text notes, not Markdown or HTML.
|
||
|
||
```kdl
|
||
desktop-widgets {
|
||
note id="today" title="Today" text="Review the pull request\nTake a break\n" anchor="top_right" margin-x=48 margin-y=80
|
||
}
|
||
```
|
||
|
||
Repeat the `note` node for additional notes; IDs must be unique. Cards stay behind windows
|
||
and take keyboard focus only when clicked. Set `interactive #false` for a fully
|
||
click-through card. Long text wraps; increase height if needed.
|
||
|
||
| Key | Type | Default / accepted values |
|
||
| --- | --- | --- |
|
||
| `id` | string | `"note"`; unique, 1–64 ASCII letters/digits/`-`/`_` |
|
||
| `enabled` | boolean | `true` |
|
||
| `interactive` | boolean | `true`; drag/edit controls; `false` is click-through |
|
||
| `title` | string | `"Note"`; empty hides it; maximum 256 bytes |
|
||
| `text` | string | `""`; multiline plain text, maximum 16 KiB |
|
||
| `outputs` | string array | `[]` means all; at most 32 exact names, each 1–128 bytes |
|
||
| `anchor` | string | `"top_right"`; same nine positions as clock |
|
||
| `margin-x`, `margin-y` | integer | `48`, `80`; 0–8192; anchored edges only |
|
||
| `width`, `height` | integer | `320`, `240`; 120–1200, 80–1200 |
|
||
| `font-family` | string | omitted/empty follows desktop font; maximum 128 bytes |
|
||
| `text-size`, `title-size` | number | `16`, `18`; 8–96 |
|
||
| `color` | string | omitted/empty/`"theme"` follows primary text; or hex color |
|
||
| `background` | string | omitted/`"theme"` follows surface base; empty is transparent; or hex color |
|
||
| `opacity` | number | `0.9`; 0–1, multiplies text/background alpha |
|
||
| `padding`, `gap` | number | `20`, `8`; 0–64 |
|
||
| `radius` | number | `16`; 0–128 |
|
||
| `alignment` | string | `"left"`; `left`, `center`, `right` |
|
||
|
||
At most 32 notes; the entire live config is limited to 60 KiB.
|