QQmlEngine Class

멤버 함수 문서

[explicit] QQmlEngine::QQmlEngine(QObject *parent = nullptr)

지정된 ` parent`을 사용하여 새로운 `QQmlEngine`을 생성합니다.

[override virtual noexcept] QQmlEngine::~QQmlEngine()

QQmlEngine 를 삭제합니다.

이 엔진에서 생성된 모든 QQmlContext 는 무효화되지만, 파기되지는 않습니다( QQmlEngine 객체의 자식인 경우는 제외).

JS 엔진 정리에 대한 자세한 내용은 ~QJSEngine()을 참조하십시오.

void QQmlEngine::addImageProvider(const QString &providerId, QQmlImageProviderBase *provider)

호스트 providerId 을 통해 image: URL 스키마로 요청된 이미지에 사용할 이미지 제공자( provider )를 설정합니다. QQmlEngine 는 provider 의 소유권을 갖습니다.

이미지 제공자는 픽스맵(pixmap) 및 스레드 기반 이미지 요청을 지원합니다. 이미지 제공자의 구현 및 사용에 대한 자세한 내용은 QQuickImageProvider 문서를 참조하십시오.

필요한 모든 이미지 제공자는 QML 소스 파일이 로드되기 전에 엔진에 추가되어야 합니다.

removeImageProvider(), QQuickImageProvider 및 QQmlImageProviderBase도 참조하십시오 .

void QQmlEngine::addImportPath(const QString &path)

URL 기반 디렉터리 구조에서 엔진이 설치된 모듈을 검색하는 디렉터리로 path 을 추가합니다. Qt는 path 아래의 모든 파일과 폴더가 신뢰할 수 있는 출처에서 비롯된 것이라고 가정합니다.

path 는 로컬 파일 시스템 디렉터리, Qt 리소스 경로(:/imports), Qt 리소스 URL(qrc:/imports) 또는 일반 URL일 수 있습니다.

path 는 가져오기 경로 목록에 추가되기 전에 정규화된 형태로 변환됩니다.

새로 추가된 path 는 importPathList()에서 가장 먼저 나열됩니다.

setImportPathList(), QML 모듈 및 QML 임포트 경로항목도 참조하십시오.

void QQmlEngine::addPluginPath(const QString &path)

path 을 엔진이 가져온 모듈( qmldir 파일에 참조된)에 대한 네이티브 플러그인을 검색하는 디렉터리로 추가합니다. Qt는 path 아래의 모든 파일과 폴더가 신뢰할 수 있는 출처에서 온 것으로 간주합니다.

기본적으로 이 목록에는 . 만 포함되어 있으며, 즉 엔진은 qmldir 파일 자체가 위치한 디렉터리에서 검색을 수행합니다.

새로 추가된 path 는 pluginPathList() 목록에서 가장 먼저 표시됩니다.

setPluginPathList()도 참조하십시오 .

void QQmlEngine::addUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

QML에서 URL을 해석할 때 사용되는 URL 인터셉터( urlInterceptor )를 추가합니다. 이는 스크립트 파일 및 QML 타입을 불러올 때 사용되는 URL에도 적용됩니다. 엔진이 파일을 불러오는 동안 URL 인터셉터를 수정해서는 안 되며, 그렇지 않으면 URL 선택에 불일치가 발생할 수 있습니다. 여러 개의 URL 인터셉터가 지정된 경우, 각 URL에 대해 추가된 순서대로 호출됩니다.

QQmlEngine 이 메서드는 인터셉터의 소유권을 인수하지 않으며, 이를 삭제하지도 않습니다.

QUrl QQmlEngine::baseUrl() const

이 엔진의 기본 URL을 반환합니다. 기본 URL은 QQmlComponent 생성자에 상대 URL이 전달되었을 때 컴포넌트를 해결하는 데에만 사용됩니다.

기본 URL이 명시적으로 설정되지 않은 경우, 이 메서드는 애플리케이션의 현재 작업 디렉터리를 반환합니다.

setBaseUrl()도 참조하십시오 .

void QQmlEngine::clearComponentCache()

엔진의 내부 컴포넌트 캐시를 지웁니다.

이 함수는 엔진에 이전에 로드된 대부분의 컴포넌트에 대한 속성 메타데이터를 삭제합니다. 이는 엔진 컴포넌트 캐시에서 참조되지 않는 컴포넌트를 제거함으로써 이루어집니다. 여전히 참조되고 있는 컴포넌트는 제거하지 않는데, 이는 나중에 거의 확실하게 크래시를 유발할 수 있기 때문입니다.

참조되는 컴포넌트가 없는 경우, 이 함수는 엔진 내의 모든 로드된 컴포넌트 데이터가 제거된 상태로 되돌립니다. 이는 이전 컴포넌트 집합 중 일부만 다시 로드하거나, 이전에 로드된 컴포넌트의 새 버전을 로드할 때 유용할 수 있습니다.

컴포넌트 캐시가 지워지면, 새로운 객체를 생성하기 전에 컴포넌트를 다시 로드해야 합니다.

일반적인 원칙으로, 컴포넌트 캐시를 지울 때는 QML 컴포넌트로 생성된 객체가 하나도 살아 있지 않도록 해야 합니다.

trimComponentCache() 및 clearSingletons()도 참조하십시오 .

void QQmlEngine::clearSingletons()

엔진이 소유한 모든 싱글톤을 제거합니다.

이 함수는 모든 싱글톤 인스턴스를 해제하며, 그중에서 엔진이 소유하고 있는 모든 QObject를 삭제합니다. 이는 clearComponentCache()를 호출하기 전에 QML로 생성된 객체가 남아 있지 않도록 하는 데 유용합니다.

QObject 를 기반으로 하는 싱글톤 인스턴스를 보유하는 QML 속성은, 엔진이 해당 싱글톤을 소유하고 있는 경우 null이 되고, 소유하지 않는 경우 기존 값을 유지합니다. 기존에 QML로 생성된 객체에 접근한다고 해서 싱글톤이 자동으로 재생성되지는 않습니다. 새로운 컴포넌트가 인스턴스화될 때만 싱글톤이 재생성됩니다.

clearComponentCache()도 참조하십시오 .

[static] QQmlContext *QQmlEngine::contextForObject(const QObject *object)

object 에 대한 QQmlContext 를 반환하며, 컨텍스트가 설정되지 않은 경우 nullptr을 반환합니다.

QQmlEngine 가 QObject 를 인스턴스화할 때, 해당 객체에는 내부 컨텍스트가 자동으로 할당됩니다. 이러한 내부 컨텍스트는 읽기 전용입니다. 이 컨텍스트에 컨텍스트 속성을 설정할 수 없습니다.

setContextForObject(), qmlContext(), qmlEngine(), QQmlContext::setContextProperty()도 참조하십시오 .

[override virtual protected] bool QQmlEngine::event(QEvent *e)

QObject::event(QEvent *e)를 재구현합니다.

[signal] void QQmlEngine::exit(int retCode)

이 신호는 엔진에 의해 로드된 QML이 지정된 반환 코드 retCode 로 이벤트 루프에서 종료하고자 할 때 발생합니다.

quit()도 참조하십시오 .

QQmlImageProviderBase *QQmlEngine::imageProvider(const QString &providerId) const

providerId 에 설정된 이미지 제공자를 찾을 수 있으면 이를 반환하고, 그렇지 않으면 nullptr 을 반환합니다.

QQuickImageProvider도 참조하십시오 .

QStringList QQmlEngine::importPathList() const

URL 기반 디렉터리 구조에서 엔진이 설치된 모듈을 검색하는 디렉터리 목록을 반환합니다.

예를 들어, 경로에 /opt/MyApp/lib/imports 이 포함되어 있다면, com.mycompany.Feature 를 임포트하는 QML 파일은 QQmlEngine 가 해당 모듈에서 제공하는 컴포넌트를 /opt/MyApp/lib/imports/com/mycompany/Feature/ 에서 찾도록 합니다. 타입 버전 매핑 및 QML 확장 플러그인을 정의하려면 qmldir 파일이 필요합니다.

기본적으로 이 목록에는 QML 임포트 경로(QML Import Path)에 언급된 경로들이 포함됩니다.

addImportPath() 및 setImportPathList()도 참조하십시오 .

QQmlIncubationController *QQmlEngine::incubationController() const

현재 설정된 인큐베이션 컨트롤러를 반환하며, 컨트롤러가 설정되어 있지 않은 경우 0을 반환합니다.

setIncubationController()도 참조하십시오 .

QUrl QQmlEngine::interceptUrl(const QUrl &url, QQmlAbstractUrlInterceptor::DataType type) const

지정된 type 의 지정된 url 에 대해 현재 URL 인터셉터를 실행하고 결과를 반환합니다.

[since 6.6] void QQmlEngine::markCurrentFunctionAsTranslationBinding()

이 메서드가 QML의 바인딩에 포함된 함수 내에서 호출되면, 해당 바인딩은 변환 바인딩으로 처리됩니다.

class I18nAwareClass : public QObject {

  //...

   QString text() const
   {
        if (auto engine = qmlEngine(this))
            engine->markCurrentFunctionAsTranslationBinding();
        return tr("Hello, world!");
   }
};

이 함수는 Qt 6.6에서 도입되었습니다.

QQmlEngine::retranslate도 참조하십시오 .

QNetworkAccessManager *QQmlEngine::networkAccessManager() const

이 엔진에 의해 인스턴스화되는 모든 QML 유형에서 사용할 수 있는 공통 QNetworkAccessManager 를 반환합니다.

QQmlNetworkAccessManagerFactory 가 설정되어 있고 QNetworkAccessManager 가 아직 생성되지 않은 경우, QQmlNetworkAccessManagerFactory 가 QNetworkAccessManager 를 생성하는 데 사용됩니다. 그렇지 않은 경우, 반환된 QNetworkAccessManager 에는 프록시나 캐시가 설정되지 않습니다.

setNetworkAccessManagerFactory()도 참조하십시오 .

QQmlNetworkAccessManagerFactory *QQmlEngine::networkAccessManagerFactory() const

현재 QQmlNetworkAccessManagerFactory 를 반환합니다.

setNetworkAccessManagerFactory()도 참조하십시오 .

QString QQmlEngine::offlineStorageDatabaseFilePath(const QString &databaseName) const

식별자가 databaseName 인 Local Storage 데이터베이스가 위치해 있거나 위치하게 될 파일 경로를 반환합니다.

LocalStorage.openDatabaseSync()도 참조하십시오 .

[signal, since 6.5] void QQmlEngine::offlineStoragePathChanged()

offlineStoragePath 가 변경되면 이 신호가 발생합니다.

이 함수는 Qt 6.5에서 도입되었습니다.

bool QQmlEngine::outputWarningsToStandardError() const

경고 메시지가 ` warnings()` 신호를 통해 전송되는 것 외에도 stderr로 출력될 경우 true를 반환하고, 그렇지 않은 경우 false를 반환합니다.

기본값은 true입니다.

setOutputWarningsToStandardError()도 참조하십시오 .

QStringList QQmlEngine::pluginPathList() const

엔진이 가져온 모듈( qmldir 파일에 참조된)에 대한 네이티브 플러그인을 검색하는 디렉터리 목록을 반환합니다.

기본적으로 이 목록에는 . 만 포함되며, 즉 엔진은 qmldir 파일 자체가 위치한 디렉터리에서 검색을 수행합니다.

addPluginPath() 및 setPluginPathList()도 참조하십시오 .

[signal] void QQmlEngine::quit()

이 신호는 엔진에 의해 로드된 QML이 종료되려고 할 때 발생합니다.

exit()도 참조하십시오 .

void QQmlEngine::removeImageProvider(const QString &providerId)

providerId 에 대한 이미지 제공자를 제거합니다.

addImageProvider() 및 QQuickImageProvider도 참조하십시오 .

void QQmlEngine::removeUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

addUrlInterceptor 를 사용하여 이전에 추가된 URL 인터셉터( urlInterceptor )를 제거합니다. 엔진이 파일을 로드하는 동안에는 URL 인터셉터를 수정해서는 안 되며, 그렇지 않으면 URL 선택에 불일치가 발생할 수 있습니다.

이 작업은 인터셉터를 삭제하는 것이 아니라, 단순히 엔진에서 제거하는 것입니다. 나중에 동일한 엔진이나 다른 엔진에서 이를 재사용할 수 있습니다.

[slot] void QQmlEngine::retranslate()

번역 대상으로 표시된 문자열을 사용하는 모든 바인딩 표현식을 새로 고칩니다.

QCoreApplication::installTranslator 를 사용하여 새로운 번역기를 설치한 후, 사용자 인터페이스에 최신 번역이 표시되도록 하려면 이 함수를 호출하십시오.

QQmlContext *QQmlEngine::rootContext() const

엔진의 루트 컨텍스트를 반환합니다.

루트 컨텍스트는 ` QQmlEngine`에 의해 자동으로 생성됩니다. 엔진에 의해 인스턴스화된 모든 QML 컴포넌트 인스턴스가 사용할 수 있어야 하는 데이터는 루트 컨텍스트에 배치해야 합니다.

일부 컴포넌트 인스턴스에만 제공되어야 하는 추가 데이터는 루트 컨텍스트의 하위 컨텍스트에 추가해야 합니다.

void QQmlEngine::setBaseUrl(const QUrl &url)

이 엔진의 기본 URL을 url 로 설정하십시오.

baseUrl()도 참조하십시오 .

[static] void QQmlEngine::setContextForObject(QObject *object, QQmlContext *context)

object 의 QQmlContext 를 context 로 설정합니다. object 에 이미 컨텍스트가 설정되어 있는 경우 경고 메시지가 출력되지만, 컨텍스트는 변경되지 않습니다.

QQmlEngine 가 QObject 를 인스턴스화할 때, 컨텍스트가 자동으로 설정됩니다.

contextForObject()도 참조하십시오 .

[since 6.12] bool QQmlEngine::setExternalSingletonInstance(QAnyStringView moduleName, QAnyStringView typeName, QObject *instance)

QML 엔진에서 지정된 유형에 사용할 싱글톤 인스턴스를 설정합니다.

이 함수를 사용하면 이 엔진의 QML에서 싱글톤으로 사용할 ` QObject` 파생 인스턴스를 수동으로 설정할 수 있습니다. 이를 통해 인스턴스 생성을 제어할 수 있습니다. 이는 싱글톤이 백엔드 컴포넌트와 통신해야 하는 경우를 포함하여 여러 시나리오에서 유용할 수 있습니다.

이 함수는 설정하려는 싱글톤 타입을 나타내는 ` moduleName ` 및 ` typeName `와 설정할 ` instance `를 매개변수로 받습니다. 타입은 이미 QML 싱글톤 타입으로 등록되어 있어야 하며, 가급적이면 ` QML_ELEMENT ` 및 `QML_SINGLETON`을 사용하여 등록하는 것이 좋습니다. 모듈이 아직 로드되지 않은 경우, 이 시점에 로드됩니다.

이 함수는 성공 시 true를, 실패 시 false를 반환합니다. 실패가 발생하면 실패 원인을 상세히 설명하는 경고가 출력됩니다.

예를 들어, 싱글톤이 작동하기 위해 백엔드 서비스가 필요한 경우, 다음과 같이 선언할 수 있습니다:

class CppSingleton: public QObject {
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    QML_UNCREATABLE("Provided via QQmlEngine::setExternalSingletonInstance")
    // Q_PROPERTY(...)
public:
    explicit CppSingleton(BackendService *service); // constructor taking a reference to something MySingleton needs
    // members, Q_INVOKABLE functions, etc.
};

애플리케이션 초기화 시 다음을 수행할 수 있습니다:

    // create and setup the backend service
    BackendService service;

    // create your singleton instance
    CppSingleton singleton(&service);
    QQmlApplicationEngine engine;
    engine.setExternalSingletonInstance("com.company.myApp", "MySingleton", &singleton);
    engine.loadFromModule("com.company.myApp", "Main");

참고: 기본 생성자나 정적 생성 함수를 제공하는 대신, QML_UNCREATABLE() 매크로를 사용하여 이 항목이 qml 엔진에 의해 생성될 수 없음을 나타냈습니다.

싱글톤 인스턴스는 유형 및 엔진당 한 번만 설정할 수 있으며, 사용 전에 반드시 설정해야 합니다. 싱글톤 인스턴스가 생성되거나 설정된 후에는 이 함수를 사용하여 다시 설정할 수 없으므로, QML에서 처음 사용하기 전에 인스턴스를 설정해야 합니다.

QJSEngine::setObjectOwnership()을 사용하여 엔진에 명시적으로 지시하지 않는 한, 엔진은 전달된 인스턴스의 소유권을 인수하지 않습니다.

이 함수는 Qt 6.12에서 도입되었습니다.

void QQmlEngine::setImportPathList(const QStringList &paths)

URL 기반 디렉터리 구조에서 엔진이 설치된 모듈을 검색할 디렉터리 목록으로 ` paths `을 설정합니다. Qt는 ` paths ` 아래의 모든 파일과 폴더가 신뢰할 수 있는 출처에서 비롯된 것이라고 가정합니다.

기본적으로 이 목록에는 QML 가져오기 경로에 언급된 경로들이 포함됩니다.

importPathList() 및 addImportPath()도 참조하십시오 .

void QQmlEngine::setIncubationController(QQmlIncubationController *controller)

엔진의 인큐베이션 controller 을 설정합니다. 엔진에는 활성 컨트롤러가 하나만 있을 수 있으며, 엔진은 해당 컨트롤러에 대한 소유권을 가지지 않습니다.

incubationController()도 참조하십시오 .

void QQmlEngine::setNetworkAccessManagerFactory(QQmlNetworkAccessManagerFactory *factory)

QNetworkAccessManager 를 생성할 때 사용할 factory 를 설정합니다.

QNetworkAccessManager 이는 QML의 모든 네트워크 액세스에 사용됩니다. 팩토리를 구현하면 특화된 캐싱, 프록시 및 쿠키 지원을 갖춘 사용자 정의 QNetworkAccessManager 를 생성할 수 있습니다.

팩토리는 엔진을 실행하기 전에 설정해야 합니다.

networkAccessManagerFactory()도 참조하십시오 .

void QQmlEngine::setOutputWarningsToStandardError(bool enabled)

경고 메시지를 stderr로 출력할지 여부를 ` enabled`로 설정합니다.

enabled 가 true인 경우, QML에서 생성된 모든 경고 메시지는 stderr로 출력되며 warnings() 시그널을 통해 발신됩니다. enabled 가 false인 경우, warnings() 시그널만 발신됩니다. 이를 통해 애플리케이션에서 경고 출력을 직접 처리할 수 있습니다.

기본값은 true입니다.

outputWarningsToStandardError()도 참조하십시오 .

void QQmlEngine::setPluginPathList(const QStringList &paths)

엔진이 ( qmldir 파일에 참조된) 가져온 모듈에 대한 네이티브 플러그인을 검색할 디렉터리 목록을 paths 로 설정합니다. Qt는 paths 아래의 모든 파일과 폴더가 신뢰할 수 있는 출처에서 온 것으로 간주합니다.

기본적으로 이 목록에는 . 만 포함되며, 즉 엔진은 qmldir 파일 자체가 위치한 디렉터리에서 검색을 수행합니다.

pluginPathList() 및 addPluginPath()도 참조하십시오 .

template <typename T> T QQmlEngine::singletonInstance(int qmlTypeId)

qmlTypeId 에 등록된 싱글톤 타입의 인스턴스를 반환합니다.

템플릿 인자 T는 QJSValue 이거나 QObject 에서 파생된 타입에 대한 포인터일 수 있으며, 이는 싱글톤이 등록된 방식에 따라 달라집니다. T의 인스턴스가 아직 생성되지 않은 경우, 이 시점에서 생성됩니다. qmlTypeId 가 유효한 싱글톤 타입을 나타내지 않는 경우, 기본 생성된 QJSValue 또는 nullptr 가 반환됩니다.

QObject* 예시:

class MySingleton : public QObject {
    Q_OBJECT

    // Register as default constructed singleton.
    QML_ELEMENT
    QML_SINGLETON

    static int typeId;
    // ...
};

    MySingleton::typeId = qmlTypeId(...);

    // Retrieve as QObject*
    QQmlEngine engine;
    MySingleton* instance = engine.singletonInstance<MySingleton*>(MySingleton::typeId);

QJSValue 예시:

    // Register with QJSValue callback
    int typeId = qmlRegisterSingletonType(...);

    // Retrieve as QJSValue
    QQmlEngine engine;
    QJSValue instance = engine.singletonInstance<QJSValue>(typeId);

QML 유형 ID를, 예를 들어 싱글톤 클래스의 정적 멤버로 저장하는 것이 권장됩니다. qmlTypeId()을 통한 조회는 성능에 부담이 큽니다.

QML_SINGLETON, qmlRegisterSingletonType() 및 qmlTypeId()도 참조하십시오 .

[since 6.5] template <typename T> T QQmlEngine::singletonInstance(QAnyStringView uri, QAnyStringView typeName)

uri 로 지정된 모듈에서 typeName 라는 이름의 싱글톤 타입 인스턴스를 반환합니다.

이 메서드는 qmlTypeId 를 호출한 후 ID 기반 singletonInstance 오버로드를 호출하는 대신 사용할 수 있습니다. 이는 싱글톤을 한 번만 설정하면 되는 경우에 편리합니다. 싱글톤에 반복적으로 접근해야 하는 경우, typeId를 캐싱해 두면 type-id based overload 를 통해 이후 접근 속도를 높일 수 있습니다.

템플릿 인자 T는 QJSValue 이거나 QObject 에서 파생된 타입에 대한 포인터일 수 있으며, 이는 싱글톤이 어떻게 등록되었는지에 따라 달라집니다. T의 인스턴스가 아직 생성되지 않았다면, 이때 생성됩니다. typeName 가 유효한 싱글톤 타입을 나타내지 않는 경우, 기본 생성된 QJSValue 또는 nullptr 가 반환됩니다.

    QQmlEngine engine;
    MySingleton *singleton = engine.singletonInstance<MySingleton *>("mymodule", "MySingleton");

이 함수는 Qt 6.5에서 도입되었습니다.

QML_SINGLETON, qmlRegisterSingletonType() 및 qmlTypeId()도 참조하십시오 .

void QQmlEngine::trimComponentCache()

엔진의 내부 컴포넌트 캐시를 정리합니다.

이 함수는 현재 사용 중이 아닌 로드된 모든 컴포넌트의 속성 메타데이터를 삭제합니다.

컴포넌트 자체의 현존하는 인스턴스, 해당 컴포넌트를 사용하는 다른 컴포넌트의 인스턴스, 또는 이러한 컴포넌트 중 하나에 의해 인스턴스화된 객체가 있는 경우, 해당 컴포넌트는 사용 중인 것으로 간주됩니다.

clearComponentCache()도 참조하십시오 .

QList<QQmlAbstractUrlInterceptor *> QQmlEngine::urlInterceptors() const

현재 활성화된 URL 인터셉터 목록을 반환합니다.

[signal] void QQmlEngine::warnings(const QList<QQmlError> &warnings)

이 신호는 QML에서 ` warnings ` 메시지가 생성될 때 발생합니다.