QMLドキュメントを用いたオブジェクト型の定義

QMLの主要な機能の一つは、個々のQMLアプリケーションのニーズに合わせて、QMLドキュメントを通じて軽量かつ容易にQMLオブジェクト型を定義できることです。標準の Qt Quick モジュールは、QMLアプリケーションを構築するためのRectangle 、Text 、Image といったさまざまな型を提供しています。これらに加え、アプリケーション内で再利用可能な独自のQML型を簡単に定義することもできます。独自の型を作成できるこの機能こそが、あらゆるQMLアプリケーションの基盤となっています。

QMLファイルを使用したオブジェクト型の定義

カスタム QML オブジェクト型の命名

オブジェクト型を作成するには、QMLドキュメントを<TypeName>.qmlという名前のテキストファイルに記述します。ここで、<TypeName>はその型の希望する名前です。型名には以下の要件があります：

• 英数字またはアンダースコアで構成されている必要があります。
• 大文字で始まる必要があります。

このドキュメントは、エンジンによって自動的に QML 型の定義として認識されます。さらに、この方法で定義された型は、QML 型名の解決時にエンジンが直下のディレクトリ内を検索するため、同じローカルディレクトリ内にある他の QML ファイルから自動的に利用可能になります。

カスタム QML 型の定義

たとえば、以下は、子要素として `MouseArea` を持つ `Rectangle ` を宣言するドキュメントです。このドキュメントは、SquareButton.qml という名前のファイルに保存されています：

// SquareButton.qml
import QtQuick 2.0

Rectangle {
    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("Button clicked!")
    }
}

ファイル名がSquareButton.qml であるため、同じディレクトリ内の他の QML ファイルから、これをSquareButton という名前の型として使用できるようになります。たとえば、同じディレクトリにmyapplication.qml というファイルがある場合、そのファイルではSquareButton 型を参照することができます:

// myapplication.qml
import QtQuick 2.0

SquareButton {}

これにより、SquareButton.qml で定義されているように、内部にMouseArea を持つ100×100の赤いRectangle が作成されます。このmyapplication.qml ドキュメントがエンジンによって読み込まれると、SquareButton.qmlドキュメントがコンポーネントとして読み込まれ、インスタンス化されてSquareButton オブジェクトが作成されます。

SquareButton 型は、SquareButton.qml で宣言されたQMLオブジェクトのツリーをカプセル化しています。QMLエンジンがこの型からSquareButton オブジェクトをインスタンス化すると、SquareButton.qml で宣言されたRectangle ツリーからオブジェクトがインスタンス化されます。

インラインコンポーネント

場合によっては、タイプごとに新しいファイルを作成するのが不便なこともあります。たとえば、小さなデリゲートを複数のビューで再利用する場合などです。実際にタイプを公開する必要がなく、インスタンスを作成するだけでよい場合は、Component を使用するという選択肢があります。 しかし、コンポーネント型でプロパティを宣言したい場合や、複数のファイルでそれを使用したい場合は、Component は選択肢になりません。その場合は、インラインコンポーネントを使用できます。インラインコンポーネントは、ファイル内で新しいコンポーネントを宣言します。その構文は次のとおりです。

component <component name> : BaseType {
    // declare properties and bindings here
}

インラインコンポーネントを宣言するファイル内では、その型を単に名前だけで参照できます。

// Images.qml
import QtQuick

Item {
    component LabeledImage: Column {
        property alias source: image.source
        property alias caption: text.text

        Image {
            id: image
            width: 50
            height: 50
        }
        Text {
            id: text
            font.bold: true
        }
    }

    Row {
        LabeledImage {
            id: before
            source: "before.png"
            caption: "Before"
        }
        LabeledImage {
            id: after
            source: "after.png"
            caption: "After"
        }
    }
    property LabeledImage selectedImage: before
}

他のファイルでは、それを含むコンポーネントの名前にプレフィックスを付ける必要があります。

// LabeledImageBox.qml
import QtQuick

Rectangle {
    property alias caption: image.caption
    property alias source: image.source
    border.width: 2
    border.color: "black"
    Images.LabeledImage {
        id: image
    }
}

// A.qml
import QtQuick

Item {
    id: root
    property string message: "From A"
    component MyInlineComponent : Item {
        Component.onCompleted: console.log(root.message)
    }
}
// B.qml
import QtQuick

Item {
    A.MyInlineComponent {}
}

現在のディレクトリ外で定義された型のインポート

SquareButton.qml がmyapplication.qml と同じディレクトリにない場合、SquareButton 型は、myapplication.qml 内のimport文を通じて明示的に利用可能にする必要があります。これは、ファイルシステム上の相対パスから、あるいはインストール済みのモジュールとしてインポートできます。詳細については、モジュールを参照してください。

カスタム型の利用可能な属性

.qmlファイル内のルートオブジェクトの定義は、QML 型で利用可能な属性を定義します。このルートオブジェクトに属するすべてのプロパティ、シグナル、およびメソッド（カスタムで宣言されたものであれ、ルートオブジェクトの QML 型に由来するものであれ）は外部からアクセス可能であり、この型のオブジェクトに対して読み取りや変更を行うことができます。

たとえば、前述のSquareButton.qml ファイルにおけるルートオブジェクト型はRectangle です。これは、Rectangle 型によって定義されたプロパティはすべて、SquareButton オブジェクトに対して変更可能であることを意味します。以下のコードは、SquareButton 型のルートオブジェクトRectangle のプロパティの一部について、カスタマイズされた値を持つ3つのSquareButton オブジェクトを定義しています：

// application.qml
import QtQuick 2.0

Column {
    SquareButton { side: 50 }
    SquareButton { x: 50; color: "blue" }
    SquareButton { radius: 10 }
}

カスタム QML 型のオブジェクトからアクセス可能な属性には、そのオブジェクトに対して追加で定義されたカスタムプロパティ、メソッド、シグナルが含まれます。たとえば、SquareButton.qml にある `Rectangle ` が、次のように追加のプロパティ、メソッド、シグナルを持って定義されていたとします:

// SquareButton.qml
import QtQuick 2.0

Rectangle {
    id: root

    property bool pressed: mouseArea.pressed

    signal buttonClicked(real xPos, real yPos)

    function randomizeColor() {
        root.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1)
    }

    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        onClicked: (mouse)=> root.buttonClicked(mouse.x, mouse.y)
    }
}

どのSquareButton オブジェクトも、ルートRectangle に追加されたpressed プロパティ、buttonClicked シグナル、およびrandomizeColor() メソッドを利用できます：

// application.qml
import QtQuick 2.0

SquareButton {
    id: squareButton

    onButtonClicked: (xPos, yPos)=> {
        console.log("Clicked", xPos, yPos)
        randomizeColor()
    }

    Text { text: squareButton.pressed ? "Down" : "Up" }
}

なお、SquareButton.qml で定義されたid の値は、SquareButton オブジェクトからはアクセスできません。これは、idの値はコンポーネントが宣言されたコンポーネントスコープ内からのみアクセス可能であるためです。 上記のSquareButton オブジェクトの定義では、MouseArea の子要素を参照するためにmouseArea を参照することはできません。また、もしid がsquareButton ではなくroot であったとしても、SquareButton.qml で定義されたルートオブジェクトのid と同じ値であっても、これらは別々のスコープ内で宣言されるため、競合は発生しません。