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 の所有権を引き継ぎます。

画像プロバイダにより、ピクマップおよびスレッド化された画像リクエストのサポートが可能になります。画像プロバイダの実装および使用方法の詳細については、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 解決時に使用される `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 インポートパス」で指定されたパスが含まれます。

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 を使用して以前に追加された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_ELEMENT およびQML_SINGLETONを使用して、すでにQMLシングルトン型として登録されている必要があります。モジュールがまだ読み込まれていない場合は、この時点で読み込まれます。

この関数は、成功した場合は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");

なお、デフォルトのコンストラクタや静的な create 関数を指定する代わりに、QML_UNCREATABLE() マクロを使用することで、この項目が qml エンジンによって作成できないことを示しています。

シングルトンのインスタンスは、型およびエンジンごとに1回のみ設定可能であり、使用前に設定する必要があります。シングルトンのインスタンスが一度作成または設定されると、この関数を使用して再度設定することはできなくなるため、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 を設定します。エンジンでアクティブなコントローラーは1つしか持つことができず、エンジンはそのコントローラーの所有権を取得しません。

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 のオーバーロードを呼び出す代わりに使用できます。これは、シングルトンのセットアップを 1 回だけ行えばよい場合に便利です。シングルトンへの繰り返しアクセスが必要な場合は、その 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 メッセージが生成されたときに発火します。