Settings Dialog

Settings Dialog

The Settings Dialog is the front door to nearly every per-collection and global option Kartend supports. Open with Ctrl+, or File → Settings.

This page is a tour of the dialog's structure: what each category covers, how the scope selector propagates changes across collections, the Apply Settings workflow for selectively copying fields, and how to duplicate / reparent / delete collections from the tree.

For a flat list of every config key see Configuration Reference. Most field-level descriptions repeat there; this page focuses on the workflow.

Anatomy

The dialog is a two-pane layout — a navigation rail on the left, the selected category's page on the right:

┌─────────────────────────────────────────────────────────────────┐
│ ┌─ navigation rail ───┐ ┌─ content ────────────────────────────┐ │
│ │ Search settings…    │ │ Appearance                           │ │
│ │ ┌ Collections ────┐ │ │ Editing collection: Arcade           │ │
│ │ │ tree  [+][-][⧉] │ │ │ ──────────────────────────────────── │ │
│ │ │ Mode: Current ▼ │ │ │                                      │ │
│ │ └─────────────────┘ │ │  (selected category's panel)         │ │
│ │ COLLECTION SETTINGS │ │                                      │ │
│ │  Configuration      │ │                                      │ │
│ │  Artwork            │ │                                      │ │
│ │  Appearance   …     │ │                                      │ │
│ │ APPLICATION         │ │                                      │ │
│ │  General      …     │ │                                      │ │
│ └─────────────────────┘ └──────────────────────────────────────┘ │
│  [Save]                                       [Cancel]   [OK]    │
└─────────────────────────────────────────────────────────────────┘

• Navigation rail (left): a search box, the collection tree with add / remove / duplicate buttons and the Mode (scope) selector, and a categorised list of settings pages.
• Content pane (right): a context header naming the current category — and, for per-collection categories, the collection being edited — above the selected page.
• Button row (bottom): Save commits changes without closing the dialog; OK saves and closes; Cancel closes (with a confirm prompt when there are unsaved edits).

The category list is split into Collection settings (per-collection: Configuration, Artwork, Appearance, Launcher, Subfolders, Details Pane) and Application (app-wide: General, Fonts, Splash, Attract Mode, Marquee, Toolbar, Controls, Launchers, Scrapers). Type in the search box to filter the list to categories containing a matching setting.

Drag the splitter handles to resize the rail and to set how its height is split between the collection tree and the category list; the dialog remembers its size and divider positions between runs. The Save button pulses with a drop-shadow glow while there are unsaved changes — an at-a-glance reminder.

Collection tree

Lists every collection (and subcollection) hierarchically. From here you can:

• Add — toolbar + button. Creates a new top-level collection.
• Reparent — drag and drop a collection onto another.
• Rename — double-click the name on the Basic tab (or the context menu Rename).
• Duplicate — right-click → Duplicate opens a dialog asking for the new name and destination parent.
• Delete — right-click → Delete, with a confirm prompt.
• Expand / Collapse — context menu shortcuts to fully expand / collapse a subtree.

Selection in the tree drives the right pane: the tab editor reflects the highlighted collection. Multi-select is not supported — use Apply To Selected for batch operations.

Per-collection categories

Basic

Field	Notes
Name	Display name. Renaming updates references everywhere.
Type	Free-form classification used by the type filter.
Parent Collection	Dropdown of all candidate parents (excluding the current collection and its descendants).
Linked Parents	Multi-select picker for alias parents.

Paths & Extensions

Field	Notes
Media Directory	Path browser. Empty = parent-only collection.
Artwork Directory	Path browser. See Artwork.
Video Directory	Path browser. See Video Previews.
Manual Directory	Path browser. Auto-discovered manuals show in the sidebar.
Placeholder Artwork	File browser. Custom missing-art image.
Collection Icon	File browser. Image used for this collection's tile when it's a subcollection.
Header Logo	File + position dropdown (topleft / topcenter / topright).
Extensions	CSV. Empty = accept all files.
Include Content Subfolders	Show subfolders as virtual tiles.
Include Artwork Subfolders	Recurse into artwork subfolders.
Show All Subfolder Items	Mix subfolder items into the parent's grid.
Show Hidden Folders	Include .dot-prefixed directories.
Custom Artwork Types	CSV of free-form custom type ids.
Extract Archives	Auto-extract archive items.
Extracted Extension	Which extension to launch from inside an archive.

Launcher

See Launchers for the full launcher model.

Section	Notes
Primary Launcher	Path / Name / Core / Parameters fields.
Additional Launchers	List with Add / Edit / Remove buttons.
Default Launcher	Dropdown selecting the pre-selected launcher.
Global Launcher Presets	Reusable presets (lives in [General] but managed here).

Appearance

Section	Notes
View Type	grid / list / coverflow / horizontal. See View Modes.
Grid sizing	gridWidth, alternate grid widths for hidden sidebar, horizontal grid height.
Tile sizing	itemWidth, itemHeight, fontSize, cornerRadius, spacing.
Alignment	left / center / right.
Hide Titles / Hide Subcollection Titles
Hide Horizontal / Vertical Scrollbar
Hide Missing Artwork
Title Exclusion Patterns	Regex patterns stripped from displayed titles, with on/off toggle.

Colors

Section	Notes
Background Type	color / image / video.
Background Color / Image / Video	Tie-ins to the chosen type.
Primary / Tile / Selection Colors	Hex pickers.
Vignette	Enable + intensity slider.
Wallpaper Parallax	Enable + strength slider.
Toolbar Backdrop Blur	Enable + radius.

Sidebar

See Sidebar & Details Pane.

Field groups:

• Visibility & Layout — visible, mode (overlay / expand), position (right / left / top / bottom), width / height, locked-resize.
• Background — color / image / pattern + crosshatch intensity.
• Bubbles — header & section bubble colors with per-bubble opacity.
• Typography — text color, accent color, font family, font size.
• Active Tab — initial tab on first show.

List View

Field	Notes
List Font Size	Row text size.
List Row Height	Pixels.
List Row Color / Alternate Row Color	Stripe colors.

Column widths (listCollectionColumnWidth, listArtworkColumnWidth) are global and apply to the List view across all collections, but they have no Settings Dialog control today — hand-edit kartend.cfg in [General].

Text & Fonts

Field	Notes
Custom Font Family	Per-collection font override.
Title Tint Saturation / Lightness	Tile-title HSV adjustments.
Title Base Color	Hex; empty = use selection color.
Show Title in Placeholder	Global.

Application categories (global settings)

The Application categories apply to the entire app, not the selected collection. They group:

• Selection & Navigation — remember selection, wrap, hover-select.
• Performance — pixmap cache, scroll animation duration, scroll velocity multiplier.
• Keyboard — key bindings (rebindable), repeat intervals, hold delays.
• Mouse — wheel rows, artwork-cycle modifier.
• Gamepad — D-pad / left-stick toggles, button bindings (live capture).
• Sorting — sort mode, exclude-subfolders.
• Filtering — collection type filter. (hideSubcollectionTiles has no UI control today; hand-edit [General] hideSubcollectionTiles in kartend.cfg.)
• View toggles — show menu bar, show toolbar, fullscreen (persistent).
• Toolbar customization — visibility & label per item-page toolbar control.
• Typography — global font family / size, UI text zoom percent, title tints.
• Splash screens — boot, resume-focus, startup video, plus title / subtitle overrides. See Splash & Now Playing.
• Preview video volume — global.
• Runtime detection — toggle.
• Launch history — enabled, max entries.
• Attract mode — enabled, idle timeout, autoscroll, advance selection. See Attract Mode.
• Marquee — secondary-monitor topper window: enable, target screen, mode (artwork vs collection icon). See Marquee.
• Scrapers — provider credentials (TMDB, MusicBrainz, OpenLibrary, ScreenScraper) and global scraper options (preset, concurrency, throttle, rescrape mode, region, scrape logging, auto-resume). See Scraper and Keychain.
• Launchers — the global launcher-preset registry (id / name / path / core / parameters). Referenced by per-collection additionalLaunchers entries. See Launchers.
• Controls — keyboard / gamepad bindings live-capture, repeat / hold timings. Same surface as the Keyboard, Gamepad, and Mouse categories above, organised together. See Input & Controls.
• Home view — synthetic Home category at startup: enable, custom label, custom icon, keyboard shortcut. See Shell Collections.
• RetroArch integration — optional path to a retroarch.cfg / core directory so the Launcher chooser can list libretro cores. See Launchers.
• First-run wizard — firstRunComplete flag. Reset by Help → Setup Wizard… (which re-runs the wizard interactively).
• Startup collection — name of the collection opened on launch.

Each section is a fold-down so the page stays scannable.

Config-only globals — a few [General] keys have no Settings Dialog control and must be edited in kartend.cfg by hand: hideSubcollectionTiles, listCollectionColumnWidth, listArtworkColumnWidth. See Configuration Reference for full descriptions.

Scope selector

The Scope dropdown (top bar) determines what saves apply to:

Scope	Effect
Current	Save changes only to the selected collection.
Current and Subcollections	Save propagates to the selected collection and all of its descendants.
All	Save propagates to every collection.

When scope is wider than Current, fields that cannot propagate sensibly (paths, extensions, parent linkage, launcher path) are grayed out — you can't accidentally overwrite all collections' media directories with one. The grayed list is determined by a category allow-list inside the dialog.

Save with a wider scope is a one-shot: the next time you open the dialog the scope resets to Current.

Watch out — propagating "All" is fast and not reversible from within Kartend. Use it intentionally, especially for appearance sweeps. The Apply Settings workflow is safer for targeted batch updates.

Apply Settings

For finer control than the global scope selector, the Apply To Selected workflow lets you copy specific categories of fields from the current collection to a chosen subset of others.

Open via the action button in the dialog header (or the Settings → Apply To… menu in some builds). The Apply Settings Dialog appears:

1. Source — the collection currently selected in the tree.
2. Categories — a checkbox grid: Basic, Paths, Appearance, Colors, Sidebar, List View, Text & Fonts. Pick which categories to copy.
3. Targets — a tree of collections with multi-select; pick which ones to receive the copied fields.
4. Mode — Pull (overwrite targets with source values) or Propagate (a sub-mode that respects per-collection differences for some fields). The dialog explains the difference inline.
5. OK — applies and closes; Cancel discards.

Fields that can't be copied (paths, parent linkage) are excluded regardless of the category checkboxes.

Workflow tip: use this when you've spent an hour tuning one collection's appearance and want every other collection to match.

Duplicate Collection

Right-click a collection in the tree → Duplicate opens a small dialog:

Field	Notes
New Name	Required, must be unique.
Parent	Sibling of the source / child of the source / root.

On OK, all non-path settings are copied. Paths (mediaDirectory, artworkDirectory, videoDirectory, manualDirectory) are deliberately left blank so you don't accidentally fork into the same folder twice.

Delete Collection

Right-click → Delete prompts for confirmation. Subcollections of the deleted collection are reparented to its parent (or to root if deleting a root collection). Per-item state remains in the database.

Save / Revert / Cancel

• Save — commits all in-memory changes to disk, applying the current scope. The dialog stays open afterward.
• Revert — discards in-memory changes and re-loads from disk. Useful when you've experimented and want to back out.
• Cancel — closes the dialog. If there are unsaved changes, you get a confirm prompt.

The Save button glows with a pulsing drop shadow while there are unsaved changes. Hovering over Revert flags fields that would be restored.

"Restart required" fields

A handful of settings only take effect after restart. The Settings Dialog tags these inline; they're also called out here:

• globalUiFontFamily and globalUiFontPointSize
• pixmapCacheSizeMB
• Some startup ordering knobs (boot splash, startup video)

Most other settings apply live as you click through tabs, including view-mode and sidebar position changes.

Recipes

Apply one collection's appearance to all collections

1. Tune one collection's Appearance, Colors, Sidebar, and Text & Fonts tabs to taste.
2. Click Apply To Selected in the dialog header.
3. Check Appearance, Colors, Sidebar, Text & Fonts under Categories.
4. Select all collections under Targets (Ctrl+A or use the Select All button).
5. OK.

Add a launcher preset and reuse it everywhere

1. Launcher tab → Global Launcher Presets → Add.
2. Fill in name, path, core, parameters.
3. Save.
4. For each collection that should use the preset: Launcher tab → edit any launcher → set the Preset dropdown to the new preset. The inline path/core/params fields gray out — preset values take over.

Reparent half a tree

Drag and drop in the tree. For larger reorganizations, edit the INI file directly: rename the [Parent > Child] section header for each collection to point at the new parent (the section header is the parent record — there's no separate key to flip), then restart.

Disable propagation for a specific tab

The Apply Settings Dialog gates by category, not by tab. If a tab crosses categories (e.g. Appearance + Colors), uncheck the categories you don't want to propagate.

For developers

• Settings UI: src/ui/dialogs/settings/ — the dialog shell is split across sibling translation units (settingsdialog, settingsdialognav for the left-rail navigation, settingsdialogtree, settingsdialogform, settingsdialogbrowse, settingsdialogchecks, …), and each settings page is its own *panel widget added to the pageStack in settingsdialog.ui.
• Persistence: src/modules/data/settings/settingsmanager* drives INI read/write, with configvalidation* for live validation.
• Apply rules: applysettingsdialog.cpp enumerates which fields propagate per category. Non-propagatable fields (paths, parent linkage, extensions, launchers) are listed in the source.
• Save signal flow: SettingsManager::settingsChanged → all managers re-read the parts of CollectionConfig and GeneralSettings they care about.
• Adding a new field: define on CollectionConfig (or GeneralSettings), serialize in the manager, add UI in the appropriate settingsdialog* file, classify into a category in applysettingsdialog, and update Configuration Reference.
• Save-button pulse animation: SettingsDialog::updateSaveButtonStyle and the QGraphicsDropShadowEffect it drives.