Add lazy loading threshold for ImageEx control (#3483)

## Fixes
<!-- Add the relevant issue number after the "#" mentioned above (for ex: Fixes #1234) which will automatically close the issue once the PR is merged. -->
Add lazy loading threshold for ```ImageEx``` control and change the lazy loading implement that will be also fixed #3258 .

<!-- Add a brief overview here of the feature/bug & fix. -->

## PR Type
What kind of change does this PR introduce?
<!-- Please uncomment one or more that apply to this PR. -->

 - Bugfix 
 - Feature 
<!-- - Code style update (formatting) -->
<!-- - Refactoring (no functional changes, no api changes) -->
<!-- - Build or CI related changes -->
<!-- - Documentation content changes -->
<!-- - Sample app changes -->
<!-- - Other... Please describe: -->


## What is the current behavior?
<!-- Please describe the current behavior that you are modifying, or link to a relevant issue. -->
If enable lazy loading, only the ImageEx entered the viewport, the source will start to load.

## What is the new behavior?
<!-- Describe how was this issue resolved or changed? -->
Give a threshold for triggering the lazy loading behavior, the default value is 300 px.

## PR Checklist

Please check if your PR fulfills the following requirements:

- [x] Tested code with current [supported SDKs](../readme.md#supported)
- [x] Pull Request has been submitted to the documentation repository [instructions](..\contributing.md#docs). Link: https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/pull/387<!-- docs PR link -->
- [x] Sample in sample app has been added / updated (for bug fixes / features)
    - [ ] Icon has been created (if new sample) following the [Thumbnail Style Guide and templates](https://github.com/windows-toolkit/WindowsCommunityToolkit-design-assets)
- [ ] Tests for the changes have been added (for bug fixes / features) (if applicable)
- [ ] Header has been added to all new source files (run *build/UpdateHeaders.bat*)
- [x] Contains **NO** breaking changes

<!-- If this PR contains a breaking change, please describe the impact and migration path for existing applications below. 
     Please note that breaking changes are likely to be rejected. -->


## Other information

Author: msftbot[bot]

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/ImageEx/ImageExLazyLoadingControl.xaml

@@ -28,8 +28,7 @@
             <TextBlock HorizontalAlignment="Left"
                        VerticalAlignment="Top"
                        Foreground="OrangeRed"
-                       IsHitTestVisible="False"
-                       Text="Please scroll down to see the effect." />
+                       IsHitTestVisible="False"><Run Text="Please scroll down to see the effect." /><LineBreak /><Run Text="The default threshold for triggering lazy loading is 300 px." /></TextBlock>
             <Button Width="48"
                     Height="48"
                     HorizontalAlignment="Right"

Microsoft.Toolkit.Uwp.UI.Controls/ImageEx/ImageEx.xaml

@@ -6,6 +6,7 @@
         <Setter Property="Background" Value="Transparent" />
         <Setter Property="Foreground" Value="{ThemeResource ApplicationForegroundThemeBrush}" />
         <Setter Property="IsTabStop" Value="False" />
+        <Setter Property="LazyLoadingThreshold" Value="300" />
         <Setter Property="Template">
             <Setter.Value>
                 <ControlTemplate TargetType="controls:ImageEx">

Microsoft.Toolkit.Uwp.UI.Controls/ImageEx/ImageExBase.Members.cs

@@ -48,7 +48,12 @@ public partial class ImageExBase
         /// <summary>
         /// Identifies the <see cref="EnableLazyLoading"/> dependency property.
         /// </summary>
-        public static readonly DependencyProperty EnableLazyLoadingProperty = DependencyProperty.Register(nameof(EnableLazyLoading), typeof(bool), typeof(ImageExBase), new PropertyMetadata(false));
+        public static readonly DependencyProperty EnableLazyLoadingProperty = DependencyProperty.Register(nameof(EnableLazyLoading), typeof(bool), typeof(ImageExBase), new PropertyMetadata(false, EnableLazyLoadingChanged));
+
+        /// <summary>
+        /// Identifies the <see cref="LazyLoadingThreshold"/> dependency property.
+        /// </summary>
+        public static readonly DependencyProperty LazyLoadingThresholdProperty = DependencyProperty.Register(nameof(LazyLoadingThreshold), typeof(double), typeof(ImageExBase), new PropertyMetadata(default(double), LazyLoadingThresholdChanged));
 
         /// <summary>
         /// Returns a mask that represents the alpha channel of an image as a <see cref="CompositionBrush"/>
@@ -139,5 +144,40 @@ public bool EnableLazyLoading
             get { return (bool)GetValue(EnableLazyLoadingProperty); }
             set { SetValue(EnableLazyLoadingProperty, value); }
         }
+
+        /// <summary>
+        /// Gets or sets a value indicating the threshold for triggering lazy loading.
+        /// </summary>
+        public double LazyLoadingThreshold
+        {
+            get { return (double)GetValue(LazyLoadingThresholdProperty); }
+            set { SetValue(LazyLoadingThresholdProperty, value); }
+        }
+
+        private static void EnableLazyLoadingChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+        {
+            if (d is ImageExBase control)
+            {
+                var value = (bool)e.NewValue;
+                if (value)
+                {
+                    control.LayoutUpdated += control.ImageExBase_LayoutUpdated;
+
+                    control.InvalidateLazyLoading();
+                }
+                else
+                {
+                    control.LayoutUpdated -= control.ImageExBase_LayoutUpdated;
+                }
+            }
+        }
+
+        private static void LazyLoadingThresholdChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+        {
+            if (d is ImageExBase control && control.EnableLazyLoading)
+            {
+                control.InvalidateLazyLoading();
+            }
+        }
     }
 }

Microsoft.Toolkit.Uwp.UI.Controls/ImageEx/ImageExBase.cs

@@ -3,6 +3,9 @@
 // See the LICENSE file in the project root for more information.
 
 using System;
+using System.Linq;
+using Microsoft.Toolkit.Uwp.Extensions;
+using Microsoft.Toolkit.Uwp.UI.Extensions;
 using Windows.Foundation;
 using Windows.UI.Xaml;
 using Windows.UI.Xaml.Controls;
@@ -79,8 +82,6 @@ public abstract partial class ImageExBase : Control
         public ImageExBase()
         {
             LockObj = new object();
-
-            EffectiveViewportChanged += ImageExBase_EffectiveViewportChanged;
         }
 
         /// <summary>
@@ -215,15 +216,47 @@ private void OnImageFailed(object sender, ExceptionRoutedEventArgs e)
             VisualStateManager.GoToState(this, FailedState, true);
         }
 
-        private void ImageExBase_EffectiveViewportChanged(FrameworkElement sender, EffectiveViewportChangedEventArgs args)
+        private void ImageExBase_LayoutUpdated(object sender, object e)
+        {
+            InvalidateLazyLoading();
+        }
+
+        private void InvalidateLazyLoading()
         {
-            var bringIntoViewDistanceX = args.BringIntoViewDistanceX;
-            var bringIntoViewDistanceY = args.BringIntoViewDistanceY;
+            if (!IsLoaded)
+            {
+                _isInViewport = false;
+                return;
+            }
+
+            // Find the first ascendant ScrollViewer, if not found, use the root element.
+            FrameworkElement hostElement = null;
+            var ascendants = this.FindAscendants().OfType<FrameworkElement>();
+            foreach (var ascendant in ascendants)
+            {
+                hostElement = ascendant;
+                if (hostElement is ScrollViewer)
+                {
+                    break;
+                }
+            }
+
+            if (hostElement == null)
+            {
+                _isInViewport = false;
+                return;
+            }
 
-            var width = ActualWidth;
-            var height = ActualHeight;
+            var controlRect = TransformToVisual(hostElement)
+                .TransformBounds(new Rect(0, 0, ActualWidth, ActualHeight));
+            var lazyLoadingThreshold = LazyLoadingThreshold;
+            var hostRect = new Rect(
+                0 - lazyLoadingThreshold,
+                0 - lazyLoadingThreshold,
+                hostElement.ActualWidth + (2 * lazyLoadingThreshold),
+                hostElement.ActualHeight + (2 * lazyLoadingThreshold));
 
-            if (bringIntoViewDistanceX <= width && bringIntoViewDistanceY <= height)
+            if (controlRect.IntersectsWith(hostRect))
             {
                 _isInViewport = true;
 

Microsoft.Toolkit.Uwp/Extensions/RectExtensions.cs

@@ -0,0 +1,37 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Diagnostics.Contracts;
+using System.Runtime.CompilerServices;
+using Rect = Windows.Foundation.Rect;
+
+namespace Microsoft.Toolkit.Uwp.Extensions
+{
+    /// <summary>
+    /// Extensions for the <see cref="Rect"/> type.
+    /// </summary>
+    public static class RectExtensions
+    {
+        /// <summary>
+        /// Determines if a rectangle intersects with another rectangle.
+        /// </summary>
+        /// <param name="rect1">The first rectangle to test.</param>
+        /// <param name="rect2">The second rectangle to test.</param>
+        /// <returns>This method returns <see langword="true"/> if there is any intersection, otherwise <see langword="false"/>.</returns>
+        [Pure]
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static bool IntersectsWith(this Rect rect1, Rect rect2)
+        {
+            if (rect1.IsEmpty || rect2.IsEmpty)
+            {
+                return false;
+            }
+
+            return (rect1.Left <= rect2.Right) &&
+                   (rect1.Right >= rect2.Left) &&
+                   (rect1.Top <= rect2.Bottom) &&
+                   (rect1.Bottom >= rect2.Top);
+        }
+    }
+}

UnitTests/UnitTests.UWP/Extensions/Test_RectExtensions.cs

@@ -0,0 +1,40 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Toolkit.Uwp.Extensions;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using Windows.Foundation;
+
+namespace UnitTests.Extensions
+{
+    [TestClass]
+    public class Test_RectExtensions
+    {
+        [TestCategory("RectExtensions")]
+        [TestMethod]
+        [DataRow(0, 0, 2, 2, 0, 0, 2, 2, true)]// Full intersection.
+        [DataRow(0, 0, 2, 2, 1, 1, 2, 2, true)]// Partial intersection.
+        [DataRow(0, 0, 2, 2, -2, 0, 2, 2, true)]// Left edge intersection.
+        [DataRow(0, 0, 2, 2, 0, -2, 2, 2, true)]// Top edge intersection.
+        [DataRow(0, 0, 2, 2, 2, 0, 2, 2, true)]// Right edge intersection.
+        [DataRow(0, 0, 2, 2, 0, 2, 2, 2, true)]// Bottom edge intersection.
+        [DataRow(0, 0, 2, 2, -2, -2, 2, 2, true)]// Left top corner(0, 0) intersection.
+        [DataRow(0, 0, 2, 2, 2, -2, 2, 2, true)]// Right top corner(2, 0) intersection.
+        [DataRow(0, 0, 2, 2, 2, 2, 2, 2, true)]// Right bottom corner(2, 2) intersection.
+        [DataRow(0, 0, 2, 2, -2, 2, 2, 2, true)]// Left bottom corner(0, 2) intersection.
+        [DataRow(0, 0, 2, 2, 3, 0, 2, 2, false)]// No intersection.
+        [SuppressMessage("StyleCop.CSharp.ReadabilityRules", "SA1117:Parameters should be on same line or separate lines", Justification = "Put the parameters of the same rectangle on the same line is clearer.")]
+        public static void Test_RectExtensions_IntersectsWith(
+            double rect1X, double rect1Y, double rect1Width, double rect1Height,
+            double rect2X, double rect2Y, double rect2Width, double rect2Height,
+            bool shouldIntersectsWith)
+        {
+            var rect1 = new Rect(rect1X, rect1Y, rect1Width, rect1Height);
+            var rect2 = new Rect(rect2X, rect2Y, rect2Width, rect2Height);
+            var isIntersectsWith = rect1.IntersectsWith(rect2);
+            Assert.IsTrue(isIntersectsWith == shouldIntersectsWith);
+        }
+    }
+}

UnitTests/UnitTests.UWP/UnitTests.UWP.csproj

@@ -133,6 +133,7 @@
     <Compile Include="Converters\Test_TypeToObjectConverter.cs" />
     <Compile Include="Extensions\Helpers\ObjectWithNullableBoolProperty.cs" />
     <Compile Include="Extensions\Test_PointExtensions.cs" />
+    <Compile Include="Extensions\Test_RectExtensions.cs" />
     <Compile Include="Extensions\Test_SizeExtensions.cs" />
     <Compile Include="Extensions\Test_BitmapIconExtensionMarkupExtension.cs" />
     <Compile Include="Extensions\Test_FontIconSourceExtensionMarkupExtension.cs" />