Dialogs & flyouts
Popup
A floating surface positioned over app content.
Example
Usage
A popup beside a button
Show a short note next to the button that opens it.
#include <FluentQt/DialogsFlyouts.h>
using namespace fluent::dialogs_flyouts;
auto* root = new QWidget(this);
auto* layout = new QVBoxLayout(root);
auto* open = new Button(QStringLiteral("Show quick note"), root);
open->setFluentStyle(Button::Accent);
layout->addWidget(open, 0, Qt::AlignLeft);
QObject::connect(open, &Button::clicked, root, [open] {
auto* popup = new Popup(open->window());
popup->setThemeSource(open);
auto* content = new QVBoxLayout(popup);
content->setContentsMargins(24, 22, 24, 22);
auto* title = new Label(QStringLiteral("Quick note"), popup);
title->setFluentTypography(Typography::FontRole::BodyStrong);
content->addWidget(title);
auto* text = new Label(QStringLiteral("Click outside or press Escape to close."), popup);
content->addWidget(text);
popup->setPosition(open, QPoint(0, open->height() + 8));
QObject::connect(popup, &Popup::closed, popup, &QObject::deleteLater);
popup->open();
});
return root;import fluentqt
from PySide6.QtCore import QPoint, Qt
from PySide6.QtWidgets import QVBoxLayout
open_button = fluentqt.Button('Show quick note')
open_button.setFluentStyle(fluentqt.Button.ButtonStyle.Accent)
layout.addWidget(open_button, 0, Qt.AlignmentFlag.AlignLeft)
def show_note():
popup = fluentqt.Popup(open_button.window())
popup.setThemeSource(open_button)
content = QVBoxLayout(popup)
content.setContentsMargins(24, 22, 24, 22)
title = fluentqt.Label('Quick note', popup)
title.setFluentTypography(fluentqt.FontRole.BodyStrong)
content.addWidget(title)
text = fluentqt.Label('Click outside or press Escape to close.', popup)
content.addWidget(text)
popup.setPosition(open_button, QPoint(0, open_button.height() + 8))
popup.closed.connect(popup.deleteLater)
popup.open()
open_button.clicked.connect(show_note)API
DeclarationNo matching API members.
fluent::dialogs_flyouts::Popup
Inherits QWidget · FluentElement · QMLPlus
Base same-window popup surface with open state and close policy control.
Constructors
Properties
bool isOpenLogical requested open state, not animation-complete or QWidget visibility.
ReadisOpen()WritesetIsOpen()NotifyisOpenChanged()ClosePolicy closePolicyPolicy controlling outside-click, escape, or programmatic close behavior.
ReadclosePolicy()WritesetClosePolicy()NotifyclosePolicyChanged()bool modalWhether the overlay blocks interaction outside itself.
ReadisModal()WritesetModal()NotifymodalChanged()bool dimWhether a dim/scrim layer is shown behind the overlay.
ReadisDim()WritesetDim()NotifydimChanged()double dimOpacityScrim opacity in [0, 1]; -1 uses the theme smoke token. Only applies when dim is enabled.
ReaddimOpacity()WritesetDimOpacity()NotifydimOpacityChanged()double backdropBlurRadiusCached content-backdrop blur radius in logical pixels [0, 32]; 0 disables blur. Defaults to 4 for modal surfaces and 0 otherwise until explicitly set. Explicit values, including 0, persist across modality changes.
ReadbackdropBlurRadius()WritesetBackdropBlurRadius()NotifybackdropBlurRadiusChanged()bool animationEnabledWhether popup open/close transitions are animated.
ReadisAnimationEnabled()WritesetAnimationEnabled()NotifyanimationEnabledChanged()double popupProgressPopup open/close animation progress.
ReadpopupProgress()WritesetPopupProgress()NotifypopupProgressChanged()
Methods
bool isOpen() constLogical requested open state, not animation-complete or QWidget visibility.
ClosePolicy closePolicy() constPolicy controlling outside-click, escape, or programmatic close behavior.
void setClosePolicy(ClosePolicy p)Policy controlling outside-click, escape, or programmatic close behavior.
bool isModal() constWhether the overlay blocks interaction outside itself.
void setModal(bool m)Whether the overlay blocks interaction outside itself.
bool lightDismissConsumesPress() constWhen true, a CloseOnPressOutside light-dismiss SWALLOWS the dismissing press instead of letting it fall through to whatever is underneath — ComboBox-dropdown semantics (one click only closes the popup; it does not also activate the control beneath). Default false keeps the menu-style behaviour where the dismiss click still hits its target.
void addLightDismissPassthrough(QWidget* widget)Regions exempt from the consume above: a dismissing press that lands inside one of these widgets still falls through to it, so a sibling toolbar / nav bar stays one-click reachable while the popup closes. Only meaningful together with lightDismissConsumesPress.
bool isDim() constWhether a dim/scrim layer is shown behind the overlay.
void setDim(bool d)Whether a dim/scrim layer is shown behind the overlay.
double dimOpacity() constScrim opacity in [0, 1]; -1 uses the theme smoke token. Only applies when dim is enabled.
void setDimOpacity(double opacity)Scrim opacity in [0, 1]; -1 uses the theme smoke token. Only applies when dim is enabled.
double backdropBlurRadius() constCached content-backdrop blur radius in logical pixels [0, 32]; 0 disables blur. Defaults to 4 for modal surfaces and 0 otherwise until explicitly set. Explicit values, including 0, persist across modality changes.
void setBackdropBlurRadius(double radius)Cached content-backdrop blur radius in logical pixels [0, 32]; 0 disables blur. Defaults to 4 for modal surfaces and 0 otherwise until explicitly set. Explicit values, including 0, persist across modality changes.
bool isAnimationEnabled() constWhether popup open/close transitions are animated.
void setAnimationEnabled(bool e)Whether popup open/close transitions are animated.
bool isExitAnimationEnabled() constWhen false, close() skips the exit (fade-out) animation and hides instantly; the open/enter animation is unaffected. Lets a caller drop just the dismissal animation for a specific popup without touching the shared default — e.g. when the opacity-effect fade-out misbehaves over a native vibrancy backdrop on macOS.
void setThemeSource(QWidget* source)Uses a widget as the local theme source when no anchor drives the popup.
double popupProgress() constPopup open/close animation progress.
void setPopupProgress(double p)Popup open/close animation progress.
void setPosition(QWidget* relativeTo, const QPoint& localPos)Positions the popup's top-left in the given widget's local coordinates; with relativeTo == topLevelWidget this is window-relative. Coordinates reference the visible card corner; open() compensates the shadow margin. While open, the popup follows relativeTo and closes when it is fully clipped. Without a call, open() centers the popup.
void setIsOpen(bool open)Logical requested open state, not animation-complete or QWidget visibility.
void refreshBackdrop()Refreshes the cached backdrop after application content changes behind an open popup.
void closeWithReason(CloseReason reason)Closes with an explicit reason; close() uses Programmatic unless a reason is pending.
Signals
void isOpenChanged(bool open)Logical requested open state, not animation-complete or QWidget visibility.
void opening()Opening transition started. Compatibility alias: aboutToShow().
void closing(CloseReason reason)Closing transition started. aboutToHide() is the parameterless compatibility alias.
void popupProgressChanged(double progress)Popup open/close animation progress.
void closePolicyChanged(ClosePolicy policy)Policy controlling outside-click, escape, or programmatic close behavior.
void modalChanged(bool modal)Whether the overlay blocks interaction outside itself.
void dimChanged(bool dim)Whether a dim/scrim layer is shown behind the overlay.
void dimOpacityChanged(double opacity)Scrim opacity in [0, 1]; -1 uses the theme smoke token. Only applies when dim is enabled.
void backdropBlurRadiusChanged(double radius)Cached content-backdrop blur radius in logical pixels [0, 32]; 0 disables blur. Defaults to 4 for modal surfaces and 0 otherwise until explicitly set. Explicit values, including 0, persist across modality changes.
void animationEnabledChanged(bool enabled)Whether popup open/close transitions are animated.
Enumerations
enum CloseFlagNoAutoClose = 0CloseOnPressOutside = 1 << 0CloseOnEscape = 1 << 1
enum CloseReasonWhy an overlay closed.
Programmatic = 0ActionButton = 1CloseButton = 2LightDismiss = 3TargetDestroyed = 4Escape = 5
Types and aliases
Destructors
Subclass interfaces
Methods
virtual QPoint computePosition() constSubclasses may override the open()-time placement (Flyout does).
virtual QWidget* automaticPositionAnchor() constReturns the widget that drives automatic placement, if any.
virtual bool shouldDismissOnOutsidePress(const QPoint& globalPos) constAllows subclasses to exclude trigger regions from outside-press dismissal.
void setFocusOnOpenEnabled(bool enabled)Controls whether open() moves keyboard focus into the popup.
void setPendingCloseReason(CloseReason reason)Records a close reason used by the next close() if none is passed explicitly.
Inherited from fluent::FluentElement
Methods
static void setTheme(Theme theme)Updates the global theme and notifies active FluentElement instances.
static void setThemeDeferred(Theme theme)Schedules a visible-first batched theme refresh without blocking the current interaction.
static Theme currentTheme()Returns the currently active global theme.
static bool themeUsesDarkAppearance(Theme theme)Returns whether a theme uses dark-backed chrome and material tokens.
static void refreshTheme()Re-broadcasts the current theme to repaint after a design-token change.
static int themeGeneration()Monotonic counter bumped on every theme change, for staleness checks.
Theme effectiveTheme() constResolves the theme used by this element, honoring an inherited QWidget override.
bool effectiveThemeUsesDarkAppearance() constReturns whether this element's effective theme uses dark-backed chrome.
bool setThemeOverrides(const QJsonObject& overrides)Component-facing token accessors.
QJsonObject themeOverrides() constReturns this element's authored overrides.
void clearThemeOverrides()Restores all token fields to global theme defaults.
const Colors& themeColorsRef() constNon-copying access to the active color set (for hot paint paths).
Material::AcrylicToken themeAcrylic() constMaterial, elevation, and adaptive layout tokens.
QColor themeBackdrop(bool active) constWindow-chrome backdrop color for the given activation state.
virtual void onThemeUpdated()Called after the global theme changes.
Enumerations
enum ThemeGlobal visual theme used when resolving design tokens.
Light = 0Dark = 1HighContrast = 2
Types and aliases
struct ColorsDesign token snapshots returned to components.
Inherited from fluent::QMLPlus
Methods
AnchorLayout::Anchors* anchors()Returns mutable anchors for the QWidget host.
void setState(const QString& name)Applies a named state, or clears state when name is empty.
void addState(const QMLState& state)Registers or replaces a named state definition.
void evaluateStates()Reevaluates conditions; the first registered true condition wins.
QMLPlusRuntime* runtime()Returns the lazy host-owned state observation object.
void setAnchors(const AnchorLayout::Anchors& anchors)Replaces all host anchors and invalidates the parent layout.
void resetAnchors()Clears all host anchors and invalidates the parent layout.
void bind(const char* targetProp, QObject* source, const char* sourceProp, PropertyBinder::Direction dir = PropertyBinder::OneWay)Binds a source property to a property on the QWidget host.
BindingHandle bindManaged(const char* targetProp, QObject* source, const char* sourceProp, PropertyBinder::Direction direction = PropertyBinder::OneWay, BindingOptions options = {})Installs a managed direct binding on this QWidget host.
BindingHandle bindComputed(const char* targetProp, const QVector<BindingDependency>& dependencies, std::function<QVariant()> evaluate, BindingOptions options = {})Installs an explicit-dependency C++ expression on this QWidget host.
void addTransition(const StateTransition& transition)Registers a state transition in precedence order.
void setBehavior(const char* propertyName, const PropertyAnimation& animation)Sets the default animation for this host's managed property writes.
void clearBehavior(const char* propertyName)Removes the default animation for future managed writes.
bool writeProperty(const char* propertyName, const QVariant& value)Writes a host property through Behavior without removing its binding.
All inherited Qt members：QWidget