모듈 정의 qmldir 파일

qmldir 파일에는 두 가지 유형이 있습니다:

• QML 문서 디렉터리 목록 파일
• QML 모듈 정의 파일

이 문서는 모듈 내에서 사용할 수 있는 QML 유형, JavaScript 파일 및 플러그인을 나열하는 두 번째 유형의 qmldir 파일에 대해서만 다룹니다. 첫 번째 유형의 qmldir 파일에 대한 자세한 내용은 디렉터리 목록 qmldir 파일을 참조하십시오.

모듈 정의 qmldir 파일의 내용

qmldir 파일은 다음 명령어를 포함하는 일반 텍스트 파일입니다:

• 모듈 식별자 선언
• 객체 유형 선언
• 내부 객체 유형 선언
• JavaScript 리소스 선언
• 플러그인 선언
• 플러그인 클래스명 선언
• 유형 설명 파일 선언
• 모듈 종속성 선언
• 모듈 임포트 선언
• 디자이너 지원 선언
• 권장 경로 선언

명령 외에도 # 로 시작하는 주석을 추가할 수도 있습니다.

모듈 식별자 선언

module <ModuleIdentifier>

모듈의 모듈 식별자를 선언합니다. <ModuleIdentifier>는 모듈에 대한 (점 구분 URI 표기법) 식별자이며, 모듈의 설치 경로와 일치해야 합니다.

모듈 식별자 지시문 은 파일의 첫 번째 줄에 위치해야 합니다. qmldir 파일에는 정확히 하나의 모듈 식별자 지시문만 존재할 수 있습니다.

예시:

module ExampleModule

객체 유형 선언

[singleton] <TypeName> <InitialVersion> <File>

모듈에서 사용할 수 있도록 QML 객체 유형을 선언합니다.

• [singleton] 선택 사항입니다. 싱글톤 타입을 선언하는 데 사용됩니다.
• <TypeName> 는 제공될 유형입니다
• <InitialVersion> 는 해당 유형이 제공될 모듈 버전입니다
• <File> 는 해당 타입을 정의하는 QML 파일의 (상대) 파일 이름입니다

qmldir 파일에는 0개 이상의 객체 유형 선언이 포함될 수 있습니다. 그러나 각 객체 유형은 모듈의 특정 버전 내에서 고유한 유형 이름을 가져야 합니다.

예:

//Style.qml with custom singleton type definition
pragma Singleton
import QtQuick 2.0

QtObject {
    property int textSize: 20
    property color textColor: "green"
}

// qmldir declaring the singleton type
module CustomStyles
singleton Style 1.0 Style.qml

// singleton type in use
import QtQuick 2.0
import CustomStyles 1.0

Text {
    font.pixelSize: Style.textSize
    color: Style.textColor
    text: "Hello World"
}

내부 객체 유형 선언

internal <TypeName> <File>

모듈 내에 존재하지만 모듈 사용자에게는 노출되어서는 안 되는 객체 유형을 선언합니다.

qmldir 파일에는 0개 이상의 내부 객체 유형 선언이 포함될 수 있습니다.

예:

internal MyPrivateType MyPrivateType.qml

모듈이 원격으로 임포트되는 경우( ‘원격으로 설치된 식별 모듈’ 참조)에는 이 선언이 필요합니다. 왜냐하면, 내보낸 유형이 모듈 내부의 내보내지 않은 유형에 의존하는 경우, 엔진도 해당 내보내지 않은 유형을 로드해야 하기 때문입니다.

JavaScript 리소스 선언

<ResourceIdentifier> <InitialVersion> <File>

모듈을 통해 사용할 수 있도록 JavaScript 파일을 선언합니다. 이 리소스는 지정된 식별자와 버전 번호를 통해 제공됩니다.

qmldir 파일에는 0개 이상의 자바스크립트 리소스 선언이 포함될 수 있습니다. 그러나 각 자바스크립트 리소스는 모듈의 특정 버전 내에서 고유한 식별자를 가져야 합니다.

예시:

MyScript 1.0 MyScript.js

자세한 내용은 JavaScript 리소스 정의 및 QML에서 JavaScript 리소스 가져오기에 관한 문서를 참조하십시오.

플러그인 선언

[optional] plugin <Name> [<Path>]

모듈을 통해 사용할 수 있도록 플러그인을 선언합니다.

• optional 는 플러그인 자체에 관련 코드가 포함되어 있지 않으며, 링크된 라이브러리를 로드하는 역할만 수행함을 나타냅니다. 이 매개변수가 지정되고, 모듈에 대한 유형이 이미 사용 가능한 상태(즉, 다른 방법으로 라이브러리가 이미 로드되었음을 나타냄)인 경우, QML은 해당 플러그인을 로드하지 않습니다.
• <Name> 는 플러그인 라이브러리 이름입니다. 이는 일반적으로 플랫폼에 따라 달라지는 플러그인 바이너리의 파일 이름과 동일하지 않습니다. 예를 들어, MyAppTypes 라이브러리는 Linux에서는 libMyAppTypes.so, Windows에서는 MyAppTypes.dll 를 생성합니다.
• <Path> (선택 사항) 다음 중 하나를 지정합니다:
  • 플러그인 파일이 포함된 디렉터리의 절대 경로, 또는
  • qmldir 파일이 있는 디렉터리에서 플러그인 파일이 있는 디렉터리까지의 상대 경로.

기본적으로 엔진은 qmldir 파일이 있는 디렉터리에서 플러그인 라이브러리를 검색합니다. (플러그인 검색 경로는 QQmlEngine::pluginPathList()를 통해 조회할 수 있으며, QQmlEngine::addPluginPath()를 사용하여 수정할 수 있습니다.)

qmldir 파일에는 0개 이상의 C++ 플러그인 선언이 포함될 수 있습니다. 그러나 플러그인 로딩은 상대적으로 비용이 많이 드는 작업이므로, 클라이언트는 최대 하나의 플러그인만 지정하는 것이 좋습니다.

예시:

plugin MyPluginLibrary

플러그인 클래스명 선언

classname <C++ plugin class>

모듈에서 사용하는 C++ 플러그인의 클래스 이름을 제공합니다.

이 정보는 추가 기능을 위해 C++ 플러그인에 의존하는 모든 QML 모듈에 필수적입니다. 정적 링크로 빌드된 Qt Quick 애플리케이션은 이 정보가 없으면 모듈 임포트를 해결할 수 없습니다.

유형 설명 파일 선언

typeinfo <File>

모듈에 대한 유형 설명 파일을 선언하며, 이 파일은 Qt Creator 와 같은 QML 도구가 모듈의 플러그인에서 정의된 유형에 대한 정보에 접근할 수 있도록 합니다. ` <File> `는 ` .qmltypes ` 파일의 (상대) 파일 이름입니다.

예:

typeinfo mymodule.qmltypes

이러한 파일이 없으면 QML 도구가 플러그인에 정의된 타입에 대한 코드 자동 완성 등의 기능을 제공하지 못할 수 있습니다.

모듈 종속성 선언

depends <ModuleIdentifier> <InitialVersion>

이 모듈이 다른 모듈에 의존함을 선언합니다.

예:

depends MyOtherModule 1.0

이 선언은 의존성이 숨겨진 경우에만 필요합니다. 예를 들어, 한 모듈의 C++ 코드를 사용하여(조건부로) QML을 로드하고, 그 QML이 다른 모듈에 의존하는 경우입니다. 이러한 경우, 애플리케이션 패키지에 다른 모듈을 포함시키기 위해서는 ` depends ` 선언이 필요합니다.

모듈 임포트 선언

import <ModuleIdentifier> [<Version>]

이 모듈이 다른 모듈을 가져온다는 것을 선언합니다.

예시:

import MyOtherModule 1.0

다른 모듈의 타입은 이 모듈이 임포트된 것과 동일한 타입 네임스페이스에서 사용할 수 있게 됩니다. 버전을 생략하면 다른 모듈의 사용 가능한 최신 버전이 임포트됩니다. 버전으로 ` auto `을 지정하면 QML의 ` import ` 문에서 지정된 이 모듈의 버전과 동일한 버전이 임포트됩니다.

디자이너 지원 선언

designersupported

플러그인이 Qt Quick Designer에서 지원되는 경우 이 속성을 설정하십시오. 기본적으로 플러그인은 지원되지 않습니다.

Qt Quick Designer에서 지원되는 플러그인은 적절한 테스트를 거쳐야 합니다. 즉, Qt Quick Designer가 QML을 실행하는 데 사용하는 qml2puppet 내에서 플러그인이 실행될 때 충돌이 발생하지 않아야 합니다. 일반적으로 플러그인은 Qt Quick 디자이너에서 원활하게 작동해야 하며, 과도한 메모리 소모, qml2puppet의 심각한 성능 저하, 또는 Qt Quick 디자이너에서 플러그인을 사실상 사용할 수 없게 만드는 기타 문제와 같은 심각한 오류를 유발해서는 안 됩니다.

Qt Quick Designer에서는 지원되지 않는 플러그인의 항목이 표시되지는 않지만, 빈 상자로는 여전히 표시되며 속성을 편집할 수 있습니다.

선호 경로 선언

prefer <Path>

이 속성은 QML 엔진이 현재 디렉터리가 아닌 <path>에서 이 모듈에 대한 추가 파일을 로드하도록 지시합니다. 이는 qmlcachegen으로 컴파일된 파일을 로드하는 데 사용할 수 있습니다.

예를 들어, 모듈의 QML 파일을 리소스 경로 :/my/path/MyModule/ 에 리소스로 추가할 수 있습니다. 그런 다음, 파일 시스템에 있는 파일 대신 리소스 시스템의 파일을 사용하려면 qmldir 파일에 prefer :/my/path/MyModule 를 추가하십시오. 이후 해당 파일들에 대해 qmlcachegen을 사용하면, 사전 컴파일된 파일을 모듈의 모든 클라이언트에서 사용할 수 있게 됩니다.

버전 관리 규칙

특정 메이저 버전에 대해 내보내진 모든 QML 유형은 동일한 메이저 버전의 최신 버전에서 사용할 수 있습니다. 예를 들어, 모듈이 버전 1.0에서 MyButton 유형을 제공하고 버전 1.1에서 MyWindow 유형을 제공하는 경우, 모듈의 버전 1.1 을 임포트하는 클라이언트는 MyButton 및 MyWindow 유형을 사용할 수 있습니다. 그러나 그 반대의 경우는 성립하지 않습니다. 특정 소버전을 위해 내보낸 타입은 더 오래된 소버전을 가져와서는 사용할 수 없습니다. 앞서 언급한 예시에서, 클라이언트가 모듈의 1.0 버전을 가져왔다면 MyButton 타입만 사용할 수 있고 MyWindow 타입은 사용할 수 없습니다.

모듈은 여러 개의 메이저 버전을 제공할 수 있지만, 클라이언트는 한 번에 하나의 메이저 버전에만 접근할 수 있습니다. 예를 들어, MyExampleModule 2.0 를 임포트하면 해당 메이저 버전에만 접근할 수 있으며, 이전 메이저 버전에는 접근할 수 없습니다. 서로 다른 메이저 버전에 속하는 아티팩트를 단일 디렉터리와 qmldir 파일 아래에 정리할 수는 있지만, 각 메이저 버전마다 별도의 디렉터리를 사용하는 것이 권장됩니다. 앞서 설명한 방식(단일 디렉터리 및 qmldir 파일)을 선택한다면, 파일 이름에 버전 접미사를 사용하는 것이 좋습니다. 예를 들어, MyExampleModule 2.0 에 속하는 아티팩트는 파일 이름에 .2 접미사를 사용할 수 있습니다.

해당 버전에 대해 명시적으로 내보낸 타입이 없는 경우, 해당 버전을 가져올 수 없습니다. 모듈이 버전 1.0에서 MyButton 타입을 제공하고, 버전 1.1에서 MyWindow 타입을 제공하는 경우, 해당 모듈의 버전 1.2나 버전 2.0은 가져올 수 없습니다.

한 타입은 서로 다른 마이너 버전의 여러 파일에서 정의될 수 있습니다. 이 경우 클라이언트가 가져올 때 가장 근접한 버전이 사용됩니다. 예를 들어, 모듈이 qmldir 파일을 통해 다음과 같은 타입을 지정했다면:

module ExampleModule
MyButton 1.0 MyButton.qml
MyButton 1.1 MyButton11.qml
MyButton 1.3 MyButton13.qml
MyRectangle 1.2 MyRectangle12.qml

ExampleModule 의 1.2 버전을 임포트하는 클라이언트는 MyButton11.qml 에서 제공하는 MyButton 타입 정의(해당 타입의 최신 버전이기 때문)와 MyRectangle12.qml 에서 제공하는 MyRectangle 타입 정의를 모두 사용할 수 있습니다.

버전 시스템은 특정 QML 파일이 설치된 소프트웨어의 버전에 관계없이 작동하도록 보장합니다. 버전이 지정된 임포트는 해당 버전에 해당하는 타입만 임포트하고, 실제 설치된 버전이 해당 식별자를 제공할 수 있더라도 다른 식별자는 그대로 사용할 수 있게 하기 때문입니다.

qmldir 파일 예시

다음은 qmldir 파일의 한 예입니다:

module ExampleModule
CustomButton 2.0 CustomButton20.qml
CustomButton 2.1 CustomButton21.qml
plugin examplemodule
MathFunctions 2.0 mathfuncs.js

위의 qmldir 파일은 "ExampleModule"이라는 모듈을 정의합니다. 이 파일은 모듈의 2.0 및 2.1 버전에서 CustomButton QML 객체 유형을 정의하며, 각 버전마다 서로 다른 구현을 사용합니다. 또한 클라이언트가 모듈을 임포트할 때 엔진에서 반드시 로드해야 하는 플러그인을 지정하며, 해당 플러그인은 QML 유형 시스템에 다양한 C++로 정의된 유형을 등록할 수 있습니다. 유닉스 계열 시스템에서 QML 엔진은 libexamplemodule.so 를 QQmlExtensionPlugin 로 로드하려고 시도하며, Windows에서는 examplemodule.dll 를 QQmlExtensionPlugin 로 로드합니다. 마지막으로, qmldir 파일은 JavaScript 리소스를 지정하며, 이 리소스는 모듈의 버전 2.0 또는 그 이후 버전(동일한 메이저 버전 내)이 임포트된 경우에만 사용할 수 있습니다.

모듈이 QML 임포트 경로에 설치되어 있다면, 클라이언트는 다음과 같은 방식으로 모듈을 임포트하고 사용할 수 있습니다:

import QtQuick 2.0
import ExampleModule 2.1

Rectangle {
    width: 400
    height: 400
    color: "lightsteelblue"

    CustomButton {
        color: "gray"
        text: "Click Me!"
        onClicked: MathFunctions.generateRandom() > 10 ? color = "red" : color = "gray";
    }
}

위에서 사용된 ` CustomButton ` 유형은 ` CustomButton21.qml ` 파일에 지정된 정의에서 가져오며, ` MathFunctions ` 식별자로 지정된 JavaScript 리소스는 ` mathfuncs.js ` 파일에 정의됩니다.

유형 설명 파일

QML 모듈은 qmldir 파일 내에서 하나 이상의 유형 정보 파일을 참조할 수 있습니다. 이러한 파일은 일반적으로 .qmltypes 확장자를 가지며, 외부 도구가 C++로 정의된 유형에 대한 정보를 얻기 위해 읽으며, 대개 플러그인을 통해 임포트됩니다.

따라서 qmltypes 파일은 QML 모듈의 기능에 아무런 영향을 미치지 않습니다. 이 파일의 유일한 용도는 Qt Creator 와 같은 도구가 모듈 사용자에게 코드 자동 완성, 오류 검사 및 기타 기능을 제공할 수 있도록 하는 데 있습니다.

C++에서 QML 타입을 정의하는 모든 모듈은 타입 설명 파일도 함께 제공해야 합니다.

모듈용 qmltypes 파일을 만드는 가장 좋은 방법은 빌드 시스템과 QML_ELEMENT 매크로를 사용하여 생성하는 것입니다. 이에 대한 문서를 따르면 추가 조치가 필요하지 않습니다. qmltyperegistrar가 자동으로 .qmltypes 파일을 생성합니다.

예시: 모듈이 /tmp/imports/My/Module 에 있는 경우, 실제 플러그인 바이너리와 함께 plugins.qmltypes 이라는 파일이 생성되어야 합니다.

다음 줄을

typeinfo plugins.qmltypes

를 /tmp/imports/My/Module/qmldir 에 추가하여 등록하십시오.