forked from qt-creator/qt-creator
7535 lines
265 KiB
Plaintext
7535 lines
265 KiB
Plaintext
// **********************************************************************
|
|
// NOTE: the sections are not ordered by their logical order to avoid
|
|
// reshuffling the file each time the index order changes (i.e., often).
|
|
// Run the fixnavi.pl script to adjust the links to the index order.
|
|
// **********************************************************************
|
|
|
|
|
|
/*!
|
|
\contentspage{index.html}{Qt Creator}
|
|
\page index.html
|
|
\nextpage creator-overview.html
|
|
|
|
\title Qt Creator Manual
|
|
|
|
\section1 Version 2.0
|
|
|
|
Qt Creator provides integrated tools for both application designers
|
|
and developers to create applications for multiple desktop and mobile device
|
|
platforms.
|
|
|
|
For application designers, Qt Creator provides integrated
|
|
visual editors, \QD
|
|
\if defined(qtquick)
|
|
and \QMLD,
|
|
\endif
|
|
that you can use to design and develop
|
|
application user interfaces.
|
|
|
|
For application developers,
|
|
Qt Creator provides a cross-platform, complete integrated development
|
|
environment (IDE) that 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{Quick Tour}
|
|
\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}
|
|
\if defined(qtquick)
|
|
\o \l{Creating a Qt Quick Application}
|
|
\endif
|
|
\endlist
|
|
\o \l{Using the Editor}
|
|
\list
|
|
\o \l{Finding and Replacing}
|
|
\o \l{Refactoring}
|
|
\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{Managing Projects}
|
|
\list
|
|
\o \l{Creating a Project}
|
|
\o \l{Setting Up a qmake Project}
|
|
\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}
|
|
\endlist
|
|
\o \l{Building and Running Applications}
|
|
\list
|
|
\o \l{Building for Multiple Targets}
|
|
\o \l{Specifying Build Settings}
|
|
\o \l{Specifying Run Settings}
|
|
\o \l{Specifying Editor Settings}
|
|
\o \l{Specifying Dependencies}
|
|
\endlist
|
|
\if defined(qtquick)
|
|
\o \l{Developing Qt Quick Applications}
|
|
\endif
|
|
\o \l{Optimizing Applications for Mobile Devices}
|
|
\o \l{Using the Maemo Emulator}
|
|
\o \l{Debugging}
|
|
\list
|
|
\o \l {Debugging Qt Applications}
|
|
\list
|
|
\o \l{Debugging the Example Application}
|
|
\o \l{Interacting with the Debugger}
|
|
\o \l{Setting Up Debugger}
|
|
\o \l{Using Debugging Helpers}
|
|
\endlist
|
|
\if defined(qtquick)
|
|
\o \l{Debugging Qt Quick Applications}
|
|
\endif
|
|
\if defined(qtquick)
|
|
\list
|
|
\o \l{Using the QML Inspector}
|
|
\endlist
|
|
\endif
|
|
\endlist
|
|
\o \l{Using Version Control Systems}
|
|
\o \l{Adding Qt Designer Plugins}
|
|
\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 provides you with tools to design and develop user interfaces and
|
|
complex applications for multiple desktop and mobile
|
|
platforms.
|
|
|
|
\section1 Designing User Interfaces
|
|
|
|
\if defined(qtquick)
|
|
|
|
Qt Creator provides two integrated visual editors, \QD and \QMLD.
|
|
|
|
\endif
|
|
|
|
\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.
|
|
|
|
\if defined(qtquick)
|
|
|
|
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-snapshot/declarativeui.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. \QMLD generates the necessary code for you.
|
|
|
|
\note The visual \QMLD editor is provided as an experimental plugin that you must
|
|
enable to be able to edit QML files in the \gui Design mode. Enabling the
|
|
visual editor can negatively affect the overall stability of Qt Creator.
|
|
|
|
You can edit the code in the code editor to add transitions from one state to another,
|
|
and interaction to specify user actions that change the states. You
|
|
can use Qt or JavaScript to implement the application logic.
|
|
|
|
\endif
|
|
|
|
\section1 Coding Applications
|
|
|
|
As an IDE, Qt Creator differs from a text editor in that it knows how to build and run
|
|
applications. It understands the code 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
|
|
|
|
\section1 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.
|
|
|
|
\if defined(qtquick)
|
|
|
|
If you choose to create a Qt Quick application, Qt Creator generates a .qml file
|
|
that you can modify with the \QMLD visual editor and the code editor.
|
|
|
|
\endif
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-overview.html
|
|
\page creator-os-supported-platforms.html
|
|
\nextpage creator-quick-tour.html
|
|
|
|
\title Operating Systems and Supported Platforms
|
|
|
|
\section1 Operating Systems
|
|
|
|
Qt Creator is available in binary packages for the following operating
|
|
systems:
|
|
\list
|
|
\o Windows XP Service Pack 2
|
|
\o Windows Vista
|
|
\o (K)Ubuntu Linux 7.04 (32-bit and 64-bit) or later, with the following:
|
|
\list
|
|
\o g++
|
|
\o make
|
|
\o libglib2.0-dev
|
|
\o libSM-dev
|
|
\o libxrender-dev
|
|
\o libfontconfig1-dev
|
|
\o libxext-dev
|
|
\o libfreetype6-dev
|
|
\o libx11-dev
|
|
\o libxcursor-dev
|
|
\o libxfixes-dev
|
|
\o libxft-dev
|
|
\o libxi-dev
|
|
\o libxrandr-dev
|
|
\o If you are using QtOpenGL, libgl-dev and libglu-dev
|
|
\endlist
|
|
\o Mac OS 10.5 or later with the following:
|
|
\list
|
|
\o Xcode tools for your Mac OS X version available from your Mac
|
|
OS X installation DVDs or at \l http://developer.apple.com.
|
|
\endlist
|
|
\endlist
|
|
|
|
\omit ## Are the Xcode tools still needed separately? \endomit
|
|
|
|
\section1 Build Environment
|
|
|
|
To build Qt Creator itself from the source, you need:
|
|
\list
|
|
\o Qt 4.7 or later
|
|
\o On Windows, MinGW 4.4 or Microsoft Visual Studio 2008
|
|
\endlist
|
|
|
|
\section1 Supported Mobile Device Platforms
|
|
You can develop applications for the following mobile device
|
|
platforms:
|
|
|
|
\list
|
|
|
|
\o Symbian
|
|
|
|
\o Maemo and Maemo Application Development and Debugging Environment (MADDE)
|
|
|
|
\endlist
|
|
|
|
The following table summarizes operating system support for building
|
|
applications for mobile device platforms.
|
|
|
|
\table
|
|
\header
|
|
\o {1,3} Operating system
|
|
\o {3,1} Platform
|
|
\header
|
|
\o Desktop
|
|
\o Symbian
|
|
\o Maemo
|
|
\row
|
|
\o Windows
|
|
\o Yes
|
|
\o Yes
|
|
\o Yes
|
|
\row
|
|
\o Linux
|
|
\o Yes
|
|
\o No
|
|
\o Yes
|
|
\row
|
|
\o Mac OS X
|
|
\o Yes
|
|
\o No
|
|
\o No
|
|
\endtable
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-os-supported-platforms.html
|
|
\page creator-quick-tour.html
|
|
\nextpage creator-getting-started.html
|
|
|
|
\title Quick Tour
|
|
|
|
The figure below shows some of the components of Qt Creator in
|
|
\gui{Edit} mode.
|
|
|
|
\image qtcreator-breakdown.png
|
|
|
|
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}.
|
|
|
|
\list
|
|
\o \gui Welcome mode for opening recent sessions and projects.
|
|
\o \gui{\l{Using the Editor}{Edit}} mode for editing project and source files.
|
|
\if defined(qtquick)
|
|
\o \gui{\l{Developing Application UI}{Design}} mode for designing and developing
|
|
application user interfaces.
|
|
\else
|
|
\o \gui{\l{Using Qt Designer}{Design}} mode for designing and developing
|
|
application user interfaces.
|
|
\endif
|
|
\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.
|
|
\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
|
|
|
|
Use the sidebar to browse files, projects and bookmarks.
|
|
\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{File System} shows the content of the currently selected
|
|
directory.
|
|
\o \gui Bookmarks shows all bookmarks for the current session.
|
|
\o \gui{Open Documents} shows currently open files.
|
|
\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
|
|
|
|
|
|
\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 list all files in a project, 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 toggle the synchronization of your project tree with the file
|
|
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
|
|
|
|
|
|
\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 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
|
|
|
|
|
|
\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 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
|
|
|
|
\section2 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.6/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
|
|
|
|
\section2 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.
|
|
|
|
\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.
|
|
|
|
\if defined(qtquick)
|
|
|
|
\section1 Developing Application UI
|
|
|
|
To help you design the user interface of your application, two visual
|
|
editors are integrated into Qt Creator:
|
|
|
|
\list
|
|
\o \QD
|
|
\o \QMLD
|
|
\endlist
|
|
|
|
The integration includes project management and code completion.
|
|
|
|
\endif
|
|
|
|
\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 Ctrl+Alt+R.
|
|
\o To specify embedded device profiles, such as style, font, and screen
|
|
resolution, select \gui{Embedded Design}.
|
|
\endlist
|
|
|
|
For more information on \QD, see
|
|
\l{http://doc.qt.nokia.com/4.7-snapshot/designer-manual.html}{Qt Designer Manual}.
|
|
|
|
\if defined(qtquick)
|
|
|
|
\section1 Using Qt Quick Designer
|
|
|
|
You can edit .qml files in the visual \QMLD editor or in the
|
|
code editor.
|
|
|
|
In \gui Projects, double-click a .qml file to open it in the code
|
|
editor. Then select the \gui {Design} mode to edit the file in the
|
|
visual editor.
|
|
|
|
\note The visual \QMLD editor is provided as an experimental plugin that you must
|
|
enable to be able to edit QML files in the \gui Design mode. Enabling the
|
|
visual editor can negatively affect the overall stability of Qt Creator.
|
|
|
|
To enable or disable the \QMLD visual editor, select
|
|
\gui {Help > About Plugins... > Qt Quick > QmlDesigner}. You must restart Qt Creator
|
|
to enable or disable the visual editor.
|
|
|
|
\image qmldesigner-visual-editor.png "Visual editor"
|
|
|
|
Use the visual editor panes to manage your project:
|
|
|
|
\list
|
|
|
|
\o \gui {Navigator} pane displays the items in the scene. You can
|
|
show and hide items to focus on specific parts of the application.
|
|
|
|
\o \gui {Library} pane displays lists of predefined \gui {Items} and
|
|
imported \gui {Resources} that you can use to design applications. The
|
|
images and other files that you copy to the project folder appear in the
|
|
\gui {Resources} pane.
|
|
|
|
\o \gui {Properties} pane displays the properties of the selected component.
|
|
You can also change the properties in the code editor.
|
|
|
|
\o \gui {State} pane displays the different states of the component. To add
|
|
states, click the empty slot. Then modify the new state in the editor.
|
|
In the code editor, you can see the changes recorded as changes to
|
|
the base state.
|
|
|
|
\endlist
|
|
|
|
\endif
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-qml-application.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:
|
|
\list
|
|
\o To browse forward or backward through your location history, click
|
|
\inlineimage qtcreator-back.png
|
|
and \inlineimage qtcreator-forward.png
|
|
.
|
|
\o To go to any open file, select it from the \gui{Open files}
|
|
drop-down menu.
|
|
\o To jump to any symbol used in the current file, select it from the
|
|
\gui Symbols drop-down menu.
|
|
\endlist
|
|
|
|
When you create or edit forms in a \c{.ui} file, the toolbar contains
|
|
Qt Designer specific tools.
|
|
|
|
|
|
\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.
|
|
\if defined(qtquick)
|
|
The code completion differs somewhat depending on whether you write Qt code or QML code.
|
|
\endif
|
|
|
|
\if defined(qtquick)
|
|
|
|
\section2 Completing Qt Code
|
|
|
|
\endif
|
|
|
|
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
|
|
|
|
\if defined(qtquick)
|
|
|
|
\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"
|
|
|
|
\endif
|
|
|
|
\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}.
|
|
|
|
|
|
\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-project-managing.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}.
|
|
|
|
You can perform the following configuration actions:
|
|
\list
|
|
\o Set the font preferences and apply syntax highlighting in
|
|
\gui{Font & Colors}.
|
|
\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. 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 Indenting Code
|
|
|
|
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.
|
|
|
|
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.6/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 creator-editor-locator.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
|
|
|
|
\if defined(qtquick)
|
|
|
|
The functions used to rename symbols depends on whether you are
|
|
writing C++ or QML code. For QML, you can only rename IDs.
|
|
|
|
\endif
|
|
|
|
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.
|
|
|
|
\if defined(qtquick)
|
|
|
|
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
|
|
|
|
\endif
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-editor-external.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 recommended way to build a project is to use a \l{Using Version Control Systems} {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 \l{Building for Multiple Targets} {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.2/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
|
|
\l{Managing Sessions}{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.
|
|
\list
|
|
\o To use \bold{qmake} to build applications, open a \c .pro file. For more
|
|
information, see \l{Setting Up a qmake Project}.
|
|
\o To use \bold{CMake} to build applications you need to have CMake version
|
|
2.8.0 or later installed. For more information, see
|
|
\l{Setting Up a CMake Project}.
|
|
\o To use \bold{other build systems} to build applications, specify which files belong to
|
|
your project and which include directories or defines you want to pass
|
|
to your compiler. For more information, see
|
|
\l{Setting Up a Generic Project}.
|
|
\endlist
|
|
|
|
Qt Creator provides support for \l{Building and Running Applications}{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:
|
|
|
|
\list
|
|
|
|
\o \l{Setting Up Development Environment for Maemo}.
|
|
|
|
\o \l{Setting Up Development Environment for Symbian}.
|
|
|
|
\endlist
|
|
|
|
\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}.
|
|
|
|
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 External Libraries
|
|
|
|
Through external libraries Qt Creator can support code completion and
|
|
syntax highlighting for external libraries as if they were a part of the
|
|
current project or the Qt library.
|
|
|
|
The procedure of adding a library to a project depends on the type of
|
|
project, which influences the build system used.
|
|
|
|
\list
|
|
\o For information on adding external libraries to qmake projects, see
|
|
\l{Adding External Libraries to a qmake Project}.
|
|
\o For information on adding external libraries to CMake projects, see
|
|
\l{Adding External Libraries to a CMake Project}.
|
|
\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.
|
|
\if defined(qtquick)
|
|
and Qt Quick applications
|
|
\endif
|
|
You can also use
|
|
wizards to add individual files to your projects. For example, you can create
|
|
the following types of files:
|
|
|
|
\list
|
|
|
|
\o Qt resource files, which allow you to store binary files in the
|
|
application executable
|
|
|
|
\if defined(qtquick)
|
|
|
|
\o \QD forms and Qt QML files, which specify parts of application user
|
|
interfaces
|
|
|
|
\endif
|
|
|
|
\o C++ class, source, or header files
|
|
|
|
\endlist
|
|
|
|
The wizards prompt you to enter the settings needed
|
|
for that particular type of project and create the necessary files for you.
|
|
|
|
\image qtcreator-new-project.png
|
|
|
|
\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 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 New Project 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 use the wizard templates in the \c {share/qtcreator/templates/wizards}
|
|
folder to create your own project and class wizards. Qt Creator looks in the
|
|
folder and adds all wizards defined in wizard.xml files to the \gui New dialog
|
|
that opens when you select \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
|
|
projcet.
|
|
|
|
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"
|
|
|
|
\section2 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 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" />
|
|
|
|
\endcode
|
|
|
|
\list
|
|
|
|
\o \c source specifies the file to copy to the project. The files must be
|
|
located in the wizard folder.
|
|
|
|
\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.
|
|
|
|
\o \c openeditor indicates that the file is to be opened in an editor after
|
|
the wizard has finished.
|
|
|
|
\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
|
|
|
|
\section2 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%} 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}. Here, the filename would
|
|
become myclass.h.
|
|
|
|
\endlist
|
|
|
|
\o The following code creates a page that allows users to select the class
|
|
name, base class, and header and source files for the class:
|
|
|
|
\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
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-project-creating.html
|
|
\page creator-project-qmake.html
|
|
\nextpage creator-project-cmake.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.2/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 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 \gui{Version Name} field.
|
|
\o Enter the qmake binary path in the \gui{qmake Location}.
|
|
\o Enter the MinGW installation path in the \gui{MinGW Directory}.
|
|
|
|
\image qtcreator-qt4-qtversions-win-mingw.png
|
|
\endlist
|
|
|
|
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
|
|
\endlist
|
|
|
|
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 \bold{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
|
|
|
|
\section1 Adding External Libraries to a qmake Project
|
|
|
|
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.
|
|
|
|
To add an external library:
|
|
\list 1
|
|
\o Open your project file (.pro) using the \gui Projects pane.
|
|
\o Follow the instructions at \l{http://doc.qt.nokia.com/4.7-snapshot/qmake-project-files.html#declaring-other-libraries}
|
|
{Declaring other Libraries}.
|
|
\endlist
|
|
|
|
Syntax completion and highlighting work once your project successfully
|
|
builds and links against the external library.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-project-managing-sessions.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 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 Multiple Targets
|
|
|
|
Different build configurations allow you to quickly switch between
|
|
different build settings. By default, Qt Creator creates \bold debug
|
|
and \bold release build configurations.
|
|
|
|
\section1 Building for Desktop
|
|
|
|
\list 1
|
|
|
|
\o Select \gui Desktop as the target.
|
|
|
|
\o Click the \gui Run button.
|
|
|
|
\endlist
|
|
|
|
\section1 Building for 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 Maemo
|
|
|
|
\list 1
|
|
|
|
\o Build and run the application for \l{Building for Qt Simulator}{Qt Simulator}.
|
|
|
|
\o Build and run the application for \l{Using the Maemo Emulator}{Maemo Emulator}.
|
|
|
|
\o Alternatively, you can build and run the application for a device:
|
|
|
|
\list 1
|
|
|
|
\o Set up the MADDE development environment and specify a connection
|
|
to the device. For more information, see
|
|
\l{Setting Up Development Environment for Maemo}.
|
|
|
|
\o Connect the device to the development PC.
|
|
|
|
\o Click the \gui Run button.
|
|
|
|
\endlist
|
|
|
|
\endlist
|
|
|
|
Qt Creator uses the compiler specified in the MADDE toolchain to
|
|
build the application.
|
|
|
|
Qt Creator generates an installation package, installs in on the device,
|
|
and executes it. The application views are displayed on the Nokia N900.
|
|
Command-line
|
|
output is visible in the Qt Creator \gui {Application Output} view.
|
|
|
|
Debugging also works transparently.
|
|
|
|
\section2 Creating Installation Packages
|
|
|
|
When you build the application for the \gui{Maemo} target, Qt
|
|
Creator automatically generates a debian installation package
|
|
in the project folder. You can deliver the installation package to
|
|
users for installation on Maemo devices.
|
|
|
|
You can add other files to the installation package in the
|
|
\gui {Create package} step in the build configuration. Add files
|
|
to the \gui {Package contents} field. In \gui {Local File Path},
|
|
specify the location of the file on the development PC. In
|
|
\gui {Remote File Path}, specify the folder to install the file on
|
|
the device.
|
|
|
|
\image qtcreator-maemo-deb-package.png "Create installation package"
|
|
|
|
|
|
\section1 Building for Symbian
|
|
|
|
\list 1
|
|
|
|
\o Build and run the application for \l{Building for 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.
|
|
|
|
\section3 Creating 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.
|
|
|
|
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 your build configuration.
|
|
|
|
\image qtcreator-qt4-symbian-signing.png
|
|
|
|
\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-snapshot/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-snapshot/qmake-platform-notes.html#capabilities}{Capabilities}.
|
|
|
|
\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, who 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-snapshot/qmake-platform-notes.html#unique-identifiers}{Unique Identifiers}.
|
|
|
|
\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
|
|
|
|
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"
|
|
|
|
\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. Activate custom steps by
|
|
checking 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.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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}.
|
|
|
|
\if defined(qtquick)
|
|
The settings to specify depend on the type of the project: qmake project
|
|
or Qt Quick project.
|
|
\endif
|
|
|
|
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"
|
|
|
|
\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"
|
|
|
|
\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"
|
|
|
|
\if defined(qtquick)
|
|
|
|
\section1 Specifying Run Settings for Qt Quick Projects
|
|
|
|
Select run settings in the \gui {Run configuration} field. The settings
|
|
are specified automatically and, usually, you do not need to change them:
|
|
|
|
\list
|
|
|
|
\o \gui {QML Viewer} is the path to the \QQV executable.
|
|
|
|
\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 {Debugging address} is the IP address to access \QQV.
|
|
|
|
\o \gui {Debugging 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"
|
|
|
|
\endif
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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-visual-editor.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
|
|
\if defined(qtquick)
|
|
and the integrated design tools, \QD and \QMLD,
|
|
\endif
|
|
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}
|
|
\if defined(qtquick)
|
|
\o \l{Creating a Qt Quick Application}
|
|
\endif
|
|
\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 Application 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-snapshot/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.
|
|
|
|
\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
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\if defined(qtquick)
|
|
\contentspage index.html
|
|
\previouspage creator-mobile-example.html
|
|
\page creator-qml-application.html
|
|
\nextpage creator-editor-using.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-snapshot/declarativeui.html}
|
|
{QML declarative language}.
|
|
|
|
\note The Qt Quick specific features and the QDeclarative help are based on a
|
|
preview version of the QtDeclarative package. Update Qt Creator when Qt 4.7 is
|
|
released.
|
|
|
|
This tutorial describes how to use Qt Creator to create a small animated
|
|
Qt Quick application, Hello World.
|
|
|
|
\image qmldesigner-helloworld.png "Hello World"
|
|
|
|
\section1 Creating the Hello World 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 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 {Hello World}.
|
|
|
|
\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
|
|
|
|
\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 some example
|
|
code that specifies the screen size (200x200) and a label that contains
|
|
the text \bold {Hello World}.
|
|
|
|
\section1 Designing the User Interface
|
|
|
|
\list 1
|
|
|
|
\o In the \gui{Edit} mode, double-click the HelloWorld.qml file in
|
|
the \gui{Projects} pane to open it in the code editor.
|
|
|
|
\o To set the screen size to that of some Symbian devices in portrait
|
|
mode, for example, change the \c width to \bold 240 and \c height to \bold 320.
|
|
|
|
\image qmldesigner-helloworld-screen-size.png "Setting the screen size"
|
|
|
|
\o Click \gui{Design} to design the UI in the visual editor.
|
|
|
|
\note The visual \QMLD editor is provided as an experimental plugin that you must
|
|
enable to be able to edit QML files in the \gui Design mode. Enabling the
|
|
visual editor can negatively affect the overall stability of Qt Creator.
|
|
|
|
\o Restart Qt Creator to enable the visual editor.
|
|
|
|
\o Drag and drop a \gui {Rectangle} from the \gui {Library} pane to the
|
|
scene.
|
|
|
|
\image qmldesigner-helloworld-widget-add.png "Add component to Hello World"
|
|
|
|
\o Edit the \gui {Properties} of the component to turn it into a red ball:
|
|
|
|
\list a
|
|
|
|
\o In the \gui {Colors} section, click the color picker to select a red
|
|
color.
|
|
|
|
\o In the \gui {Radius} field, use the slider to set the radius value
|
|
to \bold 50.
|
|
|
|
\image qmldesigner-helloworld-widget-edit.png "Edit the component"
|
|
|
|
\endlist
|
|
|
|
\o To create a blue ball, press \key {Ctrl+C} and \key {Ctrl+V} to copy
|
|
and paste the red one, and then change its color to blue.
|
|
|
|
\image qmldesigner-helloworld-base-state.png "Hello World first view"
|
|
|
|
The first view of your application is now ready.
|
|
|
|
\note You can use graphical design tools to create nice images and
|
|
copy them to the projects folder to display them in the \gui {Library}
|
|
pane in \gui {Resources}.
|
|
|
|
\o In the \gui State pane, click the plus sign to add another view, or \e state
|
|
to the application.
|
|
|
|
\o Modify the state by dragging and dropping the widgets to switch their
|
|
places.
|
|
|
|
\image qmldesigner-helloworld-state1.png "Hello World second view"
|
|
|
|
\endlist
|
|
|
|
\section1 Animating the Scene
|
|
|
|
Animate the scene so that the widgets appear to switch places
|
|
on the screen.
|
|
|
|
\list 1
|
|
|
|
\o Click \gui {Edit} to open HelloWorld.qml in the code editor.
|
|
|
|
\o Add the following code to create a transition:
|
|
|
|
\code
|
|
transitions: [
|
|
Transition {
|
|
NumberAnimation { properties: "x, y"; duration: 500 }
|
|
}
|
|
\endcode
|
|
|
|
\note The code editor completes the code for you as you type.
|
|
|
|
\o Click the \inlineimage qtcreator-run.png
|
|
button to check that the application can be built and run.
|
|
|
|
\endlist
|
|
|
|
\section1 Adding Interaction
|
|
|
|
Add interaction to the scene to allow users to click on the screen to start
|
|
the animation.
|
|
|
|
\list 1
|
|
|
|
\o Click \gui{Design} to open HelloWorld.qml in the visual editor.
|
|
|
|
\o Drag and drop a \gui {Mouse Area} from the \gui {Library} to the scene.
|
|
|
|
\o In the \gui {Properties} pane, \gui {Geometry} tab, click the
|
|
\inlineimage qmldesigner-anchor-fill-screen.png
|
|
button to make the mouse region cover the whole screen.
|
|
|
|
\o In the code editor, use data binding to add a \c when statement to
|
|
the states sections, as illustrated by the following code:
|
|
|
|
\code
|
|
|
|
states: [
|
|
State {
|
|
name: "State1"
|
|
when: mousearea1.pressed
|
|
\endcode
|
|
|
|
\endlist
|
|
|
|
\section1 Building and Running the Application
|
|
|
|
\list 1
|
|
|
|
\o Press \key {Ctrl+R} to build and run the application.
|
|
|
|
\o Click the screen and keep the mouse button pressed down to run the
|
|
animation.
|
|
|
|
\endlist
|
|
|
|
\note In the \gui {QML Viewer}, select \gui {Skin} and select a mobile device
|
|
type to view the application as on a mobile device.
|
|
|
|
\endif
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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
|
|
|
|
\note This tutorial assumes that you have experience in writing basic Qt
|
|
applications, using \QD to design user interfaces and using the Qt
|
|
Resource System.
|
|
|
|
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-snapshot/uitools-textfinder.html}{Text Finder}
|
|
example.
|
|
|
|
\image qtcreator-textfinder-screenshot.png
|
|
|
|
\section1 Setting Up Your Environment
|
|
|
|
Qt Creator automatically detects whether the location of Qt is in your \c PATH variable.
|
|
If you have installed several Qt versions, follow the
|
|
instructions in \l{Selecting the Qt version} to set the Qt path.
|
|
|
|
\section1 Creating the Text Finder 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 Application 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 \gui{Select Required Qt Versions} dialog opens.
|
|
|
|
\image qtcreator-new-project-qt-versions.png "Select Required Qt Versions dialog"
|
|
|
|
\o Click \gui{Next} to use the Qt version set in the path in your project.
|
|
|
|
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} (\l{http://doc.qt.nokia.com/4.7-snapshot/qlabel.html}{QLabel})
|
|
\o \gui{Line Edit} (\l{http://doc.qt.nokia.com/4.7-snapshot/qlineedit.html}{QLineEdit})
|
|
\o \gui{Push Button} (\l{http://doc.qt.nokia.com/4.7-snapshot/qpushbutton.html}{QPushButton})
|
|
|
|
\endlist
|
|
|
|
\image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI"
|
|
|
|
\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
|
|
(\l{http://doc.qt.nokia.com/4.7-snapshot/qhboxlayout.html}{QHBoxLayout}).
|
|
|
|
\image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout"
|
|
|
|
\o Drag and drop a \gui{Text Edit} widget (\l{http://doc.qt.nokia.com/4.7-snapshot/qtextedit.html}{QTextEdit})
|
|
to the form.
|
|
|
|
\o Select the screen area and click \gui{Lay out Vertically} (or press \gui{Ctr+V})
|
|
to apply a vertical layout (\l{http://doc.qt.nokia.com/4.7-snapshot/qvboxlayout.html}{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-snapshot/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
|
|
\l{http://doc.qt.nokia.com/4.7-snapshot/qtextedit.html}{QTextEdit}.
|
|
|
|
\list 1
|
|
|
|
\o In the \gui{Projects} 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} function, 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} view, double-click the textfinder.cpp file
|
|
to open it for editing.
|
|
|
|
\o Add code to load a text file using
|
|
\l{http://doc.qt.nokia.com/4.7-snapshot/qfile.html}{QFile}, read it with
|
|
\l{http://doc.qt.nokia.com/4.7-snapshot/qtextstream.html}{QTextStream}, and
|
|
then display it on \c{textEdit} with
|
|
\l{http://doc.qt.nokia.com/4.7-snapshot/qtextedit.html#plainText-prop}{setPlainText()}.
|
|
This is illustrated by the following code snippet:
|
|
|
|
\snippet examples/textfinder/textfinder.cpp 0
|
|
|
|
\o To use \l{http://doc.qt.nokia.com/4.7-snapshot/qfile.html}{QFile} and
|
|
\l{http://doc.qt.nokia.com/4.7-snapshot/qtextstream.html}{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-snapshot/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 your program.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-qml-inspector.html
|
|
\page creator-version-control.html
|
|
\nextpage adding-plugins.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.
|
|
|
|
\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 sub-menu for each supported version
|
|
control system.
|
|
|
|
The \gui{Version Control} output pane displays the commands
|
|
that are executed, a timestamp, and the relevant output.
|
|
Select \gui {Window > Output Panes > Version Control} to open
|
|
the pane.
|
|
|
|
|
|
\image qtcreator-vcs-pane.png
|
|
|
|
|
|
\section2 Adding Files
|
|
|
|
When you create a new file or a new project, the wizard displays a page
|
|
asking whether the files should be added to a version control system.
|
|
This happens when the parent directory or the project is already
|
|
under version control and the system supports the concept of adding files,
|
|
for example, Perforce and Subversion. Alternatively, you can
|
|
add files later by using the version control tool menus.
|
|
|
|
With Git, there is no concept of adding files. Instead, all modified
|
|
files must be staged for a commit.
|
|
|
|
|
|
\section2 Viewing Diff Output
|
|
|
|
All version control systems provide menu options to \e{diff} the current
|
|
file or project: to compare it with the latest version stored in the
|
|
repository and to display the differences. In Qt Creator, a diff is
|
|
displayed in a read-only editor. If the file is accessible, you can
|
|
double-click on a selected diff chunk and Qt Creator opens an editor
|
|
displaying the file, scrolled to the line in question.
|
|
|
|
\image qtcreator-vcs-diff.png
|
|
|
|
|
|
\section2 Viewing Versioning History and Change Details
|
|
|
|
Display the versioning history of a file by selecting \gui{Log}
|
|
(for Git and Mercurial) or \gui{Filelog} (for CVS, Perforce, and
|
|
Subversion). Typically, the log output contains the date, the commit
|
|
message, and a change or revision identifier. Click on the identifier to
|
|
display a description of the change including the diff.
|
|
Right-clicking on an identifier brings up a context menu that lets you
|
|
show annotation views of previous versions (see \l{Annotating Files}).
|
|
|
|
\image qtcreator-vcs-log.png
|
|
|
|
|
|
\section2 Annotating Files
|
|
|
|
Annotation views are obtained by selecting \gui{Annotate} or \gui{Blame}.
|
|
Selecting \gui{Annotate} or \gui{Blame} displays the lines of the file
|
|
prepended by the change identifier they originate from. Clicking on the
|
|
change identifier shows a detailed description of the change.
|
|
|
|
To show the annotation of a previous version, right-click on the
|
|
version identifier at the beginning of a line and choose one of the
|
|
revisions shown at the bottom of the context menu. This allows you to
|
|
navigate through the history of the file and obtain previous versions of
|
|
it. It also works for Git and Mercurial using SHA's.
|
|
|
|
The same context menu is available when right-clicking on a version
|
|
identifier in the file log view of a single file.
|
|
|
|
|
|
\section2 Committing Changes
|
|
|
|
Once you have finished making changes, submit them to the version control
|
|
system by choosing \gui{Commit} or \gui{Submit}. Qt Creator displays a
|
|
commit page containing a text editor where you can enter your commit
|
|
message and a checkable list of modified files to be included.
|
|
|
|
\image qtcreator-vcs-commit.png
|
|
|
|
When you have finished filling out the commit page information, click on
|
|
\gui{Commit} to start committing.
|
|
|
|
The \gui{Diff Selected Files} button brings up a diff view of the
|
|
files selected in the file list. Since the commit page is just another
|
|
editor, you can go back to it by closing the diff view. You can also check
|
|
a diff view from the editor combo box showing the \gui{Opened files}.
|
|
|
|
|
|
\section2 Reverting Changes
|
|
|
|
To discard local changes to a file or project, use the \gui Revert
|
|
function or the \gui {Undo Changes/Undo Repository Changes} function
|
|
(for Git). The changes discarded depend on the version control system.
|
|
|
|
For example, in Perforce, select \gui{Revert File/Revert Project}
|
|
to discard changes made to open files, reverting them to the
|
|
revisions last synchronized from the repository. Select
|
|
\gui{Revert Unchanged} to revert files if their contents or file
|
|
type have not changed after they were opened for editing.
|
|
|
|
\section2 Using Additional Git Functions
|
|
|
|
The \gui Git sub-menu contains the following additional items:
|
|
|
|
\table
|
|
|
|
\row
|
|
\i \gui {Apply Patch/Apply Patch...}
|
|
\i Apply changes to a file or project from a diff file. You can
|
|
either apply a patch file that is open in Qt Creator or select
|
|
the patch file to apply from the file system.
|
|
\row
|
|
\i \gui{Stash Snapshot...}
|
|
\i Save a snapshot of your current
|
|
work under a name for later reference. For example, if you
|
|
want to try out something and find out later that it does not work,
|
|
you can discard it and return to the state of the snapshot.
|
|
\row
|
|
\i \gui{Stash}
|
|
\i Stash local changes prior to executing a \gui{Pull}.
|
|
\row
|
|
\i \gui{Stash Pop}
|
|
\i Remove a single stashed state from the stash list and apply it on
|
|
top of the current working tree state.
|
|
\row
|
|
\i \gui{Pull}
|
|
\i Pull changes from the remote repository. If there are locally
|
|
modified files, you are prompted to stash those changes.
|
|
The \gui Git options page contains an option to do
|
|
a rebase operation while pulling.
|
|
|
|
\row
|
|
\i \gui{Clean Repository.../Clean Project...}
|
|
\i Collect all files that are not under version control
|
|
with the exception of patches and project files
|
|
and show them as a checkable list in a dialog
|
|
prompting for deletion. This lets you completely clean a build.
|
|
|
|
\row
|
|
\i \gui{Branches...}
|
|
\i Displays the branch dialog showing the local branches at the
|
|
top and remote branches at the bottom. To switch to the local
|
|
branch, double-click on it. Double-clicking on a remote
|
|
branch first creates a local branch with the same name that
|
|
tracks the remote branch, and then switches to it.
|
|
|
|
\image qtcreator-vcs-gitbranch.png
|
|
|
|
|
|
\row
|
|
\i \gui{Stashes...}
|
|
\i Displays a dialog showing the stashes created by
|
|
\gui{Stash Snapshot...} with options to restore,
|
|
display or delete them.
|
|
\row
|
|
\i \gui {Stage File for Commit}
|
|
\i Mark new or modified files for committing to the repository.
|
|
To undo this function, select \gui {Unstage File from Commit}.
|
|
\row
|
|
\i \gui{Show Commit...}
|
|
\i Select a commit to view. Enter the SHA of the commit
|
|
in the \gui Change field.
|
|
\endtable
|
|
|
|
\section2 Using Additional Mercurial Functions
|
|
|
|
The \gui Mercurial sub-menu contains the following additional items:
|
|
|
|
\table
|
|
\row
|
|
\i \gui{Import}
|
|
\i Apply changes from a patch file.
|
|
\row
|
|
\i \gui{Incoming}
|
|
\i Monitor the status of a remote repository by listing
|
|
the changes that will be pulled.
|
|
\row
|
|
\i \gui{Outgoing}
|
|
\i Monitor the status of a remote repository by listing
|
|
the changes that will be pushed.
|
|
\row
|
|
\i \gui{Pull}
|
|
\i Pull changes from the remote repository.
|
|
\row
|
|
\i \gui{Update}
|
|
\i Look at an earlier version of the code.
|
|
\endtable
|
|
|
|
\section2 Using Additional Perforce Functions
|
|
|
|
When you start Qt Creator, it looks for the executable specified
|
|
in the \gui{P4 command} field in \gui{Tools > Options... > Version
|
|
Control > Perforce}. If you do not use Perforce and want to turn
|
|
off the check, clear this field.
|
|
|
|
The \gui Perforce sub-menu contains the following additional items:
|
|
|
|
\table
|
|
\row
|
|
\i \gui{Describe...}
|
|
\i View information about changelists and the files in them.
|
|
\row
|
|
\i \gui{Edit File}
|
|
\i Open a file for editing.
|
|
\row
|
|
\i \gui{Opened}
|
|
\i List files that are open for editing.
|
|
\row
|
|
\i \gui{Pending Changes...}
|
|
\i Group files for commit.
|
|
\row
|
|
\i \gui{Update All/Update Current Project}
|
|
\i Fetch the current version of the current project or all
|
|
projects from the repository.
|
|
|
|
\endtable
|
|
|
|
|
|
\section2 Using Additional Subversion Functions
|
|
|
|
The \gui Subversion sub-menu contains the following additional items:
|
|
|
|
\table
|
|
\row
|
|
\i \gui{Describe...}
|
|
\i Display commit log messages for a revision.
|
|
\row
|
|
\i \gui{Update Project/Update Repository}
|
|
\i Update your working copy.
|
|
\endtable
|
|
|
|
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-editor-refactoring.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 \gui 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
|
|
\l{http://doc.qt.nokia.com/4.7-snapshot/qdatastream.html}{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-building-running.html
|
|
|
|
\title Managing Sessions
|
|
|
|
When you exit Qt Creator, a snapshot of your current workspace is stored
|
|
as a session.
|
|
A session is a collection of:
|
|
|
|
\list
|
|
\o Open projects with their dependencies
|
|
\o Open editors
|
|
\o Breakpoints and watches
|
|
\o Bookmarks
|
|
\endlist
|
|
|
|
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-maemo-emulator.html
|
|
\page creator-debugging.html
|
|
\nextpage creator-debugging-cpp.html
|
|
|
|
\title Debugging
|
|
|
|
You can use the Qt Creator \gui Debug mode to inspect the state of your
|
|
Qt
|
|
\if defined(qtquick)
|
|
and Qt Quick
|
|
\endif
|
|
projects while debugging.
|
|
|
|
Qt Creator does not include a debugger. It provides a debugger plugin that acts
|
|
as an interface between the Qt Creator core and external native debuggers
|
|
such as the GNU Symbolic Debugger (gdb), the Microsoft Console Debugger (CDB),
|
|
and an internal Java Script debugger. You can use the native debuggers to
|
|
debug the C++ language.
|
|
|
|
\image qtcreator-debugger-views.png "Native debugger views"
|
|
|
|
\if defined(qtquick)
|
|
|
|
Qt Creator includes a QML inspector plugin that you can use to debug QML.
|
|
|
|
\image qmldesigner-inspector.png "QML inspector views"
|
|
|
|
When you start debugging, the appropriate tool is automatically selected depending
|
|
on the type of the project. If you only develop one kind of projects, you can turn
|
|
off this automation in \gui {Tools > Options... > Debugger > General}. Deselect the
|
|
\gui {Change debugger language automatically} check box.
|
|
|
|
The choice of language also determines the contents of the \gui Debug menu.
|
|
The \gui {Start Debugging > Start Debugging} command starts debugging by using the
|
|
tool appropriate for the project type. The availability of the other commands depends
|
|
on whether \gui C++ or \gui QML is selected in \gui {Debug > Language}.
|
|
|
|
You can create Qt Quick projects that contain C++ plugins or Qt projects that contain
|
|
QML content. While debugging such projects, you can switch between the native
|
|
debuggers and the QML inspector during debugging.
|
|
|
|
To switch between debugged languages, select \gui {Debug > Language > C++} or
|
|
\gui QML. You can also press \key {Ctrl+L, 1} to switch to the native debugger and
|
|
\key {Ctrl+L, 2} to switch to the QML inspector.
|
|
|
|
\endif
|
|
|
|
*/
|
|
|
|
/*!
|
|
\if defined(qtquick)
|
|
\contentspage index.html
|
|
\previouspage creator-debugging-helpers.html
|
|
\page creator-debugging-qml.html
|
|
\nextpage creator-qml-inspector.html
|
|
|
|
\title Debugging Qt Quick Applications
|
|
|
|
In the \gui Debug mode you can use the QML inspector plugin to:
|
|
|
|
\list
|
|
|
|
\o View the status of the application when it is executed.
|
|
|
|
\o View debug output.
|
|
|
|
\o Write JavaScript expressions and evaluate them.
|
|
|
|
\o Modify the values of properties.
|
|
|
|
\o Watch the values of expressions.
|
|
|
|
|
|
\note You can press \key {Ctr+Alt+R} or select \gui {Tools > Qt Quick > Preview}
|
|
to view QML files that do not belong to projects in \QQV. However,
|
|
you can only debug QML files that belong to open projects, because the QML
|
|
inspector plugin needs information about the project.
|
|
|
|
\endlist
|
|
|
|
\section1 Modes of Operation
|
|
|
|
When a Qt Quick project is active and you select \gui {Debug > Start Debugging >
|
|
Start Debugging} the application is started in \QQV and inspected by
|
|
the QML inspector.
|
|
|
|
If the Qt Quick project includes C++ plugins, select
|
|
\gui {Debug > Start Debugging > Start Debugging C++ and QML Simultaneously}.
|
|
\QQV is started, the native debugger is attached to it, and
|
|
the application is inspected by the QML inspector.
|
|
|
|
\note This command is available only if \gui QML is selected in
|
|
\gui {Debug > Language (QML)}.
|
|
|
|
To debug a Qt project that contains QML content, select
|
|
\gui {Debug > Start Debugging > Start Debugging C++ and QML Simultaneously}.
|
|
The application is started under the control of the native debugger, attached
|
|
to \QQV, and inspected by the QML inspector.
|
|
|
|
You must use the native debugger to set breakpoints to C++ code and to examine
|
|
the state of the interrupted Qt application. When a C++ program is interrupted,
|
|
for example when a breakpoint is hit, you cannot use the QML inspector.
|
|
\endif
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\if defined(qtquick)
|
|
\contentspage index.html
|
|
\previouspage creator-debugging-qml.html
|
|
\page creator-qml-inspector.html
|
|
\nextpage creator-version-control.html
|
|
|
|
\title Using the QML Inspector
|
|
|
|
In \gui Debug mode, you can use several views to interact with the
|
|
application you are debugging. Frequently used views are shown by
|
|
default and rarely used ones are hidden. To change the default settings,
|
|
select \gui Debug > \gui Views, and then select views to display
|
|
or hide. You can also lock views. The position of views is saved for future
|
|
sessions.
|
|
|
|
\image qmldesigner-inspector.png "QML inspector views"
|
|
|
|
\section1 Starting the QML Inspector
|
|
|
|
To start an active application under the control of the QML inspector, select
|
|
\gui {Debug > Start Debugging > Start Debugging}, or press \key{F5}.
|
|
|
|
The application is run in \QQV. It behaves and performs as usual.
|
|
You can view the status of the application when it is executed and the debug
|
|
output in the \gui {Application Output} view.
|
|
|
|
\image qmldesigner-application-output.png "Application Output view"
|
|
|
|
\section1 Starting Simultaneous QML and C++ Debugging
|
|
|
|
To debug a Qt Quick project that includes C++ plugins, select
|
|
\gui {Debug > Start Debugging > Start Debugging C++ and QML Simultaneously}.
|
|
|
|
\note This command is available only if \gui QML is selected in
|
|
\gui {Debug > Language (QML)}.
|
|
|
|
\image qmldesigner-debugging-simultaneous.png "Start Simultaneous QML and C++ Debugging view"
|
|
|
|
Usually, the settings for \QQV are specified automatically and you do
|
|
not need to change them:
|
|
|
|
\list
|
|
|
|
\o \gui {Debugging address} is the IP address to access \QQV.
|
|
|
|
\o \gui {Debugging port} is the port to access \QQV. You can use any
|
|
free port in the registered port range.
|
|
|
|
\o \gui {Viewer path} is the path to \QQV executable.
|
|
|
|
\o \gui {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.
|
|
|
|
\endlist
|
|
|
|
\QQV is started, the native debugger is attached to it, and
|
|
the application is inspected by the QML inspector.
|
|
|
|
\section1 Viewing and Modifying Values of Properties
|
|
|
|
The \gui {Properties and Watchers} view lists the JavaScript expressions
|
|
in the project and their properties and values. The properties are grouped
|
|
by type, but you can also view them in one long list.
|
|
Right-click the list of properties to open a context-menu and then click
|
|
\gui {Group by Item Type} to change the way in which the properties are
|
|
sorted.
|
|
|
|
If an item does not have an ID, you cannot change the values of its
|
|
properties. The item type is enclosed in angle brackets and the value
|
|
is grayed.
|
|
|
|
Double-click an item to move to the place in code where it is declared.
|
|
|
|
You can change the values of properties and see the results in \QQV.
|
|
|
|
If the QML inspector cannot retrieve the value for an item or a property for
|
|
inspection, the item or property is grayed in the view. Right-click the item list
|
|
to open a context menu, and then click \gui {Show Uninspectable Items} to hide
|
|
or show the items that cannot be inspected.
|
|
|
|
\section1 Watching Expressions
|
|
|
|
In the \gui {Properties and Watchers} view, you can specify that an expression is
|
|
watched. Right-click a property and then click \gui {Watch Expression}.
|
|
The \gui Name and \gui Value of the expression are displayed at the bottom
|
|
of the view.
|
|
|
|
\image qmldesigner-inspector-watchers.png "Watched expressions"
|
|
|
|
You can add JavaScript expressions to object instances to evaluate them.
|
|
Right-click the list of items and select \gui {Add Watch Expression}. Enter
|
|
the expression to evaluate and click \gui OK.
|
|
|
|
\image qmldesigner-inspector-add-watch.png "Add Watch Expression dialog"
|
|
|
|
To stop watching a expression, right-click it and select \gui {Stop Watching}.
|
|
|
|
The QML inspector cannot show the values for some items, such as composite objects
|
|
or complicated item that you cannot change. These items cannot be watched.
|
|
To show them, right-click the properties list, and then select
|
|
\gui {Show Unwatchable Properties}.
|
|
|
|
\section1 Executing JavaScript
|
|
|
|
In the \gui {Script Console} view, you can write JavaScript expressions, see
|
|
how they are executed, and evaluate them during runtime.
|
|
|
|
You can also test the C++ code without rebuilding the whole application.
|
|
|
|
\section1 Viewing Connections to \QQV
|
|
|
|
The \gui Output view displays the status of the connection between the QML
|
|
inspector and \QQV.
|
|
|
|
You specify the connection in the \gui {Run Settings} in the \gui Projects mode.
|
|
For more information, see \l{Specifying Run Settings for Qt Quick Projects}.
|
|
|
|
If the connection does not work, check the values of the \gui {Debugging address}
|
|
and \gui {Debugging port} fields. Check that the default port number is not reserved
|
|
by another application or another instance of \QQV that was not shut
|
|
down properly. You can specify any free port number in the registered port range
|
|
(1024-49151).
|
|
\endif
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-debugging.html
|
|
\page creator-debugging-cpp.html
|
|
\nextpage creator-debugging-example.html
|
|
|
|
\title Debugging Qt Applications
|
|
|
|
In the \gui Debug mode 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.
|
|
|
|
For an example of how to debug applications in the \gui Debug mode, see
|
|
\l{Debugging the Example Application}.
|
|
|
|
For more information about the functions available in the \gui Debug mode,
|
|
see \l{Interacting with the Debugger}.
|
|
|
|
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. If you want a special setup, such as using debugging tools for Windows,
|
|
see \l {Setting Up Debugger}.
|
|
|
|
\section1 Modes of Operation
|
|
|
|
The debugger plugin runs in different operating modes depending on where and
|
|
how the process is started and run. Some of the modes are only available for
|
|
a particular operating system or platform.
|
|
|
|
You can launch the debugger in the following modes:
|
|
|
|
\list
|
|
|
|
\o \bold Plain to debug locally started applications, such as a
|
|
Qt based GUI application.
|
|
|
|
\o \bold Terminal to debug locally started processes that need a
|
|
console, typically without a GUI.
|
|
|
|
\o \bold Attach to debug local processes started outside Qt Creator.
|
|
|
|
\o \bold Remote to debug a process running on a different machine.
|
|
|
|
\o \bold Core to debug crashed processes on Unix.
|
|
|
|
\o \bold Post-mortem to debug crashed processes on Windows.
|
|
|
|
\o \bold TRK to debug processes running on a Symbian device.
|
|
|
|
\endlist
|
|
|
|
When you click the \gui {Start Debugging} button, the debugger is launched
|
|
in the appropriate operating mode (plain, terminal, or TRK), based on the
|
|
build and run settings for the active project. Select \gui Debug menu options
|
|
to launch the debugger in the other modes.
|
|
|
|
\section2 Plain Mode
|
|
|
|
To launch the debugger in the plain mode, click the \gui {Start Debugging}
|
|
button for the active project, or choose
|
|
\gui {Debug > Start Debugging > Start and Debug External Application...}
|
|
and specify an executable.
|
|
|
|
\section2 Terminal Mode
|
|
|
|
To launch the debugger in the terminal mode, select \gui {Projects > Run Settings}
|
|
and select the \gui {Run in terminal} check box. Then click the
|
|
\gui {Start Debugging} button for the active project.
|
|
|
|
\section2 Attach Mode
|
|
|
|
To launch the debugger in the attach mode, select
|
|
\gui {Debug > Start Debugging > Attach to Running External Application...},
|
|
and then select a process by its name or process ID to attach to.
|
|
|
|
\section2 Remote Mode
|
|
|
|
The remote mode uses a \e{gdbserver} daemon that runs on the remote machine.
|
|
|
|
To launch the debugger in the remote mode, select
|
|
\gui {Debug > Start Debugging > Start and Attach to Remote Application...}.
|
|
|
|
\section2 Core Mode
|
|
|
|
The core mode is available only in Unix. It debugs crashed processes using
|
|
the \e {core} files (crash dumps) that are generated if the setting
|
|
is enabled in the shell.
|
|
|
|
To enable the dumping of core files, enter the following command in the
|
|
shell from which the application will be launched:
|
|
|
|
\code
|
|
ulimit -c unlimited
|
|
\endcode
|
|
|
|
To launch the debugger in the core mode, select
|
|
\gui{Debug > Start Debugging > Attach to Core...}.
|
|
|
|
\section2 Post-Mortem Mode
|
|
|
|
The post-mortem mode is available only on Windows, if you have installed
|
|
the debugging tools for Windows.
|
|
|
|
The Qt Creator installation program asks you whether you want to
|
|
register Qt Creator as a post-mortem debugger. To change the setting, select
|
|
\gui{Tools > Options... > Debugger > Common > Use Creator for post-mortem debugging}.
|
|
|
|
You can launch the debugger in the post-mortem mode if an application crashes
|
|
on Windows. Click the \gui {Debug in Qt Creator} button in the error message
|
|
that is displayed by the Windows operating system.
|
|
|
|
\section2 TRK Mode
|
|
|
|
The TRK mode is a special mode available only for Symbian. It
|
|
debugs processes running on a Symbian
|
|
device using the App TRK application that runs on the device.
|
|
|
|
To launch the debugger in the TRK mode, open the project, select Symbian as the
|
|
target, and click the \gui {Start Debugging} button.
|
|
|
|
For more information on setting up Symbian projects, see
|
|
\l{Setting Up Development Environment for Symbian}.
|
|
|
|
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-debug-mode.html
|
|
\page creator-debugger-engines.html
|
|
\nextpage creator-debugging-helpers.html
|
|
|
|
\title Setting Up Debugger
|
|
|
|
Typically, the interaction between Qt Creator and the native debugger is set
|
|
up automatically and you do not need to do anything. However, you might have an
|
|
unsupported gdb version installed, your Linux environment might not have gdb
|
|
installed at all, or you might want to use the debugging tools for Windows.
|
|
|
|
\note To use the debugging tools for Windows, you must install them and add the
|
|
Symbol Server provided by Microsoft to the symbol search path of the debugger.
|
|
For more information, see \l{Setting the Symbol Server in Windows}.
|
|
|
|
This section explains the
|
|
options you have for debugging C++ code and provides installation notes for the
|
|
supported native debuggers.
|
|
|
|
\section1 Supported Native Debugger Versions
|
|
|
|
The debugger plugin supports different builds of the gdb debugger, both
|
|
with and without the ability to use Python scripting. The Python enabled
|
|
versions are preferred, but they are not available on Mac and on older
|
|
versions of Linux.
|
|
On Windows, Symbian, and Maemo, only the Python version is supported.
|
|
|
|
The non-Python versions use the compiled version of the debugging helpers,
|
|
that you must enable separately. For more information, see
|
|
\l{Debugging Helper Library with 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 Optional
|
|
\o Term, Plain, Attach (with Python, only), Remote
|
|
\row
|
|
\o Unix
|
|
\o gcc
|
|
\o gdb
|
|
\o Yes
|
|
\o Term, Plain, Attach, Remote
|
|
\row
|
|
\o Mac OS
|
|
\o gcc
|
|
\o gdb
|
|
\o No
|
|
\o Term, Plain, Attach
|
|
\row
|
|
\o Windows/MinGW
|
|
\o gcc
|
|
\o gdb
|
|
\o No
|
|
\o Term, Plain, Attach, Remote
|
|
\row
|
|
\o Windows/MSVC
|
|
\o Microsoft Visual C++ Compiler
|
|
\o Debugging Tools for Windows/CDB
|
|
\o Not applicable
|
|
\o Term, Plain, 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
|
|
|
|
\omit
|
|
|
|
\section2 Gdb Adapter Modes
|
|
|
|
[Advanced Topic]
|
|
|
|
The gdb native debugger used internally by the debugger plugin runs in
|
|
different adapter modes to cope with the variety
|
|
of supported platforms and environments. All gdb adapters inherit from
|
|
AbstractGdbAdapter:
|
|
|
|
\list
|
|
|
|
\o PlainGdbAdapter debugs locally started GUI processes.
|
|
It is physically split into parts that are relevant only when Python is
|
|
available, parts relevant only when Python is not available, and mixed code.
|
|
|
|
\o TermGdbAdapter debugs locally started processes that need a
|
|
console.
|
|
|
|
\o AttachGdbAdapter debugs local processes started outside Qt Creator.
|
|
|
|
\o CoreGdbAdapter debugs core files generated from crashes.
|
|
|
|
\o RemoteGdbAdapter interacts with the gdbserver running on Linux.
|
|
|
|
\o TrkGdbAdapter interacts with Symbian devices. The gdb protocol and
|
|
the gdb serial protocol are used between gdb and the adapter. The TRK
|
|
protocol is used between the adapter and AppTRK running on the device.
|
|
|
|
\endlist
|
|
|
|
\endomit
|
|
|
|
\section1 Installing Native Debuggers
|
|
|
|
There are various reasons why the debugger plugin may fail to automatically
|
|
pick up a suitable native debugger. The native debugger might be missing
|
|
(which is usually the case for the CDB debugger on Windows which always
|
|
needs to be installed manually by the user) or the installed version is not
|
|
supported.
|
|
Check the table below for the supported versions and other important
|
|
information about installing native debuggers.
|
|
|
|
\table
|
|
\header
|
|
\o Native Debugger
|
|
\o Notes
|
|
\row
|
|
\o Gdb
|
|
\o On Linux, install version 6.8, 7.0.1 (version 7.0 is not supported),
|
|
7.1, or later. On Mac OS X, install Apple gdb version 6.3.50-20050815
|
|
(build 1344) or later.
|
|
|
|
\row
|
|
\o Debugging tools for Windows
|
|
\o Using this engine requires you to install the
|
|
\e{Debugging tools for Windows}
|
|
\l{http://www.microsoft.com/whdc/devtools/debugging/installx86.Mspx}{32-bit}
|
|
or
|
|
\l{http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx}{64-bit}
|
|
package (Version 6.11.1.404 for the 32-bit or the 64-bit version of Qt Creator, respectively),
|
|
which is freely available for download from the
|
|
\l{http://msdn.microsoft.com/en-us/default.aspx}
|
|
{Microsoft Developer Network}.
|
|
|
|
\note Visual Studio does not include the Debugging tools needed,
|
|
and therefore, you must install them separately.
|
|
|
|
The pre-built \e{Qt SDK for Windows} makes use
|
|
of the library if it is present on the system. When manually building Qt
|
|
Creator using the Microsoft Visual C++ Compiler, the build process checks
|
|
for the required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}.
|
|
|
|
It is highly recommended that you add the Symbol Server provided by Microsoft to the symbol
|
|
search path of the debugger. The Symbol Server provides you
|
|
with debugging informaton for the operating system libraries for debugging
|
|
Windows applications. For more information, see
|
|
\l{Setting the Symbol Server in Windows}.
|
|
|
|
\row
|
|
\o Debugging tools for Mac OS X
|
|
\o The Qt binary distribution contains both debug and release
|
|
variants of the libraries. But you have to explicitly tell the
|
|
runtime linker that you want to use the debug libraries even if
|
|
your application is compiled as debug as release is the default
|
|
library.
|
|
|
|
If you use a qmake based project in Qt Creator, you can set a
|
|
flag in your run configuration, in \gui Projects mode. In the run
|
|
configuration, select \gui{Use debug version of frameworks}.
|
|
|
|
For more detailed information about debugging on the Mac, see:
|
|
\l http://developer.apple.com/mac/library/technotes/tn2004/tn2124.html
|
|
|
|
\note The Mac OS X Snow Leopard (10.6) has a bug, that can be worked
|
|
around as described in the link provided below:
|
|
\l http://bugreports.qt.nokia.com/browse/QTBUG-4962.
|
|
|
|
\endtable
|
|
|
|
\section1 Setting the Symbol Server in Windows
|
|
|
|
To obtain debugging information for the operating system libraries for
|
|
debugging Windows applications, add the Symbol Server provided
|
|
by Microsoft to the symbol search path of the debugger:
|
|
\list 1
|
|
\o Select \gui Tools > \gui{Options...} > \gui Debugger > \gui Cdb.
|
|
\o In the \gui {Symbol paths} field, open the \gui{Insert...} menu
|
|
and select \gui{Symbol Server...}.
|
|
\o Select a directory where you want to store the cached information
|
|
and click \gui OK.
|
|
|
|
Use a subfolder in a temporary directory, such as
|
|
\c {C:\temp\symbolcache}.
|
|
\endlist
|
|
|
|
\note Populating the cache might take a long time on a slow network
|
|
connection.
|
|
|
|
\note The first time you start debugging by using the
|
|
Debugging tools for Windows, Qt Creator prompts you to add the Symbol
|
|
Server.
|
|
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-debugging-example.html
|
|
\page creator-debug-mode.html
|
|
\nextpage creator-debugger-engines.html
|
|
|
|
\title Interacting with the Debugger
|
|
|
|
In \gui Debug mode, you can use several views to interact with the
|
|
program you are debugging. Frequently used views are shown by
|
|
default and rarely used ones are hidden. To change the default settings,
|
|
select \gui Debug > \gui Views, and then select views to display
|
|
or hide. You can also lock views. The position of views is saved for future
|
|
sessions.
|
|
|
|
\image qtcreator-debugger-views.png "Debug mode views"
|
|
|
|
|
|
\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.
|
|
|
|
Once the program starts running, it behaves and performs as usual.
|
|
You can interrupt a running program by selecting \gui{Debug} >
|
|
\gui {Interrupt}. The program is automatically interrupted as soon as a
|
|
breakpoint is hit.
|
|
|
|
Once the program stops, Qt Creator:
|
|
|
|
\list
|
|
\o Retrieves data representing the call stack at the program's current
|
|
position.
|
|
\o Retrieves the contents of local variables.
|
|
\o Examines \gui Watchers.
|
|
\o Updates the \gui Registers, \gui Modules, and \gui Disassembler
|
|
views.
|
|
\endlist
|
|
|
|
|
|
You can use the \gui Debug mode views to examine the data in more detail.
|
|
|
|
You can use the following keyboard shortcuts:
|
|
|
|
\list
|
|
|
|
\o To finish debugging, press \key{Shift+F5}.
|
|
\o To execute a line of code as a whole, press \key{F10}.
|
|
\o To step into a function or a sub-function, press \key{F11}.
|
|
\o To continue running the program, press \key{F5}.
|
|
|
|
\endlist
|
|
|
|
It is also possible to continue executing the program until the current
|
|
function completes or jump to an arbitrary position in the current function.
|
|
|
|
|
|
\section1 Setting Breakpoints
|
|
|
|
A breakpoint represents a position or sets of positions in the code that,
|
|
when executed, interrupts the program being debugged and passes the control
|
|
to you. You can then examine the state of the interrupted program, or
|
|
continue execution either line-by-line or continuously.
|
|
|
|
Qt Creator shows breakpoints in the \gui{Breakpoints} view which is enabled
|
|
by default. The \gui{Breakpoints} view is also accessible when the debugger
|
|
and the program being debugged is not running.
|
|
|
|
\image qtcreator-debug-breakpoints.png "Breakpoints view"
|
|
|
|
Typically, breakpoints are associated with a source code file and line, or
|
|
the start of a function -- both are allowed in Qt Creator.
|
|
|
|
The interruption of a program by a breakpoint can be restricted with
|
|
certain conditions.
|
|
|
|
To set a breakpoint:
|
|
|
|
\list
|
|
\o At a particular line you want the program to stop, click the
|
|
left margin or press \key F9 (\key F8 for Mac OS X).
|
|
\o At a function that you want the program to interrupt, enter the
|
|
function's name in \gui{Set Breakpoint at Function...} located in the
|
|
context menu of the \gui{Breakpoints} view.
|
|
\endlist
|
|
|
|
\note You can remove a breakpoint:
|
|
\list
|
|
\o By clicking the breakpoint marker in the text editor.
|
|
\o By selecting the breakpoint in the breakpoint view and pressing
|
|
\key{Delete}.
|
|
\o By selecting \gui{Delete Breakpoint} from the context
|
|
menu in the \gui Breakpoints view.
|
|
\endlist
|
|
|
|
You can set and delete breakpoints before the program starts running or
|
|
while it is running under the debugger's control. Breakpoints are saved
|
|
together with a session.
|
|
|
|
|
|
\section1 Viewing Call Stack Trace
|
|
|
|
When the program being debugged is interrupted, Qt Creator displays the
|
|
nested function calls leading to the current position as a call stack
|
|
trace. This stack trace is built up from call stack frames, each
|
|
representing a particular function. For each function, Qt Creator tries
|
|
to retrieve the file name and line number of the corresponding source
|
|
file. This data is shown in the \gui Stack view.
|
|
|
|
\image qtcreator-debug-stack.png
|
|
|
|
Since the call stack leading to the current position may originate or go
|
|
through code for which no debug information is available, not all stack
|
|
frames have corresponding source locations. Stack frames without
|
|
corresponding source locations are grayed out in the \gui{Stack} view.
|
|
|
|
If you click a frame with a known source location, the text editor
|
|
jumps to the corresponding location and updates the \gui{Locals and Watchers}
|
|
view, making it seem like the program was interrupted before entering the
|
|
function.
|
|
|
|
|
|
\section1 Viewing Threads
|
|
|
|
If a multi-threaded program is interrupted, the \gui Thread view or the
|
|
combobox named \gui Thread in the debugger's status bar can be used to
|
|
switch from one thread to another. The \gui Stack view adjusts itself
|
|
accordingly.
|
|
|
|
|
|
\section1 Viewing Modules and Source Files
|
|
|
|
The \gui{Modules} view and \gui{Source Files} views display information
|
|
that the debugger plugin has about modules and source files included in
|
|
the project. The \gui{Modules} view lists the modules in the project and
|
|
symbols within the modules. In addition, it indicates where the module
|
|
was loaded.
|
|
|
|
The \gui{Source Files} view lists all the source files included in the project.
|
|
If you cannot step into an instruction, you can check whether the source file is
|
|
actually part of the project, or whether it was compiled
|
|
elsewhere. The view shows the path to each file in the file system.
|
|
|
|
By default, the \gui{Modules} view and \gui{Source Files} view are hidden.
|
|
|
|
|
|
\section1 Viewing Disassembled Code and Register State
|
|
|
|
The \gui{Disassembler} view displays disassembled code for the current
|
|
function. The \gui{Registers} view displays the current state of the CPU's
|
|
registers.
|
|
|
|
The \gui{Disassembler} view and the \gui{Registers} view are both useful
|
|
for low-level commands for checking single instructions, such as \gui{Step Into}
|
|
and \gui{Step Over}. By default, both \gui{Disassembler} and
|
|
\gui{Registers} view are hidden.
|
|
|
|
\section1 Locals and Watchers
|
|
|
|
Whenever a program stops under the control of the debugger, it retrieves
|
|
information about the topmost stack frame and displays it in the
|
|
\gui{Locals and Watchers} view. The \gui{Locals and Watchers} view
|
|
typically includes information about parameters of the function in that
|
|
frame as well as the local variables.
|
|
|
|
\image qtcreator-watcher.png "Locals and Watchers view"
|
|
|
|
Compound variables of struct or class type are displayed as
|
|
expandable in the view. Expand entries to show
|
|
all members. Together with the display of value and type, you can
|
|
examine and traverse the low-level layout of object data.
|
|
|
|
|
|
\table
|
|
\row
|
|
\i \bold{Note:}
|
|
|
|
\row
|
|
\i Gdb, and therefore Qt Creator's debugger works for optimized
|
|
builds on Linux and Mac OS X. Optimization can lead to
|
|
re-ordering of instructions or removal of some local variables,
|
|
causing the \gui{Locals and Watchers} view to show unexpected
|
|
data.
|
|
\row
|
|
\i The debug information provided by gcc does not include enough
|
|
information about the time when a variable is initialized.
|
|
Therefore, Qt Creator can not tell whether the contents of a
|
|
local variable contains "real data", or "initial noise". If a
|
|
QObject appears uninitialized, its value is reported as
|
|
\gui {not in scope}. Not all uninitialized objects, however, can be
|
|
recognized as such.
|
|
\endtable
|
|
|
|
|
|
The \gui{Locals and Watchers} view also provides access to the most
|
|
powerful feature of the debugger: comprehensive display of data belonging
|
|
to Qt's basic objects.
|
|
|
|
To enable Qt's basic objects data display feature:
|
|
\list
|
|
\o Select \gui Tools > \gui {Options...} > \gui Debugger >
|
|
\gui{Debugging Helper} and check the \gui{Use Debugging Helper}
|
|
checkbox.
|
|
\o The \gui{Locals and Watchers} view is reorganized to provide a
|
|
high-level view of the objects.
|
|
\endlist
|
|
|
|
For example, in case of QObject, instead of displaying a pointer to some
|
|
private data structure, you see a list of children, signals and slots.
|
|
|
|
Similarly, instead of displaying many pointers and integers, Qt Creator's
|
|
debugger displays the contents of a QHash or QMap in an orderly manner.
|
|
Also, the debugger displays access data for QFileInfo and provides
|
|
access to the "real" contents of QVariant.
|
|
|
|
You can use the \gui{Locals and Watchers} view to change the contents of
|
|
variables of simple data types, for example, \c int or \c float when the
|
|
program is interrupted. To do so, click the \gui Value column, modify
|
|
the value with the inplace editor, and press \key Enter (or \key Return).
|
|
|
|
\note The set of watched items is saved in your session.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-debugging-cpp.html
|
|
\page creator-debugging-example.html
|
|
\nextpage creator-debug-mode.html
|
|
|
|
\title Debugging the Example Application
|
|
|
|
This section uses the \l{Creating a Qt C++ Application}{TextFinder} example to
|
|
illustrate how to debug applications in the \gui Debug mode. TextFinder
|
|
reads a text file into
|
|
QString and then displays it with QTextEdit.
|
|
To look at the example QString, \c{line}, and see the
|
|
stored data, place a breakpoint and view the QString object
|
|
data, as follows:
|
|
|
|
\list 1
|
|
\o Click in between the line number and the window border on the line
|
|
where we invoke \l{http://doc.qt.nokia.com/4.7-snapshot/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-engines.html
|
|
\page creator-debugging-helpers.html
|
|
\nextpage creator-debugging-qml.html
|
|
|
|
\title Using Debugging Helpers
|
|
|
|
\section1 Debugging Helper Library with C++
|
|
|
|
While debugging, Qt Creator dynamically loads a helper library into your
|
|
program. This helper library enables Qt Creator to pretty print Qt and STL
|
|
types. The Qt SDK package already contains a prebuilt debugging helper
|
|
library. To create 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 Helper Library with Python
|
|
|
|
With the gdb Python version, you can
|
|
use debugging helpers also for user defined types. To do so,
|
|
define one Python function per user defined type in \c{.gdbinit}.
|
|
|
|
The function name has to be qdump__NS__Foo, where NS::Foo is the class
|
|
or class template to be examined. Nested namespaces are possible.
|
|
|
|
The debugger plugin calls this function whenever you want to
|
|
display an object of this type. The function is passed the following
|
|
parameters:
|
|
\list
|
|
\o \c d of type \c Dumper
|
|
\o \c item of type \c Item
|
|
\endlist
|
|
|
|
The function has to feed the Dumper object with certain information
|
|
which is used to build up the object and its children's display in the
|
|
\gui{Locals and Watchers} view.
|
|
|
|
|
|
Example:
|
|
|
|
\code
|
|
def qdump__QVector(d, item):
|
|
d_ptr = item.value["d"]
|
|
p_ptr = item.value["p"]
|
|
alloc = d_ptr["alloc"]
|
|
size = d_ptr["size"]
|
|
|
|
check(0 <= size and size <= alloc and alloc <= 1000 * 1000 * 1000)
|
|
check(d_ptr["ref"]["_q_value"] > 0)
|
|
|
|
innerType = item.value.type.template_argument(0)
|
|
d.putItemCount(size)
|
|
d.putNumChild(size)
|
|
if d.isExpanded(item):
|
|
p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
|
|
with Children(d, [size, 2000], innerType)
|
|
for i in d.childRange():
|
|
d.putItem(Item(p.dereference(), item.iname, i))
|
|
p += 1
|
|
\endcode
|
|
|
|
\section2 Item Class
|
|
|
|
The Item Python class is a thin wrapper around values corresponding to one
|
|
line in the \gui{Locals and Watchers} view. The Item members are as follows :
|
|
|
|
\list
|
|
|
|
\o \gui{__init__(self, value, parentiname, iname, name = None)} - A
|
|
constructor. The object's internal name is created by concatenating
|
|
\c parentiname and \c iname. If \c None is passed as \c name, a
|
|
serial number is used.
|
|
|
|
\o \gui{value} - An object of type gdb.Value representing the value to
|
|
be displayed.
|
|
|
|
\o \gui{iname} - The internal name of the object, constituting a dot-separated
|
|
list of identifiers, corresponding to the position of the object's
|
|
representation in the view.
|
|
|
|
\o \gui{name} - An optional name. If given, is used in the
|
|
\gui{name} column of the view. If not, a simple number in brackets
|
|
is used instead.
|
|
|
|
\endlist
|
|
|
|
|
|
\section2 Dumper Class
|
|
|
|
For each line in the \gui{Locals and Watchers} view, a string like the
|
|
following needs to be created and channeled to the debugger plugin.
|
|
\code
|
|
"{iname='some internal name',
|
|
addr='object address in memory',
|
|
name='contents of the name column',
|
|
value='contents of the value column',
|
|
type='contents of the type column',
|
|
numchild='number of children', // zero/nonzero is sufficient
|
|
childtype='default type of children', // optional
|
|
childnumchild='default number of grandchildren', // optional
|
|
children=[ // only needed if item is expanded in view
|
|
{iname='internal name of first child',
|
|
... },
|
|
{iname='internal name of second child',
|
|
... },
|
|
...
|
|
]}"
|
|
\endcode
|
|
|
|
While in theory, you can build up the entire string above manually, it is
|
|
easier to employ the Dumper Python class for that purpose. The Dumper
|
|
Python class contains a complete framework to take care of the \c iname and
|
|
\c addr fields, to handle children of simple types, references, pointers,
|
|
enums, known and unknown structs as well as some convenience methods to
|
|
handle common situations.
|
|
|
|
The Dumper members are the following:
|
|
|
|
\list
|
|
|
|
\o \gui{__init__(self)} - Initializes the output to an empty string and
|
|
empties the child stack.
|
|
|
|
\o \gui{put(self, value)} - Low level method to directly append to the
|
|
output string.
|
|
|
|
\o \gui{putCommaIfNeeded(self)} - Appends a comma if the current output
|
|
ends in '}', '"' or ']' .
|
|
|
|
\o \gui{putField(self, name, value)} - Appends a comma if needed, and a
|
|
name='value' field.
|
|
|
|
\o \gui{beginItem(self, name)} - Starts writing a field by writing \c {name='}.
|
|
|
|
\o \gui{endItem(self)} - Ends writing a field by writing \c {'}.
|
|
|
|
\o \gui{endChildren(self)} - Ends writing a list of children.
|
|
|
|
\o \gui{childRange(self)} - Returns the range of children specified in
|
|
the current \c Children scope.
|
|
|
|
\o \gui{putItemCount(self, count)} - Appends a field \c {value='<%d items'}
|
|
to the output.
|
|
|
|
\o \gui{putEllipsis(self)} - Appends fields
|
|
\c {'{name="<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{putItemHelper(self, item)} - The "master function", handling
|
|
basic types, references, pointers and enums directly, iterates
|
|
over base classes and class members of compound types and calls
|
|
\c qdump__* functions whenever appropriate.
|
|
|
|
\o \gui{putItem(self, item)} - Equivalent to:
|
|
\code
|
|
with SubItem(self):
|
|
self.putItemHelper(item)
|
|
\endcode
|
|
Exceptions raised by nested function calls are caught and all
|
|
output produced by \c putItemHelper is replaced by the output of:
|
|
\code
|
|
...
|
|
except RuntimeError:
|
|
d.put('value="<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.putItemHelper(Item(key, item.iname, "key"))
|
|
with SubItem(d):
|
|
d.putName("value")
|
|
d.putItemHelper(Item(value, item.iname, "value"))
|
|
\endcode
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-project-qmake.html
|
|
\page creator-project-cmake.html
|
|
\nextpage creator-project-generic.html
|
|
|
|
\title Setting Up a CMake Project
|
|
|
|
CMake is an alternative to qmake for automating the generation of makefiles.
|
|
It controls the software compilation process by using simple configuration
|
|
files, called CMakeLists.txt files. CMake generates native makefiles and
|
|
workspaces that you can use in the compiler environment of your choice.
|
|
|
|
Since Qt Creator 1.1, CMake configuration files are supported.
|
|
Qt Creator 1.3 supports the Microsoft Toolchain if the CMake version
|
|
is at least 2.8.
|
|
|
|
\section1 Setting the Path for CMake
|
|
|
|
You can set the path for the \c CMake executable in \gui{Tools} >
|
|
\gui{Options... > Projects > CMake}.
|
|
|
|
\image qtcreator-cmakeexecutable.png
|
|
|
|
\note Before you open a \c CMake project it is necessary to modify the
|
|
\c{PATH} environment variable to include the bin folders of \c mingw and
|
|
Qt Creator in the SDK.
|
|
|
|
For instance, if you have the Qt Creator SDK installed in your C drive,
|
|
use the following command to set the environment variables in
|
|
the command line prompt:
|
|
\code
|
|
set PATH=C:\qtsdk\mingw\bin;C:\qtsdk\qt\bin;
|
|
\endcode
|
|
Then start Qt Creator by typing:
|
|
\code
|
|
C:\qtsdk\bin\qtcreator.exe
|
|
\endcode
|
|
|
|
\section1 Opening CMake Projects
|
|
|
|
To open a \c CMake project:
|
|
\list 1
|
|
\o Select \gui{File} > \gui{Open File or Project...}.
|
|
\o Select the \c{CMakeLists.txt} file from your \c CMake project.
|
|
\endlist
|
|
|
|
A wizard guides you through the rest of the process.
|
|
|
|
\note If the \c CMake project does not have an in-place build, Qt Creator
|
|
lets you specify the directory in which the project is built
|
|
(\l{glossary-shadow-build}{shadow build}).
|
|
|
|
\image qtcreator-cmake-import-wizard1.png
|
|
|
|
The screenshot below shows how you can specify command line arguments to
|
|
\c CMake for your project.
|
|
|
|
\image qtcreator-cmake-import-wizard2.png
|
|
|
|
Normally, there is no need to pass any command line arguments for projects
|
|
that are already built, as \c CMake caches that information.
|
|
|
|
|
|
\section1 Building CMake Projects
|
|
|
|
Qt Creator builds \c CMake projects by running \c make, \c mingw32-make, or
|
|
\c nmake depending on your platform. The build errors and warnings are
|
|
parsed and displayed in the \gui{Build Issues} output pane.
|
|
|
|
By default, Qt Creator builds the \bold{all} target. You can specify which
|
|
targets to build in \gui{Project} mode, under \gui{Build Settings}.
|
|
|
|
\image qtcreator-cmake-build-settings.png
|
|
|
|
Qt Creator supports multiple build configurations. The build
|
|
directory can also be modified after the initial import.
|
|
|
|
\section1 Running CMake Projects
|
|
Qt Creator automatically adds \gui{Run Configurations} for all targets
|
|
specified in the \c CMake project file.
|
|
|
|
Known issues for the current version can be found
|
|
\l{Known Issues}{here}.
|
|
|
|
|
|
\section1 Adding External Libraries to a CMake Project
|
|
|
|
Through external libraries Qt Creator can support code completion and
|
|
syntax highlighting as if they were part of the current project or the Qt
|
|
library.
|
|
|
|
Qt Creator detects the external libraries using the \c FIND_PACKAGE()
|
|
macro. Some libraries come with the CMake installation. You can find those
|
|
in the \bold{Modules} directory of your CMake installation.
|
|
|
|
\note If you provide your own libraries, you also need to provide your own
|
|
\c FindFoo.cmake file. For more information, see
|
|
\l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}.
|
|
|
|
Syntax completion and highlighting work once your project successfully
|
|
builds and links against the external library.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-project-cmake.html
|
|
\page creator-project-generic.html
|
|
\nextpage creator-developing-maemo.html
|
|
|
|
\title Setting Up a Generic Project
|
|
|
|
Qt Creator supports generic projects, so you can import existing projects
|
|
that do not use qmake or CMake and Qt Creator ignores your build system.
|
|
|
|
Generic project support allows you to use Qt Creator as a code editor. You
|
|
can change the way your project is built by modifying the \c make command
|
|
in the \gui{Projects} mode under \gui{Build Settings}.
|
|
|
|
When you import a project, Qt Creator creates the following files that
|
|
allow you to specify which files belong to your project and which include
|
|
directories or defines you want to pass to your compile:
|
|
\tt{.files}, \tt{.includes}, and \tt{.config}.
|
|
|
|
|
|
\section1 Importing a Generic Project
|
|
|
|
To import an existing generic project:
|
|
\list 1
|
|
\o Select \gui File > \gui{New File or Project...} >
|
|
\gui{Other Project} > \gui{Import Existing Project}.
|
|
\o In \gui{Import Existing Project}, enter the project name
|
|
and select the location of the project file you want to import.
|
|
|
|
Qt Creator automatically generates the following files in the
|
|
project directory:
|
|
\list
|
|
\o \l{Specifying Files}{.files}
|
|
\o \l{Specifying Include Paths}{.includes}
|
|
\o \l{Specifying Defines}{.config}
|
|
\o .creator
|
|
\endlist
|
|
\endlist
|
|
|
|
When the project is successfully imported, Qt Creator creates the project
|
|
tree in the sidebar.
|
|
|
|
After importing a generic project into Qt Creator, open it by selecting the
|
|
\tt{.creator} file.
|
|
|
|
|
|
\section1 Working with Generic Project Files
|
|
|
|
For a generic project, you have to manually specify which files belong to
|
|
your project and which include directories or defines you want to pass to
|
|
your compiler.
|
|
|
|
|
|
\section1 Specifying Files
|
|
|
|
The list of files for a generic project is specified in the \tt{.files}
|
|
file. When you first create a generic project, Qt Creator adds any
|
|
files it recognizes to your project.
|
|
|
|
To add or remove files, edit the \tt{.files} file in Qt Creator.
|
|
Qt Creator recreates your project tree when you save the \tt{.files} file.
|
|
Alternatively, you can add and remove files using the context menu in the
|
|
project tree.
|
|
|
|
If you frequently need to update the \tt{.files} file, you can do so
|
|
efficiently by using a script that updates the file for you. If the file
|
|
is modified externally, you have to restart Qt Creator for the changes to
|
|
take effect.
|
|
|
|
To update the \tt{.files} on the \gui Git repository use the following
|
|
script:
|
|
\code
|
|
git ls-files *.cpp *.h > MyProject.files
|
|
\endcode
|
|
|
|
\section1 Specifying Include Paths
|
|
|
|
The include paths are specified in the \tt{.includes} file, one include
|
|
path per line. The paths can be either absolute or relative to the
|
|
\tt{.includes} file.
|
|
|
|
\section1 Specifying Defines
|
|
|
|
The defines are specified in the \tt{.config} file. The \tt{.config} file is
|
|
a regular C++ file, prepended to all your source files when they are parsed.
|
|
Only use the \tt{.config} file to add lines as in the example below:
|
|
|
|
\code
|
|
#define NAME value
|
|
\endcode
|
|
|
|
|
|
\section1 Creating a Run Configuration
|
|
|
|
Qt Creator cannot automatically determine which executable to run.
|
|
|
|
In the \gui{Projects} mode under \gui{Run Settings}, define the executable
|
|
file to run:
|
|
\list 1
|
|
\o Click \gui Add and select \gui{Custom Executable}.
|
|
\o Define the configuration name, the location of the executable, any
|
|
additional arguments and the working directory.
|
|
\endlist
|
|
|
|
*/
|
|
|
|
|
|
|
|
/*!
|
|
|
|
\contentspage index.html
|
|
\previouspage creator-build-dependencies.html
|
|
\page creator-visual-editor.html
|
|
\nextpage creator-usability.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-snapshot/qdeclarativeexamples.html} {QML examples and demos}
|
|
to learn how to use various aspects of QML.
|
|
|
|
\note The Qt Quick specific features and the QDeclarative help are based on a
|
|
preview version of the QtDeclarative package. Update Qt Creator when Qt 4.7 is
|
|
released.
|
|
|
|
You can use the code editor (\gui Edit mode) or the visual editor
|
|
(\gui Design mode) to develop Qt Quick applications.
|
|
|
|
\note The \QMLD visual editor is provided as an experimental plugin that you must
|
|
enable to be able to edit QML files in the \gui Design mode. Enabling the
|
|
visual editor can negatively affect the overall stability of Qt Creator.
|
|
|
|
To enable or disable the \QMLD visual editor, select
|
|
\gui {Help > About Plugins... > Qt Quick > QmlDesigner}. You must restart Qt Creator
|
|
to enable or disable the visual editor.
|
|
|
|
\section1 Creating Qt Quick Projects
|
|
|
|
Select \gui {File > New File or Project > Qt Quick Project > Qt QML Application}.
|
|
|
|
\QMLD 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-snapshot/qdeclarativemodules.html} {Qt modules}
|
|
to import to \QMLD. 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}.
|
|
|
|
\section1 Designing Application UI
|
|
|
|
One .qml file can define a component, screen, or the whole application.
|
|
|
|
\section2 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 \gui Library items to create components. Drag and drop
|
|
the following QML elements to the editor and modify their properties in the \gui Properties pane:
|
|
|
|
\list
|
|
|
|
\o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-borderimage.html}{Border Image}
|
|
uses an image as a border or background.
|
|
\o \l{http://doc.qt.nokia.com/4.7-snapshot/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-snapshot/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-snapshot/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-snapshot/qml-text.html}{Text}
|
|
adds formatted read-only text.
|
|
\o \l{http://doc.qt.nokia.com/4.7-snapshot/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-snapshot/qml-textinput.html}{Text Input}
|
|
adds a single line of editable plain text that can be validated.
|
|
|
|
\endlist
|
|
|
|
You can use QML to add properties for a component in the code editor.
|
|
|
|
The following sections describe some use cases for the QML elements.
|
|
|
|
\section3 Creating Buttons
|
|
|
|
To create a button component:
|
|
|
|
\list 1
|
|
|
|
\o Select \gui {File > New File or Project > Qt > Qt QML File} 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 Double-click the file to open it in the code editor.
|
|
|
|
\o Click \gui {Design} to edit the file in the visual editor.
|
|
|
|
\o Drag and drop a \gui Rectangle from the \gui Library pane to the scene.
|
|
|
|
\o In the \gui Properties pane, modify the appearance of the button.
|
|
|
|
\list a
|
|
|
|
\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 button to align the text to the
|
|
center of the button.
|
|
|
|
\o Click \gui {Geometry}, and then click the
|
|
\inlineimage qmldesigner-anchor-fill-screen.png
|
|
button to anchor the text to the whole button area.
|
|
|
|
\endlist
|
|
|
|
\o Click \gui Edit to edit the \c width and \c height properties of the button
|
|
to fit the button size.
|
|
|
|
\o Press \key {Ctrl+S} to save the button.
|
|
|
|
\image qmldesigner-button.png "Button component"
|
|
|
|
\o Click the \gui Run button to view the button in \QQV.
|
|
|
|
\endlist
|
|
|
|
To create a graphical button that scales beautifully without using vector graphics,
|
|
use the \l{http://doc.qt.nokia.com/4.7-snapshot/qml-borderimage.html}{Border Image}
|
|
element.
|
|
|
|
\section3 Creating Scalable Buttons and Borders
|
|
|
|
You can use the \l{http://doc.qt.nokia.com/4.7-snapshot/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 > Qt > Qt QML File} 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 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 Click \gui Edit to specify properties for the \gui Item, as
|
|
illustrated by the following code snippet:
|
|
|
|
\code
|
|
|
|
property string text: ""
|
|
property int fontSize: 44
|
|
|
|
signal clicked
|
|
|
|
\endcode
|
|
|
|
\o In the \gui Navigator view, select \gui borderimage1 to specify
|
|
settings for it in the \gui Properties pane:
|
|
|
|
\list a
|
|
|
|
\o In the \gui Source field, select the image file for the
|
|
button, for example button_up.png.
|
|
|
|
\o In the \gui Left, \gui Right, \gui Top, and \gui Bottom fields,
|
|
enter 32 to set the margins for the image.
|
|
|
|
\o Click \gui {Geometry}, and then click the
|
|
\inlineimage qmldesigner-anchor-fill-screen.png
|
|
button to anchor the border image to the \gui Item.
|
|
|
|
\o Click \gui Advanced, and 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 {!mousearea1.pressed}.
|
|
|
|
\endlist
|
|
|
|
\o Select \gui borderimage2 to specify similar settings for it:
|
|
|
|
\list a
|
|
|
|
\o In the \gui Source field, select the image file for the
|
|
button when it is clicked, for example button_down.png.
|
|
|
|
\o In the \gui Left, \gui Right, \gui Top, and \gui Bottom fields,
|
|
enter 32 to set the margins for the image.
|
|
|
|
\o Click \gui {Geometry}, and then click the
|
|
\inlineimage qmldesigner-anchor-fill-screen.png
|
|
button to anchor the border image to the \gui Item.
|
|
|
|
\o Click \gui Advanced, and set the following epression for
|
|
\gui Visibility, to specify that the the image is visible
|
|
when the mouse is pressed down: \c {mousearea1.pressed}.
|
|
|
|
\endlist
|
|
|
|
|
|
\o Select \gui Text 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 In the \gui Size field, select \gui {Pixel} 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 Select the \gui Smooth check box to enable smooth text
|
|
rendering.
|
|
|
|
\o Click \gui {Geometry}, 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()}.
|
|
|
|
\o Click the \gui Run button to view the button in \QQV.
|
|
|
|
\endlist
|
|
|
|
\section2 Creating Screens
|
|
|
|
You can use the \gui Library items and your own components to create screens.
|
|
|
|
You can create the following types of views to organize items provided by
|
|
\l{http://doc.qt.nokia.com/4.7-snapshot/qdeclarativemodels.html}{data models}:
|
|
|
|
\list
|
|
|
|
\o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-gridview.html}{Grid View}
|
|
\o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-listview.html}{List View}
|
|
\o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-pathview.html}{Path View}
|
|
|
|
\endlist
|
|
|
|
In the code editor, write the code to use the data models.
|
|
|
|
Use states and transitions
|
|
to navigate between screens.
|
|
|
|
QML states typically describe user interface configurations, such as the UI elements,
|
|
their properties and behavior and the available actions. For example, you can use
|
|
states to create two screens:
|
|
|
|
\list 1
|
|
|
|
\o Use the \gui Library items, resources and your own components to create a screen.
|
|
For example, drag and drop the button component from the \gui Library pane to the screen.
|
|
|
|
\o In the \gui State pane, click the plus sign to add another view, or \e state
|
|
to the application.
|
|
|
|
\o Modify the second state of the screen to create a new screen.
|
|
|
|
\endlist
|
|
|
|
\section3 Creating List Views
|
|
|
|
You use list views and list models to create lists. You use delegates to handle list items.
|
|
Typically, the list model is provided by a QAbstractListModel C++ model object,
|
|
but you can also create it in QML.
|
|
|
|
\list 1
|
|
|
|
\o Select \gui {File > New File or Project > Qt > Qt QML File} to create a QML file
|
|
called ListView.qml (for example).
|
|
|
|
\o Double-click the file to open it in the code editor.
|
|
|
|
\o Add a list model that contains the data to be shown on the list, as
|
|
illustrated by the following code snippet:
|
|
|
|
\code
|
|
|
|
import Qt 4.7
|
|
|
|
Rectangle {
|
|
width: 360
|
|
height: 640
|
|
|
|
ListModel {
|
|
id: myListModel
|
|
ListElement {
|
|
item_index: 0
|
|
item_name: "Item 1"
|
|
item_description: "Description 1"
|
|
}
|
|
ListElement {
|
|
item_index: 1
|
|
item_name: "Item 2"
|
|
item_description: "Description 2"
|
|
}
|
|
ListElement {
|
|
item_index: 2
|
|
item_name: "Item 3"
|
|
item_description: "Description 3"
|
|
}
|
|
}
|
|
|
|
\endcode
|
|
|
|
\o Add a delegate that draws each item in the list.
|
|
|
|
\code
|
|
|
|
Component {
|
|
id: myListDelegate
|
|
Item {
|
|
id: wrapper
|
|
width: parent.width
|
|
height: 40
|
|
Column {
|
|
x: 5; y: 5
|
|
Text { text: '<b>Name:</b> ' + item_name }
|
|
Text { text: '<b>Descriptionr:</b> ' + item_description }
|
|
}
|
|
MouseArea {
|
|
anchors.fill: parent
|
|
onClicked: myList.currentIndex = item_index
|
|
}
|
|
}
|
|
}
|
|
|
|
\endcode
|
|
|
|
You can use a separate delegate to hilight the currently selected item.
|
|
|
|
\code
|
|
|
|
Component {
|
|
id: myListHilight
|
|
Rectangle {
|
|
width: parent.width
|
|
height: 40
|
|
color: "lightsteelblue"
|
|
radius: 5
|
|
SpringFollow on y {
|
|
to: myList.currentItem.y
|
|
spring: 3
|
|
damping: 0.2
|
|
}
|
|
}
|
|
}
|
|
|
|
\endcode
|
|
|
|
\o Add the list view, as illustrated by the following code snippet:
|
|
|
|
\code
|
|
|
|
ListView {
|
|
id: myList
|
|
width: parent.width; height: parent.height
|
|
model: myListModel
|
|
delegate: myListDelegate
|
|
highlight: myListHilight
|
|
focus: true
|
|
}
|
|
}
|
|
|
|
\endcode
|
|
|
|
\o Click the \gui Run button to view the list view in \QQV.
|
|
|
|
\endlist
|
|
|
|
\section2 Navigating Between 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-snapshot/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.
|
|
|
|
|
|
|
|
\section2 Adding User Interaction Methods
|
|
|
|
You can add the following basic interaction methods to scenes:
|
|
|
|
\list
|
|
|
|
\o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-flickable.html}{Flickable}
|
|
items can be flicked horizontally or vertically.
|
|
\o \l{http://doc.qt.nokia.com/4.7-snapshot/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-snapshot/qml-focusscope.html}{Focus Scope}
|
|
assists in keyboard focus handling when building reusable QML components.
|
|
\o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-mousearea.html}{Mouse Area}
|
|
enables simple mouse handling.
|
|
|
|
\endlist
|
|
|
|
To add interaction methods, drag and drop a \gui {Focus Scope} or \gui {Mouse Area}
|
|
to the screen. In the code editor, add signal handlers to execute when users select
|
|
the scope or area. Signal handlers allow actions to be taken in response to an event.
|
|
For instance, the \gui {MouseArea} element has signal handlers to handle mouse press,
|
|
release, and click.
|
|
|
|
\section1 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-snapshot/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-snapshot/qml-advtutorial.html} {QML Advanced Tutorial}.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
|
|
\contentspage index.html
|
|
\previouspage creator-project-generic.html
|
|
\page creator-developing-maemo.html
|
|
\nextpage creator-developing-symbian.html
|
|
|
|
\title Setting Up Development Environment for Maemo
|
|
|
|
Maemo is a software platform developed by Nokia for smartphones and
|
|
Internet Tablets. The Maemo SDK provides an open development environment
|
|
for different applications on top of the Maemo platform. The necessary
|
|
tools from the Maemo SDK are also included in the Nokia Qt SDK.
|
|
The whole tool chain that you need to create, build, debug, run, and deploy
|
|
Maemo applictions is installed and configured when you install the Nokia
|
|
Qt SDK.
|
|
|
|
Maemo 5 is based on the Linux 2.6 operating system. For more
|
|
information about the Maemo platform, see
|
|
\l{http://maemo.org/intro/platform/}{Software Platform} on the Maemo web site.
|
|
|
|
For more information about developing applications for the Maemo 5
|
|
platform, select \gui {Help > Index} and look for \gui {Platform Notes},
|
|
or see
|
|
\l{http://doc.qt.nokia.com/qt-maemo-4.6/platform-notes.html}{Platform Notes - Maemo 5}.
|
|
|
|
\section1 Hardware and Software Requirements
|
|
|
|
To build and run Qt applications for Maemo, you need the following:
|
|
\list
|
|
\o Nokia N900 device with software update release 1.2 (V10.2010.19-1)
|
|
or later installed.
|
|
\o MADDE cross-platform Maemo development
|
|
tool (installed as part of the Nokia Qt SDK).
|
|
|
|
For more information about MADDE pertaining to its
|
|
installation, configuration, and deployment on the device, see
|
|
\l{http://wiki.maemo.org/MADDE}{Introduction to MADDE}.
|
|
|
|
\o Nokia USB drivers.
|
|
|
|
Only needed if you develop on Windows and if you use a USB connection
|
|
to run applications on the device. The drivers are
|
|
installed as part of the Nokia Qt SDK. You can also download them from
|
|
\l{https://garage.maemo.org/frs/?group_id=801&release_id=2655}{PC Connectivity}
|
|
on the Maemo web site. Download and install the latest
|
|
PC_Connectivity_<version>.exe (at the time of writing,
|
|
PC_Connectivity_0.9.4.exe).
|
|
|
|
\endlist
|
|
|
|
The Qt Creator/MADDE integration is supported on the following platforms:
|
|
\list
|
|
\o Linux (32 bit and 64 bit)
|
|
\o Windows (32 bit and 64 bit)
|
|
\omit \o Mac OS 10.5 Leopard, or higher \endomit
|
|
\endlist
|
|
|
|
\note The only supported build system for Maemo in Qt
|
|
Creator is qmake.
|
|
|
|
\section1 Setting Up the Nokia N900
|
|
|
|
You can connect your device to your development PC using either a USB or
|
|
WLAN connection.
|
|
|
|
For the device, you need to use a tool called Mad Developer to create the
|
|
device-side end point for USB and WLAN connections. It provides no
|
|
diagnostics functions but is essential for creating connections between the
|
|
device and your development PC.
|
|
|
|
To use a WLAN connection, you must activate WLAN on the device and connect
|
|
it to the same WLAN as the development PC. The network address is displayed
|
|
in the Mad Developer.
|
|
|
|
To use an USB connection, you need to set up the Nokia N900 as a network device
|
|
on the development PC.
|
|
|
|
\note If you plan to connect your development PC to the Nokia N900 only over WLAN, you can
|
|
ignore the USB-specific parts in the following sections.
|
|
|
|
\section2 Installing and Configuring Mad Developer
|
|
|
|
Install Mad Developer on a device and configure
|
|
a connection between the development PC and the device.
|
|
|
|
To install and configure Mad Developer:
|
|
|
|
\list 1
|
|
\o On the Nokia N900, select \gui{Download} > \gui{Development} > \gui{mad-developer}
|
|
to install the Mad Developer software package.
|
|
\o Click \gui {Mad Developer} to start the Mad Developer application.
|
|
|
|
\o To use a WLAN connection, activate WLAN on the device and connect
|
|
to the same network as the development PC. You can see the network
|
|
address in the \gui wlan0 field.
|
|
|
|
\o To use an USB connection:
|
|
|
|
\list a
|
|
|
|
\o If you are using Microsoft Windows as development host, you must
|
|
change the driver loaded for instantiating the connection.
|
|
In the Mad Developer, select \gui{Manage USB} and select \gui{Load g_ether}.
|
|
|
|
\o To set up the USB settings, click \gui Edit on the \gui usb0 row and
|
|
confirm by clicking \gui Configure.
|
|
|
|
\note By default, you do not need to make changes. The \gui usb0 row
|
|
displays the IP address 192.168.2.15.
|
|
|
|
\endlist
|
|
|
|
\o Select \gui{Developer Password} to generate a password for a freshly
|
|
created user called \bold developer. The password stays valid for as long
|
|
as the password generation dialog is open. You enter the password when
|
|
you configure the connection in Qt Creator.
|
|
|
|
\image qtcreator-mad-developer-screenshot.png
|
|
\endlist
|
|
|
|
\section1 Installing Qt Mobility APIs
|
|
|
|
To develop applications that use the Qt Mobility APIs, you must install the
|
|
APIs on the devices. The APIs are not available in the Nokia N900 package
|
|
manager, and therefore, you must install them from the command line as the
|
|
root user. To become the root user you must first install \c rootsh from the
|
|
application manager.
|
|
|
|
\list 1
|
|
|
|
\o On the device, install \c rootsh from the \gui {Application Manager}.
|
|
|
|
\o In \gui Programs, select \c {X Terminal} to open a terminal window.
|
|
|
|
\o To switch to the root user, enter the following command:
|
|
\c{sudo gainroot}
|
|
|
|
\o To install Qt Mobility libraries, enter the following command:
|
|
\c{apt-get install libqtm-*}
|
|
|
|
\o To confirm the installation, enter: \c Y
|
|
|
|
\o Close the terminal.
|
|
|
|
\endlist
|
|
|
|
\section1 Setting Up Network Connectivity on Development PC
|
|
|
|
Use the network configuration tools on your platform to specify the
|
|
connection to the device on the development PC. You need to do this
|
|
only if you use an USB connection.
|
|
|
|
\section2 Linux
|
|
|
|
The device uses the IP address 192.168.2.15 with the subnet 255.255.255.0
|
|
for its USB connection by default, so you can create the network interface
|
|
with a different address inside the same subnet too.
|
|
|
|
\note If you have changed the IP address of the device when configuring
|
|
Mad Developer, you need to reflect those changes in your development PC USB
|
|
network settings.
|
|
|
|
Run the following command in a shell as root user:
|
|
\c{ifconfig usb0 192.168.2.14 up}
|
|
|
|
\section2 Windows
|
|
|
|
When you connect the device to your Windows PC, Windows tries to install a
|
|
driver for the Linux USB Ethernet connection. In the
|
|
\gui{Found New Hardware Wizard}, select \gui{No, not this time} in the
|
|
first dialog and \gui{Install the software automatically} in the second
|
|
dialog.
|
|
|
|
To specify a network connection:
|
|
|
|
\list 1
|
|
|
|
\o Open the Network Connections window.
|
|
|
|
\o Select the Linux USB Ethernet
|
|
connection that is displayed as a new Local Area Connection.
|
|
|
|
\o Edit the \gui {Internet Protocol Version 4 (TCP/IPv4)} properties
|
|
to specify the IP address for the connection.
|
|
In the \gui {Use the following IP address} field, enter the following values:
|
|
\list
|
|
\o \gui {IP Address}: \bold {192.168.2.14}
|
|
\o \gui SubnetMask: \bold {255.255.255.0}
|
|
\o \gui {Default gateway}: leave this field empty
|
|
\endlist
|
|
|
|
\endlist
|
|
|
|
Depending on
|
|
your version of Microsoft Windows you may have to unplug and re-plug the
|
|
Nokia N900 to reload the driver with its configuration accordingly.
|
|
|
|
\section1 Setting Up MADDE
|
|
|
|
If you install Nokia Qt SDK, the MADDE package is installed and
|
|
configured automatically on your development PC and you can omit this task.
|
|
|
|
\list 1
|
|
|
|
\o Download the MADDE installer file for your platform from the
|
|
\l{http://wiki.maemo.org/MADDE}{MADDE} site.
|
|
|
|
\o Execute the installer and follow the instructions.
|
|
|
|
\o To see which targets are available, run \c{mad-admin list targets}.
|
|
|
|
\o To install the target that starts with the string \bold fremantle, use the command:
|
|
\c{mad-admin create fremantle-qt-xxx}
|
|
|
|
\o In Qt Creator, register the MADDE tool chain:
|
|
|
|
\image qtcreator-screenshot-toolchain.png
|
|
|
|
\list a
|
|
|
|
\o Select \gui Tools > \gui Options... > \gui Qt4 > \gui{Qt Versions}.
|
|
|
|
\o Click \inlineimage qtcreator-windows-add.png,
|
|
to add a new Qt version.
|
|
|
|
The \gui{qmake Location} is the qmake
|
|
executable in \c{<MADDE dir>/targets/<fremantle target>/bin}.
|
|
|
|
\endlist
|
|
|
|
\endlist
|
|
|
|
When you have installed the target, you have a toolchain and a sysroot
|
|
environment for cross-compiling.
|
|
|
|
\section1 Configuring Connections in Qt Creator
|
|
|
|
To be able to run and debug applications on the Maemo emulator and
|
|
devices, you must set up a connection to the emulator and the device in the
|
|
Qt Creator build and run settings. If you install Nokia Qt SDK, the
|
|
necessary software is installed and configured automatically and you
|
|
only need to configure a connection to the device.
|
|
|
|
By default, you create the connection as the \e developer user. This
|
|
protects real user data on the device from getting corrupted during
|
|
testing. If you write applications that use Mobility APIs, you might want
|
|
to test them with real user data. To create a connection as a user, specify
|
|
the \gui Username and \gui Password in Qt Creator. For more information, see
|
|
\l{Testing with User Data}.
|
|
|
|
You can protect the connections between Qt Creator and the Maemo emulator
|
|
or a device by using either a password or an SSH key. You must always
|
|
use a password for the initial connection, but can then deploy an SSH
|
|
key and use it for subsequent connections. If you use a password, you
|
|
must generate it in Mad Developer and enter it in Qt Creator every time
|
|
you connect to the Maemo emulator or to a device.
|
|
|
|
If you do not have an SSH key, you can create it in Qt Creator.
|
|
Encrypted keys are not supported. For more
|
|
information, see \l{Generating SSH Keys}.
|
|
|
|
To configure connections between Qt Creator and the Maemo emulator or
|
|
device:
|
|
|
|
\list 1
|
|
|
|
\o If you install the Maemo emulator (QEMU) separately, you must
|
|
specify parameters to access it:
|
|
|
|
\list a
|
|
|
|
\o Start Mad Developer in the emulator.
|
|
|
|
\o Click \gui {Developer Password} to generate a password for
|
|
the connection.
|
|
|
|
\o In Qt Creator, select \gui {Tools > Options... > Projects >
|
|
Maemo Device Configurations > Add} to add a new configuration.
|
|
|
|
\image qtcreator-maemo-emulator-connection.png
|
|
|
|
\o In the \gui {Configuration name} field, enter a name for
|
|
the connection.
|
|
|
|
\o In the \gui {Device type} field, select \gui {Maemo emulator}.
|
|
|
|
\o In the \gui {Authentication type} field, select \gui Password
|
|
for the initial connection.
|
|
|
|
\o In the \gui Password field, enter the password from the Mad
|
|
Developer for the initial connection.
|
|
|
|
You can use the default values for the other fields.
|
|
|
|
\o Click \gui Test to test the connection.
|
|
|
|
\o To avoid having to specify the password every time you connect
|
|
to the Maemo emulator, click \gui {Deploy Key...} and select
|
|
the file that contains your public key.
|
|
|
|
\o When you have deployed the key to the device, change the
|
|
configuration to use the SSH key for protection.
|
|
|
|
\image qtcreator-maemo-emulator-connection-key.png
|
|
|
|
The default location of the private key file is displayed in the
|
|
\gui {Private key file} field.
|
|
|
|
\endlist
|
|
|
|
If you installed the Nokia Qt SDK, a connection has been configured
|
|
and you only need to specify the password and deploy the SSH key.
|
|
|
|
\o To deploy applications and run them remotely, specify parameters
|
|
for accessing devices:
|
|
|
|
\list a
|
|
|
|
\o Connect your device to the development PC via an USB cable or
|
|
a WLAN. For an USB connection, you are prompted to select the mode
|
|
to use. Choose \gui{PC suite mode}.
|
|
|
|
\note If you experience connection problems due to a USB port issue,
|
|
switch to a different port or use WLAN to connect to the device.
|
|
|
|
\o Select \gui Tools > \gui Options... > \gui Projects >
|
|
\gui{Maemo Device Configurations > Add}, and add a new configuration for a
|
|
\gui {Remote device}.
|
|
|
|
\image qtcreator-screenshot-devconf.png
|
|
|
|
\o In the \gui {Host name} field, enter the IP address from the
|
|
\gui usb0 or \gui wlan0 field in Mad Developer.
|
|
|
|
\o Specify the other settings in the same way as for a Maemo emulator
|
|
connection.
|
|
|
|
\o Click \gui Test to test the connection.
|
|
|
|
\o Click \gui OK to close the dialog.
|
|
|
|
\endlist
|
|
|
|
\o To specify build and run settings:
|
|
|
|
\list a
|
|
|
|
\o Open a project for an application you want to develop for your
|
|
Nokia N900.
|
|
|
|
\o Click \gui Projects to open the projects mode.
|
|
|
|
\o In the \gui{Build Settings} section, choose the MADDE Qt version.
|
|
|
|
\image qtcreator-screenshot-build-settings.png
|
|
|
|
\o In the \gui{Run Settings} section, click \gui Add to add a new
|
|
run configuration.
|
|
|
|
\o Set a name and select the device configuration.
|
|
|
|
\image qtcreator-screenshot-run-settings.png
|
|
|
|
\note You can either add separate run settings for both the Maemo
|
|
emulator connection and the device connection or select the
|
|
\gui {Device configuration} before you run the application.
|
|
|
|
\endlist
|
|
|
|
\endlist
|
|
|
|
\section2 Testing with User Data
|
|
|
|
To run your application as the default user, you must first assign a password
|
|
for the user account and then create the connection to the device as the
|
|
user:
|
|
|
|
\list 1
|
|
|
|
\o On the device, in \gui Programs, select \c {X Terminal} to open a
|
|
terminal window.
|
|
|
|
\o To switch to the root user, enter the following command:
|
|
\c{sudo gainroot}
|
|
|
|
\o To specify the password, enter the following command:
|
|
\c {passwd user}
|
|
|
|
\o In Qt Creator, Select \gui Tools > \gui Options... > \gui Projects >
|
|
\gui{Maemo Device Configurations}.
|
|
|
|
\o Specify the username \c user and the password in the device configuration.
|
|
|
|
\endlist
|
|
|
|
\section2 Generating SSH Keys
|
|
|
|
If you do not have an SSH public and private key pair, you can generate it
|
|
in Qt Creator. You can specify key length and the key algorithm, RSA or DSA.
|
|
If you only use the keys to protect connections to the Maemo emulator or
|
|
device, you can use the default values.
|
|
|
|
\list 1
|
|
|
|
\o Select \gui {Tools > Options... > Projects > Maemo Device Configurations
|
|
> Generate SSH Key...}.
|
|
|
|
\o Click \gui {Generate SSH Key}.
|
|
|
|
\image qtcreator-ssh-key-configuration.png "SSH Key Configuration dialog"
|
|
|
|
\o Click \gui {Save Public Key...} to select the location to save the
|
|
public key.
|
|
|
|
\o Click \gui {Save Private Key...} to specify the location to save the
|
|
private key.
|
|
|
|
\o Click \gui Close to close the dialog.
|
|
|
|
\endlist
|
|
|
|
\section1 Troubleshooting
|
|
|
|
The addresses used in this example might be reserved by some other application
|
|
in your network. If you cannot establish a connection, try the following optional
|
|
configurations:
|
|
|
|
\table
|
|
|
|
\header
|
|
\o usb0 in Mad Developer on Device
|
|
\o USB Network on Development PC
|
|
\o Host Name in Qt Creator Build Settings
|
|
|
|
\row
|
|
\o 172.30.7.15 255.255.255.0
|
|
\o 172.30.7.14 255.255.255.0
|
|
\o 172.30.7.15
|
|
|
|
\row
|
|
\o 10.133.133.15
|
|
\o 10.133.133.14
|
|
\o 10.133.133.15
|
|
|
|
\row
|
|
\o 192.168.133.15
|
|
\o 192.168.133.14
|
|
\o 192.168.133.15
|
|
|
|
\note You cannot use the value localhost for connections to a device.
|
|
|
|
\endtable
|
|
|
|
\note VPN connections might block the device connection.
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-usability.html
|
|
\page creator-maemo-emulator.html
|
|
\nextpage creator-debugging.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-developing-maemo.html
|
|
\page creator-developing-symbian.html
|
|
\nextpage creator-project-managing-sessions.html
|
|
|
|
\title Setting Up Development Environment for Symbian
|
|
|
|
For more information about developing applications for the Symbian
|
|
platform, select \gui {Help > Index} and look for \gui {Platform Notes},
|
|
or see
|
|
\l{http://doc.qt.nokia.com/4.6/platform-notes-symbian.html}{Platform Notes - Symbian}.
|
|
|
|
\section1 Hardware and Software Requirements
|
|
|
|
Windows is the only development platform for the Symbian target
|
|
supported at the moment.
|
|
|
|
For deploying and running applications on the device, you need the
|
|
following:
|
|
\list
|
|
\o The Nokia USB drivers that come with \e{PC Suite} or \e{Ovi Suite}
|
|
\o The \l{http://tools.ext.nokia.com/trk/}{App TRK} application for
|
|
your device
|
|
\o The \e{qt_installer.sis} package installed on the device, that is
|
|
delivered with the Qt SDK
|
|
\o \e {Qt Mobility APIs} installed on the device, if you use them in
|
|
applications
|
|
\endlist
|
|
|
|
To run your applications in the Symbian emulator, you also need
|
|
to install Carbide.c++ v2.0.0 or higher.
|
|
|
|
\section1 Installing Required Applications on Devices
|
|
|
|
The Nokia Qt SDK installation program creates shortcuts for installing
|
|
the required applications on Symbian devices (you can also use any of
|
|
the standard methods for installing applications on devices):
|
|
|
|
\list 1
|
|
|
|
\o Connect the device to the development PC with an USB cable in
|
|
PC Suite Mode. If you have not previously used the device with Ovi Suite
|
|
or PC Suite, all the necessary drivers are installed automatically.
|
|
This takes approximately one minute.
|
|
|
|
\o Choose \gui {Start > Nokia Qt SDK > Symbian > Install Qt to Symbian
|
|
device} and follow the instructions on the screen to install Qt 4.6.2
|
|
libraries on the device.
|
|
|
|
\o Choose \gui {Start > Nokia Qt SDK > Symbian > Install QtMobility to Symbian
|
|
device} and follow the instructions on the screen to install Qt
|
|
mobility libraries on the device.
|
|
|
|
\o Choose \gui {Start > Nokia Qt SDK > Symbian > Install TRK to Symbian
|
|
device} and follow the instructions on the screen to install the TRK
|
|
debugging application on the device.
|
|
|
|
\note To check the Symbian platform version of your device, see
|
|
\l{http://www.forum.nokia.com/devices}{Device Details}.
|
|
|
|
\endlist
|
|
|
|
\note If errors occur during the installation, copy the .sis files from
|
|
\c {<NokiaQtSDK_install_path>\Symbian\sis} to the device using USB storage
|
|
mode. Then install them from the file manager on the device.
|
|
|
|
\section1 Adding Symbian Platform SDKs
|
|
|
|
Nokia Qt SDK contains all the tools you need for developing Qt applications for
|
|
Symbian devices. To use Symbian APIs directly in your applications, you can
|
|
install additional Symbian Platform SDKs:
|
|
|
|
\list
|
|
\o \l{http://www.forum.nokia.com/main/resources/tools_and_sdks/S60SDK/}
|
|
{S60 Platform SDK 3rd Edition FP1 or higher}.
|
|
\o Either the GCCE ARM Toolchain that is included in the Symbian
|
|
SDKs, or RVCT 2.2 [build 686] or later (which is not available free
|
|
of charge)(Your environment needs to find the compiler in the PATH).
|
|
\o Qt for Symbian 4.6.2 or later, installed into the Symbian SDKs you want
|
|
to use.
|
|
|
|
\endlist
|
|
|
|
\section2 Setting Up Qt Creator
|
|
|
|
When you run Qt Creator after installing the Symbian SDK and Qt for
|
|
Symbian, the installed SDKs and their corresponding Qt versions are
|
|
automatically detected. For each detected Symbian SDK with Qt, a special entry
|
|
is made in the Qt version management settings in \gui{Tools} >
|
|
\gui{Options...} > \gui{Qt4} > \gui{Qt Versions}.
|
|
|
|
\note If you manually add a Qt version for Symbian, you must
|
|
also manually specify the Symbian SDK to use for this version.
|
|
|
|
\image qtcreator-qt4-qtversions-win-symbian.png
|
|
|
|
If you want to run your applications in the Symbian emulator, you need to
|
|
point Qt Creator to the Metrowerks Compiler that you want to use, by
|
|
setting the \gui{Carbide directory} of the Qt version to the corresponding
|
|
Carbide.c++ installation directory.
|
|
|
|
You can check which Symbian SDKs and corresponding Qt versions are found in the
|
|
\gui{Tools} > \gui{Options...} > \gui{Qt4} > \gui{S60 SDKs} preference
|
|
page.
|
|
|
|
\image qtcreator-qt4-s60sdks.png
|
|
|
|
|
|
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage creator-version-control.html
|
|
\page adding-plugins.html
|
|
\nextpage creator-tips.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-snapshot/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 and \c {QtCreator.app/Contents/MacOS/designer} folder on Mac. 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}.
|
|
|
|
\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-visual-editor.html
|
|
\page creator-usability.html
|
|
\nextpage creator-maemo-emulator.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.
|
|
|
|
\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 adding-plugins.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.
|
|
|
|
|
|
\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 Using Keyboard Shortcuts
|
|
|
|
Qt Creator provides \l{Keyboard Shortcuts}{many useful keyboard shortcuts}.
|
|
|
|
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}.
|
|
|
|
|
|
|
|
\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.
|
|
|
|
|
|
\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
|
|
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 Ctrl+Alt+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 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.0.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
|
|
|
|
\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
|
|
|
|
\list
|
|
|
|
\o Code completion does not support typedefs for nested classes.
|
|
|
|
\endlist
|
|
|
|
\section1 Projects
|
|
|
|
\list
|
|
\o Paths or file names containing spaces or special characters, e.g.,
|
|
colons, dollar signs, hash marks etc. 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/removing sub-projects. Project
|
|
hierarchies (SUBDIRS template) have to be created manually.
|
|
|
|
\o Creating new \c CMake projects with Qt Creator is not supported.
|
|
|
|
\o Building and packaging sub-projects is not supported for Maemo devices.
|
|
|
|
\o You must create projects for Maemo targets on the same partition where
|
|
you installed Nokia Qt SDK, Qt Creator, and MADDE.
|
|
|
|
\endlist
|
|
|
|
\section1 Debugging
|
|
|
|
\list
|
|
|
|
\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 On Windows, debugging a MinGW-built console application (with \gui{Run in terminal}
|
|
checked) using gdb does not work due to a bug in gdb related to attaching to
|
|
stopped processes (see \l{http://bugreports.qt.nokia.com/browse/QTCREATORBUG-1020}).
|
|
|
|
\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
|
|
*/
|