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
• 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タイプは1つのルートビジュアルアイテムの下に複数のア イテムをグループ化するのに便利です。例えば

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"
    }
}

イベント処理

すべてのアイテムベースのビジュアルタイプは入力ハンドラ（QInputEvent のサブクラス）を使用して、マウス、タッチ、キーイベントなどの入力イベントを処理できます。これはイベントを処理するための好ましい宣言的な方法です。

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

同様に、QQuickItem サブクラスは、setAcceptedMouseButtons() を呼び出してマウス・ボタン・イベントを受け取るように登録し、setAcceptHoverEvents() を呼び出してホバー・イベント（ボタンが押されていない間のマウスの動き）を受け取り、仮想関数 mousePressEvent()、mouseMoveEvent()、mouseReleaseEvent() をオーバーライドすることができます。grab それらはまた、それ以上の配信を防ぐためにイベントを受け入れ、同時に暗黙のグラブを取得することができます;または明示的にQMouseEvent 、単一のQEventPoint 。

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

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 attachedプロパティを使用してミラーリングすることができます。これにより、anchors は水平方向に反転され、また、子アイテムをレイアウトまたは配置するアイテム（ListView やRow など）も水平方向に反転されます。

詳しくはLayoutMirroring を参照してください。

アイテムのレイヤー

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

アイテムのテクスチャサイズと異なるテクスチャサイズが必要な場合は、layer.textureSize を使用することで可能です。アイテムの一部分だけをテクスチャに描画するには、layer.sourceRect を使います。また、layer.sourceRect を指定して、アイテムの境界を超えるようにすることも可能です。この場合、外側は透明ピクセルでパディングされます。

layer.smooth がtrue に設定されている場合、アイテムはスケーリングに線形補間を使用し、layer.mipmap がtrue に設定されている場合、ダウンサンプリングにミップマップを使用します。ミップマッピングは、ダウンスケールされたアイテムの視覚的な品質を向上させる可能性があります。単一の画像アイテムのミップマッピングには、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 の世界では、複雑なコンテンツを pixmap、画像、またはテクスチャにキャッシュするのが有利な場合があります。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
        }
    }
}

focus と Qt Quick のキーボード・フォーカスも参照してください 。

activeFocusOnTab : bool

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

タブ・フォーカスの連鎖は、最初に親を訪れ、次にその子を children プロパティで指定された順番に訪れ、要素を走査します。タブ・フォーカスの連鎖のある項目でタブキーを押すと、キーボード・フォーカスが連鎖の次の項目に移動します。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

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

デフォルトは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()メソッドで使用するItemのオプションのマスクを保持する。このプロパティの主な用途は、現在のところ、pointer event がアイテムに着地したかどうかを判定することです。

デフォルトでは、contains() メソッドは、Item のバウンディングボックス内のどの点に対しても真を返します。containmentMask は、より細かい制御を可能にします。たとえば、専用のcontains() メソッドを持つカスタム C++QQuickItem サブクラスが、containmentMask として使用されている場合：

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

itemのcontainsメソッドは、otherItemの 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 Examples - Shapesも参照してください 。

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 に設定すると、明示的にfalse に設定されていない限り、子アイテムのenabled 値は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 のキーボードフォーカスも参照してください 。

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

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

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

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も参照してください 。

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 Stateも参照してください 。

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-derived オブジェクトのリストとして指定されます。例えば

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も参照してください 。

visible : bool

このプロパティは、アイテムが可視であるかどうかを保持する。デフォルトでは true です。

このプロパティを設定すると、子アイテムのvisible 値に直接影響します。false に設定すると、すべての子アイテムのvisible 値もfalse になります。true に設定すると、明示的にfalse に設定されていない限り、子アイテムのvisible の値は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()

このアイテムとその子から始まるItemのビジュアルツリーの詳細を再帰的にダンプします。

出力はこの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 が呼び出されます。コールバックは1つの引数を取り、グラブ操作の結果であるItemGrabResult オブジェクトを受け取ります。

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 要素で使用する方法を示しています：

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 をマッピングする。

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 をシーンの座標系にマップする。

point と rect を受け付けるバージョンは Qt 5.15 以降です。

Item nextItemInFocusChain(bool forward)

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