Testing and Troubleshooting LaunchBox Themes

Written By launchbox

Last updated About 1 month ago

LaunchBox Desktop themes are loaded from XAML at runtime. That makes theme iteration flexible, but it also means a single invalid binding, missing named control, bad namespace, or malformed XAML file can prevent a view from loading correctly.

This article covers the practical testing and troubleshooting workflow for LaunchBox theme developers.

Test From the LBThemes Folder

LaunchBox Desktop themes are loaded from:

LaunchBox\LBThemes\[Theme Name]\Views

During development, edit the files inside your theme's Views folder and restart LaunchBox to test the result.

Theme changes are applied after LaunchBox reloads the view. For full-theme changes, fonts, plugins, and startup-sensitive view changes, restart LaunchBox instead of relying on a partial refresh.

Use the Theme Manager Flow

Apply LaunchBox themes from:

Tools > Manage > LaunchBox Themes and Media

When a theme is applied, LaunchBox saves the selected theme name, resets some saved details-panel sizing values, and restarts LaunchBox automatically.

This is the preferred flow for testing the theme exactly as users will apply it.

How LaunchBox Finds a View

LaunchBox looks for each requested XAML view in the active theme's Views folder and falls back to the matching Default-theme view when necessary. PlatformFiltersDetailsView.xaml can additionally fall back to GameDetailsView.xaml.

For the complete resolution and fallback rules, see LaunchBox Theme Architecture.

What Happens When XAML Fails to Parse

LaunchBox reads the XAML file, applies compatibility replacements and path placeholders, then loads it with WPF's XAML reader.

If parsing fails, LaunchBox shows an error message for the view that failed to load, then attempts to fall back to the Default theme version of that view.

When troubleshooting, the failing view name is the first thing to check. If the error mentions SideBarView, start with Views\SideBarView.xaml. If it mentions MainView, start with Views\MainView.xaml.

Keep the MainView License Button

MainView.xaml has one required element that should not be removed: the license button and its LicenseText binding.

<Button x:Name="License">      <TextBlock Text="{Binding LicenseText}" />    </Button>

LaunchBox checks for a License button and the {Binding LicenseText} binding when loading MainView.xaml. Removing either can prevent LaunchBox from continuing.

Use LaunchBox Path Placeholders

Use LAUNCHBOX_THEME_FOLDER for theme assets and LAUNCHBOX_ROOT_FOLDER for files under the LaunchBox installation. Avoid absolute paths because they will not work reliably on other systems.

For complete path and asset examples, see Theme Assets, Fonts, and Resource Paths.

Namespace Compatibility

LaunchBox provides compatibility replacements for some older namespaces and interactivity references, but new themes should follow the current namespaces in the Default theme.

For details on load-time compatibility behavior, see the architecture guidance earlier in this collection.

Common Causes of Broken Views

  • Malformed XAML syntax

  • Missing required named controls

  • Removing behavior-critical bindings

  • Using a binding that does not exist on that view model

  • Using an asset path that only works on the developer's machine

  • Referencing an image or font file that is not included in the theme

  • Using a font family name that does not match the font file

  • Moving a control but leaving its popup, event, or command target behind

  • Changing MainView.xaml without preserving the license button and text binding

A Practical Debugging Checklist

  1. Restart LaunchBox after making the change.

  2. Note the view name in any parsing error.

  3. Temporarily compare your view against the Default theme version of the same file.

  4. Check that required named controls still exist.

  5. Check that command, event, and visibility bindings are still present.

  6. Check every custom image and font path.

  7. Remove the most recent layout change and retest if the error started after a specific edit.

  8. If a custom view is not necessary, temporarily remove that file so LaunchBox falls back to Default.

Testing Missing Views

You do not have to customize every view. A theme can include only the views it needs.

If a view is missing from your theme, LaunchBox attempts to load the Default theme's version. This is useful during development because you can focus on one view at a time.

However, partial themes should still be tested across common workflows: switching sidebar filters, viewing boxes and lists, selecting games, opening details, playing music, showing notifications, and running long tasks.

When to Repair or Reinstall a Theme

The LaunchBox Themes and Media manager includes update, repair, and uninstall flows for managed themes. These are useful when a downloaded theme is missing files or has been modified in a way that prevents it from working.

For local development themes, it is usually faster to keep a clean backup of the theme folder, compare against the Default theme files, and replace only the view you are actively troubleshooting.

In Short

Test LaunchBox themes one view at a time, restart often, and use the Default theme as your reference. Preserve required named controls, behavior-critical bindings, and LaunchBox path placeholders. When a view fails, identify the view name, compare against Default, and let LaunchBox's fallback behavior help isolate the problem.