WinUIEx Documentation

For scenarios requiring more control than the WindowManager provides, use the TrayIcon class directly. Unlike the WindowManager approach, TrayIcon does not have default behaviors and is not automatically tied to a window.

Key capabilities:

• Create tray icons without an associated window (useful for window-less background apps).
• Manage multiple icons for a single process.
• Manually update icons and tooltips.
• Handle specific events like Selected and ContextMenu.

CRITICAL: You must call .Dispose() on all TrayIcon instances when your application closes. If you do not, the icon will remain in the system tray and the application process will not exit.

// Example of a window-less app using TrayIcon
public partial class App : Application
{
    private TrayIcon icon;
    private Window? _window;

    protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
    {
        // Create icon without a window
        icon = new TrayIcon(1, "Images/StatusOK.ico", "Test");
        icon.IsVisible = true;
        
        icon.Selected += (s, e) => GetMainWindow().Activate();
        
        icon.ContextMenu += (w, e) =>
        {
            var flyout = new MenuFlyout();
            flyout.Items.Add(new MenuFlyoutItem() { Text = "Open" });
            ((MenuFlyoutItem)flyout.Items[0]).Click += (s, e) => GetMainWindow().Activate();
            flyout.Items.Add(new MenuFlyoutItem() { Text = "Quit App" });
            ((MenuFlyoutItem)flyout.Items[1]).Click += (s, e) =>
            {
                _window?.Close();
                icon.Dispose(); // Required to exit the process
            };
            e.Flyout = flyout;
        };
    }
}

For advanced background effects like animations or blurring, inherit from CompositionBrushBackdrop. You must override the CreateBrush method, which provides a Windows.UI.Composition.Compositor to create the brush used for the window backdrop.

Custom animated backdrop

By creating a brush and applying a CompositionColorKeyFrameAnimation within CreateBrush, you can create continuously animating backgrounds.

Blurred backdrop

You can create a blurred effect by returning a host backdrop brush using compositor.CreateHostBackdropBrush() inside the CreateBrush override.

// Example: Custom animated composition-brush backdrop
public class ColorAnimatedBackdrop : CompositionBrushBackdrop
{
    protected override Windows.UI.Composition.CompositionBrush CreateBrush(Windows.UI.Composition.Compositor compositor)
    {
        var brush = compositor.CreateColorBrush(Windows.UI.Color.FromArgb(255,255,0,0));
        var animation = compositor.CreateColorKeyFrameAnimation();
        var easing = compositor.CreateLinearEasingFunction();
        animation.InsertKeyFrame(0, Colors.Red, easing);
        animation.InsertKeyFrame(.333f, Colors.Green, easing);
        animation.InsertKeyFrame(.667f, Colors.Blue, easing);
        animation.InsertKeyFrame(1, Colors.Red, easing);
        animation.InterpolationColorSpace = Windows.UI.Composition.CompositionColorSpace.Hsl;
        animation.Duration = TimeSpan.FromSeconds(15);
        animation.IterationBehavior = Windows.UI.Composition.AnimationIterationBehavior.Forever;
        brush.StartAnimation("Color", animation);
        return brush;
    }
}

// Example: Blurred composition-brush backdrop
public class BlurredBackdrop : CompositionBrushBackdrop
{
    protected override Windows.UI.Composition.CompositionBrush CreateBrush(Windows.UI.Composition.Compositor compositor)
        => compositor.CreateHostBackdropBrush();
}

The SimpleSplashScreen is a lightweight way to show an image during startup.

For the fastest possible startup, you can bypass the XAML-generated Main method by defining the DISABLE_XAML_GENERATED_MAIN preprocessor directive. This allows you to show the splash screen as the very first operation in a custom static void Main method, even before the Microsoft.UI.Xaml.Application is fully initialized.

#if DISABLE_XAML_GENERATED_MAIN
  public static class Program
  {
    [System.STAThreadAttribute]
    static void Main(string[] args)
    {
      // 1. Handle any necessary redirection (e.g. WebAuthenticator)
      if (WebAuthenticator.CheckOAuthRedirectionActivation(true))
        return;

      // 2. Show the splash screen immediately
      var fss = SimpleSplashScreen.ShowDefaultSplashScreen();

      WinRT.ComWrappersSupport.InitializeComWrappers();

      // 3. Start the XAML application
      Microsoft.UI.Xaml.Application.Start((p) => {
        var context = new Microsoft.UI.Dispatching.DispatcherQueueSynchronizationContext(Microsoft.UI.Dispatching.DispatcherQueue.GetForCurrentThread());
        System.Threading.SynchronizationContext.SetSynchronizationContext(context);
        new App(fss); // Pass the splash screen instance to your App class
      });
    }
  }
#endif

The SplashScreen class allows you to create a custom splash screen using any XAML layout, enabling features like progress bars and status text.

To implement this:

1. Create a new Window and change its base class from Window to WinUIEx.SplashScreen in both XAML and code-behind.
2. The SplashScreen constructor requires the Type of the window you want to launch after loading is complete.
3. In App.xaml.cs, instantiate the SplashScreen and subscribe to its Completed event to capture the main window instance.
4. Override the OnLoading method in your splash screen class to perform asynchronous setup work. The splash screen will automatically close once OnLoading completes.

// 1. Define the SplashScreen class
public sealed partial class MySplashScreen : WinUIEx.SplashScreen
{
  public MySplashScreen(Type window) : base(window)
  {
    this.InitializeComponent();
  }

  // 2. Perform setup work here
  protected override async Task OnLoading()
  {
    for (int i = 0; i <= 100; i += 10)
    {
      statusText.Text = $"Loading {i}%...";
      progressBar.Value = i;
      await Task.Delay(100);
    }
    // Once this method finishes, the splash screen closes and MainWindow opens
  }
}

// 3. Launch it in App.xaml.cs
protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
  var splash = new MySplashScreen(typeof(MainWindow));
  splash.Completed += (s, e) => m_window = e;
}

To create a 'Minimize-to-Tray' feature, react to the WindowManager.WindowStateChanged event. When the state becomes WindowState.Minimized, set AppWindow.IsShownInSwitchers to false to hide the app from task switchers (like Alt-Tab).

To implement 'Launch-to-Tray', check your application settings during OnLaunched and set the WindowManager.WindowState to WindowState.Minimized immediately, rather than calling Activate() on the window.

protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
    _window = new MainWindow();
    var wm = WindowManager.Get(_window);
    wm.IsVisibleInTray = true; // Show app in tray
    
    // Minimize to tray logic:
    wm.WindowStateChanged += (s, state) =>
        wm.AppWindow.IsShownInSwitchers = state != WindowState.Minimized;

    if (MyAppSettings.LaunchToTray) // Launch minimized
        wm.WindowState = WindowState.Minimized;
    else
        _window.Activate();
}

Use SimpleSplashScreen to display a single image while your application loads. You can show the default splash screen defined in your app manifest or a custom image via a full file path.

To use it, instantiate it in your App constructor. Once your main window is activated, you must manually hide or dispose of the splash screen to remove it from view.

private SimpleSplashScreen fss { get; set; }

public App()
{
  // Use the default splash screen from the app manifest
  fss = SimpleSplashScreen.ShowDefaultSplashScreen();
  
  // OR use a custom image (must be a full path, no relative paths)
  // fss = SimpleSplashScreen.ShowSplashScreenImage(@"C:\path\to\image.png");

  this.InitializeComponent();
}

// In your Window activation logic, hide the splash screen
private void Window_Activated(object sender, WindowActivatedEventArgs args)
{
  ((Window)sender).Activated -= Window_Activated;
  fss?.Hide();
  fss = null;
}