ScrollViewer expression animations extensions

[Sergio0694]

This PR is part of the group being tracked in #3108.

PR Type

What kind of change does this PR introduce?

• Feature

What is the new behavior?

Two extension methods for the ScrollViewer class that can be used to easily create and start expression animations that bind the scrolling translation on a specified axis of the source scroller, to the offset on a given axis of a target control. This can be used to keep "in sync" the contents of a ScrollViewer with some overlays rendered on another surface that is not part of the ScrollViewer, as the expression animation will adjust the offset of the external surface to perfectly follow its content.

Here it is in action, you can see that there is some text inside a RichEditBox, and these new extensions are used to keep the text in sync with the text overlays (the dashed column guides and the TAB arrows) and the indentation indicators on the left, which are all rendered in a Win2D canvas outside of the ScrollViewer within the text control. Additionally, the line number are displayed through a TextBlock living in a Canvas, which is also kept in sync with the text in the same way:

PR Checklist

Please check if your PR fulfills the following requirements:

• Tested code with current supported SDKs
• Pull Request has been submitted to the documentation repository instructions. Link: Scrollviewer expression animations MicrosoftDocs/WindowsCommunityToolkitDocs#346
• 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
• 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)
• If new feature, add to Feature List
• Contains NO breaking changes

Other information

cc. @michael-hawker - would you like me to create a sample/docs page for these two extensions, or is it not needed since they're just two small extensions in an already existing class? Keeping this as a draft PR for now since I'm not sure about this specific point 😄

[ghost]

Thanks Sergio0694 for opening a Pull Request! The reviewers will test the PR and highlight if there is any conflict or changes required. If the PR is approved we will proceed to merge the pull request 🙌

[michael-hawker]

@Sergio0694 just going through other issues and saw #1499, can you help me understand how these two things relate?

[Sergio0694]

@michael-hawker Those looks like unrelated extensions, if not for the fact that they (indirectly) both work on a target ScrollViewer at the end of the day. But for instance, those extensions target the ListViewBase type, so they would actually go in another extension class (ListViewBaseExtensions?), and not in the one I'm using here. Also, those are just doing manipulations on the internal ScrollViewer to bring a given item in view, while the ones in this PR instead are about creating a composition expression animation to get an animation that follows the scrolling on the entire targeted ScrollViewer. So yeah, different APIs in use and different use cases. Hope this helps! 😊

[michael-hawker]

It could be cool to have a sample to show you how you'd setup that sort of syncing as a sample page.

[Sergio0694]

Added a sample in the ScrollViewerExample sample page, along with a reference C# snippet. Also modified the API surface to add an additional VisualProperty option, so that users can choose whether to animate through Visual.Translation or Visual.Offset.

For instance, Visual.Translate is enabled by default as it's the one that generally works fine, but there are cases where Visual.Offset might be preferred (eg. when the target items are inside a Canvas).

Let me know if there are any other changes I should do! 😊

[michael-hawker]

Small nitpick to make the sample shine, but otherwise this is really cool!

@azchohfi I was late on reviewing this before due to all my PC/Internet troubles. This is small and isolated, so seems low-risk to take this late. You good with that?

[ghost]

This PR has been marked as "needs attention 👋" and awaiting a response from the team.

[michael-hawker]

I'll pull this down and re-review now, but I think we'll be good!

[michael-hawker]

All good, we should Squash and Merge this one again, as there's the weird history coming from @Sergio0694's branches. Hopefully we can get that reset and fixed in future PRs. 😋