QQmlEngine Proxy Page

Functions

int *qmlAttachedPropertiesObject(const int *, bool)
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 int &reason)
int qmlRegisterInterface(const char *typeName)
int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)
int qmlRegisterSingletonType(const int &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int qmlRegisterType()
int qmlRegisterType(const int &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const int &message)

Macros

Function Documentation

int *qmlAttachedPropertiesObject(const int *, bool)

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.

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 int &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.

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 int &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

This function may be used to register a singleton type with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor. The type is defined by the QML file located at url. The url must be an absolute URL, i.e. url.isRelative() == false.

In addition the type's QML file must have pragma Singleton statement among its import statements.

A 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 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).

Usage:





  // Second, register the QML singleton type by calling this function in an initialization function.
  qmlRegisterSingletonType(QUrl("file:///absolute/path/SingletonType.qml"), "Qt.example.qobjectSingleton", 1, 0, "RegisteredSingleton");

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




It is also possible to have QML singleton types registered without using the qmlRegisterSingletonType function. That can be done by adding a pragma Singleton statement among the imports of the type's QML file. In addition the type must be defined in a qmldir file with a singleton keyword and the qmldir must be imported by the QML files using the singleton.

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:




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.

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

This function registers a type in the QML system with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor. The type is defined by the QML file located at url. The url must be an absolute URL, i.e. url.isRelative() == false.

Normally QML files can be loaded as types directly from other QML files, or using a qmldir file. This function allows registration of files to types from C++ code, such as when the type mapping needs to be procedurally determined at startup.

Returns -1 if the registration was not successful.

int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const int &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.