/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************
/*!
\contentspage{index.html}{Qt Creator}
\page index.html
\nextpage creator-overview.html
\title Qt Creator Manual
\section1 Version 2.0.92
Qt Creator provides a cross-platform, complete integrated development
environment (IDE) for application developers to create applications for
multiple desktop and mobile device platforms. It is available for Linux,
Mac OS X and Windows operating systems. For more information, see
\l{Operating Systems and Supported Platforms}.
\note Please report bugs and suggestions to the
\l{http://bugreports.qt.nokia.com}{Qt Bug 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 about Qt mailing
lists, visit \l{http://lists.trolltech.com}{http://lists.trolltech.com}.
\raw HTML
\endraw
\list
\o \l{Introducing Qt Creator}
\o \l{Operating Systems and Supported Platforms}
\o \l{Qt Creator User Interface}
\o \l{Getting Started}
\list
\o \l{Building and Running an Example Application}
\o \l{Creating a Qt C++ Application}
\o \l{Creating a Mobile Application with Nokia Qt SDK}
\o \l{Creating a Qt Quick Application}
\endlist
\o \l{Managing Projects}
\list
\o \l{Creating a Project}
\o \l{Setting Up a qmake Project}
\o \l{Adding Libraries to qmake Projects}
\o \l{Setting Up a CMake Project}
\o \l{Setting Up a Generic Project}
\o \l{Setting Up Development Environment for Maemo}
\o \l{Setting Up Development Environment for Symbian}
\o \l{Managing Sessions}
\o \l{Adding New Custom Wizards}
\endlist
\o \l{Using the Editor}
\list
\o \l{Finding and Replacing}
\o \l{Refactoring}
\o \l{Using Qt Quick Toolbars}
\o \l{Searching With the Locator}
\o \l{Pasting and Fetching Code Snippets}
\o \l{Configuring the Editor}
\o \l{Using FakeVim Mode}
\o \l{Using an External Editor}
\endlist
\o \l{Developing Application UI}
\list
\o \l{Optimizing Applications for Mobile Devices}
\o \l{Adding Qt Designer Plugins}
\if defined(qtquick)
\o \l{Developing Qt Quick Applications}
\list
\o \l {Creating Qt Quick Projects}
\o \l {Creating Components}
\o \l {Creating Screens}
\o \l {Animating Screens}
\o \l {Adding User Interaction Methods}
\o \l {Implementing Application Logic}
\endlist
\endif
\endlist
\o \l{Building and Running Applications}
\list
\o \l{Building for and Running on Multiple Targets}
\o \l{Specifying Build Settings}
\o \l{Specifying Run Settings}
\o \l{Specifying Editor Settings}
\o \l{Specifying Dependencies}
\endlist
\o \l{Debugging}
\list
\o \l{Debugging the Example Application}
\o \l{Interacting with the Debugger}
\o \l{Setting Up Debugger}
\o \l{Debugger Modes of Operation}
\o \l{Using Debugging Helpers}
\endlist
\o \l{Using the Maemo Emulator}
\o \l{Using Version Control Systems}
\o \l{Creating Task List Files}
\o \l{Using Command Line Options}
\o \l{Getting Help}
\o \l{Tips and Tricks}
\o \l{Keyboard Shortcuts}
\o \l{Known Issues}
\o \l{Glossary}
\o \l{Acknowledgements}
\endlist
*/
/*!
\contentspage index.html
\previouspage index.html
\page creator-overview.html
\nextpage creator-os-supported-platforms.html
\title Introducing Qt Creator
Qt Creator is an integrated development environment (IDE) that provides you with
tools to design and develop complex applications for multiple desktop and mobile
platforms.
\image qtcreator-overview.png "Qt Creator overview"
\section1 Cross-platform Development
One of the major advantages of Qt Creator is that it allows a team of developers
to share a project across different development platforms with a common tool
for development and debugging.
The recommended way to build a project is to use a version control system.
Store and edit only project source files and the .pro and .pri files (for qmake)
or CMakeLists.txt and *.cmake files (for CMake). Do not store
files generated by the build system or Qt Creator, such as makefiles,
.pro.user, and object files. Other approaches are possible,
but we recommend that you do not use network resources, for example.
Qt Creator allows you to specify separate build settings
for each development platform. By default, \l{glossary-shadow-build}{shadow builds} are used to
keep the build specific files separate from the source.
You can create separate versions of project files to keep platform-dependent
code separate. You can use qmake
\l{http://qt.nokia.com/doc/4.7/qmake-tutorial.html#adding-platform-specific-source-files}{scopes}
to select the file to process depending on which platform qmake is run on.
Items such as open files, breakpoints, and watches are stored in
sessions. They are not considered to be part of the
information shared across platforms.
Qt Creator is integrated with cross-platform systems for build automation:
qmake and CMake. In addition, you can import generic projects that do not use qmake
or CMake, and specify that Qt Creator ignores your build system.
In addition to Qt libraries, you can link your application to other
libraries, such as system libraries or your own libraries. Further, your
own libraries might link to other libraries. To be able to compile your
project, you must add the libraries to your project. This also enables
code completion and syntax highlighting for the libraries.
The procedure of adding a library to a project depends on the the build
system that you use.
Qt Creator provides support for building and running Qt applications for
desktop environment and mobile devices. When you install the Nokia Qt SDK,
the build and run settings for the Maemo and Symbian targets are set up
automatically. However, you need to install and configure some additional software
on the devices.
\note The only supported build system for mobile applications in Qt
Creator is qmake.
Once your mobile application is ready, you can test it in the Qt Simulator.
You can also connect Maemo and Symbian devices to your development PC and
debug applications on the devices. After you have tested the application,
you can deploy it on mobile devices.
Developing applications for mobile devices is different from developing
desktop applications. For more information, see
\l{Optimizing Applications for Mobile Devices}.
\section1 Projects
But why do you need projects? To be able to build and run applications,
Qt Creator needs the same information as a compiler would need. This information
is specified in the project build and run settings.
Creating a project allows you to:
\list
\o Group files together
\o Add custom build steps
\o Include forms and resource files
\o Specify settings for running applications
\endlist
You can either create a project from scratch or import an existing
project. Qt Creator generates all the necessary files, depending on the type of
project you create. For example, if you choose to create a graphical user
interface (GUI) application, Qt Creator generates an empty .ui file
that you can modify with the integrated \QD.
Qt Creator is integrated with cross-platform systems for build automation: qmake and
CMake. In addition, you can import generic projects that do not use qmake or CMake,
and specify that Qt Creator ignores your build system.
\section1 Editors
Qt Creator comes with a code editor and two integrated visual editors for designing
and building
graphical user interfaces (GUIs) from Qt widgets.
\section2 Code Editor
As an IDE, Qt Creator differs from a text editor in that it knows how to build and run
applications. It understands the C++ and QML languages as code, not just as plain text. This allows
it to:
\list
\o Enable you to write well formatted code
\o Anticipate what you are going to write and complete the code
\o Display inline error and warning messages
\o Enable you to semantically navigate to classes, functions, and symbols
\o Provide you with context-sensitive help on classes, functions, and symbols
\o Rename symbols in an intelligent way, so that other symbols with the same name
that belong to other scopes are not renamed
\o Show you the locations in code where a function is declared or called
\endlist
\section2 UI Designer
Qt Creator provides two integrated visual editors, \QD and \QMLD.
\QD is a tool for designing and building graphical user interfaces (GUIs) from
Qt widgets. You can compose and customize your widgets or dialogs and test
them using different styles and resolutions.
Widgets and forms created with \QD are integrated seamlessly with programmed code,
using the Qt signals and slots mechanism, that lets you easily assign behavior to
graphical elements. All properties set in \QD can be changed dynamically within the code.
Furthermore, features like widget promotion and custom plugins allow you to use your
own widgets with \QD.
UIs that use widgets are clearly structured and enforce a platform look and feel,
which makes them useful for traditional applications. However, they are static, and
do not fully make use of the large high-resolution screens, touch input, and significant
graphics power that are becoming common in portable consumer devices, such as mobile
phones, media players, set-top boxes, and netbooks.
\QMLD allows you to easily develop animations by using a declarative programming
language called \l {http://doc.qt.nokia.com/4.7/qtquick.html}{QML}.
In QML, a user interface is specified as a tree of objects with properties.
You use a visual editor to create items, screens, and applications, as well as define changes
in their state, transitions from one state to another, and user actions that change the
states. \QMLD generates the necessary code for you.
You can use Qt or JavaScript to implement the application logic.
\section1 Languages
You can use the code editor to write code in Qt C++ or in the
\l {http://doc.qt.nokia.com/4.7/qtquick.html}{QML} declarative
programming language.
\section2 QML
You can use QML to build highly dynamic, custom user interfaces from a rich set
of QML elements. Qt Quick helps programmers and designers collaborate to build the
fluid user interfaces that are becoming common in portable consumer devices, such as
mobile phones, media players, set-top boxes and netbooks.
QML is an extension to JavaScript, that provides a mechanism to declaratively build
an object tree of QML elements. QML improves the integration between JavaScript and
Qt's existing QObject based type system, adds support for automatic property bindings
and provides network transparency at the language level.
\section1 Targets
Qt Creator provides support for building and running Qt applications for
desktop environment (Windows, Linux, and Mac OS) and mobile devices (Symbian, Maemo,
and MeeGo). Build settings allow you to quickly switch between build targets.
When you build an application for a mobile device target with a device
connected to the development PC, Qt Creator generates an installation package,
installs in on the device, and executes it.
You can publish the installation packages on the \l{https://publish.ovi.com/info/}{Ovi Store}.
For Symbian devices, the packages must be signed.
\section1 Tools
Qt Creator is integrated with a set of helpful tools, such as version control
systems and Qt Simulator.
\section2 Version Control Systems
Qt Creator uses the version control system's command line clients to access
your repositories. The following version control systems are supported:
\list
\o Git
\o Subversion
\o Perforce
\o CVS
\o Mercurial
\endlist
The functions available to you in Qt Creator depend on the version control
system. Basic functions are available for all the supported systems. They include
comparing files with the latest versions stored in the repository and displaying the
differences, viewing versioning history and change details, annotating files,
and committing and reverting changes.
\section2 Qt Simulator
You can use the Qt Simulator to test Qt applications that are intended
for mobile devices in an environment similar to that of the device. You
can change the information that the device has about its configuration
and environment.
The Qt Simulator is installed as part of the Nokia Qt SDK. After it is
installed, you can select it as a build target in Qt Creator.
\section1 Debuggers
Qt Creator does not include a debugger. It provides a debugger plugin that acts
as an interface between the Qt Creator core and external native debuggers:
\list
\o GNU Symbolic Debugger (gdb)
\o Microsoft Console Debugger (CDB)
\o internal Java Script debugger
\endlist
You can use the Qt Creator \gui Debug mode to inspect the state of your
application while debugging. You can interact with the debugger in several
ways, including the following:
\list
\o Go through a program line-by-line or instruction-by-instruction.
\o Interrupt running programs.
\o Set breakpoints.
\o Examine the contents of the call stack.
\o Examine and modify registers and memory contents of
the debugged program.
\o Examine and modify registers and memory contents of
local and global variables.
\o Examine the list of loaded shared libraries.
\o Create snapshots of the current state of the debugged program
and re-examine them later.
\endlist
Qt Creator displays the raw information provided by the native debuggers
in a clear and concise manner with the goal to simplify the debugging process
as much as possible without losing the power of the native debuggers.
In addition to the generic IDE functionality provided by stack view, views for
locals and watchers, registers, and so on, Qt Creator includes
features to make debugging Qt-based applications easy. The debugger
plugin understands the internal layout of several Qt classes, for
example, QString, the Qt containers, and most importantly QObject
(and classes derived from it), as well as most containers of the C++
Standard Library and some gcc and Symbian extensions. This
deeper understanding is used to present objects of such classes in
a useful way.
If you install Qt Creator as part of a Qt SDK, the GNU Symbolic Debugger
is installed automatically and you should be ready to start debugging after
you create a new project. However, you can change the setup to use debugging
tools for Windows, for example.
You can connect mobile devices to your development PC and debug processes
running on the devices.
*/
/*!
\contentspage index.html
\previouspage creator-overview.html
\page creator-os-supported-platforms.html
\nextpage creator-quick-tour.html
\title Operating Systems and Supported Platforms
\section1 Operating Systems
Qt Creator is available in binary packages for the following operating
systems:
\list
\o Windows XP Service Pack 2
\o Windows Vista
\o (K)Ubuntu Linux 7.04 (32-bit and 64-bit) or later, with the following:
\list
\o g++
\o make
\o libglib2.0-dev
\o libSM-dev
\o libxrender-dev
\o libfontconfig1-dev
\o libxext-dev
\o libfreetype6-dev
\o libx11-dev
\o libxcursor-dev
\o libxfixes-dev
\o libxft-dev
\o libxi-dev
\o libxrandr-dev
\o If you are using QtOpenGL, libgl-dev and libglu-dev
\endlist
\o Mac OS 10.5 or later with the following:
\list
\o Xcode tools for your Mac OS X version available from your Mac
OS X installation DVDs or at \l http://developer.apple.com.
\endlist
\endlist
\omit ## Are the Xcode tools still needed separately? \endomit
\section1 Build Environment
To build Qt Creator itself from the source, you need:
\list
\o Qt 4.7 or later
\o On Windows, MinGW 4.4 or Microsoft Visual Studio 2008
\endlist
\section1 Supported Mobile Device Platforms
You can develop applications for the following mobile device
platforms:
\list
\o Symbian
\o Maemo and Maemo Application Development and Debugging Environment (MADDE)
\endlist
The following table summarizes operating system support for building
applications for mobile device platforms.
\table
\header
\o {1,3} Operating system
\o {3,1} Platform
\header
\o Desktop
\o Symbian
\o Maemo
\row
\o Windows
\o Yes
\o Yes
\o Yes
\row
\o Linux
\o Yes
\o No
\o Yes
\row
\o Mac OS X
\o Yes
\o No
\o No
\endtable
*/
/*!
\contentspage index.html
\previouspage creator-os-supported-platforms.html
\page creator-quick-tour.html
\nextpage creator-getting-started.html
\title Qt Creator User Interface
\image qtcreator-breakdown.png
When you start Qt Creator, it opens to the \gui Welcome mode, where you can:
\list
\o Open tutorials and example projects
\o View tips and hints on using Qt Creator
\o Create and open projects
\o Send feedback to the development team
\o Open recent sessions and projects
\o Read news from the Qt labs
\o Ask for support
\endlist
You can use the mode selector to change to another Qt Creator mode.
Qt Creator has been localized into several languages. If the system language
is one of the supported languages, it is automatically selected. To change
the language, select \gui {Tools > Options > Environment} and select a language
in the \gui Language field. The change takes effect after you restart Qt Creator.
\section1 Qt Creator Modes
The mode selector allows you to quickly switch between tasks such as
editing project and source files, designing application UIs,
configuring how projects are built and
executed, and debugging your applications. To change modes, click the
icons, or use the \l{keyboard-shortcuts}{corresponding keyboard shortcut}.
You can use Qt Creator in the following modes:
\list
\o \gui{\l{Using the Editor}{Edit}} mode for editing project and source files.
\o \gui{\l{Developing Application UI}{Design}} mode for designing and developing
application user interfaces. This mode is available for UI files (.ui or
.qml).
\o \gui{\l{Debugging}{Debug}} mode for inspecting the state of your program while
debugging.
\o \gui{\l{Managing Projects}{Projects}} mode for configuring project building and
execution. This mode is available when a project is open.
\o \gui{\l{Getting Help}{Help}} mode for viewing Qt documentation.
\endlist
Certain actions in Qt Creator trigger a mode change. Clicking on
\gui {Debug} > \gui {Start Debugging} > \gui {Start Debugging}
automatically switches to \gui {Debug} mode.
\section1 Browsing Project Contents
The sidebar is available in the \gui Edit and \gui Debug modes.
Use the sidebar to browse projects, files, and bookmarks, and to view
the class hierarchy.
\image qtcreator-sidebar.png
You can select the content of the sidebar in the sidebar menu:
\list
\o \gui Projects shows a list of projects open in the current
session.
\o \gui{Open Documents} shows currently open files.
\o \gui Bookmarks shows all bookmarks for the current session.
\o \gui{File System} shows all files in the currently selected
directory.
\o \gui {Class View} shows the class hierarchy of the currently
open projects.
\o \gui Outline shows the element hierarchy of a QML file.
\o \gui {Type Hierarchy} shows the base classes of a class. For
more information, see \l{Viewing Type Hierarchy}.
\endlist
You can change the view of the sidebar in the following ways:
\list
\o To toggle the sidebar, click \inlineimage qtcreator-togglebutton.png
or press \key Alt+0 (\key Cmd+0 on Mac OS X).
\o To split the sidebar, click \inlineimage qtcreator-splitbar.png
. Select new content to view in the split view.
\o To close a sidebar view, click
\inlineimage qtcreator-closesidebar.png
.
\endlist
The additional options in each view are described in the following
sections.
\section2 Viewing Project Files
The sidebar displays projects in a project tree. The project tree contains
a list of all projects open in the current session. The files for each
project are grouped according to their file type.
You can use the project tree in the following ways:
\list
\o To bring up a context menu containing the actions most commonly
needed right-click an item in the project tree.
For example, through the menu of the project root directory you can,
among other actions, build, re-build, clean and run the project.
\o To hide the categories and sort project files alphabetically, click
\inlineimage qtcreator-filter.png
and select \gui{Simplify Tree}.
\o To hide source files which are automatically generated by the build
system, during a build, click \inlineimage qtcreator-filter.png
and select \gui{Hide Generated Files}.
\o To keep the position in the project tree synchronized with the file
currently opened in the editor, click
\inlineimage qtcreator-synchronizefocus.png
.
\o To see the absolute path of a file, move the mouse pointer over the
file name.
\endlist
\section2 Viewing the File System
If you cannot see a file in the \gui Projects view, switch to the
\gui {File System} view, which shows all the files in the file system.
To keep the position in the tree synchronized with the file
opened in the editor, click
\inlineimage qtcreator-synchronizefocus.png
.
\section2 Viewing the Class Hierarchy
The \gui {Class View} shows the class hierarchy of the currently
open projects. To organize the view by subprojects, click
\inlineimage qtcreator-show-subprojects.png
.
\section2 Viewing QML Elements
The \gui Outline view shows the element hierarchy in a QML file.
\list
\o To see a complete list of all bindings, click
\inlineimage qtcreator-filter.png
and select \gui{Show All Bindings}.
\o To keep the position in the view synchronized with the element
selected in the editor, click
\inlineimage qtcreator-synchronizefocus.png
.
\endlist
\section1 Viewing Output
The task pane in Qt Creator can display one of the following panes:
\list
\o \gui{Build Issues}
\o \gui{Search Results}
\o \gui{Application Output}
\o \gui{Compile Output}
\o \gui{General Messages}
\o \gui{Version Control}
\endlist
Output panes are available in all \l{Qt Creator modes}{modes}.
Click the name of an output pane to open the pane. To maximize
an open output pane, click the \gui {Maximize Output Pane} button
or press \key {Alt+9}.
To search within the \gui{Application Output} and \gui{Compile Output}
panes, press \key {Ctrl+F} when the pane is active. Enter search
criteria in the \gui Find field and click the left and right arrows to
search down and up in the pane.
To open the \gui{General Messages} and \gui{Version Control}
panes, select \gui {Window > Output Panes}.
\section2 Build Issues
The \gui{Build Issues} pane provides a list of errors and warnings
encountered during a build. The pane filters out irrelevant output from
the build tools and presents the issues in an organized way.
Right-clicking on a line brings up a context menu with options to copy
the contents and to show a version control annotation view of the
line that causes the error message.
\image qtcreator-build-issues.png
To view task lists in the \gui{Build Issues} pane, click
\inlineimage qtcreator-filter.png
and select \gui{My Tasks}. Entries from a task list file (.tasks) are
imported to the pane. Press \key F6 and \key Shift+F6 to jump from one issue
to the next.
For more information about creating task files, see \l{Creating Task List Files}.
\section2 Search Results
The \gui{Search Results} pane displays the results for global searches,
for example, searching within a current document, files on disk, or all
projects.
The figure below shows an example search result for all
occurrences of \c textfinder within the \c "/TextFinder" directory.
\image qtcreator-search-pane.png
\section2 Application Output
The \gui{Application Output} pane displays the status of a program when
it is executed, and the debug output.
The figure below shows an example output from qDebug().
\image qtcreator-application-output.png
\section2 Compile Output
The \gui{Compile Output} pane provides all output from the compiler.
The \gui{Compile Output} is a more detailed version of information
displayed in the \gui{Build Issues} pane.
\image qtcreator-compile-pane.png
\section1 Navigating with Keyboard
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{Searching With the Locator}{navigation} shortcuts are available to help
speed up the process of developing your application.
*/
/*!
\contentspage index.html
\previouspage creator-task-lists.html
\page creator-help.html
\nextpage creator-tips.html
\title Getting Help
Qt Creator comes fully integrated with Qt documentation and
examples using the Qt Help plugin.
\list
\o To view documentation, switch to \gui Help mode.
\o To obtain context sensitive help, move the text cursor to a Qt class
or function and press \key F1. The documentation is displayed in a
pane next to the code editor, or, if there is not enough vertical
space, in the fullscreen \gui Help mode.
\image qtcreator-context-sensitive-help.png
\o To select and configure how the documentation is displayed in the
\gui Help mode, select \gui Tools > \gui Options... > \gui Help.
\endlist
\section1 Finding Information in Qt Documentation
Qt Creator, Qt SDK, Nokia Qt SDK and other Qt deliverables contain documentation
as .qch files. All the documentation is accessible in the \gui Help mode.
To find information in the documentation, select:
\list
\o \gui Bookmarks to view a list of pages on which you have added bookmarks.
\o \gui Contents to see all the documentation installed on the development
PC and to browse the documentation contents.
\o \gui Index to find information based on a list of keywords in all the
installed documents.
\o \gui {Open Pages} to view a list of currently open documentation pages.
\o \gui Search to search from all the installed documents.
\endlist
\section2 Adding Bookmarks to Help Pages
You can add bookmarks to useful help pages to easily find them later
in the \gui Bookmarks view. You can either use the page title as the
bookmark or change it to any text. You can organize the bookmarks in
folders in the view.
\image qtcreator-help-add-bookmark-dlg.png "Add Bookmark dialog"
To add a bookmark to an open help page:
\list 1
\o Click the
\inlineimage qtcreator-help-add-bookmark.png
(\gui {Add Bookmark}) button on the toolbar.
\o In the \gui {Add Bookmark} dialog, click \gui OK to save the
page title as a bookmark in the \gui Bookmarks folder.
\endlist
To import and export bookmarks, select \gui {Tools > Options... > Help >
General Settings > Import} or \gui Export.
\section1 Adding External Documentation
You can display external documentation in the \gui Help mode.
To augment or replace the documentation that ships with Qt Creator and Qt:
\list 1
\o Create a .qch file from your documentation.
For information on how to prepare your documentation and create a
.qch file, see
\l{http://doc.qt.nokia.com/4.7/qthelp-framework.html}{The Qt Help Framework}.
\o To add the .qch file to Qt Creator, select \gui Tools >
\gui Options... > \gui Help > \gui Documentation > \gui Add.
\endlist
\section1 Detaching the Help Window
By default, context-sensitive help is opened in a window next to the
code editor when you press \key F1. If there is not enough vertical
space, the help opens in the full-screen help mode.
You can specify that the help always opens in full-screen mode or
is detached to an external window. Select \gui {Tools > Options... > Help >
General Settings} and specify settings for displaying context-sensitive help
in the \gui {On context help} field. To detach the help window, select
\gui {Always Show Help in External Window}.
You can select the help page to open upon startup in the \gui {Home Page}
field.
\section1 Using Documentation Filters
You can filter the documents displayed in the \gui Help mode to find
relevant information faster. Select from a list of filters in the
\gui {Filtered by} field. The contents of the \gui Index and \gui Contents
pane in the sidebar change accordingly.
\image qtcreator-help-filters.png "Help filters"
You can modify the filters to include external documentation, for example,
or you can define your own filters. To construct filters, you can use the
filter attributes that are specified in the documentation. Each document
contains at least one filter attribute. If several documents contain the
same filter attribute, such as \c tools, you can use that attribute to
include all those documents.
To add filters:
\list 1
\o Select \gui {Tools > Options... > Help > Filters > Add}.
\o Enter a name for the filter and press \gui {OK}.
\o In \gui Attributes, select the documents that you want to include
in the filter.
\image qtcreator-help-filter-attributes.png "Help filter attributes"
\o Click \gui OK.
\o In the \gui Help mode, select the filter in the \gui {Filtered by}
field to see the filtered documentation in the sidebar.
\endlist
To modify filters, select a filter in \gui Filters, select the attributes,
and then click \gui Apply.
To remove filters, select them in \gui Filters, and click \gui Remove.
*/
/*!
\contentspage index.html
\previouspage creator-editor-external.html
\page creator-design-mode.html
\nextpage creator-usability.html
\title Developing Application UI
You can use the integrated \QD to design and build graphical user interfaces (GUIs) from
Qt widgets. You can compose and customize your widgets or dialogs and test
them using different styles and resolutions.
Widgets and forms created with \QD are integrated seamlessly with programmed code,
using the Qt signals and slots mechanism, that lets you easily assign behavior to
graphical elements. All properties set in \QD can be changed dynamically within the code.
Furthermore, features like widget promotion and custom plugins allow you to use your
own widgets with \QD.
UIs that use widgets are clearly structured and enforce a platform look and feel,
which makes them useful for traditional applications. However, they are static, and
do not fully make use of the large high-resolution screens, touch input, and significant
graphics power that are becoming common in portable consumer devices, such as mobile
phones, media players, set-top boxes, and netbooks.
You can easily develop animations by using a declarative programming
language called \l {http://doc.qt.nokia.com/4.7/qtquick.html}{QML}.
In QML, a user interface is specified as a tree of objects with properties.
You can edit QML code in the code editor. You
can use Qt or JavaScript to implement the application logic.
The integration includes project management and code completion.
\section1 Using Qt Designer
Qt Creator automatically opens all .ui files in \QD.
\image qtcreator-formedit.png
To change the layout of \QD user interface elements:
\list 1
\o Select \gui Tools > \gui{Form Editor} > \gui Views >
\gui Locked.
When this option is unchecked, you can change the layout.
\o Click the header of an element and drag the element to a new
position.
\endlist
To change \QD properties, select \gui Tools > \gui Options... >
\gui Designer.
\list
\o Set the class properties and code generation preferences in \gui
{Class Generation}.
\o Set an additional folder for saving templates in \gui{Template
Paths}.
\o Set the grid settings and preview preferences in \gui Forms. To
preview your form with skins, enable \gui{Print/Preview
Configuration} and select your skin. Otherwise default preview
settings are used.
To preview the settings, select \gui Tools > \gui{Form Editor} >
\gui Preview, or press \key Alt+Shift+R.
\o To specify embedded device profiles, such as style, font, and screen
resolution, select \gui{Embedded Design}.
\endlist
To switch between forms and code, use \key Shift+F4.
For more information on \QD, see
\l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
\section1 Using Qt Quick Designer
You can edit .qml files in the visual \QMLD editor or in the
code editor.
In \gui Projects, double-click a .qml file to open it in the code
editor. Then select the \gui {Design} mode to edit the file in the
visual editor.
\note The visual \QMLD editor is provided as an experimental plugin that you must
enable to be able to edit QML files in the \gui Design mode. Enabling the
visual editor can negatively affect the overall stability of Qt Creator.
To enable or disable the \QMLD visual editor, select
\gui {Help > About Plugins... > Qt Quick > QmlDesigner}. You must restart Qt Creator
to enable or disable the visual editor.
\image qmldesigner-visual-editor.png "Visual editor"
Use the visual editor panes to manage your project:
\list
\o \gui {Navigator} pane displays the items in the scene. You can
show and hide items to focus on specific parts of the application.
\o \gui {Library} pane displays lists of predefined \gui {Items} and
imported \gui {Resources} that you can use to design applications. The
images and other files that you copy to the project folder appear in the
\gui {Resources} pane.
\o \gui {Properties} pane displays the properties of the selected component.
You can also change the properties in the code editor.
\o \gui {State} pane displays the different states of the component. To add
states, click the empty slot. Then modify the new state in the editor.
In the code editor, you can see the changes recorded as changes to
the base state.
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-project-wizards.html
\page creator-editor-using.html
\nextpage creator-editor-finding.html
\title Using the Editor
Qt Creator's code editor is designed to aid you in creating, editing and
navigating code. Qt Creator's code editor is fully equipped with syntax
checking, code completion, context sensitive help and in-line error
indicators while you are typing.
\section1 Using the Editor Toolbar
The editor toolbar is located at the top of the editor view. The editor
toolbar is context sensitive and shows items relevant to the file currently
open in the editor.
\image qtcreator-editortoolbar-symbols.png
Use the toolbar to navigate between open files and symbols in use.
To browse forward or backward through your location history, click
\inlineimage qtcreator-back.png
and \inlineimage qtcreator-forward.png
.
To go to any open file, select it from the \gui{Open files} drop-down menu.
Right-click the menu title and select \gui {Copy Full Path to Clipboard} to
copy the path and name of the current file to the clipboard.
To jump to any symbol used in the current file, select it from the
\gui Symbols drop-down menu. By default, the symbols are displayed in the
order in which they appear in the file. Right-click the menu title and select
\gui {Sort Alphabetically} to arrange the symbols in alphabetic order.
\section1 Splitting the Editor View
Split the editor view when you want to work on and view multiple files on
the same screen.
\image qtcreator-spliteditorview.png
You can split the editor view in the following ways:
\list
\o To split the editor view into a top and bottom view, select
\gui Window > \gui Split or press \key{Ctrl+E, 2}.
Split command creates views below the currently active editor view.
\o To split the editor view into adjacent views, select
\gui Window > \gui{Split Side by Side} or press
\key{Ctrl+E, 3}.
Side by side split command creates views to the right of the
currently active editor view.
\endlist
To move between split views, select \gui Window >
\gui{Go to Next Split} or press \key{Ctrl+E, O}.
To remove a split view, place the cursor within the view you want to
remove and select \gui Window > \gui{Remove Current Split} or press
\key{Ctrl+E, 0}. To remove all but the currently selected split view,
select \gui Window > \gui{Remove All Splits} or press \key{Ctrl+E, 1}.
\section1 Highlighting and Folding Blocks
Use block highlighting to visually separate parts of the code that belong
together. For example, when you place the cursor within the braces,
the code enclosed in braces is highlighted.
\image qtcreator-blockhighlighting.png
To enable block highlighting, select \gui Tools > \gui{Options...} >
\gui{Text Editor} > \gui Display > \gui{Highlight blocks}.
Use the folding markers to collapse and expand blocks of code within
braces. Click the folding marker to collapse or expand a block. In the
figure above, the folding markers are located between the line number and
the text pane.
To show the folding markers, select \gui Tools > \gui{Options...} >
\gui{Text Editor} > \gui Display > \gui{Display folding markers}. This
option is enabled by default.
When the cursor is on a brace, the matching brace is animated
by default. To turn off the animation and just highlight the block and
the braces, select \gui {Tools > Options... > Text Editor > Display} and
deselect \gui {Animate matching parentheses}.
\section1 Checking Code Syntax
As you write code Qt Creator checks code syntax. When Qt Creator spots a
syntax error in your code it underlines it and shows error details when you
move the mouse pointer over the error.
\list
\o Syntax errors are underlined in red.
In the following figure, a semicolon is missing at the end of the
line.
\image qtcreator-syntaxerror.png
\o Semantic errors and warnings are underlined in olive.
In the following figure, the type is unknown.
\image qtcreator-semanticerror.png
\endlist
\section1 Completing Code
Qt Creator understands the code as code, not just as plain text. This
allows it to help you to write well formatted code and to anticipate
what you are going to write and complete the code.
The code completion differs somewhat depending on whether you write Qt code or QML code.
\section2 Completing Qt Code
As you write code, Qt Creator provides a list of context-sensitive
suggestions to the statement currently under your cursor.
\image qtcreator-codecompletion.png
To open the list of suggestions at any time, press \key{Ctrl+Space}.
If only one option is available, Qt Creator inserts it automatically.
When completion is invoked manually, Qt Creator completes the common prefix
of the list of suggestions. This is especially useful for classes with
several similarly named members. To disable this functionality, uncheck
\gui{Autocomplete common prefix} in the code completion preferences.
Select \gui Tools > \gui{Options...} > \gui{Text Editor} > \gui Completion.
By default, code completion considers only the first letter case-sensitive.
To apply full or no case-sensitivity, select the option in the
\gui {Case-sensitivity} field.
The following table lists available types for code completion and icon
used for each.
\table
\header
\o Icon
\o Description
\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
\section2 Completing QML Code
As you write QML code, Qt Creator suggests properties, IDs, and code
snippets to complete the code. The snippets can consist of multiple
fields that you specify values for. Select an item in the list and press
\key Tab or \key Enter to complete the code. Press \key Tab to
move between the fields and specify values for them.
\image qmldesigner-code-completion.png "Completing QML code"
\section1 Using Bookmarks
To insert or delete a bookmark right-click the line number and select
\gui{Toggle Bookmark} or press \key{Ctrl+M}.
\image qtcreator-togglebookmark.png
To go to previous bookmark in the current session, press \key{Ctrl+,}.
To go to next bookmark in the current session, press \key{Ctrl+.}.
\section1 Moving to Symbol Definition or Declaration
In Qt Creator you can move directly to the definition or the declaration of
a symbol by holding the \key Ctrl and clicking the symbol.
To enable this moving function, in \gui Tools > \gui{Options...} >
\gui{Text Editor} > \gui Behavior, select \gui{Enable mouse navigation}.
You can also select the symbol and press \key F2, or right-click the symbol
and select \gui {Follow Symbol Under Cursor} to move to its definition or declaration.
This is supported for namespaces, classes, methods, variables, include statements,
and macros.
To switch between the definition and declaration of a symbol, press \key {Shift+F2}
or right-click the symbol and select \gui {Switch Between Method Declaration/Definition}.
\section1 Viewing Type Hierarchy
To view the base classes of a class, right-click the class and select
\gui {Open Type Hierarchy} or press \key {Ctrl+Shift+T}.
\section1 Using Update Code Model
To refresh the internal information in Qt Creator pertaining to your code,
select \gui{Tools} > \gui{C++} > \gui{Update Code Model}.
\note In Qt Creator indexing updates the code automatically. Use
\gui{Update Code Model} only as an emergency command.
*/
/*!
\contentspage index.html
\previouspage creator-editor-locator.html
\page creator-editor-codepasting.html
\nextpage creator-editor-options.html
\title Pasting and Fetching Code Snippets
In Qt Creator, you can paste snippets of code to a server or fetch
snippets of code from the server. To paste and fetch snippets of code,
Qt Creator uses the following:
\list
\o \gui{CodePaster}
\o \gui{Pastebin.Com}
\o \gui{Pastebin.Ca}
\endlist
To configure the server, select \gui{Tools} > \gui{Options...} >
\gui{Code Pasting}.
To paste a snippet of code onto the server, select \gui{Tools} >
\gui{Code Pasting} > \gui{Paste Snippet...} or press \key{Alt+C,Alt+P}.
To fetch a snippet of code from the server, select \gui{Tools} >
\gui{Code Pasting} > \gui{Fetch Snippet...} or press \key{Alt+C,Alt+F}.
\note To use \gui{Pastebin.Com}, configure the domain
prefix in \gui{Tools} > \gui{Options...} > \gui{Code Pasting} >
\gui{Pastebin.com}.
For example, you might ask colleagues to review a change that you plan to
submit to a version control system. If you use the Git version control system,
you can create a \e{diff} view by selecting \gui{Tools} > \gui{Git} >
\gui{Diff Repository}. You can then upload its contents to the server by choosing
\gui{Tools} > \gui{Code Pasting} > \gui{Paste Snippet...}. The reviewers can retrieve
the code snippet by selecting \gui{Tools} > \gui{Code Pasting} > \gui{Fetch Snippet...}.
If they have the project currently opened in Qt Creator, they can apply and test
the change by choosing \gui{Tools} > \gui{Git} > \gui{Apply Patch}.
*/
/*!
\contentspage index.html
\previouspage creator-editor-options.html
\page creator-editor-fakevim.html
\nextpage creator-editor-external.html
\title Using FakeVim Mode
In the \gui{FakeVim} mode, you can run the main editor in a manner similar
to the Vim editor. To run the editor in the \gui{FakeVim} mode, select
\gui{Edit} > \gui{Advanced} > \gui{Use Vim-style Editing} or press
\key{Alt+V,Alt+V}.
In the \gui{FakeVim} mode, most keystrokes in the main editor will be
intercepted and interpreted in a way that resembles Vim. Documentation for
Vim is not included in Qt Creator. For more information on using Vim,
see \l{http://www.vim.org/docs.php}{Documentation} on the Vim web site.
To map commands entered on the \gui{FakeVim} command line to actions of the
Qt Creator core, select \gui{Tools} > \gui{Options...} > \gui{FakeVim} >
\gui{Ex Command Mapping}.
To make changes to the Vim-style settings, select \gui{Tools} >
\gui{Options...} > \gui FakeVim > \gui{General}.
To use a Vim-style color scheme, select \gui {Tools > Options... >
Text Editor > Fonts & Color}. In the \gui {Color Scheme} list, select
\gui {Vim (dark)}.
To quit the FakeVim mode, click \gui {Quit FakeVim} or press
\key{Alt+V,Alt+V}.
*/
/*!
\contentspage index.html
\previouspage creator-editor-fakevim.html
\page creator-editor-external.html
\nextpage creator-design-mode.html
\title Using an External Editor
To open the file you are currently viewing in an external editor, select
\gui Edit > \gui Advanced > \gui{Open in External Editor}.
To use the external editor of your choice:
\list 1
\o Add the editor path to the \c{PATH} environment variable of your
operating system.
\o In Qt Creator select \gui Tools > \gui Options... >
\gui Environment > \gui General.
\o In \gui{External editor} enter the name of the application followed
by \key Space and \tt{\bold %f}. For example, to open the file in
Smultron, enter \tt{\bold{smultron %f}}.
To further define how to open the file in the external editor, you
can use the following variables separated by a space:
\list
\o Current line number \tt{\bold %l}
\o Current column number \tt{\bold %c}
\o Editor's x position on the screen \tt{\bold %x}
\o Editor's y position on the screen \tt{\bold %y}
\o Editor's width in pixels \tt{\bold %w}
\o Editor's height in pixels \tt{\bold %h}
\o Editor's width in characters \tt{\bold %W}
\o Editor's height in characters \tt{\bold %H}
\o To pass % symbol to the editor \tt{\bold %%}
\endlist
\note Not all variables work with all editors.
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-editor-codepasting.html
\page creator-editor-options.html
\nextpage creator-editor-fakevim.html
\title Configuring the Editor
Qt Creator allows you to configure the text editor to suit your specific
needs. To configure the editor, select \gui Tools > \gui{Options...} >
\gui{Text Editor}.
\image qtcreator-font-colors.png "Text editor options"
You can perform the following configuration actions:
\list
\o Set the font preferences and apply color schemes for syntax highlighting in
\gui{Font & Colors}.
\o Specify definition files for syntax highlighting for other types of files than
C++ or QML in \gui{Generic Highlighter}.
\o Set tabs, indentation, the handling of whitespace, and mouse operations in
\gui Behavior.
\o Set various display properties, for example,
\l{Highlighting and folding blocks}{highlighting and folding blocks},
text wrapping or \l{Moving to symbol definition or declaration}
{moving to symbol definition or declaration}
in \gui Display.
\o Configure \l{Completing Code}{code completion} in \gui Completion.
\endlist
\section2 Configuring Fonts
You can select the font family and size. You can specify a zoom setting in
percentage for viewing the text. You can also zoom in or out by pressing
\key {Ctrl++} or \key {Ctrl +-}, or by pressing \key Ctrl and rolling
the mouse button up or down. To disable the mouse wheel function, select
\gui {Tools > Options... > Text Editor > Behavior} and deselect the
\gui {Enable scroll wheel zooming} check box.
Antialiasing is used by default to make text look smoother and more
readable on the screen. Deselect the \gui Antialias check box to
turn off antialiasing.
\section2 Defining Color Schemes
You can select one of the predefined color schemes for syntax highlighting
or create customized color schemes. The color schemes apply to highlighting
both C++ and QML files and generic files.
To create a color scheme:
\list 1
\o Select \gui {Tools > Options... > Text Editor > Fonts & Color > Copy}.
\o Enter a name for the color scheme and click \gui OK.
\o In the \gui Foreground field, specify the color of the selected
code element.
\o In the \gui Background field, select the background
color for the code element.
The backgound of the \gui Text element determines the background of the
code editor.
\endlist
When you copy code from Qt Creator, it is copied in both plain text and HTML
format. The latter makes sure that syntax highlighting is preserved when
pasting to a rich-text editor.
\section2 Generic Highlighting
Generic highlighting is based on highlight definition files that are provided by the
\l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}{Kate Editor}.
You can download highlight definition files for use with Qt Creator.
If you have a Unix installation that comes with the Kate Editor, you might already
have the definition files installed. Typically, the files are in a read-only directory,
and therefore, you cannot manage them. Qt Creator can try to locate them and use them
as fallback files, when the primary location does not contain the definition for the
current file type. You can also specify the directory that contains preinstalled
highlight definition files as the primary location.
When you open a file for editing and the editor cannot find the highlight definition
for it, an alert appears. You can turn off the alerts. You can also specify patterns
for ignoring files. The editor will not alert you if highlight definitions for the
ignored files are not found.
To download highlight definition files:
\list 1
\o Select \gui {Tools > Options... > Text Editor > Generic Highlighter}.
\image qtcreator-generic-highlighter.png "Generic Highlighter options"
\o In the \gui Location field, specify the path to the primary location for
highlight definition files.
\o Click \gui {Download Definitions} to open a list of highlight definition files available for
download.
\image qtcreator-manage-definitions.png "Download Definitions dialog"
\o Select highlight definition files in the list and click \gui{Download Selected
Definitions}.
\o Select the \gui {Use fallback location} check box to specify the secondary location
where the editor will look for highlight definition files.
\o Click \gui Autodetect to allow Qt Creator to look for highlight definition
files on your system, or click \gui Browse to locate them in the file system
yourself.
\o In the \gui {Ignored file patterns} field, specify file patterns. You will not
receive alerts if the highlight definitions for the specified files are not found.
\o Click \gui OK to save your changes.
\endlist
\section2 Indenting Code
\image qtcreator-indentation.png "Text Editor Behavior options"
When you type code, it is indented automatically according to the selected
options. Select a block to indent it when you press \key Tab.
Press \key {Shift+Tab} to decrease the indentation.
When you press \gui Backspace the indentation is decreased by one level,
instead of one space, by default.
By default, the tab-length in code editor is 8 spaces, but you can change
it. The code editor can also determine whether tabs or spaces are used
on the previous or next line and copy the style.
You can determine whether the block indent style includes braces,
or you can use the GNU indent style. The GNU style places braces on a separate
line, indented by 2 spaces, except when they open a function definition, where
they are not indented.
You can also specify whether continuation lines are aligned with the previous
code or just indented to the logical depth. You can always use spaces for
alignment or use spaces or tabs depending on the other options you selected.
The following code snippet illustrates excluding braces from the indented block:
\code
void foobar(bool zoo)
{
if (zoo)
{
foo();
}
}
\endcode
The following code snippet illustrates including braces in the indented block:
\code
void foobar(bool zoo)
{
if (zoo)
{
foo();
}
}
\endcode
The following code snippet illustrates the GNU style:
\code
void foobar(bool zoo)
{
if (zoo)
{
foo();
}
}
\endcode
*/
/*!
\contentspage index.html
\previouspage creator-editor-using.html
\page creator-editor-finding.html
\nextpage creator-editor-refactoring.html
\title Finding and Replacing
To search through the currently open file:
\list 1
\o Press \key Ctrl+F or select \gui Edit > \gui Find/Replace >
\gui{Find/Replace}.
\o Enter the text you are looking for.
If the text is found, all occurrences are highlighted as you type.
\o To go to the next occurrence, click \inlineimage qtcreator-next.png
, or press \key F3. To go to the previous occurrence click
\inlineimage qtcreator-previous.png
, or press \key Shift+F3.
\endlist
You can restrict the search in the \gui Find field by selecting one
or several search criteria:
\list
\o To make your search case sensitive, select
\inlineimage qtcreator-editor-casesensitive.png
.
\o To search only whole words, select
\inlineimage qtcreator-editor-wholewords.png
.
\o To search using regular expressions, select
\inlineimage qtcreator-editor-regularexpressions.png
.
Regular expressions used in Qt Creator are modeled on Perl regular
expressions. For more information on using regular expressions, see
\l {http://doc.qt.nokia.com/4.7/qregexp.html#details}
{Detailed Description} in the QRegExp Class Reference.
\endlist
\note If you have selected text before selecting \gui Find/Replace, the
search is conducted within the selection.
To replace occurrences of the existing text, enter the new text in the
\gui{Replace with} field.
\list
\o To replace the selected occurrence and move to the next one,
click \inlineimage qtcreator-next.png
or press \key Ctrl+=.
\o To replace the selected occurrence and move to the previous one,
click \inlineimage qtcreator-previous.png
.
\o To replace all occurrences in the file, click \gui{Replace All}.
\endlist
\section1 Advanced Search
To search through projects, files on a file system or the currently open
file:
\list 1
\o Press \key Ctrl+Shift+F or select \gui Edit >
\gui Find/Replace > \gui{Advanced Find} >
\gui{Open Advanced Find...}.
\o Select the scope of your search:
\list
\o \gui{All Projects} searches files matching the defined file
pattern in all currently open projects.
For example, to search for \tt previewer only in \tt .cpp
and \tt .h files, enter in \gui{File pattern}
\tt *.cpp,*.h.
\image qtcreator-search-allprojects.png
\o \gui{Current Project} searches files matching the defined file
pattern only in the project you are currently editing.
\o \gui{Files on File System} recursively searches files matching
the defined file pattern in the selected directory.
\o \gui{Current File} searches only the current file.
\endlist
\o Enter the text you are looking for and click \gui Search.
\image qtcreator-searchresults.png
A list of files containing the searched text is displayed in the
\gui{Search Results} pane.
\list
\o To see all occurrences in a file, double-click the file name in
the list.
\o To go to an occurrence, double-click it.
\endlist
\endlist
\note You can use \gui{Advanced Find} also to search for symbols. For more
information, see \l{Finding Symbols}.
*/
/*!
\contentspage index.html
\previouspage creator-editor-finding.html
\page creator-editor-refactoring.html
\nextpage qt-quick-toolbars.html
\title Refactoring
Code refactoring is the process of changing the code without modifying the
existing functionality of your application. By refactoring your code you
can:
\list
\o Improve internal quality of your application
\o Improve performance and extensibility
\o Improve code readability and maintainability
\o Simplify code structure
\endlist
\section1 Finding Symbols
To find the use of a specific symbol in your project:
\list 1
\o In the editor place the cursor on the symbol and select \gui Tools
> \gui C++ > \gui{Find Usages} or press
\key Ctrl+Shift+U.
Qt Creator looks for the symbol in the following locations:
\list
\o Files listed as a part of the project
\o Files directly used by the project files (for example, generated
files)
\o Header files of used frameworks and libraries
\endlist
\note You can also select \gui{Edit > Find/Replace > Advanced Find >
C++ Symbols} to search for classes, methods, enums, and declarations
either from files listed as part of the project or from all files that
are used by the code, such as include files.
\image qtcreator-search-cpp-symbols.png
\o The \gui{Search Results} pane opens and shows the location and
number of instances of the symbol in the current project.
\image qtcreator-refactoring-find.png
\endlist
You can browse the search results in the following ways:
\list
\o To go directly to an instance, double-click the instance in the
\gui{Search Results} pane.
\o To move between instances, click
\inlineimage qtcreator-forward.png
and
\inlineimage qtcreator-back.png
in the \gui{Search Results} pane.
\o To expand and collapse the list of all instances, click
\inlineimage qtcreator-expand.png
.
\o To clear the search results, click \inlineimage qtcreator-clear.png
.
\endlist
\section1 Renaming Symbols
The functions available for renaming symbols depend on whether you are
writing C++ or QML code. For QML, you can only rename IDs.
To rename a specific symbol in a Qt project:
\list 1
\o In the editor, place the cursor on the symbol you would like to
change and select \gui Tools > \gui C++ >
\gui{Rename Symbol Under Cursor} or press \key Ctrl+Shift+R.
The \gui{Search Results} pane opens and shows the location and
number of instances of the symbol in the current project.
\image qtcreator-refactoring-replace.png
\o To replace all selected instances, enter the name of the new symbol
in the \gui{Replace with} text box and click \gui Replace.
To omit an instance, uncheck the check-box next to the instance.
\note This action replaces all selected instances of the symbol in
all files listed in the \gui{Search Results} pane. You cannot
undo this action.
\endlist
\note Renaming local symbols does not open the \gui{Search Results} pane.
The instances of the symbol are highlighted in code and you can edit the
symbol. All instances of the local symbol are changed as you type.
To rename an ID in a Qt Quick project:
\list 1
\o Right-click an ID in the QML code and select
\gui {Rename id}.
\o In the \gui {Rename id} field, enter the new ID.
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-qml-application.html
\page creator-project-managing.html
\nextpage creator-project-creating.html
\title Managing Projects
One of the major advantages of Qt Creator is that it allows a team of
developers to share a project across different development platforms with a common
tool for development and debugging.
The following sections describe how to manage projects:
\list
\o \l{Creating a Project}
\o \l{Setting Up a qmake Project}
\o \l{Adding Libraries to qmake Projects}
\o \l{Setting Up a CMake Project}
\o \l{Setting Up a Generic Project}
\o \l{Setting Up Development Environment for Maemo}
\o \l{Setting Up Development Environment for Symbian}
\o \l{Managing Sessions}
\o \l{Adding New Custom Wizards}
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-project-managing.html
\page creator-project-creating.html
\nextpage creator-project-qmake.html
\title Creating a Project
You use wizards to create and import several types of projects and files, such
as Qt GUI or console applications and Qt Quick applications.
You can use wizards also to add individual files to your projects.
The wizards prompt you to enter the settings needed
for that particular type of project and create the necessary files for you.
To display other types of files in the \gui Projects pane, specify them in
the project file.
\image qtcreator-new-project.png
To change the location of the project directory, and to make changes in
the build and run settings, select \gui{Tools} > \gui{Options...} >
\gui{Projects} > \gui{General}.
\section1 Using Project Wizards
To create a new project:
\list 1
\o Select \gui File > \gui{New File or Project} and select the type of your
project.
The contents of the following dialogs depend on the project type.
Follow the instructions of the wizard.
This example uses \gui {Qt Gui Application}.
\o Name the project and set its path. To select the path from a
directory tree, click \gui Browse.
Avoid using spaces and special characters in the project name and
path.
\image qtcreator-intro-and-location.png
\o Select the Qt versions to use as build targets for your project, and click
\gui{Next}.
\image qtcreator-new-project-qt-versions.png "Target setting dialog"
\note If you have only one Qt version installed, this dialog is skipped.
\o Specify the name of the class you want to create and using the
drop-down menu select its base class type.
Note that the \gui{Header file}, \gui{Source file} and
\gui{Form file} fields are automatically updated as you name your
class.
\image qtcreator-class-info.png
\o Review the project settings.
To create the project, click \gui Finish.
\image qtcreator-new-project-summary.png
\endlist
\section1 Adding Files to Projects
You can create the following types of files:
\list
\o Qt resource files, which allow you to store binary files in the
application executable
\o \QD forms and Qt QML files, which specify parts of application user
interfaces
\o C++ class, source, or header files
\o Text files
\endlist
\section2 Creating C++ Classes
The \gui {C++ Class Wizard} allows you to create a C++ header and source file for
a new class that you can add to a C++ project. Specify the class name, base
class, and header and source files for the class.
The wizard supports namespaces. To use a namespace, enter a qualified
class name in the \gui {Class name} field. For example:
MyNamespace::MySubNamespace::MyClass.
\image qtcreator-cpp-class-wizard.png "Enter Class Name dialog"
The names of the header and source file are based on the class name. To change the
default suffix of a file, click \gui Configure.
You can create your own project and class wizards. For more information,
see \l{Adding New Custom Wizards}.
\section2 Displaying Additional File Types in Projects Pane
Qt Creator determines whether to display files from the project folder
in the \gui Projects pane depending on the file type (.pro, .pri, .cpp,
.h, .ui, .qrc, and so on). To display other types of files, edit the the
project file. Add filenames as values of the \c {OTHER_FILES} variable.
You can also use wildcards.
For example, the following code specifies that text files are displayed
in the \gui Projects pane:
\code
OTHER_FILES += *.txt
\endcode
This also makes the files available in the \gui Locator.
\section1 Adding Subprojects to Projects
When you create a new project, you can add it to another project as a subproject
in the \gui{Project Management} dialog. However, you first have to edit the
.pro file of the parent project to specify that qmake uses the \c subdirs template
to build the project.
The \c subdirs template creates a Makefile for building subprojects. They can be
located either in subdirectories of the project directory or in any other directory.
The location of the targets is specified using the SUBDIRS variable. If the project file
has the same name as the directory, you can just specify the directory name. If the project
name and directory name are different, you must specify the project file name (.pro).
For more information on the SUBDIRS variable, see the
\l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#subdirs}{qmake Variable Reference}.
For example, the following code specifies that plugin_coreplugin/plugin_coreplugin.pro
and mylogin.pro belong to the project:
\code
TEMPLATE = subdirs
SUBDIRS = plugin_coreplugin \
../another/plugin/myplugin.pro
\endcode
To specify dependencies, use the \gui{Add Library} wizard. For more information,
see \l{Adding Libraries to qmake Projects}.
*/
/*!
\contentspage index.html
\previouspage creator-project-managing-sessions.html
\page creator-project-wizards.html
\nextpage creator-editor-using.html
\title Adding New Custom Wizards
If you have a team working on a large application or several applications,
you might want to standardize the way the team members create projects
and classes.
You can copy the wizard templates in the template folders
to create your own project and class wizards. They are displayed in the
\gui New dialog that opens when you choose \gui {File > New File or Project}.
In a project wizard, you can specify the files needed in a project.
You can add wizard pages to allow developers to specify settings for the
project.
In a class wizard, you can allow developers to specify the class name, base
class, and header and source files for the class.
To see how this works, rename wizard_example.xml as wizard.xml in the helloworld
and listmodels folders. After you restart Qt Creator, the \gui {Custom Classes}
and \gui {Custom Projects} categories appear in the \gui New dialog.
\image qtcreator-custom-project-wizards.png "The New dialog with custom projects and classes"
\section1 Overview of Custom Wizards
A custom wizard defines the user interface of a wizard page. The values the user enters
in the wizard are assigned field names. Field name and value pairs are then passed to
the file creation process. File creation can happen in the following ways:
\list 1
\o Template-based, where source files that contain placeholders for
the field names are provided. During processing, the placeholders are replaced
by the values from the wizard page. Optionally, modifier
characters are applied. For more information, see \l{Processing Template Files}.
\o Generator script, where a script is called to create the files.
\note This option mainly exists to accommodate existing generator scripts or
cases where complicated algorithmic logic is required when generating files. Writing
cross-platform scripts is inherently difficult, and therefore, it is not recommended
for new wizards. For more information, see \l{Using Generator Scripts}.
\endlist
Custom wizards are located in subdirectories of the following directories:
\list
\o \c{share/qtcreator/templates/wizards}
\o the local user's configuration folder,
\c{$HOME/.config/Nokia/qtcreator/templates/wizards}
\o \c{%APPDATA%\Nokia\qtcreator\templates\wizards}
\endlist
They contain an XML configuration file called wizard.xml, the
template source files, and optionally, the generator script.
\section1 Creating Project Wizards
To create a project wizard:
\list 1
\o Make a copy of the \c {share/qtcreator/templates/wizards/helloworld} or
\c {share/qtcreator/templates/wizards/listmodel} folder.
\o Modify the wizard_example.xml file.
\o The following code determines the type of the wizard and its place
in the \gui New dialog:
\code
\endcode
\list
\o \c version is the version of the file contents. Do not modify this value.
\o \c kind specifies the type of the wizard: \c project or \c class.
\o \c class specifies the type of the project. Currently the only available
type is \c qt4project, which specifies a Qt console project.
\o \c firstpage specifies the place of the new page in the standard project
wizard. The value 10 ensures that the custom page appears after the standard
pages, as the last page of the wizard.
\o \c id is the unique identifier for your wizard. The letter specifies the
position of the wizard within the \c category. The HelloWorld wizard appears
as the first wizard in the second category in the \gui New dialog.
\o \c category is the category in which to place the wizard in the list.
The letter specifies the position of the category in the list in the \gui New
dialog.
\endlist
\o The following code specifies the icon and text that appear in the \gui New
dialog:
\code
console.png
Creates a hello-world-project with custom message.
Erzeugt ein Hello-Welt-Projekt mit einer Nachricht.
Hello World;
Hallo Welt;
Custom Projects
Benutzerdefinierte Projekte
\endcode
\list
\o \c icon appears next to the \c displayName.
\o \c description appears at the bottom of the \gui New dialog when you
select the display name.
\o \c displayName appears in the \gui New dialog, under the
\c displayCategory.
You can add translations as values for the text elements. Specify the target
language as an attribute for the element. Use locale names (QLocale).
For example, \c {xml:lang="de"}.
\endlist
\o Files to be added to the project:
\list
\o Template-based: The following code specifies the files to add to the project:
\code
\endcode
\list
\o \c source specifies the file to copy to the project. The files must be
located in the wizard folder.
\o \c openeditor indicates that the file is to be opened in an editor after
the wizard has finished.
\o \c binary indicates that the file is a binary file (for example, an
image file). It is to be copied to the target folder as is. Placeholders
are not replaced with values.
\o \c target specifies the new filename for the file. The \c {%ProjectName%}
variable is replaced with the string that users specify in the \gui Name
field on the first page of the wizard.
\o \c openproject indicates that the file is a project file which is to be opened
after the wizard has finished.
\endlist
See also \l{Processing Template Files}.
\o Generator-script: The following code specifies that the script \c generate.pl is to be used
to create the files:
\code
\endcode
In each argument, the field placeholders are replaced by the field
values. There are additional boolean attributes which give fine-grained control:
\list
\o \c omit-empty specifies that complete argument is to be omitted when all
placeholders expand to empty values. In the above example,
the option \c --source-suffix will not be passed to the script if the value is empty.
\o \c write-file indicates that instead of the expanded value,
the value will be written to a temporary file and its file name will be
passed to the script instead. This is useful for multi-line text fields.
\endlist
See also \l{Using Generator Scripts}.
\endlist
\o The following code creates a page that specifies settings for the project:
\code
Hello World Parameters
Hallo Welt Parameter
Hello world message:
Hallo-Welt-Nachricht:
\endcode
\list
\o \c fieldpagetitle specifies the title of the page.
\o \c field specifies whether the field is mandatory (\c true or \c false).
You can use the value of the \c name field as a variable in other files (for
example, \c {%MESSAGE%}.
\o \c fieldcontrol specifies the field. \c class specifies the field type.
You can use interface objects from the QWidget class to create fields. This
example uses QLineEdit to create an input field.
\o \c validator specifies a regular expression to check the characters allowed in
the field.
\o \c defaulttext specifies text that appears in the field by default.
\o \c fielddescription specifies the field name that appears on the wizard page.
\endlist
\endlist
\section1 Creating Class Wizards
The widget.xml file for a class wizard is very similar to that for a project
wizard. The differences are discussed below.
To create a class wizard:
\list 1
\o The following code specifies settings for the wizard:
\code
Creates a QAbstractListModel implementation.
Erzeugt eine Implementierung von QAbstractListModel.
QAbstractListModel implementation
Implementierung von QAbstractListModel
Custom Classes
Benutzerdefinierte Klassen
\endcode
For more information about the elements and their values, see
\l {Creating Project Wizards}.
\o The following code specifies the files to add to the project:
\code
\endcode
Here, \c target contains the following variables that are used to construct
the filename:
\list
\o \c {%ClassName:l%} is replaced with the value of the \c ClassName field.
The modifier \c l converts the string to lower case, to observe Qt
conventions.
\o \c {%CppSourceSuffix%} and \c {%CppHeaderSuffix%} are pre-defined.
For more information, see \l{Pre-defined Standard Variables}.
\endlist
\code
ListModel parameters
Parameter des ListModel
Class name:
Klassenname:
Data type:
Datentyp:
\endcode
In addition to QLineEdit, QComboBox is used in the class wizard to create
a field. \c combochoices specifies the options in the combobox and
\c defaultindex specifies that QString is the default value.
\endlist
\section1 Processing Template Files
When processing a template source file, placeholders specifying the field names
in the format \c{%FIELDNAME%} are replaced by the values entered by the user.
In addition, modifier characters are supported. For example, \c{%FIELDNAME:u%}
specifies that the value is converted to upper case. This enables generating header
guards for C++ header files.
The following modifier characters are supported:
\list
\o \c{l} for lower case.
\o \c{u} for upper case.
\o \c{c} for upper case initial letter ("project" > "Project").
\endlist
You can use conditions to add sections of the file depending on field values.
Use a syntax that is similar to C++ preprocessing, as demonstrated in
the profile of the \c{helloworld} example:
\code
@if "%SCRIPT%" == "true"
QT += script
@endif
\endcode
The value of the Boolean (QCheckBox) field labeled \c{SCRIPT} determines
whether the script module is added. The expressions must expand to valid
Javascript expressions after field replacement.
\section1 Pre-defined Standard Variables
In addition to the field values entered by the user, you can use
the following pre-defined standard values:
\list
\o \c {%ProjectName%} is replaced by the name of the project in the case
of project wizards.
\o \c {%Path%} is replaced by the path to the target directory.
For classes, this is the directory, where the files
are created. For project wizards, an additional subdirectory
named after the project is created.
\o \c {%TargetPath%} is replaced by the path to the directory where the actual files
are created. For non-project wizards, it is identical to \c %Path%.
For project wizards, it is \c %Path%/%ProjectName%.
\o \c {%CppSourceSuffix%} is replaced by the default source suffix, which
is defined in Qt Creator in \gui {Tools > Options... > C++ > File Naming}.
For example, if users enter \bold MyClass, the filename becomes myclass.cpp
when the project is created.
\o \c {%CppHeaderSuffix%} is replaced by the default header suffix, which
is also defined in \gui {File Naming}.
\endlist
\section1 Validating User Input
You can specify validation rules for user input. The rules consist of a Boolean
JavaScript expression and an error message. The placeholders in them are
replaced with values before they are evaluated or displayed.
Consider the following rule used in the \l{Creating Class Wizards} example:
\code
%ClassName% cannot be used as class name.
%ClassName% kann nicht als Klassenname verwendet werden.
\endcode
It ensures that the class name entered by the user does not match the name of
the base class. If the validation fails, a red label displaying the message appears
at the bottom of the wizard page.
\section1 Using Generator Scripts
The values entered in the wizard page are passed to the script
as command line arguments as defined by the wizard configuration file.
In addition, the script must implement a \c{--dry-run} command line option.
Qt Creator needs to know the file names before the files are created to check
whether files with identical names already exist, for example. Therefore,
script file generation is a two-step process:
\list 1
\o Determine file names and attributes: The script is called with the command line
\c{--dry-run} option and the field values. It then prints the relative path
names of the files it intends to create, followed by comma-separated attributes
matching those of the \c{} element, for example:
\code
myclass.cpp,openeditor
myclass.h,openeditor
myproject.pro,openproject
\endcode
\o Create files: The script is called with the parameters only in the working directory.
It then actually creates the files. If directories are needed, the script
should create them, too.
\endlist
The \c{scriptgeneratedproject} sample wizard illustrates the usage.
A typical script invocation for this example (obtained by running Qt Creator with
\c{--customwizard-verbose}) looks as follows:
\code
generate.pl --class-name=TestClass --project-name=TestProject --header-suffix=h --source-suffix=cpp --description=/tmp/qtcreatorj26629.txt
\endcode
By default, the scripts are run in the directory corresponding to
\c %TargetPath%. This can be overriden by specifying the
attribute \c workingdirectory on the element \c generatorscript.
For example, if the script creates the project directory by itself,
%Path% can be specified. In that case, \c --dry-run should output
the correct relative paths or absolute paths constructed using the value of
\c %Path%.
*/
/*!
\contentspage index.html
\previouspage creator-project-creating.html
\page creator-project-qmake.html
\nextpage creator-project-qmake-libraries.html
\title Setting Up a qmake Project
The qmake tool helps simplify the build process for development projects
across different platforms. qmake automates the generation of makefiles
so that only a few lines of information are needed to create each makefile.
qmake can be used for any software project, whether it is written in Qt or not.
The qmake tool generates a makefile based on the information in a project
file that is generated by Qt Creator. It can generate makefiles for MinGW,
Microsoft Visual studio, and CSL ARM in Windows, and GNU Compiler Collection
(GCC) in Linux and Mac OS X.
For more information about qmake, see the
\l{http://qt.nokia.com/doc/4.7/qmake-manual.html}{qmake Manual}.
\section1 Selecting the Qt Version
Qt Creator allows you to have multiple versions of Qt installed on
your development PC and use different versions for each of your projects.
If Qt Creator finds \bold qmake in the \c{PATH} environment variable, it uses
that version. The \l{glossary-system-qt}{ qmake version of Qt} is referred
to as \bold{Qt in PATH}. If you intend to use only one version of Qt and it
is already in the \c{PATH} and correctly set up for command line use, you do
not need to manually configure your Qt version.
\section2 Compiling Projects with MinGW in Windows
To add a Qt version for \bold MinGW:
\list 1
\o Select \gui Tools > \gui Options... > \gui Qt4 >
\gui{Qt Versions}.
\o Click \inlineimage qtcreator-windows-add.png
and enter the name of the version in the \gui{Version name} field.
\o Enter the qmake binary path in the \gui{qmake location} field.
\o Enter the MinGW installation path in the \gui{MinGW directory} field.
\image qtcreator-qt4-qtversions-win-mingw.png
\endlist
\section3 Troubleshooting MinGW Compilation Errors
If error messages displayed in the \gui {Compile Output} pane contain
paths where slashes are missing (for example, C:NokiaQtSDK),
check your PATH variable. At the command line, enter the following commands:
\code
where sh.exe
where make.exe
where mingw32-make.exe
\endcode
If these commands show paths, they have been added to the global PATH variable
during the installation of a toolkit based on Cygwin or MinGW, even though
this is against Windows conventions.
To keep working with the third-party toolkit, create a new shell link
that adds the required paths (as Visual Studio and Qt do). The shell link
must point to cmd.exe, as illustrated by the following example:
\c {C:\Windows\System32\cmd.exe /K C:\path_to\myenv.bat}
where the /K parameter carries out the command specified in the bat file.
Create the myenv.bat file at \e path_to, which should be in a convenient location.
In the file, specify the paths to the toolkits. For example,
\c {set PATH=C:\path1;C:\path2;%PATH%}
where \e path1 and \e path2 are paths to the toolkits.
Finally, remove the paths from the global PATH, reboot the computer, and
run the \c where commands again to verify that the global PATH is now clean.
You can use the shell link to run the tools in the third-party toolkits.
\section2 Compiling Projects with Microsoft Visual C++
To add a Qt version for a \bold{Microsoft Visual C++} compiler:
\list 1
\o Select \gui Tools > \gui Options... > \gui Qt4 >
\gui{Qt Versions}.
\o Qt Creator automatically sets the correct environment variables for
compilation. Select the internal version number of the installed
Microsoft Visual C++ tool chain in the \gui Toolchain list.
\image qtcreator-qt4-qtversions-win-msvc.png
\o If the \gui {Debugging helper} is not in use, click \gui Rebuild
to take it to use. For more information, see \l{Using Debugging Helpers}.
\endlist
\section2 Compiling Qt for Symbian Projects
If you are using \bold{Qt for Symbian} and your Symbian SDK is registered
with devices.exe, Qt Creator automatically detects the Qt version. To add a
Qt for Symbian version:
\list 1
\o Select \gui Tools > \gui Options... > \gui Qt4 >
\gui{Qt Versions}.
\o Select the \gui{S60 SDK} you want the Qt Creator to use.
\image qtcreator-qt4-qtversions-win-symbian.png
\o To build an application for your device using GCCE, enter the path
to the CSL ARM toolchain directory in
\gui{CSL\\GCCE Directory}.
You do not need to specify this path if the compiler is included in
the \c{PATH} environment variable.
\o To build an application for the emulator (WINSCW toolchain), enter
the path to your Carbide C++ installation directory in
\gui{Carbide directory}.
\note You need to have Carbide C++ version 2.0 or later installed.
\endlist
\section2 Compiling Projects With Linux
To compile a project in Qt Creator, Linux uses GNU Compiler Collection
(GCC). Intel Compiler Collection (ICC) is supported as a drop-in
replacement for GCC.
To add a Qt version:
\list 1
\o Select \gui Tools > \gui Options... > \gui Qt4 >
\gui{Qt Versions}.
\o Click \inlineimage qtcreator-linux-add.png
and enter the name of the version in \gui{Version Name}.
\o Enter the path to the qmake binary in \gui{Path to qmake}.
\endlist
\section2 Compiling Projects With Mac OS X
To compile a project in Qt Creator, Mac OS X uses GNU Compiler Collection
(GCC), which is part of Xcode.
To add a Qt version:
\list 1
\o Select \gui{Qt Creator} > \gui Preferences... > \gui{Qt Versions}.
\o Click \inlineimage qtcreator-macosx-add.png
and enter the name of the version in \gui{Version Name}.
\o Enter the path to the qmake binary in \gui{Path to Qmake}.
\image qtcreator-qt4-qtversions.png
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-project-qmake.html
\page creator-project-qmake-libraries.html
\nextpage creator-project-cmake.html
\title Adding Libraries to qmake Projects
In addition to Qt libraries, you can add other libraries to your projects.
The way the library is added depends on whether it is a system library or
your own library or a 3rd party library located in the build tree of the
current project or in another build tree.
\image qtcreator-add-library-wizard.png "Add Library wizard"
Because system libraries do not typically change and are often found by
default, you do not need to specify the path to the library or to its includes
when you add it.
For your own libraries and 3rd party libraries, you need to specify
the paths. Qt Creator tries to quess the include path for an external library,
but you need to check it and modify it if necessary. Qt Creator automatically
adds the include path for an internal library.
For all libraries, select the target platforms for the application, library,
or plugin.
Specify whether the library is statically or dynamically linked. For a
statically linked internal library, Qt Creator adds dependencies
(PRE_TARGETDEPS) in the project file.
Depending on the development platform, some options might be detected
automatically. For example, on Mac OS, the library type (\gui Library or
\gui Framework) is detected automatically and the option is hidden. However,
if you develop on another platform than Mac OS and want to build your
project for the Mac OS, you must specify the library type.
The default convention on Windows is that the debug and release versions
of a library have the same name,
but are placed in different subdirectories, usually called \e debug and
\e release. If the library path does not contain either of these folders,
you cannot select the option to place the libraries in separate
folders.
Alternatively, the letter \e d can be added to the library name for the debug
version. For example, if the release version is called example.lib, the
debug version is called exampled.lib. You can specify that the letter
is added for the debug version and removed for the release version.
If the library name ends in \e d, deselect the \gui {Remove "d" suffix
for release version} option.
Qt Creator supports code completion and syntax highlighting for the added
libraries once your project successfully builds and links to them.
\section1 To Add Libraries
\list 1
\o In the \gui Projects pane, open the project file (.pro).
\o Right-click in the code editor to open the context menu and select
\gui {Add Library...}.
\o Follow the instructions of the wizard.
\endlist
For more information about the project file settings, see
\l{http://doc.qt.nokia.com/4.7/qmake-project-files.html#declaring-other-libraries}{Declaring other Libraries}.
\section1 Example of Adding Internal Libraries
The following example describes how to add a statically linked internal
library to your project.
\list 1
\o Choose \gui {File > New File or Project... > Other Projects >
C++ Library} to create the library.
The \gui {Introduction and Product Location} dialog opens.
\image qtcreator-add-library-wizard-ex-1.png "Introduction and Product Location dialog"
\o In the \gui Type field, select \gui {Statically Linked Library}.
\o In the \gui Name field, give a name for the library. For example,
\bold mylib.
\o Follow the instructions of the wizard until you get to the
\gui {Project Management} dialog. In the \gui {Add to project}
list, select a project. For example, \bold myapp.
\o In the \gui Projects pane, open the project file (.pro).
For example, \bold myapp.pro.
\o Right-click in the code editor to open the context menu and select
\gui {Add Library... > Internal Library > Next}.
\o In the \gui Library field, select \bold mylib and click \gui Next.
\o Click \gui Finish to add the following library declaration to the
project file:
\code
win32:CONFIG(release, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/release/ -lmylib
else:win32:CONFIG(debug, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/debug/ -lmylib
else:symbian: LIBS += -lmylib
else:unix: LIBS += -L$$OUT_PWD/../../../projects/mylib/ -lmylib
INCLUDEPATH += $$PWD/../../../projects/mylib
DEPENDPATH += $$PWD/../../../projects/mylib
win32:CONFIG(release, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/release/mylib.lib
else:win32:CONFIG(debug, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/debug/mylib.lib
else:unix:!symbian: PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/libmylib.a
\endcode
\endlist
*/
/*!
\contentspage index.html
\previouspage quick-application-logic.html
\page creator-building-running.html
\nextpage creator-building-targets.html
\title Building and Running Applications
Qt Creator provides support for building and running Qt applications for
desktop environment and mobile devices. When you install the Nokia Qt SDK,
the build and run settings for the Maemo and Symbian targets are
set up automatically.
You can add a target if the necessary tool chain is installed on the
development PC and the Qt version is configured. Click
\inlineimage qtcreator-qt4-addbutton.png "Add Target button"
and select from a list of available
targets. To remove a target, select it and click
\inlineimage qtcreator-target-remove.png "Remove Target button"
.
You can select the targets and click the \gui Run button to build and
run the applications on the targets. You can click the \gui {Build All}
button to build all open projects, one after another.
\section1 Setting Up a Project
To view and modify the settings for currently open projects, switch to the
\gui Projects mode by pressing \key Ctrl+5.
\image qtcreator-projectpane.png
The project pane consists of the following tabs:
\list
\o \l{Building for and Running on Multiple Targets}{Targets}
\note If you have installed only one tool chain, the \gui Targets
tab is replaced by a \gui {Build and Run} tab.
\o \l{Specifying Editor Settings}{Editor Settings}
\o \l{Specifying Dependencies}{Dependencies}
\endlist
Use the \gui Build and \gui Run buttons to switch between
the build and run settings for the active project.
If you have multiple projects open in Qt Creator, use
\gui{Select a Project} option at the top to navigate between different
project edits.
*/
/*!
\contentspage index.html
\previouspage creator-building-running.html
\page creator-building-targets.html
\nextpage creator-build-settings.html
\title Building for and Running on Multiple Targets
You can build your application for multiple targets and run and debug it
on the desktop and mobile devices. When you run the application on the
\gui{Maemo} or \gui {Symbian Devices} target, Qt Creator copies the necessary
files to the device that is connected to the deveopment PC. In addition, Qt
Creator generates an installation package in the build directory. You can
specify settings for deploying the files and creating the installation package.
\section1 Building for and Running on Desktop
\list 1
\o Select \gui Desktop as the target.
\o Click the \gui Run button.
\endlist
\section1 Building for and Running on Qt Simulator
You can use the Qt Simulator to test Qt applications that are intended
for mobile devices in an environment similar to that of the device. You
can change the information that the device has about its configuration
and environment.
\list 1
\o Select \gui {Qt Simulator} as the target.
\o Click the \gui Run button.
\endlist
For more information about using the Qt Simulator, see the
\l{http://doc.qt.nokia.com/qt-simulator-beta/index.html}{Qt Simulator Manual}.
\section1 Building for and Running on Maemo
\list 1
\o Build and run the application for \l{Building for and Running on Qt Simulator}{Qt Simulator}.
\o Build and run the application for \l{Using the Maemo Emulator}{Maemo Emulator}.
\o Alternatively, you can build and run the application for a device:
\list 1
\o Set up the MADDE development environment and specify a connection
to the device. For more information, see
\l{Setting Up Development Environment for Maemo}.
\o Connect the device to the development PC.
\o Click the \gui Run button.
\endlist
\endlist
Qt Creator uses the compiler specified in the MADDE toolchain to
build the application.
Qt Creator generates an installation package, installs in on the device,
and executes it. You can skip the packaging step to save some time.
The application views are displayed on the Nokia N900.
Command-line
output is visible in the Qt Creator \gui {Application Output} view.
Choose \gui {Projects > Maemo Run} to view the settings for deploying the
application on the connected device and creating the installation package.
For more information, see \l{Specifying Run Settings for Maemo Devices}.
Debugging also works transparently.
\section1 Building for and Running on Symbian
\list 1
\o Build and run the application for \l{Building for and Running on Qt Simulator}{Qt Simulator}.
\o If no problems are found, build and run the application for a device.
\o To test functionality that uses Symbian APIs, you can build and
run the application for Symbian Emulator.
\endlist
The build configuration for the \gui{Symbian Device} target
uses the GCCE tool chain by default. If you want to build
for the device using RVCT, select it in the \gui {Tool chain} field
in the \gui{General} section.
\section2 Building and Running for a Device
\list 1
\o Install the required software on the device. For more information, see
\l{Setting Up Development Environment for Symbian}.
\o Connect the device to the development PC through a USB cable.
The target selector displays a green check mark when a
device is connected.
\image qtcreator-qt4-symbian-device-connected.png
The tool tip of the target selector shows more details about the actual
device that will be used when you run your application.
\o Start the \gui{App TRK} application on your device.
\o Click the \gui Run button.
\endlist
You can connect several devices to your development PC simultaneously.
In the details of the run configuration for the \gui{Symbian Device} target,
select the device to run your application on.
When you build the application for the \gui{Symbian Device} target, Qt
Creator automatically generates a Symbian installation system (SIS) file
in the project folder. You can deliver the installation file to users for
installation on Symbian devices.
When your application is ready for delivery to users, specify run settings
for creating the final SIS installation packages. For more information,
see \l{Creating SIS Installation Packages}.
\section2 Building and Running for Symbian Emulator
Select
the \gui{Symbian Emulator} target as the active one, and build and run your
project.
\section2 Troubleshooting
If you cannot build the application, check if:
\list
\o You selected the Symbian Device target for building the application.
\o The settings for the Qt version you use to build your project are
correct. The path to the Symbian SDK must point to the Symbian SDK
installation directory. Select \gui Tools > \gui Options...
> \gui Debugger > \gui{Symbian TRK} and check if it points to the
debugger toolchain.
\endlist
If you cannot run the application on a device, check if:
\list
\o The device is connected through the USB cable in \e{PC Suite} mode.
\o \gui{App TRK} is running on the device, using the USB connection,
with the status \e connected.
\o The device is detected and selected in the run configuration
details.
\endlist
If you cannot run the application in the emulator, check if:
\list
\o You selected the \gui{Symbian Emulator} target for your application.
\o If you cannot select \gui {Symbian Emulator} as target, check that
Carbide.c++ is installed correctly and that the path to the Carbide.c++
installation directory is specified in the \gui{Carbide directory} field
in the build settings.
\o If the emulator process cannot be started, try closing Qt Creator and
starting the application directly from your file manager. Having
done this, Qt Creator should be able to run your projects in the
emulator.
\endlist
\note Qt Creator does not create release configurations for the
\gui {Symbian Emulator} target, because Symbian Emulator supports only debug
builds.
If this does not help to solve your problem, search the qt-creator@trolltech.com
mailing list archives or provide feedback to us via the methods described on the
\l{http://qt.gitorious.org/qt-creator/pages/Home}{Qt Creator Development Wiki}.
\section1 Building with Remote Compiler
The \gui {Remote Compiler} target is an interface to a compilation service at
Forum Nokia. It provides a simple, standardized environment for building Qt
applications and creating installation packages for Symbian and Maemo devices
when you do not have the necessary tool chains and SDKs installed or they are
not supported on the development PC. You can choose from a set of supported
devices, such as S60 3rd Edition or S60 5th Edition devices.
\note Remote Compiler is an experimental component that you must install
separately from the package that is included in the Nokia Qt SDK.
\list 1
\o In the Nokia Qt SDK installation directory, double-click
SDKMaintenanceTool.exe to install \gui {Experimental APIs}.
\o In Qt Creator, choose \gui {Tools > Options > Projects > Remote Compiler}
to log on to Forum Nokia.
\image remotecompiler-fn-logon.png "Remote Compiler options"
\o Choose \gui {Projects}.
\o Click
\inlineimage qtcreator-qt4-addbutton.png "Add Target button"
and select \gui {Remote Compiler} to add Remote Compiler as a target.
\o Click \gui Add to add mobile device platforms as build configurations.
\o Click the \gui {Target Selector} and select a build configuration.
\o Choose \gui {Build > Build All}.
\endlist
The installation package is generated in the \gui {Build directory} on
the development PC.
For more information about Remote Compiler, choose \gui {Help > Contents >
Remote Compiler}. The document is added during the installation of experimental
APIs.
*/
/*!
\contentspage index.html
\previouspage creator-building-targets.html
\page creator-build-settings.html
\nextpage creator-run-settings.html
\title Specifying Build Settings
Different build configurations allow you to quickly switch between
different build settings. By default, Qt Creator creates \bold debug
and \bold release build configurations.
You specify build settings in the \gui Projects mode.
\image qtcreator-projectpane.png
To add a new build configuration, click \gui Add and select the type of
configuration you would like to add. You can add as many build
configurations as you need.
To delete the build configuration currently selected, click \gui Remove.
\section1 Editing Build Configurations
To edit a build configuration:
\list 1
\o Select the build configuration you want to edit in
\gui{Edit Build Configuration}.
\o In section \gui General, you can specify:
\list
\o The \l{glossary-project-qt}{Qt version} you want to use to
build your project. For more information, see
\l{Selecting the Qt version}.
\o The tool chain required to build the project.
\o By default, projects are built in a separate directory
from the source directory, as \l{glossary-shadow-build}{shadow builds}.
This keeps the files generated for each target platform separate.
\note Shadow building is not supported by the Symbian build system.
Also, shadow building on Windows is not supported for Maemo.
If you only build for one target platform, you can deselect
the \gui{Shadow build} checkbox.
\endlist
\endlist
\section1 Build Steps
The build system of Qt Creator is built on qmake and make. In
\gui{Build Steps} you can change the settings for qmake and make. Qt
Creator runs the make command using the Qt version defined for the current
build configuration.
\image qtcreator-build-steps.png "Build steps"
\section2 Adding Custom Build Steps
To add custom steps to the build settings, select \gui {Add Build Step >
Custom Process Step}.
By default, custom steps are disabled. To activate a custom step, select
the \gui{Enable custom process step} check-box.
\image qtcreator-build-steps-custom.png "Custom Process Step"
You can use any environment variables as values in the fields. For a list
of variable names, click \gui {Build Environment > Details}. You can specify
variables as ${VARNAME} or %VARNAME%. For example, ${BUILDDIR} or %BUILDDIR%.
\note Qt Creator sets SOURCEDIR and BUILDDIR as part of the build environment.
For more information, see \l{Build Environment}.
\section1 Clean Steps
You can use the cleaning process to remove intermediate files. This process
might help you to fix obscure issues during the process of building a
project.
\image qtcreator-clean-steps.png "Clean steps"
You can define the cleaning steps for your builds in the \gui{Clean Steps}:
\list
\o To add a clean step using make or a custom process, click
\gui{Add Clean Step} and select the type of step you want to add.
By default, custom steps are disabled. To activate a custom step,
select the \gui{Enable custom process step} check-box.
\o To remove a clean step, click \gui{Remove Item}.
\o To change the order of steps, click
\inlineimage qtcreator-movestep.png
.
\endlist
\section1 Build Environment
You can specify the environment you want to use for building in the
\bold{Build Environment} section. 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 automatically sets the
necessary environment variables. You can edit existing environment
variables or add, reset and unset new variables based on your project
requirements.
\image qtcreator-build-environment.png "Build Environment"
*/
/*!
\contentspage index.html
\previouspage creator-build-settings.html
\page creator-run-settings.html
\nextpage creator-editor-settings.html
\title Specifying Run Settings
Qt Creator automatically creates run configurations for your project.
To view and modify the settings, select \gui {Projects > Run}.
The settings to specify depend on the type of the project: qmake project
or Qt Quick project.
Click \gui Add to add run settings for a project and \gui Remove to remove
the current settings.
\section1 Specifying Run Settings for qmake Projects
The run configurations for qmake projects derive their executable from the parsed .pro
files.
\section2 Specifying Run Settings for Desktop Targets
You can specify command line arguments to be passed to the executable
and the working directory to use. The working directory defaults to
the directory of the build result.
For console applications, check the \gui{Run in Terminal} check box.
If you need to run with special environment variables set up, you
also do it in the run configuration settings.
\image qtcreator-pprunsettings.png
You can also create custom executable run configurations where you
can set the executable to be run. For more information, see
\l{Specifying a Custom Executable to Run}.
\section2 Specifying Run Settings for Symbian Devices
Qt Creator automatically detects Symbian devices that are connected to
the development PC with an USB cable.
If only one device is detected, the application is deployed
and run on it. If multiple devices are connected to the PC,
make sure that the correct device is selected in the
\gui {Symbian Device} run settings for your project.
You can also pass command line arguments to your application on the device.
Press the \gui{Device info button} to get more information about the selected
device, such as the CPU type and the running TRK version.
\image qtcreator-symbian-run-settings.png "Run settings for Symbian devices"
\section3 Creating SIS Installation Packages
When you build the application for the \gui{Symbian Device} target, Qt
Creator automatically generates a Symbian installation system (SIS) file
in the project folder. You can deliver the installation file to users for
installation on Symbian devices.
The name of the installation file is displayed in the \gui {Installation file}
field. In the \gui {Installation drive} field, select the drive on the device
to install the application to. To suppress notifications on the device during the
installation, select the \gui {Silent installation} check box. If the silent
installation fails, Qt Creator attempts installation again, this time displaying
notifications and error messages.
Only installation files signed with a certificate and private key are
allowed to be installed onto Symbian devices. By default, Qt Creator
self-signs the installation file. This self-signing allows you to install
the application on a mobile device but places limits on what you can do
with the installation file, including:
\list
\o Self-signed applications cannot access the more sensitive
\l{Capabilities and Signing}{capabilities} of the mobile device.
\o Security warnings will be displayed when you install the self-signed
application on a mobile device.
\o Self-signed applications cannot be distributed commercially on Ovi
Store.
\endlist
To get around these limitations, you need to go through the Symbian Signed
process. The Symbian Signed organisation manages a public key
infrastructure to provide public authentication of the information in the
application signing certificates. Their security partner can validate your
certificate and give you a Publisher ID. Then, when you sign an
application, other people can be confident that the information in your
certificate is correct and that the application does actually come from you.
There are also options that do not require you to get a Publisher ID. For
more detail about how the Symbian Signed process works, see
\l{http://developer.symbian.org/wiki/index.php/Complete_Guide_To_Symbian_Signed}
{Complete Guide to Symbian Signed}.
When you have your own certificate and private key, you can specify them in
the \gui{Create SIS Package} step in the run settings.
\image qtcreator-qt4-symbian-signing.png
If your private key is protected by a passphrase, Qt Creator asks you for the
passphrase when the package is signed and offers to store it. However, storing
passphrases in Qt Creator presents a security risk. To make Qt Creator forget
all saved passphrases, click \gui {Reset Passphrases}.
\section3 Capabilities and Signing
Capabilities allow the Symbian platform to control access by applications to
the functionality provided by the platform APIs. Access to capabilities is
determined by the device configuration and how the application has been signed.
Symbian Signed offers the following signing options depending on the
capabilities that the application accesses:
\list
\o \bold{Express signed} for applications that access only user and system
capabilities.
\o \bold{Certified signed} for applications that access also restricted or
device manufacturer capabilities.
\note You need to request the rights to access device manufacturer
capabilities from the manufacturer.
\endlist
For more information about how to choose the appropriate signing option, see
\l{http://developer.symbian.org/wiki/index.php/Symbian_Signed_For_Distributing_Your_Application}{Symbian Signed For Distributing Your Application}.
If you select a signing option that does not allow the application to access
the defined capabilities, installing the application on mobile devices
fails. To avoid problems, only define capabilities and link libraries to a project
if you really need them.
For more information about capabilities and how you can check which ones you
need, see
\l{http://developer.symbian.org/wiki/index.php/Capabilities_(Symbian_Signed)}{Capabilities (Symbian Signed)}
and
\l{http://doc.qt.nokia.com/4.7/platform-notes-symbian.html#required-capabilities}{Required Capabilities for Qt Applications}.
For more information on how to define capabilities for a project, see
\l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#capabilities}{Capabilities}.
\section3 Creating Smart Installer for Symbian Packages
To deploy Qt applications on Symbian devices, you must install the software that Qt applications
require, typically Qt, QtWebkit, and Open C. Nokia Smart Installer for Symbian makes it easier
for users to install Qt applications to Symbian phones by checking whether the device contains
the necessary software and by installing the missing pieces.
For this to work, the Nokia Smart Installer must be packaged with the Qt application. The
application SIS file must first be Symbian Signed. The capabilities used in the applications
determine, which signing option must be selected. The wrapper package must be signed using
either the same option or a more extensive option than the application SIS.
To package Nokia Smart Installer with the application, select the \gui {Create Smart Installer
package} check box. This ensures that up-to-date and appropriate versions of Qt and its
dependencies are installed on devices. Further, it reduces the file size of the application you
publish, because you do not have to deliver the required applications.
For more information about the Nokia Smart Installer, see the \e {Nokia Smart Installer for
Symbian Manual}.
Note: Nokia Smart Installer for Symbian is only available on Windows.
\section3 Application UID
A UID is a globally unique identifier that is used to
uniquely identify, for example, an object or file type. In Symbian development,
objects are identified by compound identifiers that are constructed from three
UIDs, namely UID1, UID2, and UID3. UID1 and UID2 specify the category of an
object, whereas UID3 identifies a particular object, such as an application.
When you create a \gui {Mobile Qt Application}, Qt Creator adds a UID3 suitable for
development and debugging automatically to the application .pro file. However, to
distribute your application and get it Symbian signed, you must apply for a UID
from Symbian Signed, which manages the allocation of UIDs. You can request UIDs either one
at a time or as preallocated blocks on the \l{https://www.symbiansigned.com/app/page}{Symbian Signed}
web site.
Replace the testing UID with the distribution UID in the .pro file before you
build the final installation package. For more information, see
\l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#unique-identifiers}{Unique Identifiers}.
\section2 Specifying Run Settings for Maemo Devices
To run an application on a Maemo device, create and select
a device configuration in the Maemo run settings for your project.
You can also pass command line arguments to your application.
\image qtcreator-screenshot-run-settings.png "Run settings for Maemo devices"
\section3 Deploying Applications to Maemo Devices
You can specify settings for deploying applications to Maemo devices in the
project .pro file. You can view the settings in the \gui {Run Settings}.
When you test your application on a device or the Maemo emulator, you can
save some time by installing the built files directly on the connected device
without packaging. Select the \gui {Skip packaging step} check box in the
\gui {Create Package} step. However, this is not recommended and is only supported
for simple application projects.
The files to be installed are listed in the
\gui {Deploy to Device} step, the \gui {Files to install} field. The
\gui {Local File Path} field displays the location of the file on the development
PC. The \gui {Remote Directory} field displays the folder where the file is installed on
the device.
\image qtcreator-maemo-deployment.png "Deploy to device"
If you develop your own libraries, Qt Creator needs to be able to access them
during compilation. When you install MADDE, an instance of the device file
system, called sysroot, is installed to the development PC. Libraries are copied to
sysroot if the \gui {Also deploy to sysroot} check box is selected.
\section3 Creating Debian Installation Packages
When you run the application on the \gui{Maemo} target, Qt Creator generates
a debian installation package in the build directory by default. You can deliver
the installation package to users for installation on Maemo devices that are of
the same type and run the same firmware as the connected device.
\image qtcreator-maemo-deb-package.png "Create installation package"
The name of the installation package is displayed in the \gui {Create Package}
field in the \gui {Run Settings}. You can change the version number in the \gui {Version number} field.
Qt Creator provides templates for a set of files that must be included
in debian packages. To edit the files, select a file in \gui {Adapt debian
file} and click \gui Edit. The file opens in the text editor.
The debian control file contains an application icon in encoded form. To add the
application icon to the file, select it in the \gui {Package manager icon} field.
For more information about icon files and adding them manually, see
\l{ http://wiki.maemo.org/Packaging#Displaying_an_icon_in_the_Application_Manager_next_to_your_package}{Displaying an icon in the Application Manager next to your package}.
\note Qt Creator automates this process for you.
\section1 Specifying a Custom Executable to Run
If you use cmake or the generic project type in Qt Creator, or want
to run a custom desktop executable, create a \gui {Custom Executable}
run configuration for your project.
Specify the executable to run, command line arguments, working directory,
and environment variables to use.
\image qmldesigner-run-custom-exe.png "Run settings for custom executables"
\section1 Specifying Run Settings for Qt Quick Projects
Select run settings in the \gui {Run configuration} field. The settings
are specified automatically and, you mostly need to change them if you
develop applications that use both C++ and QML:
\list
\o \gui {Custom QML Viewer} is the path to the \QQV executable.
Qt Creator ships with a specific version of \QQV and imported
modules, which is used by default. If you develop Qt Quick applications
that contain C++ plugins, you must select the \QQV version
shipped with your Qt version here.
\o \gui {QML Viewer arguments} sets arguments for running \QQV.
The \c{-I } argument searches for C++ or QML plugins from
the project folder. For a list of available arguments, enter \c {qml --help}
on the command line.
\o \gui {Main QML file} is the Qt Quick project file.
\o \gui Debugger allows you to select the languages to debug:
\gui{C++} and \gui QML. \gui {Debug port} is the port to access \QQV.
You can use any free port in the registered port range.
\endlist
\image qmldesigner-run-settings.png "Run settings for Qt Quick projects"
*/
/*!
\contentspage index.html
\previouspage creator-run-settings.html
\page creator-editor-settings.html
\nextpage creator-build-dependencies.html
\title Specifying Editor Settings
To define the default file encoding, select the desired encoding in \gui Projects >
\gui{Editor Settings}. By default, the Qt Creator uses the file encoding
used by your system.
\image qtcreator-editor-settings.png "Editor Settings view"
*/
/*!
\contentspage index.html
\previouspage creator-editor-settings.html
\page creator-build-dependencies.html
\nextpage creator-debugging.html
\title Specifying Dependencies
If you have multiple projects loaded in your session, you can define the
dependencies between them. Inter-project dependencies affect the build
order of your projects.
\note Inter-project dependencies are unrelated inside a qmake
project.
\image qtcreator-build-dependencies.png "Dependencies view"
To define the dependencies between projects:
\list 1
\o In \gui Projects, select a project.
\o Click \gui Dependencies.
\o Select projects as dependencies.
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-quick-tour.html
\page creator-getting-started.html
\nextpage creator-build-example-application.html
\title Getting Started
This section contains examples that illustrate how to use Qt Creator
to create, build, and run simple
applications:
\list
\o \l{Building and Running an Example Application}
\o \l{Creating a Qt C++ Application}
\o \l{Creating a Mobile Application with Nokia Qt SDK}
\o \l{Creating a Qt Quick Application}
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-writing-program.html
\page creator-mobile-example.html
\nextpage creator-qml-application.html
\title Creating a Mobile Application with Nokia Qt SDK
\note To complete this tutorial, you must install Nokia Qt SDK.
The installation program installs and configures the necessary tool chains
for mobile application development.
This tutorial describes how to use Qt Creator to create a small Qt
application, Battery Indicator, that uses the System Information
Mobility API to fetch battery information from the device.
\image qtcreator-batteryindicator-screenshot.png
\section1 Creating the Battery Indicator Project
\note Create the project with the \gui{Help} mode active so that you can follow
these instructions while you work.
\list 1
\o Select \gui{File > New File or Project > Qt C++ Project > Mobile Qt
Application > Choose}.
\image qtcreator-new-mobile-project.png "New File or Project dialog"
The \gui{Introduction and Project Location} dialog opens.
\image qtcreator-mobile-intro-and-location.png "Introduction and Project Location dialog"
\o In the \gui{Name} field, type \bold {BatteryIndicator}.
\o In the \gui {Create in} field, enter the path for the project files. For example,
\c {C:\Qt\examples}, and then click \gui{Next}.
The \gui{Select Required Qt Versions} dialog opens.
\image qtcreator-mobile-project-qt-versions.png "Select Required Qt Versions dialog"
\o Select \gui Maemo, \gui {Qt Simulator}, and \gui {Symbian Device} targets,
and click \gui{Next}.
\note Targets are listed if you installed the appropriate development
environment, for example, as part of the Nokia Qt SDK.
The \gui{Class Information} dialog opens.
\image qtcreator-mobile-class-info.png "Class Information dialog"
\o In the \gui{Class Name} field, type \bold {BatteryIndicator} as the class name.
\o In the \gui{Base Class} list, select \bold {QDialog} as the base class type.
\note The \gui{Header File}, \gui{Source File} and \gui{Form File} fields are
automatically updated to match the name of the class.
\o Click \gui{Next}.
The \gui{Project Management} dialog opens.
\image qtcreator-mobile-project-summary.png "Project Management dialog"
\o Review the project settings, and click \gui{Finish} to create the project.
\endlist
The BatteryIndicator project now contains the following files:
\list
\o batteryindicator.h
\o batteryindicator.cpp
\o main.cpp
\o batteryindicator.ui
\o BatteryIndicator.pro
\endlist
\image qtcreator-mobile-project-contents.png "Project contents"
The files come with the necessary boiler plate code that you must
modify, as described in the following sections. You do not need
to change the main.cpp file.
\section1 Declaring the Qt Mobility API
The \gui New wizard automatically adds information to the .pro file
that you need when you use the Qt Mobility APIs or develop applications
for Symbian devices. You must modify the information to declare the
Qt Mobility APIs that you use.
This example uses the System Info API, so you must declare it, as
illustrated by the following code snippet:
\code
CONFIG += mobility
MOBILITY = systeminfo
\endcode
Each Mobility API has its corresponding value that you have to add
as a value of MOBILITY to use the API. For a list of the APIs and the
corresponding values that you can assign to MOBILITY, see the
\l {http://doc.qt.nokia.com/qtmobility-1.0/quickstart.html}{Quickstart Example}.
The following code snippet shows information that is needed for
applications developed for Symbian device. Qt Creator generated
the UID for testing the application on a device. You only need
to change the UID and capabilities if you deliver the application
for public use and need to have it Symbian Signed.
\code
symbian {
TARGET.UID3 = 0xecbd72d7
# TARGET.CAPABILITY +=
TARGET.EPOCSTACKSIZE = 0x14000
TARGET.EPOCHEAPSIZE = 0x020000 0x800000
}
\endcode
\section1 Designing the User Interface
\list 1
\o In the \gui{Editor} mode, double-click the batteryindicator.ui
file in the \gui{Projects} view to launch the integrated \QD.
\o Drag and drop a \gui{Progress Bar} (\l{http://doc.qt.nokia.com/4.7/qprogressbar.html}{QProgressBar})
widget to the form.
\image qtcreator-mobile-project-widgets.png "Adding widgets to the UI"
\o In the \gui Properties pane, change the \gui objectName to
\bold batteryLevelBar.
\o Right-click the \gui BatteryIndicator object and select
\gui {Lay Out > Lay Out Horizontally} to ensure that the battery
indicator widget size is adjusted correctly on Maemo devices.
To adjust widget size correctly on Qt Simulator, remove the condition
from the main.cpp file (displayed in the following code snippet) and just
leave the \c {w.showMaximized();} line:
\snippet examples/batteryindicator/main.cpp 0
\endlist
\section1 Completing the Header File
The batteryindicator.h file contains some of the necessary #includes, a
constructor, a destructor, and the \c{Ui} object. You must include
the System Info header file, add a shortcut to the mobility name
space, and add a private function to update the battery level value in
the indicator when the battery power level changes.
\list 1
\o In the \gui{Projects} view, double-click the \c{batteryindicator.h} file
to open it for editing.
\o Include the System Info header file, as illustrated by the following
code snippet:
\snippet examples/batteryindicator/batteryindicator.h 1
\o Add a shortcut to the mobility name space, as illustrated by the
following code snippet:
\snippet examples/batteryindicator/batteryindicator.h 2
\o Declare a private function in the \c{private} section, after the
\c{Ui::BatteryIndicator} function, as illustrated by the following code
snippet:
\snippet examples/batteryindicator/batteryindicator.h 3
\endlist
\section1 Completing the Source File
Now that the header file is complete, move on to the source file,
batteryindicator.cpp.
\list 1
\o In the \gui{Projects} view, double-click the batteryindicator.cpp file
to open it for editing.
\o Create a QSystemDeviceInfo object and set its value. Then connect the signal
that indicates that battery level changed to the \c setValue
slot of the progress bar. This is illustrated by the following code snippet:
\snippet examples/batteryindicator/batteryindicator.cpp 1
\o Use the constructor to set initial values and make sure that the
created object is in a defined state, as illustrated by the following
code snippet:
\snippet examples/batteryindicator/batteryindicator.cpp 2
\endlist
\section1 Compiling and Running Your Program
Now that you have all the necessary code, select \gui {Qt Simulator}
as the target and click the
\inlineimage qtcreator-run.png
button to build your program and run it in the Qt Simulator.
In Qt Simulator, run the runOutOfBattery.qs example script
to see the value change in the Battery Indicator application.
Select \gui {Scripting > examples > runOutOfBattery.qs > Run}.
\image qtcreator-mobile-simulated.png "Mobile example in Qt Simulator"
\section1 Testing on a Symbian Device
You also need to test the application on real devices. Before you can
start testing on Symbian devices, you must connect them to the development
PC by using an USB cable and install the necessary software on them.
\list 1
\o Install Qt 4.6.2 libraries, the Qt mobile libraries, and the TRK
debugging application on the device. For more information,
see \l{Setting Up Development Environment for Symbian}.
\o Start TRK on the device.
\o Click the \gui {Target Selector} and select \gui {Symbian Device}.
\o Click \gui Run to build the application for the Symbian device.
\endlist
\section1 Testing on the Maemo Emulator
The Maemo emulator emulates the Nokia N900 device environment. You can test
applications in conditions practically identical to running the application
on a Nokia N900 device with the software update release 1.2 (V10.2010.19-1).
For more information, see \l{Using the Maemo Emulator}.
*/
/*!
\contentspage index.html
\previouspage creator-getting-started.html
\page creator-build-example-application.html
\nextpage creator-writing-program.html
\title Building and Running an Example Application
You can test that your installation is successful by opening an existing
example application project.
\list 1
\o On the \gui Welcome page, select \gui {Choose an Example... >
Animation Framework > Animated Tiles}.
\image qtcreator-gs-build-example-open.png "Selecting an example"
\o Select targets for the project. Select at least Qt Simulator
and one of the mobile targets, Maemo or Symbian Device, depending on
the device you develop for.
\image qtcreator-gs-build-example-targets.png "Selecting targets"
\note You can add targets later in the \gui Projects mode.
\o To test the application in Qt Simulator, click the \gui {Target
Selector} and select \gui {Qt Simulator}.
\image {qtcreator-gs-build-example-select-qs.png} "Selecting Qt Simulator as target"
\o Click
\inlineimage{qtcreator-run.png}
to build the application and run it in Qt Simulator.
\o To see the compilation progress, press \key{Alt+4} to open the
\gui Compile Output pane.
The \gui Build progress bar on the toolbar turns green when the project
is successfully built. The application opens in Qt Simulator.
\image {qt-simulator.png} "Qt Simulator"
\o Change the settings in the
\gui View pane, for example, to toggle the orientation by clicking
\gui {Rotate Device}, or choose from the various Symbian and Maemo
configurations by clicking \gui {Device}. You can also simulate various
mobile functions and create your own scripts.
\o To test the application on a Symbian device install Qt 4.6.2
and the TRK debugging application on the device. For more information,
see \l{Setting Up Development Environment for Symbian}.
\o Click the \gui {Target Selector} and select \gui {Symbian Device}.
\o Click \gui Run to build the application for the Symbian device.
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-mobile-example.html
\page creator-qml-application.html
\nextpage creator-project-managing.html
\title Creating a Qt Quick Application
\note This tutorial assumes that you are familiar with the \l {http://doc.qt.nokia.com/4.7/qtquick.html}
{QML declarative language}.
This tutorial describes how to use Qt Creator to create a small
Qt Quick application, Hello World.
\image qmldesigner-helloworld-edited.png "Hello World"
\section1 Creating the Hello World Project
\list 1
\o Select \gui{File > New File or Project > Qt Quick Project > Qt QML Application > Choose}.
\image qmldesigner-new-project.png "New File or Project dialog"
The \gui{Introduction and Project Location} dialog opens.
\image qmldesigner-new-project-location.png "Introduction and Project Location dialog"
\o In the \gui{Name} field, type \bold {HelloWorld}.
\o In the \gui {Create in} field, enter the path for the project files. For example,
\c {C:\Qt\examples}, and then click \gui{Next}.
The \gui{Project Management} dialog opens.
\image qmldesigner-new-project-summary.png "Project Management dialog"
\o Review the project settings, and click \gui{Finish} to create the project.
\endlist
The HelloWorld project now contains the following files:
\list
\o HelloWorld.qmlproject
\o HelloWorld.qml
\endlist
The \gui Projects pane in the \gui Sidebar displays the project files:
\image qmldesigner-new-project-contents.png "HelloWorld project contents"
The .qmlproject file defines that all QML, JavaScript, and image files in
the project folder belong to the project.
The .qml file contains the following example code that specifies a rectangle
and a label that contains
the text \bold {Hello World}.
\code
import Qt 4.7
Rectangle {
width: 200
height: 200
Text {
x: 66
y: 93
text: "Hello World"
}
}
\endcode
Your application is now ready.
\section1 Running the Application
Press \key {Ctrl+R} to run the application in the QML Viewer.
\image qmldesigner-helloworld.png "Hello World"
\section1 Changing Hello World Properties
To experiment with QML and to try some of the code editor features, change the
properties of the rectangle and text. Move the cursor on \gui Rectangle and
press \key F1 to get help on the available properties. Try adding a \gui color
property to the \gui Rectangle. When you start to type,
the code completion feature of the code editor suggests properties, IDs, and
code snippets to complete the code. Select an item in the list and press
\key Tab or \key Enter to complete the code.
The code editor checks the code syntax and underlines syntax errors.
Move the cursor over an error to display detailed information about it.
The following code illustrates how to set the backround color
to light steel blue and the text color to white:
\code
import Qt 4.7
Rectangle {
width: 200
height: 200
color: "lightsteelblue"
Text {
x: 66
y: 93
text: "Hello World"
color: "white"
}
}
\endcode
\image qmldesigner-helloworld-edited.png "Hello World in blue and white"
*/
/*!
\contentspage index.html
\previouspage creator-build-example-application.html
\page creator-writing-program.html
\nextpage creator-mobile-example.html
\title Creating a Qt C++ Application
This tutorial describes how to use Qt Creator
to create a small Qt application, Text Finder. It is a simplified version of the
QtUiTools \l{http://doc.qt.nokia.com/4.7/uitools-textfinder.html}{Text Finder}
example.
\image qtcreator-textfinder-screenshot.png
\section1 Creating the Text Finder Project
\note Create the project with two instances of Qt Creator open and the \gui{Help} mode
active in one of them so that you can follow
these instructions while you work.
\list 1
\o Select \gui{File > New File or Project > Qt C++ Project > Qt Gui
Application > Choose}.
\image qtcreator-new-project.png "New File or Project dialog"
The \gui{Introduction and Project Location} dialog opens.
\image qtcreator-intro-and-location.png "Introduction and Project Location dialog"
\o In the \gui{Name} field, type \bold {TextFinder}.
\o In the \gui {Create in} field, enter the path for the project files. For example,
\c {C:\Qt\examples}, and then click \gui{Next}.
The target setting dialog opens.
\image qtcreator-new-project-qt-versions.png "Target setting dialog"
\o Select the Qt versions to use as build targets for your project, and click
\gui{Next}.
\note If you have only one Qt version installed, this dialog is skipped.
The \gui{Class Information} dialog opens.
\image qtcreator-class-info.png "Class Information dialog"
\o In the \gui{Class Name} field, type \bold {TextFinder} as the class name.
\o In the \gui{Base Class} list, select \bold {QWidget} as the base class type.
\note The \gui{Header File}, \gui{Source File} and
\gui{Form File} fields are automatically updated to match the name of the
class.
\o Click \gui{Next}.
The \gui{Project Management} dialog opens.
\image qtcreator-new-project-summary.png "Project Management dialog"
\o Review the project settings, and click \gui{Finish} to create the project.
\endlist
The TextFinder project now contains the following files:
\list
\o textfinder.h
\o textfinder.cpp
\o main.cpp
\o textfinder.ui
\o textfinder.pro
\endlist
\image qtcreator-textfinder-contents.png "TextFinder project contents"
The .h and .cpp files come with the necessary boiler plate code.
The .pro file is complete.
\section1 Filling in the Missing Pieces
Begin by designing the user interface and then move on to filling
in the missing code. Finally, add the find functionality.
\section2 Designing the User Interface
\image qtcreator-textfinder-ui.png "Text Finder UI"
\list 1
\o In the \gui{Editor} mode, double-click the textfinder.ui file in the \gui{Projects}
view to launch the integrated \QD.
\o Drag and drop the following widgets to the form:
\list
\o \gui{Label} (QLabel)
\o \gui{Line Edit} (QLineEdit)
\o \gui{Push Button} (QPushButton)
\endlist
\image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI"
\note To easily locate the widgets, use the search box at the top of the
\gui Sidebar. For example, to find the \gui Label widget, start typing
the word \bold label.
\image qtcreator-texfinder-filter.png "Filter field"
\o Double-click the \gui{Label} widget and enter the text \bold{Keyword}.
\o Double-click the \gui{Push Button} widget and enter the text \bold{Find}.
\o In the \gui Properties pane, change the \gui objectName to \bold findButton.
\image qtcreator-textfinder-objectname.png "Changing object names"
\o Press \key {Ctrl+A} to select the widgets and click \gui{Lay out Horizontally}
(or press \gui{Ctrl+H}) to apply a horizontal layout
(QHBoxLayout).
\image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout"
\o Drag and drop a \gui{Text Edit} widget (QTextEdit)
to the form.
\o Select the screen area and click \gui{Lay out Vertically} (or press \gui{Ctrl+L})
to apply a vertical layout (QVBoxLayout).
\image qtcreator-textfinder-ui.png "Text Finder UI"
Applying the horizontal and vertical layouts ensures that the application UI scales to different
screen sizes.
\o To call a find function when users press the \gui Find button, you use the Qt signals
and slots mechanism. A signal is emitted when a particular event occurs and a slot is
a function that is called in response to a particular signal. Qt widgets have predefined
signals and slots that you can use directly from \QD. To add a slot for the find function:
\list
\o Right-click the \gui Find button to open a context-menu.
\o Select \gui {Go to Slot > clicked()}, and then select \gui OK.
A private slot, \c{on_findButton_clicked()}, is added to the header file,
textfinder.h and a private function, \c{TextFinder::on_findButton_clicked()},
is added to the source file, textfinder.cpp.
\endlist
\o Press \gui{Ctrl+S} to save your changes.
\endlist
For more information about designing forms with \QD, see the
\l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
\section2 Completing the Header File
The textfinder.h file already has the necessary #includes, a
constructor, a destructor, and the \c{Ui} object. You need to add a private
function, \c{loadTextFile()}, to read and display the
contents of the input text file in the
QTextEdit.
\list 1
\o In the \gui{Projects} pane in the \gui {Edit view}, double-click the \c{textfinder.h} file
to open it for editing.
\o Add a private function
to the \c{private} section, after the \c{Ui::TextFinder} pointer, as
illustrated by the following code snippet:
\snippet examples/textfinder/textfinder.h 0
\endlist
\section2 Completing the Source File
Now that the header file is complete, move on to the source file,
textfinder.cpp.
\list 1
\o In the \gui{Projects} pane in the \gui Edit view, double-click the textfinder.cpp file
to open it for editing.
\o Add code to load a text file using
QFile, read it with QTextStream, and
then display it on \c{textEdit} with
\l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}.
This is illustrated by the following code snippet:
\snippet examples/textfinder/textfinder.cpp 0
\o To use QFile and QTextStream, add the
following #includes to textfinder.cpp:
\snippet examples/textfinder/textfinder.cpp 1
\o For the \c{on_findButton_clicked()} slot, add code to extract the search string and
use the \l{http://doc.qt.nokia.com/4.7/qtextedit.html#find}{find()} function
to look for the search string within the text file. This is illustrated by
the following code snippet:
\snippet examples/textfinder/textfinder.cpp 2
\o Once both of these functions are complete, add a line to call \c{loadTextFile()} in
the constructor, as illustrated by the following code snippet:
\snippet examples/textfinder/textfinder.cpp 3
\endlist
The \c{on_findButton_clicked()} slot is called automatically in
the uic generated ui_textfinder.h file by this line of code:
\code
QMetaObject::connectSlotsByName(TextFinder);
\endcode
\section2 Creating a Resource File
You need a resource file (.qrc) within which you embed the input
text file. The input file can be any .txt file with a paragraph of text.
Create a text file called input.txt and store it in the textfinder
folder.
To add a resource file:
\list 1
\o Select \gui{File > New File or Project > Qt > Qt Resource File > Choose}.
\image qtcreator-add-resource-wizard.png "New File or Project dialog"
The \gui {Choose the Location} dialog opens.
\image qtcreator-add-resource-wizard2.png "Choose the Location dialog"
\o In the \gui{Name} field, enter \bold{textfinder}.
\o In the \gui{Path} field, enter \c{C:\Qt\examples\TextFinder},
and click \gui{Next}.
The \gui{Project Management} dialog opens.
\image qtcreator-add-resource-wizard3.png "Project Management dialog"
\o In the \gui{Add to project} field, select \bold{TextFinder.pro}
and click \gui{Finish} to open the file in the code editor.
\o Select \gui{Add > Add Prefix}.
\o In the \gui{Prefix} field, replace the default prefix with a slash (/).
\o Select \gui{Add > Add Files}, to locate and add input.txt.
\image qtcreator-add-resource.png "Editing resource files"
\endlist
\section1 Compiling and Running Your Program
Now that you have all the necessary files, click the \inlineimage qtcreator-run.png
button to compile and run your program.
*/
/*!
\contentspage index.html
\previouspage creator-maemo-emulator.html
\page creator-version-control.html
\nextpage creator-task-lists.html
\title Using Version Control Systems
Version control systems supported by Qt Creator are:
\table
\header
\i \bold{Version Control System}
\i \bold{Address}
\i \bold{Notes}
\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
\row
\i \bold{CVS}
\i \l{http://www.cvshome.org}
\i
\row
\i \bold{Mercurial}
\i \l{http://mercurial.selenic.com/}
\i Qt Creator 2.0 and later
\endtable
\section1 Setting Up Version Control Systems
Qt Creator uses the version control system's command line clients to access
your repositories. To allow access, make sure that the command line clients
can be located using the \c{PATH} environment variable or specify the path to
the command line client executables in \gui{Tools} > \gui{Options...} >
\gui {Version Control}.
After you set up the version control system, use the command line to check
that everything works (for example, use the status command). If no issues arise,
you should be ready to use the system also from Qt Creator.
\section2 Using msysGit on Windows
If you configure Git for use with \c {git bash}, only, and use SSH
authorization, Git looks for the SSH keys in the directory where the
\c HOME environment points to. The variable is always set by \c {git bash}.
However, the variable is typically not set in a Windows command prompt.
When you run Git from a Windows command prompt, it looks for the SSH keys in its
installation directory, and therefore, the authorization fails.
You can set the \c HOME environment variable from Qt Creator. Select \gui {Tools >
Options... > Version Control > Git}. Select the \gui {Environment Variables}
and the \gui {Set "HOME" environment variable} check boxes. \c HOME is set to
\c %HOMEDRIVE%%HOMEPATH% when the Git executable is run and authorization works
as it would with \c {git bash}.
\section1 Setting Up Common Options
Select \gui{Tools} > \gui{Options...} > \gui{Version Control} > \gui{Common}
to specify settings for submit messages:
\list
\o \gui{Submit message check 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.
\o \gui{User/alias configuration file} takes a file in mailmap format
that lists user names and aliases. For example:
\code
Jon Doe
Hans Mustermann hm
\endcode
\note The second line above 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
displays a context menu with \gui{Insert name...} that pops up a
dialog letting the user select a name.
\o \gui{User fields 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
\endlist
The fields above 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.
\section1 Creating VCS Repositories for New Projects
Qt Creator allows for creating VCS repositories for version
control systems that support local repository creation, such as
Git or Mercurial.
When creating a new project by selecting \gui File >
\gui{New File or Project...}, you can choose a version
control system in the final wizard page.
\section1 Using Version Control Systems
The \gui{Tools} menu contains a sub-menu for each supported version
control system.
The \gui{Version Control} output pane displays the commands
that are executed, a timestamp, and the relevant output.
Select \gui {Window > Output Panes > Version Control} to open
the pane.
\image qtcreator-vcs-pane.png
\section2 Adding Files
When you create a new file or a new project, the wizard displays a page
asking whether the files should be added to a version control system.
This happens when the parent directory or the project is already
under version control and the system supports the concept of adding files,
for example, Perforce and Subversion. Alternatively, you can
add files later by using the version control tool menus.
With Git, there is no concept of adding files. Instead, all modified
files must be staged for a commit.
\section2 Viewing Diff Output
All version control systems provide menu options to \e{diff} the current
file or project: to compare it with the latest version stored in the
repository and to display 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 opens an editor
displaying the file, scrolled to the line in question.
\image qtcreator-vcs-diff.png
\section2 Viewing Versioning History and Change Details
Display the versioning history of a file by selecting \gui{Log}
(for Git and Mercurial) or \gui{Filelog} (for CVS, Perforce, and
Subversion). Typically, the log output contains the date, the commit
message, and a change or revision identifier. Click on the identifier to
display a description of the change including the diff.
Right-clicking on an identifier brings up a context menu that lets you
show annotation views of previous versions (see \l{Annotating Files}).
\image qtcreator-vcs-log.png
\section2 Annotating Files
Annotation views are obtained by selecting \gui{Annotate} or \gui{Blame}.
Selecting \gui{Annotate} or \gui{Blame} displays the lines of the file
prepended by the change identifier they originate from. Clicking on the
change identifier shows a detailed description of the change.
To show the annotation of a previous version, right-click on the
version identifier at the beginning of a line and choose one of the
revisions shown at the bottom of the context menu. This allows you to
navigate through the history of the file and obtain previous versions of
it. It also works for Git and Mercurial using SHA's.
The same context menu is available when right-clicking on a version
identifier in the file log view of a single file.
\section2 Committing Changes
Once you have finished making changes, submit them to the version control
system by choosing \gui{Commit} or \gui{Submit}. Qt Creator displays a
commit page containing a text editor where you can enter your commit
message and a checkable list of modified files to be included.
\image qtcreator-vcs-commit.png
When you have finished filling out the commit page information, click on
\gui{Commit} to start committing.
The \gui{Diff Selected Files} button 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. You can also check
a diff view from the editor combo box showing the \gui{Opened files}.
\section2 Reverting Changes
To discard local changes to a file or project, use the \gui Revert
function or the \gui {Undo Changes/Undo Repository Changes} function
(for Git). The changes discarded depend on the version control system.
For example, in Perforce, select \gui{Revert File/Revert Project}
to discard changes made to open files, reverting them to the
revisions last synchronized from the repository. Select
\gui{Revert Unchanged} to revert files if their contents or file
type have not changed after they were opened for editing.
\section2 Using Additional Git Functions
The \gui Git sub-menu contains the following additional items:
\table
\row
\i \gui {Apply Patch/Apply Patch...}
\i Apply changes to a file or project from a diff file. You can
either apply a patch file that is open in Qt Creator or select
the patch file to apply from the file system.
\row
\i \gui{Stash Snapshot...}
\i Save a snapshot of your current
work under a name for later reference. For example, if you
want to try out something and find out later that it does not work,
you can discard it and return to the state of the snapshot.
\row
\i \gui{Stash}
\i Stash local changes prior to executing a \gui{Pull}.
\row
\i \gui{Stash Pop}
\i Remove a single stashed state from the stash list and apply it on
top of the current working tree state.
\row
\i \gui{Pull}
\i Pull changes from the remote repository. If there are locally
modified files, you are prompted to stash those changes.
The \gui Git options page contains an option to do
a rebase operation while pulling.
\row
\i \gui{Clean Repository.../Clean Project...}
\i Collect all files that are not under version control
with the exception of patches and project files
and show them as a checkable list in a dialog
prompting for deletion. This lets you completely clean a build.
\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, double-click on it. Double-clicking on a remote
branch first creates a local branch with the same name that
tracks the remote branch, and then switches to it.
\image qtcreator-vcs-gitbranch.png
\row
\i \gui{Stashes...}
\i Displays a dialog showing the stashes created by
\gui{Stash Snapshot...} with options to restore,
display or delete them.
\row
\i \gui {Stage File for Commit}
\i Mark new or modified files for committing to the repository.
To undo this function, select \gui {Unstage File from Commit}.
\row
\i \gui{Show Commit...}
\i Select a commit to view. Enter the SHA of the commit
in the \gui Change field.
\endtable
\section2 Using Additional Mercurial Functions
The \gui Mercurial sub-menu contains the following additional items:
\table
\row
\i \gui{Import}
\i Apply changes from a patch file.
\row
\i \gui{Incoming}
\i Monitor the status of a remote repository by listing
the changes that will be pulled.
\row
\i \gui{Outgoing}
\i Monitor the status of a remote repository by listing
the changes that will be pushed.
\row
\i \gui{Pull}
\i Pull changes from the remote repository.
\row
\i \gui{Update}
\i Look at an earlier version of the code.
\endtable
\section2 Using Additional Perforce Functions
When you start Qt Creator, it looks for the executable specified
in the \gui{P4 command} field in \gui{Tools > Options... > Version
Control > Perforce}. If you do not use Perforce and want to turn
off the check, clear this field.
The \gui Perforce sub-menu contains the following additional items:
\table
\row
\i \gui{Describe...}
\i View information about changelists and the files in them.
\row
\i \gui{Edit File}
\i Open a file for editing.
\row
\i \gui{Opened}
\i List files that are open for editing.
\row
\i \gui{Pending Changes...}
\i Group files for commit.
\row
\i \gui{Update All/Update Current Project}
\i Fetch the current version of the current project or all
projects from the repository.
\endtable
\section2 Using Additional Subversion Functions
The \gui Subversion sub-menu contains the following additional items:
\table
\row
\i \gui{Describe...}
\i Display commit log messages for a revision.
\row
\i \gui{Update Project/Update Repository}
\i Update your working copy.
\endtable
*/
/*!
\contentspage index.html
\previouspage qt-quick-toolbars.html
\page creator-editor-locator.html
\nextpage creator-editor-codepasting.html
\title Searching With the Locator
The locator provides one of the easiest ways in Qt Creator to browse
through projects, files, classes, methods, documentation and file systems.
You can find the locator in the bottom left of the Qt Creator window.
To activate the locator, press \key Ctrl+K (\key Cmd+K on Mac OS
X) or select \gui Tools > \gui Locate....
\image qtcreator-locator.png
To edit the currently open project's main.cpp file using the locator:
\list 1
\o Activate the locator by pressing \key Ctrl+K.
\o Enter \tt{main.cpp}.
\image qtcreator-locator-open.png
\o Press \key Return.
The main.cpp file opens in the editor.
\endlist
It is also possible to enter only a part of a search string.
As you type, the locator shows the occurrences of that string regardless
of where in the name of an component it appears.
To narrow down the search results, you can use the following wildcard
characters:
\list
\o To match any number of any or no characters, enter \bold{*}.
\o To match a single instance of any character, enter \bold{?}.
\endlist
\section1 Using the Locator Filters
The locator allows you to browse not only files, but any items
defined by \bold{locator filters}. By default, the locator contains
filters which locate:
\list
\o Any open document
\o Files anywhere on your file system
\o Files belonging to your project, such as source, header resource,
and .ui files
\o Class and method definitions in your project or anywhere referenced
from your project
\o Help topics, including Qt documentation
\o Specific line in the document displayed in your editor
\endlist
To use a specific locator filter, type the assigned prefix followed by
\key Space. The prefix is usually a single character.
For example, to locate symbols matching
QDataStream:
\list 1
\o Activate the locator.
\o Enter \tt{\bold{: QDataStream}} (: (colon) followed by a
\key Space and the symbol name (QDataStream)).
The locator lists the results.
\image qtcreator-navigate-popup.png
\endlist
By default the following filters are enabled and you do not need to use
their prefixes explicitly:
\list
\o Going to a line in the current file (l).
\o Going to an open file (o).
\o Going to a file in any open project (a).
\endlist
\section2 Using the Default Locator Filters
The following locator filters are available by default:
\table
\header
\o Function
\o Enter in locator
\o Example
\row
\o Go to a line in the current file.
\o \tt{\bold{l \e{Line number}}}
\o \image qtcreator-locator-line.png
\row
\o Go to a symbol definition.
\o \tt{\bold{: \e{Symbol name}}}
\o \image qtcreator-locator-symbols.png
\row
\o Go to a help topic.
\o \tt{\bold{? \e{Help topic}}}
\o \image qtcreator-locator-help.png
\row
\o Go to an open file.
\o \tt{\bold{o \e{File name}}}
\o \image qtcreator-locator-opendocs.png
\row
\o Go to a file in the file system (browse the file system).
\o \tt{\bold{f \e{File name}}}
\o \image qtcreator-locator-filesystem.png
\row
\o Go to a file in any project currently open.
\o \tt{\bold{a \e{File name}}}
\o \image qtcreator-locator-files.png
\row
\o Go to a file in the current project.
\o \tt{\bold{p \e{File name}}}
\o \image qtcreator-locator-current-project.png
\row
\o Go to a class definition.
\o \tt{\bold{c \e{Class name}}}
\o \image qtcreator-locator-classes.png
\row
\o Go to a method definition.
\o \tt{\bold{m \e{Method name}}}
\o \image qtcreator-locator-methods.png
\endtable
\section2 Creating Locator Filters
To quickly access files not directly mentioned in your project, you can
create your own locator filters. That way you can locate files in a
directory structure you have defined.
To create a locator filter:
\list 1
\o In the locator, click \inlineimage qtcreator-locator-magnify.png
and select \gui Configure.... to open the \gui Locator options.
\image qtcreator-locator-customize.png
\o Click \gui Add.
\o In the \gui{Filter Configuration} dialog:
\list
\o Name your filter.
\o Select at least one directory. The locator searches directories
recursively.
\o Define the file pattern as a comma separated list. For example,
to search all .h and .cpp files, enter \bold{*.h,*.cpp}
\o Specify the prefix string.
To show only results matching this filter, select
\gui{Limit to prefix}.
\image qtcreator-navigate-customfilter.png
\endlist
\o Click OK.
\endlist
\section3 Configuring the Locator Cache
The locator searches the files matching your file pattern in the
directories you have selected and caches that information. The cache for
all default filters is updated as you write your code. By default,
Qt Creator updates the filters created by you once an hour.
To update the cached information manually, click
\inlineimage qtcreator-locator-magnify.png
and select \gui Refresh.
To set a new cache update time:
\list 1
\o Select \gui Tools > \gui Options... > \gui Locator.
\o In \gui{Refresh interval}, define new time in minutes.
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-developing-symbian.html
\page creator-project-managing-sessions.html
\nextpage creator-project-wizards.html
\title Managing Sessions
When you exit Qt Creator, a snapshot of your current workspace is stored
as a \e session. A session is an arbitrary collection of:
\list
\o Open projects with their dependencies (including SUBDIRS projects)
\o Open editors
\o Breakpoints and watches
\o Bookmarks
\endlist
A session is personal, that is, not meant to be shared. It is not
supposed to reflect the project structure. It contains personal data, such as
bookmarks and breakpoints that are usually not of interest to other developers
working on the same projects.
For example, if you work on a project and need to switch to another project for a
while, you can save your workspace as a session. This makes it easier
to return to working on the first project later.
To create a new session or remove existing sessions, select \gui File >
\gui Sessions > \gui{Session Manager}.
\image qtcreator-session-manager.png
To switch between sessions, choose
\gui File > \gui Session. If you do not create or select a session,
Qt Creator always uses the default session, which was created the
last time you exited Qt Creator.
When you launch Qt Creator, a list of existing sessions is displayed on the
\gui{Welcome screen}.
\image qtcreator-welcome-session.png
*/
/*!
\contentspage index.html
\previouspage creator-build-dependencies.html
\page creator-debugging.html
\nextpage creator-debugging-example.html
\title Debugging
Qt Creator does not include a debugger. It provides a debugger plugin that acts
as an interface between the Qt Creator core and external native debuggers
such as the GNU Symbolic Debugger (gdb), the Microsoft Console Debugger (CDB),
and an internal Java Script debugger. You can use the native debuggers to
debug the C++ language.
The following sections describe debugging with Qt Creator:
\list
\o \l{Debugging the Example Application} uses an example application to illustrate
how to debug applications in the \gui Debug mode.
\o \l{Interacting with the Debugger} describes the views and functions available
in the \gui Debug mode.
\o \l{Setting Up Debugger} summarizes the support for debugging C++ code and
requirements for installation. Typically, the interaction between Qt Creator
and the native debugger is set up automatically and you do not need to do anything.
\o \l{Debugger Modes of Operation} describes the operating modes in which the
debugger plugin runs, depending on where and how the process is started and run.
\o \l{Using Debugging Helpers} describes how to get more detailed data
on complex data.
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-debugger-engines.html
\page creator-debugger-operating-modes.html
\nextpage creator-debugging-helpers.html
\title Debugger Modes of Operation
The debugger plugin runs in different operating modes depending on where and
how the process is started and run. Some of the modes are only available for
a particular operating system or platform.
You can launch the debugger in the following modes:
\list
\o \bold Plain to debug locally started applications, such as a
Qt based GUI application.
\o \bold Terminal to debug locally started processes that need a
console, typically without a GUI.
\o \bold Attach to debug local processes started outside Qt Creator.
\o \bold Remote to debug a process running on a different machine.
\o \bold Core to debug crashed processes on Unix.
\o \bold Post-mortem to debug crashed processes on Windows.
\o \bold TRK to debug processes running on a Symbian device.
\endlist
When you click the \gui {Start Debugging} button, the debugger is launched
in the appropriate operating mode (plain, terminal, or TRK), based on the
build and run settings for the active project. Select \gui Debug menu options
to launch the debugger in the other modes.
\section2 Plain Mode
To launch the debugger in the plain mode, click the \gui {Start Debugging}
button for the active project, or choose
\gui {Debug > Start Debugging > Start and Debug External Application...}
and specify an executable.
\section2 Terminal Mode
To launch the debugger in the terminal mode, select \gui {Projects > Run Settings}
and select the \gui {Run in terminal} check box. Then click the
\gui {Start Debugging} button for the active project.
\section2 Attach Mode
To launch the debugger in the attach mode, select
\gui {Debug > Start Debugging > Attach to Running External Application...},
and then select a process by its name or process ID to attach to.
\section2 Remote Mode
The remote mode uses a \e{gdbserver} daemon that runs on the remote machine.
To launch the debugger in the remote mode, select
\gui {Debug > Start Debugging > Start and Attach to Remote Application...}.
\section2 Core Mode
The core mode is available only in Unix. It debugs crashed processes using
the \e {core} files (crash dumps) that are generated if the setting
is enabled in the shell.
To enable the dumping of core files, enter the following command in the
shell from which the application will be launched:
\code
ulimit -c unlimited
\endcode
To launch the debugger in the core mode, select
\gui{Debug > Start Debugging > Attach to Core...}.
\section2 Post-Mortem Mode
The post-mortem mode is available only on Windows, if you have installed
the debugging tools for Windows.
The Qt Creator installation program asks you whether you want to
register Qt Creator as a post-mortem debugger. To change the setting, select
\gui{Tools > Options... > Debugger > Common > Use Creator for post-mortem debugging}.
You can launch the debugger in the post-mortem mode if an application crashes
on Windows. Click the \gui {Debug in Qt Creator} button in the error message
that is displayed by the Windows operating system.
\section2 TRK Mode
The TRK mode is a special mode available only for Symbian. It
debugs processes running on a Symbian
device using the App TRK application that runs on the device.
To launch the debugger in the TRK mode, open the project, select Symbian as the
target, and click the \gui {Start Debugging} button.
For more information on setting up Symbian projects, see
\l{Setting Up Development Environment for Symbian}.
*/
/*!
\contentspage index.html
\previouspage creator-debug-mode.html
\page creator-debugger-engines.html
\nextpage creator-debugger-operating-modes.html
\title Setting Up Debugger
Typically, the interaction between Qt Creator and the native debugger is set
up automatically and you do not need to do anything. However, you might have an
unsupported gdb version installed, your Linux environment might not have gdb
installed at all, or you might want to use the debugging tools for Windows.
\note To use the debugging tools for Windows, you must install them and add the
Symbol Server provided by Microsoft to the symbol search path of the debugger.
For more information, see \l{Setting the Symbol Server in Windows}.
This section explains the
options you have for debugging C++ code and provides installation notes for the
supported native debuggers.
\section1 Supported Native Debugger Versions
The debugger plugin supports different builds of the gdb debugger, both
with and without the ability to use Python scripting. The Python enabled
versions are preferred, but they are not available on Mac and on older
versions of Linux.
On Windows, Symbian, and Maemo, only the Python version is supported.
The non-Python versions use the compiled version of the debugging helpers,
that you must enable separately. For more information, see
\l{Debugging Helpers Based on C++}.
The Python version uses a script version of the debugging helpers
that does not need any special setup.
The CDB native debugger has similar funtionality to the non-Python gdb debugger
engine. Specifically, it also uses compiled C++ code for the debugging
helper library.
The following table summarizes the support for debugging C++ code:
\table
\header
\o Platform
\o Compiler
\o Native Debugger
\o Python
\o Debugger Modes
\row
\o Linux
\o gcc
\o gdb
\o Yes
\o Plain, Terminal, Attach, Remote, Core
\row
\o Unix
\o gcc
\o gdb
\o Yes
\o Plain, Terminal, Attach, Remote, Core
\row
\o Mac OS
\o gcc
\o gdb
\o No
\o Plain, Terminal, Attach, Core
\row
\o Windows/MinGW
\o gcc
\o gdb
\o Yes
\o Plain, Terminal, Attach, Remote, Core
\row
\o Windows/MSVC
\o Microsoft Visual C++ Compiler
\o Debugging Tools for Windows/CDB
\o Not applicable
\o Plain, Terminal, Attach, Post-Mortem
\row
\o Symbian
\o gcc
\o gdb
\o Yes
\o TRK
\row
\o Maemo
\o gcc
\o gdb
\o Yes
\o Remote
\endtable
For more information on the the debugger modes, see \l{Debugger Modes of Operation}.
\omit
\section2 Gdb Adapter Modes
[Advanced Topic]
The gdb native debugger used internally by the debugger plugin runs in
different adapter modes to cope with the variety
of supported platforms and environments. All gdb adapters inherit from
AbstractGdbAdapter:
\list
\o PlainGdbAdapter debugs locally started GUI processes.
It is physically split into parts that are relevant only when Python is
available, parts relevant only when Python is not available, and mixed code.
\o TermGdbAdapter debugs locally started processes that need a
console.
\o AttachGdbAdapter debugs local processes started outside Qt Creator.
\o CoreGdbAdapter debugs core files generated from crashes.
\o RemoteGdbAdapter interacts with the gdbserver running on Linux.
\o TrkGdbAdapter interacts with Symbian devices. The gdb protocol and
the gdb serial protocol are used between gdb and the adapter. The TRK
protocol is used between the adapter and AppTRK running on the device.
\endlist
\endomit
\section1 Installing Native Debuggers
There are various reasons why the debugger plugin may fail to automatically
pick up a suitable native debugger. The native debugger might be missing
(which is usually the case for the CDB debugger on Windows which always
needs to be installed manually by the user) or the installed version is not
supported.
Check the table below for the supported versions and other important
information about installing native debuggers.
\table
\header
\o Native Debugger
\o Notes
\row
\o Gdb
\o On Linux, install version 6.8, 7.0.1 (version 7.0 is not supported),
7.1, or later. On Mac OS X, install Apple gdb version 6.3.50-20050815
(build 1344) or later.
\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.11.1.404 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}.
\note Visual Studio does not include the Debugging tools needed,
and therefore, you must install them separately.
The pre-built \e{Qt SDK for Windows} makes use
of the library if it is present on the system. When manually building Qt
Creator using the Microsoft Visual C++ Compiler, the build process checks
for the required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}.
It is highly recommended that you add the Symbol Server provided by Microsoft to the symbol
search path of the debugger. The Symbol Server provides you
with debugging informaton for the operating system libraries for debugging
Windows applications. For more information, see
\l{Setting the Symbol Server in Windows}.
\row
\o Debugging tools for Mac OS X
\o The Qt binary distribution contains both debug and release
variants of the libraries. But you have to explicitly tell the
runtime linker that you want to use the debug libraries even if
your application is compiled as debug as release is the default
library.
If you use a qmake based project in Qt Creator, you can set a
flag in your run configuration, in \gui Projects mode. In the run
configuration, select \gui{Use debug version of frameworks}.
For more detailed information about debugging on the Mac, see:
\l http://developer.apple.com/mac/library/technotes/tn2004/tn2124.html
\note The Mac OS X Snow Leopard (10.6) has a bug, that can be worked
around as described in the link provided below:
\l http://bugreports.qt.nokia.com/browse/QTBUG-4962.
\endtable
\section1 Setting the Symbol Server in Windows
To obtain debugging information for the operating system libraries for
debugging Windows applications, add the Symbol Server provided
by Microsoft to the symbol search path of the debugger:
\list 1
\o Select \gui Tools > \gui{Options...} > \gui Debugger > \gui Cdb.
\o In the \gui {Symbol paths} field, open the \gui{Insert...} menu
and select \gui{Symbol Server...}.
\o Select a directory where you want to store the cached information
and click \gui OK.
Use a subfolder in a temporary directory, such as
\c {C:\temp\symbolcache}.
\endlist
\note Populating the cache might take a long time on a slow network
connection.
\note The first time you start debugging by using the
Debugging tools for Windows, Qt Creator prompts you to add the Symbol
Server.
*/
/*!
\contentspage index.html
\previouspage creator-debugging-example.html
\page creator-debug-mode.html
\nextpage creator-debugger-engines.html
\title Interacting with the Debugger
In \gui Debug mode, you can use several views to interact with the
program you are debugging. Frequently used views are shown by
default and rarely used ones are hidden. To change the default settings,
select \gui {Window > Views}, and then select views to display or hide.
\image qtcreator-debugger-views.png "Debug mode views"
By default, the views are locked into place in the workspace. Select
\gui {Window > Views > Locked} to unlock the views. Drag and drop the
views into new positions on the screen. Drag view borders to resize the
views. The size and position of views are saved for future sessions.
\section1 Starting the Debugger
To start a program under the debugger's control, select \gui{Debug} >
\gui{Start Debugging} > \gui{Start Debugging}, or press \key{F5}.
Qt Creator 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 a considerable amount of
time, typically in the range of several seconds to minutes if complex
features (like QtWebKit) are used.
The debugger is launched in the appropriate operating mode (plain, terminal,
or TRK), based on the build and run settings for the active project.
Select \gui Debug menu options to launch the debugger in other modes.
For more information, see \l{Debugger Modes of Operation}.
Once the program starts running, it behaves and performs as usual.
You can interrupt a running program by selecting \gui{Debug} >
\gui {Interrupt}. The program is automatically interrupted as soon as a
breakpoint is hit.
\section2 Starting the Debugger from the Command Line
You can use the Qt Creator debugger interface from the command line. To
attach it to a running process, specify the process ID as a parameter for
the \c {-debug} option. To examine a core file, specify the file name.
Qt Creator executes all the necessary steps, such as searching for
the binary that belongs to a core file.
For example:
\list
\o \c {C:\qtcreator-2.1\bin>qtcreator -debug 2000}
\o \c {C:\qtcreator-2.1\bin>qtcreator -debug core.2000}
\endlist
For more information, see \l{Using Command Line Options}.
\section1 Using the Debugger
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 \gui Debug mode views to examine the data in more detail.
You can use the following keyboard shortcuts:
\list
\o To finish debugging, press \key{Shift+F5}.
\o To execute a line of code as a whole, press \key{F10}.
\o To step into a function or a sub-function, press \key{F11}.
\o To continue running the program, press \key{F5}.
\endlist
It is also possible to continue executing the program until the current
function completes or jump to an arbitrary position in the current function.
\section2 Stepping into Frameworks in Mac OS
In Mac OS X, external libraries are usually built into so-called Frameworks,
which may contain both release and debug versions of the library. When you run
applications on the Mac OS desktop, the release version of Frameworks is used
by default. To step into Frameworks, select the \gui {Use debug versions of
Frameworks} option in the project run settings for \gui Desktop and
\gui {Qt Simulator} targets.
\section1 Setting Breakpoints
A breakpoint represents a position or sets of positions in the code that,
when executed, interrupts the program being debugged and passes the control
to you. You can then examine the state of the interrupted program, or
continue execution either line-by-line or continuously.
Qt Creator shows breakpoints in the \gui{Breakpoints} view which is enabled
by default. The \gui{Breakpoints} view is also accessible when the debugger
and the program being debugged is not running.
\image qtcreator-debug-breakpoints.png "Breakpoints view"
Typically, breakpoints are associated with a source code file and line, or
the start of a function -- both are allowed in Qt Creator.
The interruption of a program by a breakpoint can be restricted with
certain conditions.
To set a breakpoint:
\list
\o At a particular line you want the program to stop, click 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...} located in the
context menu of the \gui{Breakpoints} view.
\endlist
\note You can remove a breakpoint:
\list
\o By clicking 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 context
menu in the \gui Breakpoints view.
\endlist
You can set and delete breakpoints before the program starts running or
while it is running under the debugger's control. Breakpoints are saved
together with a session.
\section1 Viewing Call Stack Trace
When the program being debugged is interrupted, Qt Creator displays the
nested function calls leading to the current position as a call stack
trace. This stack trace is built up from call stack frames, each
representing a particular function. For each function, Qt Creator tries
to retrieve the file name and line number of the corresponding source
file. 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 have corresponding source locations. Stack frames without
corresponding source locations are grayed out in the \gui{Stack} view.
If you click a frame with a known source location, the text editor
jumps to the corresponding location and updates the \gui{Locals and Watchers}
view, making it seem like the program was interrupted before entering the
function.
\section1 Viewing 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 adjusts itself
accordingly.
\section1 Viewing Modules and Source Files
The \gui{Modules} view and \gui{Source Files} views display information
that the debugger plugin has about modules and source files included in
the project. The \gui{Modules} view lists the modules in the project and
symbols within the modules. In addition, it indicates where the module
was loaded.
The \gui{Source Files} view lists all the source files included in the project.
If you cannot step into an instruction, you can check whether the source file is
actually part of the project, or whether it was compiled
elsewhere. The view shows the path to each file in the file system.
By default, the \gui{Modules} view and \gui{Source Files} view are hidden.
\section1 Viewing Disassembled Code and Register State
The \gui{Disassembler} view displays disassembled code for the current
function. The \gui{Registers} view displays the current state of the CPU's
registers.
The \gui{Disassembler} view and the \gui{Registers} view are both useful
for low-level commands for checking single instructions, such as \gui{Step Into}
and \gui{Step Over}. By default, both \gui{Disassembler} and
\gui{Registers} view are hidden.
\section1 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. The \gui{Locals and Watchers} view
typically includes information about parameters of the function in that
frame as well as the local variables.
\image qtcreator-watcher.png "Locals and Watchers view"
Compound variables of struct or class type are displayed as
expandable in the view. Expand entries to show
all members. Together with the display of value and type, you can
examine and traverse the low-level layout of object 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. Optimization can lead to
re-ordering of instructions or removal of some local variables,
causing the \gui{Locals and Watchers} view to 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 is reported as
\gui {not in scope}. Not all uninitialized objects, however, 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 Qt's basic objects data display feature:
\list
\o Select \gui Tools > \gui {Options...} > \gui Debugger >
\gui{Debugging Helper} and check the \gui{Use Debugging Helper}
checkbox.
\o The \gui{Locals and Watchers} view is reorganized to provide a
high-level view of the objects.
\endlist
For example, in case of QObject, instead of displaying a pointer to some
private data structure, you see a list of children, signals and slots.
Similarly, instead of displaying many pointers and integers, Qt Creator's
debugger displays the contents of a QHash or QMap in an orderly manner.
Also, the debugger displays access data for QFileInfo and provides
access to the "real" contents of QVariant.
You can use the \gui{Locals and Watchers} view to change the contents of
variables of simple data types, for example, \c int or \c float when the
program is interrupted. To do so, click the \gui Value column, modify
the value with the inplace editor, and press \key Enter (or \key Return).
You can enable tooltips in the main editor displaying this information.
For more information, see \l{Showing Tooltips in Debug Mode}.
\note The set of watched items is saved in your session.
*/
/*!
\contentspage index.html
\previouspage creator-debugging.html
\page creator-debugging-example.html
\nextpage creator-debug-mode.html
\title Debugging the Example Application
This section uses the \l{Creating a Qt C++ Application}{TextFinder} example to
illustrate how to debug applications in the \gui Debug mode. TextFinder
reads a text file into
QString and then displays it with QTextEdit.
To look at the example QString, \c{line}, and see the
stored data, place a breakpoint and view the QString object
data, as follows:
\list 1
\o Click in between the line number and the window border on the line
where we invoke \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}
to set a breakpoint.
\image qtcreator-setting-breakpoint1.png
\o Select \gui{Debug > Start Debugging > Start Debugging} or press \key{F5}.
\o To view the breakpoint, click the \gui{Breakpoints} tab.
\image qtcreator-setting-breakpoint2.png
\o To remove a breakpoint, right-click it and select \gui{Delete Breakpoint}.
\o To view the contents of \c{line}, go to the \gui{Locals and
Watchers} view.
\image qtcreator-watcher.png
\endlist
Modify the \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. Add the following code snippet:
\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
If you compile and run the above code, however, the application does not
work correctly due to a logic error. To locate this logic error, step
through the code using the following buttons:
\image qtcreator-debugging-buttons.png
*/
/*!
\contentspage index.html
\previouspage creator-debugger-operating-modes.html
\page creator-debugging-helpers.html
\nextpage creator-maemo-emulator.html
\title Using Debugging Helpers
Qt Creator is able to show complex data types in a customized,
user-extensible manner. For this purpose, it takes advantage of
two technologies, collectively referred to as \e{Debugging Helpers}.
Using the debugging helpers is not \e essential for debugging
with Qt Creator, but they enhance the user's ability to quickly
examine complex data significantly.
\section1 Debugging Helpers based on C++
This is the first and original approach to display complex data
types. While it has been superseded on most platforms by the more
robust and more flexible second approch using Python scripting,
it is the only feasible one on Windows/MSVC, Mac OS, and
old Linux distributions. Moreover, this approach will automatically
be chosen as fallback in case the Python based approach fails.
During debugging with the C++ based debugging helpers,
Qt Creator dynamically loads a helper library in form of a DLL or a
shared object into the debugged process.
The Qt SDK package already contains a prebuilt debugging helper
library. To create your own debugging helper library, select \gui{Tools} >
\gui{Options...} > \gui{Qt4} > \gui{Qt Versions}. As the internal data
structures of Qt can change between versions, the debugging helper
library is built for each Qt version.
\section1 Debugging Helpers based on Python
On platforms featuring a Python-enabled version of the gdb debugger,
the data extraction is done by a Python script. This is more robust
as the script execution is separated from the debugged process. It
is also easier to extend as the script is less dependent on the
actual Qt version and does not need compilation.
To extend the shipped Python based debugging helpers for custom types,
define one Python function per user defined type in the
gdb startup file. By default, the following startup file is used:
\c{~/.gdbinit}. To use another file, select \gui {Tools > Options... > Gdb}
and specify a filename in the \gui {Gdb startup script} field.
The function name has to be qdump__NS__Foo, where NS::Foo is the class
or class template to be examined. Nested namespaces are possible.
The debugger plugin calls this function whenever you want to
display an object of this type. The function is passed the following
parameters:
\list
\o \c d of type \c Dumper
\o \c item of type \c Item
\endlist
The function has to feed the Dumper object with certain information
which is used to build up the object and its children's display in the
\gui{Locals and Watchers} view.
Example:
\code
def qdump__QVector(d, item):
d_ptr = item.value["d"]
p_ptr = item.value["p"]
alloc = d_ptr["alloc"]
size = d_ptr["size"]
check(0 <= size and size <= alloc and alloc <= 1000 * 1000 * 1000)
check(d_ptr["ref"]["_q_value"] > 0)
innerType = item.value.type.template_argument(0)
d.putItemCount(size)
d.putNumChild(size)
if d.isExpanded(item):
p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
with Children(d, [size, 2000], innerType)
for i in d.childRange():
d.putItem(Item(p.dereference(), item.iname, i))
p += 1
\endcode
\section2 Item Class
The Item Python class is a thin wrapper around values corresponding to one
line in the \gui{Locals and Watchers} view. The Item members are as follows :
\list
\o \gui{__init__(self, value, parentiname, iname, name = None)} - A
constructor. The object's internal name is created by concatenating
\c parentiname and \c iname. If \c None is passed as \c name, a
serial number is used.
\o \gui{value} - An object of type gdb.Value representing the value to
be displayed.
\o \gui{iname} - The internal name of the object, constituting a dot-separated
list of identifiers, corresponding to the position of the object's
representation in the view.
\o \gui{name} - An optional name. If given, is used in the
\gui{name} column of the view. If not, a simple number in brackets
is used instead.
\endlist
\section2 Dumper Class
For each line in the \gui{Locals and Watchers} view, a string like the
following needs to be created and channeled to the debugger plugin.
\code
"{iname='some internal name',
addr='object address in memory',
name='contents of the name column',
value='contents of the value column',
type='contents of the type column',
numchild='number of children', // zero/nonzero is sufficient
childtype='default type of children', // optional
childnumchild='default number of grandchildren', // optional
children=[ // only needed if item is expanded in view
{iname='internal name of first child',
... },
{iname='internal name of second child',
... },
...
]}"
\endcode
While in theory, you can build up the entire string above manually, it is
easier to employ the Dumper Python class for that purpose. The Dumper
Python class contains a complete framework to take care of the \c iname and
\c addr fields, to handle children of simple types, references, pointers,
enums, known and unknown structs as well as some convenience methods to
handle common situations.
The Dumper members are the following:
\list
\o \gui{__init__(self)} - Initializes the output to an empty string and
empties the child stack.
\o \gui{put(self, value)} - Low level method to directly append to the
output string.
\o \gui{putCommaIfNeeded(self)} - Appends a comma if the current output
ends in '}', '"' or ']' .
\o \gui{putField(self, name, value)} - Appends a comma if needed, and a
name='value' field.
\o \gui{beginItem(self, name)} - Starts writing a field by writing \c {name='}.
\o \gui{endItem(self)} - Ends writing a field by writing \c {'}.
\o \gui{endChildren(self)} - Ends writing a list of children.
\o \gui{childRange(self)} - Returns the range of children specified in
the current \c Children scope.
\o \gui{putItemCount(self, count)} - Appends a field \c {value='<%d items'}
to the output.
\o \gui{putEllipsis(self)} - Appends fields
\c {'{name="",value="",type="",numchild="0"}'}. This is
automatically done by \c endChildren if the number of children to
print is smaller than the number of actual children.
\o \gui{putName(self, name)} - Appends a \c {name='...'} field.
\o \gui{putType(self, type)} - Appends a field \c {type='...'} unless the
\a type coincides with the parent's default child type.
\o \gui{putNumChild(self, numchild)} - Appends a field \c {numchild='...'}
unless the \c numchild coincides with the parent's default child numchild
value.
\o \gui{putValue(self, value, encoding = None)} - Append a file \c {value='...'},
optionally followed by a field \c {valueencoding='...'}. The \c value
needs to be convertible to a string entirely consisting of
alphanumerical values. The \c encoding parameter can be used to
specify the encoding in case the real value had to be encoded in some
way to meet the alphanumerical-only requirement.
Currently the following encodings are supported:
\list
\o 0: unencoded 8 bit data, interpreted as Latin1.
\o 1: base64 encoded 8 bit data, used for QByteArray,
double quotes are added.
\o 2: base64 encoded 16 bit data, used for QString,
double quotes are added.
\o 3: base64 encoded 32 bit data,
double quotes are added.
\o 4: base64 encoded 16 bit data, without quotes (see 2)
\o 5: base64 encoded 8 bit data, without quotes (see 1)
\o 6: %02x encoded 8 bit data (as with \c QByteArray::toHex),
double quotes are added.
\o 7: %04x encoded 16 bit data (as with \c QByteArray::toHex),
double quotes are added.
\endlist
\o \gui{putStringValue(self, value)} - Encodes a QString and calls
\c putValue with the correct \c encoding setting.
\o \gui{putByteArrayValue(self, value)} - Encodes a QByteArray and calls
\c putValue with the correct \c encoding setting.
\o \gui{isExpanded(self, item)} - Checks whether the item with the
internal name \c item.iname is expanded in the view.
\o \gui{isExpandedIName(self, iname)} - Checks whether the item with the
internal name \c iname is expanded in the view.
\o \gui{putIntItem(self, name, value)} - Equivalent to:
\code
self.beginHash()
self.putName(name)
self.putValue(value)
self.putType("int")
self.putNumChild(0)
self.endHash()
\endcode
\o \gui{putBoolItem(self, name, value)} - Equivalent to:
\code
self.beginHash()
self.putName(name)
self.putValue(value)
self.putType("bool")
self.putNumChild(0)
self.endHash()
\endcode
\o \gui{pushOutput(self)} - Moves the output string to a safe location
from with it is sent to the debugger plugin even if further operations
raise an exception.
\o \gui{putCallItem(self, name, item, func)} -
Uses gdb to call the function \c func on the value specified by
\a {item.value} and output the resulting item. This function is
not available when debugging core dumps and it is not available
on the Symbian platform due to restrictions imposed by AppTRK.
\o \gui{putItemHelper(self, item)} - The "master function", handling
basic types, references, pointers and enums directly, iterates
over base classes and class members of compound types and calls
\c qdump__* functions whenever appropriate.
\o \gui{putItem(self, item)} - Equivalent to:
\code
with SubItem(self):
self.putItemHelper(item)
\endcode
Exceptions raised by nested function calls are caught and all
output produced by \c putItemHelper is replaced by the output of:
\code
...
except RuntimeError:
d.put('value="",type="",numchild="0",')
\endcode
\endlist
\section2 Children and SubItem Class
The attempt to create child items might lead to errors if data is
uninitialized or corrupted. To gracefully recover in such situations,
use \c Children and \c SubItem \e{Context Managers} to create the nested items.
The \c Children constructor \gui{__init__(self, dumper, numChild = 1,
childType = None, childNumChild = None)} uses one mandatory argument and three
optional arguments. The mandatory argument refers to the current \c Dumper
object. The optional arguments can be used to specify the number \c numChild
of children, with type \c childType_ and \c childNumChild_ grandchildren each.
If \c numChild_ is a list of two integers, the first one specifies the actual
number of children and the second the maximum number of children to print.
Similarly, using the \c SubItem class helps to protect individual items.
Example:
\code
d.putNumChild(2)
if d.isExpanded(item):
with Children(d):
with SubItem(d):
d.putName("key")
d.putItemHelper(Item(key, item.iname, "key"))
with SubItem(d):
d.putName("value")
d.putItemHelper(Item(value, item.iname, "value"))
\endcode
*/
/*!
\contentspage index.html
\previouspage creator-project-qmake.html
\page creator-project-cmake.html
\nextpage creator-project-generic.html
\title Setting Up a CMake Project
CMake is an alternative to qmake for automating the generation of makefiles.
It controls the software compilation process by using simple configuration
files, called CMakeLists.txt files. CMake generates native makefiles and
workspaces that you can use in the compiler environment of your choice.
Since Qt Creator 1.1, CMake configuration files are supported.
Qt Creator 1.3 supports the Microsoft Toolchain if the CMake version
is at least 2.8.
\section1 Setting the Path for CMake
You can set the path for the \c CMake executable in \gui{Tools} >
\gui{Options... > Projects > CMake}.
\image qtcreator-cmakeexecutable.png
\note Before you open a \c CMake project it is necessary to modify the
\c{PATH} environment variable to include the bin folders of \c mingw and
Qt Creator in the SDK.
For instance, if you have the Qt Creator SDK installed in your C drive,
use the following command to set the environment variables in
the command line prompt:
\code
set PATH=C:\qtsdk\mingw\bin;C:\qtsdk\qt\bin;
\endcode
Then start Qt Creator by typing:
\code
C:\qtsdk\bin\qtcreator.exe
\endcode
\section1 Opening CMake Projects
To open a \c CMake project:
\list 1
\o Select \gui{File} > \gui{Open File or Project...}.
\o Select the \c{CMakeLists.txt} file from your \c CMake project.
\endlist
A wizard guides you through the rest of the process.
\note 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
(\l{glossary-shadow-build}{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, \c mingw32-make, or
\c nmake 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 \bold{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. The build
directory can also 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}{here}.
\section1 Adding External Libraries to CMake Projects
Through external libraries Qt Creator can support code completion and
syntax highlighting as if they were part of the current project or the Qt
library.
Qt Creator detects the external libraries using the \c FIND_PACKAGE()
macro. Some libraries come with the CMake installation. You can find those
in the \bold{Modules} directory of your CMake installation.
\note If you provide your own libraries, you also need to provide your own
\c FindFoo.cmake file. For more information, see
\l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}.
Syntax completion and highlighting work once your project successfully
builds and links against the external library.
*/
/*!
\contentspage index.html
\previouspage creator-project-cmake.html
\page creator-project-generic.html
\nextpage creator-developing-maemo.html
\title Setting Up a Generic Project
Qt Creator supports generic projects, so you can import existing projects
that do not use qmake or CMake and Qt Creator ignores your build system.
Generic project support allows you to use Qt Creator as a code editor. You
can change the way your project is built by modifying the \c make command
in the \gui{Projects} mode under \gui{Build Settings}.
When you import a project, Qt Creator creates the following files that
allow you to specify which files belong to your project and which include
directories or defines you want to pass to your compile:
\tt{.files}, \tt{.includes}, and \tt{.config}.
\section1 Importing a Generic Project
To import an existing generic project:
\list 1
\o Select \gui File > \gui{New File or Project...} >
\gui{Other Project} > \gui{Import Existing Project}.
\o In \gui{Import Existing Project}, enter the project name
and select the location of the project file you want to import.
Qt Creator automatically generates the following files in the
project directory:
\list
\o \l{Specifying Files}{.files}
\o \l{Specifying Include Paths}{.includes}
\o \l{Specifying Defines}{.config}
\o .creator
\endlist
\endlist
When the project is successfully imported, Qt Creator creates the project
tree in the sidebar.
After importing a generic project into Qt Creator, open it by selecting the
\tt{.creator} file.
\section1 Working with Generic Project Files
For a generic project, you have to manually specify which files belong to
your project and which include directories or defines you want to pass to
your compiler.
\section1 Specifying Files
The list of files for a generic project is specified in the \tt{.files}
file. When you first create a generic project, Qt Creator adds any
files it recognizes to your project.
To add or remove files, edit the \tt{.files} file in Qt Creator.
Qt Creator recreates your project tree when you save the \tt{.files} file.
Alternatively, you can add and remove files using the context menu in the
project tree.
If you frequently need to update the \tt{.files} file, you can do so
efficiently by using a script that updates the file for you. If the file
is modified externally, you have to restart Qt Creator for the changes to
take effect.
To update the \tt{.files} on the \gui Git repository use the following
script:
\code
git ls-files *.cpp *.h > MyProject.files
\endcode
\section1 Specifying Include Paths
The include paths are specified in the \tt{.includes} file, one include
path per line. The paths can be either absolute or relative to the
\tt{.includes} file.
\section1 Specifying Defines
The defines are specified in the \tt{.config} file. The \tt{.config} file is
a regular C++ file, prepended to all your source files when they are parsed.
Only use the \tt{.config} file to add lines as in the example below:
\code
#define NAME value
\endcode
\section1 Creating a Run Configuration
Qt Creator cannot automatically determine which executable to run.
In the \gui{Projects} mode under \gui{Run Settings}, define the executable
file to run:
\list 1
\o Click \gui Add and select \gui{Custom Executable}.
\o Define the configuration name, the location of the executable, any
additional arguments and the working directory.
\endlist
*/
/*!
\contentspage index.html
\previouspage adding-plugins.html
\page creator-visual-editor.html
\nextpage quick-projects.html
\title Developing Qt Quick Applications
You can either create Qt Quick projects from scratch or import them to
Qt Creator. For example, you can import and run the
\l {http://doc.qt.nokia.com/4.7/qdeclarativeexamples.html} {QML examples and demos}
to learn how to use various aspects of QML.
You can use the code editor (\l{Using the Editor}{Edit mode}) or the visual editor
(\l{Using Qt Quick Designer}{Design mode}) to develop Qt Quick applications.
The following sections describe typical tasks you can do with Qt Creator.
\list
\o \l {Creating Qt Quick Projects}
\o \l {Creating Components}
\o \l {Creating Screens}
\o \l {Animating Screens}
\o \l {Adding User Interaction Methods}
\o \l {Implementing Application Logic}
\endlist
\note The \QMLD visual editor is provided as an experimental plugin that you must
enable to be able to edit QML files in the \gui Design mode. Enabling the
visual editor can negatively affect the overall stability of Qt Creator.
To enable or disable the \QMLD visual editor, select
\gui {Help > About Plugins... > Qt Quick > QmlDesigner}. You must restart Qt Creator
to enable or disable the visual editor.
*/
/*!
\contentspage index.html
\previouspage creator-visual-editor.html
\page quick-projects.html
\nextpage quick-components.html
\title Creating Qt Quick Projects
Select \gui {File > New File or Project > Qt Quick Project > Qt QML Application}.
\image qmldesigner-new-project.png "New File or Project dialog"
Qt Creator creates the following files:
\list
\o .qmlproject project file defines that all QML, JavaScript, and image
files in the project folder belong to the project. Therefore, you do not
need to individually list all the files in the project.
\o .qml file defines an element, such as a component, screen, or the whole
application UI.
\endlist
The \c import statement in the beginning of the .qml file specifies the
\l {http://doc.qt.nokia.com/4.7/qdeclarativemodules.html} {Qt modules}
to import. Each Qt module contains a set of default elements.
Specify a version to get the features you want.
To use JavaScript and image files in the application, copy them to the
project folder.
To import a QML project to Qt Creator, select
\gui {File > New File or Project > Qt Quick Project > Import Existing Qt QML Directory}.
*/
/*!
\contentspage index.html
\previouspage quick-projects.html
\page quick-components.html
\nextpage quick-screens.html
\title Creating Components
A QML component provides a way of defining a new type that you can re-use in other QML
files. A component is like a black box; it interacts with the outside world
through properties, signals, and slots, and is generally defined in its own QML file.
You can import components to screens and applications.
You can create the following QML components:
\list
\o \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
uses an image as a border or background.
\o \l{http://doc.qt.nokia.com/4.7/qml-image.html}{Image}
adds a bitmap to the scene. You can stretch and tile images.
\o \l{http://doc.qt.nokia.com/4.7/qml-item.html}{Item}
is the most basic of all visual items in QML. Even though it has no visual appearance,
it defines all the properties that are common across visual items, such as the x and
y position, width and height, anchoring, and key handling.
\o \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
adds a rectangle that is painted with a solid fill color and an optional border.
You can also use the radius property to create rounded rectangles.
\o \l{http://doc.qt.nokia.com/4.7/qml-text.html}{Text}
adds formatted read-only text.
\o \l{http://doc.qt.nokia.com/4.7/qml-textedit.html}{Text Edit}
adds a single line of editable formatted text that can be validated.
\o \l{http://doc.qt.nokia.com/4.7/qml-textinput.html}{Text Input}
adds a single line of editable plain text that can be validated.
\endlist
*/
/*!
\contentspage index.html
\previouspage quick-components.html
\page quick-screens.html
\nextpage quick-animations.html
\title Creating Screens
You can use predefined QML elements and your own components to create screens.
You can create the following types of views to organize items provided by
\l{http://doc.qt.nokia.com/4.7/qdeclarativemodels.html}{data models}:
\list
\o \l{http://doc.qt.nokia.com/4.7/qml-gridview.html}{Grid View}
\o \l{http://doc.qt.nokia.com/4.7/qml-listview.html}{List View}
\o \l{http://doc.qt.nokia.com/4.7/qml-pathview.html}{Path View}
\endlist
In the code editor, write the code to use the data models.
Use states and transitions
to navigate between screens.
QML states typically describe user interface configurations, such as the UI elements,
their properties and behavior and the available actions. For example, you can use
states to create two screens.
*/
/*!
\contentspage index.html
\previouspage quick-screens.html
\page quick-animations.html
\nextpage quick-user-interaction.html
\title Animating Screens
To make movement between states smooth, you can specify transitions.
You can use different types of animated transitions. For example, you can animate changes
to property values and colors. You can use rotation animation to control the direction of
rotation. For more information, see
\l{http://doc.qt.nokia.com/4.7/qdeclarativeanimation.html}{QML Animation}.
You can use the \c ParallelAnimation element to start several animations at the same time.
Or use the \c SequentialAnimation element to run them one after another.
You can use the code editor to specify transitions. For more information, see
\l{http://doc.qt.nokia.com/4.7/qml-transition.html}{QML Transition Element}.
*/
/*!
\contentspage index.html
\previouspage quick-animations.html
\page quick-user-interaction.html
\nextpage quick-application-logic.html
\title Adding User Interaction Methods
You can add the following basic interaction methods to scenes:
\list
\o \l{http://doc.qt.nokia.com/4.7/qml-flickable.html}{Flickable}
items can be flicked horizontally or vertically.
\o \l{http://doc.qt.nokia.com/4.7/qml-flipable.html}{Flipable}
items can be flipped between their front and back sides by using rotation,
state, and transition.
\o \l{http://doc.qt.nokia.com/4.7/qml-focusscope.html}{Focus Scope}
assists in keyboard focus handling when building reusable QML components.
\o \l{http://doc.qt.nokia.com/4.7/qml-mousearea.html}{Mouse Area}
enables simple mouse handling.
\endlist
*/
/*!
\contentspage index.html
\previouspage quick-user-interaction.html
\page quick-application-logic.html
\nextpage creator-building-running.html
\title Implementing Application Logic
A user interface is only a part of an application, and not really useful by itself.
You can use Qt or JavaScript to implement the application logic. For more information on
using JavaScript, see
\l {http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html} {Integrating JavaScript}.
For an example of how to use JavaScript to develop a game, see the
\l {http://doc.qt.nokia.com/4.7/qml-advtutorial.html} {QML Advanced Tutorial}.
*/
/*!
\contentspage index.html
\previouspage creator-editor-refactoring.html
\page qt-quick-toolbars.html
\nextpage creator-editor-locator.html
\title Using Qt Quick Toolbars
When you edit QML code in the code editor, you specify the properties
of QML components. For some properties, such as colors and font names,
this is not a trivial task. For example, few people can visualize the
color #18793f.
To easily edit these properties, you can use the Qt Quick Toolbars.
When you select a component in the code and a toolbar is available,
a light bulb icon appears:
\inlineimage qml-toolbar-indicator.png
. Select the icon to open the toolbar.
To open toolbars immediately when you select a component, select
\gui{Tools > Options... > Qt Quick > Qt Quick Toolbar > Always show Quick
Toolbar}.
Drag the toolbar to pin it to another location. Select
\inlineimage qml-toolbar-pin.png
to unpin the toolbar and move it to its default location. To pin toolbars
by default, select \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar
> Pin Quick Toolbar}.
\section1 Previewing Images
The Qt Quick Toolbar for images allows you to edit the properties of
\l{http://doc.qt.nokia.com/latest/qml-borderimage.html}{Border Image}
and \l{http://doc.qt.nokia.com/latest/qml-image.html}{Image} components.
You can scale and tile the images, replace them with other images,
preview them, and change the image margins.
\image qml-toolbar-image.png "Qt Quick Toolbar for images"
To preview an image, double-click it on the toolbar. In the preview
dialog, you can zoom the image. Drag the image margins to change them.
\image qml-toolbar-image-preview.png "Image preview dialog"
\section1 Formatting Text
The Qt Quick Toolbar for text allows you to edit the properties of
\l{http://doc.qt.nokia.com/latest/qml-text.html}{Text} components.
You can change the font family and size as well as text formatting, style,
alignment, and color.
If a property is assigned an expression instead of a value, you
cannot use the toolbar to edit it. The button for editing the property
is disabled.
\image qml-toolbar-text.png "Qt Quick Toolbar for text"
By default, font size is specified as pixels. To use points, instead,
change \gui px to \gui pt in the size field.
\section1 Previewing Animation
The Qt Quick Toolbar for animation allows you to edit the properties of
\l{http://doc.qt.nokia.com/4.7/qml-propertyanimation.html}{PropertyAnimation}
components and the components that inherit it. You can change the easing curve
type and duration. For some curves, you can also specify amplitude, period,
and overshoot values.
\image qml-toolbar-animation.png "Qt Quick Toolbar for animation"
Select the play button to preview your changes.
\section1 Editing Rectangles
The Qt Quick Toolbar for rectangles allows you to edit the properties of
\l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
components. You can change the fill and border colors and add
gradients.
\image qml-toolbar-rectangle.png "Qt Quick Toolbar for rectangles"
To add gradient stop points, click above the gradient bar. To remove
stop points, drag them upwards.
*/
/*!
\contentspage index.html
\previouspage creator-debugging-helpers.html
\page creator-maemo-emulator.html
\nextpage creator-version-control.html
\title Using the Maemo Emulator
The Maemo emulator emulates the Nokia N900 device environment. You can test
applications in conditions practically identical to running the application
on a Nokia N900 device with software update release 1.2 (V10.2010.19-1).
You can test user interaction by using the keypad and
touch emulation.
To test the application UI, user interaction with the application, and
functionality that uses the mobility APIs, use the Qt Simulator,
instead. For more information, see the
\l{http://doc.qt.nokia.com/qt-simulator-beta/index.html}{Qt Simulator Manual}.
The Maemo emulator is installed and configured as part of the Nokia Qt SDK
package. You can also install and configure the MADDE environment and
Maemo emulator separately. For more information, see
\l{Setting Up Development Environment for Maemo}.
\section1 Starting the Maemo Emulator
The \gui {Start Maemo Emulator} button is visible if you have a project
open in Qt Creator for which you have added the Maemo build target
and if you have configured a connection between Qt Creator and the Maemo
Emulator.
To start the Maemo emulator:
\list 1
\o Click
\inlineimage qtcreator-maemo-emulator-button.png "Start Maemo Emulator button"
.
\o Select \gui {Mad Developer} on the Maemo emulator, to start the Mad Developer
application
\o If you have not deployed an SSH key to protect the connection between
Qt Creator and the Maemo emulator, select \gui {Developer Password} to generate
a password.
\o In Qt Creator, enter the password in the connection settings:
\gui {Tools > Options... > Projects > Maemo Device Configurations}.
\endlist
Test your application on the Maemo emulator as on a device. For a list of
keyboard shortcuts that you can use to emulate Nokia N900 keys and functions, see
\l {Emulating Nokia N900 Keys}.
\section1 Emulating Nokia N900 Keys
The following table summarizes the keyboard shortcuts that you can use
to emulate Nokia N900 keys and functions.
\table
\header
\o Nokia N900 Key
\o Keyboard Shortcut
\row
\o \list
\o Alphabet keys
\o Comma (,)
\o Period (.)
\o Space
\o Arrow keys
\o Enter
\o Backspace
\endlist
\o Respective keys on the development PC keyboard.
\row
\o Shift
\o Left Shift key
\row
\o Ctrl
\o Left Ctrl key
\row
\o Mode
\o Left Alt key
\row
\o Power
\o Esc
\row
\o Keypad slider open and close
\o F1
\row
\o Keypad lock
\o F2
\row
\o Camera lens open and close
\o F3
\row
\o Camera focus
\o F4
\row
\o Camera take picture
\o F5
\note The actual camera functionality is not emulated.
\row
\o Stereo headphones connect and disconnect
\o F6
\row
\o Volume down
\o F7
\row
\o Volume up
\o F8
\row
\o Accelerometer x axis, negative
\o 1
\row
\o Accelerometer x axis, positive
\o 2
\row
\o Accelerometer z axis, negative
\o 4
\row
\o Accelerometer z axis, positive
\o 5
\row
\o Accelerometer y axis, negative
\o 7
\row
\o Accelerometer y axis, positive
\o 8
\endtable
*/
/*!
\contentspage index.html
\previouspage creator-usability.html
\page adding-plugins.html
\nextpage creator-visual-editor.html
\title Adding Qt Designer Plugins
You can use Qt APIs to create plugins that extend Qt applications.
This allows you to add your own widgets to \QD.
The most flexible way to include a plugin with an application is to compile it
into a dynamic library that is shipped separately, and detected and loaded at runtime.
The applications can detect plugins that are stored in the standard plugin
subdirectories. For more information on how to create and locate plugins and to
change the default plugin path, see \l{How to Create Qt Plugins}.
For more information about how to create plugins for \QD, see
\l{http://doc.qt.nokia.com/4.7/designer-using-custom-widgets.html}{Creating and Using Components for Qt Designer}.
\section1 Locating Qt Designer Plugins
\QD fetches plugins from the standard locations and loads the plugins
that match its build key. \QD is delivered both as a standalone application
and as part of the SDK, where it is integrated into Qt Creator.
The correct folder to place the plugins depends on
which one you use.
The integrated \QD fetches plugins from the \c {%SDK%\bin\designer} folder on Windows
and Linux. For information about how to configure plugins on Mac OS, see
\l{Configuring Qt Designer Plugins on Mac OS}.
To check which plugins
were loaded successfully and which failed, choose \gui{Tools > Form Editor >
About Qt Designer Plugins}.
The standalone \QD is part of the Qt library used for building projects,
located under \c {%SDK%\qt}. Therefore, it fetches plugins from the following folder:
\c {%SDK%\qt\plugins\designer}. To check which plugins were loaded successfully and which
failed, choose \gui{Help > About Plugins}.
\section2 Configuring Qt Designer Plugins on Mac OS
On the Mac, a GUI application must be built and run from a bundle. A bundle is a
directory structure that appears as a single entity when viewed in the Finder.
A bundle for an application typcially contains the executable and all the resources
it needs.
Qt Creator uses its own set of Qt Libraries located in the bundle, and therefore,
you need to configure the \QD plugins that you want to use with Qt Creator.
Fore more information about how to deploy applications on Mac OS, see
\l{http://doc.qt.nokia.com/4.7/deployment-mac.html}{Deploying an Application on Mac OS X}.
The following example illustrates how to configure version 5.2.1 of the
\l{http://qwt.sourceforge.net/}{Qwt - Qt Widgets for Technical Applications} library
for use with Qt Creator:
\list 1
\o To check the paths used in the Qwt library, enter the following \c otool command:
\snippet examples/doc_src_plugins.qdoc 0
The output for Qwt 5.2.1 indicates that the plugin uses Qt core libraries (QtDesigner,
QtScript, QtXml, QtGui and QtCore) and libqwt.5.dylib:
\snippet examples/doc_src_plugins.qdoc 1
\o You must copy the \QD plugin and the Qwt library files to the following locations:
\list
\o \c {libqwt_designer_plugin.dylib} to \c {QtCreator.app/Contents/MacOS/designer}
\o \c {libqwt.*.dylib} to \c {QtCreator.app/Contents/Frameworks}
\endlist
Enter the following commands:
\snippet examples/doc_src_plugins.qdoc 4
\o Enter the following \c otool command to check the libraries that are used by the
Qwt library:
\snippet examples/doc_src_plugins.qdoc 2
The command returns the following output:
\snippet examples/doc_src_plugins.qdoc 3
\o Enter the following \c install_name_tool command to fix the references of the
libraries:
\snippet examples/doc_src_plugins.qdoc 5
\endlist
\section1 Matching Build Keys
The Qt Creator that is included in pre-built SDK packages on Windows is built with the
Microsoft Visual Studio compiler, whereas the version of Qt shipped for building applications
is configured and built to use the MinGW/g++ compiler. Plugins built by using this version of
Qt cannot be loaded by Qt Creator because the build-keys do not match. The plugins can only be
used in the standalone version of \QD. Choose \gui{Help > About Qt Creator} to check
the Qt version Qt Creator was built with.
To use \QD plugins that were built for the shipped Qt version, make sure that
Qt Creator is built with the same compiler by either recompiling Qt Creator using MinGW or
recompiling Qt with Microsoft Visual Studio, depending on which configuration you want to
use for your applications.
*/
/*!
\contentspage index.html
\previouspage creator-design-mode.html
\page creator-usability.html
\nextpage adding-plugins.html
\title Optimizing Applications for Mobile Devices
Before starting application development, analyze and define the requirements, scope, and
functionality of the application to ensure efficient functionality and a smooth user
experience. Design the application for a single purpose and analyze how it can best serve
its users. Mobile devices have been designed for use when mobile. Keep the characteristics
of mobile devices in mind when you create applications for them.
The following guidelines help you design and develop usable applications for mobile devices
with varying characteristics, such as screen size and support for input methods:
\list
\o Know your users
Find out who will use the application, what they will use it for,
and which mobile devices they have. Then design the application to fit a specific context
of use.
\o Design for small screens
The screen size of mobile devices is significantly smaller
than that available on desktop devices. Carefully consider what is the most relevant
content to present on the application UI, as it might not be reasonable to try and fit as
much content into the screen as you might have in a desktop application.
\o Design for multiple screen sizes
Relate the position and size of each control to the
dimensions of the display. This enables the same set of information to be presented on the
screen in all resolutions; higher resolution devices just display finer graphics.
\o Design for changing screen orientation
Some devices support screen rotation. On these
devices, applications can be displayed in portrait or landscape orientation. Account for
orientation and dynamically adjust the display when the screen is rotated.
\o Design intuitive ways of moving within applications
Mobile devices lack a mouse and
full-size keyboard, so users must use the touch screen or five way navigation pad to move within
applications. In addition, many users control the devices with one hand. To create an optimized user
experience, allow users to access information with one click; do not make them scroll and type.
\o Design for limited input methods
Applications collect information from users on the task
at hand. In addition to touch screen input, some devices contain physical keys such
as a five way navigation pad, a keypad, and a keyboard. Users enter information by using screen
controls, such as lists, check boxes, radio buttons, and text fields.
\o Keep response times short
Latency can cause delays in user interaction. If users perceive
an application as being slow, they are likely to get frustrated and stop using it.
\o Save battery time
Mobile devices are not constantly connected to a power source but run on
battery power. Optimize power consumption to keep the total consumption at an acceptable
level and to prevent users from running out of battery time.
For more information and code examples on how to minimize power consumption, see
\l{http://developer.symbian.org/wiki/index.php/Creating_Energy_Efficient_Apps_Using_Qt}{Creating Energy Efficient Apps Using Qt}.
\o Consider network issues
If users do not have a flat-rate data plan or WLAN support, mobile
network connections cost them money. Also, when users move around with the devices, the networks
available for connections constantly change.
\o Remember the processing limits of the device
The memory available on devices is limited
and you should use it carefully. Although all mobile devices have common functionality,
each device is individual in terms of both the resources available and extra features.
Therefore, you must consider the constraints of all the target devices.
\endlist
For more information about user experience techniques for mobile devices, see the
\l{http://library.forum.nokia.com/topic/Design_and_User_Experience_Library/GUID-A8DF3EB8-E97C-4DA0-95F6-F464ECC995BC_cover.html}{Design and User Experience Library}
on Forum Nokia.
*/
/*!
\contentspage index.html
\previouspage creator-help.html
\page creator-tips.html
\nextpage creator-keyboard-shortcuts.html
\title Tips and Tricks
\section1 Switching Between Modes
Qt Creator uses different modes for different purposes. You can quickly
switch between these modes with the following keyboard shortcuts:
\list
\o \gui Welcome mode \key Ctrl+1
\o \gui Edit mode \key Ctrl+2
\o \gui Design mode \key Ctrl+3
\o \gui Debug mode \key Ctrl+4
\o \gui Projects mode \key Ctrl+5
\o \gui Help mode \key Ctrl+6
\endlist
For more information about Qt Creator modes, see \l {Qt Creator Modes}.
\section1 Moving Between Open Files
To quickly move between currently open files, press
\key Ctrl+Tab.
To move forward in the location history, press \key {Alt+Right}
(\key {Cmd+Opt+Right} on Mac OS). To move backward, press \key {Alt+Left}
(\key {Cmd+Opt+Left} on Mac OS). For example, if you use the \gui Locator
to jump to a symbol in the same file, you can jump back to your original
location in that file by pressing \key {Alt+Left}.
\section1 Moving To the Edit Mode
To move to the \gui Edit mode and currently active file, press
\key Esc.
If you already are in the \gui Edit mode:
\list
\o The first press moves focus to the editor
\o The second press closes secondary windows
\endlist
\section1 Using the Filter in Options Dialog
To find specific settings you require in \gui{Tools} > \gui{Options...}
use the filter located at the top left of the \gui Options dialog box.
\section1 Opening Output Panes
The output panes provide a list of errors and warnings encountered during
a build, detailed output from the compiler, status of a program when it is
executed and debug output, as well as search results.
To open output panes, use the following shortcuts:
\list
\o \gui{Build Issues} pane Alt+1 (Cmd+1 on Mac OS X)
\o \gui{Search Results} pane Alt+2 (Cmd+2 on Mac OS X)
\o \gui{Application Output} pane Alt+3 (Cmd+3 on Mac OS X)
\o \gui{Compile Output} pane Alt+4 (Cmd+4 on Mac OS X)
\endlist
For more information about output panes, see \l{Viewing Output}.
\section1 Using Keyboard Shortcuts
Qt Creator provides \l{Keyboard Shortcuts}{many useful keyboard shortcuts}.
You can see the keyboard shortcut for a menu command in the menu
or the tooltip for a button.
To customize, import or export keyboard shortcuts, select \gui Tools >
\gui Options... > \gui Environment > \gui Keyboard.
\section1 Running Qt Creator From Command Line
You can launch Qt Creator from command line using the name of an
existing session or \c .pro file by giving the name as the command
argument.
For example, running \tt{qtcreator somesession}, launches Qt Creator and
loads session somesession.
\note Make sure Qt Creator is included in the PATH environment variable.
This can be done by typing the following in the command line:
\code
set PATH=c:\qtsdk\mingw\bin;c:\qtsdk\qt\bin;%PATH%
\endcode
\section1 Showing and Hiding the Sidebar
To toggle the sidebar in the \gui Edit and \gui Debug modes, click
\inlineimage qtcreator-togglebutton.png
or press \key Alt+0 (\key Cmd+0 on Mac OS X).
For more information on using the sidebar, see \l {Browsing Project Contents}.
\section1 Moving To Symbols
To move straight to a symbol used in a project, select the symbol in the
\gui Editor toolbar drop-down menu. For more information on the editor toolbar,
see \l {Using the Editor Toolbar}.
To jump to a symbol in the current file, press \key {Ctrl+K} to open the
\gui Locator, enter a period (.), and start typing the symbol name. Then
select the symbol in the list. For more information on using the locator,
see \l{Searching With the Locator}.
Press \key Ctrl (\key Cmd on Mac OS) and click a symbol to move directly to
the definition or the declaration of the symbol. You can also move the cursor
on the symbol and press \key {F2}. For more information, see
\l{Moving to Symbol Definition or Declaration}.
\section1 Displaying Signals and Slots
If an instance of a class 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, select \gui Tools > \gui Options...
> \gui{Debugger} > \gui{Debugging Helper} > \gui{Use Debugging Helper}.
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
shown as children of the slot. This method works with signals too.
For more information about the \gui{Locals and Watchers} view, see
\l{Locals and Watchers}.
\section1 Displaying Low Level Data
If special debugging of Qt objects fails due to data corruption within the
debugged objects, you can switch off the debugging helpers. When debugging
helpers are switched off low-level structures become visible.
To switch off the debugging helpers:
\list 1
\o Select \gui Tools > \gui Options... > \gui Debugger >
\gui{Debugging Helper}.
\o Uncheck the \gui{Use Debugging Helper} checkbox.
\endlist
\section1 Showing Tooltips in Debug Mode
To inspect the value of variables from the editor, you can turn
on tooltips. Tooltips are hidden by default for performance reasons.
\list 1
\o Select \gui Tools > \gui Options... > \gui Debugger > \gui General.
\o Select the \gui {Use tooltips in main editor while debugging} check box.
\endlist
\section1 Locating Files
The \gui Locator provides one of the easiest ways in Qt Creator to browse
through projects, files, classes, methods, documentation and file systems.
To quickly access files not directly mentioned in your project, you can
create your own locator filters. That way you can locate files in a
directory structure you have defined.
To create locator filters, select \gui {Tools > Options... > Locator > Add}.
For more information, see \l{Creating Locator Filters}.
\section1 Adding a License Header Template for C++ Code
A file containing a license header for C++ can be specified under
\gui{Tools > Options... > C++ > License Template}. It may contain special
placeholders enclosed in \c{%%} that are replaced when generating a
new file:
\list 1
\o \c %YEAR%: Year
\o \c %DATE%: Date
\o \c %USER%: User name
\o \c %FILENAME%: File name
\o \c %CLASS%: Class name (if applicable)
\o \c %$VARIABLE%: Contents of environment variable \c{VARIABLE}.
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-tips.html
\page creator-keyboard-shortcuts.html
\nextpage creator-known-issues.html
\title Keyboard Shortcuts
Qt Creator provides various keyboard shortcuts to speed up your development
process.
\section1 Configuring Keyboard Shortcuts
To customize a keyboard shortcut:
\list 1
\o Select \gui Tools > \gui Options... > \gui Environment >
\gui Keyboard.
\o Select an action from the list.
\o In \gui{Key Sequence} enter the shortcut key you want to associate
with the selected action.
\endlist
Qt Creator allows you to use different keyboard shortcut mapping schemes:
\list
\o To import a keyboard shortcut mapping scheme, click \gui Import
and select the kms file containing keyboard shortcut mapping scheme
you want to import.
\o To export the current keyboard shortcut mapping scheme, click
\gui Export and select the location where you want to save the
exported kms file.
\endlist
\section1 Default Keyboard Shortcuts
The following tables list the default keyboard shortcuts. They are
categorized by actions.
\section2 General Keyboard Shortcuts
\table
\header
\o Action
\o Keyboard shortcut
\row
\o Open file or project
\o Ctrl+O
\row
\o New file or project
\o Ctrl+N
\row
\o Open in external editor
\o Alt+V, Alt+I
\row
\o Cut
\o Ctrl+X
\row
\o Copy
\o Ctrl+C
\row
\o Paste
\o Ctrl+V
\row
\o Redo
\o Ctrl+Y
\row
\o Save
\o Ctrl+S
\row
\o Save all
\o Ctrl+A
\row
\o Close window
\o Ctrl+W
\row
\o Close all
\o Ctrl+Shift+W
\row
\o Go back
\o Alt+Left
\row
\o Go forward
\o Alt+Right
\row
\o Go to line
\o Ctrl+L
\row
\o Next open document in history
\o Ctrl+Shift+Tab
\row
\o Goto other split
\o Ctrl+E, O
\row
\o Previous open document in history
\o Ctrl+Tab
\row
\o Activate \gui Locator
\o Ctrl+K
\row
\o Switch to \gui Welcome mode
\o Ctrl+1
\row
\o Switch to \gui Edit mode
\o Ctrl+2
\row
\o Switch to \gui Design mode
\o Ctrl+3
\row
\o Switch to \gui Debug mode
\o Ctrl+4
\row
\o Switch to \gui Projects mode
\o Ctrl+5
\row
\o Switch to \gui Help mode
\o Ctrl+6
\row
\o Toggle \gui{Build Issues} pane
\o Alt+1 (Cmd+1 on Mac OS X)
\row
\o Toggle \gui{Search Results} pane
\o Alt+2 (Cmd+2 on Mac OS X)
\row
\o Toggle \gui{Application Output} pane
\o Alt+3 (Cmd+3 on Mac OS X)
\row
\o Toggle \gui{Compile Output} pane
\o Alt+4 (Cmd+4 on Mac OS X)
\row
\o Activate \gui Bookmarks pane
\o Alt+M
\row
\o Activate \gui{File System} pane
\o Alt+Y
\row
\o Activate \gui{Open Documents} pane
\o Alt+O
\row
\o Activate \gui Projects pane
\o Alt+X
\row
\o Full screen
\o Ctrl+Shift+F11
\row
\o Toggle the sidebar
\o Alt+0 (Cmd+0 on Mac OS X)
\row
\o Undo
\o Ctrl+Z
\row
\o Move to \gui Edit mode
In \gui Edit mode:
\list
\o The first press moves focus to the editor
\o The second press closes secondary windows
\endlist
\o Esc
\endtable
\section2 Editing Keyboard Shortcuts
\table
\header
\o Action
\o Keyboard shortcut
\row
\o Auto-indent selection
\o Ctrl+I
\row
\o Collapse
\o Ctrl+<
\row
\o Expand
\o Ctrl+>
\row
\o Trigger a completion in this scope
\o Ctrl+Space
\row
\o Copy line down
\o Ctrl+Alt+Down
\row
\o Copy line up
\o Ctrl+Alt+Up
\row
\o Cut line
\o Shift+Del
\row
\o Join lines
\o Ctrl+J
\row
\o Decrease font size
\o Ctrl+- (Ctrl+Roll mouse wheel down)
\row
\o Increase font size
\o Ctrl++ (Ctrl+Roll mouse wheel up)
\row
\o Toggle Vim-style editing
\o Alt+V, Alt+V
\row
\o Split
\o Ctrl+E, 2
\row
\o Split side by side
\o Ctrl+E, 3
\row
\o Remove all splits
\o Ctrl+E, 1
\row
\o Remove current split
\o Ctrl+E, 0
\row
\o Select all
\o Ctrl+A
\row
\o Go to block end
\o Ctrl+]
\row
\o Go to block start
\o Ctrl+[
\row
\o Go to block end with selection
\o Ctrl+}
\row
\o Go to block start with selection
\o Ctrl+{
\row
\o Move current line down
\o Ctrl+Shift+Down
\row
\o Move current line up
\o Ctrl+Shift+Up
\row
\o Trigger a quick fix in this scope
\o Alt+Return
\row
\o Rewrap paragraph
\o Ctrl+E, R
\row
\o Select the current block
The second press extends the selection to the parent block
\o Ctrl+U
\row
\o Enable text wrapping
\o Ctrl+E, Ctrl+W
\row
\o Toggle comment for selection
\o Ctrl+/
\row
\o Visualize whitespace
\o Ctrl+E, Ctrl+V
\row
\o Delete
\o Del
\row
\o Adjust size
\o Ctrl+J
\row
\o Lay out in a grid
\o Ctrl+G
\row
\o Lay out horizontally
\o Ctrl+H
\row
\o Lay out vertically
\o Ctrl+L
\row
\o Preview
\o Alt+Shift+R
\row
\o Edit signals and slots
\o F4
\row
\o Edit widgets
\o F3
\row
\o Toggle bookmark
\o Ctrl+M
\row
\o Go to next bookmark
\o Ctrl+.
\row
\o Go to previous bookmark
\o Ctrl+,
\row
\o Fetch snippet
\o Alt+C, Alt+F
\row
\o Paste snippet
\o Alt+C, Alt+P
\row
\o Find usages
\o Ctrl+Shift+U
\row
\o Follow symbol under cursor
Works with namespaces, classes, methods, variables, include
statements and macros
\o F2
\row
\o Rename symbol under cursor
\o Ctrl+Shift+R
\row
\o Switch between method declaration and definition
\o Shift+F2
\row
\o Open type hierarchy
\o Ctrl+Shift+T
\row
\o Switch between header and source file
\o F4
\endtable
\section2 Debugging Keyboard Shortcuts
\table
\header
\o Action
\o Keyboard shortcut
\row
\o Start debugging
\o F5
\row
\o Stop or interrupt debugger
\o Shift+F5
\row
\o Reset debugger
\o Ctrl+Shift+F5
\row
\o Step over
\o F10
\row
\o Step into
\o F11
\row
\o Step out
\o Shift+F11
\row
\o Toggle breakpoint
\o F9
\endtable
\section2 Project Keyboard Shortcuts
\table
\header
\o Action
\o Keyboard shortcut
\row
\o Build project
\o Ctrl+B
\row
\o Build all
\o Ctrl+Shift+B
\row
\o New project
\o Ctrl+Shift+N
\row
\o Run
\o Ctrl+R
\endtable
\section2 Help Keyboard Shortcuts
\table
\header
\o Action
\o Keyboard shortcut
\row
\o View context-sensitive help
\o F1
\row
\o Activate contents in \gui Help mode
\o Ctrl+T
\row
\o Add bookmark in \gui Help mode
\o Ctrl+M
\row
\o Activate index in \gui Help mode
\o Ctrl+I
\row
\o Reset font size in \gui Help mode
\o Ctrl+0
\row
\o Activate search in \gui Help mode
\o Ctrl+S
\endtable
\section2 Version Control Keyboard Shortcuts
\table
\header
\o {1,2} Action
\o {5,1} Version control system
\header
\o CVS
\o Git
\o Perforce
\o Subversion
\o Mercurial
\row
\o Add
\o Alt+C, Alt+A
\o Alt+G, Alt+A
\o
\o Alt+S, Alt+A
\o
\row
\o Commit
\o Alt+C, Alt+C
\o Alt+G, Alt+C
\o
\o
\o Alt+H, Alt+C
\row
\o Diff
\o Alt+C, Alt+D
\o Alt+G, Alt+D
\o
\o Alt+S, Alt+D
\o Alt+H, Alt+D
\row
\o Diff project
\o
\o Alt+G, Alt+Shift+D
\o Alt+P, Alt+D
\o
\o
\row
\o Blame
\o
\o Alt+G, Alt+B
\o
\o
\o
\row
\o Log
\o
\o Alt+G, Alt+L
\o Alt+P, Alt+F
\o
\o Alt+H, Alt+L
\row
\o Log project
\o
\o Alt+G, Alt+K
\o
\o
\o
\row
\o Status
\o
\o Alt+G, Alt+S
\o
\o
\o Alt+H, Alt+S
\row
\o Undo changes
\o
\o Alt+G, Alt+U
\o
\o
\o
\row
\o Diff project
\o
\o Alt+G, Alt+Shift+D
\o Alt+P, Alt+D
\o
\o
\row
\o Edit
\o
\o
\o Alt+P, Alt+E
\o
\o
\row
\o Opened
\o
\o
\o Alt+P, Alt+O
\o
\o
\row
\o Revert
\o
\o
\o Alt+P, Alt+R
\o
\o
\row
\o Submit
\o
\o
\o Alt+P, Alt+S
\o
\o
\endtable
*/
/*!
\contentspage index.html
\previouspage creator-known-issues.html
\page creator-glossary.html
\nextpage creator-acknowledgements.html
\title Glossary
\table
\header
\o Term
\o Meaning
\row
\o
\raw HTML
Qt in PATH
\endraw
\target glossary-system-qt
\o This is the Qt
version for the \c qmake command found in your \c PATH
environment variable.
This is likely to be the system's Qt version.
\row
\o
\raw HTML
Project Qt
\endraw
\target glossary-project-qt
\o The version of Qt configured in the \gui{Projects} mode, \gui {Build
Settings}, \gui {Qt Version} field. This is the Qt version that
is actually used by a particular project.
\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-keyboard-shortcuts.html
\page creator-known-issues.html
\nextpage creator-glossary.html
\title Known Issues
This section lists known issues in Qt Creator version 2.1.0.
The development team is aware of them, and therefore, you do not need to
report them as bugs.
For a list of fixed issues and added features, see the changelog file in
the \c{qtcreator\dist} folder or the \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}.
\section1 General Issues
\list
\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 Editing Issues
\list
\o Code completion does not support typedefs for nested classes.
\endlist
\section1 Projects Issues
\list
\o Paths or file names containing spaces or special characters
(such as colons, dollar signs, and hash marks) may cause problems. 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 There is no IDE support for adding or removing sub-projects. Project
hierarchies (SUBDIRS template) have to be created manually.
\o Creating new CMake projects with Qt Creator is not supported.
\o Building and packaging sub-projects is not supported for Maemo devices.
\o You must create projects for Maemo targets on the same partition where
you installed Nokia Qt SDK, Qt Creator, and MADDE.
\o If error messages displayed in the \gui {Compile Output} pane contain
paths where slashes are missing (for example, C:NokiaQtSDK),
check your PATH variable. For more information, see
\l{Troubleshooting MinGW Compilation Errors}.
\endlist
\section1 Debugging Issues
\list
\o Debugging large applications on Symbian devices using the Symbian S^3
operating system might not work, because the TRK debug agent might not be able to
access memory when the operating system starts paging. This causes breakpoint
handling and symbol resolution to fail. For more information, see
\l{http://bugreports.qt.nokia.com/browse/QTCREATORBUG-2158}{QTCREATORBUG-2158}.
As a workaround, add the following section to the application .pro file to
disable paging:
\code
debug {
MMP_RULES -= PAGED
MMP_RULES *= UNPAGED
}
\endcode
\note You must completely clean and rebuild the project for the setting to
take effect.
\o When debugging executables created by the GNU Compiler version 4.5.0
(all platforms), some data types will not be displayed in the
\gui{Locals and Watchers} view due to missing debug information.
\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 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 code that is compiled into the binary more
than once does not work.
\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.
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-glossary.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 \br
QtCreator/src/shared/cplusplus\br\br
\o \bold{Botan, a C++ crypto library. Version 1.8.8}\br
\list
\o Copyright (C) 1999-2004 The Botan Project. All rights reserved.
\o Copyright (C) 1999-2009 Jack Lloyd
\o 2001 Peter J Jones
\o 2004-2007 Justin Karneges
\o 2005 Matthew Gregan
\o 2005-2006 Matt Johnston
\o 2006 Luca Piccarreta
\o 2007 Yves Jerschow
\o 2007-2008 FlexSecure GmbH
\o 2007-2008 Technische Universitat Darmstadt
\o 2007-2008 Falko Strenzke
\o 2007-2008 Martin Doering
\o 2007 Manuel Hartl
\o 2007 Christoph Ludwig
\o 2007 Patrick Sona
\endlist
All rights reserved.\br\br
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:\br\br
1. Redistributions of source code must retain the above copyright
notice, this list of conditions, and the following disclaimer.\br\br
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions, and the following disclaimer in the
documentation and/or other materials provided with the distribution.\br
\br
THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE,
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\br\br
The source code of Botan C++ crypto library can be found
here:
\list
\o QtCreator/src/libs/3rdparty
\o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
\endlist
\br\br
\o \bold{NetSieben SSH Library is a Secure Shell client library for C++.
Version 1.3.2}\br
\list
\o \bold{Commercial License:} For organizations who do not want to
release the source code for their applications as open source/
free software; in other words they do not want to comply with the
GNU General Public License (GPL) or Q Public License.
\o \bold{Non Commercial / Open Source License:} NetSieben believes in
contributing back to the open source community, thus it has released
the SSH Library under Q Public License as it is defined by Trolltech
AS of Norway. The Open Source License allows the user to use software
under an open source / free software license, and distribute it
freely. The software can be used at no charge with the condition
that if the user uses the SSH Library in an application they wish to
redistribute, then the complete source code for your application must
be available and freely redistributable under reasonable conditions.
For more information on the used QPL License see:
QtCreator/src/libs/3rdparty/net7ssh/LICENSE.QPL
\endlist\br\br
The source code of NetSieben Secure Shell C++ Library can be found
here:
\list
\o QtCreator/src/libs/3rdparty
\o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
\endlist
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-version-control.html
\page creator-task-lists.html
\nextpage creator-cli.html
\title Creating Task List Files
You can load tasks from task lists to the \gui{Build Issues} pane. You can
either create the task lists manually or create scripts to generate them from
output of static code analysis tools, for example.
For an example of a script that checks new lines of code and matches them
against regular expressions to generate a task list, see \c{scripts\mytasks.pl}
in the Qt Creator repository.
\section1 Task List File Format
The filename extension must be .tasks for Qt Creator to recognize a file as a
task list file.
Each line in a task list file is treated as a tab-separated list of strings with
\c{\t}, \c{\n}, and \c{\\} used as escape characters. The strings are used to create
one task per line. The lines can have one of the following formats:
\list
\o \c description
\o \c{type\tdescription}
\o \c{file\ttype\tdescription}
\o \c{file\tline\ttype\tdescription}
\endlist
The task type can have one of the following values:
\list
\o A string starting with \c err, which displays the error icon in the beginning of the line
\o A string starting with \c warn, which displays the warning icon
\o Any other value, which sets the task type to Unknown and does not
display an icon
\endlist
The values are not case sensitive.
Lines starting with the hash mark character (#) in the first column are ignored.
*/
/*!
\contentspage index.html
\previouspage creator-task-lists.html
\page creator-cli.html
\nextpage creator-help.html
\title Using Command Line Options
You can start Qt Creator and specify some options from the command line.
To specify command line options, enter the following command in the Qt Creator
installation or build directory:
\c {qtcreator [option] [filename]}
For example:
\c {C:\qtcreator-2.1\bin>qtcreator -help}
The following table summarizes the available options:
\table
\header
\o Option
\o Description
\row
\o -help
\o Display help on command line options.
\row
\o -version
\o Display Qt Creator version.
\row
\o -client
\o Attempt to connect to an already running instance of Qt Creator.
\row
\o -noload
\o Do not load the specified plugin.
\row
\o -profile
\o Load profile plugin.
\row
\o -color
\o Core plugin: override the selected UI color.
\row
\o -disable-cdb
\o Debugger plugin: disable the Microsoft Console Debugger (CDB)
engine. For more information, see \l{Debugging}.
\row
\o -disable-gdb
\o Debugger plugin: disable the GNU Symbolic Debugger (gdb) engine.
\row
\o -disable-sdb
\o Debugger plugin: disable the Qt Script debugger engine.
\row
\o -debug
\o Debugger plugin: attach to process ID or core file.
\row
\o -wincrashevent
\o Debugger plugin: Attach to crashed processes by using the specified
event handle.
\row
\o -customwizard-verbose
\o ProjectExplorer plugin: display additional information when loading
custom wizards. For more information about custom wizards, see
\l{Adding New Custom Wizards}
\row
\o -lastsession
\o ProjectExplorer plugin: load the last session when Qt Creator starts.
Open the projects and files that were open when you last exited Qt Creator.
For more information about managing sessions, see \l{Managing Sessions}.
\endtable
*/