How to Build Your Own Overlays
Hello! Here’s a quick-start guide to building your own Overlays with the new system. Please post questions and discussions here, we’ll be happy to help out.
For general Overlays info, and to download the public build, view the Overlays Public Preview thread.
Please keep in mind, this is an early preview, subject to change.
The Simplest Way
1. Create a class that inherits from Overlay class
{
}```
**2.** Add the Overlay attribute and provide:
- Which type of window it can appear in, use **EditorWindow** type if you want it to appear in any window that supports overlays
- a unique id
- A name, this will be displayed in its header and menu
```[Overlay(typeof(SceneView), k_Id, "My Awesome Overlay")]
class MyOverlay : Overlay
{
const string k_Id = "my-custom-overlay";
}```
**3.** Implement the **CreatePanelContent** method and have it return the content you wish to be displayed in the overlay. From this point refer to UI Toolkit docs to know how to build UI.
```public override VisualElement CreatePanelContent()
{
var myContent = new VisualElement { name = "my-content" };
return myContent;
}```
**4.** Add the icon attribute to specify which icon to use when collapsed, if no attribute is specified an icon with the 2 most significant letters of the overlay name will be generated for you
**Important Note: IconAttribute** is not available in the current preview build, but will be public when released.
```[Overlay(typeof(SceneView), k_Id, "My Awesome Overlay")]
[Icon("path/to/myIcon.png")]
class MyOverlay : Overlay
{
const string k_Id = "my-custom-overlay";
}```
**Note:** If your overlay does not appear, be aware that is the default behavior. Bring up the overlay menu by pressing the space bar in the Scene View (you can change this in the shortcut manager) you should see your overlay appear in the menu.
**Lifecycle**
Overlay visibility can be controlled through Overlay Menu, the 3 dot menu in the corner of the window or through code by directly changing the value of the **displayed** property. You may want to prevent the users from controlling the visibility and control it yourself ( from a toggle in a toolbar for example ) in this case be sure to set the property **userControlledVisibility** to false, in the Overlay constructor for example.
**Toolbars**
If implemented this way, you will notice that your overlay will collapse when inserted into a toolbar, you can change this behavior by implementing the **ICreateHorizontalToolbar** and the **ICreateVerticalToolbar** interfaces.
```[Overlay(typeof(SceneView), k_Id, "My Awesome Overlay")]
class MyOverlay : Overlay, ICreateHorizontalToolbar, ICreateVerticalToolbar
{
const string k_Id = "my-custom-overlay";
public override VisualElement CreatePanelContent()
{
var myContent = new VisualElement { name = "my-content" };
return myContent;
}
public VisualElement CreateHorizontalToolbarContent()
{
var myContent = new VisualElement { name = "my-horizontal-content" };
return myContent;
}
public VisualElement CreateVerticalToolbarContent()
{
var myContent = new VisualElement { name = "my-vertical-content" };
return myContent;
}
}```
**IMGUI**
If you are converting some existing UI code to use the overlay system, chances are it is written in IMGUI. We strongly advise to take this opportunity to convert your whole UI to UITK. In the case where this is not possible you can use the **IMGUIOverlay** class.
```[Overlay(typeof(SceneView),k_OverlayID,k_DisplayName)]
internal class MyIMGUIOverlay : IMGUIOverlay
{
public const string k_OverlayID = "my-custom-overlay";
const string k_DisplayName = "My Awesome Overlay";
public override void OnGUI()
{
//Draw IMGUI stuff here
}
}```
**Other Windows**
The overlay system is not restricted to the SceneView, any **EditorWindow** can opt in to have it enabled. All it needs to do is implement the **ISupportsOverlays** interface. Overlays targeting **EditorWindow** will automatically be available, otherwise Overlays need to target your **EditorWindow** type.
So before doing so, let me know if you want me to give the implementation details here or somewhere else.
