path: root/doc/src/qtvstools.qdoc

/****************************************************************************
**
** Copyright (C) 2022 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page index.html
    \nextpage Getting Started
    \title Qt VS Tools Manual

    Qt VS Tools integrate the Qt development tools into Microsoft Visual Studio
    2017, and later. This enables developers to use the standard Windows
    development environment without having to worry about Qt-related build steps
    or tools. You can install and update Qt VS Tools directly from Microsoft
    Visual Studio.

    \table
        \row
            \li {4,1} \b {\l{All Topics}}
        \row
            \li \inlineimage front-gs.png
            \li \inlineimage front-advanced.png
            \li \inlineimage front-projects.png
        \row
            \li \b {\l{Getting Started}}
                \list
                    \li \l {Tutorial: Qt Widgets Application}
                    \li \l {Tutorial: Qt Quick Application}
                \endlist
            \li \b {\l {Configuring Builds}}
                \list
                    \li \l {Managing Qt Versions}
                    \li \l {Building}
                    \li \l {Cross-Compiling}
                    \li \l {Importing and Exporting Projects}
                \endlist
            \li \b {\l {Managing Projects}}
                \list
                    \li \l {Creating Projects}
                    \li \l {Creating Files}
                \endlist
        \row
            \li \inlineimage front-coding.png
            \li \inlineimage front-preview.png
            \li \inlineimage front-help.png
        \row
        \li \b {\l {Updating IntelliSense Info}}
        \li \b {\l {Debugging}}
            \list
                \li \l {Debugging Qt Quick Applications}
                \li \l {Debugging on Linux}
            \endlist
        \li \b {\l {Getting Help}}
    \endtable
*/

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

    \list
        \li \l {Getting Started}
            \list
                \li \l {Tutorial: Qt Widgets Application}
                \li \l {Tutorial: Qt Quick Application}
            \endlist
        \li \l {Configuring Builds}
            \list
                \li \l {Managing Qt Versions}
                \li \l {Building}
                \li \l {Cross-Compiling}
                \li \l {Importing and Exporting Projects}
            \endlist
        \li \l {Managing Projects}
            \list
                \li \l {Creating Projects}
                \li \l {Creating Files}
                    \list
                        \li \l {Adding Form Files}
                        \li \l {Managing Resources}
                        \li \l {Creating Qt Translation Files}
                    \endlist
            \endlist
        \li \l {Updating IntelliSense Info}
        \li \l {Debugging}
            \list
                \li \l {Debugging Qt Quick Applications}
                \li \l {Debugging on Linux}
            \endlist
        \li \l {Getting Help}
    \endlist
*/

/*!
    \page qtvstools-getting-started.html
    \previouspage Qt VS Tools Manual
    \nextpage Tutorial: Qt Widgets Application
    \title Getting Started

    The main features of Qt VS Tools are:

    \list
        \li Wizards for creating new Qt and Qt Quick projects and files.
        \li Automated build setup for the \l {Using the Meta-Object Compiler
            (moc)}{Meta-Object Compiler (moc)}, \l {User Interface Compiler
            (uic)}, and \l {Resource Compiler (rcc)}.
        \li Import and export of Qt project files (\c .pro) and project include
            files (\c .pri).
        \li Automated conversion of a Qt VS Tools project to a \l {qmake Manual}
            {qmake} project, or the other way around.
        \li Integrated Qt resource management.
        \li Creating a Qt translation source (TS) file and starting Qt Linguist
            to translate the strings.
        \li Starting Qt Designer to design widget-based UIs for applications.
        \li Integrated Qt documentation.
        \li Debugging extensions for Qt data types.
    \endlist

    \section1 Install Qt VS Tools

    In Microsoft Visual Studio, select \uicontrol Extensions >
    \uicontrol {Manage Extensions} > \uicontrol Online,
    and search for \uicontrol {Qt Visual Studio Tools}
    to install or update Qt VS Tools.

    \section1 Add a Qt Version

    To create a Qt VS Tools project, you must add at least one
    \l{Managing Qt Versions}{Qt version}.

    \section1 Create a Project

    Follow the tutorials to create your first applications:

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

    For all the options you have, see \l {Creating Projects}.
*/

/*!
    \page qtvstools-qt-widgets-application.html
    \previouspage Getting Started
    \nextpage Tutorial: Qt Quick Application
    \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. In addition, you will learn how to convert a
    Microsoft Visual Studio project file into a qmake compatible \c .pro file.

    You can use Qt VS Tools to develop also \l{Qt Quick} applications.

    \section1 Before You Start

    Before you start, you have to:

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

    \section1 Create a Qt Widgets Application Project

    To create a Qt Widgets application project in Visual Studio:

    \list 1
        \li Select \uicontrol File > \uicontrol New > \uicontrol Project, and
            search for \uicontrol {Qt Widgets Application}.
        \li Select the project wizard, and then select \uicontrol Next.
        \li In the \uicontrol {Project name} field, 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.png "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 Next to continue to the class creation page:
            \image qtvstools-widgets-app-class.png "Creating a class in Qt Widgets Application Wizard"
        \li In the \uicontrol {Base class} field, enter \uicontrol QWidget as
            the base class type.
        \li Select the \uicontrol {Lower case filenames} check box to
            only use lower case characters in the names of the generated files.
        \li Select the \uicontrol {Precompiled header} check box to use a
            precompiled header file.
        \li Select the \uicontrol {Add default application icon} check box 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. Select \uicontrol Build >
    \uicontrol {Build Solution} to build it, and then select \uicontrol Debug >
    \uicontrol {Start Debugging} to run it. For now, the result is an empty
    window.

    \section1 Design the Main Window

    You can use \QD to design the application's main window, which contains
    some widgets placed in layouts:

    \image qtvstools-addressbook-mainwindow.png AddressBook's main dialog

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

    To run \QD in a separate window by default, select \uicontrol Extensions >
    \uicontrol {Qt VS Tools} > \uicontrol Options > \uicontrol {\QD}, and set
    \uicontrol {Run in detached window} to \uicontrol True.

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

    \section2 Add Widgets

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

    \list 1
        \li In Visual Studio's Solution Explorer, double-click the
            \c addressbook.ui file to open it in \QD.
        \li In \QD's \uicontrol Widgetbox, select \uicontrol {List Widget} and
            drag and drop 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 and drop 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 and drop 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 approximately as they appear in the screenshot above.
    In order to properly position the widgets and to ensure that they are
    resized correctly 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 wigdets 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 Select \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, you can 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 connected to the \uicontrol Add
    button.

    You can use a Qt file wizard in Visual Studio to create a UI form that
    contains the \uicontrol OK and \uicontrol Cancel buttons connected to the
    QDialog::accept() and QDialog::reject() slots, respectively. You can 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, select \uicontrol Project >
            \uicontrol {Add Qt Class} > \uicontrol Installed >
            \uicontrol {Visual C++} > \uicontrol Qt >
            \uicontrol {Qt Widgets Class}.
        \li To acknowledge the \uicontrol Welcome dialog, select
            \uicontrol Next.
        \li In the \uicontrol Name field, enter \e AddDialog.
            \image qtvstools-qt-widget-class-wizard.png "Creating a class in Qt Widgets Class Wizard"
        \li In the \uicontrol {Base class} field, enter \uicontrol QDialog as
            the base class type.
        \li Select the \uicontrol {Multiple inheritance} radio button.
        \li Select the \uicontrol {Lower case filenames} check box 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 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 select \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 Select \uicontrol Form > \uicontrol Preview to preview your form
            without compiling it.
        \li Select \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 {Qt Designer'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 are created using \QD call QMetaObject::connectSlotsByName() to
    establish connections between signals emitted by the form's child widgets
    and slots that follow the naming convention \c {on_<sender>_<signal>()}.
    For the application to react appropriately when the \uicontrol Add button is
    clicked, 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, modify 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 contains the specified information is created.

    \section1 Display the Selected Item

    When the user selects an item in the list widget, the \c nameLabel and
    \c emailLabel at the bottom of the form should be updated. This behavior
    requires another slot to be added 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 /^\}/

    Thanks to the naming convention, this slot will automatically be connected
    to the QListWidget::currentItemChanged() signal of \c{addressList} and
    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.

    \section1 Create Qt Project Files

    To build the application on other platforms, you need to create a \c .pro
    file for the project.

    To let Qt VS Tools create a basic \c .pro file for you:

    \list 1
        \li Select \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol {Create Basic .pro File}.
        \li In the \uicontrol {Export Project} dialog, make sure that the
            \uicontrol {Create .pri file} check box is selected, and then select
            \uicontrol OK.
        \li Select \uicontrol Save to use the default location and name for
            saving the \c .pri file.
    \endlist

    For more information about \c .pro files and their associated \c .pri files,
    see \l {Creating Projects}.

    You should now have a working \c .pro file and \c .pri file for your
    project. For more complex projects, manually editing the \c .pro file
    is required to make it work on all platforms. However, for the example
    project, the generated \c .pro file is sufficient.
*/

/*!
    \page qtvstools-qt-quick-application.html
    \previouspage Tutorial: Qt Widgets Application
    \nextpage Configuring Builds
    \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.

    You can use Qt VS Tools to develop also \l{Qt Widgets} applications.

    \section1 Before You Start

    Before you start, you have to:

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

    \section1 Create a Qt Quick Application Project

    To create a Qt Quick application project in Visual Studio:

    \list 1
        \li Select \uicontrol File > \uicontrol New > \uicontrol Project, and
            search for \uicontrol {Qt Quick Application}.
        \li Select the project wizard, and then select \uicontrol Next.
        \li In the \uicontrol {Project name} field, 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 {Quick Modules}, and select the \uicontrol {Quick} and
            \uicontrol {Quick Controls2} modules to include in the project:
            \image qtvstools-qtquick-app-modules.png "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. Select \uicontrol Build >
    \uicontrol {Build Solution} to build it, and then select \uicontrol Debug >
    \uicontrol {Start Debugging} 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. You can modify 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 determine that address
    book entries are appended 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 is used to create a large number of 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. A repeater is
    usually enclosed in an instance of a positioner type such as a
    \l ColumnLayout to visually position the multiple delegate items created
    by the repeater.

    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 specify that an address book entry
    is removed from the list when the users click the \uicontrol Remove button
    for an address book entry.

    \printuntil }

    \section1 Add a Popup

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

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

    You can 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, select \uicontrol Project >
    \uicontrol {Add New Item} > \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 Select \uicontrol Project > \uicontrol {Add New File} >
            \uicontrol Qt > \uicontrol {Qt QML File} > \uicontrol Add.
        \li In the \uicontrol Name field, 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 can be opened within 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 determine 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

    Address book entries are presented in the main window as specified by a
    custom \c AddressBookItem type.

    Select \uicontrol Project > \uicontrol {Add New File} > \uicontrol Qt >
    \uicontrol {Qt QML File} > \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.

    \section1 Create Project Files

    To build the application on other platforms, you need to create a \c .pro
    file for the project, as instructed in \l{Create Qt Project Files}.

*/

/*!
    \page qtvstools-managing-projects.html
    \previouspage Importing and Exporting Projects
    \nextpage Creating Projects
    \title Managing Projects

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

    You can use the integrated Qt Resource editor to manage the resources in
    Qt projects.

    In addition, you can create a Qt translation source (TS) file and start
    \QL from Visual Studio to translate the strings in your application.

    \list
        \li \l {Creating Projects}
        \li \l {Creating Files}
    \endlist
*/

/*!
    \page qtvstools-creating-projects.html
    \previouspage Managing Projects
    \nextpage Creating Files
    \title Creating Projects

    Once you have installed Qt VS Tools, you can search for and then select
    the following project templates in Visual Studio in \uicontrol File >
    \uicontrol New \uicontrol Project:

    \list
        \li \uicontrol {Qt ActiveQt Server} creates a simple ActiveX server.
        \li \uicontrol {Qt Class Library} creates a basic Qt-based dynamic
            library.
        \li \uicontrol {Qt Console Application} creates a basic Qt console
            application.
        \li \uicontrol {Qt Designer Custom Widget} creates a \QD custom widget
            plugin.
        \li \uicontrol {Qt Empty Application} creates a an empty Qt application
            project.
        \li \uicontrol {Qt Quick Application} creates a Qt Quick application
            project.
        \li \uicontrol {Qt Widgets Application} creates a simple Qt widgets
            application with one form.
    \endlist

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

    To start writing Qt code and building your projects, you must tell Visual
    Studio where to find the \l{Managing 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}
    \endlist
*/

/*!
    \page qtvstools-creating-files.html
    \previouspage Creating Projects
    \nextpage Adding Form Files
    \title Creating Files

    You can use file templates to add the following types of files to projects
    by selecting \uicontrol Project > \uicontrol {Add New Item} >
    \uicontrol Installed > \uicontrol {Visual C++} > \uicontrol Qt:

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

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

    \list
        \li \l {Adding Form Files}
        \li \l {Managing Resources}
        \li \l {Creating 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
*/

/*!
    \page qtvstools-configuring-builds.html
    \previouspage Tutorial: Qt Quick Application
    \nextpage Managing Qt Versions
    \title Configuring Builds

    In Visual Studio, C++ projects are built using the Project System,
    where MSBuild provides the project file format and build framework.
    Qt VS Tools make use of the extensibility of MSBuild to provide
    design-time and build-time integration of Qt in Visual Studio projects.

    Qt uses \c .pro files with \l {qmake Manual}{qmake} to build projects,
    whereas Visual Studio uses \c .vcproj files. Qt VS Tools enables you to
    import Qt project files into Visual Studio and export them back into
    Qt build files. In addition, you can convert Qt VS Tools projects into
    a qmake project, or the other way around.

    \list
        \li \l {Managing Qt Versions}
        \li \l {Building}
        \li \l {Cross-Compiling}
        \li \l {Importing and Exporting Projects}
   \endlist

    \section1 MSBuild Configurations

    At very general level, MSBuild might be described as follows:

    \list
        \li An MSBuild project consists of references to source files and
            descriptions of actions to take in order to process 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-diagram.png "Diagram showing Visual Studio Project and MSBuild"

    \section2 Properties

    Properties may apply to the project itself or to a specific file in the
    project, and can be defined 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 applied to source files can be defined globally, in
            which case the same value will apply to all files. For example,
            the default compiler warning level could be defined globally at
            level 3.
        \li Such a global, file-scope definition may be overridden for a
            specific file by a locally defined property with the same name.
            For example, one of the source files needs to be compiled 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 Visual Studio Tools integrate with the MSBuild project system by
    providing a set of Qt-specific targets that describe how to process
    files such as moc headers by using the appropriate Qt tools.

    \image qtvstools-qt-project-settings.png "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 generated by
            Qt tools in project settings
        \li You can share Qt settings within a team or organization by
            exporting and importing them to and from shared \e {property sheet}
            files (\c .props).
    \endlist
*/

/*!
    \page qtvstools-managing-qt-versions.html
    \previouspage Configuring Builds
    \nextpage Building
    \title Managing Qt Versions

    Qt VS Tools provide you with basic Qt version management that enables you to
    use multiple Qt versions in parallel. For example, Qt 5.15.4 and 6.2.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.png Qt Versions

    To manage Qt versions:

    \list 1
        \li Select \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol {Qt Versions} > \inlineimage qtvstools-plus.png
            .
        \li In the \uicontrol Version field, enter a name for the Qt version.
            If you add the path to Qt first, this field is filled automatically.
        \li In the \uicontrol Host field, select \uicontrol Windows, unless you
            want to cross-compile the application for an embedded Linux device.
        \li In the \uicontrol Path field, enter the path to the qmake.exe for
            the Qt version.
            For example: \c {C:\Qt\6.2.0\msvc2019_64\bin\qmake.exe}.
        \li In the \uicontrol Default field, select the Qt version to be used
            by default when creating new projects or importing a project from a
            \c {.pro} file.
        \li Select \uicontrol OK.
    \endlist

    To remove a Qt version, select \inlineimage qtvstools-minus.png
    .

    To specify Qt versions for a project, right-click the project in Solution
    Explorer and select \uicontrol Properties in the context menu. Select
    \uicontrol {Qt Project Settings}, and set the Qt version as the value of
    the \uicontrol {Qt Installation} option.
*/

/*!
    \page qtvstools-building.html
    \previouspage Managing Qt Versions
    \nextpage Cross-Compiling
    \title Building

    Qt Visual Studio 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 generated by the Qt tools are added to the C++
    compilation during the build process, so that generated files do not
    need to be included 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 Select \uicontrol Properties in the context menu of the project.
        \li Select \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol {Qt Project Settings}.
    \endlist

    \image qtvstools-qt-project-settings.png "Qt Project Settings"

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

    \section1 Project File Format

    When importing .pro files, \e {custom build steps} are automatically
    converted into Qt/MSBuild steps. To convert custom build steps into
    Qt/MSBuild steps for a solution, select \uicontrol Qt >
    \uicontrol {Convert custom build steps to Qt/MSBuild} in the context
    menu of the solution.

    The Qt/MSBuild project format has changed between Qt VS Tools versions, and
    therefore you might have to manually update project files of imported
    projects. 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, select \uicontrol Extensions >
    \uicontrol {Qt VS Tools} > \uicontrol Options > \uicontrol {Qt/MSBuild}.
    This corresponds to setting the value of the \c QTMSBUILDS environment
    variable.
*/

/*!
    \page qtvstools-cross-compiling.html
    \previouspage Building
    \nextpage Importing and Exporting Projects
    \title Cross-Compiling

    Qt VS Tools supports 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.

    To develop Qt applications for Linux using Visual Studio:

    \list
        \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 Alternatively, create a connection to a remote Linux build server.
        \li Register the cross-compiled Qt build that resides in a WSL instance
            or the remote build server.
    \endlist

    To add a Qt version for cross-compilation:

    \list 1
        \li Select \uicontrol Extensions > \uicontrol {Qt VS Tools} >
            \uicontrol {Qt Versions} > \inlineimage qtvstools-plus.png
            to add a new Qt version.
        \li In the \uicontrol Version field, enter a name for the Qt version.
            If you add the path to Qt first, this field is filled automatically.
        \li In \uicontrol Host, select \uicontrol {Linux WSL} or
            \uicontrol {Linux SSH}.
        \li In the \uicontrol Path field, enter the path to the Qt installation.
        \li In the \uicontrol Compiler field, enter the cross-compiler to use.
            The default value is g++.
    \endlist

    \section1 Compiling 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 incorrect 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.
*/

/*!
    \page qtvstools-importing-and-exporting-projects.html
    \previouspage Cross-Compiling
    \nextpage Managing Projects
    \title Importing and Exporting Projects

    Qt and Visual Studio use different file formats to save projects. If you
    build your application on multiple platforms, you probably already use
    Qt \c .pro files with \l {qmake Manual}{qmake}. Otherwise, you might use
    \c .vcproj files and Visual Studio to build your project, which is usually
    more convenient for Windows-only development.

    Qt VS Tools provide a way to combine both approaches so that you do not have
    to manually maintain \c .pro files and \c .vcproj files in parallel. You
    start by creating a \c .vcproj file, as usual. When you need a qmake
    \c .pro file for storing Linux and macOS specific settings, select
    \uicontrol Extensions > \uicontrol {Qt VS Tools} >
    \uicontrol {Create Basic .pro File}.

    \image qtvstools-export-project.png Export Projects dialog

    If you have multiple Qt projects in one Visual Studio solution, the basic
    \c .pro file generator can create a master \c .pro file of type \c subdirs
    that includes all of the projects.

    The generated \c .pro file is not meant to be a complete file, but a simple
    starting point for porting to other platforms. However, these files
    should be sufficient for compiling the skeleton projects created by the
    predefined Qt project wizards. The \c .pro file includes a \c .pri file.

    The \c .pri file contains the list of source files, header files, \c .ui
    files, and \c .qrc files in the project. To generate the \c .pri file,
    select \uicontrol Extensions > \uicontrol {Qt VS Tools} >
    \uicontrol {Export Project to .pri File}.
    When you add or remove a file from the Visual Studio project file, you must
    regenerate the \c .pri file to ensure that the application can still be
    built on other platforms.

    Also, make sure that the \c .pri file included in the \c .pro file points to
    the correct file. If you saved the \c .pri file using the suggested path and
    name, this reference should be correct.

    Developers on platforms other than Windows might add or remove files to the
    project by editing the \c .pri file. When this happens, Windows developers
    must select \uicontrol Extensions > \uicontrol {Qt VS Tools} >
    \uicontrol {Import .pri File to Project} to synchronize the Visual Studio
    project file with the \c .pri file.

    If your project contains platform-specific source files, you should list
    them in the \c .pro file so that they are not overwritten by Qt VS Tools.

    To summarize, a cross-platform Qt project consists of the following files:

    \list
        \li A \c .vcproj file containing Windows-specific settings and listing
            the files in the project.
        \li A \c .pro file containing Linux and macOS specific settings.
        \li A \c .pri file (a \c qmake include file) listing the files in the
            project.
    \endlist

    If you already have a \c .pro file but no \c .vcproj file, select
    \uicontrol Extensions > \uicontrol {Qt VS Tools} >
    \uicontrol {Open Qt Project File (.pro)} to
    convert your \c .pro file to a \c .vcproj file. The generated \c .vcproj
    only contains Windows-specific settings. Also, there is no other way to
    convert a \c .vcproj file back to the \c .pro file format than using the
    \uicontrol {Create Basic .pro File} function.
*/

/*!
    \page qtvstools-form-files.html
    \previouspage Creating Files
    \nextpage Managing Resources
    \title Adding Form Files

    You can start \QD from Qt VS Tools by double-clicking a \c .ui file. For
    more information about using \QD, see the \l{Qt Designer Manual}.

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

    \image qtvstools-qt-widget-class-wizard.png

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

/*!
    \page qtvstools-managing-resources.html
    \previouspage Adding Form Files
    \nextpage Creating Qt Translation Files
    \title Managing Resources

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

    \image qtvstools-qrc-editor.png Qt Resource Editor dialog

    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,
    select \uicontrol Extensions > \uicontrol {Qt VS Tools} >
    \uicontrol Options > \uicontrol {Qt Resource Editor}, and
    set \uicontrol {Run in detached window} to \uicontrol True.

    To add new resources:

    \list 1
        \li Select \uicontrol Project > \uicontrol {Add New Item} >
            \uicontrol Installed > \uicontrol {Visual C++} > \uicontrol Qt >
            \uicontrol {Qt Resource File}.
        \li In the \uicontrol Name field, enter a name for the resource file.
        \li In the \uicontrol Location field, 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}.
        \li To add resources to the file, select \uicontrol Add >
            \uicontrol {Add Files}.
        \li In the \uicontrol Prefix field, 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}.

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

    For more information, see \l{The Qt Resource System}.
*/

/*!
    \page qtvstools-translation-files.html
    \previouspage Managing Resources
    \nextpage Updating IntelliSense Info
    \title Creating Qt Translation Files

    To add a new translation file to the project:

    \image qtvstools-qt-translation-file-wizard.png

    \list 1
        \li Select \uicontrol Project > \uicontrol {Add New Item} > \uicontrol Installed >
            \uicontrol {Visual C++} > \uicontrol Qt > \uicontrol {Qt Translation File}.
        \li In \uicontrol {Select a Language}, you can choose a language from the list
            of supported languages. You can use \uicontrol Search to filter for a specific
            language.
        \li In the \uicontrol {Save as} field, enter a filename for the translation file.
        \li Select \uicontrol Finish to create the file and have it listed in
            \uicontrol {Translation Files} in Visual Studio's Solution Explorer.
        \li Right-click a translation file to open a context menu with options
            for running \c lupdate and \c lrelease.
    \endlist

    To start \QL, select \uicontrol Extensions > \uicontrol {Qt VS Tools} >
    \uicontrol {Launch Qt Linguist} or double-click a \c .ts file in the
    Solution Explorer.

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

    To run \QL in a separate window by default, select \uicontrol Extensions >
    \uicontrol {Qt VS Tools} > \uicontrol Options > \uicontrol {\QL}, and set
    \uicontrol {Run in detached window} to \uicontrol True.

    For more information about Qt's translation tools, see the
    \l {Qt Linguist Manual}.
*/

/*!
    \page qtvstools-getting-help.html
    \previouspage Debugging on Linux
    \title Getting Help

    By default, Qt VS Tools tries 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, you can turn off this feature and use the
    default shortcut \key {Alt+F1}. Select \uicontrol Extensions >
    \uicontrol {Qt VS Tools} > \uicontrol Options > \uicontrol Help, and set
    \uicontrol {Try Qt documentation when F1 is pressed} to \uicontrol False

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

    To set up another keyboard shortcut for Qt online help:

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

/*!
    \page qtvstools-intellisense-info.html
    \previouspage Creating Qt Translation Files
    \nextpage Debugging
    \title Updating 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 are run in the background when source files change. If this
    creates too much overhead for large solutions, you can disable the
    \uicontrol {Run Qt tools in background build} option to only run
    qmake and update a minimal set of Qt build properties.

    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 selecting \uicontrol {Rescan Solution} in the context menu of
    the project.

    To set options for updating IntelliSense info, select \uicontrol Extensions
    > \uicontrol {Qt VS Tools} > \uicontrol Options > \uicontrol IntelliSense:

    \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} determines the amount
            of info recorded in the background build log.
    \endlist
*/

/*!
    \page qtvstools-debugging.html
    \previouspage Updating IntelliSense Info
    \nextpage Debugging Qt Quick Applications
    \title Debugging

    Visual Studio supports debugging Qt C++ applications using the Visual Studio
    debugger and Qt Quick applications using the \e {QML debug engine}. To debug
    applications on Linux, you can use GDB.

    You can debug Qt and Qt Quick applications in Visual Studio by setting
    breakpoints in C++ and QML files and stepping through the execution of code.
    While in break mode, you can 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.

    To start a debugging session, select \uicontrol Debug >
    \uicontrol {Start Debugging} or press \key F5.

    \list
        \li \l {Debugging Qt Quick Applications}
        \li \l {Debugging on Linux}
    \endlist
*/

/*!
    \page qtvstools-debugging-qt-quick.html
    \previouspage Debugging
    \nextpage Debugging on Linux
    \title Debugging Qt Quick Applications

    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 provides 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.

    If a Qt project contains 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. This can
    be seen in the Processes window of the Visual Studio debugger. Two processes
    are listed: a native process that corresponds to the actual physical
    process created for the C++ debugging session and a QML process that does
    not correspond to any physical process that is running on the machine, but
    rather 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.

    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, it is possible to
    view and modify the values of local variables in the context of the
    currently active call stack frame, as well as to create watches for any
    variable or expression. In the Immediate window, you can evaluate any
    expression in the context of the current stack frame.

    Move the mouse over a QML expression to display an instant watch window.
    The value of that expression in the current context is displayed and can
    be modified.

    \section1 Enabling QML Debugging

    QML debugging is enabled by default. To disable processing of all QML
    debug events by the QML debug engine, select \uicontrol Extensions >
    \uicontrol {Qt VS Tools} > \uicontrol Options > \uicontrol Qt
    \uicontrol General > \uicontrol {QML Debugging}, and set
    \uicontrol {Process debug events} to \uicontrol False.
    This effectively excludes the QML debug engine from the debugging
    environment and disables debugging of QML code for all projects.

    \image qtvstools-options-qt-general.png "Qt General Options"

    To increase or decrease the timeout for debugging connections in
    milliseconds, edit the value of \uicontrol {Runtime connection timeout}.
    To remove the timeout, set the value to \uicontrol Disabled.

    For more information about debugging Qt Quick applications on Linux devices,
    see \l {Remote QML Debugging}.
*/

/*!
    \page qtvstools-debugging-linux.html
    \previouspage Debugging Qt Quick Applications
    \nextpage Getting Help
    \title Debugging on Linux

    If you have set up Qt VS Tools for \l {Cross-Compiling}{cross-compilation}
    on Linux, you can debug applications running on a 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.png

    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 the Visual Studio uses the correct debugger,
    create a symbolic link from \c gdb to \c gdb-multiarch.

    To set up the remote debugging session in Visual Studio, you must
    pass additional commands to GDB. Select \uicontrol Project >
    \uicontrol Properties > \uicontrol Debugging, and then select
    \uicontrol {GDB Debugger} in \uicontrol {Debugger to launch}. In
    \uicontrol {Additional Debugger Commands}, add the following commands:

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

    Before starting the remote debugging session, set the required environment
    variables and launch \c gdbserver on the device:

    \list
        \li \l{https://man7.org/linux/man-pages/man8/ld.so.8.html}
            {LD_LIBRARY_PATH} specifies the path to the directory
            where Qt binaries are installed.
        \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 the platform plugin is installed.
        \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 QML modules are installed.
    \endlist

    Press \key F5 to start the remote debugging session.

    \section1 Remote QML Debugging

    To debug Qt Quick applications on Linux devices, \l{Enabling QML Debugging}
    {enable QML debugging} and set up program arguments for starting a QML
    debugging session. \uicontrol Project > \uicontrol Properties >
    \uicontrol Debugging, and then select \uicontrol {GDB Debugger} in
    \uicontrol {Debugger to launch}. In
    \uicontrol {Additional Debugger Commands}, add the following command:

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