Item QML Type

基本的なビジュアルQMLタイプ。詳細...

• 継承されたメンバーを含む、すべてのメンバーの一覧

プロパティ

• activeFocus : bool
• activeFocusOnTab : bool
• anchors
  • anchors.alignWhenCentered : bool
  • anchors.baseline : AnchorLine
  • anchors.baselineOffset : real
  • anchors.bottom : AnchorLine
  • anchors.bottomMargin : real
  • anchors.centerIn : Item
  • anchors.fill : Item
  • anchors.horizontalCenter : AnchorLine
  • anchors.horizontalCenterOffset : real
  • anchors.left : AnchorLine
  • anchors.leftMargin : real
  • anchors.margins : real
  • anchors.right : AnchorLine
  • anchors.rightMargin : real
  • anchors.top : AnchorLine
  • anchors.topMargin : real
  • anchors.verticalCenter : AnchorLine
  • anchors.verticalCenterOffset : real
• antialiasing : bool
• baselineOffset : int
• children : list<Item>
• childrenRect
  • childrenRect.height : real
  • childrenRect.width : real
  • childrenRect.x : real
  • childrenRect.y : real
• clip : bool
• containmentMask : QObject*
• data : list<QtObject>
• enabled : bool
• focus : bool
• focusPolicy : enumeration (since 6.7)
• height : real
• implicitHeight : real
• implicitWidth : real
• layer.effect : Component
• layer.enabled : bool
• layer.format : enumeration
• layer.live : bool (since 6.5)
• layer.mipmap : bool
• layer.samplerName : string
• layer.samples : enumeration
• layer.smooth : bool
• layer.sourceRect : rect
• layer.textureMirroring : enumeration
• layer.textureSize : size
• layer.wrapMode : enumeration
• mutabilityGroup : int (since 6.12)
• opacity : real
• palette : Palette (since 6.0)
• parent : Item
• resources : list<QtObject>
• rotation : real
• scale : real
• smooth : bool
• state : string
• states : list<State>
• transform : list<Transform>
• transformOrigin : enumeration
• transitions : list<Transition>
• visible : bool
• visibleChildren : list<Item>
• width : real
• x : real
• y : real
• z : real

方法

• Item childAt(real x, real y)
• bool contains(point point)
• void dumpItemTree() (since 6.3)
• void forceActiveFocus()
• void forceActiveFocus(Qt::FocusReason reason)
• bool grabToImage(callback, targetSize)
• point mapFromGlobal(real x, real y)
• point mapFromItem(Item item, point p)
• rect mapFromItem(Item item, rect r)
• point mapFromItem(Item item, real x, real y)
• rect mapFromItem(Item item, real x, real y, real width, real height)
• point mapToGlobal(real x, real y)
• point mapToItem(Item item, point p)
• rect mapToItem(Item item, rect r)
• point mapToItem(Item item, real x, real y)
• rect mapToItem(Item item, real x, real y, real width, real height)
• Item nextItemInFocusChain(bool forward)

詳細説明

Item 型は、Qt Quick におけるすべてのビジュアルアイテムの基底型です。

Qt Quick のすべてのビジュアルアイテムは Item から継承されています。Item オブジェクト自体には視覚的な外観はありませんが、x 座標や y 座標、幅や高さ、アンカー位置、キー処理のサポートなど、ビジュアルアイテムに共通するすべての属性を定義しています。

Item 型は、単一のルートビジュアル項目の下に複数の項目をグループ化する際に役立ちます。例：

import QtQuick 2.0

Item {
    Image {
        source: "tile.png"
    }
    Image {
        x: 80
        width: 100
        height: 100
        source: "tile.png"
    }
    Image {
        x: 190
        width: 100
        height: 100
        fillMode: Image.Tile
        source: "tile.png"
    }
}

イベント処理

Item ベースのすべての視覚タイプは、Input Handlerを使用して、マウス、タッチ、キーイベントなどの入力イベント（QInputEvent のサブクラス）を処理できます。これは、イベントを処理するための推奨される宣言的な方法です。

タッチイベントを処理する別の方法としては、`QQuickItem` をサブクラス化し、コンストラクタ内で `setAcceptTouchEvents()` を呼び出し、`touchEvent()` をオーバーライドする方法があります。Accept を使用すると、イベント全体を捕捉して下位のアイテムへの伝達を停止し、そのイベントのすべてのタッチポイントを排他的に取得できます。QPointerEvent::setExclusiveGrabber() を使用すると、特定のタッチポイントのみを取得し、イベントの伝達を継続させることができます。

同様に、QQuickItem のサブクラスは、setAcceptedMouseButtons()を呼び出してマウスボタンイベントの受信を登録し、setAcceptHoverEvents()を呼び出してホバーイベント（ボタンが押されていない状態でのマウスの動き）を受信し、仮想関数mousePressEvent()、mouseMoveEvent()、およびmouseReleaseEvent()をオーバーライドすることができます。 これらもイベントを受け入れてそれ以上の配信を阻止し、同時に暗黙的なグラブを行うことができます。あるいは、QMouseEvent が保持する単一のQEventPoint を明示的にgrab することも可能です。

キーの処理は、Keys というアタッチメントプロパティを通じて、すべてのItemベースのビジュアルタイプで利用可能です。Keysアタッチメントプロパティは、pressed やreleased といった基本的なシグナルに加え、spacePressed のような特定のキーに対するシグナルも提供します。以下の例では、アイテムにキーボードフォーカスを割り当て、一般的なonPressed ハンドラで左キーを処理し、onReturnPressed ハンドラでリターンキーを処理しています：

import QtQuick 2.0

Item {
    focus: true
    Keys.onPressed: (event)=> {
        if (event.key == Qt.Key_Left) {
            console.log("move left");
            event.accepted = true;
        }
    }
    Keys.onReturnPressed: console.log("Pressed return");
}

詳細なドキュメントについては、Keys の添付プロパティを参照してください。

レイアウトのミラーリング

LayoutMirroring アタッチドプロパティを使用すると、項目のレイアウトをミラーリングできます。これにより、anchors が水平方向に反転するほか、子要素のレイアウトや配置を行う項目（ListView やRow など）も、そのレイアウトの方向が水平方向に反転します。

詳細については、LayoutMirroring を参照してください。

アイテムのレイヤー

通常、アイテムはそれが属するウィンドウに直接レンダリングされます。しかし、layer.enabled を設定することで、そのアイテムとそのサブツリー全体をオフスクリーンサーフェスに委譲することが可能です。その場合、オフスクリーンサーフェス（テクスチャ）のみがウィンドウに描画されます。

アイテムとは異なるテクスチャサイズを設定したい場合は、layer.textureSize を使用することで可能です。アイテムの一部のみをテクスチャに描画するには、layer.sourceRect を使用します。また、layer.sourceRect を指定して、テクスチャをアイテムの境界を超えて拡張させることも可能です。この場合、境界の外側は透明なピクセルで埋められます。

layer.smooth がtrue に設定されている場合、アイテムはスケーリングに線形補間を使用し、layer.mipmap がtrue に設定されている場合、ダウンサンプリングにミップマッピングを使用します。ミップマッピングにより、縮小されたアイテムの画質が向上する場合があります。単一のImageアイテムのミップマッピングには、Image::mipmap を優先して使用してください。

レイヤーの不透明度とアイテムの不透明度

アイテム階層にopacity を適用する場合、不透明度は各アイテムに個別に適用されます。これにより、サブツリーに不透明度が適用された際に、意図しない視覚的な結果が生じる可能性があります。次の例を考えてみてください：

レイヤーを使用しない不透明度 Item { id: nonLayered opacity: 0.5 width: 100 height: 100 Rectangle { width: 80; height: 80; border.width: 1 } Rectangle { x: 20; y: 20; width: 80; height: 80; border.width: 1 } }

レイヤーは、ルート項目の不透明度が1に設定された状態でレンダリングされ、描画時にルート項目の不透明度がテクスチャに適用されます。つまり、大規模なアイテム階層において、透明から不透明へ、あるいはその逆へのフェードイン・フェードアウトを、通常のアイテムごとのアルファブレンディングに見られるような重なりによるアーティファクトなしに行うことができます。 以下は、レイヤーを有効にした場合の同じ例です：

Item {
    id: layered

    opacity: 0.5

    layer.enabled: true

    width: 100
    height: 100

    Rectangle { width: 80; height: 80; border.width: 1 }
    Rectangle { x: 20; y: 20; width: 80; height: 80; border.width: 1 }
}

ShaderEffectsとの組み合わせ

layer.enabled をtrueに設定すると、アイテムはtexture provider となり、例えばShaderEffect タイプと組み合わせて、そのアイテムをテクスチャとして直接使用できるようになります。

`layer.effect` を使用することで、実行時にレイヤーにエフェクトを適用することが可能です：

Item {
    id: layerRoot
    layer.enabled: true
    layer.effect: ShaderEffect {
        fragmentShader: "effect.frag.qsb"
    }
}

エフェクトの使用に関する詳細については、ShaderEffect を参照してください。

メモリとパフォーマンス

アイテムのレイヤーが有効になると、シーングラフはwidth x height x 4 と同等のメモリを GPU 上に割り当てます。メモリが制限される環境では、大規模なレイヤーの使用には注意が必要です。

QPainter /QWidget を使用する場合、複雑なコンテンツをピクマップ、画像、またはテクスチャにキャッシュすることが望ましい場合があります。Qt Quick では、シーングラフレンダラーによって既に適用されている技術のため、ほとんどの場合、そうする必要はありません。 バッチ処理によって過剰な描画呼び出しはすでに削減されており、キャッシュを使用すると、ほとんどの場合、元のコンテンツよりも多くのピクセルをブレンドすることになってしまいます。したがって、オフスクリーンへのレンダリングにかかるオーバーヘッドや、結果として得られるテクスチャを描画する際に伴うブレンド処理は、アイテムとその子要素を通常通り描画させるよりも、多くの場合、より大きな負荷となります。

また、レイヤーを使用しているアイテムは、レンダリング中にバッチ処理することができません。つまり、レイヤー化されたアイテムが多数存在するシーンでは、パフォーマンス上の問題が発生する可能性があります。

レイヤー機能は視覚効果の面で便利で有用ですが、ほとんどの場合、エフェクトの再生中のみ有効にし、終了後は無効にするべきです。

プロパティのドキュメント

activeFocus : bool [read-only]

この読み取り専用プロパティは、そのアイテムがアクティブなフォーカスを持っているかどうかを示します。

activeFocusがtrueの場合、このアイテムが現在キーボード入力を受けているか、あるいは現在キーボード入力を受けているアイテムのFocusScope の祖先であるかのいずれかです。

通常、activeFocus は、アイテムおよびそれを囲むFocusScope オブジェクトにfocus を設定することで取得されます。次の例では、input およびfocusScope オブジェクトはアクティブなフォーカスを持ちますが、ルート矩形オブジェクトは持ちません。

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: focusScope
        focus: true

        TextInput {
            id: input
            focus: true
        }
    }
}

『Qt Quick 』の「 focus 」 および「Keyboard Focus」も参照してください 。

activeFocusOnTab : bool

このプロパティは、そのアイテムがタブフォーカスチェーンに含まれるかどうかを指定します。デフォルトでは、false に設定されています。

タブフォーカスチェーンは、まず親要素を訪問し、次に `children` プロパティに指定された順序で子要素を順に訪問することで、要素を順にたどります。タブフォーカスチェーン内の項目で Tab キーを押すと、キーボードフォーカスがチェーン内の次の項目に移動します。BackTab キー（通常は Shift+Tab）を押すと、フォーカスが前の項目に移動します。

手動でタブフォーカスチェーンを設定するには、KeyNavigation を参照してください。Keys またはKeyNavigation で使用される Tab キーイベントは、フォーカスチェーンの動作よりも優先されます。フォーカスが伝播するようにするには、他のキーハンドラでのイベントを無視してください。

「 QStyleHints::tabFocusBehavior 」および「focusPolicy 」も参照してください 。

anchors group

アンカーは、他のアイテムとの関係を指定することで、アイテムの位置を決定する方法を提供します。

マージンは、top、bottom、left、right、および fill アンカーに適用されます。anchors.margins プロパティを使用すると、さまざまなマージンをすべて一度に同じ値に設定できます。これは、以前に設定された特定のマージンを上書きすることはありません。明示的に設定されたマージンをクリアするには、その値をundefined に設定してください。マージンはアンカーごとに設定されるものであり、アイテムがアンカーを使用していない場合は適用されないことに注意してください。

オフセットは、水平中央、垂直中央、およびベースラインのアンカーに適用されます。

Item {
    Image {
        id: pic
        // ...
    }
    Text {
        id: label
        anchors.horizontalCenter: pic.horizontalCenter
        anchors.top: pic.bottom
        anchors.topMargin: 5
        // ...
    }
}

Item {
    Image {
        id: pic
        // ...
    }
    Text {
        id: label
        anchors.left: pic.right
        anchors.leftMargin: 5
        // ...
    }
}

anchors.fill これは、あるアイテムのジオメトリを別のアイテムと同じにする便利な方法であり、4つの方向アンカーすべてを接続することと同等です。

アンカー値をクリアするには、undefined に設定します。

anchors.alignWhenCentered (デフォルトは `true`) は、中央揃えのアンカーをピクセル単位に揃えるように強制します。中央揃えされる項目の `width ` または `height` が奇数の場合、その項目は半ピクセル位置に配置されるのではなく、ピクセル単位の位置に配置されます。これにより、項目が鮮明に描画されます。 ただし、これが望ましくない場合もあります。例えば、アイテムを回転させる際、中心が丸みを帯びているためにジャッター（揺らぎ）が目立つことがあります。

詳細については、「アンカーレイアウト」を参照してください。

antialiasing : bool

ビジュアル要素が、そのアイテムにアンチエイリアシングを適用するかどうかを決定するために使用されます。場合によっては、アンチエイリアシングを適用したアイテムはより多くのメモリを必要とし、レンダリングに時間がかかる可能性があります（詳細については「アンチエイリアシング」を参照してください）。

デフォルトは false ですが、派生要素によって上書きされる場合があります。

baselineOffset : int

アイテムのベースラインの位置をローカル座標で指定します。

Text 項目のベースラインとは、テキストが配置される仮想の線です。テキストを含むコントロールは、通常、そのテキストのベースラインを自身のベースラインとして設定します。

テキスト以外のアイテムの場合、デフォルトのベースラインオフセットとして 0 が使用されます。

「children」プロパティには、このアイテムの視覚的な子要素のリストが含まれます。「resources」プロパティには、名前で参照したい非視覚的なリソースが含まれます。

子アイテムやリソースを追加する際、通常これらのプロパティを参照する必要はありません。デフォルトのdata プロパティにより、子オブジェクトが適切にchildren およびresources プロパティに自動的に割り当てられるためです。詳細については、data のドキュメントを参照してください。

childrenRect group

この読み取り専用プロパティには、アイテムの子要素の集合的な位置とサイズが格納されます。

このプロパティは、アイテムのサイズを正しく設定するために、その子要素の集合的なジオメトリにアクセスする必要がある場合に役立ちます。

返されるジオメトリは、そのアイテムに固有のものです。例：

Item {
    x: 50
    y: 100

    // prints: QRectF(-10, -20, 30, 40)
    Component.onCompleted: print(childrenRect)

    Item {
        x: -10
        y: -20
        width: 30
        height: 40
    }
}

clip : bool

このプロパティは、クリッピングが有効かどうかにかかわらず適用されます。デフォルトのクリップ値は `false` です。

クリッピングが有効になっている場合、アイテムは自身の描画および子要素の描画を、そのバウンディング矩形内に切り取ります。

containmentMask : QObject*

このプロパティは、contains() メソッドで使用されるアイテムのオプションのマスクを保持します。現在の主な用途は、pointer event がアイテム内に着地したかどうかを判定することです。

デフォルトでは、contains() メソッドは、Itemのバウンディングボックス内の任意の点に対してtrueを返します。containmentMask を使用することで、よりきめ細かな制御が可能になります。例えば、contains()メソッドを特化したカスタムC++のQQuickItem サブクラスをcontainmentMaskとして使用する場合：

Item { id: item; containmentMask: AnotherItem { id: anotherItem } }

その場合、アイテムの`contains` メソッドは、`anotherItem` の`contains()` の実装が `true` を返す場合にのみ、`true ` を返します。

Shape をマスクとして使用することで、アイテムが非矩形領域内でのみpointer events に反応するようにすることができます:

Rectangle { width: 90; height: 100 color: hoverHandler.hovered ? "wheat" : "lightgray" containmentMask: shape HoverHandler { id: hoverHandler } Shape { id: shape containsMode: Shape.FillContains ShapePath { fillColor: "lightsteelblue" startX: 10; startY: 20 PathArc { x: 10; y: 80 radiusX: 40; radiusY: 40 useLargeArc: true } PathLine { x: 10; y: 20 } } } }

また、QML内でcontainsメソッドを定義することも可能です。例えば、実際の境界内でのみイベントに応答する円形のアイテムを作成するには：

Rectangle { id: circle width: 100; height: width radius: width / 2 color: tapHandler.pressed ? "tomato" : hoverHandler.hovered ? "darkgray" : "lightgray" TapHandler { id: tapHandler } HoverHandler { id: hoverHandler } containmentMask: QtObject { property alias radius: circle.radius function contains(point: point) : bool { return (Math.pow(point.x - radius, 2) + Math.pow(point.y - radius, 2)) < Math.pow(radius, 2) } } }

「Qt Quick の例 - 図形」も参照してください 。

data : list<QtObject> [default]

「data」プロパティを使用すると、アイテム内でビジュアル子要素とリソースを自由に組み合わせることができます。データリストにビジュアルアイテムを割り当てると、それは子要素となり、その他のオブジェクトタイプを割り当てると、リソースとして追加されます。

したがって、次のように記述できます：

Item {
    Text {}
    Rectangle {}
    Timer {}
}

次のように記述します：

Item {
    children: [
        Text {},
        Rectangle {}
    ]
    resources: [
        Timer {}
    ]
}

通常、data プロパティを明示的に参照する必要はありません。これはItemのデフォルトプロパティであるため、すべての子アイテムが自動的にこのプロパティに割り当てられるからです。

enabled : bool

このプロパティは、そのアイテムがマウスおよびキーボードのイベントを受け取るかどうかを指定します。デフォルトでは、true に設定されています。

false に設定すると、アイテムはキー押下、キー離し、クリックなどのキーボードやポインティングデバイスのイベントを受け取らなくなりますが、ホバーイベントは引き続き受け取ることができます。

このプロパティを設定すると、子項目のenabled 値に直接影響します。false に設定すると、すべての子項目のenabled 値もfalse になります。true に設定すると、子項目のenabled 値は、明示的にfalse に設定されていない限り、true に戻ります。

このプロパティをfalse に設定すると、自動的にactiveFocus がfalse に設定され、このアイテムはキーボードイベントを受け取らなくなります。

「visible」も参照してください 。

focus : bool

このプロパティは、そのアイテムが、それを囲むFocusScope 内でフォーカスを持っているかどうかを指定します。trueの場合、囲むFocusScope がアクティブなフォーカスを獲得した際に、このアイテムもアクティブなフォーカスを獲得します。

次の例では、scope がアクティブなフォーカスを獲得すると、input にもアクティブなフォーカスが与えられます:

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: scope

        TextInput {
            id: input
            focus: true
        }
    }
}

このプロパティに関しては、シーン全体がフォーカススコープのように動作すると見なされます。実用上、これは以下の QML が起動時に `input ` にアクティブなフォーカスを与えることを意味します。

Rectangle {
    width: 100; height: 100

    TextInput {
          id: input
          focus: true
    }
}

「 activeFocus 」 および「 Qt Quick 」の「Keyboard Focus」も参照してください 。

focusPolicy : enumeration [since 6.7]

このプロパティは、アイテムがフォーカスを受け取る方法を決定します。

このプロパティは、Qt 6.7で導入されました。

項目の位置とサイズを指定します。デフォルト値は0 です。

(x,y) の位置は、parent を基準としています。

Item { x: 100; y: 100; width: 100; height: 100 }

アイテムの推奨幅または高さを指定します。

width またはheight が指定されていない場合、項目の実効サイズはimplicitWidth またはimplicitHeight によって決定されます。

ただし、アイテムがレイアウトの子要素である場合、レイアウトはその暗黙的なサイズを使用してアイテムの優先サイズを決定します。このような場合、明示的に指定されたwidth またはheight は無視されます。

ほとんどのアイテムのデフォルトの暗黙的なサイズは 0x0 ですが、Image やText など、上書きできない固有の暗黙的なサイズを持つアイテムもあります。

暗黙のサイズを設定することは、コンテンツに基づいて推奨サイズを持つコンポーネントを定義するのに役立ちます。例：

// Label.qml
import QtQuick 2.0

Item {
    property alias icon: image.source
    property alias label: text.text
    implicitWidth: text.implicitWidth + image.implicitWidth
    implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
    Image { id: image }
    Text {
        id: text
        wrapMode: Text.Wrap
        anchors.left: image.right; anchors.right: parent.right
        anchors.verticalCenter: parent.verticalCenter
    }
}

layer.effect : Component

このレイヤーに適用されるエフェクトを保持します。

エフェクトは通常、ShaderEffect コンポーネントですが、Item コンポーネントであればどれでも割り当てることができます。エフェクトには、layer.samplerName という名前のソーステクスチャプロパティが設定されている必要があります。

「 layer.samplerName 」および「Item Layers 」も参照してください 。

layer.enabled : bool

このプロパティは、アイテムがレイヤー化されているかどうかを指定します。デフォルトでは、レイヤー化は無効になっています。

レイヤー化されたアイテムは、オフスクリーンサーフェスにレンダリングされ、変更されるまでキャッシュされます。複雑な QML アイテム階層に対してレイヤー化を有効にすると、場合によってはパフォーマンスの最適化につながることもあります。

レイヤーが無効になっている場合、他のレイヤープロパティはいずれも効果を発揮しません。

Item Layersも参照してください 。

layer.format : enumeration

このプロパティは、バッキングテクスチャの形式を定義します。このプロパティを変更するのは、layer.effect も指定されている場合に最も意味があります。

Item Layersも参照してください 。

layer.live : bool [since 6.5]

このプロパティが true の場合、アイテムが更新されるたびにレイヤーのテクスチャが更新されます。そうでない場合は、常に固定された画像のままになります。

デフォルトでは、このプロパティは `true` に設定されています。

このプロパティはQt 6.5で導入されました。

「Item Layers」も参照してください 。

layer.mipmap : bool

このプロパティがtrueの場合、そのテクスチャに対してミップマップが生成されます。

Item Layersも参照してください 。

layer.samplerName : string

エフェクトのソーステクスチャプロパティの名前を保持します。

この値は、アイテムがレイヤーのオフスクリーンサーフェスをエフェクトに正しく渡せるように、エフェクトのソーステクスチャプロパティ名と一致している必要があります。

関連項目 ：layer.effect 、ShaderEffect 、およびItem Layersも参照してください 。

layer.samples : enumeration

このプロパティを使用すると、レイヤー内でマルチサンプリングによるレンダリングを要求することができます。

デフォルトでは、使用中のシーングラフレンダラーおよび基盤となるグラフィックスAPIがこれをサポートしている場合、ウィンドウ全体でマルチサンプリングが有効になっているときは常に、このレイヤーでもマルチサンプリングが有効になります。

この値を 2、4 などに設定することで、シーン全体でマルチサンプリングを有効にすることなく、シーンの一部に対してマルチサンプリングによるレンダリングを要求することができます。これにより、マルチサンプリングは指定されたサブツリーにのみ適用されるため、シーンの他の部分にはマルチサンプリングが適用されないため、パフォーマンスが大幅に向上する可能性があります。

layer.smooth : bool

このレイヤーが滑らかに変形されるかどうかを指定します。有効にすると、レイヤーのテクスチャのサンプリングはlinear 補間を使用して行われますが、無効にするとnearest フィルタリングモードが使用されます。

デフォルトでは、このプロパティは「false 」に設定されています。

「Item Layers」も参照してください 。

layer.sourceRect : rect

このプロパティは、テクスチャにレンダリングされる項目の矩形領域を定義します。ソースの矩形は、項目自体よりも大きくてもかまいません。矩形が null の場合（これがデフォルトです）、項目全体がテクスチャにレンダリングされます。

「Item Layers」も参照してください 。

layer.textureMirroring : enumeration

このプロパティは、生成されたテクスチャのミラーリング方法を定義します。デフォルト値は `ShaderEffectSource.MirrorVertically` です。ShaderEffect で指定されるようなカスタムシェーダーから生成されたテクスチャに直接アクセスする場合、カスタムミラーリングが役立つことがあります。レイヤー化されたアイテムに対して効果が指定されていない場合、ミラーリングはアイテムの UI 上の表示には影響しません。

layer.textureSize : size

このプロパティには、レイヤーのテクスチャの指定されたピクセルサイズが格納されます。空の場合（これがデフォルトです）、アイテムのサイズが使用されます。

関連項目: Item Layers 。

layer.wrapMode : enumeration

このプロパティは、テクスチャに関連付けられたラップモードを定義します。このプロパティを変更するのは、layer.effect が指定されている場合に最も意味があります。

Item Layersも参照してください 。

mutabilityGroup : int [since 6.12]

これは、低レベルの最適化に使用できる高度なプロパティです。これは、アイテムがどのくらいの頻度で更新されるかについて、レンダラーへのヒントとして機能します。一般的な使用例では、このプロパティをデフォルト値（Item.AutoMutabilityGroup （0 ））のままにしておけば十分です。

しかし、場合によっては、パフォーマンス分析を行うことで、Qt Quick シーングラフ・レンダラーのデフォルト動作では最適化できなかったボトルネックが明らかになることがあります。 これは通常、頻繁に更新されるジオメトリが静的なジオメトリとまとめてバッチ処理される場合に発生します。これを回避するには、例えば、頻繁に更新されるコンポーネントを `Item.DynamicMutabilityGroup` に割り当てることを試みてください。異なる可変性グループに属するジオメトリは、まとめてバッチ処理されません。

可変性グループはアイテム自体にのみ適用され、子要素には波及しません。

Qt Quick シーングラフレンダラーの内部動作およびジオメトリのバッチ処理に関する詳細については、「Qt Quick シーングラフデフォルトレンダラー」を参照してください。

定義済み値：

このプロパティは Qt 6.12 で導入されました。

opacity : real

このプロパティは、アイテムの不透明度を保持します。不透明度は、0.0（完全に透明）から 1.0（完全に不透明）までの数値で指定されます。デフォルト値は 1.0 です。

このプロパティを設定すると、指定された不透明度は子アイテムにも個別に適用されます。これにより、状況によっては意図しない結果が生じる場合があります。たとえば、以下の2番目の矩形群では、赤い矩形に不透明度0.5が指定されていますが、その子である青い矩形には不透明度が指定されていないにもかかわらず、赤い矩形の不透明度が青い矩形にも影響しています。

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Item {
    Rectangle {
        opacity: 0.5
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

項目の不透明度を変更しても、その項目がユーザー入力イベントを受け取るかどうかには影響しません。（対照的に、visible プロパティをfalse に設定するとマウスイベントが停止し、enabled プロパティをfalse に設定するとマウスおよびキーボードイベントが停止し、さらにその項目からアクティブなフォーカスが外れます。）

「visible」も参照してください 。

palette : Palette [since 6.0]

このプロパティには、そのアイテムに現在設定されているパレットが格納されます。

このプロパティは、アイテムに要求されたパレットを表します。このパレットは、すべてのコントロールをレンダリングする際にアイテムのスタイルで使用され、カスタムコントロールがネイティブプラットフォームのルックアンドフィールとの一貫性を維持するための手段として利用できます。アプリケーションに対して、プラットフォームやスタイルが異なると、定義されるパレットも異なることが一般的です。

デフォルトのパレットはシステム環境によって異なります。ApplicationWindow は、すべてのコントロールのデフォルトとして機能するシステム／テーマパレットを保持しています。また、特定の種類のコントロールに対して特別なデフォルトパレットが設定されている場合もあります。コントロールのデフォルトパレットは、次のいずれかの方法で設定できます。

• QMLを読み込む前に、QGuiApplication::setPalette() に関数を呼び出し、カスタムパレットを渡すか、
• qtquickcontrols2.conf ファイルで色を指定する。

アイテムは、親から子へと明示的なパレットプロパティを伝播します。アイテムのパレットにある特定のプロパティを変更すると、そのプロパティはアイテムのすべての子に伝播され、そのプロパティに関するシステムのデフォルト設定を上書きします。

Item {
    palette {
        buttonText: "maroon"
        button: "lavender"
    }

    Button {
        text: "Click Me"
    }
}

このプロパティは Qt 6.0 で導入されました。

Window::palette 、Popup::palette 、ColorGroup 、Palette 、およびSystemPaletteも参照してください 。

parent : Item

このプロパティは、アイテムの視覚的な親を保持します。

rotation : real

このプロパティは、アイテムのtransformOrigin を中心に、時計回りに度単位で回転した角度を保持します。

デフォルト値は 0 度（つまり、回転なし）です。

Rectangle {
    color: "blue"
    width: 100; height: 100
    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        rotation: 30
    }
}

「 Transform 」および「Rotation 」も参照してください 。

scale : real

このプロパティには、この項目のスケール係数が格納されます。

スケール値が 1.0 未満の場合、アイテムはより小さいサイズでレンダリングされ、1.0 より大きい場合はより大きいサイズでレンダリングされます。スケール値が負の場合、アイテムはレンダリング時に反転表示されます。

デフォルト値は 1.0 です。

スケーリングは、transformOrigin から適用されます。

import QtQuick 2.0

Rectangle {
    color: "blue"
    width: 100; height: 100

    Rectangle {
        color: "green"
        width: 25; height: 25
    }

    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        scale: 1.4
        transformOrigin: Item.TopLeft
    }
}

「 Transform 」および「Scale 」も参照してください 。

smooth : bool

主に画像ベースのアイテムで使用され、そのアイテムでスムースサンプリングを使用するかどうかを決定します。スムースサンプリングは線形補間を用いて行われ、非スムースサンプリングは最近傍法を用いて行われます。

Qt Quick 2.0 では、このプロパティがパフォーマンスに与える影響はごくわずかです。

デフォルトでは、このプロパティは「true 」に設定されています。

state : string

このプロパティには、アイテムの現在の状態の名前が格納されます。

アイテムがデフォルトの状態、つまり明示的な状態が設定されていない場合、このプロパティには空の文字列が格納されます。同様に、このプロパティを空の文字列に設定することで、アイテムをデフォルトの状態に戻すことができます。

「Qt Quick 」の状態も参照してください 。

states : list<State>

このプロパティには、このアイテムの可能な状態のリストが格納されています。このアイテムの状態を変更するには、state プロパティをこれらの状態のいずれかに設定するか、state プロパティを空の文字列に設定して、アイテムをデフォルトの状態に戻します。

このプロパティは、State オブジェクトのリストとして指定されます。たとえば、以下は「red_color」および「blue_color」という状態を持つアイテムです。

import QtQuick 2.0

Rectangle {
    id: root
    width: 100; height: 100

    states: [
        State {
            name: "red_color"
            PropertyChanges { root.color: "red" }
        },
        State {
            name: "blue_color"
            PropertyChanges { root.color: "blue" }
        }
    ]
}

状態および遷移の使用方法の詳細については、『Qt Quick 』の「状態」および『 Qt Quick 』の「アニメーションと遷移」を参照してください。

「transitions」も参照してください 。

transform : list<Transform> [read-only]

このプロパティには、適用する変換のリストが格納されます。

このプロパティは、Transform から派生したオブジェクトのリストとして指定されます。例：

import QtQuick

Image {
    source: "images/qt-logo.png"
    transform: [
        Scale { origin.x: 25; origin.y: 25; xScale: 1.25 },
        Rotation { origin.x: 45; origin.y: 55; angle: 45 }
    ]
}

詳細については、Transform を参照してください。

transformOrigin : enumeration

このプロパティは、拡大縮小および回転の変換が行われる原点を指定します。

下の画像に示すように、9つの変換原点が利用可能です。デフォルトの変換原点はItem.Center です。

この例では、画像を右下隅を基準に回転させています。

Image {
    source: "myimage.png"
    transformOrigin: Item.BottomRight
    rotation: 45
}

任意の変換原点を設定するには、`Scale ` または `Rotation ` の変換タイプを、`transform` と組み合わせて使用します。

transitions : list<Transition>

このプロパティには、このアイテムの遷移のリストが格納されます。これらは、アイテムの「state 」が変更されるたびに、そのアイテムに適用される遷移を定義します。

このプロパティは、Transition オブジェクトのリストとして指定されます。例：

import QtQuick 2.0

Item {
    transitions: [
        Transition {
            //...
        },
        Transition {
            //...
        }
    ]
}

状態と遷移の使用方法の詳細については、『Qt Quick』の「Qt Quick States」および「Animation and Transitions」を参照してください。

「states」も参照してください 。

visible : bool

このプロパティは、アイテムが表示されるかどうかを指定します。デフォルトでは true です。

このプロパティを設定すると、子項目のvisible 値に直接影響します。false に設定すると、すべての子項目のvisible 値もfalse になります。true に設定すると、子項目のvisible 値は、明示的にfalse に設定されていない限り、true に戻ります。

（この連鎖的な動作のため、プロパティのバインディングが明示的なプロパティ変更にのみ反応すべき場合、visible プロパティを使用しても意図した効果が得られない可能性があります。そのような場合は、代わりにopacity プロパティを使用する方が適切かもしれません。）

このプロパティが `false` に設定されている場合、そのアイテムはマウスイベントを受け取らなくなりますが、キーイベントは引き続き受け取り、キーボードの `focus ` が設定されている場合はその状態を維持します。（対照的に、`enabled ` プロパティを `false ` に設定すると、マウスイベントとキーボードイベントの両方が停止し、アイテムからのフォーカスも解除されます。）

「 opacity 」および「enabled 」も参照してください 。

visibleChildren : list<Item>

この読み取り専用プロパティは、現在表示されているそのアイテムの子要素をすべて一覧表示します。なお、子要素の表示状態は、明示的に変更された場合や、このアイテム（その親）または別の祖先の表示状態が変更されたことによって、変化している可能性があることに注意してください。

z : real

兄弟アイテムの重ね順を設定します。デフォルトの重ね順は 0 です。

スタック値が大きいアイテムは、スタック順序が小さい兄弟アイテムの上に描画されます。スタック値が同じアイテムは、出現順に上から下に描画されます。スタック値が負のアイテムは、親要素のコンテンツの下に描画されます。

次の例は、重ね順によるさまざまな効果を示しています。

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Item {
    Rectangle {
        z: 1
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            z: -1
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

メソッドのドキュメント

Item childAt(real x, real y)

このアイテムの座標系において、ポイント (x,y) で検出された、最初に表示されている子アイテムを返します。

そのような項目が存在しない場合は、null を返します。

bool contains(point point)

このアイテムにローカル座標系のpoint が含まれている場合はtrue を返し、それ以外の場合はfalse を返します。これは、イベント配信時にQEventPoint のヒットテストに使用されるものと同じチェックであり、containmentMask が設定されている場合はその影響を受けます。

[since 6.3] void dumpItemTree()

このアイテムとその子アイテムを起点として、アイテムのビジュアルツリーに関する詳細情報を再帰的に出力します。

出力は、以下のQMLコードの出力と似たようなものになります：

function dump(object, indent) {
    console.log(indent + object)
    for (const i in object.children)
        dump(object.children[i], indent + "    ")
}

dump(myItem, "")

したがって、より詳細な情報を得たい場合は、独自の関数を実装し、特定のプロパティの値など、追加の出力を `console.log` に記述することができます。

このメソッドは Qt 6.3 で導入されました。

QObject::dumpObjectTree()も参照してください 。

void forceActiveFocus()

そのアイテムにアクティブなフォーカスを設定します。

このメソッドは、アイテムにフォーカスを設定し、オブジェクト階層内のすべての親オブジェクトであるFocusScope オブジェクトに対してもfocus が呼び出されるようにします。

フォーカスの変更理由は `Qt::OtherFocusReason` となります。フォーカスの変更をより適切に処理するために、オーバーロードされたメソッドを使用してフォーカスの理由を指定してください。

「activeFocus」も参照してください 。

void forceActiveFocus(Qt::FocusReason reason)

指定されたreason を持つアイテムにアクティブなフォーカスを設定します。

このメソッドは、そのアイテムにフォーカスを設定し、オブジェクト階層内のすべての親FocusScope オブジェクトにもfocus が設定されるようにします。

activeFocus およびQt::FocusReasonも参照してください 。

bool grabToImage(callback, targetSize)

アイテムをメモリ内のイメージに取り込みます。

取得処理は非同期で行われ、取得が完了すると JavaScript 関数 `callback ` が呼び出されます。このコールバックには、取得処理の結果である `ItemGrabResult ` オブジェクトが 1 つの引数として渡されます。

targetSize を使用して、対象画像のサイズを指定します。デフォルトでは、結果はアイテムと同じサイズになります。

キャプチャを開始できなかった場合、この関数は `false` を返します。

以下のコードスニペットは、アイテムを取得し、その結果をファイルに保存する方法を示しています：

Rectangle {
    id: sourceRectangle
    width: 100
    height: 100
    focus: true
    gradient: Gradient {
        GradientStop { position: 0; color: "steelblue" }
        GradientStop { position: 1; color: "black" }
    }

    Keys.onSpacePressed: {
        sourceRectangle.grabToImage(function(result) {
           result.saveToFile("something.png")
        })
    }
}

以下のスニペットは、アイテムをキャプチャし、その結果を別の画像要素で使用する方法を示しています：

Image {
    id: image
}

Keys.onSpacePressed: {
    sourceRectangle.grabToImage(function(result) {
        image.source = result.url
    }, Qt.size(50, 50))
}

point mapFromGlobal(real x, real y)

グローバル座標系上の点（x 、y ）をアイテムの座標系にマッピングし、マッピングされた座標に対応するpoint を返します。

マッピングには、アイテムの以下のプロパティが使用されます：x 、y 、scale 、rotation 、transformOrigin 、およびtransform 。

アイテムが異なるシーンに属している場合、マッピングには2つのシーン間の相対位置が含まれます。

item の座標系にある点 (x,y) または矩形 (x,y,width,height) を、この項目の座標系に変換し、変換後の座標に対応するpoint またはrect を返します。

マッピングには、アイテムの以下のプロパティが使用されます：x 、y 、scale 、rotation 、transformOrigin 、およびtransform 。

アイテムが異なるシーンに属している場合、マッピングには2つのシーン間の相対位置が含まれます。

item がnull の値である場合、シーンの座標系からの点または矩形がマッピングされます。

point および rect を引数として受け付けるバージョンは、Qt 5.15 以降です。

point mapToGlobal(real x, real y)

この項目の座標系にある点（x 、y ）をグローバル座標系にマッピングし、マッピングされた座標に対応するpoint を返します。

マッピングには、アイテムの以下のプロパティが使用されます：x 、y 、scale 、rotation 、transformOrigin 、およびtransform 。

アイテムが異なるシーンに属している場合、マッピングには2つのシーン間の相対的な位置情報が含まれます。

この項目の座標系にある点（x 、y ）または矩形（x 、y 、width 、height ）を、item の座標系にマッピングし、マッピングされた座標に対応するpoint またはrect を返します。

マッピングには、アイテムの以下のプロパティが使用されます：x 、y 、scale 、rotation 、transformOrigin 、およびtransform 。

アイテムが異なるシーンに属している場合、マッピングには2つのシーン間の相対位置が含まれます。

item がnull の値である場合、このマッピングにより、点または矩形がシーンの座標系にマッピングされます。

point および rect を引数として受け付けるバージョンは、Qt 5.15 以降です。

Item nextItemInFocusChain(bool forward)

フォーカスチェーン内の、この項目の隣にある項目を返します。forward がtrue の場合、または指定されていない場合は、前方方向の次の項目が返されます。forward がfalse の場合、後方方向の次の項目が返されます。