Modern Adorners

[michael-hawker]

Adorners

Problem Statement

Adorners were a big feature in WPF for creative experiences in visual and textual editors to highlight parts of the UI for contextual interaction by a user (among other things).

This experiment is going to investigate how they work in WPF and how we might polyfill that functionality into UWP/WinUI using new components from the Windows Community Toolkit Labs.

Ideally, we have a similar experience and API surface with possible extensions for improvements to tie Adorners more to the XAML layer. At least showing some common patterns/experiences from Adorners done in WPF replicated in UWP/WinUI.

Most-likely out-of-scope is investigating/addressing the obvious gap in OnRender/DrawingContext methods from UIElement compared to WPF.

Inspiration

Much called out gap from WPF in implementing certain types of experiences.

Implementation of #212 and #213 type controls, provide an easy to use panel that may be of use for this type of overlay system.

There's also the ScrollViewerExtensions for animating/syncing content in a scrollviewer which could be handy?

XAML Behaviors and how behaviors work I think will play a role in how a modern Adorner system could work.

Proposed Solution

Overall ideas around architecture

There'll be some sort of AdornerLayer type component which represents the Canvas type space that adorners live on above all other components of an app. I think when the first Adorner is attempted to be used, an AdornerLayer is searched for and injected if none found? Otherwise, we have to leave it up to the developer to specify one within their app (which I think allowing and targeting specific layers would be good to have anyway).

Adorner can be subclassed by an implementor for specific 'behaviors' that can be shared. However, it'd be nice if there was a way to just inject XAML to be shown/placed on the adorner layer without having to write specific implementations using an Adorner class. In this case it'd be nice if there was an easy way to toggle the Adorner on/off, maybe that's just visibility?

Adorners should know where their attached component is in relation to the display surface (i.e. able to use relative coordinates for layout).

API Surface

Been using a labs:AdornerLayer.Xaml attached property helper at the moment, but expect that to be temporary and turn into it's own Adorner helper that is shipped with this feature.

Expect the actual API surface to be something like:

 <Button>
    <SymbolIcon HorizontalAlignment="Center"
                Symbol="Mail" />

    <labs:AdornerLayer.Adorner>
      <labs:XamlAdorner>
        <muxc:InfoBadge Margin="-4"
                        HorizontalAlignment="Right"
                        VerticalAlignment="Top"
                        IsHitTestVisible="False"
                        Value="5" />
      </labs:XamlAdorner>
    </labs:AdornerLayer.Xaml>
  </Button>

We want an AdornerDecorator helper to help establish a way for a developer to inject their own AdornerLayers (especially at the top-level due to issues with RootScrollViewer (TODO Link to WinUI issue to be filed)):

<AdornerDecorator>
  <ContentPresenter/><!-- or like app's root Frame -->
</AdornerDecorator>

From https://github.com/dotnet/wpf/blob/main/src/Microsoft.DotNet.Wpf/src/Themes/XAML/Window.xaml

Open Questions

API Reference Docs

• Adorner
• AdornerLayer Implementation (WPF)
• Adorner Implementation (WPF)

References

• InfoBadge proposal notes

Platform Issues

• Proposal: UIElement/FrameworkElement should expose protected method to add/initialize VisualTree microsoft/microsoft-ui-xaml#5530
• x:Bind Pathless Casting (this) references cause source generator error unoplatform/uno#7893

[michael-hawker]

Tinkering with ideas for XAML based attaching/initializing of adorners.

Obviously, it'd be one of these types of things, but just iterating on different ideas together here:

        <Button labs:Adorner.Attach="local:MyAdornerType"> <!-- auto-instantiate by type, reflection is meh -->
            <SymbolIcon Symbol="Mail" HorizontalAlignment="Center"/>
            <labs:Adorner.Xaml> <!-- Simple helper to add xaml directly as an adornment, but then how do we control position, etc...? -->
                <muxc:InfoBadge Value="5"/>
            </labs:Adorner.Xaml>
            <labs:Adorner.Attach> <!-- More generalized point -->
                <local:MyAdornerType/> <!-- Take initialized by xaml version, would need property to get element from attach helper? -->
                <labs:XamlAdorner Offset="??"> <!-- Then we could have our own XAML based adorner to helper here instead which could have more options... -->
                    <muxc:InfoBadge Value="5"/>
                </labs:XamlAdorner>
            </labs:Adorner.Attach>
        </Button>

[michael-hawker]

Started a branch here: https://github.com/michael-hawker/Labs-Windows/tree/llama/adorners/labs/Adorners

Had a lot of trouble trying to auto-inject a AdornerLayer and re-parent the content of the app scroll viewer. Kept getting the child of another element exception even after waiting for content to be set to null or content unloaded event to fire... 🙁

So easy to add a badge to a button though now with this initial exploration:

    <Grid>
            <Button>
                <SymbolIcon HorizontalAlignment="Center"
                            Symbol="Mail" />

                <labs:AdornerLayer.Xaml>
                    <muxc:InfoBadge Margin="-4"
                                    HorizontalAlignment="Right"
                                    VerticalAlignment="Top"
                                    IsHitTestVisible="False"
                                    Value="5" />
                </labs:AdornerLayer.Xaml>

            </Button>

        <!-- Dev should have this as part of their main host window/page content above the frame -->
        <labs:AdornerLayer />
    </Grid>

Even stumbled into the GetAdornerLayer static method on the AdornerLayer class, so that part is the same at the moment for WPF, just started by having this simple Xaml connector as an attached property, may change in the future, but wanted to get something to start testing. Just got hung up on the auto-insertion of the layer.

Still many things to investigate and test around scrolling, resizing, and visibility of the adorned element. But it's a start!

[michael-hawker]

Turns out my issues were specifically with RootScrollViewer at the top of the application, it looks like a ScrollViewer but behaves differently. If I try and inject in a normal ScrollViewer that's been added by the app developer, than it works fine!

Added another sample, bit more work left to do on that one, but making progress.

Main to dos left for now:

• investigate RootScrollViewer solution
• AdornerDecorator Container (optimization)
  • AdornerDecoratorPanel (optimization) simple Grid like panel where all children fill up the available space
• Detect adorned element size/position change (e.g. ScrollViewer's inner panel layout update event?)
• Samples
  • Notification Badge w/ InfoBadge
  • Highlight element bounds (partially implemented need toolkit helper port or abstraction)
  • Resize Grippers
• Custom adorners i.e. Adorner class itself
• Tests

[michael-hawker]

Quick note here to not forget that there was a clipping option for adorners, and I think with our clip helper in the Toolkit, this might not be too big a deal to implement: https://learn.microsoft.com/en-us/dotnet/api/system.windows.documents.adorner.isclipenabled

[michael-hawker]

Updated comments and main issue with latest thoughts. Added AdornerDecorator polyfill as well now to match WPF and help us with detecting already injected AdornerLayout positions.

[wbokkers]

What's the state of the Adorner implementation? Any change it will eventually land into the toolkit?

[michael-hawker]

I should have probably just merged what I had into Labs here. Our tooling has updated quite a bit, so not sure how extensive rebasing it would be.

There were a number of edge scenarios that needed investigation/work, but I think the base concept was potential viable path. I just also wanted to do some comparison to WPF as a possible polyfill/migration path, but not as familiar as I once was with that side of things.

If anyone wants to help move any of this along, the code should be all in my branch there.