Experimental interface IBehavior

stephenquan · stephenquan · commit 7a3ed80da22c · 2025-11-03T20:11:23.000+11:00
diff --git a/src/Controls/src/Core/Interactivity/Behavior.cs b/src/Controls/src/Core/Interactivity/Behavior.cs
@@ -7,7 +7,7 @@ namespace Microsoft.Maui.Controls
 	/// Base class for generalized user-defined behaviors that can respond to arbitrary conditions and events.
 	/// </summary>
 	/// <remarks>Application developers should specialize the <see cref="Behavior{T}" /> generic class, instead of directly using <see cref="Behavior" />.</remarks>
-	public abstract class Behavior : BindableObject, IAttachedObject
+	public abstract class Behavior : BindableObject, IBehavior
 	{
 		/// <summary>
 		/// Creates a new <see cref="Behavior" /> with default values.
@@ -54,7 +54,7 @@ protected virtual void OnDetachingFrom(BindableObject bindable)
 
 	/// <inheritdoc/>
 	/// <typeparam name="T">The type of object this behavior will be applied to.</typeparam>
-	public abstract class Behavior<T> : Behavior where T : BindableObject
+	public abstract class Behavior<T> : Behavior, IBehavior<T> where T : BindableObject
 	{
 		/// <inheritdoc/>
 		protected Behavior() : base(typeof(T))
diff --git a/src/Controls/src/Core/Interactivity/IAttachedObject.cs b/src/Controls/src/Core/Interactivity/IAttachedObject.cs
@@ -1,9 +1,27 @@
 #nullable disable
 namespace Microsoft.Maui.Controls
 {
-	internal interface IAttachedObject
+
+	/// <summary>
+	/// Defines a contract for objects that can be attached to a <see cref="BindableObject"/>.
+	/// This interface is typically implemented by behaviors or effects that need to interact with
+	/// the lifecycle or properties of a visual element in the UI.
+	/// </summary>
+	public interface IAttachedObject
 	{
+
+		/// <summary>
+		/// Attaches the object to the specified <see cref="BindableObject"/>.
+		/// This method is called when the object is added to the visual tree.
+		/// </summary>
+		/// <param name="bindable">The <see cref="BindableObject"/> to attach to.</param>
 		void AttachTo(BindableObject bindable);
+
+		/// <summary>
+		/// Detaches the object from the specified <see cref="BindableObject"/>.
+		/// This method is called when the object is removed from the visual tree.
+		/// </summary>
+		/// <param name="bindable">The <see cref="BindableObject"/> to detach from.</param>
 		void DetachFrom(BindableObject bindable);
 	}
 }
diff --git a/src/Controls/src/Core/Interactivity/IBehavior.cs b/src/Controls/src/Core/Interactivity/IBehavior.cs
@@ -0,0 +1,22 @@
+﻿#nullable disable
+using System.ComponentModel;
+
+namespace Microsoft.Maui.Controls
+{
+
+	/// <summary>
+	/// Represents a behavior that can be attached to a <see cref="BindableObject"/>.
+	/// </summary>
+	public interface IBehavior : INotifyPropertyChanged, IAttachedObject
+	{
+	}
+
+	/// <summary>
+	/// Represents a behavior that can be attached to a specific type of <see cref="BindableObject"/>.
+	/// This generic interface allows behaviors to be strongly typed to the target element.
+	/// </summary>
+	/// <typeparam name="T">The type of <see cref="BindableObject"/> the behavior can attach to.</typeparam>
+	public interface IBehavior<T> : IBehavior where T : BindableObject
+	{
+	}
+}
diff --git a/src/Controls/src/Core/PublicAPI/net-android/PublicAPI.Shipped.txt b/src/Controls/src/Core/PublicAPI/net-android/PublicAPI.Shipped.txt
@@ -632,6 +632,9 @@
 ~Microsoft.Maui.Controls.IAppLinks.DeregisterLink(Microsoft.Maui.Controls.IAppLinkEntry appLink) -> void
 ~Microsoft.Maui.Controls.IAppLinks.DeregisterLink(System.Uri appLinkUri) -> void
 ~Microsoft.Maui.Controls.IAppLinks.RegisterLink(Microsoft.Maui.Controls.IAppLinkEntry appLink) -> void
+~Microsoft.Maui.Controls.IAttachedObject.AttachTo(Microsoft.Maui.Controls.BindableObject bindable) -> void
+~Microsoft.Maui.Controls.IAttachedObject.DetachFrom(Microsoft.Maui.Controls.BindableObject bindable) -> void
+~Microsoft.Maui.Controls.IBehavior<T>
 ~Microsoft.Maui.Controls.IBindableLayout.Children.get -> System.Collections.IList
 ~Microsoft.Maui.Controls.IBorderElement.Background.get -> Microsoft.Maui.Controls.Brush
 ~Microsoft.Maui.Controls.IBorderElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
@@ -1816,7 +1819,7 @@
 ~Microsoft.Maui.Controls.VisualElement.Background.set -> void
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.set -> void
-~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.Behavior>
+~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.IBehavior>
 ~Microsoft.Maui.Controls.VisualElement.Clip.get -> Microsoft.Maui.Controls.Shapes.Geometry
 ~Microsoft.Maui.Controls.VisualElement.Clip.set -> void
 ~Microsoft.Maui.Controls.VisualElement.Resources.get -> Microsoft.Maui.Controls.ResourceDictionary
@@ -5239,6 +5242,8 @@ Microsoft.Maui.Controls.IAppLinkEntry
 Microsoft.Maui.Controls.IAppLinkEntry.IsLinkActive.get -> bool
 Microsoft.Maui.Controls.IAppLinkEntry.IsLinkActive.set -> void
 Microsoft.Maui.Controls.IAppLinks
+Microsoft.Maui.Controls.IAttachedObject
+Microsoft.Maui.Controls.IBehavior
 Microsoft.Maui.Controls.IBindableLayout
 Microsoft.Maui.Controls.IBorderElement
 Microsoft.Maui.Controls.IBorderElement.BorderWidth.get -> double
diff --git a/src/Controls/src/Core/PublicAPI/net-ios/PublicAPI.Shipped.txt b/src/Controls/src/Core/PublicAPI/net-ios/PublicAPI.Shipped.txt
@@ -665,6 +665,9 @@
 ~Microsoft.Maui.Controls.IAppLinks.DeregisterLink(Microsoft.Maui.Controls.IAppLinkEntry appLink) -> void
 ~Microsoft.Maui.Controls.IAppLinks.DeregisterLink(System.Uri appLinkUri) -> void
 ~Microsoft.Maui.Controls.IAppLinks.RegisterLink(Microsoft.Maui.Controls.IAppLinkEntry appLink) -> void
+~Microsoft.Maui.Controls.IAttachedObject.AttachTo(Microsoft.Maui.Controls.BindableObject bindable) -> void
+~Microsoft.Maui.Controls.IAttachedObject.DetachFrom(Microsoft.Maui.Controls.BindableObject bindable) -> void
+~Microsoft.Maui.Controls.IBehavior<T>
 ~Microsoft.Maui.Controls.IBindableLayout.Children.get -> System.Collections.IList
 ~Microsoft.Maui.Controls.IBorderElement.Background.get -> Microsoft.Maui.Controls.Brush
 ~Microsoft.Maui.Controls.IBorderElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
@@ -1824,7 +1827,7 @@
 ~Microsoft.Maui.Controls.VisualElement.Background.set -> void
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.set -> void
-~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.Behavior>
+~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.IBehavior>
 ~Microsoft.Maui.Controls.VisualElement.Clip.get -> Microsoft.Maui.Controls.Shapes.Geometry
 ~Microsoft.Maui.Controls.VisualElement.Clip.set -> void
 ~Microsoft.Maui.Controls.VisualElement.Resources.get -> Microsoft.Maui.Controls.ResourceDictionary
@@ -5435,6 +5438,8 @@ Microsoft.Maui.Controls.IAppLinkEntry
 Microsoft.Maui.Controls.IAppLinkEntry.IsLinkActive.get -> bool
 Microsoft.Maui.Controls.IAppLinkEntry.IsLinkActive.set -> void
 Microsoft.Maui.Controls.IAppLinks
+Microsoft.Maui.Controls.IAttachedObject
+Microsoft.Maui.Controls.IBehavior
 Microsoft.Maui.Controls.IBindableLayout
 Microsoft.Maui.Controls.IBorderElement
 Microsoft.Maui.Controls.IBorderElement.BorderWidth.get -> double
diff --git a/src/Controls/src/Core/PublicAPI/net-maccatalyst/PublicAPI.Shipped.txt b/src/Controls/src/Core/PublicAPI/net-maccatalyst/PublicAPI.Shipped.txt
@@ -665,6 +665,9 @@
 ~Microsoft.Maui.Controls.IAppLinks.DeregisterLink(Microsoft.Maui.Controls.IAppLinkEntry appLink) -> void
 ~Microsoft.Maui.Controls.IAppLinks.DeregisterLink(System.Uri appLinkUri) -> void
 ~Microsoft.Maui.Controls.IAppLinks.RegisterLink(Microsoft.Maui.Controls.IAppLinkEntry appLink) -> void
+~Microsoft.Maui.Controls.IAttachedObject.AttachTo(Microsoft.Maui.Controls.BindableObject bindable) -> void
+~Microsoft.Maui.Controls.IAttachedObject.DetachFrom(Microsoft.Maui.Controls.BindableObject bindable) -> void
+~Microsoft.Maui.Controls.IBehavior<T>
 ~Microsoft.Maui.Controls.IBindableLayout.Children.get -> System.Collections.IList
 ~Microsoft.Maui.Controls.IBorderElement.Background.get -> Microsoft.Maui.Controls.Brush
 ~Microsoft.Maui.Controls.IBorderElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
@@ -1824,7 +1827,7 @@
 ~Microsoft.Maui.Controls.VisualElement.Background.set -> void
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.set -> void
-~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.Behavior>
+~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.IBehavior>
 ~Microsoft.Maui.Controls.VisualElement.Clip.get -> Microsoft.Maui.Controls.Shapes.Geometry
 ~Microsoft.Maui.Controls.VisualElement.Clip.set -> void
 ~Microsoft.Maui.Controls.VisualElement.Resources.get -> Microsoft.Maui.Controls.ResourceDictionary
@@ -5435,6 +5438,8 @@ Microsoft.Maui.Controls.IAppLinkEntry
 Microsoft.Maui.Controls.IAppLinkEntry.IsLinkActive.get -> bool
 Microsoft.Maui.Controls.IAppLinkEntry.IsLinkActive.set -> void
 Microsoft.Maui.Controls.IAppLinks
+Microsoft.Maui.Controls.IAttachedObject
+Microsoft.Maui.Controls.IBehavior
 Microsoft.Maui.Controls.IBindableLayout
 Microsoft.Maui.Controls.IBorderElement
 Microsoft.Maui.Controls.IBorderElement.BorderWidth.get -> double
diff --git a/src/Controls/src/Core/PublicAPI/net-tizen/PublicAPI.Shipped.txt b/src/Controls/src/Core/PublicAPI/net-tizen/PublicAPI.Shipped.txt
@@ -1594,7 +1594,7 @@
 ~Microsoft.Maui.Controls.VisualElement.Background.set -> void
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.set -> void
-~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.Behavior>
+~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.IBehavior>
 ~Microsoft.Maui.Controls.VisualElement.Clip.get -> Microsoft.Maui.Controls.Shapes.Geometry
 ~Microsoft.Maui.Controls.VisualElement.Clip.set -> void
 ~Microsoft.Maui.Controls.VisualElement.Resources.get -> Microsoft.Maui.Controls.ResourceDictionary
diff --git a/src/Controls/src/Core/PublicAPI/net-windows/PublicAPI.Shipped.txt b/src/Controls/src/Core/PublicAPI/net-windows/PublicAPI.Shipped.txt
@@ -535,6 +535,9 @@
 ~Microsoft.Maui.Controls.IAppLinks.DeregisterLink(Microsoft.Maui.Controls.IAppLinkEntry appLink) -> void
 ~Microsoft.Maui.Controls.IAppLinks.DeregisterLink(System.Uri appLinkUri) -> void
 ~Microsoft.Maui.Controls.IAppLinks.RegisterLink(Microsoft.Maui.Controls.IAppLinkEntry appLink) -> void
+~Microsoft.Maui.Controls.IAttachedObject.AttachTo(Microsoft.Maui.Controls.BindableObject bindable) -> void
+~Microsoft.Maui.Controls.IAttachedObject.DetachFrom(Microsoft.Maui.Controls.BindableObject bindable) -> void
+~Microsoft.Maui.Controls.IBehavior<T>
 ~Microsoft.Maui.Controls.IBindableLayout.Children.get -> System.Collections.IList
 ~Microsoft.Maui.Controls.IBorderElement.Background.get -> Microsoft.Maui.Controls.Brush
 ~Microsoft.Maui.Controls.IBorderElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
@@ -1664,7 +1667,7 @@
 ~Microsoft.Maui.Controls.VisualElement.Background.set -> void
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.set -> void
-~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.Behavior>
+~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.IBehavior>
 ~Microsoft.Maui.Controls.VisualElement.Clip.get -> Microsoft.Maui.Controls.Shapes.Geometry
 ~Microsoft.Maui.Controls.VisualElement.Clip.set -> void
 ~Microsoft.Maui.Controls.VisualElement.Resources.get -> Microsoft.Maui.Controls.ResourceDictionary
@@ -4904,6 +4907,8 @@ Microsoft.Maui.Controls.IAppLinkEntry
 Microsoft.Maui.Controls.IAppLinkEntry.IsLinkActive.get -> bool
 Microsoft.Maui.Controls.IAppLinkEntry.IsLinkActive.set -> void
 Microsoft.Maui.Controls.IAppLinks
+Microsoft.Maui.Controls.IAttachedObject
+Microsoft.Maui.Controls.IBehavior
 Microsoft.Maui.Controls.IBindableLayout
 Microsoft.Maui.Controls.IBorderElement
 Microsoft.Maui.Controls.IBorderElement.BorderWidth.get -> double
diff --git a/src/Controls/src/Core/PublicAPI/net/PublicAPI.Shipped.txt b/src/Controls/src/Core/PublicAPI/net/PublicAPI.Shipped.txt
@@ -517,6 +517,9 @@
 ~Microsoft.Maui.Controls.IAppLinks.DeregisterLink(Microsoft.Maui.Controls.IAppLinkEntry appLink) -> void
 ~Microsoft.Maui.Controls.IAppLinks.DeregisterLink(System.Uri appLinkUri) -> void
 ~Microsoft.Maui.Controls.IAppLinks.RegisterLink(Microsoft.Maui.Controls.IAppLinkEntry appLink) -> void
+~Microsoft.Maui.Controls.IAttachedObject.AttachTo(Microsoft.Maui.Controls.BindableObject bindable) -> void
+~Microsoft.Maui.Controls.IAttachedObject.DetachFrom(Microsoft.Maui.Controls.BindableObject bindable) -> void
+~Microsoft.Maui.Controls.IBehavior<T>
 ~Microsoft.Maui.Controls.IBindableLayout.Children.get -> System.Collections.IList
 ~Microsoft.Maui.Controls.IBorderElement.Background.get -> Microsoft.Maui.Controls.Brush
 ~Microsoft.Maui.Controls.IBorderElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
@@ -1590,7 +1593,7 @@
 ~Microsoft.Maui.Controls.VisualElement.Background.set -> void
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.set -> void
-~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.Behavior>
+~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.IBehavior>
 ~Microsoft.Maui.Controls.VisualElement.Clip.get -> Microsoft.Maui.Controls.Shapes.Geometry
 ~Microsoft.Maui.Controls.VisualElement.Clip.set -> void
 ~Microsoft.Maui.Controls.VisualElement.Resources.get -> Microsoft.Maui.Controls.ResourceDictionary
@@ -4660,6 +4663,8 @@ Microsoft.Maui.Controls.IAppLinkEntry
 Microsoft.Maui.Controls.IAppLinkEntry.IsLinkActive.get -> bool
 Microsoft.Maui.Controls.IAppLinkEntry.IsLinkActive.set -> void
 Microsoft.Maui.Controls.IAppLinks
+Microsoft.Maui.Controls.IAttachedObject
+Microsoft.Maui.Controls.IBehavior
 Microsoft.Maui.Controls.IBindableLayout
 Microsoft.Maui.Controls.IBorderElement
 Microsoft.Maui.Controls.IBorderElement.BorderWidth.get -> double
diff --git a/src/Controls/src/Core/PublicAPI/netstandard/PublicAPI.Shipped.txt b/src/Controls/src/Core/PublicAPI/netstandard/PublicAPI.Shipped.txt
@@ -517,6 +517,9 @@
 ~Microsoft.Maui.Controls.IAppLinks.DeregisterLink(Microsoft.Maui.Controls.IAppLinkEntry appLink) -> void
 ~Microsoft.Maui.Controls.IAppLinks.DeregisterLink(System.Uri appLinkUri) -> void
 ~Microsoft.Maui.Controls.IAppLinks.RegisterLink(Microsoft.Maui.Controls.IAppLinkEntry appLink) -> void
+~Microsoft.Maui.Controls.IAttachedObject.AttachTo(Microsoft.Maui.Controls.BindableObject bindable) -> void
+~Microsoft.Maui.Controls.IAttachedObject.DetachFrom(Microsoft.Maui.Controls.BindableObject bindable) -> void
+~Microsoft.Maui.Controls.IBehavior<T>
 ~Microsoft.Maui.Controls.IBindableLayout.Children.get -> System.Collections.IList
 ~Microsoft.Maui.Controls.IBorderElement.Background.get -> Microsoft.Maui.Controls.Brush
 ~Microsoft.Maui.Controls.IBorderElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
@@ -1590,7 +1593,7 @@
 ~Microsoft.Maui.Controls.VisualElement.Background.set -> void
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.get -> Microsoft.Maui.Graphics.Color
 ~Microsoft.Maui.Controls.VisualElement.BackgroundColor.set -> void
-~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.Behavior>
+~Microsoft.Maui.Controls.VisualElement.Behaviors.get -> System.Collections.Generic.IList<Microsoft.Maui.Controls.IBehavior>
 ~Microsoft.Maui.Controls.VisualElement.Clip.get -> Microsoft.Maui.Controls.Shapes.Geometry
 ~Microsoft.Maui.Controls.VisualElement.Clip.set -> void
 ~Microsoft.Maui.Controls.VisualElement.Resources.get -> Microsoft.Maui.Controls.ResourceDictionary
@@ -4660,6 +4663,8 @@ Microsoft.Maui.Controls.IAppLinkEntry
 Microsoft.Maui.Controls.IAppLinkEntry.IsLinkActive.get -> bool
 Microsoft.Maui.Controls.IAppLinkEntry.IsLinkActive.set -> void
 Microsoft.Maui.Controls.IAppLinks
+Microsoft.Maui.Controls.IAttachedObject
+Microsoft.Maui.Controls.IBehavior
 Microsoft.Maui.Controls.IBindableLayout
 Microsoft.Maui.Controls.IBorderElement
 Microsoft.Maui.Controls.IBorderElement.BorderWidth.get -> double
diff --git a/src/Controls/src/Core/VisualElement/VisualElement.cs b/src/Controls/src/Core/VisualElement/VisualElement.cs
@@ -389,7 +389,7 @@ public override void Unsubscribe()
 			}
 		}
 
-		internal static readonly BindablePropertyKey BehaviorsPropertyKey = BindableProperty.CreateReadOnly(nameof(Behaviors), typeof(IList<Behavior>), typeof(VisualElement), default(IList<Behavior>),
+		internal static readonly BindablePropertyKey BehaviorsPropertyKey = BindableProperty.CreateReadOnly(nameof(Behaviors), typeof(IList<IBehavior>), typeof(VisualElement), default(IList<IBehavior>),
 			defaultValueCreator: bindable =>
 			{
 				var collection = new AttachedCollection<Behavior>();
@@ -567,11 +567,11 @@ public Brush Background
 		}
 
 		/// <summary>
-		/// Gets the list of <see cref="Behavior"/> objects associated to this element. This is a read-only bindable property.
+		/// Gets the list of <see cref="IBehavior"/> objects associated to this element. This is a read-only bindable property.
 		/// </summary>
-		public IList<Behavior> Behaviors
+		public IList<IBehavior> Behaviors
 		{
-			get { return (IList<Behavior>)GetValue(BehaviorsProperty); }
+			get { return (IList<IBehavior>)GetValue(BehaviorsProperty); }
 		}
 
 		/// <summary>
