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)

이미지: url 스키마를 통해 요청된 이미지에 사용할 provider 을 설정하고 호스트는 providerId 입니다. QQmlEngine 은 provider 의 소유권을 갖습니다.

이미지 공급자는 픽셀맵 및 스레드 이미지 요청을 지원할 수 있습니다. 이미지 제공업체 구현 및 사용에 대한 자세한 내용은 QQuickImageProvider 문서를 참조하세요.

모든 필수 이미지 공급자는 QML 소스 파일을 로드하기 전에 엔진에 추가해야 합니다.

removeImageProvider(), QQuickImageProvider, 및 QQmlImageProviderBase 를참조하세요 .

void QQmlEngine::addImportPath(const QString &path)

엔진이 URL 기반 디렉토리 구조에서 설치된 모듈을 검색하는 디렉터리로 path 을 추가합니다.

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

path 은 가져오기 경로 목록에 추가되기 전에 표준 형식으로 변환됩니다.

새로 추가된 path 은 importPathList()의 첫 번째가 됩니다.

setImportPathList(), QML 모듈 및 QML 가져오기 경로도참조하십시오.

void QQmlEngine::addPluginPath(const QString &path)

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

기본적으로 목록에는 ., 즉 엔진이 qmldir 파일 자체의 디렉터리에서 검색하는 디렉터리만 포함됩니다.

새로 추가된 path 은 pluginPathList()에서 가장 먼저 검색됩니다.

setPluginPathList()도 참조하세요 .

void QQmlEngine::addUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

QML에서 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/ 에서 찾게 됩니다. qmldir 파일은 유형 버전 매핑 및 QML 확장 플러그인을 정의하는 데 필요합니다.

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

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에 출력되면 참을 반환하고, 그렇지 않으면 거짓을 반환합니다.

기본값은 참입니다.

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 을 사용하여 이전에 추가한 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()도 참조하세요 .

void QQmlEngine::setImportPathList(const QStringList &paths)

엔진이 URL 기반 디렉토리 구조에서 설치된 모듈을 검색할 디렉터리 목록으로 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)

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

enabled 이 참이면 QML에서 생성된 모든 경고 메시지가 stderr로 출력되고 warnings() 신호로 전송됩니다. enabled 이 거짓이면 warnings() 신호만 방출됩니다. 이를 통해 애플리케이션이 경고 출력을 직접 처리할 수 있습니다.

기본값은 참입니다.

outputWarningsToStandardError()도 참조하세요 .

void QQmlEngine::setPluginPathList(const QStringList &paths)

엔진이 가져온 모듈( qmldir 파일에서 참조)에 대한 네이티브 플러그인을 검색하는 디렉터리 목록을 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 를 호출한 후 singletonInstance의 ID 기반 오버로드를 호출하는 대신 사용할 수 있습니다. 이는 싱글톤을 한 번만 설정해야 할 때 편리하며, 싱글톤에 반복적으로 액세스해야 하는 경우 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 메시지가 생성될 때 방출됩니다.