Skip to content

View Modes

Jump to bottom
github-actions[bot] edited this page May 30, 2026 · 5 revisions

View Modes

Each collection can be displayed in one of four view modes. The choice is per-collection (it's part of the collection's settings) but you can switch on the fly — the toolbar's view dropdown and Ctrl+1–Ctrl+4 swap modes immediately.

Mode Shortcut Best for
Grid (default) Ctrl+1 Cover-art-driven libraries: games, movies, photos.
List Ctrl+2 Long, text-heavy libraries: documents, music tracks, tools.
Cover Flow Ctrl+3 Showcase / kiosk / slideshow-style browsing.
Horizontal Ctrl+4 TV-style row layouts and wide displays.

Where to find this — Settings Dialog → Appearance tab → View Type, or toolbar View dropdown. Also persisted as viewType=grid|list|coverflow|horizontal in the collection's INI section.

Selection state is preserved across mode switches (assuming rememberSelection=true, the default), so you can flip between Grid and List without losing your place.

Grid view

The default. Tiles flow left-to-right, wrapping into rows. Vertical scroll is primary.

Setting INI key Notes
Items per row gridWidth Default 4. Adjust live with Ctrl++ / Ctrl+-.
Tile width itemWidth Pixels.
Tile height itemHeight Pixels.
Tile font size fontSize Title text size.
Tile corner radius cornerRadius Rounded-corner radius.
Horizontal gap horizontalSpacing Pixel gap between columns.
Vertical gap verticalSpacing Pixel gap between rows.
Alignment horizontalAlignment left, center, right.
Hide titles hideTitles Hide the title line under each tile.
Hide subcollection titles hideSubcollectionTitles Hide titles only on subcollection tiles.
Hide horizontal scrollbar hideHorizontalScrollbar
Hide vertical scrollbar hideVerticalScrollbar

Sidebar interaction

When the Expand sidebar is docked (see Sidebar & Details Pane), the available grid area shrinks. To avoid awkwardly-sized tiles, Kartend supports an alternate gridWidth that takes effect when the sidebar is hidden:

Key Effect
gridWidthSidebarHidden Replaces gridWidth while the Expand sidebar is hidden.
gridHeightSidebarHidden Replaces vertical fit when the sidebar is docked top/bottom.

Set both if you toggle the sidebar often.

Performance

Grid view uses virtual scrolling: only the visible rows are materialized. A 100,000-item collection renders the same as a 100-item one. The pixmap cache budget (pixmapCacheSizeMB global, default 50) bounds memory.

List view

One item per row. Columns: collection icon (or item type icon), item name, optional artwork thumbnail. Vertical scroll is primary; horizontal scroll appears only when columns overflow.

Setting INI key Notes
Row height listRowHeight Pixels. Default 40.
Font size listFontSize Default 11.
Row color listRowColor Hex.
Alternate row color listAltRowColor Hex. Stripes every other row.
Collection-icon column width [General] listCollectionColumnWidth Global, default 150. Config-only — no Settings Dialog control.
Artwork column width [General] listArtworkColumnWidth Global, default 32. Config-only — no Settings Dialog control.

List view honors keyboard repeat tuned for fast scrolling: see listKeyboardRepeatIntervalMs (default 50) and listClickHoldRepeatIntervalMs (default 80) under Configuration Reference. Holding ↓ in List view scrolls roughly 5× faster than in Grid by default — tune to taste.

When to use List

  • Long collections of similar-looking items (text files, manuals, music tracks) where artwork doesn't help discrimination
  • Discoverability via item name rather than cover art
  • Side-by-side comparison of metadata in the sidebar (Item tab updates per row)

Cover Flow view

3D-style center-focus carousel. The selected item is rendered large in the center; nearby items angle off to either side. Driven by horizontal scroll.

Notable behavior

  • Sidebar is automatically hidden while in Cover Flow so the carousel takes the full viewport. When you switch away from Cover Flow, the sidebar returns to whatever state it was in beforehand (your sidebarVisible preference is preserved, just temporarily overridden).
  • Video-first: if the selected item has a preview video in the collection's videoDirectory, it plays full-screen in the Cover Flow center tile instead of artwork. Falls back to artwork when no video is available. See Video Previews.
  • Keyboard: ← / → move selection along the carousel. Enter launches. Ctrl+1–4 switch to another mode.

Settings

Most Grid-view appearance keys (item width / height, corner radius, font size, background) apply identically. The carousel's animation timing is global and lives in UIConstants; tuning it requires a rebuild (see docs/dev/constants.md).

When to use Cover Flow

  • Showcase displays, kiosk setups, attract-mode walls
  • Collections where video previews are the primary content (e.g. movie reels, demoscene productions)
  • A movie-poster vibe where one cover gets full attention at a time

Horizontal view

Like Grid, but the wrap axis is flipped: items flow top-to-bottom, wrapping into columns. Horizontal scroll is primary.

Setting INI key Notes
Items per column horizontalGridHeight Default 4. Re-uses the gridWidth UI; just renamed conceptually.
Items per column when sidebar hidden horizontalGridHeightSidebarHidden Override for Expand sidebar interactions.

All other Grid keys (tile width / height, fonts, colors, spacing, backgrounds, parallax, vignette) apply.

When to use Horizontal

  • Wide displays where vertical scroll feels cramped
  • TV-row layouts mimicking streaming-app shelves (one long row of items)
  • Collections where you want a very shallow vertical fit (one or two rows) — set horizontalGridHeight=1 or 2

Switching between views

Three ways:

  1. Toolbar — click the View dropdown. Each option triggers an immediate switch and writes the new viewType for the collection.
  2. Keyboard — Ctrl+1 (Grid), Ctrl+2 (List), Ctrl+3 (Cover Flow), Ctrl+4 (Horizontal).
  3. Settings Dialog — Appearance tab → View Type dropdown. Useful when you want to flip multiple collections at once via the scope selector.

Hiding view buttons in the toolbar

Each view button can be hidden globally:

[General]
toolbarShowGridViewButton=true
toolbarShowListViewButton=true
toolbarShowCoverFlowViewButton=false
toolbarShowHorizontalViewButton=false

The keyboard shortcuts and the View → Layout menu still work; only the toolbar buttons are hidden. See Toolbar & Menus.

You can also rename buttons:

toolbarGridViewButtonText=Tiles
toolbarListViewButtonText=Rows

Per-collection vs. global default

There is no global "default view" setting per se — each collection remembers its own viewType. To apply one mode to many collections at once:

  1. Set the desired view on a representative collection.
  2. Open Settings → use the Apply To Selected workflow with the Appearance category checked. See Settings Dialog.

Selection indicator

Across all view modes, the selected item is marked by a translucent selection overlay painted on top of the tile, tinted by selectionColor (per-collection, see Themes & Appearance). When you move selection — arrow keys, mouse click, gamepad, alphabetic jump — the overlay glides from the previous tile to the new one rather than jump-cutting. The animation is short (matching the scroll ease) so rapid keypresses still feel responsive.

Specifics:

  • During click-and-hold scrolling the overlay is force-visible so you can see where the cursor is even as the grid scrolls underneath.
  • In Cover Flow the carousel itself moves the center slot; the overlay is suppressed in favor of the carousel's depth/scale cues.
  • The animation timing lives in UIConstants and is not a user-tunable setting today. If you need the indicator to jump instantly (e.g. for accessibility or recording), file a feature request.

Comparison table

Aspect Grid List Cover Flow Horizontal
Scroll axis Vertical Vertical Horizontal (carousel) Horizontal
Sidebar default Available Available Forced hidden Available
Video previews Sidebar only Sidebar only Full-screen center tile Sidebar only
Best for Cover-driven libraries Text-heavy libraries Kiosk / attract TV / wide displays
Preserves selection across mode switch ✓ ✓ ✓ ✓

For developers

  • View modes are a ViewType enum in src/utils/app/collectiontypes.h.
  • Each mode is wired through ScrollManager and a corresponding view-engine class under src/modules/input/scroll/:
    • Grid / Horizontal share the VirtualScrollEngine.
    • List has its own row-rendering path.
    • Cover Flow lives in the coverflow view engine and has its own interaction handler that overrides default arrow-key behavior.
  • Sidebar suppression in Cover Flow is an external hide flag set on SidebarManager — it bypasses the persisted sidebarVisible and is cleared on view-mode change so the user's preference returns.
  • Adding a new view mode involves: extending ViewType, adding a view engine, wiring it into ScrollManager::switchViewMode(), adding the toolbar button + menu entry + keyboard shortcut, adding visibility & label keys to GeneralSettings, and updating Configuration Reference.

Clone this wiki locally