<qqmlintegration.h>

マクロのドキュメント

QML_ADDED_IN_VERSION(MAJOR, MINOR)

指定されたMAJOR のMINOR バージョンにおいて、囲んでいる型または名前空間が追加されたことを宣言します。このバージョンは、メソッド、スロット、またはシグナルに対するQ_REVISION()マクロで指定された改訂、およびQ_PROPERTY()で宣言されたプロパティのREVISION()属性と整合しているものとみなされます。

QML_ADDED_IN_VERSION() は、QML_ELEMENT 、QML_NAMED_ELEMENT()、QML_ANONYMOUS 、またはQML_INTERFACE マクロが存在し、その型または名前空間が QML で利用可能な場合にのみ有効になります。

その型が属する QML モジュールが、この方法で決定されたバージョンよりも低いバージョンでインポートされた場合、その QML 型は表示されません。

「 QML_ELEMENT 」および「QML_NAMED_ELEMENT 」も参照してください 。

QML_ANONYMOUS

QMLにおいて、囲んでいる型が利用可能であるが匿名であることを宣言します。この型はQML内で作成したり、プロパティの宣言に使用したりすることはできませんが、C++から渡された場合は認識されます。QMLでは、C++で宣言されている場合、この型のプロパティを使用することができます。

QML_ELEMENT 、QML_NAMED_ELEMENT()、QML_UNCREATABLE()、およびQML_INTERFACEも参照してください 。

QML_ATTACHED(ATTACHED_TYPE)

囲んでいる型が、ATTACHED_TYPE を他の型に対するアタッチドプロパティとして付与することを宣言します。これは、QML_ELEMENT またはQML_NAMED_ELEMENT()マクロを使用して、その型がQMLに公開されている場合に有効になります。

関連項目: QML_ELEMENT 、QML_NAMED_ELEMENT()、qmlAttachedPropertiesObject()、および「アタッチドプロパティの提供」。

[since 6.5] QML_CONSTRUCTIBLE_VALUE

周囲の値型を「生成可能」としてマークします。つまり、この型のプロパティに JavaScript の値を代入する際、その型に対応する引数をちょうど 1 つ受け取る `Q_INVOKABLE ` のコンストラクタをすべて使用できます。

構築可能な値型は、次のように宣言できます。

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)
    QML_CONSTRUCTIBLE_VALUE
public:
    Q_INVOKABLE MyValueType(double d);

    // ...
};

上記の型を使用すると、次のQMLコードは、指定されたコンストラクタを使用してMyValueType 値を生成し、それをプロパティに代入します。

QtObject {
    property myValueType v: 5.4
}

この方法を使用して、値のリストを生成することもできます:

QtObject {
    property list<myValueType> v: [5.4, 4.5, 3.3]
}

Qt 6.8 以降、値型が属する Qml モジュールを名前空間にインポートすれば、JavaScript の `new ` 演算子を使用してその値をインスタンス化できます。

import MyModule as MM

QtObject {
    function process(d: real) {
        let v = new MM.myValueType(d);
        // v is a myValueType now
    }
}

このマクロは Qt 6.5 で導入されました。

QML_VALUE_TYPEも参照してください 。

QML_ELEMENT

囲んでいる型または名前空間を QML で利用可能とすることを宣言し、そのクラス名または名前空間名を QML 要素名として使用します。

たとえば、これにより、C++ クラス `Slider ` が、Slider という名前の QML タイプとして利用可能になります。そのすべてのプロパティ、呼び出し可能なメソッド、および列挙型が公開されます。

class Slider : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged FINAL)
    // ...
public:
    enum Slippiness {
        Dry, Wet, Icy
    };
    Q_ENUM(Slippiness)

    Q_INVOKABLE void slide(Slippiness slippiness);

    // ...
}

ビルドシステムを使用して、この型を、メジャーバージョン1 を持つ型名前空間com.mycompany.qmlcomponentsに登録することができます。qmake を使用する場合は、プロジェクトファイルに以下を指定します。

CONFIG += qmltypes
QML_IMPORT_NAME = com.mycompany.qmlcomponents
QML_IMPORT_MAJOR_VERSION = 1

CMake を使用する場合は、URI とバージョンを `qt_add_qml_module()`に渡します。

qt_add_qml_module(myapp
  URI com.mycompany.qmlcomponents
  VERSION 1.0
)

登録が完了すると、QML 内で同じ型ネームスペースとバージョン番号をインポートすることで、その型を使用できるようになります:

import com.mycompany.qmlcomponents 1.0

Slider {
    value: 12
    Component.onCompleted: slide(Slider.Icy)

    // ...
}

また、この方法を使用して、Q_NAMESPACE というタグが付いた名前空間を利用可能にすることで、そこに含まれるQ_ENUM_NS というタグが付いた列挙型を公開することもできます：

namespace MyNamespace {
  Q_NAMESPACE
  QML_ELEMENT

  enum MyEnum {
      Key1,
      Key2,
  };
  Q_ENUM_NS(MyEnum)
}

QML では、次のように列挙型を使用できます：

Component.onCompleted: console.log(MyNamespace.Key2)

注：クラス名が同じで、異なる名前空間にある場合、両方に QML_ELEMENT を指定すると競合が発生します。その場合は、どちらか一方に対してQML_NAMED_ELEMENT() を使用するようにしてください。

関連項目: 「C++とQML間の適切な統合方法の選択」、QML_NAMED_ELEMENT()、Q_REVISION()、およびQML_ADDED_IN_VERSION()も参照してください 。

QML_EXTENDED(EXTENDED_TYPE)

この宣言により、囲んでいる型がEXTENDED_TYPE を拡張として使用し、QMLでさらなるプロパティ、メソッド、および列挙型を提供することを指定します。これは、QML_ELEMENT またはQML_NAMED_ELEMENT()マクロを使用して、その型がQMLに公開されている場合に有効になります。

関連項目： QML_ELEMENT 、QML_NAMED_ELEMENT()、QML_EXTENDED_NAMESPACE()、および「拡張オブジェクトの登録」。

QML_EXTENDED_NAMESPACE(EXTENSION_NAMESPACE)

この宣言により、囲み型はEXTENSION_NAMESPACE を拡張として使用し、QMLでさらなる列挙型を提供することを指定します。これは、QML_ELEMENT またはQML_NAMED_ELEMENT()マクロを使用して、その型がQMLに公開されている場合に有効になります。これを機能させるには、列挙型をメタオブジェクトシステムに公開する必要があります。

たとえば、次のようなC++コードがあるとします。

namespace MyNamespace {
    Q_NAMESPACE
    enum MyEnum { MyEnumerator = 10 };
    Q_ENUM_NS(MyEnum)
}

class QmlType : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_EXTENDED_NAMESPACE(MyNamespace)
}

QMLからこの列挙型にアクセスできます：

QmlType {
    property int i: QmlType.MyEnumerator // i will be 10
}

関連項目： QML_NAMESPACE_EXTENDED()、QML_ELEMENT 、QML_NAMED_ELEMENT()、QML_EXTENDED()、拡張オブジェクトの登録、Q_ENUM 、およびQ_ENUM_NS 。

QML_EXTRA_VERSION(MAJOR, MINOR)

その型をバージョンMAJOR でも利用可能にするよう宣言します。MINOR 。これは、ある型を複数のメジャーバージョンで利用可能にする場合に役立ちます。

型は、以下の条件に基づいて自動的に登録されます：

• その型が導入されたメジャーバージョン（QML_ADDED_IN_VERSION を参照）。
• そのメンバーが導入されたすべてのメジャーバージョン。
• そのモジュールの現在のメジャーバージョン（それ以前にQML_REMOVED_IN_VERSION として登録されていた場合を除く）。

特に、上記の範囲外のPAST_MAJOR_VERSIONSには自動的に登録されません。QML_EXTRA_VERSION を使用することで、さらに先のメジャーバージョンにタイプを手動で登録することができます。

QML_ELEMENT およびQML_ADDED_IN_VERSIONも参照してください 。

QML_FOREIGN(FOREIGN_TYPE)

囲んでいる C++ 型内のQML_ELEMENT 、QML_NAMED_ELEMENT()、QML_ANONYMOUS 、QML_INTERFACE 、QML_UNCREATABLE()、QML_SINGLETON、QML_ADDED_IN_VERSION()、QML_REMOVED_IN_VERSION()、QML_ADDED_IN_MINOR_VERSION()、QML_REMOVED_IN_MINOR_VERSION()、QML_EXTENDED()、QML_EXTENDED_NAMESPACE()、またはQML_NAMESPACE_EXTENDED() といったマクロは、その囲んでいる型には適用されず、代わりにFOREIGN_TYPE に適用されることを宣言します。 外側の型は、Q_GADGET またはQ_OBJECT マクロを使用して、メタオブジェクトシステムに登録する必要があります。

これは、たとえばサードパーティのライブラリに属しているなどの理由で、マクロを追加するために修正できない型を登録する場合に役立ちます。名前空間を登録するには、QML_FOREIGN_NAMESPACE() を参照してください。

関連項目： QML_ELEMENT 、QML_NAMED_ELEMENT()、およびQML_FOREIGN_NAMESPACE()。

QML_FOREIGN_NAMESPACE(FOREIGN_NAMESPACE)

囲んでいる C++ ネームスペース内の `QML_ELEMENT`、`QML_NAMED_ELEMENT()`、`QML_ANONYMOUS`、`QML_INTERFACE`、` QML_UNCREATABLE()`、`QML_SINGLETON`、`QML_ADDED_IN_VERSION()`、`QML_REMOVED_IN_VERSION()`、`QML_ADDED_IN_MINOR_VERSION()`、または `QML_REMOVED_IN_MINOR_VERSION()` といったマクロは、囲んでいる型には適用されず、代わりに `FOREIGN_NAMESPACE` に適用されることを宣言します。 外側の名前空間は、Q_NAMESPACE マクロを使用してメタオブジェクトシステムに登録する必要があります。

これは、例えばサードパーティのライブラリに属しているなど、マクロを追加するために修正できない名前空間を登録する場合に役立ちます。

QML_ELEMENT 、QML_NAMED_ELEMENT()、およびQML_FOREIGN()も参照してください 。

QML_IMPLEMENTS_INTERFACES(interfaces)

このマクロは、クラスがどのQMLのinterfaces を実装しているかをQtに伝えます。このマクロは、QML_INTERFACE を使用してクラスと連携する場合にのみ使用すべきであり、それ以外の場合はQ_INTERFACES を使用してください。QML_ELEMENT による宣言的な登録が正しく機能するためには、このマクロが必要です。

QML_INTERFACE およびQ_INTERFACESも参照してください 。

QML_INTERFACE

このマクロは、囲んでいる C++ 型を QML システムにインターフェースとして登録します。

QMLでインターフェースとして登録される型は、メタオブジェクトシステムに対してもインターフェースとして宣言する必要があります。例：

struct FooInterface
{
    QML_INTERFACE
public:
    virtual ~FooInterface();
    virtual void doSomething() = 0;
};

Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")

このようにQMLに登録されると、プロパティ型として使用できるようになります：

Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)

このプロパティにQObject のサブクラスを割り当てると、QMLエンジンは自動的にFooInterface* へのインターフェースキャストを行います。

QML では、インターフェース型は暗黙的に匿名であり、生成することはできません。

注：QML_INTERFACE を使用して型を継承する場合は、Q_INTERFACES の代わりにQML_IMPLEMENTS_INTERFACES を使用してください。

関連項目: QML_IMPLEMENTS_INTERFACES(),QML_ELEMENT,QML_NAMED_ELEMENT(),QML_UNCREATABLE(),QML_ANONYMOUS 。

QML_NAMED_ELEMENT(name)

name を要素名として使用し、囲んでいる型または名前空間をQMLで利用可能であることを宣言します。それ以外の動作はQML_ELEMENT と同じです。

class SqlEventDatabase : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(EventDatabase)

    // ...
};

「C++ と QML 間の適切な統合方法の選択」および「QML_ELEMENT 」も参照してください 。

QML_REMOVED_IN_VERSION(MAJOR, MINOR)

指定されたMAJOR のMINOR バージョンにおいて、囲みとなる型または名前空間が削除されたことを宣言します。これは主に、QML型の実装を置き換える際に役立ちます。 同じQML名を持つ別の型または名前空間に対応するQML_ADDED_IN_VERSION()が存在する場合、モジュールのバージョンがMAJOR より低いMINOR をインポートする際には削除された型が使用され、モジュールのバージョンがMAJOR 以上MINOR をインポートする際には追加された型が使用されます。

QML_REMOVED_IN_VERSION() は、QML_ELEMENT 、QML_NAMED_ELEMENT()、QML_ANONYMOUS 、またはQML_INTERFACE マクロが存在し、QML で型または名前空間が利用可能な場合にのみ有効になります。

QML_ELEMENT およびQML_NAMED_ELEMENTも参照してください 。

QML_SEQUENTIAL_CONTAINER(VALUE_TYPE)

このマクロは、囲んでいる型または参照されている型を、VALUE_TYPE 要素のシーケンスを管理するシーケンシャルコンテナとして宣言します。VALUE_TYPE は、実際の値型、またはオブジェクト型へのポインタのいずれかです。コンテナは通常テンプレートであるため、実際のコンテナ宣言にこのマクロを追加できることはほとんどありません。QML_FOREIGN を使用して、型登録をテンプレートのインスタンス化に紐付ける必要があります。この手法を使用すると、たとえば次のようにシーケンシャルコンテナを宣言できます:

class IntDequeRegistration
{
  Q_GADGET
  QML_FOREIGN(std::deque<int>)
  QML_ANONYMOUS
  QML_SEQUENTIAL_CONTAINER(int)
};

これにより、QML内でそのコンテナをJavaScriptの配列のように使用できるようになります。

class Maze
{
  Q_OBJECT
  Q_ELEMENT
  // 0: North, 1: East, 2: South, 3: West
  Q_PROPERTY(std::deque<int> solution READ solution CONSTANT FINAL)
  [...]
}

Item {
  Maze {
    id: maze
  }

  function showSolution() {
      maze.solution.forEach([...])
  }
}

関連項目: QML_ANONYMOUS およびQML_FOREIGN()。

QML_SINGLETON

QMLにおいて、囲んでいる型をシングルトンとして宣言します。これは、その型がQ_OBJECT であり、かつQMLで利用可能である場合（QML_ELEMENT またはQML_NAMED_ELEMENT()マクロが存在する場合）にのみ有効です。QML_UNCREATABLE() マクロによってその型が明示的に「生成不可」としてマークされていない限り、各QQmlEngine は、その型に初めてアクセスされた際に、型のデフォルトコンストラクタ、またはシグネチャT *create(QQmlEngine *, QJSEngine *) を持つ静的ファクトリ関数のいずれかを使用して、シングルトンインスタンスの生成を試みます。両方が存在し、かつアクセス可能な場合、デフォルトコンストラクタが優先されます。

デフォルトコンストラクタもファクトリ関数も存在せず、かつQQmlEngine::setExternalSingletonInstance を使用してエンジンにインスタンスが明示的に設定されていない場合、そのシングルトンにはアクセスできません。QMLエンジンがシングルトンをインスタンス化した場合、エンジンは通常、そのシングルトンの所有権を引き受け、エンジン自体が破棄される際にそれを削除します。 対照的に、外部のシングルトンについては、明示的に指示されない限り、エンジンは所有権を引き受けません。この動作は、シングルトンに対してQJSEngine::setObjectOwnership()を呼び出し、意図する動作を明示的に指定することで制御できます。

デフォルトでコンストラクタが定義されているクラスをシングルトンとして宣言するには、QML_SINGLETONを追加するだけで十分です:

class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    // Q_PROPERTY( ... )
public:
    // members, Q_INVOKABLE functions, etc.
};

シングルトンクラスがデフォルトで初期化可能ではないが、変更可能な場合は、アクセス可能にするためにファクトリ関数を追加できます：

class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    // Q_PROPERTY( ... )

public:
    static MySingleton *create(QQmlEngine *qmlEngine, QJSEngine *jsEngine)
    {
        MySingleton *result = nullptr;
        // Create the object using some custom constructor or factory.
        // The QML engine will assume ownership and delete it, eventually.
        return result;
    }

    // members, Q_INVOKABLE functions, etc
};

必要に応じてエンジンにインスタンスを生成させるのではなく、エンジンにインスタンスを直接提供したい場合は、QML_UNCREATABLE() マクロを使用できます。その場合、その型はデフォルトでコンストラクタが定義されている必要も、ファクトリ関数を持つ必要もありません:

class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    QML_UNCREATABLE("Provided by C++")
    // Q_PROPERTY( ... )
public:
    MySingleton(BackendObject* backend, QObject* parent);

    // members, Q_INVOKABLE functions, etc
};

これを行うには、QMLからシングルトンに初めてアクセスする前に、QQmlEngine::setExternalSingletonInstance() を使用して、MySingleton のインスタンスをエンジンに設定しておく必要があります。これは、qmlRegisterSingletonInstance 関数の代替となります。

クラスを変更できず、かつデフォルトコンストラクタや適切なファクトリ関数も持っていない場合は、QML_FOREIGN ラッパーを提供してファクトリ関数を定義することができます:

struct SingletonForeign
{
    Q_GADGET
    QML_FOREIGN(MySingleton)
    QML_SINGLETON
    QML_NAMED_ELEMENT(MySingleton)
public:

    static MySingleton *create(QQmlEngine *, QJSEngine *engine)
    {
        MySingleton *result = nullptr;
        // Create the instance using some custom constructor or factory.
        // The QML engine will assume ownership and delete it, eventually.
        return result;
    }
};

変更できないシングルトンを宣言するための `QML_FOREIGN ` によるアプローチは、`QML_UNCREATABLE()` と組み合わせて使用することも可能です。その場合、ファクトリ関数は必要ありませんが、前述と同様に、インスタンスは最初に使用する前にエンジンに設定しておく必要があります：

struct SingletonForeign
{
    Q_GADGET
    QML_FOREIGN(MySingleton)
    QML_SINGLETON
    QML_NAMED_ELEMENT(MySingleton)
    QML_UNCREATABLE("Provided from C++")
};

QML_ELEMENT 、QML_NAMED_ELEMENT()、qmlRegisterSingletonInstance()、QQmlEngine::singletonInstance()、QQmlEngine::setExternalSingletonInstance()、およびQML におけるシングルトンも参照してください。

[since 6.5] QML_STRUCTURED_VALUE

周囲の値型を構造化型としてマークします。構造化値型は、JavaScript オブジェクトからプロパティごとに構築することができ、またそのように構築されることが推奨されます。ただし、構造化値型は常に `QML_CONSTRUCTIBLE_VALUE` でもあります。つまり、プリミティブ型からの構築を処理するために、Q_INVOKABLE のコンストラクタを指定することも可能です。

構造化値型は次のように宣言できます:

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)
    QML_STRUCTURED_VALUE
    Q_PROPERTY(double d READ d WRITE setD)
    Q_PROPERTY(string e READ e WRITE setE)

    // ...
};

その後、この型のプロパティには次のように値を代入できます：

QtObject {
    property myValueType v: ({d: 4.4, e: "a string"})
}

余分な括弧は、JavaScript オブジェクトと、JavaScript コードブロックと解釈されかねないものを区別するために必要です。

この方法では、値のリストも生成できます:

QtObject {
    property list<myValueType> v: [
        {d: 4.4, e: "a string"},
        {d: 7.1, e: "another string"}
    ]
}

このマクロは Qt 6.5 で導入されました。

QML_VALUE_TYPE およびQML_CONSTRUCTIBLE_VALUEも参照してください 。

QML_UNAVAILABLE

このマクロは、囲んでいる型をQMLでは利用できないものとして宣言します。QQmlTypeNotAvailable という内部のダミー型を、QML_FOREIGN()型として登録し、さらに指定したその他のQMLマクロを使用します。

通常、モジュールによってエクスポートされる型は固定されているべきです。しかし、C++の型が利用できない場合は、少なくともQMLの型名を「予約」し、利用できない型のユーザーに対して意味のあるエラーメッセージを表示する必要があります。

例：

#ifdef NO_GAMES_ALLOWED
struct MinehuntGame
{
    Q_GADGET
    QML_NAMED_ELEMENT(Game)
    QML_UNAVAILABLE
    QML_UNCREATABLE("Get back to work, slacker!");
};
#else
class MinehuntGame : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(Game)
    // ...
};
#endif

これにより、「Game」タイプを使用しようとするQMLコードでは、以下のエラーメッセージが表示されます：

fun.qml: Get back to work, slacker!
   Game {
   ^

この手法を用いれば、エラーメッセージをカスタマイズするために、本格的なQObject ではなく、Q_GADGET 構造体だけで済みます。QML_UNCREATABLE()がなくても、QML_UNAVAILABLEは、完全に未知の型に対して通常表示される「is not a type」というエラーメッセージよりも具体的なエラーメッセージを生成します。

関連項目： QML_ELEMENT 、QML_NAMED_ELEMENT()、QML_UNCREATABLE()、およびQML_FOREIGN()。

QML_UNCREATABLE(reason)

この宣言により、囲み型はQMLから生成できないものとされます。この設定は、QML_ELEMENT またはQML_NAMED_ELEMENT()マクロによって、その型がQMLで利用可能な場合に有効になります。QMLからその型を生成しようとする試みが検出された場合、reason というエラーメッセージが出力されます。

一部のQML型は暗黙的に生成不可となっています。具体的には、QML_ANONYMOUS で公開されている型や、QML_ELEMENT またはQML_NAMED_ELEMENT()で公開されている名前空間などが該当します。

その型がQML_SINGLETON で宣言されたシングルトンである場合、QML_UNCREATABLE を追加することで、QQmlEngine::setExternalSingletonInstance を使用してその型のインスタンスがエンジン上で明示的に設定されるという約束が示されます。

Qt 6.0 以降では、理由の代わりに "" を使用することで、代わりに標準メッセージを使用できるようになりました。

QML_ELEMENT 、QML_NAMED_ELEMENT()、およびQML_ANONYMOUSも参照してください 。

QML_VALUE_TYPE(name)

name を名前として使用し、囲んでいる型または名前空間を QML で利用可能にするように宣言します。型は値型である必要があり、名前は小文字でなければなりません。

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)

    // ...
};

「C++ と QML 間の適切な統合方法の選択」および「QML_NAMED_ELEMENT 」も参照してください 。