forked from qt-creator/qt-creator
8253 lines
295 KiB
Plaintext
8253 lines
295 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** 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.1.81
|
|
|
|
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
|
|
<img border="0" style="float:right;" src="images/qtcreator-screenshots.png" />
|
|
\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}
|
|
\o \l{Debugging Qt Quick Projects}
|
|
\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 8.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 Yes
|
|
\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.
|
|
|
|
\image qmldesigner-visual-editor.png "Visual editor"
|
|
|
|
Use the visual editor panes to manage your project:
|
|
|
|
\list
|
|
|
|
\o \gui {Navigator} pane displays the QML elements in the current QML file.
|
|
You can show and hide items to focus on specific parts of the application.
|
|
To view lists of files or projects, instead, select \gui {File System},
|
|
\gui {Open Documents}, or \gui Projects in the menu.
|
|
|
|
\o \gui {Library} pane displays the building blocks that you can use to design
|
|
applications: predefined QML elements, your own QML components, and other
|
|
resources.
|
|
|
|
\o \gui {Properties} pane organizes the properties of the selected QML element
|
|
or QML 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
|
|
|
|
\section1 Element Library
|
|
|
|
The \gui {Library} pane contains two tabs: \gui {Items} and \gui {Resources}.
|
|
The \gui Items pane displays the QML elements grouped by type: your own QML
|
|
components, basic elements, interaction elements, views, and widgets.
|
|
|
|
\image qmldesigner-qml-components.png "QML Components pane"
|
|
|
|
The \gui {Resources} pane displays the images and other files that you copy to
|
|
the project folder.
|
|
|
|
\section1 Specifying Element Properties
|
|
|
|
The \gui Properties pane displays all the properties of the selected QML element.
|
|
The properties are grouped by type. The top part of the pane displays properties
|
|
that are common to all elements, such as element type, position, size,
|
|
and visibility.
|
|
|
|
The bottom part of the pane displays properties that are specific to each element
|
|
type. For example, the following image displays the properties you can set for
|
|
\gui Rectangle and \gui Text elements.
|
|
|
|
\image qmldesigner-element-properties.png
|
|
|
|
For more information on the properties available for an element, press \key {F1}.
|
|
|
|
\section2 Setting Expressions
|
|
|
|
You can set Java Script expressions as values of some properties. Click the circle
|
|
icon next to a property to open a context menu, and select \gui {Set Expression}.
|
|
|
|
\image qmldesigner-set-expression.png "Element properties context menu"
|
|
|
|
For more information on the Java Script environment provided by QML, see
|
|
\l{http://doc.qt.nokia.com/4.7-snapshot/qdeclarativejavascript.html}{Integrating JavaScript}.
|
|
|
|
\section2 Setting Anchors and Margins
|
|
|
|
The \gui Layout pane allows you to set anchors and margins for elements. To set
|
|
the anchors of an item, click the anchor buttons. You can combine the top/bottom
|
|
and left/right anchors to anchor objects in the corners of the parent element.
|
|
|
|
\inlineimage qmldesigner-anchor-buttons.png "Anchor buttons"
|
|
|
|
\section2 Building Transformations on Items
|
|
|
|
The \gui Advanced pane allows you configure advanced transformations, such as
|
|
rotation, scale, and translation. You can assign any number of transformations
|
|
to an item. Each transformation is applied in order, one at a time.
|
|
|
|
For more information on Transform elements, see
|
|
\l {http://doc.qt.nokia.com/4.7/qml-transform.html}{QML Transform Element}.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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
|
|
\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
|
|
|
|
<wizard version="1" kind="project"
|
|
class="qt4project" firstpage="10"
|
|
id="A.HelloWorld" category="B.CustomProjects">
|
|
|
|
\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
|
|
|
|
<icon>console.png</icon>
|
|
<description>Creates a hello-world-project with custom message.</description>
|
|
<description xml:lang="de">Erzeugt ein Hello-Welt-Projekt mit einer Nachricht.</description>
|
|
<displayname>Hello World</displayname>;
|
|
<displayname xml:lang="de">Hallo Welt</displayname>;
|
|
<displaycategory>Custom Projects</displaycategory>
|
|
<displaycategory xml:lang="de">Benutzerdefinierte Projekte</displaycategory>
|
|
|
|
\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
|
|
<files>
|
|
<file source="main.cpp" openeditor="true" />
|
|
<file source="project.pro" target="%ProjectName%.pro" openproject="true" />
|
|
<file source="icon.png" target="%ProjectName%.png" binary="true" />
|
|
\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
|
|
<generatorscript binary="generate.pl">
|
|
<argument value="--class-name=%ClassName%"/>
|
|
<argument value="--project-name=%ProjectName%"/>
|
|
<argument value="--header-suffix=%CppHeaderSuffix%" omit-empty="true"/>
|
|
<argument value="--source-suffix=%CppSourceSuffix%" omit-empty="true"/>
|
|
<argument value="--description=%Description%" omit-empty="true" write-file="true"/>
|
|
</generatorscript>
|
|
\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
|
|
|
|
<!-- Create a 2nd wizard page with parameters -->
|
|
<fieldpagetitle>Hello World Parameters</fieldpagetitle>
|
|
<fieldpagetitle xml:lang="de">Hallo Welt Parameter</fieldpagetitle>
|
|
<fields>
|
|
<field mandatory="true" name="MESSAGE">
|
|
<fieldcontrol class="QLineEdit" validator='^[^"]+$' defaulttext="Hello world!" />
|
|
<fielddescription>Hello world message:</fielddescription>
|
|
<fielddescription xml:lang="de">Hallo-Welt-Nachricht:</fielddescription>
|
|
</field>
|
|
</fields>
|
|
|
|
\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
|
|
|
|
<wizard version="1" kind="class" id="A.ListModel" category="B.CustomClasses">
|
|
|
|
<description>Creates a QAbstractListModel implementation.</description>
|
|
<description xml:lang="de">Erzeugt eine Implementierung von QAbstractListModel.</description>
|
|
|
|
<displayname>QAbstractListModel implementation</displayname>
|
|
<displayname xml:lang="de">Implementierung von QAbstractListModel</displayname>
|
|
|
|
<displaycategory>Custom Classes</displaycategory>
|
|
<displaycategory xml:lang="de">Benutzerdefinierte Klassen</displaycategory>
|
|
|
|
\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
|
|
|
|
<files>
|
|
<file source="listmodel.cpp" target="%ClassName:l%.%CppSourceSuffix%" openeditor="true" />
|
|
<file source="listmodel.h" target="%ClassName:l%.%CppHeaderSuffix%" openeditor="true" />
|
|
</files>
|
|
|
|
\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
|
|
|
|
<!-- Create parameter wizard page -->
|
|
|
|
<fieldpagetitle>ListModel parameters</fieldpagetitle>
|
|
<fieldpagetitle xml:lang="de">Parameter des ListModel</fieldpagetitle>
|
|
<fields>
|
|
<field name="ClassName">
|
|
|
|
<fieldcontrol class="QLineEdit" validator="^[a-zA-Z0-9_]+$" defaulttext="MyListModel" />
|
|
|
|
<fielddescription>Class name:</fielddescription>
|
|
<fielddescription xml:lang="de">Klassenname:</fielddescription>
|
|
</field>
|
|
<field name="Datatype">
|
|
|
|
<fieldcontrol class="QComboBox" combochoices="QString,int" defaultindex="0" />
|
|
|
|
<fielddescription>Data type:</fielddescription>
|
|
<fielddescription xml:lang="de">Datentyp:</fielddescription>
|
|
</field>
|
|
</fields>
|
|
|
|
\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
|
|
<validationrules>
|
|
<validationrule condition='"%ClassName%" != "QAbstractListModel"'>
|
|
<message>%ClassName% cannot be used as class name.</message>
|
|
<message xml:lang="de">%ClassName% kann nicht als Klassenname verwendet werden.</message>
|
|
</validationrule>
|
|
</validationrules>
|
|
\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{<file>} 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 it on the device,
|
|
and executes the selected application.
|
|
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}.
|
|
|
|
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 <directory>} 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 <Jon.Doe@company.com>
|
|
Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
|
|
\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 submenu 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
|
|
|
|
All supported version control system support reverting your project to
|
|
known states. This functionality is generally called \e reverting.
|
|
|
|
The changes discarded depend on the version control system.
|
|
|
|
A version control system can replace the \gui Revert menu option with other
|
|
options.
|
|
|
|
\section3 Reverting Changes Using Git
|
|
|
|
The Git version control system has an index that is used to stage
|
|
changes. The index is commited on the next commit. Git allows you to revert
|
|
back to the state of the last commit as well as to the state staged in the
|
|
index.
|
|
|
|
\list
|
|
|
|
\o \gui{Undo Unstaged Changes} reverts all changes and resets the working
|
|
directory to the state of the index.
|
|
|
|
\o \gui{Undo Uncommitted Changes} reverts all changes, discarding the index.
|
|
This returns your working copy to the state it was in right after the last commit.
|
|
|
|
\endlist
|
|
|
|
\section2 Using Additional Git Functions
|
|
|
|
Git is a fast decentralized version control system. Git is available
|
|
for Windows, Linux and Mac.
|
|
|
|
The \gui Git submenu contains the following additional items:
|
|
|
|
\table
|
|
|
|
\row
|
|
\i \gui {Patch > Apply from Editor/Apply from File...}
|
|
\i Patches are rewriting instructions that can be applied to a set of files.
|
|
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{Pull}
|
|
\i Pull changes from the remote repository. If there are locally
|
|
modified files, you are prompted to stash those changes. Select \gui{Tools >
|
|
Options... > Version Control > Git} and select the \gui {Pull with rebase}
|
|
check box to perform a rebase operation while pulling.
|
|
|
|
\row
|
|
\i \gui{Clean.../Clean Project...}
|
|
\i All files that are not under version control (with the exception
|
|
of patches and project files) are displayed in the \gui {Clean Repository}
|
|
dialog. Select the files to delete and click \gui Delete. This allows you to
|
|
clean a build completely.
|
|
|
|
\row
|
|
\i \gui{Branches...}
|
|
\i Display the \gui Branch dialog that shows the local branches at the
|
|
top and remote branches at the bottom. To switch to a local branch,
|
|
double-click 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 {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
|
|
|
|
\section3 Using Stashes
|
|
|
|
With Git, you can put your current set of changes onto a virtual shelf called a \e stash.
|
|
Stashes are useful, for example, to put aside a set of changes to work on higher
|
|
priority tasks or to pull in new chages from another repository.
|
|
|
|
Qt Creator exposes this functionality in the \gui{Tools > Git > Stash} menu.
|
|
|
|
\table
|
|
\row
|
|
\i \gui{Stashes...}
|
|
\i Display a dialog that shows all known stashes with options to restore,
|
|
display or delete them.
|
|
\row
|
|
\i \gui{Stash}
|
|
\i Stash all local changes. The working copy is then reset to
|
|
the state it had right after the last commit.
|
|
\row
|
|
\i \gui{Stash Snapshot...}
|
|
\i Save a snapshot of your current work under a name for later reference. The
|
|
working copy is unchanged.
|
|
|
|
For example, if you want to try 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 Pop}
|
|
\i Remove a single stashed state from the stash list and apply it on
|
|
top of the current working tree state.
|
|
\endtable
|
|
|
|
\section2 Using Additional Mercurial Functionality
|
|
|
|
The \gui Mercurial submenu 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 submenu 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 submenu 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 a QML/Java Script debugger.
|
|
|
|
The following sections describe debugging with Qt Creator:
|
|
|
|
\list
|
|
|
|
\o \l{Debugging the Example Application} uses an example application to illustrate
|
|
how to debug Qt C++ 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.
|
|
|
|
\o \l{Debugging Qt Quick Projects} describes how to debug Qt Quick projects.
|
|
|
|
\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
|
|
|
|
\note Debugging QML and Java Script is supported only in plain mode.
|
|
|
|
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
|
|
|
|
\note The information in this section applies only to debugging the C++
|
|
language.
|
|
|
|
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}. The Qt Creator help browser does
|
|
not allow you to download files, and therefore, you must copy the above links to
|
|
a browser.
|
|
|
|
\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. The availability of views depends on whether
|
|
you are debugging C++ or QML. 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}.
|
|
|
|
\note Debugging QML and Java Script is supported only in plain mode.
|
|
|
|
Once the program starts running, it behaves and performs as usual.
|
|
You can interrupt a running C++ program by selecting \gui{Debug} >
|
|
\gui {Interrupt}. The program is automatically interrupted as soon as a
|
|
breakpoint is hit.
|
|
|
|
\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 if you are debugging the C++ language.
|
|
\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 subfunction, 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.
|
|
|
|
|
|
\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 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.
|
|
|
|
\section1 Debugging the C++ Language
|
|
|
|
The following sections describe additional debugging functions that apply
|
|
only to debugging C++.
|
|
|
|
\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}.
|
|
|
|
\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.
|
|
|
|
\section2 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.
|
|
|
|
\section2 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.
|
|
|
|
|
|
\section2 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.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 Qt C++ 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-debugging-qml.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.putSubItem(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="<incomplete>",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{putItem(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{putSubItem(self, item)} - Equivalent to:
|
|
\code
|
|
with SubItem(self):
|
|
self.putItem(item)
|
|
\endcode
|
|
Exceptions raised by nested function calls are caught and all
|
|
output produced by \c putItem is replaced by the output of:
|
|
\code
|
|
...
|
|
except RuntimeError:
|
|
d.put('value="<invalid>",type="<unknown>",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.putItem(Item(key, item.iname, "key"))
|
|
with SubItem(d):
|
|
d.putName("value")
|
|
d.putItem(Item(value, item.iname, "value"))
|
|
\endcode
|
|
|
|
\section1 Debugging Helpers for QML
|
|
|
|
The debugging helpers for QML provide you with code completion for custom modules
|
|
(\c qmldump) and debugging Qt Quick UI projects (\c qmlobserver).
|
|
|
|
You have to build the QML Observer once for each Qt version that you want to debug
|
|
with. Select \gui{Tools > Options... > Qt4 > Qt Versions}.
|
|
|
|
\note QML Observer requires Qt 4.7.1 or later.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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-debugging-helpers.html
|
|
\page creator-debugging-qml.html
|
|
\nextpage creator-maemo-emulator.html
|
|
|
|
\title Debugging Qt Quick Projects
|
|
|
|
\note You need Qt 4.7.1 or later to debug Qt Quick projects.
|
|
|
|
\section1 Setting Up QML Debugging
|
|
|
|
The process of setting up debugging for Qt Quick projects depends on the type of
|
|
the project: Qt Quick UI or Qt Quick Application.
|
|
|
|
To debug Qt Quick UI projects, you must compile the debugging helpers. For more
|
|
information, see \l{Debugging Helpers for QML}.
|
|
|
|
To debug Qt Quick Applications, you must modify the project file to comment in the
|
|
following line:
|
|
|
|
\c {DEFINES += QMLJSDEBUGGER}.
|
|
|
|
Then you must rebuild the project.
|
|
|
|
To enable QML debugging for both types of projects, select \gui Projects, and
|
|
then select the \gui QML check box in the run settings.
|
|
|
|
\section1 Starting QML Debugging
|
|
|
|
To start the application, choose \gui {Debug > Start Debugging
|
|
> Start Debugging} or press \key F5. Once the application starts running, it behaves
|
|
and performs as usual. You can then perform the following tasks:
|
|
|
|
\list
|
|
|
|
\o Debug Java Script functions
|
|
|
|
\o Preview QML changes at runtime
|
|
|
|
\o Inspect QML at runtime
|
|
|
|
\endlist
|
|
|
|
\section1 Debugging Java Script Functions
|
|
|
|
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, as described in the following sections:
|
|
|
|
\list
|
|
|
|
\o \l{Setting Breakpoints}
|
|
|
|
\o \l{Viewing Call Stack Trace}
|
|
|
|
\o \l{Locals and Watchers}
|
|
|
|
\endlist
|
|
|
|
\section1 Executing Java Script Expressions
|
|
|
|
When the application is interrupted by a breakpoint, you can use the \gui {QML
|
|
Script Console} to execute Java Script expressions in the current context. To
|
|
open it, choose \gui {Window > View > QML Script Console}.
|
|
|
|
\image qml-script-console.png "QML Script Console view"
|
|
|
|
You can type Java Script expressions and use them to get information about the
|
|
state or your application. For example, property values.
|
|
|
|
You can see the current value of a property by hovering over it in the code editor.
|
|
|
|
\section1 Previewing QML Changes at Runtime
|
|
|
|
If you change property values or add properties in the code editor, the changes
|
|
are updated in the running application when you save them. If live preview is not supported
|
|
for an element, a message appears. Click \gui Reload to preview the changes.
|
|
|
|
Reloading is enabled by default. To disable it, click
|
|
\inlineimage qml-observer-bar-reload.png "Apply Changes on Save button"
|
|
in the \gui {QML Observer} view.
|
|
|
|
\section1 Inspecting QML at Runtime
|
|
|
|
While the application is running, you can use the \gui {QML Observer} view to
|
|
explore the object structure, debug animations, and inspect colors.
|
|
To open the \gui {QML Observer} view, choose \gui {Window > View > QML Observer}.
|
|
|
|
\image qml-observer-view.png "QML Observer view"
|
|
|
|
When you debug complex applications, you can use the observe
|
|
mode to jump to the position in code where an element is defined. To switch to
|
|
the observe mode, click
|
|
\inlineimage qml-observer-bar-observe.png
|
|
in the \gui {QML Observer} view.
|
|
|
|
Click elements in the running application to jump to their definitions in the code.
|
|
Double-click elements to browse the element hierarchy. The hierarchy is displayed
|
|
as bread crumbs in the \gui {QML Observer} view.
|
|
|
|
You can also right-click an element in the running application to view the element
|
|
hierarchy as a context menu. Select an element to jump to its definition in code.
|
|
|
|
To zoom in and out of the application, click the \gui Zoom button.
|
|
|
|
To inspect colors, click the \gui {Color Picker} button. You can also the click
|
|
\inlineimage qml-observer-bar-copy-color.png "Copy Color button"
|
|
to copy the color definition to the clipboard.
|
|
|
|
\section1 Debugging Animations
|
|
|
|
\image qml-observer.png
|
|
|
|
To play and pause animations in the running application, click the \gui {Play/Pause Animations}
|
|
button in the \gui {QML Observer} view or \gui {Debugging > Animations > Pause} or press
|
|
\key {Ctrl+.}.
|
|
|
|
To step through an animation, select \gui {Debugging > Animations > Pause & Step}
|
|
or press \key {Ctrl+,}.
|
|
|
|
To set step duration in milliseconds, select \gui {Debugging > Animations > Set Step}.
|
|
To change the speed at which animations are played, select a value in \gui {Debugging
|
|
> Animations}.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
|
|
\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 creator-using-qt-quick-designer.html
|
|
\page quick-components.html
|
|
\nextpage quick-buttons.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 use the following QML elements to create 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
|
|
|
|
\section1 Creating Components in Qt Quick Designer
|
|
|
|
\list 1
|
|
|
|
\o Select \gui {File > New File or Project > Files and Classes > QML
|
|
> Choose...} to create a new .qml file.
|
|
|
|
\note Components are listed in the \gui {QML Components} section of the
|
|
\gui Library pane only if the filename begins with a capital letter.
|
|
|
|
\o Click \gui Design to open the .qml file in \QMLD.
|
|
|
|
\o Drag and drop an item from the \gui Library pane to the editor.
|
|
|
|
\o Edit item properties in the \gui Properties pane.
|
|
|
|
The available properties depend on the item.
|
|
|
|
\endlist
|
|
|
|
The following sections contain examples of how to create some common components:
|
|
|
|
\list
|
|
|
|
\o \l{Creating Buttons}
|
|
|
|
\o \l{Creating Scalable Buttons and Borders}
|
|
|
|
\endlist
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage quick-components.html
|
|
\page quick-buttons.html
|
|
\nextpage quick-scalable-image.html
|
|
|
|
\title Creating Buttons
|
|
|
|
To create a button component:
|
|
|
|
\list 1
|
|
|
|
\o Select \gui {File > New File or Project > QML > QML File > Choose...} to
|
|
create a QML file called Button.qml (for example).
|
|
|
|
\note Components are listed in the \gui Library pane only if the filename
|
|
begins with a capital letter.
|
|
|
|
\o Click \gui {Design} to edit the file in the visual editor.
|
|
|
|
\o In the \gui Navigator pane, click \gui Rectangle to set properties
|
|
for it.
|
|
|
|
\o In the \gui Properties pane, modify the appearance of the button.
|
|
|
|
\list a
|
|
|
|
\o In the \gui Size field, set the width (\gui W) and height (\gui H)
|
|
of the button.
|
|
|
|
\o In the \gui Color field, select the button color.
|
|
|
|
\o In the \gui Radius field, use the slider to set the radius of the
|
|
rectangle and produce rounded corners for the button.
|
|
|
|
\endlist
|
|
|
|
\o Drag and drop a \gui {Text} item on top of the \gui Rectangle. This
|
|
creates a nested element where \gui Rectangle is the parent element of
|
|
\gui Text. Elements are positioned relative to their parents.
|
|
|
|
\o In the \gui Properties pane, edit the properties of the \gui Text item.
|
|
|
|
\list a
|
|
|
|
\o In the \gui Text field, type \bold Button.
|
|
|
|
You can select the text color, font, size, and style in the \gui Font
|
|
section.
|
|
|
|
\o In the \gui Alignment field, select the center buttons to align
|
|
the text to the center of the button.
|
|
|
|
\o Click \gui {Layout}, and then click the
|
|
\inlineimage qmldesigner-anchor-fill-screen.png
|
|
button to anchor the text to the whole button area.
|
|
|
|
\endlist
|
|
|
|
\o Press \key {Ctrl+S} to save the button.
|
|
|
|
\image qmldesigner-button.png "Button component"
|
|
|
|
\endlist
|
|
|
|
\note To view the button, you must add it to a Qt Quick Application or Qt Quick UI
|
|
project.
|
|
|
|
To create a graphical button that scales beautifully without using vector graphics,
|
|
use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
|
|
element. For more information, see \l{Creating Scalable Buttons and Borders}.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
|
|
\contentspage index.html
|
|
\previouspage quick-buttons.html
|
|
\page quick-scalable-image.html
|
|
\nextpage quick-screens.html
|
|
|
|
\title Creating Scalable Buttons and Borders
|
|
|
|
You can use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
|
|
element to display an image, such as a PNG file, as a border and a background.
|
|
|
|
Use two Border Image elements and suitable graphics to make it look like the button
|
|
is pushed down when it is clicked. One of the Border Image elements is visible by default.
|
|
You can specify that it is hidden and the other one becomes visible when the mouse
|
|
is clicked.
|
|
|
|
Add a MouseArea that covers the whole area and emits the clicked signal (\c {parent.clicked()})
|
|
when it detects a mouse click.
|
|
|
|
You can add text to the button and set it up as a property. The text can then be initialized
|
|
from the outside, making the button a reusable UI component. The font size is also available
|
|
in case the default size is too big. You can scale down the button text and use smooth text
|
|
rendering for some extra quality.
|
|
|
|
\image qmldesigner-borderimage.png "Graphical button"
|
|
|
|
To create a graphical button:
|
|
|
|
\list 1
|
|
|
|
\o Select \gui {File > New File or Project > QML > QML File > Choose...} to create
|
|
a QML file called Button.qml (for example).
|
|
|
|
\o Double-click the file to open it in the code editor.
|
|
|
|
\o Replace the \gui Rectangle with an \gui Item, as illustrated by the
|
|
following code snippet:
|
|
|
|
\code
|
|
|
|
Item {
|
|
|
|
}
|
|
|
|
\endcode
|
|
|
|
\o Specify properties and set expressions for the \gui Item, as
|
|
illustrated by the following code snippet:
|
|
|
|
\code
|
|
|
|
property string text: ""
|
|
property int fontSize: 44
|
|
|
|
signal clicked
|
|
|
|
\endcode
|
|
|
|
You will point to the properties and expression later.
|
|
|
|
\o Click \gui {Design} to edit the file in the visual editor.
|
|
|
|
\o Drag and drop two \gui BorderImage items from the \gui Library pane to
|
|
the scene.
|
|
|
|
\o Drag and drop a \gui Text item to the scene.
|
|
|
|
\o Drag and drop a \gui MouseArea to the screen.
|
|
|
|
\o In the \gui Navigator pane, select \gui border_image1 to specify
|
|
settings for it in the \gui Properties pane:
|
|
|
|
\list a
|
|
|
|
\o Select \gui {Set Expression} in the menu next to the \gui Visibility
|
|
check box.
|
|
|
|
\o Enter the following expression to specify that the image is visible
|
|
when the mouse is not pressed down: \c {!mouse_area1.pressed}.
|
|
|
|
\o In the \gui Source field, select the image file for the
|
|
button, for example button_up.png.
|
|
|
|
\o Click \gui {Layout}, and then click the
|
|
\inlineimage qmldesigner-anchor-fill-screen.png
|
|
button to anchor the border image to the \gui Item.
|
|
|
|
\endlist
|
|
|
|
\o Select \gui border_image2 to specify similar settings for it:
|
|
|
|
\list a
|
|
|
|
\o Set the following epression for \gui Visibility, to specify that
|
|
the the image is visible when the mouse is pressed down:
|
|
\c {mouse_area1.pressed}.
|
|
|
|
\o In the \gui Source field, select the image file for the
|
|
button when it is clicked, for example button_down.png.
|
|
|
|
\o Click \gui {Layout}, and then click the
|
|
\inlineimage qmldesigner-anchor-fill-screen.png
|
|
button to anchor the border image to the \gui Item.
|
|
|
|
\endlist
|
|
|
|
\o Select \gui text1 to specify font size and color, and text
|
|
scaling and rendering:
|
|
|
|
\list a
|
|
|
|
\o In the \gui Color field, use the color picker to select
|
|
the font color, or enter a value in the field.
|
|
|
|
\o In the \gui Text field, select \gui {Set Expression} and
|
|
enter a pointer to the \c {text} property that you specified
|
|
earlier: \c {parent.txt}.
|
|
|
|
\o Select the \gui Aliasing check box to enable smooth text
|
|
rendering.
|
|
|
|
\o In the \gui Size field, select \gui {Pixels} to specify
|
|
the font size in pixels. By default, the size is specified in
|
|
points.
|
|
|
|
\o In the \gui Size field, select \gui {Set Expression} and
|
|
enter a pointer to the \c {fontSize} property that you specified
|
|
earlier.
|
|
|
|
\o Click \gui {Layout}, and then click the
|
|
\inlineimage qmldesigner-center-in.png "Anchor buttons"
|
|
buttons to inherit the vertical and horizontal centering from
|
|
the parent.
|
|
|
|
\o Click \gui Advanced to specify scaling for the text in the
|
|
\gui Scale field.
|
|
|
|
\o Select \gui {Set Expression} and enter the following expression:
|
|
\c {if (!mousearea1.pressed) { 1 } else { 0.95 }}.
|
|
|
|
\note You can enter long and complicated expressions also in the
|
|
code editor.
|
|
|
|
\endlist
|
|
|
|
\o In the code editor, add to the \c MouseArea item
|
|
a pointer to the \c clicked expression that you added earlier:
|
|
\c {onClicked: parent.clicked()}.
|
|
|
|
\endlist
|
|
|
|
\note To view the button, you must add it to a Qt Quick Application or Qt
|
|
Quick UI project.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
|
|
\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.
|
|
Typically, the main qml file in a Qt Quick project specifies the main window of an
|
|
application.
|
|
|
|
The QML files in the project folder are displayed in \gui {QML Components} in the
|
|
\gui Library pane.
|
|
|
|
\section1 Adding Components to Screens
|
|
|
|
\list 1
|
|
|
|
\o Drag and drop components from the \gui Library pane to the editor.
|
|
|
|
\o Select components in the \gui Navigator pane to edit their properties
|
|
in the \gui Properties pane.
|
|
|
|
For example, you can anchor components to a position on the screen.
|
|
|
|
\endlist
|
|
|
|
\section1 Organizing Items on 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.
|
|
|
|
\section1 Using States
|
|
|
|
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.
|
|
|
|
To add states, click the empty slot in the \gui States pane. Then modify the new state
|
|
in the visual editor.
|
|
|
|
\image qmldesigner-states.png "States pane"
|
|
|
|
The properties that you change in a state are highlighted with blue color.
|
|
In the code editor, you can see the changes recorded as changes to the base state.
|
|
*/
|
|
|
|
|
|
/*!
|
|
|
|
\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 subprojects. Project
|
|
hierarchies (SUBDIRS template) have to be created manually.
|
|
|
|
\o Creating new CMake projects with Qt Creator is not supported.
|
|
|
|
\o Building and packaging subprojects 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 <roberto.raggi@gmail.com>\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 <plugin>
|
|
\o Do not load the specified plugin.
|
|
|
|
\row
|
|
\o -profile
|
|
\o Output plugin start up and shut down profiling data.
|
|
|
|
\row
|
|
\o -settingspath <path>
|
|
\o Override the default path where user settings are stored.
|
|
|
|
\row
|
|
\o -color <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 <PID-or-corefile>
|
|
\o Debugger plugin: attach to process ID or core file.
|
|
|
|
\row
|
|
\o -wincrashevent <event-handle>
|
|
\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
|
|
|
|
|
|
*/
|