Add taskbar progress indicator support (#2695) by mikasoukhov · Pull Request #20621 · AvaloniaUI/Avalonia

mikasoukhov · 2026-02-06T08:31:05Z

Implement cross-platform taskbar/dock progress indicator

namespace Avalonia.Controls
{
    public enum TaskbarProgressState
    {
        None = 0,
        Indeterminate = 1,
        Normal = 2,
        Error = 4,
        Paused = 8,
    }

    public class Window
    {
         public static readonly StyledProperty<TaskbarProgressState> TaskbarProgressStateProperty;
         public static readonly StyledProperty<double> TaskbarProgressValueProperty;

         public TaskbarProgressState TaskbarProgressState { get; set; }
         public double TaskbarProgressValue { get; set; }
    }
}

Implement cross-platform taskbar/dock progress indicator: - Windows: ITaskbarList3 COM (SetProgressValue/SetProgressState) - Linux: Unity Launcher API via DBus (com.canonical.Unity.LauncherEntry) - macOS: NSDockTile with NSProgressIndicator New API on Window class: - TaskbarProgressState property (None/Indeterminate/Normal/Error/Paused) - TaskbarProgressValue property (double, 0.0-1.0) Includes Sandbox demo app for testing.

Copilot

Pull request overview

This pull request implements cross-platform taskbar/dock progress indicator support for Avalonia windows, allowing applications to display progress information in the taskbar (Windows), dock (macOS), or launcher (Linux/Unity).

Changes:

Added TaskbarProgressState enum with states: None, Indeterminate, Normal, Error, and Paused
Added TaskbarProgressState and TaskbarProgressValue properties to the Window class with platform implementation bindings
Implemented platform-specific support for Windows (via ITaskbarList3), macOS (via NSProgressIndicator in dock), and Linux (via Unity LauncherEntry DBus protocol)
Added stub implementations for headless and designer support environments
Included a sample application in Sandbox to demonstrate the feature

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
src/Avalonia.Controls/TaskbarProgressState.cs	New enum defining progress indicator states
src/Avalonia.Controls/Window.cs	Added properties and platform bindings for taskbar progress
src/Avalonia.Controls/Platform/IWindowImpl.cs	Extended interface with SetTaskbarProgressState and SetTaskbarProgressValue methods
src/Windows/Avalonia.Win32/WindowImpl.cs	Windows implementation using ITaskbarList3 COM interface
src/Windows/Avalonia.Win32/Interop/TaskBarList.cs	Windows interop wrapper for taskbar progress methods
src/Windows/Avalonia.Win32/Interop/UnmanagedMethods.cs	P/Invoke delegate definitions for ITaskbarList3
src/Avalonia.Native/WindowImpl.cs	macOS C# wrapper calling native implementation
src/Avalonia.Native/avn.idl	Native interface additions for dock progress
native/Avalonia.Native/src/OSX/WindowImpl.h	macOS native header with static dock progress fields
native/Avalonia.Native/src/OSX/WindowImpl.mm	macOS native implementation using NSProgressIndicator
src/Avalonia.X11/X11Window.cs	Linux/X11 implementation using Unity LauncherEntry via DBus
src/Avalonia.FreeDesktop/DBusUnityLauncher.cs	DBus handler for Unity launcher progress updates
src/Avalonia.FreeDesktop/DBusXml/com.canonical.Unity.LauncherEntry.xml	DBus interface definition
src/Avalonia.FreeDesktop/Avalonia.FreeDesktop.csproj	Project configuration for DBus code generation
src/Headless/Avalonia.Headless/HeadlessWindowImpl.cs	Empty stub implementation for headless testing
src/Avalonia.DesignerSupport/Remote/Stubs.cs	Empty stub implementation for designer
src/Avalonia.DesignerSupport/Remote/PreviewerWindowImpl.cs	Empty stub implementation for previewer
samples/Sandbox/MainWindow.axaml	Sample UI demonstrating progress indicator controls
samples/Sandbox/MainWindow.axaml.cs	Sample code-behind with progress animation demo

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-06T08:41:56Z

src/Avalonia.X11/X11Window.cs

+        private static DBusUnityLauncher? s_unityLauncher;
+        private TaskbarProgressState _taskbarProgressState;


The static DBusUnityLauncher field is accessed from multiple X11Window instances without synchronization. If SetTaskbarProgressState or SetTaskbarProgressValue are called concurrently from different windows (or threads), this could result in a race condition where TryCreate() is called multiple times simultaneously, potentially creating multiple launcher instances or causing issues with DBus connection registration. Consider using lazy initialization with proper thread safety, such as a Lazy<T> or adding a lock around the initialization check.

Copilot · 2026-02-06T08:41:56Z

native/Avalonia.Native/src/OSX/WindowImpl.h

+    static NSProgressIndicator* s_dockProgressIndicator;
+    static NSView* s_dockContentView;


The static dock progress indicator is shared across all WindowImpl instances, which means the progress indicator will be global to the entire application rather than per-window. This is inconsistent with the Windows implementation where each window can have its own taskbar progress indicator. While this might be a limitation of the macOS dock API, it should be documented, and consideration should be given to tracking which window last set the progress to avoid conflicts between multiple windows trying to set different progress values.

Copilot · 2026-02-06T08:41:56Z

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

+static void EnsureDockProgressIndicator() {
+    if (WindowImpl::s_dockProgressIndicator == nullptr) {
+        NSDockTile *dockTile = [[NSApplication sharedApplication] dockTile];
+        NSImageView *iconView = [[NSImageView alloc] init];
+        [iconView setImage:[NSApplication sharedApplication].applicationIconImage];
+
+        NSRect frame = NSMakeRect(0, 0, dockTile.size.width, 15);
+        WindowImpl::s_dockProgressIndicator = [[NSProgressIndicator alloc] initWithFrame:frame];
+        [WindowImpl::s_dockProgressIndicator setStyle:NSProgressIndicatorStyleBar];
+        [WindowImpl::s_dockProgressIndicator setMinValue:0.0];
+        [WindowImpl::s_dockProgressIndicator setMaxValue:1.0];
+        [WindowImpl::s_dockProgressIndicator setDoubleValue:0.0];
+        [WindowImpl::s_dockProgressIndicator setHidden:YES];
+
+        WindowImpl::s_dockContentView = [[NSView alloc] init];
+        [WindowImpl::s_dockContentView addSubview:iconView];
+        [WindowImpl::s_dockContentView addSubview:WindowImpl::s_dockProgressIndicator];
+
+        [iconView setFrame:NSMakeRect(0, 0, dockTile.size.width, dockTile.size.height)];
+
+        [dockTile setContentView:WindowImpl::s_dockContentView];
+    }
+}


The EnsureDockProgressIndicator() function is not thread-safe. If multiple threads call SetDockProgressState or SetDockProgressValue simultaneously, there's a race condition where the initialization check could pass for multiple threads, potentially causing multiple allocations or inconsistent state. Consider using dispatch_once or another synchronization mechanism to ensure thread-safe initialization.

Copilot · 2026-02-06T08:41:57Z

src/Avalonia.Controls/Window.cs

+            AvaloniaProperty.Register<Window, TaskbarProgressState>(nameof(TaskbarProgressState), TaskbarProgressState.None);
+
+        /// <summary>
+        /// Defines the <see cref="TaskbarProgressValue"/> property.


The TaskbarProgressValue property doesn't validate that the input is within the expected range of 0.0 to 1.0. While the documentation states this range, accepting values outside this range could lead to unexpected behavior in platform implementations. Consider adding validation to clamp or throw an exception for out-of-range values, or document that values outside this range have undefined behavior.

Suggested change

/// Defines the <see cref="TaskbarProgressValue"/> property.

/// Defines the <see cref="TaskbarProgressValue"/> property.

/// The value is expected to be in the range from 0.0 to 1.0. Values outside this range

/// have undefined behavior and may lead to unexpected results in platform implementations.

Copilot · 2026-02-06T08:41:57Z

src/Avalonia.Controls/Window.cs

            CreatePlatformImplBinding(CanMaximizeProperty, canMaximize => PlatformImpl!.SetCanMaximize(canMaximize));
            CreatePlatformImplBinding(ShowInTaskbarProperty, show => PlatformImpl!.ShowTaskbarIcon(show));
+            CreatePlatformImplBinding(TaskbarProgressStateProperty, state => PlatformImpl!.SetTaskbarProgressState(state));
+            CreatePlatformImplBinding(TaskbarProgressValueProperty, value => PlatformImpl!.SetTaskbarProgressValue((ulong)(value * 1000), 1000));


The conversion from double (0.0-1.0) to ulong uses a fixed scale factor of 1000. This means the progress value only has 1000 discrete steps. While this is likely sufficient for visual progress indicators, it's an arbitrary precision loss that might not match the underlying platform APIs' capabilities. Consider documenting this precision limitation or using a larger scale factor if the platform APIs support higher precision.

Copilot · 2026-02-06T08:41:57Z

src/Avalonia.Controls/Window.cs

+        public static readonly StyledProperty<TaskbarProgressState> TaskbarProgressStateProperty =
+            AvaloniaProperty.Register<Window, TaskbarProgressState>(nameof(TaskbarProgressState), TaskbarProgressState.None);
+
+        /// <summary>
+        /// Defines the <see cref="TaskbarProgressValue"/> property.
+        /// </summary>
+        public static readonly StyledProperty<double> TaskbarProgressValueProperty =
+            AvaloniaProperty.Register<Window, double>(nameof(TaskbarProgressValue), 0.0);


The new TaskbarProgressState and TaskbarProgressValue properties lack test coverage. Other Window properties like Title have corresponding tests in WindowTests.cs that verify the property values are correctly passed to the platform implementation. Consider adding tests similar to Setting_Title_Should_Set_Impl_Title to verify that these properties correctly invoke SetTaskbarProgressState and SetTaskbarProgressValue on the platform implementation.

Copilot · 2026-02-06T08:41:57Z

src/Avalonia.FreeDesktop/DBusUnityLauncher.cs

+        {
+            EmitUpdate(_desktopUri, new Dictionary<string, VariantValue>
+            {
+                ["progress"] = (double)progress,


The explicit cast to double is redundant since 'progress' is already of type double. This adds unnecessary noise to the code.

Suggested change

["progress"] = (double)progress,

["progress"] = progress,

Copilot · 2026-02-06T08:41:58Z

src/Avalonia.X11/X11Window.cs

+        private static DBusUnityLauncher? s_unityLauncher;
+        private TaskbarProgressState _taskbarProgressState;


The static DBusUnityLauncher instance is shared across all X11Window instances, which means the progress indicator will be global to the entire application rather than per-window. This is inconsistent with the Windows and macOS implementations where each window can have its own progress indicator. Consider making this an instance field instead, or document that this is a known limitation of the Unity launcher protocol.

Copilot · 2026-02-06T08:41:58Z

src/Avalonia.X11/X11Window.cs

+        public void SetTaskbarProgressState(TaskbarProgressState state)
+        {
+            _taskbarProgressState = state;
+            s_unityLauncher ??= DBusUnityLauncher.TryCreate();
+            if (s_unityLauncher is null)
+                return;
+
+            if (state == TaskbarProgressState.None)
+                s_unityLauncher.SetProgress(0, false);
+        }


When TaskbarProgressState is set to any value other than None, this method only updates the state but doesn't update the visibility or progress value. This means if the state changes from None to Normal/Error/Paused, the progress indicator won't become visible until SetTaskbarProgressValue is called. Consider calling SetProgress with the current stored progress value to ensure the indicator becomes visible immediately when the state changes.

Copilot · 2026-02-06T08:41:58Z

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

+static void EnsureDockProgressIndicator() {
+    if (WindowImpl::s_dockProgressIndicator == nullptr) {
+        NSDockTile *dockTile = [[NSApplication sharedApplication] dockTile];
+        NSImageView *iconView = [[NSImageView alloc] init];
+        [iconView setImage:[NSApplication sharedApplication].applicationIconImage];
+
+        NSRect frame = NSMakeRect(0, 0, dockTile.size.width, 15);
+        WindowImpl::s_dockProgressIndicator = [[NSProgressIndicator alloc] initWithFrame:frame];
+        [WindowImpl::s_dockProgressIndicator setStyle:NSProgressIndicatorStyleBar];
+        [WindowImpl::s_dockProgressIndicator setMinValue:0.0];
+        [WindowImpl::s_dockProgressIndicator setMaxValue:1.0];
+        [WindowImpl::s_dockProgressIndicator setDoubleValue:0.0];
+        [WindowImpl::s_dockProgressIndicator setHidden:YES];
+
+        WindowImpl::s_dockContentView = [[NSView alloc] init];
+        [WindowImpl::s_dockContentView addSubview:iconView];
+        [WindowImpl::s_dockContentView addSubview:WindowImpl::s_dockProgressIndicator];
+
+        [iconView setFrame:NSMakeRect(0, 0, dockTile.size.width, dockTile.size.height)];
+
+        [dockTile setContentView:WindowImpl::s_dockContentView];
+    }


The memory allocated for iconView, s_dockProgressIndicator, and s_dockContentView is never released. While these are intended to be long-lived static objects, there's no cleanup mechanism if the application needs to reset or release these resources. In Objective-C with ARC, these objects will be retained as long as the static pointers hold references to them, but consider whether a cleanup method might be needed for cases where the application wants to restore the default dock icon appearance.

Gillibald · 2026-02-06T09:30:00Z

Why are all non-Windows implementations global and not tied to a Window?

cla-avalonia · 2026-02-06T09:30:11Z

@mikasoukhov,

Please read the following Contributor License Agreement (CLA). If you agree with the CLA, please reply with the following:

@cla-avalonia agree

Contributor License Agreement

Contribution License Agreement

This Contribution License Agreement ( “Agreement” ) is agreed to by the party signing below ( “You” ),
and conveys certain license rights to the AvaloniaUI OÜ ( “AvaloniaUI OÜ” ) for Your contributions to
AvaloniaUI OÜ open source projects. This Agreement is effective as of the latest signature date below.

1. Definitions.

“Code” means the computer software code, whether in human-readable or machine-executable form,
that is delivered by You to AvaloniaUI OÜ under this Agreement.

“Project” means any of the projects owned or managed by AvaloniaUI OÜ and offered under a license
approved by the Open Source Initiative (www.opensource.org).

“Submit” is the act of uploading, submitting, transmitting, or distributing code or other content to any
Project, including but not limited to communication on electronic mailing lists, source code control
systems, and issue tracking systems that are managed by, or on behalf of, the Project for the purpose of
discussing and improving that Project, but excluding communication that is conspicuously marked or
otherwise designated in writing by You as “Not a Submission.”

“Submission” means the Code and any other copyrightable material Submitted by You, including any
associated comments and documentation.

2. Your Submission. You must agree to the terms of this Agreement before making a Submission to any
Project. This Agreement covers any and all Submissions that You, now or in the future (except as
described in Section 4 below), Submit to any Project.

3. Originality of Work. You represent that each of Your Submissions is entirely Your
original work. Should You wish to Submit materials that are not Your original work,
You may Submit them separately to the Project if You (a) retain all copyright and
license information that was in the materials as you received them, (b) in the
description accompanying your Submission, include the phrase "Submission
containing materials of a third party:" followed by the names of the third party and any
licenses or other restrictions of which You are aware, and (c) follow any other
instructions in the Project's written guidelines concerning Submissions.

4. Your Employer. References to “employer” in this Agreement include Your employer or anyone else
for whom You are acting in making Your Submission, e.g. as a contractor, vendor, or agent. If Your
Submission is made in the course of Your work for an employer or Your employer has intellectual
property rights in Your Submission by contract or applicable law, You must secure permission from Your
employer to make the Submission before signing this Agreement. In that case, the term “You” in this
Agreement will refer to You and the employer collectively. If You change employers in the future and
desire to Submit additional Submissions for the new employer, then You agree to sign a new Agreement
and secure permission from the new employer before Submitting those Submissions.

5. Licenses.

a. Copyright License. You grant AvaloniaUI OÜ, and those who receive the Submission directly
or indirectly from AvaloniaUI OÜ, a perpetual, worldwide, non-exclusive, royalty-free, irrevocable
license in the Submission to reproduce, prepare derivative works of, publicly display, publicly perform,
and distribute the Submission and such derivative works, and to sublicense any or all of the foregoing
rights to third parties.

b. Patent License. You grant AvaloniaUI OÜ, and those who receive the Submission directly or
indirectly from AvaloniaUI OÜ, a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license
under Your patent claims that are necessarily infringed by the Submission or the combination of the
Submission with the Project to which it was Submitted to make, have made, use, offer to sell, sell and
import or otherwise dispose of the Submission alone or with the Project.

c. Other Rights Reserved. Each party reserves all rights not expressly granted in this Agreement.
No additional licenses or rights whatsoever (including, without limitation, any implied licenses) are
granted by implication, exhaustion, estoppel or otherwise.

6. Representations and Warranties. You represent that You are legally entitled to grant the above
licenses. You represent that each of Your Submissions is entirely Your original work (except as You may
have disclosed under Section 3 ). You represent that You have secured permission from Your employer to
make the Submission in cases where Your Submission is made in the course of Your work for Your
employer or Your employer has intellectual property rights in Your Submission by contract or applicable
law. If You are signing this Agreement on behalf of Your employer, You represent and warrant that You
have the necessary authority to bind the listed employer to the obligations contained in this Agreement.
You are not expected to provide support for Your Submission, unless You choose to do so. UNLESS
REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING, AND EXCEPT FOR THE WARRANTIES
EXPRESSLY STATED IN SECTIONS 3, 4, AND 6 , THE SUBMISSION PROVIDED UNDER THIS AGREEMENT IS
PROVIDED WITHOUT WARRANTY OF ANY KIND, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY OF
NONINFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

7. Notice to AvaloniaUI OÜ. You agree to notify AvaloniaUI OÜ in writing of any facts or
circumstances of which You later become aware that would make Your representations in this
Agreement inaccurate in any respect.

8. Information about Submissions. You agree that contributions to Projects and information about
contributions may be maintained indefinitely and disclosed publicly, including Your name and other
information that You submit with Your Submission.

9. Governing Law/Jurisdiction. This Agreement is governed by the laws of the Republic of Estonia, and
the parties consent to exclusive jurisdiction and venue in the courts sitting in Talinn,
Estonia. The parties waive all defenses of lack of personal jurisdiction and forum non-conveniens.

10. Entire Agreement/Assignment. This Agreement is the entire agreement between the parties, and
supersedes any and all prior agreements, understandings or communications, written or oral, between
the parties relating to the subject matter hereof. This Agreement may be assigned by AvaloniaUI OÜ.

AvaloniaUI OÜ dedicates this Contribution License Agreement to the public domain according to the Creative Commons CC0 1.

- Move dock progress statics to file-scope in WindowImpl.mm to fix private access error in free function - Use dispatch_once for thread-safe initialization (macOS) - Use Lazy<T> for thread-safe DBus launcher initialization (Linux) - Add API compatibility suppression entries for new IWindowImpl methods - Clamp TaskbarProgressValue to 0.0-1.0 range - Show progress bar immediately when state changes to non-None (Linux)

mikasoukhov · 2026-02-06T13:43:25Z

Why are all non-Windows implementations global and not tied to a Window?

The TaskBarList COM object on Windows is also static/global - it's a single COM instance per process (private static IntPtr s_taskBarList). The difference is that the Windows ITaskbarList3 API accepts an HWND parameter to target a specific window, while macOS (NSDockTile) and Linux (Unity Launcher DBus API) don't have a per-window identifier. They operate at the application level. So the static approach is consistent across all platforms; Windows just happens to support per-window dispatch through the HWND parameter.

… methods

mikasoukhov · 2026-02-06T22:16:05Z

@cla-avalonia agree

@cla-avalonia agree

kekekeks · 2026-02-11T08:48:24Z

src/Avalonia.FreeDesktop/DBusUnityLauncher.cs

+                if (connection is null)
+                    return null;
+
+                var appId = Assembly.GetEntryAssembly()?.GetName().Name


There is zero guarantee that assembly name / process name would match a desktop file.

I. e. it's not uncommon to auto-create a .desktop entry in ~/.local/share/applications named like org.telegram.desktop._d9f9f629990a1d1bb0bb3ac9e74581d0.desktop

MrJul · 2026-02-11T09:56:37Z

Notes from the API review meeting:

We decided to create a class solely to store dock-related properties for this PR and future work.
After much debate, the team settled on NativeDock.

The property used for the progress will be NativeDock.ProgressState and NativeDock.ProgressValue.
Documentation will be added so that users looking for "taskbar" are able to find the NativeDock class.

Please wait for #20634 to be merged first.

Detect desktop file name from GIO_LAUNCHED_DESKTOP_FILE or BAMF_DESKTOP_FILE_HINT environment variables set by desktop environments, with fallback to assembly name and a warning log.

Copilot AI review requested due to automatic review settings February 6, 2026 08:31

Copilot started reviewing on behalf of mikasoukhov February 6, 2026 08:31 View session

MrJul added feature needs-api-review The PR adds new public APIs that should be reviewed. labels Feb 6, 2026

Copilot AI reviewed Feb 6, 2026

View reviewed changes

mikasoukhov and others added 3 commits February 6, 2026 15:14

Merge branch 'master' into feature/taskbar-progress

0ede26a

Fix API compat suppression signatures to match nullable annotations

c616dd3

Restore suppression file from master, add entries for new IWindowImpl…

6aa2637

… methods

kekekeks reviewed Feb 11, 2026

View reviewed changes

MrJul added api-change-requested The new public APIs need some changes. and removed needs-api-review The PR adds new public APIs that should be reviewed. labels Feb 11, 2026

Use environment variables for .desktop file detection on Linux

252c578

Detect desktop file name from GIO_LAUNCHED_DESKTOP_FILE or BAMF_DESKTOP_FILE_HINT environment variables set by desktop environments, with fallback to assembly name and a warning log.

		private static DBusUnityLauncher? s_unityLauncher;
		private TaskbarProgressState _taskbarProgressState;

		static NSProgressIndicator* s_dockProgressIndicator;
		static NSView* s_dockContentView;

Uh oh!

Comments

Conversation

mikasoukhov commented Feb 6, 2026 • edited by maxkatz6 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Gillibald commented Feb 6, 2026

Uh oh!

cla-avalonia commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Contribution License Agreement

Uh oh!

mikasoukhov commented Feb 6, 2026

Uh oh!

mikasoukhov commented Feb 6, 2026

Uh oh!

kekekeks Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

kekekeks Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

mikasoukhov Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

MrJul commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mikasoukhov commented Feb 6, 2026 •

edited by maxkatz6

Loading

cla-avalonia commented Feb 6, 2026 •

edited

Loading