모듈 정의 qmldir 파일

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

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

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

모듈 정의 qmldir 파일의 내용

qmldir 파일은 다음 명령어가 포함된 일반 텍스트 파일입니다:

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

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

모듈 식별자 선언

module <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

모듈을 원격으로 가져오는 경우( 원격으로 설치된 식별된 모듈 참조) 필요한데, 내보낸 유형이 모듈 내의 내보내지 않은 유형에 의존하는 경우 엔진은 내보내지 않은 유형도 로드해야 하기 때문입니다.

자바스크립트 리소스 선언

<ResourceIdentifier> <InitialVersion> <File>

모듈에서 사용할 수 있도록 자바스크립트 파일을 선언합니다. 리소스는 지정된 식별자를 통해 지정된 버전 번호로 사용할 수 있게 됩니다.

qmldir 파일에는 0개 이상의 JavaScript 리소스 선언이 존재할 수 있습니다. 그러나 각 JavaScript 리소스는 모듈의 특정 버전 내에서 고유 식별자를 가져야 합니다.

예시:

MyScript 1.0 MyScript.js

자세한 내용은 자바스크립트 리소스 정의하기 및 QML에서 자바스크립트 리소스 가져오기 문서를 참조하세요.

플러그인 선언

[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을 로드한 다음 다른 모듈에 종속되는 경우입니다. 이러한 경우 애플리케이션 패키지에 다른 모듈을 포함하려면 depends 선언이 필요합니다.

모듈 가져오기 선언

import <ModuleIdentifier> [<Version>]

이 모듈이 다른 모듈을 임포트한다고 선언합니다.

예시:

import MyOtherModule 1.0

다른 모듈의 유형은 이 모듈이 가져온 것과 동일한 유형 네임스페이스에서 사용할 수 있습니다. 버전을 생략하면 다른 모듈의 사용 가능한 최신 버전을 가져옵니다. auto 을 버전으로 지정하면 QML import 문에 지정된 이 모듈의 버전과 동일한 버전을 가져옵니다.

디자이너 지원 선언

designersupported

플러그인이 Qt Quick 디자이너에서 지원되는 경우 이 속성을 설정합니다. 기본적으로 플러그인은 지원되지 않습니다.

Qt Quick 디자이너에서 지원되는 플러그인은 제대로 테스트되어야 합니다. 즉, Qt Quick 디자이너가 QML을 실행하는 데 사용하는 qml2puppet 내에서 실행할 때 플러그인이 충돌하지 않아야 합니다. 일반적으로 플러그인은 Qt Quick 디자이너에서 잘 작동해야 하며, 과도한 메모리 사용, qml2puppet의 심한 속도 저하 또는 Qt Quick 디자이너에서 플러그인을 사실상 사용할 수 없게 만드는 다른 어떤 문제도 일으키지 않아야 합니다.

지원되지 않는 플러그인의 항목은 Qt Quick 디자이너에서 그려지지 않지만 빈 상자로 계속 사용할 수 있으며 속성을 편집할 수 있습니다.

기본 경로 선언

prefer <Path>

이 속성은 QML 엔진이 이 모듈에 대한 추가 파일을 현재 디렉터리가 아닌 <경로>에서 로드하도록 지시합니다. 이 속성은 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 파일은 "예제모듈"이라는 모듈을 정의합니다. 이 파일은 모듈의 버전 2.0 및 2.1에서 CustomButton QML 객체 유형을 정의하며, 각 버전마다 구현이 다릅니다. 클라이언트가 모듈을 임포트할 때 엔진에서 로드해야 하는 플러그인을 지정하며, 해당 플러그인은 다양한 C++ 정의 유형을 QML 유형 시스템에 등록할 수 있습니다. 유닉스 계열 시스템에서 QML 엔진은 libexamplemodule.so 을 QQmlExtensionPlugin 으로 로드하려고 시도하고, Windows에서는 examplemodule.dll 을 QQmlExtensionPlugin 으로 로드합니다. 마지막으로 qmldir 파일은 모듈의 버전 2.0 이상(동일한 메이저 버전 아래)을 가져온 경우에만 사용할 수 있는 JavaScript 리소스를 지정합니다.

모듈이 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 에 추가하여 등록합니다.