- Qt 6.12
- Qt Qml
- Qt Qml Tooling
- qmllint
- QML Lint Warning and Errors
- Signal handler parameters
- Qt 6.12.0 Reference Documentation

Restricted type ◦ Syntax

# Signal handler parameters

This warning category is spelled `[signal-handler-parameters]` by qmllint.

This warning category has multiple warnings, described in the sections below:

## Type of parameter in signal was not found

### What happened?

A signal handler tried to handle a signal with parameters of unknown QML types.

Usually, this happens when handling C++ defined signals in QML when the module with the C++ defined signal does not properly declare its QML dependency to another QML module. If the module with the C++ defined signal compiles, then this is a sign that a dependency was only declared on the C++ level and not on the QML module level.

Note: If you are importing QML modules with external dependencies, verify that they are actually installed, and that their modules end up in an import path.

The warning might also indicate that the parameter type of the C++ defined signal does not have a QML counterpart. The parameter type might be missing the QML_ELEMENT macro, for example. Refer to Defining QML Types from C++ or Overview - QML and C++ Integration in this case.

### Why is this bad?

In the first case, the module with the C++ signal has an undeclared dependency on the QML module level, which makes it hard to use the module, as users of the module need to guess the module's hidden dependencies.

In both cases, QML tooling is not able to find the QML counterpart of the C++ type: the compiler can't compile this signal handler to C++ and qmllint as well as QML Language Server can't analyze this handler.

### Example

Let our module have a C++ class with one `helloWorld` signal:

     #include <QQuickItem>
     #include <QtQml/qqmlregistration.h>
     #include <QObject>

     class MyCppObject : public QObject
     {
      Q_OBJECT
      QML_ELEMENT
     public:
      MyCppObject(QObject *parent = nullptr)
          : QObject(parent)
      {}

     signals:
      void helloWorld(QQuickItem *i);

     };

with following CMakeLists.txt:

     find_package(Qt6 6.5 REQUIRED COMPONENTS Quick QuickControls2)

     qt_standard_project_setup(REQUIRES 6.5)

     qt_add_executable(mymodule
      main.cpp
     )

     qt_add_qml_module(mymodule
         URI MyModule
         VERSION 1.0
         QML_FILES Main.qml
         SOURCES mycppobject.cpp mycppobject.h
     )

     # declare C++ dependency to Quick
     target_link_libraries(appuntitled27
      PRIVATE Qt6::Quick
     )

The C++ dependency `Quick` was declared, such that this class can compile and the QQuickItem include can be found. Also, mymodule does not have any QML dependency on Qt Quick.

Now, lets try to handle this `helloWorld` signal in QML:

     import MyModule // name of the module with MyCppObject

     MyCppObject {
         onHelloWorld: function (x) { console.log(x); } // not ok: Type QQuickItem was not found!
     }

The reason of the warning message is that in the QML code, `QQuickItem` and its QML counterpart `Item` are not known: the dependency `QtQuick` of MyModule was not declared in the CMakeLists.txt!

You can add it as following in the qt_add_qml_module() call:

     qt_add_qml_module(mymodule
         URI MyModule
         ...
         # declare QML dependencies to QtQuick:
         DEPENDENCIES QtQuick
         ...
     )

Now, the QML code should be fine again!

## Signal handler has more formal parameters than the signal it handles

### What happened?

A signal handler expects more parameters than what the signal will actually provide.

### Why is this bad?

The extra parameters will be undefined.

### Example

     import QtQuick

     Item {
         signal helloWorld(x: QtObject)  // signal expects only one parameter

         onHelloWorld: function (x,y,z) {} // not ok: signal handler handles three parameters
     }

To fix this warning, remove the extra parameters of the signal handler or add the missing parameters to the signal's declaration:

     import QtQuick

     Item {
         signal helloWorld(x: QtObject)  // signal expects only one parameter

         onHelloWorld: function (x) {} // ok: signal handler handles one parameter

         signal alternativeHelloWorld(x: QtObject, y: int, y: int)  // signal expects three parameters

         onAlternativeHelloWorld: function (x,y,z) {} // ok: signal handler handles three parameters
     }

## The signal has a parameter of the same name

### What happened?

The signal or signal handler might have swapped some of its arguments, or some arguments might be missing.

### Why is this bad?

This is very probably a typo and not intended by the user.

### Example

#### Missing Arguments

     import QtQuick

     Item {
         signal helloWorld(x: QtObject, y: int)

         onHelloWorld: function (y) {} // not ok: it seems that x was forgotten
     }

To fix this warning, add the missing parameters or rename the first parameter:

     import QtQuick

     Item {
         signal helloWorld(x: QtObject, y: int)

         onHelloWorld: function (x, y) {} // ok: parameters have the same order as in helloWorld

         signal alternativeHelloWorld(x: QtObject, y: int)

         onAlternativeHelloWorld: function (x) {} // ok: parameters have the same order as in helloWorld, even if y is missing
     }

#### Swapped arguments

     import QtQuick

     Item {
         signal helloWorld(x: QtObject, y: int)

         onHelloWorld: function (y, x) {} // not ok: helloWorld expects first 'x' then 'y'
     }

To fix this warning, reorder the parameters in the correct order:

     import QtQuick

     Item {
         signal helloWorld(x: QtObject, y: int)

         onHelloWorld: function (x, y) {} // ok: parameters have the same order as in helloWorld
     }

See also qt_add_qml_module#declaring-module-dependencies.

Restricted type ◦ Syntax