1 /****************************************************************************
3 ** This file is part of Qt Creator
5 ** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
7 ** Contact: Nokia Corporation (info@qt.nokia.com)
10 ** GNU Free Documentation License
12 ** Alternatively, this file may be used under the terms of the GNU Free
13 ** Documentation License version 1.3 as published by the Free Software
14 ** Foundation and appearing in the file included in the packaging of this
17 ** If you have questions regarding the use of this file, please contact
18 ** Nokia at info@qt.nokia.com.
20 ****************************************************************************/
22 // **********************************************************************
23 // NOTE: the sections are not ordered by their logical order to avoid
24 // reshuffling the file each time the index order changes (i.e., often).
25 // Run the fixnavi.pl script to adjust the links to the index order.
26 // **********************************************************************
30 \contentspage{index.html}{Qt Creator}
32 \nextpage creator-overview.html
34 \title Qt Creator Manual
36 \section1 Version \qtcversion
38 Qt Creator provides a cross-platform, complete integrated development
39 environment (IDE) for application developers to create applications for
40 multiple desktop and mobile device platforms. It is available for Linux,
41 Mac OS X and Windows operating systems. For more information, see
42 \l{Operating Systems and Supported Platforms}.
44 \note Please report bugs and suggestions to the
45 \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}.
46 You can also join the Qt Creator mailing list at:
47 \l{http://lists.qt.nokia.com}{http://lists.qt.nokia.com}.
50 <img border="0" style="float:right;" src="images/qtcreator-screenshots.png" />
54 \o \l{Introducing Qt Creator}
55 \o \l{Qt Creator User Interface}
56 \o \l{Getting Started}
58 \o \l{Building and Running an Example Application}
59 \o \l{Creating a Qt Widget Based Application}
60 \o \l{Creating a Mobile Application with Qt SDK}
61 \o \l{Creating a Qt Quick Application}
63 \o \l{Managing Projects}
65 \o \l{Creating a Project}
66 \o \l{Opening a Project}
67 \o \l{Adding Libraries to Projects}
68 \o \l{Connecting Maemo and MeeGo Harmattan Devices}
69 \o \l{Connecting Symbian Devices}
70 \o \l{Managing Sessions}
74 \o \l{Using the Editor}
75 \o \l{Semantic Highlighting}
76 \o \l{Checking Code Syntax}
77 \o \l{Completing Code}
79 \o \l{Finding and Replacing}
81 \o \l{Using Qt Quick Toolbars}
82 \o \l{Searching With the Locator}
83 \o \l{Pasting and Fetching Code Snippets}
84 \o \l{Using Text Editing Macros}
85 \o \l{Configuring the Editor}
86 \o \l{Using FakeVim Mode}
88 \o \l{Developing Application UI}
90 \o \l{Developing Qt Quick Applications}
92 \o \l {Creating Qt Quick Projects}
93 \o \l {Using Qt Quick Designer}
94 \o \l {Creating Components}
95 \o \l {Creating Buttons}
96 \o \l {Creating Scalable Buttons and Borders}
97 \o \l {Creating Screens}
98 \o \l {Animating Screens}
99 \o \l {Adding User Interaction Methods}
100 \o \l {Exporting Designs from Graphics Software}
101 \o \l {Implementing Application Logic}
102 \o \l {Using QML Modules with Plugins}
104 \o \l{Developing Widget Based Applications}
105 \o \l{Optimizing Applications for Mobile Devices}
107 \o \l{Building and Running Applications}
109 \o \l{Building Applications for Multiple Targets}
110 \o \l{Running Applications on Multiple Targets}
111 \o \l{Specifying Build Settings}
113 \o \l{Adding Qt Versions}
114 \o \l{Adding Tool Chains}
116 \o \l{Specifying Run Settings}
117 \o \l{Specifying Editor Settings}
118 \o \l{Specifying Code Style Settings}
119 \o \l{Specifying Dependencies}
123 \o \l{Debugging the Example Application}
124 \o \l{Launching the Debugger}
125 \o \l{Interacting with the Debugger}
126 \o \l{Setting Up Debugger}
127 \o \l{Using Debugging Helpers}
128 \o \l{Debugging Qt Quick Projects}
129 \o \l{Troubleshooting Debugger}
131 \o \l{Analyzing Code}
133 \o \l{Profiling QML Applications}
134 \o \l{Detecting Memory Leaks}
135 \o \l{Profiling Function Execution}
137 \o \l{Deploying Applications to Mobile Devices}
139 \o \l{Deploying Applications to Symbian Devices}
140 \o \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}
141 \o \l{Publishing Maemo Applications to Extras-devel}
142 \o \l{Publishing Applications to Ovi Store}
143 \o \l{Building with Remote Compiler}
148 \o \l{Operating Systems and Supported Platforms}
149 \o \l{Adding New Custom Wizards}
150 \o \l{Setting Up a CMake Project}
151 \o \l{Setting Up a Generic Project}
152 \o \l{Using Version Control Systems}
153 \o \l{Adding Qt Designer Plugins}
154 \o \l{Using External Tools}
155 \o \l{Using Maemo or MeeGo Harmattan Emulator}
156 \o \l{Editing MIME Types}
157 \o \l{Showing Task List Files in the Build Issues Pane}
158 \o \l{Using Command Line Options}
159 \o \l{Keyboard Shortcuts}
162 \o \l{Tips and Tricks}
164 \o \l{Technical Support}
166 \o \l{Acknowledgements}
172 \contentspage index.html
173 \previouspage index.html
174 \page creator-overview.html
175 \nextpage creator-quick-tour.html
177 \title Introducing Qt Creator
179 Qt Creator is an integrated development environment (IDE) that provides you with
180 tools to design and develop applications with the Qt application framework. Qt is designed for
181 developing applications and user interfaces once and deploying them across several
182 desktop and mobile operating systems. Qt Creator provides you with tools for
183 accomplishing your tasks throughout the whole application development life-cycle,
184 from creating a project to deploying the application on the target platforms.
186 \image qtcreator-overview.png "Qt Creator overview"
188 \section1 Cross-platform Development
190 One of the major advantages of Qt Creator is that it allows a team of developers
191 to share a project across different development platforms with a common tool
192 for development and debugging.
194 The recommended way to build a project is to use a version control system.
195 Store and edit only project source files and the .pro and .pri files (for qmake)
196 or CMakeLists.txt and *.cmake files (for CMake). Do not store
197 files generated by the build system or Qt Creator, such as makefiles,
198 .pro.user, and object files. Other approaches are possible,
199 but we recommend that you do not use network resources, for example.
201 Qt Creator allows you to specify separate build settings
202 for each development platform. By default, \l{glossary-shadow-build}{shadow builds} are used to
203 keep the build specific files separate from the source.
205 You can create separate versions of project files to keep platform-dependent
206 code separate. You can use qmake
207 \l{http://qt.nokia.com/doc/4.7/qmake-tutorial.html#adding-platform-specific-source-files}{scopes}
208 to select the file to process depending on which platform qmake is run on.
210 Items such as open files, breakpoints, and evaluated expressions are stored in
211 sessions. They are not considered to be part of the
212 information shared across platforms.
214 \section1 Creating Projects
216 But why do you need projects? To be able to build and run applications,
217 Qt Creator needs the same information as a compiler would need. This information
218 is specified in the project build and run settings.
220 Creating a project allows you to:
224 \o Group files together
226 \o Add custom build steps
228 \o Include forms and resource files
230 \o Specify settings for running applications
234 Setting up a new project in Qt Creator is aided by a wizard that guides
235 you step-by-step through the project creation process. In the first step, you
236 select the type of the project from the categories: Qt Quick project, Qt widget
237 project, or other project. Next, you select a location for the project and
238 specify settings for it.
240 \image qtcreator-new-qt-quick-project-wizard.png
242 When you have completed the steps, Qt Creator automatically generates the
243 project with required headers, source files, user interface descriptions
244 and project files, as defined by the wizard.
245 For example, if you choose to create a Qt Quick application, Qt Creator
246 generates a QML file that you can modify with the integrated \QMLD.
248 \section2 Adding Libraries
250 In addition to Qt libraries, you can link your application to other
251 libraries, such as system libraries or your own libraries. Further, your
252 own libraries might link to other libraries. To be able to compile your
253 project, you must add the libraries to your project. This also enables
254 code completion and syntax highlighting for the libraries.
255 The procedure of adding a library to a project depends on the build
258 \section2 Version Control Systems
260 Qt Creator uses the version control system's command line clients to access
261 your repositories. The following version control systems are supported:
279 The functions available to you in Qt Creator depend on the version control
280 system. Basic functions are available for all the supported systems. They include
281 comparing files with the latest versions stored in the repository and displaying the
282 differences, viewing versioning history and change details, annotating files,
283 and committing and reverting changes.
285 \section1 Designing User Interfaces
287 Qt Creator provides two integrated visual editors, \QMLD and \QD.
289 \image qtcreator-ui-designers.png "Qt Quick Designer and Qt Designer"
291 Large high-resolution screens, touch input, and significant graphics power
292 are becoming common in portable consumer devices, such as mobile
293 phones, media players, set-top boxes, and netbooks. To fully benefit from
294 these features and to create intuitive, modern-looking, fluid user interfaces,
295 you can use \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}.
297 Qt Quick consists of a rich set of user interface elements, a declarative
298 language for describing user interfaces, and a language runtime. A
299 collection of C++ APIs is used to integrate these high level features with
300 classic Qt applications.
302 You can edit QML code in the code editor or in the integrated \QMLD.
303 The integration includes project management and code completion.
305 If you need a traditional user interface that is clearly structured and
306 enforces a platform look and feel, you can use the integrated \QD. You can
307 compose and customize your widgets or dialogs and test them using different
308 styles and resolutions.
310 \section1 Code Editor
312 As an IDE, Qt Creator differs from a text editor in that it knows how to build and run
313 applications. It understands the C++ and QML languages as code, not just as plain text. This allows
318 \o Enable you to write well formatted code
320 \o Anticipate what you are going to write and complete the code
322 \o Display inline error and warning messages
324 \o Enable you to semantically navigate to classes, functions, and symbols
326 \o Provide you with context-sensitive help on classes, functions, and symbols
328 \o Rename symbols in an intelligent way, so that other symbols with the same name
329 that belong to other scopes are not renamed
331 \o Show you the locations in code where a function is declared or called
335 You can use the code editor to write code in Qt C++ or in the
336 QML declarative programming language.
337 QML is an extension to JavaScript, that provides a mechanism to declaratively build
338 an object tree of QML elements. QML improves the integration between JavaScript and
339 Qt's existing QObject based type system, adds support for automatic property bindings
340 and provides network transparency at the language level.
344 Qt Creator is integrated with cross-platform systems for build automation:
345 qmake and CMake. In addition, you can import generic projects that do not use qmake
346 or CMake, and specify that Qt Creator ignores your build system.
348 Qt Creator provides support for building and running Qt applications for
349 desktop environment (Windows, Linux, and Mac OS) and mobile devices
350 (Symbian, Maemo, and MeeGo Harmattan).
351 Build settings allow you to quickly switch between build targets.
353 When you install the \QSDK, the build and run settings for the Harmattan,
355 targets are set up automatically. However, you need to install and configure some
356 additional software on the devices to be able to connect to them from the
359 \note The only supported build system for mobile applications in Qt
364 If you install Qt Creator as part of \QSDK, the GNU Symbolic Debugger
365 is installed automatically and you should be ready to start debugging after
366 you create a new project. However, you can change the setup to use debugging
367 tools for Windows, for example.
368 You can connect mobile devices to your development PC and debug processes
369 running on the devices.
371 You can use code analysis tools to detect memory leaks, profile cache usage,
372 and profile Qt Quick applications.
374 You can test applications that are intended for mobile devices in the Qt
375 Simulator and Maemo Emulator, but you also need to test the applications
380 Qt Creator is integrated to several external native debuggers:
384 \o GNU Symbolic Debugger (GDB)
386 \o Microsoft Console Debugger (CDB)
388 \o internal JavaScript debugger
392 You can use the Qt Creator \gui Debug mode to inspect the state of your
393 application while debugging. You can interact with the debugger in several
394 ways, including the following:
397 \o Go through a program line-by-line or instruction-by-instruction.
398 \o Interrupt running programs.
400 \o Examine the contents of the call stack.
401 \o Examine and modify registers and memory contents of
402 the debugged program.
403 \o Examine and modify registers and memory contents of
404 local and global variables.
405 \o Examine the list of loaded shared libraries.
406 \o Create snapshots of the current state of the debugged program
407 and re-examine them later.
410 Qt Creator displays the raw information provided by the native debuggers
411 in a clear and concise manner with the goal to simplify the debugging process
412 as much as possible without losing the power of the native debuggers.
414 In addition to the generic IDE functionality provided by stack view, views for
415 locals and expressions, registers, and so on, Qt Creator includes
416 features to make debugging Qt-based applications easy. The debugger
417 plugin understands the internal layout of several Qt classes, for
418 example, QString, the Qt containers, and most importantly QObject
419 (and classes derived from it), as well as most containers of the C++
420 Standard Library and some GCC and Symbian extensions. This
421 deeper understanding is used to present objects of such classes in
424 \section3 QML Script Console
426 You can use the Qt Creator \gui Debug mode to inspect the state of
427 the application while debugging JavaScript functions. You can set breakpoints,
428 view call stack trace, and examine locals and expressions.
430 When the application is interrupted by a breakpoint, you can use the \gui {QML
431 Script Console} to execute JavaScript expressions in the current context. You can
432 type JavaScript expressions and use them to get information about the state of the
433 application, such as property values.
435 If you change property values or add properties in the code editor, the
436 changes are updated in the running application when they are saved.
438 \section3 QML Observer
440 While the application is running, you can use the \gui {QML Observer} view to
441 explore the object structure, debug animations, and inspect colors. When debugging
442 complex applications, you can use the observe mode to jump to the position in code
443 where an element is defined.
445 \section2 Code Analysis Tools
447 The memory available on devices is limited and you should use it carefully.
448 Qt Creator integrates Valgrind code analysis tools for detecting memory
449 leaks and profiling function execution. These tools are only supported on
451 Mac OS. You must download and install them separately to use them from Qt
454 The QML Profiler is installed as part of Qt Creator. It allows you
455 to profile your Qt Quick applications and is available on all supported
456 development platforms.
458 \section2 Qt Simulator
460 You can use the Qt Simulator to test Qt applications that are intended
461 for mobile devices in an environment similar to that of the device. You
462 can change the information that the device has about its configuration
465 The Qt Simulator is installed as part of the \QSDK. After it is
466 installed, you can select it as a build target in Qt Creator.
468 \section2 Maemo and MeeGo Harmattan Emulator
470 The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
471 of the \QSDK. After they are installed, you can start them from Qt Creator.
473 The Maemo 5 emulator emulates the Nokia N900 device environment. You can test
474 applications in conditions practically identical to running the application
475 on a Nokia N900 device with the software update release 1.3 (V20.2010.36-2).
477 The Harmattan emulator emulates the Nokia N9 device environment.
479 With the emulators, you can test how your application reacts to hardware
480 controls, such as the power button, and to the touch screen.
481 Usually, it is faster to test on a real device connected to the development
482 PC than to use the emulators.
486 Qt Creator deploy configurations handle the packaging of the application as an
487 executable and copying it to a location developers want to run the executable at.
488 The files can be copied to a location in the file system of the development PC
489 or to a mobile device.
491 Qt Creator allows you to create installation packages for Symbian, Maemo,
493 devices that are suitable for publishing on Ovi Store and other channels.
498 \contentspage index.html
499 \previouspage creator-advanced.html
500 \page creator-os-supported-platforms.html
501 \nextpage creator-project-wizards.html
503 \title Operating Systems and Supported Platforms
505 \section1 Operating Systems
507 Qt Creator is available in binary packages for the following operating
511 \o Windows XP Service Pack 2
513 \o (K)Ubuntu Linux 8.04 (32-bit and 64-bit) or later, with the following:
520 \o libfontconfig1-dev
529 \o If you are using QtOpenGL, libgl-dev and libglu-dev
531 \o Mac OS 10.5 or later with the following:
533 \o Xcode tools for your Mac OS X version available from your Mac
534 OS X installation DVDs or at \l http://developer.apple.com.
538 \omit ## Are the Xcode tools still needed separately? \endomit
540 \section1 Compiling Qt Creator from Source
542 To build Qt Creator itself from the source, see the requirements and
543 instructions in the readme file that is located in the source repository.
545 \section1 Supported Platforms
547 You can develop applications for the following platforms:
563 The following table summarizes operating system support for developing
564 applications for mobile device platforms.
568 \o {1,5} Operating system
590 \o Yes (by using Remote Compiler for building)
597 \o Yes (by using Remote Compiler for building)
603 \contentspage index.html
604 \previouspage creator-overview.html
605 \page creator-quick-tour.html
606 \nextpage creator-getting-started.html
608 \title Qt Creator User Interface
610 \image qtcreator-breakdown.png
612 When you start Qt Creator, it opens to the \gui Welcome mode, where you can:
616 \o Read news from the Qt labs
618 \o Open tutorials and example projects
620 \o Create and open projects
622 \o Send feedback to the development team
624 \o Open recent sessions and projects
628 You can use the mode selector to change to another Qt Creator mode.
629 The following image displays an example application in \gui Edit mode
630 and \gui Design mode.
632 \image qtcreator-qt-quick-editors.png "Edit mode and Design mode"
634 Qt Creator has been localized into several languages. If the system language
635 is one of the supported languages, it is automatically selected. To change
636 the language, select \gui {Tools > Options > Environment} and select a language
637 in the \gui Language field. The change takes effect after you restart Qt Creator.
639 \section1 Qt Creator Modes
641 The mode selector allows you to quickly switch between tasks such as
642 editing project and source files, designing application UIs,
643 configuring how projects are built and
644 executed, and debugging your applications. To change modes, click the
645 icons, or use the \l{keyboard-shortcuts}{corresponding keyboard shortcut}.
647 You can use Qt Creator in the following modes:
650 \o \gui Welcome mode for opening projects.
651 \o \gui{\l{Using the Editor}{Edit}} mode for editing project and source files.
652 \o \gui{\l{Developing Application UI}{Design}} mode for designing and developing
653 application user interfaces. This mode is available for UI files (.ui or
655 \o \gui{\l{Debugging}{Debug}} mode for inspecting the state of your program while
657 \o \gui{\l{Specifying Build Settings}{Projects}} mode for configuring project building and
658 execution. This mode is available when a project is open.
659 \o \gui{\l{Analyzing Code}{Analyze}} mode for using code analysis tools
660 to detect memory leaks and profile C++ or QML code.
661 \o \gui{\l{Getting Help}{Help}} mode for viewing Qt documentation.
664 Certain actions in Qt Creator trigger a mode change. Clicking on
665 \gui {Debug} > \gui {Start Debugging} > \gui {Start Debugging}
666 automatically switches to \gui {Debug} mode.
669 \section1 Browsing Project Contents
671 The sidebar is available in the \gui Edit and \gui Debug modes.
672 Use the sidebar to browse projects, files, and bookmarks, and to view
674 \image qtcreator-sidebar.png
676 You can select the content of the sidebar in the sidebar menu:
678 \o \gui Projects shows a list of projects open in the current
680 \o \gui{Open Documents} shows currently open files.
681 \o \gui Bookmarks shows all bookmarks for the current session.
682 \o \gui{File System} shows all files in the currently selected
684 \o \gui {Class View} shows the class hierarchy of the currently
686 \o \gui Outline shows the symbol hierachy of a C++ file and the element hierarchy of a QML file.
687 \o \gui {Type Hierarchy} shows the base classes of a class.
691 You can change the view of the sidebar in the following ways:
693 \o To toggle the sidebar, click \inlineimage qtcreator-togglebutton.png
694 or press \key Alt+0 (\key Cmd+0 on Mac OS X).
695 \o To split the sidebar, click \inlineimage qtcreator-splitbar.png
696 . Select new content to view in the split view.
697 \o To close a sidebar view, click
698 \inlineimage qtcreator-closesidebar.png
702 The additional options in each view are described in the following
705 \section2 Viewing Project Files
707 The sidebar displays projects in a project tree. The project tree contains
708 a list of all projects open in the current session. The files for each
709 project are grouped according to their file type.
711 You can use the project tree in the following ways:
713 \o To bring up a context menu containing the actions most commonly
714 needed right-click an item in the project tree.
715 For example, through the menu of the project root directory you can,
716 among other actions, build, re-build, clean and run the project.
717 \o To hide the categories and sort project files alphabetically, click
718 \inlineimage qtcreator-filter.png
719 and select \gui{Simplify Tree}.
720 \o To hide source files which are automatically generated by the build
721 system, during a build, click \inlineimage qtcreator-filter.png
722 and select \gui{Hide Generated Files}.
723 \o To keep the position in the project tree synchronized with the file
724 currently opened in the editor, click
725 \inlineimage qtcreator-synchronizefocus.png
727 \o To see the absolute path of a file, move the mouse pointer over the
731 \section2 Viewing the File System
733 If you cannot see a file in the \gui Projects view, switch to the
734 \gui {File System} view, which shows all the files in the file system.
736 To keep the position in the tree synchronized with the file
737 opened in the editor, click
738 \inlineimage qtcreator-synchronizefocus.png
741 \section2 Viewing the Class Hierarchy
743 The \gui {Class View} shows the class hierarchy of the currently
744 open projects. To organize the view by subprojects, click
745 \inlineimage qtcreator-show-subprojects.png
748 \section2 Viewing QML Elements
750 The \gui Outline view shows the element hierarchy in a QML file.
754 \o To see a complete list of all bindings, click
755 \inlineimage qtcreator-filter.png
756 and select \gui{Show All Bindings}.
758 \o To keep the position in the view synchronized with the element
759 selected in the editor, click
760 \inlineimage qtcreator-synchronizefocus.png
765 \section2 Viewing Type Hierarchy
767 To view the base classes of a class, right-click the class and select
768 \gui {Open Type Hierarchy} or press \key {Ctrl+Shift+T}.
770 \section1 Viewing Output
772 The task pane in Qt Creator can display one of the following panes:
774 \o \gui{Build Issues}
775 \o \gui{Search Results}
776 \o \gui{Application Output}
777 \o \gui{Compile Output}
778 \o \gui{General Messages}
780 \o \gui{Version Control}
783 Output panes are available in all \l{Qt Creator modes}{modes}.
784 Click the name of an output pane to open the pane. To maximize
785 an open output pane, click the \gui {Maximize Output Pane} button
786 or press \key {Alt+9}.
788 To search within the \gui{Application Output} and \gui{Compile Output}
789 panes, press \key {Ctrl+F} when the pane is active. Enter search
790 criteria in the \gui Find field and click the left and right arrows to
791 search down and up in the pane.
793 To open the \gui{General Messages}, \gui{Analysis}, and \gui{Version Control}
794 panes, select \gui {Window > Output Panes}.
797 \section2 Build Issues
799 The \gui{Build Issues} pane provides a list of errors and warnings
800 encountered during a build. The pane filters out irrelevant output from
801 the build tools and presents the issues in an organized way.
803 Right-clicking on a line brings up a context menu with options to copy
804 the contents and to show a version control annotation view of the
805 line that causes the error message.
807 \image qtcreator-build-issues.png
809 To view task lists in the \gui{Build Issues} pane, click
810 \inlineimage qtcreator-filter.png
811 and select \gui{My Tasks}. Entries from a task list file (.tasks) are
812 imported to the pane. Press \key F6 and \key Shift+F6 to jump from one issue
815 For more information about creating task files, see
816 \l{Showing Task List Files in the Build Issues Pane}.
818 \section2 Search Results
820 The \gui{Search Results} pane displays the results for global searches,
821 for example, searching within a current document, files on disk, or all
824 The figure below shows an example search result for all
825 occurrences of \c textfinder within the \c "/TextFinder" directory.
827 \image qtcreator-search-pane.png
830 \section2 Application Output
832 The \gui{Application Output} pane displays the status of a program when
833 it is executed, and the debug output.
835 The figure below shows an example output from qDebug().
837 \image qtcreator-application-output.png
840 \section2 Compile Output
842 The \gui{Compile Output} pane provides all output from the compiler.
843 The \gui{Compile Output} is a more detailed version of information
844 displayed in the \gui{Build Issues} pane.
846 \image qtcreator-compile-pane.png
848 \section1 Navigating with Keyboard
850 Qt Creator caters not only to developers who are used to using the mouse,
851 but also to developers who are more comfortable with the keyboard. A wide
852 range of \l{keyboard-shortcuts}{keyboard} and
853 \l{Searching With the Locator}{navigation} shortcuts are available to help
854 speed up the process of developing your application.
860 \contentspage index.html
861 \previouspage creator-remote-compiler.html
862 \page creator-help.html
863 \nextpage creator-advanced.html
867 Qt Creator comes fully integrated with Qt documentation and
868 examples using the Qt Help plugin.
871 \o To view documentation, switch to \gui Help mode.
872 \o To obtain context sensitive help, move the text cursor to a Qt class
873 or function and press \key F1. The documentation is displayed in a
874 pane next to the code editor, or, if there is not enough vertical
875 space, in the fullscreen \gui Help mode.
876 \o To select and configure how the documentation is displayed in the
877 \gui Help mode, select \gui Tools > \gui Options... > \gui Help.
880 The following image displays the \gui Search pane in the \gui Help mode.
882 \image qtcreator-help-search.png
884 The following image displays the context sensitive help in the \gui Edit
887 \image qtcreator-context-sensitive-help.png
889 \section1 Finding Information in Qt Documentation
891 Qt Creator, \QSDK and other Qt deliverables contain documentation
892 as .qch files. All the documentation is accessible in the \gui Help mode.
894 To find information in the documentation, select:
898 \o \gui Bookmarks to view a list of pages on which you have added bookmarks.
900 \o \gui Contents to see all the documentation installed on the development
901 PC and to browse the documentation contents.
903 \o \gui Index to find information based on a list of keywords in all the
906 \o \gui {Open Pages} to view a list of currently open documentation pages.
908 \o \gui Search to search from all the installed documents.
912 \section2 Adding Bookmarks to Help Pages
914 You can add bookmarks to useful help pages to easily find them later
915 in the \gui Bookmarks view. You can either use the page title as the
916 bookmark or change it to any text. You can organize the bookmarks in
919 \image qtcreator-help-add-bookmark-dlg.png "Add Bookmark dialog"
921 To add a bookmark to an open help page:
926 \inlineimage qtcreator-help-add-bookmark.png
927 (\gui {Add Bookmark}) button on the toolbar.
929 \o In the \gui {Add Bookmark} dialog, click \gui OK to save the
930 page title as a bookmark in the \gui Bookmarks folder.
934 To import and export bookmarks, select \gui {Tools > Options... > Help >
935 General Settings > Import} or \gui Export.
937 \section1 Adding External Documentation
939 You can display external documentation in the \gui Help mode.
940 To augment or replace the documentation that ships with Qt Creator and Qt:
942 \o Create a .qch file from your documentation.
944 For information on how to prepare your documentation and create a
946 \l{http://doc.qt.nokia.com/4.7/qthelp-framework.html}{The Qt Help Framework}.
947 \o To add the .qch file to Qt Creator, select \gui Tools >
948 \gui Options... > \gui Help > \gui Documentation > \gui Add.
951 \section1 Detaching the Help Window
953 By default, context-sensitive help is opened in a window next to the
954 code editor when you press \key F1. If there is not enough vertical
955 space, the help opens in the full-screen help mode.
957 You can specify that the help always opens in full-screen mode or
958 is detached to an external window. Select \gui {Tools > Options... > Help >
959 General Settings} and specify settings for displaying context-sensitive help
960 in the \gui {On context help} field. To detach the help window, select
961 \gui {Always Show Help in External Window}.
963 You can select the help page to open upon startup in the \gui {Home Page}
966 \section1 Using Documentation Filters
968 You can filter the documents displayed in the \gui Help mode to find
969 relevant information faster. Select from a list of filters in the
970 \gui {Filtered by} field. The contents of the \gui Index and \gui Contents
971 pane in the sidebar change accordingly.
973 \image qtcreator-help-filters.png "Help filters"
975 You can modify the filters to include external documentation, for example,
976 or you can define your own filters. To construct filters, you can use the
977 filter attributes that are specified in the documentation. Each document
978 contains at least one filter attribute. If several documents contain the
979 same filter attribute, such as \c tools, you can use that attribute to
980 include all those documents.
986 \o Select \gui {Tools > Options... > Help > Filters > Add}.
988 \o Enter a name for the filter and press \gui {OK}.
990 \o In \gui Attributes, select the documents that you want to include
993 \image qtcreator-help-filter-attributes.png "Help filter attributes"
997 \o In the \gui Help mode, select the filter in the \gui {Filtered by}
998 field to see the filtered documentation in the sidebar.
1002 To modify filters, select a filter in \gui Filters, select the attributes,
1003 and then click \gui Apply.
1005 To remove filters, select them in \gui Filters, and click \gui Remove.
1011 \contentspage index.html
1012 \previouspage creator-editor-fakevim.html
1013 \page creator-design-mode.html
1014 \nextpage creator-visual-editor.html
1016 \title Developing Application UI
1018 Large high-resolution screens, touch input, and significant graphics power
1019 are becoming common in portable consumer devices, such as mobile
1020 phones, media players, set-top boxes, and netbooks. To fully benefit from
1021 these features and to create intuitive, modern-looking, fluid user interfaces,
1022 you can use \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}.
1024 Qt Quick consists of a rich set of user interface elements, a declarative
1025 language for describing user interfaces, and a language runtime. A
1026 collection of C++ APIs is used to integrate these high level features with
1027 classic Qt applications.
1029 You can edit QML code in the code editor or in the integrated \QMLD.
1031 \image qtcreator-design-mode.png "Design mode"
1033 The integration includes project management and code completion.
1035 If you need a traditional user interface that is clearly structured and
1036 enforces a platform look and feel, you can use the integrated \QD. You can
1037 compose and customize your widgets or dialogs and test them using different
1038 styles and resolutions.
1040 The following sections describe how to develop application UI:
1044 \o \l{Developing Qt Quick Applications}
1045 \o \l{Developing Widget Based Applications}
1046 \o \l{Optimizing Applications for Mobile Devices}
1054 \contentspage index.html
1055 \previouspage creator-qml-modules-with-plugins.html
1056 \page creator-using-qt-designer.html
1057 \nextpage creator-usability.html
1059 \title Developing Widget Based Applications
1061 Widgets and forms created with \QD are integrated seamlessly with
1062 programmed code by using the Qt signals and slots mechanism that allows you
1063 to easily assign behavior to
1064 graphical elements. All properties set in \QD can be changed dynamically within the code.
1065 Furthermore, features such as widget promotion and custom plugins allow you to use your
1066 own widgets with \QD. For more information, see
1067 \l{Adding Qt Designer Plugins}.
1069 Qt Creator automatically opens all .ui files in the integrated \QD, in
1072 \image qtcreator-formedit.png
1074 For more information about \QD, see the
1075 \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
1077 Generally, the integrated \QD contains the same functions as the standalone
1078 \QD. The following sections describe the differences.
1080 \section1 Code Editor Integration
1082 To switch between forms (\gui Design mode) and code (\gui Edit mode),
1083 press \key Shift+F4.
1085 You can use Qt Creator to create stub implementations of slot functions.
1086 In the \gui Design mode, right-click a widget to open a context menu, and
1087 then select \gui {Go to Slot...}. Select a signal in the list to go to an
1088 existing slot function or to create a new slot function.
1090 \section1 Managing Image Resources
1092 In standalone \QD, image resources are created using the built-in
1093 \gui {Resource Editor}. In Qt Creator, .ui files are usually part of a
1094 project, which may contain several resource files (.qrc). They are created
1095 and maintained by using the Qt Creator Resource Editor. The \QD
1096 \gui {Resource Editor} is de-activated and the image resources are
1097 displayed in the \QD \gui {Resource Browser}.
1099 \section1 Specifying Settings for Qt Designer
1101 To change the layout of \QD user interface elements:
1104 \o Select \gui Tools > \gui{Form Editor} > \gui Views >
1107 When this option is unchecked, you can change the layout.
1108 \o Click the header of an element and drag the element to a new
1112 To specify settings for \QD:
1116 \o Select \gui Tools > \gui Options... > \gui Designer.
1118 \o Specify settins for generating classes and code in \gui {Class
1121 \o Specify embedded device profiles, that determine style, font, and
1122 screen resolution, for example, in \gui{Embedded Design}.
1124 \o Specify settings for the grid and previewing forms in \gui Forms.
1126 \o Specify an additional folder for saving templates in \gui{Template
1131 To preview the settings, select \gui Tools > \gui{Form Editor} >
1132 \gui Preview, or press \key Alt+Shift+R.
1134 \section1 Previewing Forms Using Device Skins
1136 A \e {device skin} is a set of configuration files that describe a mobile
1137 device. It includes a border image that surrounds the form and depicts a
1138 mobile device with its buttons.
1140 To preview your form using device skins:
1144 \o Select \gui Tools > \gui Options... > \gui Designer.
1146 \o Select the \gui{Print/Preview Configuration} check box.
1148 \o In the \gui {Device skin} field, select a device skin.
1150 \o When the form is open in \gui Design mode, press \key Alt+Shift+R.
1152 \o To end the preview, right-click the skin and select \gui Close in
1160 \contentspage index.html
1161 \previouspage quick-projects.html
1162 \page creator-using-qt-quick-designer.html
1163 \nextpage quick-components.html
1165 \title Using Qt Quick Designer
1167 You can edit .qml files in the \QMLD visual editor or in the
1170 In \gui Projects, double-click a .qml file to open it in the code
1171 editor. Then select the \gui {Design} mode to edit the file in the
1174 \image qmldesigner-visual-editor.png "Visual editor"
1176 Use the visual editor panes to manage your project:
1180 \o \gui {Navigator} pane displays the QML elements in the current QML file
1183 \o \gui {Library} pane displays the building blocks that you can use to design
1184 applications: predefined QML elements, your own QML components, and other
1187 \o \gui Canvas is the working area where you create QML components and
1188 design applications.
1190 \o \gui {Properties} pane organizes the properties of the selected QML element
1191 or QML component. You can also change the properties in the code editor.
1193 \o \gui {State} pane displays the different states of the component. QML
1194 states typically describe user interface configurations, such as the UI
1195 elements, their properties and behavior and the available actions.
1199 \section1 Managing Element Hierarchy
1201 The \gui Navigator pane displays the
1202 \l{http://doc.qt.nokia.com/4.7/qdeclarativeelements.html}{QML elements}
1203 in the current QML file and their relationships.
1204 Elements are listed in a tree structure, below their parent.
1206 \image qmldesigner-navigator.png "Navigator pane"
1208 You can select elements in the \gui Navigator to edit their properties
1209 in the \gui Properties pane. Elements can access the properties of their
1212 Typically, child elements are located within the parent element on the
1213 canvas. However, they do not necessarily have to fit inside the parent element.
1214 For example, you might want to make a mouse area larger than the rectangle
1215 or image beneath it.
1217 \image qmldesigner-element-size.png "Mouse area for a button"
1219 When you copy an element, all its child elements are also copied. When
1220 you remove an element, the child elements are also removed.
1222 You can show and hide items to focus on specific parts of the application.
1224 \inlineimage qmldesigner-show-hide-icon.png
1225 icon to change the visibility of an element on the canvas. To change the
1226 visibility of an element in the application, use the \gui Visibility
1227 check box or the \gui Opacity field in the \gui Properties pane. If you set
1228 \gui Opacity to 0, elements are hidden, but you can still apply animation
1231 As all properties, visibility and opacity are inherited from the parent
1232 element. To hide or show child elements, edit the properties of the
1235 To view lists of files or projects, instead, select \gui {File System},
1236 \gui {Open Documents}, or \gui Projects in the menu.
1237 To view several types of content at a time, split the sidebar by clicking
1238 \inlineimage qtcreator-splitbar.png
1241 \section2 Switching Parent Elements
1243 When you drag and drop QML elements to the canvas, Qt Quick Designer
1244 adds the new element as a child of the element beneath it.
1245 When you move elements on the canvas, Qt Quick Designer cannot determine
1246 whether you want to adjust their position or attach them to a new
1247 parent element. Therefore, the parent element is not automatically
1248 changed. To change the parent of the element, press down the \key Shift
1249 key before you drag and drop the element into a new position. The topmost
1250 element under the cursor becomes the new parent of the element.
1252 You can change the parent of an element also in the \gui Navigator pane.
1253 Drag and drop the element to another position in the tree.
1255 \section1 Element Library
1257 The \gui {Library} pane contains two tabs: \gui {Items} and \gui {Resources}.
1258 The \gui Items pane displays the QML elements grouped by type: your own QML
1259 components, basic elements, interaction elements, views, and widgets.
1262 Sets of UI components with the MeeGo and Symbian look and feel have been
1263 defined for Qt Quick. They are based on standard QML elements. To view the
1264 UI components in \gui {QML Components}, click
1265 \inlineimage qtcreator-filter.png
1266 and select \gui {MeeGo Components} or \gui {Symbian Components}.
1269 \image qmldesigner-qml-components.png "QML Components pane"
1271 The \gui {Resources} pane displays the images and other files that you copy to
1272 the project folder (to the same subfolder as the QML files).
1274 \section1 Specifying Element Properties
1276 The \gui Properties pane displays all the properties of the selected QML element.
1277 The properties are grouped by type. The top part of the pane displays properties
1278 that are common to all elements, such as element type, position, size,
1281 The bottom part of the pane displays properties that are specific to each element
1282 type. For example, the following image displays the properties you can set for
1283 \gui Rectangle and \gui Text elements.
1285 \image qmldesigner-element-properties.png
1287 The default values of properties are displayed in white color, while the values
1288 that you specify explicitly are highlighted with blue color. In addition, property
1289 changes in states are highlighted with blue.
1291 For more information on the properties available for an element, press \key {F1}.
1293 \section2 Setting Expressions
1295 \l{http://doc.qt.nokia.com/4.7/propertybinding.html}{Property binding}
1296 is a declarative way of specifying the value of a property.
1297 Binding allows a property value to be expressed as an JavaScript expression
1298 that defines the value relative to other property values or data accessible
1299 in the application. The property value is automatically kept up to date if
1300 the other properties or data values change.
1302 Property bindings are created implicitly in QML whenever a property is assigned
1303 an JavaScript expression. To set JavaScript expressions as values of properties
1304 in Qt Quick Designer, click the circle
1305 icon next to a property to open a context menu, and select \gui {Set Expression}.
1307 \image qmldesigner-set-expression.png "Element properties context menu"
1309 To remove expressions, select \gui Reset in the context menu.
1311 For more information on the JavaScript environment provided by QML, see
1312 \l{http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html}{Integrating JavaScript}.
1314 \section2 Loading Placeholder Data
1316 Often, QML applications are prototyped with fake data that is later
1317 replaced by real data sources from C++ plugins. QML Viewer loads fake data
1318 into the application context: it looks for a directory named \e dummydata
1319 in the same directory as the target QML file, loads any .qml files in that
1320 directory as QML objects, and binds them to the root context as properties.
1321 For more information, see
1322 \l{http://doc.qt.nokia.com/latest/qmlviewer.html}{QML Viewer}.
1324 You can use dummydata files also to specify fake properties for QML
1325 components that you open for editing in \QMLD.
1326 A QML component provides a way of defining a new UI element that you can
1327 re-use in other QML files. A component is generally defined in its own QML
1328 file. You can use property binding to specify the properties of a component
1329 to make it easily reusable.
1331 For example, you can create a button bar component (buttonbar.qml) that
1332 inherits its width from the screen that is its parent:
1344 However, when you open the QML file for editing in \QMLD, the button bar
1345 component does not have a width, because it is specified outside the QML
1346 file (in the QML file that specifies the screen). To specify a fake width
1347 for the component, create a \c <component>_dummydata.qml file (here,
1348 buttonbar_dummydata.qml) that specifies the component width and copy it to
1349 the \c dummydata directory.
1355 import QmlDesigner 1.0
1357 DummyContextObject {
1359 property real width: 1000
1364 The file is reloaded if you change it.
1366 \section2 Setting Anchors and Margins
1368 In addition to arranging elements in a grid, row, or column, you can use
1369 \l{http://doc.qt.nokia.com/4.7/qml-anchor-layout.html}{anchors} to lay out screens.
1370 In an anchor-based layout, each item can be thought of as having a set of
1371 invisible \e anchor lines: top, bottom, left, right, fill, horizontal center,
1372 vertical center, and baseline.
1374 In the \gui Layout pane you can set anchors and margins for elements. To set
1375 the anchors of an item, click the anchor buttons. You can combine the top/bottom,
1376 left/right, and horizontal/vertical anchors to anchor objects in the corners of
1377 the parent element or center them horizontally or vertically within the parent
1380 \image qmldesigner-anchor-buttons.png "Anchor buttons"
1382 In version 2.1, specifying the baseline anchor in Qt Quick Designer is
1383 not supported. You can specify it using the code editor.
1385 For performance reasons, you can only anchor an element to its siblings and
1386 direct parent. By default, an element is anchored to its parent when you
1387 use the anchor buttons. Select a sibling of the element in the \gui Target
1388 field to anchor to it, instead.
1390 Arbitrary anchoring is not supported. For example, you cannot specify:
1391 \c {anchor.left: parent.right}. You have to specify: \c {anchor.left: parent.left}.
1392 When you use the anchor buttons, anchors to the parent element are always
1393 specified to the same side. However, anchors to sibling elements are specified
1394 to the opposite side: \c {anchor.left: sibling.right}. This allows you to keep
1395 sibling elements together.
1397 In the following image, \gui{Rectangle 2} is anchored to its siblings on its
1398 right and left and to the bottom of its parent.
1400 \image qmldesigner-anchors.png "Anchoring sibling elements"
1402 The anchors for \gui{Rectangle 2} are specified as follows in code:
1407 anchors.right: rectangle3.left
1408 anchors.rightMargin: 15
1409 anchors.left: rectangle1.right
1410 anchors.leftMargin: 15
1411 anchors.bottom: parent.bottom
1412 anchors.bottomMargin: 15
1417 Margins specify the amount of empty space to leave to the outside of an item.
1418 Margins only have meaning for anchors. They do not take any effect when using
1419 other layouts or absolute positioning.
1421 \section2 Building Transformations on Items
1423 The \gui Advanced pane allows you configure advanced transformations, such as
1424 rotation, scale, and translation. You can assign any number of transformations
1425 to an item. Each transformation is applied in order, one at a time.
1427 For more information on Transform elements, see
1428 \l {http://doc.qt.nokia.com/4.7/qml-transform.html}{QML Transform Element}.
1430 \section1 Adding States
1432 User interfaces are designed to present different interface configurations
1433 in different scenarios, or to modify their appearances in response to user
1434 interaction. Often, there are a set of changes that are made concurrently,
1435 such that the interface could be seen to be internally changing from one
1436 \e state to another.
1438 This applies generally to interface elements regardless of their complexity.
1439 A photo viewer may initially present images in a grid, and when an image is
1440 clicked, change to a detailed state where the individual image is expanded
1441 and the interface is changed to present new options for image editing.
1442 On the other end of the scale, when a simple button is pressed, it may change
1443 to a \e pressed state in which its color and position is modified to give a
1446 In QML, any object can change between different states to apply sets of changes
1447 that modify the properties of relevant items. Each state can present a
1448 different configuration that can, for example:
1452 \o Show some UI elements and hide others.
1454 \o Present different available actions to the user.
1456 \o Start, stop or pause animations.
1458 \o Execute some script required in the new state.
1460 \o Change a property value for a particular item.
1462 \o Show a different view or screen.
1466 The \gui State pane displays the different
1467 \l{http://doc.qt.nokia.com/4.7/qdeclarativestates.html}{states}
1468 of the component in the Qt Quick Designer.
1470 \image qmldesigner-transitions.png "State pane"
1472 To add states, click the empty slot. Then modify the new state in the editor.
1473 For example, to change the appearance of a button, you can hide the button
1474 image and show another image in its place. Or, to add movement to the screen,
1475 you can change the position of an object on the canvas and then add animation
1476 to the change between the states.
1478 You can preview the states in the \gui State pane and click them to switch
1479 between states on the canvas.
1481 For more information on using states, see \l{Creating Screens}.
1483 If you add animation to the states, you can run the application to test the
1486 For more information on adding animation, see \l{Animating Screens}.
1488 \section1 Aligning and Positioning Elements
1490 The position of an element on the canvas can be either absolute or relative
1491 to other elements. In the element properties, you can set the x and y
1492 coordinates of an element, or \l{Setting Anchors and Margins}{anchor} it to its
1493 parent and sibling elements.
1495 \section2 Snap to Margins
1497 When you are working on a design, you can use snap and guides to align
1498 elements on the canvas. Click the
1499 \inlineimage qmldesigner-snap-to-guides-button.png
1500 button to have the elements snap to the guides.
1502 Choose \gui {Tools > Options... > Qt Quick} to specify settings for snap to
1503 margins. In the \gui {Snap margin} field, specify the position of the guides
1504 as pixels from the edge of the canvas. In the \gui {Item spacing} field,
1505 specify the space in pixels to leave between elements on the screen.
1507 The following image shows the position of the guides when \gui {Snap margin}
1510 \image qmldesigner-snap-margins.png "Snap margins on canvas"
1512 \section2 Hiding Element Boundaries
1514 Qt Quick Designer displays the boundaries of elements on the canvas. To hide
1515 the element boundaries, click the
1516 \inlineimage qmldesigner-show-bounding-rectangles-button.png
1519 \section2 Selecting Elements
1521 When you point the mouse to overlapping elements, the frontmost element is
1522 selected by default. However, elements that do not have any content, such as
1523 the mouse area, are typically located in front of elements that do have
1524 content, such as rectangles or border images. To select elements with content
1525 by default, click the
1526 \inlineimage qmldesigner-only-select-items-with-content.png
1529 \section2 Previewing Element Size
1531 The width and height of the root item in a QML file determine the size of
1532 the QML element. You can reuse elements, such as buttons, in different
1533 sizes in other QML files and design screens for use with different device
1534 profiles, screen resolution, or screen orientation. The component size
1535 might also be zero (0,0) if its final size is determined by property
1538 To experiment with different element sizes, enter values in the
1539 \gui Height and \gui Width fields on the canvas toolbar. The changes are
1540 displayed in the \gui States pane and on the canvas, but the property
1541 values are not changed permanently in the QML file. You can permanently
1542 change the property values in the \gui Properties pane.
1544 \image qmldesigner-preview-size.png "Canvas width and height"
1546 \section1 Specifying Canvas Size
1548 To change the canvas size, select \gui {Tools > Options... > Qt Quick} and
1549 specify the canvas width and height in the \gui Canvas group.
1551 \section1 Refreshing the Canvas
1553 When you open QML files in \QMLD, the QML elements in the file are drawn on
1554 the canvas. When you edit the element properties in \QMLD, the QML file and
1555 the image on the canvas might get out of sync. For example, when you change
1556 the position of an item within a column or a row, the new position might
1557 not be displayed correctly on the canvas.
1559 To refresh the image on the canvas, press \key R or select the \gui {Reset
1560 View} button on the canvas toolbar.
1566 \contentspage index.html
1567 \previouspage creator-project-managing-sessions.html
1568 \page creator-coding.html
1569 \nextpage creator-editor-using.html
1573 Writing, editing, and navigating in source code are core tasks in
1574 application development. Therefore, the code editor is one of the key
1575 components of Qt Creator. You can use the code editor in the \gui Edit
1578 The following sections describe coding with Qt Creator:
1582 \o \l{Using the Editor} describes how to work in the code editor, use
1583 the editor toolbar, split the view, add bookmarks, and move between
1584 symbol definitions and declarations.
1586 \o \l{Semantic Highlighting} describes highlighting code elements and
1587 blocks, as well as using syntax highlighting also for other types
1588 of files than C++ or QML.
1590 \o \l{Checking Code Syntax} describes how errors are visualized
1591 while you write code.
1593 \o \l{Completing Code} describes how code and code snippets are
1594 completed for elements, properties, an IDs.
1596 \o \l{Indenting Code} describes how to specify indentation either
1597 globally for all files or separately for: text, C++, or QML files.
1599 \o \l{Finding and Replacing} describes the incremental search that
1600 highlights the matching strings in the window while typing and the
1601 advanced search that allows you to search from currently open
1602 projects or files on the file system. In addition, you can search
1603 for symbols when you want to refactor code.
1605 \o \l{Refactoring} describes the features that help you improve the
1606 internal quality or your application, its performance and
1607 extendibility, and code readability and maintainability, as well as
1608 to simplify code structure.
1610 \o \l{Using Qt Quick Toolbars} describes how to use the Qt Quick
1611 Toolbars to edit the properties of QML elements in the code editor.
1613 \o \l{Searching With the Locator} describes how to browse through
1614 projects, files, classes, methods, documentation and file systems.
1616 \o \l{Pasting and Fetching Code Snippets} describes how to cooperate
1617 with other developers by pasting and fetching snippets of code from
1620 \o \l{Using Text Editing Macros} describes how to record and play
1621 text editing macros.
1623 \o \l{Configuring the Editor} describes how to change the text editor
1624 options to suit your specific needs.
1626 \o \l{Using FakeVim Mode} describes how to run the main editor in a
1636 \contentspage index.html
1637 \previouspage creator-coding.html
1638 \page creator-editor-using.html
1639 \nextpage creator-highlighting.html
1642 \title Using the Editor
1644 Qt Creator's code editor is designed to aid you in creating, editing and
1645 navigating code. Qt Creator's code editor is fully equipped with syntax
1646 checking, code completion, context sensitive help and in-line error
1647 indicators while you are typing.
1649 \image qtcreator-edit-mode.png "Edit mode"
1651 \section1 Using the Editor Toolbar
1653 The editor toolbar is located at the top of the editor view. The editor
1654 toolbar is context sensitive and shows items relevant to the file currently
1657 \image qtcreator-editortoolbar-symbols.png
1659 Use the toolbar to navigate between open files and symbols in use.
1660 To browse forward or backward through your location history, click
1661 \inlineimage qtcreator-back.png
1662 and \inlineimage qtcreator-forward.png
1665 To go to any open file, select it from the \gui{Open files} drop-down menu.
1666 Right-click the menu title and select \gui {Copy Full Path to Clipboard} to
1667 copy the path and name of the current file to the clipboard.
1669 To jump to any symbol used in the current file, select it from the
1670 \gui Symbols drop-down menu. By default, the symbols are displayed in the
1671 order in which they appear in the file. Right-click the menu title and select
1672 \gui {Sort Alphabetically} to arrange the symbols in alphabetic order.
1674 \section1 Splitting the Editor View
1676 Split the editor view when you want to work on and view multiple files on
1679 \image qtcreator-spliteditorview.png
1681 You can split the editor view in the following ways:
1683 \o To split the editor view into a top and bottom view, select
1684 \gui Window > \gui Split or press \key{Ctrl+E, 2}.
1686 Split command creates views below the currently active editor view.
1687 \o To split the editor view into adjacent views, select
1688 \gui Window > \gui{Split Side by Side} or press
1691 Side by side split command creates views to the right of the
1692 currently active editor view.
1695 To move between split views, select \gui Window >
1696 \gui{Go to Next Split} or press \key{Ctrl+E, O}.
1698 To remove a split view, place the cursor within the view you want to
1699 remove and select \gui Window > \gui{Remove Current Split} or press
1700 \key{Ctrl+E, 0}. To remove all but the currently selected split view,
1701 select \gui Window > \gui{Remove All Splits} or press \key{Ctrl+E, 1}.
1703 \section1 Using Bookmarks
1705 To insert or delete a bookmark right-click the line number and select
1706 \gui{Toggle Bookmark} or press \key{Ctrl+M}.
1708 \image qtcreator-togglebookmark.png
1710 To go to previous bookmark in the current session, press \key{Ctrl+,}.
1712 To go to next bookmark in the current session, press \key{Ctrl+.}.
1714 \section1 Moving to Symbol Definition or Declaration
1716 You can move directly to the definition or the declaration of a symbol by
1717 holding the \key Ctrl and clicking the symbol.
1719 To enable this moving function, in \gui Tools > \gui{Options...} >
1720 \gui{Text Editor} > \gui Behavior, select \gui{Enable mouse navigation}.
1722 You can also select the symbol and press \key F2, or right-click the symbol
1723 and select \gui {Follow Symbol Under Cursor} to move to its definition or
1724 declaration. This feature is supported for namespaces, classes, methods,
1725 variables, include statements, and macros.
1727 To switch between the definition and declaration of a symbol, press
1728 \key {Shift+F2} or right-click the symbol and select \gui {Switch Between
1729 Method Declaration/Definition}.
1731 \section1 Using Update Code Model
1733 To refresh the internal information in Qt Creator pertaining to your code,
1734 select \gui{Tools} > \gui{C++} > \gui{Update Code Model}.
1736 \note In Qt Creator indexing updates the code automatically. Use
1737 \gui{Update Code Model} only as an emergency command.
1742 \contentspage index.html
1743 \previouspage creator-editor-using.html
1744 \page creator-highlighting.html
1745 \nextpage creator-checking-code-syntax.html
1747 \title Semantic Highlighting
1749 Qt Creator understands the C++ and QML languages as code, not as plain text.
1750 It reads the source code, analyzes it, and highlights it based on the
1751 semantic checks that it does for the following code elements:
1755 \o Types (such as classes, structs, and type definitions)
1765 To specify the color scheme to use for semantic highlighting, select
1766 \gui {Tools > Options... > Text Editor > Fonts & Color}.
1768 Qt Creator supports syntax highlighting also for other types of files than
1771 \section1 Generic Highlighting
1773 Generic highlighting is based on highlight definition files that are
1775 \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}{Kate Editor}.
1776 You can download highlight definition files for use with Qt Creator.
1778 If you have a Unix installation that comes with the Kate Editor, you might
1779 already have the definition files installed. Typically, the files are
1780 located in a read-only directory, and therefore, you cannot manage them. Qt
1781 Creator can try to locate them and use them as fallback files, when the
1782 primary location does not contain the definition for the current file type.
1783 You can also specify the directory that contains preinstalled highlight
1784 definition files as the primary location.
1786 When you open a file for editing and the editor cannot find the highlight
1787 definition for it, an alert appears. You can turn off the alerts. You can
1788 also specify patterns for ignoring files. The editor will not alert you if
1789 highlight definitions for the ignored files are not found.
1791 To download highlight definition files:
1795 \o Select \gui {Tools > Options... > Text Editor > Generic
1798 \image qtcreator-generic-highlighter.png "Generic Highlighter options"
1800 \o In the \gui Location field, specify the path to the primary
1801 location for highlight definition files.
1803 \o Click \gui {Download Definitions} to open a list of highlight
1804 definition files available for download.
1806 \image qtcreator-manage-definitions.png "Download Definitions dialog"
1808 \o Select highlight definition files in the list and click
1809 \gui {Download Selected Definitions}.
1811 \o Select the \gui {Use fallback location} check box to specify the
1812 secondary location where the editor will look for highlight
1815 \o Click \gui Autodetect to allow Qt Creator to look for highlight
1816 definition files on your system, or click \gui Browse to locate
1817 them in the file system yourself.
1819 \o In the \gui {Ignored file patterns} field, specify file patterns.
1820 You will not receive alerts if the highlight definitions for the
1821 specified files are not found.
1823 \o Click \gui OK to save your changes.
1827 \section1 Highlighting and Folding Blocks
1829 Use block highlighting to visually separate parts of the code that belong
1830 together. For example, when you place the cursor within the braces,
1831 the code enclosed in braces is highlighted.
1833 \image qtcreator-blockhighlighting.png
1835 To enable block highlighting, select \gui Tools > \gui{Options...} >
1836 \gui{Text Editor} > \gui Display > \gui{Highlight blocks}.
1838 Use the folding markers to collapse and expand blocks of code within
1839 braces. Click the folding marker to collapse or expand a block. In the
1840 figure above, the folding markers are located between the line number and
1843 To show the folding markers, select \gui Tools > \gui{Options...} >
1844 \gui{Text Editor} > \gui Display > \gui{Display folding markers}. This
1845 option is enabled by default.
1847 When the cursor is on a brace, the matching brace is animated
1848 by default. To turn off the animation and just highlight the block and
1849 the braces, select \gui {Tools > Options... > Text Editor > Display} and
1850 deselect \gui {Animate matching parentheses}.
1856 \contentspage index.html
1857 \previouspage creator-highlighting.html
1858 \page creator-checking-code-syntax.html
1859 \nextpage creator-completing-code.html
1861 \title Checking Code Syntax
1863 As you write code Qt Creator checks code syntax. When Qt Creator spots a
1864 syntax error in your code it underlines it and shows error details when you
1865 move the mouse pointer over the error.
1867 \o Syntax errors are underlined in red.
1869 In the following figure, a semicolon is missing at the end of the
1872 \image qtcreator-syntaxerror.png
1873 \o Semantic errors and warnings are underlined in olive.
1875 In the following figure, the type is unknown.
1877 \image qtcreator-semanticerror.png
1884 \contentspage index.html
1885 \previouspage creator-checking-code-syntax.html
1886 \page creator-completing-code.html
1887 \nextpage creator-indenting-code.html
1889 \title Completing Code
1891 As you write code, Qt Creator suggests properties, IDs, and code
1892 snippets to complete the code. It provides a list of context-sensitive
1893 suggestions to the statement currently under your cursor. Press \key Tab
1894 or \key Enter to accept the selected suggestion and complete the code.
1896 \image qtcreator-codecompletion.png
1898 To open the list of suggestions at any time, press \key{Ctrl+Space}.
1899 If only one option is available, Qt Creator inserts it automatically.
1901 When completion is invoked manually, Qt Creator completes the common prefix
1902 of the list of suggestions. This is especially useful for classes with
1903 several similarly named members. To disable this functionality, uncheck
1904 \gui{Autocomplete common prefix} in the code completion preferences.
1905 Select \gui Tools > \gui{Options...} > \gui{Text Editor} > \gui Completion.
1907 By default, code completion considers only the first letter case-sensitive.
1908 To apply full or no case-sensitivity, select the option in the
1909 \gui {Case-sensitivity} field.
1911 \section2 Summary of Available Types
1913 The following table lists available types for code completion and icon
1921 \i \inlineimage completion/class.png
1924 \i \inlineimage completion/enum.png
1927 \i \inlineimage completion/enumerator.png
1928 \i An enumerator (value of an enum)
1930 \i \inlineimage completion/func.png
1933 \i \inlineimage completion/func_priv.png
1934 \i A private function
1936 \i \inlineimage completion/func_prot.png
1937 \i A protected function
1939 \i \inlineimage completion/var.png
1942 \i \inlineimage completion/var_priv.png
1943 \i A private variable
1945 \i \inlineimage completion/var_prot.png
1946 \i A protected variable
1948 \i \inlineimage completion/signal.png
1951 \i \inlineimage completion/slot.png
1954 \i \inlineimage completion/slot_priv.png
1957 \i \inlineimage completion/slot_prot.png
1960 \i \inlineimage completion/keyword.png
1963 \i \inlineimage completion/snippet.png
1964 \i A C++ code snippet
1966 \i \inlineimage completion/element.png
1969 \i \inlineimage completion/qmlsnippet.png
1970 \i A QML code snippet
1972 \i \inlineimage completion/macro.png
1975 \i \inlineimage completion/namespace.png
1979 \section2 Completing Code Snippets
1981 Code snippets can consist of multiple
1982 variables that you specify values for. Select an item in the list and press
1983 \key Tab or \key Enter to complete the code. Press \key Tab to
1984 move between the variables and specify values for them. When you specify a
1985 value for a variable, all instances of the variable within the snippet
1988 \image qmldesigner-code-completion.png "Completing QML code"
1990 \section2 Editing Code Snippets
1992 Code snippets specify C++ or QML code constructs. You can add, modify,
1993 and remove snippets in the snippet editor. To open the editor, select
1994 \gui {Tools > Options... > Text Editor > Snippets}.
1996 \image qtcreator-edit-code-snippets.png "Snippet options"
1998 Qt Creator provides you with built-in snippets in the following categories:
2002 \o Text snippets, which can contain any text string. For example, code
2005 \o C++ code snippets, which specify C++ code constructs
2007 \o QML code snippets, which specify QML code constructs
2011 \section3 Adding and Editing Snippets
2013 Select a snippet in the list to edit it in the snippet editor. To add a new
2014 snippet, select \gui Add. Specify a trigger and, if the trigger is already
2015 in use, an optional variant, which appear in the list of suggestions when
2016 you write code. Also specify a text string or C++ or QML code construct in
2017 the snippet editor, depending on the snippet category.
2019 The snippet editor provides you with:
2027 \o Parentheses matching
2029 \o Basic code completion
2033 Specify the variables for the snippets in the following format:
2037 Use unique variable names within a snippet, because all instances of a
2038 variable are renamed when you specify a value for it.
2040 The snippet editor does not check the syntax of the snippets that you edit
2041 or add. However, when you use the snippets, the code editor marks any
2042 errors by underlining them in red.
2044 To discard the changes you made to a built-in snippet, select \gui {Revert
2047 \section3 Removing Snippets
2049 Several similar built-in snippets might be provided for different use
2050 cases. To make the list of suggestions shorter when you write code, remove
2051 the built-in snippets that you do not need. If you need them later, you
2054 To remove snippets, select a snippet in the list, and then select
2055 \gui Remove. To restore the removed snippets, select \gui {Restore Removed
2058 \section3 Resetting Snippets
2060 To remove all added snippets and to restore all removed snippets, select
2063 \note If you now select \gui OK or \gui Apply, you permanently lose all
2070 \contentspage index.html
2071 \previouspage creator-editor-locator.html
2072 \page creator-editor-codepasting.html
2073 \nextpage creator-macros.html
2075 \title Pasting and Fetching Code Snippets
2077 In Qt Creator, you can paste snippets of code to a server or fetch
2078 snippets of code from the server. To paste and fetch snippets of code,
2079 Qt Creator uses the following:
2082 \o \gui{Pastebin.Com}
2083 \o \gui{Pastebin.Ca}
2086 To configure the server, select \gui{Tools} > \gui{Options...} >
2089 To paste a snippet of code onto the server, select \gui{Tools} >
2090 \gui{Code Pasting} > \gui{Paste Snippet...} or press \key{Alt+C,Alt+P}.
2094 To fetch a snippet of code from the server, select \gui{Tools} >
2095 \gui{Code Pasting} > \gui{Fetch Snippet...} or press \key{Alt+C,Alt+F}.
2097 \note To use \gui{Pastebin.Com}, configure the domain
2098 prefix in \gui{Tools} > \gui{Options...} > \gui{Code Pasting} >
2101 For example, you might ask colleagues to review a change that you plan to
2102 submit to a version control system. If you use the Git version control system,
2103 you can create a \e{diff} view by selecting \gui{Tools} > \gui{Git} >
2104 \gui{Diff Repository}. You can then upload its contents to the server by choosing
2105 \gui{Tools} > \gui{Code Pasting} > \gui{Paste Snippet...}. The reviewers can retrieve
2106 the code snippet by selecting \gui{Tools} > \gui{Code Pasting} > \gui{Fetch Snippet...}.
2107 If they have the project currently opened in Qt Creator, they can apply and test
2108 the change by choosing \gui{Tools} > \gui{Git} > \gui{Apply Patch}.
2113 \contentspage index.html
2114 \previouspage creator-editor-codepasting.html
2115 \page creator-macros.html
2116 \nextpage creator-editor-options.html
2118 \title Using Text Editing Macros
2120 When you have a file open in the code editor, you can record a keyboard
2121 sequence as a macro. You can then play the macro to repeat the sequence.
2122 You can save the latest macro and assign a keyboard shortcut for running
2123 it or run it from the locator.
2125 To record a text editing macro, select \gui {Tools > Macros > Record Macro}
2126 or press \key {Alt+(}. To stop recording, select \gui {Tools > Macros >
2127 Stop Recording Macro} or press \key {Alt+)}.
2129 To play the last macro, select \gui {Tools > Macros > Play Last Macro} or
2132 To save the last macro, select \gui {Tools > Macros > Save Last Macro}.
2134 To assign a keyboard shortcut to a text editing macro, select \gui {Tools >
2135 Options... > Environment > Keyboard}. For more information, see
2136 \l{Configuring Keyboard Shortcuts}.
2138 You can also use the \c rm locator filter to run a macro. For more
2139 information, see \l{Searching With the Locator}.
2141 To view and remove saved macros, select \gui {Tools > Options... > Text
2147 \contentspage index.html
2148 \previouspage creator-editor-options.html
2149 \page creator-editor-fakevim.html
2150 \nextpage creator-design-mode.html
2152 \title Using FakeVim Mode
2154 In the \gui{FakeVim} mode, you can run the main editor in a manner similar
2155 to the Vim editor. To run the editor in the \gui{FakeVim} mode, select
2156 \gui{Edit} > \gui{Advanced} > \gui{Use Vim-style Editing} or press
2159 In the \gui{FakeVim} mode, most keystrokes in the main editor will be
2160 intercepted and interpreted in a way that resembles Vim. Documentation for
2161 Vim is not included in Qt Creator. For more information on using Vim,
2162 see \l{http://www.vim.org/docs.php}{Documentation} on the Vim web site.
2164 To map commands entered on the \gui{FakeVim} command line to actions of the
2165 Qt Creator core, select \gui{Tools} > \gui{Options...} > \gui{FakeVim} >
2166 \gui{Ex Command Mapping}.
2168 To make changes to the Vim-style settings, select \gui{Tools} >
2169 \gui{Options...} > \gui FakeVim > \gui{General}.
2171 To use a Vim-style color scheme, select \gui {Tools > Options... >
2172 Text Editor > Fonts & Color}. In the \gui {Color Scheme} list, select
2175 To quit the FakeVim mode, click \gui {Quit FakeVim} or press
2182 \contentspage index.html
2183 \previouspage adding-plugins.html
2184 \page creator-editor-external.html
2185 \nextpage creator-maemo-emulator.html
2187 \title Using External Tools
2189 You can use external tools directly from Qt Creator. Qt Linguist, the
2190 default text editor for your system, and the \c sort tool are preconfigured
2191 for use. You can change their default configurations and configure new
2194 \section1 Using Qt Linguist
2196 You can use the Qt Linguist release manager tools, lupdate and lrelease,
2197 directly from Qt Creator. The lupdate tool is used to synchronize source
2198 code and translations. The lrelease tool is used to create run-time
2199 translation files for use by the released application.
2201 To synchronize ts files from a translator with the application code,
2202 select \gui {Tools > External > Text > Linguist > Update Translations
2205 To generate from the ts files qm translation files that can be used by an
2206 application, select \gui {Tools > External > Text > Linguist > Release
2207 Translations (lrelease)}.
2209 By default, the project .pro file is passed to the tools as an argument. To
2210 specify other command line arguments for the tools, select \gui {Tools >
2211 External > Configure}.
2213 For more information about Qt Linguist, see
2214 \l{http://doc.qt.nokia.com/4.7/linguist-manual.html}{Qt Linguist Manual}.
2216 \section1 Using External Text Editors
2218 You can open files for editing in the default text editor for your system:
2219 Notepad on Windows and vi on Linux and Mac OS.
2220 To open the file you are currently viewing in an external editor, select
2221 \gui {Tools > External > Text > Notepad} or \gui vi, depending on your
2224 Qt Creator looks for the editor path in the PATH environment variable
2225 of your operating system.
2227 \section1 Sorting Text Alphabetically
2229 To sort selected text alphabetically, select \gui {Tools > External > Text
2230 > Sort Selection}. The \c sort tool takes the selected text as input and
2231 returns it in alphabetic order. By default, the output replaces the
2232 original selection in the code editor.
2234 To change the default configuration, select \gui {Tools > External >
2237 \section1 Configuring External Tools
2239 You can change the configuration of preconfigured tools and configure
2240 additional tools in Qt Creator \gui Options.
2242 You can use Qt Creator variables in the fields that you can select from
2243 lists of available Qt Creator variables.
2245 \image qtcreator-external-tools.png "External Tools options"
2247 To configure external tools:
2251 \o Select \gui {Tools > External > Configure}.
2253 \o Select \gui {Add > Add Tool}
2254 to add a new tool. You can also select \gui {Add Category} to add a
2257 \o In the \gui Executable field, specify the executable to run. If the
2258 executable is found in your system PATH variable, do not specify
2261 \o In the \gui Arguments field, specify optional arguments for running
2264 \o In the \gui {Working directory} field, specify the path to the
2267 \o In the \gui {Output pane}, select how to handle output from the
2268 tool. You can ignore the output, view it in the \gui {General
2269 Messages} output pane, or replace the selected text with the
2270 output in the code editor.
2272 \o In the \gui {Error output pane}, select how to handle error messages
2275 \o In the \gui Input field, specify text that is passed as standard
2280 The category and tool are added to the \gui {Tools > External} menu.
2282 If you change the configuration of preconfigured tools, you can later
2283 revert the changes by selecting the \gui Revert button.
2285 The tool configurations that you add and modify are stored in XML format in
2286 the user configuration folder. For example,
2287 \c {~/config/Nokia/qtcreator/externaltools}
2288 on Linux and Mac OS and
2289 \c {C:\Users\username\AppData\Roaming\Nokia\qtcreator\externaltools}
2290 in Windows. To share a configuration with other users, copy an XML
2291 configuration file to the folder.
2297 \contentspage index.html
2298 \previouspage creator-macros.html
2299 \page creator-editor-options.html
2300 \nextpage creator-editor-fakevim.html
2302 \title Configuring the Editor
2304 Qt Creator allows you to configure the text editor to suit your specific
2305 needs. To configure the editor, select \gui Tools > \gui{Options...} >
2308 These settings apply to all projects. To specify editor behavior for an
2309 open project, select \gui {Projects > Editor Settings}. For more
2310 information, see \l{Specifying Editor Settings}.
2312 You can also specify indentation settings separately for C++ and QML files
2313 either globally or for the open project. For more information, see
2316 \image qtcreator-font-colors.png "Text editor options"
2318 You can perform the following configuration actions:
2320 \o Set the font preferences and apply color schemes for syntax highlighting in
2321 \gui{Font & Colors}.
2323 \l{Generic Highlighting}{definition files for syntax highlighting}
2324 for other types of files than
2325 C++ or QML in \gui{Generic Highlighter}.
2326 \o Set tabs, indentation, the handling of whitespace, and mouse operations in
2327 \gui Behavior. For more information, see \l{Indenting Code}.
2328 \o Set various display properties, for example,
2329 \l{Highlighting and folding blocks}{highlighting and folding blocks},
2330 text wrapping or \l{Moving to symbol definition or declaration}
2331 {moving to symbol definition or declaration}
2333 \o Add, modify, and remove \l{Editing Code Snippets}{code snippets} in
2335 \o View and remove \l{Using Text Editing Macros}{text editing macros}
2337 \o Configure \l{Completing Code}{code completion} in \gui Completion.
2340 \section2 Configuring Fonts
2342 You can select the font family and size. You can specify a zoom setting in
2343 percentage for viewing the text. You can also zoom in or out by pressing
2344 \key {Ctrl++} or \key {Ctrl +-}, or by pressing \key Ctrl and rolling
2345 the mouse button up or down. To disable the mouse wheel function, select
2346 \gui {Tools > Options... > Text Editor > Behavior} and deselect the
2347 \gui {Enable scroll wheel zooming} check box.
2349 Antialiasing is used by default to make text look smoother and more
2350 readable on the screen. Deselect the \gui Antialias check box to
2351 turn off antialiasing.
2353 \section2 Defining Color Schemes
2355 You can select one of the predefined color schemes for syntax highlighting
2356 or create customized color schemes. The color schemes apply to highlighting
2357 both C++ and QML files and generic files.
2359 To create a color scheme:
2363 \o Select \gui {Tools > Options... > Text Editor > Fonts & Color > Copy}.
2365 \o Enter a name for the color scheme and click \gui OK.
2367 \o In the \gui Foreground field, specify the color of the selected
2370 \o In the \gui Background field, select the background
2371 color for the code element.
2373 The backgound of the \gui Text element determines the background of the
2378 When you copy code from Qt Creator, it is copied in both plain text and HTML
2379 format. The latter makes sure that syntax highlighting is preserved when
2380 pasting to a rich-text editor.
2382 \section2 File Encoding
2384 To define the default file encoding, select the desired encoding in
2385 \gui {Default encoding}. By default, Qt Creator uses the file encoding
2386 used by your system.
2392 \contentspage index.html
2393 \previouspage creator-completing-code.html
2394 \page creator-indenting-code.html
2395 \nextpage creator-editor-finding.html
2397 \title Indenting Code
2399 When you type code, it is indented automatically according to the selected
2400 text editor and code style options. Select a block to indent it when you
2401 press \key Tab. Press \key {Shift+Tab} to decrease the indentation. You
2402 can disable automatic indentation.
2404 When you press \gui Backspace, the indentation is decreased by one level
2405 in leading white space, by default. You can disable this setting.
2407 Continuation lines are aligned with the previous line by using spaces. You
2408 can disable automatic alignment to have them indented to the logical depth.
2409 You can always use spaces for alignment or use spaces or tabs depending on
2410 the other options you selected.
2412 You can specify indentation either globally for all files or separately
2425 You can specify indentation either globally for all files of a particular
2426 type or separately for each project.
2428 \section1 Indenting Text Files
2430 To specify global indentation settings for the text editor, select
2431 \gui {Tools > Options... > Text Editor > Behavior}. You can also use these
2432 settings globally for all editors and files.
2434 \image qtcreator-indentation.png "Text Editor Behavior options"
2436 To specify settings for a particular project, select \gui {Projects >
2439 \section1 Indenting C++ Files
2441 To specify global indentation settings for the C++ editor, select
2442 \gui {Tools > Options... > C++}.
2444 \image qtcreator-options-code-style-cpp.png "C++ Code Style options"
2446 To specify the settings for a particular project, select \gui {Projects >
2447 Code Style Settings}.
2449 You can specify how to:
2453 \o Interpret the \key Tab and \key Backspace key presses.
2455 \o Indent the contents of classes, methods, blocks, and namespaces.
2457 \o Indent braces in classes, namespaces, enums, methods, and blocks.
2459 \o Control switch statements and their contents.
2461 \o Align continuation lines.
2465 You can use the live preview to see how the options change the indentation.
2467 \section1 Indenting QML Files
2469 To specify global settings for the Qt Quick editor, select \gui {Tools >
2470 Options... > Qt Quick}.
2472 \image qtcreator-options-code-style-qml.png "QML Code Style options"
2474 To specify the settings for a particular project, select \gui {Projects >
2475 Code Style Settings}.
2477 You can specify how to interpret the \key Tab and \key Backspace key
2480 \section1 Specifying Tab Settings
2482 You can specify tab settings at the following levels:
2486 \o Global settings for all files
2488 \o Global C++ settings for C++ files
2490 \o Global Qt Quick settings for QML files
2492 \o Project specific settings for all editors of files in the project
2494 \o Project specific settings for C++ files in the project
2496 \o Project specific settings for QML files in the project
2500 By default, the tab-length in code editor is 8 spaces. You can specify the
2501 tab length separately for each project and for
2502 different types of files.
2504 The code editor can also determine whether tabs or spaces are used
2505 on the previous or next line and copy the style.
2507 The \key Tab key can automatically indent text when you press it, or only
2508 when the cursor is located within leading white space.
2510 \section1 Specifying Settings for Content
2512 You can indent public, protected, and private statements and declarations
2513 related to them within classes.
2515 You can also indent statements within methods and blocks and declarations
2518 \image qtcreator-code-style-content.png "Content options"
2520 \section1 Specifying Settings for Braces
2522 You can indent class, namespace, enum and method declarations and code
2525 \image qtcreator-code-style-braces.png "Braces options"
2527 \section1 Specifying Settings for Switch Statements
2529 You can indent case or default statements, or statements or blocks related
2530 to them within switch statements.
2532 \image qtcreator-code-style-switch.png "Switch options"
2534 \section1 Specifying Alignment
2536 To align continuation lines to tokens after assignments, such as = or
2537 +=, select the \gui {Align after assignments} check box. You can specify
2538 additional settings for aligning continuation lines in the \gui General
2541 You can also add spaces to conditional statements, so that they are not
2542 aligned with the following line. Usually, this only affects \c if
2545 \image qtcreator-code-style-alignment.png "Alignment options"
2551 \contentspage index.html
2552 \previouspage creator-indenting-code.html
2553 \page creator-editor-finding.html
2554 \nextpage creator-editor-refactoring.html
2556 \title Finding and Replacing
2558 To search through the currently open file:
2560 \o Press \key Ctrl+F or select \gui Edit > \gui Find/Replace >
2562 \o Enter the text you are looking for.
2564 If the text is found, all occurrences are highlighted as you type.
2565 \o To go to the next occurrence, click \inlineimage qtcreator-next.png
2566 , or press \key F3. To go to the previous occurrence click
2567 \inlineimage qtcreator-previous.png
2568 , or press \key Shift+F3.
2571 You can restrict the search in the \gui Find field by selecting one
2572 or several search criteria:
2574 \o To make your search case sensitive, select
2575 \inlineimage qtcreator-editor-casesensitive.png
2577 \o To search only whole words, select
2578 \inlineimage qtcreator-editor-wholewords.png
2580 \o To search using regular expressions, select
2581 \inlineimage qtcreator-editor-regularexpressions.png
2583 Regular expressions used in Qt Creator are modeled on Perl regular
2584 expressions. For more information on using regular expressions, see
2585 \l {http://doc.qt.nokia.com/4.7/qregexp.html#details}
2586 {Detailed Description} in the QRegExp Class Reference.
2589 \note If you have selected text before selecting \gui Find/Replace, the
2590 search is conducted within the selection.
2592 To replace occurrences of the existing text, enter the new text in the
2593 \gui{Replace with} field.
2595 \o To replace the selected occurrence and move to the next one,
2596 click \inlineimage qtcreator-next.png
2597 or press \key Ctrl+=.
2598 \o To replace the selected occurrence and move to the previous one,
2599 click \inlineimage qtcreator-previous.png
2601 \o To replace all occurrences in the file, click \gui{Replace All}.
2604 \section1 Advanced Search
2606 To search through projects, files on a file system or the currently open
2609 \o Press \key Ctrl+Shift+F or select \gui Edit >
2610 \gui Find/Replace > \gui{Advanced Find} >
2611 \gui{Open Advanced Find...}.
2612 \o Select the scope of your search:
2614 \o \gui{All Projects} searches files matching the defined file
2615 pattern in all currently open projects.
2617 For example, to search for \tt previewer only in \tt .cpp
2618 and \tt .h files, enter in \gui{File pattern}
2621 \image qtcreator-search-allprojects.png
2623 \o \gui{Current Project} searches files matching the defined file
2624 pattern only in the project you are currently editing.
2625 \o \gui{Files on File System} recursively searches files matching
2626 the defined file pattern in the selected directory.
2627 \o \gui{Current File} searches only the current file.
2629 \o Enter the text you are looking for and click \gui Search.
2631 \image qtcreator-searchresults.png
2633 A list of files containing the searched text is displayed in the
2634 \gui{Search Results} pane.
2636 \o To see all occurrences in a file, double-click the file name in
2638 \o To go to an occurrence, double-click it.
2642 \note You can use \gui{Advanced Find} also to search for symbols. For more
2643 information, see \l{Finding Symbols}.
2649 \contentspage index.html
2650 \previouspage creator-editor-finding.html
2651 \page creator-editor-refactoring.html
2652 \nextpage qt-quick-toolbars.html
2656 Code refactoring is the process of changing the code without modifying the
2657 existing functionality of your application. By refactoring your code you
2660 \o Improve internal quality of your application
2661 \o Improve performance and extensibility
2662 \o Improve code readability and maintainability
2663 \o Simplify code structure
2666 \section1 Finding Symbols
2668 To find the use of a specific symbol in your Qt C++ or Qt Quick project:
2670 \o In the editor, place the cursor on the symbol, and select:
2672 \o \gui {Tools > C++ > Find Usages}
2673 \o \gui {Tools > QML > Find Usages}
2674 \o \key Ctrl+Shift+U
2677 Qt Creator looks for the symbol in the following locations:
2679 \o Files listed as a part of the project
2680 \o Files directly used by the project files (for example, generated
2682 \o Header files of used frameworks and libraries
2685 \note You can also select \gui{Edit > Find/Replace > Advanced Find >
2686 C++ Symbols} to search for classes, methods, enums, and declarations
2687 either from files listed as part of the project or from all files that
2688 are used by the code, such as include files.
2690 \image qtcreator-search-cpp-symbols.png
2692 \o The \gui{Search Results} pane opens and shows the location and
2693 number of instances of the symbol in the current project.
2695 \image qtcreator-refactoring-find.png
2698 You can browse the search results in the following ways:
2700 \o To go directly to an instance, double-click the instance in the
2701 \gui{Search Results} pane.
2702 \o To move between instances, click
2703 \inlineimage qtcreator-forward.png
2705 \inlineimage qtcreator-back.png
2706 in the \gui{Search Results} pane.
2707 \o To expand and collapse the list of all instances, click
2708 \inlineimage qtcreator-expand.png
2710 \o To clear the search results, click \inlineimage qtcreator-clear.png
2714 \section1 Renaming Symbols
2716 The functions available for renaming symbols depend on whether you are
2717 writing C++ or QML code. For QML, you can only rename IDs.
2719 To rename a specific symbol in a Qt project:
2721 \o In the editor, place the cursor on the symbol you would like to
2722 change and select \gui Tools > \gui C++ >
2723 \gui{Rename Symbol Under Cursor} or press \key Ctrl+Shift+R.
2725 The \gui{Search Results} pane opens and shows the location and
2726 number of instances of the symbol in the current project.
2728 \image qtcreator-refactoring-replace.png
2729 \o To replace all selected instances, enter the name of the new symbol
2730 in the \gui{Replace with} text box and click \gui Replace.
2732 To omit an instance, uncheck the check-box next to the instance.
2734 \note This action replaces all selected instances of the symbol in
2735 all files listed in the \gui{Search Results} pane. You cannot
2739 \note Renaming local symbols does not open the \gui{Search Results} pane.
2740 The instances of the symbol are highlighted in code and you can edit the
2741 symbol. All instances of the local symbol are changed as you type.
2743 To rename an ID in a Qt Quick project:
2747 \o Right-click an ID in the QML code and select
2750 \o In the \gui {Rename id} field, enter the new ID.
2754 \section1 Applying Refactoring Actions
2756 Qt Creator allows you to quickly and conveniently apply actions to refactor
2757 your code by selecting them in a context menu. The actions available depend on
2758 the position of the cursor in the code editor and on whether you are writing
2761 To apply refactoring actions to C++ code, right-click an operand, conditional
2762 statement, string, or name to open a context menu. In QML code, click an element
2765 In the context menu, select \gui {Refactoring} and then select a refactoring action.
2767 You can also press \gui {Alt+Enter} to open a context menu that contains refactoring
2768 actions available in the current cursor position.
2770 \section2 Refactoring C++ Code
2772 You can apply the following types of refactoring actions to C++ code:
2776 \o Change binary operands
2778 \o Simplify if and while conditions (for example, move declarations out of
2781 \o Modify strings (for example, set the encoding for a string to Latin-1, mark
2782 strings translatable, and convert symbol names to camel case)
2784 \o Create variable declarations
2786 \o Create method declarations and definitions
2790 The following table summarizes the refactoring actions for C++ code. The
2791 action is available when the cursor is in the position described in the
2796 \i Refactoring Action
2801 \i Adds curly braces to an if statement that does not contain a
2802 compound statement. For example, rewrites
2818 \i Move Declaration out of Condition
2819 \i Moves a declaration out of an if or while condition to simplify the
2820 condition. For example, rewrites
2823 if (Type name = foo()) {...}
2832 \i Name of the introduced variable
2834 \i Rewrite Condition Using ||
2835 \i Rewrites the expression according to De Morgan's laws. For example,
2848 \i Rewrite Using \e operator
2849 \i Rewrites an expression negating it and using the inverse operator. For
2888 \i Split Declaration
2889 \i Splits a simple declaration into several declarations. For example,
2901 \i Type name or variable name
2903 \i Split if Statement
2904 \i Splits an if statement into several statements. For example, rewrites:
2906 if (something && something_else) {
2914 if (something_else) {
2922 if (something || something_else)
2931 else if (something_else)
2938 \i Rewrites an expression in the inverse order using the inverse operator.
2939 For example, rewrites:
2948 \i <= < > >= == != && ||
2950 \i Convert to Decimal
2951 \i Converts an integer literal to decimal representation
2954 \i Convert to Hexadecimal
2955 \i Converts an integer literal to hexadecimal representation
2959 \i Converts an integer literal to octal representation
2962 \i Convert to Objective-C String Literal
2963 \i Converts a string literal to an Objective-C string literal
2964 if the file type is Objective-C(++). For example, rewrites the following strings
2968 QLatin1String("abcd")
2969 QLatin1Literal("abcd")
2979 \i Enclose in QLatin1Char(...)
2980 \i Sets the encoding for a character to Latin-1, unless the character is
2981 already enclosed in QLatin1Char, QT_TRANSLATE_NOOP, tr, trUtf8,
2982 QLatin1Literal, or QLatin1String. For example, rewrites
2995 \i Enclose in QLatin1String(...)
2996 \i Sets the encoding for a string to Latin-1, unless the string is
2997 already enclosed in QLatin1Char, QT_TRANSLATE_NOOP, tr, trUtf8,
2998 QLatin1Literal, or QLatin1String. For example, rewrites
3006 QLatin1String("abcd")
3012 \i Mark as Translatable
3013 \i Marks a string translatable. For example, rewrites \c "abcd" with
3014 one of the following options, depending on which of them is available:
3018 QCoreApplication::translate("CONTEXT", "abcd")
3019 QT_TRANSLATE_NOOP("GLOBAL", "abcd")
3025 \i #include Header File
3026 \i Adds the matching #include statement for a forward-declared class or struct
3027 \i Forward-declared class or struct
3029 \i Add Definition in 'filename'
3030 \i Inserts a definition stub for a member function declaration in the
3034 \i Add 'Function' Declaration
3035 \i Inserts the member function declaration that matches the member function
3036 definition into the class declaration. The function can be public,
3037 protected, private, public slot, protected slot, or private slot.
3040 \i Add Local Declaration
3042 Adds the type of an assignee, if the type of the right-hand side of the assignment
3043 is known. For example, rewrites
3055 where Type is the return type of \c {foo()}
3060 \i Convert to Camel Case...
3061 \i Converts a symbol name to camel case, where elements of the name are joined
3062 without delimiter characters and the initial character of each element is
3063 capitalized. For example, rewrites \c an_example_symbol
3064 as \c anExampleSymbol and \c AN_EXAMPLE_SYMBOL as \c AnExampleSymbol
3067 \i Complete Switch Statement
3068 \i Adds all possible cases to a switch statement of the type \c enum
3071 \i Generate Missing Q_PROPERTY Members...
3072 \i Adds missing members to a Q_PROPERTY:
3075 \o \c write method, if there is a WRITE
3076 \o \c {on...Changed} signal, if there is a NOTIFY
3077 \o data member with the name \c {m_<propertyName>}
3082 \section2 Refactoring QML Code
3084 You can apply the following types of refactoring actions to QML code:
3090 \o Split initializers
3092 \o Move a QML element into a separate file to reuse it in other
3097 The following table summarizes the refactoring actions for QML code. The
3098 action is available when the cursor is in the position described in the
3103 \i Refactoring Action
3108 \i Move Component into 'filename.qml'
3109 \i Moves a QML element into a separate file
3113 \i Renames all instances of an element ID in the currently open file
3116 \i Split Initializer
3117 \i Reformats a one-line element into a multi-line element. For example,
3121 Item { x: 10; y: 20; width: 10 }
3139 \contentspage index.html
3140 \previouspage creator-qml-application.html
3141 \page creator-project-managing.html
3142 \nextpage creator-project-creating.html
3144 \title Managing Projects
3146 To set up a project, you first have to decide what kind of an
3147 application you want to develop: whether you want a user interface
3148 based on Qt Quick, Qt widgets, or HTML5. For a Qt Quick or HTML5 project,
3150 choose the language to implement the application logic: C++ or JavaScript.
3151 You can also create other kinds of projects, such as Qt console
3152 applications, shared or static C++ libraries, or subprojects.
3154 You can use wizards to create and import projects. The wizards prompt you
3155 to enter the settings needed for that particular type of project and create
3156 the necessary files for you. You can add your own custom wizards to
3157 standardize the way subprojects and classes are added to a project.
3159 The wizards set up projects to use the Qt build tool, qmake. It is a
3160 cross-platform system for build automation that helps simplify the build
3161 process for development projects across different platforms. qmake
3162 automates the generation of build configurations so that only a few lines
3163 of information are needed to create each configuration. For more
3164 information about qmake, see the
3165 \l{http://qt.nokia.com/doc/4.7/qmake-manual.html}{qmake Manual}.
3167 You can modify the build and run settings for qmake projects in the
3170 Alternatively, you can use the CMake build automation system and set up the
3171 projects manually. In addition, you can import generic projects that do not
3172 use qmake or CMake. This allows you to use Qt Creator as a code editor. For
3173 generic projects, Qt Creator ignores your build system.
3175 To develop applications for Symbian devices, you use
3176 qmake and the local Symbian compiler (on Windows) or qmake and a compilation
3177 service at Nokia Developer (on Linux and Mac OS) to build the applications for
3178 the Symbian devices target. The interface to the compilation service, Remote
3179 Compiler, is installed as a part of the \QSDK. For more information, see
3180 \l{Building with Remote Compiler}.
3182 You can install Maemo, MeeGo Harmattan, and Symbian targets as parts of
3183 the \QSDK. The build and run settings for the selected targets are set up
3184 automatically. However, you need to install and
3185 configure some additional software on the devices to be able to connect to
3186 them from the development PC.
3188 You can use sessions to store personal data, such as bookmarks and
3189 breakpoints that are usually not of interest to other developers working on
3190 the same projects. Sessions allow you to quickly switch between projects
3191 when you work on several projects.
3193 The following sections describe how to manage projects:
3196 \o \l{Creating a Project}
3197 \o \l{Opening a Project}
3198 \o \l{Adding Libraries to Projects}
3199 \o \l{Connecting Maemo and MeeGo Harmattan Devices}
3200 \o \l{Connecting Symbian Devices}
3201 \o \l{Managing Sessions}
3204 For advanced options, see the following topics:
3207 \o \l{Adding New Custom Wizards}
3208 \o \l{Setting Up a CMake Project}
3209 \o \l{Setting Up a Generic Project}
3216 \contentspage index.html
3217 \previouspage creator-project-managing.html
3218 \page creator-project-creating.html
3219 \nextpage creator-project-opening.html
3221 \title Creating a Project
3223 \image qtcreator-new-project.png
3225 You can use wizards to create following types of projects:
3231 Use QML elements or Qt Quick Components to define the user interface and,
3232 optionally, C++ or JavaScript to define the application logic.
3236 \o Qt Widget Project
3238 Use \QD forms to define a Qt widget based
3239 user interface and C++ to define the application logic
3245 \o HTML5 based applications
3247 \o Qt console applications
3249 \o Shared or static C++ libraries
3253 \o Qt Custom Designer Widgets
3259 \o Project from Version Control
3261 Import a project from a supported version control system. For more
3262 information on how version control systems are integrated in
3263 Qt Creator, see \l{Using Version Control Systems}.
3267 To create a new project, select \gui File > \gui{New File or Project} and
3268 select the type of your
3270 The contents of the wizard dialogs depend on the project type and
3271 the build targets that you select in the \gui {Target Setup} dialog.
3272 Follow the instructions of the wizard.
3274 For examples of creating different types of projects, see
3275 \l{Getting Started}.
3277 For more information about creating Qt Quick projects, see
3278 \l {Creating Qt Quick Projects}.
3280 To change the location of the project directory, and to specify settings
3281 for building and running projects, select \gui{Tools} > \gui{Options...} >
3282 \gui{Projects} > \gui{General}.
3284 To specify build and run settings for different target platforms, select
3287 \section1 Adding Files to Projects
3289 You can use wizards also to add individual files to your projects.
3290 You can create the following types of files:
3294 \o Qt resource files, which allow you to store binary files in the
3295 application executable
3297 \o \QD forms and \QD form classes, which specify parts of user
3298 interfaces in Qt widget based projects
3300 \o QML files, which specify elements in Qt Quick projects
3302 \o GLSL files that define fragment and vertex shaders in both Qt Quick
3303 projects and Qt widget based projects
3305 \o C++ class, source, or header files that you can use to write the
3306 application logic in both Qt Quick projects and Qt widget based
3309 \o JavaScript files that you can use to write the application logic in
3316 \section2 Creating C++ Classes
3318 The \gui {C++ Class Wizard} allows you to create a C++ header and source file for
3319 a new class that you can add to a C++ project. Specify the class name, base
3320 class, and header and source files for the class.
3322 The wizard supports namespaces. To use a namespace, enter a qualified
3323 class name in the \gui {Class name} field. For example:
3324 MyNamespace::MySubNamespace::MyClass.
3326 \image qtcreator-cpp-class-wizard.png "Enter Class Name dialog"
3328 The names of the header and source file are based on the class name. To change the
3329 default suffix of a file, click \gui Configure.
3331 You can create your own project and class wizards. For more information,
3332 see \l{Adding New Custom Wizards}.
3334 \section2 Creating OpenGL Fragment and Vertex Shaders
3336 Qt provides support for integration with OpenGL implementations on all
3337 platforms, which allows you to display hardware accelerated 3D graphics
3338 alongside a more conventional user interface. For more information, see
3339 \l{http://doc.qt.nokia.com/4.7/qtopengl.html}{QtOpenGL Module}.
3341 You can use the QGLShader class to compile OpenGL shaders written in the
3342 OpenGL Shading Language (GLSL) and in the OpenGL/ES Shading Language
3343 (GLSL/ES). QGLShader and QGLShaderProgram shelter you from the details of
3344 compiling and linking vertex and fragment shaders.
3346 You can use Qt Creator code editor to write fragment and vertex shaders
3347 in GLSL or GLSL/ES. The code editor provides syntax highlighting and code
3348 completion for the files.
3350 \image qtcreator-new-opengl-file.png "New OpenGL file wizard"
3352 \section2 Displaying Additional File Types in Projects Pane
3354 Qt Creator determines whether to display files from the project folder
3355 in the \gui Projects pane depending on the file type (.pro, .pri, .cpp,
3356 .h, .ui, .qrc, and so on). To display other types of files, edit the
3357 project file. Add filenames as values of the \c {OTHER_FILES} variable.
3358 You can also use wildcards.
3360 For example, the following code specifies that text files are displayed
3361 in the \gui Projects pane:
3365 OTHER_FILES += *.txt
3369 This also makes the files available in the \gui Locator.
3371 \section1 Adding Subprojects to Projects
3373 When you create a new project, you can add it to another project as a subproject
3374 in the \gui{Project Management} dialog. However, the root project must
3375 specify that qmake uses the \c subdirs template to build the project.
3377 To create a root project, select \gui {File > New File or Project... >
3378 Other Project > Subdirs Project > Choose}.
3380 On the \gui Summary page, select \gui {Finish & Add Subproject} to create
3381 the root project and to add another project, such as a C++ library.
3383 The wizard creates a project file (.pro) that defines a \c subdirs template
3384 and the subproject that you add as a value of the
3385 \l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#subdirs}{SUBDIRS variable}.
3386 It also adds all the necessary files for the subproject.
3388 To add more subprojects, right-click the project name in the \gui Projects
3389 pane, and select \gui {New Subproject} in the context menu.
3391 To remove subprojects, right-click the project name in the \gui Projects
3392 pane, and select \gui {Remove Subproject} in the context menu.
3394 To specify dependencies, use the \gui{Add Library} wizard. For more information,
3395 see \l{Adding Libraries to Projects}.
3401 \contentspage index.html
3402 \previouspage creator-project-creating.html
3403 \page creator-project-opening.html
3404 \nextpage creator-project-qmake-libraries.html
3406 \title Opening a Project
3408 Qt Creator stores information that it needs to build projects in a .user file.
3409 If Qt Creator cannot find the file when you open an existing project, it prompts you
3410 to enter the information. If you created the project by using another Qt Creator
3411 instance, Qt Creator asks whether you want to use the old settings. The settings
3412 are specific to the development environment, and should not be copied from one
3413 environment to another. Therefore, we recommend that you click \gui No and enter
3414 the information again in the \gui {Project Setup} dialog.
3416 The \gui {Project Setup} dialog displays a list of development environments for
3417 target platforms (such as desktop, Maemo5 devices, and Symbian devices) that are
3418 installed on the development PC. Select the Qt versions that you want to use to build
3419 the project for each target.
3421 \image qtcreator-open-project-targets.png "Target Setup dialog"
3423 If Qt Creator cannot find an existing build for a particular development
3424 environment (Qt version) and target, it starts out from a clean slate, and
3425 creates a new build in the specified directory. Qt Creator suggests a name
3426 and location for the directory that you can change.
3428 By default, Qt Creator does a \l{glossary-shadow-build}{shadow build} and also
3429 creates the directory. However, shadow building is not supported for the Symbian
3430 Devices, Maemo5, or Harmattan target on Windows.
3432 If you have built the project before, Qt Creator can use the existing build
3433 configuration to make the exact same build as found in the directory available to
3436 If you know you have a build, but it is not listed, click \gui {Add Build}
3437 to locate it. Select a directory, and Qt Creator scans it (including
3438 subdirectories) for additional builds of the project. Qt Creator adds the found
3439 builds to the target list.
3441 You can edit the build configuration later. For more information, see
3442 \l{Editing Build Configurations}.
3448 \o Select \gui File > \gui{Open File or Project} and select the project
3451 \o In the \gui {Project Setup} dialog, select the Qt versions to use as
3452 build targets for your project, and click \gui{Finish}.
3454 \note If you have only one development environment installed, this dialog
3459 Qt Creator parses all the source files in the project and performs a semantic
3460 analysis to build up the information that it needs for functions such as
3461 navigation and finding usages. A progress bar is displayed during parsing.
3467 \contentspage index.html
3468 \previouspage creator-os-supported-platforms.html
3469 \page creator-project-wizards.html
3470 \nextpage creator-project-cmake.html
3472 \title Adding New Custom Wizards
3474 If you have a team working on a large application or several applications,
3475 you might want to standardize the way the team members create projects
3478 You can copy the wizard templates in the template folders
3479 to create your own project and class wizards. They are displayed in the
3480 \gui New dialog that opens when you choose \gui {File > New File or Project}.
3482 In a project wizard, you can specify the files needed in a project.
3483 You can add wizard pages to allow developers to specify settings for the
3486 In a class wizard, you can allow developers to specify the class name, base
3487 class, and header and source files for the class.
3489 To see how this works, rename wizard_sample.xml as wizard.xml in the
3490 \c {\share\qtcreator\templates\wizards\listmodel\helloworld} and
3491 \c {\share\qtcreator\templates\wizards\listmodel\listmodels} folders. After
3492 you restart Qt Creator, the \gui {Custom Classes}
3493 and \gui {Custom Projects} categories appear in the \gui New dialog.
3495 \image qtcreator-custom-project-wizards.png "The New dialog with custom projects and classes"
3497 \section1 Overview of Custom Wizards
3499 A custom wizard defines the user interface of a wizard page. The values the user enters
3500 in the wizard are assigned field names. Field name and value pairs are then passed to
3501 the file creation process. File creation can happen in the following ways:
3505 \o Template-based, where source files that contain placeholders for
3506 the field names are provided. During processing, the placeholders are replaced
3507 by the values from the wizard page. Optionally, modifier
3508 characters are applied. For more information, see \l{Processing Template Files}.
3510 \o Generator script, where a script is called to create the files.
3512 \note This option mainly exists to accommodate existing generator scripts or
3513 cases where complicated algorithmic logic is required when generating files. Writing
3514 cross-platform scripts is inherently difficult, and therefore, it is not recommended
3515 for new wizards. For more information, see \l{Using Generator Scripts}.
3519 Custom wizards are located in subdirectories of the following directories:
3523 \o \c{share/qtcreator/templates/wizards}
3525 \o the local user's configuration folder,
3526 \c{$HOME/.config/Nokia/qtcreator/templates/wizards}
3528 \o \c{%APPDATA%\Nokia\qtcreator\templates\wizards}
3532 They contain an XML configuration file called wizard.xml, the
3533 template source files, and optionally, the generator script.
3535 \section1 Creating Project Wizards
3537 To create a project wizard:
3541 \o Make a copy of the \c {share/qtcreator/templates/wizards/helloworld} or
3542 \c {share/qtcreator/templates/wizards/listmodel} folder.
3544 \o Modify the wizard_example.xml file.
3546 \o The following code determines the type of the wizard and its place
3547 in the \gui New dialog:
3551 <wizard version="1" kind="project"
3552 class="qt4project" firstpage="10"
3553 id="A.HelloWorld" category="B.CustomProjects">
3559 \o \c version is the version of the file contents. Do not modify this value.
3561 \o \c kind specifies the type of the wizard: \c project or \c class.
3563 \o \c class specifies the type of the project. Currently the only available
3564 type is \c qt4project, which specifies a Qt console project.
3566 \o \c firstpage specifies the place of the new page in the standard project
3567 wizard. The value 10 ensures that the custom page appears after the standard
3568 pages, as the last page of the wizard.
3570 \o \c id is the unique identifier for your wizard. The letter specifies the
3571 position of the wizard within the \c category. The HelloWorld wizard appears
3572 as the first wizard in the second category in the \gui New dialog.
3574 \o \c category is the category in which to place the wizard in the list.
3575 The letter specifies the position of the category in the list in the \gui New
3580 \o The following code specifies the icon and text that appear in the \gui New
3585 <icon>console.png</icon>
3586 <description>Creates a hello-world-project with custom message.</description>
3587 <description xml:lang="de">Erzeugt ein Hello-Welt-Projekt mit einer Nachricht.</description>
3588 <displayname>Hello World</displayname>;
3589 <displayname xml:lang="de">Hallo Welt</displayname>;
3590 <displaycategory>Custom Projects</displaycategory>
3591 <displaycategory xml:lang="de">Benutzerdefinierte Projekte</displaycategory>
3598 \o \c icon appears next to the \c displayName.
3600 \o \c description appears at the bottom of the \gui New dialog when you
3601 select the display name.
3603 \o \c displayName appears in the \gui New dialog, under the
3606 You can add translations as values for the text elements. Specify the target
3607 language as an attribute for the element. Use locale names (QLocale).
3608 For example, \c {xml:lang="de"}.
3612 \o Files to be added to the project:
3615 \o Template-based: The following code specifies the files to add to the project:
3618 <file source="main.cpp" openeditor="true" />
3619 <file source="project.pro" target="%ProjectName%.pro" openproject="true" />
3620 <file source="icon.png" target="%ProjectName%.png" binary="true" />
3624 \o \c source specifies the file to copy to the project. The files must be
3625 located in the wizard folder.
3627 \o \c openeditor indicates that the file is to be opened in an editor after
3628 the wizard has finished.
3630 \o \c binary indicates that the file is a binary file (for example, an
3631 image file). It is to be copied to the target folder as is. Placeholders
3632 are not replaced with values.
3634 \o \c target specifies the new filename for the file. The \c {%ProjectName%}
3635 variable is replaced with the string that users specify in the \gui Name
3636 field on the first page of the wizard.
3638 \o \c openproject indicates that the file is a project file which is to be opened
3639 after the wizard has finished.
3643 See also \l{Processing Template Files}.
3645 \o Generator-script: The following code specifies that the script \c generate.pl is to be used
3646 to create the files:
3648 <generatorscript binary="generate.pl">
3649 <argument value="--class-name=%ClassName%"/>
3650 <argument value="--project-name=%ProjectName%"/>
3651 <argument value="--header-suffix=%CppHeaderSuffix%" omit-empty="true"/>
3652 <argument value="--source-suffix=%CppSourceSuffix%" omit-empty="true"/>
3653 <argument value="--description=%Description%" omit-empty="true" write-file="true"/>
3656 In each argument, the field placeholders are replaced by the field
3657 values. There are additional boolean attributes which give fine-grained control:
3660 \o \c omit-empty specifies that complete argument is to be omitted when all
3661 placeholders expand to empty values. In the above example,
3662 the option \c --source-suffix will not be passed to the script if the value is empty.
3664 \o \c write-file indicates that instead of the expanded value,
3665 the value will be written to a temporary file and its file name will be
3666 passed to the script instead. This is useful for multi-line text fields.
3669 See also \l{Using Generator Scripts}.
3672 \o The following code creates a page that specifies settings for the project:
3676 <!-- Create a 2nd wizard page with parameters -->
3677 <fieldpagetitle>Hello World Parameters</fieldpagetitle>
3678 <fieldpagetitle xml:lang="de">Hallo Welt Parameter</fieldpagetitle>
3680 <field mandatory="true" name="MESSAGE">
3681 <fieldcontrol class="QLineEdit" validator='^[^"]+$' defaulttext="Hello world!" />
3682 <fielddescription>Hello world message:</fielddescription>
3683 <fielddescription xml:lang="de">Hallo-Welt-Nachricht:</fielddescription>
3691 \o \c fieldpagetitle specifies the title of the page.
3693 \o \c field specifies whether the field is mandatory (\c true or \c false).
3694 You can use the value of the \c name field as a variable in other files (for
3695 example, \c {%MESSAGE%}.
3697 \o \c fieldcontrol specifies the field. \c class specifies the field type.
3698 You can use interface objects from the QWidget class to create fields. This
3699 example uses QLineEdit to create an input field.
3701 \o \c validator specifies a regular expression to check the characters allowed in
3704 \o \c defaulttext specifies text that appears in the field by default.
3706 \o \c fielddescription specifies the field name that appears on the wizard page.
3712 \section1 Creating Class Wizards
3714 The widget.xml file for a class wizard is very similar to that for a project
3715 wizard. The differences are discussed below.
3717 To create a class wizard:
3721 \o The following code specifies settings for the wizard:
3725 <wizard version="1" kind="class" id="A.ListModel" category="B.CustomClasses">
3727 <description>Creates a QAbstractListModel implementation.</description>
3728 <description xml:lang="de">Erzeugt eine Implementierung von QAbstractListModel.</description>
3730 <displayname>QAbstractListModel implementation</displayname>
3731 <displayname xml:lang="de">Implementierung von QAbstractListModel</displayname>
3733 <displaycategory>Custom Classes</displaycategory>
3734 <displaycategory xml:lang="de">Benutzerdefinierte Klassen</displaycategory>
3738 For more information about the elements and their values, see
3739 \l {Creating Project Wizards}.
3741 \o The following code specifies the files to add to the project:
3746 <file source="listmodel.cpp" target="%ClassName:l%.%CppSourceSuffix%" openeditor="true" />
3747 <file source="listmodel.h" target="%ClassName:l%.%CppHeaderSuffix%" openeditor="true" />
3752 Here, \c target contains the following variables that are used to construct
3757 \o \c {%ClassName:l%} is replaced with the value of the \c ClassName field.
3758 The modifier \c l converts the string to lower case, to observe Qt
3761 \o \c {%CppSourceSuffix%} and \c {%CppHeaderSuffix%} are pre-defined.
3762 For more information, see \l{Pre-defined Standard Variables}.
3768 <!-- Create parameter wizard page -->
3770 <fieldpagetitle>ListModel parameters</fieldpagetitle>
3771 <fieldpagetitle xml:lang="de">Parameter des ListModel</fieldpagetitle>
3773 <field name="ClassName">
3775 <fieldcontrol class="QLineEdit" validator="^[a-zA-Z0-9_]+$" defaulttext="MyListModel" />
3777 <fielddescription>Class name:</fielddescription>
3778 <fielddescription xml:lang="de">Klassenname:</fielddescription>
3780 <field name="Datatype">
3782 <fieldcontrol class="QComboBox" combochoices="QString,int" defaultindex="0" />
3784 <fielddescription>Data type:</fielddescription>
3785 <fielddescription xml:lang="de">Datentyp:</fielddescription>
3791 In addition to QLineEdit, QComboBox is used in the class wizard to create
3792 a field. \c combochoices specifies the options in the combobox and
3793 \c defaultindex specifies that QString is the default value.
3797 \section1 Processing Template Files
3799 When processing a template source file, placeholders specifying the field names
3800 in the format \c{%FIELDNAME%} are replaced by the values entered by the user.
3801 In addition, modifier characters are supported. For example, \c{%FIELDNAME:u%}
3802 specifies that the value is converted to upper case. This enables generating header
3803 guards for C++ header files.
3805 The following modifier characters are supported:
3808 \o \c{l} for lower case.
3809 \o \c{u} for upper case.
3810 \o \c{c} for upper case initial letter ("project" > "Project").
3813 You can use conditions to add sections of the file depending on field values.
3814 Use a syntax that is similar to C++ preprocessing, as demonstrated in
3815 the profile of the \c{helloworld} example:
3819 @if "%SCRIPT%" == "true"
3825 The value of the Boolean (QCheckBox) field labeled \c{SCRIPT} determines
3826 whether the script module is added. The expressions must expand to valid
3827 Javascript expressions after field replacement.
3829 \section1 Pre-defined Standard Variables
3831 In addition to the field values entered by the user, you can use
3832 the following pre-defined standard values:
3836 \o \c {%ProjectName%} is replaced by the name of the project in the case
3839 \o \c {%Path%} is replaced by the path to the target directory.
3840 For classes, this is the directory, where the files
3841 are created. For project wizards, an additional subdirectory
3842 named after the project is created.
3844 \o \c {%TargetPath%} is replaced by the path to the directory where the actual files
3845 are created. For non-project wizards, it is identical to \c %Path%.
3846 For project wizards, it is \c %Path%/%ProjectName%.
3848 \o \c {%CppSourceSuffix%} is replaced by the default source suffix, which
3849 is defined in Qt Creator in \gui {Tools > Options... > C++ > File Naming}.
3850 For example, if users enter \bold MyClass, the filename becomes myclass.cpp
3851 when the project is created.
3853 \o \c {%CppHeaderSuffix%} is replaced by the default header suffix, which
3854 is also defined in \gui {File Naming}.
3858 \section1 Validating User Input
3860 You can specify validation rules for user input. The rules consist of a Boolean
3861 JavaScript expression and an error message. The placeholders in them are
3862 replaced with values before they are evaluated or displayed.
3864 Consider the following rule used in the \l{Creating Class Wizards} example:
3868 <validationrule condition='"%ClassName%" != "QAbstractListModel"'>
3869 <message>%ClassName% cannot be used as class name.</message>
3870 <message xml:lang="de">%ClassName% kann nicht als Klassenname verwendet werden.</message>
3875 It ensures that the class name entered by the user does not match the name of
3876 the base class. If the validation fails, a red label displaying the message appears
3877 at the bottom of the wizard page.
3879 \section1 Using Generator Scripts
3881 The values entered in the wizard page are passed to the script
3882 as command line arguments as defined by the wizard configuration file.
3884 In addition, the script must implement a \c{--dry-run} command line option.
3886 Qt Creator needs to know the file names before the files are created to check
3887 whether files with identical names already exist, for example. Therefore,
3888 script file generation is a two-step process:
3892 \o Determine file names and attributes: The script is called with the command line
3893 \c{--dry-run} option and the field values. It then prints the relative path
3894 names of the files it intends to create, followed by comma-separated attributes
3895 matching those of the \c{<file>} element, for example:
3898 myclass.cpp,openeditor
3899 myclass.h,openeditor
3900 myproject.pro,openproject
3903 \o Create files: The script is called with the parameters only in the working directory.
3904 It then actually creates the files. If directories are needed, the script
3905 should create them, too.
3909 The \c{scriptgeneratedproject} sample wizard illustrates the usage.
3910 A typical script invocation for this example (obtained by running Qt Creator with
3911 \c{--customwizard-verbose}) looks as follows:
3914 generate.pl --class-name=TestClass --project-name=TestProject --header-suffix=h --source-suffix=cpp --description=/tmp/qtcreatorj26629.txt
3917 By default, the scripts are run in the directory corresponding to
3918 \c %TargetPath%. This can be overriden by specifying the
3919 attribute \c workingdirectory on the element \c generatorscript.
3920 For example, if the script creates the project directory by itself,
3921 %Path% can be specified. In that case, \c --dry-run should output
3922 the correct relative paths or absolute paths constructed using the value of
3929 \contentspage index.html
3930 \previouspage creator-build-settings.html
3931 \page creator-project-qmake.html
3932 \nextpage creator-tool-chains.html
3934 \title Adding Qt Versions
3936 Qt Creator allows you to have multiple versions of Qt installed on
3937 your development PC and use different versions to build your projects for
3938 different targets. For example, \QSDK contains special Qt versions for
3939 MeeGo Harmattan, Maemo, and Symbian development.
3941 Qt Creator checks the directories listed in the \c{PATH} environment
3942 variable for the qmake executable. If a qmake executable is found, it is
3943 referred to as \bold{Qt in PATH} and selected as the Qt version to use
3944 in the \gui Projects mode in the \gui {Build Settings}. If Qt Creator
3945 cannot find qmake, the value in the \gui {Qt version} field might be
3946 invalid and you might need to change it.
3948 Qt Creator automatically detects the Qt versions that are registered by
3949 your system or by \QSDK. To view the settings for each Qt version, move the
3950 mouse pointer over it in the list. To add Qt versions, select
3951 \gui {Tools > Options... > Qt4 > Qt Versions}.
3953 Typically, you select the Qt versions for a project when you use project
3954 wizards to create the project. You can add Qt versions for a project in
3955 \gui {Build Settings}.
3957 \section2 Setting Up New Qt Versions
3959 To add a Qt version:
3963 \o Select \gui Tools > \gui Options... > \gui Qt4 > \gui Add.
3965 \image qtcreator-qt4-qtversions-add.png
3967 \o In the \gui{qmake location} field, enter the path to the
3968 directory where the qmake executable is located.
3970 \o In the \gui{Version name} field, edit the name that Qt Creator
3971 suggests for the Qt version.
3973 Qt Creator automatically determines the path to the binaries in
3974 the Qt installation and displays it in the dialog.
3976 \o In the \gui Helpers section, you can build the debugging
3977 helpers that are available for the Qt version. This is
3978 necessary, because the internal data structures of Qt can
3979 change between versions. For more information, see
3980 \l{Using Debugging Helpers}.
3984 \section2 Setting Up Qt for Symbian Versions
3986 If you install Qt for Symbian as a part of \QSDK, it is automatically
3987 detected by Qt Creator. If you install other Symbian SDKs and register them
3988 with devices.exe, Qt Creator automatically detects the Qt version.
3990 If the selected Qt version was built using the SBSv2 build system, that
3991 is available for Symbian OS 9.5 based SDKs, Qt Creator builds your projects
3992 using this build system. The \gui {SBS v2 directory} field is enabled and
3993 you must specify the path to the directory where the SBS executable (for
3994 example, sbs.bat on Windows) is located.
3996 To add a Qt for Symbian version:
4000 \o Select \gui Tools > \gui Options... > \gui Qt4 > \gui{Qt Versions}.
4002 \o Select the Qt for Symbian version you want the Qt Creator to use.
4004 \image qtcreator-qt4-qtversions-win-symbian.png
4006 For more information about how to add tool chains for using the
4007 GCCE and WINSCW compilers, see \l{Adding Tool Chains}.
4009 \o In the \gui {S60 SDK} field, enter the path to the directory where
4010 the Symbian SDK is located.
4012 \o In the \gui {SBS v2 directory} field, enter the path to the
4013 directory where the SBS v2 executable is located.
4021 \contentspage index.html
4022 \previouspage creator-project-qmake.html
4023 \page creator-tool-chains.html
4024 \nextpage creator-run-settings.html
4026 \title Adding Tool Chains
4028 A \e {tool chain} specifies a compiler and a debugger and other necessary
4029 tools for building an application that is targeted for a particular desktop
4030 or mobile platform. Qt Creator automatically detects the tool chains that
4031 are registered by your system or by \QSDK.
4033 You can add tool chains to build applications by using other compilers or
4034 with different versions of the automatically detected compilers:
4038 \o GNU Compiler Collection (GCC) is a cross compiler for Linux and
4041 \o MinGW (Minimalist GNU for Windows) is a native software port of GCC
4042 and GNU Binutils for use in the development of native Microsoft
4043 Windows applications on Windows or as cross compiler. MinGW is
4044 distributed together with Qt Creator and Qt SDK for Windows.
4046 \o GCCE (GNU Compiler Collection for Embedded) is an ARM-based
4047 compiler used in Symbian OS 9 and distributed together with the
4050 \o RVCT is an ARM-bases compiler for building applications for Symbian
4051 devices (requires a license).
4053 \o WINSCW is a compiler for building applications that can be run or
4054 debugged on the Symbian Emulator. It is distributed together with
4059 To build an application using MinGW or GCCE, specify the paths to the
4060 directories where the compiler and debugger are located and select the
4061 application binary interface (ABI) version from the list of available
4064 Qt Creator allows you to select a tool chain that matches the Qt version
4065 in the \gui Projects mode \gui {Build Settins}.
4071 \o Select \gui {Tools > Options... Tool Chains > Add} and select a
4072 compiler in the list.
4074 To clone the selected tool chain, select \gui {Clone}.
4076 \o In the \gui Name column, double-click the name to change it.
4078 \o In the \gui{Compiler path} field, enter the path to the directory
4079 where the compiler is located. For WINSCW, enter the path to the
4080 Carbide C++ installation directory here.
4082 \image qtcreator-toolchains.png
4084 The other settings to specify depend on the tool chain.
4086 \o For RVCT, select the ARM version to use in the \gui {ARM version}
4091 \section2 Troubleshooting MinGW Compilation Errors
4093 If error messages displayed in the \gui {Compile Output} pane contain
4094 paths where slashes are missing (for example, C:QtSDK),
4095 check your PATH variable. At the command line, enter the following commands:
4100 where mingw32-make.exe
4103 If these commands show paths, they have been added to the global PATH variable
4104 during the installation of a tool chain based on Cygwin or MinGW, even though
4105 this is against Windows conventions.
4107 To keep working with the third-party tool chain, create a new shell link
4108 that adds the required paths (as Visual Studio and Qt do). The shell link
4109 must point to cmd.exe, as illustrated by the following example:
4111 \c {C:\Windows\System32\cmd.exe /K C:\path_to\myenv.bat}
4113 where the /K parameter carries out the command specified in the bat file.
4115 Create the myenv.bat file at \e path_to, which should be in a convenient location.
4116 In the file, specify the paths to the tool chains. For example,
4118 \c {set PATH=C:\path1;C:\path2;%PATH%}
4120 where \e path1 and \e path2 are paths to the tool chains.
4122 Finally, remove the paths from the global PATH, reboot the computer, and
4123 run the \c where commands again to verify that the global PATH is now clean.
4125 You can use the shell link to run the tools in the third-party tool chains.
4131 \contentspage index.html
4132 \previouspage creator-project-opening.html
4133 \page creator-project-qmake-libraries.html
4134 \nextpage creator-developing-maemo.html
4136 \title Adding Libraries to Projects
4138 In addition to Qt libraries, you can add other libraries to your projects.
4139 The way the library is added depends on whether it is a system library or
4140 your own library or a 3rd party library located in the build tree of the
4141 current project or in another build tree.
4143 \image qtcreator-add-library-wizard.png "Add Library wizard"
4145 Because system libraries do not typically change and are often found by
4146 default, you do not need to specify the path to the library or to its includes
4149 For your own libraries and 3rd party libraries, you need to specify
4150 the paths. Qt Creator tries to quess the include path for an external library,
4151 but you need to check it and modify it if necessary. Qt Creator automatically
4152 adds the include path for an internal library.
4154 For all libraries, select the target platforms for the application, library,
4157 Specify whether the library is statically or dynamically linked. For a
4158 statically linked internal library, Qt Creator adds dependencies
4159 (PRE_TARGETDEPS) in the project file.
4161 Depending on the development platform, some options might be detected
4162 automatically. For example, on Mac OS, the library type (\gui Library or
4163 \gui Framework) is detected automatically and the option is hidden. However,
4164 if you develop on another platform than Mac OS and want to build your
4165 project for the Mac OS, you must specify the library type.
4167 The default convention on Windows is that the debug and release versions
4168 of a library have the same name,
4169 but are placed in different subdirectories, usually called \e debug and
4170 \e release. If the library path does not contain either of these folders,
4171 you cannot select the option to place the libraries in separate
4174 Alternatively, the letter \e d can be added to the library name for the debug
4175 version. For example, if the release version is called example.lib, the
4176 debug version is called exampled.lib. You can specify that the letter
4177 is added for the debug version and removed for the release version.
4178 If the library name ends in \e d, deselect the \gui {Remove "d" suffix
4179 for release version} option.
4181 Qt Creator supports code completion and syntax highlighting for the added
4182 libraries once your project successfully builds and links to them.
4184 \section1 To Add Libraries
4188 \o In the \gui Projects pane, open the project file (.pro).
4190 \o Right-click in the code editor to open the context menu and select
4191 \gui {Add Library...}.
4193 \o Follow the instructions of the wizard.
4197 For more information about the project file settings, see
4198 \l{http://doc.qt.nokia.com/4.7/qmake-project-files.html#declaring-other-libraries}{Declaring Other Libraries}.
4200 \section1 Example of Adding Internal Libraries
4202 The following example describes how to add a statically linked internal
4203 library to your project.
4207 \o Choose \gui {File > New File or Project... > Other Projects >
4208 C++ Library} to create the library.
4210 The \gui {Introduction and Product Location} dialog opens.
4212 \image qtcreator-add-library-wizard-ex-1.png "Introduction and Product Location dialog"
4214 \o In the \gui Type field, select \gui {Statically Linked Library}.
4216 \o In the \gui Name field, give a name for the library. For example,
4219 \o Follow the instructions of the wizard until you get to the
4220 \gui {Project Management} dialog. In the \gui {Add to project}
4221 list, select a project. For example, \bold myapp.
4223 \o In the \gui Projects pane, open the project file (.pro).
4224 For example, \bold myapp.pro.
4226 \o Right-click in the code editor to open the context menu and select
4227 \gui {Add Library... > Internal Library > Next}.
4229 \o In the \gui Library field, select \bold mylib and click \gui Next.
4231 \o Click \gui Finish to add the following library declaration to the
4235 win32:CONFIG(release, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/release/ -lmylib
4236 else:win32:CONFIG(debug, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/debug/ -lmylib
4237 else:symbian: LIBS += -lmylib
4238 else:unix: LIBS += -L$$OUT_PWD/../../../projects/mylib/ -lmylib
4240 INCLUDEPATH += $$PWD/../../../projects/mylib
4241 DEPENDPATH += $$PWD/../../../projects/mylib
4243 win32:CONFIG(release, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/release/mylib.lib
4244 else:win32:CONFIG(debug, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/debug/mylib.lib
4245 else:unix:!symbian: PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/libmylib.a
4254 \contentspage index.html
4255 \previouspage creator-usability.html
4256 \page creator-building-running.html
4257 \nextpage creator-building-targets.html
4259 \title Building and Running Applications
4261 Qt Creator provides support for building, running, and deploying Qt
4262 applications for desktop environment and mobile devices.
4264 You can set up the following configurations:
4268 \o \e {Build configuration}, which contains everything you need to
4269 compile the sources into binaries.
4271 \o \e {Deploy configuration}, which handles the packaging and copying
4272 of the necessary files to a location you want to run the executable at.
4273 The files can be copied to a location in the file system of the development
4274 PC or a mobile device.
4276 \o \e {Run configuration}, which starts the application in the location
4277 where it was stored by the deploy configuration.
4281 By default, when you select the \gui Run function, Qt Creator builds, deploys,
4282 and runs the project. For more information about how to change the default
4283 behavior, see \l{Customizing the Build Process}.
4285 \section1 Setting Up a Project
4287 When you install the \QSDK, the build and run settings for the tool chains
4288 delivered with the \QSDK are set up automatically.
4290 To view and modify the settings for currently open projects, switch to the
4291 \gui Projects mode by pressing \key Ctrl+5.
4293 \image qtcreator-projectpane.png
4295 You can add a target if the development environment for the target
4296 platform is installed on the
4297 development PC and the Qt version is configured. Click
4298 \inlineimage qtcreator-qt4-addbutton.png "Add Target button"
4299 and select from a list of available
4300 targets. To remove a target, select it and click
4301 \inlineimage qtcreator-target-remove.png "Remove Target button"
4304 You can select the targets and use the \gui Build menu commands to
4305 build, deploy, and run projects.
4307 The project pane consists of the following tabs:
4309 \o \l{Running Applications on Multiple Targets}{Targets}
4310 (If you have installed the development environment for only one target, the \gui Targets
4311 tab is replaced by a \gui Build tab and a \gui Run tab.)
4312 \o \l{Specifying Build Settings}{Build Settings}
4313 \o \l{Specifying Run Settings}{Run Settings}
4314 \o \l{Specifying Editor Settings}{Editor Settings}
4315 \o \l{Specifying Code Style Settings}{Code Style Settings}
4316 \o \l{Specifying Dependencies}{Dependencies}
4319 Use the \gui Build and \gui Run buttons to switch between
4320 the build and run settings for the active project.
4322 If you have multiple projects open in Qt Creator, use the tabs at the
4323 top of the window to navigate between their settings.
4325 \section1 Customizing the Build Process
4327 To specify the relationship between the release, build, and deploy configurations, select
4328 \gui {Tools > Options... > Project}. By default, the \gui {Always build project
4329 before deploying it} and the \gui {Always deploy project before running it}
4330 options are enabled. Therefore, when you select the \gui Run function,
4331 Qt Creator builds, deploys, and runs the project.
4333 \image qtcreator-project-options-deploy.png "Project General Options"
4339 \contentspage index.html
4340 \previouspage creator-building-running.html
4341 \page creator-building-targets.html
4342 \nextpage creator-running-targets.html
4344 \title Building Applications for Multiple Targets
4346 You can build applications for multiple targets. By default, when
4347 you run the application on a target, you also build and deploy it to the
4348 target, first. However, you can also perform each operation separately.
4350 To check that the application code can be compiled and linked for a target,
4351 you can build the project. The build errors and warnings are displayed in
4352 the \gui {Build Issues} output pane. More detailed information is displayed in
4353 the \gui {Compile Output} pane.
4355 To build an application:
4359 \o Select a target for the project.
4361 \image qtcreator-target-selector.png "Target selector"
4363 \o Choose \gui {Build > Build Project} or press \key {Ctrl+B}.
4367 For more information on the options you have, see \l{Specifying Build Settings}.
4369 \section1 Building for Symbian
4371 The tool chain for building applications locally on the development PC for
4372 the \gui {Symbian Device} target is only supported on Windows.
4373 If you develop on Linux or Mac OS, you must use the Remote Compiler
4374 interface to a compilation service at Nokia Developer. For more information,
4375 see \l{Building with Remote Compiler}.
4377 \section2 Troubleshooting Build Issues
4379 If you cannot build the application for a Symbian device, check that:
4383 \o You selected the Symbian Device target to build the application.
4385 \o You selected the correct Qt version to build the application.
4389 \section1 Building for Symbian Emulator
4391 Qt Creator does not create release configurations for the
4392 \gui {Symbian Emulator} target, because Symbian Emulator supports only debug
4399 \contentspage index.html
4400 \previouspage creator-building-targets.html
4401 \page creator-running-targets.html
4402 \nextpage creator-build-settings.html
4404 \title Running Applications on Multiple Targets
4406 By default, running an application also builds it and deploys it to a
4407 location from where it can be run on the desktop, in Qt Simulator, or
4408 on a mobile device that is connected to the development PC.
4410 To run executable files without deploying them first, deselect the \gui {Tools >
4411 Options... > Project > Always deploy project before running it} option.
4412 This allows you to test SIS files that you receive from Ovi Publishing or
4413 Symbian Signed after you have them signed, for example.
4415 For more information on the options you have, see \l{Specifying Run Settings}.
4417 \section1 Running on Desktop
4421 \o Select \gui Desktop as the target.
4423 \image qtcreator-target-selector.png "Target selector"
4425 \o Click the \gui Run button.
4429 \section1 Running on Qt Simulator
4431 You can use the Qt Simulator to test Qt applications that are intended
4432 for mobile devices in an environment similar to that of the device. You
4433 can change the information that the device has about its configuration
4438 \o Select \gui {Qt Simulator} as the target.
4440 \o Click the \gui Run button.
4444 For more information about using the Qt Simulator, see the
4445 \l{http://doc.qt.nokia.com/qtsimulator/index.html}{Qt Simulator Manual}.
4447 \section1 Running on Maemo or MeeGo Harmattan
4451 \o Build and run the application for \l{Running on Qt Simulator}{Qt Simulator}.
4453 \o Build and run the application for
4454 \l{Using Maemo or MeeGo Harmattan Emulator}
4455 {the Maemo or MeeGo Harmattan emulator}.
4457 \o Alternatively, you can build and run the application for a device:
4461 \o Configure the device and specify a connection to it. For more
4462 information, see \l{Connecting Maemo and MeeGo Harmattan Devices}.
4464 \o Connect the device to the development PC.
4466 \o Click the \gui Run button.
4472 Qt Creator uses the compiler specified in the MADDE tool chain to
4473 build the application.
4475 Qt Creator generates an installation package, installs it on the device,
4476 and executes the selected application.
4477 The application views are displayed on the device.
4479 output is visible in the Qt Creator \gui {Application Output} view.
4481 Choose \gui {Projects > Maemo Run} to view the settings for deploying the
4482 application on the connected device and creating the installation package.
4483 For more information, see
4484 \l{Specifying Run Settings for Maemo and MeeGo Harmattan Devices}.
4486 Debugging also works transparently.
4488 \section1 Running on Symbian
4492 \o Build and run the application for \l{Running on Qt Simulator}{Qt Simulator}.
4494 \o If no problems are found, build and run the application for a device.
4496 \o To test functionality that uses Symbian APIs, you can build and
4497 run the application for Symbian Emulator.
4501 \section2 Running on a Device
4505 \o Install the required software on the device. For more information, see
4506 \l{Connecting Symbian Devices}.
4508 \o Connect the device to the development PC through a USB cable.
4509 The target selector displays a green check mark when a
4510 device is connected.
4512 \image qtcreator-qt4-symbian-device-connected.png
4514 The tool tip of the target selector shows more details about the actual
4515 device that will be used when you run your application.
4517 \o Start the debugging agent (CODA or App TRK) application on your device.
4519 \note If you use CODA over an USB connection, it starts up
4520 automatically when you connect the device to the development PC.
4522 \o Click the \gui Run button.
4526 You can connect several devices to your development PC simultaneously.
4527 In the details of the run configuration for the \gui{Symbian Device} target,
4528 select the device to run your application on.
4530 When your application is ready for delivery to users, specify run settings
4531 for creating the final SIS installation packages. For more information,
4532 see \l{Creating SIS Files}.
4534 If you cannot run the application on a device, check that:
4537 \o The Nokia USB drivers that come with \e{PC Suite} or \e{Ovi Suite}
4538 have been installed on the development PC.
4539 \o The device is connected through USB cable in \e{PC Suite} mode.
4540 \o The debugging agent (App TRK or CODA) is running on the device with
4541 the status \e connected.
4543 \note If you use the CODA debugging agent over WLAN, you must enter
4544 the WLAN address and port number in Qt Creator, separated by a
4545 colon (:). For example: 192.167.0.100:1534
4546 \o The device is detected and selected in the \gui {Run Settings}.
4549 If this does not help to solve your problem, search the qt-creator@trolltech.com
4550 mailing list archives or provide feedback to us via the methods described on the
4551 \l{http://developer.qt.nokia.com/wiki/Category:Tools::QtCreator}{Qt Creator Development Wiki}.
4553 \section2 Running on Symbian Emulator
4556 the \gui{Symbian Emulator} target as the active one, and build and run your
4559 If you cannot run the application in the emulator, check that:
4561 \o You selected the \gui{Symbian Emulator} target for your application.
4563 \o If you cannot select \gui {Symbian Emulator} as target, check that
4564 Carbide.c++ is installed correctly and that the path to the Carbide.c++
4565 installation directory is specified for the WINSCW tool chain in the
4566 \gui{Compiler path} field
4567 in \gui {Tools > Options... > Tool Chains}.
4569 \o If the emulator process cannot be started, try closing Qt Creator and
4570 starting the application directly from your file manager. Having
4571 done this, Qt Creator should be able to run your projects in the
4580 \contentspage index.html
4581 \previouspage creator-publish-ovi.html
4582 \page creator-remote-compiler.html
4583 \nextpage creator-help.html
4585 \title Building with Remote Compiler
4587 The \gui {Remote Compiler} target is an interface to a compilation service at
4588 Nokia Developer. It provides a simple, standardized environment for building Qt
4589 applications and creating installation packages for Symbian, Maemo, and
4590 MeeGo Harmattan devices
4591 when you do not have the necessary tool chains and SDKs installed or they are
4592 not supported on the development PC. You can choose from a set of supported
4593 devices, such as S60 3rd Edition or S60 5th Edition devices.
4595 You need a Nokia Developer user account to use the Remote Compiler. You can
4596 create an account for free at \l{http://www.developer.nokia.com/}{Nokia Developer}.
4598 \note Remote Compiler is an experimental component that is installed as
4603 \o Select \gui {Start > \QSDK > Maintain \QSDK} to open the
4604 \gui {Maintain \QSDK} tool.
4606 \o In the \gui {Package Manager}, select \gui {Experimental >
4607 Remote Compiler} to install Remote Compiler.
4609 \o In Qt Creator, choose \gui {Tools > Options > Projects > Remote Compiler}
4610 to log on to Nokia Developer.
4612 \image remotecompiler-fn-logon.png "Remote Compiler options"
4614 \o Choose \gui {Projects}.
4617 \inlineimage qtcreator-qt4-addbutton.png "Add Target button"
4618 and select \gui {Remote Compiler} to add Remote Compiler as a target.
4620 \o Click \gui Add to add mobile device platforms as build configurations.
4622 \o Click the \gui {Target Selector} and select a build configuration.
4624 \o Choose \gui {Build > Build All}.
4628 The installation package is generated in the \gui {Build directory} on
4631 For more information about Remote Compiler, choose \gui {Help > Contents >
4632 Remote Compiler Manual}. The document is added during the installation of
4639 \contentspage index.html
4640 \previouspage creator-running-targets.html
4641 \page creator-build-settings.html
4642 \nextpage creator-project-qmake.html
4644 \title Specifying Build Settings
4646 Different build configurations allow you to quickly switch between
4647 different build settings. By default, Qt Creator creates \bold debug
4648 and \bold release build configurations. A debug build contains additional
4649 debug symbols that you need for debugging the application but that you
4650 can leave out from the release version. Generally, you use the debug
4651 configuration for testing and the release configuration for creating
4652 the final installation file.
4654 You specify build settings in the \gui Projects mode.
4656 \image qtcreator-projectpane.png
4658 To add a new build configuration, click \gui Add and select the type of
4659 configuration you would like to add. You can add as many build
4660 configurations as you need.
4662 To delete the build configuration currently selected, click \gui Remove.
4664 \section1 Editing Build Configurations
4666 To edit a build configuration:
4668 \o Select the build configuration you want to edit in
4669 \gui{Edit Build Configuration}.
4670 \o In the \gui {Qt version} field, select the Qt version to use for
4671 building project. You can add Qt versions to the list if they are
4672 installed on the development PC, but were not detected
4673 automatically. For more information, see \l{Adding Qt Versions}.
4674 \o In the \gui {Tool chain} field, select the tool chain required
4675 to build the project. The tool chains that are compatible with the
4676 selected Qt version are listed. You can add tool chains to the list
4677 if they are not automatically detected. For more information, see
4678 \l{Adding Tool Chains}.
4680 \o In the \gui {Build directory} field, specify the build directory for
4682 By default, projects are built in a separate directory from the
4683 source directory, as \l{glossary-shadow-build}{shadow builds}.
4684 This keeps the files generated for each target platform separate.
4686 \note Shadow building is not supported by the Symbian build system.
4687 Also, shadow building on Windows is not supported for Maemo or
4689 If you only build for one target platform, you can deselect
4690 the \gui{Shadow build} checkbox.
4693 \note The build configuration for the \gui{Symbian Device} target
4694 uses the GCCE tool chain by default. If you want to build
4695 for the device using RVCT, install the RVCT tool chain, and then
4696 select it in the \gui {Tool chain} field.
4698 \section1 Starting External Processes
4700 Qt Creator executes external processes to accomplish tasks such as building
4701 and running applications. To execute the processes, Qt Creator uses shell
4702 commands that are native to the system. It constructs the commands from
4703 an executable name and optional command line arguments.
4705 The executable name is specified in the executable fields: \gui qmake,
4706 \gui Make, \gui Command, or \gui Executable. It is either derived from the
4707 project or specified manually. When you specify executables manually, you
4708 can reference environment variables and Qt Creator variables. However, no
4712 You can specify command-line arguments in the arguments fields: \gui {Additional
4713 arguments}, \gui {Command arguments}, \gui {Make arguments}, or \gui Arguments.
4714 You can create shell command lines that can contain redirection and other
4715 advanced constructs. However, some more complex use cases, such as piping
4716 test data into the application being tested or grouping commands, are not
4717 supported because the value of the \gui Executable field is always placed
4718 first when constructing the command.
4720 \section2 Using Environment Variables
4722 You can use any environment variables as values in the fields. For a list
4723 of variable names, click \gui {Build Environment > Details} in the
4724 \gui {Build Settings}. Environment variables are referenced using the native
4725 syntax: $VARNAME or ${VARNAME} on Unix and %VARNAME% on Windows.
4727 \section2 Using Qt Creator Variables
4729 You can use Qt Creator variables in arguments, executable paths, and working
4731 The variables take care of quoting their expansions, so you do not need to
4734 The following Qt Creator variables are available:
4744 \section1 Build Steps
4746 The build system of Qt Creator is built on qmake and make. In
4747 \gui{Build Steps} you can change the settings for qmake and make. Qt
4748 Creator runs the make command using the Qt version defined for the current
4749 build configuration.
4751 \image qtcreator-build-steps.png "Build steps"
4753 To override the shell command that Qt Creator constructs by default, remove
4754 the build step and add a custom build step that specifies another shell
4757 \section2 Adding Custom Build Steps
4759 To add custom steps to the build settings, select \gui {Add Build Step >
4760 Custom Process Step}.
4762 By default, custom steps are disabled. To activate a custom step, select
4763 the \gui{Enable custom process step} check-box.
4765 \image qtcreator-build-steps-custom.png "Custom Process Step"
4767 \section1 Clean Steps
4769 You can use the cleaning process to remove intermediate files. This process
4770 might help you to fix obscure issues during the process of building a
4773 \image qtcreator-clean-steps.png "Clean steps"
4775 You can define the cleaning steps for your builds in the \gui{Clean Steps}:
4777 \o To add a clean step using make or a custom process, click
4778 \gui{Add Clean Step} and select the type of step you want to add.
4780 By default, custom steps are disabled. To activate a custom step,
4781 select the \gui{Enable custom process step} check-box.
4782 \o To remove a clean step, click \gui{Remove Item}.
4783 \o To change the order of steps, click
4784 \inlineimage qtcreator-movestep.png
4788 \section1 Build Environment
4790 You can specify the environment you want to use for building in the
4791 \bold{Build Environment} section. By default, the environment in which Qt
4792 Creator was started is used and modified to include the Qt version.
4793 Depending on the selected Qt version, Qt Creator automatically sets the
4794 necessary environment variables. You can edit existing environment
4795 variables or add, reset and unset new variables based on your project
4798 \image qtcreator-build-environment.png "Build Environment"
4800 \note The changes are stored in the local project specific \c{.pro.user}
4801 file. Therefore, they are not suitable for sharing between developers or
4802 development PCs. To share settings, incorporate them into the build system.
4803 For example, if you use qmake, make the changes in the \c{.pro} file.
4806 \section2 Clearing the System Environment
4808 To build with a clean system environment, select the \gui {Clear system
4809 environment} check box. Qt Creator discards the current environment, and
4810 populates a clean system environment with the environment variables that the
4811 compilers and tools need. Therefore, the environment is never totally empty,
4812 even after you clear it.
4818 \contentspage index.html
4819 \previouspage creator-tool-chains.html
4820 \page creator-run-settings.html
4821 \nextpage creator-editor-settings.html
4823 \title Specifying Run Settings
4825 Qt Creator automatically creates run configurations for your project.
4826 To view and modify the settings, select \gui {Projects > Run}.
4828 The settings to specify depend on the type of the project: Qt project
4829 or Qt Quick project, and on the target for the project.
4831 Click \gui Add to add run settings for a project and \gui Remove to remove
4832 the current settings.
4834 \section1 Specifying Run Settings for qmake Projects
4836 The run configurations for qmake projects derive their executable from the parsed .pro
4838 For more information on how the commands are constructed, see
4839 \l{Starting External Processes}.
4841 \section2 Specifying Run Settings for Desktop Targets
4843 You can specify command line arguments to be passed to the executable
4844 and the working directory to use. The working directory defaults to
4845 the directory of the build result.
4847 For console applications, check the \gui{Run in Terminal} check box.
4848 If you need to run with special environment variables set up, you
4849 also do it in the run configuration settings.
4851 \image qtcreator-pprunsettings.png
4853 You can also create custom executable run configurations where you
4854 can set the executable to be run. For more information, see
4855 \l{Specifying a Custom Executable to Run}.
4857 \section2 Specifying Run Settings for Symbian Devices
4859 Qt Creator automatically detects Symbian devices that are connected to
4860 the development PC with a USB cable.
4861 If only one device is detected, the application is deployed to it
4862 and run on it. If multiple devices are connected to the PC,
4863 make sure that the correct device is selected in the
4864 \gui {Symbian Device} run settings for your project.
4866 You can also pass command line arguments to your application on the device.
4867 Press the \gui{Device info button} to get more information about the selected
4868 device, such as the CPU type and the running debugging agent version.
4870 \image qtcreator-symbian-run-settings.png "Run settings for Symbian devices"
4872 To use the CODA debugging agent over a WLAN connection, enter the WLAN
4873 address of the device and the port number to use, separated by a colon (:),
4874 in the \gui WLAN field. For example: 192.167.0.100:1534
4876 When you deploy the application for the \gui{Symbian Device} target, Qt
4877 Creator generates a Symbian installation system (SIS) file in the project folder
4878 and copies it to the device that is connected to the development PC.
4879 If no device is connected, you must remove the \gui {Deploy SIS Package} step,
4880 to create the package. Click \gui {Remove Item} to skip the step.
4882 \image qtcreator-remove-deploy-step.png "Removing deploy steps"
4884 When you are ready to publish the application on Ovi Store or some other
4885 channel, you must make sure that the SIS file meets the requirements for
4886 publishing and installing applications on Symbian devices. For more information,
4887 see \l{Deploying Applications to Symbian Devices}.
4889 \section2 Specifying Run Settings for Maemo and MeeGo Harmattan Devices
4891 To run an application on a Maemo or MeeGo Harmattan device, create and
4892 select a device configuration in the Maemo 5 or Harmattan run settings for
4894 You can also pass command line arguments to your application.
4896 \image qtcreator-screenshot-run-settings-maemo.png "Run settings for Maemo devices"
4898 To run and debug applications on Maemo or MeeGo Harmattan devices, you must
4900 from the development PC to the devices. Click \gui {Manage device
4901 configurations} to create connections. For more information, see
4902 \l {Configuring Connections in Qt Creator}.
4904 When you run the application on the \gui{Maemo5} or \gui Harmattan target,
4905 Qt Creator generates
4906 a Debian installation package in the build directory by default. You can deliver
4907 the installation package to users for installation on devices that are of
4908 the same type and run the same firmware as the connected device. For more
4910 \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}.
4912 \section1 Specifying a Custom Executable to Run
4914 If you use CMake or the generic project type in Qt Creator, or want
4915 to run a custom desktop executable, create a \gui {Custom Executable}
4916 run configuration for your project. For example, when working on a library,
4917 you can run a test application that links against the library.
4919 Specify the executable to run, command line arguments, working directory,
4920 and environment variables to use.
4922 \image qmldesigner-run-custom-exe.png "Run settings for custom executables"
4924 \section1 Specifying Run Settings for Qt Quick UI Projects
4926 You can specify run settings for the \gui Desktop target:
4930 \o In the \gui {Qt version} field, select a Qt version that has support
4933 \o In the \gui Arguments field, you can specify command line arguments
4934 to be passed to the executable.
4936 \o In the \gui {Main QML file}, select the file that \QQV will be
4939 \o In the \gui Debugger group, select the languages to debug:
4940 \gui{C++} and \gui QML. \gui {Debug port} is the port to access \QQV.
4941 You can use any free port in the registered port range.
4942 For more information, see \l{Debugging Qt Quick Projects}.
4946 \note Opening a socket at a well-known port presents a security risk. Anyone
4947 on the Internet could connect to the application that you are debugging and
4948 execute any JavaScript functions. Therefore, you must make sure that the port
4949 is properly protected by a firewall.
4951 \image qmldesigner-run-settings.png "Run settings for Qt Quick UI projects"
4958 \contentspage index.html
4959 \previouspage creator-deployment-symbian.html
4960 \page creator-deployment-maemo.html
4961 \nextpage creator-publishing-to-maemo-extras.html
4963 \title Deploying Applications to Maemo or MeeGo Harmattan Devices
4965 You can specify settings for deploying applications to Maemo 5 and MeeGo
4966 Harmattan devices in the
4967 project .pro file. You can view the settings in the \gui {Run Settings}.
4969 \image qtcreator-maemo-deployment.png "Deploy to device"
4971 The files to be installed are listed in the
4972 \gui {Deploy to Device} step, the \gui {Files to install for subproject}
4974 \gui {Local File Path} field displays the location of the file on the development
4975 PC. The \gui {Remote Directory} field displays the folder where the file is installed on
4977 Text in red color indicates that the information is missing. Select the
4978 text to edit it and add the missing information.
4980 You can use desktop files to display icons on the home screen of the
4981 device. To add desktop files to the project file, select \gui {Add Desktop
4982 File}. To specify the icon file to display, select \gui {Add Launcher
4983 Icon...}. To remove desktop files and icons, delete the definitions from
4986 If you develop your own libraries, Qt Creator needs to be able to find
4987 them when you compile projects depending on them. When you install MADDE,
4988 an instance of the device file
4989 system, called sysroot, is installed to the development PC. Libraries are copied to
4990 sysroot if the \gui {Also deploy to sysroot} check box is selected.
4992 \section1 Creating Debian Installation Packages
4994 When you run the application on the \gui{Maemo5} or \gui Harmattan target,
4995 Qt Creator generates
4996 a Debian installation package in the build directory by default. You can deliver
4997 the installation package to users for installation on devices that are of
4998 the same type and run the same firmware as the connected device.
5000 \image qtcreator-maemo-deb-package.png "Create installation package"
5002 The name of the installation package is displayed in the \gui {Package name}
5003 field in the \gui {Create Package} step. You can change the version number
5004 in the \gui {Package version} field.
5006 You can specify information that users see on a delivery channel, such as
5007 Ovi Store or Maemo.org. You can specify a short description of the
5008 application, package
5009 name, and application icon.
5011 The Debian control file contains an application icon in encoded form. To add the
5012 application icon to the file, select it in the \gui {Icon to be displayed
5013 in Package Manager} field.
5014 For more information about icon files and adding them manually, see
5015 \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}.
5017 \note Qt Creator automates this process for you.
5019 Qt Creator provides templates for a set of files that must be included
5020 in Debian packages. When you create a \gui Maemo5 or \gui Harmattan target
5021 for a project, Qt Creator
5022 asks whether packaging files are to be added to the project and to version
5023 control. If you plan to edit the packaging files, add them to version
5026 To edit the files, select a file in \gui {Adapt Debian
5027 file} and click \gui Edit. The file opens in the text editor.
5033 \contentspage index.html
5034 \previouspage creator-deployment-maemo.html
5035 \page creator-publishing-to-maemo-extras.html
5036 \nextpage creator-publish-ovi.html
5038 \title Publishing Maemo Applications to Extras-devel
5040 Extras is the primary repository for Maemo applications where most
5041 community software can be found. You can browse the applications available
5042 in Extras at \l{http://maemo.org/downloads/Maemo5/}{Maemo Downloads}.
5044 You can publish both free and commercial applications to Extras. Free
5045 applications must be open source and pass through a QA process.
5046 Commercial applications are usually closed, binary only, and the publisher
5047 is responsible for assuring their quality and security.
5049 You can upload free applications as Debian packages to
5050 \l{http://wiki.maemo.org/Extras-devel}{Extras-devel} at Maemo.org to share
5051 new updates to your application and to start the community QA process.
5052 You need a \l{https://garage.maemo.org/}{Garage} account for the uploads,
5053 but the package itself does not need to be hosted in the Garage.
5055 You can use the \gui {Publish for Fremantle Extras-devel Free Repository}
5056 wizard to create a source archive and, optionally, upload it to a build
5057 server for compiling and packaging. The package is then moved to the
5058 Extras-devel repository. From there on, you must follow the standard
5059 Maemo processes to get the application published to Extras.
5061 The wizard checks that the package contains all the information that is
5062 required to publish applications on Extras: package description and
5063 Package Manager icon. For more information about entering this information,
5064 see \l{Creating Debian Installation Packages}.
5066 To use the publishing wizard:
5070 \o Select the \gui {Maemo5} build target for your project.
5072 \o Choose \gui {Build > Publish Project}.
5074 \o Select \gui {Publish for Fremantle Extras-devel Free Repository},
5075 and then select \gui {Start Wizard}.
5077 \o Select the Qt version and device type to build against and click
5080 To create a source archive without uploading it to the build
5081 server, select the \gui {Only create source package, do not upload}
5084 \o In the \gui {Garage account name} field, enter your login name, or
5085 select \gui {Get an account} to create a new account.
5087 \image qtcreator-publish-maemo-extras.png "Upload Settings dialog"
5089 You can also select \gui {Request upload rights} to use the Maemo
5090 Extras Assistant to validate your Garage account.
5092 \o Select \gui Commit to publish the application.
5100 \contentspage index.html
5101 \previouspage creator-cache-profiler.html
5102 \page creator-deployment.html
5103 \nextpage creator-deployment-symbian.html
5105 \title Deploying Applications to Mobile Devices
5107 Deploy configurations in the \gui Project mode \gui {Run Settings} handle
5108 the packaging of the application as an executable and copying it to a
5109 location you want to run the executable at. The files can be copied to a location
5110 in the file system of the development PC or a mobile device.
5112 When you are ready to publish the application on Ovi Store or some other
5113 channel, you must make sure that the installation file meets the requirements for
5114 publishing and installing applications to Symbian or Maemo devices. The following
5115 sections describe the steps that you have to take to create installation packages
5116 for Symbian, Maemo, or MeeGo Harmattan devices and for publishing on Ovi
5121 \o \l{Deploying Applications to Symbian Devices}
5122 \o \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}
5123 \o \l{Publishing Maemo Applications to Extras-devel}
5124 \o \l{Publishing Applications to Ovi Store}
5125 \o \l{Building with Remote Compiler}
5132 \contentspage index.html
5133 \previouspage creator-deployment.html
5134 \page creator-deployment-symbian.html
5135 \nextpage creator-deployment-maemo.html
5137 \title Deploying Applications to Symbian Devices
5139 This section describes how to create installation packages that meet the
5140 requirements for installing applications to Symbian devices.
5142 \section1 Creating SIS Files
5144 When you deploy the application for the \gui{Symbian Device} target, Qt
5145 Creator automatically generates a Symbian installation system (SIS) file
5146 in the project folder. You can deliver the installation file to users for
5147 installation on Symbian devices.
5149 The name of the installation file is displayed in the \gui {Installation file}
5150 field in the \gui {Run Settings}. In the \gui {Installation drive} field, select the drive on the device
5151 to install the application to. To suppress notifications on the device during the
5152 installation, select the \gui {Silent installation} check box. If the silent
5153 installation fails, Qt Creator attempts installation again, this time displaying
5154 notifications and error messages.
5156 To create a SIS package without copying it to the device (for example, to submit it
5157 to \e {Application Signing Services for Ovi Store} or \e {Symbian Signed}),
5158 create a deploy configuration that contains only the
5159 \gui {Create SIS Package} step.
5161 \image qtcreator-run-settings-create.png "Create SIS Package step"
5164 \section1 Signing SIS Files
5166 Only installation files signed with a certificate and private key are
5167 allowed to be installed onto Symbian devices. By default, Qt Creator
5168 self-signs the installation file. This self-signing allows you to install
5169 the application on a mobile device but places limits on what you can do
5170 with the installation file, including:
5172 \o Self-signed applications cannot access the more sensitive
5173 \l{Capabilities and Signing}{capabilities} of the mobile device.
5174 \o Security warnings will be displayed when you install the self-signed
5175 application on a mobile device.
5176 \o Self-signed applications cannot be published to Ovi
5180 To get around these limitations, you need to go through the Symbian Signed
5181 or Application Signing Services for Ovi Store. The Symbian Signed organisation
5182 manages a public key
5183 infrastructure to provide public authentication of the information in the
5184 application signing certificates. Their security partner can validate your
5185 certificate and give you a Publisher ID. Then, when you sign an
5186 application, other people can be confident that the information in your
5187 certificate is correct and that the application does actually come from you.
5189 Application Signing Services for Ovi Store is a variant of the Symbian
5190 Signed certification provided by Ovi
5191 Publishing. It is limited to the Basic and System capability sets
5192 (Express Signing). Participants can submit an unsigned SIS file to Ovi
5193 Publishing for signing. For more information about how
5195 \l {http://www.developer.nokia.com/Community/Wiki/Guide_to_Publishing_Qt_Applications_to_the_Ovi_Store}{Guide to Publishing Qt Applications to the Ovi Store}.
5197 There are also options that do not require you to get a Publisher ID. For
5198 more detail about how the Symbian Signed process works, see
5199 \l{https://www.symbiansigned.com}{Symbian Signed}.
5201 When you have your own certificate and private key, you can specify them in
5202 the \gui{Create SIS Package} step in the \gui {Run Settings}.
5204 \image qtcreator-qt4-symbian-signing.png
5207 If your private key is protected by a passphrase, Qt Creator asks you for the
5208 passphrase when the package is signed and offers to store it. However, storing
5209 passphrases in Qt Creator presents a security risk. To make Qt Creator forget
5210 all saved passphrases, click \gui {Reset Passphrases}.
5212 \section2 Capabilities and Signing
5214 Capabilities allow the Symbian platform to control access by applications to
5215 the functionality provided by the platform APIs. Access to capabilities is
5216 determined by the device configuration and how the application has been signed.
5218 Symbian Signed offers the following signing options depending on the
5219 capabilities that the application accesses:
5223 \o \bold{Express signed} for applications that access only user and system
5226 \o \bold{Certified signed} for applications that access also restricted or
5227 device manufacturer capabilities.
5229 \note You need to request the rights to access device manufacturer
5230 capabilities from the manufacturer.
5234 For more information about how to choose the appropriate signing option and
5235 how you can check which capabilities you need, see
5236 \l{https://www.symbiansigned.com}{Symbian Signed}
5238 \l{http://doc.qt.nokia.com/4.7/platform-notes-symbian.html#required-capabilities}{Required Capabilities for Qt Applications}.
5240 For more information on how to define capabilities for a project, see
5241 \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#capabilities}{Capabilities}.
5243 \note In Qt 4.7.1 and later, if you select the \gui {Self-signed certificate}
5244 option, the SIS generation process checks that the package can be self-signed.
5245 If problems are found, it attempts to fix the package. If fixes cannot be made,
5246 a message appears in the \gui {Compile Output} view.
5248 The following modifications can be made:
5252 \o Package UID is changed to an UID from the unprotected range (if it was
5253 from the protected range).
5255 \o Vendor ID is set to zero on all binaries included in the package file.
5257 \o All restricted and device manufacturer capabilities are removed from all
5258 libraries included in the package file.
5262 The application UID or capabilities used in executables (.exe) cannot be changed,
5263 because that would break the application. If the executables use protected UIDs
5264 or restricted or device manufacturer capabilities, signing fails and an error
5265 message appears in the \gui {Compile Output} view.
5267 \section1 Creating Smart Installer for Symbian Packages
5269 To deploy Qt applications on Symbian devices, you must install the software that Qt applications
5270 require, typically Qt, QtWebkit, and Open C. Nokia Smart Installer for Symbian makes it easier
5271 for users to install Qt applications to Symbian phones by checking whether the device contains
5272 the necessary software and by installing the missing pieces.
5274 For this to work, the Nokia Smart Installer must be packaged with the Qt application. The
5275 application SIS file must first be Symbian Signed or signed by the Application
5276 Signing Services for Ovi Store. The capabilities used in the applications
5277 determine, which signing option must be selected. The wrapper package must be signed using
5278 either the same option or a more extensive option than the application SIS.
5280 \note If you use the Application Signing Services for Ovi Store, you can submit an unsigned
5281 wrapper package to Ovi Publishing. For more information, see
5282 \l{Publishing Applications to Ovi Store}.
5284 You can either install the Nokia Smart Installer for Symbian as part of
5285 the \QSDK, or download and install it from the
5286 \l{http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Nokia Smart Installer for Symbian}
5289 To package Nokia Smart Installer with the application, select the \gui {Create Smart Installer
5290 package} check box. This ensures that up-to-date and appropriate versions of Qt and its
5291 dependencies are installed on devices. Further, it reduces the file size of the application you
5292 publish, because you do not have to deliver the required libraries.
5294 Nokia has reserved the following UIDs to be used with Nokia Smart Installer for Symbian:
5298 \o 0xA000D7CE for self-signed applications
5299 \o 0x2002CCCF for Ovi Store or Symbian Signed packages
5303 \section2 Creating Self-signed Smart Installer Packages
5305 To create a self-signed Nokia Smart Installer for Symbian wrapped .sis file,
5306 you must use an UID from the unprotected UID range, provided by Symbian Signed
5307 and the wrapper package UID value 0xA000D7CE. If you used the Qt Creator project
5308 wizard to create the project, this wrapper package UID is used by default.
5312 \o Make sure that the source directory is clean. For example, if you use git,
5313 enter the following command:
5317 \o Click \gui Projects to edit the \gui {Build Settings} for the
5318 \gui {Symbian Device} target.
5320 \o Select the \gui Release configuration.
5322 \o Open the \gui {Run Settings}.
5324 \o In the \gui {Create SIS Package} step, select \gui {Self-signed certificate}.
5326 \o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to
5327 skip the step of copying the SIS file to a device. The SIS file is created
5328 in the project folder.
5330 \image qtcreator-remove-deploy-step.png "Removing deploy steps"
5332 \o To package Nokia Smart Installer for Symbian with the application, select
5333 the \gui {Create Smart Installer package} check box.
5335 \o Edit the project .pro file to use the correct UIDs for the application and
5336 the wrapper package, as illustrated by the following code snippet:
5340 TARGET.UID3 = 0xE4DE5D27
5341 DEPLOYMENT.installer_header=0xA000D7CE
5344 "%{\"CustomVendor-EN\"}" \
5347 my_deployment.pkg_prerules = vendorinfo
5348 DEPLOYMENT += my_deployment
5352 \o Choose \gui {Build > Run Project}.
5356 Qt Creator automatically generates a wrapper package in the project folder.
5358 \section2 Creating Symbian Signed Smart Installer Packages
5360 If the application uses functions that require advanced capabilities (AllFiles,
5361 DRM, TCB, CommDD, DiskAdmin, NetworkControl, MultimediaDD), you must use the
5362 standard Symbian Signed process to have the application Symbian Signed. Depending
5363 on the capabilities used, you may use either the Express Signed or the Certified
5364 Signed path, or the manufacturer-specific channel (for AllFiles, DRM, and TCB).
5368 \o Make sure that the source directory is clean. For example, if you use git,
5369 enter the following command:
5373 \o Click \gui Projects to edit the \gui {Build Settings} for the
5374 \gui {Symbian Device} target.
5376 \o Select the \gui Release configuration.
5378 \o Open the \gui {Run Settings}.
5380 \o In the \gui {Create SIS Package} step, specify the developer certificate
5381 and key in the \gui {Custom certificate} and \gui {Key file} fields.
5383 \o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to
5384 skip the step of copying the SIS file to a device. The SIS file is created
5385 in the project folder.
5387 \o Edit the project .pro file to use the correct UIDs and vendor information
5388 for the application, as illustrated by the following code snippet:
5392 TARGET.UID3 = 0x2000D7D1
5393 DEPLOYMENT.installer_header=0x2002CCCF
5396 "%{\"CustomVendor-EN\"}" \
5399 my_deployment.pkg_prerules = vendorinfo
5400 DEPLOYMENT += my_deployment
5404 \o Choose \gui {Build > Run Project}.
5406 \o Submit the created .sis file to Symbian Signed for certification.
5408 \note Ensure that your application complies with the Symbian Signed
5409 Test Criteria before submitting the file for certification. Also, if the file is
5410 intended for Ovi Store publishing, verify that the application complies with Ovi
5411 Store publishing requirements.
5413 \o After receiving the .sis file from Symbian Signed, copy it over the old
5416 \note The instructions below assume that you have installed \QSDK.
5418 \o To package Nokia Smart Installer for Symbian with the application, choose
5419 \gui {Start > Qt SDK > Symbian > Qt for Symbian Command Prompt}
5420 to open the Qt command line environment.
5422 \o Change to the project directory. For example:
5424 \c{cd C:\Sources\Application}
5426 \o To create a Smart Installer wrapper package, enter the following
5429 \c {C:\Sources\Application> make ok_installer_sis QT_SIS_CERTIFICATE=publisherid.cer QT_SIS_KEY=publisherid.key}
5431 \o Submit the created wrapped .sis file, application_installer.sis, to
5432 Symbian Signed. Express Signed is a suitable signing option for the wrapper
5433 package. The capabilities used in the application do not play a role here,
5434 because the wrapper package is already signed.
5438 Qt Creator automatically generates a wrapper package in the project folder.
5440 \note Ensure that your application complies with the requirements before submitting
5441 the file to Ovi Store.
5443 For more information about the qmake DEPLOYMENT variable, see
5444 \l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#deployment}{qmake Variable Reference}.
5446 For more information about the Nokia Smart Installer, see the
5447 \l{http://doc.qt.nokia.com/smart-installer/index.html}{Nokia Smart Installer for Symbian Manual}.
5449 Note: Nokia Smart Installer for Symbian is only available on Windows.
5451 \section1 Application UID
5453 A UID is a globally unique identifier that is used to
5454 uniquely identify, for example, an object or file type. In Symbian development,
5455 objects are identified by compound identifiers that are constructed from three
5456 UIDs, namely UID1, UID2, and UID3. UID1 and UID2 specify the category of an
5457 object, whereas UID3 identifies a particular object, such as an application.
5459 When you create a \gui {Mobile Qt Application}, Qt Creator adds a UID3 suitable for
5460 development and debugging automatically to the application .pro file. However, to
5461 distribute your application and get it Symbian Signed, you must apply for a UID
5462 from Symbian Signed, which manages the allocation of UIDs. You can request UIDs either one
5463 at a time or as preallocated blocks on the \l{https://www.symbiansigned.com/app/page}{Symbian Signed}
5466 If you use the Ovi Signed process, Ovi Publisher Support allocates the UID for you.
5468 Replace the testing UID with the distribution UID in the .pro file before you
5469 build the final installation package. For more information, see
5470 \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#unique-identifiers}{Unique Identifiers}.
5476 \contentspage index.html
5477 \previouspage creator-publishing-to-maemo-extras.html
5478 \page creator-publish-ovi.html
5479 \nextpage creator-remote-compiler.html
5481 \title Publishing Applications to Ovi Store
5483 Ovi Store is the global content market of Nokia, which reaches millions of
5484 people worldwide. Consumers can access Ovi Store through either of these
5489 \o Ovi Store applications on mobile devices
5491 \o Web browsers on desktop computers, laptops, netbooks, and tablets
5495 Consumers have access to a wide selection of content and can download
5496 content in a few easy clicks.
5498 The process and requirements to publish Qt applications to Ovi Store are
5500 \l {http://www.developer.nokia.com/Community/Wiki/Guide_to_Publishing_Qt_Applications_to_the_Ovi_Store}{Guide to Publishing Qt Applications to the Ovi Store} wiki.
5502 This section describes how to
5503 generate installation packages that
5504 you can publish to Ovi Store.
5506 \section1 Publishing Qt Content for Symbian Devices
5508 You can use the \e {Application Signing Services for Ovi Store} to get your
5509 application Express Signed for
5510 free by Nokia. Make sure to use the \l{Application UID}{application UID} that you
5511 receive from Ovi Publisher Support.
5513 The \gui {Publish Qt Symbian Applications to Ovi Store} wizard allows you
5514 to check that your application can be
5515 published on Ovi Store. It checks that the application UID, vendor name,
5516 and the capabilities used meet the Ovi Publishing criteria.
5518 If you use Symbian Signed UIDs or the application uses functions that
5520 \l{Capabilities and Signing}{capabilities}, you must
5521 use the standard Symbian Signed process to have the application Symbian Signed
5522 (using the Certified Signed path or the manufacturer-specific channel).
5523 For more information, see \l{Deploying Applications to Symbian Devices}.
5525 To use the publishing wizard:
5529 \o Select \gui Projects to select the Qt version to build the
5530 application. For more information, see \l{Supported Configurations}.
5532 \o Select the \gui {Symbian Device} build target for your project.
5534 \o Choose \gui {Build > Publish Project}.
5536 \o Select \gui {Publish Qt Symbian Applications to Ovi Store}, and then
5537 select \gui {Start Wizard}.
5539 \o Select the Qt version and device type to build against and click
5540 \gui Next. We recommend that you select a release configuration.
5542 \o The wizard checks the information in the project file against the
5543 Ovi Publishing criteria and indicates possible problems. You can fix
5544 some of the problems in the wizard.
5546 \image qtcreator-publishing-wizard-symbian.png "Project File Checks dialog"
5548 \o Select \gui Commit to save changes and create the .sis file. The
5549 .sis file is packaged with Nokia Smart Installer for Symbian.
5551 \o Choose \gui {Open Containing Folder} to open the folder where the
5552 .sis file was created.
5554 \o Submit the created .sis file to Ovi Publishing as a Qt Content item.
5556 \note You cannot use this .sis file for testing.
5560 \note After you change the application UID, you must use the developer
5561 certificate-key pair that you receive from Ovi Publisher Support for testing
5562 the application on devices. The following error message is displayed on the
5563 device if you use UIDs from the trusted range (0x2xxxxxxx) in a self-signed
5564 application: \gui {Unable to install a trusted application from a trusted
5566 information, see \l{http://www.developer.nokia.com/Community/Wiki/UID}{UID}.
5568 If you try to use more capabilites than the certificate permits, the
5569 following error message is displayed on the device: \gui {Requested
5570 application access not granted.} For example, if you try to install a
5571 self-signed application that uses a system capability.
5573 \section2 Supported Configurations
5575 When you select the Qt version to build the application with, consider
5576 which version provides the application with the widest support on different
5577 Symbian platforms. The binary compatibility promise of Qt and Symbian means
5578 that applications that are built against Qt 4.6.3 also run on Qt 4.7.3.
5579 Similarly, applications that are supported on Symbian^1 are also supported
5580 on Symbian^3. However, dependencies, such as QML or Qt Mobility API
5581 versions might restrict the choice of Qt versions that you have.
5583 In general, if you use only Qt widgets and APIs in the application, you
5584 can use \gui {Qt 4.6.3 for Symbian^1} to build it.
5585 The application is supported on both Symbian^1 and Symbian^3 devices.
5587 If you use QML in the application, you can use \gui {Qt 4.7.3 for
5588 Symbian^1} to build it. The application is supported on both Symbian^1 and
5591 If you use native Symbian APIs, you must check that they are available on
5592 the target devices. For more information about the API differences between
5593 Symbian^1 (S60 5th Edition) and Symbian^3, see the \bold {Symbian
5594 Reference Documentation for Qt}, which is delivered together with \QSDK
5595 and which you can view in the \gui Help mode.
5597 The following table summarizes the supported configurations for each Qt
5598 version available in Qt Creator build settings:
5604 \i Qt Mobility Version
5605 \i Native Symbian C++ APIs
5608 \i Qt 4.6.3 for S60 3rd Edition
5614 \i Qt 4.6.3 for Symbian^1 (S60 5th Edition)
5620 \i Qt 4.6.3 for Symbian^3
5626 \i Qt 4.7.3 for Symbian^1
5632 \i Qt 4.7.3 for Symbian^3
5639 \section1 Publishing Qt Content for Maemo Devices
5641 The applications that you publish on Ovi Store, must meet the testing criteria
5643 \l{http://www.developer.nokia.com/info/sw.nokia.com/id/9cd1eb18-821b-4228-a0a3-36b049c5d608/Maemo_5_Application_OVI_Store_Entry_Requirements.pdf.html}
5644 {Maemo 5 Applications: Ovi Store Entry Requirements}.
5646 Make sure that your application passes the following most commonly
5651 \o Package filename must include the application name and version
5652 number using three digits. For example: myapplication_1_0_1.deb
5654 \o Application files must be installed to the opt folder on the ext3
5657 \o Debian packages must be given the category user/hidden.
5659 \o Application cannot crash or hang during use.
5661 \o The application must handle different memory situations correctly.
5665 You set the application name and installation folder in the
5666 \gui {Run Settings} for the project. For more information, see
5667 \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}. Qt Creator
5668 specifies the correct
5669 category settings by default when it creates the Debian directory and
5670 the necessary files.
5672 You can test the application on Qt Simulator and Maemo emulator to make
5673 sure that it does not crash or hang and to check how it handles different
5674 memory situations. Before you submit the application to Ovi Publishing, you
5675 must also fully test it on a Maemo device.
5677 \section1 Publishing Qt Content for MeeGo Harmattan Devices
5679 You cannot publish applications that are built with the beta version of the
5680 MeeGo Harmattan tool chain to Ovi Store.
5682 However, you can prepare for publishing by making sure that your application
5684 \l{http://www.developer.nokia.com/info/sw.nokia.com/id/44affcd1-ceba-4aca-8b65-670ce2cbbd1e/MeeGo_1_2_Harmattan_Applications_Ovi_Store_Entry_Requirements.html}
5685 {MeeGo 1.2 Harmattan Applications: Ovi Store Entry Requirements}.
5690 \contentspage index.html
5691 \previouspage creator-run-settings.html
5692 \page creator-editor-settings.html
5693 \nextpage creator-code-style-settings.html
5695 \title Specifying Editor Settings
5697 Qt Creator uses the \l{Editing MIME Types}{MIME type} of the file to
5698 determine which mode and editor to use for opening the file. For example,
5699 Qt Creator opens .txt files in \gui Edit mode in the text editor.
5701 You can configure the text editor according to your needs. You can specify
5702 editor behavior either globally for all projects or separately for each
5703 project. To specify global editor behavior, select \gui {Tools > Options...
5704 > Text Editor > Behavior}.
5706 To configure the text editor behavior for the current project:
5710 \o Select \gui {Projects > Editor Settings}.
5712 \o Deselect the \gui {Use global settings} check box.
5714 \o Specify text editor settings for the project.
5718 \image qtcreator-editor-settings.png "Editor Settings view"
5720 For more information about the settings, see:
5724 \o \l{Indenting Code}
5726 \o \l{File Encoding}
5728 \o \l{Moving to Symbol Definition or Declaration}
5730 \o \l{Configuring Fonts}
5738 \contentspage index.html
5739 \previouspage creator-editor-settings.html
5740 \page creator-code-style-settings.html
5741 \nextpage creator-build-dependencies.html
5743 \title Specifying Code Style Settings
5745 Qt Creator uses the \l{Editing MIME Types}{MIME type} of the file to
5746 determine which mode and editor to use for opening the file.
5747 Qt Creator opens C++ files in \gui Edit mode in the C++ code editor and
5748 QML files in the Qt Quick editor.
5750 You can configure the code style according to your needs. You can specify
5751 code style either globally for all projects or separately for each
5752 project. To specify global code style for C++ files, select \gui {Tools >
5755 To specify global code style for QML files, select \gui {Tools > Options...
5758 To configure the editor behavior for the current project:
5762 \o Select \gui {Projects > Code Style Settings}.
5764 \o In the \gui Language field, select \gui C++ or \gui Qt Quick.
5766 \o Deselect the \gui {Use global settings} check box.
5768 \o In the \gui Settings field, select \gui Custom.
5770 \o Specify code style settings for the project. Only \gui General
5771 settings are available for QML files.
5775 \image qtcreator-code-style-settings.png "Code Style Settings view"
5777 For more information about the settings, see \l{Indenting Code}.
5783 \contentspage index.html
5784 \previouspage creator-code-style-settings.html
5785 \page creator-build-dependencies.html
5786 \nextpage creator-debugging.html
5788 \title Specifying Dependencies
5790 If you have multiple projects loaded in a session, you can define the
5791 order in which they are built. For example, if project A depends on project
5792 B, project B must be built first.
5794 \note The build order is stored as a property of a session, not a project.
5795 You must open the session for these settings to take effect. For more
5796 information, see \l{Managing Sessions}.
5798 \image qtcreator-build-dependencies.png "Dependencies view"
5800 To define the build order of projects within a session:
5802 \o In \gui Projects, select a project.
5803 \o Click \gui Dependencies.
5804 \o Select projects that must be built before the current project is
5808 Qt Creator calculates the build order based on the dependencies that you
5809 specify for the projects loaded in the session.
5811 \note You cannot use this view to specify subprojects for projects.
5812 For more information on how to add subprojects, see \l{Adding Subprojects
5819 \contentspage index.html
5820 \previouspage creator-quick-tour.html
5821 \page creator-getting-started.html
5822 \nextpage creator-build-example-application.html
5824 \title Getting Started
5826 This section contains examples that illustrate how to use Qt Creator
5827 to create, build, and run simple
5831 \o \l{Building and Running an Example Application}
5832 \o \l{Creating a Qt Widget Based Application}
5833 \o \l{Creating a Mobile Application with Qt SDK}
5834 \o \l{Creating a Qt Quick Application}
5841 \contentspage index.html
5842 \previouspage creator-writing-program.html
5843 \page creator-mobile-example.html
5844 \nextpage creator-qml-application.html
5846 \title Creating a Mobile Application with Qt SDK
5848 \note To complete this tutorial, you must install \QSDK.
5849 The installation program installs and configures the necessary tool chains
5850 for mobile application development.
5852 This tutorial describes how to use Qt Creator to create a small Qt
5853 application, Battery Indicator, that uses the System Information
5854 Mobility API to fetch battery information from the device.
5856 \image qtcreator-batteryindicator-screenshot.png
5858 \section1 Creating the Battery Indicator Project
5860 \note Create the project with the \gui{Help} mode active so that you can follow
5861 these instructions while you work.
5865 \o Select \gui{File > New File or Project > Qt Widget Project > Mobile
5867 Application > Choose}.
5869 \image qtcreator-new-mobile-project.png "New File or Project dialog"
5871 The \gui{Introduction and Project Location} dialog opens.
5873 \image qtcreator-mobile-intro-and-location.png "Introduction and Project Location dialog"
5875 \o In the \gui{Name} field, type \bold {BatteryIndicator}.
5877 \o In the \gui {Create in} field, enter the path for the project files. For example,
5878 \c {C:\Qt\examples}, and then click \gui{Next}.
5880 The \gui{Target Setup} dialog opens.
5882 \image qtcreator-mobile-project-qt-versions.png "Target Setup dialog"
5884 \o Select \gui {Symbian Device}, \gui {Maemo5}, \gui Harmattan, and
5885 \gui {Qt Simulator} targets,
5886 and click \gui{Next}.
5888 \note Targets are listed if you installed the appropriate development
5889 environment, for example, as part of the \QSDK. You can add targets
5890 later in the \gui Projects mode.
5892 The \gui {Mobile Options} dialog opens.
5894 \image qtcreator-mobile-project-app-options.png "Mobile Options dialog"
5896 \o In the \gui {Orientation behavior} field, determine how the application
5897 behaves when the orientation of the device display rotates between portrait
5898 and landscape, and then click \gui{Next}.
5900 \note This dialog opens only if you select \gui Maemo5 or
5901 \gui {Symbian Device} target in the \gui {Target Setup} dialog. On
5902 Harmattan, the Qt Quick Components for MeeGo provide native-looking
5905 The \gui {Symbian Specific} dialog opens.
5907 \image qtcreator-mobile-project-symbian-options.png "Symbian Specific dialog"
5909 \note Qt Creator contains a default program icon and generates an
5910 \l{Application UID}, for testing the application on a device. You only
5911 need to change the icon and UID if you deliver the application for public use.
5915 The \gui {Maemo Specific} dialog opens.
5917 \image qtcreator-mobile-project-maemo-options.png "Maemo Specific dialog"
5919 \o In the \gui {Application icon} field, select the application
5920 icon to use on Maemo 5 or Harmattan targets, or click \gui Next to use
5923 The \gui{Project Management} dialog opens.
5925 \image qtcreator-mobile-project-summary.png "Project Management dialog"
5927 \o Review the project settings, and click \gui{Finish} to create the project.
5931 The BatteryIndicator project now contains the following files:
5935 \o BatteryIndicator.pro
5937 \o BatteryIndicator.svg
5938 \o BatteryIndicator.png
5939 \o BatteryIndicator.desktop
5944 \o templates for Debian deployment files
5948 \image qtcreator-mobile-project-contents.png "Project contents"
5950 The files come with the necessary boiler plate code that you must
5951 modify, as described in the following sections.
5953 \section1 Declaring the Qt Mobility API
5955 To use the Qt Mobility APIs or develop applications for Symbian
5956 devices, you must modify the .pro file to declare the Qt Mobility APIs
5959 This example uses the System Info API, so you must declare it, as
5960 illustrated by the following code snippet:
5965 MOBILITY = systeminfo
5969 Each Mobility API has its corresponding value that you have to add
5970 as a value of MOBILITY to use the API. For a list of the APIs and the
5971 corresponding values that you can assign to MOBILITY, see the
5972 \l {http://doc.qt.nokia.com/qtmobility/quickstart.html}{Quickstart Example}.
5974 \section1 Designing the User Interface
5978 \o In the \gui{Editor} mode, double-click the mainwindow.ui
5979 file in the \gui{Projects} view to launch the integrated \QD.
5981 \o Drag and drop a \gui{Progress Bar} (\l{http://doc.qt.nokia.com/4.7/qprogressbar.html}{QProgressBar})
5984 \image qtcreator-mobile-project-widgets.png "Adding widgets to the UI"
5986 \o In the \gui Properties pane, change the \gui objectName to
5987 \bold batteryLevelBar.
5989 \o Right-click the \gui MainWindow object and select
5990 \gui {Lay Out > Lay Out Horizontally} to ensure that the battery
5991 indicator widget size is adjusted correctly on Maemo devices.
5995 \section1 Completing the Header File
5997 The mainwindow.h file contains some of the necessary #includes, a
5998 constructor, a destructor, and the \c{Ui} object. You must include
5999 the System Info header file, add a shortcut to the mobility name
6000 space, and add a private function to update the battery level value in
6001 the indicator when the battery power level changes.
6005 \o In the \gui{Projects} view, double-click the \c{mainwindow.h} file
6006 to open it for editing.
6008 \o Include the System Device Info header file, as illustrated by the following
6011 \snippet examples/batteryindicator/mainwindow.h 1
6013 \o Add a shortcut to the mobility name space, as illustrated by the
6014 following code snippet:
6016 \snippet examples/batteryindicator/mainwindow.h 2
6018 \o Declare a private function in the \c{private} section, after the
6019 \c{Ui::MainWindow} function, as illustrated by the following code
6022 \snippet examples/batteryindicator/mainwindow.h 3
6026 \section1 Completing the Source File
6028 Now that the header file is complete, move on to the source file,
6033 \o In the \gui{Projects} view, double-click the mainwindow.cpp file
6034 to open it for editing.
6036 \o Create a QSystemDeviceInfo object and set its value. Then connect the signal
6037 that indicates that battery level changed to the \c setValue
6038 slot of the progress bar. This is illustrated by the following code snippet:
6040 \snippet examples/batteryindicator/mainwindow.cpp 1
6042 \o Use the constructor to set initial values and make sure that the
6043 created object is in a defined state, as illustrated by the following
6046 \snippet examples/batteryindicator/mainwindow.cpp 2
6050 \section1 Compiling and Running Your Program
6052 Now that you have all the necessary code, select \gui {Qt Simulator}
6053 as the target and click the
6054 \inlineimage qtcreator-run.png
6055 button to build your program and run it in the Qt Simulator.
6057 In Qt Simulator, run the runOutOfBattery.qs example script
6058 to see the value change in the Battery Indicator application.
6059 Select \gui {Scripting > examples > runOutOfBattery.qs > Run}.
6061 \image qtcreator-mobile-simulated.png "Mobile example in Qt Simulator"
6063 \section1 Testing on a Symbian Device
6065 You also need to test the application on real devices. Before you can
6066 start testing on Symbian devices, you must connect them to the development
6067 PC by using a USB cable and install the necessary software on them.
6071 \o Install Qt libraries, Qt mobile libraries, and a
6072 debugging agent on the device. For more information,
6073 see \l{Connecting Symbian Devices}.
6075 \o Start the debugging agent, App TRK or CODA, on the device.
6077 \o Click the \gui {Target Selector} and select \gui {Symbian Device}.
6079 \o Click \gui Run to build the application for the Symbian device.
6083 \section1 Testing on the Maemo or MeeGo Harmattan Emulator
6085 The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
6086 of the \QSDK. After they are installed, you can start them from Qt Creator.
6088 The Maemo emulator emulates the Nokia N900 device environment. You can test
6089 applications in conditions practically identical to running the application
6090 on a Nokia N900 device with the software update release 1.3 (V20.2010.36-2).
6092 The MeeGo Harmattan emulator emulates the Nokia N9 device environment.
6094 For more information, see \l{Using Maemo or MeeGo Harmattan Emulator}.
6099 \contentspage index.html
6100 \previouspage creator-getting-started.html
6101 \page creator-build-example-application.html
6102 \nextpage creator-writing-program.html
6104 \title Building and Running an Example Application
6106 You can test that your installation is successful by opening an existing
6107 example application project.
6111 \o On the \gui Welcome page, select \gui {Choose an Example...}
6112 in the \gui {Explore Qt Quick Examples} field, and then select
6113 \gui {Toys > Clocks}.
6115 \image qtcreator-gs-build-example-open.png "Selecting an example"
6117 \o Select targets for the project. Select at least Qt Simulator
6118 and one of the mobile targets, Symbian Device, Maemo 5, or Harmattan,
6120 the device you develop for.
6122 \image qtcreator-gs-build-example-targets.png "Selecting targets"
6124 \note You can add targets later in the \gui Projects mode.
6126 \o To test the application in Qt Simulator, click the \gui {Target
6127 Selector} and select \gui {Qt Simulator}.
6129 \image {qtcreator-gs-build-example-select-qs.png} "Selecting Qt Simulator as target"
6132 \inlineimage{qtcreator-run.png}
6133 to build the application and run it in Qt Simulator.
6135 \o To see the compilation progress, press \key{Alt+4} to open the
6136 \gui {Compile Output} pane.
6138 The \gui Build progress bar on the toolbar turns green when the project
6139 is successfully built. The application opens in Qt Simulator.
6141 \image {qt-simulator.png} "Qt Simulator"
6143 \o Change the settings in the
6144 \gui View pane. For example, rotate the device by clicking the
6145 \gui {Orientation} buttons or choose from the various Symbian and Maemo
6146 configurations in the \gui {Device} field. You can also simulate various
6147 mobile functions and create your own scripts.
6149 \o To test the application on a Symbian device, install Qt libraries
6150 and a debugging agent on the device. For more information,
6151 see \l{Connecting Symbian Devices}.
6153 \o Click the \gui {Target Selector} and select \gui {Symbian Device}.
6155 \o Click \gui Run to build the application and run it on the Symbian device.
6163 \contentspage index.html
6164 \previouspage creator-mobile-example.html
6165 \page creator-qml-application.html
6166 \nextpage creator-project-managing.html
6168 \title Creating a Qt Quick Application
6170 \note To complete this tutorial, you must have Qt 4.7 or later installed.
6172 This tutorial uses basic elements and illustrates basic concepts of
6173 \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}.
6175 This tutorial describes how to use the Qt Creator to implement the
6176 \l{http://doc.qt.nokia.com/4.7/declarative-animation-states.html}
6177 {states and transitions example application}. The example application displays a
6178 Qt logo that moves between three rectangles on the page when you click them.
6180 \image qmldesigner-tutorial.png "States and transitions example"
6182 \section1 Creating the Project
6186 \o Select \gui{File > New File or Project > Qt Quick Project > Qt Quick UI >
6189 \o Follow the instructions of the wizard to create a project called Transitions.
6191 \o Press \key {Ctrl+R} to run the application in the QML Viewer.
6195 Qt Creator generates a default QML file that you can modify to create the main view
6198 \image qmldesigner-tutorial-project.png "Transitions project in Edit mode"
6200 \section1 Creating the Main View
6202 The main view of the application displays a Qt logo in the top left corner of the
6203 screen and two empty rectangles.
6205 To use the states.png image in your application, you must copy it to the project
6206 directory (same subdirectory as the QML file) from the examples directory in the
6207 Qt installation directory. For example:
6208 \c {C:\QtSDK\Examples\4.7\declarative\animation\states}. The image appears
6209 in the \gui Resources pane. You can also use any other image or a QML element, instead.
6213 \o In the \gui Projects view, double-click the main .qml file (Transitions.qml)
6214 to open it in the code editor.
6216 \o Click \gui Design to open the file in \QMLD.
6218 \image qmldesigner-tutorial-desing-mode.png "Transitions project in Design Mode"
6220 \o In the \gui Navigator pane, select \gui Text and press \key Delete to delete it.
6222 \o Select \gui Rectangle to edit its properties.
6224 \image qmldesigner-tutorial-page.png "Page properties"
6228 \o In the \gui Id field, enter \e page, to be able to reference the rectangle
6231 \o In the \gui Colors tab, \gui Rectangle field, set the color to #343434.
6235 \o In the \gui Library view, \gui Resources tab, select states.png and
6236 drag and drop it to the canvas.
6238 \image qmldesigner-tutorial-user-icon.png "Image properties"
6242 \o In the \gui Id field, enter \e icon.
6244 \o In the \gui Position field, set \gui X to 10 and \gui Y to 20.
6250 \o In the \gui Library view, \gui Items tab, select \gui Rectangle,
6251 drag and drop it to the canvas, and edit its properties.
6253 \image qmldesigner-tutorial-topleftrect.png "Rectangle properties"
6257 \o In the \gui Id field, enter \e topLeftRect.
6259 \o In the \gui Size field, set \gui W and \gui H to 64, for the rectangle size
6260 to match the image size.
6262 \o In the \gui Colors tab, \gui Rectangle field, click the
6263 \inlineimage qmldesigner-transparent-button.png
6264 button to make the rectangle transparent.
6266 \o In the \gui Border field, set the border color to #808080.
6268 \o In the \gui Rectangle tab, \gui Border field, set the border width to
6271 \note If the \gui Border field does not appear after you set the border
6272 color, try setting the border color to solid by clicking the
6273 \inlineimage qmldesigner-solid-color-button.png
6276 \o In the \gui Radius field, select 6 to create rounded corners for the
6279 \o Click \gui {Layout}, and then click the top and left anchor buttons
6280 to anchor the rectangle to the top left corner of the page.
6282 \image qmldesigner-tutorial-topleftrect-layout.png "Layout tab"
6284 \o In the \gui Margin field, select 20 for the top anchor and 10 for
6289 \o In the \gui Navigator pane, drag and drop the \gui {Mouse Area} element from
6290 \e page to \e topLeftRect to make it apply only to the rectangle and not to the whole
6293 \o Edit \gui {Mouse Area} properties:
6297 \o Click \gui {Layout}, and then click the
6298 \inlineimage qmldesigner-anchor-fill-screen.png
6299 button to anchor the mouse area to the rectangle.
6301 \o In the code editor, edit the pointer to the clicked expression in the mouse
6302 area element, as illustrated by the following code snippet:
6306 anchors.fill: parent
6307 onClicked: page.state = ''
6311 The expression sets the state to the base state and returns the image to
6312 its initial position.
6316 \o In the \gui Navigator pane, copy topLeftRect (by pressing \key {Ctrl+C}) and
6317 paste it to the canvas twice
6318 (by pressing \key {Ctrl+V}). Qt Creator renames the new instances of the element
6319 topLeftRect1 and topLeftRect2.
6321 \o Select topLeftRect1 and edit its properties:
6325 \o In the \gui Id field, enter \e middleRightRect.
6327 \o In \gui {Layout}, select the vertical center anchor button and
6328 then the right anchor button to
6329 anchor the rectangle to the middle right margin of the screen.
6331 \o In the \gui Margin field, select 10 for the right anchor and 0 for
6332 the vertical center anchor.
6334 \o In the code editor,add a pointer to a clicked expression to the
6335 mouse area element. The following expression sets the state to \e State1:
6337 \c {onClicked: page.state = 'State1'}
6339 You will create State1 later.
6343 \o Select topLeftRect2 and edit its properties:
6347 \o In the \gui Id field, enter \e bottomLeftRect.
6349 \o In \gui {Layout}, select the bottom and left anchor buttons to
6350 anchor the rectangle to the bottom left margin of the screen.
6352 \o In the \gui Margin field, select 20 for the bottom anchor and 10 for
6355 \o In the code editor, add a pointer to a clicked expression to the
6356 mouse area element. The following expression sets the state to \e State2:
6358 \c {onClicked: page.state = 'State2'}
6360 You will create State2 later.
6364 \o Press \key {Ctrl+S} to save the changes.
6366 \o Press \key {Ctrl+R} to run the application in the QML Viewer.
6370 \image qmldesigner-tutorial.png "States and transitions example"
6372 You should see the Qt logo in the top left rectangle, and two additional
6373 rectangles in the center right and bottom left of the screen.
6375 You can now create additional states to add views to the application.
6377 \section1 Adding Views
6379 In the .qml file, you already created pointers to two additional states:
6380 State1 and State2. To create the states:
6384 \o Click the empty slot in the \gui States pane to create State1.
6386 \o Click the empty slot in the \gui States pane to create State2.
6388 \o In the code editor, bind the position of the Qt logo to the rectangle
6389 to make sure that the logo is displayed within the rectangle when the view
6390 is scaled on different sizes of screens. Set expressions for the x and y
6391 properties, as illustrated by the following code snippet:
6393 \snippet snippets/qml/states-properties.qml states
6395 \image qmldesigner-tutorial-state1.png "States"
6397 \note When you set the expressions, drag and drop is disabled for
6400 \o Press \key {Ctrl+R} to run the application in the QML Viewer.
6404 Click the rectangles to move the Qt logo from one rectangle to another.
6406 \section1 Adding Animation to the View
6408 Add transitions to define how the properties change when the Qt logo moves
6409 between states. The transitions apply animations to the Qt logo. For example,
6410 the Qt logo bounces back when it moves to the middleRightRect and eases into
6411 bottomLeftRect. Add the transitions in the code editor.
6415 \o In the code editor, add the following code to specify that when moving to
6416 State1, the x and y coordinates of the Qt logo change linearly over a duration
6419 \snippet snippets/qml/list-of-transitions.qml first transition
6421 \o You can use the Qt Quick toolbar for animation to change the easing curve
6422 type from linear to OutBounce:
6426 \o Click \gui NumberAnimation in the code editor to display the
6427 \inlineimage qml-toolbar-indicator.png
6428 icon, and then click the icon to open the toolbar:
6430 \image qmldesigner-tutorial-quick-toolbar.png "Qt Quick toolbar for animation"
6432 \o In the \gui Easing field, select \gui Bounce.
6434 \o In the \gui Subtype field, select \gui Out.
6438 \o Add the following code to specify that when moving to State2, the x and y
6439 coordinates of the Qt logo change over a duration of 2 seconds,
6440 and an InOutQuad easing function is used:
6442 \snippet snippets/qml/list-of-transitions.qml second transition
6444 \o Add the following code to specify that for any other state changes, the x
6445 and y coordinates of the Qt logo change linearly over a duration of 200
6448 \snippet snippets/qml/list-of-transitions.qml default transition
6450 \o Press \key {Ctrl+R} to run the application in the QML Viewer.
6454 Click the rectangles to view the animated transitions.
6456 \section1 Deploying the Application to Mobile Devices
6458 To deploy the application to mobile devices, use the \gui {Qt Quick Application} wizard
6459 to convert it into a Qt Quick application. For more information, see
6460 \l{Importing QML Applications}.
6466 \contentspage index.html
6467 \previouspage creator-build-example-application.html
6468 \page creator-writing-program.html
6469 \nextpage creator-mobile-example.html
6471 \title Creating a Qt Widget Based Application
6473 This tutorial describes how to use Qt Creator
6474 to create a small Qt application, Text Finder. It is a simplified version of the
6475 QtUiTools \l{http://doc.qt.nokia.com/4.7/uitools-textfinder.html}{Text Finder}
6477 The application user interface is constructed from Qt widgets by using \QD.
6478 The application logic is written in C++ by using the code editor.
6480 \image qtcreator-textfinder-screenshot.png
6482 \section1 Creating the Text Finder Project
6484 \note Create the project with two instances of Qt Creator open and the \gui{Help} mode
6485 active in one of them so that you can follow
6486 these instructions while you work.
6490 \o Select \gui{File > New File or Project > Qt Widget Project > Qt Gui
6491 Application > Choose}.
6493 \image qtcreator-new-qt-gui-application.png "New File or Project dialog"
6495 The \gui{Introduction and Project Location} dialog opens.
6497 \image qtcreator-intro-and-location-qt-gui.png "Introduction and Project Location dialog"
6499 \o In the \gui{Name} field, type \bold {TextFinder}.
6502 \o In the \gui {Create in} field, enter the path for the project files. For example,
6503 \c {C:\Qt\examples}, and then click \gui{Next}.
6505 The \gui {Target Setup} dialog opens.
6507 \image qtcreator-new-project-qt-versions-qt-gui.png "Target Setup dialog"
6509 \o Select the Qt versions to use as build targets for your project, and click
6512 \note If you have only one Qt version installed, this dialog is skipped.
6514 The \gui{Class Information} dialog opens.
6516 \image qtcreator-class-info-qt-gui.png "Class Information dialog"
6518 \o In the \gui{Class name} field, type \bold {TextFinder} as the class name.
6520 \o In the \gui{Base class} list, select \bold {QWidget} as the base class type.
6522 \note The \gui{Header file}, \gui{Source file} and
6523 \gui{Form file} fields are automatically updated to match the name of the
6526 \o Click \gui{Next}.
6528 The \gui{Project Management} dialog opens.
6530 \image qtcreator-new-project-summary-qt-gui.png "Project Management dialog"
6532 \o Review the project settings, and click \gui{Finish} to create the project.
6539 The TextFinder project now contains the following files:
6549 \image qtcreator-textfinder-contents.png "TextFinder project contents"
6551 The .h and .cpp files come with the necessary boiler plate code.
6552 The .pro file is complete.
6554 \section1 Filling in the Missing Pieces
6556 Begin by designing the user interface and then move on to filling
6557 in the missing code. Finally, add the find functionality.
6559 \section2 Designing the User Interface
6561 \image qtcreator-textfinder-ui.png "Text Finder UI"
6565 \o In the \gui{Editor} mode, double-click the textfinder.ui file in the \gui{Projects}
6566 view to launch the integrated \QD.
6568 \o Drag and drop the following widgets to the form:
6571 \o \gui{Label} (QLabel)
6572 \o \gui{Line Edit} (QLineEdit)
6573 \o \gui{Push Button} (QPushButton)
6577 \image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI"
6579 \note To easily locate the widgets, use the search box at the top of the
6580 \gui Sidebar. For example, to find the \gui Label widget, start typing
6581 the word \bold label.
6583 \image qtcreator-texfinder-filter.png "Filter field"
6585 \o Double-click the \gui{Label} widget and enter the text \bold{Keyword}.
6587 \o Double-click the \gui{Push Button} widget and enter the text \bold{Find}.
6589 \o In the \gui Properties pane, change the \gui objectName to \bold findButton.
6591 \image qtcreator-textfinder-objectname.png "Changing object names"
6593 \o Press \key {Ctrl+A} to select the widgets and click \gui{Lay out Horizontally}
6594 (or press \gui{Ctrl+H}) to apply a horizontal layout
6597 \image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout"
6599 \o Drag and drop a \gui{Text Edit} widget (QTextEdit)
6602 \o Select the screen area and click \gui{Lay out Vertically} (or press \gui{Ctrl+L})
6603 to apply a vertical layout (QVBoxLayout).
6605 \image qtcreator-textfinder-ui.png "Text Finder UI"
6607 Applying the horizontal and vertical layouts ensures that the application UI scales to different
6610 \o To call a find function when users press the \gui Find button, you use the Qt signals
6611 and slots mechanism. A signal is emitted when a particular event occurs and a slot is
6612 a function that is called in response to a particular signal. Qt widgets have predefined
6613 signals and slots that you can use directly from \QD. To add a slot for the find function:
6617 \o Right-click the \gui Find button to open a context-menu.
6618 \o Select \gui {Go to Slot > clicked()}, and then select \gui OK.
6620 A private slot, \c{on_findButton_clicked()}, is added to the header file,
6621 textfinder.h and a private function, \c{TextFinder::on_findButton_clicked()},
6622 is added to the source file, textfinder.cpp.
6626 \o Press \gui{Ctrl+S} to save your changes.
6630 For more information about designing forms with \QD, see the
6631 \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
6633 \section2 Completing the Header File
6635 The textfinder.h file already has the necessary #includes, a
6636 constructor, a destructor, and the \c{Ui} object. You need to add a private
6637 function, \c{loadTextFile()}, to read and display the
6638 contents of the input text file in the
6643 \o In the \gui{Projects} pane in the \gui {Edit view}, double-click the \c{textfinder.h} file
6644 to open it for editing.
6646 \o Add a private function
6647 to the \c{private} section, after the \c{Ui::TextFinder} pointer, as
6648 illustrated by the following code snippet:
6650 \snippet examples/textfinder/textfinder.h 0
6654 \section2 Completing the Source File
6656 Now that the header file is complete, move on to the source file,
6661 \o In the \gui{Projects} pane in the \gui Edit view, double-click the textfinder.cpp file
6662 to open it for editing.
6664 \o Add code to load a text file using
6665 QFile, read it with QTextStream, and
6666 then display it on \c{textEdit} with
6667 \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}.
6668 This is illustrated by the following code snippet:
6670 \snippet examples/textfinder/textfinder.cpp 0
6672 \o To use QFile and QTextStream, add the
6673 following #includes to textfinder.cpp:
6675 \snippet examples/textfinder/textfinder.cpp 1
6677 \o For the \c{on_findButton_clicked()} slot, add code to extract the search string and
6678 use the \l{http://doc.qt.nokia.com/4.7/qtextedit.html#find}{find()} function
6679 to look for the search string within the text file. This is illustrated by
6680 the following code snippet:
6682 \snippet examples/textfinder/textfinder.cpp 2
6684 \o Once both of these functions are complete, add a line to call \c{loadTextFile()} in
6685 the constructor, as illustrated by the following code snippet:
6687 \snippet examples/textfinder/textfinder.cpp 3
6691 The \c{on_findButton_clicked()} slot is called automatically in
6692 the uic generated ui_textfinder.h file by this line of code:
6695 QMetaObject::connectSlotsByName(TextFinder);
6698 \section2 Creating a Resource File
6700 You need a resource file (.qrc) within which you embed the input
6701 text file. The input file can be any .txt file with a paragraph of text.
6702 Create a text file called input.txt and store it in the textfinder
6705 To add a resource file:
6707 \o Select \gui{File > New File or Project > Qt > Qt Resource File > Choose}.
6708 \image qtcreator-add-resource-wizard.png "New File or Project dialog"
6710 The \gui {Choose the Location} dialog opens.
6712 \image qtcreator-add-resource-wizard2.png "Choose the Location dialog"
6714 \o In the \gui{Name} field, enter \bold{textfinder}.
6715 \o In the \gui{Path} field, enter \c{C:\Qt\examples\TextFinder},
6716 and click \gui{Next}.
6718 The \gui{Project Management} dialog opens.
6720 \image qtcreator-add-resource-wizard3.png "Project Management dialog"
6723 \o In the \gui{Add to project} field, select \bold{TextFinder.pro}
6724 and click \gui{Finish} to open the file in the code editor.
6726 \o Select \gui{Add > Add Prefix}.
6727 \o In the \gui{Prefix} field, replace the default prefix with a slash (/).
6728 \o Select \gui{Add > Add Files}, to locate and add input.txt.
6730 \image qtcreator-add-resource.png "Editing resource files"
6734 \section1 Compiling and Running Your Program
6736 Now that you have all the necessary files, click the \inlineimage qtcreator-run.png
6737 button to compile and run your program.
6743 \contentspage index.html
6744 \previouspage creator-project-generic.html
6745 \page creator-version-control.html
6746 \nextpage adding-plugins.html
6748 \title Using Version Control Systems
6750 Version control systems supported by Qt Creator are:
6753 \i Version Control System
6758 \i \l{http://bazaar.canonical.com/}
6759 \i Qt Creator 2.2 and later
6762 \i \l{http://www.cvshome.org}
6766 \i \l{http://git-scm.com/}
6770 \i \l{http://mercurial.selenic.com/}
6771 \i Qt Creator 2.0 and later
6774 \i \l{http://www.perforce.com}
6775 \i Server version 2006.1 and later
6778 \i \l{http://subversion.apache.org/}
6783 \section1 Setting Up Version Control Systems
6785 Qt Creator uses the version control system's command line clients to access
6786 your repositories. To allow access, make sure that the command line clients
6787 can be located using the \c{PATH} environment variable or specify the path to
6788 the command line client executables in \gui{Tools} > \gui{Options...} >
6789 \gui {Version Control}.
6791 After you set up the version control system, use the command line to check
6792 that everything works (for example, use the status command). If no issues arise,
6793 you should be ready to use the system also from Qt Creator.
6795 \section2 Using msysGit on Windows
6797 If you configure Git for use with \c {git bash}, only, and use SSH
6798 authorization, Git looks for the SSH keys in the directory where the
6799 \c HOME environment points to. The variable is always set by \c {git bash}.
6801 However, the variable is typically not set in a Windows command prompt.
6802 When you run Git from a Windows command prompt, it looks for the SSH keys in its
6803 installation directory, and therefore, the authorization fails.
6805 You can set the \c HOME environment variable from Qt Creator. Select \gui {Tools >
6806 Options... > Version Control > Git}. Select the \gui {Environment Variables}
6807 and the \gui {Set "HOME" environment variable} check boxes. \c HOME is set to
6808 \c %HOMEDRIVE%%HOMEPATH% when the Git executable is run and authorization works
6809 as it would with \c {git bash}.
6811 \section1 Setting Up Common Options
6813 Select \gui{Tools} > \gui{Options...} > \gui{Version Control} > \gui{Common}
6814 to specify settings for submit messages:
6816 \o \gui{Submit message check script} is a script or program that
6817 can be used to perform checks on the submit message before
6818 submitting. The submit message is passed in as the script's first
6819 parameter. If there is an error, the script should output a
6820 message on standard error and return a non-zero exit code.
6822 \o \gui{User/alias configuration file} takes a file in mailmap format
6823 that lists user names and aliases. For example:
6826 Jon Doe <Jon.Doe@company.com>
6827 Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
6830 \note The second line above specifies the alias \e{hm} and the
6831 corresponding email address for \e{Hans Mustermann}. If the
6832 user/alias configuration file is present, the submit editor
6833 displays a context menu with \gui{Insert name...} that pops up a
6834 dialog letting the user select a name.
6836 \o \gui{User fields configuration file} is a simple text file
6837 consisting of lines specifying submit message fields that take
6838 user names, for example:
6845 The fields above appear below the submit message. They provide completion
6846 for the aliases/public user names specified in the
6847 \e{User/alias configuration file} as well as a button that opens the
6848 aforementioned user name dialog.
6850 \o \gui{SSH prompt command} specifies an ssh-askpass command that you
6851 can use (on Linux) to prompt the user for a password when using SSH.
6852 For example, \c ssh-askpass or \c x11-ssh-askpass, depending on the
6853 ssh-askpass implementation that you use.
6857 \section1 Creating VCS Repositories for New Projects
6859 Qt Creator allows you to create repositories for version
6860 control systems that support local repository creation, such as
6861 Git, Mercurial, or Bazaar.
6862 When creating a new project by selecting \gui File >
6863 \gui{New File or Project...}, you can choose a version
6864 control system in the final wizard page.
6866 You can also select \gui Tools and then select \gui {Create Repository...}
6867 in the submenu for the version control system.
6869 To import a project that is under version control, choose \gui {File >
6870 New File or Project... > Project from Version Control} and select the
6871 version control system that you use. Follow the instructions of the
6872 wizard to import the project.
6874 \section1 Using Version Control Systems
6876 The \gui{Tools} menu contains a submenu for each supported version
6879 The \gui{Version Control} output pane displays the commands
6880 that are executed, a timestamp, and the relevant output.
6881 Select \gui {Window > Output Panes > Version Control} to open
6885 \image qtcreator-vcs-pane.png
6888 \section2 Adding Files
6890 When you create a new file or a new project, the wizard displays a page
6891 asking whether the files should be added to a version control system.
6892 This happens when the parent directory or the project is already
6893 under version control and the system supports the concept of adding files,
6894 for example, Perforce and Subversion. Alternatively, you can
6895 add files later by using the version control tool menus.
6897 With Git, there is no concept of adding files. Instead, all modified
6898 files must be staged for a commit.
6901 \section2 Viewing Diff Output
6903 All version control systems provide menu options to \e{diff} the current
6904 file or project: to compare it with the latest version stored in the
6905 repository and to display the differences. In Qt Creator, a diff is
6906 displayed in a read-only editor. If the file is accessible, you can
6907 double-click on a selected diff chunk and Qt Creator opens an editor
6908 displaying the file, scrolled to the line in question.
6910 \image qtcreator-vcs-diff.png
6913 \section2 Viewing Versioning History and Change Details
6915 Display the versioning history of a file by selecting \gui{Log}
6916 or \gui{Filelog}. Typically, the log output contains the date, the commit
6917 message, and a change or revision identifier. Click on the identifier to
6918 display a description of the change including the diff.
6919 Right-clicking on an identifier brings up a context menu that lets you
6920 show annotation views of previous versions (see \l{Annotating Files}).
6922 \image qtcreator-vcs-log.png
6925 \section2 Annotating Files
6927 Annotation views are obtained by selecting \gui{Annotate} or \gui{Blame}.
6928 Selecting \gui{Annotate} or \gui{Blame} displays the lines of the file
6929 prepended by the change identifier they originate from. Clicking on the
6930 change identifier shows a detailed description of the change.
6932 To show the annotation of a previous version, right-click on the
6933 version identifier at the beginning of a line and choose one of the
6934 revisions shown at the bottom of the context menu. This allows you to
6935 navigate through the history of the file and obtain previous versions of
6936 it. It also works for Git and Mercurial using SHA's.
6938 The same context menu is available when right-clicking on a version
6939 identifier in the file log view of a single file.
6942 \section2 Committing Changes
6944 Once you have finished making changes, submit them to the version control
6945 system by choosing \gui{Commit} or \gui{Submit}. Qt Creator displays a
6946 commit page containing a text editor where you can enter your commit
6947 message and a checkable list of modified files to be included.
6949 \image qtcreator-vcs-commit.png
6951 When you have finished filling out the commit page information, click on
6952 \gui{Commit} to start committing.
6954 The \gui{Diff Selected Files} button brings up a diff view of the
6955 files selected in the file list. Since the commit page is just another
6956 editor, you can go back to it by closing the diff view. You can also check
6957 a diff view from the editor combo box showing the \gui{Opened files}.
6959 \section2 Reverting Changes
6961 All supported version control system support reverting your project to
6962 known states. This functionality is generally called \e reverting.
6964 The changes discarded depend on the version control system.
6966 A version control system can replace the \gui Revert menu option with other
6969 \section3 Reverting Changes Using Git
6971 The Git version control system has an index that is used to stage
6972 changes. The index is commited on the next commit. Git allows you to revert
6973 back to the state of the last commit as well as to the state staged in the
6978 \o \gui{Undo Unstaged Changes} reverts all changes and resets the working
6979 directory to the state of the index.
6981 \o \gui{Undo Uncommitted Changes} reverts all changes, discarding the index.
6982 This returns your working copy to the state it was in right after the last commit.
6986 \section2 Viewing Status
6988 You can select \gui{Status...} to view the status of the project or
6991 \section2 Updating the Working Tree
6993 You can select \gui Update to update your working tree with the latest
6994 changes from the branch. Some version control systems allow you to choose
6995 between updating the current project and updating all projects.
6997 With Git, you stash your changes and then pull the changes from the
7000 \section2 Deleting Files
7002 You can select \gui Delete to delete obsolete files from the repository.
7004 With Git, you delete the files from the working tree and then stage the
7005 deleted files for a commit.
7007 \section2 Using Additional Bazaar Functions
7009 Bazaar is a free version control system sponsored by Canonical.
7011 The \gui Bazaar submenu contains the following additional items:
7019 \i Turn the branch into a mirror of another branch.
7022 \i Update a mirror of the branch.
7026 \section2 Using Additional CVS Functions
7028 CVS is an open source version control system.
7030 The \gui CVS submenu contains the following additional items:
7038 \i Open a file for editing.
7041 \i Push changes to the remote repository.
7044 \i Discard the changes that you made in a file.
7048 \section2 Using Additional Git Functions
7050 Git is a fast decentralized version control system. Git is available
7051 for Windows, Linux and Mac.
7053 The \gui Git submenu contains the following additional items:
7060 \i \gui {Patch > Apply from Editor/Apply from File...}
7061 \i Patches are rewriting instructions that can be applied to a set of files.
7062 You can either apply a patch file that is open in Qt Creator or select
7063 the patch file to apply from the file system.
7066 \i Pull changes from the remote repository. If there are locally
7067 modified files, you are prompted to stash those changes. Select \gui{Tools >
7068 Options... > Version Control > Git} and select the \gui {Pull with rebase}
7069 check box to perform a rebase operation while pulling.
7072 \i \gui{Clean.../Clean Project...}
7073 \i All files that are not under version control (with the exception
7074 of patches and project files) are displayed in the \gui {Clean Repository}
7075 dialog. Select the files to delete and click \gui Delete. This allows you to
7076 clean a build completely.
7078 \i \gui{Launch gitk}
7079 \i Start the commit viewer for Git, gitk.
7081 \i \gui{Branches...}
7082 \i Manage local and remote branches.
7085 \i Manage remote repositories available in Git.
7087 \i \gui {Stage File for Commit}
7088 \i Mark new or modified files for committing to the repository.
7089 To undo this function, select \gui {Unstage File from Commit}.
7091 \i \gui{Show Commit...}
7092 \i Select a commit to view. Enter the SHA of the commit
7093 in the \gui Change field.
7096 \i Store local changes temporarily.
7098 \i \gui{Amend Last Commit...}
7099 \i Revert the last commit.
7103 \section3 Working with Branches
7105 To work with Git branches, select \gui{Branches...}. The checked out branch
7106 is shown in bold and underlined in the list of branches. Double-click branch
7109 \image qtcreator-vcs-gitbranch.png "Branches dialog"
7111 The following operations are supported:
7119 \i Create new tracking and non-tracking branches.
7122 \i Check out the selected branch and make it current.
7125 \i Remove a local branch. You cannot delete remote branches.
7128 \i Show the differences between the selected and the current
7132 \i Show the changes in a branch.
7135 \i Refresh the list of branches.
7138 \section3 Working with Remote Repositories
7140 To manage remote repositories available in Git, select \gui{Remotes...}.
7141 Double-click the names and URLs of the remote repositories to edit them.
7143 The following operations are supported:
7151 \i Add a new remote repository.
7154 \i Fetch all the branches and change information from a remote
7158 \i Remove a remote repository.
7161 \i Refresh the list of remote repositories.
7165 \section3 Using Stashes
7167 With Git, you can put your current set of changes onto a virtual shelf called a \e stash.
7168 Stashes are useful, for example, to put aside a set of changes to work on higher
7169 priority tasks or to pull in new chages from another repository.
7171 Qt Creator exposes this functionality in the \gui{Tools > Git > Stash} menu.
7179 \i Display a dialog that shows all known stashes with options to restore,
7180 display or delete them.
7183 \i Stash all local changes. The working copy is then reset to
7184 the state it had right after the last commit.
7186 \i \gui{Stash Snapshot...}
7187 \i Save a snapshot of your current work under a name for later reference. The
7188 working copy is unchanged.
7190 For example, if you want to try something and find out later that it does not work,
7191 you can discard it and return to the state of the snapshot.
7194 \i Remove a single stashed state from the stash list and apply it on
7195 top of the current working tree state.
7198 \section2 Using Additional Mercurial Functionality
7200 Mercurial is a free, distributed source control management tool.
7202 The \gui Mercurial submenu contains the following additional items:
7210 \i Apply changes from a patch file.
7213 \i Monitor the status of a remote repository by listing
7214 the changes that will be pulled.
7217 \i Monitor the status of a remote repository by listing
7218 the changes that will be pushed.
7221 \i Pull changes from the remote repository.
7224 \i Push changes to the remote repository.
7227 \section2 Using Additional Perforce Functions
7229 Perforce is a fast software configuration management system developed by
7232 When you start Qt Creator, it looks for the executable specified
7233 in the \gui{P4 command} field in \gui{Tools > Options... > Version
7234 Control > Perforce}. If the file is not found, the following error
7235 message is displayed in the \gui {Version Control} output pane:
7236 \gui {Perforce: Unable to determine the repository: "p4.exe"
7237 terminated with exit code 1}. If you use Perforce, check that the
7238 path to the executable is specified correctly in the \gui{P4 command}
7241 If you do not use Perforce, you can disable the Perforce plugin to
7242 get rid of the error message. Choose \gui {Help > About Plugins} and
7243 deselect the \gui Load check box for the \gui Perforce plugin in the
7244 \gui {Version Control} group.
7246 The \gui Perforce submenu contains the following additional items:
7253 \i \gui{Describe...}
7254 \i View information about changelists and the files in them.
7257 \i Open a file for editing.
7260 \i List files that are open for editing.
7262 \i \gui{Pending Changes...}
7263 \i Group files for commit.
7266 \section2 Using Additional Subversion Functions
7268 Subversion is an open source version control system.
7270 The \gui Subversion submenu contains the following additional items:
7277 \i \gui{Describe...}
7278 \i Display commit log messages for a revision.
7285 \contentspage index.html
7286 \previouspage qt-quick-toolbars.html
7287 \page creator-editor-locator.html
7288 \nextpage creator-editor-codepasting.html
7290 \title Searching With the Locator
7292 The locator provides one of the easiest ways in Qt Creator to browse
7293 through projects, files, classes, methods, documentation and file systems.
7294 You can find the locator in the bottom left of the Qt Creator window.
7296 To activate the locator, press \key Ctrl+K (\key Cmd+K on Mac OS
7297 X) or select \gui Tools > \gui Locate....
7299 \image qtcreator-locator.png
7301 To edit the currently open project's main.cpp file using the locator:
7303 \o Activate the locator by pressing \key Ctrl+K.
7304 \o Enter \tt{main.cpp}.
7306 \image qtcreator-locator-open.png
7307 \o Press \key Return.
7309 The main.cpp file opens in the editor.
7312 It is also possible to enter only a part of a search string.
7313 As you type, the locator shows the occurrences of that string regardless
7314 of where in the name of an component it appears.
7316 To narrow down the search results, you can use the following wildcard
7319 \o To match any number of any or no characters, enter \bold{*}.
7320 \o To match a single instance of any character, enter \bold{?}.
7323 \section1 Using the Locator Filters
7325 The locator allows you to browse not only files, but any items
7326 defined by \bold{locator filters}. By default, the locator contains
7329 \o Locating any open document
7330 \o Locating files anywhere on your file system
7331 \o Locating iles belonging to your project, such as source, header resource,
7333 \o Locating class and method definitions in your project or anywhere
7336 \o Locating class and method definitions in the current document
7337 \o Locating a specific line in the document displayed in your editor
7338 \o Opening help topics, including Qt documentation
7339 \o Performing web searches
7340 \o Running text editing macros that you record and save. For more
7341 information, see \l{Using Text Editing Macros}
7344 To use a specific locator filter, type the assigned prefix followed by
7345 \key Space. The prefix is usually a single character.
7347 For example, to locate symbols matching
7350 \o Activate the locator.
7351 \o Enter \tt{\bold{: QDataStream}} (: (colon) followed by a
7352 \key Space and the symbol name (QDataStream)).
7354 The locator lists the results.
7356 \image qtcreator-navigate-popup.png
7359 By default the following filters are enabled and you do not need to use
7360 their prefixes explicitly:
7363 \o Going to a line in the current file (l).
7364 \o Going to an open file (o).
7365 \o Going to a file in any open project (a).
7368 \section2 Using the Default Locator Filters
7370 The following locator filters are available by default:
7378 \o Go to a line in the current file.
7379 \o \tt{\bold{l \e{Line number}}}
7380 \o \image qtcreator-locator-line.png
7382 \o Go to a symbol definition.
7383 \o \tt{\bold{: \e{Symbol name}}}
7384 \o \image qtcreator-locator-symbols.png
7386 \o Go to a symbol definition in the current file.
7387 \o \tt{\bold{. \e{Symbol name}}}
7388 \o \image qtcreator-locator-method-list.png
7390 \o Go to a help topic.
7391 \o \tt{\bold{? \e{Help topic}}}
7392 \o \image qtcreator-locator-help.png
7394 \o Search for a term by using a web search engine.
7395 \o \tt{\bold{r \e{Search term}}}
7396 \o \image qtcreator-locator-web.png
7398 \o Go to an open file.
7399 \o \tt{\bold{o \e{File name}}}
7400 \o \image qtcreator-locator-opendocs.png
7402 \o Go to a file in the file system (browse the file system).
7403 \o \tt{\bold{f \e{File name}}}
7404 \o \image qtcreator-locator-filesystem.png
7406 \o Go to a file in any project currently open.
7407 \o \tt{\bold{a \e{File name}}}
7408 \o \image qtcreator-locator-files.png
7410 \o Go to a file in the current project.
7411 \o \tt{\bold{p \e{File name}}}
7412 \o \image qtcreator-locator-current-project.png
7414 \o Go to a class definition.
7415 \o \tt{\bold{c \e{Class name}}}
7416 \o \image qtcreator-locator-classes.png
7418 \o Go to a method definition.
7419 \o \tt{\bold{m \e{Method name}}}
7420 \o \image qtcreator-locator-methods.png
7422 \o Execute a text editing macro.
7423 \o \tt{\bold{rm \e{Macro name}}}
7424 \o \image qtcreator-locator-macros.png
7427 \section2 Creating Locator Filters
7429 To quickly access files not directly mentioned in your project, you can
7430 create your own locator filters. That way you can locate files in a
7431 directory structure you have defined.
7433 To create a locator filter:
7435 \o In the locator, click \inlineimage qtcreator-locator-magnify.png
7436 and select \gui Configure.... to open the \gui Locator options.
7438 \image qtcreator-locator-customize.png
7441 \o In the \gui{Filter Configuration} dialog:
7443 \o Name your filter.
7444 \o Select at least one directory. The locator searches directories
7446 \o Define the file pattern as a comma separated list. For example,
7447 to search all .h and .cpp files, enter \bold{*.h,*.cpp}
7448 \o Specify the prefix string.
7450 To show only results matching this filter, select
7451 \gui{Limit to prefix}.
7453 \image qtcreator-navigate-customfilter.png
7458 \section2 Adding Web Search Engines
7460 You can use the \gui {Web Search (\c r)} locator filter to perform
7461 web searches. URLs and search commands for Bing, Google, Yahoo! Search,
7462 cplusplus.com, and Wikipedia are configured by default.
7464 To find out the format of the search command to use for your favorite
7465 web search engine, perform a search in your browser and copy the resulting
7466 URL to the locator filter configuration. Replace the search term with the
7469 To add URLs and search commands to the list:
7473 \o Select \gui {Tools > Options > Locator > Web Search (prefix: r) >
7476 \o Select \gui Add to add a new entry to the list.
7478 \image qtcreator-add-online-doc.png "Filter Configuration dialog"
7480 \o Double-click the new entry to specify a URL and a search command.
7481 For example, http://www.google.com/search?q=%1.
7487 \section2 Configuring the Locator Cache
7489 The locator searches the files matching your file pattern in the
7490 directories you have selected and caches that information. The cache for
7491 all default filters is updated as you write your code. By default,
7492 Qt Creator updates the filters created by you once an hour.
7494 To update the cached information manually, click
7495 \inlineimage qtcreator-locator-magnify.png
7496 and select \gui Refresh.
7498 To set a new cache update time:
7500 \o Select \gui Tools > \gui Options... > \gui Locator.
7501 \o In \gui{Refresh interval}, define new time in minutes.
7508 \contentspage index.html
7509 \previouspage creator-developing-symbian.html
7510 \page creator-project-managing-sessions.html
7511 \nextpage creator-coding.html
7513 \title Managing Sessions
7515 When you exit Qt Creator, a snapshot of your current workspace is stored
7516 as a \e session. To restore the session automatically when you start Qt
7517 Creator, select \gui {File > Session Manager > Restore last session on
7520 A session is an arbitrary collection of:
7523 \o Open projects with their dependencies (including SUBDIRS projects)
7525 \o Breakpoints and expressions
7529 A session is personal, that is, not meant to be shared. It is not
7530 supposed to reflect the project structure. It contains personal data, such as
7531 bookmarks and breakpoints that are usually not of interest to other developers
7532 working on the same projects.
7534 For example, if you work on a project and need to switch to another project for a
7535 while, you can save your workspace as a session. This makes it easier
7536 to return to working on the first project later.
7538 To create a new session or remove existing sessions, select \gui File >
7539 \gui{Session Manager}.
7541 \image qtcreator-session-manager.png
7543 To switch between sessions, choose
7544 \gui {File > Session Manager}. If you do not create or select a session,
7545 Qt Creator always uses the default session, which was created the
7546 last time you exited Qt Creator.
7548 When you launch Qt Creator, a list of existing sessions is displayed on the
7549 \gui{Welcome screen}.
7551 \image qtcreator-welcome-session.png
7557 \contentspage index.html
7558 \previouspage creator-build-dependencies.html
7559 \page creator-debugging.html
7560 \nextpage creator-debugging-example.html
7564 Qt Creator provides a debugger plugin that acts
7565 as an interface between the Qt Creator core and external native debuggers
7566 such as the GNU Symbolic Debugger (GDB), the Microsoft Console Debugger (CDB),
7567 and a QML/JavaScript debugger.
7569 The following sections describe debugging with Qt Creator:
7573 \o \l{Debugging the Example Application} uses an example application
7574 to illustrate how to debug Qt C++ applications in the \gui Debug
7577 \o \l{Launching the Debugger} describes the
7578 operating modes in which the debugger plugin runs, depending on
7579 where and how the process is started and run.
7581 \o \l{Interacting with the Debugger} describes the views and functions
7582 available in the \gui Debug mode.
7584 \o \l{Setting Up Debugger} summarizes the support for debugging C++
7585 code and requirements for installation. Typically, the interaction
7586 between Qt Creator and the native debugger is set up automatically
7587 and you do not need to do anything.
7589 \o \l{Using Debugging Helpers} describes how to get more detailed data
7592 \o \l{Debugging Qt Quick Projects} describes how to debug Qt Quick
7595 \o \l{Troubleshooting Debugger} lists some typical problems that you
7596 might encounter while debugging and solutions to them.
7603 \contentspage index.html
7604 \previouspage creator-debugging-example.html
7605 \page creator-debugger-operating-modes.html
7606 \nextpage creator-debug-mode.html
7608 \title Launching the Debugger
7610 To start a program under the control of the debugger, select \gui{Debug} >
7611 \gui{Start Debugging} > \gui{Start Debugging}, or press \key{F5}.
7612 Qt Creator checks whether the compiled program is up-to-date, and rebuilds
7613 it if necessary. The debugger then takes over and starts the program.
7615 \note Starting a program in the debugger can take a long
7616 time, typically in the range of several seconds to minutes if complex
7617 features (like QtWebKit) are used.
7619 The debugger is launched in the appropriate operating mode (plain, terminal,
7620 or on-device), based on the build and run settings for the active project.
7621 Select \gui Debug menu options to launch the debugger in other modes.
7623 \note Debugging QML and JavaScript is supported only in plain mode.
7625 \section1 Launching the Debugger in Different Modes
7627 The debugger plugin runs in different operating modes depending on where and
7628 how the process is started and run. Some of the modes are only available for
7629 a particular operating system or platform.
7631 You can launch the debugger in the following modes:
7635 \o \bold Plain to debug locally started applications, such as a
7636 Qt based GUI application.
7638 \o \bold Terminal to debug locally started processes that need a
7639 console, typically without a GUI.
7641 \o \bold Attach to debug local processes started outside Qt Creator.
7643 \o \bold Remote to debug a process running on a different machine.
7645 \o \bold Core to debug crashed processes on Unix.
7647 \o \bold Post-mortem to debug crashed processes on Windows.
7649 \o \bold On-device to debug processes running on a mobile device.
7653 \note Debugging QML and JavaScript is supported only in plain mode.
7655 \section2 Launching in Plain Mode
7657 To launch the debugger in the plain mode, click the \gui {Start Debugging}
7658 button for the active project, or choose
7659 \gui {Debug > Start Debugging > Start and Debug External Application...}
7660 and specify an executable.
7662 \section2 Launching in Terminal Mode
7664 To launch the debugger in the terminal mode, select \gui {Projects > Run Settings}
7665 and select the \gui {Run in terminal} check box. Then click the
7666 \gui {Start Debugging} button for the active project.
7668 \section2 Launching in Attach Mode
7670 To launch the debugger in the attach mode, select
7671 \gui {Debug > Start Debugging > Attach to Running External Application...},
7672 and then select a process by its name or process ID to attach to.
7674 You can load the source project in advance and set breakpoints in it before
7675 attaching to an already running process. For more information, see
7676 \l{Setting Breakpoints}.
7678 \section2 Launching in Remote Mode
7680 The remote mode allows you to debug processes that run on remote machines.
7684 In remote mode, the local GDB process talks to a GDB server
7685 process running on the remote machine that controls the process to be
7688 The GDB server process is started on the remote machines by passing a port
7689 number and the executable:
7692 gdbserver :1234 <executable>
7695 It then typically responds:
7697 Process bin/qtcreator created; pid = 5159
7698 Listening on port 1234
7701 On the local machine that runs Qt Creator:
7705 \o Select \gui {Debug > Start Debugging > Start and Attach to Remote
7708 \o In the \gui {Host and port} field, enter the name of the remote
7709 machine and the port number to use.
7711 \o Select \gui{OK} to start debugging.
7717 In remote mode, the local CDB process talks to a CDB process that
7718 runs on the remote machine. The process is started with special
7719 command line options that switch it into server mode. The remote CDB
7720 process must load the Qt Creator CDB extension library that is shipped with
7725 \o Install the \e{Debugging Tools for Windows} on the remote machine.
7726 The installation folder contains the CDB command line executable (cdb.exe).
7728 \o Copy the Qt Creator CDB extension library from the Qt installation
7729 directory to the a new folder on the remote machine
7730 (32 or 64 bit version depending on the version of the Debugging
7736 \o \c {\lib\qtcreatorcdbext32\qtcreatorcdbext.dll} (32 bit)
7738 \o \c {\lib\qtcreatorcdbext64\qtcreatorcdbext.dll} (64 bit)
7742 \o Set the _NT_DEBUGGER_EXTENSION_PATH environment variable to point
7745 \o To use TCP/IP as communication protocol, launch remote CDB as
7749 cdb.exe -server tcp:port=1234 <executable>
7752 \o On the local machine running Qt Creator, select
7753 \gui {Debug > Start Debugging > Attach to Remote CDB Session...}
7756 \o In the \gui Connection field enter the connection parameters.
7757 For example, for TCP/IP:
7763 If you chose some other protocol, specify one of the alternative
7767 tcp:server=Server,port=Port[,password=Password][,ipversion=6]
7768 tcp:clicon=Server,port=Port[,password=Password][,ipversion=6]
7769 npipe:server=Server,pipe=PipeName[,password=Password]
7770 com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
7771 spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
7772 ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
7773 ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
7776 \o Click \gui{OK} to start debugging.
7780 \section2 Launching in Core Mode
7782 The core mode it used to debug \e {core} files (crash dumps) that are
7783 generated from crashed processes if the system is set up to allow this.
7785 To enable the dumping of core files on a Unix system enter the following
7786 command in the shell from which the application will be launched:
7792 To launch the debugger in the core mode, select
7793 \gui{Debug > Start Debugging > Attach to Core...}.
7795 \section2 Launching in Post-Mortem Mode
7797 The post-mortem mode is available only on Windows, if you have installed
7798 the debugging tools for Windows.
7800 The Qt Creator installation program asks you whether you want to
7801 register Qt Creator as a post-mortem debugger. To change the setting, select
7802 \gui{Tools > Options... > Debugger > Common > Use Creator for post-mortem debugging}.
7804 You can launch the debugger in the post-mortem mode if an application crashes
7805 on Windows. Click the \gui {Debug in Qt Creator} button in the error message
7806 that is displayed by the Windows operating system.
7808 \section2 Launching in On-device Mode
7810 The on-device mode is a special mode available for run configurations
7811 targeting mobile devices. It debugs processes running on mobile
7812 devices using on-device debugging agents, such as CODA on Symbian and
7813 gdbserver on Maemo and MeeGo Harmattan.
7815 To launch the debugger in the on-device mode, open the project, select a
7816 run configuration that targets a mobile device, and click the
7817 \gui {Start Debugging} button.
7822 \contentspage index.html
7823 \previouspage creator-debug-mode.html
7824 \page creator-debugger-engines.html
7825 \nextpage creator-debugging-helpers.html
7827 \title Setting Up Debugger
7829 \note The information in this section applies only to debugging the C++
7832 Typically, the interaction between Qt Creator and the native debugger is set
7833 up automatically and you do not need to do anything. However, you might have an
7834 unsupported GDB version installed, your Linux environment might not have GDB
7835 installed at all, or you might want to use the debugging tools for Windows.
7837 \note To use the debugging tools for Windows, you must install them and add the
7838 Symbol Server provided by Microsoft to the symbol search path of the debugger.
7839 For more information, see \l{Setting the Symbol Server in Windows}.
7841 This section explains the
7842 options you have for debugging C++ code and provides installation notes for the
7843 supported native debuggers.
7845 \section1 Supported Native Debugger Versions
7847 The debugger plugin supports different builds of the GDB debugger, both
7848 with and without the ability to use Python scripting. The Python enabled
7849 versions are preferred, but they are not available on Mac and on older
7851 On Windows, Symbian, Maemo, and MeeGo Harmattan, only the Python version is
7854 The non-Python versions use the compiled version of the debugging helpers,
7855 that you must enable separately. For more information, see
7856 \l{Debugging Helpers Based on C++}.
7858 The Python version uses a script version of the debugging helpers
7859 that does not need any special setup.
7861 The CDB native debugger has similar funtionality to the non-Python GDB debugger
7862 engine. Specifically, it also uses compiled C++ code for the debugging
7865 The following table summarizes the support for debugging C++ code:
7879 \o Plain, Terminal, Attach, Remote, Core
7885 \o Plain, Terminal, Attach, Remote, Core
7891 \o Plain, Terminal, Attach, Core
7897 \o Plain, Terminal, Attach, Remote, Core
7900 \o Microsoft Visual C++ Compiler
7901 \o Debugging Tools for Windows/CDB
7903 \o Plain, Terminal, Attach, Post-Mortem
7924 For more information on the debugger modes, see \l{Launching the Debugger in Different Modes}.
7928 \section2 GDB Adapter Modes
7932 The GDB native debugger used internally by the debugger plugin runs in
7933 different adapter modes to cope with the variety
7934 of supported platforms and environments. All GDB adapters inherit from
7939 \o PlainGdbAdapter debugs locally started GUI processes.
7940 It is physically split into parts that are relevant only when Python is
7941 available, parts relevant only when Python is not available, and mixed code.
7943 \o TermGdbAdapter debugs locally started processes that need a
7946 \o AttachGdbAdapter debugs local processes started outside Qt Creator.
7948 \o CoreGdbAdapter debugs core files generated from crashes.
7950 \o RemoteGdbAdapter interacts with the gdbserver running on Linux.
7952 \o CodaGdbAdapter interacts with Symbian devices. The GDB protocol and
7953 the GDB serial protocol are used between GDB and the adapter. The
7954 target communication framework (TCF) protocol is used between the
7955 adapter and the CODA debugging agent running on the device.
7961 \section1 Installing Native Debuggers
7963 There are various reasons why the debugger plugin may fail to automatically
7964 pick up a suitable native debugger. The native debugger might be missing
7965 (which is usually the case for the CDB debugger on Windows which always
7966 needs to be installed manually by the user) or the installed version is not
7968 Check the table below for the supported versions and other important
7969 information about installing native debuggers.
7977 \o On Linux and Windows, use the Python-enabled GDB versions that
7978 are installed when you install Qt Creator and Qt SDK. On Mac OS X,
7979 use the GDB provided with Xcode.
7980 For a custom target, you can build your own Python-enabled GDB.
7981 Follow the instructions on
7982 \l{http://developer.qt.nokia.com/wiki/QtCreatorBuildGdb}{Building GDB}.
7983 You must use at least Python version 2.5, but we recommend that you
7987 \o Debugging tools for Windows
7988 \o Using this engine requires you to install the
7989 \e{Debugging tools for Windows}
7990 \l{http://www.microsoft.com/whdc/devtools/debugging/installx86.Mspx}
7992 \l{http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx}
7993 package (Version 6.12 for the 32-bit or the 64-bit version
7994 of Qt Creator, respectively),
7995 which are freely available for download from the
7996 \l{http://msdn.microsoft.com/en-us/default.aspx}{Microsoft Developer Network}.
7998 The Qt Creator help browser does
7999 not allow you to download files, and therefore, you must copy
8000 the above links to a browser.
8002 \note Visual Studio does not include the Debugging tools needed,
8003 and therefore, you must install them separately.
8005 The pre-built \QSDK for Windows makes use of the library if it
8006 is present on the system. When manually building Qt Creator using
8007 the Microsoft Visual C++ Compiler, the build process checks for the
8008 required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}.
8010 It is highly recommended that you add the Symbol Server provided
8011 by Microsoft to the symbol search path of the debugger. The Symbol
8012 Server provides you with debugging informaton for the operating
8013 system libraries for debugging Windows applications. For more
8014 information, see \l{Setting the Symbol Server in Windows}.
8017 \o Debugging tools for Mac OS X
8018 \o The Qt binary distribution contains both debug and release
8019 variants of the libraries. But you have to explicitly tell the
8020 runtime linker that you want to use the debug libraries even if
8021 your application is compiled as debug as release is the default
8024 If you use a qmake based project in Qt Creator, you can set a
8025 flag in your run configuration, in \gui Projects mode. In the run
8026 configuration, select \gui{Use debug version of frameworks}.
8028 For more detailed information about debugging on the Mac OS X, see:
8029 \l{http://developer.apple.com/mac/library/technotes/tn2004/tn2124.html}{Mac OS X Debugging Magic}.
8031 \note The Mac OS X Snow Leopard (10.6) has a bug that might cause the
8032 application to crash. For a workaround, see:
8033 \l{http://bugreports.qt.nokia.com/browse/QTBUG-4962}{QTBUG-4962}.
8037 \section1 Setting the Symbol Server in Windows
8039 To obtain debugging information for the operating system libraries for
8040 debugging Windows applications, add the Symbol Server provided
8041 by Microsoft to the symbol search path of the debugger:
8043 \o Select \gui Tools > \gui{Options...} > \gui Debugger > \gui CDB.
8044 \o In the \gui {Symbol paths} field, open the \gui{Insert...} menu
8045 and select \gui{Symbol Server...}.
8046 \o Select a directory where you want to store the cached information
8049 Use a subfolder in a temporary directory, such as
8050 \c {C:\temp\symbolcache}.
8053 \note Populating the cache might take a long time on a slow network
8056 \note The first time you start debugging by using the
8057 Debugging tools for Windows, Qt Creator prompts you to add the Symbol
8063 \contentspage index.html
8064 \previouspage creator-debugger-operating-modes.html
8065 \page creator-debug-mode.html
8066 \nextpage creator-debugger-engines.html
8068 \title Interacting with the Debugger
8070 In \gui Debug mode, you can use several views to interact with the
8071 program you are debugging. The availability of views depends on whether
8072 you are debugging C++ or QML. Frequently used views are shown by
8073 default and rarely used ones are hidden. To change the default settings,
8074 select \gui {Window > Views}, and then select views to display or hide.
8076 \image qtcreator-debugger-views.png "Debug mode views"
8078 By default, the views are locked into place in the workspace. Select
8079 \gui {Window > Views > Locked} to unlock the views. Drag and drop the
8080 views into new positions on the screen. Drag view borders to resize the
8081 views. The size and position of views are saved for future sessions.
8083 \section1 Using the Debugger
8085 Once the program starts running under the control of the debugger, it
8086 behaves and performs as usual. You can interrupt a running C++ program by
8087 selecting \gui{Debug} > \gui {Interrupt}. The program is automatically
8088 interrupted when a breakpoint is hit.
8090 Once the program stops, Qt Creator:
8093 \o Retrieves data representing the call stack at the program's current
8095 \o Retrieves the contents of local variables.
8096 \o Examines \gui Expressions.
8097 \o Updates the \gui Registers, \gui Modules, and \gui Disassembler
8098 views if you are debugging the C++ based applications.
8101 You can use the \gui Debug mode views to examine the data in more detail.
8103 You can use the following keyboard shortcuts:
8107 \o To finish debugging, press \key{Shift+F5}.
8108 \o To execute a line of code as a whole, press \key{F10}.
8109 \o To step into a function or a subfunction, press \key{F11}.
8110 \o To continue running the program, press \key{F5}.
8111 \o To run to the selected function when you are stepping into a nested
8112 function, press \key{Ctrl+F6}.
8116 It is also possible to continue executing the program until the current
8117 function completes or jump to an arbitrary position in the current function.
8120 \section1 Setting Breakpoints
8122 A breakpoint represents a position or sets of positions in the code that,
8123 when executed, interrupts the program being debugged and passes the control
8124 to you. You can then examine the state of the interrupted program, or
8125 continue execution either line-by-line or continuously.
8127 Qt Creator shows breakpoints in the \gui{Breakpoints} view which is enabled
8128 by default. The \gui{Breakpoints} view is also accessible when the debugger
8129 and the program being debugged is not running.
8131 \image qtcreator-debug-breakpoints.png "Breakpoints view"
8133 You can associate breakpoints with:
8137 \o Source code files and lines
8143 \o Throwing and catching exceptions
8145 \o Executing and forking processes
8147 \o Executing some system calls
8149 \o Changes in a block of memory at a particular address when a
8154 The interruption of a program by a breakpoint can be restricted with
8157 To set a breakpoint at a particular line you want the program to stop,
8158 click the left margin or press \key F9 (\key F8 for Mac OS X).
8160 To set breakpoints, select \gui {Add Breakpoint...} in
8161 the context menu in the \gui Breakpoints view.
8163 \image qtcreator-add-breakpoint.png "Add Breakpoints" dialog
8165 \note You can remove a breakpoint:
8167 \o By clicking the breakpoint marker in the text editor.
8168 \o By selecting the breakpoint in the breakpoint view and pressing
8170 \o By selecting \gui{Delete Breakpoint} from the context
8171 menu in the \gui Breakpoints view.
8174 You can set and delete breakpoints before the program starts running or
8175 while it is running under the debugger's control. Breakpoints are saved
8176 together with a session.
8178 \section2 Setting Data Breakpoints
8180 To set a data breakpoint at an address:
8184 \o Right-click in the \gui Breakpoints view to open the context menu,
8185 and select \gui {Add Breakpoint...}.
8187 \o In the \gui {Breakpoint type} field, select \gui {Break on data
8188 access at fixed address}.
8190 \o In the \gui Address field, specify the address of the memory block.
8196 If the address is displayed in the \gui {Locals and Expressions} view, you can
8197 select \gui {Add Data Breakpoint at Object's Address} in the context menu to set
8198 the data breakpoint.
8200 \section1 Viewing Call Stack Trace
8202 When the program being debugged is interrupted, Qt Creator displays the
8203 nested function calls leading to the current position as a call stack
8204 trace. This stack trace is built up from call stack frames, each
8205 representing a particular function. For each function, Qt Creator tries
8206 to retrieve the file name and line number of the corresponding source
8207 file. This data is shown in the \gui Stack view.
8209 \image qtcreator-debug-stack.png
8211 Since the call stack leading to the current position may originate or go
8212 through code for which no debug information is available, not all stack
8213 frames have corresponding source locations. Stack frames without
8214 corresponding source locations are grayed out in the \gui{Stack} view.
8216 If you click a frame with a known source location, the text editor
8217 jumps to the corresponding location and updates the \gui{Locals and Expressions}
8218 view, making it seem like the program was interrupted before entering the
8221 \section1 Locals and Expressions
8223 Whenever a program stops under the control of the debugger, it retrieves
8224 information about the topmost stack frame and displays it in the
8225 \gui{Locals and Expressions} view. The \gui{Locals and Expressions} view
8226 typically includes information about parameters of the function in that
8227 frame as well as the local variables.
8229 \image qtcreator-watcher.png "Locals and Expressions view"
8231 Compound variables of struct or class type are displayed as
8232 expandable in the view. Expand entries to show
8233 all members. Together with the display of value and type, you can
8234 examine and traverse the low-level layout of object data.
8242 \i GDB, and therefore Qt Creator's debugger works for optimized
8243 builds on Linux and Mac OS X. Optimization can lead to
8244 re-ordering of instructions or removal of some local variables,
8245 causing the \gui{Locals and Expressions} view to show unexpected
8248 \i The debug information provided by GCC does not include enough
8249 information about the time when a variable is initialized.
8250 Therefore, Qt Creator can not tell whether the contents of a
8251 local variable contains "real data", or "initial noise". If a
8252 QObject appears uninitialized, its value is reported as
8253 \gui {not in scope}. Not all uninitialized objects, however, can be
8258 The \gui{Locals and Expressions} view also provides access to the most
8259 powerful feature of the debugger: comprehensive display of data belonging
8260 to Qt's basic objects.
8262 To enable Qt's basic objects data display feature:
8264 \o Select \gui Tools > \gui {Options...} > \gui Debugger >
8265 \gui{Debugging Helper} and check the \gui{Use Debugging Helper}
8267 \o The \gui{Locals and Expressions} view is reorganized to provide a
8268 high-level view of the objects.
8271 For example, in case of QObject, instead of displaying a pointer to some
8272 private data structure, you see a list of children, signals and slots.
8274 Similarly, instead of displaying many pointers and integers, Qt Creator's
8275 debugger displays the contents of a QHash or QMap in an orderly manner.
8276 Also, the debugger displays access data for QFileInfo and provides
8277 access to the "real" contents of QVariant.
8279 You can use the \gui{Locals and Expressions} view to change the contents of
8280 variables of simple data types, for example, \c int or \c float when the
8281 program is interrupted. To do so, click the \gui Value column, modify
8282 the value with the inplace editor, and press \key Enter (or \key Return).
8284 You can enable tooltips in the main editor displaying this information.
8285 For more information, see \l{Showing Tooltips in Debug Mode}.
8287 \note The set of evaluated expressions is saved in your session.
8289 \section1 Directly Interacting with Native Debuggers
8291 In some cases, it is convenient to directly interact with the command
8292 line of the native debugger. In Qt Creator, you can use the left
8293 pane of the \gui {Debugger Log} view for that purpose. When you press
8294 \key {Ctrl+Return}, the contents of the line under the text cursor
8295 are sent directly to the native debugger. Alternatively, you
8296 can use the line edit at the bottom of the view. Output is displayed in the
8297 right pane of the \gui {Debugger Log} view.
8299 \note Usually, you do not need this feature, because Qt Creator provides
8300 you with better ways to handle the task. For example, instead of using the
8301 GDB \c print command from the command line, you can evaluate an expression
8302 in the \gui{Locals and Expressions} view.
8304 \section1 Debugging C++ Based Applications
8306 The following sections describe additional debugging functions that apply
8307 only to debugging C++.
8309 \section2 Starting the Debugger from the Command Line
8311 You can use the Qt Creator debugger interface from the command line. To
8312 attach it to a running process, specify the process ID as a parameter for
8313 the \c {-debug} option. To examine a core file, specify the file name.
8314 Qt Creator executes all the necessary steps, such as searching for
8315 the binary that belongs to a core file.
8321 \o \c {C:\qtcreator\bin>qtcreator -debug 2000}
8323 \o \c {C:\qtcreator\bin>qtcreator -debug core.2000}
8327 For more information, see \l{Using Command Line Options}.
8329 \section2 Stepping into Frameworks in Mac OS
8331 In Mac OS X, external libraries are usually built into so-called Frameworks,
8332 which may contain both release and debug versions of the library. When you run
8333 applications on the Mac OS desktop, the release version of Frameworks is used
8334 by default. To step into Frameworks, select the \gui {Use debug versions of
8335 Frameworks} option in the project run settings for \gui Desktop and
8336 \gui {Qt Simulator} targets.
8338 \section2 Viewing Threads
8340 If a multi-threaded program is interrupted, the \gui Thread view or the
8341 combobox named \gui Thread in the debugger's status bar can be used to
8342 switch from one thread to another. The \gui Stack view adjusts itself
8345 \section2 Viewing Modules
8347 The \gui{Modules} view displays information that the debugger plugin has
8348 about modules included in the application that is being debugged. A module
8349 is a dynamic link library (.dll) in Windows, a shared object (.so) in
8350 Linux, and a dynamic shared library (.dylib) in Mac OS.
8352 In addition, the view displays symbols within the modules and indicates
8353 where each module was loaded.
8355 Right-click the view to open a context menu that contains menu items for:
8359 \o Updating the module list
8361 \o Loading symbols for modules
8363 \o Examining modules
8365 \o Editing module files
8367 \o Showing symbols in modules
8369 \o Showing dependencies between modules (Windows only)
8373 By default, the \gui{Modules} view is hidden.
8375 \section2 Viewing Source Files
8377 The \gui{Source Files} view lists all the source files included in the project.
8378 If you cannot step into an instruction, you can check whether the source file is
8379 actually part of the project, or whether it was compiled
8380 elsewhere. The view shows the path to each file in the file system.
8382 Right-click the view to open a context menu that contains menu items for
8383 reloading data and opening files.
8385 By default, the \gui{Source Files} view is hidden.
8388 \section2 Viewing Disassembled Code and Register State
8390 The \gui{Disassembler} view displays disassembled code for the current
8391 function. The \gui{Registers} view displays the current state of the CPU's
8394 The \gui{Disassembler} view and the \gui{Registers} view are both useful
8395 for low-level commands for checking single instructions, such as \gui{Step Into}
8396 and \gui{Step Over}. By default, both \gui{Disassembler} and
8397 \gui{Registers} view are hidden.
8403 \contentspage index.html
8404 \previouspage creator-debugging.html
8405 \page creator-debugging-example.html
8406 \nextpage creator-debugger-operating-modes.html
8408 \title Debugging the Example Application
8410 This section uses the \l{Creating a Qt Widget Based Application}{TextFinder} example to
8411 illustrate how to debug Qt C++ applications in the \gui Debug mode.
8414 reads a text file into
8415 QString and then displays it with QTextEdit.
8416 To look at the example QString, \c{line}, and see the
8417 stored data, place a breakpoint and view the QString object
8418 data in textfinder.cpp, as follows:
8421 \o Click in between the line number and the window border on the line
8422 where we invoke \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}
8423 to set a breakpoint.
8425 \image qtcreator-setting-breakpoint1.png
8427 \o Select \gui{Debug > Start Debugging > Start Debugging} or press \key{F5}.
8430 \o To view the breakpoint, click the \gui{Breakpoints} tab.
8432 \image qtcreator-setting-breakpoint2.png
8434 \o To remove a breakpoint, right-click it and select \gui{Delete Breakpoint}.
8437 \o To view the contents of \c{line}, go to the \gui{Locals and
8440 \image qtcreator-watcher.png
8444 Modify the \c{on_findButton_clicked()} function to move back to
8445 the start of the document and continue searching once the cursor hits the
8446 end of the document. Add the following code snippet:
8449 void TextFinder::on_findButton_clicked()
8451 QString searchString = ui->lineEdit->text();
8453 QTextDocument *document = ui->textEdit->document();
8454 QTextCursor cursor = ui->textEdit->textCursor();
8455 cursor = document->find(searchString, cursor,
8456 QTextDocument::FindWholeWords);
8457 ui->textEdit->setTextCursor(cursor);
8459 bool found = cursor.isNull();
8461 if (!found && previouslyFound) {
8462 int ret = QMessageBox::question(this, tr("End of Document"),
8463 tr("I have reached the end of the document. Would you like "
8464 "me to start searching from the beginning of the document?"),
8465 QMessageBox::Yes | QMessageBox::No, QMessageBox::Yes);
8467 if (ret == QMessageBox::Yes) {
8468 cursor = document->find(searchString,
8469 QTextDocument::FindWholeWords);
8470 ui->textEdit->setTextCursor(cursor);
8474 previouslyFound = found;
8478 If you compile and run the above code, however, the application does not
8479 work correctly due to a logic error. To locate this logic error, step
8480 through the code using the following buttons:
8482 \image qtcreator-debugging-buttons.png
8488 \contentspage index.html
8489 \previouspage creator-debugger-engines.html
8490 \page creator-debugging-helpers.html
8491 \nextpage creator-debugging-qml.html
8493 \title Using Debugging Helpers
8495 Qt Creator is able to show complex data types in a customized,
8496 user-extensible manner. For this purpose, it takes advantage of
8497 two technologies, collectively referred to as \e{Debugging Helpers}.
8499 Using the debugging helpers is not \e essential for debugging
8500 with Qt Creator, but they enhance the user's ability to quickly
8501 examine complex data significantly.
8503 \section1 Debugging Helpers Based on C++
8505 This is the first and original approach to display complex data
8506 types. While it has been superseded on most platforms by the more
8507 robust and more flexible second approch using Python scripting,
8508 it is the only feasible one on Windows/MSVC, Mac OS, and
8509 old Linux distributions. Moreover, this approach will automatically
8510 be chosen as fallback in case the Python based approach fails.
8512 During debugging with the C++ based debugging helpers,
8513 Qt Creator dynamically loads a helper library in form of a DLL or a
8514 shared object into the debugged process.
8515 The \QSDK package already contains a prebuilt debugging helper
8516 library. To create your own debugging helper library, select \gui{Tools} >
8517 \gui{Options...} > \gui{Qt4} > \gui{Qt Versions}. As the internal data
8518 structures of Qt can change between versions, the debugging helper
8519 library is built for each Qt version.
8522 \section1 Debugging Helpers Based on Python
8524 Qt Creator uses GDB builds that enable Python scripting to display
8525 information in the \gui {Locals and Expressions} view. When Python scripting
8526 is used, code (Debugging helpers) does not need to be injected into the
8527 debugged process to nicely display QStringList or \c std::map contents, for
8530 The code injection caused problems and put an extra stress on the debugged
8531 process. You can now easily extend the debugging helpers to other types. No
8532 compilation is required, just adding a few lines of Python.
8534 Python scripting vastly reduces the communication overhead compared
8535 with the previous solution. However, there are some obstacles:
8539 \o There is no Python-enabled GDB for Mac OS. Mac OS continues
8540 injection with C++ based debugging helpers.
8542 \o On the Symbian platform, an on-device debugging agent restricts the
8543 communication between GDB and the device. Therefore, extracting
8544 QObject properties, for example, is not possible.
8546 \o There is no GDB to communicate with MSVC compiled applications on
8547 Windows. So information can be displayed nicely only in a limited
8548 fashion by using a cdb extension DLL.
8552 \section2 Extending the Python Based Debugging Helpers
8554 On platforms featuring a Python-enabled version of the GDB debugger,
8555 the data extraction is done by a Python script. This is more robust
8556 as the script execution is separated from the debugged process. It
8557 is also easier to extend as the script is less dependent on the
8558 actual Qt version and does not need compilation.
8560 To extend the shipped Python based debugging helpers for custom types,
8561 define one Python function per user defined type in the
8562 GDB startup file. By default, the following startup file is used:
8563 \c{~/.gdbinit}. To use another file, select \gui {Tools > Options... >
8565 and specify a filename in the \gui {GDB startup script} field.
8567 The function name has to be qdump__NS__Foo, where NS::Foo is the class
8568 or class template to be examined. Nested namespaces are possible.
8570 The debugger plugin calls this function whenever you want to
8571 display an object of this type. The function is passed the following
8574 \o \c d of type \c Dumper
8575 \o \c item of type \c Item
8578 The function has to feed the Dumper object with certain information
8579 which is used to build up the object and its children's display in the
8580 \gui{Locals and Expressions} view.
8586 def qdump__QVector(d, item):
8587 d_ptr = item.value["d"]
8588 p_ptr = item.value["p"]
8589 alloc = d_ptr["alloc"]
8590 size = d_ptr["size"]
8592 check(0 <= size and size <= alloc and alloc <= 1000 * 1000 * 1000)
8593 check(d_ptr["ref"]["_q_value"] > 0)
8595 innerType = item.value.type.template_argument(0)
8596 d.putItemCount(size)
8598 if d.isExpanded(item):
8599 p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
8600 with Children(d, [size, 2000], innerType)
8601 for i in d.childRange():
8602 d.putSubItem(Item(p.dereference(), item.iname, i))
8606 \section2 Item Class
8608 The Item Python class is a thin wrapper around values corresponding to one
8609 line in the \gui{Locals and Expressions} view. The Item members are as follows :
8613 \o \gui{__init__(self, value, parentiname, iname, name = None)} - A
8614 constructor. The object's internal name is created by concatenating
8615 \c parentiname and \c iname. If \c None is passed as \c name, a
8616 serial number is used.
8618 \o \gui{value} - An object of type gdb.Value representing the value to
8621 \o \gui{iname} - The internal name of the object, constituting a dot-separated
8622 list of identifiers, corresponding to the position of the object's
8623 representation in the view.
8625 \o \gui{name} - An optional name. If given, is used in the
8626 \gui{name} column of the view. If not, a simple number in brackets
8632 \section2 Dumper Class
8634 For each line in the \gui{Locals and Expressions} view, a string like the
8635 following needs to be created and channeled to the debugger plugin.
8637 "{iname='some internal name',
8638 addr='object address in memory',
8639 name='contents of the name column',
8640 value='contents of the value column',
8641 type='contents of the type column',
8642 numchild='number of children', // zero/nonzero is sufficient
8643 childtype='default type of children', // optional
8644 childnumchild='default number of grandchildren', // optional
8645 children=[ // only needed if item is expanded in view
8646 {iname='internal name of first child',
8648 {iname='internal name of second child',
8654 While in theory, you can build up the entire string above manually, it is
8655 easier to employ the Dumper Python class for that purpose. The Dumper
8656 Python class contains a complete framework to take care of the \c iname and
8657 \c addr fields, to handle children of simple types, references, pointers,
8658 enums, known and unknown structs as well as some convenience methods to
8659 handle common situations.
8661 The Dumper members are the following:
8665 \o \gui{__init__(self)} - Initializes the output to an empty string and
8666 empties the child stack.
8668 \o \gui{put(self, value)} - Low level method to directly append to the
8671 \o \gui{putCommaIfNeeded(self)} - Appends a comma if the current output
8672 ends in '}', '"' or ']' .
8674 \o \gui{putField(self, name, value)} - Appends a comma if needed, and a
8677 \o \gui{beginItem(self, name)} - Starts writing a field by writing \c {name='}.
8679 \o \gui{endItem(self)} - Ends writing a field by writing \c {'}.
8681 \o \gui{endChildren(self)} - Ends writing a list of children.
8683 \o \gui{childRange(self)} - Returns the range of children specified in
8684 the current \c Children scope.
8686 \o \gui{putItemCount(self, count)} - Appends a field \c {value='<%d items'}
8689 \o \gui{putEllipsis(self)} - Appends fields
8690 \c {'{name="<incomplete>",value="",type="",numchild="0"}'}. This is
8691 automatically done by \c endChildren if the number of children to
8692 print is smaller than the number of actual children.
8694 \o \gui{putName(self, name)} - Appends a \c {name='...'} field.
8696 \o \gui{putType(self, type)} - Appends a field \c {type='...'} unless the
8697 \a type coincides with the parent's default child type.
8699 \o \gui{putNumChild(self, numchild)} - Appends a field \c {numchild='...'}
8700 unless the \c numchild coincides with the parent's default child numchild
8703 \o \gui{putValue(self, value, encoding = None)} - Append a file \c {value='...'},
8704 optionally followed by a field \c {valueencoding='...'}. The \c value
8705 needs to be convertible to a string entirely consisting of
8706 alphanumerical values. The \c encoding parameter can be used to
8707 specify the encoding in case the real value had to be encoded in some
8708 way to meet the alphanumerical-only requirement.
8709 Currently the following encodings are supported:
8712 \o 0: unencoded 8 bit data, interpreted as Latin1.
8714 \o 1: base64 encoded 8 bit data, used for QByteArray,
8715 double quotes are added.
8717 \o 2: base64 encoded 16 bit data, used for QString,
8718 double quotes are added.
8720 \o 3: base64 encoded 32 bit data,
8721 double quotes are added.
8723 \o 4: base64 encoded 16 bit data, without quotes (see 2)
8725 \o 5: base64 encoded 8 bit data, without quotes (see 1)
8727 \o 6: %02x encoded 8 bit data (as with \c QByteArray::toHex),
8728 double quotes are added.
8730 \o 7: %04x encoded 16 bit data (as with \c QByteArray::toHex),
8731 double quotes are added.
8734 \o \gui{putStringValue(self, value)} - Encodes a QString and calls
8735 \c putValue with the correct \c encoding setting.
8737 \o \gui{putByteArrayValue(self, value)} - Encodes a QByteArray and calls
8738 \c putValue with the correct \c encoding setting.
8740 \o \gui{isExpanded(self, item)} - Checks whether the item with the
8741 internal name \c item.iname is expanded in the view.
8743 \o \gui{isExpandedIName(self, iname)} - Checks whether the item with the
8744 internal name \c iname is expanded in the view.
8746 \o \gui{putIntItem(self, name, value)} - Equivalent to:
8750 self.putValue(value)
8756 \o \gui{putBoolItem(self, name, value)} - Equivalent to:
8760 self.putValue(value)
8761 self.putType("bool")
8766 \o \gui{pushOutput(self)} - Moves the output string to a safe location
8767 from with it is sent to the debugger plugin even if further operations
8770 \o \gui{putCallItem(self, name, item, func)} -
8771 Uses GDB to call the function \c func on the value specified by
8772 \a {item.value} and output the resulting item. This function is
8773 not available when debugging core dumps and it is not available
8774 on the Symbian platform due to restrictions imposed by the on-device
8777 \o \gui{putItem(self, item)} - The "master function", handling
8778 basic types, references, pointers and enums directly, iterates
8779 over base classes and class members of compound types and calls
8780 \c qdump__* functions whenever appropriate.
8782 \o \gui{putSubItem(self, item)} - Equivalent to:
8787 Exceptions raised by nested function calls are caught and all
8788 output produced by \c putItem is replaced by the output of:
8791 except RuntimeError:
8792 d.put('value="<invalid>",type="<unknown>",numchild="0",')
8798 \section2 Children and SubItem Class
8800 The attempt to create child items might lead to errors if data is
8801 uninitialized or corrupted. To gracefully recover in such situations,
8802 use \c Children and \c SubItem \e{Context Managers} to create the nested items.
8804 The \c Children constructor \gui{__init__(self, dumper, numChild = 1,
8805 childType = None, childNumChild = None)} uses one mandatory argument and three
8806 optional arguments. The mandatory argument refers to the current \c Dumper
8807 object. The optional arguments can be used to specify the number \c numChild
8808 of children, with type \c childType_ and \c childNumChild_ grandchildren each.
8809 If \c numChild_ is a list of two integers, the first one specifies the actual
8810 number of children and the second the maximum number of children to print.
8812 Similarly, using the \c SubItem class helps to protect individual items.
8817 if d.isExpanded(item):
8821 d.putItem(Item(key, item.iname, "key"))
8824 d.putItem(Item(value, item.iname, "value"))
8827 \section1 Debugging Helpers for QML
8829 The debugging helpers for QML provide you with code completion for custom modules
8830 (\c qmldump) and debugging Qt Quick UI projects (\c qmlobserver).
8832 You have to build the QML Observer once for each Qt version that you want to debug
8833 with. Select \gui{Tools > Options... > Qt4 > Qt Versions}.
8835 \note QML Observer requires Qt 4.7.1 or later.
8837 \section1 Enabling Debugging Helpers for Qt's Bootstrapped Applications
8839 Qt's bootstrapped applications (such as moc and qmake) are built in a way
8840 that is incompatible with the default build of the debugging helpers. To
8841 work around this, add \c{dumper.cpp} to the compiled sources in the
8842 application Makefile.
8844 Choose \gui {Tools > Options > Debugger > Debugging Helper > Use debugging
8845 helper from custom location}, and specify an invalid location, such as
8852 \contentspage index.html
8853 \previouspage creator-project-wizards.html
8854 \page creator-project-cmake.html
8855 \nextpage creator-project-generic.html
8857 \title Setting Up a CMake Project
8859 CMake is an alternative to qmake for automating the generation of build
8861 It controls the software compilation process by using simple configuration
8862 files, called CMakeLists.txt files. CMake generates native build
8864 workspaces that you can use in the compiler environment of your choice.
8866 Since Qt Creator 1.1, CMake configuration files are supported.
8867 Qt Creator 1.3 supports the Microsoft tool chain if the CMake version
8870 \section1 Setting the Path for CMake
8872 You can set the path for the \c CMake executable in \gui{Tools} >
8873 \gui{Options... > Projects > CMake}.
8875 \image qtcreator-cmakeexecutable.png
8877 \note Before you open a \c CMake project it is necessary to modify the
8878 \c{PATH} environment variable to include the bin folders of \c mingw and
8879 Qt Creator in the SDK.
8881 For instance, if you have the Qt SDK installed in your C drive,
8882 use the following command to set the environment variables in
8883 the command line prompt:
8885 set PATH=C:\qtsdk\mingw\bin;C:\qtsdk\qt\bin;
8887 Then start Qt Creator by typing:
8889 C:\qtsdk\bin\qtcreator.exe
8892 \section1 Opening CMake Projects
8894 To open a \c CMake project:
8896 \o Select \gui{File} > \gui{Open File or Project...}.
8897 \o Select the \c{CMakeLists.txt} file from your \c CMake project.
8900 A wizard guides you through the rest of the process.
8902 \note If the \c CMake project does not have an in-place build, Qt Creator
8903 lets you specify the directory in which the project is built
8904 (\l{glossary-shadow-build}{shadow build}).
8906 \image qtcreator-cmake-import-wizard1.png
8908 The screenshot below shows how you can specify command line arguments to
8909 \c CMake for your project.
8911 \image qtcreator-cmake-import-wizard2.png
8913 Normally, there is no need to pass any command line arguments for projects
8914 that are already built, as \c CMake caches that information.
8917 \section1 Building CMake Projects
8919 Qt Creator builds \c CMake projects by running \c make, \c mingw32-make, or
8920 \c nmake depending on your platform. The build errors and warnings are
8921 parsed and displayed in the \gui{Build Issues} output pane.
8923 By default, Qt Creator builds the \bold{all} target. You can specify which
8924 targets to build in \gui{Project} mode, under \gui{Build Settings}.
8926 \image qtcreator-cmake-build-settings.png
8928 Qt Creator supports multiple build configurations. The build
8929 directory can also be modified after the initial import.
8931 \section1 Running CMake Projects
8932 Qt Creator automatically adds \gui{Run Configurations} for all targets
8933 specified in the \c CMake project file.
8935 Known issues for the current version can be found
8936 \l{Known Issues}{here}.
8939 \section1 Adding External Libraries to CMake Projects
8941 Through external libraries Qt Creator can support code completion and
8942 syntax highlighting as if they were part of the current project or the Qt
8945 Qt Creator detects the external libraries using the \c FIND_PACKAGE()
8946 macro. Some libraries come with the CMake installation. You can find those
8947 in the \bold{Modules} directory of your CMake installation.
8949 \note If you provide your own libraries, you also need to provide your own
8950 \c FindFoo.cmake file. For more information, see
8951 \l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}.
8953 Syntax completion and highlighting work once your project successfully
8954 builds and links against the external library.
8959 \contentspage index.html
8960 \previouspage creator-debugging-helpers.html
8961 \page creator-debugging-qml.html
8962 \nextpage creator-troubleshooting-debugging.html
8964 \title Debugging Qt Quick Projects
8966 \note You need Qt 4.7.1 or later to debug Qt Quick projects. Debugging projects
8967 not created with the Qt Quick wizards is only supported with Qt 4.8, or later.
8969 \section1 Setting Up QML Debugging
8971 The process of setting up debugging for Qt Quick projects depends on the type of
8972 the project: Qt Quick UI or Qt Quick Application.
8974 To debug Qt Quick UI projects:
8978 \o Select \gui Projects, and then select the \gui QML check box in the
8979 \gui {Run Settings}, to enable QML debugging.
8981 \o Compile the QML Observer debugging helper. For more information, see
8982 \l{Debugging Helpers for QML}.
8986 To debug Qt Quick Applications:
8990 \o Select \gui Projects, and then select the \gui {Link QML debugging
8991 library} check box in \gui {Build Steps}.
8993 You might have to compile the library first, by selecting the
8996 \image qml-link-debugging-library.png "Build Steps"
8998 \note Debugging requires opening a socket at a well-known port, which
8999 presents a security risk. Anyone on the Internet could connect to the
9000 application that you are debugging and execute any JavaScript
9001 functions. Therefore, you must make sure that the port is properly
9002 protected by a firewall.
9004 \o In the \gui {Run Settings}, select the \gui QML check box to enable
9007 \o Select \gui {Build > Rebuild Project} to clean and rebuild the
9012 \section1 Starting QML Debugging
9014 To start the application, choose \gui {Debug > Start Debugging
9015 > Start Debugging} or press \key F5. Once the application starts running, it behaves
9016 and performs as usual. You can then perform the following tasks:
9020 \o Debug JavaScript functions
9022 \o Preview QML changes at runtime
9024 \o Inspect QML at runtime
9028 \section1 Debugging JavaScript Functions
9030 You can use the Qt Creator \gui Debug mode to inspect the state of your
9031 application while debugging. You can interact with the debugger in several
9032 ways, as described in the following sections:
9036 \o \l{Setting Breakpoints}
9038 \o \l{Viewing Call Stack Trace}
9040 \o \l{Locals and Expressions}
9044 \section1 Executing JavaScript Expressions
9046 When the application is interrupted by a breakpoint, you can use the \gui {QML
9047 Script Console} to execute JavaScript expressions in the current context. To
9048 open it, choose \gui {Window > View > QML Script Console}.
9050 \image qml-script-console.png "QML Script Console view"
9052 You can type JavaScript expressions and use them to get information about the
9053 state or your application. For example, property values.
9055 You can see the current value of a property by hovering over it in the code editor.
9057 \section1 Previewing QML Changes at Runtime
9059 If you change property values or add properties in the code editor, the changes
9060 are updated in the running application when you save them. If live preview is not supported
9061 for an element, a message appears. Click \gui Reload to preview the changes.
9063 Reloading is enabled by default. To disable it, click
9064 \inlineimage qml-observer-bar-reload.png "Apply Changes on Save button"
9067 \section1 Inspecting QML at Runtime
9069 While the application is running, you can use the \gui {QML Observer} view to
9070 explore the object structure, debug animations, and inspect colors.
9071 To open the \gui {QML Observer} view, choose \gui {Window > View > QML Observer}.
9072 The view shows the properties of the currently selected QML element.
9074 \image qml-observer-view.png "QML Observer view"
9076 When you debug complex applications, you can use the observe
9077 mode to jump to the position in code where an element is defined. To switch to
9078 the observe mode, click
9079 \inlineimage qml-observer-bar-observe.png
9082 Click elements in the running application to jump to their definitions in the code.
9083 Double-click elements to browse the element hierarchy. The hierarchy is displayed
9084 as bread crumbs in the \gui {QML Observer} view.
9086 To move the application running in \QQV to the front, select the
9087 \gui {Show Application on Top} button.
9089 You can also right-click an element in the running application to view the element
9090 hierarchy as a context menu. Select an element to jump to its definition in code.
9092 \image qml-observer-context-menu.png "QML Observer"
9094 To zoom in and out of the application, click the \gui Zoom button.
9096 To inspect colors, click the \gui {Color Picker} button. You can also click
9097 \inlineimage qml-observer-bar-copy-color.png "Copy Color button"
9098 to copy the color definition to the clipboard.
9100 \section1 Debugging Animations
9102 \image qml-observer.png
9104 To play and pause animations in the running application, select the
9105 \gui {Play/Pause Animations} button on the toolbar or \gui {Debugging >
9106 Animations > Pause}, or press
9109 To change the speed at which animations are played, select a value in \gui {Debugging
9110 > Animations} or click and hold down the \gui {Play/Pause Animations}
9111 button to select a value.
9117 \contentspage index.html
9118 \previouspage creator-project-cmake.html
9119 \page creator-project-generic.html
9120 \nextpage creator-version-control.html
9122 \title Setting Up a Generic Project
9124 Qt Creator supports generic projects, so you can import existing projects
9125 that do not use qmake or CMake and Qt Creator ignores your build system.
9127 Generic project support allows you to use Qt Creator as a code editor. You
9128 can change the way your project is built by modifying the \c make command
9129 in the \gui{Projects} mode under \gui{Build Settings}.
9131 When you import a project, Qt Creator creates the following files that
9132 allow you to specify which files belong to your project and which include
9133 directories or defines you want to pass to your compile:
9134 \tt{.files}, \tt{.includes}, and \tt{.config}.
9137 \section1 Importing a Generic Project
9139 To import an existing generic project:
9141 \o Select \gui File > \gui{New File or Project...} >
9142 \gui{Other Project} > \gui{Import Existing Project}.
9143 \o In \gui{Import Existing Project}, enter the project name
9144 and select the location of the project file you want to import.
9146 Qt Creator automatically generates the following files in the
9149 \o \l{Specifying Files}{.files}
9150 \o \l{Specifying Include Paths}{.includes}
9151 \o \l{Specifying Defines}{.config}
9156 When the project is successfully imported, Qt Creator creates the project
9157 tree in the sidebar.
9159 After importing a generic project into Qt Creator, open it by selecting the
9163 \section1 Working with Generic Project Files
9165 For a generic project, you have to manually specify which files belong to
9166 your project and which include directories or defines you want to pass to
9170 \section1 Specifying Files
9172 The list of files for a generic project is specified in the \tt{.files}
9173 file. When you first create a generic project, Qt Creator adds any
9174 files it recognizes to your project.
9176 To add or remove files, edit the \tt{.files} file in Qt Creator.
9177 Qt Creator recreates your project tree when you save the \tt{.files} file.
9178 Alternatively, you can add and remove files using the context menu in the
9181 If you frequently need to update the \tt{.files} file, you can do so
9182 efficiently by using a script that updates the file for you. If the file
9183 is modified externally, you have to restart Qt Creator for the changes to
9186 To update the \tt{.files} on the \gui Git repository use the following
9189 git ls-files "*.cpp" "*.h" > MyProject.files
9192 \section1 Specifying Include Paths
9194 The include paths are specified in the \tt{.includes} file, one include
9195 path per line. The paths can be either absolute or relative to the
9196 \tt{.includes} file.
9198 \section1 Specifying Defines
9200 The defines are specified in the \tt{.config} file. The \tt{.config} file is
9201 a regular C++ file, prepended to all your source files when they are parsed.
9202 Only use the \tt{.config} file to add lines as in the example below:
9209 \section1 Creating a Run Configuration
9211 Qt Creator cannot automatically determine which executable to run.
9213 In the \gui{Projects} mode under \gui{Run Settings}, define the executable
9216 \o Click \gui Add and select \gui{Custom Executable}.
9217 \o Define the configuration name, the location of the executable, any
9218 additional arguments and the working directory.
9227 \contentspage index.html
9228 \previouspage creator-design-mode.html
9229 \page creator-visual-editor.html
9230 \nextpage quick-projects.html
9232 \title Developing Qt Quick Applications
9234 You can either create Qt Quick projects from scratch or import existing projects to
9237 You can use the code editor (\l{Using the Editor}{Edit mode}) or the visual editor
9238 (\l{Using Qt Quick Designer}{Design mode}) to develop Qt Quick applications.
9240 \image qtcreator-qt-quick-editors.png "Edit mode and Design mode"
9242 The following sections describe typical tasks you can do with Qt Creator.
9246 \o \l {Creating Qt Quick Projects}
9247 \o \l {Using Qt Quick Designer}
9248 \o \l {Creating Components}
9249 \o \l {Creating Buttons}
9250 \o \l {Creating Scalable Buttons and Borders}
9251 \o \l {Creating Screens}
9252 \o \l {Animating Screens}
9253 \o \l {Adding User Interaction Methods}
9254 \o \l {Exporting Designs from Graphics Software}
9255 \o \l {Implementing Application Logic}
9256 \o \l {Using QML Modules with Plugins}
9265 \contentspage index.html
9266 \previouspage creator-visual-editor.html
9267 \page quick-projects.html
9268 \nextpage creator-using-qt-quick-designer.html
9270 \title Creating Qt Quick Projects
9272 \image qmldesigner-new-project.png "New File or Project dialog"
9274 When you create a new Qt Quick project from scratch, you have the following options:
9278 \o \gui {Qt Quick Application} creates a Qt Quick application project that can
9279 contain both QML and C++ code. The project includes a QDeclarativeView. You can build
9280 the application and deploy it on desktop and mobile target platforms. For example, you
9281 can create signed Symbian Installation System (SIS) packages for this type of projects.
9283 \o \gui {Qt Quick UI} creates a Qt Quick UI project with a single QML file that
9284 contains the main view. You can review Qt Quick UI projects in the QML Viewer and you
9285 need not build them. You do not need to have the development environment installed on your
9286 computer to create and run this type of projects.
9288 \o \gui {Custom QML Extension Plugin} creates a C++ plugin that makes it possible
9289 to offer extensions that can be loaded dynamically into applications by using the
9290 QDeclarativeEngine class.
9294 If you have existing QML applications that you want to run in Qt Creator or deploy
9295 to mobile devices, use the \gui {Qt Quick Application} wizard to convert them
9296 to Qt Quick applications.
9298 \section1 Creating Qt Quick UI Projects
9302 \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick UI
9305 The \gui{Introduction and Project Location} dialog opens.
9307 \image qmldesigner-new-ui-project-location.png "Introduction and Project Location dialog"
9309 \o In the \gui Name field, give a name to the project.
9311 Do not use spaces and special characters in the project name and path.
9313 \o In the \gui {Create in} field, enter the path for the project files. For example,
9314 \c {C:\Qt\examples}. To select the path from a directory tree, click \gui Browse.
9316 \o Click \gui{Next}.
9318 \image qmldesigner-new-ui-project-summary.png "Project Management dialog"
9320 \o Review the project settings, and click \gui{Finish} to create the project.
9325 Qt Creator creates the following files:
9329 \o .qmlproject project file defines that all QML, JavaScript, and image
9330 files in the project folder belong to the project. Therefore, you do not
9331 need to individually list all the files in the project.
9333 \o .qml file defines an element, such as a component, screen, or the whole
9338 The \c import statement in the beginning of the .qml file specifies the
9339 \l {http://doc.qt.nokia.com/4.7/qdeclarativemodules.html} {Qt modules}
9340 to import. Each Qt module contains a set of default elements.
9341 Specify a version to get the features you want.
9343 To use JavaScript and image files in the application, copy them to the
9346 \section1 Creating Qt Quick Applications
9350 \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick Application
9353 The \gui{Introduction and Project Location} dialog opens.
9355 \image qmldesigner-new-project-location.png "Introduction and Project Location dialog"
9357 \o In the \gui Name field, give a name to the project.
9359 Do not use spaces and special characters in the project name and path.
9361 \o In the \gui {Create in} field, enter the path for the project files. For example,
9362 \c {C:\Qt\examples}. To select the path from a directory tree, click \gui Browse.
9364 \o Click \gui{Next}.
9366 The \gui {Application Type} dialog opens.
9368 \image qmldesigner-new-project-qml-sources.png "Application Type dialog"
9370 \o Select the Qt Quick Component Set to use in your application. The
9371 built-in elements allow you to write cross-platform applications with
9372 custom look and feel. The components for Symbian and MeeGo Harmattan
9373 allow you to create applications with a native look and feel for the
9374 selected mobile platform.
9376 You can also import an existing QML file in this dialog.
9378 \o Click \gui{Next}.
9380 The \gui {Target Setup} dialog opens.
9382 \image qmldesigner-new-project-qt-versions.png "Target Setup dialog"
9384 \o Select the Qt versions to use as build targets for your project,
9385 and then click \gui{Next}.
9387 \note Qt Quick is supported since Qt 4.7, and therefore, only Qt 4.7 and later
9388 versions are displayed. Further, if you have only one supported Qt version installed,
9389 this dialog is skipped.
9391 The \gui {Mobile Options} dialog opens.
9393 \image qmldesigner-new-app-project-mobile-options.png "Mobile Options dialog"
9395 \o In the \gui {Orientation behavior} field, determine how the application
9396 behaves when the orientation of the device display rotates between portrait
9397 and landscape, and then click \gui Next.
9399 \note This dialog opens only if you select \gui Maemo5 or
9400 \gui {Symbian Device} target in the \gui {Target Setup} dialog. On
9401 Harmattan, the Qt Quick Components for MeeGo provide native-looking
9404 The \gui {Symbian Specific} dialog opens.
9406 \image qmldesigner-new-project-symbian-options.png "Symbian Specific dialog"
9408 \o In the \gui {Application icon (.svg)} field, select an application
9409 icon for the \gui {Symbian Device} target, or use the default icon.
9411 \o In the \gui {Target UID3} field, specify the \l{Application UID}, or
9412 use the default UID.
9414 \note Qt Creator generates a UID for testing the application on a device.
9415 You need to change the UID when you deliver the application for public
9420 The \gui {Maemo Specific} dialog opens.
9422 \image qmldesigner-new-project-maemo-options.png "Maemo Specific dialog"
9424 \o In the \gui {Application icon} field, select the application
9425 icon to use on Maemo or Harmattan targets, or use the default icon.
9427 The \gui {Project Management} dialog opens.
9429 \image qmldesigner-new-project-summary.png "Project Management" dialog
9431 \o In the \gui {Add to project} field, you can add this project to another
9432 project as a subproject.
9434 \o In the \gui {Add to version control} field, you can add the project to
9435 a version control system.
9437 \o Click \gui Finish to create the project.
9441 Qt Creator creates the necessary boilerplate files. Some of the files are
9442 specific to the Symbian, Maemo, or MeeGo Harmattan platform.
9444 \section1 Importing QML Applications
9446 If you have existing QML applications that you want to run in Qt Creator or deploy
9447 to mobile devices, use the \gui {Qt Quick Application} wizard and select the main
9448 .qml file in your project. All the other files in the project are automatically added
9449 to the application project.
9451 To import QML applications:
9455 \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick Application
9458 \o Name the project and set its path, and then click \gui Next.
9460 \o In the \gui {Application Type} dialog, select the \gui {Use an
9462 option and specify the main .qml file of the project you want to import.
9464 \image qmldesigner-import-project.png "Application Type dialog"
9468 \o Select the Qt versions to use as build targets for your project, and click
9471 \o Specify options for deploying the application to mobile device targets, and
9474 \o Review the project settings, and click \gui{Finish} to create the project.
9478 Qt Creator adds references to the QML files to a project and creates the additional files
9479 necessary for deploying applications to mobile devices.
9486 \contentspage index.html
9487 \previouspage creator-using-qt-quick-designer.html
9488 \page quick-components.html
9489 \nextpage quick-buttons.html
9491 \title Creating Components
9493 A QML component provides a way of defining a new type that you can re-use in other QML
9494 files. A component is like a black box; it interacts with the outside world
9495 through properties, signals, and slots, and is generally defined in its own QML file.
9496 You can import components to screens and applications.
9498 You can use the following QML elements to create components:
9502 \o \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
9503 uses an image as a border or background.
9504 \o \l{http://doc.qt.nokia.com/4.7/qml-image.html}{Image}
9505 adds a bitmap to the scene. You can stretch and tile images.
9506 \o \l{http://doc.qt.nokia.com/4.7/qml-item.html}{Item}
9507 is the most basic of all visual items in QML. Even though it has no visual appearance,
9508 it defines all the properties that are common across visual items, such as the x and
9509 y position, width and height, anchoring, and key handling.
9510 \o \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
9511 adds a rectangle that is painted with a solid fill color and an optional border.
9512 You can also use the radius property to create rounded rectangles.
9513 \o \l{http://doc.qt.nokia.com/4.7/qml-text.html}{Text}
9514 adds formatted read-only text.
9515 \o \l{http://doc.qt.nokia.com/4.7/qml-textedit.html}{Text Edit}
9516 adds a single line of editable formatted text that can be validated.
9517 \o \l{http://doc.qt.nokia.com/4.7/qml-textinput.html}{Text Input}
9518 adds a single line of editable plain text that can be validated.
9519 \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-webview.html}{Web View}
9520 adds web content to a canvas.
9524 QML elements allow you to write cross-platform applications with custom look
9525 and feel. You can also use ready-made Qt Quick Components for Symbian and
9526 MeeGo Harmattan that allow you to create applications with a native look and
9527 feel for the selected mobile platform. You can install the components as
9530 When you use the Qt Creator project wizard to create Qt Quick applications,
9531 you can select which component set to use in your application.
9533 Even if you use the Qt Quick Components, you can still write cross-platform
9534 applications, by using different sets of QML files for each platform.
9536 You can dowload a set of commonly used UI-components for generic use in
9537 Qt Quick projects from
9538 \l{https://projects.forum.nokia.com/QMLTemplates}{QML Templates}. You can
9539 open and edit the templates in \QD.
9541 \section1 Creating Components in Qt Quick Designer
9545 \o Select \gui {File > New File or Project > Files and Classes > QML
9546 > Choose...} to create a new .qml file.
9548 \note Components are listed in the \gui {QML Components} section of the
9549 \gui Library pane only if the filename begins with a capital letter.
9551 \o Click \gui Design to open the .qml file in \QMLD.
9553 \o Drag and drop an item from the \gui Library pane to the editor.
9555 \o Edit item properties in the \gui Properties pane.
9557 The available properties depend on the item.
9561 The following sections contain examples of how to create some common components:
9565 \o \l{Creating Buttons}
9567 \o \l{Creating Scalable Buttons and Borders}
9575 \contentspage index.html
9576 \previouspage quick-components.html
9577 \page quick-buttons.html
9578 \nextpage quick-scalable-image.html
9580 \title Creating Buttons
9582 To create a button component:
9586 \o Select \gui {File > New File or Project > QML > QML File > Choose...} to
9587 create a QML file called Button.qml (for example).
9589 \note Components are listed in the \gui Library pane only if the filename
9590 begins with a capital letter.
9592 \o Click \gui {Design} to edit the file in the visual editor.
9594 \o In the \gui Navigator pane, click \gui Rectangle to set properties
9597 \o In the \gui Properties pane, modify the appearance of the button.
9601 \o In the \gui Size field, set the width (\gui W) and height (\gui H)
9604 \o In the \gui Color field, select the button color.
9606 \o In the \gui Radius field, use the slider to set the radius of the
9607 rectangle and produce rounded corners for the button.
9611 \o Drag and drop a \gui {Text} item on top of the \gui Rectangle. This
9612 creates a nested element where \gui Rectangle is the parent element of
9613 \gui Text. Elements are positioned relative to their parents.
9615 \o In the \gui Properties pane, edit the properties of the \gui Text item.
9619 \o In the \gui Text field, type \bold Button.
9621 You can select the text color, font, size, and style in the \gui Font
9624 \o In the \gui Alignment field, select the center buttons to align
9625 the text to the center of the button.
9627 \o Click \gui {Layout}, and then click the
9628 \inlineimage qmldesigner-anchor-fill-screen.png
9629 button to anchor the text to the whole button area.
9633 \o Press \key {Ctrl+S} to save the button.
9635 \image qmldesigner-button.png "Button component"
9639 \note To view the button, you must add it to a Qt Quick Application or Qt Quick UI
9642 To create a graphical button that scales beautifully without using vector graphics,
9643 use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
9644 element. For more information, see \l{Creating Scalable Buttons and Borders}.
9651 \contentspage index.html
9652 \previouspage quick-buttons.html
9653 \page quick-scalable-image.html
9654 \nextpage quick-screens.html
9656 \title Creating Scalable Buttons and Borders
9658 You can use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
9659 element to display an image, such as a PNG file, as a border and a background.
9661 Use two Border Image elements and suitable graphics to make it look like the button
9662 is pushed down when it is clicked. One of the Border Image elements is visible by default.
9663 You can specify that it is hidden and the other one becomes visible when the mouse
9666 Add a MouseArea that covers the whole area and emits the clicked signal (\c {parent.clicked()})
9667 when it detects a mouse click.
9669 You can add text to the button and set it up as a property. The text can then be initialized
9670 from the outside, making the button a reusable UI component. The font size is also available
9671 in case the default size is too big. You can scale down the button text and use smooth text
9672 rendering for some extra quality.
9674 \image qmldesigner-borderimage.png "Graphical button"
9676 To create a graphical button:
9680 \o Select \gui {File > New File or Project > QML > QML File > Choose...} to create
9681 a QML file called Button.qml (for example).
9683 \o Double-click the file to open it in the code editor.
9685 \o Replace the \gui Rectangle with an \gui Item, as illustrated by the
9686 following code snippet:
9694 \o Specify properties and set expressions for the \gui Item, as
9695 illustrated by the following code snippet:
9697 \snippet snippets/qml/quick-scalable-image.qml properties and signal definitions
9699 You will point to the properties and expression later.
9701 \o Click \gui {Design} to edit the file in the visual editor.
9703 \o Drag and drop two \gui BorderImage items from the \gui Library pane to
9706 \o Drag and drop a \gui Text item to the scene.
9708 \o Drag and drop a \gui MouseArea to the screen.
9710 \o In the \gui Navigator pane, select \gui border_image1 to specify
9711 settings for it in the \gui Properties pane:
9715 \o Select \gui {Set Expression} in the menu next to the \gui Visibility
9718 \o Enter the following expression to specify that the image is visible
9719 when the mouse is not pressed down: \c {!mouse_area1.pressed}.
9721 \o In the \gui Source field, select the image file for the
9722 button, for example button_up.png.
9724 \o Click \gui {Layout}, and then click the
9725 \inlineimage qmldesigner-anchor-fill-screen.png
9726 button to anchor the border image to the \gui Item.
9730 \o Select \gui border_image2 to specify similar settings for it:
9734 \o Set the following epression for \gui Visibility, to specify that
9735 the image is visible when the mouse is pressed down:
9736 \c {mouse_area1.pressed}.
9738 \o In the \gui Source field, select the image file for the
9739 button when it is clicked, for example button_down.png.
9741 \o Click \gui {Layout}, and then click the
9742 \inlineimage qmldesigner-anchor-fill-screen.png
9743 button to anchor the border image to the \gui Item.
9747 \o Select \gui text1 to specify font size and color, and text
9748 scaling and rendering:
9752 \o In the \gui Color field, use the color picker to select
9753 the font color, or enter a value in the field.
9755 \o In the \gui Text field, select \gui {Set Expression} and
9756 enter a pointer to the \c {text} property that you specified
9757 earlier: \c {parent.txt}.
9759 \o Select the \gui Aliasing check box to enable smooth text
9762 \o In the \gui Size field, select \gui {Pixels} to specify
9763 the font size in pixels. By default, the size is specified in
9766 \o In the \gui Size field, select \gui {Set Expression} and
9767 enter a pointer to the \c {fontSize} property that you specified
9770 \o Click \gui {Layout}, and then click the
9771 \inlineimage qmldesigner-center-in.png "Anchor buttons"
9772 buttons to inherit the vertical and horizontal centering from
9775 \o Click \gui Advanced to specify scaling for the text in the
9778 \o Select \gui {Set Expression} and enter the following expression:
9779 \c {if (!mousearea1.pressed) { 1 } else { 0.95 }}.
9781 \note You can enter long and complicated expressions also in the
9786 \o In the code editor, add to the \c MouseArea item
9787 a pointer to the \c clicked expression that you added earlier:
9788 \c {onClicked: parent.clicked()}.
9792 \note To view the button, you must add it to a Qt Quick Application or Qt
9800 \contentspage index.html
9801 \previouspage quick-scalable-image.html
9802 \page quick-screens.html
9803 \nextpage quick-animations.html
9805 \title Creating Screens
9807 You can use predefined QML elements and your own components to create screens.
9808 Typically, the main qml file in a Qt Quick project specifies the main window of an
9811 The QML files in the project folder are displayed in \gui {QML Components} in the
9814 You can also use ready-made Qt Quick Components for Symbian and
9815 MeeGo Harmattan that allow you to create screens with a native look and
9816 feel for the selected mobile platform. You can install the components as
9819 You can dowload QML templates that specify different types of screens from
9820 \l{https://projects.developer.nokia.com/QMLTemplates}{QML Templates} for use in
9821 your Qt Quick projects. You can open and edit the templates in \QD.
9823 \section1 Adding Components to Screens
9827 \o Drag and drop components from the \gui Library pane to the editor.
9829 \o Select components in the \gui Navigator pane to edit their properties
9830 in the \gui Properties pane.
9832 For example, you can anchor components to a position on the screen.
9836 \section1 Using Data Models
9838 You can create the following types of views to organize items provided by
9839 \l{http://doc.qt.nokia.com/4.7/qdeclarativemodels.html}{data models}:
9843 \o \l{http://doc.qt.nokia.com/4.7/qml-gridview.html}{Grid View}
9844 provides a grid vizualization of a model.
9846 \o \l{http://doc.qt.nokia.com/4.7/qml-listview.html}{List View}
9847 provides a list vizualization of a model.
9849 \o \l{http://doc.qt.nokia.com/4.7/qml-pathview.html}{Path View}
9850 visualizes the contents of a model along a path.
9854 In the code editor, write the code to use the data models.
9856 \section1 Positioning Items on Screens
9858 You can use the following items to arrange items on screens:
9862 \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-column.html}{Column}
9863 arranges its child items vertically.
9865 \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-row.html}{Row}
9866 arranges its child items horizontally.
9868 \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-grid.html}{Grid}
9869 arranges its child items so that they are aligned in a grid and
9870 are not overlapping.
9872 \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-flow.html}{Flow}
9873 arranges its child items side by side, wrapping as necessary.
9877 \section1 Using States
9879 Use states and transitions
9880 to navigate between screens.
9882 QML states typically describe user interface configurations, such as the UI elements,
9883 their properties and behavior and the available actions. For example, you can use
9884 states to create two screens.
9886 To add states, click the empty slot in the \gui States pane. Then modify the new state
9887 in the visual editor.
9889 \image qmldesigner-states.png "States pane"
9891 The properties that you change in a state are highlighted with blue color.
9892 In the code editor, you can see the changes recorded as changes to the base state.
9894 To keep the QML code clean, you should create a base state that contains all the
9895 elements you will need in the application. You can then create states, in
9896 which you hide and show a set of items and modify their properties.
9901 \o Align items on different screens with each other.
9903 \o Avoid excessive property changes. If an item is invisible in the base
9904 state, you must define all changes to its child elements as property changes,
9905 which leads to complicated QML code.
9907 \o Minimize the differences between the base state and the other states
9908 to keep the QML code short and readable and to improve performance.
9910 \o Avoid problems when using transitions and animation when changing
9915 To create screens for an application by using states:
9919 \o In the base state, add all elements you will need in the application.
9920 While you work on one screen, you can click the
9921 \inlineimage qmldesigner-show-hide-icon.png
9922 icon to hide elements on the canvas that are not part of a screen.
9924 \o In the \gui States pane, click the empty slot to create a new state
9925 and give it a name. For example, \c Normal.
9927 \o In the \gui Properties pane, deselect the \gui Visibility check box
9928 or set \gui Opacity to 0 for each element that is not needed in this view.
9929 If you specify the setting for the parent element, all child elements
9930 inherit it and are also hidden.
9932 \image qmldesigner-screen-design.png "Designing screens"
9934 \o Create additional states for each screen and set the visibility or
9935 opacity of the elements in the screen.
9937 \o To determine which view opens when the application starts, use the code
9938 editor to set the state of the root item of the .qml file, as specified by the
9939 following code snippet:
9955 \contentspage index.html
9956 \previouspage quick-screens.html
9957 \page quick-animations.html
9958 \nextpage quick-user-interaction.html
9960 \title Animating Screens
9962 To make movement between states smooth, you can specify transitions.
9963 You can use different types of animated transitions. For example, you can animate changes
9964 to property values and colors. You can use rotation animation to control the direction of
9965 rotation. For more information, see
9966 \l{http://doc.qt.nokia.com/4.7/qdeclarativeanimation.html}{QML Animation}.
9968 You can use the \c ParallelAnimation element to start several animations at the same time.
9969 Or use the \c SequentialAnimation element to run them one after another.
9971 You can use the code editor to specify transitions. For more information, see
9972 \l{http://doc.qt.nokia.com/4.7/qml-transition.html}{QML Transition Element}.
9980 \contentspage index.html
9981 \previouspage quick-animations.html
9982 \page quick-user-interaction.html
9983 \nextpage quick-export-to-qml.html
9985 \title Adding User Interaction Methods
9987 You can add the following basic interaction methods to scenes:
9991 \o \l{http://doc.qt.nokia.com/4.7/qml-flickable.html}{Flickable}
9992 items can be flicked horizontally or vertically.
9993 \o \l{http://doc.qt.nokia.com/4.7/qml-flipable.html}{Flipable}
9994 items can be flipped between their front and back sides by using rotation,
9995 state, and transition.
9996 \o \l{http://doc.qt.nokia.com/4.7/qml-focusscope.html}{Focus Scope}
9997 assists in keyboard focus handling when building reusable QML components.
9998 \o \l{http://doc.qt.nokia.com/4.7/qml-mousearea.html}{Mouse Area}
9999 enables simple mouse handling.
10008 \contentspage index.html
10009 \previouspage quick-user-interaction.html
10010 \page quick-export-to-qml.html
10011 \nextpage quick-application-logic.html
10013 \title Exporting Designs from Graphics Software
10015 You can export designs from graphics software, such as Adobe Photoshop and GIMP,
10016 to QML files. Each scene is converted into a single QML file with an Image or a
10017 Text element for each layer and saved on the development PC. Top-level layer
10018 groups are converted into merged QML Image elements.
10020 Note: GIMP does not support grouping, and therefore, each layer is exported as
10023 The following rules apply to the conversions:
10027 \o Layer names are used as element names. Spaces and hash marks (#) are
10028 replaced with underscore characters to create valid ids for the elements.
10030 \o Layer styles, such as drop shadows, are converted to images.
10032 \o Offset, size, ordering and opacity are preserved.
10034 \o Text layers are converted to Text elements, unless you specify that they
10035 be converted to Image elements.
10037 \o Hidden layers can be exported, and their visibility is set to hidden.
10039 \o PNG images are copied to the images subirectory.
10043 You can open the QML file in Qt Creator for editing. If you edit the file in Adobe
10044 Photoshop and export it to the same directory again, any changes you made in Qt
10045 Creator are overwritten. However, you can re-export graphical assets without
10046 recreating the QML code.
10048 If you create vector graphics with other tools that have an Adobe Photoshop export
10049 option,such as Adobe Illustrator, you can export them first to Photoshop and then
10052 \section1 Exporting from Adobe Photoshop to QML
10054 \image qml-export-photoshop.png
10056 The script has been tested to work on Adobe Photoshop CS 4 and 5, but it might also
10057 work on other versions.
10061 \o Download the export script, \e{Export QML.jx}, from
10062 \l{http://qt.gitorious.org/qt-labs/photoshop-qmlexporter/trees/master}{Gitorious}.
10064 \note Read the README.txt file in the repository for latest information about
10067 \o Double-click the export script to add the export command to the \gui Scripts
10068 menu. You can also copy the script file to the Adobe Photoshop scripts directory
10069 (typically, \c{\Presets\Scripts} in the Photoshop installation directory).
10071 \o In Adobe Photoshop, choose \gui {File > Scripts > Export to QML} to export the
10072 scene to a QML file.
10074 \o In the \gui {Export Document to QML} dialog, enter a name and location for the
10077 \o Select the \gui {Rasterize text} check box to export text layers as images,
10078 not as Text elements.
10080 \o Select the \gui {Group layers} check box to export each top-level group as a
10081 merged QML Image element.
10083 \o Select the \gui {Export hidden} check box to export hidden layers and to set
10084 their visibility property to hidden.
10086 \o Deselect the \gui {Export QML} check box if you have modified the QML document
10087 in Qt Creator, but still want to re-export graphical assets.
10089 \o Click \gui Export.
10093 The QML file is saved to the location that you specified.
10094 In Qt Creator, choose \gui {File > Open File or Project} to open the QML file.
10096 \note Existing files are replaced without warning.
10098 \section1 Exporting from GIMP to QML
10100 \image qml-export-gimp.png
10102 The script has been tested to work on GIMP 2. You can download GIMP 2 from
10103 \l{http://www.gimp.org/downloads/}{GIMP Downloads}.
10105 To use the export script on Microsoft Windows, you also need to install the
10106 GIMP Python extension (Python, PyCairo, PyGobject, PyGTK). However, GIMP is
10107 not officially supported on Windows, so we cannot guarantee that this will
10112 \o On Microsoft Windows, you must first add Python support to your GIMP
10113 installation, as instructed in
10114 \l {http://www.gimpusers.com/tutorials/install-python-for-gimp-2-6-windows}{Tutorial: Installing Python for GIMP 2.6 (Windows)}.
10116 \o Download the export script, \e qmlexporter.py, from
10117 \l{http://qt.gitorious.org/qt-labs/gimp-qmlexporter/trees/master}{Gitorious}.
10119 \note Read the INSTALL.txt in the repository for latest information about the
10122 \o Copy the export script to the plug-ins directory in the GIMP installation
10125 \o Check the properties of the file to make sure that it is executable.
10127 On Linux, run the following command: \c {chmod u+rx}
10129 \o Restart GIMP to have the export command added to the \gui File menu.
10131 \o Choose \gui {File > Export to QML} to export the design to a QML file.
10133 \o In the \gui {Export Layers to a QML Document} dialog, enter a name and
10134 location for the QML file, and click \gui Export.
10138 The QML file is saved to the location that you specified.
10139 In Qt Creator, choose \gui {File > Open File or Project} to open the QML file.
10141 \note Existing files are replaced without warning.
10148 \contentspage index.html
10149 \previouspage quick-export-to-qml.html
10150 \page quick-application-logic.html
10151 \nextpage creator-qml-modules-with-plugins.html
10153 \title Implementing Application Logic
10155 A user interface is only a part of an application, and not really useful by itself.
10156 You can use Qt or JavaScript to implement the application logic. For more information on
10157 using JavaScript, see
10158 \l {http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html} {Integrating JavaScript}.
10160 For an example of how to use JavaScript to develop a game, see the
10161 \l {http://doc.qt.nokia.com/4.7/qml-advtutorial.html} {QML Advanced Tutorial}.
10167 \contentspage index.html
10168 \previouspage quick-application-logic.html
10169 \page creator-qml-modules-with-plugins.html
10170 \nextpage creator-using-qt-designer.html
10172 \title Using QML Modules with Plugins
10174 QML modules may use plugins to expose components defined in C++ to
10175 QML applications. Since Qt Creator cannot load the plugins to determine
10176 the details of the contained components, these modules need to provide
10177 extra type information for code completion and the semantic checks to work
10180 Ideally, QML modules have a \c{plugins.qmltypes} file in the same directory
10181 as the \c qmldir file. The \c qmltypes file contains a description of the
10182 components exported by the module's plugins and is loaded by Qt Creator
10183 when the module is imported.
10185 For Qt 4.8 and later, one or more \c qmltypes files can be listed in the
10186 \c qmldir file under the \c typeinfo header. These files will be read in addition
10187 to \c{plugins.qmltypes}. For more information, see
10188 \l{http://doc.qt.nokia.com/4.8-snapshot/qdeclarativemodules.html#writing-a-qmldir-file}{Writing a qmldir File}.
10190 \section1 Generating qmltypes Files
10192 You can create and edit \c qmltypes files manually, but you are recommended
10193 to use the \c qmlplugindump tool shipped with Qt 4.8 and later to generate
10194 them automatically. For earlier versions of Qt, you can compile a version
10195 of the tool called \c qmldump from the sources in
10196 \c{<QtCreator>/share/qtcreator/qml/qmldump} if the Qt version contains private headers.
10198 Once you have obtained qmlplugindump for the Qt version the QML module's
10199 plugins were compiled with, run the following command to load My.Module
10200 version 1.0 from \c{/import/path/my/module} including all its plugins and
10201 output a description of the plugins' types to
10202 \c{/import/path/my/module/plugins.qmltypes}:
10205 qmlplugindump My.Module 1.0 /import/path > /import/path/my/module/plugins.qmltypes
10208 You can safely ignore the debug output.
10210 \section1 Dumping Plugins Automatically
10212 If a module with plugins lacks the \c qmltypes file, Qt Creator tries to
10213 generate a temporary file itself by running the \c qmldump program in the
10214 background. However, this automatic dumping is a fallback mechanism with
10215 many points of failure and cannot be relied upon.
10220 \contentspage index.html
10221 \previouspage creator-editor-refactoring.html
10222 \page qt-quick-toolbars.html
10223 \nextpage creator-editor-locator.html
10225 \title Using Qt Quick Toolbars
10227 When you edit QML code in the code editor, you specify the properties
10228 of QML components. For some properties, such as colors and font names,
10229 this is not a trivial task. For example, few people can visualize the
10232 To easily edit these properties, you can use the Qt Quick Toolbars.
10233 When you select a component in the code and a toolbar is available,
10234 a light bulb icon appears:
10235 \inlineimage qml-toolbar-indicator.png
10236 . Select the icon to open the toolbar.
10238 To open toolbars immediately when you select a component, select
10239 \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar > Always show Quick
10242 Drag the toolbar to pin it to another location. Select
10243 \inlineimage qml-toolbar-pin.png
10244 to unpin the toolbar and move it to its default location. To pin toolbars
10245 by default, select \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar
10246 > Pin Quick Toolbar}.
10248 \section1 Previewing Images
10250 The Qt Quick Toolbar for images allows you to edit the properties of
10251 \l{http://doc.qt.nokia.com/latest/qml-borderimage.html}{Border Image}
10252 and \l{http://doc.qt.nokia.com/latest/qml-image.html}{Image} components.
10253 You can scale and tile the images, replace them with other images,
10254 preview them, and change the image margins.
10256 \image qml-toolbar-image.png "Qt Quick Toolbar for images"
10258 To preview an image, double-click it on the toolbar. In the preview
10259 dialog, you can zoom the image. Drag the image margins to change them.
10261 \image qml-toolbar-image-preview.png "Image preview dialog"
10263 \section1 Formatting Text
10265 The Qt Quick Toolbar for text allows you to edit the properties of
10266 \l{http://doc.qt.nokia.com/latest/qml-text.html}{Text} components.
10267 You can change the font family and size as well as text formatting, style,
10268 alignment, and color.
10270 If a property is assigned an expression instead of a value, you
10271 cannot use the toolbar to edit it. The button for editing the property
10274 \image qml-toolbar-text.png "Qt Quick Toolbar for text"
10276 By default, font size is specified as pixels. To use points, instead,
10277 change \gui px to \gui pt in the size field.
10279 \section1 Previewing Animation
10281 The Qt Quick Toolbar for animation allows you to edit the properties of
10282 \l{http://doc.qt.nokia.com/4.7/qml-propertyanimation.html}{PropertyAnimation}
10283 components and the components that inherit it. You can change the easing curve
10284 type and duration. For some curves, you can also specify amplitude, period,
10285 and overshoot values.
10287 \image qml-toolbar-animation.png "Qt Quick Toolbar for animation"
10289 Select the play button to preview your changes.
10291 \section1 Editing Rectangles
10293 The Qt Quick Toolbar for rectangles allows you to edit the properties of
10294 \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
10295 components. You can change the fill and border colors and add
10298 \image qml-toolbar-rectangle.png "Qt Quick Toolbar for rectangles"
10300 To add gradient stop points, click above the gradient bar. To remove
10301 stop points, drag them upwards.
10307 \contentspage index.html
10308 \previouspage creator-editor-external.html
10309 \page creator-maemo-emulator.html
10310 \nextpage creator-mime-types.html
10312 \title Using Maemo or MeeGo Harmattan Emulator
10314 The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
10315 of the \QSDK. After they are installed, you can start them from Qt Creator.
10317 The Maemo 5 emulator emulates the Nokia N900 device environment. You can test
10318 applications in conditions practically identical to running the application
10319 on a Nokia N900 device with software update release 1.3 (V20.2010.36-2).
10321 The MeeGo Harmattan emulator emulates the Nokia N9 device environment.
10323 With the emulators, you can test how your application reacts to hardware
10324 controls, such as the power button, and to the touch screen.
10326 To test the application UI, user interaction with the application, and
10327 functionality that uses the mobility APIs, use the Qt Simulator,
10328 instead. For more information, see the
10329 \l{http://doc.qt.nokia.com/qtsimulator/index.html}{Qt Simulator Manual}.
10331 The difference between Qt Simulator and the emulators is that when you
10332 compile your application binary for Qt Simulator, it is compiled against a
10333 host library. The binary run on the emulator is compiled for the actual
10334 device, using the Maemo 5 or Harmattan tool chain.
10336 \section1 Starting the Emulator
10338 The \gui {Start Maemo Emulator} button is visible if you have a project
10339 open in Qt Creator for which you have added the Maemo or MeeGo Harmattan
10340 build target. It starts the Maemo or MeeGo Harmattan emulator, depending
10341 on the selected target.
10343 To start the emulator, click
10344 \inlineimage qtcreator-maemo-emulator-button.png "Start Maemo Emulator button"
10347 Test your application on the Maemo emulator as on a device. For a list of
10348 keyboard shortcuts that you can use to emulate keys and functions, see
10349 \l {Emulating Device Keys}.
10351 \section1 Rendering Graphics
10353 The emulators support OpenGL to improve graphics rendering. Hardware
10354 acceleration produces better results than software rendering. By default,
10355 Qt Creator automatically detects, whether hardware acceleration is
10356 supported on the development PC and tries to use it. However, sometimes
10357 the results of the automatic detection are not reliable, and
10358 hardware acceleration might be selected even if it is actually not
10359 available on the development PC. This causes the emulator to crash.
10361 If the emulator crashes, you are asked whether you want to try software
10362 rendering, instead.
10364 To specify the OpenGL mode, select \gui {Tools > Options... > Maemo > Qemu
10367 \section1 Emulating Device Keys
10369 The following table summarizes the keyboard shortcuts that you can use
10370 to emulate device keys and functions.
10375 \o Keyboard Shortcut
10386 \o Respective keys on the development PC keyboard.
10389 \o Left Shift key (Maemo 5)
10394 \o Left Ctrl key (Maemo 5)
10399 \o Left Alt key (Maemo 5)
10406 \o Keypad slider open and close
10409 \o Keypad lock (Maemo 5 only)
10412 \o Camera lens open and close (Maemo 5 only)
10418 \o Camera take picture
10421 \note The actual camera functionality is not emulated.
10423 \o Stereo headphones connect and disconnect (Maemo 5 only)
10432 \o Accelerometer x axis, negative
10435 \o Accelerometer x axis, positive
10438 \o Accelerometer z axis, negative
10441 \o Accelerometer z axis, positive
10444 \o Accelerometer y axis, negative
10447 \o Accelerometer y axis, positive
10452 \note Each press of the accelerometer key turns the acceleration by 50
10455 \section1 Closing the Emulator
10457 To close the emulator, click the X at the top right corner of the device
10458 emulator view. The emulator interprets this as a press of the power button
10459 and displays the text \e {Shutting down} in the emulator window title pane.
10460 The emulator closes shortly after this.
10462 You can also select the \gui {Start Maemo Emulator} button to close the
10463 emulator. This is a faster way to close the emulator, because it does not
10464 wait for the operating system running on the emulated machine to shut down,
10465 but this also means that it is less safe.
10471 \contentspage index.html
10472 \previouspage creator-version-control.html
10473 \page adding-plugins.html
10474 \nextpage creator-editor-external.html
10476 \title Adding Qt Designer Plugins
10478 You can use Qt APIs to create plugins that extend Qt applications.
10479 This allows you to add your own widgets to \QD.
10480 The most flexible way to include a plugin with an application is to compile it
10481 into a dynamic library that is shipped separately, and detected and loaded at runtime.
10483 The applications can detect plugins that are stored in the standard plugin
10484 subdirectories. For more information on how to create and locate plugins and to
10485 change the default plugin path, see \l{How to Create Qt Plugins}.
10487 For more information about how to create plugins for \QD, see
10488 \l{http://doc.qt.nokia.com/4.7/designer-using-custom-widgets.html}{Creating and Using Components for Qt Designer}.
10490 \section1 Locating Qt Designer Plugins
10492 \QD fetches plugins from the standard locations and loads the plugins
10493 that match its build key. \QD is delivered both as a standalone application
10494 and as part of the SDK, where it is integrated into Qt Creator.
10495 The correct folder to place the plugins depends on
10498 The integrated \QD fetches plugins from the \c {%SDK%\bin\designer} folder on Windows
10499 and Linux. For information about how to configure plugins on Mac OS, see
10500 \l{Configuring Qt Designer Plugins on Mac OS}.
10502 To check which plugins
10503 were loaded successfully and which failed, choose \gui{Tools > Form Editor >
10504 About Qt Designer Plugins}.
10506 The standalone \QD is part of the Qt library used for building projects,
10507 located under \c {%SDK%\qt}. Therefore, it fetches plugins from the following folder:
10508 \c {%SDK%\qt\plugins\designer}. To check which plugins were loaded successfully and which
10509 failed, choose \gui{Help > About Plugins}.
10511 \section2 Configuring Qt Designer Plugins on Mac OS
10513 On the Mac, a GUI application must be built and run from a bundle. A bundle is a
10514 directory structure that appears as a single entity when viewed in the Finder.
10515 A bundle for an application typcially contains the executable and all the resources
10518 Qt Creator uses its own set of Qt Libraries located in the bundle, and therefore,
10519 you need to configure the \QD plugins that you want to use with Qt Creator.
10520 Fore more information about how to deploy applications on Mac OS, see
10521 \l{http://doc.qt.nokia.com/4.7/deployment-mac.html}{Deploying an Application on Mac OS X}.
10523 The following example illustrates how to configure version 5.2.1 of the
10524 \l{http://qwt.sourceforge.net/}{Qwt - Qt Widgets for Technical Applications} library
10525 for use with Qt Creator:
10529 \o To check the paths used in the Qwt library, enter the following \c otool command:
10531 \snippet examples/doc_src_plugins.qdoc 0
10533 The output for Qwt 5.2.1 indicates that the plugin uses Qt core libraries (QtDesigner,
10534 QtScript, QtXml, QtGui and QtCore) and libqwt.5.dylib:
10536 \snippet examples/doc_src_plugins.qdoc 1
10539 \o You must copy the \QD plugin and the Qwt library files to the following locations:
10542 \o \c {libqwt_designer_plugin.dylib} to \c {QtCreator.app/Contents/MacOS/designer}
10543 \o \c {libqwt.*.dylib} to \c {QtCreator.app/Contents/Frameworks}
10546 Enter the following commands:
10548 \snippet examples/doc_src_plugins.qdoc 4
10550 \o Enter the following \c otool command to check the libraries that are used by the
10553 \snippet examples/doc_src_plugins.qdoc 2
10555 The command returns the following output:
10557 \snippet examples/doc_src_plugins.qdoc 3
10559 \o Enter the following \c install_name_tool command to fix the references of the
10562 \snippet examples/doc_src_plugins.qdoc 5
10567 \section1 Matching Build Keys
10569 The Qt Creator that is included in pre-built SDK packages on Windows is built with the
10570 Microsoft Visual Studio compiler, whereas the version of Qt shipped for building applications
10571 is configured and built to use the MinGW/g++ compiler. Plugins built by using this version of
10572 Qt cannot be loaded by Qt Creator because the build-keys do not match. The plugins can only be
10573 used in the standalone version of \QD. Choose \gui{Help > About Qt Creator} to check
10574 the Qt version Qt Creator was built with.
10576 To use \QD plugins that were built for the shipped Qt version, make sure that
10577 Qt Creator is built with the same compiler by either recompiling Qt Creator using MinGW or
10578 recompiling Qt with Microsoft Visual Studio, depending on which configuration you want to
10579 use for your applications.
10585 \contentspage index.html
10586 \previouspage creator-using-qt-designer.html
10587 \page creator-usability.html
10588 \nextpage creator-building-running.html
10590 \title Optimizing Applications for Mobile Devices
10592 Before starting application development, analyze and define the requirements, scope, and
10593 functionality of the application to ensure efficient functionality and a smooth user
10594 experience. Design the application for a single purpose and analyze how it can best serve
10595 its users. Mobile devices have been designed for use when mobile. Keep the characteristics
10596 of mobile devices in mind when you create applications for them.
10598 The following guidelines help you design and develop usable applications for mobile devices
10599 with varying characteristics, such as screen size and support for input methods:
10605 Find out who will use the application, what they will use it for,
10606 and which mobile devices they have. Then design the application to fit a specific context
10609 \o Design for small screens
10611 The screen size of mobile devices is significantly smaller
10612 than that available on desktop devices. Carefully consider what is the most relevant
10613 content to present on the application UI, as it might not be reasonable to try and fit as
10614 much content into the screen as you might have in a desktop application.
10616 \o Design for multiple screen sizes
10618 Relate the position and size of each control to the
10619 dimensions of the display. This enables the same set of information to be presented on the
10620 screen in all resolutions; higher resolution devices just display finer graphics.
10622 \o Design for changing screen orientation
10624 Some devices support screen rotation. On these
10625 devices, applications can be displayed in portrait or landscape orientation. Account for
10626 orientation and dynamically adjust the display when the screen is rotated.
10628 \o Design intuitive ways of moving within applications
10630 Mobile devices lack a mouse and
10631 full-size keyboard, so users must use the touch screen or five way navigation pad to move within
10632 applications. In addition, many users control the devices with one hand. To create an optimized user
10633 experience, allow users to access information with one click; do not make them scroll and type.
10635 \o Design for limited input methods
10637 Applications collect information from users on the task
10638 at hand. In addition to touch screen input, some devices contain physical keys such
10639 as a five way navigation pad, a keypad, and a keyboard. Users enter information by using screen
10640 controls, such as lists, check boxes, radio buttons, and text fields.
10642 \o Keep response times short
10644 Latency can cause delays in user interaction. If users perceive
10645 an application as being slow, they are likely to get frustrated and stop using it.
10647 \o Save battery time
10649 Mobile devices are not constantly connected to a power source but run on
10650 battery power. Optimize power consumption to keep the total consumption at an acceptable
10651 level and to prevent users from running out of battery time.
10653 \o Consider network issues
10655 If users do not have a flat-rate data plan or WLAN support, mobile
10656 network connections cost them money. Also, when users move around with the devices, the networks
10657 available for connections constantly change.
10659 \o Remember the processing limits of the device
10662 The memory available on devices is limited
10663 and you should use it carefully. Although all mobile devices have common functionality,
10664 each device is individual in terms of both the resources available and extra features.
10665 Therefore, you must consider the constraints of all the target devices.
10669 For more information about user experience techniques for mobile devices, see the
10670 \l{http://www.developer.nokia.com/Resources/Library/Design_and_UX} on Nokia Developer.
10676 \contentspage index.html
10677 \previouspage creator-faq.html
10678 \page creator-tips.html
10679 \nextpage creator-known-issues.html
10681 \title Tips and Tricks
10684 \section1 Switching Between Modes
10686 Qt Creator uses different modes for different purposes. You can quickly
10687 switch between these modes with the following keyboard shortcuts:
10689 \o \gui Welcome mode \key Ctrl+1
10690 \o \gui Edit mode \key Ctrl+2
10691 \o \gui Design mode \key Ctrl+3
10692 \o \gui Debug mode \key Ctrl+4
10693 \o \gui Projects mode \key Ctrl+5
10694 \o \gui Help mode \key Ctrl+6
10698 For more information about Qt Creator modes, see \l {Qt Creator Modes}.
10702 \section1 Moving Between Open Files
10704 To quickly move between currently open files, press
10707 To move forward in the location history, press \key {Alt+Right}
10708 (\key {Cmd+Opt+Right} on Mac OS). To move backward, press \key {Alt+Left}
10709 (\key {Cmd+Opt+Left} on Mac OS). For example, if you use the \gui Locator
10710 to jump to a symbol in the same file, you can jump back to your original
10711 location in that file by pressing \key {Alt+Left}.
10714 \section1 Moving To the Edit Mode
10716 To move to the \gui Edit mode and currently active file, press
10719 If you already are in the \gui Edit mode:
10721 \o The first press moves focus to the editor
10722 \o The second press closes secondary windows
10725 \section1 Using the Filter in Options Dialog
10727 To find specific settings you require in \gui{Tools} > \gui{Options...}
10728 use the filter located at the top left of the \gui Options dialog box.
10730 \section1 Opening Output Panes
10732 The output panes provide a list of errors and warnings encountered during
10733 a build, detailed output from the compiler, status of a program when it is
10734 executed and debug output, as well as search results.
10736 To open output panes, use the following shortcuts:
10740 \o \gui{Build Issues} pane Alt+1 (Cmd+1 on Mac OS X)
10742 \o \gui{Search Results} pane Alt+2 (Cmd+2 on Mac OS X)
10744 \o \gui{Application Output} pane Alt+3 (Cmd+3 on Mac OS X)
10746 \o \gui{Compile Output} pane Alt+4 (Cmd+4 on Mac OS X)
10750 For more information about output panes, see \l{Viewing Output}.
10753 \section1 Using Keyboard Shortcuts
10755 Qt Creator provides \l{Keyboard Shortcuts}{many useful keyboard shortcuts}.
10756 You can see the keyboard shortcut for a menu command in the menu
10757 or the tooltip for a button.
10759 To customize, import or export keyboard shortcuts, select \gui Tools >
10760 \gui Options... > \gui Environment > \gui Keyboard.
10763 \section1 Running Qt Creator From Command Line
10765 You can launch Qt Creator from command line using the name of an
10766 existing session or \c .pro file by giving the name as the command
10769 For example, running \tt{qtcreator somesession}, launches Qt Creator and
10770 loads session somesession.
10772 \note Make sure Qt Creator is included in the PATH environment variable.
10773 This can be done by typing the following in the command line:
10775 set PATH=c:\qtsdk\mingw\bin;c:\qtsdk\qt\bin;%PATH%
10779 \section1 Showing and Hiding the Sidebar
10781 To toggle the sidebar in the \gui Edit and \gui Debug modes, click
10782 \inlineimage qtcreator-togglebutton.png
10783 or press \key Alt+0 (\key Cmd+0 on Mac OS X).
10785 For more information on using the sidebar, see \l {Browsing Project Contents}.
10789 \section1 Moving To Symbols
10791 To move straight to a symbol used in a project, select the symbol in the
10792 \gui Editor toolbar drop-down menu. For more information on the editor toolbar,
10793 see \l {Using the Editor Toolbar}.
10795 To jump to a symbol in the current file, press \key {Ctrl+K} to open the
10796 \gui Locator, enter a period (.), and start typing the symbol name. Then
10797 select the symbol in the list. For more information on using the locator,
10798 see \l{Searching With the Locator}.
10800 Press \key Ctrl (\key Cmd on Mac OS) and click a symbol to move directly to
10801 the definition or the declaration of the symbol. You can also move the cursor
10802 on the symbol and press \key {F2}. For more information, see
10803 \l{Moving to Symbol Definition or Declaration}.
10807 \section1 Displaying Signals and Slots
10809 If an instance of a class is derived from QObject, and you would like to
10810 find all other objects connected to one of your object's slots using
10811 Qt's signals and slots mechanism, select \gui Tools > \gui Options...
10812 > \gui{Debugger} > \gui{Debugging Helper} > \gui{Use Debugging Helper}.
10814 In the \gui{Locals and Expressions} view, expand the object's entry and open
10815 the slot in the \e slots subitem. The objects connected to this slot are
10816 shown as children of the slot. This method works with signals too.
10818 For more information about the \gui{Locals and Expressions} view, see
10819 \l{Locals and Expressions}.
10822 \section1 Displaying Low Level Data
10824 If special debugging of Qt objects fails due to data corruption within the
10825 debugged objects, you can switch off the debugging helpers. When debugging
10826 helpers are switched off low-level structures become visible.
10828 To switch off the debugging helpers:
10831 \o Select \gui Tools > \gui Options... > \gui Debugger >
10832 \gui{Debugging Helper}.
10833 \o Uncheck the \gui{Use Debugging Helper} checkbox.
10837 \section1 Showing Tooltips in Debug Mode
10839 To inspect the value of variables from the editor, you can turn
10840 on tooltips. Tooltips are hidden by default for performance reasons.
10843 \o Select \gui Tools > \gui Options... > \gui Debugger > \gui General.
10844 \o Select the \gui {Use tooltips in main editor while debugging} check box.
10847 When you hover over a variable in the code editor in \gui Debug mode, a
10848 tooltip is displayed. To keep the tooltip visible, click the pin button.
10849 You can expand pinned tooltips to view their full content.
10851 \image qtcreator-pin-tooltip.png
10853 Pinned tooltips are stored in the session. To close all pinned tooltips,
10854 select \gui {Close Editor Tooltips} in the context menu in the \gui {Locals
10855 and Expressions} view.
10858 \section1 Locating Files
10860 The \gui Locator provides one of the easiest ways in Qt Creator to browse
10861 through projects, files, classes, methods, documentation and file systems.
10862 To quickly access files not directly mentioned in your project, you can
10863 create your own locator filters. That way you can locate files in a
10864 directory structure you have defined.
10866 To create locator filters, select \gui {Tools > Options... > Locator > Add}.
10868 For more information, see \l{Creating Locator Filters}.
10870 \section1 Adding a License Header Template for C++ Code
10872 A file containing a license header for C++ can be specified under
10873 \gui{Tools > Options... > C++ > License Template}. It may contain special
10874 placeholders enclosed in \c{%%} that are replaced when generating a
10879 \o \c %MONTH%: Month
10880 \o \c %DAY%: Day of the month
10882 \o \c %USER%: User name
10883 \o \c %FILENAME%: File name
10884 \o \c %CLASS%: Class name (if applicable)
10885 \o \c %$VARIABLE%: Contents of environment variable \c{VARIABLE}.
10892 \contentspage index.html
10893 \previouspage creator-cli.html
10894 \page creator-keyboard-shortcuts.html
10895 \nextpage creator-faq.html
10897 \title Keyboard Shortcuts
10899 Qt Creator provides various keyboard shortcuts to speed up your development
10903 \section1 Configuring Keyboard Shortcuts
10905 To customize a keyboard shortcut:
10907 \o Select \gui Tools > \gui Options... > \gui Environment >
10909 \o Select an action from the list.
10910 \o In \gui{Key Sequence} enter the shortcut key you want to associate
10911 with the selected action.
10914 Qt Creator allows you to use different keyboard shortcut mapping schemes:
10916 \o To import a keyboard shortcut mapping scheme, click \gui Import
10917 and select the kms file containing keyboard shortcut mapping scheme
10918 you want to import.
10919 \o To export the current keyboard shortcut mapping scheme, click
10920 \gui Export and select the location where you want to save the
10925 \section1 Default Keyboard Shortcuts
10927 The following tables list the default keyboard shortcuts. They are
10928 categorized by actions.
10931 \section2 General Keyboard Shortcuts
10936 \o Keyboard shortcut
10938 \o Open file or project
10941 \o New file or project
10944 \o Open in external editor
10980 \o Next open document in history
10983 \o Goto other split
10986 \o Previous open document in history
10989 \o Activate \gui Locator
10992 \o Switch to \gui Welcome mode
10995 \o Switch to \gui Edit mode
10998 \o Switch to \gui Design mode
11001 \o Switch to \gui Debug mode
11004 \o Switch to \gui Projects mode
11007 \o Switch to \gui Help mode
11010 \o Toggle \gui{Build Issues} pane
11011 \o Alt+1 (Cmd+1 on Mac OS X)
11013 \o Toggle \gui{Search Results} pane
11014 \o Alt+2 (Cmd+2 on Mac OS X)
11016 \o Toggle \gui{Application Output} pane
11017 \o Alt+3 (Cmd+3 on Mac OS X)
11019 \o Toggle \gui{Compile Output} pane
11020 \o Alt+4 (Cmd+4 on Mac OS X)
11022 \o Activate \gui Bookmarks pane
11025 \o Activate \gui{File System} pane
11028 \o Activate \gui{Open Documents} pane
11031 \o Activate \gui Projects pane
11037 \o Toggle the sidebar
11038 \o Alt+0 (Cmd+0 on Mac OS X)
11043 \o Move to \gui Edit mode
11047 \o The first press moves focus to the editor
11048 \o The second press closes secondary windows
11054 \section2 Editing Keyboard Shortcuts
11059 \o Keyboard shortcut
11061 \o Auto-indent selection
11070 \o Trigger a completion in this scope
11085 \o Decrease font size
11086 \o Ctrl+- (Ctrl+Roll mouse wheel down)
11088 \o Increase font size
11089 \o Ctrl++ (Ctrl+Roll mouse wheel up)
11091 \o Toggle Vim-style editing
11097 \o Split side by side
11100 \o Remove all splits
11103 \o Remove current split
11112 \o Go to block start
11115 \o Go to block end with selection
11118 \o Go to block start with selection
11121 \o Move current line down
11124 \o Move current line up
11127 \o Trigger a quick fix in this scope
11130 \o Rewrap paragraph
11133 \o Select the current block
11135 The second press extends the selection to the parent block
11138 \o Enable text wrapping
11141 \o Toggle comment for selection
11144 \o Visualize whitespace
11153 \o Lay out in a grid
11156 \o Lay out horizontally
11159 \o Lay out vertically
11165 \o Edit signals and slots
11174 \o Go to next bookmark
11177 \o Go to previous bookmark
11189 \o Follow symbol under cursor
11191 Works with namespaces, classes, methods, variables, include
11192 statements and macros
11195 \o Rename symbol under cursor
11198 \o Switch between method declaration and definition
11201 \o Open type hierarchy
11204 \o Switch between header and source file
11207 \o Turn selected text into lowercase
11210 \o Turn selected text into uppercase
11214 \section2 Debugging Keyboard Shortcuts
11219 \o Keyboard shortcut
11224 \o Stop or interrupt debugger
11239 \o Toggle breakpoint
11242 \o Run to selected function
11247 \section2 Project Keyboard Shortcuts
11252 \o Keyboard shortcut
11268 \section2 Help Keyboard Shortcuts
11273 \o Keyboard shortcut
11275 \o View context-sensitive help
11278 \o Activate contents in \gui Help mode
11281 \o Add bookmark in \gui Help mode
11284 \o Activate index in \gui Help mode
11287 \o Reset font size in \gui Help mode
11290 \o Activate search in \gui Help mode
11295 \section2 Version Control Keyboard Shortcuts
11300 \o {5,1} Version control system
11331 \o Alt+G, Alt+Shift+D
11373 \o Alt+G, Alt+Shift+D
11410 \contentspage index.html
11411 \previouspage technical-support.html
11412 \page creator-glossary.html
11413 \nextpage creator-acknowledgements.html
11425 Qt in PATH
11427 \target glossary-system-qt
11429 version for the \c qmake command found in your \c PATH
11430 environment variable.
11431 This is likely to be the system's Qt version.
11439 \target glossary-project-qt
11440 \o The version of Qt configured in the \gui{Projects} mode, \gui {Build
11441 Settings}, \gui {Qt Version} field. This is the Qt version that
11442 is actually used by a particular project.
11449 \target glossary-shadow-build
11450 \o Shadow building means building a project in a separate
11451 directory, the \e{build directory}. The build directory is
11452 different from the source directory. One of the benefits of
11453 shadow building is that it keeps your source directory clean.
11454 Shadow building is the best practice if you need many build
11455 configurations for a single set of source.
11462 \contentspage index.html
11463 \previouspage creator-tips.html
11464 \page creator-known-issues.html
11465 \nextpage technical-support.html
11467 \title Known Issues
11469 This section lists known issues in Qt Creator version 2.2.0.
11470 The development team is aware of them, and therefore, you do not need to
11471 report them as bugs.
11473 For a list of fixed issues and added features, see the changelog file in
11474 the \c{qtcreator\dist} folder or the \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}.
11476 \section1 General Issues
11480 \o If you change the Input Languages in Windows, Qt Creator might not
11481 respond for 30 seconds. This is a known issue in the Advanced Text
11482 Service of Microsoft Windows.
11484 \o Qt Creator uses SQLite for storing some of its settings. SQLite is
11485 known to have problems with certain NFS servers (most notably the
11486 nfs-user-server 2.2beta), since they can lock up the application
11487 when it tries to lock the database. If your home directory is on an
11488 NFS share and you encounter this issue, one option would be to
11489 switch to the nfs-kernel-server, or create a symlink so that the
11490 settings are stored locally.
11492 \o The Okteta KDE custom widget plugin might be installed as part of
11493 some Linux distributions. It can cause Qt Designer to crash. For
11494 more information, see:
11498 \o \l{https://bugs.launchpad.net/ubuntu/+source/kdeutils/+bug/662005}{Ubuntu bug 662005}
11499 \o \l{http://bugreports.qt.nokia.com/browse/QTBUG-12025}{QTBUG-12025}
11503 To resolve the issue, enter the following command to remove the package:
11505 sudo apt-get remove okteta
11507 Or delete the following file:
11508 \c /usr/lib/kde4/plugins/designer/oktetadesignerplugin.so.
11512 \section1 Editing Issues
11516 \o Code completion does not support typedefs for nested classes.
11520 \section1 Projects Issues
11523 \o Paths or file names containing spaces or special characters
11524 (such as colons, dollar signs, and hash marks) may cause problems. This
11525 is because some of the tools Qt Creator uses in the background have
11526 restrictions on the characters allowed in file and directory names.
11527 To be on the safe side, we recommend creating projects and project
11528 items with names consisting of plain characters, numbers,
11529 underscores, and hyphens.
11531 \o Creating new CMake projects with Qt Creator is not supported.
11533 \o On Windows, you must create projects for Maemo 5 and Harmattan
11534 targets on the same partition where
11535 you installed \QSDK, Qt Creator, and MADDE.
11537 \o If error messages displayed in the \gui {Compile Output} pane contain
11538 paths where slashes are missing (for example, C:QtSDK),
11539 check your PATH variable. For more information, see
11540 \l{Troubleshooting MinGW Compilation Errors}.
11544 \section1 Debugging Issues
11548 \o Debugging large applications on Symbian devices using the Symbian^3
11549 operating system might not work, because the on-device debugging agent
11550 might not be able to
11551 access memory when the operating system starts paging. This causes breakpoint
11552 handling and symbol resolution to fail. For more information, see
11553 \l{http://bugreports.qt.nokia.com/browse/QTCREATORBUG-2158}{QTCREATORBUG-2158}.
11555 As a workaround, add the following section to the application .pro file to
11561 MMP_RULES *= UNPAGED
11565 \note You must completely clean and rebuild the project for the setting to
11568 \o When debugging executables created by the GNU Compiler version 4.5.0
11569 (all platforms), some data types will not be displayed in the
11570 \gui{Locals and Expressions} view due to missing debug information.
11572 \o GDB on Windows may not work if the 'Embassy \reg Security Center' software
11573 by 'Wave \reg Systems' is installed and active (causing crashes in \c{vxvault.dll)}).
11575 \o GDB may take long to load debugging symbols, especially from large
11578 \o Setting breakpoints in code that is compiled into the binary more
11579 than once does not work.
11581 \o Setting breakpoints in files that do not have unique absolute
11582 paths may fail. For example, remounting parts of a file system
11583 using the --bind mount option.
11587 \section1 Qt Quick Designer Issues
11591 \o \QMLD uses external processes (QML Puppet) to render and preview
11592 images and to collect data. Executing C++ code might cause the QML
11593 Puppet to crash. If it crashes, an error message is displayed and
11594 you can continue editing the QML file in the code editor.
11601 \contentspage index.html
11602 \previouspage creator-glossary.html
11603 \page creator-acknowledgements.html
11605 \title Acknowledgements
11607 \section1 Third-party Components
11609 Qt Creator contains the following third-party components:
11612 \o \bold{Open Source front-end for C++ (license MIT)}, enhanced for use in
11614 Roberto Raggi <roberto.raggi@gmail.com>\br
11615 QtCreator/src/shared/cplusplus\br\br
11617 \o \bold{Botan, a C++ crypto library. Version 1.8.8}\br
11619 \o Copyright (C) 1999-2004 The Botan Project. All rights reserved.
11620 \o Copyright (C) 1999-2009 Jack Lloyd
11621 \o 2001 Peter J Jones
11622 \o 2004-2007 Justin Karneges
11623 \o 2005 Matthew Gregan
11624 \o 2005-2006 Matt Johnston
11625 \o 2006 Luca Piccarreta
11626 \o 2007 Yves Jerschow
11627 \o 2007-2008 FlexSecure GmbH
11628 \o 2007-2008 Technische Universitat Darmstadt
11629 \o 2007-2008 Falko Strenzke
11630 \o 2007-2008 Martin Doering
11631 \o 2007 Manuel Hartl
11632 \o 2007 Christoph Ludwig
11633 \o 2007 Patrick Sona
11635 All rights reserved.\br\br
11637 Redistribution and use in source and binary forms, with or without
11638 modification, are permitted provided that the following conditions are
11641 1. Redistributions of source code must retain the above copyright
11642 notice, this list of conditions, and the following disclaimer.\br\br
11644 2. Redistributions in binary form must reproduce the above copyright
11645 notice, this list of conditions, and the following disclaimer in the
11646 documentation and/or other materials provided with the distribution.\br
11649 THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND ANY EXPRESS OR
11650 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
11651 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE,
11652 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE
11653 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
11654 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
11655 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
11656 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
11657 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
11658 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
11659 IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\br\br
11660 The source code of Botan C++ crypto library can be found
11663 \o QtCreator/src/libs/3rdparty
11664 \o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
11668 \o \bold{NetSieben SSH Library is a Secure Shell client library for C++.
11671 \o \bold{Commercial License:} For organizations who do not want to
11672 release the source code for their applications as open source/
11673 free software; in other words they do not want to comply with the
11674 GNU General Public License (GPL) or Q Public License.
11675 \o \bold{Non Commercial / Open Source License:} NetSieben believes in
11676 contributing back to the open source community, thus it has released
11677 the SSH Library under Q Public License as it is defined by Trolltech
11678 AS of Norway. The Open Source License allows the user to use software
11679 under an open source / free software license, and distribute it
11680 freely. The software can be used at no charge with the condition
11681 that if the user uses the SSH Library in an application they wish to
11682 redistribute, then the complete source code for your application must
11683 be available and freely redistributable under reasonable conditions.
11684 For more information on the used QPL License see:
11685 QtCreator/src/libs/3rdparty/net7ssh/LICENSE.QPL
11687 The source code of NetSieben Secure Shell C++ Library can be found
11690 \o QtCreator/src/libs/3rdparty
11691 \o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
11698 \contentspage index.html
11699 \previouspage creator-mime-types.html
11700 \page creator-task-lists.html
11701 \nextpage creator-cli.html
11703 \title Showing Task List Files in the Build Issues Pane
11705 Code scanning and analysis tools create report files in ASCII format.
11706 Usually, the report files consist of lines that contain a file name, a line
11707 number, and an error message. A similar format is used for stack traces
11708 obtained from crash reports. Traditionally, you would fix the errors by
11709 manually navigating to them and correcting them, which is tedious.
11711 Qt Creator makes this very easy by providing a way to load these files into
11712 the \gui{Build Issues} pane. You can navigate to the corresponding source
11713 code by clicking the error message. But first you must convert the files to
11714 the \l{Task List File Format} by using conversion scripts that based on
11715 standard text processing tools of the operating system.
11717 In addition, you can generate task list files from code.
11718 For an example of a script that checks new lines of code and matches them
11719 against regular expressions to generate a task list, see \c{scripts\mytasks.pl}
11720 in the Qt Creator repository.
11722 To open task list files, choose \gui{File} > \gui{Open}.
11724 \section1 Task List File Format
11726 The filename extension must be .tasks for Qt Creator to recognize a file as a
11729 Each line in a task list file is treated as a tab-separated list of strings with
11730 \c{\t}, \c{\n}, and \c{\\} used as escape characters. The strings are used to create
11731 one task per line. The lines can have one of the following formats:
11737 \o \c{type\tdescription}
11739 \o \c{file\ttype\tdescription}
11741 \o \c{file\tline\ttype\tdescription}
11745 The task type can have one of the following values:
11749 \o A string starting with \c err, which displays the error icon in the beginning of the line
11750 \o A string starting with \c warn, which displays the warning icon
11751 \o Any other value, which sets the task type to Unknown and does not
11756 The values are not case sensitive.
11758 Lines starting with the hash mark character (#) in the first column are ignored.
11764 \contentspage index.html
11765 \previouspage creator-task-lists.html
11766 \page creator-cli.html
11767 \nextpage creator-keyboard-shortcuts.html
11769 \title Using Command Line Options
11771 You can start Qt Creator and specify some options from the command line.
11772 For example, you can open a file to any line.
11774 To specify command line options, enter the following command in the Qt Creator
11775 installation or build directory:
11777 \c {qtcreator [option] [filename[:line_number]]}
11779 \note You can use either a colon (:) or a plus sign (+) as a separator
11780 between the filename and line number. You can also use a space between the
11781 separator and the line number.
11787 \o \c {C:\qtcreator\bin>qtcreator -help}
11789 \o \c {C:\qtcreator\bin>qtcreator C:\TextFinder\textfinder.cpp:100}
11791 \o \c {C:\qtcreator\bin>qtcreator C:\TextFinder\textfinder.cpp +100}
11795 The following table summarizes the available options:
11804 \o Display help on command line options.
11808 \o Display Qt Creator version.
11812 \o Attempt to connect to an already running instance of Qt Creator.
11815 \o -noload <plugin>
11816 \o Do not load the specified plugin.
11820 \o Output plugin start up and shut down profiling data.
11823 \o -settingspath <path>
11824 \o Override the default path where user settings are stored.
11828 \o Core plugin: override the selected UI color.
11832 \o Debugger plugin: disable the Microsoft Console Debugger (CDB)
11833 engine. For more information, see \l{Debugging}.
11837 \o Debugger plugin: disable the GNU Symbolic Debugger (GDB) engine.
11841 \o Debugger plugin: disable the Qt Script debugger engine.
11844 \o -debug <PID-or-corefile>
11845 \o Debugger plugin: attach to process ID or core file.
11848 \o -wincrashevent <event-handle>
11849 \o Debugger plugin: Attach to crashed processes by using the specified
11853 \o -customwizard-verbose
11854 \o ProjectExplorer plugin: display additional information when loading
11855 custom wizards. For more information about custom wizards, see
11856 \l{Adding New Custom Wizards}
11860 \o ProjectExplorer plugin: load the last session when Qt Creator starts.
11861 Open the projects and files that were open when you last exited Qt Creator.
11862 For more information about managing sessions, see \l{Managing Sessions}.
11871 \contentspage index.html
11872 \previouspage creator-maemo-emulator.html
11873 \page creator-mime-types.html
11874 \nextpage creator-task-lists.html
11876 \title Editing MIME Types
11878 Qt Creator uses the
11879 \l{http://en.wikipedia.org/wiki/Internet_media_type}{Internet media type}
11880 (MIME type) of the file to determine which mode and editor to use for
11881 opening the file. For example, Qt Creator opens C++ source and header files
11882 in the C++ editor, and Qt widget based UI files (.ui) in \QD.
11884 To identify the MIME type of a file, Qt Creator uses matching by pattern
11885 and matching by contents. First, Qt Creator looks at the filename to check
11886 whether it matches the patterns specified for any MIME type. If no match is
11887 found, it checks the contents of the file for magic headers specified for the
11890 The magic headers can contain text strings or bytes. The type of the
11891 header value, string or byte, determines how Qt Creator interprets the
11892 value. Qt Creator searches for the value within a specified
11893 range in the files and takes the priority of the magic header into account.
11894 If you specify wide search ranges, openging files in Qt Creator might take
11895 a long time. Therefore, you are advised to use the recommended values for
11896 the range and priority of the magic header.
11898 If your files do not match the predefined MIME types, you can edit the
11899 MIME types to add filename extensions and magic headers. You cannot
11900 add new MIME types, however.
11902 To edit MIME types:
11906 \o Select \gui {Tools > Options... > Environment > MIME Types}.
11908 \image qtcreator-mime-types.png "MIME Types"
11910 \o In \gui {MIME Type}, select a MIME type.
11912 \o In \gui Patterns, add the filename extension for the type of files
11913 that you want to identify as having this MIME type.
11915 \o Click \gui Add to add \gui {Magic Headers}.
11917 \image qtcreator-mime-types-magic-header.png "Magic Header"
11919 \o In the \gui Value field, specify a text string or bytes that
11920 appear in the files.
11922 \o In the \gui Type field, select the type of the value.
11924 \note You are recommended not to change the range and priority, because
11925 it might cause problems when opening files in Qt Creator.
11931 To revert all the changes you have made to the MIME type definitions,
11932 select \gui {Reset All}.
11934 \note If you now select \gui OK or \gui Apply, you permanently lose all
11935 your own patterns and magic headers. The changes are reverted the next
11936 time you start Qt Creator.
11942 \contentspage index.html
11943 \previouspage creator-debugging-qml.html
11944 \page creator-troubleshooting-debugging.html
11945 \nextpage creator-analyze-mode.html
11947 \title Troubleshooting Debugger
11949 This section lists some typical problems that you might encounter while
11950 debugging and solutions to them.
11952 \section1 Cannot Launch Debugger
11954 Some anti-virus applications do not allow debuggers to retrieve data. For
11955 example, on Windows, launching the debugger might fail with the following
11956 message if the Avira AntiVir is installed on the development PC: \e{The
11957 inferior stopped because it received a signal from the operating system.
11958 Signal name:? signal meaning: Unknown signal.}
11960 Some versions of Avira AntiVir Desktop-Products contain known issues in
11961 various development environments, including Qt Creator. To fix the problem,
11962 Avira instructs you to update to version \c {avipbb.sys 10.0.22.22}. For
11963 more information, see
11964 \l{http://www.avira.com/en/support-for-business-knowledgebase-detail/kbid/805}{Restricted Usability of IDE/Debuggers since 2010-12-08}.
11966 \section1 Debugger Does Not Hit Breakpoints
11968 You might have created a release build that does not contain debug
11969 information. A GNU Compiler Collection (GCC) debug build has the \c {-g}
11970 option on the compiler command line. Check that this option is present in
11971 the \gui {Compile Output} pane. If it is not, adjust your build settings
11972 in the \gui {Projects} mode.
11974 \section1 Debugger Does Not Work
11976 If the debugger does not work properly, try the following:
11980 \o Make sure you use at least Qt Creator 2.1.
11982 \o Make sure the debugger is set up properly. For more information,
11983 see \l{Setting Up Debugger}.
11985 \o In the \gui Debug mode, select \gui {Windows > Views > Debugger
11986 Log} to open the \gui {Debugger Log} view. Browse the contents of
11987 the pane on the right hand side to find out what went wrong.
11988 Always attach the contents of the pane to debugger-related
11989 questions to the Qt Creator mailing list (qt-creator@trolltech.com)
11991 \l{http://creator.pastebin.com}{creator.pastebin.com} before
11992 asking questions in the IRC (on the #qt-creator channel at
11997 \section1 Pointer Variable Members Are Not Displayed Directly
11999 When you use the \gui {Locals and Expressions} view to inspect a pointer
12000 variable and expand the variable tree item, another tree item level
12001 is displayed. To directly display the members of the pointer variable,
12002 select \gui {Dereference Pointers Automatically} in the context menu in the
12003 \gui {Locals and Expressions} view.
12005 \section1 Built-in Debugger Is Slow During Startup and Runtime
12007 The Qt Creator for Windows installation packages install GDB from MinGW.
12008 Unfortunately, GDB is quite slow on Windows. Qt Creator does not cause
12009 this, as it interacts with GDB and adds custom dumpers for Qt types.
12011 \note You can use Qt Creator with MSVC on Windows for debugging.
12013 \section1 Debugger Displays <not in scope> Message
12015 The message is created by the debugging helpers. Qt Creator posts an
12016 expression to the GDB command line to invoke the debugging helpers.
12017 The expression includes the address of the object to examine. This
12018 address might be modified by GDB before the helper function is called. It
12019 is unclear why and when this happens, but if it happens, the debugging
12020 helpers operate on wrong data and come to wrong conclusions. Most likely,
12021 they find garbage and declare the variable to be <not in scope>.
12023 \section1 Application Crashes when Debugging on Mac OS X Snow Leopard
12025 You must use a workaround to use the DYLD_IMAGE_SUFFIX option in the
12026 \gui Projects tab on Mac OS X Snow Leopard. For more information on the
12028 \l{http://wimleers.com/blog/dyld-image-suffix-causing-havoc-on-mac-os-x-snow-leopard}{DYLD_IMAGE_SUFFIX causing havoc on Mac OS X Snow Leopard}.
12030 To use the option, enter the following commands in the Terminal
12033 sudo mv /usr/lib/libSystem.B_debug.dylib /usr/lib/libSystem.B_debug.dylib.backup
12034 sudo cp /usr/lib/libSystem.B.dylib /usr/lib/libSystem.B_debug.dylib.backup
12037 \section1 Debugger Cannot Attach to Running Process on Linux
12039 GDB uses \c ptrace to attach to running processes. Some Linux distributions
12040 do not allow this, which stops all attempts to either directly attach to an
12041 existing process or use the \gui {Run in terminal} option in Qt Creator.
12043 The reasons for this are described in
12044 \l{https://wiki.ubuntu.com/SecurityTeam/Roadmap/KernelHardening#ptrace%20Protection}{KernelHardening}.
12046 However, the usefulness of this security measure seems dubious,
12047 because this feature can be easily disabled. With root permissions, you can
12048 disable the feature immediately by writing \c{0} into
12049 \c{/proc/sys/kernel/yama/ptrace_scope}. Even if you do not have elevated
12050 permissions, you can disable the feature later by adding a library that
12051 calls \c{prctl(0x59616d61, getppid(), 0, 0, 0);}, such as the one in
12052 \c{$QTCREATORDIR/lib/libptracepreload.so} to the LD_PRELOAD environment.
12058 \contentspage index.html
12059 \previouspage creator-qml-performance-monitor.html
12060 \page creator-analyzer.html
12061 \nextpage creator-cache-profiler.html
12063 \title Detecting Memory Leaks
12065 You can use the Memcheck tool included in the
12066 \l{http://valgrind.org/info/tools.html}{Valgrind tool suite} to detect
12067 problems that are related to memory management in applications.
12069 \note Memcheck is supported on Linux and Mac OS.
12071 After you download and install Valgrind tools, you can use Memcheck from Qt
12073 To analyze applications:
12077 \o In the \gui Projects mode, select a release build configuration.
12079 \o Select \gui Analyze to open the \gui Analyze mode.
12081 \o Select \gui {Analyze Memory} on the toolbar.
12084 \inlineimage qtcreator-analyze-start-button.png "Start button"
12085 button to start the application.
12087 \o Use the application to analyze it.
12090 \inlineimage qtcreator-analyzer-stop-button.png "Stop button"
12091 button to view the results of the analysis in the
12092 \gui {Analysis} view.
12096 While the application is running, Memcheck checks all reads and writes of
12097 memory and intercepts calls that allocate or free memory or create or
12098 delete memory blocks. When you stop Memcheck, it displays the results in
12099 the \gui Analysis output pane. Click a line to view where a memory leak
12100 occurred and a stack trace that shows what caused it.
12102 \image analyzer-issues.png "Analysis view"
12104 Move the mouse on on a row to view more information about the function.
12106 For more information about using Memcheck, see
12107 \l{http://valgrind.org/docs/manual/quick-start.html#quick-start.mcrun}
12108 {Interpreting Memcheck's Output} in the Valgrind documentation.
12110 \section1 Selecting Options for Memory Analysis
12112 Stack traces can get quite large and confusing, and therefore, reading them
12113 from the bottom up can help. If the stack trace is not big enough or it is
12114 too big, select \gui {Tools > Options... > Analyzer > Memory Analysis}.
12115 Define the length of the stack trace in the \gui {Backtrace frame count}
12118 Memcheck also reports uses of uninitialised values, most commonly with the
12119 message \gui {Conditional jump or move depends on uninitialised value(s).}
12120 To determine the root cause of these errors, the \gui {Track origins of
12121 uninitialized memory} check box is selected by default. This makes Memcheck
12122 run slower, but the extra information you get often saves a lot of time
12123 figuring out where the uninitialised values are coming from.
12125 Memcheck detects numerous problems in the system libraries, such as the C
12126 library, which come pre-installed with your OS. As you cannot easily fix
12127 them, you want to suppress them. Valgrind reads a list of errors to suppress
12128 at startup. A default suppression file is created by the ./configure script
12129 when the system is built.
12131 You can write your own suppression files if parts of your project contain
12132 errors you cannot fix and you do not want to be reminded of them. Click
12133 \gui Add in the \gui {Memory Analysis} dialog to add the suppression files.
12134 For more information about writing suppression files, see
12135 \l{http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress}
12136 {Suppressing Errors} in the Valgrind documentation.
12138 \image qtcreator-valgrind-memcheck-options.png "Memory Analysis options"
12145 \contentspage index.html
12146 \previouspage creator-analyzer.html
12147 \page creator-cache-profiler.html
12148 \nextpage creator-deployment.html
12150 \title Profiling Function Execution
12152 You can use the Callgrind tool included in the
12153 \l{http://valgrind.org/info/tools.html}{Valgrind tool suite} to detect
12154 problems that are related to cache usage.
12156 After you download and install Valgrind tools, you can use Callgrind from Qt
12158 To analyze applications:
12162 \o In the \gui Projects mode, select a release build configuration.
12164 \o Select \gui Analyze to open the \gui Analyze mode.
12166 \o Select \gui Profile on the toolbar.
12169 \inlineimage qtcreator-analyze-start-button.png "Start button"
12170 button to start the application.
12172 \o Use the application to analyze it.
12175 \inlineimage qtcreator-analyzer-stop-button.png "Stop button"
12176 button to view the results of the analysis in the \gui Profile
12181 Callgrind records the call history of functions that are executed when the
12182 application is run. It collects the number of instructions that are
12183 executed, their relationship to source lines, the relationships of the
12184 caller and callee between functions, and the numbers of such calls. You can
12185 also use cache simulation or branch prediction to gather information about
12186 the runtime behavior of an application.
12188 Double-click a function to view information about the calling functions in
12189 the \gui Callers view and about the called functions in the \gui Callees
12192 \image qtcreator-valgrind-callgrind.png "Profile view"
12194 \section1 Selecting Profiling Options
12196 To specify settings for Callgrind, select \gui {Tools > Options... >
12197 Analyzer > Profiling}.
12199 \image qtcreator-valgrind-callgrind-options.png "Profiling options"
12201 In the \gui {Result view: Show events with inclusive costs higher than}
12202 field, limit the amount of results the profiler gives you to increase
12203 profiler performance.
12205 You can collect information about the system call times and the number of
12206 global bus events of the event type \c Ge that are executed.
12208 \section2 Enabling Full Cache Simulation
12210 By default, only instruction read accesses (Ir) are counted. To fully
12211 simulate the cache, select the \gui {Enable cache simulation} check box.
12212 This enables the following additional event counters:
12216 \o Cache misses on instruction reads (I1mr/I2mr)
12218 \o Data read accesses (Dr) and related cache misses (D1mr/D2mr)
12220 \o Data write accesses (Dw) and related cache misses (D1mw/D2mw)
12224 \section2 Enabling Branch Prediction Simulation
12226 To enable the following additional event counters, select the
12227 \gui {Enable branch prediction simulation} check box:
12231 \o Number of conditional branches executed and related predictor misses
12234 \o Executed indirect jumps and related misses of the jump address
12243 \contentspage index.html
12244 \previouspage creator-help.html
12245 \page creator-advanced.html
12246 \nextpage creator-os-supported-platforms.html
12248 \title Advanced Use
12250 Qt Creator attempts to meet your development needs, whether you are an
12251 experienced Qt developer or a newcomer to Qt. When you install Qt Creator
12252 as a part of \QSDK, the default configuration allows you to start coding,
12253 building, running and debugging applications with very little effort.
12255 However, you can easily change or extend the default configuration, by
12256 choosing a different build system, adding project wizards, integrating
12257 external tools, or editing the standard MIME types that Qt Creator uses
12258 to recognize your files.
12260 You can start Qt Creator and specify some options for running it from the
12263 This following topics describe advanced use of Qt Creator:
12266 \o \l{Operating Systems and Supported Platforms}
12267 \o \l{Adding New Custom Wizards}
12268 \o \l{Setting Up a CMake Project}
12269 \o \l{Setting Up a Generic Project}
12270 \o \l{Using Version Control Systems}
12271 \o \l{Adding Qt Designer Plugins}
12272 \o \l{Using External Tools}
12273 \o \l{Using Maemo or MeeGo Harmattan Emulator}
12274 \o \l{Editing MIME Types}
12275 \o \l{Showing Task List Files in the Build Issues Pane}
12276 \o \l{Using Command Line Options}
12277 \o \l{Keyboard Shortcuts}
12284 \contentspage index.html
12285 \previouspage creator-known-issues.html
12286 \page technical-support.html
12287 \nextpage creator-glossary.html
12289 \title Technical Support
12291 The following table lists Qt support sites and other useful links.
12295 \o What Do You Want to Do
12299 \o Learn more about Qt
12300 \o \l{http://qt.nokia.com/developer/learning/online/training/specialized-elearning/}
12301 {Specialized eLearning Modules Based on Qt Training Modules}
12304 \o Develop Qt applications for desktop and mobile devices
12305 \o \l{http://developer.qt.nokia.com/}{Qt Developer Network}
12308 \o Develop Qt applications for Nokia mobile devices
12309 \o \l{http://www.developer.nokia.com/Develop/Qt/}{Nokia Developer - Qt}
12312 \o Participate in Qt development
12313 \o \l{http://qt.gitorious.org/}{Qt Git Hosting}
12316 \o Find free Qt-based applications
12317 \o \l{http://qt-apps.org/}{Qt Apps}
12320 \o Buy commercial Qt support from Digia
12321 \o \l{http://qt.digia.com/}{Qt Commercial}
12328 \contentspage index.html
12329 \previouspage creator-troubleshooting-debugging.html
12330 \page creator-analyze-mode.html
12331 \nextpage creator-qml-performance-monitor.html
12333 \title Analyzing Code
12335 The memory available on mobile devices is limited and you should use it
12336 carefully. Qt Creator contains tools that you can use to analyze your code.
12338 The \gui {QML Profiler} allows you to profile your Qt
12339 Quick applications. You can inspect binding evaluations, signal handling,
12340 and painting operations when running QML code. This is useful for
12341 identifying potential bottlenecks, especially in the evaluation of bindings.
12343 In addition, Qt Creator integrates Valgrind code analysis tools for
12344 detecting memory leaks and profiling function execution. These tools are
12346 supported on Linux and Mac OS. You have to download and install them
12347 separately to use them from Qt Creator.
12349 You can use the code analysis tools in the \gui Analyze mode or from the
12350 \gui {Debug > Start Analyzer} menu. In \gui Analyze mode, you can switch
12351 between tools by selecting them in the menu on the toolbar.
12353 \image qtcreator-analyze-menu "Analyze mode menu"
12355 To run the Valgrind tools on a remote device over SSH, select \gui {Debug >
12356 Start Analyzer > Start Remote}.
12358 To stop the currently running analyzer, select \gui {Debug > Start Analyzer
12361 To select options for the Valgrind tools, select \gui {Tools > Options... >
12364 The following sections describe how to use the code analysis tools:
12368 \o \l{Profiling QML Applications} describes how to inspect binding
12369 evaluations, signal handling, and painting operations when running
12372 \o \l{Detecting Memory Leaks} describes how to use the Valgrind
12373 Memcheck tool to detect problems in memory management.
12375 \o \l{Profiling Function Execution} describes how to use the Valgrind Callgrind
12376 tool to find cache misses in the code.
12384 \contentspage index.html
12385 \previouspage creator-analyze-mode.html
12386 \page creator-qml-performance-monitor.html
12387 \nextpage creator-analyzer.html
12389 \title Profiling QML Applications
12391 To monitor the performance of an application in the QML Profiler:
12395 \o In the \gui Projects mode, select Qt 4.7.4 in the \gui {Qt version}
12398 \o Select \gui Analyze to open the \gui Analyze mode.
12401 \inlineimage qtcreator-analyze-start-button.png "Start button"
12402 button to start the application from the QML Profiler.
12404 \note: If data collection does not start automatically, select the
12405 \inlineimage qtcreator-analyzer-button.png "Analyzer button"
12410 When you start analyzing an application, the application is launched, and
12411 the QML Profiler immediately begins to collect data. This is indicated by
12412 the time running in the \gui Elapsed field.
12414 Data is collected until you select the
12415 \inlineimage qtcreator-analyzer-stop-button.png "Stop button"
12416 button. Data collection takes time, and therefore, there might be a delay
12417 before the data is displayed.
12419 \image qtcreator-qml-performance-monitor-toolbar.png "QML Profiler toolbar"
12421 Do not use application commands to exit the application, because data is
12422 sent to the QML Profiler when you select the \gui Stop button.
12423 The application continues to run for some seconds, after which it is stopped
12424 automatically. If you exit the application, the data is not sent.
12426 Select the \inlineimage qtcreator-analyzer-button.png "Analyzer button"
12427 button to disable the automatic start of the data collection when an
12428 application is launched. Data collection starts when you select the button
12431 To monitor applications running on devices:
12435 \o On the command line, enter the following command to launch the Qt
12436 Quick application with parameters:
12438 \c {<application> -qmljsdebugger=port:33456}
12440 The port number is specified in the run settings of the project in
12441 the \gui {Debug port} field.
12443 \o Select \gui {Debug > Start Analyzer > Attach...} to attach the QML
12444 Profiler to the running application.
12448 \section1 Analyzing Collected Data
12450 The \gui Timeline view displays graphical representations of:
12454 \o Painting operations
12456 \o Compiling the QML sources
12458 \o Creating elements
12460 \o Binding evaluations
12464 \o Summary of the recorded period
12468 \image qtcreator-qml-performance-monitor.png "QML Profiler"
12470 The outline summarizes the period for which data was collected. Drag the
12471 range bar or click the outline to move on the outline. Drag the borders of
12472 the range bar to zoom in and out.
12474 Additional information is displayed on the rows above the outline.
12475 Each row in the timeline describes a type of QML events that were recorded.
12476 Move the cursor on an event on a row to see how long it takes and where
12477 in the source it is being called.
12479 On the \gui Binding row, you can see when a binding is evaluated and how
12480 long the evaluation takes. Move the mouse over the binding for details
12481 about the binding: location in the source code, duration, and source
12484 Click the binding to move the cursor in the code editor to the part of the
12485 code where the binding is called.
12487 The time bar at the top of the \gui Timeline view displays the time in
12488 seconds. To see the time in milliseconds, move the mouse on the time bar.
12490 \section1 Viewing Bindings
12492 The \gui Bindings view displays the number of times each binding is called
12493 and the time the calls take. This allows you to examine which bindings you
12494 need to optimize. A high number of calls might indicate that a binding is
12495 called unnecessarily. Click on a binding to move to it in the source code
12496 in the code editor.
12498 \image qtcreator-analyzer-bindings.png "Bindings view"
12500 \section1 Viewing Calling and Called Bindings
12502 The \gui Callees and \gui Callers views show dependencies between bindings.
12503 They allow you to examine the internal functions of the application.
12505 The \gui Callees view summarizes the QML events that a binding triggers.
12506 This tells you which QML events are affected if you change a binding.
12508 \image qtcreator-qml-performance-monitor-callees.png "Callees view"
12510 The \gui Callers view summarizes the QML events that trigger a binding.
12511 This tells you what caused a change in a binding.
12513 \image qtcreator-qml-performance-monitor-callers.png "Callers view"
12515 Click on a binding to move to it in the source code in the code editor.
12517 \section2 Viewing More Data
12519 The QML JavaScript engine optimizes trivial bindings. The QML Profiler
12520 does not receive information about optimized bindings, and
12521 therefore, it displays the text \gui {<bytecode>} and the message
12522 \gui {Source code not available} in the \gui Callees and \gui {Callers}
12525 To inspect the optimized bindings, turn off the QML optimizer by setting the
12526 environment variable QML_DISABLE_OPTIMIZER to 1. To set the environment
12527 variable for the current project in the project settings:
12531 \o Select \gui {Projects > Run}.
12533 \o In \gui {Run Environment}, click \gui Add.
12535 \o Add the QML_DISABLE_OPTIMIZER variable and set its value to 1.