Fluent-Qt

Menus & toolbars

CommandPalette

Find and run an action by typing its name. Use the keyboard to choose a result and press Enter to execute it.

Example

CommandPalette: Find and run a command

Usage

Find and run a command

Search a page name, choose with the arrow keys, and press Enter. Escape closes the palette.

#include <FluentQt/MenusToolbars.h>
using namespace fluent::menus_toolbars;

auto* root = new QWidget(this);
auto* layout = new QVBoxLayout(root);
auto* location = new Label(QStringLiteral("Current page: Home"), root);
location->setObjectName(QStringLiteral("Gallery.CommandPalette.BasicLocation"));
auto* palette = new fluent::menus_toolbars::CommandPalette(root);
palette->setObjectName(QStringLiteral("Gallery.CommandPalette.Basic"));
palette->setPlaceholderText(QStringLiteral("Search pages..."));
const QStringList pages{QStringLiteral("Home"), QStringLiteral("Inbox"),
    QStringLiteral("Documents"), QStringLiteral("Folders")};
for (const QString& page : pages) {
    auto* action = new QAction(page, root);
    palette->addCommand(action, QStringLiteral("Navigation"));
    QObject::connect(action, &QAction::triggered, location, [location, page] {
        location->setText(QStringLiteral("Current page: %1").arg(page));
    });
}
auto* open = new Button(QStringLiteral("Search pages"), root);
open->setObjectName(QStringLiteral("Gallery.CommandPalette.OpenBasic"));
open->setFluentStyle(Button::Accent);
QObject::connect(open, &Button::clicked, palette, &fluent::menus_toolbars::CommandPalette::open);
layout->addWidget(open, 0, Qt::AlignLeft);
layout->addWidget(location);
return root;

API

Declaration

fluent::menus_toolbars::CommandPalette

Inherits dialogs_flyouts::Popup

Searchable same-window presentation of borrowed application actions.

Constructors

Properties

QString query
Read query()Write setQuery()Notify queryChanged()
QString placeholderText
Read placeholderText()Write setPlaceholderText()Notify placeholderTextChanged()
QString emptyText
Read emptyText()Write setEmptyText()Notify emptyTextChanged()
int resultCount
Read resultCount()Notify resultCountChanged()
QAction* currentAction
Read currentAction()Write setCurrentAction()Notify currentActionChanged()

Methods

bool removeCommand(QAction* action)

Removes a command without deleting or reparenting its action.

void clearCommands()

Removes all registrations without deleting their actions.

QString placeholderText() const
void setPlaceholderText(const QString& text)
QString emptyText() const
void setEmptyText(const QString& text)
bool triggerCurrent()

Closes and restores focus before executing the current enabled leaf.

Signals

void placeholderTextChanged(const QString& text)
void emptyTextChanged(const QString& text)

Destructors

Subclass interfaces

Methods

Inherited from fluent::dialogs_flyouts::Popup

Properties

bool isOpen

Logical requested open state, not animation-complete or QWidget visibility.

Read isOpen()Write setIsOpen()Notify isOpenChanged()
ClosePolicy closePolicy

Policy controlling outside-click, escape, or programmatic close behavior.

Read closePolicy()Write setClosePolicy()Notify closePolicyChanged()
bool modal

Whether the overlay blocks interaction outside itself.

Read isModal()Write setModal()Notify modalChanged()
bool dim

Whether a dim/scrim layer is shown behind the overlay.

Read isDim()Write setDim()Notify dimChanged()
double dimOpacity

Scrim opacity in [0, 1]; -1 uses the theme smoke token. Only applies when dim is enabled.

Read dimOpacity()Write setDimOpacity()Notify dimOpacityChanged()
double backdropBlurRadius

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.

Read backdropBlurRadius()Write setBackdropBlurRadius()Notify backdropBlurRadiusChanged()
bool animationEnabled

Whether popup open/close transitions are animated.

Read isAnimationEnabled()Write setAnimationEnabled()Notify animationEnabledChanged()
double popupProgress

Popup open/close animation progress.

Read popupProgress()Write setPopupProgress()Notify popupProgressChanged()

Methods

bool isOpen() const

Logical requested open state, not animation-complete or QWidget visibility.

ClosePolicy closePolicy() const

Policy controlling outside-click, escape, or programmatic close behavior.

void setClosePolicy(ClosePolicy p)

Policy controlling outside-click, escape, or programmatic close behavior.

bool isModal() const

Whether the overlay blocks interaction outside itself.

void setModal(bool m)

Whether the overlay blocks interaction outside itself.

bool lightDismissConsumesPress() const

When 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() const

Whether 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() const

Scrim 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() const

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 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() const

Whether popup open/close transitions are animated.

void setAnimationEnabled(bool e)

Whether popup open/close transitions are animated.

bool isExitAnimationEnabled() const

When 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() const

Popup 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 CloseFlag
  • NoAutoClose = 0
  • CloseOnPressOutside = 1 << 0
  • CloseOnEscape = 1 << 1
enum CloseReason

Why an overlay closed.

  • Programmatic = 0
  • ActionButton = 1
  • CloseButton = 2
  • LightDismiss = 3
  • TargetDestroyed = 4
  • Escape = 5

Types and aliases

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() const

Resolves the theme used by this element, honoring an inherited QWidget override.

bool effectiveThemeUsesDarkAppearance() const

Returns whether this element's effective theme uses dark-backed chrome.

QJsonObject themeOverrides() const

Returns this element's authored overrides.

void clearThemeOverrides()

Restores all token fields to global theme defaults.

const Colors& themeColorsRef() const

Non-copying access to the active color set (for hot paint paths).

Material::AcrylicToken themeAcrylic() const

Material, elevation, and adaptive layout tokens.

QColor themeBackdrop(bool active) const

Window-chrome backdrop color for the given activation state.

virtual void onThemeUpdated()

Called after the global theme changes.

Enumerations

enum Theme

Global visual theme used when resolving design tokens.

  • Light = 0
  • Dark = 1
  • HighContrast = 2

Types and aliases

struct Colors

Design 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 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