From a4826b2036380299347bf7c42b56690ceb9ae997 Mon Sep 17 00:00:00 2001
From: Dong Bin <14807942+rabbitism@users.noreply.github.com>
Date: Thu, 23 Jul 2026 18:39:32 +0800
Subject: [PATCH] Add ToolTip.ShouldUseOverlayLayer attached property (#21830)

* feat: add ToolTip.ShouldUseOverlayLayer attached property

Add ShouldUseOverlayLayer attached property to ToolTip, which is bound
to Popup.ShouldUseOverlayLayer when the tooltip popup is created. This
allows per-control control over whether the tooltip popup uses the
overlay layer.

* docs: add proper XML docs for GetShouldUseOverlayLayer/SetShouldUseOverlayLayer

Replace <inheritdoc/> pointing to Popup.ShouldUseOverlayLayer (a property)
with proper <summary>, <param>, and <remarks> documentation for the
getter and setter methods.
---
 src/Avalonia.Controls/ToolTip.cs | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/src/Avalonia.Controls/ToolTip.cs b/src/Avalonia.Controls/ToolTip.cs
index 433098e3f5..7eeea5f0d4 100644
--- a/src/Avalonia.Controls/ToolTip.cs
+++ b/src/Avalonia.Controls/ToolTip.cs
@@ -81,6 +81,10 @@ namespace Avalonia.Controls
         public static readonly AttachedProperty<bool> ServiceEnabledProperty =
             AvaloniaProperty.RegisterAttached<ToolTip, Control, bool>("ServiceEnabled", defaultValue: true, inherits: true);
 
+        /// <inheritdoc cref="Popup.ShouldUseOverlayLayer"/>
+        public static readonly AttachedProperty<bool> ShouldUseOverlayLayerProperty =
+            AvaloniaProperty.RegisterAttached<ToolTip, Control, bool>("ShouldUseOverlayLayer");
+
         /// <summary>
         /// Stores the current <see cref="ToolTip"/> instance in the control.
         /// </summary>
@@ -301,6 +305,27 @@ namespace Avalonia.Controls
         public static void SetServiceEnabled(Control element, bool value) => 
             element.SetValue(ServiceEnabledProperty, value);
 
+        /// <summary>
+        /// Gets whether the tooltip popup for <paramref name="element"/> is shown in the overlay layer.
+        /// </summary>
+        /// <param name="element">The control to get the property from.</param>
+        /// <remarks>
+        /// See <see cref="Popup.ShouldUseOverlayLayer"/> for details.
+        /// </remarks>
+        public static bool GetShouldUseOverlayLayer(Control element) =>
+            element.GetValue(ShouldUseOverlayLayerProperty);
+
+        /// <summary>
+        /// Sets whether the tooltip popup for <paramref name="element"/> is shown in the overlay layer.
+        /// </summary>
+        /// <param name="element">The control to set the property on.</param>
+        /// <param name="value">Whether to show the tooltip popup in the overlay layer.</param>
+        /// <remarks>
+        /// See <see cref="Popup.ShouldUseOverlayLayer"/> for details.
+        /// </remarks>
+        public static void SetShouldUseOverlayLayer(Control element, bool value) =>
+            element.SetValue(ShouldUseOverlayLayerProperty, value);
+
         /// <summary>
         /// Adds a handler for the <see cref="ToolTipOpeningEvent"/> attached event.
         /// </summary>
@@ -421,7 +446,8 @@ namespace Avalonia.Controls
                 _popup.Bind(Popup.HorizontalOffsetProperty, control.GetBindingObservable(HorizontalOffsetProperty)),
                 _popup.Bind(Popup.VerticalOffsetProperty, control.GetBindingObservable(VerticalOffsetProperty)),
                 _popup.Bind(Popup.PlacementProperty, control.GetBindingObservable(PlacementProperty)),
-                _popup.Bind(Popup.CustomPopupPlacementCallbackProperty, control.GetBindingObservable(CustomPopupPlacementCallbackProperty))
+                _popup.Bind(Popup.CustomPopupPlacementCallbackProperty, control.GetBindingObservable(CustomPopupPlacementCallbackProperty)),
+                _popup.Bind(Popup.ShouldUseOverlayLayerProperty, control.GetBindingObservable(ShouldUseOverlayLayerProperty))
             });
 
             _popup.PlacementTarget = control;