QMetaMethod Class

The QMetaMethod class provides meta-data about a member function. More...

Header: #include <QMetaMethod>

Public Types

enum Access { Private, Protected, Public }
enum Attributes { Compatibility, Cloned, Scriptable }
enum MethodType { Method, Signal, Slot, Constructor }

Public Functions

QMetaMethod()
Access access() const
int attributes() const
const QMetaObject *enclosingMetaObject() const
void getParameterTypes(int *types) const
bool invoke(QObject *object, Qt::ConnectionType connectionType, QGenericReturnArgument returnValue, QGenericArgument val0 = QGenericArgument(nullptr), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument(), QGenericArgument val4 = QGenericArgument(), QGenericArgument val5 = QGenericArgument(), QGenericArgument val6 = QGenericArgument(), QGenericArgument val7 = QGenericArgument(), QGenericArgument val8 = QGenericArgument(), QGenericArgument val9 = QGenericArgument()) const
bool invoke(QObject *object, QGenericReturnArgument returnValue, QGenericArgument val0 = QGenericArgument(0), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument(), QGenericArgument val4 = QGenericArgument(), QGenericArgument val5 = QGenericArgument(), QGenericArgument val6 = QGenericArgument(), QGenericArgument val7 = QGenericArgument(), QGenericArgument val8 = QGenericArgument(), QGenericArgument val9 = QGenericArgument()) const
bool invoke(QObject *object, Qt::ConnectionType connectionType, QGenericArgument val0 = QGenericArgument(0), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument(), QGenericArgument val4 = QGenericArgument(), QGenericArgument val5 = QGenericArgument(), QGenericArgument val6 = QGenericArgument(), QGenericArgument val7 = QGenericArgument(), QGenericArgument val8 = QGenericArgument(), QGenericArgument val9 = QGenericArgument()) const
bool invoke(QObject *object, QGenericArgument val0 = QGenericArgument(0), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument(), QGenericArgument val4 = QGenericArgument(), QGenericArgument val5 = QGenericArgument(), QGenericArgument val6 = QGenericArgument(), QGenericArgument val7 = QGenericArgument(), QGenericArgument val8 = QGenericArgument(), QGenericArgument val9 = QGenericArgument()) const
bool invoke(QObject *obj, Qt::ConnectionType type, QMetaMethodReturnArgument ret, Args &&... arguments) const
bool invoke(QObject *obj, Qt::ConnectionType type, Args &&... arguments) const
bool invoke(QObject *obj, QMetaMethodReturnArgument ret, Args &&... arguments) const
bool invoke(QObject *obj, Args &&... arguments) const
bool invokeOnGadget(void *gadget, QGenericReturnArgument returnValue, QGenericArgument val0 = QGenericArgument(nullptr), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument(), QGenericArgument val4 = QGenericArgument(), QGenericArgument val5 = QGenericArgument(), QGenericArgument val6 = QGenericArgument(), QGenericArgument val7 = QGenericArgument(), QGenericArgument val8 = QGenericArgument(), QGenericArgument val9 = QGenericArgument()) const
bool invokeOnGadget(void *gadget, QGenericArgument val0 = QGenericArgument(0), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument(), QGenericArgument val4 = QGenericArgument(), QGenericArgument val5 = QGenericArgument(), QGenericArgument val6 = QGenericArgument(), QGenericArgument val7 = QGenericArgument(), QGenericArgument val8 = QGenericArgument(), QGenericArgument val9 = QGenericArgument()) const
bool invokeOnGadget(void *gadget, QMetaMethodReturnArgument ret, Args &&... arguments) const
bool invokeOnGadget(void *gadget, Args &&... arguments) const
bool isConst() const
bool isValid() const
int methodIndex() const
QByteArray methodSignature() const
MethodType methodType() const
QByteArray name() const
int parameterCount() const
QMetaType parameterMetaType(int index) const
QList<QByteArray> parameterNames() const
int parameterType(int index) const
QByteArray parameterTypeName(int index) const
QList<QByteArray> parameterTypes() const
int relativeMethodIndex() const
QMetaType returnMetaType() const
int returnType() const
int revision() const
const char *tag() const
const char *typeName() const

Static Public Members

QMetaMethod fromSignal(PointerToMemberFunction signal)
bool operator!=(const QMetaMethod &m1, const QMetaMethod &m2)
bool operator==(const QMetaMethod &m1, const QMetaMethod &m2)

Macros

Detailed Description

\inmoduleQtCore

\ingroupobjectmodel

A QMetaMethod has a methodType(), a methodSignature(), a list of parameterTypes() and parameterNames(), a return typeName(), a tag(), and an access() specifier. You can use invoke() to invoke the method on an arbitrary QObject.

See also QMetaObject, QMetaEnum, QMetaProperty, and Qt's Property System.

Member Type Documentation

enum QMetaMethod::Access

This enum describes the access level of a method, following the conventions used in C++.

ConstantValue
QMetaMethod::Private0
QMetaMethod::Protected1
QMetaMethod::Public2

enum QMetaMethod::Attributes

\internal

ConstantValue
QMetaMethod::Compatibility0x1
QMetaMethod::Cloned0x2
QMetaMethod::Scriptable0x4

enum QMetaMethod::MethodType

ConstantValueDescription
QMetaMethod::Method0The function is a plain member function.
QMetaMethod::Signal1The function is a signal.
QMetaMethod::Slot2The function is a slot.
QMetaMethod::Constructor3The function is a constructor.

Member Function Documentation

template <typename Args> bool QMetaMethod::invoke(QObject *obj, Args &&... arguments) const

template <typename Args> bool QMetaMethod::invoke(QObject *obj, QMetaMethodReturnArgument ret, Args &&... arguments) const

template <typename Args> bool QMetaMethod::invoke(QObject *obj, Qt::ConnectionType type, Args &&... arguments) const

template <typename Args> bool QMetaMethod::invoke(QObject *obj, Qt::ConnectionType type, QMetaMethodReturnArgument ret, Args &&... arguments) const

\since6.5

Invokes this method on the object object. Returns true if the member could be invoked. Returns false if there is no such member or the parameters did not match.

For the overloads with a QMetaMethodReturnArgument parameter, the return value of the member function call is placed in ret. For the overloads without such a member, the return value of the called function (if any) will be discarded. QMetaMethodReturnArgument is an internal type you should not use directly. Instead, use the qReturnArg() function.

The overloads with a Qt::ConnectionType type parameter allow explicitly selecting whether the invocation will be synchronous or not:

  • If type is Qt::DirectConnection, the member will be invoked immediately in the current thread.
  • If type is Qt::QueuedConnection, a QEvent will be sent and the member is invoked as soon as the application enters the event loop in the thread the obj was created in or was moved to.
  • If type is Qt::BlockingQueuedConnection, the method will be invoked in the same way as for Qt::QueuedConnection, except that the current thread will block until the event is delivered. Using this connection type to communicate between objects in the same thread will lead to deadlocks.
  • If type is Qt::AutoConnection, the member is invoked synchronously if obj lives in the same thread as the caller; otherwise it will invoke the member asynchronously. This is the behavior of the overloads that do not have the type parameter.

To asynchronously invoke the animateClick() slot on a QPushButton:

 int methodIndex = pushButton->metaObject()->indexOfMethod("animateClick()");
 QMetaMethod method = metaObject->method(methodIndex);
 method.invoke(pushButton, Qt::QueuedConnection);

With asynchronous method invocations, the parameters must be copyable types, because Qt needs to copy the arguments to store them in an event behind the scenes. Since Qt 6.5, this function automatically registers the types being used; however, as a side-effect, it is not possible to make calls using types that are only forward-declared. Additionally, it is not possible to make asynchronous calls that use references to non-const-qualified types as parameters either.

To synchronously invoke the compute(QString, int, double) slot on some arbitrary object obj retrieve its return value:

 QString retVal;
 QByteArray normalizedSignature = QMetaObject::normalizedSignature("compute(QString, int, double)");
 int methodIndex = obj->metaObject()->indexOfMethod(normalizedSignature);
 QMetaMethod method = obj->metaObject()->method(methodIndex);
 method.invoke(obj, Qt::DirectConnection, qReturnArg(retVal),
               QString("sqrt"), 42, 9.7);

If the "compute" slot does not take exactly one QString, one int, and one double in the specified order, the call will fail. Note how it was necessary to be explicit about the type of the QString, as the character literal is not exactly the right type to match. If the method instead took a QByteArray, a qint64, and a long double, the call would need to be written as:

 QString retVal;
 QByteArray normalizedSignature = QMetaObject::normalizedSignature("compute(QByteArray, qint64, long double)");
 int methodIndex = obj->metaObject()->indexOfMethod(normalizedSignature);
 QMetaMethod method = obj->metaObject()->method(methodIndex);
 method.invoke(obj, Qt::DirectConnection, qReturnArg(retVal),
               QByteArray("sqrt"), qint64(42), 9.7L);

The same call can be executed using the Q_ARG() and Q_RETURN_ARG() macros, as in:

 QString retVal;
 QByteArray normalizedSignature = QMetaObject::normalizedSignature("compute(QString, int, double)");
 int methodIndex = obj->metaObject()->indexOfMethod(normalizedSignature);
 QMetaMethod method = obj->metaObject()->method(methodIndex);
 method.invoke(obj,
               Qt::DirectConnection,
               Q_RETURN_ARG(QString, retVal),
               Q_ARG(QString, "sqrt"),
               Q_ARG(int, 42),
               Q_ARG(double, 9.7));

Warning: this method will not test the validity of the arguments: object must be an instance of the class of the QMetaObject of which this QMetaMethod has been constructed with.

See also Q_ARG(), Q_RETURN_ARG(), qRegisterMetaType(), and QMetaObject::invokeMethod().

template <typename Args> bool QMetaMethod::invokeOnGadget(void *gadget, Args &&... arguments) const

template <typename Args> bool QMetaMethod::invokeOnGadget(void *gadget, QMetaMethodReturnArgument ret, Args &&... arguments) const

\since6.5

Invokes this method on a Q_GADGET. Returns true if the member could be invoked. Returns false if there is no such member or the parameters did not match.

The pointer gadget must point to an instance of the gadget class.

The invocation is always synchronous.

For the overload with a QMetaMethodReturnArgument parameter, the return value of the member function call is placed in ret. For the overload without it, the return value of the called function (if any) will be discarded. QMetaMethodReturnArgument is an internal type you should not use directly. Instead, use the qReturnArg() function.

Warning: this method will not test the validity of the arguments: gadget must be an instance of the class of the QMetaObject of which this QMetaMethod has been constructed with.

See also Q_ARG(), Q_RETURN_ARG(), qRegisterMetaType(), and QMetaObject::invokeMethod().

[constexpr] QMetaMethod::QMetaMethod()

\internal

Access QMetaMethod::access() const

Returns the access specification of this method (private, protected, or public).

Note: Signals are always public, but you should regard that as an implementation detail. It is almost always a bad idea to emit a signal from outside its class.

See also methodType().

int QMetaMethod::attributes() const

\internal

const QMetaObject *QMetaMethod::enclosingMetaObject() const

\internal

[static] template <typename PointerToMemberFunction> QMetaMethod QMetaMethod::fromSignal(PointerToMemberFunction signal)

\since5.0

Returns the meta-method that corresponds to the given signal, or an invalid QMetaMethod if signal is not a signal of the class.

Example:

 QMetaMethod destroyedSignal = QMetaMethod::fromSignal(&QObject::destroyed);

void QMetaMethod::getParameterTypes(int *types) const

\since5.0 \internal

Gets the parameter types of this method. The storage for types must be able to hold parameterCount() items.

See also parameterCount(), returnType(), and parameterType().

bool QMetaMethod::invoke(QObject *object, Qt::ConnectionType connectionType, QGenericReturnArgument returnValue, QGenericArgument val0 = QGenericArgument(nullptr), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument(), QGenericArgument val4 = QGenericArgument(), QGenericArgument val5 = QGenericArgument(), QGenericArgument val6 = QGenericArgument(), QGenericArgument val7 = QGenericArgument(), QGenericArgument val8 = QGenericArgument(), QGenericArgument val9 = QGenericArgument()) const

\obsolete[6.5] Please use the variadic overload of this function

Invokes this method on the object object. Returns true if the member could be invoked. Returns false if there is no such member or the parameters did not match.

See the variadic invokeMethod() function for more information. This function should behave the same way as that one, with the following limitations:

  • The number of parameters is limited to 10.
  • Parameter names may need to be an exact string match.
  • Meta types are not automatically registered.

With asynchronous method invocations, the parameters must be of types that are known to Qt's meta-object system, because Qt needs to copy the arguments to store them in an event behind the scenes. If you try to use a queued connection and get the error message

 QMetaMethod::invoke: Unable to handle unregistered datatype 'MyType'

call qRegisterMetaType() to register the data type before you call QMetaMethod::invoke().

Warning: In addition to the limitations of the variadic invoke() overload, the arguments must have the same type as the ones expected by the method, else, the behavior is undefined.

See also Q_ARG(), Q_RETURN_ARG(), qRegisterMetaType(), and QMetaObject::invokeMethod().

bool QMetaMethod::invoke(QObject *object, QGenericReturnArgument returnValue, QGenericArgument val0 = QGenericArgument(0), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument(), QGenericArgument val4 = QGenericArgument(), QGenericArgument val5 = QGenericArgument(), QGenericArgument val6 = QGenericArgument(), QGenericArgument val7 = QGenericArgument(), QGenericArgument val8 = QGenericArgument(), QGenericArgument val9 = QGenericArgument()) const

\obsolete[6.5] Please use the variadic overload of this function

This function overloads invoke().

This overload always invokes this method using the connection type Qt::AutoConnection.

bool QMetaMethod::invoke(QObject *object, Qt::ConnectionType connectionType, QGenericArgument val0 = QGenericArgument(0), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument(), QGenericArgument val4 = QGenericArgument(), QGenericArgument val5 = QGenericArgument(), QGenericArgument val6 = QGenericArgument(), QGenericArgument val7 = QGenericArgument(), QGenericArgument val8 = QGenericArgument(), QGenericArgument val9 = QGenericArgument()) const

\obsolete[6.5] Please use the variadic overload of this function

This function overloads invoke().

This overload can be used if the return value of the member is of no interest.

bool QMetaMethod::invoke(QObject *object, QGenericArgument val0 = QGenericArgument(0), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument(), QGenericArgument val4 = QGenericArgument(), QGenericArgument val5 = QGenericArgument(), QGenericArgument val6 = QGenericArgument(), QGenericArgument val7 = QGenericArgument(), QGenericArgument val8 = QGenericArgument(), QGenericArgument val9 = QGenericArgument()) const

\obsolete[6.5] Please use the variadic overload of this function

This function overloads invoke().

This overload invokes this method using the connection type Qt::AutoConnection and ignores return values.

bool QMetaMethod::invokeOnGadget(void *gadget, QGenericReturnArgument returnValue, QGenericArgument val0 = QGenericArgument(nullptr), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument(), QGenericArgument val4 = QGenericArgument(), QGenericArgument val5 = QGenericArgument(), QGenericArgument val6 = QGenericArgument(), QGenericArgument val7 = QGenericArgument(), QGenericArgument val8 = QGenericArgument(), QGenericArgument val9 = QGenericArgument()) const

\since5.5 \obsolete [6.5] Please use the variadic overload of this function

Invokes this method on a Q_GADGET. Returns true if the member could be invoked. Returns false if there is no such member or the parameters did not match.

See the variadic invokeMethod() function for more information. This function should behave the same way as that one, with the following limitations:

  • The number of parameters is limited to 10.
  • Parameter names may need to be an exact string match.
  • Meta types are not automatically registered.

Warning: In addition to the limitations of the variadic invoke() overload, the arguments must have the same type as the ones expected by the method, else, the behavior is undefined.

See also Q_ARG(), Q_RETURN_ARG(), qRegisterMetaType(), and QMetaObject::invokeMethod().

bool QMetaMethod::invokeOnGadget(void *gadget, QGenericArgument val0 = QGenericArgument(0), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument(), QGenericArgument val4 = QGenericArgument(), QGenericArgument val5 = QGenericArgument(), QGenericArgument val6 = QGenericArgument(), QGenericArgument val7 = QGenericArgument(), QGenericArgument val8 = QGenericArgument(), QGenericArgument val9 = QGenericArgument()) const

This is an overloaded function.

\obsolete[6.5] Please use the variadic overload of this function \since 5.5

This overload invokes this method for a gadget and ignores return values.

bool QMetaMethod::isConst() const

\since6.2

Returns whether the method is const qualified.

Note: This method might erroneously return false for a const method if it belongs to a library compiled against an older version of Qt.

bool QMetaMethod::isValid() const

\since5.0

Returns true if this method is valid (can be introspected and invoked), otherwise returns false.

int QMetaMethod::methodIndex() const

\since4.6

Returns this method's index.

QByteArray QMetaMethod::methodSignature() const

\since5.0

Returns the signature of this method (e.g., setValue(double)).

See also parameterTypes() and parameterNames().

MethodType QMetaMethod::methodType() const

Returns the type of this method (signal, slot, or method).

See also access().

QByteArray QMetaMethod::name() const

\since5.0

Returns the name of this method.

See also methodSignature() and parameterCount().

int QMetaMethod::parameterCount() const

\since5.0

Returns the number of parameters of this method.

See also parameterType() and parameterNames().

QMetaType QMetaMethod::parameterMetaType(int index) const

\since6.0

Returns the metatype of the parameter at the given index.

If the index is smaller than zero or larger than parameterCount(), an invalid QMetaType is returned.

See also parameterCount(), returnMetaType(), and QMetaType.

QList<QByteArray> QMetaMethod::parameterNames() const

Returns a list of parameter names.

See also parameterTypes() and methodSignature().

int QMetaMethod::parameterType(int index) const

\since5.0

Returns the type of the parameter at the given index.

The return value is one of the types that are registered with QMetaType, or QMetaType::UnknownType if the type is not registered.

See also parameterCount(), parameterMetaType(), returnType(), and QMetaType.

QByteArray QMetaMethod::parameterTypeName(int index) const

\since6.0 Returns the name of the type at position index If there is no parameter at index, returns an empty QByteArray

See also parameterNames().

QList<QByteArray> QMetaMethod::parameterTypes() const

Returns a list of parameter types.

See also parameterNames() and methodSignature().

int QMetaMethod::relativeMethodIndex() const

\since6.0

Returns this method's local index inside.

QMetaType QMetaMethod::returnMetaType() const

\since6.0

Returns the return type of this method.

See also parameterMetaType(), QMetaType, and typeName().

int QMetaMethod::returnType() const

\since5.0

Returns the return type of this method.

The return value is one of the types that are registered with QMetaType, or QMetaType::UnknownType if the type is not registered.

See also parameterType(), QMetaType, typeName(), and returnMetaType().

int QMetaMethod::revision() const

\since5.1 Returns the method revision if one was specified by Q_REVISION, otherwise returns 0.

const char *QMetaMethod::tag() const

Returns the tag associated with this method.

Tags are special macros recognized by moc that make it possible to add extra information about a method.

Tag information can be added in the following way in the function declaration:

     // In the class MainWindow declaration
     #ifndef Q_MOC_RUN
     // define the tag text as empty, so the compiler doesn't see it
     #  define MY_CUSTOM_TAG
     #endif
     ...
     private slots:
         MY_CUSTOM_TAG void testFunc();

and the information can be accessed by using:

     MainWindow win;
     win.show();

     int functionIndex = win.metaObject()->indexOfSlot("testFunc()");
     QMetaMethod mm = win.metaObject()->method(functionIndex);
     qDebug() << mm.tag(); // prints MY_CUSTOM_TAG

For the moment, moc will extract and record all tags, but it will not handle any of them specially. You can use the tags to annotate your methods differently, and treat them according to the specific needs of your application.

Note: Since Qt 5.0, moc expands preprocessor macros, so it is necessary to surround the definition with #ifndef Q_MOC_RUN, as shown in the example above. This was not required in Qt 4. The code as shown above works with Qt 4 too.

const char *QMetaMethod::typeName() const

Returns the return type name of this method.

See also returnType() and QMetaType::type().

Related Non-Members

[noexcept] bool operator!=(const QMetaMethod &m1, const QMetaMethod &m2)

\since5.0

This is an overloaded function.

Returns true if method m1 is not equal to method m2, otherwise returns false.

[noexcept] bool operator==(const QMetaMethod &m1, const QMetaMethod &m2)

\since5.0

This is an overloaded function.

Returns true if method m1 is equal to method m2, otherwise returns false.

Macro Documentation

Q_METAMETHOD_INVOKE_MAX_ARGS

Equals maximum number of arguments available for execution of the method via QMetaMethod::invoke()