tui-cs/Terminal.Gui · error · InvalidOperationException

Popovers must have ViewportSettings.Transparent and Viewport

Error message

Popovers must have ViewportSettings.Transparent and ViewportSettings.TransparentMouse set.

What it means

Thrown by ApplicationPopover.Show when the popover (as a View) does not have both ViewportSettingsFlags.Transparent and ViewportSettingsFlags.TransparentMouse set. Popovers render over the content beneath them and must let mouse/visual transparency pass through correctly so underlying views receive events outside the popover's bounds. The check uses ViewportSettings.FastHasFlags for both flags.

Source

Thrown at Terminal.Gui/App/ApplicationPopover.cs:221

        if (popover is null)
        {
            return;
        }

        // Validation requires View cast (ViewportSettings, KeyBindings, BeginInit/EndInit)
        if (popover is View newPopover)
        {
            if (!newPopover.IsInitialized)
            {
                newPopover.App = App;
                newPopover.BeginInit ();
                newPopover.EndInit ();
            }

            if (!(newPopover.ViewportSettings.FastHasFlags (ViewportSettingsFlags.Transparent)
                  && newPopover.ViewportSettings.FastHasFlags (ViewportSettingsFlags.TransparentMouse)))
            {
                throw new InvalidOperationException ("Popovers must have ViewportSettings.Transparent and ViewportSettings.TransparentMouse set.");
            }

            if (newPopover.KeyBindings.GetFirstFromCommands (Command.Quit) is null)
            {
                throw new InvalidOperationException ("Popovers must have a key binding for Command.Quit.");
            }
        }

        _activePopover = popover;
        popover.Enabled = true;
        popover.Visible = true;
    }

    /// <summary>
    ///     INTERNAL: Called when the user presses a key. Dispatches the key to the active popover, if any,
    ///     otherwise to the popovers in the order they were registered. Inactive popovers only get hotkeys.
    /// </summary>
    /// <param name="key"></param>

View on GitHub (pinned to 2e47b11478)

Solutions

1. Set both flags on the popover before registering/showing: popover.ViewportSettings |= ViewportSettingsFlags.Transparent | ViewportSettingsFlags.TransparentMouse;.
2. Use the built-in PopoverMenu / Tooltip views which already set the required flags.
3. Configure the flags in the popover's constructor so callers cannot forget them.

Example fix

// before
var popover = new View { /* ... */ };
app.Popovers.Register (popover);
app.Popovers.Show (popover); // throws

// after
var popover = new View { /* ... */ };
popover.ViewportSettings |= ViewportSettingsFlags.Transparent | ViewportSettingsFlags.TransparentMouse;
app.Popovers.Register (popover);
app.Popovers.Show (popover);

popover.ViewportSettings |= ViewportSettingsFlags.Transparent | ViewportSettingsFlags.TransparentMouse;
app.Popovers.Show (popover);

static bool HasPopoverFlags (View v) =>
    v.ViewportSettings.FastHasFlags (ViewportSettingsFlags.Transparent)
    && v.ViewportSettings.FastHasFlags (ViewportSettingsFlags.TransparentMouse);

When it happens

Trigger: Constructing a popover View and calling Show without setting ViewportSettings to include Transparent | TransparentMouse; subclassing a view for use as a popover and forgetting the required flags; a config that overrides ViewportSettings.

Common situations: Custom popover implementations (autocomplete, tooltips, menus) that omit the transparency flags; migrating a v1 floating view to a v2 popover without setting the flags; view templates that reset ViewportSettings.

Related errors

• Popovers must be registered before being shown.
• {propertyName}: Unexpected token when parsing Attribute: {re
• {propertyName}: Expected a string value.
• Expected a valid text style value.
• {propertyName}: Unknown Attribute property .

AI-assisted analysis of tui-cs/Terminal.Gui@2e47b11478 (2026-08-13). Data as JSON: /api/errors/28cf7de113d52f6b. Report an issue: GitHub.