Fluent-Qt

3D パース表示 (Spatial)

SpatialView 空間ビュー

既存のウィジェットに 3D パースペクティブとポインター追従の傾きを適用します。テキスト編集やポップアップは通常レイアウトに保ってください。ネイティブウィンドウや OpenGL の子要素は埋め込めません。

サンプル

SpatialView 空間ビュー: シーンのパースペクティブ

使い方

シーンのパースペクティブ

カメラとズームを調整し、カードの上にポインターを動かします。

#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

継承元 QWidget · FluentElement · QMLPlus

OpenGL および CPU ラスターバックエンドによる 3D パースペクティブ変換に対応したウィジェットコンテナです。パースペクティブが無効な場合や、入力およびアクセシビリティのために Tab / Esc が押された場合は、フラットな 2D 縦方向レイアウトにフォールバックします。

コンストラクタ

デストラクタ

列挙型

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

メソッド

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

3D ビューにウィジェットを追加し、対応する SpatialItem を返します。削除時の解放方法は ownership で制御します。

QWidget* takeWidget(SpatialItem* item)

ウィジェットを切り離して item を削除し、ウィジェットの所有権を呼び出し側に返します。

void releaseItem(SpatialItem* item)

項目を削除し、その WidgetOwnership 設定に従ってウィジェットを処理します。

int itemCount() const

現在ビュー内にあるアイテム数。

bool isSpatialEnabled() const

3D パースペクティブを有効にします(許可時はデフォルトで true)。無効にすると 2D の縦方向レイアウトに切り替わります。

void setSpatialEnabled(bool enabled)

3D パースペクティブを有効にします(許可時はデフォルトで true)。無効にすると 2D の縦方向レイアウトに切り替わります。

qreal cameraDistance() const

論理ピクセル単位の透視投影カメラ距離([100, 10000]、既定値は 1000)。

void setCameraDistance(qreal distance)

論理ピクセル単位の透視投影カメラ距離([100, 10000]、既定値は 1000)。

qreal zoom() const

シーン全体のズーム倍率 [0.1, 4](デフォルトは 1)。

void setZoom(qreal zoom)

シーン全体のズーム倍率 [0.1, 4](デフォルトは 1)。

bool isPointerTrackingEnabled() const

3D モードでポインターの方向へシーンを傾けます。デフォルトは true です。

void setPointerTrackingEnabled(bool enabled)

3D モードでポインターの方向へシーンを傾けます。デフォルトは true です。

QPointF maximumTilt() const

軸ごとのポインター最大傾斜角度([0, 45] 度)。既定値は (10, 16) です。

void setMaximumTilt(const QPointF& degrees)

軸ごとのポインター最大傾斜角度([0, 45] 度)。既定値は (10, 16) です。

int responseTime() const

ポインター平滑化の時定数(ms、[0, 1000])、既定値は 140。

void setResponseTime(int milliseconds)

ポインター平滑化の時定数(ms、[0, 1000])、既定値は 140。

int maximumFrameRate() const

ポインターチルトの更新レート上限([15, 120] fps)、既定値は 60。

void setMaximumFrameRate(int framesPerSecond)

ポインターチルトの更新レート上限([15, 120] fps)、既定値は 60。

bool isCacheEnabled() const

項目のオフスクリーンキャッシュを有効にします。デフォルトは true です。

void setCacheEnabled(bool enabled)

項目のオフスクリーンキャッシュを有効にします。デフォルトは true です。

RenderMode renderMode() const

描画バックエンド:Auto(デフォルト)、Raster(CPU)、または OpenGL(ハードウェアが利用できない場合は CPU にフォールバックします)。

void setRenderMode(RenderMode mode)

描画バックエンド:Auto(デフォルト)、Raster(CPU)、または OpenGL(ハードウェアが利用できない場合は CPU にフォールバックします)。

Backend activeBackend() const

現在アクティブなレンダリングバックエンド(Raster または OpenGL)。

QString rendererName() const

現在の OpenGL レンダラー名。CPU ラスター使用時は空になります。

QString fallbackReason() const

OpenGL が CPU レンダリングにフォールバックした理由。フォールバックしていない場合は空になります。

プロパティ

bool spatialEnabled

3D パースペクティブを有効にします(許可時はデフォルトで true)。無効にすると 2D の縦方向レイアウトに切り替わります。

読み取り isSpatialEnabled()書き込み setSpatialEnabled()通知シグナル spatialEnabledChanged()
qreal cameraDistance

論理ピクセル単位の透視投影カメラ距離([100, 10000]、既定値は 1000)。

読み取り cameraDistance()書き込み setCameraDistance()通知シグナル cameraDistanceChanged()
qreal zoom

シーン全体のズーム倍率 [0.1, 4](デフォルトは 1)。

読み取り zoom()書き込み setZoom()通知シグナル zoomChanged()
bool pointerTrackingEnabled

3D モードでポインターの方向へシーンを傾けます。デフォルトは true です。

読み取り isPointerTrackingEnabled()書き込み setPointerTrackingEnabled()通知シグナル pointerTrackingEnabledChanged()
QPointF maximumTilt

軸ごとのポインター最大傾斜角度([0, 45] 度)。既定値は (10, 16) です。

読み取り maximumTilt()書き込み setMaximumTilt()通知シグナル maximumTiltChanged()
int responseTime

ポインター平滑化の時定数(ms、[0, 1000])、既定値は 140。

読み取り responseTime()書き込み setResponseTime()通知シグナル responseTimeChanged()
int maximumFrameRate

ポインターチルトの更新レート上限([15, 120] fps)、既定値は 60。

読み取り maximumFrameRate()書き込み setMaximumFrameRate()通知シグナル maximumFrameRateChanged()
bool cacheEnabled

項目のオフスクリーンキャッシュを有効にします。デフォルトは true です。

読み取り isCacheEnabled()書き込み setCacheEnabled()通知シグナル cacheEnabledChanged()
RenderMode renderMode

描画バックエンド:Auto(デフォルト)、Raster(CPU)、または OpenGL(ハードウェアが利用できない場合は CPU にフォールバックします)。

読み取り renderMode()書き込み setRenderMode()通知シグナル renderModeChanged()
Backend activeBackend

現在アクティブなレンダリングバックエンド(Raster または OpenGL)。

読み取り activeBackend()通知シグナル rendererChanged()
QString rendererName

現在の OpenGL レンダラー名。CPU ラスター使用時は空になります。

読み取り rendererName()通知シグナル rendererChanged()
QString fallbackReason

OpenGL が CPU レンダリングにフォールバックした理由。フォールバックしていない場合は空になります。

読み取り fallbackReason()通知シグナル rendererChanged()
int itemCount

現在ビュー内にあるアイテム数。

読み取り itemCount()通知シグナル itemCountChanged()

シグナル

void spatialEnabledChanged(bool enabled)

3D パースペクティブを有効にします(許可時はデフォルトで true)。無効にすると 2D の縦方向レイアウトに切り替わります。

void cameraDistanceChanged(qreal distance)

論理ピクセル単位の透視投影カメラ距離([100, 10000]、既定値は 1000)。

void zoomChanged(qreal zoom)

シーン全体のズーム倍率 [0.1, 4](デフォルトは 1)。

void pointerTrackingEnabledChanged(bool enabled)

3D モードでポインターの方向へシーンを傾けます。デフォルトは true です。

void maximumTiltChanged(const QPointF& degrees)

軸ごとのポインター最大傾斜角度([0, 45] 度)。既定値は (10, 16) です。

void responseTimeChanged(int milliseconds)

ポインター平滑化の時定数(ms、[0, 1000])、既定値は 140。

void maximumFrameRateChanged(int framesPerSecond)

ポインターチルトの更新レート上限([15, 120] fps)、既定値は 60。

void cacheEnabledChanged(bool enabled)

項目のオフスクリーンキャッシュを有効にします。デフォルトは true です。

void renderModeChanged(RenderMode mode)

描画バックエンド:Auto(デフォルト)、Raster(CPU)、または OpenGL(ハードウェアが利用できない場合は CPU にフォールバックします)。

void rendererChanged()

現在アクティブなレンダリングバックエンド(Raster または OpenGL)。

void itemCountChanged(int count)

現在ビュー内にあるアイテム数。

PySide6 拡張

addOwnedWidget(widget)

コンテンツの所有権をビューに移します。対応する項目を解放するとコンテンツは破棄されます。

addReparentedWidget(widget)

解放時にコンテンツを元の親 QWidget に戻します。

protected メンバー

メソッド

fluent::FluentElement から継承

列挙型

enum Theme

デザイントークン解決時に使用されるグローバルな視覚テーマ。

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

メソッド

static void setTheme(Theme theme)

グローバルテーマを更新し、アクティブな FluentElement インスタンスに通知します。

static void setThemeDeferred(Theme theme)

現在の操作をブロックせずに、可視要素を優先したバッチ処理でテーマの更新をスケジュールします。

static Theme currentTheme()

現在有効なグローバルテーマを返します。

static bool themeUsesDarkAppearance(Theme theme)

テーマがダークベースのクロームおよびマテリアルトークンを使用するかどうかを返します。

static void refreshTheme()

デザイントークンの変更後に再描画するため、現在のテーマを再ブロードキャストします。

static int themeGeneration()

テーマ変更ごとに加算される単調増加カウンターです。鮮度チェックに使用されます。

Theme effectiveTheme() const

継承された QWidget の上書きを尊重し、この要素が使用するテーマを解決します。

bool effectiveThemeUsesDarkAppearance() const

この要素の有効なテーマがダークベースのクロームを使用するかどうかを返します。

bool setThemeOverrides(const QJsonObject& overrides)

この要素のスパースな色、角丸半径、フォントトークンの上書きを置き換えます。

QJsonObject themeOverrides() const

この要素に設定されたオーバーライドを返します。

void clearThemeOverrides()

すべてのトークンフィールドをグローバルテーマの既定値に復元します。

const Colors& themeColorsRef() const

描画のホットパス向けにアクティブなカラーセットへ非コピーでアクセスします。

Material::AcrylicToken themeAcrylic() const

マテリアル、エレベーション、およびアダプティブレイアウトのトークン。

QColor themeBackdrop(bool active) const

指定されたアクティブ状態に対するウィンドウ chrome の背景色。

virtual void onThemeUpdated()

グローバルテーマの変更後に呼び出されます。

型とエイリアス

struct Colors

コンポーネントに返されるデザイントークンのスナップショット。

fluent::QMLPlus から継承

メソッド

AnchorLayout::Anchors* anchors()

QWidget ホストの変更可能なアンカーを返します。

void setState(const QString& name)

登録済みの状態を名前で適用するか、@p name が空の場合はデフォルト状態を復元します。未知の名前は無視され、その状態を離れると既存のバインディングが再開されます。

void addState(const QMLState& state)

名前付き状態定義を登録または置換します。アクティブな状態を置換した場合は即座に適用されます。

void evaluateStates()

登録順に状態条件を再評価し、最初に一致した状態(一致しない場合はデフォルト状態)をアクティブにします。依存プロパティの変更通知時にも自動実行され、extend を使用する派生状態は、循環や欠損がない限り祖先の変更を継承します。

QMLPlusRuntime* runtime()

このホストが所有し、遅延生成される状態オブザーバーを返します。

void setAnchors(const AnchorLayout::Anchors& anchors)

すべてのホストアンカーを置き換え、親レイアウトを無効化します。

void resetAnchors()

ホストのすべてのアンカーをクリアし、親レイアウトを無効化します。

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

PropertyBinder::bind() を介して、@p source の @p sourceProp をこの QWidget ホストの @p targetProp にバインドします。

void addTransition(const StateTransition& transition)

優先順位順に状態遷移を登録します。

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

writeProperty() またはバインディング経由で @p propertyName が書き込まれた際に使用されるデフォルトアニメーションを設定します。明示的な StateTransition ルールが優先され、C++ のセッターを直接呼び出した場合はアニメーションしません。

void clearBehavior(const char* propertyName)

今後のマネージド書き込みに使用するデフォルトアニメーションを削除します。

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

バインディングを削除せずに Behavior 経由でホストプロパティに書き込みます。

Qt 基底クラスドキュメント:QWidget