2 \contentspage{index.html}{Qt Creator}
4 \nextpage creator-quick-tour.html
6 \title Qt Creator Manual
8 \section1 Version 1.2.94
10 The goal of Qt Creator is to provide a cross-platform, complete Integrated
11 Development Environment (IDE) to develop Qt projects. It is available for
12 the Linux, Mac OS X and Windows platforms.
14 \note Please report bugs and suggestions to the
15 \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}.
16 You can also join the Qt Creator mailing list. To subscribe,
17 send a message with the word \e subscribe to
18 \l{mailto:qt-creator-request@trolltech.com}
19 {qt-creator-request@trolltech.com}. For more information on Qt mailing
20 lists, visit \l{http://lists.trolltech.com}{http://lists.trolltech.com}.
23 <img border="0" style="float:right;" src="images/qtcreator-screenshots.png" />
27 \o \l{A Quick Tour of Qt Creator}
28 \o \l{Creating a Project in Qt Creator}
29 \o \l{The Code Editor}
30 \o \l{Project Settings}
31 \o \l{Qt Version Management}
32 \o \l{Writing a Simple Program with Qt Creator}
33 \o \l{Qt Creator and Version Control Systems}
34 \o \l{Navigating Quickly Around Your Code with Locator}
35 \o \l{Session Management in Qt Creator}
36 \o \l{Debugging with Qt Creator}
37 \o \l{CMake Support in Qt Creator}
38 \o \l{Support for Generic Projects in Qt Creator}
39 \o \l{Development of Qt for Symbian Based Applications}
40 \o \l{Handling External Libraries}
41 \o \l{Tips and Tricks}
42 \o \l{Keyboard Shortcuts}
44 \o \l{Supported Platforms}
46 \o \l{Acknowledgements}
51 \contentspage index.html
52 \page creator-quick-tour.html
53 \nextpage creator-code-editor.html
55 \title A Quick Tour of Qt Creator
57 The labeled screenshot below shows some of the components of Qt Creator, in
60 \image qtcreator-breakdown.png
62 \section1 The Mode Selectors
64 When working in Qt Creator, you can be in one of six modes: \bold Welcome,
65 \bold Edit, \bold Debug, \bold Projects, \bold Help, and \bold Output.
67 Mode selectors allow you to quickly switch between tasks: Editing, browsing
68 the Qt Creator manual, setting up the build environment, etc. You can
69 activate a mode by either clicking on its mode selector, or using the
70 \l{keyboard-shortcuts}{corresponding shortcut}. Certain actions also
71 trigger a mode change, e.g., \gui{Debug}/\gui{Start Debugging} will switch
72 to the \gui Debug mode.
76 \o \gui{Welcome Mode} - Displays a welcome screen allowing you to quickly
77 load recent sessions or individual projects. This is the mode you will see
78 if Qt Creator is run without command line switches.
80 \o \gui{Edit Mode} - Lets you edit both project and source files. A sidebar
81 on the left provides different views to navigate between files.
83 \o \gui{Debug Mode} - Provides various ways to inspect the state of the
84 program while debugging. See \l{Debugging With Qt Creator} for a hands-on
85 description of how to use this mode.
87 \o \gui{Projects Mode} - Lets you configure how projects can be built and
88 executed. Under the list of projects, there are tabs to configure the
89 build, run, and editor settings.
91 \o \gui{Help Mode} - Shows any documentation registered by Qt Assistant,
92 such as the Qt library and Qt Creator documentation.
94 \o \gui{Output Mode} - Lets you examine various data in detail, for example
95 build issues as well as compile and application output. This information
96 is also available in the output panes.
101 \section1 The Output Panes
103 The task pane in Qt Creator can display one of four different panes:
104 \gui{Build Issues}, \gui{Search Results}, \gui{Application Output}, and
105 \gui{Compile Output}. These panes are available in all modes.
108 \section2 Build Issues
110 The \gui{Build Issues} pane provides a list of issues, e.g., error messages
111 or warnings that need to be fixed. It filters out irrelevant output from
112 the compiler and collects them in an organized way.
114 \image qtcreator-build-issues.png
117 \section2 Search Results
119 The \gui{Search Results} pane displays the results for global searches such
120 as searching within a current document, files on disk, or all projects. In
121 the screenshot below, we searched for all occurrences of \c{textfinder}
122 within the \c{"/TextFinder"} folder.
124 \image qtcreator-search-pane.png
127 \section2 Application Output
129 The \gui{Application Output} pane displays the status of the program when
130 it is executed and debug output, e.g., output from qDebug().
132 \image qtcreator-application-output.png
137 The \gui{Compile Output} pane provides all the output from the compiler. In
138 other words, it is a more verbose version of information displayed in the
141 \image qtcreator-compile-pane.png
144 \section1 Qt Help Integration
146 Qt Creator comes fully integrated with all of Qt's documentation and
147 examples via the Qt Help plugin. To view the documentation, you can switch
148 to the \gui{Help} mode. To obtain context sensitive help, move your text
149 cursor to a Qt class or function and press \key{F1}. The documentation
150 will be displayed within a panel on the right, as shown in the screenshot
151 below. If there is enough vertical space, it will be shown in the
152 fullscreen help mode.
154 External Documentation provided by the user can be used to augment or
155 replace the documentation shipped with Qt Creator and Qt.
157 \image qtcreator-context-sensitive-help.png
160 \section1 Qt Designer Integration
162 Qt Creator is fully integrated with Qt Designer to help you design user
163 interface forms just like you would with the standalone version. The Qt
164 Designer integration also includes project management and code completion.
165 For more information on Qt Designer, you can refer to
166 \l{http://doc.trolltech.com/designer-manual.html}{The Designer Manual}.
168 \image qtcreator-formedit.png
171 \section1 Keyboard Navigation
173 Qt Creator caters not only to developers who are used to using the mouse,
174 but also to developers who are more comfortable with the keyboard. A wide
175 range of \l{keyboard-shortcuts}{keyboard} and
176 \l{Navigating Quickly Around Your Code with Locator}{navigation} shortcuts
177 are available to help speed up the process of developing your application.
180 /*! \contentspage index.html
181 \previouspage creator-quick-tour.html
182 \page creator-code-editor.html
183 \nextpage creator-project-pane.html
185 \title The Code Editor
187 Qt Creator's code editor is designed to aid the developer to create, edit,
188 and navigate code. It is fully equipped with syntax highlighting, code
189 completion, context sensitive help, as well as inline error indicators
190 while you are typing. The screenshots below show the various dialogs within
191 which you can configure your editor.
195 \i \inlineimage qtcreator-texteditor-fonts.png
196 \i \inlineimage qtcreator-texteditor-behavior.png
198 \i \inlineimage qtcreator-texteditor-display.png
199 \i \inlineimage qtcreator-texteditor-completion.png
202 The table below lists keyboard shortcuts supported by the code editor.
207 \i To navigate between blocks, e.g., from one \bold{\{} to another
208 \bold{\}} , use \key{Ctrl+[} and \key{Ctrl+]}.
211 \i To select a current block, use \key{Ctrl+U}. Pressing
212 \key{Ctrl+U} again extends the selection to the parent block.
213 To deselect, use \key{Ctrl+Shift+U}.
215 \i Moving lines up and down
216 \i Use \key{Ctrl+Shift+Up} and \key{Ctrl+Shift+Down}
220 \i Use \key{Ctrl+Space}
231 \i Commenting or uncommenting blocks
236 \i Use \key{Shift+Del}
239 \i Switch between header file and source file
243 \i Increasing and decreasing font size
244 \i Use \key{Ctrl+Scroll Wheel}
247 \i Follow symbols under the cursor
248 \i Use \key{F2} and \key{Shift+F2}. This feature works with
249 namespaces, classes, methods, variables, include statements,
253 \i Switch to an external editor
254 \i Select \gui{Open in external editor} from the
255 \gui{Edit -> Advanced} menu.
258 \section1 Code Completion
260 The completion popup shows possible completions to a certain statement.
261 These completions include classes, namespaces, functions, variables,
262 macros and keywords. Listed below are the icons used in the completion box
267 \i \inlineimage completion/class.png
270 \i \inlineimage completion/enum.png
273 \i \inlineimage completion/enumerator.png
274 \i An enumerator (value of an enum)
276 \i \inlineimage completion/func.png
279 \i \inlineimage completion/func_priv.png
280 \i A private function
282 \i \inlineimage completion/func_prot.png
283 \i A protected function
285 \i \inlineimage completion/var.png
288 \i \inlineimage completion/var_priv.png
289 \i A private variable
291 \i \inlineimage completion/var_prot.png
292 \i A protected variable
294 \i \inlineimage completion/signal.png
297 \i \inlineimage completion/slot.png
300 \i \inlineimage completion/slot_priv.png
303 \i \inlineimage completion/slot_prot.png
306 \i \inlineimage completion/keyword.png
309 \i \inlineimage completion/macro.png
312 \i \inlineimage completion/namespace.png
319 \contentspage index.html
320 \previouspage creator-code-editor.html
321 \page creator-project-pane.html
322 \nextpage creator-version-management.html
324 \title Project Settings
328 \i \note This page describes Qt Creator's support for \c qmake.
329 For information on CMake support, see
330 \l{CMake Support in Qt Creator}.
333 To modify the project settings of your project, switch to the \gui{Projects}
334 mode using the mouse or \key{Ctrl+4}.
336 \image qtcreator-projectpane.png
338 The project pane is divided into two areas. At the top the currently active
339 settings are shown. The active build or run configuration for all projects
340 can be changed there. The bottom area allows you to quickly get an overview
341 of the build, run and editor settings as well as the dependencies between your
342 projects. It also allows you to edit those settings.
344 \section1 Build Settings
346 Build configurations allow you to quickly switch between different build
347 settings. By default Qt Creator Qt Creator creates a \bold{debug} and
348 \bold{release} build configuration. Both these configurations use the
349 \l{glossary-default-qt}{Default Qt Version}. Action items to create, clone,
350 or delete build configurations can be found at the top. You can have as
351 many build configurations as needed. To edit settings click on the
352 \gui{Show Details} button. Here you can specify which
353 \l{glossary-project-qt}{Qt version} to use to build your project, or whether
354 to \l{glossary-shadow-build}{shadow build} the project, for instance.
356 \image qtcreator-ppbuildsettings.png
358 The build system of Qt Creator is built on top of \c qmake and \c make. The
359 settings for \c qmake and \c make can be changed. Qt Creator will run the
360 make command using the correct Qt version.
362 In the \bold{Build Environment} section you can specify the environment used
363 for building. By default the environment in which Qt Creator was started
364 is used and modified to include the Qt version. Depending on the selected
365 Qt version, Qt Creator will automatically set the necessary environment
368 \section1 Run Settings
370 \image qtcreator-pprunsettings.png
371 Qt Creator automatically creates run configurations for your project.
372 These run configurations derive their executable
373 from the parsed .pro files. You can also create \bold{custom executable}
374 run configurations where you can freely set the executable to be run.
376 \section1 Dependencies
378 If you have multiple projects loaded in your session, you can configure
379 dependencies between them. This will affect the build order of your
380 projects. To do this, go the the \bold{Dependencies} section after selecting
381 the project for which you want to configure the dependencies, and then use
382 the checkboxes to check which of the other projects is a dependency.
383 \note This is unrelated to the dependencies inside a qmake project.
388 \contentspage index.html
389 \previouspage creator-project-pane.html
390 \page creator-version-management.html
391 \nextpage creator-creating-project.html
393 \title Qt Version Management
395 Qt Creator allows you to use multiple versions of Qt installed on your hard
396 disk and switch between them easily.
398 Qt Creator automatically detects if \c qmake is in the environment variable
399 \c PATH. This \l{glossary-system-qt}{version of Qt} is referred to as
400 \bold{Qt in PATH}. If you intend to use only one version of Qt - it is
401 already in your path and correctly set up for command line usage - you do
402 not need to manually configure your Qt version.
404 Otherwise, you can add your Qt version in
405 \gui{Tools -> Options... -> Qt Versions} on Windows and Linux or
406 in \gui{Qt Creator -> Preferences... -> Qt Versions} on Mac OS X.
408 The detailed settings depend on your Operating system and on the targeted
413 \i \image qtcreator-qt4-qtversions.png
414 On Linux and Mac OS X, simply set the \gui{Path to QMake}
415 to the \c qmake binary of the Qt installation. If a Qt is
416 found in the \c PATH environment variable, it will show up
417 automatically as \gui{Qt in PATH}.
419 On both platforms, the platforms Gnu Compiler Collection (GCC)
420 is used to compile Qt. On Mac OS, the GCC compiler is part of XCode.
421 On Linux, the Intel Compiler (ICC) is supported as a drop-in replacement
425 \i \image qtcreator-qt4-qtversions-win-mingw.png
426 If you are on the Windows platform and used MinGW
427 to compile Qt, you need to additionally tell Qt Creator
428 where MinGW is installed. This is done by setting the
429 \gui{MinGW Directory}.
431 \i \image qtcreator-qt4-qtversions-win-msvc.png
432 If your Qt version is compiled with Microsoft Visual C++'s
433 compiler, Qt Creator will automatically set the correct
434 environment variables for compilation. The \gui{MSVC}
435 dropdown box indicates the internal Version Number of the
436 installed Microsoft Visual C++ tool chains:
439 \o \bold{7.1}: Visual Studio 2003
440 \o \bold{8.0}: Visual Studio 2005
441 \o \bold{9.0}: Visual Studio 2008
444 If you are using the \c{Windows SDK for Windows Server 2008}
445 instead of Visual Studio, it will identify as version 9.0.
447 \i \image qtcreator-qt4-qtversions-win-symbian.png
448 If you are using Qt for Symbian and your S60 SDK is registered
449 with \c devices.exe, Qt Creator will detect the Qt version
450 automatically. These are shown in the \bold{Auto-detected}
451 section in the options dialog.
452 You can also manually add Qt for Symbian versions. In this case
453 you need to tell Qt Creator the path to the S60 SDK
454 it is supposed to use with these Qt installations.
455 Add the path to your Carbide C++ install, version 2.0
456 or later, if you want to build for the emulator
457 (\c WINSCW tool chain).
458 If you want to use \c GCCE to build for your device,
459 you might need to add the path to the
460 \c{CSL Arm Toolchain} directory (\gui{CSL/GCCE Directory}),
461 if the compiler is not found in the \c PATH environment
465 \note By default projects are compiled with the
466 \l{glossary-default-qt}{default Qt version}. You can override this in the
467 \gui{Build Configuration}.
472 \contentspage index.html
473 \previouspage creator-version-management.html
474 \page creator-creating-project.html
475 \nextpage creator-writing-program.html
477 \title Creating a Project in Qt Creator
481 \i \inlineimage qtcreator-new-project.png
482 \i \bold{Creating a New Project}
484 To create a new project, select \gui{New Project} from the \gui{File} menu.
485 You can create one of the following three projects:
488 \o Qt4 Console Application
489 \o Qt4 Gui Application
493 In this example, we select a \e{Qt4 Gui Application} and click \gui{OK}.
496 \i \inlineimage qtcreator-intro-and-location.png
497 \i \bold{Setting the Project name and location}
499 Next, we set the project's name and its path. Click on the \gui{...}
500 button to browse and select your path.
502 Ideally, the path should not contain spaces or special characters.
505 \i \inlineimage qtcreator-select-modules.png
506 \i \bold{Selecting The Necessary Qt Modules}
508 Click on the check boxes of each Qt Module you would like to include in
511 Since we started a Qt4 Gui Application, the Core and Gui modules are
512 set, but you are free to add more.
515 \i \inlineimage qtcreator-class-info.png
516 \i \bold{Specifying Class Information}
518 Specify the name of the class you would like to create. The
519 \e{Header file}, \e{Source file} and \e{Form file} fields will update
520 automatically according to your choice of class name.
522 You also have to select the base class for your class, either a
523 QWidget, QDialog or QMainWindow, from the drop down box.
526 \i \inlineimage qtcreator-new-project-summary.png
527 \i \bold{Creating the Project}
529 Finally, review the files that will be created for you. Click
530 \gui{Done} and your project will be generated.
538 \contentspage index.html
539 \previouspage creator-creating-project.html
540 \page creator-writing-program.html
541 \nextpage creator-version-control.html
543 \title Writing a Simple Program with Qt Creator
547 \o \note This tutorial assumes that the user has experience writing
548 basic Qt applications, designing user interfaces with Qt Designer
549 and using the Qt Resource System.
553 In this example, we will describe the steps involve in using Qt Creator
554 to create a small Qt program, Text Finder. Inspired by the QtUiTools'
555 \l{http://doc.trolltech.com/uitools-textfinder.html}{Text Finder}
556 example, we will write a similar but simplified version of it, as shown
559 \image qtcreator-textfinder-screenshot.png
561 \section1 Setting Up Your Environment
563 Once you have installed Qt Creator, it will automatically detect if Qt's
564 location is in your \c PATH variable. If Qt's location is not in your
565 \c PATH, you can set it in one of the following ways, depending on your
569 \o On Windows and Linux: in the \gui{Tools} menu, under \gui{Options}.
570 \o On Mac OS X: in \gui{Preferences}, under \gui{Qt4}.
573 \note If you use Visual Studio to compile Qt, all environment variables set
574 in Visual Studio will be set for Qt Creator as well.
576 \section1 Setting Up The Project
578 We begin with a Qt4 Gui Application project generated by Qt Creator. The
579 \l{Creating a Project in Qt Creator} document describes this process in
580 detail. Remember to select QWidget as the Text Finder's base class. If
581 your project is not yet loaded, you can load it by selecting \gui{Open}
582 from the \gui{File} menu.
584 In your project you will have the following files:
588 \o \c{textfinder.cpp}
591 \o \c{textfinder.pro}
594 The \c{.h} and \c{.cpp} files come with the necessary boiler plate code;
595 the \c{.pro} file is also complete.
597 \section1 Filling In The Missing Pieces
599 We will begin by designing the user interface and then move on to filling
600 in the missing code. Finally, we will add the find functionality.
602 \section2 Designing the User Interface
604 To begin designing the user interface, double-click on the
605 \c{textfinder.ui} file in your \gui{Project Explorer}. This will launch the
606 integrated Qt Designer.
608 \image qtcreator-textfinder-ui.png
610 Design the form above using a \l{http://doc.trolltech.com/qlabel.html}
611 {QLabel}, \l{http://doc.trolltech.com/qlinedit.html}{QLineEdit}
612 (named lineEdit), \l{http://doc.trolltech.com/qpushbutton.html}{QPushButton}
613 (named findButton), and a
614 \l{http://doc.trolltech.com/qtextedit.html}{QTextEdit} (named textEdit).
616 you use a QGridLayout to lay out the
617 \l{http://doc.trolltech.com/qlabel.html}{QLabel},
618 \l{http://doc.trolltech.com/qlinedit.html}{QLineEdit} and
619 \l{http://doc.trolltech.com/qpushbutton.html}{QPushButton}. The
620 \l{http://doc.trolltech.com/qtextedit.html}{QTextEdit} can then be added to
621 a \l{http://doc.trolltech.com/qvboxlayout.html}{QVBoxLayout}, along with
622 the \l{http://doc.trolltech.com/qgridlayout.html}{QGridLayout}. If you are
623 new to designing forms with \QD, you can take a look at the
624 \l{http://doc.trolltech.com/designer-manual.html}{Designer Manual}.
626 \section2 The Header File
628 The \c{textfinder.h} file already has the necessary includes, a
629 constructor, a destructor, and the \c{Ui} object. We need to add a private
630 slot, \c{on_findButton_clicked()}, to carry out our find operation. We
631 also need a private function, \c{loadTextFile()}, to read and display the
632 contents of our input text file in the
633 \l{http://doc.trolltech.com/qtextedit.html}{QTextEdit}. This is done with
636 \snippet examples/textfinder/textfinder.h 0
638 \note The \c{Ui::TextFinder} object is already provided.
640 \section2 The Source File
642 Now that our header file is complete we move on to our source file,
643 \c{textfinder.cpp}. We begin by filling in the functionality to load a
644 text file. The code snippet below describes this:
646 \snippet examples/textfinder/textfinder.cpp 0
648 Basically, we load a text file using
649 \l{http://doc.trolltech.com/qfile.html}{QFile}, read it with
650 \l{http://doc.trolltech.com/qtextstream.html}{QTextStream}, and
651 then display it on \c{textEdit} with
652 \l{http://doc.trolltech.com/qtextedit.html#plainText-prop}{setPlainText()}
653 which requires adding the following additional #includes to textfinder.cpp:
655 \snippet examples/textfinder/textfinder.cpp 1
657 For the \c{on_findButton_clicked()} slot, we extract the search string and
658 use the \l{http://doc.trolltech.com/qtextedit.html#find}{find()} function
659 to look for the search string within the text file. The code snippet below
660 further describes it:
662 \snippet examples/textfinder/textfinder.cpp 2
664 Once we have both these functions complete, we call \c{loadTextFile()} in
667 \snippet examples/textfinder/textfinder.cpp 3
669 The \c{on_findButton_clicked()} slot will be called automatically due to
673 QMetaObject::connectSlotsByName(TextFinder);
676 in the uic generated \c{ui_textfinder.h} file.
678 \section2 The Resource File
680 We require a resource file (\c{.qrc}) within which we will embed the input
681 text file. This can be any \c{.txt} file with a paragraph of text. To add
682 a resource file, right click on \gui{Resource Files} in the
683 \gui{Project Explorer} and select \gui{Add New File...}. You will see the
684 wizard dialog displayed below.
686 \image qtcreator-add-resource-wizard.png
688 Enter "textfinder" in the \gui{Name} field and use the given \gui{Path}.
689 Then, click \gui{Continue}.
691 \image qtcreator-add-resource-wizard2.png
693 On this page you can choose to which project you want to add the new file.
694 Make sure that \gui{Add to Project} is checked and
695 "TextFinder" is selected as the \gui{Project}, and click
698 Your resource file will now be displayed with the Resource Editor. Click
699 on the \gui{Add} drop down box and select \gui{Add Prefix}. The prefix we
700 require is just a slash (\c{/}). Click \gui{Add} again but this time,
701 select \gui{Add File}. Locate the text file you are going to use, we use
704 \image qtcreator-add-resource.png
706 The screenshot above shows what you can expect to see once you have added
707 the resource file successfully.
709 \section1 Compiling and Running Your Program
711 Now that you have all the necessary files, you can compile your program by
713 \inlineimage qtcreator-run.png
719 \contentspage index.html
720 \previouspage creator-writing-program.html
721 \page creator-version-control.html
722 \nextpage creator-navigation.html
724 \title Qt Creator and Version Control Systems
727 \caption Version control systems supported by Qt Creator
730 \i \l{http://git-scm.com/}
734 \i \l{http://subversion.tigris.org/}
738 \i \l{http://www.perforce.com}
739 \i Server version 2006.1 and later
742 \i \l{http://www.cvshome.org}
749 Qt Creator uses the version control system's command line clients to
750 access your repositories. To set it up, you must ensure that these command
751 line clients can be located via the \c{PATH} environment variable. You can
752 specify the path to the command line client's executable in the settings
753 pages that can be found under \gui{Options...} in the \gui{Tools} menu.
758 You can find the version control menu entries in a sub-menu of the
759 \gui{Tools} menu. The version control system displayed here is the system
760 that manages the current project.
762 Each version control system adds a pane to the \gui{Application Output}
763 panes within which it will log the commands it executes, prepended by a
764 timestamp and the relevant output.
766 \image qtcreator-vcs-pane.png
769 \section2 Addings Files
771 When you create a new file or a new project, the wizards will display page
772 requesting whether the files should be added to a version control system.
773 This depends on whether the parent directory or the project is already
774 under version control and the system supports the concept of adding files,
775 e.g., \bold{Perforce} and \bold{Subversion}. Alternatively, you can also
776 add files later on using the version control tool menus.
778 With \bold{git}, there is no concept of adding files. Instead, all modified
779 files must be \e{staged} for a commit.
782 \section2 Viewing Diff Output
784 All version control systems provide menu options to \e{diff} the current
785 file or project - comparing with the latest version stored in the
786 repository and displaying the differences. In Qt Creator, a diff is
787 displayed in a read-only editor. If the file is accessible, you can double
788 -click on a selected diff chunk and Qt Creator will open an editor
789 displaying the file, scrolled to the line in question.
791 \image qtcreator-vcs-diff.png
794 \section2 Viewing Versioning History and Change Details
796 The versioning history of a file can be displayed by selecting the
797 \gui{Log} (for \bold{git}) or \gui{Filelog} (for \bold{Perforce} and
798 \bold{Subversion}) option. Typically, the log output will contain the
799 date, the commit message, and a change or revision identifier. If you
800 click on the identifier, a description of the change including the diff
803 \image qtcreator-vcs-log.png
804 \image qtcreator-vcs-describe.png
807 \section2 Annotating Files
809 Annotation views are obtained by selecting \gui{Annotate} or \gui{Blame}.
810 This will display the lines of the file prepended by the change identifier
811 they originate from. Clicking on the change identifier shows a detailed
812 description of the file.
815 \section2 Committing Changes
817 Once you have finished making changes, you can submit them to the version
818 control system by choosing \gui{Commit} or \gui{Submit}. Qt Creator will
819 display a commit page containing a text editor, where you can enter your
820 commit message, and a checkable list of modified files to be included.
821 When you are done, click \gui{Commit} to start committing. In addition,
822 there is a \gui{Diff selected} button that brings up a diff view of the
823 files selected in the file list. Since the commit page is just another
824 editor, you can go back to it by closing the diff view. Alternatively, you
825 can view it from the editor combo box showing the \gui{Opened files}.
827 \image qtcreator-vcs-commit.png
830 \section2 Menu Entries Specific to git
832 The git sub-menu contains additional entries:
837 \i Stash local changes prior to executing a \bold{pull}.
840 \i Pull changes from the remote repository. If there are locally
841 modified files, you will be prompted to stash those changes.
844 \i Displays the branch dialog showing the local branches at the
845 top and remote branches at the bottom. To switch to the local
846 branch, simply double-click on it. Double-clicking on a remote
847 branch will first create a local branch with the same name that
848 tracks the remote branch, and then switch to it.
850 \image qtcreator-vcs-gitbranch.png
853 \section2 Common options
855 The \gui{Version Control/Common} settings page features common settings for
856 version control systems, such as commit message line wrapping and checking
859 \gui{Submit message checking script} is a script or program that can be
860 used to perform checks on the submit message before submitting. The submit
861 message is passed in as the script's first parameter. If there is an error,
862 the script should output a message on standard error and return a non-zero
865 \gui{User/alias configuration file} takes a file in mailmap format that
866 lists user names and aliases. For example:
869 Jon Doe <Jon.Doe@company.com>
870 Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
873 Notice that the second line specifies the alias \e{hm} and the
874 corresponding email address for \e{Hans Mustermann}. If the user/alias
875 configuration file is present, the submit editor will display a context
876 menu with \gui{Insert name...} that will pop up a dialog letting the user
879 \gui{User field configuration file} is a simple text file consisting of
880 lines specifying submit message fields that take user names, for example:
887 These fields will appear below the submit message. They provide completion
888 for the aliases/public user names specified in the
889 \e{User/alias configuration file} as well as a button that opens the
890 aforementioned user name dialog.
896 \contentspage index.html
897 \previouspage creator-version-control.html
898 \page creator-navigation.html
899 \nextpage creator-debugging.html
901 \title Navigating Quickly Around Your Code with Locator
903 With Qt Creator, navigating to different locations in your project or on
904 your disk, e.g., files, classes, methods, etc., is trivial using
905 \gui Locator -- a smart line edit at the bottom left of Qt Creator's
908 \image qtcreator-locator.png
910 Suppose you would like to open your project's \c{main.cpp} file, click on
911 \gui Locator or use \key{Ctrl+K} (Mac OS X: \key{Cmd+K}), type in the file
912 name and then press \key Return. The file will be opened in the editor.
913 You can also type part of a file name and use the wildcard characters
914 \c{*} and \c{?} to match \e{any} number of \e{any} characters. A list
915 of all files matching your criteria will be displayed.
917 \gui Locator not only allows you to navigate files on disk but also other
918 "locations", which are organized with \bold{Filters}. Currently there are
922 \o files anywhere on your hard disk (browsing through the file system),
923 \o files from a subdirectory structure defined by you,
924 \o files mentioned in your \c{.pro} files, such as source, header,
925 resource, and \c{.ui} files,
926 \o any open document,
927 \o class and method definitions in your project or anywhere referenced
929 \o help topics, including Qt's documentation, and,
930 \o a specific line in the document displayed on your editor,
934 Some of these filters require you to activate them by typing an assigned
935 \e prefix. This prefix is usually a single character followed by
936 \key{Space}. For example, to jump to the definition of the class
937 \l{http://doc.trolltech.com/qdatastream.html}{QDataStream}, type:
938 \key{Ctrl+K} (Mac OS X: \key{Cmd+K}) to activate \gui Locator.
939 Then type colon (\key{:}) followed by \key{Space} and the class name.
942 Below is a full list of \l{http://doc.trolltech.com/qdatastream.html}
943 {QDataStream} related output:
945 \image qtcreator-navigate-popup.png
948 Filters can be added to provide quick navigation around files in a
949 subdirectory structure defined by you. This way, you can acccess files you
950 need, that are not directly mentioned in your project. Click on
951 \image qtcreator-locator-magnify.png
952 and choose \gui{Configure...} from the menu displayed.
954 \image qtcreator-locator-customize.png
956 This displays the \gui Preferences dialog (\gui Options on Mac Os X) for
957 navigation filters. Click \gui Add to create a new filter. In the
958 \gui{Filter Configuration} dialog below, give your filter a name, select
959 your preferred directories, set file patterns with a comma separated list,
960 and specify a prefix string.
962 \image qtcreator-navigate-customfilter.png
964 After closing this dialog, \gui Locator will search the directories you
965 selected for files matching your file patterns, and the information will be
966 cached. Click \gui Refresh from the menu above to update the cached
969 The following table lists the filters currently available:
977 \o Go to a line in the current document
978 \o Ctrl+K, l, Space, and the line number
979 \o \image qtcreator-locator-line.png
981 \o Go to a symbol definition
982 \o Ctrl+K, :, Space, and the function name
983 \o \image qtcreator-locator-symbols.png
985 \o Go to a help topic
986 \o Ctrl+K, ?, Space, and the topic
987 \o \image qtcreator-locator-help.png
989 \o Go to an opened document
990 \o Ctrl+K, o, Space, and the document name.
991 \o \image qtcreator-locator-opendocs.png
993 \o Go to a file in the file system (browse the file system)
994 \o Ctrl+K, f, Space, and the file name.
995 \o \image qtcreator-locator-filesystem.png
997 \o Go to a file in any project currently loaded
998 \o Ctrl+K, a, Space, and the function name.
999 \o \image qtcreator-locator-files.png
1001 \o Go to a file in the current project
1002 \o Ctrl+K, p, Space, and the function name.
1003 \o \image qtcreator-locator-current-project.png
1005 \o Go to a class definition
1006 \o Ctrl+K, c, Space, and the class name.
1007 \o \image qtcreator-locator-classes.png
1009 \o Go to a method definition
1010 \o Ctrl+K, m, Space, and the class name.
1011 \o \image qtcreator-locator-methods.png
1014 \note By default, if you press \key{Ctrl+K} and do not use a prefix to
1015 specify a filter, three filters will be enabled: \c{o}, \c{l}, and \c{a}.
1017 \note On Mac OS X, use \key{Cmd+K} instead of \key{Ctrl+K}.
1023 \contentspage index.html
1024 \previouspage creator-navigation.html
1025 \page creator-session.html
1026 \nextpage creator-debugging.html
1028 \title Session Management in Qt Creator
1030 In Qt Creator, a session is a collection of:
1033 \o open projects together with their dependencies,
1035 \o breakpoints and watches, as well as
1039 When you run Qt Creator, you have a default session. You can create a new
1040 session using the \gui{Session Manager...} option, available in the
1041 \gui{File -> Session} menu.
1044 \image qtcreator-session-manager.png
1047 To switch between sessions, select \gui{File -> Session}. If you do not
1048 create and select any session, Qt Creator will always use the default
1051 \image qtcreator-session-menu.png
1053 When you launch Qt Creator, a list of your recent sessions will be
1054 displayed on the \gui{Welcome Screen}.
1056 \image qtcreator-welcome-session.png
1062 \contentspage index.html
1063 \previouspage creator-navigation.html
1064 \page creator-debugging.html
1065 \nextpage creator-cmake-support.html
1067 \title Debugging with Qt Creator
1070 \section1 Introduction
1072 Qt Creator does not have its own debugger. Instead, it provides a graphical
1073 frontend to various debugger engines:
1081 \o Linux, Unixes, Mac OS
1083 \o GNU Symbolic Debugger (gdb)
1087 \o GNU Symbolic Debugger (gdb)
1090 \o Microsoft Visual C++ Compiler
1091 \o Debugging Tools for Windows/Microsoft Console Debugger (CDB)
1094 The frontend allows you to
1095 step through a program line-by-line or instruction-by-instruction,
1096 interrupt running programs, set breakpoints, examine the contents of the
1097 call stack, local and global variables, etc.
1099 Within Qt Creator, the raw information provided by the engine is displayed
1100 in a clear and concise manner, simplifying the process of debugging.
1102 In addition to generic IDE functionality: stack view, views for locals and
1103 watchers, registers, etc, Qt Creator comes with additional features to make
1104 debugging Qt-based applications easy. The debugger frontend knows about the
1105 internal layout of several Qt classes such as QString, the QTL containers,
1106 and most importantly QObject (and classes derived from it), as well as
1107 most containers of the C++ Standard Library, and is therefore able to
1108 present their contents in a useful way.
1111 \section1 Debugger Engine Installation Notes
1119 \o Requires gdb version 6.8.
1121 \o Debugging Tools for Windows
1122 \o Using this engine requires you to install the
1123 \e{Debugging Tools for Windows}
1124 \l{http://www.microsoft.com/whdc/devtools/debugging/installx86.Mspx}{32-bit}
1126 \l{http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx}{64-bit}
1127 package (Version 6.11.1.404 for the 32-bit or the 64-bit version of Qt Creator, respectively),
1128 which is freely available for download from the
1129 \l{http://msdn.microsoft.com/en-us/default.aspx}
1130 {Microsoft Developer Network}.
1132 The pre-built \e{Qt SDK for Windows} will make use
1133 of the library if it is present on the system. When building Qt
1134 Creator using the Microsoft Visual C++ Compiler, the
1135 \c{"%ProgramFiles%\Debugging Tools for Windows"} path will be
1136 checked to ensure that all required header files are there.
1140 \section1 Interacting with the Debugger
1142 In \gui Debug mode, several dock widgets are used to interact with the
1143 program you are debugging. The frequently used dock widgets are visible by
1144 default; the rarely used ones are hidden. To change the default settings,
1145 select \gui Debug and then select \gui View.
1147 \image qtcreator-debug-view.png
1149 Here, you can lock or unlock the location of your views as well as display
1150 or hide them. Among the views you can display are \gui Breakpoints,
1151 \gui Disassembler, \gui Modules, \gui Registers, \gui Debugger, \gui Stack, and
1152 \gui Thread. The position of your dock widgets will be saved for future
1156 \section2 Breakpoints
1158 Breakpoints are shown in the \gui{Breakpoints} view which is enabled by
1159 by default. This view is also accessible when the debugger and the program
1160 being debugged is not running.
1162 A breakpoint represents a position or sets of positions in the code that,
1163 when executed, interrupts the program being debugged and passing the
1164 control to the user. The user is then free to examine the state of the
1165 interrupted program, or continue execution line-by-line or continuously.
1167 Typically, breakpoints are associated with a source code file and line, or
1168 the start of a function -- both allowed in Qt Creator.
1170 Also, the interruption of a program by a breakpoint can be restricted with
1173 You can set a breakpoint:
1176 \o At a particular line you want the program to stop -- click on the
1177 left margin or press \key F9 (\key F8 for Mac OS X).
1178 \o At a function that you want the program to interrupt -- enter the
1179 function's name in \gui{Set Breakpoint at Function...} under the
1183 You can remove a breakpoint:
1186 \o By clicking on the breakpoint marker in the text editor.
1187 \o By selecting the breakpoint in the breakpoint view and pressing
1189 \o By selecting \gui{Delete Breakpoint} from the breakpoint's context
1190 menu in the \gui Breakpoints view.
1193 Breakpoints can be set and deleted before the program has actually started
1194 running or while it is running under the debugger's control. Also,
1195 breakpoints are saved together with a session.
1200 To start a program under the debugger's control, select the \gui{Debug}
1201 menu and \gui{Start Debugging}, or simply press \key{F5}. Qt Creator then
1202 checks whether the compiled program is up-to-date, rebuilding it if
1203 necessary. The debugger then takes over and starts the program.
1205 \note Starting a program in the debugger can take considerable amount of
1206 time, typically in the range of several seconds to minutes if complex
1207 features (like QtWebKit) are used.
1209 Once the program starts running, it behaves as usual; performance-wise as
1210 well. The user can interrupt a running program by selecting
1211 \gui {Interrupt} from the \gui{Debug} menu. The program is automatically
1212 interrupted as soon as a breakpoint is hit.
1214 Once the program stops, Qt Creator:
1217 \o Retrieves data representing the call stack at the program's current
1219 \o Retrieves the contents of local variables.
1220 \o Examines \gui Watchers.
1221 \o Updates the \gui Registers, \gui Modules, and \gui Disassembler
1226 You can use the debugger views to examine the data in more detail.
1228 To finish debugging, Press \key{Shift+F5}. A line of code can be executed
1229 as a whole with \key F10; to execute a function or a sub-function, use
1230 \key F11. Alternatively, you can continue running the program with \key F5.
1231 It is possible to continue executing your program until the current
1232 function completes or jump to an arbitrary position in the current
1238 When the program being debugged is interrupted, Qt Creator displays the
1239 nested function calls leading to the current position as a \e call stack
1240 trace. This stack trace is built up from \e{call stack frames}, each
1241 representing a particular function. For each function, Qt Creator will try
1242 to retrieve the file name and line number of the corresponding source
1243 files. This data is shown in the \gui Stack view.
1245 \image qtcreator-debug-stack.png
1247 Since the call stack leading to the current position may originate or go
1248 through code for which no debug information is available, not all stack
1249 frames will have corresponding source locations. These frames will be
1250 grayed out in the \gui Stack view.
1252 If you click on a frame with a known source location, the text editor will
1253 jump to the corresponding location and update the \gui{Locals and Watchers}
1254 view, making it seem like the program was interrupted before entering the
1260 If a multi-threaded program is interrupted, the \gui Thread view or the
1261 combobox named \gui Thread in the debugger's status bar can be used to
1262 switch from one thread to another. The \gui Stack view will adjust itself
1266 \section2 Locals and Watchers
1268 Whenever a program stops under the control of the debugger, it retrieves
1269 information about the topmost stack frame and displays it in the
1270 \gui{Locals and Watchers} view. This typically includes information about
1271 parameters of the function in that frame as well as the local variables.
1273 Compound variables of struct or class type will be displayed as
1274 "expandable" in the view. Click on the "+" to expand the entry and show
1275 all members. Together with the display of value and type, the user can
1276 examine and traverse the low-level layout of an object's data.
1284 \i Gdb, and therefore Qt Creator's debugger works for optimized
1285 builds on Linux and Mac OS X. However, optimization may lead
1286 to re-ordering of instructions or sometimes even complete
1287 removal of some local variables. In this case, the
1288 \gui{Locals and Watchers} view may show unexpected data.
1291 \i The debug information provided by gcc does not include enough
1292 information about the time when a variable is initialized.
1293 Therefore, Qt Creator can not tell whether the contents of a
1294 local variable contains "real data", or "initial noise". If a
1295 QObject appears uninitialized, its value will be reported as
1296 "out of scope". However, not all uninitialized objects can be
1301 The \gui{Locals and Watchers} view also provides access to the most
1302 powerful feature of the debugger: comprehensive display of data belonging
1303 to Qt's basic objects. To enable this feature, select \gui{Use
1304 debugging helper} from the \gui Debug menu.The
1305 \gui{Locals and Watchers} view will be re-organized to provide a high-level
1306 view of the objects. For example, in case of QObject, instead of displaying
1307 a pointer to some private data structure, you will see a list of children,
1310 Similarly, instead of displaying many pointers and integers, Qt Creator's
1311 debugger will display the contents of a QHash or QMap in an orderly manner.
1312 Also, the debugger will display access data for QFileInfo and provide
1313 access to the "real" contents of QVariant.
1315 The \gui{Locals and Watchers} view can be used to change the contents of
1316 variables of simple data types such as \c int or \c float when the program
1317 is interrupted. To do so, click on the \gui Value column, modify the value
1318 with the inplace editor, and hit \key Enter (or \key Return).
1320 \note The set of watched items is saved within your session.
1325 By default, the \gui Modules view is hidden as it is only useful with the
1326 experimental delayed loaing of debug information feature. You can turn
1327 this feature on by selecting \gui{Fast Debugger Start}
1330 With this feature, debug information from the Qt library itself is not
1331 loaded when the application starts up, thereby reducing the startup times
1332 for some applications. You can then use the \gui Modules view to manually
1333 load this information, if required.
1335 \note In this scenario, some breakpoints may not be triggered by the
1339 \section2 Disassembler View and Registers View
1341 By default, both the \gui Disassembler and \gui Registers view are hidden.
1342 The \gui Disassembler view displays disassembled code for the current
1343 function; the \gui Registers view displays the current state of the CPU's
1344 registers. Both views are useful for low-level commands such as
1345 \gui{Step Single Instruction} and \gui{Step Over Single Instruction}.
1347 \section1 Debugging Helper Library
1349 While debugging Qt Creator dynamically loads a helper library into your
1350 program. This helper library enables Qt Creator to pretty print Qt and STL
1351 types. The Qt SDK package already contains a prebuilt debugging helper
1352 library. To create a debugging helper library, select the \gui{Options}
1353 from the \gui{Tools} menu, and go to the \gui{Qt/Qt Versions} pane. As the
1354 internal layout of qt can change between versions, the debugging helper
1355 library is built for each Qt version.
1358 \section1 A Walkthrough for the Debugger Frontend
1360 In our \l{Writing a Simple Program with Qt Creator}{TextFinder} example, we
1361 read a text file into a QString and then display it with a QTextEdit.
1362 Suppose, you would like to look at this QString, \c{line}, and see what
1363 data it actually stores. Follow the steps described below to place a
1364 breakpoint and view the QString object's data.
1368 \i \inlineimage qtcreator-setting-breakpoint1.png
1369 \i \bold{Setting a Breakpoint}
1371 First, we set a breakpoint on the line where we invoke
1372 \l{http://doc.trolltech.com/qtextedit.html#plainText-prop}{setPlainText()}
1373 by clicking between the line number and the window border. Then, select
1374 \gui{Start Debugging} from the \gui{Debug} menu or press \key{F5}.
1377 Breakpoints are visible in the \gui{Breakpoints} view, shown below, in
1378 \gui{Debug} mode. If you wish to remove a breakpoint, simply right-click on
1379 it and select \gui{Delete breakpoint} from the context menu.
1381 \image qtcreator-setting-breakpoint2.png
1383 To view the contents of \c{line}, take a look at the \gui{Locals and
1386 \image qtcreator-watcher.png
1388 Suppose we modify our \c{on_findButton_clicked()} function to move back to
1389 the start of the document and continue searching once the cursor hits the
1390 end of the document. Adding this functionality can be done with the code
1394 void TextFinder::on_findButton_clicked()
1396 QString searchString = ui->lineEdit->text();
1398 QTextDocument *document = ui->textEdit->document();
1399 QTextCursor cursor = ui->textEdit->textCursor();
1400 cursor = document->find(searchString, cursor,
1401 QTextDocument::FindWholeWords);
1402 ui->textEdit->setTextCursor(cursor);
1404 bool found = cursor.isNull();
1406 if (!found && previouslyFound) {
1407 int ret = QMessageBox::question(this, tr("End of Document"),
1408 tr("I have reached the end of the document. Would you like "
1409 "me to start searching from the beginning of the document?"),
1410 QMessageBox::Yes | QMessageBox::No, QMessageBox::Yes);
1412 if (ret == QMessageBox::Yes) {
1413 cursor = document->find(searchString,
1414 QTextDocument::FindWholeWords);
1415 ui->textEdit->setTextCursor(cursor);
1419 previouslyFound = found;
1423 However, if you compile and run this code, the application will not work
1424 correctly due to a logic error. To locate this logic error, you can step
1425 through the code using the following buttons:
1427 \image qtcreator-debugging-buttons.png
1434 \contentspage index.html
1435 \previouspage creator-debugging.html
1436 \page creator-cmake-support.html
1437 \nextpage creator-generic-projects.html
1439 \title CMake Support in Qt Creator
1441 Since Qt Creator 1.1, support for \c CMake project files is available.
1442 Qt Creator 1.3 supports the Microsoft Toolchain if the cmake version
1445 \section1 Opening CMake Projects
1447 To open a \c CMake project select \gui Open from the \gui File menu and
1448 select the \c{CMakeLists.txt} file from your \c CMake project. A wizard
1449 will guide you with the rest of the process. If the \c CMake project does
1450 not have an in-place build, Qt Creator lets you specify the directory in
1451 which the project is built (shadow build).
1453 \image qtcreator-cmake-import-wizard1.png
1455 The screenshot below shows how you can specify command line arguments to
1456 \c CMake for your project.
1458 \image qtcreator-cmake-import-wizard2.png
1460 Normally, there is no need to pass any command line arguments for projects
1461 that are already built, as \c CMake caches that information.
1464 \section1 Building CMake Projects
1466 Qt Creator builds \c CMake Projects by running \c make, \c mingw32-make, or
1467 \c nmake depending on your platform. The build errors and warnings are
1468 parsed and displayed in the \gui{Build Issues} output pane.
1470 By default Qt Creator builds the \e{all} target. You can specify which
1471 targets to build in \gui{Project} mode, under \gui{Build Settings}.
1473 \image qtcreator-cmake-build-settings.png
1475 Qt Creator supports multiple build configurations. Also, the build
1476 directory can be modified after the initial import.
1478 \section1 Running CMake Projects
1479 Qt Creator automatically adds \gui{Run Configurations} for all targets
1480 specified in the \c CMake project file.
1482 Known issues for the current version can be found
1483 \l{Known Issues of Version 1.2.94}{here}.
1488 \contentspage index.html
1489 \previouspage creator-cmake-support.html
1490 \page creator-generic-projects.html
1491 \nextpage creator-qt-for-symbian.html
1493 \title Support for Generic Projects in Qt Creator
1495 Since Qt Creator 1.1, generic projects are supported, in addition to
1496 \c qmake projects. In other words, you can import existing projects that do
1497 not use \c qmake or \c CMake and Qt Creator will simply ignore your build
1500 This feature lets you use Qt Creator as a code editor. You can change the
1501 way your project is built by modifying the \c make command under
1502 \gui{Build Settings} in the \gui{Projects} mode.
1504 For a generic project, you have to manually specify which files belong to
1505 your project and which include directories/defines you want to pass to your
1509 \section2 Specifying Files
1511 The list of files for a generic project is specified in the \c{.files}
1512 file. When you first create a generic project, Qt Creator will add any
1513 files it recognizes to your project. To add or remove files later, simply
1514 edit the \c{.files} file in Qt Creator. Your project tree will be refreshed
1515 when you save this file. You can also add or remove files using the context
1516 menu in the project tree.
1518 If you frequently need to update the \c{.files} file, we recommend the use
1519 of a small script that will update the files for you. Currently, if the
1520 file is modified externally, Qt Creator must be restarted for the changes
1524 \section2 Specifying Include Paths
1526 The include paths are specified in the \c{.includes} file, one include
1527 path per line. The paths can be either absolute or relative to the
1530 \section2 Specifying Defines
1532 The defines are specified in the \c{.config} file. This file is a regular
1533 C++ file, prepended to all your source files when they are being parsed.
1534 However, you should only use it to add lines like the following:
1541 \section2 Creating a Run Configuration
1543 Qt Creator cannot automatically determine which executable it should run.
1544 To set up a custom executable run configuration in the \gui Projects mode,
1545 use the \bold{Add} button. Here you can specify the name, executable, and
1546 some optional arguments. By default, the working directory is
1547 \c{$BUILDDIR} which should work fine.
1551 \contentspage index.html
1552 \previouspage creator-generic-projects.html
1553 \page creator-qt-for-symbian.html
1554 \nextpage creator-external-library-handling.html
1556 \title Development of Qt for Symbian Based Applications
1558 Qt Creator 1.3 comes with preliminary support for development of
1559 applications using Qt for the Symbian Platform.
1561 \e{Note that this is highly experimental, and not intended for production use.
1562 The primary aim is to allow Symbian developers to familiarize themselves with Qt Creator
1563 and provide feedback that will help us improve Symbian support in future versions of
1566 Please provide us with feedback, using the mailing list or IRC, as described on the
1567 \l{http://qt.gitorious.org/qt-creator/pages/Home}{Qt Creator Development Wiki}.
1569 \section2 Getting Started
1571 You need the following software installed on your PC.
1572 Only Windows development is supported.
1575 \o \l{http://www.forum.nokia.com/main/resources/tools_and_sdks/S60SDK/}
1576 {S60 Platform SDK 3rd Edition FP1 or higher}
1577 \o \l{http://www.forum.nokia.com/main/resources/technologies/openc_cpp/}
1578 {Open C/C++ v1.6.0 or higher.} Install this to all S60 SDKs you plan to use Qt with.
1579 This is included in the Qt for Symbian binary installers.
1580 \o Either the GCCE Arm Toolchain that is included in the S60 Platform SDKs, or
1581 RVCT 2.2 [build 686] or later (which is not available free of charge).
1582 Your environment needs to find the compiler in the PATH.
1583 \o Qt for Symbian 4.6.0, installed into the S60 SDKs you want to use.
1587 And for deploying and running applications on the device
1589 \o The Nokia USB drivers that come e.g. with PC Suite.
1590 \o The \l{http://tools.ext.nokia.com/trk/}{App TRK} application for your device.
1593 Running Qt based applications on real devices requires the following packages to be installed on
1594 your device. The packages can be found in the S60 SDK where you installed Open C/C++:
1596 \o nokia_plugin\\openc\\s60opencsis\\pips_s60_\<version\>.sis
1597 \o nokia_plugin\\openc\\s60opencsis\\openc_ssl_s60_\<version\>.sis
1598 \o nokia_plugin\\opencpp\\s60opencppsis\\stdcpp_s60_\<version\>.sis
1601 If you want to run your applications in the Symbian Emulator, you also need to install
1602 Carbide.c++ v2.0.0 or higher.
1604 \section2 Setting up Qt Creator
1606 When you run Qt Creator after installing the S60 Platform SDK and Qt for Symbian,
1607 the installed SDKs and their corresponding Qt versions are automatically detected.
1608 For each detected S60 SDK with Qt, a special entry is made in the Qt Version Management settings
1609 \gui{Tools -> Options... -> Qt4 -> Qt Versions}.
1611 \e{Note that if you manually add a Qt version for Symbian, you must
1612 also manually specify the S60 SDK to use for this version.}
1614 \image qtcreator-qt4-qtversions-win-symbian.png
1616 If you want to run your applications in the Symbian Emulator, you need to point Qt Creator
1617 to the Metrowerks Compiler that you want to use, by setting the \gui{Carbide Directory}
1618 of the Qt version to the corresponding Carbide.c++ installation directory.
1620 You can check what S60 SDKs and corresponding Qt versions are found in the
1621 \gui{Tools -> Options... -> Qt4 -> S60 SDKs} preference page.
1623 \image qtcreator-qt4-s60sdks.png
1625 \section2 Building your Project
1627 After installing all the prerequisites and checking the setup in Qt Creator as described
1628 above, you need to make some settings for your project.
1629 \e{Note that the only supported build system for Qt for Symbian applications in Qt Creator
1632 Before you can build your project for the Symbian Platform you need to create build
1633 configurations for it.
1634 Open \gui{Projects mode} and make sure that your project is selected for editing in
1635 \gui{Edit Project Settings for Project ...}. Add debug and release build configurations
1636 for the Symbian target by selecting the corresponding Qt version from the build configuration
1639 \image qtcreator-symbian-add-buildconfiguration.png
1641 The created build configurations default to using the GCCE tool chain. If you want to build
1642 for the device using RVCT, or for the Symbian Emulator using WINSCW, change the tool chain in
1643 the \gui{General} section of the build configuration settings (press the \gui{Show Details}
1646 Now you can switch to building your project for the device by selecting one of the
1647 new build configurations as the active configuration at the top of \gui{Projects mode}.
1649 \image qtcreator-symbian-change-buildconfiguration.png
1651 \section2 Running your Project
1653 \section3 Running your Project in the Emulator
1655 Similar to the build configuration setup for your project you need to create a run
1656 configuration for running your project in the Symbian emulator: Switch to \gui{Projects mode}
1657 and in \gui{Run Settings} you will find the \gui{Add -> YourApplication in Symbian Emulator}
1660 \image qtcreator-symbian-add-run-in-emulator.png
1662 To start your project in the emulator select this run configuration as the active configuration
1663 at the top of \gui{Projects mode} and press the run button.
1665 \image qtcreator-symbian-change-run-in-emulator.png
1667 \section3 Running your Project on the Device
1669 To run your project on a real Symbian device, just add another run configuration in
1670 \gui{Projects mode} via \gui{Run Settings}, \gui{Add -> YourApplication on Symbian Device} button.
1672 \image qtcreator-symbian-add-runconfiguration.png
1674 \image qtcreator-symbian-details-runconfiguration.png
1676 In the details of the run configuration you can specify a certificate to use, and
1677 select one of the devices that you have currently attached to your computer.
1678 The only connection mode supported at the moment is USB in \e{PC Suite} mode.
1679 For actually running your application on the device, you need to set the device run configuration
1680 as the active configuration at the top of \gui{Projects mode}.
1681 Start the \gui{App TRK} application on your device and press the run button to create
1682 a package for your application, deploy, install and run it automatically on your device.
1684 \image qtcreator-symbian-change-runconfiguration.png
1686 \section2 Troubleshooting
1688 When something goes wrong check the following things:
1690 \o Did you build your application with a Qt version for Symbian?
1691 \o Are the settings for the Qt version you use to build your project correct? Check the
1692 path to the S60 SDK, and if you need to specify the path to your compiler tool chain.
1693 \o Is the emulator/device run configuration selected as the active run configuration?
1694 \o Did you build using the right toolchain, i. e. WINSCW for running in the Emulator,
1695 GCCE or RVCT for running on the device?
1696 \o If the emulator process could not be started, try closing Creator and starting the
1697 application directly from your file manager. Having done this, Creator should be
1698 able to run your projects in the Emulator.
1699 \o Is the device connected via USB in \e{PC Suite} mode?
1700 \o Is App TRK running on the device, using the USB connection, and does it have status
1702 \o Is your device detected and selected in the run configuration details?
1705 If neither of this helps to solve your problem, search the qt-creator@trolltech.com
1706 mailinglist archives or provide feedback to us via the methods described on the
1707 \l{http://qt.gitorious.org/qt-creator/pages/Home}{Qt Creator Development Wiki}.
1712 \contentspage index.html
1713 \previouspage creator-qt-for-symbian.html
1714 \page creator-external-library-handling.html
1715 \nextpage creator-tips.html
1717 \title Handling External Libraries
1719 The ability to recognize external libraries is not only important for the
1720 underlying build system, but also for Qt Creator itself. This ability
1721 allows Qt Creator to support code completion and syntax highlighting for
1722 external libraries as if they were part of the current project or the Qt
1725 The procedure of adding a library to a project, depends on the type of
1726 project, which influences the build system used. The following sections
1727 describe the the procedure required for each project type.
1730 \section1 QMake Projects (the default)
1732 Open your project file (\c{.pro}) from the \gui{Projects} pane. Then,
1733 follow the guidelines in the
1734 \l{http://doc.trolltech.com/latest/make-project-files.html#declaring-other-libraries}
1735 {Declaring other Libraries} section of the Qt documentation.
1737 If your project successfully builds and links against the external library,
1738 syntax completion and highlighting should work.
1741 \section1 CMake Projects
1743 In CMake, libraries are usually detected using the \c{FIND_PACKAGE()}
1744 macro. A couple of them are already being shipped with CMake, they can be
1745 found in the \c{Modules} directory of your CMake installation. If you
1746 provide libraries on your own, you will need to provide your own
1747 \c{FindFoo.cmake} file. Refer to the
1748 \l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}
1751 As with \c qmake projects, syntax completion and highlighting should work
1752 if you can sucessfully build and link against the external library.
1755 \section1 Generic Projects
1757 If you import a project using the \e{Generic Projects} function, Qt Creator
1758 will create a file called \c{<projectname>.includes} in your project root
1759 directory. This file contains all project subdirectories which Qt Creator
1760 could find relevant headers for. Simply add your include pathes here.
1762 In \gui{Generic Project} mode, Qt Creator will not modify any project
1763 settings, so the above is merely a hint for code completion and syntax
1769 \contentspage index.html
1770 \previouspage creator-external-library-handling.html
1771 \page creator-tips.html
1772 \nextpage creator-keyboard-shortcuts.html
1774 \title Tips and Tricks
1776 \bold{Quickly Switching between Modes}
1778 You can quickly switch between modes by pressing \key{Ctrl+1},
1779 \key{Ctrl+2}, and so on.
1781 \bold{Keyboard Shortcuts}
1783 Qt Creator provides a lot of useful keyboard shortcuts. Some useful
1784 shortcuts can be found \l{Keyboard Shortcuts}{here}.
1786 \bold{Running Qt Creator from the Command Line}
1788 You can start Qt Creator from a command prompt with the name of an existing
1789 session or \c{.pro} file by giving the name as argument on the command
1792 \bold{Show and Hide the Sidebar}
1794 You can show and hide the the sidebar in \gui Edit and \gui Debug mode by
1795 clicking on the corresponding icon, or by pressing \key{Alt+0} (Mac OS X:
1798 \bold{Display Signals and Slots}
1800 If you have an instance of a class that is derived from QObject, and you
1801 would like to find all other objects connected to one of your object's
1802 slots using Qt's signals and slots mechanism -- you can enable
1803 \gui{Use Custom Display for Qt Objects} feature under the \gui Debug menu.
1805 In the \gui{Locals and Watchers} view, expand the object's entry and open
1806 the slot in the \e slots subitem. The objects connected to this slot are
1807 exposed as children of the slot. This method works with signals too.
1809 \bold{Display Low Level Data}
1811 If special debugging of Qt objects fails due to data corruption within the
1812 debugged objects, you can switch the debugging helpers off in the
1813 \gui{Debugger -> Debugging Helper} options dialog.
1814 This will make the low-level structures visible again.
1819 \contentspage index.html
1820 \previouspage creator-tips.html
1821 \page creator-keyboard-shortcuts.html
1822 \nextpage creator-glossary.html
1824 \title Keyboard Shortcuts
1826 Qt Creator provides various keyboard shortcuts to aid in the development
1827 process. These shortcuts are listed in the table below:
1835 \o Activate \gui Welcome mode
1838 \o Activate \gui Edit mode
1841 \o Activate \gui Debug mode
1844 \o Activate \gui Projects mode
1847 \o Activate \gui Help mode
1850 \o Activate \gui Output mode
1859 \o Go back to the code editor (\gui Edit mode: The first press
1860 gives the editor focus, without closing secondary windows; the
1861 second press closes all secondary windows. \gui Debug mode or
1862 \gui Help mode: Switch to \gui Edit mode.)
1868 \o Navigate between pages
1869 \o Alt + Left, Alt + Right
1877 \o Toggle code declaration and definition
1880 \o Toggle header file and source file
1884 \o Alt + 0 / Cmd + 0
1886 \o Toggle \gui{Build Issues} pane
1887 \o Alt + 1 / Cmd + 1
1889 \o Toggle \gui{Search Results} pane
1890 \o Alt + 2 / Cmd + 2
1892 \o Toggle \gui{Application Output} pane
1893 \o Alt + 3 / Cmd + 3
1895 \o Toggle \gui{Compile Output} pane
1896 \o Alt + 4 / Cmd + 4
1902 \contentspage index.html
1903 \previouspage creator-keyboard-shortcuts.html
1904 \page creator-glossary.html
1905 \nextpage creator-supported-platforms.html
1917 Qt in PATH
1919 \target glossary-system-qt
1921 version for the \c qmake command found in your \c PATH
1922 environment variable.
1929 \target glossary-default-qt
1930 \o The version of Qt configured in \gui{Tools -> Options -> Qt 4
1931 -> Default Qt Version}. This is the Qt version used by your
1932 new projects. It defaults to the Auto-detected Qt.
1939 \target glossary-project-qt
1940 \o The version of Qt configured in \gui{Build&Run -> Build
1941 Settings -> Build Configurations}. This is the Qt version that
1942 is actually used by a particular project. It defaults to
1950 \target glossary-shadow-build
1951 \o Shadow building means building a project in a separate
1952 directory, the \e{build directory}. The build directory is
1953 different from the source directory. One of the benefits of
1954 shadow building is that it keeps your source directory clean.
1955 Shadow building is the best practice if you need many build
1956 configurations for a single set of source.
1963 \contentspage index.html
1964 \previouspage creator-glossary.html
1965 \page creator-supported-platforms.html
1966 \nextpage creator-known-issues.html
1968 \title Supported Platforms
1970 Qt Creator is available in binary packages for the following platforms:
1973 \o Windows XP Service Pack 2
1975 \o (K)Ubuntu Linux 5.04
1976 \o (K)Ubuntu Linux 7.04 32bit and 64 bit
1977 \o Mac OS 10.4 and later
1980 \note Building the sources requires \bold{Qt 4.6.0} or later.
1985 \contentspage index.html
1986 \previouspage creator-supported-platforms.html
1987 \page creator-known-issues.html
1988 \nextpage creator-acknowledgements.html
1992 There are some known issues with Qt Creator.
1993 The development team is aware of those, there is no need to report them as bug.
1995 \section1 Known Issues of Version 1.2.94
1998 \o Debugging Helper do not work while doing On Device Debugging.
2000 \o QML Preview (Run Project) only works if build against Qt with
2003 \o Setting breakpoints in code that is compiled into the binary more
2004 than once does not work.
2006 \o On Linux and Windows, Installing Qt with one user account and
2007 then using it with another requires other users to manually set
2008 the Qt version. On Windows, setting the MinGW location is
2009 required as well. The same applies to the location of GDB for Symbian.
2010 A workaround is to copy %APPDATA%/Nokia/qtcreator.ini (Windows) or
2011 $HOME/.config/Nokia/QtCreator.ini (Linux) from the directory
2012 of the user who installed Creator to the other user.
2013 This issues does not exist on Mac OS X.
2017 \section1 Known Issues of Version 1.2.0 and 1.2.1
2020 \o Gdb on Windows may not work if the 'Embassy \reg Security Center' software
2021 by 'Wave \reg Systems' is installed and active (causing crashes in \c{vxvault.dll)}).
2023 \o Only simple data types (POD) work in the Watch Window of CDB.
2025 \o Qt Creator uses SQLite for storing some of its settings. SQLite is
2026 known to have problems with certain NFS servers (most notably the
2027 nfs-user-server 2.2beta), since they can lock up the application
2028 when it tries to lock the database. If your home directory is on an
2029 NFS share and you encounter this issue, one option would be to
2030 switch to the nfs-kernel-server, or create a symlink so that the
2031 settings are stored locally.
2034 \section1 Known Issues of Version 1.1.0
2037 \o Paths or file names containing spaces or special characters, e.g.,
2038 colons, dollar signs, hash marks etc. may cause difficulties. This
2039 is because some of the tools Qt Creator uses in the background have
2040 restrictions on the characters allowed in file and directory names.
2041 To be on the safe side, we recommend creating projects and project
2042 items with names consisting of plain characters, numbers,
2043 underscores, and hyphens.
2045 \o \c{.pro} files are reformatted if files have been added or removed.
2046 Whitespace is not preserved.
2048 \o There is no IDE support for adding files to include (\c .pri) files.
2050 \o There is no IDE support for adding/removing sub-projects. Project
2051 hierarchies (SUBDIRS template) have to be created manually.
2053 \o The file system sidebar does not update automatically. As a
2054 workaround, switch to another directory and then back.
2056 \o Loading KDE4 designer plugins breaks the style in KDE < 4.2.1
2057 due to a bug in KDE.
2059 \o The DEFINES and INCLUDES set in \c{.pro} files are not dealt with
2060 on a file-specific level. Because of this, handling of DEFINES has
2061 been disabled completely. Also the \c{.qmake.cache} is not being
2062 parsed. In general, the \c{.pro} file parser is incomplete and
2063 problems are still to be expected.
2065 \o Code completion for generated UI header files is updated only
2068 \o Code completion does not support typedefs for nested classes.
2070 \o There is a kernel bug essentially making debugging unreliable on
2071 2.6.24 kernels for i386 (which is, unfortunately, the default on
2073 \l{https://bugs.launchpad.net/ubuntu/+source/gdb/+bug/230315/} for
2074 details. The only solution to this problem is to boot another
2077 \o Gdb may take long to load debugging symbols, especially from large
2078 libraries like \c libQtWebKit. Starting the debugging module can
2079 take up to several minutes without visible progress.
2081 \o Setting breakpoints in files that do not have unique absolute
2082 paths may fail. For example, remounting parts of a file system
2083 using the --bind mount option.
2085 \o There is no syntax highlighting for \c CMake project files.
2087 \o Project files included from \c{CMakeLists.txt} are not shown in the
2090 \o Using the Visual Studio Compiler with \c CMake is unsupported.
2092 \o Creating new \c CMake projects with Qt Creator is unsupported.
2094 \o Having more than one build directory for \c CMake is not supported.
2096 \o Changing the build directory for \c CMake after the initial import
2103 \contentspage index.html
2104 \previouspage creator-known-issues.html
2105 \page creator-acknowledgements.html
2107 \title Acknowledgements
2109 \section1 Third-party Components
2111 Qt Creator contains the following third-party components:
2114 \o \bold{Open Source front-end for C++ (license MIT)}, enhanced for use in
2116 Roberto Raggi <roberto.raggi@gmail.com>\br
2117 QtCreator/src/shared/cplusplus