#Callout

A Callout is a speech bubble: a box with a tip that points at a control. It stays open until your code, Escape or a press outside closes it. Use it for a hint, a tutorial step, a warning next to a field, or a small popover with controls. For a text that shows while the pointer is over a control, use a ToolTip. For a callout that opens on hover, use a HoverCard.

Video tutorial: Callouts. All videos: Video tutorials.

How to add a callout in UXML:

1. Declare the callout in the UXML of a window. Set target to the name of the control that it points at.
2. Find the callout in code and call Open or Toggle from a button.

<ui:Button name="rename" text="Rename" />
<tb:Callout name="renamePopover" target="rename" placement="Right" close-on-outside-click="true" text="Type the new name.">
    <ui:TextField label="Name" />
    <ui:Button name="ok" text="OK" />
</tb:Callout>

var popover = root.Q<Callout>("renamePopover");
root.Q<Button>("rename").clicked += () => popover.Toggle();
root.Q<Button>("ok").clicked += popover.Close;
popover.Closed += () => Debug.Log($"Name: {popover.Q<TextField>().value}");

How to make a callout in code:

var hint = new Callout { Text = "Click here to save.", Placement = CalloutPlacement.Right };
hint.Open(saveButton);

How to show a warning next to a field:

var warning = new Callout { Text = "The name is in use.", Severity = Severity.Warning };
nameField.RegisterValueChangedCallback(evt =>
{
    if (names.Contains(evt.newValue)) warning.Open(nameField);
    else warning.Close();
});

How to keep a callout at a fixed place (a tutorial text in a corner that points at one control, then at the next):

var step = new Callout { Placement = CalloutPlacement.Free, TipSize = 18, Text = "First, pick a class." };
step.style.left = 40;
step.style.top = 170;
step.style.width = 220;
step.Open(classDropdown);
// The box stays. The tip turns to the new target.
nextButton.clicked += () => { step.Text = "Then type a name."; step.Target = nameField; };

Tutorial hint: a callout that the user can move, with a line to the control and a frame around it:

<ui:Button name="continue" text="Continue" />
<tb:Callout name="tutorial" target="continue" placement="Free" style="left: 40px; top: 170px;"
            title="Step 1" text="Click the button to continue."
            connector="true" highlight-target="true" draggable="true" />

var tutorial = root.Q<Callout>("tutorial");
tutorial.Open();
root.Q<Button>("continue").clicked += tutorial.Close;

// The same callout in code
var hint = new Callout { Placement = CalloutPlacement.Free, Title = "Step 1", Text = "Click the button to continue." };
hint.Connector = true;
hint.HighlightTarget = true;
hint.Draggable = true; // the user can move the hint off the controls that it covers
hint.style.left = 40;
hint.style.top = 170;
hint.Open(continueButton);

How to point one callout at several elements:

// The box is next to the first element. The other two get a line from the box and a frame.
var step = new Callout { Title = "Edit the label", Text = "Select the series, then change its Label.", HighlightTarget = true };
step.Open(labelField, seriesRow, chart);

How to give a callout the look of a speech bubble or a thought bubble:

<tb:Callout target="npc" look="Talk" placement="Above" tip-size="18" text="Hello, traveler!" />
<tb:Callout target="hero" look="Thought" placement="Above" tip-size="28" text="I need a key." />

Talk gives the box round corners and a curved tail in place of the tip. Thought draws a cloud around the box and a tail of three circles that get smaller toward the target. The two looks use the background and the border of the box.

How to point a callout at an object of the 3D scene:

// A tag that follows an enemy on the screen, with lock-on brackets around it
var tag = new Callout { Title = "TARGET", Text = "Orc", TargetBox = CalloutTargetBox.Brackets, ClampToEdge = true };
tag.TargetRenderer(enemy.GetComponent<Renderer>());
tag.Open(hudRoot);

// A speech bubble over the head of an NPC
var talk = new Callout { Text = "Hello!", Look = CalloutLook.Talk, Placement = CalloutPlacement.Above };
talk.TargetWorld(npc.transform.Find("Head"));
talk.Open(hudRoot);

// A label at a point of the world
var label = new Callout { Text = "Exit", Connector = true, TipSize = 40 };
label.TargetWorldPosition(new Vector3(12, 3, 40));
label.Open(hudRoot);

The callout calculates the screen position of the target each frame. The element that you give to Open sets the workspace (or the panel) that the callout shows over. A callout declared in UXML can use Open() with no element.

When a camera draws into a render texture that an element shows, give the camera and that element:

tag.TargetRenderer(enemy.GetComponent<Renderer>(), minimapCamera, minimapView);
tag.Open();

The callout then maps the view of the camera to the element, and the edges of the element are the edges of the screen.

• The callout follows its target. When the user moves the window of the target, the callout moves with it.
• The tip slides along the edge of the box and turns to the center of the target. It has the background and the border of the box.
• The connector line and the frame follow the target and the callout. They hide while the target does not show, for example in a tab that is not selected, and they go away when the callout closes.
• The lines to MoreTargets show also when Connector is off, because the tip points at one target only. A line hides while its target does not show or the box covers it.
• The connector line starts at the point of the box edge that is nearest to the target, and ends on the edge of the target, not at its center.
• A drag starts after the pointer moves 4 px, so a click in the callout is still a click. A press on a control in the callout, such as a button or a text field, does not start a drag.
• A callout that the user dragged stays inside the workspace and does not go back to its target when the target moves. Its tip or its line still points at the target. Close and Open put it back at its declared placement.
• A callout is not modal. The user can work with the windows while it is open, and the workspace shortcuts work.
• A callout with controls gives the focus to its first control. A callout with only text leaves the focus where it is.
• Escape closes the callout that has the focus. A callout closes when its target leaves the panel, for example when its window closes.
• A callout declared in UXML stays hidden until Open. It moves to the workspace while it is open, then goes back to its place.
• The callout takes the classes of the nearest tb-style-scope above its UXML place, or above the target, as a MessageBox does.
• A 3D target moves with the frames of the game, so the callout calculates its place on each update of the panel. It does not allocate memory for this.
• A callout closes when its 3D object is destroyed. It hides while the object is not active, the renderer or the collider is off, or the viewport does not show.
• For a 3D target that is out of view, the callout gets the class tb-callout--out-of-view. Behind the camera, a clamped callout goes to the edge on the side that is the short turn to the target.
• The callout uses no editor API. It works in a built player.

Tips:

• Use one callout for a tutorial and change its Text and Target for each step. The user sees one bubble that moves.
• Give a popover close-on-outside-click="true". Leave it off for a hint that must stay while the user works.
• Use Toggle on the button that opens the callout, so a second click closes it. A press on the target does not count as a press outside.
• Keep the text short. The box is 320 px wide at most; change max-width on .tb-callout for a wider one.
• A Free callout with tip-size="0" is a plain floating note.
• Use alignment="Start" for a popover under a wide control, such as a search field, so the popover starts at the left edge of the control.
• Make a tutorial hint draggable, so the user can move it off the controls that it covers.
• A callout has no cursor for the drag. Tell the user in the text when the drag is important.
• Give a Thought callout a tip-size of 24 or more. The cloud uses 10 px of the tip, and the three circles need the rest.
• Use ClampToEdge for a quest marker or an enemy tag, so the player sees where to turn. Leave it off for a label that is only useful on the screen.
• Use TargetRenderer for a lock-on. TargetWorld points at the pivot of the object, which is often at its feet.
• An MDI window has an opaque background. To show a 3D target in a window, let a camera draw into a render texture and show it in an element. The CalloutDemo example does this in its 3D target tab.

#Styling

Set these USS variables on the callout to style the connector line and the target box:

.enemy-tag {
    --tb-callout-box-color: rgb(255, 196, 0);
    --tb-callout-box-width: 3;
    --tb-callout-box-corner: 20;
}

.tb-callout {
    --tb-callout-connector-color: var(--tb-color-warning);
    --tb-callout-connector-width: 3;
    --tb-callout-connector-cap: "arrow";
}
.tb-callout__highlight { border-width: 3px; border-radius: 0; }

To make every callout a yellow note with a thick border:

.tb-callout {
    background-color: #fff3b0;
    border-color: #c9a400;
    border-width: 2px;
    border-radius: 2px;
}
.tb-callout__text { color: #3b2f1e; }

Use an opaque background. The tip is drawn over the border of the box, and a transparent background shows the overlap.