Fluent-Qt

Perspectiva 3D (Spatial)

SpatialView Vista espacial

Aplica perspectiva e inclinación según el puntero a los widgets existentes. Mantén la edición de texto y los elementos emergentes en el diseño normal; no se pueden incrustar hijos de ventana nativa ni OpenGL.

Ejemplo

SpatialView Vista espacial: Perspectiva de escena

Uso

Perspectiva de escena

Ajusta la cámara y el zoom, luego mueve el puntero sobre las tarjetas.

#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

Hereda de QWidget · FluentElement · QMLPlus

Contenedor de widgets compatible con transformaciones de perspectiva 3D mediante backends de OpenGL y rasterización por CPU. Recurre a un diseño vertical plano en 2D cuando se desactiva la perspectiva o se pulsa Tab / Esc para entrada y accesibilidad.

Constructores

Destructores

Enumeraciones

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

Métodos

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

Añade un widget a la vista 3D y devuelve su SpatialItem; ownership controla la limpieza al eliminarlo.

QWidget* takeWidget(SpatialItem* item)

Desvincula el widget, elimina item y devuelve la propiedad del widget al llamador.

void releaseItem(SpatialItem* item)

Quita el elemento y administra su widget según su configuración WidgetOwnership.

int itemCount() const

Número de elementos actualmente en la vista.

bool isSpatialEnabled() const

Habilita la perspectiva 3D (true de forma predeterminada cuando se permite); deshabilitarlo cambia a un diseño vertical 2D.

void setSpatialEnabled(bool enabled)

Habilita la perspectiva 3D (true de forma predeterminada cuando se permite); deshabilitarlo cambia a un diseño vertical 2D.

qreal cameraDistance() const

Distancia de cámara en perspectiva en píxeles lógicos [100, 10000]; predeterminado: 1000.

void setCameraDistance(qreal distance)

Distancia de cámara en perspectiva en píxeles lógicos [100, 10000]; predeterminado: 1000.

qreal zoom() const

Factor de zoom de toda la escena [0.1, 4]; 1 de forma predeterminada.

void setZoom(qreal zoom)

Factor de zoom de toda la escena [0.1, 4]; 1 de forma predeterminada.

bool isPointerTrackingEnabled() const

Inclina la escena hacia el puntero en modo 3D; el valor predeterminado es true.

void setPointerTrackingEnabled(bool enabled)

Inclina la escena hacia el puntero en modo 3D; el valor predeterminado es true.

QPointF maximumTilt() const

Inclinación máxima del puntero en grados por eje [0, 45]; valor predeterminado (10, 16).

void setMaximumTilt(const QPointF& degrees)

Inclinación máxima del puntero en grados por eje [0, 45]; valor predeterminado (10, 16).

int responseTime() const

Constante de tiempo de suavizado del puntero en ms [0, 1000]; valor predeterminado: 140.

void setResponseTime(int milliseconds)

Constante de tiempo de suavizado del puntero en ms [0, 1000]; valor predeterminado: 140.

int maximumFrameRate() const

Límite de frecuencia de actualización de inclinación del puntero [15, 120] fps; valor predeterminado: 60.

void setMaximumFrameRate(int framesPerSecond)

Límite de frecuencia de actualización de inclinación del puntero [15, 120] fps; valor predeterminado: 60.

bool isCacheEnabled() const

Habilita la caché fuera de pantalla para los elementos; true de forma predeterminada.

void setCacheEnabled(bool enabled)

Habilita la caché fuera de pantalla para los elementos; true de forma predeterminada.

RenderMode renderMode() const

Backend de renderizado: Auto (predeterminado), Raster (CPU) u OpenGL (recurre a CPU si el hardware no está disponible).

void setRenderMode(RenderMode mode)

Backend de renderizado: Auto (predeterminado), Raster (CPU) u OpenGL (recurre a CPU si el hardware no está disponible).

Backend activeBackend() const

Backend de renderizado activo actualmente (Raster u OpenGL).

QString rendererName() const

Nombre del renderizador OpenGL activo, o vacío al usar rasterización por CPU.

QString fallbackReason() const

Motivo por el que OpenGL recurrió al renderizado por CPU, o vacío en caso contrario.

Propiedades

bool spatialEnabled

Habilita la perspectiva 3D (true de forma predeterminada cuando se permite); deshabilitarlo cambia a un diseño vertical 2D.

Lectura isSpatialEnabled()Escritura setSpatialEnabled()Notificación spatialEnabledChanged()
qreal cameraDistance

Distancia de cámara en perspectiva en píxeles lógicos [100, 10000]; predeterminado: 1000.

Lectura cameraDistance()Escritura setCameraDistance()Notificación cameraDistanceChanged()
qreal zoom

Factor de zoom de toda la escena [0.1, 4]; 1 de forma predeterminada.

Lectura zoom()Escritura setZoom()Notificación zoomChanged()
bool pointerTrackingEnabled

Inclina la escena hacia el puntero en modo 3D; el valor predeterminado es true.

Lectura isPointerTrackingEnabled()Escritura setPointerTrackingEnabled()Notificación pointerTrackingEnabledChanged()
QPointF maximumTilt

Inclinación máxima del puntero en grados por eje [0, 45]; valor predeterminado (10, 16).

Lectura maximumTilt()Escritura setMaximumTilt()Notificación maximumTiltChanged()
int responseTime

Constante de tiempo de suavizado del puntero en ms [0, 1000]; valor predeterminado: 140.

Lectura responseTime()Escritura setResponseTime()Notificación responseTimeChanged()
int maximumFrameRate

Límite de frecuencia de actualización de inclinación del puntero [15, 120] fps; valor predeterminado: 60.

Lectura maximumFrameRate()Escritura setMaximumFrameRate()Notificación maximumFrameRateChanged()
bool cacheEnabled

Habilita la caché fuera de pantalla para los elementos; true de forma predeterminada.

Lectura isCacheEnabled()Escritura setCacheEnabled()Notificación cacheEnabledChanged()
RenderMode renderMode

Backend de renderizado: Auto (predeterminado), Raster (CPU) u OpenGL (recurre a CPU si el hardware no está disponible).

Lectura renderMode()Escritura setRenderMode()Notificación renderModeChanged()
Backend activeBackend

Backend de renderizado activo actualmente (Raster u OpenGL).

Lectura activeBackend()Notificación rendererChanged()
QString rendererName

Nombre del renderizador OpenGL activo, o vacío al usar rasterización por CPU.

Lectura rendererName()Notificación rendererChanged()
QString fallbackReason

Motivo por el que OpenGL recurrió al renderizado por CPU, o vacío en caso contrario.

Lectura fallbackReason()Notificación rendererChanged()
int itemCount

Número de elementos actualmente en la vista.

Lectura itemCount()Notificación itemCountChanged()

Señales

void spatialEnabledChanged(bool enabled)

Habilita la perspectiva 3D (true de forma predeterminada cuando se permite); deshabilitarlo cambia a un diseño vertical 2D.

void cameraDistanceChanged(qreal distance)

Distancia de cámara en perspectiva en píxeles lógicos [100, 10000]; predeterminado: 1000.

void zoomChanged(qreal zoom)

Factor de zoom de toda la escena [0.1, 4]; 1 de forma predeterminada.

void pointerTrackingEnabledChanged(bool enabled)

Inclina la escena hacia el puntero en modo 3D; el valor predeterminado es true.

void maximumTiltChanged(const QPointF& degrees)

Inclinación máxima del puntero en grados por eje [0, 45]; valor predeterminado (10, 16).

void responseTimeChanged(int milliseconds)

Constante de tiempo de suavizado del puntero en ms [0, 1000]; valor predeterminado: 140.

void maximumFrameRateChanged(int framesPerSecond)

Límite de frecuencia de actualización de inclinación del puntero [15, 120] fps; valor predeterminado: 60.

void cacheEnabledChanged(bool enabled)

Habilita la caché fuera de pantalla para los elementos; true de forma predeterminada.

void renderModeChanged(RenderMode mode)

Backend de renderizado: Auto (predeterminado), Raster (CPU) u OpenGL (recurre a CPU si el hardware no está disponible).

void rendererChanged()

Backend de renderizado activo actualmente (Raster u OpenGL).

void itemCountChanged(int count)

Número de elementos actualmente en la vista.

Adiciones de PySide6

addOwnedWidget(widget)

Transfiere el contenido a la vista. Al liberar su elemento, se destruye el contenido.

addReparentedWidget(widget)

Al liberar el contenido, lo devuelve a su QWidget padre original.

Miembros protegidos

Métodos

Heredado de fluent::FluentElement

Enumeraciones

enum Theme

Tema visual global usado al resolver los tokens de diseño.

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

Métodos

static void setTheme(Theme theme)

Actualiza el tema global y notifica a las instancias activas de FluentElement.

static void setThemeDeferred(Theme theme)

Programa una actualización de tema por lotes dando prioridad a lo visible sin bloquear la interacción actual.

static Theme currentTheme()

Devuelve el tema global activo actualmente.

static bool themeUsesDarkAppearance(Theme theme)

Devuelve si un tema utiliza cromo sobre fondo oscuro y tokens de material.

static void refreshTheme()

Vuelve a difundir el tema actual para repintar tras un cambio de token de diseño.

static int themeGeneration()

Contador monótono incrementado en cada cambio de tema para comprobaciones de obsolescencia.

Theme effectiveTheme() const

Resuelve el tema usado por este elemento, respetando una invalidación heredada de QWidget.

bool effectiveThemeUsesDarkAppearance() const

Devuelve si el tema efectivo de este elemento usa cromo sobre fondo oscuro.

bool setThemeOverrides(const QJsonObject& overrides)

Reemplaza las invalidaciones dispersas de tokens de color, radio y fuente de este elemento.

QJsonObject themeOverrides() const

Devuelve las anulaciones definidas en este elemento.

void clearThemeOverrides()

Restaura todos los campos de token a los valores predeterminados del tema global.

const Colors& themeColorsRef() const

Acceso sin copia al conjunto de colores activo para rutas críticas de pintado.

Material::AcrylicToken themeAcrylic() const

Tokens de material, elevación y diseño adaptable.

QColor themeBackdrop(bool active) const

Color de fondo del chrome de la ventana para el estado de activación indicado.

virtual void onThemeUpdated()

Se llama después de que cambia el tema global.

Tipos y alias

struct Colors

Instantáneas de tokens de diseño devueltas a los componentes.

Heredado de fluent::QMLPlus

Métodos

AnchorLayout::Anchors* anchors()

Devuelve los anclajes mutables del host QWidget.

void setState(const QString& name)

Aplica un estado registrado por nombre o restaura el estado predeterminado cuando @p name está vacío. Los nombres desconocidos se ignoran y los enlaces existentes se reanudan al salir del estado.

void addState(const QMLState& state)

Registra o reemplaza una definición de estado con nombre; reemplazar el estado activo lo aplica de inmediato.

void evaluateStates()

Reevalúa las condiciones de estado en orden de registro y activa la primera coincidencia, o el estado predeterminado si ninguna coincide. También se ejecuta automáticamente cuando notifican las propiedades dependientes; los estados derivados que usan extend heredan cambios de ancestros salvo que sean cíclicos o falten.

QMLPlusRuntime* runtime()

Devuelve el observador de estado creado de forma diferida y propiedad de este host.

void setAnchors(const AnchorLayout::Anchors& anchors)

Reemplaza todos los anclajes del host e invalida el diseño padre.

void resetAnchors()

Limpia todos los anclajes del host e invalida el diseño padre.

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

Vincula @p sourceProp en @p source con @p targetProp en este host QWidget mediante PropertyBinder::bind().

void addTransition(const StateTransition& transition)

Registra una transición de estado por orden de precedencia.

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

Establece la animación por defecto usada al escribir @p propertyName mediante writeProperty() o un enlace. Las reglas StateTransition explícitas tienen prioridad; las llamadas directas a setters de C++ no se animan.

void clearBehavior(const char* propertyName)

Quita la animación predeterminada para futuras escrituras administradas.

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

Escribe una propiedad del host mediante Behavior sin eliminar su enlace.

Documentación de la clase base de Qt: QWidget