ThemeManager.PreloadThemeResourceAsync(String, CancellationToken, Boolean) Method

Preloads the specified theme and creates theme resources for all loaded assemblies.

Namespace: DevExpress.Xpf.Core

Assembly: DevExpress.Xpf.Core.v24.1.dll

NuGet Package: DevExpress.Wpf.Core

Declaration

C#

public static Task PreloadThemeResourceAsync(
    string themeName,
    CancellationToken token = default(CancellationToken),
    bool runTypeInitializers = false
)

VB.NET

Public Shared Function PreloadThemeResourceAsync(
    themeName As String,
    token As CancellationToken = Nothing,
    runTypeInitializers As Boolean = False
) As Task

Parameters

Name	Type	Description
themeName	String	A theme you want to preload.

Optional Parameters

Name	Type	Default	Description
token	CancellationToken	null	Indicates whether to cancel the action.
runTypeInitializers	Boolean	False	true to invoke static constructors; otherwise, false.

Returns

Type	Description
Task	A task that allows you to asynchronously return the preloaded theme.

Remarks

Note

The PreloadThemeResourceAsync does not preload lightweight theme resources. To accomplish this task, use the ApplicationThemeHelper.PreloadAsync method instead.

Controls in an application use theme resources (default styles, templates, keys) to change their appearance when you apply a DevExpress WPF Theme to the application.

A WPF application loads a control’s theme resources only when the control is about to be displayed. As a result, consequent windows that rely on DevExpress WPF themes can take longer to appear.

This prolonged display time can be crucial when the first window of your application is lightweight (login form), and the main application window is heavy (contains a massive control\many controls). In this case, the first window appears quickly, but the second one can take a noticeable amount of time to load theme resources.

The PreloadThemeResource and PreloadThemeResourceAsync methods allow you to speed up the display time of subsequent windows. These methods preload theme resources for the control assemblies that are referenced on these windows.

Set the CompatibilitySettings.AllowThemePreload property to true to enable the theme preload.

Load Assemblies

If you need to preload theme resources for a control, ensure that the control’s assembly is loaded beforehand. If the control’s assembly references another assembly, the referenced assembly will be also preloaded.

To get the list of loaded assemblies, use the Debug Modules view.

The following code sample preloads the additionally loaded DevExpress.Xpf.Grid.v24.1.dll and DevExpress.Xpf.PropertyGrid.v24.1.dll assemblies and their dependencies:

App.xaml.cs

using System.Windows;
using System.Threading;
using DevExpress.Xpf.Core;
using DevExpress.Xpf.PropertyGrid;
using DevExpress.Xpf.Grid;

public partial class App : Application {
    static Type[] types;
    static App() {
        CompatibilitySettings.AllowThemePreload = true;
    }
    protected override async void OnStartup(StartupEventArgs e) {
        base.OnStartup(e);

        types = new Type[] { typeof(GridControl), typeof(PropertyGrid) };
        await ThemeManager.PreloadThemeResourceAsync("Office2019Colorful");
    }
}

Cancellation Token

A cancellation token allows you to stop the theme resource preload. Create a cancellation token, pass it to the PreloadThemeResourceAsync method, and use the CancellationTokenSource.Cancel method to stop the theme resource preload. If you cancel the preload, the resources that were already preloaded stay cached.

MainWindow.xaml.cs

using System.Windows;
using System.Threading;
using DevExpress.Xpf.Core;

namespace Application {
    public partial class MainWindow : Window {
        public MainWindow() {
            InitializeComponent();
        }

        static CancellationTokenSource cancelTokenSource = new CancellationTokenSource();

        private async void Button_Click(object sender, RoutedEventArgs e) {
            await ThemeManager.PreloadThemeResourceAsync("Office2019Colorful", cancelTokenSource.Token);
            var window = new Window1();
            window.ShowDialog();
        }

        private void Button_Click_1(object sender, RoutedEventArgs e) {
            cancelTokenSource.Cancel();
        }
    }
}

Asynchronous Theme Resource Preload

How to Use

Asynchronous theme preload works best when the application’s start window is lightweight, like a login form. In this case, you can use the PreloadThemeResourceAsync method to preload theme resources of the second window asynchronously while a user inputs login credentials.

Example

The following code sample creates static constructors and preloads the Office2019Colorful theme resources asynchronously at the application startup.

App.xaml.cs

using System.Windows;
using System.Threading;
using DevExpress.Xpf.Core;

public partial class App : Application {
    static App() {
        CompatibilitySettings.AllowThemePreload = true;
    }
    protected override async void OnStartup(StartupEventArgs e) {
        base.OnStartup(e);
        await ThemeManager.PreloadThemeResourceAsync("Office2019Colorful");
    }
}

Issues

Asynchronous theme resource preload may slow down resource loading from the UI thread. Refer to the following section to avoid this shortcoming: Use Asynchronous Theme Preload on Dispatcher.

Asynchronous Theme Resource Preload on Dispatcher

How to Use

Use this technique when the first application window is heavy and you do not want to slow down the first application window loading.

You can start the asynchronous theme resource preload after the first application window is displayed (on the Dispatcher). In this case, preload does not slow down resource loading from the UI thread of the first application window (as the asynchronous theme resource preload does).

Example

The following code sample starts the theme resource preload after the first application window is displayed:

App.xaml.cs

using DevExpress.Xpf.Core;
using DevExpress.Xpf.Grid;
using DevExpress.Xpf.RichEdit;
using System;
using System.Diagnostics;
using System.Runtime.CompilerServices;
using System.Threading;
using System.Windows;
using System.Windows.Threading;

namespace Application {
    public partial class App : Application {
        static Type[] types;

        static App() {
            CompatibilitySettings.AllowThemePreload = true;
            PreloadThemes();
        }
        [MethodImpl(MethodImplOptions.NoInlining)]
        static void PreloadThemes() {
            types = new Type[] { typeof(GridControl), typeof(RichEditControl) };
            Dispatcher.CurrentDispatcher.BeginInvoke((Action)(() =>
            {
                ThemeManager.PreloadThemeResourceAsync("Office2019Colorful");
            }), DispatcherPriority.Render); 
        }
    }
}

Issues

This technique may increase time required to display a subsequent window if a user opens it while the PreloadThemeResourceAsync method is still loading theme resources. Refer to the next section to avoid this shortcoming.

Asynchronous Theme Resource Preload on Dispatcher with Cancellation Token

When to Use

You can combine the asynchronous theme resource preload (use it on Dispatcher) with a cancellation token. Use this technique to stop the asynchronous theme resource preload process to avoid performance slowdowns when a user opens another window while the preload process is still running.

Performance

This technique does not slow down resource loading from the UI thread (as the asynchronous theme resource preload does).

Example

The following code sample starts to preload theme resources after the first application window is displayed and stops the process if a user opens the gridWindow while the PreloadThemeResourceAsync method is still running:

App.xaml.cs

using DevExpress.Xpf.Core;
using DevExpress.Xpf.Grid;
using DevExpress.Xpf.RichEdit;
using System;
using System.Diagnostics;
using System.Runtime.CompilerServices;
using System.Threading;
using System.Windows;
using System.Windows.Threading;

namespace Application {
    public partial class App : Application {
        static Type[] types;
        internal static CancellationTokenSource source = new CancellationTokenSource();

        static App() {
            CompatibilitySettings.AllowThemePreload = true;
            PreloadThemes(); 
        }
        [MethodImpl(MethodImplOptions.NoInlining)]
        static void PreloadThemes() {
            types = new Type[] { typeof(GridControl), typeof(RichEditControl) };
            Dispatcher.CurrentDispatcher.BeginInvoke((Action)(() =>
            {
                ThemeManager.PreloadThemeResourceAsync("Office2019Colorful", source.Token);
            }), DispatcherPriority.Render);
        }
    }
}

MainWindow.xaml.cs

using DevExpress.Xpf.Core;
using System;
using System.Diagnostics;
using System.Threading;
using System.Windows;

namespace PreloadWorks {
    public partial class MainWindow : ThemedWindow {
        private void Button_Click(object sender, RoutedEventArgs e) {
            var gridWindow = new GridWindow();
            App.Current.MainWindow = gridWindow;
            App.source.Cancel();
            gridWindow.Show();
            Close();
        }
    }
}

Issues

If you cancel the running theme preload process, not all resources may be loaded when a user opens the window with the controls that use these theme resources. In this case, WPF loads unloaded theme resources as it is designed in the framework.

Synchronous Theme Resource Preload

When to Use

This technique works best when you display a splash screen at the application startup. In this case, the method loads a control’s theme resources while the Splashscreen is displayed.

Performance

Theme preload slows down application startup, but speeds up startup of subsequent windows that use preloaded theme resources.

Example

Call the PreloadThemeResource method to preload theme resources synchronously.

The following code sample preloads Data Grid and LayoutControl assemblies while the Splashscreen Manager is displayed:

App.xaml.cs

using DevExpress.Xpf.Core;
using DevExpress.Xpf.Grid;
using DevExpress.Xpf.LayoutControl;
using System;
using System.Runtime.CompilerServices;
using System.Windows;

public partial class App : Application {
    static Type[] types;
    static App() {
        CompatibilitySettings.AllowThemePreload = true;
        PreloadThemes();
    }
    [MethodImpl(MethodImplOptions.NoInlining)]
    static void PreloadThemes() {
        types = new Type[] { typeof(GridControl), typeof(LayoutControl) };
        SplashScreenManager.CreateThemed().ShowOnStartup();
        ThemeManager.PreloadThemeResource("Office2019Colorful");
    }
}

View Example: Synchronously Preload WPF Themes Within Splashscreen