path: root/doc/src/qtvstools.qdoc

// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0

/*!
    \page index.html

    \title Qt VS Tools

    \raw HTML
    <style>
    .main-navigation table { table-layout: fixed; }
    .main-navigation table tr:first-child { text-align: center; background: none; }
    </style>
    \endraw

    \div {class="main-navigation"}
    \table borderless 100%
        \row
            \li \inlineimage {installation.png} {Installation icon}
            \li \inlineimage {getting-started.png} {Getting started icon}
            \li \inlineimage {tutorials.png} {Tutorials icon}
        \row
            \li \b {INSTALLATION}

                Install Qt VS Tools from Microsoft Visual Studio.

                \l {Install Qt VS Tools}
            \li \b {GETTING STARTED}

                Get started with developing Qt applications with Visual Studio.

                \l{Getting started}
            \li \b {TUTORIALS}

                Learn how to develop Qt and Qt Quick applications with
                Visual Studio.

                \l{Tutorials}
    \endtable
    \enddiv

    \section1 About

    Qt VS Tools integrate the Qt development tools into Microsoft Visual Studio
    2019, and later. Use the standard Windows development environment
    without having to worry about Qt-related build steps or tools.

    \b {HOW TO}

    \raw HTML
    <style>
    .link-list table { table-layout: fixed; }
    .link-list table, .link-list table tr:first-child { background: none; border: none; }
    </style>
    \endraw

    \div {class="link-list"}
    \table 100%
        \row
            \li \inlineimage {demo-32x32.png} {Demo icon}
            \li \inlineimage {build-32x32.png} {Build icon}
            \li \inlineimage {settings-32x32.png} {Settings icon}
        \row
            \li Work with code
                \list
                    \li \l {Edit}
                    \li \l {Debug}
                    \li \l {Test}
                \endlist
            \li Build and run applications
                \list
                    \li \l {Set up Qt VS Tools}
                    \li \l {Create}
                    \li \l {Build}
                \endlist
            \li Use tools
                \list
                    \li \l {Localize}
                    \li \l {Get help}
                \endlist
    \endtable
    \enddiv
*/

/*!
    \page qtvstools-toc.html
    \title All Topics

    \list
        \li \l{Install Qt VS Tools}
        \li \l{Getting Started}
        \li \l{Tutorials}
            \list
                \li \l {Tutorial: Qt Widgets application}
                \li \l {Tutorial: Qt Quick application}
                \li \l {Tutorial: Qt Quick debugging}
                \li \l {Tutorial: Qt Test application}
            \endlist
        \li \l{How to}
            \list
                \li \l {Add Qt versions}
                \li \l {Build solutions that have Qt/MSBuild format 2}
                \li \l {Configure Qt tests using a .runsettings file}
                \li \l {Convert solutions to latest Qt/MSBuild format}
                \li \l {Create Qt translation files}
                \li \l {Create UI form files}
                \li \l {Cross-compile}
                \li \l {Debug applications}
                \li \l {Debug on Linux}
                \li \l {Enable QML debugging}
                \li \l {Get help}
                \li \l {Hide output}
                \li \l {Load Qt projects}
                \li \l {Manage resources}
                \li \l {Profile Qt Quick applications}
                \li \l {Select Qt versions for a project}
                \li \l {Set tool theme}
                \li \l {Start \QD}
                \li \l {Start \QL}
                \li \l {Start Qt Resource Editor}
                \li \l {Turn on QML Language Server}
                \li \l {Update IntelliSense info}
                \li \l {Update Qt translation files}
                \li \l {Visualize C++ types}
            \endlist
        \li \l{Explanation}
            \list
                \li \l {Building}
                \li \l {Configuring builds}
                \li \l {Debugging Qt Quick applications}
                \li \l {Features}
            \endlist
        \li \l{Reference}
            \list
                \li \l {Files}
                \li \l {Projects}
                \li \l {Test Adapter settings}
            \endlist
    \endlist
*/

/*!
    \page qtvstools-getting-started.html

    \title Getting started

    To develop Qt and Qt Quick applications in Microsoft Visual Studio:

    \list 1
        \li \l {Install Qt VS Tools}.
        \li \l {Add Qt versions}.
        \li Follow the \l {Tutorials} to learn how to develop and debug
            applications and create Qt unit tests.
    \endlist
*/

/*!
    \page qtvstools-tutorials.html

    \title Tutorials

    The following tutorials describe how to create and debug Qt applications.

    \list
        \li \l {Tutorial: Qt Widgets application}
        \li \l {Tutorial: Qt Quick application}
        \li \l {Tutorial: Qt Quick debugging}
        \li \l {Tutorial: Qt Test application}
    \endlist

    To learn the basics of Qt VS Tools, take the
    \l{https://www.qt.io/academy/course-catalog#getting-started-with-qt-tools-for-visual-studio-}
    {Getting Started with Qt Tools for Visual Studio} course in Qt Academy.
*/

/*!
    \page qtvstools-how-to.html

    \title How to

    The following topics describe how to set up Qt VS Tools and to use them to
    create, build, debug, and localize Qt applications.

    \section1 Set up Qt VS Tools

    Install Qt VS Tools in Microsoft Visual Studio, and then tell it where to
    find the Qt versions that you want to develop with.

    \list
        \li \l {Install Qt VS Tools}
        \li \l {Add Qt versions}
    \endlist

    \section1 Create

    Use wizards to create several types of Qt and Qt Quick projects and files
    that you add to the projects, such as classes, form files, or custom
    QML types.

    \list
        \li \l {Select Qt versions for a project}
        \li \l {Create UI form files}
        \li \l {Start \QD}
        \li \l {Manage resources}
        \li \l {Start Qt Resource Editor}
        \li \l {Set tool theme}
        \li \l {Get help}
    \endlist

    \section1 Edit

    With IntelliSense information and the QML Language Server support, you get
    code editing features for C++ and QML types.

    \list
        \li \l {Turn on QML Language Server}
        \li \l {Update IntelliSense info}
    \endlist

    \section1 Build

    Qt VS Tools integrate with MSBuild, and therefore, you build Qt applications
    as Visual Studio projects. Special build rules called \e Qt/MSBuild let you
    run Qt build tools and set build options for them.

    \list
        \li \l {Load Qt projects}
        \li \l {Build solutions that have Qt/MSBuild format 2}
        \li \l {Convert solutions to latest Qt/MSBuild format}
        \li \l {Cross-compile}
        \li \l {Hide output}
        \li \l {Update IntelliSense info}
    \endlist

    \section1 Debug

    With a debugger, you can see what happens inside an application while it runs
    or when it crashes. You can debug Qt Widgets and Qt Quick applications.

    \list
        \li \l {Debug applications}
        \li \l {Visualize C++ types}
        \li \l {Enable QML debugging}
        \li \l {Debug on Linux}
    \endlist

    \section1 Test

    Use QtTest, the Qt Testing Framework, to unit test Qt-based applications and
    libraries. Write tests, use Test Explorer, create test suites, and test
    graphical user interfaces.

    \list
        \li \l {Configure Qt tests using a .runsettings file}
        \li \l {Profile Qt Quick applications}
    \endlist

    \section1 Localize

    Use Qt translation tools to adapt applications for a specific region or
    language by adding locale-specific components such as date, time, and number
    formats and translating text.

    \list
        \li \l {Create Qt translation files}
        \li \l {Start \QL}
        \li \l {Update Qt translation files}
        \li \l {Set tool theme}
    \endlist
*/

/*!
    \page qtvstools-explanation.html

    \title Explanation

    The following topics explain building and debugging Qt applications.

    \list
        \li \l {Building}
        \li \l {Configuring builds}
        \li \l {Debugging Qt Quick applications}
        \li \l {Features}
    \endlist
*/

/*!
    \page qtvstools-reference.html

    \title Reference

    The following topics list the projects and files that you can create.

    \list
        \li \l {Files}
        \li \l {Projects}
        \li \l {Test Adapter settings}
    \endlist
*/

/*!
    \page qtvstools-explanation-features.html
    \ingroup qtvstools-explanation

    \title Features

    The main features of Qt VS Tools are:

    \list
        \li Wizards for creating new Qt and Qt Quick projects and files, as
            well as unit tests.
        \li Automated build setup for \l {Using the Meta-Object Compiler
            (moc)}{Meta-Object Compiler (moc)}, \l {User Interface Compiler
            (uic)}, and \l {Resource Compiler (rcc)}.
        \li Loading existing Qt projects (\c .pro).
        \li Using CMake for cross-platform development.
        \li Integrated Qt resource management.
        \li Creating a Qt translation source (TS) file and starting \QL
            to translate the strings.
        \li Starting \QD to design widget-based UIs for applications.
        \li Integrated Qt documentation.
        \li Debugging extensions for Qt data types.
    \endlist

    \sa {Projects}, {Files}, {Building}, {Load Qt projects}, {Cross-compile},
    {Manage resources}, {Create Qt translation files}, {Create UI form files},
    {Start \QD}, {Get help}, {Debug applications}
*/

/*!
    \page qtvstools-how-to-install.html
    \ingroup qtvstools-how-to

    \title Install Qt VS Tools

    To install or update Qt VS Tools in Microsoft Visual Studio:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Manage Extensions} >
            \uicontrol Online.
        \li Search for \uicontrol {Qt Visual Studio Tools}.
            \image {qtvstools-manage-extensions.webp} {Manage Extensions dialog}
        \li Select \uicontrol Download.
        \li Restart Microsoft Visual Studio to have the changes take effect.
    \endlist

    \section1 Turn on installation notifications

    To turn on notifications about new Qt VS Tools versions being installed:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {Notifications}.
            \image {qtvstools-options-qt-general-notifications.webp} {Notifications in Qt General Options}
        \li In \uicontrol {New version installed}, select \uicontrol Enable.
    \endlist

    \section1 Search for updates to development releases

    Qt VS Tools can search for updates to development releases when you
    start it.

    To set options for the search:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {Notifications}, and then select \uicontrol {Enable} to
            show notifications that let you turn searching for new releases on
            or off.
        \li In \uicontrol {Development releases}, select options:
            \image {qtvstools-options-qt-general-dev-releases.webp} {Development releases in Qt General Options}
            \list
                \li In \uicontrol {Search automatically}, turn searching for new
                    releases on or off.
                \li In \uicontrol {Search timeout}, set the time in seconds to
                    search for new releases.
            \endlist
    \endlist
*/

/*!
    \page qtvstools-tutorial-qt-widgets-application.html
    \ingroup qtvstools-tutorials

    \title Tutorial: Qt Widgets application

    This tutorial illustrates how to use Qt VS Tools to create a \l {Qt Widgets}
    application. You will create a project using a project wizard and design a
    widget-based UI using \QD.

    \section1 Before you start

    Before you start, you have to:

    \list
        \li \l {Install Qt VS Tools}
        \li \l {Add Qt versions}
    \endlist

    \section1 Create a Qt Widgets application project

    To create a Qt Widgets application project in Visual Studio:

    \list 1
        \li Go to \uicontrol File > \uicontrol New > \uicontrol Project.
        \li Search for \uicontrol {Qt Widgets Application}.
        \li Select the project wizard, and then select \uicontrol Next.
        \li In \uicontrol {Project name}, enter \e AddressBook,
            and then select \uicontrol OK.
        \li To acknowledge the \uicontrol Welcome dialog, select
            \uicontrol Next.
        \li Set up the \uicontrol Debug build configuration and select the
            modules to include in the project:
            \image {qtvstools-widgets-app-modules.webp} {Selecting Qt modules in Qt Widgets Application Wizard}
            The modules that are typically needed in widget application projects
            are selected by default.
        \li Select \uicontrol {Enable PCH Support} to use a precompiled header
            file.
        \li Select \uicontrol Next to continue to the class creation page:
            \image {qtvstools-widgets-app-class.webp} {Creating a class in Qt Widgets Application Wizard}
        \li In \uicontrol {Base class}, enter \uicontrol QWidget as
            the base class type.
        \li Select \uicontrol {Lower case filenames} to
            only use lower case characters in the names of the generated files.
        \li Select \uicontrol {Add default application icon} to
            use a default application icon for the application.
        \li Select \uicontrol Finish to create the project.
    \endlist

    You now have a small working Qt application. Go to \uicontrol Build >
    \uicontrol {Build Solution} to build it, and then go to \uicontrol Debug >
    \uicontrol {Start Without Debugging} (or press \key {Ctrl+F5}) to run it.
    For now, the result is an empty window.

    \section1 Design the main window

    Use \QD to design the application's main window, which has
    some widgets placed in layouts:

    \image {qtvstools-addressbook-mainwindow.webp} {AddressBook's main dialog}

    By default, \QD opens in Visual Studio. To open it as a stand-alone
    application, select \uicontrol Detach.

    For more information about using \QD, see the \l{\QD Manual}.

    \section2 Add widgets

    To add widgets to the UI and to set properties for them:

    \list 1
        \li In Visual Studio's \uicontrol {Solution Explorer}, double-click the
            \c addressbook.ui file to open it in \QD.
        \li In \QD's \uicontrol {Widget Box}, select \uicontrol {List Widget} and
            Drag it to the form to add a \l QListWidget.
        \li In the \uicontrol {Property Editor}, set the \c ObjectName property
            to \e addressList.
        \li Drag two \uicontrol {Push Button} widgets to the top-right
            corner of the form to add \l QPushButton objects for the
            \uicontrol Add and \uicontrol Delete buttons.
        \li Set the button names to \e addButton and \e deleteButton and
            \uicontrol text property values to \e Add and \e Delete.
        \li Drag two \uicontrol {Label} widgets to the form to add
            \l QLabel objects for displaying the selected item in the list.
        \li Rename the first label to \e nameLabel and change its
            \uicontrol text property to \e {<No item selected>}.
        \li Rename the second label to \e emailLabel and leave its
            \uicontrol text property empty.
    \endlist

    Position the widgets as they appear in the screenshot above.
    To properly position the widgets and to automatically resize
    them when the form is resized, you need to add layouts to the
    form.

    \section2 Add widgets to layouts

    You will need a vertical layout for the buttons as well as a spacer to push
    the buttons to the top of the layout. In addition, you will need a second
    layout to manage the positioning of the other widgets as well as the button
    layout.

    To add widgets to layouts:

    \list 1
        \li Drag a \uicontrol {Vertical Spacer} item to the form to add a
            spacer.
        \li Select the buttons and the spacer, and then select \uicontrol Form >
            \uicontrol {Lay Out Vertically} to add a vertical layout
            (\l QVBoxLayout).
        \li Select the list widgets, the two labels, and the button layout,
            and then select \uicontrol Form > \uicontrol {Lay Out in a Grid} to
            add a grid layout (\l QGridLayout).

            \note Make sure that the labels are almost as wide as the form.
            Otherwise, the grid layout will make them only as wide as the
            address list.
        \li Select \uicontrol Form > \uicontrol Preview to preview your form
            without compiling it.
        \li Go to \uicontrol File > \uicontrol Save to save the form.
    \endlist

    Build and run the application to check the main window.

    \section1 Add a dialog

    Now that the main window is ready, move on to add functionality to
    the application. To have the application open a dialog when the user clicks
    the \uicontrol Add button, you must create an \uicontrol {Add Address}
    dialog and invoke the dialog from a slot that you connect to the
    \uicontrol Add button.

    Use a Qt file wizard in Visual Studio to create a UI form that
    has the \uicontrol OK and \uicontrol Cancel buttons connected to the
    QDialog::accept() and QDialog::reject() slots, respectively. Use \QD
    to add other widgets to the form.

    \section2 Create the dialog

    To add a dialog to a project:

    \list 1
        \li In Visual Studio, go to \uicontrol Project >
            \uicontrol {Add New Item} > \uicontrol Installed >
            \uicontrol {Visual C++} > \uicontrol Qt >
            \uicontrol {Qt Widgets Class}.
        \li To acknowledge the \uicontrol Welcome dialog, select
            \uicontrol Next.
        \li In \uicontrol Name, enter \e AddDialog.
            \image {qtvstools-qt-widget-class-wizard.webp} {Creating a class in Qt Widgets Class Wizard}
        \li In \uicontrol {Base class}, enter \uicontrol QDialog as
            the base class type.
        \li Select the \uicontrol {Multiple inheritance} radio button.
        \li Select \uicontrol {Lower case filenames} to
            only use lower case characters in the names of the generated files.
        \li Select \uicontrol Finish to create source, header, and UI files for
            the dialog.
    \endlist

    \section2 Design the dialog

    \image {qtvstools-addressbook-adddialog.png} {Add Address Dialog}

    To design the dialog:

    \list 1
        \li In Visual Studio's \uicontrol {Solution Explorer}, double-click the
            \c adddialog.ui file to open it in \QD.
        \li In \QD, set \e {Add Address} as the \uicontrol windowTitle.
        \li Add a \uicontrol Label to the form and set its \uicontrol objectName
            property to \e nameText and \uicontrol text property to \e {Name:}.
        \li Add another \uicontrol Label and set its \uicontrol objectName
            property to \e emailText and \uicontrol text property to
            \e {Email:}.
        \li Add a \uicontrol {Line Edit} (\l QLineEdit) and set its
            \uicontrol objectName property to \e nameEdit. Leave the
            \uicontrol text property empty.
        \li Add another \uicontrol {Line Edit} and set its \uicontrol objectName
            property to \e emailEdit. Leave the \uicontrol text property empty.
        \li Select the labels and line edits, and then go to \uicontrol Form >
            \uicontrol {Lay Out in a Grid} to add a grid layout.
        \li Add a \uicontrol {Push Button} and set its \uicontrol objectName
            property to \e okButton and \uicontrol text property to \e OK.
        \li Add a horizontal spacer to the left of the button.
        \li Add a horizontal layout for the spacer and the button.
        \li Add a vertical spacer between the labels and the button.
        \li Add a vertical layout for the labels and the spacer.
        \li Add a grid layout for both layouts.
        \li Go to \uicontrol Form > \uicontrol Preview to preview your form
            without compiling it.
        \li Go to \uicontrol File > \uicontrol Save to save the form.
    \endlist

    \section1 Connect to the dialog's OK button

    To have the \uicontrol OK button invoke the QDialog::accept() slot, click
    the \uicontrol {Edit Signals/Slots} toolbar button to enter
    \l {\QD's Signals and Slots Editing Mode}.

    Click the \uicontrol OK button, drag the mouse cursor to an empty area of
    the form, and release the mouse button. In the
    \uicontrol {Configure Connection} dialog, connect the button's
    QPushButton::clicked() signal to the form's QDialog::accept() slot.

    \section1 Open dialogs from the main window

    To invoke the dialog when the user selects \uicontrol Add in the main
    window, you must add a slot to the \c AddressBook class and invoke
    \c AddDialog from this slot.

    Forms that you create using \QD call QMetaObject::connectSlotsByName() to
    establish connections between signals that the form's child widgets
    emit and slots that follow the naming convention \c {on_<sender>_<signal>()}.
    For the application to react appropriately when the user clicks the
    \uicontrol Add button, you must implement a slot called
    \c{on_addButton_clicked()}.

    To implement the slot, open the \c addressbook.h file in Visual Studio and
    add a declaration for the slot:

    \badcode
    private slots:
        void on_addButton_clicked();
    \endcode

    Then open \c addressbook.cpp, and add the slot definition:

    \badcode
    void AddressBook::on_addButton_clicked()
    {
        AddDialog dialog(this);
        dialog.exec();
    }
    \endcode

    To connect to some other signal, you must add the signal to the
    \c AddressBook class. This requires editing both the header file,
    \c addressbook.h, and the implementation file, \c addressbook.cpp.

    Include \c adddialog.h to \c addressbook.cpp:

    \quotefromfile AddressBook/addressbook.cpp
    \skipto adddialog
    \printuntil adddialog.h

    To test your changes, build and run the application. Select the
    \uicontrol Add button to open the \uicontrol {Add Address} dialog, and then
    select \uicontrol OK to close it.

    \section1 Add items to the list widget

    When the user selects \uicontrol OK, an item should be added to the
    QListWidget. To implement this function, change the code in the
    \c {on_addButton_clicked()} slot, as follows:

    \skipto AddDialog dialog(this);
    \printuntil }
    \printuntil }

    The dialog is executed. If the user accepts it by selecting \uicontrol OK,
    the \uicontrol Name and \uicontrol Email fields are extracted and a
    QListWidgetItem that has the specified information is created.

    \section1 Display the selected item

    To update the \c nameLabel and the \c emailLabel at the bottom of the form
    when the user selects an item in the list widget, add another slot to the
    \c AddressBook class.

    In the \c addressbook.h file, add the following code in the
    \c{private slots} section of the class:

    \quotefromfile AddressBook/addressbook.h
    \skipto on_addressList_currentItemChanged()
    \printuntil ;

    Then, add the block of code below to \c addressbook.cpp:

    \quotefromfile AddressBook/addressbook.cpp
    \skipto on_addressList_currentItemChanged()
    \printuntil /^\}/

    The naming convention enables this slot to be automatically connected
    to the QListWidget::currentItemChanged() signal of \c{addressList} and
    be invoked whenever the selected item in the list changes.

    \section1 Add functionality for the Delete button

    To implement a slot for the \uicontrol Delete button, open the
    \c addressbook.h file in Visual Studio and add a declaration for the
    \c on_deleteButton_clicked() slot. Then open \c addressbook.cpp and add the
    slot definition for \c on_deleteButton_clicked().

    Type the following code in the slot's body:

    \skipto on_deleteButton_clicked()
    \printuntil /^\}/

    Your application is now complete.

    \sa {Tutorial: Qt Quick application}
*/

/*!
    \page qtvstools-tutorial-qt-quick-application.html
    \ingroup qtvstools-tutorials

    \title Tutorial: Qt Quick application

    This tutorial illustrates how to use Qt VS Tools to create a \l {Qt Quick}
    application. You will create a project using a project wizard and design a
    Qt Quick UI. In addition, you will learn how to add QML module definitions
    and QML files to your projects.

    \section1 Before you start

    Before you start, you have to:

    \list
        \li \l {Install Qt VS Tools}
        \li \l {Add Qt versions}
    \endlist

    \section1 Create a Qt Quick application project

    To create a Qt Quick application project in Visual Studio:

    \list 1
        \li Go to \uicontrol File > \uicontrol New > \uicontrol Project.
        \li Search for \uicontrol {Qt Quick Application}.
        \li Select the project wizard, and then select \uicontrol Next.
        \li In \uicontrol {Project name}, enter \e QuickAddressBook,
            and then select \uicontrol Create.
        \li To acknowledge the \uicontrol Welcome dialog, select
            \uicontrol Next.
        \li To set up debug and release build configurations, click in
            \uicontrol {Qt Modules}, and select the \uicontrol {Qt Quick} and
            \uicontrol {Qt Quick Controls} modules to include in the project:
            \image {qtvstools-qtquick-app-modules.webp} {Selecting Qt modules in Qt Quick Application Wizard}
        \li Select \uicontrol Finish to create the project.
    \endlist

    You now have a small working Qt Quick application. Go to \uicontrol Build >
    \uicontrol {Build Solution} to build it, and then go to \uicontrol Debug >
    \uicontrol {Start Without Debugging} (or press \key {Ctrl+F5}) to run it.
    For now, the result is an empty window.

    \section1 Design the main window

    The wizard created a main QML file for you, which declares a root object of
    the type \l Window. Change the file to design the application's main
    window.

    Specify values for the Window \c color and \c title properties to set the
    background color and title of the application main window:

    \quotefromfile QuickAddressBook/main.qml
    \skipto Window {
    \printuntil title

    \section2 Add a button

    To create the \uicontrol Add button, declare an object of the \l Button type
    from the \l {Qt Quick Controls} module. Set the value of the button \c text
    property to \e Add and the value of the \c font.pointSize property to \e 24:

    \skipto Button {
    \printuntil font.pointSize

    When you run the application, you should now see this:

    \image {qtvstools-quick-addressbook-mainwindow.png} {QuickAddressBook's main window}

    \section2 Connect the button to an action

    QML has a signal and handler mechanism, where the signal is the event and
    the signal is responded to through a signal handler. When a signal is
    emitted, the corresponding signal handler is invoked. Placing logic such
    as a script or other operations in the handler allows the component to
    respond to the event.

    To receive a notification when a particular signal is emitted for a
    particular object, the object definition should declare a signal handler
    named \c on<Signal>, where \c <Signal> is the name of the signal, with
    the first letter capitalized. The signal handler should contain the
    JavaScript code to be executed when the signal handler is invoked.

    The \l Button type has a \c clicked signal, which is emitted when the users
    click the button. To invoke a popup for adding an address book entry when
    the users select the \uicontrol Add button in the main window, you must
    connect the \c onClicked signal handler of the button to the \c open()
    method of the popup. You will add the popup as a separate QML type later.

    \printuntil }

    \section2 Add a list model

    \image {qtvstools-quick-addressbook-entries.png} {QuickAddressBook entries}

    Within the Window, declare an object of the \l ListModel type with the
    \c id \e addressList for storing the contact data. A list model defines
    a free-form list data source:

    \quotefromfile QuickAddressBook/main.qml
    \skipto ListModel {
    \printuntil }

    \section2 Declare a popup

    Declare an object of the custom \c NewAddressPopup type that
    defines the popup where the users will add address book entries.
    Use the \c onAddressAdded signal handler to append address
    book entries to the \e addressList model:

    \printuntil }
    \printuntil }

    You will create the \c NewAddressPopup type later.

    \section2 Position the button

    Declare an object of \l ColumnLayout type to position the \l Button object
    and an instance of the \l Repeater type:

    \printuntil }

    Anchor the column layout to the left and right edges of its parent to make
    the application scalable on different screen sizes. Set the \c spacing
    between the rows in the column to \e 0.

    \section2 Add a repeater

    The \l Repeater type creates many similar items. It
    has a model and a delegate: for each entry in the model, the delegate is
    instantiated in a context seeded with data from the model. Enclose the
    repeater in an instance of a positioner type such as a \l ColumnLayout to
    visually position the delegate items that the repeater creates.

    Specify \e addressList as the \c model to use for the repeater:

    \printuntil anchors.right

    Declare an object of the custom \c AddressBookItem type that the
    repeater will use to instantiate address book entries:

    \printuntil id:

    You will create the \c AddressBookItem type later.

    \section2 Connect the Remove button to an action

    Use the \c onRemoved signal handler to remove an address book entry from the
    list when the user clicks its \uicontrol Remove button.

    \printuntil }

    \section1 Add a popup

    Now that the main window is ready, move on to create the popup
    where users can add address book entries. The \c AddressBookItem type
    specifies that the repeater instantiates the data that the users enter
    in the main window.

    \image {qtvstools-quick-addressbook-popup.png} {QuickAddressBook's popup}

    Use a Qt file wizard in Visual Studio to create a custom type
    that defines the popup.

    To create custom QML types, you must first add a QML Module Definition
    (\c qmldir) file to the project.

    \section2 Add a QML module definition

    A QML module definition (\c qmldir) maps each custom QML type to its
    corresponding source file.

    To add a QML module definition, go to \uicontrol Project >
    \uicontrol {Add New Item} > \uicontrol {Installed} > \uicontrol {Visual C++}
    > \uicontrol Qt > \uicontrol {Qt QML Module Definition} > \uicontrol Add.

    In the \c qmldir file, add QML type definitions for \e AddressBookItem and
    \e NewAddressPopup:

    \quotefile QuickAddressBook/qmldir

    Next, you will create the QML types.

    \section2 Create a popup

    To add a custom QML type to the project:

    \list 1
        \li Go to \uicontrol Project > \uicontrol {Add New Item} >
            \uicontrol {Installed} > \uicontrol {Visual C++} > \uicontrol {Qt} >
            \uicontrol {Qt QML File}.
        \li Select \uicontrol Add.
        \li In \uicontrol Name, enter \e NewAddressPopup.
        \li Select \uicontrol Finish to create a custom QML type.
    \endlist

    \section2 Design the popup

    In \e NewAddressPopup.qml, declare a root object of the type \l Popup to
    create a popup that opens in a \l Window. A popup does not
    provide a layout of its own, so you will use a \l ColumnLayout and a
    \l RowLayout to position the \uicontrol Name and \uicontrol {E-Mail Address}
    fields.

    \quotefromfile QuickAddressBook/QuickAddressBookTypes/NewAddressPopup.qml
    \skipto Popup {
    \printuntil id:

    Set the \c modal property to \c true to specify that the popup is modal. Set
    the \c focus property to \c true to specify that the popup requests focus:

    \printuntil focus:

    Specify values for the \c width, \c x, and \c y properties to set the
    position and size of the popup on top of the main window:

    \printuntil y:

    \section2 Reset popup controls

    When the popup opens, the \uicontrol Name and \uicontrol {E-Mail Address}
    fields should display placeholder text and any values entered previously
    should be cleared. You use the \c onOpened signal handler to reset the
    values of the fields and give focus to the \uicontrol Name field:

    \printuntil }

    \section2 Position fields

    Use an instance of the \l ColumnLayout type to position the \l TextField
    objects that specify the \uicontrol Name and \uicontrol {E-Mail Address}
    fields of the popup:

    \skipto ColumnLayout {
    \printuntil id: addrField
    \printuntil }
    \printuntil }

    \section2 Position buttons

    Use an instance of a \l RowLayout type to position two \l Button objects
    that specify the \uicontrol Add and \uicontrol Cancel buttons:

    \printuntil Layout.fillWidth: true

    \section2 Connect buttons to actions

    When the users click the \uicontrol Add button, the values they entered to
    the \uicontrol Name and \uicontrol {E-Mail Address} fields are added to the
    address list in the main window and the popup is closed.

    To enable this, add the \c {addressAdded(string newName, string newAddr)}
    signal:

    \quotefromfile QuickAddressBook/QuickAddressBookTypes/NewAddressPopup.qml
    \skipto addressAdded(
    \printuntil )

    Connect the \c onClicked signal handler of the \uicontrol Add button to
    the \c addressAdded() signal and to the popup's \c close() method:

    \skipto Button {
    \printuntil }
    \printuntil }

    For the \uicontrol Cancel button, connect the \c onClicked signal handler to
    the to the popup's \c close() method to close the popup without saving the
    data:

    \printuntil }

    \section1 Define an address book entry

    The custom \c AddressBookItem type specifies how to present address book
    entries in the main window.

    Go to \uicontrol Project > \uicontrol {Add New Item} > \uicontrol Installed
    > \uicontrol {Visual C++} > \uicontrol Qt > \uicontrol {Qt QML File} and
    select \uicontrol Add to create a new QML file called \e AddressBookItem.qml.

    \section2 Design the entry

    First, you will declare a root object of type \l Rectangle. It is one of the
    basic building blocks you can use to create an application in QML. Give it
    an \c id to be able to refer to it later.

    \quotefromfile QuickAddressBook/QuickAddressBookTypes/AddressBookItem.qml
    \skipto Rectangle {
    \printuntil id:

    To use alternating colors for rows, set the value of the \c color property:

    \printuntil color:

    Anchor the rectangle to the left and right edges of its parent to make
    the application scalable on different screen sizes. Bind the rectangle
    \c height property to the height of the text items it will contain:

    \printuntil height:

    \section2 Connect the Remove button to an action

    Add the \c removed() signal that you will connect to the \onClicked
    signal handler of the remove button. This removes an address book entry
    from the main window when users click the button:

    \printuntil signal removed()

    \section2 Position the button and text

    Use instances of the \l RoundButton and \l Text types within an instance of
    a \l RowLayout type to define an address book entry:

    \printuntil }

    \section2 Format the text

    Set the value of the \c text property to combine the values of the \c name
    and \c addr fields from the popup and to use bold and italic formatting for
    the values:

    \printuntil }

    Your application is now complete.

    \sa {Tutorial: Qt Quick debugging}, {Tutorial: Qt Widgets application}
*/

/*!
    \page qtvstools-tutorial-debug-qt-quick.html
    \ingroup qtvstools-tutorials

    \title Tutorial: Qt Quick debugging

    This tutorial illustrates how to use Qt VS Tools to debug the
    \l {Tutorial: Qt Quick application}{Qt Quick tutorial application},
    \e QuickAddressBook. After you enable QML debugging for the project,
    set breakpoints in QML files and step through the execution
    of code. While in break mode, watch variables and change their
    values, as well as evaluate arbitrary expressions.

    For more information about all the options you have, see
    \l {Debugging Qt Quick Applications}.

    \section1 Before you start

    Before you start, you have to:

    \list
        \li \l {Install Qt VS Tools}
        \li \l {Add Qt versions}
        \li \l {Tutorial: Qt Quick application}{Create a Qt Quick Application}
        \li \l {Enable QML debugging}
    \endlist

    \section1 Set a breakpoint

    Go to \uicontrol File > \uicontrol Open > \uicontrol {File or Solution} to
    open the \e QuickAddressBook solution.

    To look at the code that adds a new contact, add a breakpoint in
    \e {NewAddressPopup.qml} by clicking the line that implements the
    \c onClicked signal handler and selecting \uicontrol {Debug} >
    \uicontrol {Toggle Breakpoint} (or pressing \key F9).

    \image {qtvstools-quick-addressbook-breakpoint.webp} {Setting a breakpoint}

    The red circle indicates that a breakpoint is now set on that line.

    \section1 Start debugging

    Go to \uicontrol Debug > \uicontrol {Start Debugging} or press \key F5.

    Once the application starts, select \uicontrol {Add} to create a new
    address book entry. Enter a name and email address, and select
    \uicontrol {Add} again to add the entry to the address book.

    When the debugger hits the breakpoint, it interrupts the application.
    Qt VS Tools displays the nested function calls leading to the current
    position as a call stack trace. View and change the values of
    local variables.

    \image {qtvstools-quick-addressbook-breakpoint-hit.webp} {Viewing a variable}

    \section1 Step through code

    Go to \uicontrol {Debug} > \uicontrol {Step Into} or press \key F11 to step
    into the code in the stack. The \e {NewAddressPopup.qml} file opens in the
    code editor at the function that creates a new address book entry.

    \image {qtvstools-quick-addressbook-step-into.webp} {Stepping into code}

    \section1 Watch variable values

    The \uicontrol {Autos} and \uicontrol {Locals} windows show a subset of
    local variables that Visual Studio considers possibly interesting based
    on the location of the breakpoint. To watch a particular variable or
    expression, set a watch in the \uicontrol {Watch 1} view.

    \image {qtvstools-quick-addressbook-watch.webp} {Watching a variable}

    Step through the code to see how the information changes in the view.

    \section1 Evaluate expressions

    To execute JavaSript commands in the context of the current stack frame, open
    the \uicontrol {Immediate Commands} window and type the expression to
    evaluate.

    \section1 Remove the breakpoint

    To remove the breakpoint, go to \uicontrol {Debug} >
    \uicontrol {Toggle Breakpoint} (or press \key F9).

    \sa {Cross-compile}, {Debug applications}, {Debug on Linux},
    {Debugging Qt Quick applications}
*/


/*!
    \page qtvstools-reference-projects.html
    \ingroup qtvstools-reference

    \title Projects

    Qt VS Tools provide wizards for creating several types of Qt and Qt Quick
    projects and files that you add to the projects, such as classes, form
    files, or custom QML types.

    You can also load existing Qt projects into Visual Studio for further
    development.

    Use the integrated Qt Resource editor to manage the resources in
    Qt projects.

    Create a Qt translation source (TS) file and start \QL from
    Visual Studio to translate the strings in your application.

    To create Qt projects, go to \uicontrol File > \uicontrol New >
    \uicontrol Project, and search for Qt.

    \image {qtvstools-projects.webp} {Qt project wizard templates}

    You can create following types of projects.

    \table
    \header
        \li Template
        \li Creates
    \row
        \li \uicontrol {Qt ActiveQt Server}
        \li A simple ActiveX server.
    \row
        \li \uicontrol {Qt Class Library}
        \li A basic Qt-based dynamic library.
    \row
        \li \uicontrol {Qt Console Application}
        \li A basic Qt console application.
    \row
        \li \uicontrol {\QD Custom Widget}
        \li A \QD custom widget plugin.
    \row
        \li \uicontrol {Qt Empty Application}
        \li An empty Qt application project.
    \row
        \li \uicontrol {Qt Quick Application}
        \li A Qt Quick application project.
    \row
        \li \uicontrol {Qt Test Application}
        \li A simple Qt test application.
    \row
        \li \uicontrol {Qt Widgets Application}
        \li A simple Qt widgets application with one form.
    \endtable

    Each Qt project provides a wizard that allows you to specify the Qt modules
    required for your project. For some projects, the wizard also generates
    a skeleton class or QML type instance to get you started.

    To start writing Qt code and building your projects, you must tell Visual
    Studio where to find the \l{Add Qt versions}{Qt version} that you want
    to use.

    The application tutorials contain examples of using the project templates:

    \list
        \li \l {Tutorial: Qt Widgets application}
        \li \l {Tutorial: Qt Quick application}
        \li \l {Tutorial: Qt Test application}
    \endlist

    \sa {Add Qt versions}, {Files}
*/

/*!
    \page qtvstools-reference-files.html
    \ingroup qtvstools-reference

    \title Files

    Use file templates to add files to projects.

    Go to \uicontrol Project > \uicontrol {Add New Item} >
    \uicontrol Installed > \uicontrol {Visual C++} > \uicontrol Qt.

    \image {qtvstools-add-new-item.webp} {Add New Item dialog}

    \table
    \header
        \li Template
        \li Adds
    \row
        \li \uicontrol {Qt .runsettings File}
        \li A Qt .runsettings file to a Qt Test Application project.
    \row
        \li \uicontrol {Qt Class}
        \li A Qt class to an Application project.
    \row
        \li \uicontrol {Qt Dialog Form File (Button Bottom)}
        \li A dialog with \uicontrol OK and \uicontrol Cancel buttons at
            its bottom to a Qt Widgets Application project.
    \row
        \li \uicontrol {Qt Dialog Form File (Button Right)}
        \li A dialog with buttons at its right edge to a
            Qt Widgets Application project.
    \row
        \li \uicontrol {Qt MainWindow Form File}
        \li A form file to a Qt Widgets Application project.
    \row
        \li \uicontrol {Qt QML File}
        \li A custom QML type to a Qt Quick Application project.
    \row
        \li \uicontrol {Qt QML Module Definition}
        \li A \c qmldir file that specifies the custom QML types used in a
            Qt Quick Application project.
    \row
        \li \uicontrol {Qt Resource File}
        \li A Qt resource file (.qrc) to an Application project.
    \row
        \li \uicontrol {Qt Translation File}
        \li A Qt translation file (.ts) to an Application project.
    \row
        \li \uicontrol {Qt Widget Form File}
        \li A Qt Widgets form file (.ui) to an Application project.
    \row
        \li \uicontrol {Qt Widgets Class}
        \li A Qt Widgets class to a Qt Widgets Application project.
    \endtable

    The following topics describe how to add different types of files to
    projects:

    \list
        \li \l {Create UI form files}
        \li \l {Manage resources}
        \li \l {Create Qt translation files}
    \endlist

    The application tutorials contain examples of using file templates to add
    files to projects:

    \list
        \li \l {Tutorial: Qt Widgets application}
        \li \l {Tutorial: Qt Quick application}
    \endlist

    \sa {Projects}
*/

/*!
    \page qtvstools-how-to-load-qt-projects.html
    \ingroup qtvstools-how-to

    \title Load Qt projects

    If your Qt projects have \c .pro files that you use to build them with
    \l {qmake Manual}{qmake}, load them to Visual Studio and convert
    them into solutions. Then, use Visual Studio to build them.

    To open Qt projects (.pro) in Visual Studio, go to \uicontrol Extensions >
    \uicontrol {Qt VS Tools} > \uicontrol {Open Qt Project File (.pro)}.

    \section1 View conversion reports

    A message on the info bar indicates that the conversion is complete.

    \image {qtvstools-pro-file-conversion-message.webp} {Project format conversion complete message}

    To see the changes that Qt VS Tools made, select \uicontrol {View report}.

    \image {qtvstools-pro-file-conversion-report.webp} {Project format conversion report}

    \section1 Hide the message

    To turn off notifications about completing the conversion:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {Notifications}.
            \image {qtvstools-options-qt-general-notifications.webp} {Notifications in Qt General Options}
        \li In \uicontrol {CMake conversion confirmation}, select
            \uicontrol Disable.
    \endlist

    \sa {Building}, {Configuring builds}
*/

/*!
    \page qtvstools-explanation-configuring-builds.html
    \ingroup vstools-explanation

    \title Configuring builds

    Visual Studio uses the Project System to build C++ projects, where MSBuild
    provides the project file format and build framework. Qt VS Tools integrate
    with MSBuild, so that you design and build Qt applications as Visual Studio
    projects. In addition, Visual Studio supports using \l {Build with CMake}
    {CMake} to build projects.

    When you create new Qt application projects, select whether to use
    MSBuild or CMake to build them. The wizards create the necessary files for
    you.

    \image {qtvstools-wizard-cmake.webp} {Selecting CMake in the application wizard}

    Load .pro files to Visual Studio to continue developing existing Qt
    application projects that you configured to use qmake.

    \section1 MSBuild configurations

    At very general level, MSBuild works as follows:

    \list
        \li An MSBuild project consists of references to source files and
            descriptions of actions for processing those source
            files that are called \e targets.
        \li The build process runs in the context of a project configuration,
            such as \e Debug or \e Release. A project may contain any number
            of configurations.
        \li Data associated to source files and the project itself is accessible
            through \e properties. MSBuild properties are name-value definitions,
            specified per configuration. That is, each configuration has its own
            set of property definitions.
    \endlist

    \image {qtvstools-msbuild-configurations.webp} {Diagram showing Visual Studio Project and MSBuild}

    \section2 Properties

    Set property values for the project itself (\e {project scope}) or
    for a specific file in the project (\e {file scope}), either globally or
    locally:

    \list
        \li Project scope properties are always global. For example, the
            project's output directory or target file name.
        \li Properties that apply to source files can be global, in
            which case the same value applies to all files. For example,
            set the default compiler warning level globally at level 3.
        \li To override such a global, file-scope definition for a
            specific file define a local property with the same name.
            For example, compile one of the source files with warning level 4.
        \li Global definitions are stored in the project file or imported from
            property sheet files.
        \li Local property definitions are stored in the project file, within
            the associated source file references.
    \endlist

    \section2 Qt settings

    Qt VS Tools provide the MSBuild project system with a set of
    Qt-specific targets that describe how to use the appropriate Qt tools to
    process files such as moc headers.

    \image {qtvstools-qt-project-settings.webp} {Qt Project Settings}

    Qt settings are fully-fledged project properties, which ensures that:

    \list
        \li Changes in Qt settings are synchronized with all the other
            properties in the project.
        \li You can specify Qt settings, such as Qt versions and modules,
            separately for each build configuration.
        \li You can override compiler properties for files that Qt tools
            generate in project settings
        \li To share Qt settings within a team or organization,
            export and import them to and from shared \e {property sheet}
            files (\c .props).
    \endlist

    \sa {Add Qt versions}, {Cross-compile}, {Load Qt projects}, {Building}
*/

/*!
    \page qtvstools-how-to-add-qt-versions.html
    \ingroup qtvstools-how-to

    \title Add Qt versions

    You can develop with multiple Qt versions in parallel, such as Qt 5.15.11 and
    Qt 6.8.0. You have to add at least one Qt version that was built for MSVC to
    be able to create Qt projects.

    \image {qtvstools-qt-versions.webp} {Qt Versions}

    \section1 Detect installed Qt versions

    Qt VS Tools can automatically detect Qt versions that you install with \QOI.
    To automatically detect installed Qt versions, select \uicontrol Autodetect.

    To detect installed Qt versions from a folder, select \uicontrol Import and
    locate the Qt installation folder.

    \section1 Remove Qt versions

    To remove entries for Qt versions that you have uninstalled, select
    \uicontrol {Cleanup}.

    To remove a particular Qt version, select it in the list and then select
    \uicontrol Remove.

    You can remove the default Qt version only if you make another version the
    default or if it is the only Qt version in the list.

    \section1 Set default Qt version

    To set the Qt version to use by default when creating new projects or
    importing a project from a \c {.pro} file, select it in the list and
    then select \uicontrol Default.

    \section1 Turn off notifications about new Qt versions

    To turn off notifications about new Qt versions being available:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {Notifications}.
            \image {qtvstools-options-qt-general-notifications.webp} {Notifications in Qt General Options}
        \li In \uicontrol {Update Qt installation}, select \uicontrol Disable.
    \endlist

    \section1 Add other Qt versions

    To add Qt versions that you installed from other sources than \QOI or built
    yourself:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol {Qt Versions}.
        \li Select \uicontrol Add.
        \li In \uicontrol Name, enter a name for the Qt version. If you add the
            location of Qt first, this field is filled automatically.
        \li In \uicontrol Location, enter the path to the qmake.exe for
            the Qt version.
            For example: \c {C:\Qt\6.8.0\msvc2022_64\bin\qmake.exe}.
        \li In \uicontrol Host, select \uicontrol Windows, unless you
            want to cross-compile the application for an embedded Linux device.
            \uicontrol Compiler shows the compiler type.
        \li Select \uicontrol OK.
    \endlist

    \sa {Select Qt versions for a project}, {Cross-compile}, {Load Qt projects}
*/

/*!
    \page qtvstools-how-to-select-qt-versions-for-project.html
    \ingroup qtvstools-how-to

    \title Select Qt versions for a project

    To select another Qt version than the default Qt version for a project:

    \list 1
        \li In \uicontrol {Solution Explorer}, right-click the project and
            go to \uicontrol Properties in the context menu.
        \li Select \uicontrol {Configuration Properties} >
            \uicontrol {Qt Project Settings}.
            \image {qtvstools-qt-project-settings.webp} {Qt Project Settings dialog}
        \li In \uicontrol {Qt Installation}, select the Qt version.
    \endlist

    \section1 CMake projects

    When you create or load Qt application projects, Qt VS Tools creates the
    necessary files for you: CMakePresets.json and CMakeUserPresets.json.

    To select a Qt version for a CMake project:

    \list 1
        \li In the CMakeUserPresets.json file, find the visible preset (that is,
            without the text \c {"hidden":true}) whose display name matches the
            configuration.
        \li In that preset, set the \c {"inherits"} property to the registered
            name of the target Qt version, as it appears in \uicontrol Tools >
            \uicontrol Options > \uicontrol Qt > \uicontrol Versions.

            If the preset inherits from a list of presets, make sure that the
            target Qt version is the only Qt version referenced in the list.

            To select the default Qt version, use \c {"Qt-Default"}.
    \endlist

    \sa {Add Qt versions}, {Cross-compile}
*/

/*!
    \page qtvstools-explanation-building.html
    \ingroup qtvstools-explanation

    \title Building

    Qt VS Tools includes MSBuild rules and targets specific to
    \l {Using the Meta-Object Compiler (moc)}{Meta-Object Compiler (moc)},
    \l {User Interface Compiler (uic)}, and \l {Resource Compiler (rcc)}.
    These rules are referred to as \e Qt/MSBuild. They enable running moc,
    rcc and uic in parallel processes and setting build options, such as
    selecting project items to process and the tools to process them.
    Further, source files that the Qt tools generate are added to the C++
    compilation during the build process, so you do not need to include
    generated files in projects.

    You can set options for each Qt tool either globally at project level
    or for specific files. To set global options for handling files at project
    level:

    \list
        \li Go to \uicontrol Project > \uicontrol Properties >
            \uicontrol {Configuration Properties} >
            \uicontrol {Qt Project Settings}.
        \li Go to \uicontrol Properties in the context menu of the project.
    \endlist

    \image {qtvstools-qt-project-settings.webp} {Qt Project Settings}

    To set options for handling a specific file, go to \uicontrol Properties in
    the context menu of the file. The dialog lists only tools relevant for the
    file type. For example, moc options are available for C++ source and header
    files, whereas uic options are available for UI forms (.ui).

    \section1 Qt/MSBuild project format

    The Qt/MSBuild project file format has changed between Qt VS Tools versions.
    Currently, version 3 and later are supported.

    If you open an existing solution that has version 1 project format, you can
    still build it. If it has version 2 format, you can build it if you set
    additional command line options and set the default Qt version
    to the Qt version that you initially created the project for.

    When you load .pro files, Qt VS Tools automatically converts
    \e {custom build steps} into Qt/MSBuild steps.

    For more information about Qt/MSBuild project format versions, see
    \l {https://github.com/qt-labs/vstools/blob/dev/Tests/ProjectFormats/ProjectFormats.md}
    {Qt VS Tools - Project format versions}.

    \section1 Path to build files

    To set the path to the Qt/MSBuild files, go to \uicontrol Extensions >
    \uicontrol {Qt VS Tools} > \uicontrol Options > \uicontrol {Qt/MSBuild}.

    \image {qtvstools-options-qt-general-qt-msbuild.webp} {Qt/MSBuild in Qt General Options}

    This corresponds to setting the value of the \c QTMSBUILDS environment
    variable.

    \sa {Build solutions that have Qt/MSBuild format 2},
    {Convert solutions to latest Qt/MSBuild format}, {Load Qt projects}
*/

/*!
    \page qtvstools-how-to-build-older-projects.html
    \ingroup qtvstools-how-to

    \title Build solutions that have Qt/MSBuild format 2

    The Qt/MSBuild project format has changed between Qt VS Tools versions.

    To build solutions that have project format 2:

    \list 1
        \li Open the solution.
        \li In the context menu, go to \uicontrol Properties >
            \uicontrol {C/C++} > \uicontrol {Command Line} to
            set additional command line options.
        \li In \uicontrol {Additional Options}, enter the following options:
            \c {/std:c++17 /Zc:__cplusplus /permissive-}
            \image {qtvstools-convert-project-format.webp} {Additional command line options}
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol {Qt Versions}.
        \li Select the Qt version that you initially created the project for, and
            then select \uicontrol Default.
            \image {qtvstools-qt-versions.webp} {Qt Versions}
    \endlist

    \sa {Add Qt versions}, {Convert solutions to latest Qt/MSBuild format},
    {Building}
*/

/*!
    \page qtvstools-how-to-convert-project-format.html
    \ingroup qtvstools-how-to

    \title Convert solutions to latest Qt/MSBuild format

    To further develop existing solutions that have old Qt/MSbuild project
    format, convert them to the supported project format version:

    \list 1
        \li Open the solution.
        \li Select \uicontrol Update.
            \image {qtvstools-open-solution-update.webp} {Opening a solution with old project format}
        \li If you don't see the message, right-click the solution and go to
            \uicontrol Qt > \uicontrol {Convert custom build steps to Qt/MSBuild}
            in the context menu.
    \endlist

    \section1 Filter legacy projects within solutions

    If the solution contains several Qt projects, select
    \uicontrol {Legacy Project Filter} on the \uicontrol {Solution Explorer}
    toolbar to filter the projects that have the old format.

    \image {qtvstools-legacy-project-filter.webp} {Legacy Project Filter button}

    \sa {Build solutions that have Qt/MSBuild format 2}, {Building}
*/

/*!
    \page qtvstools-how-to-cross-compile.html
    \ingroup qtvstools-how-to

    \title Cross-compile

    Qt VS Tools support cross-compilation of Qt projects by integrating
    Qt/MSBuild and the Linux development VS workload. This enables you to
    develop widget-based and Qt Quick applications that target both Windows
    and Linux, including embedded devices.

    \section1 Set up cross-compilation

    To develop Qt applications for Linux using Visual Studio:

    \list 1
        \li Install the Desktop development with C++ and Linux development with
            C++ workloads.
        \li Enable the Windows Subsystem for Linux (WSL) and install a
            Linux distribution.
        \li Or, create a connection to a remote Linux build server.
        \li Add the cross-compiled Qt build that resides in a WSL instance
            or the remote build server.
    \endlist

    \section1 Add Qt version for cross-compilation

    To add a Qt version for cross-compilation:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol {Qt Versions}.
            \image {qtvstools-qt-versions.webp} {Qt Versions}
        \li Select \uicontrol Add.
        \li In \uicontrol Name, enter a name for the Qt version. If you add the
            location of Qt first, this field is filled automatically.
        \li In \uicontrol Location, enter the path to the Qt installation.
        \li In \uicontrol Host, select \uicontrol {Linux WSL} or
            \uicontrol {Linux SSH}.
        \li \uicontrol Compiler shows the cross-compiler to use.
    \endlist

    \section1 Compile on WSL

    Using a WSL instance to run the cross-compiler is faster than using an
    SSH connection to a build host. When using SSH, MSBuild must first upload
    the source files to the remote host, whereas WSL mounts local drives in
    \c /mnt, making file access instantaneous.

    MSBuild assumes that paths specified in options are local paths and maps
    them to corresponding Linux paths rooted on \c /mnt. For example:

    \badcode
    C:\include\foolib maps to /mnt/c/include/foolib
    \endcode

    Using absolute Linux paths as value of \uicontrol Extensions >
    \uicontrol {Qt VS Tools} > \uicontrol Options > \uicontrol {Qt/MSBuild}
    can lead to wrong mappings. For example, \c {/home/user/raspi} maps
    to \c {/mnt/home/user/raspi}.

    To avoid this issue, create symbolic links in \c /mnt to other top-level
    directories in the WSL instance file system.

    \sa {Tutorial: Qt Quick debugging}, {Debug applications}, {Debug on Linux},
    {Enable QML debugging}, {Building}, {Debugging Qt Quick applications}
*/

/*!
    \page qtvstools-how-to-add-form-files.html
    \ingroup qtvstools-how-to

    \title Create UI form files

    Use \QD to design widget-based UIs.

    To add a new \c .ui file to the project, go to \uicontrol Project >
    \uicontrol {Add New Item} > \uicontrol Installed > \uicontrol {Visual C++} >
    \uicontrol Qt > \uicontrol {Qt Widgets Form File}.

    \image {qtvstools-qt-widget-class-wizard.webp} {Qt Widgets Class Wizard}

    Typically, you need to wrap the code generated for the form file into a
    QWidget subclass to add signals or slots to it. Therefore, Qt VS Tools
    create a \c .h and \c .cpp file for you, along with an empty UI form.

    \sa {Tutorial: Qt Widgets application}, {Start \QD},
    {\QD Manual}
*/

/*!
    \page qtvstools-how-to-start-qt-designer.html
    \ingroup qtvstools-how-to

    \title Start \QD

    To start \QD:

    \list
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol {Launch \QD}.
        \li Double-click a \c .ui file in the \uicontrol {Solution Explorer}.
    \endlist

    \section1 Detach \QD

    To run \QD in a separate window by default:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {\QD}.
            \image {qtvstools-options-qt-general-qd.webp} {Qt Designer in Qt General Options}
        \li Set \uicontrol {Run in detached window} to \uicontrol True.
    \endlist

    To be notified when \QD is detachable, select \uicontrol {Notifications},
    and then set \uicontrol {Designer window detachable} to \uicontrol {Enabled}.

    \image {qtvstools-options-qt-general-notifications.webp} {Notifications in Qt General Options}

    \sa {Create UI form files}, {Set tool theme}, {\QD Manual}
*/

/*!
    \page qtvstools-how-to-set-tool-theme.html
    \ingroup qtvstools-how-to

    \title Set tool theme

    You can start \QD, \QL, and Qt Resource Editor with a particular color theme
    or style sheet.

    To set editor color them and style sheet:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {Style}.
            \image {qtvstools-options-qt-general-style.webp} {Style in Qt General Options}
        \li In \uicontrol {Color theme}, select the theme to use in the Qt tools.
            The \uicontrol Consistent option uses the Visual Studio color theme.
        \li In \uicontrol {Path to stylesheet}, select a style sheet for the Qt
            tools.
    \endlist

    \sa {Start \QD}, {Start \QL}, {Start Qt Resource Editor}
*/

/*!
    \page qtvstools-how-to-manage-resources.html
    \ingroup qtvstools-how-to

    \title Manage resources

    Adding new resources to a Qt project is similar to adding resources to a
    normal C++ project. The main difference is that you use Qt resource files
    (\c .qrc ) instead of Windows \c .rc files. Unlike \c .rc files , \c .qrc
    files work on all platforms that Qt supports and are trivial to load from Qt
    code.

    To add new resources:

    \list 1
        \li Go to \uicontrol Project > \uicontrol {Add New Item} >
            \uicontrol Installed > \uicontrol {Visual C++} > \uicontrol Qt.
        \li Select \uicontrol {Qt Resource File}.
            \image {qtvstools-new-project-item-qt-resource-file.webp} {Add New Item dialog}
        \li In \uicontrol Name, enter a name for the resource file.
        \li In \uicontrol Location, specify a location for the file.
        \li Select \uicontrol Add to create a \c .qrc file and to open it in the
            \uicontrol {Qt Resource Editor}.
            \image {qtvstools-qrc-editor.png} {Qt Resource Editor}
        \li To add resources to the file, select \uicontrol Add >
            \uicontrol {Add Files}.
        \li In \uicontrol Prefix, you can change the prefix.
    \endlist

    When referring to the resources later on from Qt code, you must prepend the
    prefix, the file name, and a colon. For example, \c{:/MyProject/print.bmp}.

    \section1 Add prefixes

    To add prefixes to the \c .qrc file, select \uicontrol Add >
    \uicontrol {Add Prefix} in the \uicontrol {Qt Resource Editor}.

    \sa {Start Qt Resource Editor}, {The Qt Resource System}
*/

/*!
    \page qtvstools-how-to-start-qt-resource-editor.html
    \ingroup qtvstools-how-to

    \title Start Qt Resource Editor

    To start Qt Resource Editor, double-click a \c .qrc file in the Solution
    Explorer.

    \image {qtvstools-qrc-editor.png} {Qt Resource Editor}

    \section1 Detach Qt Resource Editor

    By default, Qt Resource Editor opens in Visual Studio. To run it in a
    separate window, select \uicontrol Detach.

    To run \uicontrol {Qt Resource Editor} in a separate window by default:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol {Qt Resource Editor}.
            \image {qtvstools-options-qt-general-qrc-editor.webp} {Qt Resource Editor in Qt General Options}
        \li Set \uicontrol {Run in detached window} to \uicontrol True.
    \endlist

    To be notified when Qt Resource Editor is detachable, select
    \uicontrol {Notifications}, and then set
    \uicontrol {Qt Resource Editor window detachable} to \uicontrol {Enabled}.

    \image {qtvstools-options-qt-general-notifications.webp} {Notifications in Qt General Options}

    \sa {Manage resources}, {Set tool theme}, {The Qt Resource System}
*/

/*!
    \page qtvstools-how-to-create-qt-translation-files.html
    \ingroup qtvstools-how-to

    \title Create Qt translation files

    Design applications so that they can be adapted to various languages
    and regions without engineering changes. Mark UI text as translatable
    to create Qt translation source (TS) files that contain them, and start
    \QL to translate the strings.

    To add a new translation file to the project:

    \list 1
        \li Go to \uicontrol Project > \uicontrol {Add New Item} > \uicontrol Installed >
            \uicontrol {Visual C++} > \uicontrol Qt > \uicontrol {Qt Translation File}.
        \li In \uicontrol {Select a Language}, select a language from the list
            of supported languages. Use \uicontrol Search to filter for a specific
            language.
            \image {qtvstools-qt-translation-file-wizard.png} {Adding a translation file to a project}
        \li In \uicontrol {Save as}, enter a filename for the translation file.
        \li Go to \uicontrol Finish to create the file and have it listed in
            \uicontrol {Translation Files} in Visual Studio's
            \uicontrol {Solution Explorer}.
        \li Right-click the translation file to open a context menu, and go to
            \c lupdate. It finds translatable strings in source, header, and UI
            files and generates or updates TS files.
    \endlist

    After translating the UI text, go to \c lrelease in the context menu to
    create QM files out of TS files. The QM file format is a compact binary
    format that the localized application uses to look up translations.

    \sa {Start \QL}, {Update Qt translation files},
    {Internationalization with Qt}, {\QL Manual}
*/

/*!
    \page qtvstools-how-to-update-qt-translation-files.html
    \ingroup qtvstools-how-to

    \title Update Qt translation files

    To update all TS or QM files for a project, go to \uicontrol Qt >
    \uicontrol {lupdate All .ts Files for Project} or
    \uicontrol {lrelease All .ts Files for Project} in the context menu for the
    project.

    \section1 Run translation tools during builds

    To run \l {Using lupdate}{lupdate} or \l {Using lrelease}{lrelease} when you
    build a project:

    \list 1
        \li In \uicontrol {Solution Explorer}, right-click the project and
            select \uicontrol Qt > \uicontrol {Qt Project Settings} in the
            context menu.
        \li Select \uicontrol {Configuration Properties} >
            \uicontrol {Qt Translation} > \uicontrol {General}.
        \li In \uicontrol {Run Translation Tool During Build}, select the tools
            to run.
            \image {qtvstools-project-properties-qt-translation.webp} {Qt Translation properties}
    \endlist

    \note The \uicontrol {Qt Translation} properties are shown only if the
    project has translation files.

    \section1 Set lupdate properties

    To set properties for running \c lupdate for a project:

    \list 1
        \li In \uicontrol {Solution Explorer}, right-click the project and
            select \uicontrol Qt > \uicontrol {Qt Project Settings} in the
            context menu.
        \li Select \uicontrol {Configuration Properties} >
            \uicontrol {Qt Translation} > \uicontrol {lupdate}.
            \image {qtvstools-project-properties-lupdate.webp} {lupdate properties}
        \li Select a property to see its description.
    \endlist

    For a list of properties that you can set in \uicontrol {AdditionalOptions},
    see \l {lupdate options}.

    \section1 Set lrelease properties

    To set properties for running \c lrelease for a project:

    \list 1
        \li In \uicontrol {Solution Explorer}, right-click the project and
            select \uicontrol Qt > \uicontrol {Qt Project Settings} in the
            context menu.
        \li Select \uicontrol {Configuration Properties} >
            \uicontrol {Qt Translation} > \uicontrol {lrelease}.
            \image {qtvstools-project-properties-lrelease.webp} {lrelease properties}
        \li Select a property to see its description.
    \endlist

    For a list of properties that you can set in \uicontrol {AdditionalOptions},
    see \l {lrelease options}.

    \sa {Create Qt translation files}, {Start \QL},
    {Internationalization with Qt}, {\QL Manual}
*/

/*!
    \page qtvstools-how-to-start-qt-linguist.html
    \ingroup qtvstools-how-to

    \title Start \QL

    To start \QL:

    \list
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol {Launch \QL}.
        \li Double-click a \c .ts file in the \uicontrol {Solution Explorer}.
    \endlist

    \section1 Detach \QL

    To run \QL in a separate window by default:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {\QL}.
            \image {qtvstools-options-qt-general-ql.webp} {Qt Linguist in Qt General Options}
        \li Set \uicontrol {Run in detached window} to \uicontrol True.
    \endlist

    To be notified when \QL is detachable, select \uicontrol {Notifications},
    and then set \uicontrol {Linguist window detachable} to \uicontrol {Enabled}.

    \image {qtvstools-options-qt-general-notifications.webp} {Notifications in Qt General Options}

    \sa {Create Qt translation files}, {Set tool theme},
    {Internationalization with Qt}, {\QL Manual}
*/

/*!
    \page qtvstools-how-to-get-help.html
    \ingroup qtvstools-how-to

    \title Get help

    By default, Qt VS Tools try to display Qt online documentation when you
    press \key F1. If you often end up in the Qt documentation even though you
    wanted Microsoft documentation, turn off this feature and use the
    default shortcut \key {Alt+F1}.

    To access Microsoft documentation when pressing \key F1:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol Help.
            \image {qtvstools-options-qt-general-help.webp} {Help in Qt General Options}
        \li Set \uicontrol {Try Qt documentation when F1 is pressed} to
            \uicontrol False.
    \endlist

    \section1 Access offline help

    To read the documentation delivered with your Qt version instead of the
    latest online version, set \uicontrol {Preferred source} to
    \uicontrol Offline.

    \section1 Change Qt online help keyboard shortcut

    To set up another keyboard shortcut for Qt online help:

    \list 1
        \li Go to \uicontrol Tools > \uicontrol Options >
            \uicontrol Environment > \uicontrol Keyboard.
            \image {qtvstools-options-environment-keyboard.webp} {Keyboard in Environment options}
        \li In \uicontrol {Show commands containing}, enter \e {Help.F1Help}.
        \li Select \uicontrol {Press shortcut keys} and press your
            preferred keys to add them to the field.
        \li Select \uicontrol Assign, and then select \uicontrol OK.
    \endlist
*/

/*!
    \page qtvstools-how-to-update-intellisense-info.html
    \ingroup qtvstools-how-to

    \title Update IntelliSense info

    Visual Studio provides IntelliSense code editing features for C++ types
    including code completion, parameter info, and member lists.

    To keep IntelliSense info updated also with code generated by
    Qt tools, such as \l {Using the Meta-Object Compiler (moc)}{moc},
    \l {User Interface Compiler (uic)}{uic}, or \l {Resource Compiler (rcc)}
    {rcc}, they run in the background when source files change. If this
    creates too much overhead for large solutions, disable the
    \uicontrol {Run Qt tools in background build} option to only update
    the minimum set of Qt build properties needed to ensure that Qt types
    are included in the IntelliSense index.

    If you disable the option and code completion does not work, try to rebuild
    the project. You might have to wait some time before code completion fully
    works after updating a source file. If rebuilding does not help, refresh the
    code model by going to \uicontrol {Rescan Solution} in the context menu of
    the project.

    \section1 Refresh IntelliSense info

    To refresh IntelliSense info, go to \uicontrol Qt >
    \uicontrol {Refresh IntelliSense} in the context menu
    of the project.

    \section1 Set IntelliSense options

    To set options for updating IntelliSense info:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol IntelliSense.
            \image {qtvstools-options-qt-general-intellisense.webp} {IntelliSense in Qt General Options}
        \li Select options:
            \list
                \li \uicontrol {Auto project tracking} tracks changes and
                    triggers a background build of Qt targets when necessary.
                \li \uicontrol {Show debug information} displays debug
                    information about IntelliSense info updates.
                \li \uicontrol {Verbosity of background build log} sets the
                    amount of info recorded in the background build log.
            \endlist
    \endlist

    \sa {Turn on QML Language Server}
*/

/*!
    \page qtvstools-how-to-enable-qmlls.html
    \ingroup qtvstools-how-to

    \title Turn on QML Language Server

    For several programming languages, a language server offers information
    about the code to IDEs as long as they support communication via the
    \l{QML Language Server Reference}{language server protocol (LSP)}. The IDE
    can then offer services, such as code completion.

    Turn on the QML Language Server to get code editing services when developing
    Qt Quick applications if:

    \list
        \li The default Qt version supports the QML Language Server
            (available since Qt 6.5).
        \li The Visual Studio version supports
            \l {https://learn.microsoft.com/en-us/visualstudio/extensibility/adding-an-lsp-extension}
            {LSP}.
    \endlist

    The services you get depend on the Qt version and Visual Studio version
    that you use.

    To turn on the QML Language Server:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {QML Language Server}.
            \image {qtvstools-options-qt-general-qmlls.webp} {QML Language Server in Qt General Options}
        \li In \uicontrol Enable, select \uicontrol Enable to turn on the
            QML Language Server.
        \li In \uicontrol Log, select \uicontrol Enable to write LSP messages to
            a log file in a temporary folder.
        \li In \uicontrol {Log size}, set the maximum size of the log file in KB.
        \li In \uicontrol {QML Language Server path}, select the path to the
            QML Language Server version you want to use. Leave the field empty
            to use the default version that Qt VS Tools provides. However, if you
            develop with a Qt version earlier than 6.5.0, Qt VS Tools tries to
            start QML Language Server for that version, and if it is not
            available, the default version.
    \endlist

    To receive notifications for QML Language Server updates:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {Notifications}.
            \image {qtvstools-options-qt-general-notifications.webp} {Notifications in Qt General Options}
        \li In \uicontrol {QML Language Server update}, select \uicontrol Enable.
    \endlist

    \sa {Update IntelliSense info}
*/

/*!
    \page qtvstools-how-to-debug-apps.html
    \ingroup qtvstools-how-to

    \title Debug applications

    You can debug:

    \list
        \li Qt C++ applications using the Visual Studio debugger.
        \li Qt Quick applications using the \e {QML debug engine}.
        \li Applications on Linux using GDB.
    \endlist

    \section1 Start debugging

    To start a debugging session:

    \list
        \li Go to \uicontrol Debug > \uicontrol {Start Debugging}.
        \li To debug a CMake project, select the main source
            file in\uicontrol {Solution Explorer} and then select
            \uicontrol {Set as Startup Item} in the context menu.
        \li Press \key F5.
    \endlist

    \section1 Set breakpoints

    Set breakpoints in C++ and QML files and step through the execution of code.
    While in break mode, watch variables and change their values, as
    well as evaluate arbitrary expressions. For Qt Quick applications, a QML
    debugging session runs concurrently to a C++ debugging session, which
    enables you to set breakpoints and watch variables in both C++ and QML
    during the same debugging session.

    \sa {Tutorial: Qt Quick debugging}, {Cross-compile}, {Debug on Linux},
    {Enable QML debugging}, {Debugging Qt Quick Applications},
    {Visualize C++ types}
*/

/*!
    \page qtvstools-how-to-embed-natvis-files.html
    \ingroup qtvstools-how-to

    \title Visualize C++ types

    The Visual Studio Natvis framework customizes the way native types appear
    in debugger variable windows, such as the \uicontrol Locals and
    \uicontrol Watch windows, and in \uicontrol DataTips. You can add
    visualization rules to \c {.natvis} files. By default, the user-specific
    files are in \c {%USERPROFILE%\Documents\Visual Studio 2022\Visualizers}.

    You can embed debugger visualizations into the program database (PDB) file
    generated by \c LINK. It contains type and symbolic debugging information
    collected when compiling and linking the project.

    Embedding Natvis files into PDB files has the following benefits:

    \list
        \li \e {Portability} - The visualization logic travels with the binary,
            ensuring that anyone using the binary (such as other developers,
            testers, or users) benefits from the custom debug visualizations
            without needing to manually copy the .natvis file to a specific
            directory.
        \li \e {Version consistency} - The visualizer is guaranteed to match
            the version of the binary, as they are packaged together. If the
            binary changes, the visualizer reflects the correct internal
            structures or changes, avoiding mismatches.
        \li \e {Ease of distribution} - When distributing the binary (for example,
            for internal builds or external releases), the embedded Natvis file
            is automatically included, so you don't need to distribute a separate
            one and install it on each computer.
        \li \e {Security} - A Natvis file that is a part of the binary is
            more secure and controlled, as users cannot modify it.
    \endlist

    \section1 Embed Natvis files in PDB files

    To embed Natvis files into PDB files:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {Natvis}.
            \image {qtvstools-options-qt-general-natvis.webp} {Natvis in Qt General Options}
        \li Set \uicontrol {Embed .natvis file into PDB} to \uicontrol Enable.
    \endlist

    The embedded Natvis file takes precedence over user-specific Natvis files.

    \sa {Debug applications}
*/

/*!
    \page qtvstools-explanation-debugging-qt-quick.html
    \ingroup qtvstools-explanation

    \title Debugging Qt Quick applications

    A debugger lets you see what happens \e inside an application while it runs
    or when it crashes. A debugger can do the following to help you find errors
    in the application:

    \list
        \li Start the application with parameters that specify its behavior.
        \li Stop the application when conditions are met.
        \li Examine what happens when the application stops.
        \li Make changes in the application when you fix an error and continue
            to find the next one.
    \endlist

    \section1 QML debug engine

    A \e {QML debug engine} extends the Visual Studio debugger with features of
    the \l{QML Debugging Infrastructure}{QML debugging infrastructure}, which is
    a part of the \l{Qt Qml} module that offers services for debugging,
    inspecting, and profiling applications via a TCP port. The debug engine
    implements interfaces from the Active Debugging 7 (AD7) extensibility
    framework for the Visual Studio debugger.

    \section1 Setting breakpoints

    If a Qt project has QML resource files, starting a debugging session
    (for example, by pressing \key F5) launches the native application and
    connects to the QML debugging infrastructure of that application. You can see
    this in the \uicontrol {Processes} window of the Visual Studio debugger.

    \image {qtvstools-quick-addressbook-step-into.webp} {Viewing processes}

    The \uicontrol {Processes} window
    lists two processes: a native process and a QML process. The native process
    corresponds to the actual physical process created for the C++ debugging
    session. The QML process does not correspond to any physical process that is
    running on the machine, but represents the connection to the QML debugging
    runtime within the native process.

    The presence of both a native process and a QML process enables setting
    breakpoints both in C++ or QML code. The Visual Studio debugger forwards
    breakpoint requests to the appropriate debug engine. A filled circular
    breakpoint marker in QML code indicates a valid breakpoint. This means that
    a breakpoint request for that file position was sent to the QML runtime
    and was confirmed by it.

    \section1 Examining data

    When a breakpoint is hit, Visual Studio shows the current state of the call
    stack. Unlike other scenarios of debugging applications that mix several
    languages, such as .NET and native debugging, the QML debug engine does not
    provide true mixed mode debugging. It runs concurrently with the native
    debug engine and is not considered to be related to the native process by
    the Visual Studio debugger. Therefore, even though you can debug both C++
    and QML in the same debugging session, the stack that is shown when a QML
    breakpoint is hit includes only QML function calls. The C++ context of those
    calls will not be available.

    As in the case of native debugging, while in break mode, you can
    view and change the values of local variables in the context of the
    currently active call stack frame, as well as create watches for any
    variable or expression. In the Immediate window, evaluate any
    expression in the context of the current stack frame.

    Move the mouse over a QML expression to display an instant watch window.
    View and change the value of that expression in the current context.

    \sa {Tutorial: Qt Quick debugging}, {Cross-compile}, {Debug applications},
    {Debug on Linux}, {Enable QML debugging}
*/

/*!
    \page qtvstools-how-to-enable-qml-debugging.html
    \ingroup qtvstools-how-to

    \title Enable QML debugging

    To enable QML debugging for a project:

    \list 1
        \li In \uicontrol {Solution Explorer}, right-click the project and
            select \uicontrol Properties in the context menu.
        \li Select \uicontrol {Configuration Properties} >
            \uicontrol {Qt Project Settings}.
        \li In \uicontrol {Enable QML Debugging}, select \uicontrol {Yes}.
            \image {qtvstools-quick-addressbook-enable-qml-debugging.webp} {Enabling QML debugging for a project}
        \li Select \uicontrol {OK} to save the project settings.
        \li Go to \uicontrol {Build} > \uicontrol {Rebuild Solution} to rebuild
        the project.
    \endlist

    \section1 Disable QML debugging

    To disable processing of all QML debug events by the QML debug engine:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {QML Debugging}.
            \image {qtvstools-options-qt-general-qml-debugging.webp} {QML Debugging in Qt General Options}
        \li Set \uicontrol {Process debug events} to \uicontrol False.
    \endlist

    This effectively excludes the QML debug engine from the debugging
    environment and disables debugging of QML code for all projects.

    \section1 Set debugging connection timeout

    To increase or decrease the timeout for debugging connections in
    milliseconds:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {QML Debugging}.
        \li Set the value of \uicontrol {Runtime connection timeout} in
            milliseconds.
    \endlist

    To remove the timeout, set the value to \uicontrol Disabled.

    \sa {Tutorial: Qt Quick debugging}, {Cross-compile}, {Debug applications},
    {Debug on Linux}, {Debugging Qt Quick applications}
*/

/*!
    \page qtvstools-how-to-debug-on-linux.html
    \ingroup qtvstools-how-to

    \title Debug on Linux

    Set up Qt VS Tools for \l {Cross-compile}{cross-compilation}
    on Linux, to debug applications running on Linux devices. First
    launch the application using \c gdbserver and then configure GDB to connect
    to the device and start a remote debugging session.

    \image {qtvstools-remote-debugging.webp} {Debugging applications running on Linux devices}

    For this to work, the GDB installed in the WSL must support the target
    device architecture. A simple way to achieve this is to install
    \c gdb-multiarch. To ensure that Visual Studio uses the correct debugger,
    create a symbolic link from \c gdb to \c gdb-multiarch.

    \section1 Set up remote debugging

    To set up the remote debugging session in Visual Studio, you must
    pass additional commands to GDB:

    \list 1
        \li Select a project in the \uicontrol {Solution Explorer}.
        \li Go to \uicontrol Project > \uicontrol Properties >
            \uicontrol {Configuration Properties} > \uicontrol Debugging.
            \image {qtvstools-project-properties-debugging.webp} {Debugging properties}
        \li In \uicontrol {Debugger to launch}, select \uicontrol {GDB Debugger}.
        \li In \uicontrol {Additional Debugger Commands}, add the following
            commands:

            \badcode
            target extended-remote <IP_address>:<port>
            set remote exec-file <path_to_executable>
            \endcode
    \endlist

    \section1 Set environment variables

    Before starting the remote debugging session:

    \list 1
        \li Set the required environment variables:
            \list
                \li \l{https://man7.org/linux/man-pages/man8/ld.so.8.html}
                    {LD_LIBRARY_PATH} specifies the path to the directory
                    where you installed Qt binaries.
                \li \l {Qt for Embedded Linux}{QT_QPA_PLATFORM} specifies the
                    platform plugin, such as EGLFS, LinuxFB, DirectFB, or Wayland.
                \li \c QT_QPA_PLATFORM_PLUGIN_PATH specifies the path to the
                    directory where you installed the platform plugin.
                \li For the \l {EGLFS} platform, \c QT_QPA_EGLFS_PHYSICAL_WIDTH
                    and \c QT_QPA_EGLFS_PHYSICAL_HEIGHT specify the screen width
                    and height in millimeters.
                \li \l{QML Import Path}{QML2_IMPORT_PATH} specifies the path to
                    the directory where you installed QML modules.
            \endlist
        \li Launch \c gdbserver on the device.
    \endlist

    \section1 Start remote debugging

    Press \key F5 to start the remote debugging session.

    \section1 Set up debugging on Linux devices

    To debug Qt Quick applications on Linux devices:

    \list 1
        \li Enable QML debugging for the project.
        \li Go to \uicontrol Project > \uicontrol Properties >
            \uicontrol {Configuration Properties} > \uicontrol Debugging
            to set up program arguments for starting a QML debugging session.
        \li In \uicontrol {Debugger to launch}, select \uicontrol {GDB Debugger}.
        \li In \uicontrol {Additional Debugger Commands}, add the following
            command:

            \badcode
            -qmljsdebugger=port:<port>,host:<IP_address>,block
            \endcode
    \endlist

    \sa  {Tutorial: Qt Quick debugging}, {Cross-compile}, {Debug applications},
    {Enable QML debugging}, {Debugging Qt Quick applications}
*/

/*!
    \page qtvstools-tutorial-qt-test-project.html
    \ingroup qtvstools-tutorials

    \title Tutorial: Qt Test application

    This tutorial describes how to use Qt VS Tools with the Unit Test Explorer
    provided by Microsoft to visualize and run unit test cases. Write the test
    cases with the \l{Qt Test Overview}{Qt Test} framework.

    \section1 Before you start

    Before you start, you have to:

    \list
        \li \l {Install Qt VS Tools}
        \li \l {Add Qt versions}
    \endlist

    \section1 Create a Qt Test application

    \list 1
        \li Go to \uicontrol File > \uicontrol New > \uicontrol Project.
        \li Search for \uicontrol {Qt Test Application}.
        \li Select the project wizard, and then select \uicontrol Next.
        \li In \uicontrol {Project name}, enter \e QtTest,
            and then select \uicontrol OK.
        \li To acknowledge the \uicontrol Welcome dialog, select
            \uicontrol Next.
        \li Set up the \uicontrol Debug build configuration and select the
            modules to include in the project:
            \image {qtvstools-wizard-test.webp} {Selecting Qt modules in Qt Test Application Wizard}
            The modules that are typically needed in test application projects
            are selected by default.
        \li Select \uicontrol Next to continue to the class creation page:
            \image {qtvstools-wizard-test-finish.webp} {Creating a class in Qt Test Application Wizard}
        \li Select \uicontrol {Lower case filenames} to
            only use lower case characters in the names of the generated files.
        \li Select \uicontrol {Add .runsettings file to project} to
            use a default .runsettings file for the application. To use a
            solution-wide .runsettings file, add a \c QtTest run configuration
            section, as instructed in \l{Test Adapter settings}.
        \li Select \uicontrol Finish to create the project.
    \endlist

    You now have a small working Qt Test application. Go to \uicontrol Test >
    \uicontrol {Test Explorer} (or press \key {Ctrl+E, T}) to open the Visual
    Studio Unit Test Explorer.

    \section1 Write your test cases

    Use functions and macros of the Qt Testing framework to define tests.
    The created test application provides a set of common functions,
    as well as one test function.

    \code

#include <QtTest>

class QtTest : public QObject
{
    Q_OBJECT

private slots:

    void initTestCase_data()
    {
        qDebug("Creates a global test data table.");
    }

    void initTestCase()
    {
        qDebug("Called before the first test function is executed.");
    }

    void init()
    {
        qDebug("Called before each test function is executed.");
    }

    void myTest()
    {
        QVERIFY(true); // check that a condition is satisfied
        QCOMPARE(1, 1); // compare two values
    }

    void cleanup()
    {
        qDebug("Called after every test function.");
    }

    void cleanupTestCase()
    {
        qDebug("Called after the last test function was executed.");
    }
};

QTEST_MAIN(QtTest)
#include "QtTest.moc"

    \endcode

    \section1 Discover tests with Unit Test Explorer

    Now that you have test application project with test functions, use the
    Unit Test Explorer to discover and manage the test functions.

    To build the solution, go to \uicontrol Build > \uicontrol {Build Solution}
    (or press \key Ctrl+Shift+B). This step is crucial as it compiles the test
    binaries that the Unit Test Explorer discovers.

    The Unit Test Explorer automatically discovers tests after a successful
    build. If the tests do not appear, select \uicontrol {Run All} or
    \uicontrol Refresh on the Test Explorer toolbar to manually trigger test
    discovery.

    \image {ute.webp} {Unit Test Explorer}

    \section1 Run and analyze tests with Unit Test Explorer

    In the Unit Test Explorer, select \uicontrol {Run All} to run all tests.
    To run specific tests or test groups, select them from the list and select
    \uicontrol {Run Selected Tests}. Right-click on individual tests or test
    groups for more options, such as debugging specific tests.

    The Unit Test Explorer displays the results of your tests, showing which
    tests passed or failed. For failed tests, select the test name to see
    detailed information, including error messages and stack traces. Use the
    filtering and grouping options in the Test Explorer to organize and manage
    your test results effectively.

    \image {ute-finish.webp} {Test results in Unit Test Explorer}

    Usually, Qt tests require a project-local or solution-wide.runsettings file
    for configuring various testing parameters and environments.

    \sa {Configure Qt tests using a .runsettings file}
*/

/*!
    \page qtvstools-configure-runsettings.html
    \ingroup qtvstools-how-to

    \title Configure Qt tests using a .runsettings file

    Visual Studio uses XML-based .runsettings files to define and customize the
    behavior of unit tests. The files control the discovery, execution, and
    reporting of tests.

    To specify global settings for the entire solution, go to \uicontrol Tools >
    \uicontrol Options > \uicontrol Qt > \uicontrol {Test Adapter}.

    \image {ute-settings.webp} {Test Adapter in Qt Options}

    If there is no project-specific or solution-wide .runsettings file, the
    values of global settings are used as default values.

    The values from a project-specific or solution-wide .runsettings file
    override the global settings. The settings are merged to customize test
    behavior.

    \sa {Test Adapter settings}
*/

/*!
    \page qtvstools-reference-runsettings.html
    \ingroup qtvstools-reference

    \title Test Adapter settings

    A .runsettings file is structured as an XML document. The root element,
    \c <RunSettings>, has settings specific to your testing framework. The
    \c <QtTest> element has settings for Qt unit tests.

    For more information about using .runsettings files in Visual Studio, see
    \l{Configure unit tests by using a .runsettings file}.

    \section1 Mandatory element

    You must set the Qt version in the \c <QtTest> element.

    \table
    \header
        \li Name
        \li Description
        \li Example
    \row
        \li QtInstall
        \li Specifies the Qt version used to build and run the
                tests.
        \li \c {<QtInstall>$(DefaultQtVersion)</QtInstall>}
    \endtable

    \section2 Minimum runsettings example

    \badcode
        <RunSettings>
            <QtTest>
                <QtInstall>$(DefaultQtVersion)</QtInstall> <!-- Mandatory -->
            </QtTest>
        </RunSettings>
    \endcode


    \section1 Optional elements

    The following table lists optional elements in the \c <QtTest> element.

    \table
    \header
        \li Name
        \li Description
        \li Occurrence
        \li Default value
        \li Example

    \row
        \li EnabledAdapter
        \li Enables or disables the Qt test adapter.
        \li Once
        \li \c true
        \li \c {<EnabledAdapter>true</EnabledAdapter>}
    \row
        \li ShowAdapterOutput
        \li Shows output from the test adapter in \uicontrol Output >
            \uicontrol Tests.
        \li Once
        \li \c false
        \li \c {<ShowAdapterOutput>false</ShowAdapterOutput>}
    \row
        \li TestTimeout
        \li Sets a timeout for individual tests in milliseconds.
            A value of -1 means no timeout.
        \li Once
        \li -1
        \li \c {<TestTimeout>-1</TestTimeout>}
    \row
        \li DiscoveryTimeout
        \li Sets a timeout for test discovery in milliseconds.
            A value of -1 means no timeout.
        \li Once
        \li 2000
        \li \c {<DiscoveryTimeout>2000</DiscoveryTimeout>}
    \row
        \li ParsePdbFiles
        \li Parses PDB files to retrieve the source file and line number of test
            functions.
        \li Once
        \li \c true
        \li \c {<ParsePdbFiles>true</ParsePdbFiles>}
    \row
        \li SubsystemConsoleOnly
        \li Scans only console binaries for Qt test functions.
        \li Once
        \li \c true
        \li \c {<SubsystemConsoleOnly>true</SubsystemConsoleOnly>}
    \endtable

    \section2 Output section

    Control the location and format of the logs generated during test runs.

    \table
    \header
        \li Name
        \li Description
        \li Occurrence
        \li Example
    \row
        \li FilenameFormat
        \li Defines how and where the test results are written. Supported output
            formats are: txt, csv, junitxml, xml, lightxml, teamcity, and tap.
        \li Multiple
        \li \c {<FilenameFormat>PATH,OUTPUTFORMAT</FilenameFormat>}
    \endtable

    \section2 Verbosity section

    Influence the amount of detail in the logs generated during test runs.

    \table
    \header
        \li Name
        \li Description
        \li Occurrence
        \li Default value
        \li Example
    \row
        \li Level
        \li The amount of detail reported in test logs.
        \li Once
        \li empty
        \li \c {<Level>silent</Level>} for minimal output.
    \row
        \li LogSignals
        \li Logs all emitted signals and the slot invocations resulting from
            those signals.
        \li Once
        \li \c false
        \li \c {<LogSignals>false</LogSignals>}
    \endtable

    \section2 Commands section

    Influence how tests are run and control the test execution environment.

    \table
    \header
        \li Name
        \li Description
        \li Occurrence
        \li Default value
        \li Example
    \row
        \li EventDelay
        \li Control delays in event simulations.
        \li Once
        \li -1
        \li \c {<EventDelay>-1</EventDelay>}
    \row
        \li KeyDelay
        \li Control delays in event simulations.
        \li Once
        \li -1
        \li \c {<KeyDelay>-1</KeyDelay>}
    \row
        \li MouseDelay
        \li Control delays in event simulations.
        \li Once
        \li -1
        \li \c {<MouseDelay>-1</MouseDelay>}
    \row
        \li MaxWarnings
        \li The maximum number of warnings to output.
        \li Once
        \li 2000
        \li \c { <MaxWarnings>2000</MaxWarnings>}
    \row
        \li NoCrashHandler
        \li Enables or disables the Windows Error Reporting dialog.
        \li Once
        \li \c false
        \li \c {<NoCrashHandler>false</NoCrashHandler>}
    \endtable

    \section1 Example .runsettings file

    The following XML shows the contents of a default Qt .runsettings file. The
    \c {<QtInstall>} is mandatory, all other elements or sections are optional
    because the Qt test adapter provides default values.

    \quotefile ../../Templates/runsettings/.runsettings

    \sa {Tutorial: Qt Test application},
    {Configure Qt tests using a .runsettings file}, {Files}
*/

/*!
    \page qtvstools-how-to-hide-output.html
    \ingroup qtvstools-how-to

    \title Hide output

    Qt VS Tools shows messages in the \uicontrol Output pane when you start it
    and build applications, for example.

    \image {qtvstools-output.webp} {Qt VS Tools messages in the Output pane}

    To stop the Qt VS Tools output from being activated and hiding the output
    from Visual Studio:

    \list 1
        \li Go to \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol Options > \uicontrol Qt > \uicontrol General >
            \uicontrol {Notifications}.
            \image {qtvstools-options-qt-general-notifications.webp} {Notifications in Qt General Options}
        \li In \uicontrol {Auto activate console pane}, select \uicontrol Disable.
    \endlist
*/

/*!
    \page qtvstools-how-to-profile-qt-quick-apps.html
    \ingroup qtvstools-how-to

    \title Profile Qt Quick applications

    You can use the QML Profiler integrated into \QC to profile a Qt Quick
    application that you run from Visual Studio. With QML Profiler, you
    can find causes for typical performance problems in your applications,
    such as slowness and unresponsive, stuttering user interfaces.

    One typical cause for such performance problems is executing too much
    JavaScript in too few frames. All JavaScript must return before the GUI
    thread can proceed, and frames are delayed or dropped if the GUI thread
    is not ready. Another typical cause is creating or updating invisible
    items, which takes time in the GUI thread.

    To profile Qt Quick applications:

    \list 1
        \li In Visual Studio, open a Qt Quick application project.
        \li In \uicontrol {Solution Explorer}, right-click the project and
            select \uicontrol Properties in the context menu.
        \li Select \uicontrol {Configuration Properties} >
            \uicontrol {Qt Project Settings}.
        \li In \uicontrol {Enable QML Debugging}, select \uicontrol {Yes}.
            \image {qtvstools-quick-addressbook-enable-qml-debugging.webp} {Enabling QML debugging for a project}
        \li Select \uicontrol {Debugging}.
        \li In \uicontrol {Command arguments}, enter:
            \c {-qmljsdebugger=port:<number>,block}
            \image {qtvstools-options-qml-profiling.webp} {Setting command line arguments for profiling}
            For more information, see \l {Qt Quick: Starting Applications}.
            \note The command arguments conflict with the ones set in
            \uicontrol {Environment} by default, so debugging won't work until
            you remove them.
        \li Select \uicontrol {OK}.
        \li Go to \uicontrol Build, and then select \uicontrol {Build Solution}
            to build the application.
        \li Go to \uicontrol Debug, and then select
            \uicontrol {Start without Debugging} (or press \key {Ctrl+F5})
            to run the application.
        \li In \QC, go to \uicontrol {Analyze}, and then select
            \uicontrol {QML Profiler (Attach to Waiting Application)}.
            \image {qtcreator-start-qml-profiler.webp} {Qt Creator Start QML Profiler dialog}
        \li In \uicontrol {Port}, set the same port number as in the command
            arguments.
        \li Select \uicontrol {OK} to start profiling.
        \li If profiling does not start immediately in \uicontrol {QML Profiler},
            select \uicontrol {Enable Profiling} to start collecting data.
    \endlist

    \sa {Enable QML debugging}, {\QC: Profile QML applications},
    {\QC: Profiling QML applications}
*/