Qt 5.13 | Qt QML | QQmlEngine Proxy Page

Qt 5.13.2 Reference Documentation

# QQmlEngine Proxy Page

## Functions

QObject * | qmlAttachedPropertiesObject(const QObject *attachee, bool create = ...)
class Q_DECL_IMPORT | qmlClearTypeRegistrations()
class Q_DECL_IMPORT | qmlProtectModule(const char *uri, int majVersion)
int | qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int | qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)
int | qmlRegisterInterface(const char *typeName)
class Q_DECL_IMPORT | qmlRegisterModule(const char *uri, int versionMajor, int versionMinor)
int | qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)
int | qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QJSValue (*)(QQmlEngine *, QJSEngine *) callback)
int | qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *(*)(QQmlEngine *, QJSEngine *) callback)
int | qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int | qmlRegisterType()
class Q_DECL_IMPORT | qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)
int | qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

## Macros

| QML_DECLARE_TYPE
| QML_DECLARE_TYPEINFO(Type, Flags)

## Function Documentation

### QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = ...)

The form of this template function is:

      template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)

This returns the attached object instance that has been attached to the specified attachee by the attaching type T.

If create is true and type T is a valid attaching type, this creates and returns a new attached object instance.

Returns 0 if type T is not a valid attaching type, or if create is false and no attachment object instance has previously been created for attachee.

See also Providing Attached Properties.

### class Q_DECL_IMPORT qmlClearTypeRegistrations()

Clears all stored type registrations, such as those produced with qmlRegisterType().

Do not call this function while a QQmlEngine exists or behavior will be undefined. Any existing QQmlEngines must be deleted before calling this function. This function only affects the application global cache. Delete the QQmlEngine to clear all cached data relating to that engine.

### class Q_DECL_IMPORT qmlProtectModule(const char *uri, int majVersion)

This function protects a module from having types registered into it. This can be used to prevent other plugins from injecting types into your module. It can also be a performance improvement, as it allows the engine to skip checking for the possibility of new types or plugins when this import is reached.

The performance benefit is primarily seen when registering application specific types from within the application instead of through a plugin. Using qmlProtectModule allows the engine to skip checking for a plugin when that uri is imported, which can be noticeable with slow file systems.

After this function is called, any attempt to register C++ types into this uri, major version combination will lead to a runtime error. Call this after you have registered all of your types with the engine.

Returns true if the module with uri as a module identifier and majVersion as a major version number was found and locked, otherwise returns false. The module must contain exported types in order to be found.

### int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

This template function registers the C++ type and its extension object in the QML system with the name qmlName in the library imported from uri having version number composed from versionMajor and versionMinor. Properties not available in the main type will be searched for in the extension object.

Returns the QML type id.

See also qmlRegisterType() and Registering Extension Objects.

### int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)

This template function registers the C++ type and its extension in the QML system with the name qmlName in the library imported from uri having version number composed from versionMajor and versionMinor.

While the type has a name and a type, it cannot be created. An error message with the given reason is printed if the user attempts to create an instance of this type.

This is useful where the type is only intended for providing attached properties, enum values or an abstract base class with its extension.

Returns the QML type id.

See also qmlRegisterUncreatableType().

### int qmlRegisterInterface(const char *typeName)

This template function registers the C++ type in the QML system under the name typeName.

Types registered as an interface with the engine should also declare themselves as an interface with the meta object system. For example:

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

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

When registered with the QML engine in this way, they can be used as property types:

Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)

When you assign a QObject sub-class to this property, the QML engine does the interface cast to `FooInterface*` automatically.

Returns the QML type id.

### class Q_DECL_IMPORT qmlRegisterModule(const char *uri, int versionMajor, int versionMinor)

This function registers a module in a particular uri with a version specified in versionMajor and versionMinor.

This can be used to make a certain module version available, even if no types are registered for that version. This is particularly useful for keeping the versions of related modules in sync.

This function was introduced in Qt 5.9.

### int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)

This template function registers the specified revision of a C++ type in the QML system with the library imported from uri having the version number composed from versionMajor and versionMinor.

Returns the QML type id.

      template<typename T, int metaObjectRevision>
      int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);

This function is typically used to register the revision of a base class to use for the specified version of the type (see Type Revisions and Versions).

### int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QJSValue (*)(QQmlEngine *, QJSEngine *) callback)

This function may be used to register a singleton type provider callback in a particular uri and typeName with a version specified in versionMajor and versionMinor.

Installing a singleton type allows developers to provide arbitrary functionality (methods and properties) to a client without requiring individual instances of the type to be instantiated by the client.

A singleton type may be either a QObject or a QJSValue. This function should be used to register a singleton type provider function which returns a QJSValue as a singleton type.

NOTE: QJSValue singleton type properties will not trigger binding re-evaluation if changed.

Usage:

      // First, define the singleton type provider function (callback).
      static QJSValue example_qjsvalue_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
      {
          Q_UNUSED(engine)

          static int seedValue = 5;
          QJSValue example = scriptEngine->newObject();
          example.setProperty("someProperty", seedValue++);
          return example;
      }

      // Second, register the singleton type provider with QML by calling this function in an initialization function.
      qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", example_qjsvalue_singletontype_provider);

Alternatively, you can use a C++11 lambda:

      qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QJSValue {
          Q_UNUSED(engine)

          static int seedValue = 5;
          QJSValue example = scriptEngine->newObject();
          example.setProperty("someProperty", seedValue++);
          return example;
      });

In order to use the registered singleton type in QML, you must import the singleton type.

      import QtQuick 2.0
      import Qt.example.qjsvalueApi 1.0 as ExampleApi
      Item {
          id: root
          property int someValue: ExampleApi.MyApi.someProperty
      }

See also Choosing the Correct Integration Method Between C++ and QML.

### int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *(*)(QQmlEngine *, QJSEngine *) callback)

This function may be used to register a singleton type provider callback in a particular uri and typeName with a version specified in versionMajor and versionMinor.

Installing a singleton type into a uri allows developers to provide arbitrary functionality (methods and properties) to clients without requiring individual instances ot the type to be instantiated by the client.

A singleton type may be either a QObject or a QJSValue. This function should be used to register a singleton type provider function which returns a QObject of the given type T as a singleton type.

A QObject singleton type may be referenced via the type name with which it was registered, and this typename may be used as the target in a Connections type or otherwise used as any other type id would. One exception to this is that a QObject singleton type property may not be aliased (because the singleton type name does not identify an object within the same component as any other item).

NOTE: A QObject singleton type instance returned from a singleton type provider is owned by the QML engine unless the object has explicit QQmlEngine::CppOwnership flag set.

Usage:

      // First, define your QObject which provides the functionality.
      class SingletonTypeExample : public QObject
      {
          Q_OBJECT
          Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)

      public:
          SingletonTypeExample(QObject* parent = 0)
              : QObject(parent), m_someProperty(0)
          {
          }

          ~SingletonTypeExample() {}

          Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; }

          int someProperty() const { return m_someProperty; }
          void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); }

      signals:
          void somePropertyChanged(int newValue);

      private:
          int m_someProperty;
      };

      // Second, define the singleton type provider function (callback).
      static QObject *example_qobject_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
      {
          Q_UNUSED(engine)
          Q_UNUSED(scriptEngine)

          SingletonTypeExample *example = new SingletonTypeExample();
          return example;
      }

      // Third, register the singleton type provider with QML by calling this function in an initialization function.
      qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider);

Alternatively, you can use a C++11 lambda:

      qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * {
          Q_UNUSED(engine)
          Q_UNUSED(scriptEngine)

          SingletonTypeExample *example = new SingletonTypeExample();
          return example;
      });

In order to use the registered singleton type in QML, you must import the singleton type.

      import QtQuick 2.0
      import Qt.example.qobjectSingleton 1.0
      Item {
          id: root
          property int someValue: MyApi.someProperty

          Component.onCompleted: {
              someValue = MyApi.doSomething()
          }
      }

See also Choosing the Correct Integration Method Between C++ and QML.

### int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

This template function registers the C++ type in the QML system with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor.

Returns the QML type id.

There are two forms of this template function:

      template<typename T>
      int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);

      template<typename T, int metaObjectRevision>
      int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);

The former is the standard form which registers the type T as a new type. The latter allows a particular revision of a class to be registered in a specified version (see Type Revisions and Versions).

For example, this registers a C++ class `MySliderItem` as a QML type named `Slider` for version 1.0 of a type namespace called "com.mycompany.qmlcomponents":

      qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");

Once this is registered, the type can be used in QML by importing the specified type namespace and version number:

      import com.mycompany.qmlcomponents 1.0

      Slider {
          // ...
      }

Note that it's perfectly reasonable for a library to register types to older versions than the actual version of the library. Indeed, it is normal for the new library to allow QML written to previous versions to continue to work, even if more advanced versions of some of its types are available.

See also Choosing the Correct Integration Method Between C++ and QML.

### int qmlRegisterType()

This is an overloaded function.

This template function registers the C++ type in the QML system. Instances of this type cannot be created from the QML system.

This function should be used when the type will not be referenced by name. Specifically, it has to be used for C++ types that are used as the left-hand side of a property binding.

For example, consider the following two classes:

      class Bar : public QObject
      {
          Q_OBJECT
          Q_PROPERTY(QString baz READ baz WRITE setBaz NOTIFY bazChanged)

      public:
          Bar() {}

          QString baz() const { return mBaz; }

          void setBaz(const QString &baz)
          {
              if (baz == mBaz)
                  return;

              mBaz = baz;
              emit bazChanged();
          }

      signals:
          void bazChanged();

      private:
          QString mBaz;
      };

      class Foo : public QObject
      {
          Q_OBJECT
          Q_PROPERTY(Bar *bar READ bar CONSTANT FINAL)

      public:
          Foo() {}

          Bar *bar() { return &mBar; }

      private:
          Bar mBar;
      };

In QML, we assign a string to the `baz` property of `bar`:

      Foo {
          bar.baz: "abc"
          Component.onCompleted: print(bar.baz)
      }

For the QML engine to know that the `Bar` type has a `baz` property, we have to make `Bar` known:

      qmlRegisterType<Foo>("App", 1, 0, "Foo");
      qmlRegisterType<Bar>();

As the `Foo` type is instantiated in QML, it must be registered with the version of qmlRegisterType() that takes an import URI.

Returns the QML type id.

See also Choosing the Correct Integration Method Between C++ and QML.

### class Q_DECL_IMPORT qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)

This function registers the staticMetaObject and its extension in the QML system with the name qmlName in the library imported from uri having version number composed from versionMajor and versionMinor.

An instance of the meta object cannot be created. An error message with the given reason is printed if the user attempts to create it.

This function is useful for registering Q_NAMESPACE namespaces.

Returns the QML type id.

For example:

      namespace MyNamespace {
        Q_NAMESPACE
        enum MyEnum {
            Key1,
            Key2,
        };
        Q_ENUMS(MyEnum)
      }

      //...
      qmlRegisterUncreatableMetaObject(MyNamespace::staticMetaObject, "io.qt", 1, 0, "MyNamespace", "Access to enums & flags only");

On the QML side, you can now use the registered enums:

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

This function was introduced in Qt 5.8.

### int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

This template function registers the C++ type in the QML system with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor.

While the type has a name and a type, it cannot be created, and the given error message will result if creation is attempted.

This is useful where the type is only intended for providing attached properties or enum values.

Returns the QML type id.

See also qmlRegisterTypeNotAvailable() and Choosing the Correct Integration Method Between C++ and QML.

## Macro Documentation

### QML_DECLARE_TYPE

Equivalent to `Q_DECLARE_METATYPE(TYPE *)` and `Q_DECLARE_METATYPE(QQmlListProperty<TYPE>)`

### QML_DECLARE_TYPEINFO(Type, Flags)

Declares additional properties of the given Type as described by the specified Flags.

Current the only supported type info is `QML_HAS_ATTACHED_PROPERTIES` which declares that the Type supports attached properties.