Custom overlays (OverlayElement)

MessageBox, Dialog, Drawer, CommandPalette, Callout and HoverCard share the base OverlayElement. Use it for your own control that covers the workspace, for example a loading screen or a tutorial step.

[UxmlElement]
public partial class LoadingOverlay : OverlayElement
{
    public LoadingOverlay() : base("loading-overlay") => Add(new Label("Loading..."));

    public void Show(VisualElement anchor) => ShowOver(anchor);

    public void Hide() => HideOverlay();

    // Escape does not close a loading screen
    protected override void Dismiss() { }
}

Member	Description
`OverlayElement(ussClass)`	The class of the control. The base makes the state and animation classes from it.
`ShowOver(anchor)`	Adds the overlay over the workspace of `anchor`, or over its document, and plays the enter animation.
`HideOverlay()`	Plays the exit animation and removes the overlay. An overlay declared in UXML goes back to its place, hidden.
`IsOpen`	True from the show until the close starts.
`IsModal`	Override it for an overlay that lets the keys through. Call `UpdateModal()` after its value changes.
`Dismiss()`	Called for Escape and the gamepad cancel button. Close the overlay here.
`OnRemoved()`	Called when other code removes the open overlay from the panel.
`OnEditorPreview()`	Called when the overlay attaches to an editor panel, such as the UI Builder canvas, where it shows in place. Fill the parts that the overlay otherwise makes when it shows.
`FocusFirst(preferred)`	Gives the focus to the first control in `preferred`, or to the first control of the overlay. It takes one or more parts, in the order of preference.
`HasFocusStops`	True when the overlay has a control that Tab stops at. A control in a hidden part does not count.
`TakePart(content, part, ussClass)`	Moves the controls of each child of `content` that has the class `ussClass` into `part`, and hides `part` while it is empty. Use it for a part that UXML declares as a marked child, such as a footer.

The USS of the control sets the position and the look. The base only adds the classes. Write rules for {class}--hidden (the start of the enter animation and the end of the exit), {class}--anim-in and {class}--anim-out (the transitions). See the tb-drawer rules in Controls.uss.
A modal overlay has the class tb-modal while it is open. It stops the workspace shortcuts, no key reaches the controls under it, and Tab and the arrow keys cycle its controls.
When the overlay closes, the focus goes back to the control that had it before the show. If your code moved the focus out of the overlay before the close, the focus stays there.

#Custom overlays (OverlayElement)

Custom overlays (OverlayElement)