HierarchyViewItem.OverlayIcon

Description

Gets the VisualElement that represents an icon that overlays over the icon of the item. This element is hidden by default.

Typically used to add an icon that indicates the state of the item. For example, you can use this to display an icon over a GameObject's icon that indicates a prefab has a broken reference.

The following example adds a custom tooltip that displays in the Hierarchy window when you hover over any GameObject that has a custom component named Notes attached to it. It uses OverlayIcon to add the custom overlay indicator to the icon of the GameObject.

The example requires a USS file called CustomTooltip.uss and a custom MonoBehaviour script called Notes.cs.

To use this example:

1. Save the script in a folder called Assets/Editor/CustomTooltip. Scripts in an Editor folder can use the Hierarchy module API without additional setup. If you save the script outside of an Editor folder, you must enable the Hierarchy built-in module in the Package Manager window, which also adds the module to your Player builds.
2. Copy the styles from the USS example on this page. Save them in a USS file called CustomTooltip.uss in the same Assets/Editor/CustomTooltip folder.
3. Save the Notes.cs script outside of an Editor folder, because MonoBehaviour scripts in an Editor folder can't be attached to GameObjects.
4. Add the Notes component to a GameObject.
5. In the Inspector window, enter text in the Note field of the Notes component.
6. In the Hierarchy window, hover over the name of the GameObject to display the text as a tooltip. A small overlay indicator also displays in the corner of the icon of any GameObject that has a note.

using System.Text;
using Unity.Hierarchy;
using Unity.Hierarchy.Editor;
using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;

namespace Unity.HierarchySamples.Editor
{
    class CustomTooltip
    {
        const string k_NotesOverlayUssClassName = "hierarchy-item__notes-overlay";

        [InitializeOnLoadMethod]
        static void Initialize()
        {
            HierarchyWindow.BindView += OnBindView;
            HierarchyWindow.BindViewItem += OnBindViewItem;
            HierarchyWindow.GetTooltip += OnGetTooltip;
        }

        static void OnBindView(HierarchyWindow window, HierarchyView view)
            => view.styleSheets.Add(AssetDatabase.LoadAssetAtPath<StyleSheet>("Assets/Editor/CustomTooltip/CustomTooltip.uss"));

        static void OnBindViewItem(HierarchyWindow window, HierarchyView view, HierarchyViewItem item)
        {
            if (item.Handler is not HierarchyGameObjectHandler handler)
                return;

            GameObject gameObject = handler.GetGameObject(item.Node);

            bool hasNotes = gameObject.TryGetComponent<Notes>(out Notes notes) && !string.IsNullOrWhiteSpace(notes.note);

            VisualElement notesOverlay = item.OverlayIcon.Q(className: k_NotesOverlayUssClassName);

            if (hasNotes)
            {
                if (notesOverlay == null)
                {
                    notesOverlay = new VisualElement();
                    notesOverlay.AddToClassList(k_NotesOverlayUssClassName);
                    item.OverlayIcon.Add(notesOverlay);
                }
            }
            else if (notesOverlay != null)
            {
                notesOverlay.RemoveFromHierarchy();
            }
        }

        static void OnGetTooltip(HierarchyWindow window, HierarchyView view, HierarchyViewItem item, StringBuilder tooltip, bool filtering)
        {
            if (item.Handler is not HierarchyGameObjectHandler handler)
                return;

            GameObject gameObject = handler.GetGameObject(item.Node);

            if (!gameObject.TryGetComponent<Notes>(out Notes notes) || string.IsNullOrWhiteSpace(notes.note))
                return;

            if (filtering)
            {
                // When filtering, append the note to the existing tooltip.
                tooltip.Append("\nNote: ");
                tooltip.Append(notes.note);
            }
            else
            {
                // When not filtering, fully override the tooltip.
                tooltip.Clear();
                tooltip.Append("Note: ");
                tooltip.Append(notes.note);
            }
        }
    }
}

The following example shows how to style CustomTooltip.uss.

.hierarchy-item__notes-overlay {
    position: absolute;
    width: 100%;
    height: 100%;
    background-size: 8px 8px;
    background-position: top left;
    background-repeat: no-repeat;
    background-image: var(--unity-icons-console_entry_info_small);
}

The following example shows the Notes component that the CustomTooltip example uses.

using UnityEngine;

namespace Unity.HierarchySamples
{
    // Simple component that allows attaching notes to GameObjects for display in custom tooltips.
    public class Notes : MonoBehaviour
    {
        [TextArea(3, 10)]
        public string note;
    }
}