forked from qt-creator/qt-creator
1892 lines
69 KiB
Plaintext
1892 lines
69 KiB
Plaintext
/*!
|
|
\contentspage{index.html}{Qt Creator}
|
|
\page index.html
|
|
\nextpage creator-quick-tour.html
|
|
|
|
\title Qt Creator Manual
|
|
|
|
\section1 Version 1.2.91
|
|
|
|
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 Please report bugs and suggestions to the
|
|
\l{http://qt.nokia.com/developer/task-tracker}{Qt task tracker}.
|
|
You can also join the Qt Creator mailing list. To subscribe,
|
|
send a message with the word \e subscribe to
|
|
\l{mailto:qt-creator-request@trolltech.com}
|
|
{qt-creator-request@trolltech.com}. For more information on Qt mailing
|
|
lists, visit \l{http://lists.trolltech.com}{http://lists.trolltech.com}.
|
|
|
|
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}: Applications can be debugged
|
|
within Qt Creator using a graphical frontend to the GNU symbolic
|
|
debugger (GDB) and the Microsoft Console Debugger (CDB).
|
|
\endlist
|
|
|
|
To learn more about the Qt Creator, click on one of the links below:
|
|
|
|
|
|
\raw HTML
|
|
<img border="0" style="float:right;" src="images/qtcreator-screenshots.png" />
|
|
\endraw
|
|
|
|
\list
|
|
\o \l{A Quick Tour of Qt Creator}
|
|
\o \l{Creating a Project in Qt Creator}
|
|
\o \l{The Code Editor}
|
|
\o \l{Build Settings}
|
|
\o \l{Qt Version Management}
|
|
\o \l{Writing a Simple Program with Qt Creator}
|
|
\o \l{Qt Creator and Version Control Systems}
|
|
\o \l{Navigating Quickly Around Your Code with Locator}
|
|
\o \l{Session Management in Qt Creator}
|
|
\o \l{Debugging with Qt Creator}
|
|
\o \l{CMake Support in Qt Creator}
|
|
\o \l{Support for Generic Projects in Qt Creator}
|
|
\o \l{Handling External Libraries}
|
|
\o \l{Tips and Tricks}
|
|
\o \l{Keyboard Shortcuts}
|
|
\o \l{Glossary}
|
|
\o \l{Supported Platforms}
|
|
\o \l{Known Issues}
|
|
\o \l{Acknowledgements}
|
|
\endlist
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\page creator-quick-tour.html
|
|
\nextpage creator-code-editor.html
|
|
|
|
\title A Quick Tour of 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 \gui{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-code-editor.html
|
|
\nextpage creator-build-settings.html
|
|
|
|
\title The Code Editor
|
|
|
|
Qt Creator's code editor is designed to aid the developer to create, edit,
|
|
and navigate code. It is fully equipped with syntax highlighting, code
|
|
completion, context sensitive help, as well as inline error indicators
|
|
while you are typing. The screenshots below show the various dialogs within
|
|
which you can configure your editor.
|
|
|
|
\table
|
|
\row
|
|
\i \inlineimage qtcreator-texteditor-fonts.png
|
|
\i \inlineimage qtcreator-texteditor-behavior.png
|
|
\row
|
|
\i \inlineimage qtcreator-texteditor-display.png
|
|
\i \inlineimage qtcreator-texteditor-completion.png
|
|
\endtable
|
|
|
|
The table below lists keyboard shortcuts supported by the code editor.
|
|
|
|
\table
|
|
\row
|
|
\i Block navigation
|
|
\i To navigate between blocks, e.g., from one \bold{\{} to another
|
|
\bold{\}} , use \key{Ctrl+[} and \key{Ctrl+]}.
|
|
\row
|
|
\i Block selection
|
|
\i To select a current block, use \key{Ctrl+U}. Pressing
|
|
\key{Ctrl+U} again extends the selection to the parent block.
|
|
To deselect, use \key{Ctrl+Shift+U}.
|
|
\row
|
|
\i Moving lines up and down
|
|
\i Use \key{Ctrl+Shift+Up} and \key{Ctrl+Shift+Down}
|
|
|
|
\row
|
|
\i Completion
|
|
\i Use \key{Ctrl+Space}
|
|
|
|
\row
|
|
\i Indenting Blocks
|
|
\i Use \key{Ctrl+I}
|
|
|
|
\row
|
|
\i Collapse
|
|
\i Use \key{Ctrl+\<}
|
|
|
|
\row
|
|
\i Commenting or uncommenting blocks
|
|
\i Use \key{Ctrl+\/}
|
|
|
|
\row
|
|
\i Delete a line
|
|
\i Use \key{Shift+Del}
|
|
|
|
\row
|
|
\i Switch between header file and source file
|
|
\i Use \key{F4}.
|
|
|
|
\row
|
|
\i Increasing and decreasing font size
|
|
\i Use \key{Ctrl+Scroll Wheel}
|
|
|
|
\row
|
|
\i Follow symbols under the cursor
|
|
\i Use \key{F2} and \key{Shift+F2}. This feature works with
|
|
namespaces, classes, methods, variables, include statements,
|
|
and macros.
|
|
|
|
\row
|
|
\i Switch to an external editor
|
|
\i Select \gui{Open in external editor} from the
|
|
\gui{Edit -> Advanced} menu.
|
|
\endtable
|
|
|
|
\section1 Code Completion
|
|
|
|
The completion popup shows possible completions to a certain statement.
|
|
These completions include classes, namespaces, functions, variables,
|
|
macros and keywords. Listed below are the icons used in the completion box
|
|
and their meaning.
|
|
|
|
\table
|
|
\row
|
|
\i \inlineimage completion/class.png
|
|
\i A class
|
|
\row
|
|
\i \inlineimage completion/enum.png
|
|
\i An enum
|
|
\row
|
|
\i \inlineimage completion/enumerator.png
|
|
\i An enumerator (value of an enum)
|
|
\row
|
|
\i \inlineimage completion/func.png
|
|
\i A function
|
|
\row
|
|
\i \inlineimage completion/func_priv.png
|
|
\i A private function
|
|
\row
|
|
\i \inlineimage completion/func_prot.png
|
|
\i A protected function
|
|
\row
|
|
\i \inlineimage completion/var.png
|
|
\i A variable
|
|
\row
|
|
\i \inlineimage completion/var_priv.png
|
|
\i A private variable
|
|
\row
|
|
\i \inlineimage completion/var_prot.png
|
|
\i A protected variable
|
|
\row
|
|
\i \inlineimage completion/signal.png
|
|
\i A signal
|
|
\row
|
|
\i \inlineimage completion/slot.png
|
|
\i A slot
|
|
\row
|
|
\i \inlineimage completion/slot_priv.png
|
|
\i A private slot
|
|
\row
|
|
\i \inlineimage completion/slot_prot.png
|
|
\i A protected slot
|
|
\row
|
|
\i \inlineimage completion/keyword.png
|
|
\i A keyword
|
|
\row
|
|
\i \inlineimage completion/macro.png
|
|
\i A macro
|
|
\row
|
|
\i \inlineimage completion/namespace.png
|
|
\i A namespace
|
|
\endtable
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-code-editor.html
|
|
\page creator-build-settings.html
|
|
\nextpage creator-version-management.html
|
|
|
|
\title Build Settings
|
|
|
|
\table
|
|
\row
|
|
\i \note This page describes Qt Creator's support for \c qmake.
|
|
For information on CMake support, see
|
|
\l{CMake Support in Qt Creator}.
|
|
\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, for instance.
|
|
|
|
\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 set 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.
|
|
|
|
\section1 Dependencies
|
|
|
|
If you have multiple projects loaded in your session, you can configure
|
|
dependencies between them. This will affect the build order of your
|
|
projects. To do this, go the the \bold{Dependencies} tab after selecting
|
|
the project for which you want to configure the dependencies, and then use
|
|
the checkboxes to check which of the other projects is a dependency.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-build-settings.html
|
|
\page creator-version-management.html
|
|
\nextpage creator-creating-project.html
|
|
|
|
\title 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{Auto-detected 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-version-management.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-version-control.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 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 you use Visual Studio to compile Qt, all environment variables set
|
|
in Visual Studio will be set for 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. If
|
|
your project is not yet loaded, you can load it by selecting \gui{Open}
|
|
from the \gui{File} menu.
|
|
|
|
In your project 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}
|
|
(named lineEdit), \l{http://doc.trolltech.com/qpushbutton.html}{QPushButton}
|
|
(named findButton), and a
|
|
\l{http://doc.trolltech.com/qtextedit.html}{QTextEdit} (named textEdit).
|
|
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:
|
|
|
|
\snippet examples/textfinder/textfinder.h 0
|
|
|
|
\note The \c{Ui::TextFinder} 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:
|
|
|
|
\snippet examples/textfinder/textfinder.cpp 0
|
|
|
|
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()}
|
|
which requires adding the following additional #includes to textfinder.cpp:
|
|
|
|
\snippet examples/textfinder/textfinder.cpp 1
|
|
|
|
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:
|
|
|
|
\snippet examples/textfinder/textfinder.cpp 2
|
|
|
|
Once we have both these functions complete, we call \c{loadTextFile()} in
|
|
our constructor.
|
|
|
|
\snippet examples/textfinder/textfinder.cpp 3
|
|
|
|
The \c{on_findButton_clicked()} slot will be called automatically due to
|
|
this line of code:
|
|
|
|
\code
|
|
QMetaObject::connectSlotsByName(TextFinder);
|
|
\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-version-control.html
|
|
\nextpage creator-navigation.html
|
|
|
|
\title Qt Creator and Version Control Systems
|
|
|
|
\table
|
|
\caption Version control systems supported by Qt Creator
|
|
\row
|
|
\i \bold{git}
|
|
\i \l{http://git-scm.com/}
|
|
\i
|
|
\row
|
|
\i \bold{Subversion}
|
|
\i \l{http://subversion.tigris.org/}
|
|
\i
|
|
\row
|
|
\i \bold{Perforce}
|
|
\i \l{http://www.perforce.com}
|
|
\i Server version 2006.1 and later
|
|
\endtable
|
|
|
|
|
|
\section1 Setup
|
|
|
|
Qt Creator uses the version control system's command line clients to
|
|
access your repositories. To set it up, you must ensure that these command
|
|
line clients can be located via the \c{PATH} environment variable. You can
|
|
specify the path to the command line client's executable in the settings
|
|
pages that can be found under \gui{Options...} in the \gui{Tools} menu.
|
|
|
|
|
|
\section1 Usage
|
|
|
|
You can find the version control menu entries in a sub-menu of the
|
|
\gui{Tools} menu. The version control system displayed here is the system
|
|
that manages the current project.
|
|
|
|
Each version control system adds a pane to the \gui{Application Output}
|
|
panes within which it will log the commands it executes, prepended by a
|
|
timestamp and the relevant output.
|
|
|
|
\image qtcreator-vcs-pane.png
|
|
|
|
|
|
\section2 Addings Files
|
|
|
|
When you create a new file or a new project, the wizards will display page
|
|
requesting whether the files should be added to a version control system.
|
|
This depends on whether the parent directory or the project is already
|
|
under version control and the system supports the concept of adding files,
|
|
e.g., \bold{Perforce} and \bold{Subversion}. Alternatively, you can also
|
|
add files later on using the version control tool menus.
|
|
|
|
With \bold{git}, there is no concept of adding files. Instead, all modified
|
|
files must be \e{staged} for a commit.
|
|
|
|
|
|
\section2 Viewing Diff Output
|
|
|
|
All version control systems provide menu options to \e{diff} the current
|
|
file or project - comparing with the latest version stored in the
|
|
repository and displaying the differences. In Qt Creator, a diff is
|
|
displayed in a read-only editor. If the file is accessible, you can double
|
|
-click on a selected diff chunk and Qt Creator will open an editor
|
|
displaying the file, scrolled to the line in question.
|
|
|
|
\image qtcreator-vcs-diff.png
|
|
|
|
|
|
\section2 Viewing Versioning History and Change Details
|
|
|
|
The versioning history of a file can be displayed by selecting the
|
|
\gui{Log} (for \bold{git}) or \gui{Filelog} (for \bold{Perforce} and
|
|
\bold{Subversion}) option. Typically, the log output will contain the
|
|
date, the commit message, and a change or revision identifier. If you
|
|
click on the identifier, a description of the change including the diff
|
|
will be displayed.
|
|
|
|
\image qtcreator-vcs-log.png
|
|
\image qtcreator-vcs-describe.png
|
|
|
|
|
|
\section2 Annotating Files
|
|
|
|
Annotation views are obtained by selecting \gui{Annotate} or \gui{Blame}.
|
|
This will display the lines of the file prepended by the change identifier
|
|
they originate from. Clicking on the change identifier shows a detailed
|
|
description of the file.
|
|
|
|
|
|
\section2 Committing Changes
|
|
|
|
Once you have finished making changes, you can submit them to the version
|
|
control system by choosing \gui{Commit} or \gui{Submit}. Qt Creator will
|
|
display a commit page containing a text editor, where you can enter your
|
|
commit message, and a checkable list of modified files to be included.
|
|
When you are done, click \gui{Commit} to start committing. In addition,
|
|
there is a \gui{Diff selected} button that brings up a diff view of the
|
|
files selected in the file list. Since the commit page is just another
|
|
editor, you can go back to it by closing the diff view. Alternatively, you
|
|
can view it from the editor combo box showing the \gui{Opened files}.
|
|
|
|
\image qtcreator-vcs-commit.png
|
|
|
|
|
|
\section2 Menu Entries Specific to git
|
|
|
|
The git sub-menu contains additional entries:
|
|
|
|
\table
|
|
\row
|
|
\i \gui{Stash}
|
|
\i Stash local changes prior to executing a \bold{pull}.
|
|
\row
|
|
\i \gui{Pull}
|
|
\i Pull changes from the remote repository. If there are locally
|
|
modified files, you will be prompted to stash those changes.
|
|
\row
|
|
\i \gui{Branches...}
|
|
\i Displays the branch dialog showing the local branches at the
|
|
top and remote branches at the bottom. To switch to the local
|
|
branch, simply double-click on it. Double-clicking on a remote
|
|
branch will first create a local branch with the same name that
|
|
tracks the remote branch, and then switch to it.
|
|
|
|
\image qtcreator-vcs-gitbranch.png
|
|
\endtable
|
|
|
|
\section2 Common options
|
|
|
|
The \gui{Version Control/Common} settings page features common settings for
|
|
version control systems, such as commit message line wrapping and checking
|
|
options.
|
|
|
|
\gui{Submit message checking script} is a script or program that can be
|
|
used to perform checks on the submit message before submitting. The submit
|
|
message is passed in as the script's first parameter. If there is an error,
|
|
the script should output a message on standard error and return a non-zero
|
|
exit code.
|
|
|
|
\gui{User/alias configuration file} takes a file in mailmap format that
|
|
lists user names and aliases. For example:
|
|
|
|
\code
|
|
Jon Doe <Jon.Doe@company.com>
|
|
Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
|
|
\endcode
|
|
|
|
Notice that the second line specifies the alias \e{hm} and the
|
|
corresponding email address for \e{Hans Mustermann}. If the user/alias
|
|
configuration file is present, the submit editor will display a context
|
|
menu with \gui{Insert name...} that will pop up a dialog letting the user
|
|
select a name.
|
|
|
|
\gui{User field configuration file} is a simple text file consisting of
|
|
lines specifying submit message fields that take user names, for example:
|
|
|
|
\code
|
|
Reviewed-by:
|
|
Signed-off-by:
|
|
\endcode
|
|
|
|
These fields will appear below the submit message. They provide completion
|
|
for the aliases/public user names specified in the
|
|
\e{User/alias configuration file} as well as a button that opens the
|
|
aforementioned user name dialog.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-version-control.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 the 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 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-session.html
|
|
\nextpage creator-debugging.html
|
|
|
|
\title Session Management in Qt Creator
|
|
|
|
In Qt Creator, a session is a collection of:
|
|
|
|
\list
|
|
\o open projects together with their dependencies,
|
|
\o open editors,
|
|
\o breakpoints and watches, as well as
|
|
\o bookmarks
|
|
\endlist
|
|
|
|
When you run Qt Creator, you have a default session. You can create a new
|
|
session using the \gui{Session Manager...} option, available in the
|
|
\gui{File -> Session} menu.
|
|
|
|
|
|
\image qtcreator-session-manager.png
|
|
|
|
|
|
To switch between sessions, select \gui{File -> Session}. If you do not
|
|
create and select any session, Qt Creator will always use the default
|
|
session.
|
|
|
|
\image qtcreator-session-menu.png
|
|
|
|
When you launch Qt Creator, a list of your recent sessions will be
|
|
displayed on the \gui{Welcome Screen}.
|
|
|
|
\image qtcreator-welcome-session.png
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-navigation.html
|
|
\page creator-debugging.html
|
|
\nextpage creator-cmake-support.html
|
|
|
|
\title Debugging with Qt Creator
|
|
|
|
|
|
\section1 Introduction
|
|
|
|
Qt Creator does not have its own debugger. Instead, it provides a graphical
|
|
frontend to various debugger engines:
|
|
|
|
\table
|
|
\header
|
|
\o Platform
|
|
\o Compiler
|
|
\o Debugger Engine
|
|
\row
|
|
\o Linux, Unixes, Mac OS
|
|
\o gcc
|
|
\o GNU Symbolic Debugger (gdb)
|
|
\row
|
|
\o Windows/MinGW
|
|
\o gcc
|
|
\o GNU Symbolic Debugger (gdb)
|
|
\row
|
|
\o Windows
|
|
\o Microsoft Visual C++ Compiler
|
|
\o Debugging Tools for Windows/Microsoft Console Debugger (CDB)
|
|
\endtable
|
|
|
|
The 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 the engine 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 Debugger Engine Installation Notes
|
|
|
|
\table
|
|
\header
|
|
\o Debugger Engine
|
|
\o Notes
|
|
\row
|
|
\o Gdb
|
|
\o Requires gdb version 6.8.
|
|
\row
|
|
\o Debugging Tools for Windows
|
|
\o Using this engine requires you to install the
|
|
\e{Debugging Tools for Windows}
|
|
\l{http://www.microsoft.com/whdc/devtools/debugging/installx86.Mspx}{32-bit}
|
|
or
|
|
\l{http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx}{64-bit}
|
|
package (Version 6.10 for the 32-bit or the 64-bit version of Qt Creator, respectively),
|
|
which is freely available for download from the
|
|
\l{http://msdn.microsoft.com/en-us/default.aspx}
|
|
{Microsoft Developer Network}.
|
|
|
|
The pre-built \e{Qt SDK for Windows} will make use
|
|
of the library if it is present on the system. When building Qt
|
|
Creator using the Microsoft Visual C++ Compiler, the
|
|
\c{"%ProgramFiles%\Debugging Tools for Windows"} path will be
|
|
checked to ensure that all required header files are there.
|
|
\endtable
|
|
|
|
|
|
\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 Debugger, \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, interrupts 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 interrupt -- 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 can 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.
|
|
|
|
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 interrupted, 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
|
|
grayed 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 was interrupted before entering the
|
|
function.
|
|
|
|
|
|
\section2 Threads
|
|
|
|
If a multi-threaded program is interrupted, 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:}
|
|
|
|
\row
|
|
\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.
|
|
|
|
\row
|
|
\i The debug information provided by gcc does not include enough
|
|
information about the time when a variable is initialized.
|
|
Therefore, Qt Creator 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 interrupted. To do so, click on the \gui Value column, modify the value
|
|
with the inplace editor, and hit \key Enter (or \key Return).
|
|
|
|
\note The set of watched items is saved within your session.
|
|
|
|
|
|
\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 triggered 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 Debugging Helper Library
|
|
|
|
While debugging Qt Creator dynamically loads a helper library into your
|
|
program. This helper library enables Qt Creator to pretty print Qt and STL
|
|
types. The Qt SDK package already contains a prebuilt debugging helper
|
|
library. To create a debugging helper library, select the \gui{Options}
|
|
from the \gui{Tools} menu, and go to the \gui{Qt/Qt Versions} pane. As the
|
|
internal layout of qt can change between versions, the debugging helper
|
|
library is built for each Qt version.
|
|
|
|
|
|
\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) {
|
|
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-cmake-support.html
|
|
\nextpage creator-generic-projects.html
|
|
|
|
\title CMake Support in Qt Creator
|
|
|
|
Since Qt Creator 1.1, support for \c CMake project files is available.
|
|
|
|
|
|
\section1 Opening CMake Projects
|
|
|
|
To open a \c CMake project select \gui Open from the \gui File menu and
|
|
select the \c{CMakeLists.txt} file from your \c CMake project. A wizard
|
|
will guide you with the rest of the process. If the \c CMake project does
|
|
not have an in-place build, Qt Creator lets you specify the directory in
|
|
which the project is built (shadow build).
|
|
|
|
\image qtcreator-cmake-import-wizard1.png
|
|
|
|
The screenshot below shows how you can specify command line arguments to
|
|
\c CMake for your project.
|
|
|
|
\image qtcreator-cmake-import-wizard2.png
|
|
|
|
Normally, there is no need to pass any command line arguments for projects
|
|
that are already built, as \c CMake caches that information.
|
|
|
|
|
|
\section1 Building CMake Projects
|
|
|
|
Qt Creator builds \c CMake Projects by running \c make or \c mingw32-make,
|
|
depending on your platform. The build errors and warnings are parsed and
|
|
displayed in the \gui{Build Issues} output pane.
|
|
|
|
By default Qt Creator builds the \e{all} target. You can specify which
|
|
targets to build in \gui{Project} mode, under \gui{Build Settings}.
|
|
|
|
\image qtcreator-cmake-build-settings.png
|
|
|
|
Qt Creator supports multiple build configurations. Also, the build
|
|
directory can be modified after the initial import.
|
|
|
|
|
|
\section1 Running CMake Projects
|
|
Qt Creator automatically adds \gui{Run Configurations} for all targets
|
|
specified in the \c CMake project file.
|
|
|
|
Known issues for the current version can be found
|
|
\l{Known Issues of Version 1.1.0}{here}.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-cmake-support.html
|
|
\page creator-generic-projects.html
|
|
\nextpage creator-external-library-handling.html
|
|
|
|
\title Support for Generic Projects in Qt Creator
|
|
|
|
Since Qt Creator 1.1, generic projects are supported, in addition to
|
|
\c qmake projects. In other words, you can import existing projects that do
|
|
not use \c qmake or \c CMake and Qt Creator will simply ignore your build
|
|
system.
|
|
|
|
This feature lets you use Qt Creator as a code editor. You can change the
|
|
way your project is built by modifying the \c make command under
|
|
\gui{Build Settings} in the \gui{Projects} mode.
|
|
|
|
For a generic project, you have to manually specify which files belong to
|
|
your project and which include directories/defines you want to pass to your
|
|
compiler.
|
|
|
|
|
|
\section2 Specifying Files
|
|
|
|
The list of files for a generic project is specified in the \c{.files}
|
|
file. When you first create a generic project, Qt Creator will add any
|
|
files it recognizes to your project. To add or remove files later, simply
|
|
edit the \c{.files} file in Qt Creator. Your project tree will be refreshed
|
|
when you save this file. You can also add or remove files using the context
|
|
menu in the project tree.
|
|
|
|
If you frequently need to update the \c{.files} file, we recommend the use
|
|
of a small script that will update the files for you. Currently, if the
|
|
file is modified externally, Qt Creator must be restarted for the changes
|
|
to take effect.
|
|
|
|
|
|
\section2 Specifying Include Paths
|
|
|
|
The include paths are specified in the \c{.includes} file, one include
|
|
path per line. The paths can be either absolute or relative to the
|
|
\c{.includes} file.
|
|
|
|
\section2 Specifying Defines
|
|
|
|
The defines are specified in the \c{.config} file. This file is a regular
|
|
C++ file, prepended to all your source files when they are being parsed.
|
|
However, you should only use it to add lines like the following:
|
|
|
|
\code
|
|
#define NAME value
|
|
\endcode
|
|
|
|
|
|
\section2 Creating a Run Configuration
|
|
|
|
Qt Creator cannot automatically determine which executable it should run.
|
|
To set up a custom executable run configuration in the \gui Projects mode,
|
|
use the \bold{Add} button. Here you can specify the name, executable, and
|
|
some optional arguments. By default, the working directory is
|
|
\c{$BUILDDIR} which should work fine.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-generic-projects.html
|
|
\page creator-external-library-handling.html
|
|
\nextpage creator-tips.html
|
|
|
|
\title Handling External Libraries
|
|
|
|
The ability to recognize external libraries is not only important for the
|
|
underlying build system, but also for Qt Creator itself. This ability
|
|
allows Qt Creator to support code completion and syntax highlighting for
|
|
external libraries as if they were part of the current project or the Qt
|
|
library.
|
|
|
|
The procedure of adding a library to a project, depends on the type of
|
|
project, which influences the build system used. The following sections
|
|
describe the the procedure required for each project type.
|
|
|
|
|
|
\section1 QMake Projects (the default)
|
|
|
|
Open your project file (\c{.pro}) from the \gui{Projects} pane. Then,
|
|
follow the guidelines in the
|
|
\l{http://doc.trolltech.com/latest/make-project-files.html#declaring-other-libraries}
|
|
{Declaring other Libraries} section of the Qt documentation.
|
|
|
|
If your project successfully builds and links against the external library,
|
|
syntax completion and highlighting should work.
|
|
|
|
|
|
\section1 CMake Projects
|
|
|
|
In CMake, libraries are usually detected using the \c{FIND_PACKAGE()}
|
|
macro. A couple of them are already being shipped with CMake, they can be
|
|
found in the \c{Modules} directory of your CMake installation. If you
|
|
provide libraries on your own, you will need to provide your own
|
|
\c{FindFoo.cmake} file. Refer to the
|
|
\l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}
|
|
for details.
|
|
|
|
As with \c qmake projects, syntax completion and highlighting should work
|
|
if you can sucessfully build and link against the external library.
|
|
|
|
|
|
\section1 Generic Projects
|
|
|
|
If you import a project using the \e{Generic Projects} function, Qt Creator
|
|
will create a file called \c{<projectname>.includes} in your project root
|
|
directory. This file contains all project subdirectories which Qt Creator
|
|
could find relevant headers for. Simply add your include pathes here.
|
|
|
|
In \gui{Generic Project} mode, Qt Creator will not modify any project
|
|
settings, so the above is merely a hint for code completion and syntax
|
|
highlighting.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-external-library-handling.html
|
|
\page creator-tips.html
|
|
\nextpage creator-keyboard-shortcuts.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. Some useful
|
|
shortcuts 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
|
|
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 special debugging of Qt objects fails due to data corruption within the
|
|
debugged objects, you can switch the debugging helpers off in the
|
|
\gui{Debugger -> Debugging Helper} options dialog.
|
|
This will make the low-level structures visible again.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-tips.html
|
|
\page creator-keyboard-shortcuts.html
|
|
\nextpage creator-glossary.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 Navigate between pages
|
|
\o Alt + Left, Alt + Right
|
|
\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-glossary.html
|
|
\nextpage creator-supported-platforms.html
|
|
|
|
\title Glossary
|
|
|
|
\table
|
|
\header
|
|
\o Term
|
|
\o Meaning
|
|
|
|
\row
|
|
\o
|
|
\raw HTML
|
|
Auto-detected Qt
|
|
\endraw
|
|
\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
|
|
\raw HTML
|
|
Default Qt
|
|
\endraw
|
|
\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 the Auto-detected Qt.
|
|
|
|
\row
|
|
\o
|
|
\raw HTML
|
|
Project Qt
|
|
\endraw
|
|
\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
|
|
\raw HTML
|
|
Shadow Build
|
|
\endraw
|
|
\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-supported-platforms.html
|
|
\nextpage creator-known-issues.html
|
|
|
|
\title Supported Platforms
|
|
|
|
Qt Creator is available in binary packages for the following platforms:
|
|
|
|
\list
|
|
\o Windows XP Service Pack 2
|
|
\o Windows Vista
|
|
\o (K)Ubuntu Linux 5.04
|
|
\o (K)Ubuntu Linux 7.04 32bit and 64 bit
|
|
\o Mac OS 10.4 and later
|
|
\endlist
|
|
|
|
\note Building the sources requires \bold{Qt 4.5.0} or later.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-supported-platforms.html
|
|
\page creator-known-issues.html
|
|
\nextpage creator-acknowledgements.html
|
|
|
|
\title Known Issues
|
|
|
|
There are some known issues with Qt Creator.
|
|
The development team is aware of those, there is no need to report them as bug.
|
|
|
|
\section1 Known Issues of Version 1.2.91
|
|
|
|
\list
|
|
\o Gdb on Windows may not work if the 'Embassy \reg Security Center' software
|
|
by 'Wave \reg Systems' is installed and active (causing crashes in \c{vxvault.dll)}).
|
|
|
|
\o Only simple data types (POD) work in the Watch Window of CDB.
|
|
|
|
\o Qt Creator uses SQLite for storing some of its settings. SQLite is
|
|
known to have problems with certain NFS servers (most notably the
|
|
nfs-user-server 2.2beta), since they can lock up the application
|
|
when it tries to lock the database. If your home directory is on an
|
|
NFS share and you encounter this issue, one option would be to
|
|
switch to the nfs-kernel-server, or create a symlink so that the
|
|
settings are stored locally.
|
|
\endlist
|
|
|
|
\section1 Known Issues of Version 1.1.0
|
|
|
|
\list
|
|
\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 recommend 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 in KDE < 4.2.1
|
|
due to a bug in KDE.
|
|
|
|
\o The DEFINES and INCLUDES set in \c{.pro} files are not dealt with
|
|
on a file-specific level. Because of this, handling of DEFINES has
|
|
been disabled completely. Also the \c{.qmake.cache} is not being
|
|
parsed. In general, the \c{.pro} file parser is incomplete and
|
|
problems are still to be expected.
|
|
|
|
\o Code completion for generated UI header files is updated only
|
|
after a build.
|
|
|
|
\o Code completion does not support typedefs for nested classes.
|
|
|
|
\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 Setting breakpoints in files that do not have unique absolute
|
|
paths may fail. For example, remounting parts of a file system
|
|
using the --bind mount option.
|
|
|
|
\o There is no syntax highlighting for \c CMake project files.
|
|
|
|
\o Project files included from \c{CMakeLists.txt} are not shown in the
|
|
navigation tree.
|
|
|
|
\o Using the Visual Studio Compiler with \c CMake is unsupported.
|
|
|
|
\o Creating new \c CMake projects with Qt Creator is unsupported.
|
|
|
|
\o Having more than one build directory for \c CMake is not supported.
|
|
|
|
\o Changing the build directory for \c CMake after the initial import
|
|
is disabled.
|
|
\endlist
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-known-issues.html
|
|
\page creator-acknowledgements.html
|
|
|
|
\title Acknowledgements
|
|
|
|
\section1 Third-party Components
|
|
|
|
Qt Creator contains the following third-party components:
|
|
|
|
\list
|
|
\o \bold{Open Source front-end for C++ (license MIT)}, enhanced for use in
|
|
Qt Creator.\br
|
|
Roberto Raggi <roberto.raggi@gmail.com>\br
|
|
QtCreator/src/shared/cplusplus
|
|
\endlist
|
|
*/
|