Overlay

Description

Overlays are persistent and customizable panels and toolbars that are available within Editor Windows. Use Overlays to expose actions and tool options in a convenient and user-controllable way.

This is the base class that all overlays inherit from. To create an overlay, return a UnityEngine.UIElements.VisualElement.

The simplest way to display an overlay is to use OverlayAttribute and register a target EditorWindow.

using UnityEditor;
using UnityEditor.Overlays;
using UnityEngine.UIElements;

// Specifying `OverlayAttribute.editorWindowType` tells the OverlayCanvas to always show this Overlay in the menu.
[Overlay(typeof(SceneView), "Selection Count")]
class SelectionCount : Overlay
{
    Label m_Label;

    public override VisualElement CreatePanelContent()
    {
        Selection.selectionChanged += () =>
        {
            if (m_Label != null)
                m_Label.text = $"Selection Count {Selection.count}";
        };

        return m_Label = new Label($"Selection Count {Selection.count}");
    }
}

Overlays can be used in any EditorWindow that implements ISupportsOverlays. You can use OverlayCanvas.Add and OverlayCanvas.Remove to add and remove overlays from the Overlays menu.

using System;
using UnityEditor;
using UnityEditor.Overlays;
using UnityEngine;
using UnityEngine.UIElements;

public class OverlayWindowExample : EditorWindow, ISupportsOverlays
{
    bool m_ShowOverlay;
    InstanceOverlay m_Overlay;
    
    // InstanceOverlay is not registered as a persistent Overlay, and must be instantiated through code. In contrast, 
    // PersistentOverlay is registered with a target window type and will be available at any time.
    // All OverlayAttribute properties are optional. Here we specify that when this Overlay is added to a window for the 
    // first time, it should be visible by default. If `defaultDisplay` is set to it's default value of false, the 
    // Overlay will be available in the Overlay Menu when added to a window, but not visible.
    [Overlay(defaultDisplay = true)]
    class InstanceOverlay : Overlay
    {
        OverlayWindowExample m_Window;
        public InstanceOverlay(OverlayWindowExample win) => m_Window = win;
        public override VisualElement CreatePanelContent() => new Label() { text = $"Hello from {m_Window.name}!" };
    }

    // Persistent overlays are always available in the Overlay Menu. An Overlay is made persistent by assigning the 
    // `editorWindowType` property in `OverlayAttribute`.
    [Overlay(typeof(OverlayWindowExample), "Persistent Overlay", defaultDisplay = true)]
    class PersistentOverlay : Overlay
    {
        public override VisualElement CreatePanelContent() => new Label() { text = "Hello, I'm always available!" };
    }

    [MenuItem("Window/Overlay Window")]
    static void Init() => GetWindow<OverlayWindowExample>();

    void OnEnable() => m_Overlay = new InstanceOverlay(this);

    void OnGUI()
    {
        EditorGUI.BeginChangeCheck();
        m_ShowOverlay = EditorGUILayout.Toggle("Show Overlay", m_ShowOverlay);
        if (EditorGUI.EndChangeCheck())
        {
            if (m_ShowOverlay)
                overlayCanvas.Add(m_Overlay);
            else
                overlayCanvas.Remove(m_Overlay);
        }
    }
}

Overlays can be shown in the active SceneView through SceneView.AddOverlayToActiveView and SceneView.RemoveOverlayFromActiveView. This is useful for EditorTools that need to show UI.

using System.Linq;
using UnityEngine;
using UnityEditor;
using UnityEditor.EditorTools;
using UnityEditor.Overlays;
using UnityEngine.UIElements;

// A simple tool that moves the selected transforms using an Overlay interface.
[EditorTool("Offset", typeof(Transform))]
public class OffsetTool : EditorTool
{
    // By default, Overlays added to the canvas are not shown. Setting the `defaultDisplay` property ensures that the
    // first time this Overlay is added to a canvas it will be visible.
    [Overlay(defaultDisplay = true)]
    class OffsetToolOverlay : Overlay, ITransientOverlay
    {
        Transform[] selection;

        public OffsetToolOverlay(Transform[] targets) => selection = targets;

        public override VisualElement CreatePanelContent()
        {
            var root = new VisualElement();
            root.Add(new Button(() => Move(Vector3.right)) { text = "Move Right" });
            root.Add(new Button(() => Move(Vector3.up)) { text = "Move Up" });
            root.Add(new Button(() => Move(Vector3.forward)) { text = "Move Forward" });
            return root;
        }

        void Move(Vector3 direction)
        {
            Undo.RecordObjects(selection, "Move Selection");
            foreach (var transform in selection)
                transform.position += direction;
        }

        // Use the visible property to hide or show this instance from within the class.
        public bool visible => true;
    }

    OffsetToolOverlay m_Overlay;

    public override void OnActivated()
    {
        SceneView.AddOverlayToActiveView(m_Overlay = new OffsetToolOverlay(targets.Select(x => x as Transform).ToArray()));
    }

    public override void OnWillBeDeactivated()
    {
        SceneView.RemoveOverlayFromActiveView(m_Overlay);
    }
}

To create an Overlay that is dockable in a toolbar, see ToolbarOverlay.

Static Properties

Properties

Public Methods

Events