unqualified.qdoc

Go to the documentation of this file.

// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qmllint-warnings-and-errors-unqualified.html
\ingroup qmllint-warnings-and-errors
 
\title Unqualified
\brief [unqualified] Accessing an outer scope without its id.
 
\qmllintwarningcategory unqualified
 
\section1 Unqualified access
 
\section2 What happened?
 
You accessed a parent element without its \l{QML Object Attributes#the-id-attribute}{id}.
 
\section2 Why is this bad?
 
This makes the code harder to read and impedes performance.
 
\section2 Example
 
\qml
import QtQuick
 
Item {
    property int helloWorld
    Item {
        property int unqualifiedAccess: helloWorld + 1 // not ok: Unqualified access here.
    }
}
\endqml
To fix this warning, refer to the parent object by \l{QML Object Attributes#the-id-attribute}{id}.
You will need to add an \l{QML Object Attributes#the-id-attribute}{id} first if the object
currently has none.
 
\qml
import QtQuick
 
Item {
    id: root
    property int helloWorld
    Item {
        property int unqualifiedAccess: root.helloWorld + 1 // ok: this access is qualified now!
    }
}
\endqml
 
\sa {QML Coding Conventions#unqualified-access}{QML Coding Conventions - Unqualified Access}
 
\section1 Type was not found
 
\section2 What happened?
 
You accessed a type or context property that can't be found.
 
\section2 Why is this bad?
 
The QML tooling will not work on your types.
 
\section2 Example
 
\qml
import QtQuick
 
Item {
    Component.onCompleted: { console.log(MyItem.someProperty); } // MyItem was not found
}
\endqml
To fix this warning,
\list
    \li Ensure that the QML Module of MyItem is built.
    \li Ensure that the QML Module of MyItem is imported.
    \li Ensure that MyItem is correctly spelled.
    \li Ensure that MyItem is registered via \l{Registering C++ Types with the QML Type System} as
        \list
            \li A singleton type.
            \li An attached type.
            \li A namespace type with enums.
        \endlist
    \li Ensure that MyItem is not a context property, see \l{Context properties} on how to replace
        context properties.
\endlist
 
\section1 Unknown attached/grouped property scope
 
\section2 What happened?
You used an \l{Attached Properties and Attached Signal Handlers}{attached property} type or
\l{QML Object Attributes#Grouped Properties}{grouped property} that can't be found.
This can be caused by a typo or by a missing QML module dependency.
 
\note If you are importing QML modules with external dependencies, verify that they are
actually installed and inside an \l{Import Statements#qml-import-path}{import path}.
 
\section2 Why is this bad?
Components with unknown attached property scopes or unknown grouped properties will not be created
at runtime: they will be null instead.
 
\section2 Example
 
Let's try to use the (inexistent) attached property of \c Item or the (inexistent) grouped property
\c grouped of \c Item:
\qml
import QtQuick
 
Item {
    Item.helloAttached: 44 // not ok: unknown attached property scope Item. [unqualified]
    grouped.helloGrouped: 44 // not ok: unknown grouped property scope grouped. [unqualified]
}
\endqml
 
Indeed, \l{Item} does neither have any attached type nor any grouped property called \c{item}.
To fix this warning, remove the attached type and the grouped property.
 
Refer to \l{Attached Properties and Attached Signal Handlers} on how to use attached
properties and to \l{QML Object Attributes#Grouped Properties}{Grouped Properties} on how to
use grouped properties.
 
\section1 No matching signal found for handler
 
\section2 What happened?
You used a \l{Signal and Handler Event System}{signal handler} on a signal that can't be found.
This can be caused by a typo in the signal handler or by a missing QML module dependency.
 
\note The name of a signal handler is \c on concatenated with the capitalized signal name.
\c onHelloWorld handles the signal \c helloWorld and \c on_helloWorld  handles \c _helloWorld,
for example.
 
\note If you are importing QML modules with external dependencies, verify that they are
actually installed and inside an \l{Import Statements#qml-import-path}{import path}.
 
\section2 Why is this bad?
Components with unknown signal handlers will not be created at runtime: they will be null
instead.
 
\section2 Example
 
Lets try to write a signal handler for the (inexistent) signal \c{mySignal}:
\qml
import QtQuick
 
Item {
    onMySignal: console.log("hello") // not ok: no matching signal found for handler "onMySignal" [unqualified]
}
\endqml
 
Indeed, this \l{Item} does not have any signal called \c{mySignal}. To fix this warning,
remove the signal handler or add the missing signal.
 
\section1 Implicitly defining signal handler in Connections is deprecated
 
\section2 What happened?
You used a signal handler on a \l[Qml]{Connections} type.
 
\section2 Why is this bad?
This is deprecated.
 
\section2 Example
 
\qml
import QtQuick
 
Window {
    id: root
    property int myInt
 
    Connections {
        target: root
        onMyIntChanged: console.log("new int", myInt)
    }
}
\endqml
 
To fix this warning, replace the signal handler binding with a function:
 
\qml
import QtQuick
 
Window {
    id: root
    property int myInt
 
    Connections {
        target: root
        function onMyIntChanged() { console.log("new int", myInt) }
    }
}
\endqml
*/