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 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
*/