config.ini.example

; Hosula config — copy this file to ~/.config/hosula/config.ini
; (or $XDG_CONFIG_HOME/hosula/config.ini) and fill in your own values.
; There is no in-app settings UI; this file is the only way to configure
; Hosula. It's read once at startup — restart the app after editing.

[general]
; Comma-separated list of stops to show departures for (required, no
; default). Each entry can be either:
;   - a Digitransit GTFS ID, e.g. HSL:1173434 (find yours at
;     https://reittiopas.hsl.fi/ or https://digitransit.fi/en/developers/), or
;   - a stop name to fuzzy-search for, e.g. Ristikkokatu - resolved to a
;     GTFS ID once at startup. Most stop names actually have two stops
;     (one per direction) - if the name matches several stops that all
;     share that exact name, all of them are included (a warning is
;     logged, since there's no way to tell which direction you meant);
;     a broader fuzzy match against a genuinely different-named stop is
;     left out. A name matching nothing is dropped (also warned).
; One stop is shown as a single tile; more than one are tiled to fit the
; widget's overall size (width_scale/height_scale below) at a readable
; minimum size - stops that don't fit are dropped from the end of this
; list, with a warning logged.
stop_ids=HSL:1173434,Ristikkokatu

; Subscription key from https://portal-api.digitransit.fi/ (required,
; no default — requests without a valid key are rejected by the API).
api_key=YOUR_DIGITRANSIT_API_KEY

; How often to poll the Digitransit Routing API, in seconds. 20-30 is a
; reasonable range; values below 5 are ignored and 25 is used instead,
; to avoid hammering the API on a typo.
refresh_seconds=25

; Which corner of the screen to anchor the widget to.
; One of: top-left, top-right, bottom-left, bottom-right
anchor=top-right

; Which wlr-layer-shell stacking layer to render the widget in - this
; controls whether *other* windows can end up covering Hosula, not the
; other way around. One of: background, bottom, top, overlay
;   - top (the default): renders above ordinary windows. A fullscreen
;     app (e.g. a video player or browser) can still cover the widget
;     though - fullscreen surfaces get promoted to this same layer by
;     the compositor, and which one of two same-layer surfaces wins is
;     left up to the compositor, not something Hosula controls.
;   - overlay: renders above *everything*, including fullscreen
;     surfaces (those are only ever promoted to top, not overlay) - a
;     true "always visible, no exceptions" mode, if that's what you
;     want (some people find that annoying, hence this being opt-in
;     rather than the default).
;   - bottom / background: renders *below* ordinary windows too - the
;     opposite of a kiosk display; anything covering that part of the
;     screen, fullscreen or not, will cover the widget instead.
layer=top

; IANA timezone name to render departure times in, e.g. Europe/Helsinki.
; Leave empty (the default) to use the system's own configured timezone.
; The underlying Digitransit data is always Helsinki-local regardless of
; where Hosula runs, so set this explicitly if the machine running
; Hosula isn't itself configured for Europe/Helsinki.
timezone=

; Fraction of the target screen's width/height the widget occupies,
; each independently clamped to [0.1, 1.0]. Two separate knobs (not one
; "scale") since a departure list reads better taller than it is wide -
; these defaults give roughly a 2:3 (~6:9) box on a 1920x1080 screen.
; Note the resulting shape varies a bit across differently-shaped
; monitors, since both are fractions of that specific screen's own
; dimensions.
width_scale=0.15
height_scale=0.4

; How many hours into the future to fetch/show departures for. Clamped
; to [0.25, 24.0] - below 15 minutes there's rarely anything to show.
; If more departures exist in this window than fit in the height above,
; the list scrolls rather than being cut off.
departure_window_hours=3.0

; Whole-window opacity, clamped to [0.05, 1.0]. Distinct from
; tile_opacity/tile_bg_color below (which only tint each tile's own
; background box, not the outer title/status area or any text) - this
; dims the *entire* widget, text included, same idea as a terminal
; emulator's opacity slider. Note text readability degrades along with
; everything else at low values, since it all fades together; there's
; no way to keep text fully opaque while only fading the background
; using this knob specifically - see tile_opacity for that instead.
widget_opacity=1.0

; Each tile's own background box: a color (as "#RRGGBB") and its own
; opacity, independent of widget_opacity above. tile_opacity is clamped
; to [0.0, 1.0] - unlike widget_opacity, 0 is a legitimate choice here
; (no visible box behind the text at all, just the widget's own window
; showing through - this was the only, hardcoded look before these
; became configurable). The default below is a 50% white tint: enough
; to make the departure list comfortably readable over a busy
; wallpaper without fully hiding it. An invalid tile_bg_color falls
; back to this same default with a warning, rather than failing
; startup - there's always a safe color to substitute.
tile_opacity=0.5
tile_bg_color=#000000

; Wayland output name to anchor the widget to, e.g. DP-5 (find yours via
; `wlr-randr`, `kscreen-doctor -o`, or Hosula's own startup log, which
; lists detected monitor names on a "Monitor not found" error). Leave
; empty (the default) to use whatever screen Qt picks by default. If set
; but not currently connected, Hosula shows an error dialog and exits
; rather than silently falling back - useful given a laptop's connected
; monitors can vary by dock/day.
monitor=

; Extra pixel padding between the widget and the corner it's anchored
; to (from anchor= above), for nudging it into alignment with existing
; desktop widgets/panels. Defaults to 0 (flush against anchor= with only
; the built-in 16px margin). The two axes work a bit differently:
;
; x_offset is absolute: positive always nudges the widget right on
; screen, whichever corner is anchored - e.g. x_offset=100 moves a
; top-left widget 100px right (away from its left-anchored edge) and a
; top-right widget also 100px right (towards its right-anchored edge).
;
; y_offset is relative to the anchored edge: positive always nudges the
; widget away from whichever vertical edge it's anchored to, deeper into
; the screen - down for a top-* anchor, up for a bottom-* anchor. (Not
; "always down" like x_offset is "always right" - for a bottom anchor,
; a bigger y_offset moving the widget *closer* to the bottom edge would
; be the opposite of what nudging it into alignment usually means.)
x_offset=0
y_offset=0