Introduce Flyout concept

Proposal: Introduce Flyout concept

A flyout is a light dismiss container that can show arbitrary UI as its content. Flyouts can contain other flyouts or context menus to create a nested experience. (UWP docs)

Summary

Our old WPF-like ContextMenu API limits us and doesn’t allow to use anything more complex that simple menu. In same time Flyout has more use cases where it can be effectively used without low-level Popup.

Rationale

• We need ability to set any custom content inside of context menu (e.g. old MenuFlyout, new Flyout with a content, custom user flyout and maybe NativeMenuFlyout in the future).
• We need ability to use MenuFlyout (currently named as ContextMenu control) in other scenarios, not only “control right-click”. For instance, “Button.Flyout” should be displayed on button left-click without any additional code in code behind.
• Current ContextMenu can’t be extended to work with native menus. With new FlyoutBase API we can provide some space for that. Low priority, I guess.
• For TextBox we can implement richer context flyout instead of simple menu (as UWP did with TextCommandBarFlyout)

Scope

Capability	Priority
API that can work with either menu control (MenuFlyout) or content control (Flyout)	Must
Deprecate ContextMenu property and control	Should (see open question number 1)
Allow MenuFlyout with native menu implementation	Should (see open question number 3)
API similar to UWP	Should

Important Notes

API proposal without dependency properties (part of UWP API):

public abstract class FlyoutBase : AvaloniaObject
{
    bool IsOpen { get; }
    FlyoutPlacementMode Placement { get; set; } // Top, Bottom, Left, Right, Full
    Control? Target { get; set; }
    
    void ShowAt(Control);
    void Hide(); 
    virtual Control CreatePresenter();

    event EventHandler Closed;
    event EventHandler<CancelEventArgs> Closing;
    event EventHandler Opened;
    event EventHandler<CancelEventArgs> Opening;

    static FlyoutBase GetAttachedFlyout(Control);
    static void SetAttachedFlyout(Control, FlyoutBase);
    static void ShowAttachedFlyout(Control);
}

public class Flyout : FlyoutBase
{
    Classes FlyoutPresenterClasses { get; }
    Control Content { get; set; }
}

public class MenuFlyout : FlyoutBase
{
    IList<MenuItem> Items { get; }
}

public class Control
{
    FlyoutBase ContextFlyout { get; set; }
}

public class Button : Control
{
    FlyoutBase Flyout { get; set; }
}

And usage from xaml:

<Button Content="Hi!">
    <Button.Flyout>
       <MenuFlyout Placement="Bottom">
          <MenuItem Header="I am classic menu item, but show on button left-click." />
       </MenuFlyout>
    </Button.Flyout>
    <Button.ContextFlyout>
       <Flyout Placement="Top">
          <TextBlock Text="I will be shown on button right-click." />
       </Flyout>
    </Button.ContextFlyout>
</Button>

Another notes:

1. FlyoutBase is not a control, thus it has not a logical/visual parent and its one instance can be shared between controls.
2. One FlyoutBase has one internal Popup, which is created lazily with content from CreatePresenter.

Open Questions

1. Instead of deprecating old functionality, we can introduce Flyout functionality and related attached properties in optional package (Avalonia.WinUI or something like that).
2. UWP doesn’t have flexibility in Flyout-popup position customizations, including offsets. In same time our old ContextMenu does, so probably we might want to extend API with this.
3. FlyoutBase uses CreatePresenter method to show controls in the Popup. In similar way we can add another optional method to override, that will return platform specific handler for native implementation with Show and Hide methods - it can be helpful for native menu implementation. Related: https://github.com/AvaloniaUI/Avalonia/issues/3855
4. Difference between Popup and Flyout may not be clear enough. But even with simple Popup we can’t put custom content inside of ContextMenu property.

[MarcoMuellner]

@maxkatz6 Ah, sorry, i was just looking up how Flyouts work on Avalonia, so i stumbled upon this issue. Seeing that there was no documentation on it on the page, and this just being closed i assumed that nothing happened with this Issue. Apologies.

[maxkatz6]

@MarcoMuellner what’s news? It’s merged and closed. We don’t have good documentation yet though. But it’s the same as in UWP, so you can take a look there.