{"record":{"id":"28cf7de113d52f6b","repo":"tui-cs/Terminal.Gui","slug":"popovers-must-have-viewportsettings-transparent-an","errorCode":null,"errorMessage":"Popovers must have ViewportSettings.Transparent and ViewportSettings.TransparentMouse set.","messagePattern":"Popovers must have ViewportSettings\\.Transparent and ViewportSettings\\.TransparentMouse set\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"Terminal.Gui/App/ApplicationPopover.cs","lineNumber":221,"sourceCode":"        if (popover is null)\n        {\n            return;\n        }\n\n        // Validation requires View cast (ViewportSettings, KeyBindings, BeginInit/EndInit)\n        if (popover is View newPopover)\n        {\n            if (!newPopover.IsInitialized)\n            {\n                newPopover.App = App;\n                newPopover.BeginInit ();\n                newPopover.EndInit ();\n            }\n\n            if (!(newPopover.ViewportSettings.FastHasFlags (ViewportSettingsFlags.Transparent)\n                  && newPopover.ViewportSettings.FastHasFlags (ViewportSettingsFlags.TransparentMouse)))\n            {\n                throw new InvalidOperationException (\"Popovers must have ViewportSettings.Transparent and ViewportSettings.TransparentMouse set.\");\n            }\n\n            if (newPopover.KeyBindings.GetFirstFromCommands (Command.Quit) is null)\n            {\n                throw new InvalidOperationException (\"Popovers must have a key binding for Command.Quit.\");\n            }\n        }\n\n        _activePopover = popover;\n        popover.Enabled = true;\n        popover.Visible = true;\n    }\n\n    /// <summary>\n    ///     INTERNAL: Called when the user presses a key. Dispatches the key to the active popover, if any,\n    ///     otherwise to the popovers in the order they were registered. Inactive popovers only get hotkeys.\n    /// </summary>\n    /// <param name=\"key\"></param>","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/tui-cs/Terminal.Gui/blob/2e47b11478db083499917f2ad27c34d30efb0df1/Terminal.Gui/App/ApplicationPopover.cs#L203-L239","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set both flags on the popover before registering/showing: popover.ViewportSettings |= ViewportSettingsFlags.Transparent | ViewportSettingsFlags.TransparentMouse;.","Use the built-in PopoverMenu / Tooltip views which already set the required flags.","Configure the flags in the popover's constructor so callers cannot forget them."],"exampleFix":"// before\nvar popover = new View { /* ... */ };\napp.Popovers.Register (popover);\napp.Popovers.Show (popover); // throws\n\n// after\nvar popover = new View { /* ... */ };\npopover.ViewportSettings |= ViewportSettingsFlags.Transparent | ViewportSettingsFlags.TransparentMouse;\napp.Popovers.Register (popover);\napp.Popovers.Show (popover);","handlingStrategy":"validation","validationCode":"popover.ViewportSettings |= ViewportSettingsFlags.Transparent | ViewportSettingsFlags.TransparentMouse;\napp.Popovers.Show (popover);","typeGuard":"static bool HasPopoverFlags (View v) =>\n    v.ViewportSettings.FastHasFlags (ViewportSettingsFlags.Transparent)\n    && v.ViewportSettings.FastHasFlags (ViewportSettingsFlags.TransparentMouse);","tryCatchPattern":null,"preventionTips":["Set both Transparent and TransparentMouse in the popover's constructor.","Prefer built-in popover views (PopoverMenu, etc.) that set the flags for you.","Do not override ViewportSettings on a registered popover without re-applying the flags."],"tags":["popover","viewport","configuration"],"backgroundTag":null,"analyzedSha":"2e47b11478db083499917f2ad27c34d30efb0df1","analyzedAt":"2026-08-13T19:20:08.826Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}