Initial switch over to inversion of paradigm for Header behaviors to enable more scenarios

michael-hawker · michael-hawker · commit 406521623436 · 2023-07-17T11:58:15.000-07:00
diff --git a/components/Behaviors/samples/Headers/FadeHeaderBehaviorSample.xaml b/components/Behaviors/samples/Headers/FadeHeaderBehaviorSample.xaml
@@ -10,12 +10,12 @@
 
     <!--  We need to set height here to force scrolling in the sample  -->
     <ListView Height="300">
-        <interactivity:Interaction.Behaviors>
-            <behaviors:FadeHeaderBehavior />
-        </interactivity:Interaction.Behaviors>
         <ListView.Header>
             <Grid MinHeight="100"
                   Background="#FF0078D7">
+                <interactivity:Interaction.Behaviors>
+                    <behaviors:FadeHeaderBehavior />
+                </interactivity:Interaction.Behaviors>
                 <TextBlock HorizontalAlignment="Center"
                            VerticalAlignment="Center"
                            Text="Sample Text" />
diff --git a/components/Behaviors/samples/Headers/HeaderBehaviors.md b/components/Behaviors/samples/Headers/HeaderBehaviors.md
@@ -1,7 +1,7 @@
 ---
 title: Header Behaviors
 author: michael-hawker
-description: Behaviors modifying the headers of ListView based components when scrolling.
+description: Behaviors for modifying an element's movement/response when scrolling within a ScrollViewer.
 keywords: Behaviors
 dev_langs:
   - csharp
@@ -12,22 +12,30 @@ issue-id: 0
 icon: Assets/Behaviors.png
 ---
 
-The `FadeHeaderBehavior`, `QuickReturnHeaderBehavior`, and `StickyHeaderBehavior` apply behaviors to `ListView`, `GridView`, and `HeaderedTreeView` Headers.
+The `FadeHeaderBehavior`, `QuickReturnHeaderBehavior`, and `StickyHeaderBehavior` most commonly apply behaviors to `ListView`, `GridView`, and `HeaderedTreeView` elements in their `Header`. It can also be applied to any element contained at the top of a `ScrollViewer`.
+
+They use composition animations to allow the visual of an element of a scrolling viewport to be manipulated for various effects.
+
+To use the behavior, place it on the _element in the header to be manipulated_.
+
+> [!NOTE]
+> This is different in 8.x than it was in 7.x where the behavior was placed on the parent containing element (e.g. `ListView`).
+> This change was made to enable more scenarios for these components.
 
 ## FadeHeaderBehavior
 
-The FadeHeaderBehavior causes the Header of the scrolling collection to fade in and out as the user scrolls at the top of the collection.
+The FadeHeaderBehavior causes the element in the scrolling collection to fade in and out as the user scrolls at the top of the collection.
 
 > [!Sample FadeHeaderBehaviorSample]
 
 ## QuickReturnBehavior
 
-The QuickReturnHeaderBehavior causes the Header of the scrolling collection to return back into view as soon as the user scrolls up even if they are not near the top of the collection.
+The QuickReturnHeaderBehavior causes the element in the scrolling collection to return back into view as soon as the user scrolls up even if they are not near the top of the collection.
 
 > [!Sample QuickReturnHeaderBehaviorSample]
 
 ## StickyHeaderBehavior
 
-The StickyHeaderBehavior causes the Header of the scrolling collection to stay in view as the user scrolls up and down in the collection.
+The StickyHeaderBehavior causes the element in the scrolling collection to stay in view as the user scrolls up and down in the collection.
 
 > [!Sample StickyHeaderBehaviorSample]
diff --git a/components/Behaviors/samples/Headers/QuickReturnHeaderBehaviorSample.xaml b/components/Behaviors/samples/Headers/QuickReturnHeaderBehaviorSample.xaml
@@ -10,12 +10,12 @@
 
     <!--  We need to set height here to force scrolling in the sample  -->
     <GridView Height="300">
-        <interactivity:Interaction.Behaviors>
-            <behaviors:QuickReturnHeaderBehavior />
-        </interactivity:Interaction.Behaviors>
         <GridView.Header>
             <Grid MinHeight="100"
                   Background="#FF0078D7">
+                <interactivity:Interaction.Behaviors>
+                    <behaviors:QuickReturnHeaderBehavior />
+                </interactivity:Interaction.Behaviors>
                 <TextBlock HorizontalAlignment="Center"
                            VerticalAlignment="Center"
                            Text="Sample Text" />
diff --git a/components/Behaviors/samples/Headers/StickyHeaderBehaviorSample.xaml b/components/Behaviors/samples/Headers/StickyHeaderBehaviorSample.xaml
@@ -14,12 +14,12 @@
     <!--  We need to set height here to force scrolling in the sample  -->
     <controls:HeaderedTreeView Height="300"
                                ItemsSource="{x:Bind Items, Mode=OneWay}">
-        <interactivity:Interaction.Behaviors>
-            <behaviors:StickyHeaderBehavior />
-        </interactivity:Interaction.Behaviors>
         <controls:HeaderedTreeView.Header>
             <Grid MinHeight="100"
                   Background="#FF0078D7">
+                <interactivity:Interaction.Behaviors>
+                    <behaviors:StickyHeaderBehavior />
+                </interactivity:Interaction.Behaviors>
                 <TextBlock HorizontalAlignment="Center"
                            VerticalAlignment="Center"
                            Text="Sample Text" />
diff --git a/components/Behaviors/src/Headers/FadeHeaderBehavior.cs b/components/Behaviors/src/Headers/FadeHeaderBehavior.cs
@@ -34,7 +34,7 @@ protected override bool AssignAnimation()
             var scrollPropSet = _scrollProperties!.GetSpecializedReference<ManipulationPropertySetReferenceNode>();
 
             // Use the ScrollViewer's Y offset and the header's height to calculate the opacity percentage. Clamp it between 0% and 100%
-            var headerHeight = (float)HeaderElement.RenderSize.Height;
+            var headerHeight = (float)AssociatedObject.RenderSize.Height;
             var opacityExpression = ExpressionFunctions.Clamp(1 - (-scrollPropSet.Translation.Y / headerHeight), 0, 1);
 
             // Begin animating
diff --git a/components/Behaviors/src/Headers/HeaderBehaviorBase.cs b/components/Behaviors/src/Headers/HeaderBehaviorBase.cs
@@ -24,37 +24,6 @@ public abstract class HeaderBehaviorBase : BehaviorBase<FrameworkElement>
     protected CompositionPropertySet? _animationProperties;
     protected Visual? _headerVisual;
 
-    /// <summary>
-    /// Gets or sets the target element for the Header behavior to be manipulated within the viewport.
-    /// </summary>
-    /// <remarks>
-    /// Set this using the header of a ListView or GridView.
-    /// </remarks>
-    public FrameworkElement HeaderElement
-    {
-        get { return (FrameworkElement)GetValue(HeaderElementProperty); }
-        set { SetValue(HeaderElementProperty, value); }
-    }
-
-    /// <summary>
-    /// Defines the Dependency Property for the <see cref="HeaderElement"/> property.
-    /// </summary>
-    public static readonly DependencyProperty HeaderElementProperty = DependencyProperty.Register(
-        nameof(HeaderElement), typeof(FrameworkElement), typeof(HeaderBehaviorBase), new PropertyMetadata(null, PropertyChangedCallback));
-
-    /// <summary>
-    /// If any of the properties are changed then the animation is automatically started.
-    /// </summary>
-    /// <param name="d">The dependency object.</param>
-    /// <param name="e">The <see cref="DependencyPropertyChangedEventArgs"/> instance containing the event data.</param>
-    private static void PropertyChangedCallback(DependencyObject d, DependencyPropertyChangedEventArgs e)
-    {
-        if (d is HeaderBehaviorBase @base)
-        {
-            @base.AssignAnimation();
-        }
-    }
-
     /// <summary>
     /// Attaches the behavior to the associated object.
     /// </summary>
@@ -95,23 +64,23 @@ protected virtual bool AssignAnimation()
             return false;
         }
 
-        // TODO: What if we attach to the 'header element' and look up for the ScrollViewer?
         if (_scrollViewer == null)
         {
-            _scrollViewer = AssociatedObject as ScrollViewer ?? AssociatedObject.FindDescendant<ScrollViewer>();
+            // TODO: We probably want checks which provide better guidance if we detect we're not attached correctly?
+            _scrollViewer = AssociatedObject.FindAscendant<ScrollViewer>();
         }
 
         if (_scrollViewer == null)
         {
             return false;
         }
 
-        var listView = AssociatedObject as ListViewBase ?? AssociatedObject.FindDescendant<ListViewBase>();
+        var itemsControl = AssociatedObject.FindAscendant<ItemsControl>();
 
-        // TODO: Is this required?
-        if (listView != null && listView.ItemsPanelRoot != null)
+        if (itemsControl != null && itemsControl.ItemsPanelRoot != null)
         {
-            Canvas.SetZIndex(listView.ItemsPanelRoot, -1);
+            // This appears to be important to force the items within the ScrollViewer of an ItemsControl behind our header element.
+            Canvas.SetZIndex(itemsControl.ItemsPanelRoot, -1);
         }
 
         if (_scrollProperties == null)
@@ -124,20 +93,15 @@ protected virtual bool AssignAnimation()
             return false;
         }
 
-        // Implicit operation: Find the Header object of the control if it uses ListViewBase
-        if (HeaderElement == null && listView != null)
-        {
-            HeaderElement = (listView.Header as FrameworkElement)!;
-        }
-
-        if (HeaderElement == null || HeaderElement.RenderSize.Height == 0)
+        // Implicit operation: Double-check that we have an element associated with us (we should) and that it has size
+        if (AssociatedObject == null || AssociatedObject.RenderSize.Height == 0)
         {
             return false;
         }
 
         if (_headerVisual == null)
         {
-            _headerVisual = ElementCompositionPreview.GetElementVisual(HeaderElement);
+            _headerVisual = ElementCompositionPreview.GetElementVisual(AssociatedObject);
         }
 
         if (_headerVisual == null)
@@ -146,8 +110,8 @@ protected virtual bool AssignAnimation()
         }
 
         // TODO: Not sure if we need to provide an option to turn these events off, as FadeHeaderBehavior didn't use these two, unlike QuickReturn/Sticky did...
-        HeaderElement.SizeChanged -= ScrollHeader_SizeChanged;
-        HeaderElement.SizeChanged += ScrollHeader_SizeChanged;
+        AssociatedObject.SizeChanged -= ScrollHeader_SizeChanged;
+        AssociatedObject.SizeChanged += ScrollHeader_SizeChanged;
 
         _scrollViewer.GotFocus -= ScrollViewer_GotFocus;
         _scrollViewer.GotFocus += ScrollViewer_GotFocus;
@@ -177,9 +141,9 @@ protected virtual void RemoveAnimation()
             _scrollViewer.GotFocus -= ScrollViewer_GotFocus;
         }
 
-        if (HeaderElement != null)
+        if (AssociatedObject != null)
         {
-            HeaderElement.SizeChanged -= ScrollHeader_SizeChanged;
+            AssociatedObject.SizeChanged -= ScrollHeader_SizeChanged;
         }
 
         StopAnimation();
@@ -210,9 +174,9 @@ private void ScrollViewer_GotFocus(object sender, RoutedEventArgs e)
         {
             var point = element.TransformToVisual(scroller).TransformPoint(new Point(0, 0));
 
-            if (point.Y < HeaderElement.ActualHeight)
+            if (point.Y < AssociatedObject.ActualHeight)
             {
-                scroller.ChangeView(0, scroller.VerticalOffset - (HeaderElement.ActualHeight - point.Y), 1, false);
+                scroller.ChangeView(0, scroller.VerticalOffset - (AssociatedObject.ActualHeight - point.Y), 1, false);
             }
         }
     }
diff --git a/components/Behaviors/src/Headers/QuickReturnHeaderBehavior.cs b/components/Behaviors/src/Headers/QuickReturnHeaderBehavior.cs
@@ -90,7 +90,7 @@ private void ScrollViewer_ViewChanged(object? sender, ScrollViewerViewChangedEve
     {
         if (_animationProperties != null && _scrollViewer != null)
         {
-            var headerHeight = HeaderElement.ActualHeight;
+            var headerHeight = AssociatedObject.ActualHeight;
             if (_headerPosition + headerHeight < _scrollViewer.VerticalOffset)
             {
                 // scrolling down: move header down, so it is just above screen

Original file line number	Diff line number	Diff line change
`@@ -24,37 +24,6 @@ public abstract class HeaderBehaviorBase : BehaviorBase<FrameworkElement>`
`24`	`24`	`protected CompositionPropertySet? _animationProperties;`
`25`	`25`	`protected Visual? _headerVisual;`
`26`	`26`
`27`		`- /// <summary>`
`28`		`- /// Gets or sets the target element for the Header behavior to be manipulated within the viewport.`
`29`		`- /// </summary>`
`30`		`- /// <remarks>`
`31`		`- /// Set this using the header of a ListView or GridView.`
`32`		`- /// </remarks>`
`33`		`- public FrameworkElement HeaderElement`
`34`		`- {`
`35`		`- get { return (FrameworkElement)GetValue(HeaderElementProperty); }`
`36`		`- set { SetValue(HeaderElementProperty, value); }`
`37`		`- }`
`38`		`-`
`39`		`- /// <summary>`
`40`		`- /// Defines the Dependency Property for the <see cref="HeaderElement"/> property.`
`41`		`- /// </summary>`
`42`		`- public static readonly DependencyProperty HeaderElementProperty = DependencyProperty.Register(`
`43`		`- nameof(HeaderElement), typeof(FrameworkElement), typeof(HeaderBehaviorBase), new PropertyMetadata(null, PropertyChangedCallback));`
`44`		`-`
`45`		`- /// <summary>`
`46`		`- /// If any of the properties are changed then the animation is automatically started.`
`47`		`- /// </summary>`
`48`		`- /// <param name="d">The dependency object.</param>`
`49`		`- /// <param name="e">The <see cref="DependencyPropertyChangedEventArgs"/> instance containing the event data.</param>`
`50`		`- private static void PropertyChangedCallback(DependencyObject d, DependencyPropertyChangedEventArgs e)`
`51`		`- {`
`52`		`- if (d is HeaderBehaviorBase @base)`
`53`		`- {`
`54`		`- @base.AssignAnimation();`
`55`		`- }`
`56`		`- }`
`57`		`-`
`58`	`27`	`/// <summary>`
`59`	`28`	`/// Attaches the behavior to the associated object.`
`60`	`29`	`/// </summary>`
`@@ -95,23 +64,23 @@ protected virtual bool AssignAnimation()`
`95`	`64`	`return false;`
`96`	`65`	`}`
`97`	`66`
`98`		`- // TODO: What if we attach to the 'header element' and look up for the ScrollViewer?`
`99`	`67`	`if (_scrollViewer == null)`
`100`	`68`	`{`
`101`		`- _scrollViewer = AssociatedObject as ScrollViewer ?? AssociatedObject.FindDescendant<ScrollViewer>();`
	`69`	`+ // TODO: We probably want checks which provide better guidance if we detect we're not attached correctly?`
	`70`	`+ _scrollViewer = AssociatedObject.FindAscendant<ScrollViewer>();`
`102`	`71`	`}`
`103`	`72`
`104`	`73`	`if (_scrollViewer == null)`
`105`	`74`	`{`
`106`	`75`	`return false;`
`107`	`76`	`}`
`108`	`77`
`109`		`- var listView = AssociatedObject as ListViewBase ?? AssociatedObject.FindDescendant<ListViewBase>();`
	`78`	`+ var itemsControl = AssociatedObject.FindAscendant<ItemsControl>();`
`110`	`79`
`111`		`- // TODO: Is this required?`
`112`		`- if (listView != null && listView.ItemsPanelRoot != null)`
	`80`	`+ if (itemsControl != null && itemsControl.ItemsPanelRoot != null)`
`113`	`81`	`{`
`114`		`- Canvas.SetZIndex(listView.ItemsPanelRoot, -1);`
	`82`	`+ // This appears to be important to force the items within the ScrollViewer of an ItemsControl behind our header element.`
	`83`	`+ Canvas.SetZIndex(itemsControl.ItemsPanelRoot, -1);`
`115`	`84`	`}`
`116`	`85`
`117`	`86`	`if (_scrollProperties == null)`
`@@ -124,20 +93,15 @@ protected virtual bool AssignAnimation()`
`124`	`93`	`return false;`
`125`	`94`	`}`
`126`	`95`
`127`		`- // Implicit operation: Find the Header object of the control if it uses ListViewBase`
`128`		`- if (HeaderElement == null && listView != null)`
`129`		`- {`
`130`		`- HeaderElement = (listView.Header as FrameworkElement)!;`
`131`		`- }`
`132`		`-`
`133`		`- if (HeaderElement == null \|\| HeaderElement.RenderSize.Height == 0)`
	`96`	`+ // Implicit operation: Double-check that we have an element associated with us (we should) and that it has size`
	`97`	`+ if (AssociatedObject == null \|\| AssociatedObject.RenderSize.Height == 0)`
`134`	`98`	`{`
`135`	`99`	`return false;`
`136`	`100`	`}`
`137`	`101`
`138`	`102`	`if (_headerVisual == null)`
`139`	`103`	`{`
`140`		`- _headerVisual = ElementCompositionPreview.GetElementVisual(HeaderElement);`
	`104`	`+ _headerVisual = ElementCompositionPreview.GetElementVisual(AssociatedObject);`
`141`	`105`	`}`
`142`	`106`
`143`	`107`	`if (_headerVisual == null)`
`@@ -146,8 +110,8 @@ protected virtual bool AssignAnimation()`
`146`	`110`	`}`
`147`	`111`
`148`	`112`	`// TODO: Not sure if we need to provide an option to turn these events off, as FadeHeaderBehavior didn't use these two, unlike QuickReturn/Sticky did...`
`149`		`- HeaderElement.SizeChanged -= ScrollHeader_SizeChanged;`
`150`		`- HeaderElement.SizeChanged += ScrollHeader_SizeChanged;`
	`113`	`+ AssociatedObject.SizeChanged -= ScrollHeader_SizeChanged;`
	`114`	`+ AssociatedObject.SizeChanged += ScrollHeader_SizeChanged;`
`151`	`115`
`152`	`116`	`_scrollViewer.GotFocus -= ScrollViewer_GotFocus;`
`153`	`117`	`_scrollViewer.GotFocus += ScrollViewer_GotFocus;`
`@@ -177,9 +141,9 @@ protected virtual void RemoveAnimation()`
`177`	`141`	`_scrollViewer.GotFocus -= ScrollViewer_GotFocus;`
`178`	`142`	`}`
`179`	`143`
`180`		`- if (HeaderElement != null)`
	`144`	`+ if (AssociatedObject != null)`
`181`	`145`	`{`
`182`		`- HeaderElement.SizeChanged -= ScrollHeader_SizeChanged;`
	`146`	`+ AssociatedObject.SizeChanged -= ScrollHeader_SizeChanged;`
`183`	`147`	`}`
`184`	`148`
`185`	`149`	`StopAnimation();`
`@@ -210,9 +174,9 @@ private void ScrollViewer_GotFocus(object sender, RoutedEventArgs e)`
`210`	`174`	`{`
`211`	`175`	`var point = element.TransformToVisual(scroller).TransformPoint(new Point(0, 0));`
`212`	`176`
`213`		`- if (point.Y < HeaderElement.ActualHeight)`
	`177`	`+ if (point.Y < AssociatedObject.ActualHeight)`
`214`	`178`	`{`
`215`		`- scroller.ChangeView(0, scroller.VerticalOffset - (HeaderElement.ActualHeight - point.Y), 1, false);`
	`179`	`+ scroller.ChangeView(0, scroller.VerticalOffset - (AssociatedObject.ActualHeight - point.Y), 1, false);`
`216`	`180`	`}`
`217`	`181`	`}`
`218`	`182`	`}`
Original file line number	Diff line number	Diff line change
`@@ -90,7 +90,7 @@ private void ScrollViewer_ViewChanged(object? sender, ScrollViewerViewChangedEve`
`90`	`90`	`{`
`91`	`91`	`if (_animationProperties != null && _scrollViewer != null)`
`92`	`92`	`{`
`93`		`- var headerHeight = HeaderElement.ActualHeight;`
	`93`	`+ var headerHeight = AssociatedObject.ActualHeight;`
`94`	`94`	`if (_headerPosition + headerHeight < _scrollViewer.VerticalOffset)`
`95`	`95`	`{`
`96`	`96`	`// scrolling down: move header down, so it is just above screen`