Windowing

TitleBar

A custom window title bar with drag regions and themed chrome.

Example

Usage

Content respects system regions

Place custom content in TitleBar while preserving macOS leading controls or Windows trailing caption buttons.

#include <FluentQt/Windowing.h>
using namespace fluent::windowing;

auto* titleBar = new TitleBar(this);
// macOS reserves leading traffic-light controls;
// Windows reserves trailing caption buttons.
titleBar->setSystemReservedLeadingWidth(platformLeadingWidth);
titleBar->setSystemReservedTrailingWidth(platformTrailingWidth);

auto* content = new QWidget(titleBar);
auto* layout = new QHBoxLayout(content);
layout->addWidget(titleLabel);
layout->addWidget(searchBox);
layout->addWidget(shareButton);

titleBar->setContentWidget(content);

import fluentqt

from PySide6.QtWidgets import QHBoxLayout, QWidget

title_bar = fluentqt.TitleBar()
title_bar.setSystemReservedLeadingWidth(platform_leading_width)
title_bar.setSystemReservedTrailingWidth(platform_trailing_width)

content = QWidget(title_bar)
layout = QHBoxLayout(content)
layout.addWidget(title_label)
layout.addWidget(search_box)
layout.addWidget(share_button)
title_bar.setContentWidget(content)

API

Declaration

`fluent::windowing::TitleBar`

Inherits QWidget · FluentElement · QMLPlus

Custom title bar container with reserved system button regions.

Constructors

explicit TitleBar(QWidget* parent = nullptr)

Properties

QWidget* contentWidget: Caller-owned widget hosted as component content.
Read contentWidget()Write setContentWidget()Notify contentWidgetChanged()
int systemReservedLeadingWidth: Leading width reserved for platform window controls.
Read systemReservedLeadingWidth()Write setSystemReservedLeadingWidth()Notify systemReservedLeadingWidthChanged()
int systemReservedTrailingWidth: Trailing width reserved for platform window controls.
Read systemReservedTrailingWidth()Write setSystemReservedTrailingWidth()Notify systemReservedTrailingWidthChanged()
int titleBarHeight: Title bar height in pixels.
Read titleBarHeight()Write setTitleBarHeight()Notify titleBarHeightChanged()
bool windowActive: Whether the owning top-level window is currently active.
Read isWindowActive()Notify windowActiveChanged()

Methods

static constexpr int defaultTitleBarHeight()
QWidget* contentHost() const
QWidget* contentWidget() const: Caller-owned widget hosted as component content.
void setContentWidget(QWidget* widget): Caller-owned widget hosted as component content.
int systemReservedLeadingWidth() const: Leading width reserved for platform window controls.
void setSystemReservedLeadingWidth(int width): Leading width reserved for platform window controls.
int systemReservedTrailingWidth() const: Trailing width reserved for platform window controls.
void setSystemReservedTrailingWidth(int width): Trailing width reserved for platform window controls.
int titleBarHeight() const: Title bar height in pixels.
void setTitleBarHeight(int height): Title bar height in pixels.
bool isWindowActive() const: Whether the owning top-level window is currently active.
QVector<QRect> dragExclusionRects() const
void refreshChromeExclusions(): Re-publishes the drag-exclusion (native hit-test) regions to the window.
QSize sizeHint() const override
QSize minimumSizeHint() const override
void onThemeUpdated() override

Signals

void contentWidgetChanged(QWidget* widget): Caller-owned widget hosted as component content.
void systemReservedLeadingWidthChanged(int width): Leading width reserved for platform window controls.
void systemReservedTrailingWidthChanged(int width): Trailing width reserved for platform window controls.
void titleBarHeightChanged(int height): Title bar height in pixels.
void windowActiveChanged(bool active): Whether the owning top-level window is currently active.
void dragStarted(const QPoint& globalPos)
void dragMoved(const QPoint& globalPos)
void dragFinished()
void doubleClicked(const QPoint& globalPos)
void contextMenuRequested(const QPoint& globalPos)
void chromeGeometryChanged()

Subclass interfaces

Methods

bool event(QEvent* event) override
void paintEvent(QPaintEvent* event) override
void resizeEvent(QResizeEvent* event) override
void mousePressEvent(QMouseEvent* event) override
void mouseDoubleClickEvent(QMouseEvent* event) override
void mouseMoveEvent(QMouseEvent* event) override
void mouseReleaseEvent(QMouseEvent* event) override

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.
bool setThemeOverrides(const QJsonObject& overrides): Component-facing token accessors.
QJsonObject themeOverrides() const: Returns this element's authored overrides.
void clearThemeOverrides(): Restores all token fields to global theme defaults.
Colors themeColors() const
const Colors& themeColorsRef() const: Non-copying access to the active color set (for hot paint paths).
FontStyle themeFont(Typography::FontRole role = Typography::FontRole::Body) const
Radius themeRadius() const
Spacing themeSpacing() const
Animation themeAnimation() const
Material::AcrylicToken themeAcrylic() const: Material, elevation, and adaptive layout tokens.
Material::MicaToken themeMica() const
Material::SmokeToken themeSmoke() const
Elevation::ShadowParams themeShadow(Elevation::Level level) const
int themeBreakpoint(Breakpoints::Breakpoint breakpoint = Breakpoints::Breakpoint::Medium) const
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.
struct FontStyle
struct Radius
struct Spacing
struct Animation

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.
QString state() const
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