3D パース表示 (Spatial)
SpatialView 空間ビュー
既存のウィジェットに 3D パースペクティブとポインター追従の傾きを適用します。テキスト編集やポップアップは通常レイアウトに保ってください。ネイティブウィンドウや OpenGL の子要素は埋め込めません。
サンプル
プロパティプレビューを読み込めませんでした。もう一度「プロパティプレビュー」を選択して再試行してください。

使い方
シーンのパースペクティブ
カメラとズームを調整し、カードの上にポインターを動かします。
#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();import fluentqt
from PySide6.QtCore import QEvent, QPointF
from PySide6.QtGui import QVector3D
from PySide6.QtWidgets import QGridLayout, QHBoxLayout, QVBoxLayout, QWidget
from fluentqt.spatial import SpatialSession, SpatialView
class SpatialPreviewPanel(QWidget):
def stop_spatial(self):
session = self.findChild(SpatialSession)
if session is not None:
session.deactivate()
def event(self, event):
# Stop before deleteLater dismantles this panel's widgets.
# Also call stop_spatial before disposing an enclosing window.
if event.type() == QEvent.DeferredDelete:
self.stop_spatial()
return super().event(event)
class SceneView(SpatialView):
def arrange(self):
if self.itemCount() == 2:
spread = 24 if self.width() < 650 else 100
self.items()[0].setPosition(QVector3D(-spread, -44, -160))
self.items()[-1].setPosition(QVector3D(spread, 44, 160))
def resizeEvent(self, event):
super().resizeEvent(event)
self.arrange()
panel = SpatialPreviewPanel()
column = QVBoxLayout(panel)
column.setContentsMargins(0, 0, 0, 0)
column.setSpacing(12)
session = SpatialSession(panel, panel)
spatial_attached = session.activate()
view = SceneView(panel)
spatial_attached = spatial_attached and session.attachView(view)
if not spatial_attached:
view.setRenderMode(SpatialView.RenderMode.Raster)
view.setSpatialEnabled(False)
view.setObjectName("spatialPreviewView")
view.setFixedHeight(400)
view.setCameraDistance(1200)
view.setMaximumTilt(QPointF(4, 6))
column.addWidget(view)
def add_slider(parent, layout, name, label, unit, minimum, maximum, initial):
in_grid = isinstance(layout, QGridLayout)
group = QWidget(parent) if in_grid else parent
column = QVBoxLayout(group) if in_grid else QVBoxLayout()
column.setContentsMargins(0, 0, 0, 0)
column.setSpacing(4)
text = fluentqt.Label(f"{label}: {initial}{unit}", group)
slider = fluentqt.Slider(group)
slider.setObjectName(name)
slider.setAccessibleName(label)
slider.setRange(minimum, maximum)
slider.setValue(initial)
slider.valueChanged.connect(
lambda value: text.setText(f"{label}: {value}{unit}")
)
column.addWidget(text)
column.addWidget(slider)
if isinstance(layout, QGridLayout):
layout.addWidget(group, 0, layout.count())
else:
layout.addLayout(column)
return slider
column.setSpacing(16)
view.setZoom(0.9)
view.setMaximumTilt(QPointF(6, 12))
def make_layer(title, caption):
card = fluentqt.Card()
card.setFixedSize(220, 150)
content = QVBoxLayout(card)
content.setContentsMargins(16, 12, 16, 12)
content.setSpacing(6)
heading = fluentqt.Label(title, card)
heading.setFluentTypography(fluentqt.FontRole.Subtitle)
content.addWidget(heading)
chart = fluentqt.Sparkline(card)
chart.setAccessibleName(title + " sample chart")
model = fluentqt.ChartModel(card)
model.setPoints([QPointF(x, y) for x, y in enumerate([12, 24, 18, 38, 32, 54])])
chart.setModel(model)
content.addWidget(chart, 1)
note = fluentqt.Label(caption, card)
note.setTextColorRole(fluentqt.Label.TextColorRole.Secondary)
content.addWidget(note)
card._model = model
return card
back = view.addOwnedWidget(make_layer("Back layer", "Z -160 · sample data"))
front = view.addOwnedWidget(make_layer("Front layer", "Z +160 · sample data"))
back.setRotation(QVector3D(6, 16, 0))
front.setRotation(QVector3D(-6, -16, 0))
back.setSurfaceIntensity(0.75)
front.setSurfaceIntensity(0.75)
view.arrange()
toolbar = QHBoxLayout()
follow = fluentqt.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.removeWidget(view)
column.addLayout(toolbar)
column.addWidget(view)
controls = QWidget(panel)
controls.setObjectName("spatialViewControls")
sliders = QGridLayout(controls)
sliders.setContentsMargins(0, 0, 0, 0)
sliders.setHorizontalSpacing(24)
sliders.setVerticalSpacing(12)
sliders.setColumnStretch(0, 1)
sliders.setColumnStretch(1, 1)
distance = add_slider(
controls,
sliders,
"spatialViewDistance",
"Camera distance",
" px",
650,
2400,
1200
)
zoom = add_slider(
controls,
sliders,
"spatialViewZoom",
"Scene zoom",
"%",
50,
110,
90
)
distance.valueChanged.connect(view.setCameraDistance)
zoom.valueChanged.connect(lambda value: view.setZoom(value / 100.0))
column.addWidget(controls)
follow.toggled.connect(view.setPointerTrackingEnabled)
view.pointerTrackingEnabledChanged.connect(follow.setIsOn)
def update_availability():
controls.setEnabled(view.isSpatialEnabled())
follow.setEnabled(view.isSpatialEnabled())
view.spatialEnabledChanged.connect(update_availability)
update_availability()API
宣言を表示一致する API メンバーはありません。
fluent::spatial::SpatialView
継承元 QWidget · FluentElement · QMLPlus
OpenGL および CPU ラスターバックエンドによる 3D パースペクティブ変換に対応したウィジェットコンテナです。パースペクティブが無効な場合や、入力およびアクセシビリティのために Tab / Esc が押された場合は、フラットな 2D 縦方向レイアウトにフォールバックします。
コンストラクタ
デストラクタ
列挙型
enum class RenderModeAutoRasterOpenGL
enum class BackendRasterOpenGL
メソッド
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() const3D パースペクティブを有効にします(許可時はデフォルトで 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() const3D モードでポインターの方向へシーンを傾けます。デフォルトは 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() constOpenGL が CPU レンダリングにフォールバックした理由。フォールバックしていない場合は空になります。
プロパティ
bool spatialEnabled3D パースペクティブを有効にします(許可時はデフォルトで true)。無効にすると 2D の縦方向レイアウトに切り替わります。
読み取りisSpatialEnabled()書き込みsetSpatialEnabled()通知シグナルspatialEnabledChanged()qreal cameraDistance論理ピクセル単位の透視投影カメラ距離([100, 10000]、既定値は 1000)。
読み取りcameraDistance()書き込みsetCameraDistance()通知シグナルcameraDistanceChanged()qreal zoomシーン全体のズーム倍率 [0.1, 4](デフォルトは 1)。
読み取りzoom()書き込みsetZoom()通知シグナルzoomChanged()bool pointerTrackingEnabled3D モードでポインターの方向へシーンを傾けます。デフォルトは 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 fallbackReasonOpenGL が 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 = 0Dark = 1HighContrast = 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 にバインドします。
BindingHandle bindManaged(const char* targetProp, QObject* source, const char* sourceProp, PropertyBinder::Direction direction = PropertyBinder::OneWay, BindingOptions options = {})この QWidget ホストに管理された直接バインディングを設定します。
BindingHandle bindComputed(const char* targetProp, const QVector<BindingDependency>& dependencies, std::function<QVariant()> evaluate, BindingOptions options = {})この QWidget ホストに明示的依存関係を持つ C++ 式を設定します。
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