/****************************************************************************
|
**
|
** 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 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.
|
|
The options for each Qt tool can be set 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).
|
|
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.
|
|
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
|
*/
|
