ElementPass Class

class QQmlSA::ElementPass

Base class for all static analysis passes on elements. More...

Header: #include <ElementPass>
CMake: find_package(Qt6 REQUIRED COMPONENTS QmlCompiler)
target_link_libraries(mytarget PRIVATE Qt6::QmlCompiler)
Inherits: QQmlSA::GenericPass
Status: Technical Preview

Public Functions

virtual void run(const QQmlSA::Element &element) = 0
virtual bool shouldRun(const QQmlSA::Element &element)

Detailed Description

ElementPass is the simpler of the two analysis passes. It will consider every element in a file. The shouldRun() method can be used to filter out irrelevant elements, and the run() method is doing the initial work.

Common tasks suitable for an ElementPass are

  • checking that properties of an Element are not combined in a nonsensical way
  • validating property values (e.g. that a property takes only certain enum values)
  • checking behavior dependent on an Element's parent (e.g. not using Item::width when the parent element is a Layout).

As shown in the snippet below, it is recommended to do necessary type resolution in the constructor of the ElementPass and cache it in local members, and to implement some filtering via shouldRun() to keep the static analysis performant.

using namespace QQmlSA;
class MyElementPass : public ElementPass
    Element myType;
        MyElementPass(QQmlSA::PassManager *manager)
        : myType(resolveType("MyModule", "MyType")) {}

        bool shouldRun(const Element &element) override
            return element.inherits(myType);
        void run(const Element &element) override
            // actual pass logic

ElementPasses have limited insight into how an element's properties are used. If you need that information, consider using a PropertyPass instead.

Note: ElementPass will only ever consider instantiable types. Therefore, it is unsuitable to analyze attached types and singletons. Those need to be handled via a PropertyPass.

Member Function Documentation

[pure virtual] void ElementPass::run(const QQmlSA::Element &element)

Executes if shouldRun() returns true. Performs the real computation of the pass on element. This method is meant to be overridden. Calling the base method is not necessary.

[virtual] bool ElementPass::shouldRun(const QQmlSA::Element &element)

Controls whether the run() function should be executed on the given element. Subclasses can override this method to improve performance of the analysis by filtering out elements which are not relevant.

The default implementation unconditionally returns true.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.