QML文書によるオブジェクトタイプの定義

QMLの中核的な特徴の1つは、QMLアプリケーションのニーズに合わせて、 QMLドキュメントを通してQMLオブジェクトの型を軽量な方法で簡単に定義できることです。標準のQt Quickモジュールでは、QML アプリケーションを構築するためのRectangle 、Text 、Image といった様々な型が提供されています。これらの型以外にも、アプリケーション内で再利用する独自の QML 型を簡単に定義することができます。このように独自の型を作成する機能は、あらゆるQMLアプリケーションの構成要素となります。

QMLファイルによるオブジェクト型の定義

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

オブジェクトタイプを作成するには、QML文書を<TypeName>.qmlという名前のテキストファイルに記述します。型名には次のような条件があります：

• 英数字かアンダースコアであること。
• 大文字で始まること。

この文書がQMLの型定義として自動的に認識されます。また、このようにして定義された型は、QMLの型名を解決する際に、同じローカルディレクトリ内にある他のQMLファイルからも自動的に利用できるようになります。

カスタムQMLタイプ定義

例えば、Rectangle とその子MouseArea を宣言したドキュメントを以下に示します。このドキュメントは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 x 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 を参照することはできません。また、squareButton ではなくroot のid を持っていたとしても、SquareButton.qml で定義されたルートオブジェクトの同じ値のid と衝突することはありません。