Fluent-Qt

3D-Perspektive (Spatial)

SpatialView Räumliche Ansicht

Verleiht vorhandenen Widgets eine 3D-Perspektive mit zeigerabhängiger Neigung. Texteingaben und Popups sollten im normalen Layout bleiben; native Fenster und OpenGL-Kindelemente lassen sich nicht einbetten.

Beispiel

SpatialView Räumliche Ansicht: Szenenperspektive

Verwendung

Szenenperspektive

Kamera und Zoom anpassen und den Zeiger über die Karten bewegen.

#include <FluentQt/Spatial.h>
using namespace fluent::spatial;

using namespace fluent;
// The two cards keep their own poses while the view changes the whole scene.
class SceneView final : public spatial::SpatialView {
public:
    using SpatialView::SpatialView;
    void arrange()
    {
        if (itemCount() != 2)
            return;
        const float spread = width() < 650 ? 24 : 100;
        items().first()->setPosition(QVector3D(-spread, -44, -160));
        items().last()->setPosition(QVector3D(spread, 44, 160));
    }
protected:
    void resizeEvent(QResizeEvent* event) override
    {
        SpatialView::resizeEvent(event);
        arrange();
    }
};
auto* panel = new SpatialPreviewPanel(parent);
auto* column = new QVBoxLayout(panel);
column->setContentsMargins(0, 0, 0, 0);
column->setSpacing(16);
auto* session = new spatial::SpatialSession(panel, panel);
const bool active = session->activate();
auto* view = new SceneView(panel);
if (!active || !session->attachView(view)) {
    view->setSpatialEnabled(false);
    view->setRenderMode(spatial::SpatialView::RenderMode::Raster);
}
view->setObjectName("spatialPreviewView");
view->setFixedHeight(400);
view->setCameraDistance(1200);
view->setZoom(0.9);
view->setMaximumTilt(QPointF(6, 12));
// Response time (140 ms), animation limit (60 fps), cache and Auto renderer use UILib defaults.
// See SpatialView.h for the full parameter contract.

// Both layers use the same size and data, making perspective easy to compare.
const auto makeLayer = [](const QString& title, const QString& caption) {
    auto* card = new layout::Card;
    card->setFixedSize(220, 150);
    auto* content = new QVBoxLayout(card);
    content->setContentsMargins(16, 12, 16, 12);
    content->setSpacing(6);
    auto* heading = new textfields::Label(title, card);
    heading->setFluentTypography(Typography::FontRole::Subtitle);
    heading->setTextColorRole(textfields::Label::TextColorRole::Primary);
    content->addWidget(heading);
    auto* chart = new charts::Sparkline(card);
    chart->setAccessibleName(title + " sample chart");
    auto* model = new charts::ChartModel(card);
    model->setPoints({{0, 12}, {1, 24}, {2, 18}, {3, 38}, {4, 32}, {5, 54}});
    chart->setModel(model);
    content->addWidget(chart, 1);
    auto* note = new textfields::Label(caption, card);
    note->setTextColorRole(textfields::Label::TextColorRole::Secondary);
    content->addWidget(note);
    return card;
};
spatial::SpatialItem* back = view->addWidget(
    makeLayer("Back layer", "Z -160 · sample data"), WidgetOwnership::Owned);
spatial::SpatialItem* front = view->addWidget(
    makeLayer("Front layer", "Z +160 · sample data"), WidgetOwnership::Owned);
back->setRotation(QVector3D(6, 16, 0));
front->setRotation(QVector3D(-6, -16, 0));
back->setSurfaceIntensity(0.75);
front->setSurfaceIntensity(0.75);
view->arrange();

auto* toolbar = new QHBoxLayout;
auto* follow = new basicinput::ToggleSwitch(panel);
follow->setObjectName("spatialViewFollow");
follow->setAccessibleName("Follow pointer");
follow->setOnContent("Follow pointer");
follow->setOffContent("Follow pointer");
follow->setIsOn(true);
toolbar->addWidget(follow);
toolbar->addStretch();
column->addLayout(toolbar);
column->addWidget(view);

// Keep view-wide controls outside the projection so their drag targets stay still.
auto* controls = new QWidget(panel);
controls->setObjectName("spatialViewControls");
auto* grid = new QGridLayout(controls);
grid->setContentsMargins(0, 0, 0, 0);
grid->setHorizontalSpacing(24);
grid->setVerticalSpacing(12);
grid->setColumnStretch(0, 1);
grid->setColumnStretch(1, 1);
const auto addSlider = [controls, grid](const QString& name, const QString& label,
                                      const QString& unit, int minimum, int maximum,
                                      int initial, int row, int col) {
    auto* group = new QWidget(controls);
    auto* layout = new QVBoxLayout(group);
    layout->setContentsMargins(0, 0, 0, 0);
    layout->setSpacing(4);
    auto* text = new textfields::Label(group);
    text->setTextColorRole(textfields::Label::TextColorRole::Primary);
    auto* slider = new basicinput::Slider(group);
    slider->setObjectName(name);
    slider->setAccessibleName(label);
    slider->setRange(minimum, maximum);
    slider->setValue(initial);
    const auto updateText = [text, label, unit](int value) {
        text->setText(QString("%1: %2%3").arg(label).arg(value).arg(unit));
    };
    updateText(initial);
    QObject::connect(slider, &basicinput::Slider::valueChanged, text, updateText);
    layout->addWidget(text);
    layout->addWidget(slider);
    grid->addWidget(group, row, col);
    return slider;
};
auto* distance = addSlider("spatialViewDistance", "Camera distance", " px",
                           650, 2400, 1200, 0, 0);
auto* zoom = addSlider("spatialViewZoom", "Scene zoom", "%", 50, 110, 90, 0, 1);
QObject::connect(distance, &basicinput::Slider::valueChanged, view,
                 [view](int value) { view->setCameraDistance(value); });
QObject::connect(zoom, &basicinput::Slider::valueChanged, view,
                 [view](int value) { view->setZoom(value / 100.0); });
column->addWidget(controls);

QObject::connect(follow, &basicinput::ToggleSwitch::toggled,
                 view, &spatial::SpatialView::setPointerTrackingEnabled);
QObject::connect(view, &spatial::SpatialView::pointerTrackingEnabledChanged,
                 follow, &basicinput::ToggleSwitch::setIsOn);
const auto updateAvailability = [view, controls, follow] {
    controls->setEnabled(view->isSpatialEnabled());
    follow->setEnabled(view->isSpatialEnabled());
};
QObject::connect(view, &spatial::SpatialView::spatialEnabledChanged, controls, updateAvailability);
updateAvailability();

fluent::spatial::SpatialView

Erbt von QWidget · FluentElement · QMLPlus

Widget-Container mit Unterstützung für perspektivische 3D-Transformationen über OpenGL- und CPU-Raster-Backends. Fällt bei deaktivierter Perspektive oder beim Drücken von Tab / Esc für Eingabe und Barrierefreiheit auf ein flaches vertikales 2D-Layout zurück.

Konstruktoren

Destruktoren

Enumerationen

enum class RenderMode
  • Auto
  • Raster
  • OpenGL
enum class Backend
  • Raster
  • OpenGL

Methoden

SpatialItem* addWidget(QWidget* widget, WidgetOwnership ownership = WidgetOwnership::Borrowed)

Fügt der 3D-Ansicht ein Widget hinzu und gibt dessen SpatialItem zurück; ownership steuert die Bereinigung beim Entfernen.

QWidget* takeWidget(SpatialItem* item)

Löst das Widget, löscht item und gibt die Eigentümerschaft des Widgets an den Aufrufer zurück.

void releaseItem(SpatialItem* item)

Entfernt das Element und behandelt sein Widget gemäß seiner WidgetOwnership-Einstellung.

int itemCount() const

Anzahl der aktuell in der Ansicht vorhandenen Elemente.

bool isSpatialEnabled() const

Aktiviert die 3D-Perspektive (standardmäßig true, sofern zulässig); beim Deaktivieren wird auf ein vertikales 2D-Layout umgeschaltet.

void setSpatialEnabled(bool enabled)

Aktiviert die 3D-Perspektive (standardmäßig true, sofern zulässig); beim Deaktivieren wird auf ein vertikales 2D-Layout umgeschaltet.

qreal cameraDistance() const

Perspektivische Kameradistanz in logischen Pixeln [100, 10000]; Standard 1000.

void setCameraDistance(qreal distance)

Perspektivische Kameradistanz in logischen Pixeln [100, 10000]; Standard 1000.

qreal zoom() const

Zoomfaktor der gesamten Szene [0.1, 4]; Standard 1.

void setZoom(qreal zoom)

Zoomfaktor der gesamten Szene [0.1, 4]; Standard 1.

bool isPointerTrackingEnabled() const

Neigt die Szene im 3D-Modus zum Zeiger hin; Standardwert true.

void setPointerTrackingEnabled(bool enabled)

Neigt die Szene im 3D-Modus zum Zeiger hin; Standardwert true.

QPointF maximumTilt() const

Maximale Zeigerneigung in Grad pro Achse [0, 45]; Standard (10, 16).

void setMaximumTilt(const QPointF& degrees)

Maximale Zeigerneigung in Grad pro Achse [0, 45]; Standard (10, 16).

int responseTime() const

Zeitkonstante für die Zeigerglättung in ms [0, 1000]; Standardwert 140.

void setResponseTime(int milliseconds)

Zeitkonstante für die Zeigerglättung in ms [0, 1000]; Standardwert 140.

int maximumFrameRate() const

Obergrenze der Aktualisierungsrate für die Zeigerneigung [15, 120] fps; Standardwert 60.

void setMaximumFrameRate(int framesPerSecond)

Obergrenze der Aktualisierungsrate für die Zeigerneigung [15, 120] fps; Standardwert 60.

bool isCacheEnabled() const

Aktiviert Offscreen-Caching für Elemente; Standardwert ist true.

void setCacheEnabled(bool enabled)

Aktiviert Offscreen-Caching für Elemente; Standardwert ist true.

RenderMode renderMode() const

Render-Backend: Auto (Standard), Raster (CPU) oder OpenGL (fällt auf CPU zurück, falls keine Hardware verfügbar ist).

void setRenderMode(RenderMode mode)

Render-Backend: Auto (Standard), Raster (CPU) oder OpenGL (fällt auf CPU zurück, falls keine Hardware verfügbar ist).

Backend activeBackend() const

Derzeit aktives Rendering-Backend (Raster oder OpenGL).

QString rendererName() const

Name des aktiven OpenGL-Renderers oder leer bei Verwendung von CPU-Rasterisierung.

QString fallbackReason() const

Grund für den OpenGL-Fallback auf CPU-Rendering, andernfalls leer.

Eigenschaften

bool spatialEnabled

Aktiviert die 3D-Perspektive (standardmäßig true, sofern zulässig); beim Deaktivieren wird auf ein vertikales 2D-Layout umgeschaltet.

Lesen isSpatialEnabled()Schreiben setSpatialEnabled()Benachrichtigung spatialEnabledChanged()
qreal cameraDistance

Perspektivische Kameradistanz in logischen Pixeln [100, 10000]; Standard 1000.

Lesen cameraDistance()Schreiben setCameraDistance()Benachrichtigung cameraDistanceChanged()
qreal zoom

Zoomfaktor der gesamten Szene [0.1, 4]; Standard 1.

Lesen zoom()Schreiben setZoom()Benachrichtigung zoomChanged()
bool pointerTrackingEnabled

Neigt die Szene im 3D-Modus zum Zeiger hin; Standardwert true.

Lesen isPointerTrackingEnabled()Schreiben setPointerTrackingEnabled()Benachrichtigung pointerTrackingEnabledChanged()
QPointF maximumTilt

Maximale Zeigerneigung in Grad pro Achse [0, 45]; Standard (10, 16).

Lesen maximumTilt()Schreiben setMaximumTilt()Benachrichtigung maximumTiltChanged()
int responseTime

Zeitkonstante für die Zeigerglättung in ms [0, 1000]; Standardwert 140.

Lesen responseTime()Schreiben setResponseTime()Benachrichtigung responseTimeChanged()
int maximumFrameRate

Obergrenze der Aktualisierungsrate für die Zeigerneigung [15, 120] fps; Standardwert 60.

Lesen maximumFrameRate()Schreiben setMaximumFrameRate()Benachrichtigung maximumFrameRateChanged()
bool cacheEnabled

Aktiviert Offscreen-Caching für Elemente; Standardwert ist true.

Lesen isCacheEnabled()Schreiben setCacheEnabled()Benachrichtigung cacheEnabledChanged()
RenderMode renderMode

Render-Backend: Auto (Standard), Raster (CPU) oder OpenGL (fällt auf CPU zurück, falls keine Hardware verfügbar ist).

Lesen renderMode()Schreiben setRenderMode()Benachrichtigung renderModeChanged()
Backend activeBackend

Derzeit aktives Rendering-Backend (Raster oder OpenGL).

Lesen activeBackend()Benachrichtigung rendererChanged()
QString rendererName

Name des aktiven OpenGL-Renderers oder leer bei Verwendung von CPU-Rasterisierung.

Lesen rendererName()Benachrichtigung rendererChanged()
QString fallbackReason

Grund für den OpenGL-Fallback auf CPU-Rendering, andernfalls leer.

Lesen fallbackReason()Benachrichtigung rendererChanged()
int itemCount

Anzahl der aktuell in der Ansicht vorhandenen Elemente.

Lesen itemCount()Benachrichtigung itemCountChanged()

Signale

void spatialEnabledChanged(bool enabled)

Aktiviert die 3D-Perspektive (standardmäßig true, sofern zulässig); beim Deaktivieren wird auf ein vertikales 2D-Layout umgeschaltet.

void cameraDistanceChanged(qreal distance)

Perspektivische Kameradistanz in logischen Pixeln [100, 10000]; Standard 1000.

void zoomChanged(qreal zoom)

Zoomfaktor der gesamten Szene [0.1, 4]; Standard 1.

void pointerTrackingEnabledChanged(bool enabled)

Neigt die Szene im 3D-Modus zum Zeiger hin; Standardwert true.

void maximumTiltChanged(const QPointF& degrees)

Maximale Zeigerneigung in Grad pro Achse [0, 45]; Standard (10, 16).

void responseTimeChanged(int milliseconds)

Zeitkonstante für die Zeigerglättung in ms [0, 1000]; Standardwert 140.

void maximumFrameRateChanged(int framesPerSecond)

Obergrenze der Aktualisierungsrate für die Zeigerneigung [15, 120] fps; Standardwert 60.

void cacheEnabledChanged(bool enabled)

Aktiviert Offscreen-Caching für Elemente; Standardwert ist true.

void renderModeChanged(RenderMode mode)

Render-Backend: Auto (Standard), Raster (CPU) oder OpenGL (fällt auf CPU zurück, falls keine Hardware verfügbar ist).

void rendererChanged()

Derzeit aktives Rendering-Backend (Raster oder OpenGL).

void itemCountChanged(int count)

Anzahl der aktuell in der Ansicht vorhandenen Elemente.

PySide6-Erweiterungen

addOwnedWidget(widget)

Überträgt den Inhalt an die Ansicht. Die Freigabe des zugehörigen Eintrags zerstört den Inhalt.

addReparentedWidget(widget)

Gibt den Inhalt bei der Freigabe an sein ursprüngliches übergeordnetes QWidget zurück.

Geschützte Elemente

Methoden

Geerbt von fluent::FluentElement

Enumerationen

enum Theme

Globales visuelles Theme zum Auflösen von Design-Tokens.

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

Methoden

static void setTheme(Theme theme)

Aktualisiert das globale Theme und benachrichtigt aktive FluentElement-Instanzen.

static void setThemeDeferred(Theme theme)

Plant eine gebündelte Theme-Aktualisierung mit Priorität für sichtbare Elemente, ohne die aktuelle Interaktion zu blockieren.

static Theme currentTheme()

Gibt das aktuell aktive globale Design zurück.

static bool themeUsesDarkAppearance(Theme theme)

Gibt zurück, ob ein Theme Chrome und Material-Tokens auf dunklem Hintergrund verwendet.

static void refreshTheme()

Sendet das aktuelle Theme nach einer Änderung von Design-Tokens erneut, um ein Neuzeichnen auszulösen.

static int themeGeneration()

Monotoner Zähler zur Veraltungsprüfung, der bei jedem Designwechsel erhöht wird.

Theme effectiveTheme() const

Löst das von diesem Element verwendete Theme auf und berücksichtigt dabei eine geerbte QWidget-Überschreibung.

bool effectiveThemeUsesDarkAppearance() const

Gibt zurück, ob das effektive Theme dieses Elements Chrome auf dunklem Hintergrund verwendet.

bool setThemeOverrides(const QJsonObject& overrides)

Ersetzt die selektiven Farb-, Radius- und Schrift-Token-Überschreibungen dieses Elements.

QJsonObject themeOverrides() const

Gibt die festgelegten Überschreibungen dieses Elements zurück.

void clearThemeOverrides()

Setzt alle Token-Felder auf die Standardwerte des globalen Designs zurück.

const Colors& themeColorsRef() const

Kopiefreier Zugriff auf das aktive Farbset für kritische Zeichenpfade.

Material::AcrylicToken themeAcrylic() const

Material-, Höhenstufen- und adaptive Layout-Tokens.

QColor themeBackdrop(bool active) const

Backdrop-Farbe des Fenster-Chrome für den angegebenen Aktivierungszustand.

virtual void onThemeUpdated()

Wird nach einer Änderung des globalen Themes aufgerufen.

Typen und Aliase

struct Colors

An Komponenten zurückgegebene Design-Token-Snapshots.

Geerbt von fluent::QMLPlus

Methoden

AnchorLayout::Anchors* anchors()

Gibt veränderbare Anker für den QWidget-Host zurück.

void setState(const QString& name)

Wendet einen registrierten Zustand anhand seines Namens an oder stellt den Standardzustand wieder her, wenn @p name leer ist. Unbekannte Namen werden ignoriert, und bestehende Bindungen werden beim Verlassen des Zustands wieder aufgenommen.

void addState(const QMLState& state)

Registriert oder ersetzt eine benannte Zustandsdefinition; das Ersetzen des aktiven Zustands wendet diesen sofort an.

void evaluateStates()

Wertet Zustandsbedingungen in Registrierungsreihenfolge neu aus und aktiviert den ersten Treffer oder den Standardzustand, wenn keiner zutrifft. Wird auch automatisch bei Benachrichtigungen abhängiger Eigenschaften ausgeführt; abgeleitete Zustände mit extend erben Änderungen der Vorgänger, sofern keine Zyklen vorliegen oder Vorgänger fehlen.

QMLPlusRuntime* runtime()

Gibt den bei Bedarf erstellten Zustandsbeobachter im Besitz dieses Hosts zurück.

void setAnchors(const AnchorLayout::Anchors& anchors)

Ersetzt alle Host-Anker und macht das übergeordnete Layout ungültig.

void resetAnchors()

Löscht alle Host-Anker und invalidiert das übergeordnete Layout.

void bind(const char* targetProp, QObject* source, const char* sourceProp, PropertyBinder::Direction dir = PropertyBinder::OneWay)

Bindet @p sourceProp von @p source über PropertyBinder::bind() an @p targetProp dieses QWidget-Hosts.

void addTransition(const StateTransition& transition)

Registriert einen Zustandsübergang in Prioritätsreihenfolge.

void setBehavior(const char* propertyName, const PropertyAnimation& animation)

Setzt die Standardanimation, die beim Schreiben von @p propertyName über writeProperty() oder eine Bindung verwendet wird. Explizite StateTransition-Regeln haben Vorrang; direkte C++-Setter-Aufrufe werden nicht animiert.

void clearBehavior(const char* propertyName)

Entfernt die Standardanimation für zukünftige verwaltete Schreibvorgänge.

bool writeProperty(const char* propertyName, const QVariant& value)

Schreibt eine Host-Eigenschaft über Behavior, ohne deren Bindung zu entfernen.

Qt-Basisklassendokumentation: QWidget