QMLの基礎 - カスタムQMLタイプ

概要

設計者は、既存のQMLタイプを使用して、独自の機能を追加したカスタムQMLタイプを作成することができる。

カスタムQMLタイプは、コンポーネントと呼ぶこともある。
コンポーネントとは、複数のQMLタイプをまとめて1つのQMLタイプとして扱う仕組みである。

カスタムQMLタイプ以外にも、Componentタイプを使用してコンポーネントを作成することができる。

カスタムQMLタイプの作成

1. Qt Creatorを起動して、[ファイル]メニューバー - [New File...]を選択する。
2. 次に、[New File]ダイアログの左ペインにある[Qt] - 右ペインにある[QMLファイル(Qt Quick 2)]を選択する。
3. 作成するQMLファイル名を入力して、[次へ]ボタンを押下する。
4. [プロジェクト管理]画面にある[完了]ボタンを押下する。

QMLファイル名には、英数字や_(アンダーバー)が使用できる。
ただし、ファイル名の1文字目は大文字のアルファベットで始まる必要がある。

もし、カスタムQMLファイルがQtプロジェクトのトップディレクトリと異なるディレクトリに存在する場合、該当ディレクトリをimportする必要がある。

 import "<カスタムQMLファイルが存在するディレクトリの相対パスまたは絶対パス>"

カスタムQMLファイルがQtプロジェクトのトップディレクトリに存在する場合は省略できる。

カスタムQMLタイプの例

以下の例では、押下するたびに乱数を発生させて、テキストに乱数値を表示するカスタムQMLタイプを作成および使用している。
なお、カスタムQMLファイル名は"CustomItem.qml"として、Qtプロジェクトのトップディレクトリに配置している。

 // CustomItem.qmlファイル
 
 import QtQuick 2.15
 import QtQuick.Controls 2.15
 
 Row {
    Button {
       id: btn
       text: "Click"
       function onClicked() {
          textvalue.text = Math.random()
       }
    }
 
    Text {
       id: textvalue
       text: "0"
    }
 }

 // main.qmlファイル
 
 import QtQuick 2.15
 import QtQuick.Window 2.15
 
 Window {
    visible: true
    width: 640
    height: 480
 
    Column {
       CustomItem {
          height: 50
       }
 
       CustomItem {
          height: 50
       }
 
       CustomItem {
          height: 50
       }
    }
 }

コンポーネントの作成

まず、カスタムQMLタイプを作成する。

1. Qt Creatorを起動して、[ファイル]メニューバー - [New File...]を選択する。
2. 次に、[New File]ダイアログの左ペインにある[Qt] - 右ペインにある[QMLファイル(Qt Quick 2)]を選択する。
3. 作成するQMLファイル名を入力して、[次へ]ボタンを押下する。
4. [プロジェクト管理]画面にある[完了]ボタンを押下する。

カスタムQMLファイル名には、英数字や_(アンダーバー)が使用できる。
ただし、ファイル名の1文字目は大文字のアルファベットで始まる必要がある。

コンポーネントは、以下に示すいずれかの手順により、オブジェクトを動的に生成することができる。

• Loaderタイプを使用する。
• ComponentタイプのcreateObject関数を使用する。

オブジェクトを必要に応じて生成する場合、または、パフォーマンス性からオブジェクトを不必要に削除したくない場合等に使用する。

コンポーネントの例

Loaderタイプを使用する場合

Loaderタイプは、カスタムQMLファイルを読み込み、オブジェクトを動的に生成することができる。
カスタムQMLファイルのオブジェクトを生成するには、sourceプロパティにカスタムQMLファイルのパスを指定する。

生成したオブジェクトを削除する場合は、sourceプロパティを空に指定する。

LoaderタイプはItemタイプを継承しているため、xプロパティ、yプロパティ、anchorsプロパティを使用して、
動的に生成したカスタムQMLファイルのオブジェクトのレイアウトを設定することができる。
デフォルトのxプロパティおよびyプロパティの値は、0であるため、そのオブジェクトは左上に表示される。

 // main.qmlファイル
 
 import QtQuick 2.15
 import QtQuick.Window 2.15
 
 Window {
    visible: true
    width: 640
    height: 480
 
    MouseArea {
       anchors.fill: parent
       function onClicked() {
          pageLoader.source = "CustomItem.qml"
       }
    }
 
    Loader {
       id: pageLoader
    }
 }

また、読み込んだカスタムQMLタイプがシグナルを送信してそれを呼び出し側が受信する場合、ConnectionsタイプをLoaderタイプのitemプロパティと一緒に使用する必要がある。
また、読み込んだカスタムQMLタイプが破棄された場合、カスタムQMLタイプが再び生成されるまで、全てのシグナルハンドラは無視される。

 // main.qmlファイル
 
 Loader {
    id: pageLoader 
    source: "CustomQML.qml"
 }
 
 Connections {
    target: pageLoader.item
 
    // Qt 5.14以前の場合
    onMessage: {
       pageLoader.source = ""
    }
 
    // Qt 5.15以降は、以下に示すシンタックスでも可能
    function onMessage()
    {
       pageLoader.source = ""
    }
 }

 // CustomQML.qmlファイル
 
 import QtQuick 2.15
 
 Rectangle {
    id: root
    width: 100
    height: 100
 
    signal message(string msg)
 
    MouseArea {
       anchors.fill: parent
       onClicked: {
          root.message("clicked!")
       }
    }
 }

Componentタイプを使用する場合

Componentタイプは、複数のQMLオブジェクトをまとめてコンポーネント化して、再利用可能なオブジェクトとして部品化する。

 Component {
    // ...略
 
    <任意のカスタムQMLタイプ名  例. CustomItem> {
       // ...略
    }
 }

Componentタイプは、Itemタイプを継承していないため、xプロパティ、yプロパティ、anchorsプロパティ、レイアウトの設定は使用できない。
レイアウトの設定が必要な場合、カスタムQMLタイプのプロパティを変更して、レイアウトを設定する必要がある。

Componentタイプ内に定義したカスタムQMLタイプをウインドウに表示する場合は、ComponentタイプをLoaderタイプのsourceComponentプロパティに設定する。
また、LoaderタイプのsourceComponentプロパティにundefinedを指定することにより、読み込み済みのオブジェクトを削除することができる。

以下の例では、カスタムQMLタイプ(CustomItem)をコンポーネント化したComponentタイプを読み込んで表示している。

 import QtQuick 2.15
 import QtQuick.Window 2.15
 
 window {
    visible: true
    width: 640
    height: 480
 
    MouseArea {
       anchors.fill: parent
       onClicked: {
          componentLoader.sourceComponent = customComponent
       }
    }
 
    Loader {
       id: componentLoader
    }
 
    Component {
       id: customComponent
       CustomItem {
          id: customItem
       }
    }
 }

Componentタイプの重要な機能として、completedとdestructionという2つのアタッチドシグナルが存在する。

• completed

  インスタンスが生成された直後に送信される。

  シグナルハンドラであるonCompletedは、インスタンスの生存確認およびインスタンスの生成直後に何らかの処理が必要な場合に使用するため、使用頻度が高い。

• destruction

  インスタンスが削除された時に送信される。

ComponentタイプのcreateObject関数を使用する場合

グローバル関数であるQt.createComponent関数を使用することにより、Componentタイプのインスタンスを生成することができる。
このインスタンスから、ComponentタイプにあるcreateObject関数を使用して、表示可能なインスタンスを動的に生成することができる。

また、createObject関数の第2引数にカスタムQMLタイプに渡すプロパティを指定することにより、インスタンスの生成と同時にプロパティを設定することができる。

以下の例では、Qt.createComponent関数とcreateObject関数を使用して、カスタムQMLタイプ(CustomItem)を動的に生成している。

 import QtQuick 2.15
 import QtQuick.Window 2.15
 
 window {
    id: mainWindow
    visible: true
    width: 640
    height: 480
 
    Component.onCompleted {
       var component = Qt.createComponent("CustomItem.qml")
       component.createObject(mainWindow, {"anchors.fill": mainWindow})
    }
 }

Componentタイプは、Loaderタイプと比較して手順が複雑であるが複数のインスタンスを生成できる等、Loaderタイプには無いメリットが存在する。

ダイアログの例

ダイアログは、カスタムQMLタイプとして定義することができない。
ただし、WindowタイプまたはApplicationWindowタイプを定義したカスタムQMLタイプを、createComponent関数を使用して読み込むことにより実現できる。

また、ダイアログから戻り値を取得する場合は、カスタムQMLタイプにpropertyを定義して、Connectionsタイプから取得する。

 // main.qmlファイル
 
 import QtQuick 2.15
 import QtQuick.Controls 2.15
 import QtQuick.Layouts 1.15
 import QtQuick.Window 2.15
 
 // ...略
 
 Button {
    text: "Popup MessageDialog"
 
    onClicked: {
       var component = Qt.createComponent("MessageDialog.qml");
       if (component.status === Component.Ready) {
       var messageDialog = component.createObject(parent, {someValue1: 1, someValue2: 2});
       messageDialogConnection.target = dlg
       messageDialog.show();
    }
 }
 
 Connections {
    id: messageDialogConnection
    onVisibleChanged: {
       if(!target.visible) {
          console.log(target.returnValue);       
       }
    }
 }
 
 // ...略

 // MessageDialog.qmlファイル
 
 import QtQuick 2.15
 import QtQuick.Window 2.15
 import QtQuick.Layouts 1.15
 import QtQuick.Controls 2.15
 
 ApplicationWindow {
    property int someValue1:  0
    property int someValue2:  0
    property int returnValue: 0

    id: messageDialog
    title: "Some Title"
    width: 600
    height: 450

    flags: Qt.Dialog
    modality: Qt.WindowModal

    onVisibleChanged: {
        messageDialogBtnCancel.focus = true
    }

    ColumnLayout {
        id: messageColumn
        width: parent.width
        spacing: 20

        Label {
            text: "Some Message"
            width: parent.width

            font.pointSize: 12

            wrapMode: Label.WordWrap
            horizontalAlignment: Label.AlignHCenter
            verticalAlignment: Label.AlignVCenter
            Layout.fillWidth: true
            Layout.fillHeight: true
            Layout.topMargin: 20
            Layout.bottomMargin: 20
        }

        RowLayout {
            x: parent.x
            width: parent.width
            Layout.alignment: Qt.AlignHCenter
            Layout.bottomMargin: 20
            spacing: 20

            Button {
                id: messageDialogBtnOK
                text: "OK"

                Connections {
                    target: messageDialogBtnOK
                    function onClicked() {
                        returnValue = 0
                        messageDialog.close()
                    }
                }
            }

            Button {
                id: messageDialogBtnCancel
                text: "Cancel"
                focus: true

                Connections {
                    target: messageDialogBtnCancel
                    function onClicked() {
                        returnValue = 1
                        messageDialog.close();
                    }
                }
            }
        }
    }
 }