1 /****************************************************************************
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
11 ** Licensees holding valid Qt Commercial licenses may use this file in
12 ** accordance with the Qt Commercial License Agreement provided with the
13 ** Software or, alternatively, in accordance with the terms contained in a
14 ** written agreement between you and Nokia.
16 ** GNU Free Documentation License
17 ** Alternatively, this file may be used under the terms of the GNU Free
18 ** Documentation License version 1.3 as published by the Free Software
19 ** Foundation and appearing in the file included in the packaging of this
22 ** If you have questions regarding the use of this file, please contact
23 ** Nokia at qt-info@nokia.com.
26 ****************************************************************************/
28 // **********************************************************************
29 // NOTE: the sections are not ordered by their logical order to avoid
30 // reshuffling the file each time the index order changes (i.e., often).
31 // Run the fixnavi.pl script to adjust the links to the index order.
32 // **********************************************************************
36 \contentspage{index.html}{Qt Creator}
38 \nextpage creator-overview.html
40 \title Qt Creator Manual
42 \section1 Version 2.1.81
44 Qt Creator provides a cross-platform, complete integrated development
45 environment (IDE) for application developers to create applications for
46 multiple desktop and mobile device platforms. It is available for Linux,
47 Mac OS X and Windows operating systems. For more information, see
48 \l{Operating Systems and Supported Platforms}.
50 \note Please report bugs and suggestions to the
51 \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}.
52 You can also join the Qt Creator mailing list. To subscribe,
53 send a message with the word \e subscribe to
54 \l{mailto:qt-creator-request@trolltech.com}
55 {qt-creator-request@trolltech.com}. For more information about Qt mailing
56 lists, visit \l{http://lists.trolltech.com}{http://lists.trolltech.com}.
59 <img border="0" style="float:right;" src="images/qtcreator-screenshots.png" />
63 \o \l{Introducing Qt Creator}
64 \o \l{Operating Systems and Supported Platforms}
65 \o \l{Qt Creator User Interface}
66 \o \l{Getting Started}
68 \o \l{Building and Running an Example Application}
69 \o \l{Creating a Qt C++ Application}
70 \o \l{Creating a Mobile Application with Nokia Qt SDK}
71 \o \l{Creating a Qt Quick Application}
73 \o \l{Managing Projects}
75 \o \l{Creating a Project}
76 \o \l{Setting Up a qmake Project}
77 \o \l{Adding Libraries to qmake Projects}
78 \o \l{Setting Up a CMake Project}
79 \o \l{Setting Up a Generic Project}
80 \o \l{Setting Up Development Environment for Maemo}
81 \o \l{Setting Up Development Environment for Symbian}
82 \o \l{Managing Sessions}
83 \o \l{Adding New Custom Wizards}
85 \o \l{Using the Editor}
87 \o \l{Finding and Replacing}
89 \o \l{Using Qt Quick Toolbars}
90 \o \l{Searching With the Locator}
91 \o \l{Pasting and Fetching Code Snippets}
92 \o \l{Configuring the Editor}
93 \o \l{Using FakeVim Mode}
94 \o \l{Using an External Editor}
96 \o \l{Developing Application UI}
98 \o \l{Optimizing Applications for Mobile Devices}
99 \o \l{Adding Qt Designer Plugins}
101 \o \l{Developing Qt Quick Applications}
103 \o \l {Creating Qt Quick Projects}
104 \o \l {Creating Components}
105 \o \l {Creating Screens}
106 \o \l {Animating Screens}
107 \o \l {Adding User Interaction Methods}
108 \o \l {Implementing Application Logic}
112 \o \l{Building and Running Applications}
114 \o \l{Building for and Running on Multiple Targets}
115 \o \l{Specifying Build Settings}
116 \o \l{Specifying Run Settings}
117 \o \l{Specifying Editor Settings}
118 \o \l{Specifying Dependencies}
123 \o \l{Debugging the Example Application}
124 \o \l{Interacting with the Debugger}
125 \o \l{Setting Up Debugger}
126 \o \l{Debugger Modes of Operation}
127 \o \l{Using Debugging Helpers}
129 \o \l{Using the Maemo Emulator}
130 \o \l{Using Version Control Systems}
131 \o \l{Creating Task List Files}
132 \o \l{Using Command Line Options}
134 \o \l{Tips and Tricks}
135 \o \l{Keyboard Shortcuts}
138 \o \l{Acknowledgements}
144 \contentspage index.html
145 \previouspage index.html
146 \page creator-overview.html
147 \nextpage creator-os-supported-platforms.html
149 \title Introducing Qt Creator
151 Qt Creator is an integrated development environment (IDE) that provides you with
152 tools to design and develop complex applications for multiple desktop and mobile
155 \image qtcreator-overview.png "Qt Creator overview"
157 \section1 Cross-platform Development
159 One of the major advantages of Qt Creator is that it allows a team of developers
160 to share a project across different development platforms with a common tool
161 for development and debugging.
163 The recommended way to build a project is to use a version control system.
164 Store and edit only project source files and the .pro and .pri files (for qmake)
165 or CMakeLists.txt and *.cmake files (for CMake). Do not store
166 files generated by the build system or Qt Creator, such as makefiles,
167 .pro.user, and object files. Other approaches are possible,
168 but we recommend that you do not use network resources, for example.
170 Qt Creator allows you to specify separate build settings
171 for each development platform. By default, \l{glossary-shadow-build}{shadow builds} are used to
172 keep the build specific files separate from the source.
174 You can create separate versions of project files to keep platform-dependent
175 code separate. You can use qmake
176 \l{http://qt.nokia.com/doc/4.7/qmake-tutorial.html#adding-platform-specific-source-files}{scopes}
177 to select the file to process depending on which platform qmake is run on.
179 Items such as open files, breakpoints, and watches are stored in
180 sessions. They are not considered to be part of the
181 information shared across platforms.
183 Qt Creator is integrated with cross-platform systems for build automation:
184 qmake and CMake. In addition, you can import generic projects that do not use qmake
185 or CMake, and specify that Qt Creator ignores your build system.
187 In addition to Qt libraries, you can link your application to other
188 libraries, such as system libraries or your own libraries. Further, your
189 own libraries might link to other libraries. To be able to compile your
190 project, you must add the libraries to your project. This also enables
191 code completion and syntax highlighting for the libraries.
192 The procedure of adding a library to a project depends on the the build
195 Qt Creator provides support for building and running Qt applications for
196 desktop environment and mobile devices. When you install the Nokia Qt SDK,
197 the build and run settings for the Maemo and Symbian targets are set up
198 automatically. However, you need to install and configure some additional software
201 \note The only supported build system for mobile applications in Qt
204 Once your mobile application is ready, you can test it in the Qt Simulator.
205 You can also connect Maemo and Symbian devices to your development PC and
206 debug applications on the devices. After you have tested the application,
207 you can deploy it on mobile devices.
209 Developing applications for mobile devices is different from developing
210 desktop applications. For more information, see
211 \l{Optimizing Applications for Mobile Devices}.
215 But why do you need projects? To be able to build and run applications,
216 Qt Creator needs the same information as a compiler would need. This information
217 is specified in the project build and run settings.
219 Creating a project allows you to:
223 \o Group files together
225 \o Add custom build steps
227 \o Include forms and resource files
229 \o Specify settings for running applications
233 You can either create a project from scratch or import an existing
234 project. Qt Creator generates all the necessary files, depending on the type of
235 project you create. For example, if you choose to create a graphical user
236 interface (GUI) application, Qt Creator generates an empty .ui file
237 that you can modify with the integrated \QD.
239 Qt Creator is integrated with cross-platform systems for build automation: qmake and
240 CMake. In addition, you can import generic projects that do not use qmake or CMake,
241 and specify that Qt Creator ignores your build system.
245 Qt Creator comes with a code editor and two integrated visual editors for designing
247 graphical user interfaces (GUIs) from Qt widgets.
249 \section2 Code Editor
251 As an IDE, Qt Creator differs from a text editor in that it knows how to build and run
252 applications. It understands the C++ and QML languages as code, not just as plain text. This allows
257 \o Enable you to write well formatted code
259 \o Anticipate what you are going to write and complete the code
261 \o Display inline error and warning messages
263 \o Enable you to semantically navigate to classes, functions, and symbols
265 \o Provide you with context-sensitive help on classes, functions, and symbols
267 \o Rename symbols in an intelligent way, so that other symbols with the same name
268 that belong to other scopes are not renamed
270 \o Show you the locations in code where a function is declared or called
274 \section2 UI Designer
276 Qt Creator provides two integrated visual editors, \QD and \QMLD.
278 \QD is a tool for designing and building graphical user interfaces (GUIs) from
279 Qt widgets. You can compose and customize your widgets or dialogs and test
280 them using different styles and resolutions.
282 Widgets and forms created with \QD are integrated seamlessly with programmed code,
283 using the Qt signals and slots mechanism, that lets you easily assign behavior to
284 graphical elements. All properties set in \QD can be changed dynamically within the code.
285 Furthermore, features like widget promotion and custom plugins allow you to use your
286 own widgets with \QD.
288 UIs that use widgets are clearly structured and enforce a platform look and feel,
289 which makes them useful for traditional applications. However, they are static, and
290 do not fully make use of the large high-resolution screens, touch input, and significant
291 graphics power that are becoming common in portable consumer devices, such as mobile
292 phones, media players, set-top boxes, and netbooks.
294 \QMLD allows you to easily develop animations by using a declarative programming
295 language called \l {http://doc.qt.nokia.com/4.7/qtquick.html}{QML}.
296 In QML, a user interface is specified as a tree of objects with properties.
298 You use a visual editor to create items, screens, and applications, as well as define changes
299 in their state, transitions from one state to another, and user actions that change the
300 states. \QMLD generates the necessary code for you.
302 You can use Qt or JavaScript to implement the application logic.
306 You can use the code editor to write code in Qt C++ or in the
307 \l {http://doc.qt.nokia.com/4.7/qtquick.html}{QML} declarative
308 programming language.
312 You can use QML to build highly dynamic, custom user interfaces from a rich set
313 of QML elements. Qt Quick helps programmers and designers collaborate to build the
314 fluid user interfaces that are becoming common in portable consumer devices, such as
315 mobile phones, media players, set-top boxes and netbooks.
317 QML is an extension to JavaScript, that provides a mechanism to declaratively build
318 an object tree of QML elements. QML improves the integration between JavaScript and
319 Qt's existing QObject based type system, adds support for automatic property bindings
320 and provides network transparency at the language level.
324 Qt Creator provides support for building and running Qt applications for
325 desktop environment (Windows, Linux, and Mac OS) and mobile devices (Symbian, Maemo,
326 and MeeGo). Build settings allow you to quickly switch between build targets.
328 When you build an application for a mobile device target with a device
329 connected to the development PC, Qt Creator generates an installation package,
330 installs in on the device, and executes it.
332 You can publish the installation packages on the \l{https://publish.ovi.com/info/}{Ovi Store}.
333 For Symbian devices, the packages must be signed.
337 Qt Creator is integrated with a set of helpful tools, such as version control
338 systems and Qt Simulator.
340 \section2 Version Control Systems
342 Qt Creator uses the version control system's command line clients to access
343 your repositories. The following version control systems are supported:
359 The functions available to you in Qt Creator depend on the version control
360 system. Basic functions are available for all the supported systems. They include
361 comparing files with the latest versions stored in the repository and displaying the
362 differences, viewing versioning history and change details, annotating files,
363 and committing and reverting changes.
365 \section2 Qt Simulator
367 You can use the Qt Simulator to test Qt applications that are intended
368 for mobile devices in an environment similar to that of the device. You
369 can change the information that the device has about its configuration
372 The Qt Simulator is installed as part of the Nokia Qt SDK. After it is
373 installed, you can select it as a build target in Qt Creator.
377 Qt Creator does not include a debugger. It provides a debugger plugin that acts
378 as an interface between the Qt Creator core and external native debuggers:
382 \o GNU Symbolic Debugger (gdb)
384 \o Microsoft Console Debugger (CDB)
386 \o internal Java Script debugger
390 You can use the Qt Creator \gui Debug mode to inspect the state of your
391 application while debugging. You can interact with the debugger in several
392 ways, including the following:
395 \o Go through a program line-by-line or instruction-by-instruction.
396 \o Interrupt running programs.
398 \o Examine the contents of the call stack.
399 \o Examine and modify registers and memory contents of
400 the debugged program.
401 \o Examine and modify registers and memory contents of
402 local and global variables.
403 \o Examine the list of loaded shared libraries.
404 \o Create snapshots of the current state of the debugged program
405 and re-examine them later.
408 Qt Creator displays the raw information provided by the native debuggers
409 in a clear and concise manner with the goal to simplify the debugging process
410 as much as possible without losing the power of the native debuggers.
412 In addition to the generic IDE functionality provided by stack view, views for
413 locals and watchers, registers, and so on, Qt Creator includes
414 features to make debugging Qt-based applications easy. The debugger
415 plugin understands the internal layout of several Qt classes, for
416 example, QString, the Qt containers, and most importantly QObject
417 (and classes derived from it), as well as most containers of the C++
418 Standard Library and some gcc and Symbian extensions. This
419 deeper understanding is used to present objects of such classes in
422 If you install Qt Creator as part of a Qt SDK, the GNU Symbolic Debugger
423 is installed automatically and you should be ready to start debugging after
424 you create a new project. However, you can change the setup to use debugging
425 tools for Windows, for example.
427 You can connect mobile devices to your development PC and debug processes
428 running on the devices.
433 \contentspage index.html
434 \previouspage creator-overview.html
435 \page creator-os-supported-platforms.html
436 \nextpage creator-quick-tour.html
438 \title Operating Systems and Supported Platforms
440 \section1 Operating Systems
442 Qt Creator is available in binary packages for the following operating
445 \o Windows XP Service Pack 2
447 \o (K)Ubuntu Linux 7.04 (32-bit and 64-bit) or later, with the following:
454 \o libfontconfig1-dev
463 \o If you are using QtOpenGL, libgl-dev and libglu-dev
465 \o Mac OS 10.5 or later with the following:
467 \o Xcode tools for your Mac OS X version available from your Mac
468 OS X installation DVDs or at \l http://developer.apple.com.
472 \omit ## Are the Xcode tools still needed separately? \endomit
474 \section1 Build Environment
476 To build Qt Creator itself from the source, you need:
479 \o On Windows, MinGW 4.4 or Microsoft Visual Studio 2008
482 \section1 Supported Mobile Device Platforms
483 You can develop applications for the following mobile device
490 \o Maemo and Maemo Application Development and Debugging Environment (MADDE)
494 The following table summarizes operating system support for building
495 applications for mobile device platforms.
499 \o {1,3} Operating system
525 \contentspage index.html
526 \previouspage creator-os-supported-platforms.html
527 \page creator-quick-tour.html
528 \nextpage creator-getting-started.html
530 \title Qt Creator User Interface
532 \image qtcreator-breakdown.png
534 When you start Qt Creator, it opens to the \gui Welcome mode, where you can:
538 \o Open tutorials and example projects
540 \o View tips and hints on using Qt Creator
542 \o Create and open projects
544 \o Send feedback to the development team
546 \o Open recent sessions and projects
548 \o Read news from the Qt labs
554 You can use the mode selector to change to another Qt Creator mode.
556 Qt Creator has been localized into several languages. If the system language
557 is one of the supported languages, it is automatically selected. To change
558 the language, select \gui {Tools > Options > Environment} and select a language
559 in the \gui Language field. The change takes effect after you restart Qt Creator.
561 \section1 Qt Creator Modes
563 The mode selector allows you to quickly switch between tasks such as
564 editing project and source files, designing application UIs,
565 configuring how projects are built and
566 executed, and debugging your applications. To change modes, click the
567 icons, or use the \l{keyboard-shortcuts}{corresponding keyboard shortcut}.
569 You can use Qt Creator in the following modes:
572 \o \gui{\l{Using the Editor}{Edit}} mode for editing project and source files.
573 \o \gui{\l{Developing Application UI}{Design}} mode for designing and developing
574 application user interfaces. This mode is available for UI files (.ui or
576 \o \gui{\l{Debugging}{Debug}} mode for inspecting the state of your program while
578 \o \gui{\l{Managing Projects}{Projects}} mode for configuring project building and
579 execution. This mode is available when a project is open.
580 \o \gui{\l{Getting Help}{Help}} mode for viewing Qt documentation.
583 Certain actions in Qt Creator trigger a mode change. Clicking on
584 \gui {Debug} > \gui {Start Debugging} > \gui {Start Debugging}
585 automatically switches to \gui {Debug} mode.
588 \section1 Browsing Project Contents
590 The sidebar is available in the \gui Edit and \gui Debug modes.
591 Use the sidebar to browse projects, files, and bookmarks, and to view
593 \image qtcreator-sidebar.png
595 You can select the content of the sidebar in the sidebar menu:
597 \o \gui Projects shows a list of projects open in the current
599 \o \gui{Open Documents} shows currently open files.
600 \o \gui Bookmarks shows all bookmarks for the current session.
601 \o \gui{File System} shows all files in the currently selected
603 \o \gui {Class View} shows the class hierarchy of the currently
605 \o \gui Outline shows the element hierarchy of a QML file.
606 \o \gui {Type Hierarchy} shows the base classes of a class. For
607 more information, see \l{Viewing Type Hierarchy}.
611 You can change the view of the sidebar in the following ways:
613 \o To toggle the sidebar, click \inlineimage qtcreator-togglebutton.png
614 or press \key Alt+0 (\key Cmd+0 on Mac OS X).
615 \o To split the sidebar, click \inlineimage qtcreator-splitbar.png
616 . Select new content to view in the split view.
617 \o To close a sidebar view, click
618 \inlineimage qtcreator-closesidebar.png
622 The additional options in each view are described in the following
625 \section2 Viewing Project Files
627 The sidebar displays projects in a project tree. The project tree contains
628 a list of all projects open in the current session. The files for each
629 project are grouped according to their file type.
631 You can use the project tree in the following ways:
633 \o To bring up a context menu containing the actions most commonly
634 needed right-click an item in the project tree.
635 For example, through the menu of the project root directory you can,
636 among other actions, build, re-build, clean and run the project.
637 \o To hide the categories and sort project files alphabetically, click
638 \inlineimage qtcreator-filter.png
639 and select \gui{Simplify Tree}.
640 \o To hide source files which are automatically generated by the build
641 system, during a build, click \inlineimage qtcreator-filter.png
642 and select \gui{Hide Generated Files}.
643 \o To keep the position in the project tree synchronized with the file
644 currently opened in the editor, click
645 \inlineimage qtcreator-synchronizefocus.png
647 \o To see the absolute path of a file, move the mouse pointer over the
651 \section2 Viewing the File System
653 If you cannot see a file in the \gui Projects view, switch to the
654 \gui {File System} view, which shows all the files in the file system.
656 To keep the position in the tree synchronized with the file
657 opened in the editor, click
658 \inlineimage qtcreator-synchronizefocus.png
661 \section2 Viewing the Class Hierarchy
663 The \gui {Class View} shows the class hierarchy of the currently
664 open projects. To organize the view by subprojects, click
665 \inlineimage qtcreator-show-subprojects.png
668 \section2 Viewing QML Elements
670 The \gui Outline view shows the element hierarchy in a QML file.
674 \o To see a complete list of all bindings, click
675 \inlineimage qtcreator-filter.png
676 and select \gui{Show All Bindings}.
678 \o To keep the position in the view synchronized with the element
679 selected in the editor, click
680 \inlineimage qtcreator-synchronizefocus.png
685 \section1 Viewing Output
687 The task pane in Qt Creator can display one of the following panes:
689 \o \gui{Build Issues}
690 \o \gui{Search Results}
691 \o \gui{Application Output}
692 \o \gui{Compile Output}
693 \o \gui{General Messages}
694 \o \gui{Version Control}
697 Output panes are available in all \l{Qt Creator modes}{modes}.
698 Click the name of an output pane to open the pane. To maximize
699 an open output pane, click the \gui {Maximize Output Pane} button
700 or press \key {Alt+9}.
702 To search within the \gui{Application Output} and \gui{Compile Output}
703 panes, press \key {Ctrl+F} when the pane is active. Enter search
704 criteria in the \gui Find field and click the left and right arrows to
705 search down and up in the pane.
707 To open the \gui{General Messages} and \gui{Version Control}
708 panes, select \gui {Window > Output Panes}.
711 \section2 Build Issues
713 The \gui{Build Issues} pane provides a list of errors and warnings
714 encountered during a build. The pane filters out irrelevant output from
715 the build tools and presents the issues in an organized way.
717 Right-clicking on a line brings up a context menu with options to copy
718 the contents and to show a version control annotation view of the
719 line that causes the error message.
721 \image qtcreator-build-issues.png
723 To view task lists in the \gui{Build Issues} pane, click
724 \inlineimage qtcreator-filter.png
725 and select \gui{My Tasks}. Entries from a task list file (.tasks) are
726 imported to the pane. Press \key F6 and \key Shift+F6 to jump from one issue
729 For more information about creating task files, see \l{Creating Task List Files}.
731 \section2 Search Results
733 The \gui{Search Results} pane displays the results for global searches,
734 for example, searching within a current document, files on disk, or all
737 The figure below shows an example search result for all
738 occurrences of \c textfinder within the \c "/TextFinder" directory.
740 \image qtcreator-search-pane.png
743 \section2 Application Output
745 The \gui{Application Output} pane displays the status of a program when
746 it is executed, and the debug output.
748 The figure below shows an example output from qDebug().
750 \image qtcreator-application-output.png
753 \section2 Compile Output
755 The \gui{Compile Output} pane provides all output from the compiler.
756 The \gui{Compile Output} is a more detailed version of information
757 displayed in the \gui{Build Issues} pane.
759 \image qtcreator-compile-pane.png
761 \section1 Navigating with Keyboard
763 Qt Creator caters not only to developers who are used to using the mouse,
764 but also to developers who are more comfortable with the keyboard. A wide
765 range of \l{keyboard-shortcuts}{keyboard} and
766 \l{Searching With the Locator}{navigation} shortcuts are available to help
767 speed up the process of developing your application.
773 \contentspage index.html
774 \previouspage creator-task-lists.html
775 \page creator-help.html
776 \nextpage creator-tips.html
780 Qt Creator comes fully integrated with Qt documentation and
781 examples using the Qt Help plugin.
783 \o To view documentation, switch to \gui Help mode.
784 \o To obtain context sensitive help, move the text cursor to a Qt class
785 or function and press \key F1. The documentation is displayed in a
786 pane next to the code editor, or, if there is not enough vertical
787 space, in the fullscreen \gui Help mode.
789 \image qtcreator-context-sensitive-help.png
791 \o To select and configure how the documentation is displayed in the
792 \gui Help mode, select \gui Tools > \gui Options... > \gui Help.
795 \section1 Finding Information in Qt Documentation
797 Qt Creator, Qt SDK, Nokia Qt SDK and other Qt deliverables contain documentation
798 as .qch files. All the documentation is accessible in the \gui Help mode.
800 To find information in the documentation, select:
804 \o \gui Bookmarks to view a list of pages on which you have added bookmarks.
806 \o \gui Contents to see all the documentation installed on the development
807 PC and to browse the documentation contents.
809 \o \gui Index to find information based on a list of keywords in all the
812 \o \gui {Open Pages} to view a list of currently open documentation pages.
814 \o \gui Search to search from all the installed documents.
818 \section2 Adding Bookmarks to Help Pages
820 You can add bookmarks to useful help pages to easily find them later
821 in the \gui Bookmarks view. You can either use the page title as the
822 bookmark or change it to any text. You can organize the bookmarks in
825 \image qtcreator-help-add-bookmark-dlg.png "Add Bookmark dialog"
827 To add a bookmark to an open help page:
832 \inlineimage qtcreator-help-add-bookmark.png
833 (\gui {Add Bookmark}) button on the toolbar.
835 \o In the \gui {Add Bookmark} dialog, click \gui OK to save the
836 page title as a bookmark in the \gui Bookmarks folder.
840 To import and export bookmarks, select \gui {Tools > Options... > Help >
841 General Settings > Import} or \gui Export.
843 \section1 Adding External Documentation
845 You can display external documentation in the \gui Help mode.
846 To augment or replace the documentation that ships with Qt Creator and Qt:
848 \o Create a .qch file from your documentation.
850 For information on how to prepare your documentation and create a
852 \l{http://doc.qt.nokia.com/4.7/qthelp-framework.html}{The Qt Help Framework}.
853 \o To add the .qch file to Qt Creator, select \gui Tools >
854 \gui Options... > \gui Help > \gui Documentation > \gui Add.
857 \section1 Detaching the Help Window
859 By default, context-sensitive help is opened in a window next to the
860 code editor when you press \key F1. If there is not enough vertical
861 space, the help opens in the full-screen help mode.
863 You can specify that the help always opens in full-screen mode or
864 is detached to an external window. Select \gui {Tools > Options... > Help >
865 General Settings} and specify settings for displaying context-sensitive help
866 in the \gui {On context help} field. To detach the help window, select
867 \gui {Always Show Help in External Window}.
869 You can select the help page to open upon startup in the \gui {Home Page}
872 \section1 Using Documentation Filters
874 You can filter the documents displayed in the \gui Help mode to find
875 relevant information faster. Select from a list of filters in the
876 \gui {Filtered by} field. The contents of the \gui Index and \gui Contents
877 pane in the sidebar change accordingly.
879 \image qtcreator-help-filters.png "Help filters"
881 You can modify the filters to include external documentation, for example,
882 or you can define your own filters. To construct filters, you can use the
883 filter attributes that are specified in the documentation. Each document
884 contains at least one filter attribute. If several documents contain the
885 same filter attribute, such as \c tools, you can use that attribute to
886 include all those documents.
892 \o Select \gui {Tools > Options... > Help > Filters > Add}.
894 \o Enter a name for the filter and press \gui {OK}.
896 \o In \gui Attributes, select the documents that you want to include
899 \image qtcreator-help-filter-attributes.png "Help filter attributes"
903 \o In the \gui Help mode, select the filter in the \gui {Filtered by}
904 field to see the filtered documentation in the sidebar.
908 To modify filters, select a filter in \gui Filters, select the attributes,
909 and then click \gui Apply.
911 To remove filters, select them in \gui Filters, and click \gui Remove.
917 \contentspage index.html
918 \previouspage creator-editor-external.html
919 \page creator-design-mode.html
920 \nextpage creator-usability.html
922 \title Developing Application UI
924 You can use the integrated \QD to design and build graphical user interfaces (GUIs) from
925 Qt widgets. You can compose and customize your widgets or dialogs and test
926 them using different styles and resolutions.
928 Widgets and forms created with \QD are integrated seamlessly with programmed code,
929 using the Qt signals and slots mechanism, that lets you easily assign behavior to
930 graphical elements. All properties set in \QD can be changed dynamically within the code.
931 Furthermore, features like widget promotion and custom plugins allow you to use your
932 own widgets with \QD.
934 UIs that use widgets are clearly structured and enforce a platform look and feel,
935 which makes them useful for traditional applications. However, they are static, and
936 do not fully make use of the large high-resolution screens, touch input, and significant
937 graphics power that are becoming common in portable consumer devices, such as mobile
938 phones, media players, set-top boxes, and netbooks.
940 You can easily develop animations by using a declarative programming
941 language called \l {http://doc.qt.nokia.com/4.7/qtquick.html}{QML}.
942 In QML, a user interface is specified as a tree of objects with properties.
943 You can edit QML code in the code editor. You
944 can use Qt or JavaScript to implement the application logic.
946 The integration includes project management and code completion.
948 \section1 Using Qt Designer
950 Qt Creator automatically opens all .ui files in \QD.
952 \image qtcreator-formedit.png
954 To change the layout of \QD user interface elements:
956 \o Select \gui Tools > \gui{Form Editor} > \gui Views >
959 When this option is unchecked, you can change the layout.
960 \o Click the header of an element and drag the element to a new
964 To change \QD properties, select \gui Tools > \gui Options... >
967 \o Set the class properties and code generation preferences in \gui
969 \o Set an additional folder for saving templates in \gui{Template
971 \o Set the grid settings and preview preferences in \gui Forms. To
972 preview your form with skins, enable \gui{Print/Preview
973 Configuration} and select your skin. Otherwise default preview
976 To preview the settings, select \gui Tools > \gui{Form Editor} >
977 \gui Preview, or press \key Alt+Shift+R.
978 \o To specify embedded device profiles, such as style, font, and screen
979 resolution, select \gui{Embedded Design}.
982 To switch between forms and code, use \key Shift+F4.
984 For more information on \QD, see
985 \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
987 \section1 Using Qt Quick Designer
989 You can edit .qml files in the visual \QMLD editor or in the
992 In \gui Projects, double-click a .qml file to open it in the code
993 editor. Then select the \gui {Design} mode to edit the file in the
996 \note The visual \QMLD editor is provided as an experimental plugin that you must
997 enable to be able to edit QML files in the \gui Design mode. Enabling the
998 visual editor can negatively affect the overall stability of Qt Creator.
1000 To enable or disable the \QMLD visual editor, select
1001 \gui {Help > About Plugins... > Qt Quick > QmlDesigner}. You must restart Qt Creator
1002 to enable or disable the visual editor.
1004 \image qmldesigner-visual-editor.png "Visual editor"
1006 Use the visual editor panes to manage your project:
1010 \o \gui {Navigator} pane displays the items in the scene. You can
1011 show and hide items to focus on specific parts of the application.
1013 \o \gui {Library} pane displays lists of predefined \gui {Items} and
1014 imported \gui {Resources} that you can use to design applications. The
1015 images and other files that you copy to the project folder appear in the
1016 \gui {Resources} pane.
1018 \o \gui {Properties} pane displays the properties of the selected component.
1019 You can also change the properties in the code editor.
1021 \o \gui {State} pane displays the different states of the component. To add
1022 states, click the empty slot. Then modify the new state in the editor.
1023 In the code editor, you can see the changes recorded as changes to
1032 \contentspage index.html
1033 \previouspage creator-project-wizards.html
1034 \page creator-editor-using.html
1035 \nextpage creator-editor-finding.html
1037 \title Using the Editor
1039 Qt Creator's code editor is designed to aid you in creating, editing and
1040 navigating code. Qt Creator's code editor is fully equipped with syntax
1041 checking, code completion, context sensitive help and in-line error
1042 indicators while you are typing.
1044 \section1 Using the Editor Toolbar
1046 The editor toolbar is located at the top of the editor view. The editor
1047 toolbar is context sensitive and shows items relevant to the file currently
1050 \image qtcreator-editortoolbar-symbols.png
1052 Use the toolbar to navigate between open files and symbols in use.
1053 To browse forward or backward through your location history, click
1054 \inlineimage qtcreator-back.png
1055 and \inlineimage qtcreator-forward.png
1058 To go to any open file, select it from the \gui{Open files} drop-down menu.
1059 Right-click the menu title and select \gui {Copy Full Path to Clipboard} to
1060 copy the path and name of the current file to the clipboard.
1062 To jump to any symbol used in the current file, select it from the
1063 \gui Symbols drop-down menu. By default, the symbols are displayed in the
1064 order in which they appear in the file. Right-click the menu title and select
1065 \gui {Sort Alphabetically} to arrange the symbols in alphabetic order.
1067 \section1 Splitting the Editor View
1069 Split the editor view when you want to work on and view multiple files on
1072 \image qtcreator-spliteditorview.png
1074 You can split the editor view in the following ways:
1076 \o To split the editor view into a top and bottom view, select
1077 \gui Window > \gui Split or press \key{Ctrl+E, 2}.
1079 Split command creates views below the currently active editor view.
1080 \o To split the editor view into adjacent views, select
1081 \gui Window > \gui{Split Side by Side} or press
1084 Side by side split command creates views to the right of the
1085 currently active editor view.
1088 To move between split views, select \gui Window >
1089 \gui{Go to Next Split} or press \key{Ctrl+E, O}.
1091 To remove a split view, place the cursor within the view you want to
1092 remove and select \gui Window > \gui{Remove Current Split} or press
1093 \key{Ctrl+E, 0}. To remove all but the currently selected split view,
1094 select \gui Window > \gui{Remove All Splits} or press \key{Ctrl+E, 1}.
1097 \section1 Highlighting and Folding Blocks
1099 Use block highlighting to visually separate parts of the code that belong
1100 together. For example, when you place the cursor within the braces,
1101 the code enclosed in braces is highlighted.
1103 \image qtcreator-blockhighlighting.png
1105 To enable block highlighting, select \gui Tools > \gui{Options...} >
1106 \gui{Text Editor} > \gui Display > \gui{Highlight blocks}.
1108 Use the folding markers to collapse and expand blocks of code within
1109 braces. Click the folding marker to collapse or expand a block. In the
1110 figure above, the folding markers are located between the line number and
1113 To show the folding markers, select \gui Tools > \gui{Options...} >
1114 \gui{Text Editor} > \gui Display > \gui{Display folding markers}. This
1115 option is enabled by default.
1117 When the cursor is on a brace, the matching brace is animated
1118 by default. To turn off the animation and just highlight the block and
1119 the braces, select \gui {Tools > Options... > Text Editor > Display} and
1120 deselect \gui {Animate matching parentheses}.
1123 \section1 Checking Code Syntax
1125 As you write code Qt Creator checks code syntax. When Qt Creator spots a
1126 syntax error in your code it underlines it and shows error details when you
1127 move the mouse pointer over the error.
1129 \o Syntax errors are underlined in red.
1131 In the following figure, a semicolon is missing at the end of the
1134 \image qtcreator-syntaxerror.png
1135 \o Semantic errors and warnings are underlined in olive.
1137 In the following figure, the type is unknown.
1139 \image qtcreator-semanticerror.png
1143 \section1 Completing Code
1145 Qt Creator understands the code as code, not just as plain text. This
1146 allows it to help you to write well formatted code and to anticipate
1147 what you are going to write and complete the code.
1148 The code completion differs somewhat depending on whether you write Qt code or QML code.
1150 \section2 Completing Qt Code
1152 As you write code, Qt Creator provides a list of context-sensitive
1153 suggestions to the statement currently under your cursor.
1155 \image qtcreator-codecompletion.png
1157 To open the list of suggestions at any time, press \key{Ctrl+Space}.
1158 If only one option is available, Qt Creator inserts it automatically.
1160 When completion is invoked manually, Qt Creator completes the common prefix
1161 of the list of suggestions. This is especially useful for classes with
1162 several similarly named members. To disable this functionality, uncheck
1163 \gui{Autocomplete common prefix} in the code completion preferences.
1164 Select \gui Tools > \gui{Options...} > \gui{Text Editor} > \gui Completion.
1166 By default, code completion considers only the first letter case-sensitive.
1167 To apply full or no case-sensitivity, select the option in the
1168 \gui {Case-sensitivity} field.
1170 The following table lists available types for code completion and icon
1178 \i \inlineimage completion/class.png
1181 \i \inlineimage completion/enum.png
1184 \i \inlineimage completion/enumerator.png
1185 \i An enumerator (value of an enum)
1187 \i \inlineimage completion/func.png
1190 \i \inlineimage completion/func_priv.png
1191 \i A private function
1193 \i \inlineimage completion/func_prot.png
1194 \i A protected function
1196 \i \inlineimage completion/var.png
1199 \i \inlineimage completion/var_priv.png
1200 \i A private variable
1202 \i \inlineimage completion/var_prot.png
1203 \i A protected variable
1205 \i \inlineimage completion/signal.png
1208 \i \inlineimage completion/slot.png
1211 \i \inlineimage completion/slot_priv.png
1214 \i \inlineimage completion/slot_prot.png
1217 \i \inlineimage completion/keyword.png
1220 \i \inlineimage completion/macro.png
1223 \i \inlineimage completion/namespace.png
1227 \section2 Completing QML Code
1229 As you write QML code, Qt Creator suggests properties, IDs, and code
1230 snippets to complete the code. The snippets can consist of multiple
1231 fields that you specify values for. Select an item in the list and press
1232 \key Tab or \key Enter to complete the code. Press \key Tab to
1233 move between the fields and specify values for them.
1235 \image qmldesigner-code-completion.png "Completing QML code"
1237 \section1 Using Bookmarks
1239 To insert or delete a bookmark right-click the line number and select
1240 \gui{Toggle Bookmark} or press \key{Ctrl+M}.
1242 \image qtcreator-togglebookmark.png
1244 To go to previous bookmark in the current session, press \key{Ctrl+,}.
1246 To go to next bookmark in the current session, press \key{Ctrl+.}.
1249 \section1 Moving to Symbol Definition or Declaration
1251 In Qt Creator you can move directly to the definition or the declaration of
1252 a symbol by holding the \key Ctrl and clicking the symbol.
1254 To enable this moving function, in \gui Tools > \gui{Options...} >
1255 \gui{Text Editor} > \gui Behavior, select \gui{Enable mouse navigation}.
1257 You can also select the symbol and press \key F2, or right-click the symbol
1258 and select \gui {Follow Symbol Under Cursor} to move to its definition or declaration.
1259 This is supported for namespaces, classes, methods, variables, include statements,
1262 To switch between the definition and declaration of a symbol, press \key {Shift+F2}
1263 or right-click the symbol and select \gui {Switch Between Method Declaration/Definition}.
1265 \section1 Viewing Type Hierarchy
1267 To view the base classes of a class, right-click the class and select
1268 \gui {Open Type Hierarchy} or press \key {Ctrl+Shift+T}.
1270 \section1 Using Update Code Model
1272 To refresh the internal information in Qt Creator pertaining to your code,
1273 select \gui{Tools} > \gui{C++} > \gui{Update Code Model}.
1275 \note In Qt Creator indexing updates the code automatically. Use
1276 \gui{Update Code Model} only as an emergency command.
1282 \contentspage index.html
1283 \previouspage creator-editor-locator.html
1284 \page creator-editor-codepasting.html
1285 \nextpage creator-editor-options.html
1287 \title Pasting and Fetching Code Snippets
1289 In Qt Creator, you can paste snippets of code to a server or fetch
1290 snippets of code from the server. To paste and fetch snippets of code,
1291 Qt Creator uses the following:
1294 \o \gui{Pastebin.Com}
1295 \o \gui{Pastebin.Ca}
1298 To configure the server, select \gui{Tools} > \gui{Options...} >
1301 To paste a snippet of code onto the server, select \gui{Tools} >
1302 \gui{Code Pasting} > \gui{Paste Snippet...} or press \key{Alt+C,Alt+P}.
1304 To fetch a snippet of code from the server, select \gui{Tools} >
1305 \gui{Code Pasting} > \gui{Fetch Snippet...} or press \key{Alt+C,Alt+F}.
1307 \note To use \gui{Pastebin.Com}, configure the domain
1308 prefix in \gui{Tools} > \gui{Options...} > \gui{Code Pasting} >
1311 For example, you might ask colleagues to review a change that you plan to
1312 submit to a version control system. If you use the Git version control system,
1313 you can create a \e{diff} view by selecting \gui{Tools} > \gui{Git} >
1314 \gui{Diff Repository}. You can then upload its contents to the server by choosing
1315 \gui{Tools} > \gui{Code Pasting} > \gui{Paste Snippet...}. The reviewers can retrieve
1316 the code snippet by selecting \gui{Tools} > \gui{Code Pasting} > \gui{Fetch Snippet...}.
1317 If they have the project currently opened in Qt Creator, they can apply and test
1318 the change by choosing \gui{Tools} > \gui{Git} > \gui{Apply Patch}.
1324 \contentspage index.html
1325 \previouspage creator-editor-options.html
1326 \page creator-editor-fakevim.html
1327 \nextpage creator-editor-external.html
1329 \title Using FakeVim Mode
1331 In the \gui{FakeVim} mode, you can run the main editor in a manner similar
1332 to the Vim editor. To run the editor in the \gui{FakeVim} mode, select
1333 \gui{Edit} > \gui{Advanced} > \gui{Use Vim-style Editing} or press
1336 In the \gui{FakeVim} mode, most keystrokes in the main editor will be
1337 intercepted and interpreted in a way that resembles Vim. Documentation for
1338 Vim is not included in Qt Creator. For more information on using Vim,
1339 see \l{http://www.vim.org/docs.php}{Documentation} on the Vim web site.
1341 To map commands entered on the \gui{FakeVim} command line to actions of the
1342 Qt Creator core, select \gui{Tools} > \gui{Options...} > \gui{FakeVim} >
1343 \gui{Ex Command Mapping}.
1345 To make changes to the Vim-style settings, select \gui{Tools} >
1346 \gui{Options...} > \gui FakeVim > \gui{General}.
1348 To use a Vim-style color scheme, select \gui {Tools > Options... >
1349 Text Editor > Fonts & Color}. In the \gui {Color Scheme} list, select
1352 To quit the FakeVim mode, click \gui {Quit FakeVim} or press
1359 \contentspage index.html
1360 \previouspage creator-editor-fakevim.html
1361 \page creator-editor-external.html
1362 \nextpage creator-design-mode.html
1364 \title Using an External Editor
1366 To open the file you are currently viewing in an external editor, select
1367 \gui Edit > \gui Advanced > \gui{Open in External Editor}.
1369 To use the external editor of your choice:
1371 \o Add the editor path to the \c{PATH} environment variable of your
1373 \o In Qt Creator select \gui Tools > \gui Options... >
1374 \gui Environment > \gui General.
1375 \o In \gui{External editor} enter the name of the application followed
1376 by \key Space and \tt{\bold %f}. For example, to open the file in
1377 Smultron, enter \tt{\bold{smultron %f}}.
1379 To further define how to open the file in the external editor, you
1380 can use the following variables separated by a space:
1382 \o Current line number \tt{\bold %l}
1383 \o Current column number \tt{\bold %c}
1384 \o Editor's x position on the screen \tt{\bold %x}
1385 \o Editor's y position on the screen \tt{\bold %y}
1386 \o Editor's width in pixels \tt{\bold %w}
1387 \o Editor's height in pixels \tt{\bold %h}
1388 \o Editor's width in characters \tt{\bold %W}
1389 \o Editor's height in characters \tt{\bold %H}
1390 \o To pass % symbol to the editor \tt{\bold %%}
1393 \note Not all variables work with all editors.
1399 \contentspage index.html
1400 \previouspage creator-editor-codepasting.html
1401 \page creator-editor-options.html
1402 \nextpage creator-editor-fakevim.html
1404 \title Configuring the Editor
1406 Qt Creator allows you to configure the text editor to suit your specific
1407 needs. To configure the editor, select \gui Tools > \gui{Options...} >
1410 \image qtcreator-font-colors.png "Text editor options"
1412 You can perform the following configuration actions:
1414 \o Set the font preferences and apply color schemes for syntax highlighting in
1415 \gui{Font & Colors}.
1416 \o Specify definition files for syntax highlighting for other types of files than
1417 C++ or QML in \gui{Generic Highlighter}.
1418 \o Set tabs, indentation, the handling of whitespace, and mouse operations in
1420 \o Set various display properties, for example,
1421 \l{Highlighting and folding blocks}{highlighting and folding blocks},
1422 text wrapping or \l{Moving to symbol definition or declaration}
1423 {moving to symbol definition or declaration}
1425 \o Configure \l{Completing Code}{code completion} in \gui Completion.
1428 \section2 Configuring Fonts
1430 You can select the font family and size. You can specify a zoom setting in
1431 percentage for viewing the text. You can also zoom in or out by pressing
1432 \key {Ctrl++} or \key {Ctrl +-}, or by pressing \key Ctrl and rolling
1433 the mouse button up or down. To disable the mouse wheel function, select
1434 \gui {Tools > Options... > Text Editor > Behavior} and deselect the
1435 \gui {Enable scroll wheel zooming} check box.
1437 Antialiasing is used by default to make text look smoother and more
1438 readable on the screen. Deselect the \gui Antialias check box to
1439 turn off antialiasing.
1441 \section2 Defining Color Schemes
1443 You can select one of the predefined color schemes for syntax highlighting
1444 or create customized color schemes. The color schemes apply to highlighting
1445 both C++ and QML files and generic files.
1447 To create a color scheme:
1451 \o Select \gui {Tools > Options... > Text Editor > Fonts & Color > Copy}.
1453 \o Enter a name for the color scheme and click \gui OK.
1455 \o In the \gui Foreground field, specify the color of the selected
1458 \o In the \gui Background field, select the background
1459 color for the code element.
1461 The backgound of the \gui Text element determines the background of the
1466 When you copy code from Qt Creator, it is copied in both plain text and HTML
1467 format. The latter makes sure that syntax highlighting is preserved when
1468 pasting to a rich-text editor.
1470 \section2 Generic Highlighting
1472 Generic highlighting is based on highlight definition files that are provided by the
1473 \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}{Kate Editor}.
1474 You can download highlight definition files for use with Qt Creator.
1476 If you have a Unix installation that comes with the Kate Editor, you might already
1477 have the definition files installed. Typically, the files are in a read-only directory,
1478 and therefore, you cannot manage them. Qt Creator can try to locate them and use them
1479 as fallback files, when the primary location does not contain the definition for the
1480 current file type. You can also specify the directory that contains preinstalled
1481 highlight definition files as the primary location.
1483 When you open a file for editing and the editor cannot find the highlight definition
1484 for it, an alert appears. You can turn off the alerts. You can also specify patterns
1485 for ignoring files. The editor will not alert you if highlight definitions for the
1486 ignored files are not found.
1488 To download highlight definition files:
1492 \o Select \gui {Tools > Options... > Text Editor > Generic Highlighter}.
1494 \image qtcreator-generic-highlighter.png "Generic Highlighter options"
1496 \o In the \gui Location field, specify the path to the primary location for
1497 highlight definition files.
1499 \o Click \gui {Download Definitions} to open a list of highlight definition files available for
1502 \image qtcreator-manage-definitions.png "Download Definitions dialog"
1504 \o Select highlight definition files in the list and click \gui{Download Selected
1507 \o Select the \gui {Use fallback location} check box to specify the secondary location
1508 where the editor will look for highlight definition files.
1510 \o Click \gui Autodetect to allow Qt Creator to look for highlight definition
1511 files on your system, or click \gui Browse to locate them in the file system
1514 \o In the \gui {Ignored file patterns} field, specify file patterns. You will not
1515 receive alerts if the highlight definitions for the specified files are not found.
1517 \o Click \gui OK to save your changes.
1522 \section2 Indenting Code
1524 \image qtcreator-indentation.png "Text Editor Behavior options"
1526 When you type code, it is indented automatically according to the selected
1527 options. Select a block to indent it when you press \key Tab.
1528 Press \key {Shift+Tab} to decrease the indentation.
1530 When you press \gui Backspace the indentation is decreased by one level,
1531 instead of one space, by default.
1533 By default, the tab-length in code editor is 8 spaces, but you can change
1534 it. The code editor can also determine whether tabs or spaces are used
1535 on the previous or next line and copy the style.
1537 You can determine whether the block indent style includes braces,
1538 or you can use the GNU indent style. The GNU style places braces on a separate
1539 line, indented by 2 spaces, except when they open a function definition, where
1540 they are not indented.
1542 You can also specify whether continuation lines are aligned with the previous
1543 code or just indented to the logical depth. You can always use spaces for
1544 alignment or use spaces or tabs depending on the other options you selected.
1546 The following code snippet illustrates excluding braces from the indented block:
1550 void foobar(bool zoo)
1560 The following code snippet illustrates including braces in the indented block:
1564 void foobar(bool zoo)
1574 The following code snippet illustrates the GNU style:
1578 void foobar(bool zoo)
1592 \contentspage index.html
1593 \previouspage creator-editor-using.html
1594 \page creator-editor-finding.html
1595 \nextpage creator-editor-refactoring.html
1597 \title Finding and Replacing
1599 To search through the currently open file:
1601 \o Press \key Ctrl+F or select \gui Edit > \gui Find/Replace >
1603 \o Enter the text you are looking for.
1605 If the text is found, all occurrences are highlighted as you type.
1606 \o To go to the next occurrence, click \inlineimage qtcreator-next.png
1607 , or press \key F3. To go to the previous occurrence click
1608 \inlineimage qtcreator-previous.png
1609 , or press \key Shift+F3.
1612 You can restrict the search in the \gui Find field by selecting one
1613 or several search criteria:
1615 \o To make your search case sensitive, select
1616 \inlineimage qtcreator-editor-casesensitive.png
1618 \o To search only whole words, select
1619 \inlineimage qtcreator-editor-wholewords.png
1621 \o To search using regular expressions, select
1622 \inlineimage qtcreator-editor-regularexpressions.png
1624 Regular expressions used in Qt Creator are modeled on Perl regular
1625 expressions. For more information on using regular expressions, see
1626 \l {http://doc.qt.nokia.com/4.7/qregexp.html#details}
1627 {Detailed Description} in the QRegExp Class Reference.
1630 \note If you have selected text before selecting \gui Find/Replace, the
1631 search is conducted within the selection.
1633 To replace occurrences of the existing text, enter the new text in the
1634 \gui{Replace with} field.
1636 \o To replace the selected occurrence and move to the next one,
1637 click \inlineimage qtcreator-next.png
1638 or press \key Ctrl+=.
1639 \o To replace the selected occurrence and move to the previous one,
1640 click \inlineimage qtcreator-previous.png
1642 \o To replace all occurrences in the file, click \gui{Replace All}.
1645 \section1 Advanced Search
1647 To search through projects, files on a file system or the currently open
1650 \o Press \key Ctrl+Shift+F or select \gui Edit >
1651 \gui Find/Replace > \gui{Advanced Find} >
1652 \gui{Open Advanced Find...}.
1653 \o Select the scope of your search:
1655 \o \gui{All Projects} searches files matching the defined file
1656 pattern in all currently open projects.
1658 For example, to search for \tt previewer only in \tt .cpp
1659 and \tt .h files, enter in \gui{File pattern}
1662 \image qtcreator-search-allprojects.png
1664 \o \gui{Current Project} searches files matching the defined file
1665 pattern only in the project you are currently editing.
1666 \o \gui{Files on File System} recursively searches files matching
1667 the defined file pattern in the selected directory.
1668 \o \gui{Current File} searches only the current file.
1670 \o Enter the text you are looking for and click \gui Search.
1672 \image qtcreator-searchresults.png
1674 A list of files containing the searched text is displayed in the
1675 \gui{Search Results} pane.
1677 \o To see all occurrences in a file, double-click the file name in
1679 \o To go to an occurrence, double-click it.
1686 \contentspage index.html
1687 \previouspage creator-editor-finding.html
1688 \page creator-editor-refactoring.html
1689 \nextpage qt-quick-toolbars.html
1693 Code refactoring is the process of changing the code without modifying the
1694 existing functionality of your application. By refactoring your code you
1697 \o Improve internal quality of your application
1698 \o Improve performance and extensibility
1699 \o Improve code readability and maintainability
1700 \o Simplify code structure
1703 \section1 Finding Symbols
1705 To find the use of a specific symbol in your project:
1707 \o In the editor place the cursor on the symbol and select \gui Tools
1708 > \gui C++ > \gui{Find Usages} or press
1711 Qt Creator looks for the symbol in the following locations:
1713 \o Files listed as a part of the project
1714 \o Files directly used by the project files (for example, generated
1716 \o Header files of used frameworks and libraries
1718 \o The \gui{Search Results} pane opens and shows the location and
1719 number of instances of the symbol in the current project.
1721 \image qtcreator-refactoring-find.png
1724 You can browse the search results in the following ways:
1726 \o To go directly to an instance, double-click the instance in the
1727 \gui{Search Results} pane.
1728 \o To move between instances, click
1729 \inlineimage qtcreator-forward.png
1731 \inlineimage qtcreator-back.png
1732 in the \gui{Search Results} pane.
1733 \o To expand and collapse the list of all instances, click
1734 \inlineimage qtcreator-expand.png
1736 \o To clear the search results, click \inlineimage qtcreator-clear.png
1740 \section1 Renaming Symbols
1742 The functions available for renaming symbols depend on whether you are
1743 writing C++ or QML code. For QML, you can only rename IDs.
1745 To rename a specific symbol in a Qt project:
1747 \o In the editor, place the cursor on the symbol you would like to
1748 change and select \gui Tools > \gui C++ >
1749 \gui{Rename Symbol Under Cursor} or press \key Ctrl+Shift+R.
1751 The \gui{Search Results} pane opens and shows the location and
1752 number of instances of the symbol in the current project.
1754 \image qtcreator-refactoring-replace.png
1755 \o To replace all selected instances, enter the name of the new symbol
1756 in the \gui{Replace with} text box and click \gui Replace.
1758 To omit an instance, uncheck the check-box next to the instance.
1760 \note This action replaces all selected instances of the symbol in
1761 all files listed in the \gui{Search Results} pane. You cannot
1765 \note Renaming local symbols does not open the \gui{Search Results} pane.
1766 The instances of the symbol are highlighted in code and you can edit the
1767 symbol. All instances of the local symbol are changed as you type.
1769 To rename an ID in a Qt Quick project:
1773 \o Right-click an ID in the QML code and select
1776 \o In the \gui {Rename id} field, enter the new ID.
1783 \contentspage index.html
1784 \previouspage creator-qml-application.html
1785 \page creator-project-managing.html
1786 \nextpage creator-project-creating.html
1788 \title Managing Projects
1790 One of the major advantages of Qt Creator is that it allows a team of
1791 developers to share a project across different development platforms with a common
1792 tool for development and debugging.
1794 The following sections describe how to manage projects:
1797 \o \l{Creating a Project}
1798 \o \l{Setting Up a qmake Project}
1799 \o \l{Adding Libraries to qmake Projects}
1800 \o \l{Setting Up a CMake Project}
1801 \o \l{Setting Up a Generic Project}
1802 \o \l{Setting Up Development Environment for Maemo}
1803 \o \l{Setting Up Development Environment for Symbian}
1804 \o \l{Managing Sessions}
1805 \o \l{Adding New Custom Wizards}
1812 \contentspage index.html
1813 \previouspage creator-project-managing.html
1814 \page creator-project-creating.html
1815 \nextpage creator-project-qmake.html
1817 \title Creating a Project
1819 You use wizards to create and import several types of projects and files, such
1820 as Qt GUI or console applications and Qt Quick applications.
1821 You can use wizards also to add individual files to your projects.
1823 The wizards prompt you to enter the settings needed
1824 for that particular type of project and create the necessary files for you.
1825 To display other types of files in the \gui Projects pane, specify them in
1828 \image qtcreator-new-project.png
1830 To change the location of the project directory, and to make changes in
1831 the build and run settings, select \gui{Tools} > \gui{Options...} >
1832 \gui{Projects} > \gui{General}.
1834 \section1 Using Project Wizards
1836 To create a new project:
1838 \o Select \gui File > \gui{New File or Project} and select the type of your
1841 The contents of the following dialogs depend on the project type.
1842 Follow the instructions of the wizard.
1843 This example uses \gui {Qt Gui Application}.
1845 \o Name the project and set its path. To select the path from a
1846 directory tree, click \gui Browse.
1848 Avoid using spaces and special characters in the project name and
1851 \image qtcreator-intro-and-location.png
1853 \o Select the Qt versions to use as build targets for your project, and click
1856 \image qtcreator-new-project-qt-versions.png "Target setting dialog"
1858 \note If you have only one Qt version installed, this dialog is skipped.
1860 \o Specify the name of the class you want to create and using the
1861 drop-down menu select its base class type.
1863 Note that the \gui{Header file}, \gui{Source file} and
1864 \gui{Form file} fields are automatically updated as you name your
1867 \image qtcreator-class-info.png
1868 \o Review the project settings.
1870 To create the project, click \gui Finish.
1872 \image qtcreator-new-project-summary.png
1875 \section1 Adding Files to Projects
1877 You can create the following types of files:
1881 \o Qt resource files, which allow you to store binary files in the
1882 application executable
1884 \o \QD forms and Qt QML files, which specify parts of application user
1887 \o C++ class, source, or header files
1893 \section2 Creating C++ Classes
1895 The \gui {C++ Class Wizard} allows you to create a C++ header and source file for
1896 a new class that you can add to a C++ project. Specify the class name, base
1897 class, and header and source files for the class.
1899 The wizard supports namespaces. To use a namespace, enter a qualified
1900 class name in the \gui {Class name} field. For example:
1901 MyNamespace::MySubNamespace::MyClass.
1903 \image qtcreator-cpp-class-wizard.png "Enter Class Name dialog"
1905 The names of the header and source file are based on the class name. To change the
1906 default suffix of a file, click \gui Configure.
1908 You can create your own project and class wizards. For more information,
1909 see \l{Adding New Custom Wizards}.
1911 \section2 Displaying Additional File Types in Projects Pane
1913 Qt Creator determines whether to display files from the project folder
1914 in the \gui Projects pane depending on the file type (.pro, .pri, .cpp,
1915 .h, .ui, .qrc, and so on). To display other types of files, edit the the
1916 project file. Add filenames as values of the \c {OTHER_FILES} variable.
1917 You can also use wildcards.
1919 For example, the following code specifies that text files are displayed
1920 in the \gui Projects pane:
1924 OTHER_FILES += *.txt
1928 This also makes the files available in the \gui Locator.
1930 \section1 Adding Subprojects to Projects
1932 When you create a new project, you can add it to another project as a subproject
1933 in the \gui{Project Management} dialog. However, you first have to edit the
1934 .pro file of the parent project to specify that qmake uses the \c subdirs template
1935 to build the project.
1937 The \c subdirs template creates a Makefile for building subprojects. They can be
1938 located either in subdirectories of the project directory or in any other directory.
1939 The location of the targets is specified using the SUBDIRS variable. If the project file
1940 has the same name as the directory, you can just specify the directory name. If the project
1941 name and directory name are different, you must specify the project file name (.pro).
1943 For more information on the SUBDIRS variable, see the
1944 \l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#subdirs}{qmake Variable Reference}.
1946 For example, the following code specifies that plugin_coreplugin/plugin_coreplugin.pro
1947 and mylogin.pro belong to the project:
1952 SUBDIRS = plugin_coreplugin \
1953 ../another/plugin/myplugin.pro
1956 To specify dependencies, use the \gui{Add Library} wizard. For more information,
1957 see \l{Adding Libraries to qmake Projects}.
1963 \contentspage index.html
1964 \previouspage creator-project-managing-sessions.html
1965 \page creator-project-wizards.html
1966 \nextpage creator-editor-using.html
1968 \title Adding New Custom Wizards
1970 If you have a team working on a large application or several applications,
1971 you might want to standardize the way the team members create projects
1974 You can copy the wizard templates in the template folders
1975 to create your own project and class wizards. They are displayed in the
1976 \gui New dialog that opens when you choose \gui {File > New File or Project}.
1978 In a project wizard, you can specify the files needed in a project.
1979 You can add wizard pages to allow developers to specify settings for the
1982 In a class wizard, you can allow developers to specify the class name, base
1983 class, and header and source files for the class.
1985 To see how this works, rename wizard_example.xml as wizard.xml in the helloworld
1986 and listmodels folders. After you restart Qt Creator, the \gui {Custom Classes}
1987 and \gui {Custom Projects} categories appear in the \gui New dialog.
1989 \image qtcreator-custom-project-wizards.png "The New dialog with custom projects and classes"
1991 \section1 Overview of Custom Wizards
1993 A custom wizard defines the user interface of a wizard page. The values the user enters
1994 in the wizard are assigned field names. Field name and value pairs are then passed to
1995 the file creation process. File creation can happen in the following ways:
1999 \o Template-based, where source files that contain placeholders for
2000 the field names are provided. During processing, the placeholders are replaced
2001 by the values from the wizard page. Optionally, modifier
2002 characters are applied. For more information, see \l{Processing Template Files}.
2004 \o Generator script, where a script is called to create the files.
2006 \note This option mainly exists to accommodate existing generator scripts or
2007 cases where complicated algorithmic logic is required when generating files. Writing
2008 cross-platform scripts is inherently difficult, and therefore, it is not recommended
2009 for new wizards. For more information, see \l{Using Generator Scripts}.
2013 Custom wizards are located in subdirectories of the following directories:
2017 \o \c{share/qtcreator/templates/wizards}
2019 \o the local user's configuration folder,
2020 \c{$HOME/.config/Nokia/qtcreator/templates/wizards}
2022 \o \c{%APPDATA%\Nokia\qtcreator\templates\wizards}
2026 They contain an XML configuration file called wizard.xml, the
2027 template source files, and optionally, the generator script.
2029 \section1 Creating Project Wizards
2031 To create a project wizard:
2035 \o Make a copy of the \c {share/qtcreator/templates/wizards/helloworld} or
2036 \c {share/qtcreator/templates/wizards/listmodel} folder.
2038 \o Modify the wizard_example.xml file.
2040 \o The following code determines the type of the wizard and its place
2041 in the \gui New dialog:
2045 <wizard version="1" kind="project"
2046 class="qt4project" firstpage="10"
2047 id="A.HelloWorld" category="B.CustomProjects">
2053 \o \c version is the version of the file contents. Do not modify this value.
2055 \o \c kind specifies the type of the wizard: \c project or \c class.
2057 \o \c class specifies the type of the project. Currently the only available
2058 type is \c qt4project, which specifies a Qt console project.
2060 \o \c firstpage specifies the place of the new page in the standard project
2061 wizard. The value 10 ensures that the custom page appears after the standard
2062 pages, as the last page of the wizard.
2064 \o \c id is the unique identifier for your wizard. The letter specifies the
2065 position of the wizard within the \c category. The HelloWorld wizard appears
2066 as the first wizard in the second category in the \gui New dialog.
2068 \o \c category is the category in which to place the wizard in the list.
2069 The letter specifies the position of the category in the list in the \gui New
2074 \o The following code specifies the icon and text that appear in the \gui New
2079 <icon>console.png</icon>
2080 <description>Creates a hello-world-project with custom message.</description>
2081 <description xml:lang="de">Erzeugt ein Hello-Welt-Projekt mit einer Nachricht.</description>
2082 <displayname>Hello World</displayname>;
2083 <displayname xml:lang="de">Hallo Welt</displayname>;
2084 <displaycategory>Custom Projects</displaycategory>
2085 <displaycategory xml:lang="de">Benutzerdefinierte Projekte</displaycategory>
2092 \o \c icon appears next to the \c displayName.
2094 \o \c description appears at the bottom of the \gui New dialog when you
2095 select the display name.
2097 \o \c displayName appears in the \gui New dialog, under the
2100 You can add translations as values for the text elements. Specify the target
2101 language as an attribute for the element. Use locale names (QLocale).
2102 For example, \c {xml:lang="de"}.
2106 \o Files to be added to the project:
2109 \o Template-based: The following code specifies the files to add to the project:
2112 <file source="main.cpp" openeditor="true" />
2113 <file source="project.pro" target="%ProjectName%.pro" openproject="true" />
2114 <file source="icon.png" target="%ProjectName%.png" binary="true" />
2118 \o \c source specifies the file to copy to the project. The files must be
2119 located in the wizard folder.
2121 \o \c openeditor indicates that the file is to be opened in an editor after
2122 the wizard has finished.
2124 \o \c binary indicates that the file is a binary file (for example, an
2125 image file). It is to be copied to the target folder as is. Placeholders
2126 are not replaced with values.
2128 \o \c target specifies the new filename for the file. The \c {%ProjectName%}
2129 variable is replaced with the string that users specify in the \gui Name
2130 field on the first page of the wizard.
2132 \o \c openproject indicates that the file is a project file which is to be opened
2133 after the wizard has finished.
2137 See also \l{Processing Template Files}.
2139 \o Generator-script: The following code specifies that the script \c generate.pl is to be used
2140 to create the files:
2142 <generatorscript binary="generate.pl">
2143 <argument value="--class-name=%ClassName%"/>
2144 <argument value="--project-name=%ProjectName%"/>
2145 <argument value="--header-suffix=%CppHeaderSuffix%" omit-empty="true"/>
2146 <argument value="--source-suffix=%CppSourceSuffix%" omit-empty="true"/>
2147 <argument value="--description=%Description%" omit-empty="true" write-file="true"/>
2150 In each argument, the field placeholders are replaced by the field
2151 values. There are additional boolean attributes which give fine-grained control:
2154 \o \c omit-empty specifies that complete argument is to be omitted when all
2155 placeholders expand to empty values. In the above example,
2156 the option \c --source-suffix will not be passed to the script if the value is empty.
2158 \o \c write-file indicates that instead of the expanded value,
2159 the value will be written to a temporary file and its file name will be
2160 passed to the script instead. This is useful for multi-line text fields.
2163 See also \l{Using Generator Scripts}.
2166 \o The following code creates a page that specifies settings for the project:
2170 <!-- Create a 2nd wizard page with parameters -->
2171 <fieldpagetitle>Hello World Parameters</fieldpagetitle>
2172 <fieldpagetitle xml:lang="de">Hallo Welt Parameter</fieldpagetitle>
2174 <field mandatory="true" name="MESSAGE">
2175 <fieldcontrol class="QLineEdit" validator='^[^"]+$' defaulttext="Hello world!" />
2176 <fielddescription>Hello world message:</fielddescription>
2177 <fielddescription xml:lang="de">Hallo-Welt-Nachricht:</fielddescription>
2185 \o \c fieldpagetitle specifies the title of the page.
2187 \o \c field specifies whether the field is mandatory (\c true or \c false).
2188 You can use the value of the \c name field as a variable in other files (for
2189 example, \c {%MESSAGE%}.
2191 \o \c fieldcontrol specifies the field. \c class specifies the field type.
2192 You can use interface objects from the QWidget class to create fields. This
2193 example uses QLineEdit to create an input field.
2195 \o \c validator specifies a regular expression to check the characters allowed in
2198 \o \c defaulttext specifies text that appears in the field by default.
2200 \o \c fielddescription specifies the field name that appears on the wizard page.
2206 \section1 Creating Class Wizards
2208 The widget.xml file for a class wizard is very similar to that for a project
2209 wizard. The differences are discussed below.
2211 To create a class wizard:
2215 \o The following code specifies settings for the wizard:
2219 <wizard version="1" kind="class" id="A.ListModel" category="B.CustomClasses">
2221 <description>Creates a QAbstractListModel implementation.</description>
2222 <description xml:lang="de">Erzeugt eine Implementierung von QAbstractListModel.</description>
2224 <displayname>QAbstractListModel implementation</displayname>
2225 <displayname xml:lang="de">Implementierung von QAbstractListModel</displayname>
2227 <displaycategory>Custom Classes</displaycategory>
2228 <displaycategory xml:lang="de">Benutzerdefinierte Klassen</displaycategory>
2232 For more information about the elements and their values, see
2233 \l {Creating Project Wizards}.
2235 \o The following code specifies the files to add to the project:
2240 <file source="listmodel.cpp" target="%ClassName:l%.%CppSourceSuffix%" openeditor="true" />
2241 <file source="listmodel.h" target="%ClassName:l%.%CppHeaderSuffix%" openeditor="true" />
2246 Here, \c target contains the following variables that are used to construct
2251 \o \c {%ClassName:l%} is replaced with the value of the \c ClassName field.
2252 The modifier \c l converts the string to lower case, to observe Qt
2255 \o \c {%CppSourceSuffix%} and \c {%CppHeaderSuffix%} are pre-defined.
2256 For more information, see \l{Pre-defined Standard Variables}.
2262 <!-- Create parameter wizard page -->
2264 <fieldpagetitle>ListModel parameters</fieldpagetitle>
2265 <fieldpagetitle xml:lang="de">Parameter des ListModel</fieldpagetitle>
2267 <field name="ClassName">
2269 <fieldcontrol class="QLineEdit" validator="^[a-zA-Z0-9_]+$" defaulttext="MyListModel" />
2271 <fielddescription>Class name:</fielddescription>
2272 <fielddescription xml:lang="de">Klassenname:</fielddescription>
2274 <field name="Datatype">
2276 <fieldcontrol class="QComboBox" combochoices="QString,int" defaultindex="0" />
2278 <fielddescription>Data type:</fielddescription>
2279 <fielddescription xml:lang="de">Datentyp:</fielddescription>
2285 In addition to QLineEdit, QComboBox is used in the class wizard to create
2286 a field. \c combochoices specifies the options in the combobox and
2287 \c defaultindex specifies that QString is the default value.
2291 \section1 Processing Template Files
2293 When processing a template source file, placeholders specifying the field names
2294 in the format \c{%FIELDNAME%} are replaced by the values entered by the user.
2295 In addition, modifier characters are supported. For example, \c{%FIELDNAME:u%}
2296 specifies that the value is converted to upper case. This enables generating header
2297 guards for C++ header files.
2299 The following modifier characters are supported:
2302 \o \c{l} for lower case.
2303 \o \c{u} for upper case.
2304 \o \c{c} for upper case initial letter ("project" > "Project").
2307 You can use conditions to add sections of the file depending on field values.
2308 Use a syntax that is similar to C++ preprocessing, as demonstrated in
2309 the profile of the \c{helloworld} example:
2313 @if "%SCRIPT%" == "true"
2319 The value of the Boolean (QCheckBox) field labeled \c{SCRIPT} determines
2320 whether the script module is added. The expressions must expand to valid
2321 Javascript expressions after field replacement.
2323 \section1 Pre-defined Standard Variables
2325 In addition to the field values entered by the user, you can use
2326 the following pre-defined standard values:
2330 \o \c {%ProjectName%} is replaced by the name of the project in the case
2333 \o \c {%Path%} is replaced by the path to the target directory.
2334 For classes, this is the directory, where the files
2335 are created. For project wizards, an additional subdirectory
2336 named after the project is created.
2338 \o \c {%TargetPath%} is replaced by the path to the directory where the actual files
2339 are created. For non-project wizards, it is identical to \c %Path%.
2340 For project wizards, it is \c %Path%/%ProjectName%.
2342 \o \c {%CppSourceSuffix%} is replaced by the default source suffix, which
2343 is defined in Qt Creator in \gui {Tools > Options... > C++ > File Naming}.
2344 For example, if users enter \bold MyClass, the filename becomes myclass.cpp
2345 when the project is created.
2347 \o \c {%CppHeaderSuffix%} is replaced by the default header suffix, which
2348 is also defined in \gui {File Naming}.
2352 \section1 Validating User Input
2354 You can specify validation rules for user input. The rules consist of a Boolean
2355 JavaScript expression and an error message. The placeholders in them are
2356 replaced with values before they are evaluated or displayed.
2358 Consider the following rule used in the \l{Creating Class Wizards} example:
2362 <validationrule condition='"%ClassName%" != "QAbstractListModel"'>
2363 <message>%ClassName% cannot be used as class name.</message>
2364 <message xml:lang="de">%ClassName% kann nicht als Klassenname verwendet werden.</message>
2369 It ensures that the class name entered by the user does not match the name of
2370 the base class. If the validation fails, a red label displaying the message appears
2371 at the bottom of the wizard page.
2373 \section1 Using Generator Scripts
2375 The values entered in the wizard page are passed to the script
2376 as command line arguments as defined by the wizard configuration file.
2378 In addition, the script must implement a \c{--dry-run} command line option.
2380 Qt Creator needs to know the file names before the files are created to check
2381 whether files with identical names already exist, for example. Therefore,
2382 script file generation is a two-step process:
2386 \o Determine file names and attributes: The script is called with the command line
2387 \c{--dry-run} option and the field values. It then prints the relative path
2388 names of the files it intends to create, followed by comma-separated attributes
2389 matching those of the \c{<file>} element, for example:
2392 myclass.cpp,openeditor
2393 myclass.h,openeditor
2394 myproject.pro,openproject
2397 \o Create files: The script is called with the parameters only in the working directory.
2398 It then actually creates the files. If directories are needed, the script
2399 should create them, too.
2403 The \c{scriptgeneratedproject} sample wizard illustrates the usage.
2404 A typical script invocation for this example (obtained by running Qt Creator with
2405 \c{--customwizard-verbose}) looks as follows:
2408 generate.pl --class-name=TestClass --project-name=TestProject --header-suffix=h --source-suffix=cpp --description=/tmp/qtcreatorj26629.txt
2411 By default, the scripts are run in the directory corresponding to
2412 \c %TargetPath%. This can be overriden by specifying the
2413 attribute \c workingdirectory on the element \c generatorscript.
2414 For example, if the script creates the project directory by itself,
2415 %Path% can be specified. In that case, \c --dry-run should output
2416 the correct relative paths or absolute paths constructed using the value of
2423 \contentspage index.html
2424 \previouspage creator-project-creating.html
2425 \page creator-project-qmake.html
2426 \nextpage creator-project-qmake-libraries.html
2428 \title Setting Up a qmake Project
2430 The qmake tool helps simplify the build process for development projects
2431 across different platforms. qmake automates the generation of makefiles
2432 so that only a few lines of information are needed to create each makefile.
2433 qmake can be used for any software project, whether it is written in Qt or not.
2435 The qmake tool generates a makefile based on the information in a project
2436 file that is generated by Qt Creator. It can generate makefiles for MinGW,
2437 Microsoft Visual studio, and CSL ARM in Windows, and GNU Compiler Collection
2438 (GCC) in Linux and Mac OS X.
2440 For more information about qmake, see the
2441 \l{http://qt.nokia.com/doc/4.7/qmake-manual.html}{qmake Manual}.
2443 \section1 Selecting the Qt Version
2445 Qt Creator allows you to have multiple versions of Qt installed on
2446 your development PC and use different versions for each of your projects.
2448 If Qt Creator finds \bold qmake in the \c{PATH} environment variable, it uses
2449 that version. The \l{glossary-system-qt}{ qmake version of Qt} is referred
2450 to as \bold{Qt in PATH}. If you intend to use only one version of Qt and it
2451 is already in the \c{PATH} and correctly set up for command line use, you do
2452 not need to manually configure your Qt version.
2454 \section2 Compiling Projects with MinGW in Windows
2456 To add a Qt version for \bold MinGW:
2458 \o Select \gui Tools > \gui Options... > \gui Qt4 >
2460 \o Click \inlineimage qtcreator-windows-add.png
2461 and enter the name of the version in the \gui{Version name} field.
2462 \o Enter the qmake binary path in the \gui{qmake location} field.
2463 \o Enter the MinGW installation path in the \gui{MinGW directory} field.
2465 \image qtcreator-qt4-qtversions-win-mingw.png
2468 \section3 Troubleshooting MinGW Compilation Errors
2470 If error messages displayed in the \gui {Compile Output} pane contain
2471 paths where slashes are missing (for example, C:NokiaQtSDK),
2472 check your PATH variable. At the command line, enter the following commands:
2477 where mingw32-make.exe
2480 If these commands show paths, they have been added to the global PATH variable
2481 during the installation of a toolkit based on Cygwin or MinGW, even though
2482 this is against Windows conventions.
2484 To keep working with the third-party toolkit, create a new shell link
2485 that adds the required paths (as Visual Studio and Qt do). The shell link
2486 must point to cmd.exe, as illustrated by the following example:
2488 \c {C:\Windows\System32\cmd.exe /K C:\path_to\myenv.bat}
2490 where the /K parameter carries out the command specified in the bat file.
2492 Create the myenv.bat file at \e path_to, which should be in a convenient location.
2493 In the file, specify the paths to the toolkits. For example,
2495 \c {set PATH=C:\path1;C:\path2;%PATH%}
2497 where \e path1 and \e path2 are paths to the toolkits.
2499 Finally, remove the paths from the global PATH, reboot the computer, and
2500 run the \c where commands again to verify that the global PATH is now clean.
2502 You can use the shell link to run the tools in the third-party toolkits.
2504 \section2 Compiling Projects with Microsoft Visual C++
2506 To add a Qt version for a \bold{Microsoft Visual C++} compiler:
2508 \o Select \gui Tools > \gui Options... > \gui Qt4 >
2510 \o Qt Creator automatically sets the correct environment variables for
2511 compilation. Select the internal version number of the installed
2512 Microsoft Visual C++ tool chain in the \gui Toolchain list.
2514 \image qtcreator-qt4-qtversions-win-msvc.png
2516 \o If the \gui {Debugging helper} is not in use, click \gui Rebuild
2517 to take it to use. For more information, see \l{Using Debugging Helpers}.
2521 \section2 Compiling Qt for Symbian Projects
2523 If you are using \bold{Qt for Symbian} and your Symbian SDK is registered
2524 with devices.exe, Qt Creator automatically detects the Qt version. To add a
2525 Qt for Symbian version:
2527 \o Select \gui Tools > \gui Options... > \gui Qt4 >
2529 \o Select the \gui{S60 SDK} you want the Qt Creator to use.
2531 \image qtcreator-qt4-qtversions-win-symbian.png
2532 \o To build an application for your device using GCCE, enter the path
2533 to the CSL ARM toolchain directory in
2534 \gui{CSL\\GCCE Directory}.
2536 You do not need to specify this path if the compiler is included in
2537 the \c{PATH} environment variable.
2538 \o To build an application for the emulator (WINSCW toolchain), enter
2539 the path to your Carbide C++ installation directory in
2540 \gui{Carbide directory}.
2542 \note You need to have Carbide C++ version 2.0 or later installed.
2545 \section2 Compiling Projects With Linux
2547 To compile a project in Qt Creator, Linux uses GNU Compiler Collection
2548 (GCC). Intel Compiler Collection (ICC) is supported as a drop-in
2549 replacement for GCC.
2551 To add a Qt version:
2553 \o Select \gui Tools > \gui Options... > \gui Qt4 >
2555 \o Click \inlineimage qtcreator-linux-add.png
2556 and enter the name of the version in \gui{Version Name}.
2557 \o Enter the path to the qmake binary in \gui{Path to qmake}.
2560 \section2 Compiling Projects With Mac OS X
2562 To compile a project in Qt Creator, Mac OS X uses GNU Compiler Collection
2563 (GCC), which is part of Xcode.
2565 To add a Qt version:
2567 \o Select \gui{Qt Creator} > \gui Preferences... > \gui{Qt Versions}.
2568 \o Click \inlineimage qtcreator-macosx-add.png
2569 and enter the name of the version in \gui{Version Name}.
2570 \o Enter the path to the qmake binary in \gui{Path to Qmake}.
2572 \image qtcreator-qt4-qtversions.png
2579 \contentspage index.html
2580 \previouspage creator-project-qmake.html
2581 \page creator-project-qmake-libraries.html
2582 \nextpage creator-project-cmake.html
2584 \title Adding Libraries to qmake Projects
2586 In addition to Qt libraries, you can add other libraries to your projects.
2587 The way the library is added depends on whether it is a system library or
2588 your own library or a 3rd party library located in the build tree of the
2589 current project or in another build tree.
2591 \image qtcreator-add-library-wizard.png "Add Library wizard"
2593 Because system libraries do not typically change and are often found by
2594 default, you do not need to specify the path to the library or to its includes
2597 For your own libraries and 3rd party libraries, you need to specify
2598 the paths. Qt Creator tries to quess the include path for an external library,
2599 but you need to check it and modify it if necessary. Qt Creator automatically
2600 adds the include path for an internal library.
2602 For all libraries, select the target platforms for the application, library,
2605 Specify whether the library is statically or dynamically linked. For a
2606 statically linked internal library, Qt Creator adds dependencies
2607 (PRE_TARGETDEPS) in the project file.
2609 Depending on the development platform, some options might be detected
2610 automatically. For example, on Mac OS, the library type (\gui Library or
2611 \gui Framework) is detected automatically and the option is hidden. However,
2612 if you develop on another platform than Mac OS and want to build your
2613 project for the Mac OS, you must specify the library type.
2615 The default convention on Windows is that the debug and release versions
2616 of a library have the same name,
2617 but are placed in different subdirectories, usually called \e debug and
2618 \e release. If the library path does not contain either of these folders,
2619 you cannot select the option to place the libraries in separate
2622 Alternatively, the letter \e d can be added to the library name for the debug
2623 version. For example, if the release version is called example.lib, the
2624 debug version is called exampled.lib. You can specify that the letter
2625 is added for the debug version and removed for the release version.
2626 If the library name ends in \e d, deselect the \gui {Remove "d" suffix
2627 for release version} option.
2629 Qt Creator supports code completion and syntax highlighting for the added
2630 libraries once your project successfully builds and links to them.
2632 \section1 To Add Libraries
2636 \o In the \gui Projects pane, open the project file (.pro).
2638 \o Right-click in the code editor to open the context menu and select
2639 \gui {Add Library...}.
2641 \o Follow the instructions of the wizard.
2645 For more information about the project file settings, see
2646 \l{http://doc.qt.nokia.com/4.7/qmake-project-files.html#declaring-other-libraries}{Declaring other Libraries}.
2648 \section1 Example of Adding Internal Libraries
2650 The following example describes how to add a statically linked internal
2651 library to your project.
2655 \o Choose \gui {File > New File or Project... > Other Projects >
2656 C++ Library} to create the library.
2658 The \gui {Introduction and Product Location} dialog opens.
2660 \image qtcreator-add-library-wizard-ex-1.png "Introduction and Product Location dialog"
2662 \o In the \gui Type field, select \gui {Statically Linked Library}.
2664 \o In the \gui Name field, give a name for the library. For example,
2667 \o Follow the instructions of the wizard until you get to the
2668 \gui {Project Management} dialog. In the \gui {Add to project}
2669 list, select a project. For example, \bold myapp.
2671 \o In the \gui Projects pane, open the project file (.pro).
2672 For example, \bold myapp.pro.
2674 \o Right-click in the code editor to open the context menu and select
2675 \gui {Add Library... > Internal Library > Next}.
2677 \o In the \gui Library field, select \bold mylib and click \gui Next.
2679 \o Click \gui Finish to add the following library declaration to the
2683 win32:CONFIG(release, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/release/ -lmylib
2684 else:win32:CONFIG(debug, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/debug/ -lmylib
2685 else:symbian: LIBS += -lmylib
2686 else:unix: LIBS += -L$$OUT_PWD/../../../projects/mylib/ -lmylib
2688 INCLUDEPATH += $$PWD/../../../projects/mylib
2689 DEPENDPATH += $$PWD/../../../projects/mylib
2691 win32:CONFIG(release, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/release/mylib.lib
2692 else:win32:CONFIG(debug, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/debug/mylib.lib
2693 else:unix:!symbian: PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/libmylib.a
2702 \contentspage index.html
2703 \previouspage quick-application-logic.html
2704 \page creator-building-running.html
2705 \nextpage creator-building-targets.html
2707 \title Building and Running Applications
2709 Qt Creator provides support for building and running Qt applications for
2710 desktop environment and mobile devices. When you install the Nokia Qt SDK,
2711 the build and run settings for the Maemo and Symbian targets are
2712 set up automatically.
2714 You can add a target if the necessary tool chain is installed on the
2715 development PC and the Qt version is configured. Click
2716 \inlineimage qtcreator-qt4-addbutton.png "Add Target button"
2717 and select from a list of available
2718 targets. To remove a target, select it and click
2719 \inlineimage qtcreator-target-remove.png "Remove Target button"
2722 You can select the targets and click the \gui Run button to build and
2723 run the applications on the targets. You can click the \gui {Build All}
2724 button to build all open projects, one after another.
2726 \section1 Setting Up a Project
2728 To view and modify the settings for currently open projects, switch to the
2729 \gui Projects mode by pressing \key Ctrl+5.
2731 \image qtcreator-projectpane.png
2733 The project pane consists of the following tabs:
2735 \o \l{Building for and Running on Multiple Targets}{Targets}
2736 \note If you have installed only one tool chain, the \gui Targets
2737 tab is replaced by a \gui {Build and Run} tab.
2738 \o \l{Specifying Editor Settings}{Editor Settings}
2739 \o \l{Specifying Dependencies}{Dependencies}
2742 Use the \gui Build and \gui Run buttons to switch between
2743 the build and run settings for the active project.
2745 If you have multiple projects open in Qt Creator, use
2746 \gui{Select a Project} option at the top to navigate between different
2753 \contentspage index.html
2754 \previouspage creator-building-running.html
2755 \page creator-building-targets.html
2756 \nextpage creator-build-settings.html
2758 \title Building for and Running on Multiple Targets
2760 You can build your application for multiple targets and run and debug it
2761 on the desktop and mobile devices. When you run the application on the
2762 \gui{Maemo} or \gui {Symbian Devices} target, Qt Creator copies the necessary
2763 files to the device that is connected to the deveopment PC. In addition, Qt
2764 Creator generates an installation package in the build directory. You can
2765 specify settings for deploying the files and creating the installation package.
2767 \section1 Building for and Running on Desktop
2771 \o Select \gui Desktop as the target.
2773 \o Click the \gui Run button.
2777 \section1 Building for and Running on Qt Simulator
2779 You can use the Qt Simulator to test Qt applications that are intended
2780 for mobile devices in an environment similar to that of the device. You
2781 can change the information that the device has about its configuration
2786 \o Select \gui {Qt Simulator} as the target.
2788 \o Click the \gui Run button.
2792 For more information about using the Qt Simulator, see the
2793 \l{http://doc.qt.nokia.com/qt-simulator-beta/index.html}{Qt Simulator Manual}.
2795 \section1 Building for and Running on Maemo
2799 \o Build and run the application for \l{Building for and Running on Qt Simulator}{Qt Simulator}.
2801 \o Build and run the application for \l{Using the Maemo Emulator}{Maemo Emulator}.
2803 \o Alternatively, you can build and run the application for a device:
2807 \o Set up the MADDE development environment and specify a connection
2808 to the device. For more information, see
2809 \l{Setting Up Development Environment for Maemo}.
2811 \o Connect the device to the development PC.
2813 \o Click the \gui Run button.
2819 Qt Creator uses the compiler specified in the MADDE toolchain to
2820 build the application.
2822 Qt Creator generates an installation package, installs in on the device,
2823 and executes it. You can skip the packaging step to save some time.
2824 The application views are displayed on the Nokia N900.
2826 output is visible in the Qt Creator \gui {Application Output} view.
2828 Choose \gui {Projects > Maemo Run} to view the settings for deploying the
2829 application on the connected device and creating the installation package.
2830 For more information, see \l{Specifying Run Settings for Maemo Devices}.
2832 Debugging also works transparently.
2834 \section1 Building for and Running on Symbian
2838 \o Build and run the application for \l{Building for and Running on Qt Simulator}{Qt Simulator}.
2840 \o If no problems are found, build and run the application for a device.
2842 \o To test functionality that uses Symbian APIs, you can build and
2843 run the application for Symbian Emulator.
2847 The build configuration for the \gui{Symbian Device} target
2848 uses the GCCE tool chain by default. If you want to build
2849 for the device using RVCT, select it in the \gui {Tool chain} field
2850 in the \gui{General} section.
2852 \section2 Building and Running for a Device
2856 \o Install the required software on the device. For more information, see
2857 \l{Setting Up Development Environment for Symbian}.
2859 \o Connect the device to the development PC through a USB cable.
2860 The target selector displays a green check mark when a
2861 device is connected.
2863 \image qtcreator-qt4-symbian-device-connected.png
2865 The tool tip of the target selector shows more details about the actual
2866 device that will be used when you run your application.
2868 \o Start the \gui{App TRK} application on your device.
2870 \o Click the \gui Run button.
2874 You can connect several devices to your development PC simultaneously.
2875 In the details of the run configuration for the \gui{Symbian Device} target,
2876 select the device to run your application on.
2878 When you build the application for the \gui{Symbian Device} target, Qt
2879 Creator automatically generates a Symbian installation system (SIS) file
2880 in the project folder. You can deliver the installation file to users for
2881 installation on Symbian devices.
2883 When your application is ready for delivery to users, specify run settings
2884 for creating the final SIS installation packages. For more information,
2885 see \l{Creating SIS Installation Packages}.
2887 \section2 Building and Running for Symbian Emulator
2890 the \gui{Symbian Emulator} target as the active one, and build and run your
2893 \section2 Troubleshooting
2895 If you cannot build the application, check if:
2897 \o You selected the Symbian Device target for building the application.
2898 \o The settings for the Qt version you use to build your project are
2899 correct. The path to the Symbian SDK must point to the Symbian SDK
2900 installation directory. Select \gui Tools > \gui Options...
2901 > \gui Debugger > \gui{Symbian TRK} and check if it points to the
2904 If you cannot run the application on a device, check if:
2906 \o The device is connected through the USB cable in \e{PC Suite} mode.
2907 \o \gui{App TRK} is running on the device, using the USB connection,
2908 with the status \e connected.
2909 \o The device is detected and selected in the run configuration
2913 If you cannot run the application in the emulator, check if:
2915 \o You selected the \gui{Symbian Emulator} target for your application.
2917 \o If you cannot select \gui {Symbian Emulator} as target, check that
2918 Carbide.c++ is installed correctly and that the path to the Carbide.c++
2919 installation directory is specified in the \gui{Carbide directory} field
2920 in the build settings.
2922 \o If the emulator process cannot be started, try closing Qt Creator and
2923 starting the application directly from your file manager. Having
2924 done this, Qt Creator should be able to run your projects in the
2929 \note Qt Creator does not create release configurations for the
2930 \gui {Symbian Emulator} target, because Symbian Emulator supports only debug
2933 If this does not help to solve your problem, search the qt-creator@trolltech.com
2934 mailing list archives or provide feedback to us via the methods described on the
2935 \l{http://qt.gitorious.org/qt-creator/pages/Home}{Qt Creator Development Wiki}.
2938 \section1 Building with Remote Compiler
2940 The \gui {Remote Compiler} target is an interface to a compilation service at
2941 Forum Nokia. It provides a simple, standardized environment for building Qt
2942 applications and creating installation packages for Symbian and Maemo devices
2943 when you do not have the necessary tool chains and SDKs installed or they are
2944 not supported on the development PC. You can choose from a set of supported
2945 devices, such as S60 3rd Edition or S60 5th Edition devices.
2947 \note Remote Compiler is an experimental component that you must install
2948 separately from the package that is included in the Nokia Qt SDK.
2952 \o In the Nokia Qt SDK installation directory, double-click
2953 SDKMaintenanceTool.exe to install \gui {Experimental APIs}.
2955 \o In Qt Creator, choose \gui {Tools > Options > Projects > Remote Compiler}
2956 to log on to Forum Nokia.
2958 \image remotecompiler-fn-logon.png "Remote Compiler options"
2960 \o Choose \gui {Projects}.
2963 \inlineimage qtcreator-qt4-addbutton.png "Add Target button"
2964 and select \gui {Remote Compiler} to add Remote Compiler as a target.
2966 \o Click \gui Add to add mobile device platforms as build configurations.
2968 \o Click the \gui {Target Selector} and select a build configuration.
2970 \o Choose \gui {Build > Build All}.
2974 The installation package is generated in the \gui {Build directory} on
2977 For more information about Remote Compiler, choose \gui {Help > Contents >
2978 Remote Compiler}. The document is added during the installation of experimental
2985 \contentspage index.html
2986 \previouspage creator-building-targets.html
2987 \page creator-build-settings.html
2988 \nextpage creator-run-settings.html
2990 \title Specifying Build Settings
2992 Different build configurations allow you to quickly switch between
2993 different build settings. By default, Qt Creator creates \bold debug
2994 and \bold release build configurations.
2996 You specify build settings in the \gui Projects mode.
2998 \image qtcreator-projectpane.png
3000 To add a new build configuration, click \gui Add and select the type of
3001 configuration you would like to add. You can add as many build
3002 configurations as you need.
3004 To delete the build configuration currently selected, click \gui Remove.
3006 \section1 Editing Build Configurations
3008 To edit a build configuration:
3010 \o Select the build configuration you want to edit in
3011 \gui{Edit Build Configuration}.
3012 \o In section \gui General, you can specify:
3014 \o The \l{glossary-project-qt}{Qt version} you want to use to
3015 build your project. For more information, see
3016 \l{Selecting the Qt version}.
3017 \o The tool chain required to build the project.
3018 \o By default, projects are built in a separate directory
3019 from the source directory, as \l{glossary-shadow-build}{shadow builds}.
3020 This keeps the files generated for each target platform separate.
3022 \note Shadow building is not supported by the Symbian build system.
3023 Also, shadow building on Windows is not supported for Maemo.
3024 If you only build for one target platform, you can deselect
3025 the \gui{Shadow build} checkbox.
3029 \section1 Build Steps
3031 The build system of Qt Creator is built on qmake and make. In
3032 \gui{Build Steps} you can change the settings for qmake and make. Qt
3033 Creator runs the make command using the Qt version defined for the current
3034 build configuration.
3036 \image qtcreator-build-steps.png "Build steps"
3038 \section2 Adding Custom Build Steps
3040 To add custom steps to the build settings, select \gui {Add Build Step >
3041 Custom Process Step}.
3043 By default, custom steps are disabled. To activate a custom step, select
3044 the \gui{Enable custom process step} check-box.
3046 \image qtcreator-build-steps-custom.png "Custom Process Step"
3048 You can use any environment variables as values in the fields. For a list
3049 of variable names, click \gui {Build Environment > Details}. You can specify
3050 variables as ${VARNAME} or %VARNAME%. For example, ${BUILDDIR} or %BUILDDIR%.
3052 \note Qt Creator sets SOURCEDIR and BUILDDIR as part of the build environment.
3053 For more information, see \l{Build Environment}.
3055 \section1 Clean Steps
3057 You can use the cleaning process to remove intermediate files. This process
3058 might help you to fix obscure issues during the process of building a
3061 \image qtcreator-clean-steps.png "Clean steps"
3063 You can define the cleaning steps for your builds in the \gui{Clean Steps}:
3065 \o To add a clean step using make or a custom process, click
3066 \gui{Add Clean Step} and select the type of step you want to add.
3068 By default, custom steps are disabled. To activate a custom step,
3069 select the \gui{Enable custom process step} check-box.
3070 \o To remove a clean step, click \gui{Remove Item}.
3071 \o To change the order of steps, click
3072 \inlineimage qtcreator-movestep.png
3076 \section1 Build Environment
3078 You can specify the environment you want to use for building in the
3079 \bold{Build Environment} section. By default, the environment in which Qt
3080 Creator was started is used and modified to include the Qt version.
3081 Depending on the selected Qt version, Qt Creator automatically sets the
3082 necessary environment variables. You can edit existing environment
3083 variables or add, reset and unset new variables based on your project
3086 \image qtcreator-build-environment.png "Build Environment"
3092 \contentspage index.html
3093 \previouspage creator-build-settings.html
3094 \page creator-run-settings.html
3095 \nextpage creator-editor-settings.html
3097 \title Specifying Run Settings
3099 Qt Creator automatically creates run configurations for your project.
3100 To view and modify the settings, select \gui {Projects > Run}.
3102 The settings to specify depend on the type of the project: qmake project
3103 or Qt Quick project.
3105 Click \gui Add to add run settings for a project and \gui Remove to remove
3106 the current settings.
3108 \section1 Specifying Run Settings for qmake Projects
3110 The run configurations for qmake projects derive their executable from the parsed .pro
3113 \section2 Specifying Run Settings for Desktop Targets
3115 You can specify command line arguments to be passed to the executable
3116 and the working directory to use. The working directory defaults to
3117 the directory of the build result.
3119 For console applications, check the \gui{Run in Terminal} check box.
3120 If you need to run with special environment variables set up, you
3121 also do it in the run configuration settings.
3123 \image qtcreator-pprunsettings.png
3125 You can also create custom executable run configurations where you
3126 can set the executable to be run. For more information, see
3127 \l{Specifying a Custom Executable to Run}.
3129 \section2 Specifying Run Settings for Symbian Devices
3131 Qt Creator automatically detects Symbian devices that are connected to
3132 the development PC with an USB cable.
3133 If only one device is detected, the application is deployed
3134 and run on it. If multiple devices are connected to the PC,
3135 make sure that the correct device is selected in the
3136 \gui {Symbian Device} run settings for your project.
3138 You can also pass command line arguments to your application on the device.
3139 Press the \gui{Device info button} to get more information about the selected
3140 device, such as the CPU type and the running TRK version.
3142 \image qtcreator-symbian-run-settings.png "Run settings for Symbian devices"
3144 \section3 Creating SIS Installation Packages
3146 When you build the application for the \gui{Symbian Device} target, Qt
3147 Creator automatically generates a Symbian installation system (SIS) file
3148 in the project folder. You can deliver the installation file to users for
3149 installation on Symbian devices.
3151 The name of the installation file is displayed in the \gui {Installation file}
3152 field. In the \gui {Installation drive} field, select the drive on the device
3153 to install the application to. To suppress notifications on the device during the
3154 installation, select the \gui {Silent installation} check box. If the silent
3155 installation fails, Qt Creator attempts installation again, this time displaying
3156 notifications and error messages.
3158 Only installation files signed with a certificate and private key are
3159 allowed to be installed onto Symbian devices. By default, Qt Creator
3160 self-signs the installation file. This self-signing allows you to install
3161 the application on a mobile device but places limits on what you can do
3162 with the installation file, including:
3164 \o Self-signed applications cannot access the more sensitive
3165 \l{Capabilities and Signing}{capabilities} of the mobile device.
3166 \o Security warnings will be displayed when you install the self-signed
3167 application on a mobile device.
3168 \o Self-signed applications cannot be distributed commercially on Ovi
3172 To get around these limitations, you need to go through the Symbian Signed
3173 process. The Symbian Signed organisation manages a public key
3174 infrastructure to provide public authentication of the information in the
3175 application signing certificates. Their security partner can validate your
3176 certificate and give you a Publisher ID. Then, when you sign an
3177 application, other people can be confident that the information in your
3178 certificate is correct and that the application does actually come from you.
3180 There are also options that do not require you to get a Publisher ID. For
3181 more detail about how the Symbian Signed process works, see
3182 \l{http://developer.symbian.org/wiki/index.php/Complete_Guide_To_Symbian_Signed}
3183 {Complete Guide to Symbian Signed}.
3185 When you have your own certificate and private key, you can specify them in
3186 the \gui{Create SIS Package} step in the run settings.
3188 \image qtcreator-qt4-symbian-signing.png
3191 If your private key is protected by a passphrase, Qt Creator asks you for the
3192 passphrase when the package is signed and offers to store it. However, storing
3193 passphrases in Qt Creator presents a security risk. To make Qt Creator forget
3194 all saved passphrases, click \gui {Reset Passphrases}.
3196 \section3 Capabilities and Signing
3198 Capabilities allow the Symbian platform to control access by applications to
3199 the functionality provided by the platform APIs. Access to capabilities is
3200 determined by the device configuration and how the application has been signed.
3202 Symbian Signed offers the following signing options depending on the
3203 capabilities that the application accesses:
3207 \o \bold{Express signed} for applications that access only user and system
3210 \o \bold{Certified signed} for applications that access also restricted or
3211 device manufacturer capabilities.
3213 \note You need to request the rights to access device manufacturer
3214 capabilities from the manufacturer.
3218 For more information about how to choose the appropriate signing option, see
3219 \l{http://developer.symbian.org/wiki/index.php/Symbian_Signed_For_Distributing_Your_Application}{Symbian Signed For Distributing Your Application}.
3221 If you select a signing option that does not allow the application to access
3222 the defined capabilities, installing the application on mobile devices
3223 fails. To avoid problems, only define capabilities and link libraries to a project
3224 if you really need them.
3226 For more information about capabilities and how you can check which ones you
3228 \l{http://developer.symbian.org/wiki/index.php/Capabilities_(Symbian_Signed)}{Capabilities (Symbian Signed)}
3230 \l{http://doc.qt.nokia.com/4.7/platform-notes-symbian.html#required-capabilities}{Required Capabilities for Qt Applications}.
3232 For more information on how to define capabilities for a project, see
3233 \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#capabilities}{Capabilities}.
3235 \section3 Creating Smart Installer for Symbian Packages
3237 To deploy Qt applications on Symbian devices, you must install the software that Qt applications
3238 require, typically Qt, QtWebkit, and Open C. Nokia Smart Installer for Symbian makes it easier
3239 for users to install Qt applications to Symbian phones by checking whether the device contains
3240 the necessary software and by installing the missing pieces.
3242 For this to work, the Nokia Smart Installer must be packaged with the Qt application. The
3243 application SIS file must first be Symbian Signed. The capabilities used in the applications
3244 determine, which signing option must be selected. The wrapper package must be signed using
3245 either the same option or a more extensive option than the application SIS.
3247 To package Nokia Smart Installer with the application, select the \gui {Create Smart Installer
3248 package} check box. This ensures that up-to-date and appropriate versions of Qt and its
3249 dependencies are installed on devices. Further, it reduces the file size of the application you
3250 publish, because you do not have to deliver the required applications.
3252 For more information about the Nokia Smart Installer, see the \e {Nokia Smart Installer for
3255 Note: Nokia Smart Installer for Symbian is only available on Windows.
3257 \section3 Application UID
3259 A UID is a globally unique identifier that is used to
3260 uniquely identify, for example, an object or file type. In Symbian development,
3261 objects are identified by compound identifiers that are constructed from three
3262 UIDs, namely UID1, UID2, and UID3. UID1 and UID2 specify the category of an
3263 object, whereas UID3 identifies a particular object, such as an application.
3265 When you create a \gui {Mobile Qt Application}, Qt Creator adds a UID3 suitable for
3266 development and debugging automatically to the application .pro file. However, to
3267 distribute your application and get it Symbian signed, you must apply for a UID
3268 from Symbian Signed, which manages the allocation of UIDs. You can request UIDs either one
3269 at a time or as preallocated blocks on the \l{https://www.symbiansigned.com/app/page}{Symbian Signed}
3272 Replace the testing UID with the distribution UID in the .pro file before you
3273 build the final installation package. For more information, see
3274 \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#unique-identifiers}{Unique Identifiers}.
3276 \section2 Specifying Run Settings for Maemo Devices
3278 To run an application on a Maemo device, create and select
3279 a device configuration in the Maemo run settings for your project.
3280 You can also pass command line arguments to your application.
3282 \image qtcreator-screenshot-run-settings.png "Run settings for Maemo devices"
3284 \section3 Deploying Applications to Maemo Devices
3286 You can specify settings for deploying applications to Maemo devices in the
3287 project .pro file. You can view the settings in the \gui {Run Settings}.
3289 When you test your application on a device or the Maemo emulator, you can
3290 save some time by installing the built files directly on the connected device
3291 without packaging. Select the \gui {Skip packaging step} check box in the
3292 \gui {Create Package} step. However, this is not recommended and is only supported
3293 for simple application projects.
3295 The files to be installed are listed in the
3296 \gui {Deploy to Device} step, the \gui {Files to install} field. The
3297 \gui {Local File Path} field displays the location of the file on the development
3298 PC. The \gui {Remote Directory} field displays the folder where the file is installed on
3301 \image qtcreator-maemo-deployment.png "Deploy to device"
3303 If you develop your own libraries, Qt Creator needs to be able to access them
3304 during compilation. When you install MADDE, an instance of the device file
3305 system, called sysroot, is installed to the development PC. Libraries are copied to
3306 sysroot if the \gui {Also deploy to sysroot} check box is selected.
3308 \section3 Creating Debian Installation Packages
3310 When you run the application on the \gui{Maemo} target, Qt Creator generates
3311 a debian installation package in the build directory by default. You can deliver
3312 the installation package to users for installation on Maemo devices that are of
3313 the same type and run the same firmware as the connected device.
3315 \image qtcreator-maemo-deb-package.png "Create installation package"
3317 The name of the installation package is displayed in the \gui {Create Package}
3318 field in the \gui {Run Settings}. You can change the version number in the \gui {Version number} field.
3320 Qt Creator provides templates for a set of files that must be included
3321 in debian packages. To edit the files, select a file in \gui {Adapt debian
3322 file} and click \gui Edit. The file opens in the text editor.
3324 The debian control file contains an application icon in encoded form. To add the
3325 application icon to the file, select it in the \gui {Package manager icon} field.
3326 For more information about icon files and adding them manually, see
3327 \l{ http://wiki.maemo.org/Packaging#Displaying_an_icon_in_the_Application_Manager_next_to_your_package}{Displaying an icon in the Application Manager next to your package}.
3329 \note Qt Creator automates this process for you.
3331 \section1 Specifying a Custom Executable to Run
3333 If you use cmake or the generic project type in Qt Creator, or want
3334 to run a custom desktop executable, create a \gui {Custom Executable}
3335 run configuration for your project.
3337 Specify the executable to run, command line arguments, working directory,
3338 and environment variables to use.
3340 \image qmldesigner-run-custom-exe.png "Run settings for custom executables"
3342 \section1 Specifying Run Settings for Qt Quick Projects
3344 Select run settings in the \gui {Run configuration} field. The settings
3345 are specified automatically and, you mostly need to change them if you
3346 develop applications that use both C++ and QML:
3350 \o \gui {Custom QML Viewer} is the path to the \QQV executable.
3351 Qt Creator ships with a specific version of \QQV and imported
3352 modules, which is used by default. If you develop Qt Quick applications
3353 that contain C++ plugins, you must select the \QQV version
3354 shipped with your Qt version here.
3356 \o \gui {QML Viewer arguments} sets arguments for running \QQV.
3357 The \c{-I <directory>} argument searches for C++ or QML plugins from
3358 the project folder. For a list of available arguments, enter \c {qml --help}
3359 on the command line.
3361 \o \gui {Main QML file} is the Qt Quick project file.
3363 \o \gui Debugger allows you to select the languages to debug:
3364 \gui{C++} and \gui QML. \gui {Debug port} is the port to access \QQV.
3365 You can use any free port in the registered port range.
3369 \image qmldesigner-run-settings.png "Run settings for Qt Quick projects"
3375 \contentspage index.html
3376 \previouspage creator-run-settings.html
3377 \page creator-editor-settings.html
3378 \nextpage creator-build-dependencies.html
3380 \title Specifying Editor Settings
3382 To define the default file encoding, select the desired encoding in \gui Projects >
3383 \gui{Editor Settings}. By default, the Qt Creator uses the file encoding
3384 used by your system.
3386 \image qtcreator-editor-settings.png "Editor Settings view"
3392 \contentspage index.html
3393 \previouspage creator-editor-settings.html
3394 \page creator-build-dependencies.html
3395 \nextpage creator-debugging.html
3397 \title Specifying Dependencies
3399 If you have multiple projects loaded in your session, you can define the
3400 dependencies between them. Inter-project dependencies affect the build
3401 order of your projects.
3403 \note Inter-project dependencies are unrelated inside a qmake
3406 \image qtcreator-build-dependencies.png "Dependencies view"
3408 To define the dependencies between projects:
3410 \o In \gui Projects, select a project.
3411 \o Click \gui Dependencies.
3412 \o Select projects as dependencies.
3419 \contentspage index.html
3420 \previouspage creator-quick-tour.html
3421 \page creator-getting-started.html
3422 \nextpage creator-build-example-application.html
3424 \title Getting Started
3426 This section contains examples that illustrate how to use Qt Creator
3427 to create, build, and run simple
3431 \o \l{Building and Running an Example Application}
3432 \o \l{Creating a Qt C++ Application}
3433 \o \l{Creating a Mobile Application with Nokia Qt SDK}
3434 \o \l{Creating a Qt Quick Application}
3441 \contentspage index.html
3442 \previouspage creator-writing-program.html
3443 \page creator-mobile-example.html
3444 \nextpage creator-qml-application.html
3446 \title Creating a Mobile Application with Nokia Qt SDK
3448 \note To complete this tutorial, you must install Nokia Qt SDK.
3449 The installation program installs and configures the necessary tool chains
3450 for mobile application development.
3452 This tutorial describes how to use Qt Creator to create a small Qt
3453 application, Battery Indicator, that uses the System Information
3454 Mobility API to fetch battery information from the device.
3456 \image qtcreator-batteryindicator-screenshot.png
3458 \section1 Creating the Battery Indicator Project
3460 \note Create the project with the \gui{Help} mode active so that you can follow
3461 these instructions while you work.
3465 \o Select \gui{File > New File or Project > Qt C++ Project > Mobile Qt
3466 Application > Choose}.
3468 \image qtcreator-new-mobile-project.png "New File or Project dialog"
3470 The \gui{Introduction and Project Location} dialog opens.
3472 \image qtcreator-mobile-intro-and-location.png "Introduction and Project Location dialog"
3474 \o In the \gui{Name} field, type \bold {BatteryIndicator}.
3476 \o In the \gui {Create in} field, enter the path for the project files. For example,
3477 \c {C:\Qt\examples}, and then click \gui{Next}.
3479 The \gui{Select Required Qt Versions} dialog opens.
3481 \image qtcreator-mobile-project-qt-versions.png "Select Required Qt Versions dialog"
3483 \o Select \gui Maemo, \gui {Qt Simulator}, and \gui {Symbian Device} targets,
3484 and click \gui{Next}.
3486 \note Targets are listed if you installed the appropriate development
3487 environment, for example, as part of the Nokia Qt SDK.
3489 The \gui{Class Information} dialog opens.
3491 \image qtcreator-mobile-class-info.png "Class Information dialog"
3493 \o In the \gui{Class Name} field, type \bold {BatteryIndicator} as the class name.
3495 \o In the \gui{Base Class} list, select \bold {QDialog} as the base class type.
3497 \note The \gui{Header File}, \gui{Source File} and \gui{Form File} fields are
3498 automatically updated to match the name of the class.
3500 \o Click \gui{Next}.
3502 The \gui{Project Management} dialog opens.
3504 \image qtcreator-mobile-project-summary.png "Project Management dialog"
3506 \o Review the project settings, and click \gui{Finish} to create the project.
3510 The BatteryIndicator project now contains the following files:
3514 \o batteryindicator.h
3515 \o batteryindicator.cpp
3517 \o batteryindicator.ui
3518 \o BatteryIndicator.pro
3522 \image qtcreator-mobile-project-contents.png "Project contents"
3524 The files come with the necessary boiler plate code that you must
3525 modify, as described in the following sections. You do not need
3526 to change the main.cpp file.
3528 \section1 Declaring the Qt Mobility API
3530 The \gui New wizard automatically adds information to the .pro file
3531 that you need when you use the Qt Mobility APIs or develop applications
3532 for Symbian devices. You must modify the information to declare the
3533 Qt Mobility APIs that you use.
3535 This example uses the System Info API, so you must declare it, as
3536 illustrated by the following code snippet:
3541 MOBILITY = systeminfo
3545 Each Mobility API has its corresponding value that you have to add
3546 as a value of MOBILITY to use the API. For a list of the APIs and the
3547 corresponding values that you can assign to MOBILITY, see the
3548 \l {http://doc.qt.nokia.com/qtmobility-1.0/quickstart.html}{Quickstart Example}.
3550 The following code snippet shows information that is needed for
3551 applications developed for Symbian device. Qt Creator generated
3552 the UID for testing the application on a device. You only need
3553 to change the UID and capabilities if you deliver the application
3554 for public use and need to have it Symbian Signed.
3559 TARGET.UID3 = 0xecbd72d7
3560 # TARGET.CAPABILITY +=
3561 TARGET.EPOCSTACKSIZE = 0x14000
3562 TARGET.EPOCHEAPSIZE = 0x020000 0x800000
3567 \section1 Designing the User Interface
3571 \o In the \gui{Editor} mode, double-click the batteryindicator.ui
3572 file in the \gui{Projects} view to launch the integrated \QD.
3574 \o Drag and drop a \gui{Progress Bar} (\l{http://doc.qt.nokia.com/4.7/qprogressbar.html}{QProgressBar})
3577 \image qtcreator-mobile-project-widgets.png "Adding widgets to the UI"
3579 \o In the \gui Properties pane, change the \gui objectName to
3580 \bold batteryLevelBar.
3582 \o Right-click the \gui BatteryIndicator object and select
3583 \gui {Lay Out > Lay Out Horizontally} to ensure that the battery
3584 indicator widget size is adjusted correctly on Maemo devices.
3586 To adjust widget size correctly on Qt Simulator, remove the condition
3587 from the main.cpp file (displayed in the following code snippet) and just
3588 leave the \c {w.showMaximized();} line:
3590 \snippet examples/batteryindicator/main.cpp 0
3595 \section1 Completing the Header File
3597 The batteryindicator.h file contains some of the necessary #includes, a
3598 constructor, a destructor, and the \c{Ui} object. You must include
3599 the System Info header file, add a shortcut to the mobility name
3600 space, and add a private function to update the battery level value in
3601 the indicator when the battery power level changes.
3605 \o In the \gui{Projects} view, double-click the \c{batteryindicator.h} file
3606 to open it for editing.
3608 \o Include the System Info header file, as illustrated by the following
3611 \snippet examples/batteryindicator/batteryindicator.h 1
3613 \o Add a shortcut to the mobility name space, as illustrated by the
3614 following code snippet:
3616 \snippet examples/batteryindicator/batteryindicator.h 2
3618 \o Declare a private function in the \c{private} section, after the
3619 \c{Ui::BatteryIndicator} function, as illustrated by the following code
3622 \snippet examples/batteryindicator/batteryindicator.h 3
3626 \section1 Completing the Source File
3628 Now that the header file is complete, move on to the source file,
3629 batteryindicator.cpp.
3633 \o In the \gui{Projects} view, double-click the batteryindicator.cpp file
3634 to open it for editing.
3636 \o Create a QSystemDeviceInfo object and set its value. Then connect the signal
3637 that indicates that battery level changed to the \c setValue
3638 slot of the progress bar. This is illustrated by the following code snippet:
3640 \snippet examples/batteryindicator/batteryindicator.cpp 1
3642 \o Use the constructor to set initial values and make sure that the
3643 created object is in a defined state, as illustrated by the following
3646 \snippet examples/batteryindicator/batteryindicator.cpp 2
3650 \section1 Compiling and Running Your Program
3652 Now that you have all the necessary code, select \gui {Qt Simulator}
3653 as the target and click the
3654 \inlineimage qtcreator-run.png
3655 button to build your program and run it in the Qt Simulator.
3657 In Qt Simulator, run the runOutOfBattery.qs example script
3658 to see the value change in the Battery Indicator application.
3659 Select \gui {Scripting > examples > runOutOfBattery.qs > Run}.
3661 \image qtcreator-mobile-simulated.png "Mobile example in Qt Simulator"
3663 \section1 Testing on a Symbian Device
3665 You also need to test the application on real devices. Before you can
3666 start testing on Symbian devices, you must connect them to the development
3667 PC by using an USB cable and install the necessary software on them.
3671 \o Install Qt 4.6.2 libraries, the Qt mobile libraries, and the TRK
3672 debugging application on the device. For more information,
3673 see \l{Setting Up Development Environment for Symbian}.
3675 \o Start TRK on the device.
3677 \o Click the \gui {Target Selector} and select \gui {Symbian Device}.
3679 \o Click \gui Run to build the application for the Symbian device.
3683 \section1 Testing on the Maemo Emulator
3685 The Maemo emulator emulates the Nokia N900 device environment. You can test
3686 applications in conditions practically identical to running the application
3687 on a Nokia N900 device with the software update release 1.2 (V10.2010.19-1).
3689 For more information, see \l{Using the Maemo Emulator}.
3694 \contentspage index.html
3695 \previouspage creator-getting-started.html
3696 \page creator-build-example-application.html
3697 \nextpage creator-writing-program.html
3699 \title Building and Running an Example Application
3701 You can test that your installation is successful by opening an existing
3702 example application project.
3706 \o On the \gui Welcome page, select \gui {Choose an Example... >
3707 Animation Framework > Animated Tiles}.
3709 \image qtcreator-gs-build-example-open.png "Selecting an example"
3711 \o Select targets for the project. Select at least Qt Simulator
3712 and one of the mobile targets, Maemo or Symbian Device, depending on
3713 the device you develop for.
3715 \image qtcreator-gs-build-example-targets.png "Selecting targets"
3717 \note You can add targets later in the \gui Projects mode.
3719 \o To test the application in Qt Simulator, click the \gui {Target
3720 Selector} and select \gui {Qt Simulator}.
3722 \image {qtcreator-gs-build-example-select-qs.png} "Selecting Qt Simulator as target"
3725 \inlineimage{qtcreator-run.png}
3726 to build the application and run it in Qt Simulator.
3728 \o To see the compilation progress, press \key{Alt+4} to open the
3729 \gui Compile Output pane.
3731 The \gui Build progress bar on the toolbar turns green when the project
3732 is successfully built. The application opens in Qt Simulator.
3734 \image {qt-simulator.png} "Qt Simulator"
3736 \o Change the settings in the
3737 \gui View pane, for example, to toggle the orientation by clicking
3738 \gui {Rotate Device}, or choose from the various Symbian and Maemo
3739 configurations by clicking \gui {Device}. You can also simulate various
3740 mobile functions and create your own scripts.
3742 \o To test the application on a Symbian device install Qt 4.6.2
3743 and the TRK debugging application on the device. For more information,
3744 see \l{Setting Up Development Environment for Symbian}.
3746 \o Click the \gui {Target Selector} and select \gui {Symbian Device}.
3748 \o Click \gui Run to build the application for the Symbian device.
3756 \contentspage index.html
3757 \previouspage creator-mobile-example.html
3758 \page creator-qml-application.html
3759 \nextpage creator-project-managing.html
3761 \title Creating a Qt Quick Application
3763 \note This tutorial assumes that you are familiar with the \l {http://doc.qt.nokia.com/4.7/qtquick.html}
3764 {QML declarative language}.
3766 This tutorial describes how to use Qt Creator to create a small
3767 Qt Quick application, Hello World.
3769 \image qmldesigner-helloworld-edited.png "Hello World"
3771 \section1 Creating the Hello World Project
3775 \o Select \gui{File > New File or Project > Qt Quick Project > Qt QML Application > Choose}.
3777 \image qmldesigner-new-project.png "New File or Project dialog"
3779 The \gui{Introduction and Project Location} dialog opens.
3781 \image qmldesigner-new-project-location.png "Introduction and Project Location dialog"
3783 \o In the \gui{Name} field, type \bold {HelloWorld}.
3785 \o In the \gui {Create in} field, enter the path for the project files. For example,
3786 \c {C:\Qt\examples}, and then click \gui{Next}.
3788 The \gui{Project Management} dialog opens.
3790 \image qmldesigner-new-project-summary.png "Project Management dialog"
3792 \o Review the project settings, and click \gui{Finish} to create the project.
3796 The HelloWorld project now contains the following files:
3799 \o HelloWorld.qmlproject
3803 The \gui Projects pane in the \gui Sidebar displays the project files:
3805 \image qmldesigner-new-project-contents.png "HelloWorld project contents"
3807 The .qmlproject file defines that all QML, JavaScript, and image files in
3808 the project folder belong to the project.
3810 The .qml file contains the following example code that specifies a rectangle
3811 and a label that contains
3812 the text \bold {Hello World}.
3830 Your application is now ready.
3832 \section1 Running the Application
3834 Press \key {Ctrl+R} to run the application in the QML Viewer.
3838 \image qmldesigner-helloworld.png "Hello World"
3840 \section1 Changing Hello World Properties
3842 To experiment with QML and to try some of the code editor features, change the
3843 properties of the rectangle and text. Move the cursor on \gui Rectangle and
3844 press \key F1 to get help on the available properties. Try adding a \gui color
3845 property to the \gui Rectangle. When you start to type,
3846 the code completion feature of the code editor suggests properties, IDs, and
3847 code snippets to complete the code. Select an item in the list and press
3848 \key Tab or \key Enter to complete the code.
3850 The code editor checks the code syntax and underlines syntax errors.
3851 Move the cursor over an error to display detailed information about it.
3853 The following code illustrates how to set the backround color
3854 to light steel blue and the text color to white:
3863 color: "lightsteelblue"
3874 \image qmldesigner-helloworld-edited.png "Hello World in blue and white"
3880 \contentspage index.html
3881 \previouspage creator-build-example-application.html
3882 \page creator-writing-program.html
3883 \nextpage creator-mobile-example.html
3885 \title Creating a Qt C++ Application
3887 This tutorial describes how to use Qt Creator
3888 to create a small Qt application, Text Finder. It is a simplified version of the
3889 QtUiTools \l{http://doc.qt.nokia.com/4.7/uitools-textfinder.html}{Text Finder}
3892 \image qtcreator-textfinder-screenshot.png
3894 \section1 Creating the Text Finder Project
3896 \note Create the project with two instances of Qt Creator open and the \gui{Help} mode
3897 active in one of them so that you can follow
3898 these instructions while you work.
3902 \o Select \gui{File > New File or Project > Qt C++ Project > Qt Gui
3903 Application > Choose}.
3905 \image qtcreator-new-project.png "New File or Project dialog"
3907 The \gui{Introduction and Project Location} dialog opens.
3909 \image qtcreator-intro-and-location.png "Introduction and Project Location dialog"
3911 \o In the \gui{Name} field, type \bold {TextFinder}.
3914 \o In the \gui {Create in} field, enter the path for the project files. For example,
3915 \c {C:\Qt\examples}, and then click \gui{Next}.
3917 The target setting dialog opens.
3919 \image qtcreator-new-project-qt-versions.png "Target setting dialog"
3921 \o Select the Qt versions to use as build targets for your project, and click
3924 \note If you have only one Qt version installed, this dialog is skipped.
3926 The \gui{Class Information} dialog opens.
3928 \image qtcreator-class-info.png "Class Information dialog"
3930 \o In the \gui{Class Name} field, type \bold {TextFinder} as the class name.
3932 \o In the \gui{Base Class} list, select \bold {QWidget} as the base class type.
3934 \note The \gui{Header File}, \gui{Source File} and
3935 \gui{Form File} fields are automatically updated to match the name of the
3938 \o Click \gui{Next}.
3940 The \gui{Project Management} dialog opens.
3942 \image qtcreator-new-project-summary.png "Project Management dialog"
3944 \o Review the project settings, and click \gui{Finish} to create the project.
3951 The TextFinder project now contains the following files:
3961 \image qtcreator-textfinder-contents.png "TextFinder project contents"
3963 The .h and .cpp files come with the necessary boiler plate code.
3964 The .pro file is complete.
3966 \section1 Filling in the Missing Pieces
3968 Begin by designing the user interface and then move on to filling
3969 in the missing code. Finally, add the find functionality.
3971 \section2 Designing the User Interface
3973 \image qtcreator-textfinder-ui.png "Text Finder UI"
3977 \o In the \gui{Editor} mode, double-click the textfinder.ui file in the \gui{Projects}
3978 view to launch the integrated \QD.
3980 \o Drag and drop the following widgets to the form:
3983 \o \gui{Label} (QLabel)
3984 \o \gui{Line Edit} (QLineEdit)
3985 \o \gui{Push Button} (QPushButton)
3989 \image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI"
3991 \note To easily locate the widgets, use the search box at the top of the
3992 \gui Sidebar. For example, to find the \gui Label widget, start typing
3993 the word \bold label.
3995 \image qtcreator-texfinder-filter.png "Filter field"
3997 \o Double-click the \gui{Label} widget and enter the text \bold{Keyword}.
3999 \o Double-click the \gui{Push Button} widget and enter the text \bold{Find}.
4001 \o In the \gui Properties pane, change the \gui objectName to \bold findButton.
4003 \image qtcreator-textfinder-objectname.png "Changing object names"
4005 \o Press \key {Ctrl+A} to select the widgets and click \gui{Lay out Horizontally}
4006 (or press \gui{Ctrl+H}) to apply a horizontal layout
4009 \image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout"
4011 \o Drag and drop a \gui{Text Edit} widget (QTextEdit)
4014 \o Select the screen area and click \gui{Lay out Vertically} (or press \gui{Ctrl+L})
4015 to apply a vertical layout (QVBoxLayout).
4017 \image qtcreator-textfinder-ui.png "Text Finder UI"
4019 Applying the horizontal and vertical layouts ensures that the application UI scales to different
4022 \o To call a find function when users press the \gui Find button, you use the Qt signals
4023 and slots mechanism. A signal is emitted when a particular event occurs and a slot is
4024 a function that is called in response to a particular signal. Qt widgets have predefined
4025 signals and slots that you can use directly from \QD. To add a slot for the find function:
4029 \o Right-click the \gui Find button to open a context-menu.
4030 \o Select \gui {Go to Slot > clicked()}, and then select \gui OK.
4032 A private slot, \c{on_findButton_clicked()}, is added to the header file,
4033 textfinder.h and a private function, \c{TextFinder::on_findButton_clicked()},
4034 is added to the source file, textfinder.cpp.
4038 \o Press \gui{Ctrl+S} to save your changes.
4042 For more information about designing forms with \QD, see the
4043 \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
4045 \section2 Completing the Header File
4047 The textfinder.h file already has the necessary #includes, a
4048 constructor, a destructor, and the \c{Ui} object. You need to add a private
4049 function, \c{loadTextFile()}, to read and display the
4050 contents of the input text file in the
4055 \o In the \gui{Projects} pane in the \gui {Edit view}, double-click the \c{textfinder.h} file
4056 to open it for editing.
4058 \o Add a private function
4059 to the \c{private} section, after the \c{Ui::TextFinder} pointer, as
4060 illustrated by the following code snippet:
4062 \snippet examples/textfinder/textfinder.h 0
4066 \section2 Completing the Source File
4068 Now that the header file is complete, move on to the source file,
4073 \o In the \gui{Projects} pane in the \gui Edit view, double-click the textfinder.cpp file
4074 to open it for editing.
4076 \o Add code to load a text file using
4077 QFile, read it with QTextStream, and
4078 then display it on \c{textEdit} with
4079 \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}.
4080 This is illustrated by the following code snippet:
4082 \snippet examples/textfinder/textfinder.cpp 0
4084 \o To use QFile and QTextStream, add the
4085 following #includes to textfinder.cpp:
4087 \snippet examples/textfinder/textfinder.cpp 1
4089 \o For the \c{on_findButton_clicked()} slot, add code to extract the search string and
4090 use the \l{http://doc.qt.nokia.com/4.7/qtextedit.html#find}{find()} function
4091 to look for the search string within the text file. This is illustrated by
4092 the following code snippet:
4094 \snippet examples/textfinder/textfinder.cpp 2
4096 \o Once both of these functions are complete, add a line to call \c{loadTextFile()} in
4097 the constructor, as illustrated by the following code snippet:
4099 \snippet examples/textfinder/textfinder.cpp 3
4103 The \c{on_findButton_clicked()} slot is called automatically in
4104 the uic generated ui_textfinder.h file by this line of code:
4107 QMetaObject::connectSlotsByName(TextFinder);
4110 \section2 Creating a Resource File
4112 You need a resource file (.qrc) within which you embed the input
4113 text file. The input file can be any .txt file with a paragraph of text.
4114 Create a text file called input.txt and store it in the textfinder
4117 To add a resource file:
4119 \o Select \gui{File > New File or Project > Qt > Qt Resource File > Choose}.
4120 \image qtcreator-add-resource-wizard.png "New File or Project dialog"
4122 The \gui {Choose the Location} dialog opens.
4124 \image qtcreator-add-resource-wizard2.png "Choose the Location dialog"
4126 \o In the \gui{Name} field, enter \bold{textfinder}.
4127 \o In the \gui{Path} field, enter \c{C:\Qt\examples\TextFinder},
4128 and click \gui{Next}.
4130 The \gui{Project Management} dialog opens.
4132 \image qtcreator-add-resource-wizard3.png "Project Management dialog"
4135 \o In the \gui{Add to project} field, select \bold{TextFinder.pro}
4136 and click \gui{Finish} to open the file in the code editor.
4138 \o Select \gui{Add > Add Prefix}.
4139 \o In the \gui{Prefix} field, replace the default prefix with a slash (/).
4140 \o Select \gui{Add > Add Files}, to locate and add input.txt.
4142 \image qtcreator-add-resource.png "Editing resource files"
4146 \section1 Compiling and Running Your Program
4148 Now that you have all the necessary files, click the \inlineimage qtcreator-run.png
4149 button to compile and run your program.
4155 \contentspage index.html
4156 \previouspage creator-maemo-emulator.html
4157 \page creator-version-control.html
4158 \nextpage creator-task-lists.html
4160 \title Using Version Control Systems
4162 Version control systems supported by Qt Creator are:
4165 \i \bold{Version Control System}
4170 \i \l{http://git-scm.com/}
4173 \i \bold{Subversion}
4174 \i \l{http://subversion.tigris.org/}
4178 \i \l{http://www.perforce.com}
4179 \i Server version 2006.1 and later
4182 \i \l{http://www.cvshome.org}
4186 \i \l{http://mercurial.selenic.com/}
4187 \i Qt Creator 2.0 and later
4191 \section1 Setting Up Version Control Systems
4193 Qt Creator uses the version control system's command line clients to access
4194 your repositories. To allow access, make sure that the command line clients
4195 can be located using the \c{PATH} environment variable or specify the path to
4196 the command line client executables in \gui{Tools} > \gui{Options...} >
4197 \gui {Version Control}.
4199 After you set up the version control system, use the command line to check
4200 that everything works (for example, use the status command). If no issues arise,
4201 you should be ready to use the system also from Qt Creator.
4203 \section2 Using msysGit on Windows
4205 If you configure Git for use with \c {git bash}, only, and use SSH
4206 authorization, Git looks for the SSH keys in the directory where the
4207 \c HOME environment points to. The variable is always set by \c {git bash}.
4209 However, the variable is typically not set in a Windows command prompt.
4210 When you run Git from a Windows command prompt, it looks for the SSH keys in its
4211 installation directory, and therefore, the authorization fails.
4213 You can set the \c HOME environment variable from Qt Creator. Select \gui {Tools >
4214 Options... > Version Control > Git}. Select the \gui {Environment Variables}
4215 and the \gui {Set "HOME" environment variable} check boxes. \c HOME is set to
4216 \c %HOMEDRIVE%%HOMEPATH% when the Git executable is run and authorization works
4217 as it would with \c {git bash}.
4219 \section1 Setting Up Common Options
4221 Select \gui{Tools} > \gui{Options...} > \gui{Version Control} > \gui{Common}
4222 to specify settings for submit messages:
4224 \o \gui{Submit message check script} is a script or program that
4225 can be used to perform checks on the submit message before
4226 submitting. The submit message is passed in as the script's first
4227 parameter. If there is an error, the script should output a
4228 message on standard error and return a non-zero exit code.
4230 \o \gui{User/alias configuration file} takes a file in mailmap format
4231 that lists user names and aliases. For example:
4234 Jon Doe <Jon.Doe@company.com>
4235 Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
4238 \note The second line above specifies the alias \e{hm} and the
4239 corresponding email address for \e{Hans Mustermann}. If the
4240 user/alias configuration file is present, the submit editor
4241 displays a context menu with \gui{Insert name...} that pops up a
4242 dialog letting the user select a name.
4244 \o \gui{User fields configuration file} is a simple text file
4245 consisting of lines specifying submit message fields that take
4246 user names, for example:
4254 The fields above appear below the submit message. They provide completion
4255 for the aliases/public user names specified in the
4256 \e{User/alias configuration file} as well as a button that opens the
4257 aforementioned user name dialog.
4259 \section1 Creating VCS Repositories for New Projects
4261 Qt Creator allows for creating VCS repositories for version
4262 control systems that support local repository creation, such as
4264 When creating a new project by selecting \gui File >
4265 \gui{New File or Project...}, you can choose a version
4266 control system in the final wizard page.
4268 \section1 Using Version Control Systems
4270 The \gui{Tools} menu contains a sub-menu for each supported version
4273 The \gui{Version Control} output pane displays the commands
4274 that are executed, a timestamp, and the relevant output.
4275 Select \gui {Window > Output Panes > Version Control} to open
4279 \image qtcreator-vcs-pane.png
4282 \section2 Adding Files
4284 When you create a new file or a new project, the wizard displays a page
4285 asking whether the files should be added to a version control system.
4286 This happens when the parent directory or the project is already
4287 under version control and the system supports the concept of adding files,
4288 for example, Perforce and Subversion. Alternatively, you can
4289 add files later by using the version control tool menus.
4291 With Git, there is no concept of adding files. Instead, all modified
4292 files must be staged for a commit.
4295 \section2 Viewing Diff Output
4297 All version control systems provide menu options to \e{diff} the current
4298 file or project: to compare it with the latest version stored in the
4299 repository and to display the differences. In Qt Creator, a diff is
4300 displayed in a read-only editor. If the file is accessible, you can
4301 double-click on a selected diff chunk and Qt Creator opens an editor
4302 displaying the file, scrolled to the line in question.
4304 \image qtcreator-vcs-diff.png
4307 \section2 Viewing Versioning History and Change Details
4309 Display the versioning history of a file by selecting \gui{Log}
4310 (for Git and Mercurial) or \gui{Filelog} (for CVS, Perforce, and
4311 Subversion). Typically, the log output contains the date, the commit
4312 message, and a change or revision identifier. Click on the identifier to
4313 display a description of the change including the diff.
4314 Right-clicking on an identifier brings up a context menu that lets you
4315 show annotation views of previous versions (see \l{Annotating Files}).
4317 \image qtcreator-vcs-log.png
4320 \section2 Annotating Files
4322 Annotation views are obtained by selecting \gui{Annotate} or \gui{Blame}.
4323 Selecting \gui{Annotate} or \gui{Blame} displays the lines of the file
4324 prepended by the change identifier they originate from. Clicking on the
4325 change identifier shows a detailed description of the change.
4327 To show the annotation of a previous version, right-click on the
4328 version identifier at the beginning of a line and choose one of the
4329 revisions shown at the bottom of the context menu. This allows you to
4330 navigate through the history of the file and obtain previous versions of
4331 it. It also works for Git and Mercurial using SHA's.
4333 The same context menu is available when right-clicking on a version
4334 identifier in the file log view of a single file.
4337 \section2 Committing Changes
4339 Once you have finished making changes, submit them to the version control
4340 system by choosing \gui{Commit} or \gui{Submit}. Qt Creator displays a
4341 commit page containing a text editor where you can enter your commit
4342 message and a checkable list of modified files to be included.
4344 \image qtcreator-vcs-commit.png
4346 When you have finished filling out the commit page information, click on
4347 \gui{Commit} to start committing.
4349 The \gui{Diff Selected Files} button brings up a diff view of the
4350 files selected in the file list. Since the commit page is just another
4351 editor, you can go back to it by closing the diff view. You can also check
4352 a diff view from the editor combo box showing the \gui{Opened files}.
4355 \section2 Reverting Changes
4357 To discard local changes to a file or project, use the \gui Revert
4358 function or the \gui {Undo Changes/Undo Repository Changes} function
4359 (for Git). The changes discarded depend on the version control system.
4361 For example, in Perforce, select \gui{Revert File/Revert Project}
4362 to discard changes made to open files, reverting them to the
4363 revisions last synchronized from the repository. Select
4364 \gui{Revert Unchanged} to revert files if their contents or file
4365 type have not changed after they were opened for editing.
4367 \section2 Using Additional Git Functions
4369 The \gui Git sub-menu contains the following additional items:
4374 \i \gui {Apply Patch/Apply Patch...}
4375 \i Apply changes to a file or project from a diff file. You can
4376 either apply a patch file that is open in Qt Creator or select
4377 the patch file to apply from the file system.
4379 \i \gui{Stash Snapshot...}
4380 \i Save a snapshot of your current
4381 work under a name for later reference. For example, if you
4382 want to try out something and find out later that it does not work,
4383 you can discard it and return to the state of the snapshot.
4386 \i Stash local changes prior to executing a \gui{Pull}.
4389 \i Remove a single stashed state from the stash list and apply it on
4390 top of the current working tree state.
4393 \i Pull changes from the remote repository. If there are locally
4394 modified files, you are prompted to stash those changes.
4395 The \gui Git options page contains an option to do
4396 a rebase operation while pulling.
4399 \i \gui{Clean Repository.../Clean Project...}
4400 \i Collect all files that are not under version control
4401 with the exception of patches and project files
4402 and show them as a checkable list in a dialog
4403 prompting for deletion. This lets you completely clean a build.
4406 \i \gui{Branches...}
4407 \i Displays the branch dialog showing the local branches at the
4408 top and remote branches at the bottom. To switch to the local
4409 branch, double-click on it. Double-clicking on a remote
4410 branch first creates a local branch with the same name that
4411 tracks the remote branch, and then switches to it.
4413 \image qtcreator-vcs-gitbranch.png
4418 \i Displays a dialog showing the stashes created by
4419 \gui{Stash Snapshot...} with options to restore,
4420 display or delete them.
4422 \i \gui {Stage File for Commit}
4423 \i Mark new or modified files for committing to the repository.
4424 To undo this function, select \gui {Unstage File from Commit}.
4426 \i \gui{Show Commit...}
4427 \i Select a commit to view. Enter the SHA of the commit
4428 in the \gui Change field.
4431 \section2 Using Additional Mercurial Functions
4433 The \gui Mercurial sub-menu contains the following additional items:
4438 \i Apply changes from a patch file.
4441 \i Monitor the status of a remote repository by listing
4442 the changes that will be pulled.
4445 \i Monitor the status of a remote repository by listing
4446 the changes that will be pushed.
4449 \i Pull changes from the remote repository.
4452 \i Look at an earlier version of the code.
4455 \section2 Using Additional Perforce Functions
4457 When you start Qt Creator, it looks for the executable specified
4458 in the \gui{P4 command} field in \gui{Tools > Options... > Version
4459 Control > Perforce}. If you do not use Perforce and want to turn
4460 off the check, clear this field.
4462 The \gui Perforce sub-menu contains the following additional items:
4466 \i \gui{Describe...}
4467 \i View information about changelists and the files in them.
4470 \i Open a file for editing.
4473 \i List files that are open for editing.
4475 \i \gui{Pending Changes...}
4476 \i Group files for commit.
4478 \i \gui{Update All/Update Current Project}
4479 \i Fetch the current version of the current project or all
4480 projects from the repository.
4485 \section2 Using Additional Subversion Functions
4487 The \gui Subversion sub-menu contains the following additional items:
4491 \i \gui{Describe...}
4492 \i Display commit log messages for a revision.
4494 \i \gui{Update Project/Update Repository}
4495 \i Update your working copy.
4504 \contentspage index.html
4505 \previouspage qt-quick-toolbars.html
4506 \page creator-editor-locator.html
4507 \nextpage creator-editor-codepasting.html
4509 \title Searching With the Locator
4511 The locator provides one of the easiest ways in Qt Creator to browse
4512 through projects, files, classes, methods, documentation and file systems.
4513 You can find the locator in the bottom left of the Qt Creator window.
4515 To activate the locator, press \key Ctrl+K (\key Cmd+K on Mac OS
4516 X) or select \gui Tools > \gui Locate....
4518 \image qtcreator-locator.png
4520 To edit the currently open project's main.cpp file using the locator:
4522 \o Activate the locator by pressing \key Ctrl+K.
4523 \o Enter \tt{main.cpp}.
4525 \image qtcreator-locator-open.png
4526 \o Press \key Return.
4528 The main.cpp file opens in the editor.
4531 It is also possible to enter only a part of a search string.
4532 As you type, the locator shows the occurrences of that string regardless
4533 of where in the name of an component it appears.
4535 To narrow down the search results, you can use the following wildcard
4538 \o To match any number of any or no characters, enter \bold{*}.
4539 \o To match a single instance of any character, enter \bold{?}.
4542 \section1 Using the Locator Filters
4544 The locator allows you to browse not only files, but any items
4545 defined by \bold{locator filters}. By default, the locator contains
4546 filters which locate:
4548 \o Any open document
4549 \o Files anywhere on your file system
4550 \o Files belonging to your project, such as source, header resource,
4552 \o Class and method definitions in your project or anywhere referenced
4554 \o Help topics, including Qt documentation
4555 \o Specific line in the document displayed in your editor
4558 To use a specific locator filter, type the assigned prefix followed by
4559 \key Space. The prefix is usually a single character.
4561 For example, to locate symbols matching
4564 \o Activate the locator.
4565 \o Enter \tt{\bold{: QDataStream}} (: (colon) followed by a
4566 \key Space and the symbol name (QDataStream)).
4568 The locator lists the results.
4570 \image qtcreator-navigate-popup.png
4573 By default the following filters are enabled and you do not need to use
4574 their prefixes explicitly:
4576 \o Going to a line in the current file (l).
4577 \o Going to an open file (o).
4578 \o Going to a file in any open project (a).
4581 \section2 Using the Default Locator Filters
4583 The following locator filters are available by default:
4591 \o Go to a line in the current file.
4592 \o \tt{\bold{l \e{Line number}}}
4593 \o \image qtcreator-locator-line.png
4595 \o Go to a symbol definition.
4596 \o \tt{\bold{: \e{Symbol name}}}
4597 \o \image qtcreator-locator-symbols.png
4599 \o Go to a help topic.
4600 \o \tt{\bold{? \e{Help topic}}}
4601 \o \image qtcreator-locator-help.png
4603 \o Go to an open file.
4604 \o \tt{\bold{o \e{File name}}}
4605 \o \image qtcreator-locator-opendocs.png
4607 \o Go to a file in the file system (browse the file system).
4608 \o \tt{\bold{f \e{File name}}}
4609 \o \image qtcreator-locator-filesystem.png
4611 \o Go to a file in any project currently open.
4612 \o \tt{\bold{a \e{File name}}}
4613 \o \image qtcreator-locator-files.png
4615 \o Go to a file in the current project.
4616 \o \tt{\bold{p \e{File name}}}
4617 \o \image qtcreator-locator-current-project.png
4619 \o Go to a class definition.
4620 \o \tt{\bold{c \e{Class name}}}
4621 \o \image qtcreator-locator-classes.png
4623 \o Go to a method definition.
4624 \o \tt{\bold{m \e{Method name}}}
4625 \o \image qtcreator-locator-methods.png
4628 \section2 Creating Locator Filters
4630 To quickly access files not directly mentioned in your project, you can
4631 create your own locator filters. That way you can locate files in a
4632 directory structure you have defined.
4634 To create a locator filter:
4636 \o In the locator, click \inlineimage qtcreator-locator-magnify.png
4637 and select \gui Configure.... to open the \gui Locator options.
4639 \image qtcreator-locator-customize.png
4642 \o In the \gui{Filter Configuration} dialog:
4644 \o Name your filter.
4645 \o Select at least one directory. The locator searches directories
4647 \o Define the file pattern as a comma separated list. For example,
4648 to search all .h and .cpp files, enter \bold{*.h,*.cpp}
4649 \o Specify the prefix string.
4651 To show only results matching this filter, select
4652 \gui{Limit to prefix}.
4654 \image qtcreator-navigate-customfilter.png
4659 \section3 Configuring the Locator Cache
4661 The locator searches the files matching your file pattern in the
4662 directories you have selected and caches that information. The cache for
4663 all default filters is updated as you write your code. By default,
4664 Qt Creator updates the filters created by you once an hour.
4666 To update the cached information manually, click
4667 \inlineimage qtcreator-locator-magnify.png
4668 and select \gui Refresh.
4670 To set a new cache update time:
4672 \o Select \gui Tools > \gui Options... > \gui Locator.
4673 \o In \gui{Refresh interval}, define new time in minutes.
4680 \contentspage index.html
4681 \previouspage creator-developing-symbian.html
4682 \page creator-project-managing-sessions.html
4683 \nextpage creator-project-wizards.html
4685 \title Managing Sessions
4687 When you exit Qt Creator, a snapshot of your current workspace is stored
4688 as a \e session. A session is an arbitrary collection of:
4691 \o Open projects with their dependencies (including SUBDIRS projects)
4693 \o Breakpoints and watches
4697 A session is personal, that is, not meant to be shared. It is not
4698 supposed to reflect the project structure. It contains personal data, such as
4699 bookmarks and breakpoints that are usually not of interest to other developers
4700 working on the same projects.
4702 For example, if you work on a project and need to switch to another project for a
4703 while, you can save your workspace as a session. This makes it easier
4704 to return to working on the first project later.
4706 To create a new session or remove existing sessions, select \gui File >
4707 \gui Sessions > \gui{Session Manager}.
4709 \image qtcreator-session-manager.png
4711 To switch between sessions, choose
4712 \gui File > \gui Session. If you do not create or select a session,
4713 Qt Creator always uses the default session, which was created the
4714 last time you exited Qt Creator.
4716 When you launch Qt Creator, a list of existing sessions is displayed on the
4717 \gui{Welcome screen}.
4719 \image qtcreator-welcome-session.png
4725 \contentspage index.html
4726 \previouspage creator-build-dependencies.html
4727 \page creator-debugging.html
4728 \nextpage creator-debugging-example.html
4732 Qt Creator does not include a debugger. It provides a debugger plugin that acts
4733 as an interface between the Qt Creator core and external native debuggers
4734 such as the GNU Symbolic Debugger (gdb), the Microsoft Console Debugger (CDB),
4735 and an internal Java Script debugger. You can use the native debuggers to
4736 debug the C++ language.
4738 The following sections describe debugging with Qt Creator:
4742 \o \l{Debugging the Example Application} uses an example application to illustrate
4743 how to debug applications in the \gui Debug mode.
4745 \o \l{Interacting with the Debugger} describes the views and functions available
4746 in the \gui Debug mode.
4748 \o \l{Setting Up Debugger} summarizes the support for debugging C++ code and
4749 requirements for installation. Typically, the interaction between Qt Creator
4750 and the native debugger is set up automatically and you do not need to do anything.
4752 \o \l{Debugger Modes of Operation} describes the operating modes in which the
4753 debugger plugin runs, depending on where and how the process is started and run.
4755 \o \l{Using Debugging Helpers} describes how to get more detailed data
4763 \contentspage index.html
4764 \previouspage creator-debugger-engines.html
4765 \page creator-debugger-operating-modes.html
4766 \nextpage creator-debugging-helpers.html
4768 \title Debugger Modes of Operation
4770 The debugger plugin runs in different operating modes depending on where and
4771 how the process is started and run. Some of the modes are only available for
4772 a particular operating system or platform.
4774 You can launch the debugger in the following modes:
4778 \o \bold Plain to debug locally started applications, such as a
4779 Qt based GUI application.
4781 \o \bold Terminal to debug locally started processes that need a
4782 console, typically without a GUI.
4784 \o \bold Attach to debug local processes started outside Qt Creator.
4786 \o \bold Remote to debug a process running on a different machine.
4788 \o \bold Core to debug crashed processes on Unix.
4790 \o \bold Post-mortem to debug crashed processes on Windows.
4792 \o \bold TRK to debug processes running on a Symbian device.
4796 When you click the \gui {Start Debugging} button, the debugger is launched
4797 in the appropriate operating mode (plain, terminal, or TRK), based on the
4798 build and run settings for the active project. Select \gui Debug menu options
4799 to launch the debugger in the other modes.
4801 \section2 Plain Mode
4803 To launch the debugger in the plain mode, click the \gui {Start Debugging}
4804 button for the active project, or choose
4805 \gui {Debug > Start Debugging > Start and Debug External Application...}
4806 and specify an executable.
4808 \section2 Terminal Mode
4810 To launch the debugger in the terminal mode, select \gui {Projects > Run Settings}
4811 and select the \gui {Run in terminal} check box. Then click the
4812 \gui {Start Debugging} button for the active project.
4814 \section2 Attach Mode
4816 To launch the debugger in the attach mode, select
4817 \gui {Debug > Start Debugging > Attach to Running External Application...},
4818 and then select a process by its name or process ID to attach to.
4820 \section2 Remote Mode
4822 The remote mode uses a \e{gdbserver} daemon that runs on the remote machine.
4824 To launch the debugger in the remote mode, select
4825 \gui {Debug > Start Debugging > Start and Attach to Remote Application...}.
4829 The core mode is available only in Unix. It debugs crashed processes using
4830 the \e {core} files (crash dumps) that are generated if the setting
4831 is enabled in the shell.
4833 To enable the dumping of core files, enter the following command in the
4834 shell from which the application will be launched:
4840 To launch the debugger in the core mode, select
4841 \gui{Debug > Start Debugging > Attach to Core...}.
4843 \section2 Post-Mortem Mode
4845 The post-mortem mode is available only on Windows, if you have installed
4846 the debugging tools for Windows.
4848 The Qt Creator installation program asks you whether you want to
4849 register Qt Creator as a post-mortem debugger. To change the setting, select
4850 \gui{Tools > Options... > Debugger > Common > Use Creator for post-mortem debugging}.
4852 You can launch the debugger in the post-mortem mode if an application crashes
4853 on Windows. Click the \gui {Debug in Qt Creator} button in the error message
4854 that is displayed by the Windows operating system.
4858 The TRK mode is a special mode available only for Symbian. It
4859 debugs processes running on a Symbian
4860 device using the App TRK application that runs on the device.
4862 To launch the debugger in the TRK mode, open the project, select Symbian as the
4863 target, and click the \gui {Start Debugging} button.
4865 For more information on setting up Symbian projects, see
4866 \l{Setting Up Development Environment for Symbian}.
4872 \contentspage index.html
4873 \previouspage creator-debug-mode.html
4874 \page creator-debugger-engines.html
4875 \nextpage creator-debugger-operating-modes.html
4877 \title Setting Up Debugger
4879 Typically, the interaction between Qt Creator and the native debugger is set
4880 up automatically and you do not need to do anything. However, you might have an
4881 unsupported gdb version installed, your Linux environment might not have gdb
4882 installed at all, or you might want to use the debugging tools for Windows.
4884 \note To use the debugging tools for Windows, you must install them and add the
4885 Symbol Server provided by Microsoft to the symbol search path of the debugger.
4886 For more information, see \l{Setting the Symbol Server in Windows}.
4888 This section explains the
4889 options you have for debugging C++ code and provides installation notes for the
4890 supported native debuggers.
4892 \section1 Supported Native Debugger Versions
4894 The debugger plugin supports different builds of the gdb debugger, both
4895 with and without the ability to use Python scripting. The Python enabled
4896 versions are preferred, but they are not available on Mac and on older
4898 On Windows, Symbian, and Maemo, only the Python version is supported.
4900 The non-Python versions use the compiled version of the debugging helpers,
4901 that you must enable separately. For more information, see
4902 \l{Debugging Helpers Based on C++}.
4904 The Python version uses a script version of the debugging helpers
4905 that does not need any special setup.
4907 The CDB native debugger has similar funtionality to the non-Python gdb debugger
4908 engine. Specifically, it also uses compiled C++ code for the debugging
4911 The following table summarizes the support for debugging C++ code:
4925 \o Plain, Terminal, Attach, Remote, Core
4931 \o Plain, Terminal, Attach, Remote, Core
4937 \o Plain, Terminal, Attach, Core
4943 \o Plain, Terminal, Attach, Remote, Core
4946 \o Microsoft Visual C++ Compiler
4947 \o Debugging Tools for Windows/CDB
4949 \o Plain, Terminal, Attach, Post-Mortem
4964 For more information on the the debugger modes, see \l{Debugger Modes of Operation}.
4968 \section2 Gdb Adapter Modes
4972 The gdb native debugger used internally by the debugger plugin runs in
4973 different adapter modes to cope with the variety
4974 of supported platforms and environments. All gdb adapters inherit from
4979 \o PlainGdbAdapter debugs locally started GUI processes.
4980 It is physically split into parts that are relevant only when Python is
4981 available, parts relevant only when Python is not available, and mixed code.
4983 \o TermGdbAdapter debugs locally started processes that need a
4986 \o AttachGdbAdapter debugs local processes started outside Qt Creator.
4988 \o CoreGdbAdapter debugs core files generated from crashes.
4990 \o RemoteGdbAdapter interacts with the gdbserver running on Linux.
4992 \o TrkGdbAdapter interacts with Symbian devices. The gdb protocol and
4993 the gdb serial protocol are used between gdb and the adapter. The TRK
4994 protocol is used between the adapter and AppTRK running on the device.
5000 \section1 Installing Native Debuggers
5002 There are various reasons why the debugger plugin may fail to automatically
5003 pick up a suitable native debugger. The native debugger might be missing
5004 (which is usually the case for the CDB debugger on Windows which always
5005 needs to be installed manually by the user) or the installed version is not
5007 Check the table below for the supported versions and other important
5008 information about installing native debuggers.
5016 \o On Linux, install version 6.8, 7.0.1 (version 7.0 is not supported),
5017 7.1, or later. On Mac OS X, install Apple gdb version 6.3.50-20050815
5018 (build 1344) or later.
5021 \o Debugging tools for Windows
5022 \o Using this engine requires you to install the
5023 \e{Debugging tools for Windows}
5024 \l{http://www.microsoft.com/whdc/devtools/debugging/installx86.Mspx}{32-bit}
5026 \l{http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx}{64-bit}
5027 package (Version 6.11.1.404 for the 32-bit or the 64-bit version of Qt Creator, respectively),
5028 which is freely available for download from the
5029 \l{http://msdn.microsoft.com/en-us/default.aspx}
5030 {Microsoft Developer Network}.
5032 \note Visual Studio does not include the Debugging tools needed,
5033 and therefore, you must install them separately.
5035 The pre-built \e{Qt SDK for Windows} makes use
5036 of the library if it is present on the system. When manually building Qt
5037 Creator using the Microsoft Visual C++ Compiler, the build process checks
5038 for the required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}.
5040 It is highly recommended that you add the Symbol Server provided by Microsoft to the symbol
5041 search path of the debugger. The Symbol Server provides you
5042 with debugging informaton for the operating system libraries for debugging
5043 Windows applications. For more information, see
5044 \l{Setting the Symbol Server in Windows}.
5047 \o Debugging tools for Mac OS X
5048 \o The Qt binary distribution contains both debug and release
5049 variants of the libraries. But you have to explicitly tell the
5050 runtime linker that you want to use the debug libraries even if
5051 your application is compiled as debug as release is the default
5054 If you use a qmake based project in Qt Creator, you can set a
5055 flag in your run configuration, in \gui Projects mode. In the run
5056 configuration, select \gui{Use debug version of frameworks}.
5058 For more detailed information about debugging on the Mac, see:
5059 \l http://developer.apple.com/mac/library/technotes/tn2004/tn2124.html
5061 \note The Mac OS X Snow Leopard (10.6) has a bug, that can be worked
5062 around as described in the link provided below:
5063 \l http://bugreports.qt.nokia.com/browse/QTBUG-4962.
5067 \section1 Setting the Symbol Server in Windows
5069 To obtain debugging information for the operating system libraries for
5070 debugging Windows applications, add the Symbol Server provided
5071 by Microsoft to the symbol search path of the debugger:
5073 \o Select \gui Tools > \gui{Options...} > \gui Debugger > \gui Cdb.
5074 \o In the \gui {Symbol paths} field, open the \gui{Insert...} menu
5075 and select \gui{Symbol Server...}.
5076 \o Select a directory where you want to store the cached information
5079 Use a subfolder in a temporary directory, such as
5080 \c {C:\temp\symbolcache}.
5083 \note Populating the cache might take a long time on a slow network
5086 \note The first time you start debugging by using the
5087 Debugging tools for Windows, Qt Creator prompts you to add the Symbol
5093 \contentspage index.html
5094 \previouspage creator-debugging-example.html
5095 \page creator-debug-mode.html
5096 \nextpage creator-debugger-engines.html
5098 \title Interacting with the Debugger
5100 In \gui Debug mode, you can use several views to interact with the
5101 program you are debugging. Frequently used views are shown by
5102 default and rarely used ones are hidden. To change the default settings,
5103 select \gui {Window > Views}, and then select views to display or hide.
5105 \image qtcreator-debugger-views.png "Debug mode views"
5107 By default, the views are locked into place in the workspace. Select
5108 \gui {Window > Views > Locked} to unlock the views. Drag and drop the
5109 views into new positions on the screen. Drag view borders to resize the
5110 views. The size and position of views are saved for future sessions.
5112 \section1 Starting the Debugger
5114 To start a program under the debugger's control, select \gui{Debug} >
5115 \gui{Start Debugging} > \gui{Start Debugging}, or press \key{F5}.
5116 Qt Creator checks whether the compiled program is up-to-date, rebuilding
5117 it if necessary. The debugger then takes over and starts the program.
5119 \note Starting a program in the debugger can take a considerable amount of
5120 time, typically in the range of several seconds to minutes if complex
5121 features (like QtWebKit) are used.
5123 The debugger is launched in the appropriate operating mode (plain, terminal,
5124 or TRK), based on the build and run settings for the active project.
5125 Select \gui Debug menu options to launch the debugger in other modes.
5126 For more information, see \l{Debugger Modes of Operation}.
5128 Once the program starts running, it behaves and performs as usual.
5129 You can interrupt a running program by selecting \gui{Debug} >
5130 \gui {Interrupt}. The program is automatically interrupted as soon as a
5133 \section2 Starting the Debugger from the Command Line
5135 You can use the Qt Creator debugger interface from the command line. To
5136 attach it to a running process, specify the process ID as a parameter for
5137 the \c {-debug} option. To examine a core file, specify the file name.
5138 Qt Creator executes all the necessary steps, such as searching for
5139 the binary that belongs to a core file.
5145 \o \c {C:\qtcreator-2.1\bin>qtcreator -debug 2000}
5147 \o \c {C:\qtcreator-2.1\bin>qtcreator -debug core.2000}
5151 For more information, see \l{Using Command Line Options}.
5153 \section1 Using the Debugger
5155 Once the program stops, Qt Creator:
5158 \o Retrieves data representing the call stack at the program's current
5160 \o Retrieves the contents of local variables.
5161 \o Examines \gui Watchers.
5162 \o Updates the \gui Registers, \gui Modules, and \gui Disassembler
5167 You can use the \gui Debug mode views to examine the data in more detail.
5169 You can use the following keyboard shortcuts:
5173 \o To finish debugging, press \key{Shift+F5}.
5174 \o To execute a line of code as a whole, press \key{F10}.
5175 \o To step into a function or a sub-function, press \key{F11}.
5176 \o To continue running the program, press \key{F5}.
5180 It is also possible to continue executing the program until the current
5181 function completes or jump to an arbitrary position in the current function.
5183 \section2 Stepping into Frameworks in Mac OS
5185 In Mac OS X, external libraries are usually built into so-called Frameworks,
5186 which may contain both release and debug versions of the library. When you run
5187 applications on the Mac OS desktop, the release version of Frameworks is used
5188 by default. To step into Frameworks, select the \gui {Use debug versions of
5189 Frameworks} option in the project run settings for \gui Desktop and
5190 \gui {Qt Simulator} targets.
5192 \section1 Setting Breakpoints
5194 A breakpoint represents a position or sets of positions in the code that,
5195 when executed, interrupts the program being debugged and passes the control
5196 to you. You can then examine the state of the interrupted program, or
5197 continue execution either line-by-line or continuously.
5199 Qt Creator shows breakpoints in the \gui{Breakpoints} view which is enabled
5200 by default. The \gui{Breakpoints} view is also accessible when the debugger
5201 and the program being debugged is not running.
5203 \image qtcreator-debug-breakpoints.png "Breakpoints view"
5205 Typically, breakpoints are associated with a source code file and line, or
5206 the start of a function -- both are allowed in Qt Creator.
5208 The interruption of a program by a breakpoint can be restricted with
5211 To set a breakpoint:
5214 \o At a particular line you want the program to stop, click the
5215 left margin or press \key F9 (\key F8 for Mac OS X).
5216 \o At a function that you want the program to interrupt, enter the
5217 function's name in \gui{Set Breakpoint at Function...} located in the
5218 context menu of the \gui{Breakpoints} view.
5221 \note You can remove a breakpoint:
5223 \o By clicking the breakpoint marker in the text editor.
5224 \o By selecting the breakpoint in the breakpoint view and pressing
5226 \o By selecting \gui{Delete Breakpoint} from the context
5227 menu in the \gui Breakpoints view.
5230 You can set and delete breakpoints before the program starts running or
5231 while it is running under the debugger's control. Breakpoints are saved
5232 together with a session.
5235 \section1 Viewing Call Stack Trace
5237 When the program being debugged is interrupted, Qt Creator displays the
5238 nested function calls leading to the current position as a call stack
5239 trace. This stack trace is built up from call stack frames, each
5240 representing a particular function. For each function, Qt Creator tries
5241 to retrieve the file name and line number of the corresponding source
5242 file. This data is shown in the \gui Stack view.
5244 \image qtcreator-debug-stack.png
5246 Since the call stack leading to the current position may originate or go
5247 through code for which no debug information is available, not all stack
5248 frames have corresponding source locations. Stack frames without
5249 corresponding source locations are grayed out in the \gui{Stack} view.
5251 If you click a frame with a known source location, the text editor
5252 jumps to the corresponding location and updates the \gui{Locals and Watchers}
5253 view, making it seem like the program was interrupted before entering the
5257 \section1 Viewing Threads
5259 If a multi-threaded program is interrupted, the \gui Thread view or the
5260 combobox named \gui Thread in the debugger's status bar can be used to
5261 switch from one thread to another. The \gui Stack view adjusts itself
5265 \section1 Viewing Modules and Source Files
5267 The \gui{Modules} view and \gui{Source Files} views display information
5268 that the debugger plugin has about modules and source files included in
5269 the project. The \gui{Modules} view lists the modules in the project and
5270 symbols within the modules. In addition, it indicates where the module
5273 The \gui{Source Files} view lists all the source files included in the project.
5274 If you cannot step into an instruction, you can check whether the source file is
5275 actually part of the project, or whether it was compiled
5276 elsewhere. The view shows the path to each file in the file system.
5278 By default, the \gui{Modules} view and \gui{Source Files} view are hidden.
5281 \section1 Viewing Disassembled Code and Register State
5283 The \gui{Disassembler} view displays disassembled code for the current
5284 function. The \gui{Registers} view displays the current state of the CPU's
5287 The \gui{Disassembler} view and the \gui{Registers} view are both useful
5288 for low-level commands for checking single instructions, such as \gui{Step Into}
5289 and \gui{Step Over}. By default, both \gui{Disassembler} and
5290 \gui{Registers} view are hidden.
5292 \section1 Locals and Watchers
5294 Whenever a program stops under the control of the debugger, it retrieves
5295 information about the topmost stack frame and displays it in the
5296 \gui{Locals and Watchers} view. The \gui{Locals and Watchers} view
5297 typically includes information about parameters of the function in that
5298 frame as well as the local variables.
5300 \image qtcreator-watcher.png "Locals and Watchers view"
5302 Compound variables of struct or class type are displayed as
5303 expandable in the view. Expand entries to show
5304 all members. Together with the display of value and type, you can
5305 examine and traverse the low-level layout of object data.
5313 \i Gdb, and therefore Qt Creator's debugger works for optimized
5314 builds on Linux and Mac OS X. Optimization can lead to
5315 re-ordering of instructions or removal of some local variables,
5316 causing the \gui{Locals and Watchers} view to show unexpected
5319 \i The debug information provided by gcc does not include enough
5320 information about the time when a variable is initialized.
5321 Therefore, Qt Creator can not tell whether the contents of a
5322 local variable contains "real data", or "initial noise". If a
5323 QObject appears uninitialized, its value is reported as
5324 \gui {not in scope}. Not all uninitialized objects, however, can be
5329 The \gui{Locals and Watchers} view also provides access to the most
5330 powerful feature of the debugger: comprehensive display of data belonging
5331 to Qt's basic objects.
5333 To enable Qt's basic objects data display feature:
5335 \o Select \gui Tools > \gui {Options...} > \gui Debugger >
5336 \gui{Debugging Helper} and check the \gui{Use Debugging Helper}
5338 \o The \gui{Locals and Watchers} view is reorganized to provide a
5339 high-level view of the objects.
5342 For example, in case of QObject, instead of displaying a pointer to some
5343 private data structure, you see a list of children, signals and slots.
5345 Similarly, instead of displaying many pointers and integers, Qt Creator's
5346 debugger displays the contents of a QHash or QMap in an orderly manner.
5347 Also, the debugger displays access data for QFileInfo and provides
5348 access to the "real" contents of QVariant.
5350 You can use the \gui{Locals and Watchers} view to change the contents of
5351 variables of simple data types, for example, \c int or \c float when the
5352 program is interrupted. To do so, click the \gui Value column, modify
5353 the value with the inplace editor, and press \key Enter (or \key Return).
5355 You can enable tooltips in the main editor displaying this information.
5356 For more information, see \l{Showing Tooltips in Debug Mode}.
5358 \note The set of watched items is saved in your session.
5364 \contentspage index.html
5365 \previouspage creator-debugging.html
5366 \page creator-debugging-example.html
5367 \nextpage creator-debug-mode.html
5369 \title Debugging the Example Application
5371 This section uses the \l{Creating a Qt C++ Application}{TextFinder} example to
5372 illustrate how to debug applications in the \gui Debug mode. TextFinder
5373 reads a text file into
5374 QString and then displays it with QTextEdit.
5375 To look at the example QString, \c{line}, and see the
5376 stored data, place a breakpoint and view the QString object
5380 \o Click in between the line number and the window border on the line
5381 where we invoke \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}
5382 to set a breakpoint.
5384 \image qtcreator-setting-breakpoint1.png
5386 \o Select \gui{Debug > Start Debugging > Start Debugging} or press \key{F5}.
5389 \o To view the breakpoint, click the \gui{Breakpoints} tab.
5391 \image qtcreator-setting-breakpoint2.png
5393 \o To remove a breakpoint, right-click it and select \gui{Delete Breakpoint}.
5396 \o To view the contents of \c{line}, go to the \gui{Locals and
5399 \image qtcreator-watcher.png
5403 Modify the \c{on_findButton_clicked()} function to move back to
5404 the start of the document and continue searching once the cursor hits the
5405 end of the document. Add the following code snippet:
5408 void TextFinder::on_findButton_clicked()
5410 QString searchString = ui->lineEdit->text();
5412 QTextDocument *document = ui->textEdit->document();
5413 QTextCursor cursor = ui->textEdit->textCursor();
5414 cursor = document->find(searchString, cursor,
5415 QTextDocument::FindWholeWords);
5416 ui->textEdit->setTextCursor(cursor);
5418 bool found = cursor.isNull();
5420 if (!found && previouslyFound) {
5421 int ret = QMessageBox::question(this, tr("End of Document"),
5422 tr("I have reached the end of the document. Would you like "
5423 "me to start searching from the beginning of the document?"),
5424 QMessageBox::Yes | QMessageBox::No, QMessageBox::Yes);
5426 if (ret == QMessageBox::Yes) {
5427 cursor = document->find(searchString,
5428 QTextDocument::FindWholeWords);
5429 ui->textEdit->setTextCursor(cursor);
5433 previouslyFound = found;
5437 If you compile and run the above code, however, the application does not
5438 work correctly due to a logic error. To locate this logic error, step
5439 through the code using the following buttons:
5441 \image qtcreator-debugging-buttons.png
5447 \contentspage index.html
5448 \previouspage creator-debugger-operating-modes.html
5449 \page creator-debugging-helpers.html
5450 \nextpage creator-maemo-emulator.html
5452 \title Using Debugging Helpers
5454 Qt Creator is able to show complex data types in a customized,
5455 user-extensible manner. For this purpose, it takes advantage of
5456 two technologies, collectively referred to as \e{Debugging Helpers}.
5458 Using the debugging helpers is not \e essential for debugging
5459 with Qt Creator, but they enhance the user's ability to quickly
5460 examine complex data significantly.
5462 \section1 Debugging Helpers based on C++
5464 This is the first and original approach to display complex data
5465 types. While it has been superseded on most platforms by the more
5466 robust and more flexible second approch using Python scripting,
5467 it is the only feasible one on Windows/MSVC, Mac OS, and
5468 old Linux distributions. Moreover, this approach will automatically
5469 be chosen as fallback in case the Python based approach fails.
5471 During debugging with the C++ based debugging helpers,
5472 Qt Creator dynamically loads a helper library in form of a DLL or a
5473 shared object into the debugged process.
5474 The Qt SDK package already contains a prebuilt debugging helper
5475 library. To create your own debugging helper library, select \gui{Tools} >
5476 \gui{Options...} > \gui{Qt4} > \gui{Qt Versions}. As the internal data
5477 structures of Qt can change between versions, the debugging helper
5478 library is built for each Qt version.
5481 \section1 Debugging Helpers based on Python
5483 On platforms featuring a Python-enabled version of the gdb debugger,
5484 the data extraction is done by a Python script. This is more robust
5485 as the script execution is separated from the debugged process. It
5486 is also easier to extend as the script is less dependent on the
5487 actual Qt version and does not need compilation.
5489 To extend the shipped Python based debugging helpers for custom types,
5490 define one Python function per user defined type in the
5491 gdb startup file. By default, the following startup file is used:
5492 \c{~/.gdbinit}. To use another file, select \gui {Tools > Options... > Gdb}
5493 and specify a filename in the \gui {Gdb startup script} field.
5495 The function name has to be qdump__NS__Foo, where NS::Foo is the class
5496 or class template to be examined. Nested namespaces are possible.
5498 The debugger plugin calls this function whenever you want to
5499 display an object of this type. The function is passed the following
5502 \o \c d of type \c Dumper
5503 \o \c item of type \c Item
5506 The function has to feed the Dumper object with certain information
5507 which is used to build up the object and its children's display in the
5508 \gui{Locals and Watchers} view.
5514 def qdump__QVector(d, item):
5515 d_ptr = item.value["d"]
5516 p_ptr = item.value["p"]
5517 alloc = d_ptr["alloc"]
5518 size = d_ptr["size"]
5520 check(0 <= size and size <= alloc and alloc <= 1000 * 1000 * 1000)
5521 check(d_ptr["ref"]["_q_value"] > 0)
5523 innerType = item.value.type.template_argument(0)
5524 d.putItemCount(size)
5526 if d.isExpanded(item):
5527 p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
5528 with Children(d, [size, 2000], innerType)
5529 for i in d.childRange():
5530 d.putItem(Item(p.dereference(), item.iname, i))
5534 \section2 Item Class
5536 The Item Python class is a thin wrapper around values corresponding to one
5537 line in the \gui{Locals and Watchers} view. The Item members are as follows :
5541 \o \gui{__init__(self, value, parentiname, iname, name = None)} - A
5542 constructor. The object's internal name is created by concatenating
5543 \c parentiname and \c iname. If \c None is passed as \c name, a
5544 serial number is used.
5546 \o \gui{value} - An object of type gdb.Value representing the value to
5549 \o \gui{iname} - The internal name of the object, constituting a dot-separated
5550 list of identifiers, corresponding to the position of the object's
5551 representation in the view.
5553 \o \gui{name} - An optional name. If given, is used in the
5554 \gui{name} column of the view. If not, a simple number in brackets
5560 \section2 Dumper Class
5562 For each line in the \gui{Locals and Watchers} view, a string like the
5563 following needs to be created and channeled to the debugger plugin.
5565 "{iname='some internal name',
5566 addr='object address in memory',
5567 name='contents of the name column',
5568 value='contents of the value column',
5569 type='contents of the type column',
5570 numchild='number of children', // zero/nonzero is sufficient
5571 childtype='default type of children', // optional
5572 childnumchild='default number of grandchildren', // optional
5573 children=[ // only needed if item is expanded in view
5574 {iname='internal name of first child',
5576 {iname='internal name of second child',
5582 While in theory, you can build up the entire string above manually, it is
5583 easier to employ the Dumper Python class for that purpose. The Dumper
5584 Python class contains a complete framework to take care of the \c iname and
5585 \c addr fields, to handle children of simple types, references, pointers,
5586 enums, known and unknown structs as well as some convenience methods to
5587 handle common situations.
5589 The Dumper members are the following:
5593 \o \gui{__init__(self)} - Initializes the output to an empty string and
5594 empties the child stack.
5596 \o \gui{put(self, value)} - Low level method to directly append to the
5599 \o \gui{putCommaIfNeeded(self)} - Appends a comma if the current output
5600 ends in '}', '"' or ']' .
5602 \o \gui{putField(self, name, value)} - Appends a comma if needed, and a
5605 \o \gui{beginItem(self, name)} - Starts writing a field by writing \c {name='}.
5607 \o \gui{endItem(self)} - Ends writing a field by writing \c {'}.
5609 \o \gui{endChildren(self)} - Ends writing a list of children.
5611 \o \gui{childRange(self)} - Returns the range of children specified in
5612 the current \c Children scope.
5614 \o \gui{putItemCount(self, count)} - Appends a field \c {value='<%d items'}
5617 \o \gui{putEllipsis(self)} - Appends fields
5618 \c {'{name="<incomplete>",value="",type="",numchild="0"}'}. This is
5619 automatically done by \c endChildren if the number of children to
5620 print is smaller than the number of actual children.
5622 \o \gui{putName(self, name)} - Appends a \c {name='...'} field.
5624 \o \gui{putType(self, type)} - Appends a field \c {type='...'} unless the
5625 \a type coincides with the parent's default child type.
5627 \o \gui{putNumChild(self, numchild)} - Appends a field \c {numchild='...'}
5628 unless the \c numchild coincides with the parent's default child numchild
5631 \o \gui{putValue(self, value, encoding = None)} - Append a file \c {value='...'},
5632 optionally followed by a field \c {valueencoding='...'}. The \c value
5633 needs to be convertible to a string entirely consisting of
5634 alphanumerical values. The \c encoding parameter can be used to
5635 specify the encoding in case the real value had to be encoded in some
5636 way to meet the alphanumerical-only requirement.
5637 Currently the following encodings are supported:
5640 \o 0: unencoded 8 bit data, interpreted as Latin1.
5642 \o 1: base64 encoded 8 bit data, used for QByteArray,
5643 double quotes are added.
5645 \o 2: base64 encoded 16 bit data, used for QString,
5646 double quotes are added.
5648 \o 3: base64 encoded 32 bit data,
5649 double quotes are added.
5651 \o 4: base64 encoded 16 bit data, without quotes (see 2)
5653 \o 5: base64 encoded 8 bit data, without quotes (see 1)
5655 \o 6: %02x encoded 8 bit data (as with \c QByteArray::toHex),
5656 double quotes are added.
5658 \o 7: %04x encoded 16 bit data (as with \c QByteArray::toHex),
5659 double quotes are added.
5662 \o \gui{putStringValue(self, value)} - Encodes a QString and calls
5663 \c putValue with the correct \c encoding setting.
5665 \o \gui{putByteArrayValue(self, value)} - Encodes a QByteArray and calls
5666 \c putValue with the correct \c encoding setting.
5668 \o \gui{isExpanded(self, item)} - Checks whether the item with the
5669 internal name \c item.iname is expanded in the view.
5671 \o \gui{isExpandedIName(self, iname)} - Checks whether the item with the
5672 internal name \c iname is expanded in the view.
5674 \o \gui{putIntItem(self, name, value)} - Equivalent to:
5678 self.putValue(value)
5684 \o \gui{putBoolItem(self, name, value)} - Equivalent to:
5688 self.putValue(value)
5689 self.putType("bool")
5694 \o \gui{pushOutput(self)} - Moves the output string to a safe location
5695 from with it is sent to the debugger plugin even if further operations
5698 \o \gui{putCallItem(self, name, item, func)} -
5699 Uses gdb to call the function \c func on the value specified by
5700 \a {item.value} and output the resulting item. This function is
5701 not available when debugging core dumps and it is not available
5702 on the Symbian platform due to restrictions imposed by AppTRK.
5704 \o \gui{putItemHelper(self, item)} - The "master function", handling
5705 basic types, references, pointers and enums directly, iterates
5706 over base classes and class members of compound types and calls
5707 \c qdump__* functions whenever appropriate.
5709 \o \gui{putItem(self, item)} - Equivalent to:
5712 self.putItemHelper(item)
5714 Exceptions raised by nested function calls are caught and all
5715 output produced by \c putItemHelper is replaced by the output of:
5718 except RuntimeError:
5719 d.put('value="<invalid>",type="<unknown>",numchild="0",')
5725 \section2 Children and SubItem Class
5727 The attempt to create child items might lead to errors if data is
5728 uninitialized or corrupted. To gracefully recover in such situations,
5729 use \c Children and \c SubItem \e{Context Managers} to create the nested items.
5731 The \c Children constructor \gui{__init__(self, dumper, numChild = 1,
5732 childType = None, childNumChild = None)} uses one mandatory argument and three
5733 optional arguments. The mandatory argument refers to the current \c Dumper
5734 object. The optional arguments can be used to specify the number \c numChild
5735 of children, with type \c childType_ and \c childNumChild_ grandchildren each.
5736 If \c numChild_ is a list of two integers, the first one specifies the actual
5737 number of children and the second the maximum number of children to print.
5739 Similarly, using the \c SubItem class helps to protect individual items.
5744 if d.isExpanded(item):
5748 d.putItemHelper(Item(key, item.iname, "key"))
5751 d.putItemHelper(Item(value, item.iname, "value"))
5757 \contentspage index.html
5758 \previouspage creator-project-qmake.html
5759 \page creator-project-cmake.html
5760 \nextpage creator-project-generic.html
5762 \title Setting Up a CMake Project
5764 CMake is an alternative to qmake for automating the generation of makefiles.
5765 It controls the software compilation process by using simple configuration
5766 files, called CMakeLists.txt files. CMake generates native makefiles and
5767 workspaces that you can use in the compiler environment of your choice.
5769 Since Qt Creator 1.1, CMake configuration files are supported.
5770 Qt Creator 1.3 supports the Microsoft Toolchain if the CMake version
5773 \section1 Setting the Path for CMake
5775 You can set the path for the \c CMake executable in \gui{Tools} >
5776 \gui{Options... > Projects > CMake}.
5778 \image qtcreator-cmakeexecutable.png
5780 \note Before you open a \c CMake project it is necessary to modify the
5781 \c{PATH} environment variable to include the bin folders of \c mingw and
5782 Qt Creator in the SDK.
5784 For instance, if you have the Qt Creator SDK installed in your C drive,
5785 use the following command to set the environment variables in
5786 the command line prompt:
5788 set PATH=C:\qtsdk\mingw\bin;C:\qtsdk\qt\bin;
5790 Then start Qt Creator by typing:
5792 C:\qtsdk\bin\qtcreator.exe
5795 \section1 Opening CMake Projects
5797 To open a \c CMake project:
5799 \o Select \gui{File} > \gui{Open File or Project...}.
5800 \o Select the \c{CMakeLists.txt} file from your \c CMake project.
5803 A wizard guides you through the rest of the process.
5805 \note If the \c CMake project does not have an in-place build, Qt Creator
5806 lets you specify the directory in which the project is built
5807 (\l{glossary-shadow-build}{shadow build}).
5809 \image qtcreator-cmake-import-wizard1.png
5811 The screenshot below shows how you can specify command line arguments to
5812 \c CMake for your project.
5814 \image qtcreator-cmake-import-wizard2.png
5816 Normally, there is no need to pass any command line arguments for projects
5817 that are already built, as \c CMake caches that information.
5820 \section1 Building CMake Projects
5822 Qt Creator builds \c CMake projects by running \c make, \c mingw32-make, or
5823 \c nmake depending on your platform. The build errors and warnings are
5824 parsed and displayed in the \gui{Build Issues} output pane.
5826 By default, Qt Creator builds the \bold{all} target. You can specify which
5827 targets to build in \gui{Project} mode, under \gui{Build Settings}.
5829 \image qtcreator-cmake-build-settings.png
5831 Qt Creator supports multiple build configurations. The build
5832 directory can also be modified after the initial import.
5834 \section1 Running CMake Projects
5835 Qt Creator automatically adds \gui{Run Configurations} for all targets
5836 specified in the \c CMake project file.
5838 Known issues for the current version can be found
5839 \l{Known Issues}{here}.
5842 \section1 Adding External Libraries to CMake Projects
5844 Through external libraries Qt Creator can support code completion and
5845 syntax highlighting as if they were part of the current project or the Qt
5848 Qt Creator detects the external libraries using the \c FIND_PACKAGE()
5849 macro. Some libraries come with the CMake installation. You can find those
5850 in the \bold{Modules} directory of your CMake installation.
5852 \note If you provide your own libraries, you also need to provide your own
5853 \c FindFoo.cmake file. For more information, see
5854 \l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}.
5856 Syntax completion and highlighting work once your project successfully
5857 builds and links against the external library.
5862 \contentspage index.html
5863 \previouspage creator-project-cmake.html
5864 \page creator-project-generic.html
5865 \nextpage creator-developing-maemo.html
5867 \title Setting Up a Generic Project
5869 Qt Creator supports generic projects, so you can import existing projects
5870 that do not use qmake or CMake and Qt Creator ignores your build system.
5872 Generic project support allows you to use Qt Creator as a code editor. You
5873 can change the way your project is built by modifying the \c make command
5874 in the \gui{Projects} mode under \gui{Build Settings}.
5876 When you import a project, Qt Creator creates the following files that
5877 allow you to specify which files belong to your project and which include
5878 directories or defines you want to pass to your compile:
5879 \tt{.files}, \tt{.includes}, and \tt{.config}.
5882 \section1 Importing a Generic Project
5884 To import an existing generic project:
5886 \o Select \gui File > \gui{New File or Project...} >
5887 \gui{Other Project} > \gui{Import Existing Project}.
5888 \o In \gui{Import Existing Project}, enter the project name
5889 and select the location of the project file you want to import.
5891 Qt Creator automatically generates the following files in the
5894 \o \l{Specifying Files}{.files}
5895 \o \l{Specifying Include Paths}{.includes}
5896 \o \l{Specifying Defines}{.config}
5901 When the project is successfully imported, Qt Creator creates the project
5902 tree in the sidebar.
5904 After importing a generic project into Qt Creator, open it by selecting the
5908 \section1 Working with Generic Project Files
5910 For a generic project, you have to manually specify which files belong to
5911 your project and which include directories or defines you want to pass to
5915 \section1 Specifying Files
5917 The list of files for a generic project is specified in the \tt{.files}
5918 file. When you first create a generic project, Qt Creator adds any
5919 files it recognizes to your project.
5921 To add or remove files, edit the \tt{.files} file in Qt Creator.
5922 Qt Creator recreates your project tree when you save the \tt{.files} file.
5923 Alternatively, you can add and remove files using the context menu in the
5926 If you frequently need to update the \tt{.files} file, you can do so
5927 efficiently by using a script that updates the file for you. If the file
5928 is modified externally, you have to restart Qt Creator for the changes to
5931 To update the \tt{.files} on the \gui Git repository use the following
5934 git ls-files *.cpp *.h > MyProject.files
5937 \section1 Specifying Include Paths
5939 The include paths are specified in the \tt{.includes} file, one include
5940 path per line. The paths can be either absolute or relative to the
5941 \tt{.includes} file.
5943 \section1 Specifying Defines
5945 The defines are specified in the \tt{.config} file. The \tt{.config} file is
5946 a regular C++ file, prepended to all your source files when they are parsed.
5947 Only use the \tt{.config} file to add lines as in the example below:
5954 \section1 Creating a Run Configuration
5956 Qt Creator cannot automatically determine which executable to run.
5958 In the \gui{Projects} mode under \gui{Run Settings}, define the executable
5961 \o Click \gui Add and select \gui{Custom Executable}.
5962 \o Define the configuration name, the location of the executable, any
5963 additional arguments and the working directory.
5972 \contentspage index.html
5973 \previouspage adding-plugins.html
5974 \page creator-visual-editor.html
5975 \nextpage quick-projects.html
5977 \title Developing Qt Quick Applications
5979 You can either create Qt Quick projects from scratch or import them to
5980 Qt Creator. For example, you can import and run the
5981 \l {http://doc.qt.nokia.com/4.7/qdeclarativeexamples.html} {QML examples and demos}
5982 to learn how to use various aspects of QML.
5984 You can use the code editor (\l{Using the Editor}{Edit mode}) or the visual editor
5985 (\l{Using Qt Quick Designer}{Design mode}) to develop Qt Quick applications.
5986 The following sections describe typical tasks you can do with Qt Creator.
5990 \o \l {Creating Qt Quick Projects}
5991 \o \l {Creating Components}
5992 \o \l {Creating Screens}
5993 \o \l {Animating Screens}
5994 \o \l {Adding User Interaction Methods}
5995 \o \l {Implementing Application Logic}
5999 \note The \QMLD visual editor is provided as an experimental plugin that you must
6000 enable to be able to edit QML files in the \gui Design mode. Enabling the
6001 visual editor can negatively affect the overall stability of Qt Creator.
6003 To enable or disable the \QMLD visual editor, select
6004 \gui {Help > About Plugins... > Qt Quick > QmlDesigner}. You must restart Qt Creator
6005 to enable or disable the visual editor.
6012 \contentspage index.html
6013 \previouspage creator-visual-editor.html
6014 \page quick-projects.html
6015 \nextpage quick-components.html
6017 \title Creating Qt Quick Projects
6019 Select \gui {File > New File or Project > Qt Quick Project > Qt QML Application}.
6021 \image qmldesigner-new-project.png "New File or Project dialog"
6023 Qt Creator creates the following files:
6027 \o .qmlproject project file defines that all QML, JavaScript, and image
6028 files in the project folder belong to the project. Therefore, you do not
6029 need to individually list all the files in the project.
6031 \o .qml file defines an element, such as a component, screen, or the whole
6036 The \c import statement in the beginning of the .qml file specifies the
6037 \l {http://doc.qt.nokia.com/4.7/qdeclarativemodules.html} {Qt modules}
6038 to import. Each Qt module contains a set of default elements.
6039 Specify a version to get the features you want.
6041 To use JavaScript and image files in the application, copy them to the
6044 To import a QML project to Qt Creator, select
6045 \gui {File > New File or Project > Qt Quick Project > Import Existing Qt QML Directory}.
6052 \contentspage index.html
6053 \previouspage quick-projects.html
6054 \page quick-components.html
6055 \nextpage quick-screens.html
6057 \title Creating Components
6059 A QML component provides a way of defining a new type that you can re-use in other QML
6060 files. A component is like a black box; it interacts with the outside world
6061 through properties, signals, and slots, and is generally defined in its own QML file.
6062 You can import components to screens and applications.
6064 You can create the following QML components:
6068 \o \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
6069 uses an image as a border or background.
6070 \o \l{http://doc.qt.nokia.com/4.7/qml-image.html}{Image}
6071 adds a bitmap to the scene. You can stretch and tile images.
6072 \o \l{http://doc.qt.nokia.com/4.7/qml-item.html}{Item}
6073 is the most basic of all visual items in QML. Even though it has no visual appearance,
6074 it defines all the properties that are common across visual items, such as the x and
6075 y position, width and height, anchoring, and key handling.
6076 \o \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
6077 adds a rectangle that is painted with a solid fill color and an optional border.
6078 You can also use the radius property to create rounded rectangles.
6079 \o \l{http://doc.qt.nokia.com/4.7/qml-text.html}{Text}
6080 adds formatted read-only text.
6081 \o \l{http://doc.qt.nokia.com/4.7/qml-textedit.html}{Text Edit}
6082 adds a single line of editable formatted text that can be validated.
6083 \o \l{http://doc.qt.nokia.com/4.7/qml-textinput.html}{Text Input}
6084 adds a single line of editable plain text that can be validated.
6093 \contentspage index.html
6094 \previouspage quick-components.html
6095 \page quick-screens.html
6096 \nextpage quick-animations.html
6098 \title Creating Screens
6100 You can use predefined QML elements and your own components to create screens.
6102 You can create the following types of views to organize items provided by
6103 \l{http://doc.qt.nokia.com/4.7/qdeclarativemodels.html}{data models}:
6107 \o \l{http://doc.qt.nokia.com/4.7/qml-gridview.html}{Grid View}
6108 \o \l{http://doc.qt.nokia.com/4.7/qml-listview.html}{List View}
6109 \o \l{http://doc.qt.nokia.com/4.7/qml-pathview.html}{Path View}
6113 In the code editor, write the code to use the data models.
6115 Use states and transitions
6116 to navigate between screens.
6118 QML states typically describe user interface configurations, such as the UI elements,
6119 their properties and behavior and the available actions. For example, you can use
6120 states to create two screens.
6127 \contentspage index.html
6128 \previouspage quick-screens.html
6129 \page quick-animations.html
6130 \nextpage quick-user-interaction.html
6132 \title Animating Screens
6134 To make movement between states smooth, you can specify transitions.
6135 You can use different types of animated transitions. For example, you can animate changes
6136 to property values and colors. You can use rotation animation to control the direction of
6137 rotation. For more information, see
6138 \l{http://doc.qt.nokia.com/4.7/qdeclarativeanimation.html}{QML Animation}.
6140 You can use the \c ParallelAnimation element to start several animations at the same time.
6141 Or use the \c SequentialAnimation element to run them one after another.
6143 You can use the code editor to specify transitions. For more information, see
6144 \l{http://doc.qt.nokia.com/4.7/qml-transition.html}{QML Transition Element}.
6152 \contentspage index.html
6153 \previouspage quick-animations.html
6154 \page quick-user-interaction.html
6155 \nextpage quick-application-logic.html
6157 \title Adding User Interaction Methods
6159 You can add the following basic interaction methods to scenes:
6163 \o \l{http://doc.qt.nokia.com/4.7/qml-flickable.html}{Flickable}
6164 items can be flicked horizontally or vertically.
6165 \o \l{http://doc.qt.nokia.com/4.7/qml-flipable.html}{Flipable}
6166 items can be flipped between their front and back sides by using rotation,
6167 state, and transition.
6168 \o \l{http://doc.qt.nokia.com/4.7/qml-focusscope.html}{Focus Scope}
6169 assists in keyboard focus handling when building reusable QML components.
6170 \o \l{http://doc.qt.nokia.com/4.7/qml-mousearea.html}{Mouse Area}
6171 enables simple mouse handling.
6180 \contentspage index.html
6181 \previouspage quick-user-interaction.html
6182 \page quick-application-logic.html
6183 \nextpage creator-building-running.html
6185 \title Implementing Application Logic
6187 A user interface is only a part of an application, and not really useful by itself.
6188 You can use Qt or JavaScript to implement the application logic. For more information on
6189 using JavaScript, see
6190 \l {http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html} {Integrating JavaScript}.
6192 For an example of how to use JavaScript to develop a game, see the
6193 \l {http://doc.qt.nokia.com/4.7/qml-advtutorial.html} {QML Advanced Tutorial}.
6199 \contentspage index.html
6200 \previouspage creator-editor-refactoring.html
6201 \page qt-quick-toolbars.html
6202 \nextpage creator-editor-locator.html
6204 \title Using Qt Quick Toolbars
6206 When you edit QML code in the code editor, you specify the properties
6207 of QML components. For some properties, such as colors and font names,
6208 this is not a trivial task. For example, few people can visualize the
6211 To easily edit these properties, you can use the Qt Quick Toolbars.
6212 When you select a component in the code and a toolbar is available,
6213 a light bulb icon appears:
6214 \inlineimage qml-toolbar-indicator.png
6215 . Select the icon to open the toolbar.
6217 To open toolbars immediately when you select a component, select
6218 \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar > Always show Quick
6221 Drag the toolbar to pin it to another location. Select
6222 \inlineimage qml-toolbar-pin.png
6223 to unpin the toolbar and move it to its default location. To pin toolbars
6224 by default, select \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar
6225 > Pin Quick Toolbar}.
6227 \section1 Previewing Images
6229 The Qt Quick Toolbar for images allows you to edit the properties of
6230 \l{http://doc.qt.nokia.com/latest/qml-borderimage.html}{Border Image}
6231 and \l{http://doc.qt.nokia.com/latest/qml-image.html}{Image} components.
6232 You can scale and tile the images, replace them with other images,
6233 preview them, and change the image margins.
6235 \image qml-toolbar-image.png "Qt Quick Toolbar for images"
6237 To preview an image, double-click it on the toolbar. In the preview
6238 dialog, you can zoom the image. Drag the image margins to change them.
6240 \image qml-toolbar-image-preview.png "Image preview dialog"
6242 \section1 Formatting Text
6244 The Qt Quick Toolbar for text allows you to edit the properties of
6245 \l{http://doc.qt.nokia.com/latest/qml-text.html}{Text} components.
6246 You can change the font family and size as well as text formatting, style,
6247 alignment, and color.
6249 If a property is assigned an expression instead of a value, you
6250 cannot use the toolbar to edit it. The button for editing the property
6253 \image qml-toolbar-text.png "Qt Quick Toolbar for text"
6255 By default, font size is specified as pixels. To use points, instead,
6256 change \gui px to \gui pt in the size field.
6258 \section1 Previewing Animation
6260 The Qt Quick Toolbar for animation allows you to edit the properties of
6261 \l{http://doc.qt.nokia.com/4.7/qml-propertyanimation.html}{PropertyAnimation}
6262 components and the components that inherit it. You can change the easing curve
6263 type and duration. For some curves, you can also specify amplitude, period,
6264 and overshoot values.
6266 \image qml-toolbar-animation.png "Qt Quick Toolbar for animation"
6268 Select the play button to preview your changes.
6270 \section1 Editing Rectangles
6272 The Qt Quick Toolbar for rectangles allows you to edit the properties of
6273 \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
6274 components. You can change the fill and border colors and add
6277 \image qml-toolbar-rectangle.png "Qt Quick Toolbar for rectangles"
6279 To add gradient stop points, click above the gradient bar. To remove
6280 stop points, drag them upwards.
6286 \contentspage index.html
6287 \previouspage creator-debugging-helpers.html
6288 \page creator-maemo-emulator.html
6289 \nextpage creator-version-control.html
6291 \title Using the Maemo Emulator
6293 The Maemo emulator emulates the Nokia N900 device environment. You can test
6294 applications in conditions practically identical to running the application
6295 on a Nokia N900 device with software update release 1.2 (V10.2010.19-1).
6296 You can test user interaction by using the keypad and
6299 To test the application UI, user interaction with the application, and
6300 functionality that uses the mobility APIs, use the Qt Simulator,
6301 instead. For more information, see the
6302 \l{http://doc.qt.nokia.com/qt-simulator-beta/index.html}{Qt Simulator Manual}.
6304 The Maemo emulator is installed and configured as part of the Nokia Qt SDK
6305 package. You can also install and configure the MADDE environment and
6306 Maemo emulator separately. For more information, see
6307 \l{Setting Up Development Environment for Maemo}.
6309 \section1 Starting the Maemo Emulator
6311 The \gui {Start Maemo Emulator} button is visible if you have a project
6312 open in Qt Creator for which you have added the Maemo build target
6313 and if you have configured a connection between Qt Creator and the Maemo
6316 To start the Maemo emulator:
6321 \inlineimage qtcreator-maemo-emulator-button.png "Start Maemo Emulator button"
6324 \o Select \gui {Mad Developer} on the Maemo emulator, to start the Mad Developer
6327 \o If you have not deployed an SSH key to protect the connection between
6328 Qt Creator and the Maemo emulator, select \gui {Developer Password} to generate
6331 \o In Qt Creator, enter the password in the connection settings:
6332 \gui {Tools > Options... > Projects > Maemo Device Configurations}.
6336 Test your application on the Maemo emulator as on a device. For a list of
6337 keyboard shortcuts that you can use to emulate Nokia N900 keys and functions, see
6338 \l {Emulating Nokia N900 Keys}.
6340 \section1 Emulating Nokia N900 Keys
6342 The following table summarizes the keyboard shortcuts that you can use
6343 to emulate Nokia N900 keys and functions.
6348 \o Keyboard Shortcut
6359 \o Respective keys on the development PC keyboard.
6373 \o Keypad slider open and close
6379 \o Camera lens open and close
6385 \o Camera take picture
6387 \note The actual camera functionality is not emulated.
6389 \o Stereo headphones connect and disconnect
6398 \o Accelerometer x axis, negative
6401 \o Accelerometer x axis, positive
6404 \o Accelerometer z axis, negative
6407 \o Accelerometer z axis, positive
6410 \o Accelerometer y axis, negative
6413 \o Accelerometer y axis, positive
6423 \contentspage index.html
6424 \previouspage creator-usability.html
6425 \page adding-plugins.html
6426 \nextpage creator-visual-editor.html
6428 \title Adding Qt Designer Plugins
6430 You can use Qt APIs to create plugins that extend Qt applications.
6431 This allows you to add your own widgets to \QD.
6432 The most flexible way to include a plugin with an application is to compile it
6433 into a dynamic library that is shipped separately, and detected and loaded at runtime.
6435 The applications can detect plugins that are stored in the standard plugin
6436 subdirectories. For more information on how to create and locate plugins and to
6437 change the default plugin path, see \l{How to Create Qt Plugins}.
6439 For more information about how to create plugins for \QD, see
6440 \l{http://doc.qt.nokia.com/4.7/designer-using-custom-widgets.html}{Creating and Using Components for Qt Designer}.
6442 \section1 Locating Qt Designer Plugins
6444 \QD fetches plugins from the standard locations and loads the plugins
6445 that match its build key. \QD is delivered both as a standalone application
6446 and as part of the SDK, where it is integrated into Qt Creator.
6447 The correct folder to place the plugins depends on
6450 The integrated \QD fetches plugins from the \c {%SDK%\bin\designer} folder on Windows
6451 and Linux. For information about how to configure plugins on Mac OS, see
6452 \l{Configuring Qt Designer Plugins on Mac OS}.
6454 To check which plugins
6455 were loaded successfully and which failed, choose \gui{Tools > Form Editor >
6456 About Qt Designer Plugins}.
6458 The standalone \QD is part of the Qt library used for building projects,
6459 located under \c {%SDK%\qt}. Therefore, it fetches plugins from the following folder:
6460 \c {%SDK%\qt\plugins\designer}. To check which plugins were loaded successfully and which
6461 failed, choose \gui{Help > About Plugins}.
6463 \section2 Configuring Qt Designer Plugins on Mac OS
6465 On the Mac, a GUI application must be built and run from a bundle. A bundle is a
6466 directory structure that appears as a single entity when viewed in the Finder.
6467 A bundle for an application typcially contains the executable and all the resources
6470 Qt Creator uses its own set of Qt Libraries located in the bundle, and therefore,
6471 you need to configure the \QD plugins that you want to use with Qt Creator.
6472 Fore more information about how to deploy applications on Mac OS, see
6473 \l{http://doc.qt.nokia.com/4.7/deployment-mac.html}{Deploying an Application on Mac OS X}.
6475 The following example illustrates how to configure version 5.2.1 of the
6476 \l{http://qwt.sourceforge.net/}{Qwt - Qt Widgets for Technical Applications} library
6477 for use with Qt Creator:
6481 \o To check the paths used in the Qwt library, enter the following \c otool command:
6483 \snippet examples/doc_src_plugins.qdoc 0
6485 The output for Qwt 5.2.1 indicates that the plugin uses Qt core libraries (QtDesigner,
6486 QtScript, QtXml, QtGui and QtCore) and libqwt.5.dylib:
6488 \snippet examples/doc_src_plugins.qdoc 1
6491 \o You must copy the \QD plugin and the Qwt library files to the following locations:
6494 \o \c {libqwt_designer_plugin.dylib} to \c {QtCreator.app/Contents/MacOS/designer}
6495 \o \c {libqwt.*.dylib} to \c {QtCreator.app/Contents/Frameworks}
6498 Enter the following commands:
6500 \snippet examples/doc_src_plugins.qdoc 4
6502 \o Enter the following \c otool command to check the libraries that are used by the
6505 \snippet examples/doc_src_plugins.qdoc 2
6507 The command returns the following output:
6509 \snippet examples/doc_src_plugins.qdoc 3
6511 \o Enter the following \c install_name_tool command to fix the references of the
6514 \snippet examples/doc_src_plugins.qdoc 5
6519 \section1 Matching Build Keys
6521 The Qt Creator that is included in pre-built SDK packages on Windows is built with the
6522 Microsoft Visual Studio compiler, whereas the version of Qt shipped for building applications
6523 is configured and built to use the MinGW/g++ compiler. Plugins built by using this version of
6524 Qt cannot be loaded by Qt Creator because the build-keys do not match. The plugins can only be
6525 used in the standalone version of \QD. Choose \gui{Help > About Qt Creator} to check
6526 the Qt version Qt Creator was built with.
6528 To use \QD plugins that were built for the shipped Qt version, make sure that
6529 Qt Creator is built with the same compiler by either recompiling Qt Creator using MinGW or
6530 recompiling Qt with Microsoft Visual Studio, depending on which configuration you want to
6531 use for your applications.
6537 \contentspage index.html
6538 \previouspage creator-design-mode.html
6539 \page creator-usability.html
6540 \nextpage adding-plugins.html
6542 \title Optimizing Applications for Mobile Devices
6544 Before starting application development, analyze and define the requirements, scope, and
6545 functionality of the application to ensure efficient functionality and a smooth user
6546 experience. Design the application for a single purpose and analyze how it can best serve
6547 its users. Mobile devices have been designed for use when mobile. Keep the characteristics
6548 of mobile devices in mind when you create applications for them.
6550 The following guidelines help you design and develop usable applications for mobile devices
6551 with varying characteristics, such as screen size and support for input methods:
6557 Find out who will use the application, what they will use it for,
6558 and which mobile devices they have. Then design the application to fit a specific context
6561 \o Design for small screens
6563 The screen size of mobile devices is significantly smaller
6564 than that available on desktop devices. Carefully consider what is the most relevant
6565 content to present on the application UI, as it might not be reasonable to try and fit as
6566 much content into the screen as you might have in a desktop application.
6568 \o Design for multiple screen sizes
6570 Relate the position and size of each control to the
6571 dimensions of the display. This enables the same set of information to be presented on the
6572 screen in all resolutions; higher resolution devices just display finer graphics.
6574 \o Design for changing screen orientation
6576 Some devices support screen rotation. On these
6577 devices, applications can be displayed in portrait or landscape orientation. Account for
6578 orientation and dynamically adjust the display when the screen is rotated.
6580 \o Design intuitive ways of moving within applications
6582 Mobile devices lack a mouse and
6583 full-size keyboard, so users must use the touch screen or five way navigation pad to move within
6584 applications. In addition, many users control the devices with one hand. To create an optimized user
6585 experience, allow users to access information with one click; do not make them scroll and type.
6587 \o Design for limited input methods
6589 Applications collect information from users on the task
6590 at hand. In addition to touch screen input, some devices contain physical keys such
6591 as a five way navigation pad, a keypad, and a keyboard. Users enter information by using screen
6592 controls, such as lists, check boxes, radio buttons, and text fields.
6594 \o Keep response times short
6596 Latency can cause delays in user interaction. If users perceive
6597 an application as being slow, they are likely to get frustrated and stop using it.
6599 \o Save battery time
6601 Mobile devices are not constantly connected to a power source but run on
6602 battery power. Optimize power consumption to keep the total consumption at an acceptable
6603 level and to prevent users from running out of battery time.
6605 For more information and code examples on how to minimize power consumption, see
6606 \l{http://developer.symbian.org/wiki/index.php/Creating_Energy_Efficient_Apps_Using_Qt}{Creating Energy Efficient Apps Using Qt}.
6608 \o Consider network issues
6610 If users do not have a flat-rate data plan or WLAN support, mobile
6611 network connections cost them money. Also, when users move around with the devices, the networks
6612 available for connections constantly change.
6614 \o Remember the processing limits of the device
6616 The memory available on devices is limited
6617 and you should use it carefully. Although all mobile devices have common functionality,
6618 each device is individual in terms of both the resources available and extra features.
6619 Therefore, you must consider the constraints of all the target devices.
6623 For more information about user experience techniques for mobile devices, see the
6624 \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}
6631 \contentspage index.html
6632 \previouspage creator-help.html
6633 \page creator-tips.html
6634 \nextpage creator-keyboard-shortcuts.html
6636 \title Tips and Tricks
6639 \section1 Switching Between Modes
6641 Qt Creator uses different modes for different purposes. You can quickly
6642 switch between these modes with the following keyboard shortcuts:
6644 \o \gui Welcome mode \key Ctrl+1
6645 \o \gui Edit mode \key Ctrl+2
6646 \o \gui Design mode \key Ctrl+3
6647 \o \gui Debug mode \key Ctrl+4
6648 \o \gui Projects mode \key Ctrl+5
6649 \o \gui Help mode \key Ctrl+6
6653 For more information about Qt Creator modes, see \l {Qt Creator Modes}.
6657 \section1 Moving Between Open Files
6659 To quickly move between currently open files, press
6662 To move forward in the location history, press \key {Alt+Right}
6663 (\key {Cmd+Opt+Right} on Mac OS). To move backward, press \key {Alt+Left}
6664 (\key {Cmd+Opt+Left} on Mac OS). For example, if you use the \gui Locator
6665 to jump to a symbol in the same file, you can jump back to your original
6666 location in that file by pressing \key {Alt+Left}.
6669 \section1 Moving To the Edit Mode
6671 To move to the \gui Edit mode and currently active file, press
6674 If you already are in the \gui Edit mode:
6676 \o The first press moves focus to the editor
6677 \o The second press closes secondary windows
6680 \section1 Using the Filter in Options Dialog
6682 To find specific settings you require in \gui{Tools} > \gui{Options...}
6683 use the filter located at the top left of the \gui Options dialog box.
6685 \section1 Opening Output Panes
6687 The output panes provide a list of errors and warnings encountered during
6688 a build, detailed output from the compiler, status of a program when it is
6689 executed and debug output, as well as search results.
6691 To open output panes, use the following shortcuts:
6695 \o \gui{Build Issues} pane Alt+1 (Cmd+1 on Mac OS X)
6697 \o \gui{Search Results} pane Alt+2 (Cmd+2 on Mac OS X)
6699 \o \gui{Application Output} pane Alt+3 (Cmd+3 on Mac OS X)
6701 \o \gui{Compile Output} pane Alt+4 (Cmd+4 on Mac OS X)
6705 For more information about output panes, see \l{Viewing Output}.
6708 \section1 Using Keyboard Shortcuts
6710 Qt Creator provides \l{Keyboard Shortcuts}{many useful keyboard shortcuts}.
6711 You can see the keyboard shortcut for a menu command in the menu
6712 or the tooltip for a button.
6714 To customize, import or export keyboard shortcuts, select \gui Tools >
6715 \gui Options... > \gui Environment > \gui Keyboard.
6718 \section1 Running Qt Creator From Command Line
6720 You can launch Qt Creator from command line using the name of an
6721 existing session or \c .pro file by giving the name as the command
6724 For example, running \tt{qtcreator somesession}, launches Qt Creator and
6725 loads session somesession.
6727 \note Make sure Qt Creator is included in the PATH environment variable.
6728 This can be done by typing the following in the command line:
6730 set PATH=c:\qtsdk\mingw\bin;c:\qtsdk\qt\bin;%PATH%
6734 \section1 Showing and Hiding the Sidebar
6736 To toggle the sidebar in the \gui Edit and \gui Debug modes, click
6737 \inlineimage qtcreator-togglebutton.png
6738 or press \key Alt+0 (\key Cmd+0 on Mac OS X).
6740 For more information on using the sidebar, see \l {Browsing Project Contents}.
6744 \section1 Moving To Symbols
6746 To move straight to a symbol used in a project, select the symbol in the
6747 \gui Editor toolbar drop-down menu. For more information on the editor toolbar,
6748 see \l {Using the Editor Toolbar}.
6750 To jump to a symbol in the current file, press \key {Ctrl+K} to open the
6751 \gui Locator, enter a period (.), and start typing the symbol name. Then
6752 select the symbol in the list. For more information on using the locator,
6753 see \l{Searching With the Locator}.
6755 Press \key Ctrl (\key Cmd on Mac OS) and click a symbol to move directly to
6756 the definition or the declaration of the symbol. You can also move the cursor
6757 on the symbol and press \key {F2}. For more information, see
6758 \l{Moving to Symbol Definition or Declaration}.
6762 \section1 Displaying Signals and Slots
6764 If an instance of a class is derived from QObject, and you would like to
6765 find all other objects connected to one of your object's slots using
6766 Qt's signals and slots mechanism, select \gui Tools > \gui Options...
6767 > \gui{Debugger} > \gui{Debugging Helper} > \gui{Use Debugging Helper}.
6769 In the \gui{Locals and Watchers} view, expand the object's entry and open
6770 the slot in the \e slots subitem. The objects connected to this slot are
6771 shown as children of the slot. This method works with signals too.
6773 For more information about the \gui{Locals and Watchers} view, see
6774 \l{Locals and Watchers}.
6777 \section1 Displaying Low Level Data
6779 If special debugging of Qt objects fails due to data corruption within the
6780 debugged objects, you can switch off the debugging helpers. When debugging
6781 helpers are switched off low-level structures become visible.
6783 To switch off the debugging helpers:
6785 \o Select \gui Tools > \gui Options... > \gui Debugger >
6786 \gui{Debugging Helper}.
6787 \o Uncheck the \gui{Use Debugging Helper} checkbox.
6790 \section1 Showing Tooltips in Debug Mode
6792 To inspect the value of variables from the editor, you can turn
6793 on tooltips. Tooltips are hidden by default for performance reasons.
6796 \o Select \gui Tools > \gui Options... > \gui Debugger > \gui General.
6797 \o Select the \gui {Use tooltips in main editor while debugging} check box.
6800 \section1 Locating Files
6802 The \gui Locator provides one of the easiest ways in Qt Creator to browse
6803 through projects, files, classes, methods, documentation and file systems.
6804 To quickly access files not directly mentioned in your project, you can
6805 create your own locator filters. That way you can locate files in a
6806 directory structure you have defined.
6808 To create locator filters, select \gui {Tools > Options... > Locator > Add}.
6810 For more information, see \l{Creating Locator Filters}.
6812 \section1 Adding a License Header Template for C++ Code
6814 A file containing a license header for C++ can be specified under
6815 \gui{Tools > Options... > C++ > License Template}. It may contain special
6816 placeholders enclosed in \c{%%} that are replaced when generating a
6822 \o \c %USER%: User name
6823 \o \c %FILENAME%: File name
6824 \o \c %CLASS%: Class name (if applicable)
6825 \o \c %$VARIABLE%: Contents of environment variable \c{VARIABLE}.
6832 \contentspage index.html
6833 \previouspage creator-tips.html
6834 \page creator-keyboard-shortcuts.html
6835 \nextpage creator-known-issues.html
6837 \title Keyboard Shortcuts
6839 Qt Creator provides various keyboard shortcuts to speed up your development
6843 \section1 Configuring Keyboard Shortcuts
6845 To customize a keyboard shortcut:
6847 \o Select \gui Tools > \gui Options... > \gui Environment >
6849 \o Select an action from the list.
6850 \o In \gui{Key Sequence} enter the shortcut key you want to associate
6851 with the selected action.
6854 Qt Creator allows you to use different keyboard shortcut mapping schemes:
6856 \o To import a keyboard shortcut mapping scheme, click \gui Import
6857 and select the kms file containing keyboard shortcut mapping scheme
6859 \o To export the current keyboard shortcut mapping scheme, click
6860 \gui Export and select the location where you want to save the
6865 \section1 Default Keyboard Shortcuts
6867 The following tables list the default keyboard shortcuts. They are
6868 categorized by actions.
6871 \section2 General Keyboard Shortcuts
6876 \o Keyboard shortcut
6878 \o Open file or project
6881 \o New file or project
6884 \o Open in external editor
6920 \o Next open document in history
6926 \o Previous open document in history
6929 \o Activate \gui Locator
6932 \o Switch to \gui Welcome mode
6935 \o Switch to \gui Edit mode
6938 \o Switch to \gui Design mode
6941 \o Switch to \gui Debug mode
6944 \o Switch to \gui Projects mode
6947 \o Switch to \gui Help mode
6950 \o Toggle \gui{Build Issues} pane
6951 \o Alt+1 (Cmd+1 on Mac OS X)
6953 \o Toggle \gui{Search Results} pane
6954 \o Alt+2 (Cmd+2 on Mac OS X)
6956 \o Toggle \gui{Application Output} pane
6957 \o Alt+3 (Cmd+3 on Mac OS X)
6959 \o Toggle \gui{Compile Output} pane
6960 \o Alt+4 (Cmd+4 on Mac OS X)
6962 \o Activate \gui Bookmarks pane
6965 \o Activate \gui{File System} pane
6968 \o Activate \gui{Open Documents} pane
6971 \o Activate \gui Projects pane
6977 \o Toggle the sidebar
6978 \o Alt+0 (Cmd+0 on Mac OS X)
6983 \o Move to \gui Edit mode
6987 \o The first press moves focus to the editor
6988 \o The second press closes secondary windows
6994 \section2 Editing Keyboard Shortcuts
6999 \o Keyboard shortcut
7001 \o Auto-indent selection
7010 \o Trigger a completion in this scope
7025 \o Decrease font size
7026 \o Ctrl+- (Ctrl+Roll mouse wheel down)
7028 \o Increase font size
7029 \o Ctrl++ (Ctrl+Roll mouse wheel up)
7031 \o Toggle Vim-style editing
7037 \o Split side by side
7040 \o Remove all splits
7043 \o Remove current split
7052 \o Go to block start
7055 \o Go to block end with selection
7058 \o Go to block start with selection
7061 \o Move current line down
7064 \o Move current line up
7067 \o Trigger a quick fix in this scope
7073 \o Select the current block
7075 The second press extends the selection to the parent block
7078 \o Enable text wrapping
7081 \o Toggle comment for selection
7084 \o Visualize whitespace
7093 \o Lay out in a grid
7096 \o Lay out horizontally
7099 \o Lay out vertically
7105 \o Edit signals and slots
7114 \o Go to next bookmark
7117 \o Go to previous bookmark
7129 \o Follow symbol under cursor
7131 Works with namespaces, classes, methods, variables, include
7132 statements and macros
7135 \o Rename symbol under cursor
7138 \o Switch between method declaration and definition
7141 \o Open type hierarchy
7144 \o Switch between header and source file
7148 \section2 Debugging Keyboard Shortcuts
7153 \o Keyboard shortcut
7158 \o Stop or interrupt debugger
7173 \o Toggle breakpoint
7178 \section2 Project Keyboard Shortcuts
7183 \o Keyboard shortcut
7199 \section2 Help Keyboard Shortcuts
7204 \o Keyboard shortcut
7206 \o View context-sensitive help
7209 \o Activate contents in \gui Help mode
7212 \o Add bookmark in \gui Help mode
7215 \o Activate index in \gui Help mode
7218 \o Reset font size in \gui Help mode
7221 \o Activate search in \gui Help mode
7226 \section2 Version Control Keyboard Shortcuts
7231 \o {5,1} Version control system
7262 \o Alt+G, Alt+Shift+D
7304 \o Alt+G, Alt+Shift+D
7341 \contentspage index.html
7342 \previouspage creator-known-issues.html
7343 \page creator-glossary.html
7344 \nextpage creator-acknowledgements.html
7356 Qt in PATH
7358 \target glossary-system-qt
7360 version for the \c qmake command found in your \c PATH
7361 environment variable.
7362 This is likely to be the system's Qt version.
7370 \target glossary-project-qt
7371 \o The version of Qt configured in the \gui{Projects} mode, \gui {Build
7372 Settings}, \gui {Qt Version} field. This is the Qt version that
7373 is actually used by a particular project.
7380 \target glossary-shadow-build
7381 \o Shadow building means building a project in a separate
7382 directory, the \e{build directory}. The build directory is
7383 different from the source directory. One of the benefits of
7384 shadow building is that it keeps your source directory clean.
7385 Shadow building is the best practice if you need many build
7386 configurations for a single set of source.
7393 \contentspage index.html
7394 \previouspage creator-keyboard-shortcuts.html
7395 \page creator-known-issues.html
7396 \nextpage creator-glossary.html
7400 This section lists known issues in Qt Creator version 2.1.0.
7401 The development team is aware of them, and therefore, you do not need to
7402 report them as bugs.
7404 For a list of fixed issues and added features, see the changelog file in
7405 the \c{qtcreator\dist} folder or the \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}.
7407 \section1 General Issues
7411 \o Qt Creator uses SQLite for storing some of its settings. SQLite is
7412 known to have problems with certain NFS servers (most notably the
7413 nfs-user-server 2.2beta), since they can lock up the application
7414 when it tries to lock the database. If your home directory is on an
7415 NFS share and you encounter this issue, one option would be to
7416 switch to the nfs-kernel-server, or create a symlink so that the
7417 settings are stored locally.
7421 \section1 Editing Issues
7425 \o Code completion does not support typedefs for nested classes.
7429 \section1 Projects Issues
7432 \o Paths or file names containing spaces or special characters
7433 (such as colons, dollar signs, and hash marks) may cause problems. This
7434 is because some of the tools Qt Creator uses in the background have
7435 restrictions on the characters allowed in file and directory names.
7436 To be on the safe side, we recommend creating projects and project
7437 items with names consisting of plain characters, numbers,
7438 underscores, and hyphens.
7440 \o There is no IDE support for adding or removing sub-projects. Project
7441 hierarchies (SUBDIRS template) have to be created manually.
7443 \o Creating new CMake projects with Qt Creator is not supported.
7445 \o Building and packaging sub-projects is not supported for Maemo devices.
7447 \o You must create projects for Maemo targets on the same partition where
7448 you installed Nokia Qt SDK, Qt Creator, and MADDE.
7450 \o If error messages displayed in the \gui {Compile Output} pane contain
7451 paths where slashes are missing (for example, C:NokiaQtSDK),
7452 check your PATH variable. For more information, see
7453 \l{Troubleshooting MinGW Compilation Errors}.
7457 \section1 Debugging Issues
7461 \o Debugging large applications on Symbian devices using the Symbian S^3
7462 operating system might not work, because the TRK debug agent might not be able to
7463 access memory when the operating system starts paging. This causes breakpoint
7464 handling and symbol resolution to fail. For more information, see
7465 \l{http://bugreports.qt.nokia.com/browse/QTCREATORBUG-2158}{QTCREATORBUG-2158}.
7467 As a workaround, add the following section to the application .pro file to
7473 MMP_RULES *= UNPAGED
7477 \note You must completely clean and rebuild the project for the setting to
7480 \o When debugging executables created by the GNU Compiler version 4.5.0
7481 (all platforms), some data types will not be displayed in the
7482 \gui{Locals and Watchers} view due to missing debug information.
7484 \o Gdb on Windows may not work if the 'Embassy \reg Security Center' software
7485 by 'Wave \reg Systems' is installed and active (causing crashes in \c{vxvault.dll)}).
7487 \o Gdb may take long to load debugging symbols, especially from large
7488 libraries like \c libQtWebKit. Starting the debugging module can
7489 take up to several minutes without visible progress.
7491 \o Setting breakpoints in code that is compiled into the binary more
7492 than once does not work.
7494 \o Setting breakpoints in files that do not have unique absolute
7495 paths may fail. For example, remounting parts of a file system
7496 using the --bind mount option.
7504 \contentspage index.html
7505 \previouspage creator-glossary.html
7506 \page creator-acknowledgements.html
7508 \title Acknowledgements
7510 \section1 Third-party Components
7512 Qt Creator contains the following third-party components:
7515 \o \bold{Open Source front-end for C++ (license MIT)}, enhanced for use in
7517 Roberto Raggi <roberto.raggi@gmail.com>\br
7518 QtCreator/src/shared/cplusplus\br\br
7520 \o \bold{Botan, a C++ crypto library. Version 1.8.8}\br
7522 \o Copyright (C) 1999-2004 The Botan Project. All rights reserved.
7523 \o Copyright (C) 1999-2009 Jack Lloyd
7524 \o 2001 Peter J Jones
7525 \o 2004-2007 Justin Karneges
7526 \o 2005 Matthew Gregan
7527 \o 2005-2006 Matt Johnston
7528 \o 2006 Luca Piccarreta
7529 \o 2007 Yves Jerschow
7530 \o 2007-2008 FlexSecure GmbH
7531 \o 2007-2008 Technische Universitat Darmstadt
7532 \o 2007-2008 Falko Strenzke
7533 \o 2007-2008 Martin Doering
7534 \o 2007 Manuel Hartl
7535 \o 2007 Christoph Ludwig
7536 \o 2007 Patrick Sona
7538 All rights reserved.\br\br
7540 Redistribution and use in source and binary forms, with or without
7541 modification, are permitted provided that the following conditions are
7544 1. Redistributions of source code must retain the above copyright
7545 notice, this list of conditions, and the following disclaimer.\br\br
7547 2. Redistributions in binary form must reproduce the above copyright
7548 notice, this list of conditions, and the following disclaimer in the
7549 documentation and/or other materials provided with the distribution.\br
7552 THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND ANY EXPRESS OR
7553 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
7554 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE,
7555 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE
7556 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
7557 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
7558 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
7559 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
7560 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
7561 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
7562 IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\br\br
7563 The source code of Botan C++ crypto library can be found
7566 \o QtCreator/src/libs/3rdparty
7567 \o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
7571 \o \bold{NetSieben SSH Library is a Secure Shell client library for C++.
7574 \o \bold{Commercial License:} For organizations who do not want to
7575 release the source code for their applications as open source/
7576 free software; in other words they do not want to comply with the
7577 GNU General Public License (GPL) or Q Public License.
7578 \o \bold{Non Commercial / Open Source License:} NetSieben believes in
7579 contributing back to the open source community, thus it has released
7580 the SSH Library under Q Public License as it is defined by Trolltech
7581 AS of Norway. The Open Source License allows the user to use software
7582 under an open source / free software license, and distribute it
7583 freely. The software can be used at no charge with the condition
7584 that if the user uses the SSH Library in an application they wish to
7585 redistribute, then the complete source code for your application must
7586 be available and freely redistributable under reasonable conditions.
7587 For more information on the used QPL License see:
7588 QtCreator/src/libs/3rdparty/net7ssh/LICENSE.QPL
7590 The source code of NetSieben Secure Shell C++ Library can be found
7593 \o QtCreator/src/libs/3rdparty
7594 \o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
7601 \contentspage index.html
7602 \previouspage creator-version-control.html
7603 \page creator-task-lists.html
7604 \nextpage creator-cli.html
7606 \title Creating Task List Files
7608 You can load tasks from task lists to the \gui{Build Issues} pane. You can
7609 either create the task lists manually or create scripts to generate them from
7610 output of static code analysis tools, for example.
7612 For an example of a script that checks new lines of code and matches them
7613 against regular expressions to generate a task list, see \c{scripts\mytasks.pl}
7614 in the Qt Creator repository.
7616 \section1 Task List File Format
7618 The filename extension must be .tasks for Qt Creator to recognize a file as a
7621 Each line in a task list file is treated as a tab-separated list of strings with
7622 \c{\t}, \c{\n}, and \c{\\} used as escape characters. The strings are used to create
7623 one task per line. The lines can have one of the following formats:
7629 \o \c{type\tdescription}
7631 \o \c{file\ttype\tdescription}
7633 \o \c{file\tline\ttype\tdescription}
7637 The task type can have one of the following values:
7641 \o A string starting with \c err, which displays the error icon in the beginning of the line
7642 \o A string starting with \c warn, which displays the warning icon
7643 \o Any other value, which sets the task type to Unknown and does not
7648 The values are not case sensitive.
7650 Lines starting with the hash mark character (#) in the first column are ignored.
7656 \contentspage index.html
7657 \previouspage creator-task-lists.html
7658 \page creator-cli.html
7659 \nextpage creator-help.html
7661 \title Using Command Line Options
7663 You can start Qt Creator and specify some options from the command line.
7665 To specify command line options, enter the following command in the Qt Creator
7666 installation or build directory:
7668 \c {qtcreator [option] [filename]}
7672 \c {C:\qtcreator-2.1\bin>qtcreator -help}
7674 The following table summarizes the available options:
7683 \o Display help on command line options.
7687 \o Display Qt Creator version.
7691 \o Attempt to connect to an already running instance of Qt Creator.
7695 \o Do not load the specified plugin.
7699 \o Load profile plugin.
7703 \o Core plugin: override the selected UI color.
7707 \o Debugger plugin: disable the Microsoft Console Debugger (CDB)
7708 engine. For more information, see \l{Debugging}.
7712 \o Debugger plugin: disable the GNU Symbolic Debugger (gdb) engine.
7716 \o Debugger plugin: disable the Qt Script debugger engine.
7719 \o -debug <PID-or-corefile>
7720 \o Debugger plugin: attach to process ID or core file.
7723 \o -wincrashevent <event-handle>
7724 \o Debugger plugin: Attach to crashed processes by using the specified
7728 \o -customwizard-verbose
7729 \o ProjectExplorer plugin: display additional information when loading
7730 custom wizards. For more information about custom wizards, see
7731 \l{Adding New Custom Wizards}
7735 \o ProjectExplorer plugin: load the last session when Qt Creator starts.
7736 Open the projects and files that were open when you last exited Qt Creator.
7737 For more information about managing sessions, see \l{Managing Sessions}.