LaunchBox Theme Architecture

LaunchBox Desktop themes are loaded through LaunchBox's WPF view system. When LaunchBox needs a themeable view, it looks for a matching XAML file in the active theme folder. If that file is missing or cannot be loaded, LaunchBox can fall back to the Default theme.

The Active Theme

LaunchBox stores the selected Desktop theme in its settings. During startup, LaunchBox loads that theme from:

LaunchBox\LBThemes\[Theme Name]

If the selected theme folder does not exist, LaunchBox uses:

LaunchBox\LBThemes\Default

Theme changes require a LaunchBox restart because the main interface is built from the selected theme during startup.

View Resolution

LaunchBox resolves theme views by file name. When a view model needs a view, LaunchBox checks the active theme's Views folder for a XAML file with the matching view name.

For example, the main LaunchBox window uses:

LaunchBox\LBThemes\[Theme Name]\Views\MainView.xaml

The game details panel uses:

LaunchBox\LBThemes\[Theme Name]\Views\GameDetailsView.xaml

The platform, category, and playlist details panel uses:

LaunchBox\LBThemes\[Theme Name]\Views\PlatformFiltersDetailsView.xaml

Fallback Behavior

If a view is missing from the active theme, LaunchBox looks for the same view in the Default theme.

For example, if this file is missing:

LaunchBox\LBThemes\My Theme\Views\ControlsView.xaml

LaunchBox can use:

LaunchBox\LBThemes\Default\Views\ControlsView.xaml

This allows theme developers to customize only the views they need. A theme does not have to replace every XAML file to work.

There is one additional fallback: if PlatformFiltersDetailsView.xaml is missing, LaunchBox can fall back to GameDetailsView.xaml.

Theme Path Placeholders

LaunchBox resolves LAUNCHBOX_THEME_FOLDER to the active theme and LAUNCHBOX_ROOT_FOLDER to the LaunchBox installation while loading XAML.

For asset, font, and image examples, see Theme Assets, Fonts, and Resource Paths.

Namespace Compatibility

LaunchBox also updates several older namespace strings while loading theme XAML. This helps older themes continue working after internal namespace changes.

For current themes, use the namespaces and examples from the generated Default theme whenever possible.

MainView License Requirement

MainView.xaml must preserve LaunchBox's required license UI. Custom themes should keep both of these pieces in the main view:

• A binding to LicenseText.

• A button named License.

If these required elements are removed, LaunchBox will reject the custom MainView.xaml. When customizing the main layout, move or restyle the license UI if needed, but do not remove it.

Theme Plugins

Most themes are pure XAML, but advanced themes can load plugin DLLs from their own Plugins folder when bindings, converters, and templates are not enough.

For plugin locations, custom controls, packaging, and testing guidance, see Theme-Specific Plugins and Custom Controls.

Startup and Pause Themes Are Separate

The Desktop theme engine described here only covers the main LaunchBox interface in LBThemes.

Game startup, shutdown, and pause screens use separate folders and a different lookup system:

LaunchBox\StartupThemes    LaunchBox\PauseThemes

Those systems should be treated as related but separate theming engines.

Related Articles

• LaunchBox Theme Files and Folder Structure

• MainView Layout and Composition

• Testing and Troubleshooting LaunchBox Themes

In Short

LaunchBox Desktop themes are loaded by matching view names to XAML files in LBThemes\[Theme Name]\Views. Missing or broken views can fall back to the Default theme, assets can be referenced with theme path placeholders, and MainView.xaml must keep the required license UI.