- Qt 6.12
- Qt Qml
- QML Lint Warning and Errors
- Context properties
- Qt 6.12.0 Reference Documentation

# Context properties

This warning category is spelled `[context-properties]` by qmllint.

## Potential context property access detected

### What happened?

A potential context property access was detected.

### Why is this bad?

By using context properties in your QML code, you create a dependency from your QML code to the specific context you have in mind when writing it. This limits reusability of your code since the context may be different in other places where it might be used. Furthermore, the dependency is not declared. You never import the context or otherwise state what you expect. Therefore, anyone trying to reuse your code will have difficulties finding out whether the place where it is reused has a context sufficient for your code.

QML tooling can't use the context property: the compiler can't compile this file to C++ and qmllint as well as QML Language Server can't provide useful warnings on that file.

### Example

     // main.cpp
     int main(int argc, char **argv)
     {
         QGuiApplication app(argc, argv);
         QQuickView view;
         view.rootContext()
             ->setContextProperty("myProperty", QDateTime::currentDateTime());
         view.loadFromModule("MyModule", "Main");
         view.show();
         app.exec();
     }

     // Main.qml
     import QtQuick

     Item {
         Component.onCompleted: console.log(myProperty)
     }

To fix this warning, you can:

- Make the property required.
- Use a singleton.
- Add an entry to `.contextProperties.ini`.

#### Using a required property

Use required properties for context properties that have different values in different components. To fix this warning with a required property, use one of the `setInitialProperties` methods instead of setContextProperty:

- QQuickView::setInitialProperties,
- QQmlComponent::setInitialProperties,
- QQmlApplicationEngine::setInitialProperties,
- QQmlIncubator::setInitialProperties, or
- QQuickWidget::setInitialProperties.

Also define the required property in `Main.qml`.

     // main.cpp
     int main(int argc, char **argv)
     {
         QGuiApplication app(argc, argv);
         QQuickView view;
         view.setInitialProperties( { {"myProperty", QDateTime::currentDateTime()}  } );
         view.loadFromModule("MyModule", "Main");
         view.show();
         app.exec();
     }

     // Main.qml
     import QtQuick

     Item {
         required property date myProperty
         Component.onCompleted: console.log(myProperty)
     }

See also Exposing State from C++ to QML.

#### Using a singleton

Use singletons for context properties that have the same value in all components. To fix this warning with a singleton, remove the setContextProperty call, define a singleton and replace the context property usage with the singleton property.

     // mysingleton.h
     class MySingleton : public QObject {
         Q_OBJECT
         QML_SINGLETON
         QML_ELEMENT
         Q_PROPERTY(QDateTime myProperty MEMBER m_myProperty NOTIFY myPropertyChanged FINAL)

         QDateTime m_myProperty = QDateTime::currentDateTime();
     signals:
         void myPropertyChanged();
     };
     // main.cpp
     int main(int argc, char **argv)
     {
         QGuiApplication app(argc, argv);
         QQuickView view;
         view.loadFromModule("MyModule", "Main");
         view.show();
         app.exec();
     }

     // Main.qml
     import QtQuick

     Item {
         Component.onCompleted: console.log(MySingleton.myProperty)
     }

See also Exposing State from C++ to QML.

#### Adding an entry to .contextProperties.ini

If you can't replace the context property, create a .contextProperties.ini file in your project source directory if there is none, and write the following content:

     [General]
     disableUnqualifiedAccess = "myProperty"
     warnOnUsage = "myProperty"
     disableHeuristic = false

To silence this warning if the `.contextProperties.ini` file already exists, append the context property name to the already existing lists:

     [General]
     disableUnqualifiedAccess = "someOtherProperty,myProperty"
     warnOnUsage = "someOtherProperty,myProperty"
     disableHeuristic = false

See also Context property settings for more information on the `.contextProperties.ini` format.