[macOS] Add NativeDock.Menu API for adding menu items to macOS dock icon by drasticactions · Pull Request #20634 · AvaloniaUI/Avalonia

drasticactions · 2026-02-07T16:37:40Z

What does the pull request do?

This PR adds support for a native Dock menu interop for macOS, allowing apps to customize the menu shown when right-clicking the app icon in the dock.

For this, I added some new APIs to the Avalonia.Native codebase and sample usage in ControlGallery. If you right click the dock in ControlGallery, you can open a new window or pull up the main window.

As this adds new APIs, we'll need to do an API review.

What is the current behavior?

There is currently no way to add dock menu items in Avalonia, without pulling in the .NET MacOS SDK bindings and doing it yourself.

What is the updated/expected behavior with this PR?

In Application.xaml

  <NativeDock.Menu>
    <NativeMenu>
      <NativeMenuItem Header="New Window" Click="OnDockNewWindowClicked"/>
      <NativeMenuItemSeparator/>
      <NativeMenuItem Header="Show Main Window" Click="OnDockShowMainWindowClicked"/>
    </NativeMenu>
  </NativeDock.Menu>

        public void OnDockNewWindowClicked(object? sender, EventArgs e)
        {
            if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime)
            {
                var window = new MainWindow();
                window.Show();
            }
        }

        public void OnDockShowMainWindowClicked(object? sender, EventArgs e)
        {
            if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktopLifetime)
            {
                desktopLifetime.MainWindow?.Activate();
            }
        }

NativeDock.Menu lets you add menu items to the macOS dock icon.

How was the solution implemented (if it's not obvious)?

I refactored the NativeMenu API to be usable for both the Native taskbar menu and dock for macOS and added the interop code to the Avalonia.Native dylib. The API should function similar to what is done for NativeMenu, only it's for the dock. This only supports macOS.

Checklist

Added unit tests (if possible)? (tests/Avalonia.Controls.UnitTests/NativeMenuTests.cs)
Added XML documentation to any related classes?
Consider submitting a PR to https://github.com/AvaloniaUI/avalonia-docs with user documentation

Breaking changes

Obsoletions / Deprecations

Fixed issues

avaloniaui-bot · 2026-02-07T17:11:25Z

You can test this PR using the following package version. 12.0.999-cibuild0062029-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

kekekeks · 2026-02-07T19:45:01Z

src/Avalonia.Native/AvaloniaNativeDockMenuExporter.cs

+
+namespace Avalonia.Native
+{
+    internal class AvaloniaNativeDockMenuExporter : INativeMenuExporter, INativeMenuExporterResetHandler


Why do we need a separate exporter when tray menu reuses the shared one?

Avalonia/src/Avalonia.Native/TrayIconImpl.cs

Line 17 in 61f8103

MenuExporter = new AvaloniaNativeMenuExporter(_native, factory);

I'd suggest to just change that ctor of AvaloniaNativeMenuExporter to accept Action<IAvnMenu> and reuse the existing class

In my head I was thinking about NativeMenu.Menu and didn't consider what TrayIcon did. I'll try changing it.

Updated with 3cdf0d4

kekekeks · 2026-02-07T19:45:20Z

tests/Avalonia.Controls.UnitTests/NativeMenuTests.cs

+using Avalonia.UnitTests;
+using Xunit;
+
+namespace Avalonia.Controls.UnitTests


You have 6 tests for an attached property registration.

This is what happens when you use Claude for writing tests and don't actually look at it. Sorry, should have caught that these are basically useless.

Removed and replaced with Appium tests, 464ad50. These just validate that the dock items can be updated, checking the dock itself with Appium seemed very flakey on my machine so I want to validate it doesn't throw before going too crazy.

kekekeks · 2026-02-07T19:57:22Z

native/Avalonia.Native/src/OSX/main.mm

-
-
+
+    virtual HRESULT SetDockMenu(IAvnMenu* dockMenu) override


What happens if this is called after initial startup?

It updates the dock menu. You can dynamically update the dock menu with new menu items (Although IMO it's a bad idea to do it because it won't be obvious to users that the items have changed). I updated the tests and the ControlGallery app (cc90f5c) to show it.

kekekeks · 2026-02-07T20:16:16Z

native/Avalonia.Native/src/OSX/menu.mm

    return s_appMenuItem;
 }

+static IAvnMenu* s_dockMenu = nullptr;


Actually, you can just save NSMenu* reference somewhere in app.mm, no need to keep a COM reference here.

I was following the pattern with what was used for NativeMenu Menu's (Basically copy/paste it but with "Dock" instead.) Yeah, this could be simplified, changed with f47b0d6

avaloniaui-bot · 2026-02-08T03:00:35Z

You can test this PR using the following package version. 12.0.999-cibuild0062031-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

maxkatz6 · 2026-02-08T04:10:28Z

Related #7487
And #8567

drasticactions · 2026-02-08T06:18:06Z

Related #7487 And #8567

For #8567, this could be used as a starting point for a feature like that. I don't want to implement that wholesale for this PR, since this needs to be back ported to 11.x and I rather not add more APIs than needed for that, but for 12.x I could see it.

kekekeks · 2026-02-08T08:21:37Z

src/Avalonia.Native/INativeMenuExporterResetHandler.cs

@@ -0,0 +1,8 @@
+namespace Avalonia.Native
+{
+    internal interface INativeMenuExporterResetHandler


This part of the change set isn't needed anymore

Yeah, will revert.

Reverted with 6582192

drasticactions · 2026-02-08T09:51:10Z

src/Avalonia.Native/IAvnMenu.cs

+        private Action _queueReset = null!;
+        private Action _updateIfNeeded = null!;


Since I got rid of the common interface, I changed the internal calls in IAvnMenu to Actions so they could be called by both Menu and DockMenu calls. If you feel this should be different I'm open to it.

avaloniaui-bot · 2026-02-08T10:18:00Z

You can test this PR using the following package version. 12.0.999-cibuild0062035-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

avaloniaui-bot · 2026-02-08T11:18:03Z

You can test this PR using the following package version. 12.0.999-cibuild0062037-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

drasticactions · 2026-02-08T12:18:08Z

Re. d8c34cc

Between Github CI runners and Appium, finding a way to interact with the Dock in macOS has proven very hard. Looking at the TrayIcon tests, those seemed to have been turned off for similar reasons. I'm still thinking of how to solve that, but the test that invokes the dock menu is running and working.

avaloniaui-bot · 2026-02-11T11:20:34Z

You can test this PR using the following package version. 12.0.999-cibuild0062152-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

avaloniaui-bot · 2026-02-13T13:58:14Z

You can test this PR using the following package version. 12.0.999-cibuild0062201-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

drasticactions · 2026-02-13T14:03:11Z

src/Avalonia.Native/AvaloniaNativeMenuExporter.cs

 {
    internal class AvaloniaNativeMenuExporter : ITopLevelNativeMenuExporter
    {
+        internal enum MenuTarget { Application, Window, TrayIcon, Dock }


The logic before was checking against which object in the exporter was null. Adding an enum to check against this when it's created and using a switch seemed safer to me, but I'm open to changes to this.

avaloniaui-bot · 2026-02-13T14:54:03Z

You can test this PR using the following package version. 12.0.999-cibuild0062211-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

avaloniaui-bot · 2026-02-16T10:13:01Z

You can test this PR using the following package version. 12.0.999-cibuild0062275-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

src/Avalonia.Controls/NativeDock.cs

avaloniaui-bot · 2026-02-17T05:37:06Z

You can test this PR using the following package version. 12.0.999-cibuild0062299-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

MrJul

LGTM!

avaloniaui-bot · 2026-02-19T05:59:31Z

You can test this PR using the following package version. 12.0.999-cibuild0062350-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

Requested changes have been made.

drasticactions added 5 commits February 6, 2026 17:00

Native DockMenu code

00570c4

Add Native Interop

75bc2a6

Update ControlCatalog sample

f9d8eb3

Add unit tests

0b71e07

Merge branch 'master' into dev/timill/DockMenu

169aadf

timunie added the customer-priority Issue reported by a customer with a support agreement. label Feb 7, 2026

MrJul added feature needs-api-review The PR adds new public APIs that should be reviewed. backport-candidate-11.3.x Consider this PR for backporting to 11.3 branch os-macos labels Feb 7, 2026

kekekeks requested changes Feb 7, 2026

View reviewed changes

kekekeks previously requested changes Feb 7, 2026

View reviewed changes

kekekeks reviewed Feb 7, 2026

View reviewed changes

drasticactions added 4 commits February 8, 2026 10:44

Add Action<IAvnMenu> to AvaloniaNativeMenuExporter

3cdf0d4

Add dynamic dock item demo

cc90f5c

Move s_dockMenu reference to App

f47b0d6

Use Appium tests

464ad50

kekekeks reviewed Feb 8, 2026

View reviewed changes

Revert INativeMenuExporterResetHandler

6582192

drasticactions commented Feb 8, 2026

View reviewed changes

drasticactions added 2 commits February 8, 2026 19:27

Properly set the button for the checkbox

cefdae2

Add dock test

b26b2e2

I hate Appium

d8c34cc

Make static

ae69be5

Merge branch 'master' into dev/timill/DockMenu

2a5cf63

drasticactions added 3 commits February 13, 2026 22:59

Remove Dock Click Test

d4d5741

Add white space back for cleaner diff

6f2e92c

Reduce MenuExporter back to one

38d9f4d

drasticactions commented Feb 13, 2026

View reviewed changes

drasticactions added 5 commits February 13, 2026 23:06

Revert UpdateIfNeeded to private

df939af

Revert QueueReset to private too... and fix some whitespace

57f1095

Revert IAvnMenuItem/IAvnMenu back

a148ca1

That's what I get not comparing it to master

70f5a7c

And update this too

8ae3b53

Merge branch 'master' into dev/timill/DockMenu

a5a6b32

timunie mentioned this pull request Feb 16, 2026

'Quit' option in dock menu on macOS can't be canceled when SetupWithClassicDesktopLifetime() is used #20683

Open

MrJul reviewed Feb 16, 2026

View reviewed changes

src/Avalonia.Controls/NativeDock.cs Show resolved Hide resolved

drasticactions and others added 2 commits February 17, 2026 13:59

Merge branch 'master' into dev/timill/DockMenu

04f583c

Add documentation

3366c08

MrJul approved these changes Feb 17, 2026

View reviewed changes

MrJul enabled auto-merge February 17, 2026 11:07

Merge branch 'master' into dev/timill/DockMenu

7f133dd

MrJul added this pull request to the merge queue Feb 19, 2026

Merged via the queue into master with commit ef70264 Feb 19, 2026
11 checks passed

MrJul deleted the dev/timill/DockMenu branch February 19, 2026 13:16

		private Action _queueReset = null!;
		private Action _updateIfNeeded = null!;

Uh oh!

Comments

Conversation

drasticactions commented Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does the pull request do?

What is the current behavior?

What is the updated/expected behavior with this PR?

How was the solution implemented (if it's not obvious)?

Checklist

Breaking changes

Obsoletions / Deprecations

Fixed issues

Uh oh!

avaloniaui-bot commented Feb 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kekekeks Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avaloniaui-bot commented Feb 8, 2026

Uh oh!

maxkatz6 commented Feb 8, 2026

Uh oh!

drasticactions commented Feb 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avaloniaui-bot commented Feb 8, 2026

Uh oh!

avaloniaui-bot commented Feb 8, 2026

Uh oh!

drasticactions commented Feb 8, 2026

Uh oh!

avaloniaui-bot commented Feb 11, 2026

Uh oh!

avaloniaui-bot commented Feb 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avaloniaui-bot commented Feb 13, 2026

Uh oh!

avaloniaui-bot commented Feb 16, 2026

Uh oh!

Uh oh!

avaloniaui-bot commented Feb 17, 2026

Uh oh!

MrJul left a comment

Choose a reason for hiding this comment

Uh oh!

avaloniaui-bot commented Feb 19, 2026

Uh oh!

Uh oh!

Reviewers

drasticactions commented Feb 7, 2026 •

edited

Loading

kekekeks Feb 7, 2026 •

edited

Loading