Mica support in .NET MAUI

MauiProgram.cs

// ************************************************************************ //
// This implementation is inspired from the official WinUI3 backdrops examples
// https://github.com/microsoft/WinUI-Gallery/blob/winui3/XamlControlsGallery/ControlPagesSampleCode/SystemBackdrops/SystemBackdropsSample2.txt
// *********************************************************************** //

using Microsoft.Maui.LifecycleEvents;

#if WINDOWS10_0_17763_0_OR_GREATER
// The namespace of where the WindowsHelpers class resides
// In older versions of .NET MAUI, this was
//using YOUR_APP.Platforms.Windows
// In newer versions of .NET MAUI, it is now
using YOUR_APP.WinUI;
#endif

namespace YOUR_APP.Maui
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiApp<App>()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                    fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
                });

        // **** THIS SECTION IS WHAT IS RELEVANT FOR YOU ************ //
        builder.ConfigureLifecycleEvents(events =>
        {
#if WINDOWS10_0_17763_0_OR_GREATER

            events.AddWindows(wndLifeCycleBuilder =>
            {
                wndLifeCycleBuilder.OnWindowCreated(window =>
                {
                    window.TryMicaOrAcrylic(); // requires 'using YOUR_APP.WinUI;'
                });
            });
#endif
        });
        // ************* END OF RELEVANT SECTION *********** //

            return builder.Build();
        }
    }
}

WindowHelpers.cs

// **************************************************** //
// Place this class file in your Platforms/Windows folder
// **************************************************** //

using Microsoft.UI.Composition;
using Microsoft.UI.Composition.SystemBackdrops;
using Microsoft.UI.Xaml;
using WinRT;

namespace YOUR_APP.Platforms.Windows
{
    public static class WindowHelpers
    {
        public static void TryMicaOrAcrylic(this Microsoft.UI.Xaml.Window window)
        {
            var dispatcherQueueHelper = new WindowsSystemDispatcherQueueHelper(); // in Platforms.Windows folder
            dispatcherQueueHelper.EnsureWindowsSystemDispatcherQueueController();

            // Hooking up the policy object
            var configurationSource = new SystemBackdropConfiguration();
            configurationSource.IsInputActive = true;

            switch (((FrameworkElement)window.Content).ActualTheme)
            {
                case ElementTheme.Dark:
                    configurationSource.Theme = SystemBackdropTheme.Dark; 
                    break;
                case ElementTheme.Light:
                    configurationSource.Theme = SystemBackdropTheme.Light;
                    break;
                case ElementTheme.Default:
                    configurationSource.Theme = SystemBackdropTheme.Default;
                    break;
            }
            
            // Let's try Mica first
            if (MicaController.IsSupported()) 
            {
                var micaController = new MicaController();
                micaController.AddSystemBackdropTarget(window.As<ICompositionSupportsSystemBackdrop>());
                micaController.SetSystemBackdropConfiguration(configurationSource);
                
                window.Activated += (object sender, WindowActivatedEventArgs args) =>
                {
                    if (args.WindowActivationState is WindowActivationState.CodeActivated or WindowActivationState.PointerActivated)
                    {
                        // Handle situation where a window is activated and placed on top of other active windows.
                        if (micaController == null)
                        {
                            micaController = new MicaController();
                            micaController.AddSystemBackdropTarget(window.As<ICompositionSupportsSystemBackdrop>()); // Requires 'using WinRT;'
                            micaController.SetSystemBackdropConfiguration(configurationSource);
                        }

                        if (configurationSource != null)
                            configurationSource.IsInputActive = args.WindowActivationState != WindowActivationState.Deactivated;
                    }
                };

                window.Closed += (object sender, WindowEventArgs args) =>
                {
                    if (micaController != null)
                    {
                        micaController.Dispose();
                        micaController = null;
                    }

                    configurationSource = null;
                };
            }
            // If no Mica, maybe we can use Acrylic instead
            else if (DesktopAcrylicController.IsSupported())
            {
                var acrylicController = new DesktopAcrylicController();
                acrylicController.AddSystemBackdropTarget(window.As<ICompositionSupportsSystemBackdrop>());
                acrylicController.SetSystemBackdropConfiguration(configurationSource);

                window.Activated += (object sender, WindowActivatedEventArgs args) =>
                {
                    if (args.WindowActivationState is WindowActivationState.CodeActivated or WindowActivationState.PointerActivated)
                    {
                        // Handle situation where a window is activated and placed on top of other active windows.
                        if (acrylicController == null)
                        {
                            acrylicController = new DesktopAcrylicController();
                            acrylicController.AddSystemBackdropTarget(window.As<ICompositionSupportsSystemBackdrop>()); // Requires 'using WinRT;'
                            acrylicController.SetSystemBackdropConfiguration(configurationSource);
                        }
                    }

                    if (configurationSource != null)
                        configurationSource.IsInputActive = args.WindowActivationState != WindowActivationState.Deactivated;
                };

                window.Closed += (object sender, WindowEventArgs args) =>
                {
                    if (acrylicController != null)
                    {
                        acrylicController.Dispose();
                        acrylicController = null;
                    }

                    configurationSource = null;
                };
            }
        }
    }
}

WindowsSystemDispatcherQueueHelper.cs

// **************************************************** //
// Place this class file in your Platforms/Windows folder
// **************************************************** //

using System.Runtime.InteropServices;
using Windows.System; // Required for DllImport attribute and DispatcherQueue

namespace YOUR_APP.Maui.Platforms.Windows;

public class WindowsSystemDispatcherQueueHelper
{
    [StructLayout(LayoutKind.Sequential)]
    struct DispatcherQueueOptions
    {
        internal int dwSize;
        internal int threadType;
        internal int apartmentType;
    }

    [DllImport("CoreMessaging.dll")]
    private static extern int CreateDispatcherQueueController([In] DispatcherQueueOptions options, [In, Out, MarshalAs(UnmanagedType.IUnknown)] ref object dispatcherQueueController);

    object m_dispatcherQueueController = null;

    public void EnsureWindowsSystemDispatcherQueueController()
    {
        if (DispatcherQueue.GetForCurrentThread() != null)
        {
            // one already exists, so we'll just use it.
            return;
        }

        if (m_dispatcherQueueController == null)
        {
            DispatcherQueueOptions options;

            options.dwSize = Marshal.SizeOf(typeof(DispatcherQueueOptions));
            options.threadType = 2;    // DQTYPE_THREAD_CURRENT
            options.apartmentType = 2; // DQTAT_COM_STA

            CreateDispatcherQueueController(options, ref m_dispatcherQueueController);
        }
    }
}

Lance,
Any chance you got this working with Shell Apps?
When using a single page, everything works fine. However, in a shell app, the following elements also get the Mica background resulting in a stacking of the effect:

• Shell.TitleView
• ShellContent

This results in the background for the page's content looking like it's not fully transparent.

If you have any insight as to how we could possible tap into the lifecycle of those components and set them to transparent, I would be very grateful.

You can see this especially well when you add the title bar to a flyout page.

Hi @kolkonos I'm sorry, I didn't see this until now.

What you want to do is not technically possible. That is because WinUI 2 and 3 does not support 100% transparent background Windows. You can get semi-transparent real-time blur (what is called Acrylic).

Update
I just realized you might be talking about the Shell page's background so that you can get the acrylic all the way through. I believe you can achieve that with Styles targeting ContentPage, Shell and possibly NavigationPage, then setting the BackgroundColor to Transparent. Though, I would ask the MAUI team for assistance with that if you're still stuck, you can get help here => https://learn.microsoft.com/en-us/answers/tags/247/dotnet-maui

Yeah, I wasn't talking about the shell, but as you pointed out, the background of the flyout header and content.
Setting those to have a background of transparent has no effect. Matter of fact, the screen shot I attached already has those properties set to transparent. I believe the internals of how those components are rendered (much like the label on a check box in Windows) is overriding the explicit background property. When inspecting the rendered UI, there are many pieces that are added by the platform, and which I cannot seem to be able to target with regular styling.

I will see if the MAUI team has any guidance for me.

NEW APPROACH

Hi folks, we no longer need a bunch of custom code. Microsoft now has an easy API to set the backdrop right on the Window class itself:

window.SystemBackdrop = new MicaBackdrop { Kind = MicaKind.BaseAlt };

Here's what it looks like in MauiProgram.cs

using Microsoft.Maui.LifecycleEvents;

#if WINDOWS10_0_17763_0_OR_GREATER
using Hacked.Maui.Platforms.Windows;
using Microsoft.UI.Composition.SystemBackdrops;
using Microsoft.UI.Xaml.Media;

#endif

namespace MyMauiApp;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            });

        builder.ConfigureLifecycleEvents(events =>
        {
#if WINDOWS10_0_17763_0_OR_GREATER
            events.AddWindows(wndLifeCycleBuilder =>
            {
                wndLifeCycleBuilder.OnWindowCreated(window =>
                {
                    window.SystemBackdrop = new MicaBackdrop { Kind = MicaKind.BaseAlt };
                });
            });
#endif
         }

        return builder.Build();
    }

Here is the result at runtime (note MicaKind.BaseAlt is more tinted than default Mica):

That's good! I'm trying now...

I haven't been able to test it in most situations, so I'd be happy to hear how it goes.

Here are the docs => https://learn.microsoft.com/en-us/windows/apps/design/style/mica#use-mica-with-the-windows-app-sdk

It seems cannot put wasdk api on maui...

You do not install anything, Maui already uses the WinUI3 SDK. Just look at my using statements above, and make sure you have this Windows-only code inside windows ifdef blocks. I've confirmed this works. Sent from Nine<http://www.9folders.com/>

…

________________________________ From: Stella-Lucky-Lee ***@***.***> Sent: Friday, December 29, 2023 8:44 PM To: FHWWC Cc: Author; Comment Subject: Re: LanceMcCarthy/MauiProgram.cs @FHWWC commented on this gist.

________________________________ It seems cannot put wasdk api on maui... — Reply to this email directly, view it on GitHub<https://gist.github.com/LanceMcCarthy/4954ab92ca44c19eb4316d9d683efd50#gistcomment-4811818> or unsubscribe<https://github.com/notifications/unsubscribe-auth/AA23QFEBFKZUDBORFB3FUNTYL5WXDBFKMF2HI4TJMJ2XIZLTSKBKK5TBNR2WLJDHNFZXJJDOMFWWLK3UNBZGKYLEL52HS4DFQKSXMYLMOVS2I5DSOVS2I3TBNVS3W5DIOJSWCZC7OBQXE5DJMNUXAYLOORPWCY3UNF3GS5DZVRZXKYTKMVRXIX3UPFYGLK2HNFZXIQ3PNVWWK3TUUZ2G64DJMNZZDAVEOR4XAZNEM5UXG5FFOZQWY5LFVEYTCNRRGQ3DGMZSU52HE2LHM5SXFJTDOJSWC5DF>. You are receiving this email because you authored the thread. Triage notifications on the go with GitHub Mobile for iOS<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android<https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

Oh sorry, I'm forgot to update the nuget package, now works fine.

@LanceMcCarthy Question for you,

Does this work in shell apps? Ive tried your exact code (and a bunch of other things, i even tried going into the inheritance hierarchy) but nothing seems to work. It feels like .net Maui keeps overriding the default platform behavior.

@ajsuydam There is a ShellPage background color that is overlaying the window background. I forget the exact trick to change it, but I want to say just make sure the Shell page's background color is Transparent.

Yeah, I wasn't talking about the shell, but as you pointed out, the background of the flyout header and content. Setting those to have a background of transparent has no effect. Matter of fact, the screen shot I attached already has those properties set to transparent. I believe the internals of how those components are rendered (much like the label on a check box in Windows) is overriding the explicit background property. When inspecting the rendered UI, there are many pieces that are added by the platform, and which I cannot seem to be able to target with regular styling.

I will see if the MAUI team has any guidance for me.

Hey @kolkonos with the new approach that @LanceMcCarthy listed (just doing it in MauiProgram.cs), I'm now running into the same issue that you are. Did you ever find a solution? @LanceMcCarthy I did try setting those properties, no dice sadly.

@ajsuydam In case you haven't tried it yet, there is an official Discord server for .NET and there's a dedicated MAUI channel. Here's the invite link http://aka.ms/dotnet-discord

@ajsuydam While I was still working on that project, I found some references to creating custom renderes for components. In those articles, which I don’t have handy, they mentioned that you can override the rendering of a built in component by inheriting from it. However I have since had to move off that project, and never tested the suggested approach.
perhaps you can dive into that rabbit hole and keep us posted.

Just watched this vid, and it seems to point in the right direction for overriding or defining custom behavior on default controls or custom ones.
https://www.youtube.com/live/tOCh0d4PpOw?si=H4LClSKD37epxtzb

This has been a long time coming. To all who are still trying to solve this issue... it's done.

full sample: https://github.com/kolkonos/MicaBackdropMAUI

As Lance mentioned, add the mica effect during the lifecycle event. I prefer the MikaKind.BaseAlt as it is more pronounced (more vivid color).

THEN in the AppShell.xaml.cs in the class constructor:

public partial class AppShell : Shell
{
    public AppShell()
    {
        InitializeComponent();

        this.Loaded += (_, _) => {
#if WINDOWS        
          var shellView = `Shell.Current?.Handler?.PlatformView` as ShellView;
          var navigationView = shellView?.Content as MauiNavigationView;

          var contentGrid = navigationView?.GetType()
              .GetProperty("ContentGrid", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance)?
              .GetValue(navigationView) as Microsoft.UI.Xaml.Controls.Grid;

          contentGrid!.Background.Opacity = 0;
#endif
       };
}

It's crucial that you set the opacity to 0 rather than setting the Background to null, as this would cause the framework to fallback to the default.
@ajsuydam

@kolkonos BOOM! Looks great.