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

QML의 핵심 기능 중 하나는 개별 QML 애플리케이션의 요구 사항에 맞춰 QML 문서를 통해 가볍고 간편하게 QML 객체 유형을 정의할 수 있다는 점입니다. 표준 Qt Quick 모듈은 QML 애플리케이션 구축을 위해 ` Rectangle`, ` Text `, ` Image `과 같은 다양한 유형을 제공하며, 이 외에도 애플리케이션 내에서 재사용할 수 있는 자체 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 을 참조할 수 없으며, 만약 id 값이 squareButton 대신 root 으로 설정되어 있었다면, 이는 SquareButton.qml 에 정의된 루트 객체의 id 값과 동일한 값을 가진다 하더라도 두 정의가 서로 다른 범위 내에서 선언되었기 때문에 충돌이 발생하지 않았을 것입니다.