// **********************************************************************
// 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 1.3.84

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 two integrated
visual editors, \QD and \QMLD, 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{Writing a Simple Program}
\o \l{Creating an Animated Application}
\endlist
\o \l{Using the Editor}
\list
\o \l{Finding and Replacing}
\o \l{Refactoring}
\o \l{Searching With the Locator}
\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{Managing Sessions}
\endlist
\o \l{Developing Qt Quick Applications}
\o \l{Developing Mobile Applications}
\list
\o \l{Developing Maemo Applications}
\o \l{Developing Symbian Applications}
\o \l{Developing Usable Applications}
\endlist
\o \l{Debugging}
\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

Qt Creator provides two integrated visual editors, \QD and \QMLD.

\QD is a tool for designing and building graphical user interfaces (GUIs) from
Qt widgets. You can compose and customize your widgets or dialogs and test
them using different styles and resolutions.

Widgets and forms created with \QD are integrated seamlessly with programmed code,
using the Qt signals and slots mechanism, that lets you easily assign behavior to
graphical elements. All properties set in \QD can be changed dynamically within the code.
Furthermore, features like widget promotion and custom plugins allow you to use your
own widgets with \QD.

UIs that use widgets are clearly structured and enforce a platform look and feel,
which makes them useful for traditional applications. However, they are static, and
do not fully make use of the large high-resolution screens, touch input, and significant
graphics power that are becoming common in portable consumer devices, such as mobile
phones, media players, set-top boxes, and netbooks.

\QMLD allows you to easily develop animations by using a declarative programming
language called \l {http://qt.nokia.com/doc/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.
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 to implement the application logic.

\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 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.
*/

/*!
\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 with the following:
\list
\o g++
\o make
\o libglib2.0-dev
\o libSM-dev
\o libxrender-dev
\o libfontconfig1-dev
\o libxext-dev
\o libfreetype6-dev
\o libx11-dev
\o libxcursor-dev
\o libxfixes-dev
\o libxft-dev
\o libxi-dev
\o libxrandr-dev
\o If you are using QtOpenGL, libgl-dev and libglu-dev
\endlist
\o Mac OS 10.5 or later with the following:
\list
\o Xcode tools for your Mac OS X version available from your Mac
OS X installation DVDs or at \l http://developer.apple.com.
\endlist
\endlist

\omit ## Are the Xcode tools still needed separately? \endomit

\section1 Build Environment

To build Qt Creator itself from the source, you need:
\list
\o Qt 4.7 or later
\o On Windows, MinGW 4.4 or Microsoft Visual Studio 2008
\endlist

\section1 Supported Mobile Device Platforms
You can develop applications for the following mobile device
platforms:

\list

\o Symbian

\o Maemo and Maemo Application Development and Debugging Environment (MADDE)

\endlist

The following table summarizes operating system support for building
applications for mobile device platforms.

\table
\header
\o {1,3} Operating system
\o {3,1} Platform
\header
\o Desktop
\o Symbian
\o Maemo
\row
\o Windows
\o Yes
\o Yes
\o Yes
\row
\o Linux
\o Yes
\o No
\o Yes
\row
\o Mac OS X
\o Yes
\o No
\o Yes
\endtable
*/

/*!
\contentspage index.html
\previouspage creator-os-supported-platforms.html
\page creator-quick-tour.html
\nextpage creator-getting-started.html

\title Quick Tour

The figure below shows some of the components of Qt Creator in
\gui{Edit} mode.

\image qtcreator-breakdown.png

\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.
\o \gui{\l{Developing Application UI}{Design}} mode for designing and developing
application user interfaces.
\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}
\endlist

Output panes are available in all \l{Qt Creator modes}{modes}.

\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.

\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.

\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.trolltech.com/designer-manual.html}{Qt Designer Manual}.

\section1 Using Qt Quick Designer

You can edit .qml files in either the visual \QMLD editor or in the
code editor.

In \gui Projects, double-click a .qml file to open it in the code
editor. Then select the \gui {Design} mode to edit the file in the
visual editor.

\image qmldesigner-visual-editor.png "Visual editor"

Use the visual editor panes to manage your project:

\list

\o \gui {Navigator} pane displays the items in the scene. You can
show and hide items to focus on specific parts of the application.

\o \gui {Library} pane displays lists of predefined \gui {Items} and
imported \gui {Resources} that you can use to design applications. The
images and other files that you copy to the project folder appear in the
\gui {Resources} pane.

\o \gui {Properties} pane displays the properties of the selected component.
You can also change the properties in the code editor.

\o \gui {State} pane displays the different states of the component. To add
states, click the empty slot. Then modify the new state in the editor.
In the code editor, you can see the changes recorded as changes to
the base state.

\endlist

/*!
\contentspage index.html
\previouspage creator-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 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 and the handling of whitespace 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{Code Completion}{code completion} in \gui Completion.
\endlist

\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.

\section1 Syntax Checking

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 Code Completion

As you write code, Qt Creator provides a list of context-sensitive
suggestions to the statement currently under your cursor.

\image qtcreator-codecompletion.png

Set code completion preferences in \gui Tools > \gui{Options...} >
\gui{Text Editor} > \gui Completion. To trigger code completion
manually press \key{Ctrl+Space}.

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.

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

\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.

\section1 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}.

\section1 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{Toggle 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.

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 \gui{Vim style settings}, select \gui{Tools} >
\gui{Options...} > \gui{General}.

\section1 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-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

To narrow your search results, click
\inlineimage qtcreator-locator-magnify.png
in the \gui Find/Replace pane and select any of the following
preferences:
\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} text box.
\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

To rename a specific symbol in your 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.
*/

/*!
\contentspage index.html
\previouspage creator-editor-locator.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{Build Settings} {build settings}
for each development platform. You can use \l{glossary-shadow-build}{shadow builds} 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 work with \bold{qmake projects}, open a \c .pro file. For more
information, see \l{Setting Up a qmake Project}.
\o To work with \bold{CMake projects} you need to have CMake version
2.8.0 or later installed. For more information, see
\l{Setting Up a CMake Project}.
\o To work with \bold{generic projects}, 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

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 and Qt Quick applications. 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

\o \QD forms and Qt QML files, which specify parts of application user
interfaces

\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

\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

\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.

\endlist

\o The following code creates a page that specifies settings for the project:

\code

<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

\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

<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

\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

<fieldpagetitle>ListModel parameters</fieldpagetitle>
<fieldpagetitle xml:lang="de">Parameter des ListModel</fieldpagetitle>
<fields>
<field name="ClassName">

<fielddescription>Class name:</fielddescription>
<fielddescription xml:lang="de">Klassenname:</fielddescription>
</field>
<field name="Datatype">

<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 computer 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.

\note By default, Qt Creator compiles projects with the
\l{glossary-default-qt}{default Qt version}. For information on how to
override this setting, see \l{Build Settings}.

\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 chains using the \gui MSVC drop-down
box:
\list
\o \bold 7.1 for Visual Studio 2003
\o \bold 8.0 for Visual Studio 2005
\o \bold 9.0 for Visual Studio 2008
\endlist

\note If you are using the
\bold{Windows SDK for Windows Server 2008}, Qt Creator identifies
it as version 9.0.

\image qtcreator-qt4-qtversions-win-msvc.png
\endlist

If you are using \bold{Qt for Symbian} and your S60 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 Setting Up a Project

To view and modify the settings for currently open projects, switch to the
\gui Projects mode by pressing \key Ctrl+4.

\image qtcreator-projectpane.png

The project pane consists of the following tabs:
\list
\o Targets
\o Editor Settings
\o Dependencies
\endlist

Use the \gui Build and \gui Run buttons on *Desktop* 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.

\section1 Build Settings

Different build configurations allow you to quickly switch between
different build settings. By default, Qt Creator creates \bold debug
and \bold release build configurations. The \bold{debug} and \bold{release}
build configurations both use the
\l{glossary-default-qt}{default Qt version}.

\image qtcreator-ppbuildsettings.png

\section2 Adding and Removing Build Configurations

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.

\section2 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 toolchain required to build the project.
\o If you want to \l{glossary-shadow-build}{shadow build} your
project, check the \gui{Shadow Build} checkbox and select the
build directory.
\endlist
\endlist

\section2 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.

\section2 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.

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 clean step} and select the
step you want to remove.
\o To change the order of steps, click
\inlineimage qtcreator-movestep.png
.
\endlist

\section2 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.

\section1 Run Settings

Qt Creator automatically creates run configurations for your project.
These run configurations derive their executable from the parsed .pro
files. You can also create custom executable run configurations where you
can set the executable to be run.

\image qtcreator-pprunsettings.png

\section1 File Encoding

To define the default file encoding, select the desired encoding in the
\gui{Editor Settings}. By default, the Qt Creator uses the file encoding
used by your system.

\section1 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.

To define the dependencies between projects:
\list 1
\o Select the project for which you want to configure dependencies.
\o Check the checkboxes in the Dependencies section to select other
projects as dependencies.
\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.trolltech.com/latest/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-quick-tour.html
\page creator-getting-started.html
\nextpage creator-writing-program.html

\title Getting Started

This section contains examples that illustrate how to use Qt Creator and the
integrated design tools, \QD and \QMLD, to create simple applications:

\list
\o \l{Writing a Simple Program}
\o \l{Creating an Animated Application}
\endlist

/*!
\contentspage index.html
\previouspage creator-writing-program.html
\page creator-qml-application.html
\nextpage creator-editor-using.html

\title Creating an Animated Application

\note This tutorial assumes that you are familiar with the \l {http://qt.nokia.com/doc/4.7-snapshot/declarativeui.html}
{QML declarative language}.

This tutorial describes how to use Qt Creator to create a small animated
Qt 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 > QML Application > OK}.

\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

\o In the \gui{Editor} 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 height to \bold 240 and \c width to \bold 320.

\o Click \gui{Design} to design the UI in the visual \QMLD 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

\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 Buiding 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.

/*!
\contentspage index.html
\previouspage creator-getting-started.html
\page creator-writing-program.html
\nextpage creator-qml-application.html

\title Writing a Simple Program

\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.trolltech.com/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 > OK}.

\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.trolltech.com/qlabel.html}{QLabel})
\o \gui{Line Edit} (\l{http://doc.trolltech.com/qlineedit.html}{QLineEdit})
\o \gui{Push Button} (\l{http://doc.trolltech.com/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 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.trolltech.com/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.trolltech.com/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.trolltech.com/qvboxlayout.html}{QVBoxLayout}).

\image qtcreator-textfinder-ui.png "Text Finder UI"

\o Press \gui{Ctrl+S} to save your changes.

\endlist

Applying the horizontal and vertical layouts ensures that the application UI scales to different
screen sizes.

For more information about designing forms with \QD, see the
\l{http://doc.trolltech.com/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
slot, \c{on_findButton_clicked()}, to carry out the find operation. You
also need a private function, \c{loadTextFile()}, to read and display the
contents of the input text file in the
\l{http://doc.trolltech.com/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 slot in a \c{private slots} section and a private function
in 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.trolltech.com/qfile.html}{QFile}, read it with
\l{http://doc.trolltech.com/qtextstream.html}{QTextStream}, and
then display it on \c{textEdit} with
\l{http://doc.trolltech.com/qtextedit.html#plainText-prop}{setPlainText()}
This is illustrated by the following code snippet:

\snippet examples/textfinder/textfinder.cpp 0

\o To use \l{http://doc.trolltech.com/qfile.html}{QFile} and
\l{http://doc.trolltech.com/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.trolltech.com/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 > OK}.
\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-debugging.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 set up the version control system's command line
clients to access your repositories, 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 the settings pages shown by
\gui{Tools} > \gui{Options...}.

\section1 Setting Up Common Options

Select \gui{Tools} > \gui{Options...} > \gui{Version Control} > \gui{Common}
to view the common settings for version control systems. The following are
the options present in \gui{Common}:
\list
\o \gui{Submit message checking script} is a script or program that
can be used to perform checks on the submit message before
submitting. The submit message is passed in as the script's first
parameter. If there is an error, the script should output a
message on standard error and return a non-zero exit code.

\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
\bold{git} or \bold{hg}.
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 version control sub-menus are in \gui{Tools} > \gui{Options...}.
The \gui{Version Control} page also displays the
version control system managing the current project

Under \gui{Application Output} > \gui{Version Control}, there is an output
pane showing the commands that are executed, prepended by a
timestamp and the relevant output.

\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, \bold{Perforce} and \bold{Subversion}. Alternatively, you can
add files later by using the version control tool menus.

With \bold{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 \bold{git}) or \gui{Filelog}(for \bold{Perforce} and
\bold{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
\image qtcreator-vcs-describe.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 \gui git/hg 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.

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}.

\image qtcreator-vcs-commit.png

\section2 Using git-specific Menu Entries

The git sub-menu contains additional entries:

\table
\row
\i \gui{Stash snapshot...}
\i Allows you to 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 \bold{pull}.
\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 \bold{git} settings 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 snapshots...} with options to restore,
display or delete them.
\endtable
*/

/*!
\contentspage index.html
\previouspage creator-editor-refactoring.html
\page creator-editor-locator.html
\nextpage creator-project-managing.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.trolltech.com/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....

\image qtcreator-locator-customize.png

\o In the \gui{Options...} window click \gui Add.
\o In the \gui{Filters} 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. The filters you have
created Qt Creator by default updates 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-project-generic.html
\page creator-project-managing-sessions.html
\nextpage creator-visual-editor.html

\title Managing Sessions

In Qt Creator, a session is a collection of:

\list
\o Open projects with their dependencies
\o Open editors
\o Breakpoints and watches
\o Bookmarks
\endlist

When you launch Qt Creator, a list of existing sessions is displayed on the
\gui{Welcome screen}.

\image qtcreator-welcome-session.png

To switch between sessions, select the session from sessions listed in
\gui File > \gui Session. If you do not create or select a session,
Qt Creator always uses the default session.

To create a new session or remove existing sessions, select \gui File >
\gui Sessions > \gui{Session Manager}.

\image qtcreator-session-manager.png
*/

/*!
\contentspage index.html
\previouspage creator-usability.html
\page creator-debugging.html
\nextpage creator-version-control.html

\title Debugging

\section1 About Debugging with Qt Creator

Qt Creator does not have its own debugger. Qt Creator provides a graphical
frontend to the following:

\table
\header
\o Platform
\o Compiler
\o Debugger Engine
\row
\o Linux, Unixes, Mac OS
\o gcc
\o GNU Symbolic Debugger (gdb)
\row
\o Windows/MinGW
\o gcc
\o GNU Symbolic Debugger (gdb)
\row
\o Windows
\o Microsoft Visual C++ Compiler
\o Debugging Tools for Windows/Microsoft Console Debugger (CDB)
\endtable

The frontend allows you to:
\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, local and global variables, etc.
\endlist

Qt Creator displays the raw information provided by the engine
in a clear and concise manner. This simplifies the debugging process.

Qt Creator comes with generic IDE functionality: stack view, views for
locals and watchers, registers, etc. In addition, Qt Creator includes
features to make debugging Qt-based applications easy. The debugger
frontend understands the internal layout of several Qt classes, for
example, QString, the QTL containers, and most importantly QObject
(and classes derived from it), as well as most containers of the C++
Standard Library. The debugger can present its contents in a useful way.

\section1 Debugger Engine Installation Notes

\table
\header
\o Debugger engine
\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.x.

\row
\o Debugging tools for Windows
\o Using this engine requires you to install the
\e{Debugging tools for Windows}
\l{http://www.microsoft.com/whdc/devtools/debugging/installx86.Mspx}{32-bit}
or
\l{http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx}{64-bit}
package (Version 6.11.1.404 for the 32-bit or the 64-bit version of Qt Creator, respectively),
which is freely available for download from the
\l{http://msdn.microsoft.com/en-us/default.aspx}
{Microsoft Developer Network}.

The pre-built \e{Qt SDK for Windows} makes use
of the library if it is present on the system. When building Qt
Creator using the Microsoft Visual C++ Compiler, the
\c{"%ProgramFiles%\Debugging Tools for Windows"} path is
checked to ensure that all required header files are there.
\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 Projects mode. In the run
configuration, select \gui{Use debug version of frameworks}.

For more detailed information about debugging on the Mac, refer:
\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 Interaction with the Debugger

In \gui Debug mode, several dock widgets are used to interact with the
program you are debugging. Frequently used dock widgets are visible by
default and rarely used ones are hidden. To change the default settings,
select \gui Debug > \gui View, and then select an option to
lock or unlock the location of the dock widgets or display
or hide them. The position of your dock widgets is saved for future
sessions.

\section2 Usage of 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 debugger views to examine the data in more detail.

To finish debugging, press \key{Shift+F5}. You can execute a line of code
as a whole with \key{F10}. To step into a function or a sub-function, use
\key{F11}. You can also continue running the program with \key{F5}.

It is also possible to continue executing the program until the current
function completes or jump to an arbitrary position in the current function.

\section2 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.

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 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 breakpoint's 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.

\section2 Stack

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.

\section2 Threads

If a multi-threaded program is interrupted, the \gui Thread view or the
combobox named \gui Thread in the debugger's status bar can be used to
switch from one thread to another. The \gui Stack view adjusts itself
accordingly.

\section2 Modules View and Source Files View

The \gui{Modules} view and \gui{Source Files} view display the debugger's idea.
By default, the \gui{Modules} view and \gui{Source Files} view are hidden.

\section2 Disassembler View and Registers View

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 such as \gui{Step Single Instruction} and
\gui{Step Over Single Instruction}. By default, both \gui{Disassembler} and
\gui{Registers} view are hidden.

\section2 Locals and Watchers

Whenever a program stops under the control of the debugger, it retrieves
information about the topmost stack frame and displays it in the
\gui{Locals and Watchers} view. The \gui{Locals and Watchers} view
typically includes information about parameters of the function in that
frame as well as the local variables.

Compound variables of struct or class type are displayed as
"expandable" in the view. Click the "+" to expand the entry and show
all members. Together with the display of value and type, you can
examine and traverse the low-level layout of an object's data.

\table
\row
\i \bold{Note:}

\row
\i Gdb, and therefore Qt Creator's debugger works for optimized
builds on Linux and Mac OS X. 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
"out of 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.

\section1 Walkthrough for the Debugger Frontend

The \l{Writing a simple program}{TextFinder} example reads a text file into
QString and then displays it with QTextEdit.

If you want to look at the example's QString, \c{line}, and see the
stored data, you must place a breakpoint and view the QString object's
data. Perform the following steps:

\table
\row
\i \inlineimage qtcreator-setting-breakpoint1.png
\i \bold{Setting a Breakpoint}

\list 1
\o Click in between the line number and the window border on the line
where we invoke \l{http://doc.trolltech.com/qtextedit.html#plainText-prop}{setPlainText()}
to set a breakpoint.
\o Select \gui{Start Debugging} from the \gui{Debug} menu or press \key{F5}.
\endlist

\row
\i \inlineimage qtcreator-setting-breakpoint2.png
\i \bold{Viewing and removing breakpoints}

Breakpoints are visible in the \gui{Breakpoints} view in \gui{Debug} mode.
To remove a breakpoint, right-click it and select \gui{Delete breakpoint}.

\row
\i \inlineimage qtcreator-watcher.png
\i \bold{Viewing Locals and Watchers}

To view the contents of \c{line}, go to the \gui{Locals and
Watchers} view.

\endtable

If you modify your \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. You can add the restart from beginning functionality
with 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

\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 Click \inlineimage qtcreator-serverbutton.png
located next to the \gui{Insert...} button of the Symbol paths
field and select \gui{Symbol Server...}.
\o Select a directory where you want to store the cached information
and click \gui OK.
\endlist

\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

Using a gdb version that has Python scripting available it is possible to
use Debugging Helpers also for user defined types. To do so you need to
define one Python function per user defined type in \c{.gdbinit}.

The function's name has to be qdump__NS__Foo where NS::Foo is the class
or class template to be examined. Nested namespaces are possible.

Qt Creator's debugger integration calls this function whenever you want to
display an object of this type. The function is passed the following
parameters:
\list
\o 'd' of type 'Dumper'
\o 'item' of type '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())
d.beginChildren([size, 2000], innerType)
for i in d.childRange():
d.safePutItem(Item(p.dereference(), item.iname, i))
p += 1
d.endChildren()
\endcode

\section2 'Item' Python 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' Python Class

For each line in the \gui{Locals and Watchers} view, a string like the
following needs to be created and channeled to Creator's 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 'iname' and
'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{beginHash(self)} - Appends a comma if needed and a '{', marking
the begin of a set of fields.

\o \gui{endHash(self)} - Appends a '}', marking the end of a set of
fields.

\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{beginChildren(self, numChild_ = 1, childType_ = None, childNumChild_ = None)}
- Starts writing a list of \c numChild 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.

\o \gui{endChildren(self)} - Ends writing a list of children.

\o \gui{childRange(self)} - Return the range of children specified in
\c beginChildren.

\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 corrent \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 frontend 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:
self.beginHash()
self.putItemHelper(item)
self.endHash()

\o \gui{safePutItemHelper(self, item)} - Calls \c putItemHelper(self, item).
If an exception is raised, catch it, and replace all output produced by
\c putItemHelper with the output of \code
self.putName(item.name)
self.putValue("<invalid>")
self.putType(str(item.value.type))
self.putNumChild(0)
self.beginChildren()
self.endChildren() \endcode

\o \gui{safePutItem(self, item)} - Equivalent to
self.beginHash()
self.safePutItemHelper(item)
self.endHash()

\endlist

/*!
\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...} > \gui{CMake} > \gui{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 of version 1.3.84}{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-project-managing-sessions.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-visual-editor.html
\page creator-developing-applications.html
\nextpage creator-developing-maemo.html

\title Developing Mobile Applications

\omit Use \QD or \QMLD to design and implement application UI. \endomit

Qt Creator provides support for development of various mobile device
applications. Once you specify the build and run settings in Qt Creator,
you can build and run various types of mobile applications.

To develop applications for mobile devices using Qt Creator, you can use
the following development environments:
\list
\o To develop \bold{Maemo} applications, you need to set up the
MADDE development tool. For more information, see
\l{Developing Maemo Applications}.
\o To develop \bold{Symbian} applications, you need to set up the S60
platform SDK and the Qt for Symbian. For more information, see
\l{Developing Symbian Applications}.
\endlist

Once your application is ready you can deploy it on a mobile device.
If you do not have a mobile device connected to your computer, you can
run Maemo applications in the \gui{Local Simulator}, and Symbian
applications in the \gui{Symbian Emulator}.

Developing applications for mobile devices is different from developing
desktop applications. For more information, see
\l{Developing Usable Applications}.

/*!

\contentspage index.html
\previouspage creator-project-managing-sessions.html
\page creator-visual-editor.html
\nextpage creator-developing-applications.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://qt.nokia.com/doc/4.7-snapshot/qdeclarativeexamples.html} {QML examples and demos}
to learn how to use various aspects of QML.

\section1 Creating Qt Quick Projects

Select \gui {File > New File or Project > Qt Quick Project > 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://qt.nokia.com/doc/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
them to the editor and modify their properties in the \gui Properties pane.
You can use QML to add properties for a component. The properties are automatically
displayed in the \gui Properties pane.

For example, 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.

\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"

\endlist

\section2 Creating Screens

You can use the \gui Library items and your own components to create screens. 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 specify
different states of a screen to allow users to view and edit the properties of an
object:

\list 1

\o Use the \gui Library items, resources and your own components to create a screen.
For example, add the button component 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

\section2 Navigating Between Screens

To make movement between states smooth, you can specify transitions. The
\c from and \c to properties define the states between which the transitions run. To
run the transitions in reverse when changing back from the down state to the default state,
set \c reversible to \c true. This is equivalent to writing the two transitions separately.

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.

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

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://qt.nokia.com/doc/4.7-snapshot/qdeclarativejavascript.html} {JavaScript Blocks}.

For an example of how to use JavaScript to develop a game, see the
\l {http://qt.nokia.com/doc/4.7-snapshot/qml-advtutorial.html} {QML Advanced Tutorial}.

/*!

\contentspage index.html
\previouspage creator-developing-applications.html
\page creator-developing-maemo.html
\nextpage creator-developing-symbian.html

\title Developing Maemo Applications

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.
Maemo 5 is based on the Linux 2.6 operating system. You can find more
information about the Maemo platform \l{http://maemo.org/intro/platform/}{here}.

\section1 Getting Started with Maemo Based Applications

To begin development for Maemo applications, you require the following:
\list
\o An N900 device with updates installed.
\o MADDE is a cross-platform Maemo development
tool.

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 An IP address for the device.

In order to setup the device IP address, you need to install
PC Connectivity or implement it using CLI. More information about PC
Connectivity can be found
\l{http://pc-connectivity.garage.maemo.org/2nd_edition/node3.html#SECTION00032300000000000000}
{here}.
\endlist

For deploying and running applications on the device, you need the
following:
\list
\o The Nokia USB drivers that come, for example with, PC Suite.
\o Qt installed on the device. Recent images should have Qt pre-installed.
\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)
\o MacOS 10.5 ("Leopard") or higher
\endlist

\section1 Setting Up the N900

You can connect your device to your workstation using either an USB or a
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 workstation.

For the workstation, you need to set up the N900 as a network device.

\note If you use the device's USB network functionality and plan to
connect your development PC to the N900 via a common WLAN network, you can
ignore the USB-specific parts in the following sections.

\section2 Installing the Mad Developer Package

To install Mad Developer on your device, you need to add an application
catalogue (repository) to the list of catalogues your device checks for
installable software, and install the actual Mad Developer software
package. This is done according to the following
steps:
\list 1
\o Start the application manager

Enter the data as displayed in the screenshot below.

\note The complete web address is
\l http://repository.maemo.org/extras-devel

\image qtcreator-app-manager-extras-devel-screenshot.png

\o Select \gui{Download} > \gui{Development} > \gui{mad-developer}.

The screenshots below shows the process for selecting the
\gui{mad-developer}:

\image qt-creator-app_manager_screenshot1.png
\image qt-creator-app_manager_screenshot2.png

\o Install the Mad Developer software package.
\o Start the Mad Developer application.
\endlist

\note If you are using Microsoft Windows as development host, you must
change the driver loaded for instantiating the connection.
For this click \gui{Manage USB} and select \gui{Load g_ether}.

Follow the steps mentioned below to set up the USB settings:
\list 1
\o Click \gui Edit in the usb0 row and confirm with \gui Configure.

\note By default, you do not need to make changes. The usb0 row
displays the IP address 192.168.2.15.

\o Select \gui{Developer Password} to generate a password for a freshly
created user called "developer". The password stays valid for as long
the password generation dialog is open.

Refer to the screenshot below as an example.

\image qtcreator-mad-developer-screenshot.png
\endlist

\section2 Establishing the USB Connection

Connect your device to the development PC via the USB cable. A dialog
pops up asking for 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.

\section1 Setting Up Connectivity

\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 workstation's USB
network settings as well.

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.

Open the Network Connections window. The just installed Linux USB Ethernet
connection is now displayed as a new Local Area Connection.

Perform the same steps through the Network configuration tools available
with the operating system.

Change the IP to be set statically and enter the following values:
\list
\o IP Address: 192.168.2.14
\o SubnetMask: 255.255.255.0
\o Default gateway: 192.168.2.15
\endlist

Accept these settings and close the Network Configuration. Depending on
your version of Microsoft Windows you may have to unplug and re-plug the
N900 to reload the driver with its configuration accordingly.

\section2 Setting Up MADDE

After having downloaded the MADDE installer file for your platform from
\l{http://wiki.maemo.org/MADDE}{here}, execute it and follow the
instructions. The package will be installed. Then run:
\c{mad-admin list targets} to see which targets are available.
Install the target that starts with "fremantle" by using the command:
\c{mad-admin create fremantle-qt-xxx}

When you have installed the target, you have a toolchain and a sysroot
environment for cross-compiling.

\section1 Setting Up Qt Creator

Set up the Qt Creator for developing Maemo applications by following the
steps mentioned below:

\list 1
\o \bold{Registering the MADDE Toolchain}

Select \gui Tools > \gui Options > \gui Qt4 > \gui{Qt Versions}.
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}.

\image qtcreator-screenshot-toolchain.png

\o \bold{Creating a Device Configuration}

In order to deploy applications and run them remotely, Qt Creator
needs parameters for device access which you can set in device
configurations.

Select \gui Tools > \gui Options > \gui Qt4 >
\gui{Maemo Device Configurations} and add a new configuration.

\image qtcreator-screenshot-devconf.png

\note The password is the one MADDE Developer displays on the
device. Click \gui Test to check whether the device can be accessed
properly. It is recommended that you use the password-based login
only to deploy your public SSH key to the device
(using the \gui{Deploy Key} button) and then switch to key-based
authentication.

Close the dialog by clicking the \gui OK button after completion.

\o \bold{Setting Build and Run Configuration}

Open a project for an application you want to develop for your
N900. Click \gui Projects to open the projects mode. In the
\gui{Build Settings} section, choose the MADDE Qt version which you
registered earlier:

\image qtcreator-screenshot-build-settings.png

In the \gui{Run Settings} section, click \gui Add to add a new
run configuration on the Maemo device. Set a name and select the
device configuration you created above in the popup menu.

The following screenshot shows the result below:

\image qtcreator-screenshot-run-settings.png

\o \bold{Compiling, Running and Debugging Your Application}

You can now continue your work as if developing for any
other platform supported by Qt Creator: for compiling, Qt Creator
will use the MADDE toolchain's cross compiler.

When you run your application, it is automatically copied onto
the device and executed there. Your application's windows will be
displayed on the N900 and command-line output is visible in Qt
Creator's "Application output" window.

Debugging also works transparently.
\endlist
*/

/*!
\contentspage index.html
\previouspage creator-developing-maemo.html
\page creator-developing-symbian.html
\nextpage creator-usability.html

\title Developing Symbian Applications

\section1 Getting Started with Symbian Based Applications

Windows is the only development platform supported at the moment. You
need to install the following software on your system:

\list
\o \l{http://www.forum.nokia.com/main/resources/tools_and_sdks/S60SDK/}
{S60 Platform SDK 3rd Edition FP1 or higher}.
\o \l{http://www.forum.nokia.com/main/resources/technologies/openc_cpp/}
{Open C/C++ v1.6.0 or higher}
(install this into all S60 SDKs you plan to use Qt with).
\o Either the GCCE ARM Toolchain that is included in the S60 Platform
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 S60 SDKs you want
to use.

\endlist

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
\endlist

Running Qt based applications on real devices requires the
\e{qt_installer.sis} package installed on the device, that is bundled with
the binary Qt distribution.

If you want to run your applications in the Symbian emulator, you also need
to install Carbide.c++ v2.0.0 or higher.

\section1 Setting Up Qt Creator

When you run Qt Creator after installing the S60 Platform SDK and Qt for
Symbian, the installed SDKs and their corresponding Qt versions are
automatically detected. For each detected S60 SDK with Qt, a special entry
is made in the Qt version management settings \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 S60 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 what S60 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

\section1 Setting Up Your Project

After installing all the prerequisites and checking the setup in Qt Creator
as described above, you need to set up your project.

\note The only supported build system for Qt for Symbian applications in Qt
Creator is qmake.

Before you can build your project for the Symbian platform, you need to
create build and run configurations for it. To do this, follow the steps
listed below:
\list 1
\o Open \gui{Projects} mode and make sure that your project is selected
at the top of the page.
\o Select the \gui{Targets} configuration. The \gui{Targets}
configuration page allows you to add and configure the build and run
configurations for your project, categorized by the target platform
you want to build and run your application on.

\note Targets for instance can be \gui{Desktop},
\gui{Symbian Emulator}, and \gui{Symbian Device}.
\o Ensure that your project has a \gui{Symbian Device} entry. In case
you want to target the symbian emulator then your project needs to
have \gui{Symbian Emulator} entry as well.
\o If one of the targets is missing in the list for your project, you
can add a complete configuration for a new target by pressing the
\inlineimage qtcreator-qt4-addbutton.png
button and selecting the desired target from the wizard page that
appears.
\endlist

\image qtcreator-qt4-symbian-target-tabs.png
\image qtcreator-qt4-symbian-add-target.png
\image qtcreator-qt4-symbian-target-added.png

The build configuration that is created for the \gui{Symbian Device} target,
uses the GCCE tool chain by default. If you want to build
for the device using RVCT, select the tool chain in the \gui{General}
section for your build configurations.

\section2 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
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.com/wiki/display/pub/The+Complete+Guide+to+Symbian+Signed}
{The 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

\section1 Running Your Project

After setting up your project as described above you build and run your
project for a specific target platform by selecting the target as the
active one, using the target button from the left hand tool bar, and then
press the run button.

\image qtcreator-qt4-symbian-select-symbian-device.png

The icon in the target selector indicates if a device is currently
connected. When Qt Creator detects a device being connected, it shows a
green check mark.

\image qtcreator-qt4-symbian-device-connected.png

\section2 Running Your Project in the Emulator

Running your project in the emulator doesn't require special setup. Select
the \gui{Symbian Emulator} target as the active one, and build and run your
project.

\section2 Running Your Project on the Device

To run your project on a device, you first need to connect it to your
computer through a USB cable. Qt Creator shows the current connection state
of a device in its main toolbar, showing a red cross when no device is
connected, or a green check mark when a device is connected.

\image qtcreator-qt4-symbian-device-notconnected.png
\image qtcreator-qt4-symbian-device-connected.png

The tool tip of the target button shows more details about the actual
device that will be used when you run your application.

Start the \gui{App TRK} application on your device and press the run button
to create a package for your application, deploy, install and run it
automatically on your device.

In the details of the run configuration for the \gui{Symbian Device} target
you can select a specific device to run your application on, if you have
multiple devices connected simultaneously to your computer. If you only
connect a single device, this will automatically be chosen for running your
application.

\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 S60 SDK must point to the S60 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 in the emulator, check if:
\list
\o You selected the \gui{Symbian Emulator} target for your application.
\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
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 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}.

/*!
\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.trolltech.com/4.6/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-developing-symbian.html
\page creator-usability.html
\nextpage creator-debugging.html

\title Developing Usable Applications

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 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 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&nbsp;in&nbsp;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
Default&nbsp;Qt
\endraw
\target glossary-default-qt
\o The version of Qt configured in \gui{Tools > Options... > Qt 4
> Default Qt Version}. This is the Qt version used by your
new projects. It defaults to the Qt in PATH.

\row
\o
\raw HTML
Project&nbsp;Qt
\endraw
\target glossary-project-qt
\o The version of Qt configured in \gui{Build&Run > Build
Settings > Build Configurations}. This is the Qt version that
is actually used by a particular project. It defaults to
Default Qt.

\row
\o
\raw HTML
Shadow&nbsp;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

There are some known issues with Qt Creator.
The development team is aware of them, there is no need to report them as bugs.

\section1 Known Issues of Version 1.3.84

\list
\o Debugging Helper does not work while performing On-Device Debugging.

\o QML Preview (Run Project) only works if built against Qt with
Declarative UI.

\o Setting breakpoints in code that is compiled into the binary more
than once does not work.

\o On Linux and Windows, installing Qt with one user account and
then using it with another requires other users to manually set
the Qt version. On Windows, setting the MinGW location is
required as well. The same applies to the location of GDB for Symbian.
A workaround is to copy %APPDATA%/Nokia/qtcreator.ini (Windows) or
$HOME/.config/Nokia/QtCreator.ini (Linux) from the directory
of the user who installed Qt Creator to the other user.
This issue does not exist on Mac OS X.
\endlist

\section1 Known Issues of Version 1.2.0 and 1.2.1

\list
\o Gdb on Windows may not work if the 'Embassy \reg Security Center' software
by 'Wave \reg Systems' is installed and active (causing crashes in \c{vxvault.dll)}).

\o Only simple data types (POD) work in the Watch Window of CDB.

\o Qt Creator uses SQLite for storing some of its settings. SQLite is
known to have problems with certain NFS servers (most notably the
nfs-user-server 2.2beta), since they can lock up the application
when it tries to lock the database. If your home directory is on an
NFS share and you encounter this issue, one option would be to
switch to the nfs-kernel-server, or create a symlink so that the
settings are stored locally.
\endlist

\section1 Known Issues of Version 1.1.0

\list
\o Paths or file names containing spaces or special characters, e.g.,
colons, dollar signs, hash marks etc. may cause 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 \c{.pro} files are reformatted if files have been added or removed.
Whitespace is not preserved.

\o There is no IDE support for adding files to include (\c .pri) files.

\o There is no IDE support for adding/removing sub-projects. Project
hierarchies (SUBDIRS template) have to be created manually.

\o The file system sidebar does not update automatically. As a
workaround, switch to another directory and then back.

\o Loading KDE4 designer plugins breaks the style in KDE < 4.2.1
due to a bug in KDE.

\o The DEFINES and INCLUDES set in \c{.pro} files are not dealt with
on a file-specific level. Because of this, handling of DEFINES has
been disabled completely. Also the \c{.qmake.cache} is not being
parsed. In general, the \c{.pro} file parser is incomplete and
problems are still to be expected.

\o Code completion for generated UI header files is updated only
after a build.

\o Code completion does not support typedefs for nested classes.

\o There is a kernel bug essentially making debugging unreliable on
2.6.24 kernels for i386 (which is, unfortunately, the default on
Ubuntu 8.04). See
\l{https://bugs.launchpad.net/ubuntu/+source/gdb/+bug/230315/} for
details. The only solution to this problem is to boot another
kernel.

\o Gdb may take long to load debugging symbols, especially from large
libraries like \c libQtWebKit. Starting the debugging module can
take up to several minutes without visible progress.

\o Setting breakpoints in files that do not have unique absolute
paths may fail. For example, remounting parts of a file system
using the --bind mount option.

\o There is no syntax highlighting for \c CMake project files.

\o Project files included from \c{CMakeLists.txt} are not shown in the
navigation tree.

\o Using the Visual Studio Compiler with \c CMake is not supported.

\o Creating new \c CMake projects with Qt Creator is not supported.

\o Having more than one build directory for \c CMake is not supported.

\o Changing the build directory for \c CMake after the initial import
is disabled.
\endlist

/*!
\contentspage index.html
\previouspage creator-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
*/