Skip to content
Haiku OSDeep Dive Published Updated 4 min readViews unavailable

Haiku BView Tooltips: Use the Public Text API, Avoid Private BToolTip Dependencies

Add, refresh, and clear ordinary Haiku view tooltips through BView::SetToolTip(const char*) without depending on the private BToolTip class.

For a normal text tooltip, use BView::SetToolTip(const char*). It is the small, supported Interface Kit surface: attach explanatory text to the view, update that text when the view’s state changes, and clear it when there is nothing useful to explain. Haiku’s BView implementation handles the ordinary idle-hover path; application code does not need to construct a tooltip window or intercept pointer messages just to show a label.

The advanced BToolTip class is a different boundary. Haiku’s own tooltip documentation calls it private, warns that it may change before release, and directs ordinary cases to BView::SetToolTip(). The public View.h also declares overloads that accept BToolTip*, but that declaration does not turn the private class and its private header into a stable application API. For maintainable app code, do not include <private/interface/ToolTip.h>, instantiate BTextToolTip, or subclass BToolTip merely to customize a string label.

Set text on the view that owns the explanation

Set the tooltip on the specific control or view whose action needs explanation. For a button, keep the action message short and describe the result rather than repeating its label:

BButton* saveButton = new BButton(
    "save",
    "Save",
    new BMessage(kSaveDocument));

saveButton->SetToolTip("Save the current document.");

This is a text tooltip, not a rich-text or custom-view API. It stays attached to that BView and participates in the view’s normal tooltip lookup when the pointer idles over it. You generally should not call ShowToolTip() in MouseMoved() or implement a custom idle timer for this case; doing so duplicates framework behavior and introduces another lifecycle to manage.

Refresh or clear it with the same public call

Tooltip text should describe current state. If an action is temporarily unavailable, say what condition is blocking it; when the state changes, update the same view rather than replacing its tooltip implementation.

void SavePanel::UpdateSaveHint()
{
    if (fSaving) {
        fSaveButton->SetToolTip(
            "A save is already in progress. Wait for it to finish.");
    } else if (fValidationFailed) {
        fSaveButton->SetToolTip(
            "Fix the highlighted fields before saving.");
    } else {
        fSaveButton->SetToolTip("Save the current document.");
    }
}

When the view no longer needs an explanation, clear the text through the same API:

fSaveButton->SetToolTip("");

At the pinned implementation, an empty string clears the tooltip; for non-empty text, BView updates its existing text-tooltip object when possible or creates a text tooltip otherwise. Do not pass a bare NULL: the public header also declares a BToolTip* overload, so that call is ambiguous. Code depending on implementation details should still use only the supported text method. The safe ownership rule is simple: pass a valid C string for the call and let the view manage its tooltip state; do not keep a pointer to an internal tooltip object.

Keep custom tooltip UI out of the private class

The private BToolTip API exists for advanced custom contents or behavior, but Haiku explicitly marks it as private and potentially changeable. This is a source-compatibility and lifecycle warning, not just a suggestion that custom tooltips are visually discouraged. Building against the private header can make an app depend on implementation details that are not promised to remain stable across Haiku revisions.

If a product requirement truly needs interactive or richly structured help, design that experience as an application-owned view or window using supported Interface Kit APIs, with its own clear attachment, dismissal, focus, and accessibility rules. Do not smuggle that feature into SetToolTip(const char*) or assume BToolTip is a general-purpose public extension point.

For a simple label, test the actual user interaction: hover over the owning view, move away, disable the control, and update or clear the hint after its state changes. Keep the copy useful without making hover the only place where critical instructions or errors appear. Tooltips supplement the visible interface; they should not carry essential information that keyboard, touchpad, or assistive-technology users cannot otherwise discover.

Related:

Sources:

Comments