QML 문서를 통한 객체 유형 정의

QML의 핵심 기능 중 하나는 개별 QML 애플리케이션의 요구 사항에 맞게 QML 문서를 통해 경량화된 방식으로 QML 객체 유형을 쉽게 정의할 수 있다는 점입니다. 표준 Qt Quick 모듈은 Rectangle, Text, Image 와 같은 다양한 유형을 제공하여 QML 애플리케이션을 구축할 수 있도록 지원하며, 이 외에도 애플리케이션 내에서 재사용할 고유한 QML 유형을 쉽게 정의할 수 있습니다. 이렇게 자신만의 유형을 생성하는 기능은 모든 QML 애플리케이션의 빌딩 블록을 형성합니다.

QML 파일로 객체 유형 정의하기

사용자 지정 QML 객체 유형 이름 지정

객체 유형을 만들려면 QML 문서를 <TypeName>.qml이라는 이름의 텍스트 파일에 넣어야 합니다(여기서 <TypeName>은 원하는 유형의 이름입니다). 유형 이름에는 다음과 같은 요구 사항이 있습니다:

• 영숫자 또는 밑줄로 구성되어야 합니다.
• 대문자로 시작해야 합니다.

그러면 이 문서는 엔진에서 자동으로 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 개체의 일부 속성에 대해 사용자 정의된 값을 가진 세 개의 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 과 충돌하지 않습니다.