From db2b01bc01885283757c967dffc75f770b7ea41e Mon Sep 17 00:00:00 2001
From: Julien Lebosquain <julien@lebosquain.net>
Date: Mon, 27 Apr 2026 12:32:52 +0200
Subject: [PATCH] Clarify that ElementRole is dependent on
 ExtendClientAreaToDecorationsHint (#21243)

---
 src/Avalonia.Controls/Chrome/WindowDecorationProperties.cs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/Avalonia.Controls/Chrome/WindowDecorationProperties.cs b/src/Avalonia.Controls/Chrome/WindowDecorationProperties.cs
index 5ad874eec4..0881dda57f 100644
--- a/src/Avalonia.Controls/Chrome/WindowDecorationProperties.cs
+++ b/src/Avalonia.Controls/Chrome/WindowDecorationProperties.cs
@@ -12,6 +12,7 @@ public static class WindowDecorationProperties
     /// Marks a visual element with a specific role for non-client hit-testing.
     /// Can be applied to any element in the visual tree, not limited to decoration children.
     /// </summary>
+    /// <remarks>Setting an element role only has an effect if <see cref="Window.ExtendClientAreaToDecorationsHint"/> is true.</remarks>
     public static readonly AttachedProperty<WindowDecorationsElementRole> ElementRoleProperty =
         AvaloniaProperty.RegisterAttached<Visual, WindowDecorationsElementRole>("ElementRole", typeof(WindowDecorationProperties));
 
@@ -23,5 +24,6 @@ public static class WindowDecorationProperties
     /// <summary>
     /// Sets the <see cref="WindowDecorationsElementRole"/> for the specified element.
     /// </summary>
+    /// <remarks>Setting an element role only has an effect if <see cref="Window.ExtendClientAreaToDecorationsHint"/> is true.</remarks>
     public static void SetElementRole(Visual element, WindowDecorationsElementRole value) => element.SetValue(ElementRoleProperty, value);
 }