Theme-Specific Plugins and Custom Controls

Written By launchbox

Last updated About 1 month ago

Most LaunchBox Desktop theme work should be done with XAML, bindings, styles, images, fonts, and the built-in LaunchBox controls. A plugin should only be used when the theme needs behavior that XAML cannot provide on its own.

LaunchBox can load plugins from the normal LaunchBox Plugins folder, and it can also load plugins from the active LaunchBox theme's own Plugins folder.

Theme Plugin Location

Theme-specific LaunchBox plugins belong inside the theme folder:

LaunchBox\LBThemes\[Theme Name]\Plugins

When LaunchBox starts and loads the active theme, it checks:

LBThemes\[Theme Name]\Plugins

If that folder exists, LaunchBox loads plugins from it for that theme.

When to Use a Plugin

Use XAML first. A plugin is only worth adding when the theme needs custom behavior or reusable controls that cannot be expressed cleanly in XAML.

A plugin may make sense for:

  • A custom WPF control used by one or more theme views

  • Special interaction logic beyond normal bindings and commands

  • Custom data processing for a visual element

  • Integration with LaunchBox plugin APIs

  • Behavior that needs C# code instead of XAML triggers, converters, or templates

A plugin is usually not needed for:

  • Changing layout

  • Changing colors, fonts, spacing, or animations

  • Showing existing LaunchBox data through existing bindings

  • Restyling boxes, lists, details, sidebars, controls, notifications, or backgrounds

  • Referencing custom images or fonts

Theme Plugins Versus Regular Plugins

Regular plugins live in:

LaunchBox\Plugins

Theme-specific plugins live in:

LaunchBox\LBThemes\[Theme Name]\Plugins

Use a regular plugin when the functionality should be available regardless of the active theme. Use a theme-specific plugin when the functionality exists only to support that theme's visuals or custom controls.

Referencing Custom Controls From XAML

If a theme plugin provides a custom WPF control, the theme XAML can reference it with an XML namespace that points to the plugin assembly.

xmlns:custom="clr-namespace:Your.Plugin.Namespace;assembly=YourPluginAssembly"

Then the control can be used in a themed view:

<custom:YourCustomControl />

The exact namespace and assembly name must match the compiled plugin. If either value is wrong, the XAML view will fail to load.

Using Built-In LaunchBox Controls First

Before creating a custom control, check the Default theme for existing controls that may already solve the problem. LaunchBox themes already use built-in controls such as media lists, media previews, star ratings, platform icons, cloud sync indicators, and store links.

Common built-in namespaces include:

xmlns:controls="clr-namespace:Unbroken.LaunchBox.Windows.Controls;assembly=Unbroken.LaunchBox.Windows"    xmlns:dsktp="clr-namespace:Unbroken.LaunchBox.Windows.Desktop.Controls;assembly=LaunchBox"

Using built-in controls keeps the theme simpler and avoids requiring custom compiled code.

Plugin API Access

LaunchBox plugins can use the PluginHelper class to access LaunchBox data and state. For LaunchBox Desktop, PluginHelper.LaunchBoxMainViewModel provides access to parts of the LaunchBox interface.

Examples of available LaunchBox main view model functionality include:

  • Launching games

  • Refreshing displayed data

  • Reading or changing box size

  • Reading the active image group

  • Reading or changing sidebar and game details widths

  • Switching between images and list views

  • Minimizing, maximizing, restoring, or closing LaunchBox

Use these APIs carefully. A theme plugin should support the user's visual experience, not unexpectedly change application state.

Big Box Theme Element Plugins

The plugin API includes IBigBoxThemeElementPlugin, which is specifically designed for Big Box theme elements and controller-style input handling.

That interface is not the normal starting point for LaunchBox Desktop theming. LaunchBox Desktop themes should usually rely on XAML views, built-in controls, standard WPF controls, and normal LaunchBox plugin APIs.

Packaging a Theme With Plugins

If a LaunchBox theme requires a theme-specific plugin, include the plugin files inside the theme's Plugins folder before packaging the theme.

Your Theme Package\      Views      Images      Fonts      Plugins\YourPlugin.dll              AnyRequiredDependency.dll

Only include plugin files that are required by the theme. Do not include development build folders, source files, temporary files, or unrelated dependencies.

Testing Theme Plugins

Theme plugins should be tested with the final packaged theme, not only from the development folder.

  1. Place the plugin files in LBThemes\[Theme Name]\Plugins.

  2. Apply the theme from Tools > Manage > LaunchBox Themes and Media.

  3. Restart LaunchBox.

  4. Verify the theme views that reference the plugin load successfully.

  5. Test any custom controls or plugin-driven behavior.

  6. Package the theme and test the package in a separate LaunchBox folder.

If a plugin-backed control fails to load, check the plugin DLL location, the XAML namespace, the assembly name, missing dependencies, and whether LaunchBox was restarted after adding the plugin.

Common Mistakes

  • Using a plugin when XAML would be enough

  • Putting a theme-specific plugin in the wrong folder

  • Forgetting to include plugin dependencies

  • Referencing the wrong assembly name in XAML

  • Referencing the wrong CLR namespace in XAML

  • Testing with a globally installed plugin but forgetting to include it in the theme package

  • Adding plugin behavior that unexpectedly changes user settings or navigation state

  • Not restarting LaunchBox after adding or changing plugin files

In Short

Use plugins only when a LaunchBox theme needs custom behavior or controls that XAML cannot provide. Theme-specific plugins live in LBThemes\[Theme Name]\Plugins and should be packaged with the theme only when required. Prefer built-in LaunchBox controls and standard XAML first, then use custom plugin code only for the pieces that truly need it.