forked from qt-creator/qt-creator
1212 lines
46 KiB
Plaintext
1212 lines
46 KiB
Plaintext
/*!
|
|
\contentspage{index.html}{Qt Creator}
|
|
\page index.html
|
|
\nextpage creator-quick-tour.html
|
|
|
|
\title Qt Creator Manual
|
|
|
|
\section1 Version 0.9.1 (Beta)
|
|
|
|
The goal of Qt Creator is to provide a cross-platform, complete Integrated
|
|
Development Environment (IDE) to develop Qt projects. It is available for
|
|
the Linux, Mac OS X and Windows platforms.
|
|
|
|
\note The current version of Qt Creator is 0.9.1 (Beta). It is
|
|
possible to edit source code, compile, run and debug applications; other
|
|
features are still under development. Please send bug reports and
|
|
suggestions to qt-creator@trolltech.com. To subscribe, send a
|
|
message with the word \e subscribe to qt-creator-request@trolltech.com.
|
|
For more information on Qt mailing lists, visit http://lists.trolltech.com
|
|
|
|
\table
|
|
\row
|
|
\o \inlineimage qtcreator-screenshots.png
|
|
\row
|
|
\o Qt Creator includes a wide range of useful features. Among them are:
|
|
\list 1
|
|
\o \bold{Smart Code Editor}: The code editor provides syntax
|
|
highlighting as well as code completion.
|
|
\o \bold{Qt4 Project Generating Wizard}: This wizard allows the user
|
|
to generate a project for a console application, a GUI application,
|
|
or a C++ library.
|
|
\o \bold{Qt Help Integration}: Qt's entire documentation can be
|
|
accessed easily by clicking on the \gui{Help} button.
|
|
\o \bold{Qt Designer Integration}: User interface forms can be designed
|
|
within Qt Creator. Simply double-click on a \c{.ui} file within the
|
|
\gui{Project Explorer} to launch the integration.
|
|
\o \bold{Locator}: A powerful navigation tool that lets the user locate
|
|
files and classes using minimal keystrokes.
|
|
\o \bold{Support for qmake's .pro file format}: The project's \c{.pro}
|
|
file is used as a project description file.
|
|
\o \bold{Debugging Interface to GDB}: Applications can be debugged
|
|
within Qt Creator using a graphical frontend to the GNU symbolic
|
|
debugger.
|
|
\endlist
|
|
\endtable
|
|
|
|
To learn more about the Qt Creator, click on one of the links below:
|
|
|
|
\list
|
|
\o \l{A Quick Tour Around Qt Creator}
|
|
\o \l{Creating a Project in Qt Creator}
|
|
\o \l{Build Settings}
|
|
\o \l{Writing a Simple Program with Qt Creator}
|
|
\o \l{Navigating Quickly Around Your Code with Locator}
|
|
\o \l{Debugging with Qt Creator}
|
|
\o \l{Tips and Tricks}
|
|
\o \l{Glossary}
|
|
\o \l{Known Issues of Version 0.9.1 (Beta)}
|
|
\endlist
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\page creator-quick-tour.html
|
|
\nextpage creator-build-settings.html
|
|
|
|
\title A Quick Tour Around Qt Creator
|
|
|
|
The labeled screenshot below shows some of the components of Qt Creator, in
|
|
\gui Edit mode.
|
|
|
|
\image qtcreator-breakdown.png
|
|
|
|
\section1 The Mode Selectors
|
|
|
|
When working in Qt Creator, you can be in one of six modes: \bold Welcome,
|
|
\bold Edit, \bold Debug, \bold Projects, \bold Help, and \bold Output.
|
|
|
|
Mode selectors allow you to quickly switch between tasks: Editing, browsing
|
|
the Qt Creator manual, setting up the build environment, etc. You can
|
|
activate a mode by either clicking on its mode selector, or using the
|
|
\l{keyboard-shortcuts}{corresponding shortcut}. Certain actions also
|
|
trigger a mode change, e.g., \gui{Debug}/\gui{Start Debugging} will switch
|
|
to the \gui Debug mode.
|
|
|
|
\list
|
|
|
|
\o \gui{Welcome Mode} - Displays a welcome screen allowing you to quickly
|
|
load recent sessions or individual projects. This is the mode you will see
|
|
if Qt Creator is run without command line switches.
|
|
|
|
\o \gui{Edit Mode} - Lets you edit both project and source files. A sidebar
|
|
on the left provides different views to navigate between files.
|
|
|
|
\o \gui{Debug Mode} - Provides various ways to inspect the state of the
|
|
program while debugging. See \l{Debugging With Qt Creator} for a hands-on
|
|
description of how to use this mode.
|
|
|
|
\o \gui{Projects Mode} - Lets you configure how projects can be built and
|
|
executed. Under the list of projects, there are tabs to configure the
|
|
build, run, and editor settings.
|
|
|
|
\o \gui{Help Mode} - Shows any documentation registered by Qt Assistant,
|
|
such as the Qt library and Qt Creator documentation.
|
|
|
|
\o \gui{Output Mode} - Lets you examine various data in detail, for example
|
|
build issues as well as compile and application output. This information
|
|
is also available in the output panes.
|
|
|
|
\endlist
|
|
|
|
|
|
\section1 The Output Panes
|
|
|
|
The task pane in Qt Creator can display one of four different panes:
|
|
\gui{Build Issues}, \gui{Search Results}, \gui{Application Output}, and
|
|
\gui{Compile Output}. These panes are available in all modes.
|
|
|
|
\section2 Build Issues
|
|
|
|
The {Build Issues} pane provides a list of issues, e.g., error messages or
|
|
warnings that need to be fixed. It filters out irrelevant output from the
|
|
compiler and collects them in an organized way.
|
|
|
|
\image qtcreator-build-issues.png
|
|
|
|
\section2 Search Results
|
|
|
|
The \gui{Search Results} pane displays the results for global searches such
|
|
as searching within a current document, files on disk, or all projects. In
|
|
the screenshot below, we searched for all occurrences of \c{textfinder}
|
|
within the \c{"/TextFinder"} folder.
|
|
|
|
\image qtcreator-search-pane.png
|
|
|
|
\section2 Application Output
|
|
|
|
The \gui{Application Output} pane displays the status of the program when
|
|
it is executed and debug output, e.g., output from qDebug().
|
|
|
|
\image qtcreator-application-output.png
|
|
|
|
\section2 Compile
|
|
|
|
The \gui{Compile Output} pane provides all the output from the compiler. In
|
|
other words, it is a more verbose version of information displayed in the
|
|
\gui{Build Issues}
|
|
|
|
\image qtcreator-compile-pane.png
|
|
|
|
\section1 Qt Help Integration
|
|
|
|
Qt Creator comes fully integrated with all of Qt's documentation and
|
|
examples via the Qt Help plugin. To view the documentation, you can switch
|
|
to the \gui{Help} mode. To obtain context sensitive help, move your text
|
|
cursor to a Qt class or function and press \key{F1}. The documentation
|
|
will be displayed within a panel on the right, as shown in the screenshot
|
|
below.
|
|
|
|
External Documentation provided by the user can be used to augment or
|
|
replace the documentation shipped with Qt Creator and Qt.
|
|
|
|
\image qtcreator-context-sensitive-help.png
|
|
|
|
|
|
\section1 Qt Designer Integration
|
|
|
|
Qt Creator is fully integrated with Qt Designer to help you design user
|
|
interface forms just like you would with the standalone version. The Qt
|
|
Designer integration also includes project management and code completion.
|
|
For more information on Qt Designer, you can refer to
|
|
\l{http://doc.trolltech.com/designer-manual.html}{The Designer Manual}.
|
|
|
|
\image qtcreator-formedit.png
|
|
|
|
|
|
\section1 Keyboard Navigation
|
|
|
|
Qt Creator caters not only to developers who are used to using the mouse,
|
|
but also to developers who are more comfortable with the keyboard. A wide
|
|
range of \l{keyboard-shortcuts}{keyboard} and
|
|
\l{Navigating Quickly Around Your Code with Locator}{navigation} shortcuts
|
|
are available to help speed up the process of developing your application.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-quick-tour.html
|
|
\page creator-build-settings.html
|
|
\nextpage creator-creating-project.html
|
|
|
|
\title Build Settings
|
|
|
|
\table
|
|
\row
|
|
\i \note Qt Creator currently supports \c qmake only. \c Makefile
|
|
and \c CMake support is currently unavailable.
|
|
\endtable
|
|
|
|
To modify the build settings of your project, switch to the \gui{Projects}
|
|
mode using the mouse or with \key{Ctrl+4}.
|
|
|
|
\image qtcreator-buildsettingstab.png
|
|
|
|
Action items to create, clone, or delete build configurations can be found
|
|
at the bottom of the dialog. You can have as many build configurations as
|
|
needed. By default Qt Creator creates a \bold{debug} and \bold{release}
|
|
build configuration. Both these configurations use the
|
|
\l{glossary-default-qt}{Default Qt Version}.
|
|
|
|
In the tree on the left, a list of build configurations and their settings
|
|
are displayed. The screenshot above shows the \bold{debug} and
|
|
\bold{release} configurations and their corresponding settings:
|
|
\bold{Build Environment} and \bold{Build Steps}.
|
|
|
|
When you select a build configuration in the tree, a configuration page for
|
|
general build settings will be displayed. Here you can specify which
|
|
\l{glossary-project-qt}{Qt version} to use to build your project, whether
|
|
to \l{glossary-shadow-build}{shadow build} the project.
|
|
|
|
\image qtcreator-buildenvironment.png
|
|
|
|
In the \bold{Build Environment} page you can specify the environment used
|
|
for building. By default the environment in which Qt Creator was started
|
|
is used and modified to include the Qt version. Depending on the selected
|
|
Qt version, Qt Creator will automatically add the necessary environment
|
|
variables.
|
|
|
|
\image qtcreator-buildsteps.png
|
|
|
|
The build system of Qt Creator is built on top of \c qmake and \c make. The
|
|
settings for \c qmake and \c make can be changed in the
|
|
\bold{Build Settings} page. Qt Creator will run the make command using the
|
|
correct Qt version.
|
|
|
|
\note The \bold{Gdb Macros Build} step builds a small library along with your
|
|
project that is used for the custom display of Qt and STL objects in the
|
|
integrated debugger. The library is created and built in a "qtc-gdbmacros"
|
|
subfolder of your project's main directory, and loaded dynamically into your
|
|
application if you run it in the debugger. If the
|
|
debugging helper seems to break your build or your application, you can
|
|
remove the build step. You will still be able to debug applications, but the
|
|
contents of Qt and STL data types will not be displayed properly.
|
|
|
|
|
|
\section1 Qt Version Management
|
|
|
|
Qt Creator allows you to use multiple versions of Qt installed on your hard
|
|
disk and switch between them easily.
|
|
|
|
Qt Creator automatically detects if \c qmake is in the environment variable
|
|
\c PATH. This \l{glossary-system-qt}{version of Qt} is referred to as
|
|
\bold{System Qt}. If you intend to use only one version of Qt - it is
|
|
already in your path and correctly set up for command line usage - you do
|
|
not need to manually configure your Qt version.
|
|
|
|
Otherwise, you can add your Qt version in
|
|
\gui{Tools -> Options... -> Qt Versions}. If you are on the Windows
|
|
platform and use MinGW to compile Qt, you need to tell Qt Creator where
|
|
MinGW is installed. This is done by setting the \gui{MinGW Directory}
|
|
under \gui{Tools -> Options... -> Qt4 -> Qt Versions -> MinGw Directory}.
|
|
If your Qt version is compiled with Microsoft Visual C++'s compiler, Qt
|
|
Creator will automatically set the correct environment variables for
|
|
compilation.
|
|
|
|
\note By default projects are compiled with the
|
|
\l{glossary-default-qt}{default Qt version}. You can override this in the
|
|
\gui{Build Configuration}.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-quick-tour.html
|
|
\page creator-creating-project.html
|
|
\nextpage creator-writing-program.html
|
|
|
|
\title Creating a Project in Qt Creator
|
|
|
|
\table
|
|
\row
|
|
\i \inlineimage qtcreator-new-project.png
|
|
\i \bold{Creating a New Project}
|
|
|
|
To create a new project, select \gui{New Project} from the \gui{File} menu.
|
|
You can create one of the following three projects:
|
|
|
|
\list
|
|
\o Qt4 Console Application
|
|
\o Qt4 Gui Application
|
|
\o C++ Library
|
|
\endlist
|
|
|
|
In this example, we select a \e{Qt4 Gui Application} and click \gui{OK}.
|
|
|
|
\row
|
|
\i \inlineimage qtcreator-intro-and-location.png
|
|
\i \bold{Setting The Project Name and Location}
|
|
|
|
Next, we set the project's name and its path. Click on the \gui{...}
|
|
button to browse and select your path.
|
|
|
|
Ideally, the path should not contain spaces or special characters.
|
|
|
|
\row
|
|
\i \inlineimage qtcreator-select-modules.png
|
|
\i \bold{Selecting The Necessary Qt Modules}
|
|
|
|
Click on the check boxes of each Qt Module you would like to include in
|
|
your project.
|
|
|
|
Since we started a Qt4 Gui Application, the Core and Gui modules are
|
|
set, but you are free to add more.
|
|
|
|
\row
|
|
\i \inlineimage qtcreator-class-info.png
|
|
\i \bold{Specifying Class Information}
|
|
|
|
Specify the name of the class you would like to create. The
|
|
\e{Header file}, \e{Source file} and \e{Form file} fields will update
|
|
automatically according to your choice of class name.
|
|
|
|
You also have to select the base class for your class, either a
|
|
QWidget, QDialog or QMainWindow, from the drop down box.
|
|
|
|
\row
|
|
\i \inlineimage qtcreator-new-project-summary.png
|
|
\i \bold{Creating the Project}
|
|
|
|
Finally, review the files that will be created for you. Click
|
|
\gui{Done} and your project will be generated.
|
|
|
|
\endtable
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-creating-project.html
|
|
\page creator-writing-program.html
|
|
\nextpage creator-navigation.html
|
|
|
|
\title Writing a Simple Program with Qt Creator
|
|
|
|
\table
|
|
\row
|
|
\o \note This tutorial assumes that the user has experience writing
|
|
basic Qt applications, designing user interfaces with Qt Designer
|
|
and and using the Qt Resource System.
|
|
\endtable
|
|
|
|
|
|
In this example, we will describe the steps involve in using Qt Creator
|
|
to create a small Qt program, Text Finder. Inspired by the QtUiTools'
|
|
\l{http://doc.trolltech.com/uitools-textfinder.html}{Text Finder}
|
|
example, we will write a similar but simplified version of it, as shown
|
|
below.
|
|
|
|
\image qtcreator-textfinder-screenshot.png
|
|
|
|
\section1 Setting Up Your Environment
|
|
|
|
Once you have installed Qt Creator, it will automatically detect if Qt's
|
|
location is in your \c PATH variable. If Qt's location is not in your
|
|
\c PATH, you can set it in one of the following ways, depending on your
|
|
platform:
|
|
|
|
\list
|
|
\o On Windows and Linux: in the \gui{Tools} menu, under \gui{Options}.
|
|
\o On Mac OS X: in \gui{Preferences}, under \gui{Qt4}.
|
|
\endlist
|
|
|
|
\note If Qt was compiled with Visual Studio, all environment variables set
|
|
in Visual Studio will be added to Qt Creator as well.
|
|
|
|
\section1 Setting Up The Project
|
|
|
|
We begin with a Qt4 Gui Application project generated by Qt Creator. The
|
|
\l{Creating a Project in Qt Creator} document describes this process in
|
|
detail. Remember to select QWidget as the Text Finder's base class.
|
|
|
|
Once your project is generated, you will have the following files:
|
|
|
|
\list
|
|
\o \c{textfinder.h}
|
|
\o \c{textfinder.cpp}
|
|
\o \c{main.cpp}
|
|
\o \c{textfinder.ui}
|
|
\o \c{textfinder.pro}
|
|
\endlist
|
|
|
|
The \c{.h} and \c{.cpp} files come with the necessary boiler plate code;
|
|
the \c{.pro} file is also complete.
|
|
|
|
\section1 Filling In The Missing Pieces
|
|
|
|
We will begin by designing the user interface and then move on to filling
|
|
in the missing code. Finally, we will add the find functionality.
|
|
|
|
\section2 Designing the User Interface
|
|
|
|
To begin designing the user interface, double-click on the
|
|
\c{textfinder.ui} file in your \gui{Project Explorer}. This will launch the
|
|
integrated Qt Designer.
|
|
|
|
\image qtcreator-textfinder-ui.png
|
|
|
|
Design the form above using a \l{http://doc.trolltech.com/qlabel.html}
|
|
{QLabel}, \l{http://doc.trolltech.com/qlinedit.html}{QLineEdit},
|
|
\l{http://doc.trolltech.com/qpushbutton.html}{QPushButton} and a
|
|
\l{http://doc.trolltech.com/qtextedit.html}{QTextEdit}. We recommend that
|
|
you use a QGridLayout to lay out the
|
|
\l{http://doc.trolltech.com/qlabel.html}{QLabel},
|
|
\l{http://doc.trolltech.com/qlinedit.html}{QLineEdit} and
|
|
\l{http://doc.trolltech.com/qpushbutton.html}{QPushButton}. The
|
|
\l{http://doc.trolltech.com/qtextedit.html}{QTextEdit} can then be added to
|
|
a \l{http://doc.trolltech.com/qvboxlayout.html}{QVBoxLayout}, along with
|
|
the \l{http://doc.trolltech.com/qgridlayout.html}{QGridLayout}. If you are
|
|
new to designing forms with \QD, you can take a look at the
|
|
\l{http://doc.trolltech.com/designer-manual.html}{Designer Manual}.
|
|
|
|
\section2 The Header File
|
|
|
|
The \c{textfinder.h} file already has the necessary includes, a
|
|
constructor, a destructor, and the \c{Ui} object. We need to add a private
|
|
slot, \c{on_findButton_clicked()}, to carry out our find operation. We
|
|
also need a private function, \c{loadTextFile()}, to read and display the
|
|
contents of our input text file in the
|
|
\l{http://doc.trolltech.com/qtextedit.html}{QTextEdit}. This is done with
|
|
the following code:
|
|
|
|
\code
|
|
private slots:
|
|
void on_findButton_clicked();
|
|
|
|
private:
|
|
Ui::Form ui;
|
|
void loadTextFile();
|
|
\endcode
|
|
|
|
\note The \c{Ui::Form} object is already provided.
|
|
|
|
\section2 The Source File
|
|
|
|
Now that our header file is complete we move on to our source file,
|
|
\c{textfinder.cpp}. We begin by filling in the functionality to load a
|
|
text file. The code snippet below describes this:
|
|
|
|
\code
|
|
void TextFinder::loadTextFile()
|
|
{
|
|
QFile inputFile(":/input.txt");
|
|
inputFile.open(QIODevice::ReadOnly);
|
|
|
|
QTextStream in(&inputFile);
|
|
QString line = in.readAll();
|
|
inputFile.close();
|
|
|
|
ui.textEdit->setPlainText(line);
|
|
QTextCursor cursor = ui.textEdit->textCursor();
|
|
}
|
|
\endcode
|
|
|
|
Basically, we load a text file using
|
|
\l{http://doc.trolltech.com/qfile.html}{QFile}, read it with
|
|
\l{http://doc.trolltech.com/qtextstream.html}{QTextStream}, and
|
|
then display it on \c{textEdit} with
|
|
\l{http://doc.trolltech.com/qtextedit.html#plainText-prop}{setPlainText()}.
|
|
|
|
For the \c{on_findButton_clicked()} slot, we extract the search string and
|
|
use the \l{http://doc.trolltech.com/qtextedit.html#find}{find()} function
|
|
to look for the search string within the text file. The code snippet below
|
|
further describes it:
|
|
|
|
\code
|
|
void TextFinder::on_findButton_clicked()
|
|
{
|
|
QString searchString = ui.lineEdit->text();
|
|
ui.textEdit->find(searchString, QTextDocument::FindWholeWords);
|
|
}
|
|
\endcode
|
|
|
|
Once we have both these functions complete, we call \c{loadTextFile()} in
|
|
our constructor.
|
|
|
|
\code
|
|
TextFinder::TextFinder(QWidget *parent, Qt::WFlags flags)
|
|
: QWidget(parent, flags)
|
|
{
|
|
ui.setupUi(this);
|
|
loadTextFile();
|
|
}
|
|
\endcode
|
|
|
|
The \c{on_findButton_clicked()} slot will be called automatically due to
|
|
this line of code:
|
|
|
|
\code
|
|
QMetaObject::connectSlotsByName(Form);
|
|
\endcode
|
|
|
|
in the uic generated \c{ui_textfinder.h} file.
|
|
|
|
\section2 The Resource File
|
|
|
|
We require a resource file (\c{.qrc}) within which we will embed the input
|
|
text file. This can be any \c{.txt} file with a paragraph of text. To add
|
|
a resource file, right click on \gui{Resource Files} in the
|
|
\gui{Project Explorer} and select \gui{Add New File...}. You will see the
|
|
wizard dialog displayed below.
|
|
|
|
\image qtcreator-add-resource-wizard.png
|
|
|
|
Enter "textfinder" in the \gui{Name} field and use the given \gui{Path}.
|
|
Then, click \gui{Continue}.
|
|
|
|
\image qtcreator-add-resource-wizard2.png
|
|
|
|
On this page you can choose to which project you want to add the new file.
|
|
Make sure that \gui{Add to Project} is checked and
|
|
"TextFinder" is selected as the \gui{Project}, and click
|
|
\gui{Done}.
|
|
|
|
Your resource file will now be displayed with the Resource Editor. Click
|
|
on the \gui{Add} drop down box and select \gui{Add Prefix}. The prefix we
|
|
require is just a slash (\c{/}). Click \gui{Add} again but this time,
|
|
select \gui{Add File}. Locate the text file you are going to use, we use
|
|
\c{input.txt}.
|
|
|
|
\image qtcreator-add-resource.png
|
|
|
|
The screenshot above shows what you can expect to see once you have added
|
|
the resource file successfully.
|
|
|
|
\section1 Compiling and Running Your Program
|
|
|
|
Now that you have all the necessary files, you can compile your program by
|
|
clicking on the
|
|
\inlineimage qtcreator-run.png
|
|
button.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-writing-program.html
|
|
\page creator-navigation.html
|
|
\nextpage creator-debugging.html
|
|
|
|
\title Navigating Quickly Around Your Code with Locator
|
|
|
|
With Qt Creator, navigating to different locations in your project or on
|
|
your disk, e.g., files, classes, methods, etc., is trivial using
|
|
\gui Locator -- a smart line edit at the bottom left of Qt Creator's
|
|
window.
|
|
|
|
\image qtcreator-locator.png
|
|
|
|
Suppose you would like to open your project's \c{main.cpp} file, click on
|
|
\gui Locator or use \key{Ctrl+K}, type in the file name and then press
|
|
\key Return. The file will be opened in the editor. You can also type
|
|
part of a file name and use wildcard characters \c{*} and \c{?} to match
|
|
\e{any} number of \e{any} characters. A list of all files matching your
|
|
criteria will be displayed.
|
|
|
|
\gui Locator not only allows you to navigate files on disk but also other
|
|
"locations", which are organized with \bold{Filters}. Currently there are
|
|
filters for:
|
|
|
|
\list
|
|
\o files anywhere on your hard disk (browsing through the file system),
|
|
\o files from a subdirectory structure defined by you,
|
|
\o files mentioned in your \c{.pro} files, such as source, header,
|
|
resource, and \c{.ui} files,
|
|
\o any open document,
|
|
\o class and method definitions in your project or anywhere referenced
|
|
from your project,
|
|
\o help topics, including Qt's documentation, and,
|
|
\o a specific line in the document displayed on your editor,
|
|
\endlist
|
|
|
|
|
|
Some of these filters require you to activate them by typing an assigned
|
|
\e prefix. This prefix is usually a single character followed by
|
|
\key{Space}. For example, to jump to the definition of the class
|
|
\l{http://doc.trolltech.com/qdatastream.html}{QDataStream}, type:
|
|
\key{Ctrl+K} to activate \gui Locator. Then type colon (\key{:}) followed
|
|
by \key{Space} and the class name.
|
|
|
|
|
|
Below is a full list of \l{http://doc.trolltech.com/qdatastream.html}
|
|
{QDataStream} related output:
|
|
|
|
\image qtcreator-navigate-popup.png
|
|
|
|
|
|
Filters can be added to provide quick navigation around files in a
|
|
subdirectory structure defined by you. This way, you can acccess files you
|
|
need, that are not directly mentioned in your project. Click on
|
|
\image qtcreator-locator-magnify.png
|
|
and choose \gui{Configure...} from the menu displayed.
|
|
|
|
\image qtcreator-locator-customize.png
|
|
|
|
This then displays the \gui Preferences dialog (\gui Options on Mac Os X)
|
|
for navigation filters. Click \gui Add to create a new filter. In the
|
|
\gui{Filter Configuration} dialog below, give your filter a name, select
|
|
your preferred directories, set file patterns with a comma separated list,
|
|
and specify a prefix string.
|
|
|
|
\image qtcreator-navigate-customfilter.png
|
|
|
|
After closing this dialog, \gui Locator will search the directories you
|
|
selected for files matching your file patterns, and the information will be
|
|
cached. Click \gui Refresh from the menu above to update the cached
|
|
information.
|
|
|
|
The following table lists the filters currently available:
|
|
|
|
\table
|
|
\header
|
|
\o Function
|
|
\o Key Combination
|
|
\o Screenshot
|
|
\row
|
|
\o Go to a line in the current document
|
|
\o Ctrl+K, l, Space, and the line number
|
|
\o \image qtcreator-locator-line.png
|
|
\row
|
|
\o Go to a symbol definition
|
|
\o Ctrl+K, :, Space, and the function name
|
|
\o \image qtcreator-locator-symbols.png
|
|
\row
|
|
\o Go to a help topic
|
|
\o Ctrl+K, ?, Space, and the topic
|
|
\o \image qtcreator-locator-help.png
|
|
\row
|
|
\o Go to an opened document
|
|
\o Ctrl+K, o, Space, and the document name.
|
|
\o \image qtcreator-locator-opendocs.png
|
|
\row
|
|
\o Go to a file in the file system (browse the file system)
|
|
\o Ctrl+K, f, Space, and the file name.
|
|
\o \image qtcreator-locator-filesystem.png
|
|
\row
|
|
\o Go to a file in any project currently loaded
|
|
\o Ctrl+K, a, Space, and the function name.
|
|
\o \image qtcreator-locator-files.png
|
|
\row
|
|
\o Go to a file in the current project
|
|
\o Ctrl+K, p, Space, and the function name.
|
|
\o \image qtcreator-locator-current-project.png
|
|
\row
|
|
\o Go to a class definition
|
|
\o Ctrl+K, c, Space, and the class name.
|
|
\o \image qtcreator-locator-classes.png
|
|
\row
|
|
\o Go to a method definition
|
|
\o Ctrl+K, m, Space, and the class name.
|
|
\o \image qtcreator-locator-methods.png
|
|
\endtable
|
|
|
|
\note By default, if you press \key{Ctrl+K} and do not use a prefix to
|
|
specify a filter, three filters will be enabled: \c{o}, \c{l}, and \c{a}.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-navigation.html
|
|
\page creator-debugging.html
|
|
\nextpage creator-tips.html
|
|
|
|
\title Debugging with Qt Creator
|
|
|
|
\table
|
|
\row
|
|
\i \note Qt Creator's debugger integration currently does not
|
|
support debugging applications created with the Microsoft Visual
|
|
Studio Compiler.
|
|
\endtable
|
|
|
|
Qt Creator does not have its own debugger. Instead, it provides a graphical
|
|
frontend to the GNU Symbolic Debugger (gdb). This frontend allows you to
|
|
step through a program line-by-line or instruction-by-instruction,
|
|
interrupt running programs, set breakpoints, examine the contents of the
|
|
call stack, local and global variables, etc.
|
|
|
|
|
|
Within Qt Creator, the raw information provided by gdb is displayed in a
|
|
clear and concise manner, simplifying the process of debugging.
|
|
|
|
In addition to generic IDE functionality: stack view, views for locals and
|
|
watchers, registers, etc, Qt Creator comes with additional features to make
|
|
debugging Qt-based applications easy. The debugger frontend knows about the
|
|
internal layout of several Qt classes such as QString, the QTL containers,
|
|
and most importantly QObject (and classes derived from it). Therefore, it
|
|
is able to present Qt's data clearly.
|
|
|
|
|
|
\section1 Interacting with the Debugger
|
|
|
|
In \gui Debug mode, several dock widgets are used to interact with the
|
|
program you are debugging. The frequently used dock widgets are visible by
|
|
default; the rarely used ones are hidden. To change the default settings,
|
|
select \gui Debug and then select \gui View.
|
|
|
|
\image qtcreator-debug-view.png
|
|
|
|
Here, you can lock or unlock the location of your views as well as display
|
|
or hide them. Among the views you can display are \gui Breakpoints,
|
|
\gui Disassembler, \gui Modules, \gui Registers, \gui Gdb, \gui Stack, and
|
|
\gui Thread. The position of your dock widgets will be saved for future
|
|
sessions.
|
|
|
|
|
|
\section2 Breakpoints
|
|
|
|
Breakpoints are shown in the \gui{Breakpoints} view which is enabled by
|
|
by default. This view is also accessible when the debugger and the program
|
|
being debugged is not running.
|
|
|
|
A breakpoint represents a position or sets of positions in the code that,
|
|
when executed, stops the program being debugged and passing the control to
|
|
the user. The user is then free to examine the state of the interrupted
|
|
program, or continue execution line-by-line or continuously.
|
|
|
|
Typically, breakpoints are associated with a source code file and line, or
|
|
the start of a function -- both allowed in Qt Creator.
|
|
|
|
Also, the interruption of a program by a breakpoint can be restricted with
|
|
certain conditions.
|
|
|
|
You can set a breakpoint:
|
|
|
|
\list
|
|
\o At a particular line you want the program to stop -- click on the
|
|
left margin or press \key F9 (\key F8 for Mac OS X).
|
|
\o At a function that you want the program to stop -- enter the
|
|
function's name in \gui{Set Breakpoint at Function...} under the
|
|
\gui Debug menu.
|
|
\endlist
|
|
|
|
You can remove a breakpoint:
|
|
|
|
\list
|
|
\o By clicking on the breakpoint marker in the text editor.
|
|
\o By selecting the breakpoint in the breakpoint view and pressing
|
|
\key{Delete}.
|
|
\o By selecting \gui{Delete Breakpoint} from the breakpoint's context
|
|
menu in the \gui Breakpoints view.
|
|
\endlist
|
|
|
|
Breakpoints can be set and deleted before the program has actually started
|
|
running or while it is running under the debugger's control. Also,
|
|
breakpoints are saved together with a session.
|
|
|
|
|
|
\section2 Running
|
|
|
|
To start a program under the debugger's control, select the \gui{Debug}
|
|
menu and \gui{Start Debugging}, or simply press \key{F5}. Qt Creator then
|
|
checks whether the compiled program is up-to-date, rebuilding it if
|
|
necessary. The debugger then takes over and starts the program.
|
|
|
|
\note Starting a program in the debugger will take considerable amount of
|
|
time, typically in the range of several seconds to minutes if complex
|
|
features (like QtWebKit) are used.
|
|
|
|
Once the program starts running, it behaves as usual; performance-wise as
|
|
well. The user can interrupt a running program by selecting
|
|
\gui {Interrupt} from the \gui{Debug} menu. The program is automatically
|
|
interrupted as soon as a breakpoint is hit.
|
|
|
|
\omit (and, if set, its associated conditions are met). \endomit
|
|
|
|
Once the program stops, Qt Creator:
|
|
|
|
\list
|
|
\o Retrieves data representing the call stack at the program's current
|
|
position.
|
|
\o Retrieves the contents of local variables.
|
|
\o Examines \gui Watchers.
|
|
\o Updates the \gui Registers, \gui Modules, and \gui Disassembler
|
|
views.
|
|
\endlist
|
|
|
|
|
|
You can use the debugger views to examine the data in more detail.
|
|
|
|
To finish debugging, Press \key{Shift+F5}. A line of code can be executed
|
|
as a whole with \key F10; to execute a function or a sub-function, use
|
|
\key F11. Alternatively, you can continue running the program with \key F5.
|
|
It is possible to continue executing your program until the current
|
|
function completes or jump to an arbitrary position in the current
|
|
function.
|
|
|
|
|
|
\section2 Stack
|
|
|
|
When the program being debugged is stopped, Qt Creator displays the nested
|
|
function calls leading to the current position as a \e call stack trace.
|
|
This stack trace is built up from \e{call stack frames}, each representing a
|
|
particular function. For each function, Qt Creator will try to retrieve the
|
|
file name and line number of the corresponding source files. This data is
|
|
shown in the \gui Stack view.
|
|
|
|
\image qtcreator-debug-stack.png
|
|
|
|
Since the call stack leading to the current position may originate or go
|
|
through code for which no debug information is available, not all stack
|
|
frames will have corresponding source locations. These frames will be
|
|
greyed out in the \gui Stack view.
|
|
|
|
If you click on a frame with a known source location, the text editor will
|
|
jump to the corresponding location and update the \gui{Locals and Watchers}
|
|
view, making it seem like the program stopped before entering the function.
|
|
|
|
|
|
\section2 Threads
|
|
|
|
If a multi-threaded program is stopped, the \gui Thread view or the
|
|
combobox named \gui Thread in the debugger's status bar can be used to
|
|
switch from one thread to another. The \gui Stack view will adjust itself
|
|
accordingly.
|
|
|
|
|
|
\section2 Locals and Watchers
|
|
|
|
Whenever a program stops under the control of the debugger, it retrieves
|
|
information about the topmost stack frame and displays it in the
|
|
\gui{Locals and Watchers} view. This typically includes information about
|
|
parameters of the function in that frame as well as the local variables.
|
|
|
|
Compound variables of struct or class type will be displayed as
|
|
"expandable" in the view. C lick on the "+" to expand the entry and show
|
|
all members. Together with the display of value and type, the user can
|
|
examine and traverse the low-level layout of an object's data.
|
|
|
|
|
|
\table
|
|
\row
|
|
\i \bold{Note:}
|
|
|
|
\i Gdb, and therefore Qt Creator's debugger works for optimized
|
|
builds on Linux and Mac OS X. However, optimization may lead
|
|
to re-ordering of instructions or sometimes even complete
|
|
removal of some local variables. In this case, the
|
|
\gui{Locals and Watchers} view may show unexpected data.
|
|
|
|
\i The debug information provided by gcc does not include enough
|
|
information about the time when a variable is initialized.
|
|
Qt Creator therefore can not tell whether the contents of a
|
|
local variable contains "real data", or "initial noise". If a
|
|
QObject appears uninitialized, its value will be reported as
|
|
"out of scope". However, not all uninitialized objects can be
|
|
recognized as such.
|
|
\endtable
|
|
|
|
|
|
The \gui{Locals and Watchers} view also provides access to the most
|
|
powerful feature of the debugger: comprehensive display of data belonging
|
|
to Qt's basic objects. To enable this feature, select \gui{Use Custom
|
|
Display for Qt Objects} from the \gui Debug menu.The
|
|
\gui{Locals and Watchers} view will be re-organized to provide a high-level
|
|
view of the objects. For example, in case of QObject, instead of displaying
|
|
a pointer to some private data structure, you will see a list of children,
|
|
signals and slots.
|
|
|
|
Similarly, instead of displaying many pointers and integers, Qt Creator's
|
|
debugger will display the contents of a QHash or QMap in an orderly manner.
|
|
Also, the debugger will display access data for QFileInfo and provide
|
|
access to the "real" contents of QVariant.
|
|
|
|
The \gui{Locals and Watchers} view can be used to change the contents of
|
|
variables of simple data types such as \c int or \c float when the program
|
|
is stopped. To do so, click on the \gui Value column, modify the value
|
|
with the inplace editor, and hit \key Enter (or \key Return).
|
|
|
|
|
|
\section2 Modules
|
|
|
|
By default, the \gui Modules view is hidden as it is only useful with the
|
|
experimental delayed loaing of debug information feature. You can turn
|
|
this feature on by selecting \gui{Fast Debugger Start}
|
|
|
|
|
|
With this feature, debug information from the Qt library itself is not
|
|
loaded when the application starts up, thereby reducing the startup times
|
|
for some applications. You can then use the \gui Modules view to manually
|
|
load this information, if required.
|
|
|
|
\note In this scenario, some breakpoints may not be set by the debugger.
|
|
|
|
|
|
\section2 Disassembler View and Registers View
|
|
|
|
By default, both the \gui Disassembler and \gui Registers view are hidden.
|
|
The \gui Disassembler view displays disassembled code for the current
|
|
function; the \gui Registers view displays the current state of the CPU's
|
|
registers. Both views are useful for low-level commands such as
|
|
\gui{Step Single Instruction} and \gui{Step Over Single Instruction}.
|
|
|
|
\section1 A Walkthrough for the Debugger Frontend
|
|
|
|
In our \l{Writing a Simple Program with Qt Creator}{TextFinder} example, we
|
|
read a text file into a QString and then display it with a QTextEdit.
|
|
Suppose, you would like to look at this QString, \c{line}, and see what
|
|
data it actually stores. Follow the steps described below to place a
|
|
breakpoint and view the QString object's data.
|
|
|
|
\table
|
|
\row
|
|
\i \inlineimage qtcreator-setting-breakpoint1.png
|
|
\i \bold{Setting a Breakpoint}
|
|
|
|
First, we set a breakpoint on the line where we invoke
|
|
\l{http://doc.trolltech.com/qtextedit.html#plainText-prop}{setPlainText()}
|
|
by clicking between the line number and the window border. Then, select
|
|
\gui{Start Debugging} from the \gui{Debug} menu or press \key{F5}.
|
|
\endtable
|
|
|
|
Breakpoints are visible in the \gui{Breakpoints} view, shown below, in
|
|
\gui{Debug} mode. If you wish to remove a breakpoint, simply right-click on
|
|
it and select \gui{Delete breakpoint} from the context menu.
|
|
|
|
\image qtcreator-setting-breakpoint2.png
|
|
|
|
To view the contents of \c{line}, take a look at the \gui{Locals and
|
|
Watchers} view.
|
|
|
|
\image qtcreator-watcher.png
|
|
|
|
Suppose we modify our \c{on_findButton_clicked()} function to move back to
|
|
the start of the document and continue searching once the cursor hits the
|
|
end of the document. Adding this functionality can be done with the code
|
|
snippet below:
|
|
|
|
\code
|
|
void TextFinder::on_findButton_clicked()
|
|
{
|
|
QString searchString = ui.lineEdit->text();
|
|
|
|
QTextDocument *document = ui.textEdit->document();
|
|
QTextCursor cursor = ui.textEdit->textCursor();
|
|
cursor = document->find(searchString, cursor,
|
|
QTextDocument::FindWholeWords);
|
|
ui.textEdit->setTextCursor(cursor);
|
|
|
|
bool found = cursor.isNull();
|
|
|
|
if (!found && previouslyFound == true) {
|
|
int ret = QMessageBox::question(this, tr("End of Document"),
|
|
tr("I have reached the end of the document. Would you like "
|
|
"me to start searching from the beginning of the document?"),
|
|
QMessageBox::Yes | QMessageBox::No, QMessageBox::Yes);
|
|
|
|
if (ret == QMessageBox::Yes) {
|
|
cursor = document->find(searchString,
|
|
QTextDocument::FindWholeWords);
|
|
ui.textEdit->setTextCursor(cursor);
|
|
} else
|
|
return;
|
|
}
|
|
previouslyFound = found;
|
|
}
|
|
\endcode
|
|
|
|
However, if you compile and run this code, the application will not work
|
|
correctly due to a logic error. To locate this logic error, you can step
|
|
through the code using the following buttons:
|
|
|
|
\image qtcreator-debugging-buttons.png
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-debugging.html
|
|
\page creator-tips.html
|
|
\nextpage creator-glossary.html
|
|
|
|
\title Tips and Tricks
|
|
|
|
\bold{Quickly Switching between Modes}
|
|
|
|
You can quickly switch between modes by pressing \key{Ctrl+1},
|
|
\key{Ctrl+2}, and so on.
|
|
|
|
\bold{Keyboard Shortcuts}
|
|
|
|
Qt Creator provides a lot of useful keyboard shortcuts. A complete list can
|
|
be found \l{Keyboard Shortcuts}{here}.
|
|
|
|
\bold{Running Qt Creator from the Command Line}
|
|
|
|
You can start Qt Creator from a command prompt with the name of an existing
|
|
session or \c{.pro} file by giving the name as argument on the command
|
|
line.
|
|
|
|
\bold{Show and Hide the Sidebar}
|
|
|
|
You can show and hide the the sidebar in \gui Edit and \gui Debug mode by
|
|
clicking on the corresponding icon, or by pressing \key{Alt+0}.
|
|
|
|
\bold{Display Signals and Slots}
|
|
|
|
If you have an instance of a class that is derived from QObject, and you
|
|
you would like to find all other objects connected to one of your object's
|
|
slots using Qt's signals and slots mechanism -- you can enable
|
|
\gui{Use Custom Display for Qt Objects} feature under the \gui Debug menu.
|
|
|
|
In the \gui{Locals and Watchers} view, expand the object's entry and open
|
|
the slot in the \e slots subitem. The objects connected to this slot are
|
|
exposed as children of the slot. This method works with signals too.
|
|
|
|
\bold{Display Low Level Data}
|
|
|
|
If the special debugging of Qt objects fails due to data
|
|
corruption within the debugged objects, you can switch the
|
|
special debugging off in the \gui{Debug} menu. This will make
|
|
the low-level structures visible again.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-tips.html
|
|
\page creator-glossary.html
|
|
\nextpage creator-known-issues.html
|
|
|
|
\title Glossary
|
|
|
|
\table
|
|
\header
|
|
\o Term
|
|
\o Meaning
|
|
|
|
\row
|
|
\o System Qt \target glossary-system-qt
|
|
\o The version of Qt installed on your system. This is the Qt
|
|
version for the \c qmake command found in your \c PATH.
|
|
|
|
\row
|
|
\o Default Qt \target glossary-default-qt
|
|
\o The version of Qt configured in \gui{Tools -> Options -> Qt 4
|
|
-> Default Qt Version}. This is the Qt version used by your
|
|
new projects. It defaults to System Qt.
|
|
|
|
\row
|
|
\o Project Qt \target glossary-project-qt
|
|
\o The version of Qt configured in \gui{Build&Run -> Build
|
|
Settings -> Build Configurations}. This is the Qt version that
|
|
is actually used by a particular project. It defaults to
|
|
Default Qt.
|
|
|
|
\row
|
|
\o Shadow Build \target glossary-shadow-build
|
|
\o Shadow building means building a project in a separate
|
|
directory, the \e{build directory}. The build directory is
|
|
different from the source directory. One of the benefits of
|
|
shadow building is that it keeps your source directory clean.
|
|
Shadow building is the best practice if you need many build
|
|
configurations for a single set of source.
|
|
\endtable
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-glossary.html
|
|
\page creator-keyboard-shortcuts.html
|
|
|
|
\title Keyboard Shortcuts
|
|
|
|
Qt Creator provides various keyboard shortcuts to aid in the development
|
|
process. These shortcuts are listed in the table below:
|
|
|
|
\table
|
|
\header
|
|
\o Function
|
|
\o Key Combination
|
|
|
|
\row
|
|
\o Activate \gui Welcome mode
|
|
\o Ctrl + 1
|
|
\row
|
|
\o Activate \gui Edit mode
|
|
\o Ctrl + 2
|
|
\row
|
|
\o Activate \gui Debug mode
|
|
\o Ctrl + 3
|
|
\row
|
|
\o Activate \gui Projects mode
|
|
\o Ctrl + 4
|
|
\row
|
|
\o Activate \gui Help mode
|
|
\o Ctrl + 5
|
|
\row
|
|
\o Activate \gui Output mode
|
|
\o Ctrl + 6
|
|
\row
|
|
\o Find
|
|
\o Ctrl + F
|
|
\row
|
|
\o Find next
|
|
\o F3
|
|
\row
|
|
\o Go back to the code editor (\gui Edit mode: The first press
|
|
gives the editor focus, without closing secondary windows; the
|
|
second press closes all secondary windows. \gui Debug mode or
|
|
\gui Help mode: Switch to \gui Edit mode.)
|
|
\o Esc
|
|
\row
|
|
\o Go to a line
|
|
\o Ctrl + L
|
|
\row
|
|
\o Start debugging
|
|
\o F5
|
|
\row
|
|
\o Stop debugging
|
|
\o Shift + F5
|
|
\row
|
|
\o Toggle code declaration and definition
|
|
\o F2
|
|
\row
|
|
\o Toggle header file and source file
|
|
\o F4
|
|
\row
|
|
\o Toggle Side Bar
|
|
\o Alt + 0
|
|
\row
|
|
\o Toggle \gui{Build Issues} pane
|
|
\o Alt + 1
|
|
\row
|
|
\o Toggle \gui{Search Results} pane
|
|
\o Alt + 2
|
|
\row
|
|
\o Toggle \gui{Application Output} pane
|
|
\o Alt + 3
|
|
\row
|
|
\o Toggle \gui{Compile Output} pane
|
|
\o Alt + 4
|
|
\endtable
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-keyboard-shortcuts.html
|
|
\page creator-known-issues.html
|
|
|
|
\title Known Issues of Version 0.9.1 (Beta)
|
|
|
|
There are some known issues with Qt Creator 0.9.1 (Beta).
|
|
The development team is aware of those, there is no need to report them as bug.
|
|
|
|
\list
|
|
\o The central editor sometimes loses it "changed" status marker.
|
|
|
|
\o There is a kernel bug essentially making debugging unreliable on
|
|
2.6.24 kernels for i386 (which is, unfortunately, the default on
|
|
Ubuntu 8.04). See
|
|
\l{https://bugs.launchpad.net/ubuntu/+source/gdb/+bug/230315/} for
|
|
details. The only solution to this problem is to boot another
|
|
kernel.
|
|
|
|
\o Gdb may take long to load debugging symbols, especially from large
|
|
libraries like \c libQtWebKit. Starting the debugging module can
|
|
take up to several minutes without visible progress.
|
|
|
|
\o Paths or file names containing spaces or special characters, e.g.,
|
|
colons, dollar signs, hash marks etc. may cause difficulties. This
|
|
is because some of the tools Qt Creator uses in the background have
|
|
restrictions on the characters allowed in file and directory names.
|
|
To be on the safe side, we recomment creating projects and project
|
|
items with names consisting of plain characters, numbers,
|
|
underscores, and hyphens.
|
|
|
|
\o \c{.pro} files are reformatted if files have been added or removed.
|
|
Whitespace is not preserved.
|
|
|
|
\o There is no IDE support for adding files to include (\c .pri) files.
|
|
|
|
\o There is no IDE support for adding/removing sub-projects. Project
|
|
hierarchies (SUBDIRS template) have to be created manually.
|
|
|
|
\o The file system sidebar does not update automatically. As a
|
|
workaround, switch to another directory and then back.
|
|
|
|
\o Loading KDE4 designer plugins breaks the style, due to a bug in KDE.
|
|
|
|
\o Scopes in .pro files are ignored, and environment variables not expanded.
|
|
|
|
\o Code completion for generated UI header files is not updated properly
|
|
after the first time.
|
|
|
|
\o Code completion does not support typedefs (e.g. std::string) and
|
|
private classes (e.g. class MyClass::Data {};).
|
|
|
|
\o On Gnome, after minimizing Qt Creator and restoring again, the
|
|
application window does not repaint properly until resized.
|
|
\endlist
|
|
*/
|
|
|