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]
}

値の型をアドレス指定できるようにすれば、そのような型を型アサーションで使って明示的に構成することができます：

pragma ValueTypeBehavior: Addressable

QtObject {
    function process(d: real) {
        let v = d as myValueType;
        // v is a myValueType now, not a number
    }
}

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

QML_VALUE_TYPEも参照して ください。

QML_ELEMENT

クラス名や名前空間名をQMLの要素名として、その型や名前空間をQMLで利用できるように宣言します。

例えば、C++のクラスSlider を QML の型名Slider として利用可能にします。すべてのプロパティ、呼び出し可能なメソッド、列挙型が公開されます。

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 に渡します。

qt6_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_ENUM_NS のタグが付けられた列挙型を公開するために、Q_NAMESPACE のタグが付けられた名前空間を利用できるようにすることもできます：

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)

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

QML_ELEMENT 、QML_NAMED_ELEMENT()、QML_EXTENDED_NAMESPACE()、拡張オブジェクトの登録も参照してください 。

QML_EXTENDED_NAMESPACE(EXTENSION_NAMESPACE)

QMLでさらに列挙を行うための拡張として、EXTENSION_NAMESPACE を使用することを宣言します。これはその型が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)

MAJORMINORこれは、ある型が複数のメジャーバージョンで利用可能である場合に便利である。

型は自動的に登録されます：

• その型が導入されたメジャーバージョン。QML_ADDED_IN_VERSION を参照のこと。
• 型が導入されたメジャーバージョン。
• そのモジュールの現在のメジャーバージョン。それ以前にQML_REMOVED_IN_VERSION 。

注目すべきは、上記の間のPAST_MAJOR_VERSIONSには自動的に登録されないということです。QML_EXTRA_VERSIONを使用することで、さらにメジャーなバージョンに手動で型を登録することができます。

QML_ELEMENT とQML_ADDED_IN_VERSION も参照して ください。

QML_FOREIGN(FOREIGN_TYPE)

このマクロは、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 （）マクロを包含するC++型には適用されず、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)

このマクロは、クラスがどの QMLinterfaces を実装しているかを Qt に伝えます。Q_INTERFACES このマクロはQML_INTERFACE を使用しているクラスとのインターフェイスにのみ使用してください。このマクロは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)

(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)

QMLで使用可能な型または名前空間を宣言します。name を要素名として使用します。それ以外は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()マクロを持つことで)利用可能である場合にのみ有効です。デフォルトでは、QQmlEngine は、その型が最初にアクセスされたときに、その型のデフォルトコンストラクタか、T *create(QQmlEngine *, QJSEngine *) のシグネチャを持つ静的ファクトリ関数を使用して、シングルトンインスタンスを生成しようとします。両方が存在し、アクセス可能な場合、デフォルトコンストラクタが優先されます。デフォルトコンストラクタもファクトリ関数も存在しない場合、シングルトンはアクセスできません。一般に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_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;
    }
};

最後に、特定のシングルトン・オブジェクトを提供したい場合、その生成は制御できませんが、ファクトリー関数からそのオブジェクトを返すことができます。これはqmlRegisterSingletonInstance 関数の代わりとなるものです。もし

qmlRegisterSingletonInstance("MyModule", 1, 0, "MySingleton", myObject);

MySingleton *を呼び出していた場合、代わりに次のようにすることができます：

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

    // Initialize this using myObject where you would previously
    // call qmlRegisterSingletonInstance().
    inline static MySingleton *s_singletonInstance = nullptr;

    static MySingleton *create(QQmlEngine *, QJSEngine *engine)
    {
        // The instance has to exist before it is used. We cannot replace it.
        Q_ASSERT(s_singletonInstance);

        // The engine has to have the same thread affinity as the singleton.
        Q_ASSERT(engine->thread() == s_singletonInstance->thread());

        // There can only be one engine accessing the singleton.
        if (s_engine)
            Q_ASSERT(engine == s_engine);
        else
            s_engine = engine;

        // Explicitly specify C++ ownership so that the engine doesn't delete
        // the instance.
        QJSEngine::setObjectOwnership(s_singletonInstance,
                                      QJSEngine::CppOwnership);
        return s_singletonInstance;
    }

private:
    inline static QJSEngine *s_engine = nullptr;
};

このようにすると、既存のクラスMySingleton は QML のシングルトンとして宣言され、MySingleton と呼ばれます。このようにすることで、既存のクラスs_singletonInstance はQMLのシングルトンとして宣言され、 と呼ばれます。MySingleton 自体を変更する必要はありません。

QML_ELEMENT 、QML_NAMED_ELEMENT()、qmlRegisterSingletonInstance()、QQmlEngine::singletonInstance()、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"}
    ]
}

値型をアドレス指定できるようにすれば、型アサーションでそのような型を使って明示的に構築することができます：

pragma ValueTypeBehavior: Addressable

QtObject {
    function process(d: real) {
        let v = {d: d, e: objectName} as myValueType;
        // v is a myValueType now
    }
}

このマクロは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 {
   ^

このテクニックを使えば、エラーメッセージをカスタマイズするために必要なのはQ_GADGET 構造体だけで、本格的なQObject は必要ありません。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_ANONYMOUS で公開される型や、QML_ELEMENT やQML_NAMED_ELEMENT() で公開される名前空間などです。

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

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

QML_VALUE_TYPE(name)

QMLで使用可能な型または名前空間を宣言します。name を名前として使用します。型は値型でなければならず、名前は小文字でなければなりません。

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)

    // ...
};

C++とQMLの正しい統合方法の選択と QML_NAMED_ELEMENTも参照してください 。