omp_utils/QtVSTools.git

			@@ -1,6 +1,6 @@
			/****************************************************************************
			**
			** Copyright (C) 2021 The Qt Company Ltd.
			** Copyright (C) 2022 The Qt Company Ltd.
			** Contact: https://www.qt.io/licensing/
			**
			** This file is part of the documentation of the Qt Toolkit.
			@@ -36,10 +36,93 @@
			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 projects and classes.
			\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)}.
			@@ -55,36 +138,6 @@
			\li Debugging extensions for Qt data types.
			\endlist

			\section1 Table of Contents

			\list
			\li \l {Getting Started}
			\li \l {Managing Qt Versions}
			\li \l {Building}
			\li \l {Cross-Compiling}
			\li \l {Creating Projects}
			\li \l {Importing and Exporting Projects}
			\li \l {Adding Form Files to Projects}
			\li \l {Managing Resources}
			\li \l {Creating Qt Translation Files for Projects}
			\li \l {Updating IntelliSense Info}
			\li \l {Getting Help}
			\endlist
			*/

			/*!
			\page qtvstools-getting-started.html
			\previouspage Qt VS Tools Manual
			\nextpage Managing Qt Versions
			\title Getting Started

			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 Install Qt VS Tools

			In Microsoft Visual Studio, select \uicontrol Extensions >
			@@ -97,6 +150,40 @@
			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:
			@@ -104,8 +191,9 @@
			\list 1
			\li Select \uicontrol File > \uicontrol New > \uicontrol Project, and
			search for \uicontrol {Qt Widgets Application}.
			\li In the \uicontrol Name field, enter \e AddressBook, and then select
			\uicontrol OK.
			\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
			@@ -407,9 +495,366 @@
			*/

			/*!
			\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 Cross-Compiling
			\nextpage Importing and Exporting Projects
			\previouspage Managing Projects
			\nextpage Creating Files
			\title Creating Projects

			Once you have installed Qt VS Tools, you can search for and then select
			@@ -439,11 +884,158 @@
			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 Getting Started
			\previouspage Configuring Builds
			\nextpage Building
			\title Managing Qt Versions

			@@ -529,7 +1121,7 @@
			/*!
			\page qtvstools-cross-compiling.html
			\previouspage Building
			\nextpage Creating Projects
			\nextpage Importing and Exporting Projects
			\title Cross-Compiling

			Qt VS Tools supports cross-compilation of Qt projects by integrating
			@@ -589,8 +1181,8 @@

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

			Qt and Visual Studio use different file formats to save projects. If you
			@@ -659,16 +1251,16 @@

			/*!
			\page qtvstools-form-files.html
			\previouspage Importing and Exporting Projects
			\previouspage Creating Files
			\nextpage Managing Resources
			\title Adding Form Files to Projects
			\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 Qt Class} > \uicontrol Installed > \uicontrol {Visual C++} >
			\uicontrol Qt > \uicontrol {Qt Widget Class}.
			\uicontrol {Add New Item} > \uicontrol Installed > \uicontrol {Visual C++} >
			\uicontrol Qt > \uicontrol {Qt Widgets Form File}.

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

			@@ -679,8 +1271,8 @@

			/*!
			\page qtvstools-managing-resources.html
			\previouspage Adding Form Files to Projects
			\nextpage Creating Qt Translation Files for Projects
			\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
			@@ -727,18 +1319,20 @@
			\page qtvstools-translation-files.html
			\previouspage Managing Resources
			\nextpage Updating IntelliSense Info
			\title Creating Qt Translation Files for Projects
			\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 Extensions > \uicontrol {Qt VS Tools} >
			\uicontrol {Create New Translation File}.
			\li In the \uicontrol Language field, select a language from the list of
			supported languages.
			\li In the \uicontrol Filename field, enter a filename for the
			translation file.
			\li Select \uicontrol OK to create the file and have it listed in
			\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.
			@@ -761,7 +1355,7 @@

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

			By default, Qt VS Tools tries to display Qt online documentation when you
			@@ -790,8 +1384,8 @@

			/*!
			\page qtvstools-intellisense-info.html
			\previouspage Creating Qt Translation Files for Projects
			\nextpage Getting Help
			\previouspage Creating Qt Translation Files
			\nextpage Debugging
			\title Updating IntelliSense Info

			Visual Studio provides IntelliSense code editing features for C++ types
			@@ -822,6 +1416,164 @@
			\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
			*/