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 Generic Linux Devices}
70 \o \l{Connecting Symbian Devices}
71 \o \l{Managing Sessions}
75 \o \l{Using the Editor}
76 \o \l{Semantic Highlighting}
77 \o \l{Checking Code Syntax}
78 \o \l{Completing Code}
80 \o \l{Finding and Replacing}
82 \o \l{Using Qt Quick Toolbars}
83 \o \l{Searching With the Locator}
84 \o \l{Pasting and Fetching Code Snippets}
85 \o \l{Using Text Editing Macros}
86 \o \l{Configuring the Editor}
87 \o \l{Using FakeVim Mode}
89 \o \l{Developing Application UI}
91 \o \l{Developing Qt Quick Applications}
93 \o \l {Creating Qt Quick Projects}
94 \o \l {Using Qt Quick Designer}
95 \o \l {Creating Components}
96 \o \l {Creating Buttons}
97 \o \l {Creating Scalable Buttons and Borders}
98 \o \l {Creating Screens}
99 \o \l {Animating Screens}
100 \o \l {Adding User Interaction Methods}
101 \o \l {Exporting Designs from Graphics Software}
102 \o \l {Implementing Application Logic}
103 \o \l {Using QML Modules with Plugins}
105 \o \l{Developing Widget Based Applications}
106 \o \l{Optimizing Applications for Mobile Devices}
108 \o \l{Building and Running Applications}
110 \o \l{Building Applications for Multiple Targets}
111 \o \l{Running Applications on Multiple Targets}
112 \o \l{Specifying Build Settings}
114 \o \l{Adding Qt Versions}
115 \o \l{Adding Tool Chains}
117 \o \l{Specifying Run Settings}
118 \o \l{Specifying Editor Settings}
119 \o \l{Specifying Code Style Settings}
120 \o \l{Specifying Dependencies}
124 \o \l{Debugging the Example Application}
125 \o \l{Launching the Debugger}
126 \o \l{Interacting with the Debugger}
127 \o \l{Setting Up Debugger}
128 \o \l{Using Debugging Helpers}
129 \o \l{Debugging Qt Quick Projects}
130 \o \l{Troubleshooting Debugger}
132 \o \l{Analyzing Code}
134 \o \l{Profiling QML Applications}
135 \o \l{Detecting Memory Leaks}
136 \o \l{Profiling Function Execution}
138 \o \l{Deploying Applications to Mobile Devices}
140 \o \l{Deploying Applications to Symbian Devices}
141 \o \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}
142 \o \l{Publishing Maemo Applications to Extras-devel}
143 \o \l{Publishing Applications to Ovi Store}
144 \o \l{Building with Remote Compiler}
149 \o \l{Operating Systems and Supported Platforms}
150 \o \l{Adding New Custom Wizards}
151 \o \l{Setting Up a CMake Project}
152 \o \l{Setting Up a Generic Project}
153 \o \l{Using Version Control Systems}
154 \o \l{Adding Qt Designer Plugins}
155 \o \l{Using External Tools}
156 \o \l{Using Maemo or MeeGo Harmattan Emulator}
157 \o \l{Editing MIME Types}
158 \o \l{Showing Task List Files in the Build Issues Pane}
159 \o \l{Using Command Line Options}
160 \o \l{Keyboard Shortcuts}
163 \o \l{Tips and Tricks}
165 \o \l{Technical Support}
167 \o \l{Acknowledgements}
173 \contentspage index.html
174 \previouspage index.html
175 \page creator-overview.html
176 \nextpage creator-quick-tour.html
178 \title Introducing Qt Creator
180 Qt Creator is an integrated development environment (IDE) that provides you with
181 tools to design and develop applications with the Qt application framework. Qt is designed for
182 developing applications and user interfaces once and deploying them across several
183 desktop and mobile operating systems. Qt Creator provides you with tools for
184 accomplishing your tasks throughout the whole application development life-cycle,
185 from creating a project to deploying the application on the target platforms.
187 \image qtcreator-overview.png "Qt Creator overview"
189 \section1 Cross-platform Development
191 One of the major advantages of Qt Creator is that it allows a team of developers
192 to share a project across different development platforms with a common tool
193 for development and debugging.
195 The recommended way to build a project is to use a version control system.
196 Store and edit only project source files and the .pro and .pri files (for qmake)
197 or CMakeLists.txt and *.cmake files (for CMake). Do not store
198 files generated by the build system or Qt Creator, such as makefiles,
199 .pro.user, and object files. Other approaches are possible,
200 but we recommend that you do not use network resources, for example.
202 Qt Creator allows you to specify separate build settings
203 for each development platform. By default, \l{glossary-shadow-build}{shadow builds} are used to
204 keep the build specific files separate from the source.
206 You can create separate versions of project files to keep platform-dependent
207 code separate. You can use qmake
208 \l{http://qt.nokia.com/doc/4.7/qmake-tutorial.html#adding-platform-specific-source-files}{scopes}
209 to select the file to process depending on which platform qmake is run on.
211 Items such as open files, breakpoints, and evaluated expressions are stored in
212 sessions. They are not considered to be part of the
213 information shared across platforms.
215 \section1 Creating Projects
217 But why do you need projects? To be able to build and run applications,
218 Qt Creator needs the same information as a compiler would need. This information
219 is specified in the project build and run settings.
221 Creating a project allows you to:
225 \o Group files together
227 \o Add custom build steps
229 \o Include forms and resource files
231 \o Specify settings for running applications
235 Setting up a new project in Qt Creator is aided by a wizard that guides
236 you step-by-step through the project creation process. In the first step, you
237 select the type of the project from the categories: Qt Quick project, Qt widget
238 project, or other project. Next, you select a location for the project and
239 specify settings for it.
241 \image qtcreator-new-qt-quick-project-wizard.png
243 When you have completed the steps, Qt Creator automatically generates the
244 project with required headers, source files, user interface descriptions
245 and project files, as defined by the wizard.
246 For example, if you choose to create a Qt Quick application, Qt Creator
247 generates a QML file that you can modify with the integrated \QMLD.
249 \section2 Adding Libraries
251 In addition to Qt libraries, you can link your application to other
252 libraries, such as system libraries or your own libraries. Further, your
253 own libraries might link to other libraries. To be able to compile your
254 project, you must add the libraries to your project. This also enables
255 code completion and syntax highlighting for the libraries.
256 The procedure of adding a library to a project depends on the build
259 \section2 Version Control Systems
261 Qt Creator uses the version control system's command line clients to access
262 your repositories. The following version control systems are supported:
280 The functions available to you in Qt Creator depend on the version control
281 system. Basic functions are available for all the supported systems. They include
282 comparing files with the latest versions stored in the repository and displaying the
283 differences, viewing versioning history and change details, annotating files,
284 and committing and reverting changes.
286 \section1 Designing User Interfaces
288 Qt Creator provides two integrated visual editors, \QMLD and \QD.
290 \image qtcreator-ui-designers.png "Qt Quick Designer and Qt Designer"
292 Large high-resolution screens, touch input, and significant graphics power
293 are becoming common in portable consumer devices, such as mobile
294 phones, media players, set-top boxes, and netbooks. To fully benefit from
295 these features and to create intuitive, modern-looking, fluid user interfaces,
296 you can use \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}.
298 Qt Quick consists of a rich set of user interface elements, a declarative
299 language for describing user interfaces, and a language runtime. A
300 collection of C++ APIs is used to integrate these high level features with
301 classic Qt applications.
303 You can edit QML code in the code editor or in the integrated \QMLD.
304 The integration includes project management and code completion.
306 If you need a traditional user interface that is clearly structured and
307 enforces a platform look and feel, you can use the integrated \QD. You can
308 compose and customize your widgets or dialogs and test them using different
309 styles and resolutions.
311 \section1 Code Editor
313 As an IDE, Qt Creator differs from a text editor in that it knows how to build and run
314 applications. It understands the C++ and QML languages as code, not just as plain text. This allows
319 \o Enable you to write well formatted code
321 \o Anticipate what you are going to write and complete the code
323 \o Display inline error and warning messages
325 \o Enable you to semantically navigate to classes, functions, and symbols
327 \o Provide you with context-sensitive help on classes, functions, and symbols
329 \o Rename symbols in an intelligent way, so that other symbols with the same name
330 that belong to other scopes are not renamed
332 \o Show you the locations in code where a function is declared or called
336 You can use the code editor to write code in Qt C++ or in the
337 QML declarative programming language.
338 QML is an extension to JavaScript, that provides a mechanism to declaratively build
339 an object tree of QML elements. QML improves the integration between JavaScript and
340 Qt's existing QObject based type system, adds support for automatic property bindings
341 and provides network transparency at the language level.
345 Qt Creator is integrated with cross-platform systems for build automation:
346 qmake and CMake. In addition, you can import generic projects that do not use qmake
347 or CMake, and specify that Qt Creator ignores your build system.
349 Qt Creator provides support for building and running Qt applications for
350 desktop environment (Windows, Linux, and Mac OS) and mobile devices
351 (Symbian, Maemo, and MeeGo Harmattan).
352 Build settings allow you to quickly switch between build targets.
354 When you install the \QSDK, the build and run settings for the Harmattan,
356 targets are set up automatically. However, you need to install and configure some
357 additional software on the devices to be able to connect to them from the
360 \note The only supported build system for mobile applications in Qt
365 If you install Qt Creator as part of \QSDK, the GNU Symbolic Debugger
366 is installed automatically and you should be ready to start debugging after
367 you create a new project. However, you can change the setup to use debugging
368 tools for Windows, for example.
369 You can connect mobile devices to your development PC and debug processes
370 running on the devices.
372 You can use code analysis tools to detect memory leaks, profile cache usage,
373 and profile Qt Quick applications.
375 You can test applications that are intended for mobile devices in the Qt
376 Simulator and Maemo Emulator, but you also need to test the applications
381 Qt Creator is integrated to several external native debuggers:
385 \o GNU Symbolic Debugger (GDB)
387 \o Microsoft Console Debugger (CDB)
389 \o internal JavaScript debugger
393 You can use the Qt Creator \gui Debug mode to inspect the state of your
394 application while debugging. You can interact with the debugger in several
395 ways, including the following:
398 \o Go through a program line-by-line or instruction-by-instruction.
399 \o Interrupt running programs.
401 \o Examine the contents of the call stack.
402 \o Examine and modify registers and memory contents of
403 the debugged program.
404 \o Examine and modify registers and memory contents of
405 local and global variables.
406 \o Examine the list of loaded shared libraries.
407 \o Create snapshots of the current state of the debugged program
408 and re-examine them later.
411 Qt Creator displays the raw information provided by the native debuggers
412 in a clear and concise manner with the goal to simplify the debugging process
413 as much as possible without losing the power of the native debuggers.
415 In addition to the generic IDE functionality provided by stack view, views for
416 locals and expressions, registers, and so on, Qt Creator includes
417 features to make debugging Qt-based applications easy. The debugger
418 plugin understands the internal layout of several Qt classes, for
419 example, QString, the Qt containers, and most importantly QObject
420 (and classes derived from it), as well as most containers of the C++
421 Standard Library and some GCC and Symbian extensions. This
422 deeper understanding is used to present objects of such classes in
425 \section3 QML Script Console
427 You can use the Qt Creator \gui Debug mode to inspect the state of
428 the application while debugging JavaScript functions. You can set breakpoints,
429 view call stack trace, and examine locals and expressions.
431 When the application is interrupted by a breakpoint, you can use the \gui {QML
432 Script Console} to execute JavaScript expressions in the current context. You can
433 type JavaScript expressions and use them to get information about the state of the
434 application, such as property values.
436 If you change property values or add properties in the code editor, the
437 changes are updated in the running application when they are saved.
439 \section3 QML Inspector
441 While the application is running, you can use the \gui {QML Inspector} view to
442 explore the object structure, debug animations, and inspect colors. When debugging
443 complex applications, you can use the inspection mode to jump to the position in code
444 where an element is defined.
446 \section2 Code Analysis Tools
448 The memory available on devices is limited and you should use it carefully.
449 Qt Creator integrates Valgrind code analysis tools for detecting memory
450 leaks and profiling function execution. These tools are only supported on
452 Mac OS. You must download and install them separately to use them from Qt
455 The QML Profiler is installed as part of Qt Creator. It allows you
456 to profile your Qt Quick applications and is available on all supported
457 development platforms.
459 \section2 Qt Simulator
461 You can use the Qt Simulator to test Qt applications that are intended
462 for mobile devices in an environment similar to that of the device. You
463 can change the information that the device has about its configuration
466 The Qt Simulator is installed as part of the \QSDK. After it is
467 installed, you can select it as a build target in Qt Creator.
469 \section2 Maemo and MeeGo Harmattan Emulator
471 The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
472 of the \QSDK. After they are installed, you can start them from Qt Creator.
474 The Maemo 5 emulator emulates the Nokia N900 device environment. You can test
475 applications in conditions practically identical to running the application
476 on a Nokia N900 device with the software update release 1.3 (V20.2010.36-2).
478 The Harmattan emulator emulates the Nokia N9 device environment.
480 With the emulators, you can test how your application reacts to hardware
481 controls, such as the power button, and to the touch screen.
482 Usually, it is faster to test on a real device connected to the development
483 PC than to use the emulators.
487 Qt Creator deploy configurations handle the packaging of the application as an
488 executable and copying it to a location developers want to run the executable at.
489 The files can be copied to a location in the file system of the development PC
490 or to a mobile device.
492 Qt Creator allows you to create installation packages for Symbian, Maemo,
494 devices that are suitable for publishing on Ovi Store and other channels.
499 \contentspage index.html
500 \previouspage creator-advanced.html
501 \page creator-os-supported-platforms.html
502 \nextpage creator-project-wizards.html
504 \title Operating Systems and Supported Platforms
506 \section1 Operating Systems
508 Qt Creator is available in binary packages for the following operating
512 \o Windows XP Service Pack 2
514 \o (K)Ubuntu Linux 8.04 (32-bit and 64-bit) or later, with the following:
521 \o libfontconfig1-dev
530 \o If you are using QtOpenGL, libgl-dev and libglu-dev
532 \o Mac OS 10.5 or later with the following:
534 \o Xcode tools for your Mac OS X version available from your Mac
535 OS X installation DVDs or at \l http://developer.apple.com.
539 \omit ## Are the Xcode tools still needed separately? \endomit
541 \section1 Compiling Qt Creator from Source
543 To build Qt Creator itself from the source, see the requirements and
544 instructions in the readme file that is located in the source repository.
546 \section1 Supported Platforms
548 You can develop applications for the following platforms:
560 \o Generic remote Linux
566 The following table summarizes operating system support for developing
567 applications for mobile device platforms.
571 \o {1,6} Operating system
578 \o Generic Remote Linux
596 \o Yes (by using Remote Compiler for building)
604 \o Yes (by using Remote Compiler for building)
610 \contentspage index.html
611 \previouspage creator-overview.html
612 \page creator-quick-tour.html
613 \nextpage creator-getting-started.html
615 \title Qt Creator User Interface
617 \image qtcreator-breakdown.png
619 When you start Qt Creator, it opens to the \gui Welcome mode, where you can:
623 \o Read news from the Qt labs
625 \o Open tutorials and example projects
627 \o Create and open projects
629 \o Send feedback to the development team
631 \o Open recent sessions and projects
635 You can use the mode selector to change to another Qt Creator mode.
636 The following image displays an example application in \gui Edit mode
637 and \gui Design mode.
639 \image qtcreator-qt-quick-editors.png "Edit mode and Design mode"
641 Qt Creator has been localized into several languages. If the system language
642 is one of the supported languages, it is automatically selected. To change
643 the language, select \gui {Tools > Options > Environment} and select a language
644 in the \gui Language field. The change takes effect after you restart Qt Creator.
646 \section1 Qt Creator Modes
648 The mode selector allows you to quickly switch between tasks such as
649 editing project and source files, designing application UIs,
650 configuring how projects are built and
651 executed, and debugging your applications. To change modes, click the
652 icons, or use the \l{keyboard-shortcuts}{corresponding keyboard shortcut}.
654 You can use Qt Creator in the following modes:
657 \o \gui Welcome mode for opening projects.
658 \o \gui{\l{Using the Editor}{Edit}} mode for editing project and source files.
659 \o \gui{\l{Developing Application UI}{Design}} mode for designing and developing
660 application user interfaces. This mode is available for UI files (.ui or
662 \o \gui{\l{Debugging}{Debug}} mode for inspecting the state of your program while
664 \o \gui{\l{Specifying Build Settings}{Projects}} mode for configuring project building and
665 execution. This mode is available when a project is open.
666 \o \gui{\l{Analyzing Code}{Analyze}} mode for using code analysis tools
667 to detect memory leaks and profile C++ or QML code.
668 \o \gui{\l{Getting Help}{Help}} mode for viewing Qt documentation.
671 Certain actions in Qt Creator trigger a mode change. Clicking on
672 \gui {Debug} > \gui {Start Debugging} > \gui {Start Debugging}
673 automatically switches to \gui {Debug} mode.
676 \section1 Browsing Project Contents
678 The sidebar is available in the \gui Edit and \gui Debug modes.
679 Use the sidebar to browse projects, files, and bookmarks, and to view
681 \image qtcreator-sidebar.png
683 You can select the content of the sidebar in the sidebar menu:
685 \o \gui Projects shows a list of projects open in the current
687 \o \gui{Open Documents} shows currently open files.
688 \o \gui Bookmarks shows all bookmarks for the current session.
689 \o \gui{File System} shows all files in the currently selected
691 \o \gui {Class View} shows the class hierarchy of the currently
693 \o \gui Outline shows the symbol hierachy of a C++ file and the element hierarchy of a QML file.
694 \o \gui {Type Hierarchy} shows the base classes of a class.
698 You can change the view of the sidebar in the following ways:
700 \o To toggle the sidebar, click \inlineimage qtcreator-togglebutton.png
701 or press \key Alt+0 (\key Cmd+0 on Mac OS X).
702 \o To split the sidebar, click \inlineimage qtcreator-splitbar.png
703 . Select new content to view in the split view.
704 \o To close a sidebar view, click
705 \inlineimage qtcreator-closesidebar.png
709 The additional options in each view are described in the following
712 \section2 Viewing Project Files
714 The sidebar displays projects in a project tree. The project tree contains
715 a list of all projects open in the current session. The files for each
716 project are grouped according to their file type.
718 You can use the project tree in the following ways:
720 \o To bring up a context menu containing the actions most commonly
721 needed right-click an item in the project tree.
722 For example, through the menu of the project root directory you can,
723 among other actions, build, re-build, clean and run the project.
724 \o To hide the categories and sort project files alphabetically, click
725 \inlineimage qtcreator-filter.png
726 and select \gui{Simplify Tree}.
727 \o To hide source files which are automatically generated by the build
728 system, during a build, click \inlineimage qtcreator-filter.png
729 and select \gui{Hide Generated Files}.
730 \o To keep the position in the project tree synchronized with the file
731 currently opened in the editor, click
732 \inlineimage qtcreator-synchronizefocus.png
734 \o To see the absolute path of a file, move the mouse pointer over the
738 \section2 Viewing the File System
740 If you cannot see a file in the \gui Projects view, switch to the
741 \gui {File System} view, which shows all the files in the file system.
743 To keep the position in the tree synchronized with the file
744 opened in the editor, click
745 \inlineimage qtcreator-synchronizefocus.png
748 \section2 Viewing the Class Hierarchy
750 The \gui {Class View} shows the class hierarchy of the currently
751 open projects. To organize the view by subprojects, click
752 \inlineimage qtcreator-show-subprojects.png
755 \section2 Viewing QML Elements
757 The \gui Outline view shows the element hierarchy in a QML file.
761 \o To see a complete list of all bindings, click
762 \inlineimage qtcreator-filter.png
763 and select \gui{Show All Bindings}.
765 \o To keep the position in the view synchronized with the element
766 selected in the editor, click
767 \inlineimage qtcreator-synchronizefocus.png
772 \section2 Viewing Type Hierarchy
774 To view the base classes of a class, right-click the class and select
775 \gui {Open Type Hierarchy} or press \key {Ctrl+Shift+T}.
777 \section1 Viewing Output
779 The task pane in Qt Creator can display one of the following panes:
781 \o \gui{Build Issues}
782 \o \gui{Search Results}
783 \o \gui{Application Output}
784 \o \gui{Compile Output}
785 \o \gui{General Messages}
787 \o \gui{Version Control}
790 Output panes are available in all \l{Qt Creator modes}{modes}.
791 Click the name of an output pane to open the pane. To maximize
792 an open output pane, click the \gui {Maximize Output Pane} button
793 or press \key {Alt+9}.
795 To search within the \gui{Application Output} and \gui{Compile Output}
796 panes, press \key {Ctrl+F} when the pane is active. Enter search
797 criteria in the \gui Find field and click the left and right arrows to
798 search down and up in the pane.
800 To open the \gui{General Messages}, \gui{Analysis}, and \gui{Version Control}
801 panes, select \gui {Window > Output Panes}.
804 \section2 Build Issues
806 The \gui{Build Issues} pane provides a list of errors and warnings
807 encountered during a build. The pane filters out irrelevant output from
808 the build tools and presents the issues in an organized way.
810 Right-clicking on a line brings up a context menu with options to copy
811 the contents and to show a version control annotation view of the
812 line that causes the error message.
814 \image qtcreator-build-issues.png
816 To view task lists in the \gui{Build Issues} pane, click
817 \inlineimage qtcreator-filter.png
818 and select \gui{My Tasks}. Entries from a task list file (.tasks) are
819 imported to the pane. Press \key F6 and \key Shift+F6 to jump from one issue
822 For more information about creating task files, see
823 \l{Showing Task List Files in the Build Issues Pane}.
825 \section2 Search Results
827 The \gui{Search Results} pane displays the results for global searches,
828 for example, searching within a current document, files on disk, or all
831 The figure below shows an example search result for all
832 occurrences of \c textfinder within the \c "/TextFinder" directory.
834 \image qtcreator-search-pane.png
837 \section2 Application Output
839 The \gui{Application Output} pane displays the status of a program when
840 it is executed, and the debug output.
842 The figure below shows an example output from qDebug().
844 \image qtcreator-application-output.png
847 \section2 Compile Output
849 The \gui{Compile Output} pane provides all output from the compiler.
850 The \gui{Compile Output} is a more detailed version of information
851 displayed in the \gui{Build Issues} pane.
853 \image qtcreator-compile-pane.png
855 \section1 Navigating with Keyboard
857 Qt Creator caters not only to developers who are used to using the mouse,
858 but also to developers who are more comfortable with the keyboard. A wide
859 range of \l{keyboard-shortcuts}{keyboard} and
860 \l{Searching With the Locator}{navigation} shortcuts are available to help
861 speed up the process of developing your application.
867 \contentspage index.html
868 \previouspage creator-remote-compiler.html
869 \page creator-help.html
870 \nextpage creator-advanced.html
874 Qt Creator comes fully integrated with Qt documentation and
875 examples using the Qt Help plugin.
878 \o To view documentation, switch to \gui Help mode.
879 \o To obtain context sensitive help, move the text cursor to a Qt class
880 or function and press \key F1. The documentation is displayed in a
881 pane next to the code editor, or, if there is not enough vertical
882 space, in the fullscreen \gui Help mode.
883 \o To select and configure how the documentation is displayed in the
884 \gui Help mode, select \gui Tools > \gui Options... > \gui Help.
887 The following image displays the \gui Search pane in the \gui Help mode.
889 \image qtcreator-help-search.png
891 The following image displays the context sensitive help in the \gui Edit
894 \image qtcreator-context-sensitive-help.png
896 \section1 Finding Information in Qt Documentation
898 Qt Creator, \QSDK and other Qt deliverables contain documentation
899 as .qch files. All the documentation is accessible in the \gui Help mode.
901 To find information in the documentation, select:
905 \o \gui Bookmarks to view a list of pages on which you have added bookmarks.
907 \o \gui Contents to see all the documentation installed on the development
908 PC and to browse the documentation contents.
910 \o \gui Index to find information based on a list of keywords in all the
913 \o \gui {Open Pages} to view a list of currently open documentation pages.
915 \o \gui Search to search from all the installed documents.
919 \section2 Adding Bookmarks to Help Pages
921 You can add bookmarks to useful help pages to easily find them later
922 in the \gui Bookmarks view. You can either use the page title as the
923 bookmark or change it to any text. You can organize the bookmarks in
926 \image qtcreator-help-add-bookmark-dlg.png "Add Bookmark dialog"
928 To add a bookmark to an open help page:
933 \inlineimage qtcreator-help-add-bookmark.png
934 (\gui {Add Bookmark}) button on the toolbar.
936 \o In the \gui {Add Bookmark} dialog, click \gui OK to save the
937 page title as a bookmark in the \gui Bookmarks folder.
941 To import and export bookmarks, select \gui {Tools > Options... > Help >
942 General Settings > Import} or \gui Export.
944 \section1 Adding External Documentation
946 You can display external documentation in the \gui Help mode.
947 To augment or replace the documentation that ships with Qt Creator and Qt:
949 \o Create a .qch file from your documentation.
951 For information on how to prepare your documentation and create a
953 \l{http://doc.qt.nokia.com/4.7/qthelp-framework.html}{The Qt Help Framework}.
954 \o To add the .qch file to Qt Creator, select \gui Tools >
955 \gui Options... > \gui Help > \gui Documentation > \gui Add.
958 \section1 Detaching the Help Window
960 By default, context-sensitive help is opened in a window next to the
961 code editor when you press \key F1. If there is not enough vertical
962 space, the help opens in the full-screen help mode.
964 You can specify that the help always opens in full-screen mode or
965 is detached to an external window. Select \gui {Tools > Options... > Help >
966 General Settings} and specify settings for displaying context-sensitive help
967 in the \gui {On context help} field. To detach the help window, select
968 \gui {Always Show Help in External Window}.
970 You can select the help page to open upon startup in the \gui {Home Page}
973 \section1 Using Documentation Filters
975 You can filter the documents displayed in the \gui Help mode to find
976 relevant information faster. Select from a list of filters in the
977 \gui {Filtered by} field. The contents of the \gui Index and \gui Contents
978 pane in the sidebar change accordingly.
980 \image qtcreator-help-filters.png "Help filters"
982 You can modify the filters to include external documentation, for example,
983 or you can define your own filters. To construct filters, you can use the
984 filter attributes that are specified in the documentation. Each document
985 contains at least one filter attribute. If several documents contain the
986 same filter attribute, such as \c tools, you can use that attribute to
987 include all those documents.
993 \o Select \gui {Tools > Options... > Help > Filters > Add}.
995 \o Enter a name for the filter and press \gui {OK}.
997 \o In \gui Attributes, select the documents that you want to include
1000 \image qtcreator-help-filter-attributes.png "Help filter attributes"
1004 \o In the \gui Help mode, select the filter in the \gui {Filtered by}
1005 field to see the filtered documentation in the sidebar.
1009 To modify filters, select a filter in \gui Filters, select the attributes,
1010 and then click \gui Apply.
1012 To remove filters, select them in \gui Filters, and click \gui Remove.
1018 \contentspage index.html
1019 \previouspage creator-editor-fakevim.html
1020 \page creator-design-mode.html
1021 \nextpage creator-visual-editor.html
1023 \title Developing Application UI
1025 Large high-resolution screens, touch input, and significant graphics power
1026 are becoming common in portable consumer devices, such as mobile
1027 phones, media players, set-top boxes, and netbooks. To fully benefit from
1028 these features and to create intuitive, modern-looking, fluid user interfaces,
1029 you can use \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}.
1031 Qt Quick consists of a rich set of user interface elements, a declarative
1032 language for describing user interfaces, and a language runtime. A
1033 collection of C++ APIs is used to integrate these high level features with
1034 classic Qt applications.
1036 You can edit QML code in the code editor or in the integrated \QMLD.
1038 \image qtcreator-design-mode.png "Design mode"
1040 The integration includes project management and code completion.
1042 If you need a traditional user interface that is clearly structured and
1043 enforces a platform look and feel, you can use the integrated \QD. You can
1044 compose and customize your widgets or dialogs and test them using different
1045 styles and resolutions.
1047 The following sections describe how to develop application UI:
1051 \o \l{Developing Qt Quick Applications}
1052 \o \l{Developing Widget Based Applications}
1053 \o \l{Optimizing Applications for Mobile Devices}
1061 \contentspage index.html
1062 \previouspage creator-qml-modules-with-plugins.html
1063 \page creator-using-qt-designer.html
1064 \nextpage creator-usability.html
1066 \title Developing Widget Based Applications
1068 Widgets and forms created with \QD are integrated seamlessly with
1069 programmed code by using the Qt signals and slots mechanism that allows you
1070 to easily assign behavior to
1071 graphical elements. All properties set in \QD can be changed dynamically within the code.
1072 Furthermore, features such as widget promotion and custom plugins allow you to use your
1073 own widgets with \QD. For more information, see
1074 \l{Adding Qt Designer Plugins}.
1076 Qt Creator automatically opens all .ui files in the integrated \QD, in
1079 \image qtcreator-formedit.png
1081 For more information about \QD, see the
1082 \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
1084 Generally, the integrated \QD contains the same functions as the standalone
1085 \QD. The following sections describe the differences.
1087 \section1 Code Editor Integration
1089 To switch between forms (\gui Design mode) and code (\gui Edit mode),
1090 press \key Shift+F4.
1092 You can use Qt Creator to create stub implementations of slot functions.
1093 In the \gui Design mode, right-click a widget to open a context menu, and
1094 then select \gui {Go to Slot...}. Select a signal in the list to go to an
1095 existing slot function or to create a new slot function.
1097 \section1 Managing Image Resources
1099 In standalone \QD, image resources are created using the built-in
1100 \gui {Resource Editor}. In Qt Creator, .ui files are usually part of a
1101 project, which may contain several resource files (.qrc). They are created
1102 and maintained by using the Qt Creator Resource Editor. The \QD
1103 \gui {Resource Editor} is de-activated and the image resources are
1104 displayed in the \QD \gui {Resource Browser}.
1106 \section1 Specifying Settings for Qt Designer
1108 To change the layout of \QD user interface elements:
1111 \o Select \gui Tools > \gui{Form Editor} > \gui Views >
1114 When this option is unchecked, you can change the layout.
1115 \o Click the header of an element and drag the element to a new
1119 To specify settings for \QD:
1123 \o Select \gui Tools > \gui Options... > \gui Designer.
1125 \o Specify settins for generating classes and code in \gui {Class
1128 \o Specify embedded device profiles, that determine style, font, and
1129 screen resolution, for example, in \gui{Embedded Design}.
1131 \o Specify settings for the grid and previewing forms in \gui Forms.
1133 \o Specify an additional folder for saving templates in \gui{Template
1138 To preview the settings, select \gui Tools > \gui{Form Editor} >
1139 \gui Preview, or press \key Alt+Shift+R.
1141 \section1 Previewing Forms Using Device Skins
1143 A \e {device skin} is a set of configuration files that describe a mobile
1144 device. It includes a border image that surrounds the form and depicts a
1145 mobile device with its buttons.
1147 To preview your form using device skins:
1151 \o Select \gui Tools > \gui Options... > \gui Designer.
1153 \o Select the \gui{Print/Preview Configuration} check box.
1155 \o In the \gui {Device skin} field, select a device skin.
1157 \o When the form is open in \gui Design mode, press \key Alt+Shift+R.
1159 \o To end the preview, right-click the skin and select \gui Close in
1167 \contentspage index.html
1168 \previouspage quick-projects.html
1169 \page creator-using-qt-quick-designer.html
1170 \nextpage quick-components.html
1172 \title Using Qt Quick Designer
1174 You can edit .qml files in the \QMLD visual editor or in the
1177 In \gui Projects, double-click a .qml file to open it in the code
1178 editor. Then select the \gui {Design} mode to edit the file in the
1181 \image qmldesigner-visual-editor.png "Visual editor"
1183 Use the visual editor panes to manage your project:
1187 \o \gui {Navigator} pane displays the QML elements in the current QML file
1190 \o \gui {Library} pane displays the building blocks that you can use to design
1191 applications: predefined QML elements, your own QML components, and other
1194 \o \gui Canvas is the working area where you create QML components and
1195 design applications.
1197 \o \gui {Properties} pane organizes the properties of the selected QML element
1198 or QML component. You can also change the properties in the code editor.
1200 \o \gui {State} pane displays the different states of the component. QML
1201 states typically describe user interface configurations, such as the UI
1202 elements, their properties and behavior and the available actions.
1206 \section1 Managing Element Hierarchy
1208 The \gui Navigator pane displays the
1209 \l{http://doc.qt.nokia.com/4.7/qdeclarativeelements.html}{QML elements}
1210 in the current QML file and their relationships.
1211 Elements are listed in a tree structure, below their parent.
1213 \image qmldesigner-navigator.png "Navigator pane"
1215 You can select elements in the \gui Navigator to edit their properties
1216 in the \gui Properties pane. Elements can access the properties of their
1219 Typically, child elements are located within the parent element on the
1220 canvas. However, they do not necessarily have to fit inside the parent element.
1221 For example, you might want to make a mouse area larger than the rectangle
1222 or image beneath it.
1224 \image qmldesigner-element-size.png "Mouse area for a button"
1226 When you copy an element, all its child elements are also copied. When
1227 you remove an element, the child elements are also removed.
1229 You can show and hide items to focus on specific parts of the application.
1231 \inlineimage qmldesigner-show-hide-icon.png
1232 icon to change the visibility of an element on the canvas. To change the
1233 visibility of an element in the application, use the \gui Visibility
1234 check box or the \gui Opacity field in the \gui Properties pane. If you set
1235 \gui Opacity to 0, elements are hidden, but you can still apply animation
1238 As all properties, visibility and opacity are inherited from the parent
1239 element. To hide or show child elements, edit the properties of the
1242 To view lists of files or projects, instead, select \gui {File System},
1243 \gui {Open Documents}, or \gui Projects in the menu.
1244 To view several types of content at a time, split the sidebar by clicking
1245 \inlineimage qtcreator-splitbar.png
1248 \section2 Switching Parent Elements
1250 When you drag and drop QML elements to the canvas, Qt Quick Designer
1251 adds the new element as a child of the element beneath it.
1252 When you move elements on the canvas, Qt Quick Designer cannot determine
1253 whether you want to adjust their position or attach them to a new
1254 parent element. Therefore, the parent element is not automatically
1255 changed. To change the parent of the element, press down the \key Shift
1256 key before you drag and drop the element into a new position. The topmost
1257 element under the cursor becomes the new parent of the element.
1259 You can change the parent of an element also in the \gui Navigator pane.
1260 Drag and drop the element to another position in the tree.
1262 \section1 Element Library
1264 The \gui {Library} pane contains two tabs: \gui {Items} and \gui {Resources}.
1265 The \gui Items pane displays the QML elements grouped by type: your own QML
1266 components, basic elements, interaction elements, views, and widgets.
1269 Sets of UI components with the MeeGo and Symbian look and feel have been
1270 defined for Qt Quick. They are based on standard QML elements. To view the
1271 UI components in \gui {QML Components}, click
1272 \inlineimage qtcreator-filter.png
1273 and select \gui {MeeGo Components} or \gui {Symbian Components}.
1276 \image qmldesigner-qml-components.png "QML Components pane"
1278 The \gui {Resources} pane displays the images and other files that you copy to
1279 the project folder (to the same subfolder as the QML files).
1281 \section1 Specifying Element Properties
1283 The \gui Properties pane displays all the properties of the selected QML element.
1284 The properties are grouped by type. The top part of the pane displays properties
1285 that are common to all elements, such as element type, position, size,
1288 The bottom part of the pane displays properties that are specific to each element
1289 type. For example, the following image displays the properties you can set for
1290 \gui Rectangle and \gui Text elements.
1292 \image qmldesigner-element-properties.png
1294 The default values of properties are displayed in white color, while the values
1295 that you specify explicitly are highlighted with blue color. In addition, property
1296 changes in states are highlighted with blue.
1298 For more information on the properties available for an element, press \key {F1}.
1300 \section2 Setting Expressions
1302 \l{http://doc.qt.nokia.com/4.7/propertybinding.html}{Property binding}
1303 is a declarative way of specifying the value of a property.
1304 Binding allows a property value to be expressed as an JavaScript expression
1305 that defines the value relative to other property values or data accessible
1306 in the application. The property value is automatically kept up to date if
1307 the other properties or data values change.
1309 Property bindings are created implicitly in QML whenever a property is assigned
1310 an JavaScript expression. To set JavaScript expressions as values of properties
1311 in Qt Quick Designer, click the circle
1312 icon next to a property to open a context menu, and select \gui {Set Expression}.
1314 \image qmldesigner-set-expression.png "Element properties context menu"
1316 To remove expressions, select \gui Reset in the context menu.
1318 For more information on the JavaScript environment provided by QML, see
1319 \l{http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html}{Integrating JavaScript}.
1321 \section2 Loading Placeholder Data
1323 Often, QML applications are prototyped with fake data that is later
1324 replaced by real data sources from C++ plugins. QML Viewer loads fake data
1325 into the application context: it looks for a directory named \e dummydata
1326 in the same directory as the target QML file, loads any .qml files in that
1327 directory as QML objects, and binds them to the root context as properties.
1328 For more information, see
1329 \l{http://doc.qt.nokia.com/latest/qmlviewer.html}{QML Viewer}.
1331 You can use dummydata files also to specify fake properties for QML
1332 components that you open for editing in \QMLD.
1333 A QML component provides a way of defining a new UI element that you can
1334 re-use in other QML files. A component is generally defined in its own QML
1335 file. You can use property binding to specify the properties of a component
1336 to make it easily reusable.
1338 For example, you can create a button bar component (buttonbar.qml) that
1339 inherits its width from the screen that is its parent:
1351 However, when you open the QML file for editing in \QMLD, the button bar
1352 component does not have a width, because it is specified outside the QML
1353 file (in the QML file that specifies the screen). To specify a fake width
1354 for the component, create a \c <component>_dummydata.qml file (here,
1355 buttonbar_dummydata.qml) that specifies the component width and copy it to
1356 the \c dummydata directory.
1362 import QmlDesigner 1.0
1364 DummyContextObject {
1366 property real width: 1000
1371 The file is reloaded if you change it.
1373 \section2 Setting Anchors and Margins
1375 In addition to arranging elements in a grid, row, or column, you can use
1376 \l{http://doc.qt.nokia.com/4.7/qml-anchor-layout.html}{anchors} to lay out screens.
1377 In an anchor-based layout, each item can be thought of as having a set of
1378 invisible \e anchor lines: top, bottom, left, right, fill, horizontal center,
1379 vertical center, and baseline.
1381 In the \gui Layout pane you can set anchors and margins for elements. To set
1382 the anchors of an item, click the anchor buttons. You can combine the top/bottom,
1383 left/right, and horizontal/vertical anchors to anchor objects in the corners of
1384 the parent element or center them horizontally or vertically within the parent
1387 \image qmldesigner-anchor-buttons.png "Anchor buttons"
1389 In version 2.1, specifying the baseline anchor in Qt Quick Designer is
1390 not supported. You can specify it using the code editor.
1392 For performance reasons, you can only anchor an element to its siblings and
1393 direct parent. By default, an element is anchored to its parent when you
1394 use the anchor buttons. Select a sibling of the element in the \gui Target
1395 field to anchor to it, instead.
1397 Arbitrary anchoring is not supported. For example, you cannot specify:
1398 \c {anchor.left: parent.right}. You have to specify: \c {anchor.left: parent.left}.
1399 When you use the anchor buttons, anchors to the parent element are always
1400 specified to the same side. However, anchors to sibling elements are specified
1401 to the opposite side: \c {anchor.left: sibling.right}. This allows you to keep
1402 sibling elements together.
1404 In the following image, \gui{Rectangle 2} is anchored to its siblings on its
1405 right and left and to the bottom of its parent.
1407 \image qmldesigner-anchors.png "Anchoring sibling elements"
1409 The anchors for \gui{Rectangle 2} are specified as follows in code:
1414 anchors.right: rectangle3.left
1415 anchors.rightMargin: 15
1416 anchors.left: rectangle1.right
1417 anchors.leftMargin: 15
1418 anchors.bottom: parent.bottom
1419 anchors.bottomMargin: 15
1424 Margins specify the amount of empty space to leave to the outside of an item.
1425 Margins only have meaning for anchors. They do not take any effect when using
1426 other layouts or absolute positioning.
1428 \section2 Building Transformations on Items
1430 The \gui Advanced pane allows you configure advanced transformations, such as
1431 rotation, scale, and translation. You can assign any number of transformations
1432 to an item. Each transformation is applied in order, one at a time.
1434 For more information on Transform elements, see
1435 \l {http://doc.qt.nokia.com/4.7/qml-transform.html}{QML Transform Element}.
1437 \section1 Adding States
1439 User interfaces are designed to present different interface configurations
1440 in different scenarios, or to modify their appearances in response to user
1441 interaction. Often, there are a set of changes that are made concurrently,
1442 such that the interface could be seen to be internally changing from one
1443 \e state to another.
1445 This applies generally to interface elements regardless of their complexity.
1446 A photo viewer may initially present images in a grid, and when an image is
1447 clicked, change to a detailed state where the individual image is expanded
1448 and the interface is changed to present new options for image editing.
1449 On the other end of the scale, when a simple button is pressed, it may change
1450 to a \e pressed state in which its color and position is modified to give a
1453 In QML, any object can change between different states to apply sets of changes
1454 that modify the properties of relevant items. Each state can present a
1455 different configuration that can, for example:
1459 \o Show some UI elements and hide others.
1461 \o Present different available actions to the user.
1463 \o Start, stop or pause animations.
1465 \o Execute some script required in the new state.
1467 \o Change a property value for a particular item.
1469 \o Show a different view or screen.
1473 The \gui State pane displays the different
1474 \l{http://doc.qt.nokia.com/4.7/qdeclarativestates.html}{states}
1475 of the component in the Qt Quick Designer.
1477 \image qmldesigner-transitions.png "State pane"
1479 To add states, click the empty slot. Then modify the new state in the editor.
1480 For example, to change the appearance of a button, you can hide the button
1481 image and show another image in its place. Or, to add movement to the screen,
1482 you can change the position of an object on the canvas and then add animation
1483 to the change between the states.
1485 You can preview the states in the \gui State pane and click them to switch
1486 between states on the canvas.
1488 For more information on using states, see \l{Creating Screens}.
1490 If you add animation to the states, you can run the application to test the
1493 For more information on adding animation, see \l{Animating Screens}.
1495 \section1 Aligning and Positioning Elements
1497 The position of an element on the canvas can be either absolute or relative
1498 to other elements. In the element properties, you can set the x and y
1499 coordinates of an element, or \l{Setting Anchors and Margins}{anchor} it to its
1500 parent and sibling elements.
1502 \section2 Snap to Margins
1504 When you are working on a design, you can use snap and guides to align
1505 elements on the canvas. Click the
1506 \inlineimage qmldesigner-snap-to-guides-button.png
1507 button to have the elements snap to the guides.
1509 Choose \gui {Tools > Options... > Qt Quick} to specify settings for snap to
1510 margins. In the \gui {Snap margin} field, specify the position of the guides
1511 as pixels from the edge of the canvas. In the \gui {Item spacing} field,
1512 specify the space in pixels to leave between elements on the screen.
1514 The following image shows the position of the guides when \gui {Snap margin}
1517 \image qmldesigner-snap-margins.png "Snap margins on canvas"
1519 \section2 Hiding Element Boundaries
1521 Qt Quick Designer displays the boundaries of elements on the canvas. To hide
1522 the element boundaries, click the
1523 \inlineimage qmldesigner-show-bounding-rectangles-button.png
1526 \section2 Selecting Elements
1528 When you point the mouse to overlapping elements, the frontmost element is
1529 selected by default. However, elements that do not have any content, such as
1530 the mouse area, are typically located in front of elements that do have
1531 content, such as rectangles or border images. To select elements with content
1532 by default, click the
1533 \inlineimage qmldesigner-only-select-items-with-content.png
1536 \section2 Previewing Element Size
1538 The width and height of the root item in a QML file determine the size of
1539 the QML element. You can reuse elements, such as buttons, in different
1540 sizes in other QML files and design screens for use with different device
1541 profiles, screen resolution, or screen orientation. The component size
1542 might also be zero (0,0) if its final size is determined by property
1545 To experiment with different element sizes, enter values in the
1546 \gui Height and \gui Width fields on the canvas toolbar. The changes are
1547 displayed in the \gui States pane and on the canvas, but the property
1548 values are not changed permanently in the QML file. You can permanently
1549 change the property values in the \gui Properties pane.
1551 \image qmldesigner-preview-size.png "Canvas width and height"
1553 \section1 Specifying Canvas Size
1555 To change the canvas size, select \gui {Tools > Options... > Qt Quick} and
1556 specify the canvas width and height in the \gui Canvas group.
1558 \section1 Refreshing the Canvas
1560 When you open QML files in \QMLD, the QML elements in the file are drawn on
1561 the canvas. When you edit the element properties in \QMLD, the QML file and
1562 the image on the canvas might get out of sync. For example, when you change
1563 the position of an item within a column or a row, the new position might
1564 not be displayed correctly on the canvas.
1566 To refresh the image on the canvas, press \key R or select the \gui {Reset
1567 View} button on the canvas toolbar.
1573 \contentspage index.html
1574 \previouspage creator-project-managing-sessions.html
1575 \page creator-coding.html
1576 \nextpage creator-editor-using.html
1580 Writing, editing, and navigating in source code are core tasks in
1581 application development. Therefore, the code editor is one of the key
1582 components of Qt Creator. You can use the code editor in the \gui Edit
1585 The following sections describe coding with Qt Creator:
1589 \o \l{Using the Editor} describes how to work in the code editor, use
1590 the editor toolbar, split the view, add bookmarks, and move between
1591 symbol definitions and declarations.
1593 \o \l{Semantic Highlighting} describes highlighting code elements and
1594 blocks, as well as using syntax highlighting also for other types
1595 of files than C++ or QML.
1597 \o \l{Checking Code Syntax} describes how errors are visualized
1598 while you write code.
1600 \o \l{Completing Code} describes how code and code snippets are
1601 completed for elements, properties, an IDs.
1603 \o \l{Indenting Code} describes how to specify indentation either
1604 globally for all files or separately for: text, C++, or QML files.
1606 \o \l{Finding and Replacing} describes the incremental search that
1607 highlights the matching strings in the window while typing and the
1608 advanced search that allows you to search from currently open
1609 projects or files on the file system. In addition, you can search
1610 for symbols when you want to refactor code.
1612 \o \l{Refactoring} describes the features that help you improve the
1613 internal quality or your application, its performance and
1614 extendibility, and code readability and maintainability, as well as
1615 to simplify code structure.
1617 \o \l{Using Qt Quick Toolbars} describes how to use the Qt Quick
1618 Toolbars to edit the properties of QML elements in the code editor.
1620 \o \l{Searching With the Locator} describes how to browse through
1621 projects, files, classes, methods, documentation and file systems.
1623 \o \l{Pasting and Fetching Code Snippets} describes how to cooperate
1624 with other developers by pasting and fetching snippets of code from
1627 \o \l{Using Text Editing Macros} describes how to record and play
1628 text editing macros.
1630 \o \l{Configuring the Editor} describes how to change the text editor
1631 options to suit your specific needs.
1633 \o \l{Using FakeVim Mode} describes how to run the main editor in a
1643 \contentspage index.html
1644 \previouspage creator-coding.html
1645 \page creator-editor-using.html
1646 \nextpage creator-highlighting.html
1649 \title Using the Editor
1651 Qt Creator's code editor is designed to aid you in creating, editing and
1652 navigating code. Qt Creator's code editor is fully equipped with syntax
1653 checking, code completion, context sensitive help and in-line error
1654 indicators while you are typing.
1656 \image qtcreator-edit-mode.png "Edit mode"
1658 \section1 Using the Editor Toolbar
1660 The editor toolbar is located at the top of the editor view. The editor
1661 toolbar is context sensitive and shows items relevant to the file currently
1664 \image qtcreator-editortoolbar-symbols.png
1666 Use the toolbar to navigate between open files and symbols in use.
1667 To browse forward or backward through your location history, click
1668 \inlineimage qtcreator-back.png
1669 and \inlineimage qtcreator-forward.png
1672 To go to any open file, select it from the \gui{Open files} drop-down menu.
1673 Right-click the menu title and select \gui {Copy Full Path to Clipboard} to
1674 copy the path and name of the current file to the clipboard.
1676 To jump to any symbol used in the current file, select it from the
1677 \gui Symbols drop-down menu. By default, the symbols are displayed in the
1678 order in which they appear in the file. Right-click the menu title and select
1679 \gui {Sort Alphabetically} to arrange the symbols in alphabetic order.
1681 \section1 Splitting the Editor View
1683 Split the editor view when you want to work on and view multiple files on
1686 \image qtcreator-spliteditorview.png
1688 You can split the editor view in the following ways:
1690 \o To split the editor view into a top and bottom view, select
1691 \gui Window > \gui Split or press \key{Ctrl+E, 2}.
1693 Split command creates views below the currently active editor view.
1694 \o To split the editor view into adjacent views, select
1695 \gui Window > \gui{Split Side by Side} or press
1698 Side by side split command creates views to the right of the
1699 currently active editor view.
1702 To move between split views, select \gui Window >
1703 \gui{Go to Next Split} or press \key{Ctrl+E, O}.
1705 To remove a split view, place the cursor within the view you want to
1706 remove and select \gui Window > \gui{Remove Current Split} or press
1707 \key{Ctrl+E, 0}. To remove all but the currently selected split view,
1708 select \gui Window > \gui{Remove All Splits} or press \key{Ctrl+E, 1}.
1710 \section1 Using Bookmarks
1712 To insert or delete a bookmark right-click the line number and select
1713 \gui{Toggle Bookmark} or press \key{Ctrl+M}.
1715 \image qtcreator-togglebookmark.png
1717 To go to previous bookmark in the current session, press \key{Ctrl+,}.
1719 To go to next bookmark in the current session, press \key{Ctrl+.}.
1721 \section1 Moving to Symbol Definition or Declaration
1723 You can move directly to the definition or the declaration of a symbol by
1724 holding the \key Ctrl and clicking the symbol.
1726 To enable this moving function, in \gui Tools > \gui{Options...} >
1727 \gui{Text Editor} > \gui Behavior, select \gui{Enable mouse navigation}.
1729 You can also select the symbol and press \key F2, or right-click the symbol
1730 and select \gui {Follow Symbol Under Cursor} to move to its definition or
1731 declaration. This feature is supported for namespaces, classes, methods,
1732 variables, include statements, and macros.
1734 To switch between the definition and declaration of a symbol, press
1735 \key {Shift+F2} or right-click the symbol and select \gui {Switch Between
1736 Method Declaration/Definition}.
1738 \section1 Using Update Code Model
1740 To refresh the internal information in Qt Creator pertaining to your code,
1741 select \gui{Tools} > \gui{C++} > \gui{Update Code Model}.
1743 \note In Qt Creator indexing updates the code automatically. Use
1744 \gui{Update Code Model} only as an emergency command.
1749 \contentspage index.html
1750 \previouspage creator-editor-using.html
1751 \page creator-highlighting.html
1752 \nextpage creator-checking-code-syntax.html
1754 \title Semantic Highlighting
1756 Qt Creator understands the C++ and QML languages as code, not as plain text.
1757 It reads the source code, analyzes it, and highlights it based on the
1758 semantic checks that it does for the following code elements:
1762 \o Types (such as classes, structs, and type definitions)
1772 To specify the color scheme to use for semantic highlighting, select
1773 \gui {Tools > Options... > Text Editor > Fonts & Color}.
1775 Qt Creator supports syntax highlighting also for other types of files than
1778 \section1 Generic Highlighting
1780 Generic highlighting is based on highlight definition files that are
1782 \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}{Kate Editor}.
1783 You can download highlight definition files for use with Qt Creator.
1785 If you have a Unix installation that comes with the Kate Editor, you might
1786 already have the definition files installed. Typically, the files are
1787 located in a read-only directory, and therefore, you cannot manage them. Qt
1788 Creator can try to locate them and use them as fallback files, when the
1789 primary location does not contain the definition for the current file type.
1790 You can also specify the directory that contains preinstalled highlight
1791 definition files as the primary location.
1793 When you open a file for editing and the editor cannot find the highlight
1794 definition for it, an alert appears. You can turn off the alerts. You can
1795 also specify patterns for ignoring files. The editor will not alert you if
1796 highlight definitions for the ignored files are not found.
1798 To download highlight definition files:
1802 \o Select \gui {Tools > Options... > Text Editor > Generic
1805 \image qtcreator-generic-highlighter.png "Generic Highlighter options"
1807 \o In the \gui Location field, specify the path to the primary
1808 location for highlight definition files.
1810 \o Click \gui {Download Definitions} to open a list of highlight
1811 definition files available for download.
1813 \image qtcreator-manage-definitions.png "Download Definitions dialog"
1815 \o Select highlight definition files in the list and click
1816 \gui {Download Selected Definitions}.
1818 \o Select the \gui {Use fallback location} check box to specify the
1819 secondary location where the editor will look for highlight
1822 \o Click \gui Autodetect to allow Qt Creator to look for highlight
1823 definition files on your system, or click \gui Browse to locate
1824 them in the file system yourself.
1826 \o In the \gui {Ignored file patterns} field, specify file patterns.
1827 You will not receive alerts if the highlight definitions for the
1828 specified files are not found.
1830 \o Click \gui OK to save your changes.
1834 \section1 Highlighting and Folding Blocks
1836 Use block highlighting to visually separate parts of the code that belong
1837 together. For example, when you place the cursor within the braces,
1838 the code enclosed in braces is highlighted.
1840 \image qtcreator-blockhighlighting.png
1842 To enable block highlighting, select \gui Tools > \gui{Options...} >
1843 \gui{Text Editor} > \gui Display > \gui{Highlight blocks}.
1845 Use the folding markers to collapse and expand blocks of code within
1846 braces. Click the folding marker to collapse or expand a block. In the
1847 figure above, the folding markers are located between the line number and
1850 To show the folding markers, select \gui Tools > \gui{Options...} >
1851 \gui{Text Editor} > \gui Display > \gui{Display folding markers}. This
1852 option is enabled by default.
1854 When the cursor is on a brace, the matching brace is animated
1855 by default. To turn off the animation and just highlight the block and
1856 the braces, select \gui {Tools > Options... > Text Editor > Display} and
1857 deselect \gui {Animate matching parentheses}.
1863 \contentspage index.html
1864 \previouspage creator-highlighting.html
1865 \page creator-checking-code-syntax.html
1866 \nextpage creator-completing-code.html
1868 \title Checking Code Syntax
1870 As you write code Qt Creator checks code syntax. When Qt Creator spots a
1871 syntax error in your code it underlines it and shows error details when you
1872 move the mouse pointer over the error.
1874 \o Syntax errors are underlined in red.
1876 In the following figure, a semicolon is missing at the end of the
1879 \image qtcreator-syntaxerror.png
1880 \o Semantic errors and warnings are underlined in olive.
1882 In the following figure, the type is unknown.
1884 \image qtcreator-semanticerror.png
1891 \contentspage index.html
1892 \previouspage creator-checking-code-syntax.html
1893 \page creator-completing-code.html
1894 \nextpage creator-indenting-code.html
1896 \title Completing Code
1898 As you write code, Qt Creator suggests properties, IDs, and code
1899 snippets to complete the code. It provides a list of context-sensitive
1900 suggestions to the statement currently under your cursor. Press \key Tab
1901 or \key Enter to accept the selected suggestion and complete the code.
1903 \image qtcreator-codecompletion.png
1905 To open the list of suggestions at any time, press \key{Ctrl+Space}.
1906 If only one option is available, Qt Creator inserts it automatically.
1908 When completion is invoked manually, Qt Creator completes the common prefix
1909 of the list of suggestions. This is especially useful for classes with
1910 several similarly named members. To disable this functionality, uncheck
1911 \gui{Autocomplete common prefix} in the code completion preferences.
1912 Select \gui Tools > \gui{Options...} > \gui{Text Editor} > \gui Completion.
1914 By default, code completion considers only the first letter case-sensitive.
1915 To apply full or no case-sensitivity, select the option in the
1916 \gui {Case-sensitivity} field.
1918 \section2 Summary of Available Types
1920 The following table lists available types for code completion and icon
1928 \i \inlineimage completion/class.png
1931 \i \inlineimage completion/enum.png
1934 \i \inlineimage completion/enumerator.png
1935 \i An enumerator (value of an enum)
1937 \i \inlineimage completion/func.png
1940 \i \inlineimage completion/func_priv.png
1941 \i A private function
1943 \i \inlineimage completion/func_prot.png
1944 \i A protected function
1946 \i \inlineimage completion/var.png
1949 \i \inlineimage completion/var_priv.png
1950 \i A private variable
1952 \i \inlineimage completion/var_prot.png
1953 \i A protected variable
1955 \i \inlineimage completion/signal.png
1958 \i \inlineimage completion/slot.png
1961 \i \inlineimage completion/slot_priv.png
1964 \i \inlineimage completion/slot_prot.png
1967 \i \inlineimage completion/keyword.png
1970 \i \inlineimage completion/snippet.png
1971 \i A C++ code snippet
1973 \i \inlineimage completion/element.png
1976 \i \inlineimage completion/qmlsnippet.png
1977 \i A QML code snippet
1979 \i \inlineimage completion/macro.png
1982 \i \inlineimage completion/namespace.png
1986 \section2 Completing Code Snippets
1988 Code snippets can consist of multiple
1989 variables that you specify values for. Select an item in the list and press
1990 \key Tab or \key Enter to complete the code. Press \key Tab to
1991 move between the variables and specify values for them. When you specify a
1992 value for a variable, all instances of the variable within the snippet
1995 \image qmldesigner-code-completion.png "Completing QML code"
1997 \section2 Editing Code Snippets
1999 Code snippets specify C++ or QML code constructs. You can add, modify,
2000 and remove snippets in the snippet editor. To open the editor, select
2001 \gui {Tools > Options... > Text Editor > Snippets}.
2003 \image qtcreator-edit-code-snippets.png "Snippet options"
2005 Qt Creator provides you with built-in snippets in the following categories:
2009 \o Text snippets, which can contain any text string. For example, code
2012 \o C++ code snippets, which specify C++ code constructs
2014 \o QML code snippets, which specify QML code constructs
2018 \section3 Adding and Editing Snippets
2020 Select a snippet in the list to edit it in the snippet editor. To add a new
2021 snippet, select \gui Add. Specify a trigger and, if the trigger is already
2022 in use, an optional variant, which appear in the list of suggestions when
2023 you write code. Also specify a text string or C++ or QML code construct in
2024 the snippet editor, depending on the snippet category.
2026 The snippet editor provides you with:
2034 \o Parentheses matching
2036 \o Basic code completion
2040 Specify the variables for the snippets in the following format:
2044 Use unique variable names within a snippet, because all instances of a
2045 variable are renamed when you specify a value for it.
2047 The snippet editor does not check the syntax of the snippets that you edit
2048 or add. However, when you use the snippets, the code editor marks any
2049 errors by underlining them in red.
2051 To discard the changes you made to a built-in snippet, select \gui {Revert
2054 \section3 Removing Snippets
2056 Several similar built-in snippets might be provided for different use
2057 cases. To make the list of suggestions shorter when you write code, remove
2058 the built-in snippets that you do not need. If you need them later, you
2061 To remove snippets, select a snippet in the list, and then select
2062 \gui Remove. To restore the removed snippets, select \gui {Restore Removed
2065 \section3 Resetting Snippets
2067 To remove all added snippets and to restore all removed snippets, select
2070 \note If you now select \gui OK or \gui Apply, you permanently lose all
2077 \contentspage index.html
2078 \previouspage creator-editor-locator.html
2079 \page creator-editor-codepasting.html
2080 \nextpage creator-macros.html
2082 \title Pasting and Fetching Code Snippets
2084 In Qt Creator, you can paste snippets of code to a server or fetch
2085 snippets of code from the server. To paste and fetch snippets of code,
2086 Qt Creator uses the following:
2089 \o \gui{Pastebin.Com}
2090 \o \gui{Pastebin.Ca}
2093 To configure the server, select \gui{Tools} > \gui{Options...} >
2096 To paste a snippet of code onto the server, select \gui{Tools} >
2097 \gui{Code Pasting} > \gui{Paste Snippet...} or press \key{Alt+C,Alt+P}.
2101 To fetch a snippet of code from the server, select \gui{Tools} >
2102 \gui{Code Pasting} > \gui{Fetch Snippet...} or press \key{Alt+C,Alt+F}.
2104 \note To use \gui{Pastebin.Com}, configure the domain
2105 prefix in \gui{Tools} > \gui{Options...} > \gui{Code Pasting} >
2108 For example, you might ask colleagues to review a change that you plan to
2109 submit to a version control system. If you use the Git version control system,
2110 you can create a \e{diff} view by selecting \gui{Tools} > \gui{Git} >
2111 \gui{Diff Repository}. You can then upload its contents to the server by choosing
2112 \gui{Tools} > \gui{Code Pasting} > \gui{Paste Snippet...}. The reviewers can retrieve
2113 the code snippet by selecting \gui{Tools} > \gui{Code Pasting} > \gui{Fetch Snippet...}.
2114 If they have the project currently opened in Qt Creator, they can apply and test
2115 the change by choosing \gui{Tools} > \gui{Git} > \gui{Apply Patch}.
2120 \contentspage index.html
2121 \previouspage creator-editor-codepasting.html
2122 \page creator-macros.html
2123 \nextpage creator-editor-options.html
2125 \title Using Text Editing Macros
2127 When you have a file open in the code editor, you can record a keyboard
2128 sequence as a macro. You can then play the macro to repeat the sequence.
2129 You can save the latest macro and assign a keyboard shortcut for running
2130 it or run it from the locator.
2132 To record a text editing macro, select \gui {Tools > Macros > Record Macro}
2133 or press \key {Alt+(}. To stop recording, select \gui {Tools > Macros >
2134 Stop Recording Macro} or press \key {Alt+)}.
2136 To play the last macro, select \gui {Tools > Macros > Play Last Macro} or
2139 To save the last macro, select \gui {Tools > Macros > Save Last Macro}.
2141 To assign a keyboard shortcut to a text editing macro, select \gui {Tools >
2142 Options... > Environment > Keyboard}. For more information, see
2143 \l{Configuring Keyboard Shortcuts}.
2145 You can also use the \c rm locator filter to run a macro. For more
2146 information, see \l{Searching With the Locator}.
2148 To view and remove saved macros, select \gui {Tools > Options... > Text
2154 \contentspage index.html
2155 \previouspage creator-editor-options.html
2156 \page creator-editor-fakevim.html
2157 \nextpage creator-design-mode.html
2159 \title Using FakeVim Mode
2161 In the \gui{FakeVim} mode, you can run the main editor in a manner similar
2162 to the Vim editor. To run the editor in the \gui{FakeVim} mode, select
2163 \gui{Edit} > \gui{Advanced} > \gui{Use Vim-style Editing} or press
2166 In the \gui{FakeVim} mode, most keystrokes in the main editor will be
2167 intercepted and interpreted in a way that resembles Vim. Documentation for
2168 Vim is not included in Qt Creator. For more information on using Vim,
2169 see \l{http://www.vim.org/docs.php}{Documentation} on the Vim web site.
2171 To map commands entered on the \gui{FakeVim} command line to actions of the
2172 Qt Creator core, select \gui{Tools} > \gui{Options...} > \gui{FakeVim} >
2173 \gui{Ex Command Mapping}.
2175 To make changes to the Vim-style settings, select \gui{Tools} >
2176 \gui{Options...} > \gui FakeVim > \gui{General}.
2178 To use a Vim-style color scheme, select \gui {Tools > Options... >
2179 Text Editor > Fonts & Color}. In the \gui {Color Scheme} list, select
2182 To quit the FakeVim mode, click \gui {Quit FakeVim} or press
2189 \contentspage index.html
2190 \previouspage adding-plugins.html
2191 \page creator-editor-external.html
2192 \nextpage creator-maemo-emulator.html
2194 \title Using External Tools
2196 You can use external tools directly from Qt Creator. Qt Linguist, the
2197 default text editor for your system, and the \c sort tool are preconfigured
2198 for use. You can change their default configurations and configure new
2201 \section1 Using Qt Linguist
2203 You can use the Qt Linguist release manager tools, lupdate and lrelease,
2204 directly from Qt Creator. The lupdate tool is used to synchronize source
2205 code and translations. The lrelease tool is used to create run-time
2206 translation files for use by the released application.
2208 To synchronize ts files from a translator with the application code,
2209 select \gui {Tools > External > Text > Linguist > Update Translations
2212 To generate from the ts files qm translation files that can be used by an
2213 application, select \gui {Tools > External > Text > Linguist > Release
2214 Translations (lrelease)}.
2216 By default, the project .pro file is passed to the tools as an argument. To
2217 specify other command line arguments for the tools, select \gui {Tools >
2218 External > Configure}.
2220 For more information about Qt Linguist, see
2221 \l{http://doc.qt.nokia.com/4.7/linguist-manual.html}{Qt Linguist Manual}.
2223 \section1 Using External Text Editors
2225 You can open files for editing in the default text editor for your system:
2226 Notepad on Windows and vi on Linux and Mac OS.
2227 To open the file you are currently viewing in an external editor, select
2228 \gui {Tools > External > Text > Notepad} or \gui vi, depending on your
2231 Qt Creator looks for the editor path in the PATH environment variable
2232 of your operating system.
2234 \section1 Sorting Text Alphabetically
2236 To sort selected text alphabetically, select \gui {Tools > External > Text
2237 > Sort Selection}. The \c sort tool takes the selected text as input and
2238 returns it in alphabetic order. By default, the output replaces the
2239 original selection in the code editor.
2241 To change the default configuration, select \gui {Tools > External >
2244 \section1 Configuring External Tools
2246 You can change the configuration of preconfigured tools and configure
2247 additional tools in Qt Creator \gui Options.
2249 You can use Qt Creator variables in the fields that you can select from
2250 lists of available Qt Creator variables.
2252 \image qtcreator-external-tools.png "External Tools options"
2254 To configure external tools:
2258 \o Select \gui {Tools > External > Configure}.
2260 \o Select \gui {Add > Add Tool}
2261 to add a new tool. You can also select \gui {Add Category} to add a
2264 \o In the \gui Executable field, specify the executable to run. If the
2265 executable is found in your system PATH variable, do not specify
2268 \o In the \gui Arguments field, specify optional arguments for running
2271 \o In the \gui {Working directory} field, specify the path to the
2274 \o In the \gui {Output pane}, select how to handle output from the
2275 tool. You can ignore the output, view it in the \gui {General
2276 Messages} output pane, or replace the selected text with the
2277 output in the code editor.
2279 \o In the \gui {Error output pane}, select how to handle error messages
2282 \o In the \gui Input field, specify text that is passed as standard
2287 The category and tool are added to the \gui {Tools > External} menu.
2289 If you change the configuration of preconfigured tools, you can later
2290 revert the changes by selecting the \gui Revert button.
2292 The tool configurations that you add and modify are stored in XML format in
2293 the user configuration folder. For example,
2294 \c {~/config/Nokia/qtcreator/externaltools}
2295 on Linux and Mac OS and
2296 \c {C:\Users\username\AppData\Roaming\Nokia\qtcreator\externaltools}
2297 in Windows. To share a configuration with other users, copy an XML
2298 configuration file to the folder.
2304 \contentspage index.html
2305 \previouspage creator-macros.html
2306 \page creator-editor-options.html
2307 \nextpage creator-editor-fakevim.html
2309 \title Configuring the Editor
2311 Qt Creator allows you to configure the text editor to suit your specific
2312 needs. To configure the editor, select \gui Tools > \gui{Options...} >
2315 These settings apply to all projects. To specify editor behavior for an
2316 open project, select \gui {Projects > Editor Settings}. For more
2317 information, see \l{Specifying Editor Settings}.
2319 You can also specify indentation settings separately for C++ and QML files
2320 either globally or for the open project. For more information, see
2323 \image qtcreator-font-colors.png "Text editor options"
2325 You can perform the following configuration actions:
2327 \o Set the font preferences and apply color schemes for syntax highlighting in
2328 \gui{Font & Colors}.
2330 \l{Generic Highlighting}{definition files for syntax highlighting}
2331 for other types of files than
2332 C++ or QML in \gui{Generic Highlighter}.
2333 \o Set tabs, indentation, the handling of whitespace, and mouse operations in
2334 \gui Behavior. For more information, see \l{Indenting Code}.
2335 \o Set various display properties, for example,
2336 \l{Highlighting and folding blocks}{highlighting and folding blocks},
2337 text wrapping or \l{Moving to symbol definition or declaration}
2338 {moving to symbol definition or declaration}
2340 \o Add, modify, and remove \l{Editing Code Snippets}{code snippets} in
2342 \o View and remove \l{Using Text Editing Macros}{text editing macros}
2344 \o Configure \l{Completing Code}{code completion} in \gui Completion.
2347 \section2 Configuring Fonts
2349 You can select the font family and size. You can specify a zoom setting in
2350 percentage for viewing the text. You can also zoom in or out by pressing
2351 \key {Ctrl++} or \key {Ctrl +-}, or by pressing \key Ctrl and rolling
2352 the mouse button up or down. To disable the mouse wheel function, select
2353 \gui {Tools > Options... > Text Editor > Behavior} and deselect the
2354 \gui {Enable scroll wheel zooming} check box.
2356 Antialiasing is used by default to make text look smoother and more
2357 readable on the screen. Deselect the \gui Antialias check box to
2358 turn off antialiasing.
2360 \section2 Defining Color Schemes
2362 You can select one of the predefined color schemes for syntax highlighting
2363 or create customized color schemes. The color schemes apply to highlighting
2364 both C++ and QML files and generic files.
2366 To create a color scheme:
2370 \o Select \gui {Tools > Options... > Text Editor > Fonts & Color > Copy}.
2372 \o Enter a name for the color scheme and click \gui OK.
2374 \o In the \gui Foreground field, specify the color of the selected
2377 \o In the \gui Background field, select the background
2378 color for the code element.
2380 The backgound of the \gui Text element determines the background of the
2385 When you copy code from Qt Creator, it is copied in both plain text and HTML
2386 format. The latter makes sure that syntax highlighting is preserved when
2387 pasting to a rich-text editor.
2389 \section2 File Encoding
2391 To define the default file encoding, select the desired encoding in
2392 \gui {Default encoding}. By default, Qt Creator uses the file encoding
2393 used by your system.
2399 \contentspage index.html
2400 \previouspage creator-completing-code.html
2401 \page creator-indenting-code.html
2402 \nextpage creator-editor-finding.html
2404 \title Indenting Code
2406 When you type code, it is indented automatically according to the selected
2407 text editor and code style options. Select a block to indent it when you
2408 press \key Tab. Press \key {Shift+Tab} to decrease the indentation. You
2409 can disable automatic indentation.
2411 When you press \gui Backspace, the indentation is decreased by one level
2412 in leading white space, by default. You can disable this setting.
2414 Continuation lines are aligned with the previous line by using spaces. You
2415 can disable automatic alignment to have them indented to the logical depth.
2416 You can always use spaces for alignment or use spaces or tabs depending on
2417 the other options you selected.
2419 You can specify indentation either globally for all files or separately
2432 You can specify indentation either globally for all files of a particular
2433 type or separately for each project.
2435 \section1 Indenting Text Files
2437 To specify global indentation settings for the text editor, select
2438 \gui {Tools > Options... > Text Editor > Behavior}. You can also use these
2439 settings globally for all editors and files.
2441 \image qtcreator-indentation.png "Text Editor Behavior options"
2443 To specify settings for a particular project, select \gui {Projects >
2446 \section1 Indenting C++ Files
2448 To specify global indentation settings for the C++ editor, select
2449 \gui {Tools > Options... > C++}.
2451 \image qtcreator-options-code-style-cpp.png "C++ Code Style options"
2453 To specify the settings for a particular project, select \gui {Projects >
2454 Code Style Settings}.
2456 You can specify how to:
2460 \o Interpret the \key Tab and \key Backspace key presses.
2462 \o Indent the contents of classes, methods, blocks, and namespaces.
2464 \o Indent braces in classes, namespaces, enums, methods, and blocks.
2466 \o Control switch statements and their contents.
2468 \o Align continuation lines.
2472 You can use the live preview to see how the options change the indentation.
2474 \section1 Indenting QML Files
2476 To specify global settings for the Qt Quick editor, select \gui {Tools >
2477 Options... > Qt Quick}.
2479 \image qtcreator-options-code-style-qml.png "QML Code Style options"
2481 To specify the settings for a particular project, select \gui {Projects >
2482 Code Style Settings}.
2484 You can specify how to interpret the \key Tab and \key Backspace key
2487 \section1 Specifying Tab Settings
2489 You can specify tab settings at the following levels:
2493 \o Global settings for all files
2495 \o Global C++ settings for C++ files
2497 \o Global Qt Quick settings for QML files
2499 \o Project specific settings for all editors of files in the project
2501 \o Project specific settings for C++ files in the project
2503 \o Project specific settings for QML files in the project
2507 By default, the tab-length in code editor is 8 spaces. You can specify the
2508 tab length separately for each project and for
2509 different types of files.
2511 The code editor can also determine whether tabs or spaces are used
2512 on the previous or next line and copy the style.
2514 The \key Tab key can automatically indent text when you press it, or only
2515 when the cursor is located within leading white space.
2517 \section1 Specifying Settings for Content
2519 You can indent public, protected, and private statements and declarations
2520 related to them within classes.
2522 You can also indent statements within methods and blocks and declarations
2525 \image qtcreator-code-style-content.png "Content options"
2527 \section1 Specifying Settings for Braces
2529 You can indent class, namespace, enum and method declarations and code
2532 \image qtcreator-code-style-braces.png "Braces options"
2534 \section1 Specifying Settings for Switch Statements
2536 You can indent case or default statements, or statements or blocks related
2537 to them within switch statements.
2539 \image qtcreator-code-style-switch.png "Switch options"
2541 \section1 Specifying Alignment
2543 To align continuation lines to tokens after assignments, such as = or
2544 +=, select the \gui {Align after assignments} check box. You can specify
2545 additional settings for aligning continuation lines in the \gui General
2548 You can also add spaces to conditional statements, so that they are not
2549 aligned with the following line. Usually, this only affects \c if
2552 \image qtcreator-code-style-alignment.png "Alignment options"
2558 \contentspage index.html
2559 \previouspage creator-indenting-code.html
2560 \page creator-editor-finding.html
2561 \nextpage creator-editor-refactoring.html
2563 \title Finding and Replacing
2565 To search through the currently open file:
2567 \o Press \key Ctrl+F or select \gui Edit > \gui Find/Replace >
2569 \o Enter the text you are looking for.
2571 If the text is found, all occurrences are highlighted as you type.
2572 \o To go to the next occurrence, click \inlineimage qtcreator-next.png
2573 , or press \key F3. To go to the previous occurrence click
2574 \inlineimage qtcreator-previous.png
2575 , or press \key Shift+F3.
2578 You can restrict the search in the \gui Find field by selecting one
2579 or several search criteria:
2581 \o To make your search case sensitive, select
2582 \inlineimage qtcreator-editor-casesensitive.png
2584 \o To search only whole words, select
2585 \inlineimage qtcreator-editor-wholewords.png
2587 \o To search using regular expressions, select
2588 \inlineimage qtcreator-editor-regularexpressions.png
2590 Regular expressions used in Qt Creator are modeled on Perl regular
2591 expressions. For more information on using regular expressions, see
2592 \l {http://doc.qt.nokia.com/4.7/qregexp.html#details}
2593 {Detailed Description} in the QRegExp Class Reference.
2596 \note If you have selected text before selecting \gui Find/Replace, the
2597 search is conducted within the selection.
2599 To replace occurrences of the existing text, enter the new text in the
2600 \gui{Replace with} field.
2602 \o To replace the selected occurrence and move to the next one,
2603 click \inlineimage qtcreator-next.png
2604 or press \key Ctrl+=.
2605 \o To replace the selected occurrence and move to the previous one,
2606 click \inlineimage qtcreator-previous.png
2608 \o To replace all occurrences in the file, click \gui{Replace All}.
2611 \section1 Advanced Search
2613 To search through projects, files on a file system or the currently open
2616 \o Press \key Ctrl+Shift+F or select \gui Edit >
2617 \gui Find/Replace > \gui{Advanced Find} >
2618 \gui{Open Advanced Find...}.
2619 \o Select the scope of your search:
2621 \o \gui{All Projects} searches files matching the defined file
2622 pattern in all currently open projects.
2624 For example, to search for \tt previewer only in \tt .cpp
2625 and \tt .h files, enter in \gui{File pattern}
2628 \image qtcreator-search-allprojects.png
2630 \o \gui{Current Project} searches files matching the defined file
2631 pattern only in the project you are currently editing.
2632 \o \gui{Files on File System} recursively searches files matching
2633 the defined file pattern in the selected directory.
2634 \o \gui{Current File} searches only the current file.
2636 \o Enter the text you are looking for and click \gui Search.
2638 \image qtcreator-searchresults.png
2640 A list of files containing the searched text is displayed in the
2641 \gui{Search Results} pane.
2643 \o To see all occurrences in a file, double-click the file name in
2645 \o To go to an occurrence, double-click it.
2649 \note You can use \gui{Advanced Find} also to search for symbols. For more
2650 information, see \l{Finding Symbols}.
2656 \contentspage index.html
2657 \previouspage creator-editor-finding.html
2658 \page creator-editor-refactoring.html
2659 \nextpage qt-quick-toolbars.html
2663 Code refactoring is the process of changing the code without modifying the
2664 existing functionality of your application. By refactoring your code you
2667 \o Improve internal quality of your application
2668 \o Improve performance and extensibility
2669 \o Improve code readability and maintainability
2670 \o Simplify code structure
2673 \section1 Finding Symbols
2675 To find the use of a specific symbol in your Qt C++ or Qt Quick project:
2677 \o In the editor, place the cursor on the symbol, and select:
2679 \o \gui {Tools > C++ > Find Usages}
2680 \o \gui {Tools > QML > Find Usages}
2681 \o \key Ctrl+Shift+U
2684 Qt Creator looks for the symbol in the following locations:
2686 \o Files listed as a part of the project
2687 \o Files directly used by the project files (for example, generated
2689 \o Header files of used frameworks and libraries
2692 \note You can also select \gui{Edit > Find/Replace > Advanced Find >
2693 C++ Symbols} to search for classes, methods, enums, and declarations
2694 either from files listed as part of the project or from all files that
2695 are used by the code, such as include files.
2697 \image qtcreator-search-cpp-symbols.png
2699 \o The \gui{Search Results} pane opens and shows the location and
2700 number of instances of the symbol in the current project.
2702 \image qtcreator-refactoring-find.png
2705 You can browse the search results in the following ways:
2707 \o To go directly to an instance, double-click the instance in the
2708 \gui{Search Results} pane.
2709 \o To move between instances, click
2710 \inlineimage qtcreator-forward.png
2712 \inlineimage qtcreator-back.png
2713 in the \gui{Search Results} pane.
2714 \o To expand and collapse the list of all instances, click
2715 \inlineimage qtcreator-expand.png
2717 \o To clear the search results, click \inlineimage qtcreator-clear.png
2721 \section1 Renaming Symbols
2723 The functions available for renaming symbols depend on whether you are
2724 writing C++ or QML code. For QML, you can only rename IDs.
2726 To rename a specific symbol in a Qt project:
2728 \o In the editor, place the cursor on the symbol you would like to
2729 change and select \gui Tools > \gui C++ >
2730 \gui{Rename Symbol Under Cursor} or press \key Ctrl+Shift+R.
2732 The \gui{Search Results} pane opens and shows the location and
2733 number of instances of the symbol in the current project.
2735 \image qtcreator-refactoring-replace.png
2736 \o To replace all selected instances, enter the name of the new symbol
2737 in the \gui{Replace with} text box and click \gui Replace.
2739 To omit an instance, uncheck the check-box next to the instance.
2741 \note This action replaces all selected instances of the symbol in
2742 all files listed in the \gui{Search Results} pane. You cannot
2746 \note Renaming local symbols does not open the \gui{Search Results} pane.
2747 The instances of the symbol are highlighted in code and you can edit the
2748 symbol. All instances of the local symbol are changed as you type.
2750 To rename an ID in a Qt Quick project:
2754 \o Right-click an ID in the QML code and select
2757 \o In the \gui {Rename id} field, enter the new ID.
2761 \section1 Applying Refactoring Actions
2763 Qt Creator allows you to quickly and conveniently apply actions to refactor
2764 your code by selecting them in a context menu. The actions available depend on
2765 the position of the cursor in the code editor and on whether you are writing
2768 To apply refactoring actions to C++ code, right-click an operand, conditional
2769 statement, string, or name to open a context menu. In QML code, click an element
2772 In the context menu, select \gui {Refactoring} and then select a refactoring action.
2774 You can also press \gui {Alt+Enter} to open a context menu that contains refactoring
2775 actions available in the current cursor position.
2777 \section2 Refactoring C++ Code
2779 You can apply the following types of refactoring actions to C++ code:
2783 \o Change binary operands
2785 \o Simplify if and while conditions (for example, move declarations out of
2788 \o Modify strings (for example, set the encoding for a string to Latin-1, mark
2789 strings translatable, and convert symbol names to camel case)
2791 \o Create variable declarations
2793 \o Create method declarations and definitions
2797 The following table summarizes the refactoring actions for C++ code. The
2798 action is available when the cursor is in the position described in the
2803 \i Refactoring Action
2808 \i Adds curly braces to an if statement that does not contain a
2809 compound statement. For example, rewrites
2825 \i Move Declaration out of Condition
2826 \i Moves a declaration out of an if or while condition to simplify the
2827 condition. For example, rewrites
2830 if (Type name = foo()) {...}
2839 \i Name of the introduced variable
2841 \i Rewrite Condition Using ||
2842 \i Rewrites the expression according to De Morgan's laws. For example,
2855 \i Rewrite Using \e operator
2856 \i Rewrites an expression negating it and using the inverse operator. For
2895 \i Split Declaration
2896 \i Splits a simple declaration into several declarations. For example,
2908 \i Type name or variable name
2910 \i Split if Statement
2911 \i Splits an if statement into several statements. For example, rewrites:
2913 if (something && something_else) {
2921 if (something_else) {
2929 if (something || something_else)
2938 else if (something_else)
2945 \i Rewrites an expression in the inverse order using the inverse operator.
2946 For example, rewrites:
2955 \i <= < > >= == != && ||
2957 \i Convert to Decimal
2958 \i Converts an integer literal to decimal representation
2961 \i Convert to Hexadecimal
2962 \i Converts an integer literal to hexadecimal representation
2966 \i Converts an integer literal to octal representation
2969 \i Convert to Objective-C String Literal
2970 \i Converts a string literal to an Objective-C string literal
2971 if the file type is Objective-C(++). For example, rewrites the following strings
2975 QLatin1String("abcd")
2976 QLatin1Literal("abcd")
2986 \i Enclose in QLatin1Char(...)
2987 \i Sets the encoding for a character to Latin-1, unless the character is
2988 already enclosed in QLatin1Char, QT_TRANSLATE_NOOP, tr, trUtf8,
2989 QLatin1Literal, or QLatin1String. For example, rewrites
3002 \i Enclose in QLatin1String(...)
3003 \i Sets the encoding for a string to Latin-1, unless the string is
3004 already enclosed in QLatin1Char, QT_TRANSLATE_NOOP, tr, trUtf8,
3005 QLatin1Literal, or QLatin1String. For example, rewrites
3013 QLatin1String("abcd")
3019 \i Mark as Translatable
3020 \i Marks a string translatable. For example, rewrites \c "abcd" with
3021 one of the following options, depending on which of them is available:
3025 QCoreApplication::translate("CONTEXT", "abcd")
3026 QT_TRANSLATE_NOOP("GLOBAL", "abcd")
3032 \i #include Header File
3033 \i Adds the matching #include statement for a forward-declared class or struct
3034 \i Forward-declared class or struct
3036 \i Add Definition in 'filename'
3037 \i Inserts a definition stub for a member function declaration in the
3041 \i Add 'Function' Declaration
3042 \i Inserts the member function declaration that matches the member function
3043 definition into the class declaration. The function can be public,
3044 protected, private, public slot, protected slot, or private slot.
3047 \i Add Local Declaration
3049 Adds the type of an assignee, if the type of the right-hand side of the assignment
3050 is known. For example, rewrites
3062 where Type is the return type of \c {foo()}
3067 \i Convert to Camel Case...
3068 \i Converts a symbol name to camel case, where elements of the name are joined
3069 without delimiter characters and the initial character of each element is
3070 capitalized. For example, rewrites \c an_example_symbol
3071 as \c anExampleSymbol and \c AN_EXAMPLE_SYMBOL as \c AnExampleSymbol
3074 \i Complete Switch Statement
3075 \i Adds all possible cases to a switch statement of the type \c enum
3078 \i Generate Missing Q_PROPERTY Members...
3079 \i Adds missing members to a Q_PROPERTY:
3082 \o \c write method, if there is a WRITE
3083 \o \c {on...Changed} signal, if there is a NOTIFY
3084 \o data member with the name \c {m_<propertyName>}
3089 \section2 Refactoring QML Code
3091 You can apply the following types of refactoring actions to QML code:
3097 \o Split initializers
3099 \o Move a QML element into a separate file to reuse it in other
3104 The following table summarizes the refactoring actions for QML code. The
3105 action is available when the cursor is in the position described in the
3110 \i Refactoring Action
3115 \i Move Component into 'filename.qml'
3116 \i Moves a QML element into a separate file
3120 \i Renames all instances of an element ID in the currently open file
3123 \i Split Initializer
3124 \i Reformats a one-line element into a multi-line element. For example,
3128 Item { x: 10; y: 20; width: 10 }
3146 \contentspage index.html
3147 \previouspage creator-qml-application.html
3148 \page creator-project-managing.html
3149 \nextpage creator-project-creating.html
3151 \title Managing Projects
3153 To set up a project, you first have to decide what kind of an
3154 application you want to develop: whether you want a user interface
3155 based on Qt Quick, Qt widgets, or HTML5. For a Qt Quick or HTML5 project,
3157 choose the language to implement the application logic: C++ or JavaScript.
3158 You can also create other kinds of projects, such as Qt console
3159 applications, shared or static C++ libraries, or subprojects.
3161 You can use wizards to create and import projects. The wizards prompt you
3162 to enter the settings needed for that particular type of project and create
3163 the necessary files for you. You can add your own custom wizards to
3164 standardize the way subprojects and classes are added to a project.
3166 The wizards set up projects to use the Qt build tool, qmake. It is a
3167 cross-platform system for build automation that helps simplify the build
3168 process for development projects across different platforms. qmake
3169 automates the generation of build configurations so that only a few lines
3170 of information are needed to create each configuration. For more
3171 information about qmake, see the
3172 \l{http://qt.nokia.com/doc/4.7/qmake-manual.html}{qmake Manual}.
3174 You can modify the build and run settings for qmake projects in the
3177 Alternatively, you can use the CMake build automation system and set up the
3178 projects manually. In addition, you can import generic projects that do not
3179 use qmake or CMake. This allows you to use Qt Creator as a code editor. For
3180 generic projects, Qt Creator ignores your build system.
3182 To develop applications for Symbian devices, you use
3183 qmake and the local Symbian compiler (on Windows) or qmake and a compilation
3184 service at Nokia Developer (on Linux and Mac OS) to build the applications for
3185 the Symbian devices target. The interface to the compilation service, Remote
3186 Compiler, is installed as a part of the \QSDK. For more information, see
3187 \l{Building with Remote Compiler}.
3189 You can install Maemo, MeeGo Harmattan, and Symbian targets as parts of
3190 the \QSDK. The build and run settings for the selected targets are set up
3191 automatically. However, you need to install and
3192 configure some additional software on the devices to be able to connect to
3193 them from the development PC.
3195 You can use sessions to store personal data, such as bookmarks and
3196 breakpoints that are usually not of interest to other developers working on
3197 the same projects. Sessions allow you to quickly switch between projects
3198 when you work on several projects.
3200 The following sections describe how to manage projects:
3203 \o \l{Creating a Project}
3204 \o \l{Opening a Project}
3205 \o \l{Adding Libraries to Projects}
3206 \o \l{Connecting Maemo and MeeGo Harmattan Devices}
3207 \o \l{Connecting Generic Linux Devices}
3208 \o \l{Connecting Symbian Devices}
3209 \o \l{Managing Sessions}
3212 For advanced options, see the following topics:
3215 \o \l{Adding New Custom Wizards}
3216 \o \l{Setting Up a CMake Project}
3217 \o \l{Setting Up a Generic Project}
3224 \contentspage index.html
3225 \previouspage creator-project-managing.html
3226 \page creator-project-creating.html
3227 \nextpage creator-project-opening.html
3229 \title Creating a Project
3231 \image qtcreator-new-project.png
3233 You can use wizards to create following types of projects:
3239 Use QML elements or Qt Quick Components to define the user interface and,
3240 optionally, C++ or JavaScript to define the application logic.
3244 \o Qt Widget Project
3246 Use \QD forms to define a Qt widget based
3247 user interface and C++ to define the application logic
3253 \o HTML5 based applications
3255 \o Qt console applications
3257 \o Shared or static C++ libraries
3261 \o Qt Custom Designer Widgets
3267 \o Project from Version Control
3269 Import a project from a supported version control system. For more
3270 information on how version control systems are integrated in
3271 Qt Creator, see \l{Using Version Control Systems}.
3275 To create a new project, select \gui File > \gui{New File or Project} and
3276 select the type of your
3278 The contents of the wizard dialogs depend on the project type and
3279 the build targets that you select in the \gui {Target Setup} dialog.
3280 Follow the instructions of the wizard.
3282 For examples of creating different types of projects, see
3283 \l{Getting Started}.
3285 For more information about creating Qt Quick projects, see
3286 \l {Creating Qt Quick Projects}.
3288 To change the location of the project directory, and to specify settings
3289 for building and running projects, select \gui{Tools} > \gui{Options...} >
3290 \gui{Projects} > \gui{General}.
3292 To specify build and run settings for different target platforms, select
3295 \section1 Adding Files to Projects
3297 You can use wizards also to add individual files to your projects.
3298 You can create the following types of files:
3302 \o Qt resource files, which allow you to store binary files in the
3303 application executable
3305 \o \QD forms and \QD form classes, which specify parts of user
3306 interfaces in Qt widget based projects
3308 \o QML files, which specify elements in Qt Quick projects
3310 \o GLSL files that define fragment and vertex shaders in both Qt Quick
3311 projects and Qt widget based projects
3313 \o C++ class, source, or header files that you can use to write the
3314 application logic in both Qt Quick projects and Qt widget based
3317 \o JavaScript files that you can use to write the application logic in
3324 \section2 Creating C++ Classes
3326 The \gui {C++ Class Wizard} allows you to create a C++ header and source file for
3327 a new class that you can add to a C++ project. Specify the class name, base
3328 class, and header and source files for the class.
3330 The wizard supports namespaces. To use a namespace, enter a qualified
3331 class name in the \gui {Class name} field. For example:
3332 MyNamespace::MySubNamespace::MyClass.
3334 \image qtcreator-cpp-class-wizard.png "Enter Class Name dialog"
3336 The names of the header and source file are based on the class name. To change the
3337 default suffix of a file, click \gui Configure.
3339 You can create your own project and class wizards. For more information,
3340 see \l{Adding New Custom Wizards}.
3342 \section2 Creating OpenGL Fragment and Vertex Shaders
3344 Qt provides support for integration with OpenGL implementations on all
3345 platforms, which allows you to display hardware accelerated 3D graphics
3346 alongside a more conventional user interface. For more information, see
3347 \l{http://doc.qt.nokia.com/4.7/qtopengl.html}{QtOpenGL Module}.
3349 You can use the QGLShader class to compile OpenGL shaders written in the
3350 OpenGL Shading Language (GLSL) and in the OpenGL/ES Shading Language
3351 (GLSL/ES). QGLShader and QGLShaderProgram shelter you from the details of
3352 compiling and linking vertex and fragment shaders.
3354 You can use Qt Creator code editor to write fragment and vertex shaders
3355 in GLSL or GLSL/ES. The code editor provides syntax highlighting and code
3356 completion for the files.
3358 \image qtcreator-new-opengl-file.png "New OpenGL file wizard"
3360 \section2 Displaying Additional File Types in Projects Pane
3362 Qt Creator determines whether to display files from the project folder
3363 in the \gui Projects pane depending on the file type (.pro, .pri, .cpp,
3364 .h, .ui, .qrc, and so on). To display other types of files, edit the
3365 project file. Add filenames as values of the \c {OTHER_FILES} variable.
3366 You can also use wildcards.
3368 For example, the following code specifies that text files are displayed
3369 in the \gui Projects pane:
3373 OTHER_FILES += *.txt
3377 This also makes the files available in the \gui Locator.
3379 \section1 Adding Subprojects to Projects
3381 When you create a new project, you can add it to another project as a subproject
3382 in the \gui{Project Management} dialog. However, the root project must
3383 specify that qmake uses the \c subdirs template to build the project.
3385 To create a root project, select \gui {File > New File or Project... >
3386 Other Project > Subdirs Project > Choose}.
3388 On the \gui Summary page, select \gui {Finish & Add Subproject} to create
3389 the root project and to add another project, such as a C++ library.
3391 The wizard creates a project file (.pro) that defines a \c subdirs template
3392 and the subproject that you add as a value of the
3393 \l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#subdirs}{SUBDIRS variable}.
3394 It also adds all the necessary files for the subproject.
3396 To add more subprojects, right-click the project name in the \gui Projects
3397 pane, and select \gui {New Subproject} in the context menu.
3399 To remove subprojects, right-click the project name in the \gui Projects
3400 pane, and select \gui {Remove Subproject} in the context menu.
3402 To specify dependencies, use the \gui{Add Library} wizard. For more information,
3403 see \l{Adding Libraries to Projects}.
3409 \contentspage index.html
3410 \previouspage creator-project-creating.html
3411 \page creator-project-opening.html
3412 \nextpage creator-project-qmake-libraries.html
3414 \title Opening a Project
3416 Qt Creator stores information that it needs to build projects in a .user file.
3417 If Qt Creator cannot find the file when you open an existing project, it prompts you
3418 to enter the information. If you created the project by using another Qt Creator
3419 instance, Qt Creator asks whether you want to use the old settings. The settings
3420 are specific to the development environment, and should not be copied from one
3421 environment to another. Therefore, we recommend that you click \gui No and enter
3422 the information again in the \gui {Project Setup} dialog.
3424 The \gui {Project Setup} dialog displays a list of development environments for
3425 target platforms (such as desktop, Maemo5 devices, and Symbian devices) that are
3426 installed on the development PC. Select the Qt versions that you want to use to build
3427 the project for each target.
3429 \image qtcreator-open-project-targets.png "Target Setup dialog"
3431 If Qt Creator cannot find an existing build for a particular development
3432 environment (Qt version) and target, it starts out from a clean slate, and
3433 creates a new build in the specified directory. Qt Creator suggests a name
3434 and location for the directory that you can change.
3436 By default, Qt Creator does a \l{glossary-shadow-build}{shadow build} and also
3437 creates the directory. However, shadow building is not supported for the Symbian
3438 Devices, Maemo5, or Harmattan target on Windows.
3440 If you have built the project before, Qt Creator can use the existing build
3441 configuration to make the exact same build as found in the directory available to
3444 If you know you have a build, but it is not listed, click \gui {Add Build}
3445 to locate it. Select a directory, and Qt Creator scans it (including
3446 subdirectories) for additional builds of the project. Qt Creator adds the found
3447 builds to the target list.
3449 You can edit the build configuration later. For more information, see
3450 \l{Editing Build Configurations}.
3456 \o Select \gui File > \gui{Open File or Project} and select the project
3459 \o In the \gui {Project Setup} dialog, select the Qt versions to use as
3460 build targets for your project, and click \gui{Finish}.
3462 \note If you have only one development environment installed, this dialog
3467 Qt Creator parses all the source files in the project and performs a semantic
3468 analysis to build up the information that it needs for functions such as
3469 navigation and finding usages. A progress bar is displayed during parsing.
3475 \contentspage index.html
3476 \previouspage creator-os-supported-platforms.html
3477 \page creator-project-wizards.html
3478 \nextpage creator-project-cmake.html
3480 \title Adding New Custom Wizards
3482 If you have a team working on a large application or several applications,
3483 you might want to standardize the way the team members create projects
3486 You can copy the wizard templates in the template folders
3487 to create your own project and class wizards. They are displayed in the
3488 \gui New dialog that opens when you choose \gui {File > New File or Project}.
3490 In a project wizard, you can specify the files needed in a project.
3491 You can add wizard pages to allow developers to specify settings for the
3494 In a class wizard, you can allow developers to specify the class name, base
3495 class, and header and source files for the class.
3497 To see how this works, rename wizard_sample.xml as wizard.xml in the
3498 \c {\share\qtcreator\templates\wizards\listmodel\helloworld} and
3499 \c {\share\qtcreator\templates\wizards\listmodel\listmodels} folders. After
3500 you restart Qt Creator, the \gui {Custom Classes}
3501 and \gui {Custom Projects} categories appear in the \gui New dialog.
3503 \image qtcreator-custom-project-wizards.png "The New dialog with custom projects and classes"
3505 \section1 Overview of Custom Wizards
3507 A custom wizard defines the user interface of a wizard page. The values the user enters
3508 in the wizard are assigned field names. Field name and value pairs are then passed to
3509 the file creation process. File creation can happen in the following ways:
3513 \o Template-based, where source files that contain placeholders for
3514 the field names are provided. During processing, the placeholders are replaced
3515 by the values from the wizard page. Optionally, modifier
3516 characters are applied. For more information, see \l{Processing Template Files}.
3518 \o Generator script, where a script is called to create the files.
3520 \note This option mainly exists to accommodate existing generator scripts or
3521 cases where complicated algorithmic logic is required when generating files. Writing
3522 cross-platform scripts is inherently difficult, and therefore, it is not recommended
3523 for new wizards. For more information, see \l{Using Generator Scripts}.
3527 Custom wizards are located in subdirectories of the following directories:
3531 \o \c{share/qtcreator/templates/wizards}
3533 \o the local user's configuration folder,
3534 \c{$HOME/.config/Nokia/qtcreator/templates/wizards}
3536 \o \c{%APPDATA%\Nokia\qtcreator\templates\wizards}
3540 They contain an XML configuration file called wizard.xml, the
3541 template source files, and optionally, the generator script.
3543 \section1 Creating Project Wizards
3545 To create a project wizard:
3549 \o Make a copy of the \c {share/qtcreator/templates/wizards/helloworld} or
3550 \c {share/qtcreator/templates/wizards/listmodel} folder.
3552 \o Modify the wizard_example.xml file.
3554 \o The following code determines the type of the wizard and its place
3555 in the \gui New dialog:
3559 <wizard version="1" kind="project"
3560 class="qt4project" firstpage="10"
3561 id="A.HelloWorld" category="B.CustomProjects">
3567 \o \c version is the version of the file contents. Do not modify this value.
3569 \o \c kind specifies the type of the wizard: \c project or \c class.
3571 \o \c class specifies the type of the project. Currently the only available
3572 type is \c qt4project, which specifies a Qt console project.
3574 \o \c firstpage specifies the place of the new page in the standard project
3575 wizard. The value 10 ensures that the custom page appears after the standard
3576 pages, as the last page of the wizard.
3578 \o \c id is the unique identifier for your wizard. The letter specifies the
3579 position of the wizard within the \c category. The HelloWorld wizard appears
3580 as the first wizard in the second category in the \gui New dialog.
3582 \o \c category is the category in which to place the wizard in the list.
3583 The letter specifies the position of the category in the list in the \gui New
3588 \o The following code specifies the icon and text that appear in the \gui New
3593 <icon>console.png</icon>
3594 <description>Creates a hello-world-project with custom message.</description>
3595 <description xml:lang="de">Erzeugt ein Hello-Welt-Projekt mit einer Nachricht.</description>
3596 <displayname>Hello World</displayname>;
3597 <displayname xml:lang="de">Hallo Welt</displayname>;
3598 <displaycategory>Custom Projects</displaycategory>
3599 <displaycategory xml:lang="de">Benutzerdefinierte Projekte</displaycategory>
3606 \o \c icon appears next to the \c displayName.
3608 \o \c description appears at the bottom of the \gui New dialog when you
3609 select the display name.
3611 \o \c displayName appears in the \gui New dialog, under the
3614 You can add translations as values for the text elements. Specify the target
3615 language as an attribute for the element. Use locale names (QLocale).
3616 For example, \c {xml:lang="de"}.
3620 \o Files to be added to the project:
3623 \o Template-based: The following code specifies the files to add to the project:
3626 <file source="main.cpp" openeditor="true" />
3627 <file source="project.pro" target="%ProjectName%.pro" openproject="true" />
3628 <file source="icon.png" target="%ProjectName%.png" binary="true" />
3632 \o \c source specifies the file to copy to the project. The files must be
3633 located in the wizard folder.
3635 \o \c openeditor indicates that the file is to be opened in an editor after
3636 the wizard has finished.
3638 \o \c binary indicates that the file is a binary file (for example, an
3639 image file). It is to be copied to the target folder as is. Placeholders
3640 are not replaced with values.
3642 \o \c target specifies the new filename for the file. The \c {%ProjectName%}
3643 variable is replaced with the string that users specify in the \gui Name
3644 field on the first page of the wizard.
3646 \o \c openproject indicates that the file is a project file which is to be opened
3647 after the wizard has finished.
3651 See also \l{Processing Template Files}.
3653 \o Generator-script: The following code specifies that the script \c generate.pl is to be used
3654 to create the files:
3656 <generatorscript binary="generate.pl">
3657 <argument value="--class-name=%ClassName%"/>
3658 <argument value="--project-name=%ProjectName%"/>
3659 <argument value="--header-suffix=%CppHeaderSuffix%" omit-empty="true"/>
3660 <argument value="--source-suffix=%CppSourceSuffix%" omit-empty="true"/>
3661 <argument value="--description=%Description%" omit-empty="true" write-file="true"/>
3664 In each argument, the field placeholders are replaced by the field
3665 values. There are additional boolean attributes which give fine-grained control:
3668 \o \c omit-empty specifies that complete argument is to be omitted when all
3669 placeholders expand to empty values. In the above example,
3670 the option \c --source-suffix will not be passed to the script if the value is empty.
3672 \o \c write-file indicates that instead of the expanded value,
3673 the value will be written to a temporary file and its file name will be
3674 passed to the script instead. This is useful for multi-line text fields.
3677 See also \l{Using Generator Scripts}.
3680 \o The following code creates a page that specifies settings for the project:
3684 <!-- Create a 2nd wizard page with parameters -->
3685 <fieldpagetitle>Hello World Parameters</fieldpagetitle>
3686 <fieldpagetitle xml:lang="de">Hallo Welt Parameter</fieldpagetitle>
3688 <field mandatory="true" name="MESSAGE">
3689 <fieldcontrol class="QLineEdit" validator='^[^"]+$' defaulttext="Hello world!" />
3690 <fielddescription>Hello world message:</fielddescription>
3691 <fielddescription xml:lang="de">Hallo-Welt-Nachricht:</fielddescription>
3699 \o \c fieldpagetitle specifies the title of the page.
3701 \o \c field specifies whether the field is mandatory (\c true or \c false).
3702 You can use the value of the \c name field as a variable in other files (for
3703 example, \c {%MESSAGE%}.
3705 \o \c fieldcontrol specifies the field. \c class specifies the field type.
3706 You can use interface objects from the QWidget class to create fields. This
3707 example uses QLineEdit to create an input field.
3709 \o \c validator specifies a regular expression to check the characters allowed in
3712 \o \c defaulttext specifies text that appears in the field by default.
3714 \o \c fielddescription specifies the field name that appears on the wizard page.
3720 \section1 Creating Class Wizards
3722 The widget.xml file for a class wizard is very similar to that for a project
3723 wizard. The differences are discussed below.
3725 To create a class wizard:
3729 \o The following code specifies settings for the wizard:
3733 <wizard version="1" kind="class" id="A.ListModel" category="B.CustomClasses">
3735 <description>Creates a QAbstractListModel implementation.</description>
3736 <description xml:lang="de">Erzeugt eine Implementierung von QAbstractListModel.</description>
3738 <displayname>QAbstractListModel implementation</displayname>
3739 <displayname xml:lang="de">Implementierung von QAbstractListModel</displayname>
3741 <displaycategory>Custom Classes</displaycategory>
3742 <displaycategory xml:lang="de">Benutzerdefinierte Klassen</displaycategory>
3746 For more information about the elements and their values, see
3747 \l {Creating Project Wizards}.
3749 \o The following code specifies the files to add to the project:
3754 <file source="listmodel.cpp" target="%ClassName:l%.%CppSourceSuffix%" openeditor="true" />
3755 <file source="listmodel.h" target="%ClassName:l%.%CppHeaderSuffix%" openeditor="true" />
3760 Here, \c target contains the following variables that are used to construct
3765 \o \c {%ClassName:l%} is replaced with the value of the \c ClassName field.
3766 The modifier \c l converts the string to lower case, to observe Qt
3769 \o \c {%CppSourceSuffix%} and \c {%CppHeaderSuffix%} are pre-defined.
3770 For more information, see \l{Pre-defined Standard Variables}.
3776 <!-- Create parameter wizard page -->
3778 <fieldpagetitle>ListModel parameters</fieldpagetitle>
3779 <fieldpagetitle xml:lang="de">Parameter des ListModel</fieldpagetitle>
3781 <field name="ClassName">
3783 <fieldcontrol class="QLineEdit" validator="^[a-zA-Z0-9_]+$" defaulttext="MyListModel" />
3785 <fielddescription>Class name:</fielddescription>
3786 <fielddescription xml:lang="de">Klassenname:</fielddescription>
3788 <field name="Datatype">
3790 <fieldcontrol class="QComboBox" combochoices="QString,int" defaultindex="0" />
3792 <fielddescription>Data type:</fielddescription>
3793 <fielddescription xml:lang="de">Datentyp:</fielddescription>
3799 In addition to QLineEdit, QComboBox is used in the class wizard to create
3800 a field. \c combochoices specifies the options in the combobox and
3801 \c defaultindex specifies that QString is the default value.
3805 \section1 Processing Template Files
3807 When processing a template source file, placeholders specifying the field names
3808 in the format \c{%FIELDNAME%} are replaced by the values entered by the user.
3809 In addition, modifier characters are supported. For example, \c{%FIELDNAME:u%}
3810 specifies that the value is converted to upper case. This enables generating header
3811 guards for C++ header files.
3813 The following modifier characters are supported:
3816 \o \c{l} for lower case.
3817 \o \c{u} for upper case.
3818 \o \c{c} for upper case initial letter ("project" > "Project").
3821 You can use conditions to add sections of the file depending on field values.
3822 Use a syntax that is similar to C++ preprocessing, as demonstrated in
3823 the profile of the \c{helloworld} example:
3827 @if "%SCRIPT%" == "true"
3833 The value of the Boolean (QCheckBox) field labeled \c{SCRIPT} determines
3834 whether the script module is added. The expressions must expand to valid
3835 Javascript expressions after field replacement.
3837 \section1 Pre-defined Standard Variables
3839 In addition to the field values entered by the user, you can use
3840 the following pre-defined standard values:
3844 \o \c {%ProjectName%} is replaced by the name of the project in the case
3847 \o \c {%Path%} is replaced by the path to the target directory.
3848 For classes, this is the directory, where the files
3849 are created. For project wizards, an additional subdirectory
3850 named after the project is created.
3852 \o \c {%TargetPath%} is replaced by the path to the directory where the actual files
3853 are created. For non-project wizards, it is identical to \c %Path%.
3854 For project wizards, it is \c %Path%/%ProjectName%.
3856 \o \c {%CppSourceSuffix%} is replaced by the default source suffix, which
3857 is defined in Qt Creator in \gui {Tools > Options... > C++ > File Naming}.
3858 For example, if users enter \bold MyClass, the filename becomes myclass.cpp
3859 when the project is created.
3861 \o \c {%CppHeaderSuffix%} is replaced by the default header suffix, which
3862 is also defined in \gui {File Naming}.
3866 \section1 Validating User Input
3868 You can specify validation rules for user input. The rules consist of a Boolean
3869 JavaScript expression and an error message. The placeholders in them are
3870 replaced with values before they are evaluated or displayed.
3872 Consider the following rule used in the \l{Creating Class Wizards} example:
3876 <validationrule condition='"%ClassName%" != "QAbstractListModel"'>
3877 <message>%ClassName% cannot be used as class name.</message>
3878 <message xml:lang="de">%ClassName% kann nicht als Klassenname verwendet werden.</message>
3883 It ensures that the class name entered by the user does not match the name of
3884 the base class. If the validation fails, a red label displaying the message appears
3885 at the bottom of the wizard page.
3887 \section1 Using Generator Scripts
3889 The values entered in the wizard page are passed to the script
3890 as command line arguments as defined by the wizard configuration file.
3892 In addition, the script must implement a \c{--dry-run} command line option.
3894 Qt Creator needs to know the file names before the files are created to check
3895 whether files with identical names already exist, for example. Therefore,
3896 script file generation is a two-step process:
3900 \o Determine file names and attributes: The script is called with the command line
3901 \c{--dry-run} option and the field values. It then prints the relative path
3902 names of the files it intends to create, followed by comma-separated attributes
3903 matching those of the \c{<file>} element, for example:
3906 myclass.cpp,openeditor
3907 myclass.h,openeditor
3908 myproject.pro,openproject
3911 \o Create files: The script is called with the parameters only in the working directory.
3912 It then actually creates the files. If directories are needed, the script
3913 should create them, too.
3917 The \c{scriptgeneratedproject} sample wizard illustrates the usage.
3918 A typical script invocation for this example (obtained by running Qt Creator with
3919 \c{--customwizard-verbose}) looks as follows:
3922 generate.pl --class-name=TestClass --project-name=TestProject --header-suffix=h --source-suffix=cpp --description=/tmp/qtcreatorj26629.txt
3925 By default, the scripts are run in the directory corresponding to
3926 \c %TargetPath%. This can be overriden by specifying the
3927 attribute \c workingdirectory on the element \c generatorscript.
3928 For example, if the script creates the project directory by itself,
3929 %Path% can be specified. In that case, \c --dry-run should output
3930 the correct relative paths or absolute paths constructed using the value of
3937 \contentspage index.html
3938 \previouspage creator-build-settings.html
3939 \page creator-project-qmake.html
3940 \nextpage creator-tool-chains.html
3942 \title Adding Qt Versions
3944 Qt Creator allows you to have multiple versions of Qt installed on
3945 your development PC and use different versions to build your projects for
3946 different targets. For example, \QSDK contains special Qt versions for
3947 MeeGo Harmattan, Maemo, and Symbian development.
3949 Qt Creator checks the directories listed in the \c{PATH} environment
3950 variable for the qmake executable. If a qmake executable is found, it is
3951 referred to as \bold{Qt in PATH} and selected as the Qt version to use
3952 in the \gui Projects mode in the \gui {Build Settings}. If Qt Creator
3953 cannot find qmake, the value in the \gui {Qt version} field might be
3954 invalid and you might need to change it.
3956 Qt Creator automatically detects the Qt versions that are registered by
3957 your system or by \QSDK. To view the settings for each Qt version, move the
3958 mouse pointer over it in the list. To add Qt versions, select
3959 \gui {Tools > Options... > Qt4 > Qt Versions}.
3961 Typically, you select the Qt versions for a project when you use project
3962 wizards to create the project. You can add Qt versions for a project in
3963 \gui {Build Settings}.
3965 \section2 Setting Up New Qt Versions
3967 To add a Qt version:
3971 \o Select \gui Tools > \gui Options... > \gui Qt4 > \gui Add.
3973 \image qtcreator-qt4-qtversions-add.png
3975 \o In the \gui{qmake location} field, enter the path to the
3976 directory where the qmake executable is located.
3978 \o In the \gui{Version name} field, edit the name that Qt Creator
3979 suggests for the Qt version.
3981 Qt Creator automatically determines the path to the binaries in
3982 the Qt installation and displays it in the dialog.
3984 \o In the \gui Helpers section, you can build the debugging
3985 helpers that are available for the Qt version. This is
3986 necessary, because the internal data structures of Qt can
3987 change between versions. For more information, see
3988 \l{Using Debugging Helpers}.
3992 \section2 Setting Up Qt for Symbian Versions
3994 If you install Qt for Symbian as a part of \QSDK, it is automatically
3995 detected by Qt Creator. If you install other Symbian SDKs and register them
3996 with devices.exe, Qt Creator automatically detects the Qt version.
3998 If the selected Qt version was built using the SBSv2 build system, that
3999 is available for Symbian OS 9.5 based SDKs, Qt Creator builds your projects
4000 using this build system. The \gui {SBS v2 directory} field is enabled and
4001 you must specify the path to the directory where the SBS executable (for
4002 example, sbs.bat on Windows) is located.
4004 To add a Qt for Symbian version:
4008 \o Select \gui Tools > \gui Options... > \gui Qt4 > \gui{Qt Versions}.
4010 \o Select the Qt for Symbian version you want the Qt Creator to use.
4012 \image qtcreator-qt4-qtversions-win-symbian.png
4014 For more information about how to add tool chains for using the
4015 GCCE and WINSCW compilers, see \l{Adding Tool Chains}.
4017 \o In the \gui {S60 SDK} field, enter the path to the directory where
4018 the Symbian SDK is located.
4020 \o In the \gui {SBS v2 directory} field, enter the path to the
4021 directory where the SBS v2 executable is located.
4029 \contentspage index.html
4030 \previouspage creator-project-qmake.html
4031 \page creator-tool-chains.html
4032 \nextpage creator-run-settings.html
4034 \title Adding Tool Chains
4036 A \e {tool chain} specifies a compiler and a debugger and other necessary
4037 tools for building an application that is targeted for a particular desktop
4038 or mobile platform. Qt Creator automatically detects the tool chains that
4039 are registered by your system or by \QSDK.
4041 You can add tool chains to build applications by using other compilers or
4042 with different versions of the automatically detected compilers:
4046 \o GNU Compiler Collection (GCC) is a compiler for Linux and
4049 \o MinGW (Minimalist GNU for Windows) is a native software port of GCC
4050 and GNU Binutils for use in the development of native Microsoft
4051 Windows applications on Windows. MinGW is
4052 distributed together with Qt Creator and Qt SDK for Windows.
4054 \o Linux ICC (Intel C++ Compiler) is a group of C and C++ compilers
4057 \o Clang is a C, C++, Objective C, and Objective C++ front-end for the
4058 LLVM compiler for Windows, Linux, Mac OS X, and Symbian.
4060 \o GCCE (GNU Compiler Collection for Embedded) is an ARM-based
4061 compiler used in Symbian OS 9 and distributed together with \QSDK.
4063 \o RVCT is an ARM-based compiler for building applications for Symbian
4064 devices (requires a license).
4066 \o WINSCW is a compiler for building applications that can be run or
4067 debugged on the Symbian Emulator. It is distributed together with
4068 Symbian SDKs (but not with the \QSDK).
4072 To build an application using GCC, MinGW, GCCE, or Clang, specify the paths
4074 directories where the compiler and debugger are located and select the
4075 application binary interface (ABI) version from the list of available
4076 versions. You can also create a custom ABI definition.
4078 Qt Creator allows you to select a tool chain that matches the Qt version
4079 in the \gui Projects mode \gui {Build Settins}.
4085 \o Select \gui {Tools > Options... Tool Chains > Add} and select a
4086 compiler in the list.
4088 \image qtcreator-toolchains.png
4090 To clone the selected tool chain, select \gui {Clone}.
4092 \o In the \gui Name column, double-click the name to change it.
4094 \o In the \gui{Compiler path} field, enter the path to the directory
4095 where the compiler is located. For WINSCW, enter the path to the
4096 Carbide C++ installation directory here.
4098 The other settings to specify depend on the tool chain.
4100 \o For RVCT, select the ARM version to use in the \gui {ARM version}
4105 \section2 Troubleshooting MinGW Compilation Errors
4107 If error messages displayed in the \gui {Compile Output} pane contain
4108 paths where slashes are missing (for example, C:QtSDK),
4109 check your PATH variable. At the command line, enter the following commands:
4114 where mingw32-make.exe
4117 If these commands show paths, they have been added to the global PATH variable
4118 during the installation of a tool chain based on Cygwin or MinGW, even though
4119 this is against Windows conventions.
4121 To keep working with the third-party tool chain, create a new shell link
4122 that adds the required paths (as Visual Studio and Qt do). The shell link
4123 must point to cmd.exe, as illustrated by the following example:
4125 \c {C:\Windows\System32\cmd.exe /K C:\path_to\myenv.bat}
4127 where the /K parameter carries out the command specified in the bat file.
4129 Create the myenv.bat file at \e path_to, which should be in a convenient location.
4130 In the file, specify the paths to the tool chains. For example,
4132 \c {set PATH=C:\path1;C:\path2;%PATH%}
4134 where \e path1 and \e path2 are paths to the tool chains.
4136 Finally, remove the paths from the global PATH, reboot the computer, and
4137 run the \c where commands again to verify that the global PATH is now clean.
4139 You can use the shell link to run the tools in the third-party tool chains.
4145 \contentspage index.html
4146 \previouspage creator-project-opening.html
4147 \page creator-project-qmake-libraries.html
4148 \nextpage creator-developing-maemo.html
4150 \title Adding Libraries to Projects
4152 In addition to Qt libraries, you can add other libraries to your projects.
4153 The way the library is added depends on whether it is a system library or
4154 your own library or a 3rd party library located in the build tree of the
4155 current project or in another build tree.
4157 \image qtcreator-add-library-wizard.png "Add Library wizard"
4159 Because system libraries do not typically change and are often found by
4160 default, you do not need to specify the path to the library or to its includes
4163 For your own libraries and 3rd party libraries, you need to specify
4164 the paths. Qt Creator tries to quess the include path for an external library,
4165 but you need to check it and modify it if necessary. Qt Creator automatically
4166 adds the include path for an internal library.
4168 For all libraries, select the target platforms for the application, library,
4171 Specify whether the library is statically or dynamically linked. For a
4172 statically linked internal library, Qt Creator adds dependencies
4173 (PRE_TARGETDEPS) in the project file.
4175 Depending on the development platform, some options might be detected
4176 automatically. For example, on Mac OS, the library type (\gui Library or
4177 \gui Framework) is detected automatically and the option is hidden. However,
4178 if you develop on another platform than Mac OS and want to build your
4179 project for the Mac OS, you must specify the library type.
4181 The default convention on Windows is that the debug and release versions
4182 of a library have the same name,
4183 but are placed in different subdirectories, usually called \e debug and
4184 \e release. If the library path does not contain either of these folders,
4185 you cannot select the option to place the libraries in separate
4188 Alternatively, the letter \e d can be added to the library name for the debug
4189 version. For example, if the release version is called example.lib, the
4190 debug version is called exampled.lib. You can specify that the letter
4191 is added for the debug version and removed for the release version.
4192 If the library name ends in \e d, deselect the \gui {Remove "d" suffix
4193 for release version} option.
4195 Qt Creator supports code completion and syntax highlighting for the added
4196 libraries once your project successfully builds and links to them.
4198 \section1 To Add Libraries
4202 \o In the \gui Projects pane, open the project file (.pro).
4204 \o Right-click in the code editor to open the context menu and select
4205 \gui {Add Library...}.
4207 \o Follow the instructions of the wizard.
4211 For more information about the project file settings, see
4212 \l{http://doc.qt.nokia.com/4.7/qmake-project-files.html#declaring-other-libraries}{Declaring Other Libraries}.
4214 \section1 Example of Adding Internal Libraries
4216 The following example describes how to add a statically linked internal
4217 library to your project.
4221 \o Choose \gui {File > New File or Project... > Other Projects >
4222 C++ Library} to create the library.
4224 The \gui {Introduction and Product Location} dialog opens.
4226 \image qtcreator-add-library-wizard-ex-1.png "Introduction and Product Location dialog"
4228 \o In the \gui Type field, select \gui {Statically Linked Library}.
4230 \o In the \gui Name field, give a name for the library. For example,
4233 \o Follow the instructions of the wizard until you get to the
4234 \gui {Project Management} dialog. In the \gui {Add to project}
4235 list, select a project. For example, \bold myapp.
4237 \o In the \gui Projects pane, open the project file (.pro).
4238 For example, \bold myapp.pro.
4240 \o Right-click in the code editor to open the context menu and select
4241 \gui {Add Library... > Internal Library > Next}.
4243 \o In the \gui Library field, select \bold mylib and click \gui Next.
4245 \o Click \gui Finish to add the following library declaration to the
4249 win32:CONFIG(release, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/release/ -lmylib
4250 else:win32:CONFIG(debug, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/debug/ -lmylib
4251 else:symbian: LIBS += -lmylib
4252 else:unix: LIBS += -L$$OUT_PWD/../../../projects/mylib/ -lmylib
4254 INCLUDEPATH += $$PWD/../../../projects/mylib
4255 DEPENDPATH += $$PWD/../../../projects/mylib
4257 win32:CONFIG(release, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/release/mylib.lib
4258 else:win32:CONFIG(debug, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/debug/mylib.lib
4259 else:unix:!symbian: PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/libmylib.a
4268 \contentspage index.html
4269 \previouspage creator-usability.html
4270 \page creator-building-running.html
4271 \nextpage creator-building-targets.html
4273 \title Building and Running Applications
4275 Qt Creator provides support for building, running, and deploying Qt
4276 applications for desktop environment and mobile devices.
4278 You can set up the following configurations:
4282 \o \e {Build configuration}, which contains everything you need to
4283 compile the sources into binaries.
4285 \o \e {Deploy configuration}, which handles the packaging and copying
4286 of the necessary files to a location you want to run the executable at.
4287 The files can be copied to a location in the file system of the development
4288 PC or a mobile device.
4290 \o \e {Run configuration}, which starts the application in the location
4291 where it was stored by the deploy configuration.
4295 By default, when you select the \gui Run function, Qt Creator builds, deploys,
4296 and runs the project. For more information about how to change the default
4297 behavior, see \l{Customizing the Build Process}.
4299 \section1 Setting Up a Project
4301 When you install the \QSDK, the build and run settings for the tool chains
4302 delivered with the \QSDK are set up automatically.
4304 To view and modify the settings for currently open projects, switch to the
4305 \gui Projects mode by pressing \key Ctrl+5.
4307 \image qtcreator-projectpane.png
4309 You can add a target if the development environment for the target
4310 platform is installed on the
4311 development PC and the Qt version is configured. Click
4312 \inlineimage qtcreator-qt4-addbutton.png "Add Target button"
4313 and select from a list of available
4314 targets. To remove a target, select it and click
4315 \inlineimage qtcreator-target-remove.png "Remove Target button"
4318 You can select the targets and use the \gui Build menu commands to
4319 build, deploy, and run projects.
4321 The project pane consists of the following tabs:
4323 \o \l{Running Applications on Multiple Targets}{Targets}
4324 (If you have installed the development environment for only one target, the \gui Targets
4325 tab is replaced by a \gui Build tab and a \gui Run tab.)
4326 \o \l{Specifying Build Settings}{Build Settings}
4327 \o \l{Specifying Run Settings}{Run Settings}
4328 \o \l{Specifying Editor Settings}{Editor Settings}
4329 \o \l{Specifying Code Style Settings}{Code Style Settings}
4330 \o \l{Specifying Dependencies}{Dependencies}
4333 Use the \gui Build and \gui Run buttons to switch between
4334 the build and run settings for the active project.
4336 If you have multiple projects open in Qt Creator, use the tabs at the
4337 top of the window to navigate between their settings.
4339 \section1 Customizing the Build Process
4341 To specify the relationship between the release, build, and deploy configurations, select
4342 \gui {Tools > Options... > Project}. By default, the \gui {Always build project
4343 before deploying it} and the \gui {Always deploy project before running it}
4344 options are enabled. Therefore, when you select the \gui Run function,
4345 Qt Creator builds, deploys, and runs the project.
4347 \image qtcreator-project-options-deploy.png "Project General Options"
4353 \contentspage index.html
4354 \previouspage creator-building-running.html
4355 \page creator-building-targets.html
4356 \nextpage creator-running-targets.html
4358 \title Building Applications for Multiple Targets
4360 You can build applications for multiple targets. By default, when
4361 you run the application on a target, you also build and deploy it to the
4362 target, first. However, you can also perform each operation separately.
4364 To check that the application code can be compiled and linked for a target,
4365 you can build the project. The build errors and warnings are displayed in
4366 the \gui {Build Issues} output pane. More detailed information is displayed in
4367 the \gui {Compile Output} pane.
4369 To build an application:
4373 \o Select a target for the project.
4375 \image qtcreator-target-selector.png "Target selector"
4377 \o Choose \gui {Build > Build Project} or press \key {Ctrl+B}.
4381 For more information on the options you have, see \l{Specifying Build Settings}.
4383 \section1 Building for Symbian
4385 The tool chain for building applications locally on the development PC for
4386 the \gui {Symbian Device} target is only supported on Windows.
4387 If you develop on Linux or Mac OS, you must use the Remote Compiler
4388 interface to a compilation service at Nokia Developer. For more information,
4389 see \l{Building with Remote Compiler}.
4391 \section2 Troubleshooting Build Issues
4393 If you cannot build the application for a Symbian device, check that:
4397 \o You selected the Symbian Device target to build the application.
4399 \o You selected the correct Qt version to build the application.
4403 \section1 Building for Symbian Emulator
4405 Qt Creator does not create release configurations for the
4406 \gui {Symbian Emulator} target, because Symbian Emulator supports only debug
4413 \contentspage index.html
4414 \previouspage creator-building-targets.html
4415 \page creator-running-targets.html
4416 \nextpage creator-build-settings.html
4418 \title Running Applications on Multiple Targets
4420 By default, running an application also builds it and deploys it to a
4421 location from where it can be run on the desktop, in Qt Simulator, or
4422 on a mobile device that is connected to the development PC.
4424 To run executable files without deploying them first, deselect the \gui {Tools >
4425 Options... > Project > Always deploy project before running it} option.
4426 This allows you to test SIS files that you receive from Ovi Publishing or
4427 Symbian Signed after you have them signed, for example.
4429 For more information on the options you have, see \l{Specifying Run Settings}.
4431 \section1 Running on Desktop
4435 \o Select \gui Desktop as the target.
4437 \image qtcreator-target-selector.png "Target selector"
4439 \o Click the \gui Run button.
4443 \section1 Running on Qt Simulator
4445 You can use the Qt Simulator to test Qt applications that are intended
4446 for mobile devices in an environment similar to that of the device. You
4447 can change the information that the device has about its configuration
4452 \o Select \gui {Qt Simulator} as the target.
4454 \o Click the \gui Run button.
4458 For more information about using the Qt Simulator, see the
4459 \l{http://doc.qt.nokia.com/qtsimulator/index.html}{Qt Simulator Manual}.
4461 \section1 Running on Maemo or MeeGo Harmattan
4465 \o Build and run the application for \l{Running on Qt Simulator}{Qt Simulator}.
4467 \o Build and run the application for
4468 \l{Using Maemo or MeeGo Harmattan Emulator}
4469 {the Maemo or MeeGo Harmattan emulator}.
4471 \o Alternatively, you can build and run the application for a device:
4475 \o Configure the device and specify a connection to it. For more
4476 information, see \l{Connecting Maemo and MeeGo Harmattan Devices}.
4478 \o Connect the device to the development PC.
4480 \o Click the \gui Run button.
4486 Qt Creator uses the compiler specified in the MADDE tool chain to
4487 build the application.
4489 Qt Creator generates an installation package, installs it on the device,
4490 and executes the selected application.
4491 The application views are displayed on the device.
4493 output is visible in the Qt Creator \gui {Application Output} view.
4495 Choose \gui {Projects > Maemo Run} to view the settings for deploying the
4496 application on the connected device and creating the installation package.
4497 For more information, see
4498 \l{Specifying Run Settings for Maemo and MeeGo Harmattan Devices}.
4500 Debugging also works transparently.
4502 \section1 Running on Generic Linux Devices
4506 \o Build and run the application for \l{Running on Qt Simulator}
4509 \o Build and run the application for a device:
4513 \o Specify a connection to the device. For more information, see
4514 \l{Connecting Generic Linux Devices}.
4516 \o Click the \gui Run button.
4522 Qt Creator uses the compiler specified in the project build settings
4523 (tool chain) to build the application.
4525 Qt Creator generates an installation package, installs it on the
4526 device, and executes the selected application. The application views are
4527 displayed on the device. Command-line output is visible in the Qt
4528 Creator \gui {Application Output} view.
4530 Choose \gui {Projects > Desktop > Run} to view the settings for deploying
4531 the application on the connected device and creating the installation
4532 package. For more information, see
4533 \l{Specifying Run Settings for Generic Linux Devices}.
4535 Debugging works transparently if GDB server is installed on the device and
4536 it is compatible with the GDB on the host.
4538 \section1 Running on Symbian
4542 \o Build and run the application for \l{Running on Qt Simulator}{Qt Simulator}.
4544 \o If no problems are found, build and run the application for a device.
4546 \o To test functionality that uses Symbian APIs, you can build and
4547 run the application for Symbian Emulator.
4551 \section2 Running on a Device
4555 \o Install the required software on the device. For more information, see
4556 \l{Connecting Symbian Devices}.
4558 \o Connect the device to the development PC through a USB cable.
4559 The target selector displays a green check mark when a
4560 device is connected.
4562 \image qtcreator-qt4-symbian-device-connected.png
4564 The tool tip of the target selector shows more details about the actual
4565 device that will be used when you run your application.
4567 \o Start the CODA debugging agent on the device.
4569 \note If you use CODA over an USB connection, it starts up
4570 automatically when you connect the device to the development PC.
4572 \o Click the \gui Run button.
4576 You can connect several devices to your development PC simultaneously.
4577 In the details of the run configuration for the \gui{Symbian Device} target,
4578 select the device to run your application on.
4580 When your application is ready for delivery to users, specify run settings
4581 for creating the final SIS installation packages. For more information,
4582 see \l{Creating SIS Files}.
4584 If you cannot run the application on a device, check that:
4587 \o The Nokia USB drivers that come with \e{PC Suite} or \e{Ovi Suite}
4588 have been installed on the development PC.
4589 \o The device is connected through USB cable in \e{PC Suite} mode.
4590 \o The CODA debugging agent is running on the device with
4591 the status \e connected.
4593 \note If you use the CODA debugging agent over WLAN, you must enter
4594 the WLAN address and port number in Qt Creator, separated by a
4595 colon (:). For example: 192.167.0.100:1534
4596 \o The device is detected and selected in the \gui {Run Settings}.
4599 If this does not help to solve your problem, search the qt-creator@trolltech.com
4600 mailing list archives or provide feedback to us via the methods described on the
4601 \l{http://developer.qt.nokia.com/wiki/Category:Tools::QtCreator}{Qt Creator Development Wiki}.
4603 \section2 Running on Symbian Emulator
4606 the \gui{Symbian Emulator} target as the active one, and build and run your
4609 If you cannot run the application in the emulator, check that:
4611 \o You selected the \gui{Symbian Emulator} target for your application.
4613 \o If you cannot select \gui {Symbian Emulator} as target, check that
4614 Carbide.c++ is installed correctly and that the path to the Carbide.c++
4615 installation directory is specified for the WINSCW tool chain in the
4616 \gui{Compiler path} field
4617 in \gui {Tools > Options... > Tool Chains}.
4619 \o If the emulator process cannot be started, try closing Qt Creator and
4620 starting the application directly from your file manager. Having
4621 done this, Qt Creator should be able to run your projects in the
4630 \contentspage index.html
4631 \previouspage creator-publish-ovi.html
4632 \page creator-remote-compiler.html
4633 \nextpage creator-help.html
4635 \title Building with Remote Compiler
4637 The \gui {Remote Compiler} target is an interface to a compilation service at
4638 Nokia Developer. It provides a simple, standardized environment for building Qt
4639 applications and creating installation packages for Symbian, Maemo, and
4640 MeeGo Harmattan devices
4641 when you do not have the necessary tool chains and SDKs installed or they are
4642 not supported on the development PC. You can choose from a set of supported
4643 devices, such as S60 3rd Edition or S60 5th Edition devices.
4645 You need a Nokia Developer user account to use the Remote Compiler. You can
4646 create an account for free at \l{http://www.developer.nokia.com/}{Nokia Developer}.
4648 \note Remote Compiler is an experimental component that is installed as
4653 \o Select \gui {Start > \QSDK > Maintain \QSDK} to open the
4654 \gui {Maintain \QSDK} tool.
4656 \o In the \gui {Package Manager}, select \gui {Experimental >
4657 Remote Compiler} to install Remote Compiler.
4659 \o In Qt Creator, choose \gui {Tools > Options > Projects > Remote Compiler}
4660 to log on to Nokia Developer.
4662 \image remotecompiler-fn-logon.png "Remote Compiler options"
4664 \o Choose \gui {Projects}.
4667 \inlineimage qtcreator-qt4-addbutton.png "Add Target button"
4668 and select \gui {Remote Compiler} to add Remote Compiler as a target.
4670 \o Click \gui Add to add mobile device platforms as build configurations.
4672 \o Click the \gui {Target Selector} and select a build configuration.
4674 \o Choose \gui {Build > Build All}.
4678 The installation package is generated in the \gui {Build directory} on
4681 For more information about Remote Compiler, choose \gui {Help > Contents >
4682 Remote Compiler Manual}. The document is added during the installation of
4689 \contentspage index.html
4690 \previouspage creator-running-targets.html
4691 \page creator-build-settings.html
4692 \nextpage creator-project-qmake.html
4694 \title Specifying Build Settings
4696 Different build configurations allow you to quickly switch between
4697 different build settings. By default, Qt Creator creates \bold debug
4698 and \bold release build configurations. A debug build contains additional
4699 debug symbols that you need for debugging the application but that you
4700 can leave out from the release version. Generally, you use the debug
4701 configuration for testing and the release configuration for creating
4702 the final installation file.
4704 You specify build settings in the \gui Projects mode.
4706 \image qtcreator-projectpane.png
4708 To add a new build configuration, click \gui Add and select the type of
4709 configuration you would like to add. You can add as many build
4710 configurations as you need.
4712 To delete the build configuration currently selected, click \gui Remove.
4714 \section1 Editing Build Configurations
4716 To edit a build configuration:
4718 \o Select the build configuration you want to edit in
4719 \gui{Edit Build Configuration}.
4720 \o In the \gui {Qt version} field, select the Qt version to use for
4721 building project. You can add Qt versions to the list if they are
4722 installed on the development PC, but were not detected
4723 automatically. For more information, see \l{Adding Qt Versions}.
4724 \o In the \gui {Tool chain} field, select the tool chain required
4725 to build the project. The tool chains that are compatible with the
4726 selected Qt version are listed. You can add tool chains to the list
4727 if they are not automatically detected. For more information, see
4728 \l{Adding Tool Chains}.
4730 \o In the \gui {Build directory} field, specify the build directory for
4732 By default, projects are built in a separate directory from the
4733 source directory, as \l{glossary-shadow-build}{shadow builds}.
4734 This keeps the files generated for each target platform separate.
4736 \note Shadow building is not supported by the Symbian build system.
4737 Also, shadow building on Windows is not supported for Maemo or
4739 If you only build for one target platform, you can deselect
4740 the \gui{Shadow build} checkbox.
4743 \note The build configuration for the \gui{Symbian Device} target
4744 uses the GCCE tool chain by default. If you want to build
4745 for the device using RVCT, install the RVCT tool chain, and then
4746 select it in the \gui {Tool chain} field.
4748 \section1 Starting External Processes
4750 Qt Creator executes external processes to accomplish tasks such as building
4751 and running applications. To execute the processes, Qt Creator uses shell
4752 commands that are native to the system. It constructs the commands from
4753 an executable name and optional command line arguments.
4755 The executable name is specified in the executable fields: \gui qmake,
4756 \gui Make, \gui Command, or \gui Executable. It is either derived from the
4757 project or specified manually. When you specify executables manually, you
4758 can reference environment variables and Qt Creator variables. However, no
4762 You can specify command-line arguments in the arguments fields: \gui {Additional
4763 arguments}, \gui {Command arguments}, \gui {Make arguments}, or \gui Arguments.
4764 You can create shell command lines that can contain redirection and other
4765 advanced constructs. However, some more complex use cases, such as piping
4766 test data into the application being tested or grouping commands, are not
4767 supported because the value of the \gui Executable field is always placed
4768 first when constructing the command.
4770 \section2 Using Environment Variables
4772 You can use any environment variables as values in the fields. For a list
4773 of variable names, click \gui {Build Environment > Details} in the
4774 \gui {Build Settings}. Environment variables are referenced using the native
4775 syntax: $VARNAME or ${VARNAME} on Unix and %VARNAME% on Windows.
4777 \section2 Using Qt Creator Variables
4779 You can use Qt Creator variables in arguments, executable paths, and working
4781 The variables take care of quoting their expansions, so you do not need to
4784 The following Qt Creator variables are available:
4794 \section1 Build Steps
4796 The build system of Qt Creator is built on qmake and make. In
4797 \gui{Build Steps} you can change the settings for qmake and make. Qt
4798 Creator runs the make command using the Qt version defined for the current
4799 build configuration.
4801 \image qtcreator-build-steps.png "Build steps"
4803 To override the shell command that Qt Creator constructs by default, remove
4804 the build step and add a custom build step that specifies another shell
4807 \section2 Adding Custom Build Steps
4809 To add custom steps to the build settings, select \gui {Add Build Step >
4810 Custom Process Step}.
4812 By default, custom steps are disabled. To activate a custom step, select
4813 the \gui{Enable custom process step} check-box.
4815 \image qtcreator-build-steps-custom.png "Custom Process Step"
4817 \section1 Clean Steps
4819 You can use the cleaning process to remove intermediate files. This process
4820 might help you to fix obscure issues during the process of building a
4823 \image qtcreator-clean-steps.png "Clean steps"
4825 You can define the cleaning steps for your builds in the \gui{Clean Steps}:
4827 \o To add a clean step using make or a custom process, click
4828 \gui{Add Clean Step} and select the type of step you want to add.
4830 By default, custom steps are disabled. To activate a custom step,
4831 select the \gui{Enable custom process step} check-box.
4832 \o To remove a clean step, click \gui{Remove Item}.
4833 \o To change the order of steps, click
4834 \inlineimage qtcreator-movestep.png
4838 \section1 Build Environment
4840 You can specify the environment you want to use for building in the
4841 \bold{Build Environment} section. By default, the environment in which Qt
4842 Creator was started is used and modified to include the Qt version.
4843 Depending on the selected Qt version, Qt Creator automatically sets the
4844 necessary environment variables. You can edit existing environment
4845 variables or add, reset and unset new variables based on your project
4848 \image qtcreator-build-environment.png "Build Environment"
4850 \note The changes are stored in the local project specific \c{.pro.user}
4851 file. Therefore, they are not suitable for sharing between developers or
4852 development PCs. To share settings, incorporate them into the build system.
4853 For example, if you use qmake, make the changes in the \c{.pro} file.
4856 \section2 Clearing the System Environment
4858 To build with a clean system environment, select the \gui {Clear system
4859 environment} check box. Qt Creator discards the current environment, and
4860 populates a clean system environment with the environment variables that the
4861 compilers and tools need. Therefore, the environment is never totally empty,
4862 even after you clear it.
4868 \contentspage index.html
4869 \previouspage creator-tool-chains.html
4870 \page creator-run-settings.html
4871 \nextpage creator-editor-settings.html
4873 \title Specifying Run Settings
4875 Qt Creator automatically creates run configurations for your project.
4876 To view and modify the settings, select \gui {Projects > Run}.
4878 The settings to specify depend on the type of the project: Qt project
4879 or Qt Quick project, and on the target for the project.
4881 Click \gui Add to add run settings for a project and \gui Remove to remove
4882 the current settings.
4884 \section1 Specifying Run Settings for qmake Projects
4886 The run configurations for qmake projects derive their executable from the parsed .pro
4888 For more information on how the commands are constructed, see
4889 \l{Starting External Processes}.
4891 \section2 Specifying Run Settings for Desktop Targets
4893 You can specify command line arguments to be passed to the executable
4894 and the working directory to use. The working directory defaults to
4895 the directory of the build result.
4897 For console applications, check the \gui{Run in Terminal} check box.
4898 If you need to run with special environment variables set up, you
4899 also do it in the run configuration settings.
4901 \image qtcreator-pprunsettings.png
4903 You can also create custom executable run configurations where you
4904 can set the executable to be run. For more information, see
4905 \l{Specifying a Custom Executable to Run}.
4907 \section2 Specifying Run Settings for Symbian Devices
4909 Qt Creator automatically detects Symbian devices that are connected to
4910 the development PC with a USB cable.
4911 If only one device is detected, the application is deployed to it
4912 and run on it. If multiple devices are connected to the PC,
4913 make sure that the correct device is selected in the
4914 \gui {Symbian Device} run settings for your project.
4916 You can also pass command line arguments to your application on the device.
4917 Press the \gui{Device info button} to get more information about the selected
4918 device, such as the CPU type and the running debugging agent version.
4920 \image qtcreator-symbian-run-settings.png "Run settings for Symbian devices"
4922 To use the CODA debugging agent over a WLAN connection, enter the WLAN
4923 address of the device and the port number to use, separated by a colon (:),
4924 in the \gui WLAN field. For example: 192.167.0.100:1534
4926 When you deploy the application for the \gui{Symbian Device} target, Qt
4927 Creator generates a Symbian installation system (SIS) file in the project folder
4928 and copies it to the device that is connected to the development PC.
4929 If no device is connected, you must remove the \gui {Deploy SIS Package} step,
4930 to create the package. Click \gui {Remove Item} to skip the step.
4932 \image qtcreator-remove-deploy-step.png "Removing deploy steps"
4934 When you are ready to publish the application on Ovi Store or some other
4935 channel, you must make sure that the SIS file meets the requirements for
4936 publishing and installing applications on Symbian devices. For more information,
4937 see \l{Deploying Applications to Symbian Devices}.
4939 \section2 Specifying Run Settings for Maemo and MeeGo Harmattan Devices
4941 To run an application on a Maemo or MeeGo Harmattan device, create and
4942 select a device configuration in the Maemo 5 or Harmattan run settings for
4944 You can also pass command line arguments to your application.
4946 \image qtcreator-screenshot-run-settings-maemo.png "Run settings for Maemo devices"
4948 To run and debug applications on Maemo or MeeGo Harmattan devices, you must
4950 from the development PC to the devices. Click \gui {Manage device
4951 configurations} to create connections. For more information, see
4952 \l {Configuring Connections in Qt Creator}.
4954 When you run the application on the \gui{Maemo5} or \gui Harmattan target,
4955 Qt Creator generates
4956 a Debian installation package in the build directory by default. You can deliver
4957 the installation package to users for installation on devices that are of
4958 the same type and run the same firmware as the connected device. For more
4960 \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}.
4962 \section2 Specifying Run Settings for Generic Linux Devices
4964 To run an application on a generic Linux device (without MADDE support),
4965 create and select a device configuration in the Desktop run settings for
4966 your project. You can also pass command line arguments to your application.
4968 \image qtcreator-run-settings-linux-devices.png "Run settings for Generic Linux devices"
4970 In addition, you must create a connection from the development PC to the
4971 device. Click \gui {Manage device configurations} to create connections.
4972 For more information, see \l {Connecting Generic Linux Devices}.
4974 When you run the application on the \gui Desktop target, Qt Creator
4975 generates an installation package in the build directory. The name of the
4976 directory is displayed in the \gui {Create tarball} step. Qt Creator copies
4977 the tarball to devices by using the SSH file transfer protocol (SFTP) and
4980 \section1 Specifying a Custom Executable to Run
4982 If you use CMake or the generic project type in Qt Creator, or want
4983 to run a custom desktop executable, create a \gui {Custom Executable}
4984 run configuration for your project. For example, when working on a library,
4985 you can run a test application that links against the library.
4987 Specify the executable to run, command line arguments, working directory,
4988 and environment variables to use.
4990 \image qmldesigner-run-custom-exe.png "Run settings for custom executables"
4992 \section1 Specifying Run Settings for Qt Quick UI Projects
4994 You can specify run settings for the \gui Desktop target:
4998 \o In the \gui {Qt version} field, select a Qt version that has support
5001 \o In the \gui Arguments field, you can specify command line arguments
5002 to be passed to the executable.
5004 \o In the \gui {Main QML file}, select the file that \QQV will be
5007 \o In the \gui Debugger group, select the languages to debug:
5008 \gui{C++} and \gui QML. \gui {Debug port} is the port to access \QQV.
5009 You can use any free port in the registered port range.
5010 For more information, see \l{Debugging Qt Quick Projects}.
5014 \note Opening a socket at a well-known port presents a security risk. Anyone
5015 on the Internet could connect to the application that you are debugging and
5016 execute any JavaScript functions. Therefore, you must make sure that the port
5017 is properly protected by a firewall.
5019 \image qmldesigner-run-settings.png "Run settings for Qt Quick UI projects"
5026 \contentspage index.html
5027 \previouspage creator-deployment-symbian.html
5028 \page creator-deployment-maemo.html
5029 \nextpage creator-publishing-to-maemo-extras.html
5031 \title Deploying Applications to Maemo or MeeGo Harmattan Devices
5033 You can specify settings for deploying applications to Maemo 5 and MeeGo
5034 Harmattan devices in the
5035 project .pro file. You can view the settings in the \gui {Run Settings}.
5037 \image qtcreator-maemo-deployment.png "Deploy to device"
5039 The files to be installed are listed in the
5040 \gui {Deploy to Device} step, the \gui {Files to install for subproject}
5042 \gui {Local File Path} field displays the location of the file on the development
5043 PC. The \gui {Remote Directory} field displays the folder where the file is installed on
5045 Text in red color indicates that the information is missing. Select the
5046 text to edit it and add the missing information.
5048 You can use desktop files to display icons on the home screen of the
5049 device. To add desktop files to the project file, select \gui {Add Desktop
5050 File}. To specify the icon file to display, select \gui {Add Launcher
5051 Icon...}. To remove desktop files and icons, delete the definitions from
5054 If you develop your own libraries, Qt Creator needs to be able to find
5055 them when you compile projects depending on them. When you install MADDE,
5056 an instance of the device file
5057 system, called sysroot, is installed to the development PC. Libraries are copied to
5058 sysroot if the \gui {Also deploy to sysroot} check box is selected.
5060 \section1 Creating Debian Installation Packages
5062 When you run the application on the \gui{Maemo5} or \gui Harmattan target,
5063 Qt Creator generates
5064 a Debian installation package in the build directory by default. You can deliver
5065 the installation package to users for installation on devices that are of
5066 the same type and run the same firmware as the connected device.
5068 \image qtcreator-maemo-deb-package.png "Create installation package"
5070 The name of the installation package is displayed in the \gui {Package name}
5071 field in the \gui {Create Package} step. You can change the version number
5072 in the \gui {Package version} field.
5074 You can specify information that users see on a delivery channel, such as
5075 Ovi Store or Maemo.org. You can specify a short description of the
5076 application, package
5077 name, and application icon.
5079 The Debian control file contains an application icon in encoded form. To add the
5080 application icon to the file, select it in the \gui {Icon to be displayed
5081 in Package Manager} field.
5082 For more information about icon files and adding them manually, see
5083 \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}.
5085 \note Qt Creator automates this process for you.
5087 Qt Creator provides templates for a set of files that must be included
5088 in Debian packages. When you create a \gui Maemo5 or \gui Harmattan target
5089 for a project, Qt Creator
5090 asks whether packaging files are to be added to the project and to version
5091 control. If you plan to edit the packaging files, add them to version
5094 To edit the files, select a file in \gui {Adapt Debian
5095 file} and click \gui Edit. The file opens in the text editor.
5101 \contentspage index.html
5102 \previouspage creator-deployment-maemo.html
5103 \page creator-publishing-to-maemo-extras.html
5104 \nextpage creator-publish-ovi.html
5106 \title Publishing Maemo Applications to Extras-devel
5108 Extras is the primary repository for Maemo applications where most
5109 community software can be found. You can browse the applications available
5110 in Extras at \l{http://maemo.org/downloads/Maemo5/}{Maemo Downloads}.
5112 You can publish both free and commercial applications to Extras. Free
5113 applications must be open source and pass through a QA process.
5114 Commercial applications are usually closed, binary only, and the publisher
5115 is responsible for assuring their quality and security.
5117 You can upload free applications as Debian packages to
5118 \l{http://wiki.maemo.org/Extras-devel}{Extras-devel} at Maemo.org to share
5119 new updates to your application and to start the community QA process.
5120 You need a \l{https://garage.maemo.org/}{Garage} account for the uploads,
5121 but the package itself does not need to be hosted in the Garage.
5123 You can use the \gui {Publish for Fremantle Extras-devel Free Repository}
5124 wizard to create a source archive and, optionally, upload it to a build
5125 server for compiling and packaging. The package is then moved to the
5126 Extras-devel repository. From there on, you must follow the standard
5127 Maemo processes to get the application published to Extras.
5129 The wizard checks that the package contains all the information that is
5130 required to publish applications on Extras: package description and
5131 Package Manager icon. For more information about entering this information,
5132 see \l{Creating Debian Installation Packages}.
5134 To use the publishing wizard:
5138 \o Select the \gui {Maemo5} build target for your project.
5140 \o Choose \gui {Build > Publish Project}.
5142 \o Select \gui {Publish for Fremantle Extras-devel Free Repository},
5143 and then select \gui {Start Wizard}.
5145 \o Select the Qt version and device type to build against and click
5148 To create a source archive without uploading it to the build
5149 server, select the \gui {Only create source package, do not upload}
5152 \o In the \gui {Garage account name} field, enter your login name, or
5153 select \gui {Get an account} to create a new account.
5155 \image qtcreator-publish-maemo-extras.png "Upload Settings dialog"
5157 You can also select \gui {Request upload rights} to use the Maemo
5158 Extras Assistant to validate your Garage account.
5160 \o Select \gui Commit to publish the application.
5168 \contentspage index.html
5169 \previouspage creator-cache-profiler.html
5170 \page creator-deployment.html
5171 \nextpage creator-deployment-symbian.html
5173 \title Deploying Applications to Mobile Devices
5175 Deploy configurations in the \gui Project mode \gui {Run Settings} handle
5176 the packaging of the application as an executable and copying it to a
5177 location you want to run the executable at. The files can be copied to a location
5178 in the file system of the development PC or a mobile device.
5180 When you are ready to publish the application on Ovi Store or some other
5181 channel, you must make sure that the installation file meets the requirements for
5182 publishing and installing applications to Symbian or Maemo devices. The following
5183 sections describe the steps that you have to take to create installation packages
5184 for Symbian, Maemo, or MeeGo Harmattan devices and for publishing on Ovi
5189 \o \l{Deploying Applications to Symbian Devices}
5190 \o \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}
5191 \o \l{Publishing Maemo Applications to Extras-devel}
5192 \o \l{Publishing Applications to Ovi Store}
5193 \o \l{Building with Remote Compiler}
5200 \contentspage index.html
5201 \previouspage creator-deployment.html
5202 \page creator-deployment-symbian.html
5203 \nextpage creator-deployment-maemo.html
5205 \title Deploying Applications to Symbian Devices
5207 This section describes how to create installation packages that meet the
5208 requirements for installing applications to Symbian devices.
5210 \section1 Creating SIS Files
5212 When you deploy the application for the \gui{Symbian Device} target, Qt
5213 Creator automatically generates a Symbian installation system (SIS) file
5214 in the project folder. You can deliver the installation file to users for
5215 installation on Symbian devices.
5217 The name of the installation file is displayed in the \gui {Installation file}
5218 field in the \gui {Run Settings}. In the \gui {Installation drive} field, select the drive on the device
5219 to install the application to. To suppress notifications on the device during the
5220 installation, select the \gui {Silent installation} check box. If the silent
5221 installation fails, Qt Creator attempts installation again, this time displaying
5222 notifications and error messages.
5224 To create a SIS package without copying it to the device (for example, to submit it
5225 to \e {Application Signing Services for Ovi Store} or \e {Symbian Signed}),
5226 create a deploy configuration that contains only the
5227 \gui {Create SIS Package} step.
5229 \image qtcreator-run-settings-create.png "Create SIS Package step"
5232 \section1 Signing SIS Files
5234 Only installation files signed with a certificate and private key are
5235 allowed to be installed onto Symbian devices. By default, Qt Creator
5236 self-signs the installation file. This self-signing allows you to install
5237 the application on a mobile device but places limits on what you can do
5238 with the installation file, including:
5240 \o Self-signed applications cannot access the more sensitive
5241 \l{Capabilities and Signing}{capabilities} of the mobile device.
5242 \o Security warnings will be displayed when you install the self-signed
5243 application on a mobile device.
5244 \o Self-signed applications cannot be published to Ovi
5248 To get around these limitations, you need to go through the Symbian Signed
5249 or Application Signing Services for Ovi Store. The Symbian Signed organisation
5250 manages a public key
5251 infrastructure to provide public authentication of the information in the
5252 application signing certificates. Their security partner can validate your
5253 certificate and give you a Publisher ID. Then, when you sign an
5254 application, other people can be confident that the information in your
5255 certificate is correct and that the application does actually come from you.
5257 Application Signing Services for Ovi Store is a variant of the Symbian
5258 Signed certification provided by Ovi
5259 Publishing. It is limited to the Basic and System capability sets
5260 (Express Signing). Participants can submit an unsigned SIS file to Ovi
5261 Publishing for signing. For more information about how
5263 \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}.
5265 There are also options that do not require you to get a Publisher ID. For
5266 more detail about how the Symbian Signed process works, see
5267 \l{https://www.symbiansigned.com}{Symbian Signed}.
5269 When you have your own certificate and private key, you can specify them in
5270 the \gui{Create SIS Package} step in the \gui {Run Settings}.
5272 \image qtcreator-qt4-symbian-signing.png
5275 If your private key is protected by a passphrase, Qt Creator asks you for the
5276 passphrase when the package is signed and offers to store it. However, storing
5277 passphrases in Qt Creator presents a security risk. To make Qt Creator forget
5278 all saved passphrases, click \gui {Reset Passphrases}.
5280 \section2 Capabilities and Signing
5282 Capabilities allow the Symbian platform to control access by applications to
5283 the functionality provided by the platform APIs. Access to capabilities is
5284 determined by the device configuration and how the application has been signed.
5286 Symbian Signed offers the following signing options depending on the
5287 capabilities that the application accesses:
5291 \o \bold{Express signed} for applications that access only user and system
5294 \o \bold{Certified signed} for applications that access also restricted or
5295 device manufacturer capabilities.
5297 \note You need to request the rights to access device manufacturer
5298 capabilities from the manufacturer.
5302 For more information about how to choose the appropriate signing option and
5303 how you can check which capabilities you need, see
5304 \l{https://www.symbiansigned.com}{Symbian Signed}
5306 \l{http://doc.qt.nokia.com/4.7/platform-notes-symbian.html#required-capabilities}{Required Capabilities for Qt Applications}.
5308 For more information on how to define capabilities for a project, see
5309 \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#capabilities}{Capabilities}.
5311 \note In Qt 4.7.1 and later, if you select the \gui {Self-signed certificate}
5312 option, the SIS generation process checks that the package can be self-signed.
5313 If problems are found, it attempts to fix the package. If fixes cannot be made,
5314 a message appears in the \gui {Compile Output} view.
5316 The following modifications can be made:
5320 \o Package UID is changed to an UID from the unprotected range (if it was
5321 from the protected range).
5323 \o Vendor ID is set to zero on all binaries included in the package file.
5325 \o All restricted and device manufacturer capabilities are removed from all
5326 libraries included in the package file.
5330 The application UID or capabilities used in executables (.exe) cannot be changed,
5331 because that would break the application. If the executables use protected UIDs
5332 or restricted or device manufacturer capabilities, signing fails and an error
5333 message appears in the \gui {Compile Output} view.
5335 \section1 Creating Smart Installer for Symbian Packages
5337 To deploy Qt applications on Symbian devices, you must install the software that Qt applications
5338 require, typically Qt, QtWebkit, and Open C. Nokia Smart Installer for Symbian makes it easier
5339 for users to install Qt applications to Symbian phones by checking whether the device contains
5340 the necessary software and by installing the missing pieces.
5342 For this to work, the Nokia Smart Installer must be packaged with the Qt application. The
5343 application SIS file must first be Symbian Signed or signed by the Application
5344 Signing Services for Ovi Store. The capabilities used in the applications
5345 determine, which signing option must be selected. The wrapper package must be signed using
5346 either the same option or a more extensive option than the application SIS.
5348 \note If you use the Application Signing Services for Ovi Store, you can submit an unsigned
5349 wrapper package to Ovi Publishing. For more information, see
5350 \l{Publishing Applications to Ovi Store}.
5352 You can either install the Nokia Smart Installer for Symbian as part of
5353 the \QSDK, or download and install it from the
5354 \l{http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Nokia Smart Installer for Symbian}
5357 To package Nokia Smart Installer with the application, select the \gui {Create Smart Installer
5358 package} check box. This ensures that up-to-date and appropriate versions of Qt and its
5359 dependencies are installed on devices. Further, it reduces the file size of the application you
5360 publish, because you do not have to deliver the required libraries.
5362 Nokia has reserved the following UIDs to be used with Nokia Smart Installer for Symbian:
5366 \o 0xA000D7CE for self-signed applications
5367 \o 0x2002CCCF for Ovi Store or Symbian Signed packages
5371 \section2 Creating Self-signed Smart Installer Packages
5373 To create a self-signed Nokia Smart Installer for Symbian wrapped .sis file,
5374 you must use an UID from the unprotected UID range, provided by Symbian Signed
5375 and the wrapper package UID value 0xA000D7CE. If you used the Qt Creator project
5376 wizard to create the project, this wrapper package UID is used by default.
5380 \o Make sure that the source directory is clean. For example, if you use Git,
5381 enter the following command:
5385 \o Click \gui Projects to edit the \gui {Build Settings} for the
5386 \gui {Symbian Device} target.
5388 \o Select the \gui Release configuration.
5390 \o Open the \gui {Run Settings}.
5392 \o In the \gui {Create SIS Package} step, select \gui {Self-signed certificate}.
5394 \o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to
5395 skip the step of copying the SIS file to a device. The SIS file is created
5396 in the project folder.
5398 \image qtcreator-remove-deploy-step.png "Removing deploy steps"
5400 \o To package Nokia Smart Installer for Symbian with the application, select
5401 the \gui {Create Smart Installer package} check box.
5403 \o Edit the project .pro file to use the correct UIDs for the application and
5404 the wrapper package, as illustrated by the following code snippet:
5408 TARGET.UID3 = 0xE4DE5D27
5409 DEPLOYMENT.installer_header=0xA000D7CE
5412 "%{\"CustomVendor-EN\"}" \
5415 my_deployment.pkg_prerules = vendorinfo
5416 DEPLOYMENT += my_deployment
5420 \o Choose \gui {Build > Run Project}.
5424 Qt Creator automatically generates a wrapper package in the project folder.
5426 \section2 Creating Symbian Signed Smart Installer Packages
5428 If the application uses functions that require advanced capabilities (AllFiles,
5429 DRM, TCB, CommDD, DiskAdmin, NetworkControl, MultimediaDD), you must use the
5430 standard Symbian Signed process to have the application Symbian Signed. Depending
5431 on the capabilities used, you may use either the Express Signed or the Certified
5432 Signed path, or the manufacturer-specific channel (for AllFiles, DRM, and TCB).
5436 \o Make sure that the source directory is clean. For example, if you use Git,
5437 enter the following command:
5441 \o Click \gui Projects to edit the \gui {Build Settings} for the
5442 \gui {Symbian Device} target.
5444 \o Select the \gui Release configuration.
5446 \o Open the \gui {Run Settings}.
5448 \o In the \gui {Create SIS Package} step, specify the developer certificate
5449 and key in the \gui {Custom certificate} and \gui {Key file} fields.
5451 \o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to
5452 skip the step of copying the SIS file to a device. The SIS file is created
5453 in the project folder.
5455 \o Edit the project .pro file to use the correct UIDs and vendor information
5456 for the application, as illustrated by the following code snippet:
5460 TARGET.UID3 = 0x2000D7D1
5461 DEPLOYMENT.installer_header=0x2002CCCF
5464 "%{\"CustomVendor-EN\"}" \
5467 my_deployment.pkg_prerules = vendorinfo
5468 DEPLOYMENT += my_deployment
5472 \o Choose \gui {Build > Run Project}.
5474 \o Submit the created .sis file to Symbian Signed for certification.
5476 \note Ensure that your application complies with the Symbian Signed
5477 Test Criteria before submitting the file for certification. Also, if the file is
5478 intended for Ovi Store publishing, verify that the application complies with Ovi
5479 Store publishing requirements.
5481 \o After receiving the .sis file from Symbian Signed, copy it over the old
5484 \note The instructions below assume that you have installed \QSDK.
5486 \o To package Nokia Smart Installer for Symbian with the application, choose
5487 \gui {Start > Qt SDK > Symbian > Qt for Symbian Command Prompt}
5488 to open the Qt command line environment.
5490 \o Change to the project directory. For example:
5492 \c{cd C:\Sources\Application}
5494 \o To create a Smart Installer wrapper package, enter the following
5497 \c {C:\Sources\Application> make ok_installer_sis QT_SIS_CERTIFICATE=publisherid.cer QT_SIS_KEY=publisherid.key}
5499 \o Submit the created wrapped .sis file, application_installer.sis, to
5500 Symbian Signed. Express Signed is a suitable signing option for the wrapper
5501 package. The capabilities used in the application do not play a role here,
5502 because the wrapper package is already signed.
5506 Qt Creator automatically generates a wrapper package in the project folder.
5508 \note Ensure that your application complies with the requirements before submitting
5509 the file to Ovi Store.
5511 For more information about the qmake DEPLOYMENT variable, see
5512 \l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#deployment}{qmake Variable Reference}.
5514 For more information about the Nokia Smart Installer, see the
5515 \l{http://doc.qt.nokia.com/smart-installer/index.html}{Nokia Smart Installer for Symbian Manual}.
5517 Note: Nokia Smart Installer for Symbian is only available on Windows.
5519 \section1 Application UID
5521 A UID is a globally unique identifier that is used to
5522 uniquely identify, for example, an object or file type. In Symbian development,
5523 objects are identified by compound identifiers that are constructed from three
5524 UIDs, namely UID1, UID2, and UID3. UID1 and UID2 specify the category of an
5525 object, whereas UID3 identifies a particular object, such as an application.
5527 When you create a \gui {Mobile Qt Application}, Qt Creator adds a UID3 suitable for
5528 development and debugging automatically to the application .pro file. However, to
5529 distribute your application and get it Symbian Signed, you must apply for a UID
5530 from Symbian Signed, which manages the allocation of UIDs. You can request UIDs either one
5531 at a time or as preallocated blocks on the \l{https://www.symbiansigned.com/app/page}{Symbian Signed}
5534 If you use the Ovi Signed process, Ovi Publisher Support allocates the UID for you.
5536 Replace the testing UID with the distribution UID in the .pro file before you
5537 build the final installation package. For more information, see
5538 \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#unique-identifiers}{Unique Identifiers}.
5544 \contentspage index.html
5545 \previouspage creator-publishing-to-maemo-extras.html
5546 \page creator-publish-ovi.html
5547 \nextpage creator-remote-compiler.html
5549 \title Publishing Applications to Ovi Store
5551 Ovi Store is the global content market of Nokia, which reaches millions of
5552 people worldwide. Consumers can access Ovi Store through either of these
5557 \o Ovi Store applications on mobile devices
5559 \o Web browsers on desktop computers, laptops, netbooks, and tablets
5563 Consumers have access to a wide selection of content and can download
5564 content in a few easy clicks.
5566 The process and requirements to publish Qt applications to Ovi Store are
5568 \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.
5570 This section describes how to
5571 generate installation packages that
5572 you can publish to Ovi Store.
5574 \section1 Publishing Qt Content for Symbian Devices
5576 You can use the \e {Application Signing Services for Ovi Store} to get your
5577 application Express Signed for
5578 free by Nokia. Make sure to use the \l{Application UID}{application UID} that you
5579 receive from Ovi Publisher Support.
5581 The \gui {Publish Qt Symbian Applications to Ovi Store} wizard allows you
5582 to check that your application can be
5583 published on Ovi Store. It checks that the application UID, vendor name,
5584 and the capabilities used meet the Ovi Publishing criteria.
5586 If you use Symbian Signed UIDs or the application uses functions that
5588 \l{Capabilities and Signing}{capabilities}, you must
5589 use the standard Symbian Signed process to have the application Symbian Signed
5590 (using the Certified Signed path or the manufacturer-specific channel).
5591 For more information, see \l{Deploying Applications to Symbian Devices}.
5593 To use the publishing wizard:
5597 \o Select \gui Projects to select the Qt version to build the
5598 application. For more information, see \l{Supported Configurations}.
5600 \o Select the \gui {Symbian Device} build target for your project.
5602 \o Choose \gui {Build > Publish Project}.
5604 \o Select \gui {Publish Qt Symbian Applications to Ovi Store}, and then
5605 select \gui {Start Wizard}.
5607 \o Select the Qt version and device type to build against and click
5608 \gui Next. We recommend that you select a release configuration.
5610 \o The wizard checks the information in the project file against the
5611 Ovi Publishing criteria and indicates possible problems. You can fix
5612 some of the problems in the wizard.
5614 \image qtcreator-publishing-wizard-symbian.png "Project File Checks dialog"
5616 \o Select \gui Commit to save changes and create the .sis file. The
5617 .sis file is packaged with Nokia Smart Installer for Symbian.
5619 \o Choose \gui {Open Containing Folder} to open the folder where the
5620 .sis file was created.
5622 \o Submit the created .sis file to Ovi Publishing as a Qt Content item.
5624 \note You cannot use this .sis file for testing.
5628 \note After you change the application UID, you must use the developer
5629 certificate-key pair that you receive from Ovi Publisher Support for testing
5630 the application on devices. The following error message is displayed on the
5631 device if you use UIDs from the trusted range (0x2xxxxxxx) in a self-signed
5632 application: \gui {Unable to install a trusted application from a trusted
5634 information, see \l{http://www.developer.nokia.com/Community/Wiki/UID}{UID}.
5636 If you try to use more capabilites than the certificate permits, the
5637 following error message is displayed on the device: \gui {Requested
5638 application access not granted.} For example, if you try to install a
5639 self-signed application that uses a system capability.
5641 \section2 Supported Configurations
5643 When you select the Qt version to build the application with, consider
5644 which version provides the application with the widest support on different
5645 Symbian platforms. The binary compatibility promise of Qt and Symbian means
5646 that applications that are built against Qt 4.6.3 also run on Qt 4.7.3.
5647 Similarly, applications that are supported on Symbian^1 are also supported
5648 on Symbian^3. However, dependencies, such as QML or Qt Mobility API
5649 versions might restrict the choice of Qt versions that you have.
5651 In general, if you use only Qt widgets and APIs in the application, you
5652 can use \gui {Qt 4.6.3 for Symbian^1} to build it.
5653 The application is supported on both Symbian^1 and Symbian^3 devices.
5655 If you use QML in the application, you can use \gui {Qt 4.7.3 for
5656 Symbian^1} to build it. The application is supported on both Symbian^1 and
5659 If you use native Symbian APIs, you must check that they are available on
5660 the target devices. For more information about the API differences between
5661 Symbian^1 (S60 5th Edition) and Symbian^3, see the \bold {Symbian
5662 Reference Documentation for Qt}, which is delivered together with \QSDK
5663 and which you can view in the \gui Help mode.
5665 The following table summarizes the supported configurations for each Qt
5666 version available in Qt Creator build settings:
5672 \i Qt Mobility Version
5673 \i Native Symbian C++ APIs
5676 \i Qt 4.6.3 for S60 3rd Edition
5682 \i Qt 4.6.3 for Symbian^1 (S60 5th Edition)
5688 \i Qt 4.6.3 for Symbian^3
5694 \i Qt 4.7.3 for Symbian^1
5700 \i Qt 4.7.3 for Symbian^3
5707 \section1 Publishing Qt Content for Maemo Devices
5709 The applications that you publish on Ovi Store, must meet the testing criteria
5711 \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}
5712 {Maemo 5 Applications: Ovi Store Entry Requirements}.
5714 Make sure that your application passes the following most commonly
5719 \o Package filename must include the application name and version
5720 number using three digits. For example: myapplication_1_0_1.deb
5722 \o Application files must be installed to the opt folder on the ext3
5725 \o Debian packages must be given the category user/hidden.
5727 \o Application cannot crash or hang during use.
5729 \o The application must handle different memory situations correctly.
5733 You set the application name and installation folder in the
5734 \gui {Run Settings} for the project. For more information, see
5735 \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}. Qt Creator
5736 specifies the correct
5737 category settings by default when it creates the Debian directory and
5738 the necessary files.
5740 You can test the application on Qt Simulator and Maemo emulator to make
5741 sure that it does not crash or hang and to check how it handles different
5742 memory situations. Before you submit the application to Ovi Publishing, you
5743 must also fully test it on a Maemo device.
5745 \section1 Publishing Qt Content for MeeGo Harmattan Devices
5747 You cannot publish applications that are built with the beta version of the
5748 MeeGo Harmattan tool chain to Ovi Store.
5750 However, you can prepare for publishing by making sure that your application
5752 \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}
5753 {MeeGo 1.2 Harmattan Applications: Ovi Store Entry Requirements}.
5758 \contentspage index.html
5759 \previouspage creator-run-settings.html
5760 \page creator-editor-settings.html
5761 \nextpage creator-code-style-settings.html
5763 \title Specifying Editor Settings
5765 Qt Creator uses the \l{Editing MIME Types}{MIME type} of the file to
5766 determine which mode and editor to use for opening the file. For example,
5767 Qt Creator opens .txt files in \gui Edit mode in the text editor.
5769 You can configure the text editor according to your needs. You can specify
5770 editor behavior either globally for all projects or separately for each
5771 project. To specify global editor behavior, select \gui {Tools > Options...
5772 > Text Editor > Behavior}.
5774 To configure the text editor behavior for the current project:
5778 \o Select \gui {Projects > Editor Settings}.
5780 \o Deselect the \gui {Use global settings} check box.
5782 \o Specify text editor settings for the project.
5786 \image qtcreator-editor-settings.png "Editor Settings view"
5788 For more information about the settings, see:
5792 \o \l{Indenting Code}
5794 \o \l{File Encoding}
5796 \o \l{Moving to Symbol Definition or Declaration}
5798 \o \l{Configuring Fonts}
5806 \contentspage index.html
5807 \previouspage creator-editor-settings.html
5808 \page creator-code-style-settings.html
5809 \nextpage creator-build-dependencies.html
5811 \title Specifying Code Style Settings
5813 Qt Creator uses the \l{Editing MIME Types}{MIME type} of the file to
5814 determine which mode and editor to use for opening the file.
5815 Qt Creator opens C++ files in \gui Edit mode in the C++ code editor and
5816 QML files in the Qt Quick editor.
5818 You can configure the code style according to your needs. You can specify
5819 code style either globally for all projects or separately for each
5820 project. To specify global code style for C++ files, select \gui {Tools >
5823 To specify global code style for QML files, select \gui {Tools > Options...
5826 To configure the editor behavior for the current project:
5830 \o Select \gui {Projects > Code Style Settings}.
5832 \o In the \gui Language field, select \gui C++ or \gui Qt Quick.
5834 \o Deselect the \gui {Use global settings} check box.
5836 \o In the \gui Settings field, select \gui Custom.
5838 \o Specify code style settings for the project. Only \gui General
5839 settings are available for QML files.
5843 \image qtcreator-code-style-settings.png "Code Style Settings view"
5845 For more information about the settings, see \l{Indenting Code}.
5851 \contentspage index.html
5852 \previouspage creator-code-style-settings.html
5853 \page creator-build-dependencies.html
5854 \nextpage creator-debugging.html
5856 \title Specifying Dependencies
5858 If you have multiple projects loaded in a session, you can define the
5859 order in which they are built. For example, if project A depends on project
5860 B, project B must be built first.
5862 \note The build order is stored as a property of a session, not a project.
5863 You must open the session for these settings to take effect. For more
5864 information, see \l{Managing Sessions}.
5866 \image qtcreator-build-dependencies.png "Dependencies view"
5868 To define the build order of projects within a session:
5870 \o In \gui Projects, select a project.
5871 \o Click \gui Dependencies.
5872 \o Select projects that must be built before the current project is
5876 Qt Creator calculates the build order based on the dependencies that you
5877 specify for the projects loaded in the session.
5879 \note You cannot use this view to specify subprojects for projects.
5880 For more information on how to add subprojects, see \l{Adding Subprojects
5887 \contentspage index.html
5888 \previouspage creator-quick-tour.html
5889 \page creator-getting-started.html
5890 \nextpage creator-build-example-application.html
5892 \title Getting Started
5894 This section contains examples that illustrate how to use Qt Creator
5895 to create, build, and run simple
5899 \o \l{Building and Running an Example Application}
5900 \o \l{Creating a Qt Widget Based Application}
5901 \o \l{Creating a Mobile Application with Qt SDK}
5902 \o \l{Creating a Qt Quick Application}
5909 \contentspage index.html
5910 \previouspage creator-writing-program.html
5911 \page creator-mobile-example.html
5912 \nextpage creator-qml-application.html
5914 \title Creating a Mobile Application with Qt SDK
5916 \note To complete this tutorial, you must install \QSDK.
5917 The installation program installs and configures the necessary tool chains
5918 for mobile application development.
5920 This tutorial describes how to use Qt Creator to create a small Qt
5921 application, Battery Indicator, that uses the System Information
5922 Mobility API to fetch battery information from the device.
5924 \image qtcreator-batteryindicator-screenshot.png
5926 \section1 Creating the Battery Indicator Project
5928 \note Create the project with the \gui{Help} mode active so that you can follow
5929 these instructions while you work.
5933 \o Select \gui{File > New File or Project > Qt Widget Project > Mobile
5935 Application > Choose}.
5937 \image qtcreator-new-mobile-project.png "New File or Project dialog"
5939 The \gui{Introduction and Project Location} dialog opens.
5941 \image qtcreator-mobile-intro-and-location.png "Introduction and Project Location dialog"
5943 \o In the \gui{Name} field, type \bold {BatteryIndicator}.
5945 \o In the \gui {Create in} field, enter the path for the project files. For example,
5946 \c {C:\Qt\examples}, and then click \gui{Next}.
5948 The \gui{Target Setup} dialog opens.
5950 \image qtcreator-mobile-project-qt-versions.png "Target Setup dialog"
5952 \o Select \gui {Symbian Device}, \gui {Maemo5}, \gui Harmattan, and
5953 \gui {Qt Simulator} targets,
5954 and click \gui{Next}.
5956 \note Targets are listed if you installed the appropriate development
5957 environment, for example, as part of the \QSDK. You can add targets
5958 later in the \gui Projects mode.
5960 The \gui {Mobile Options} dialog opens.
5962 \image qtcreator-mobile-project-app-options.png "Mobile Options dialog"
5964 \o In the \gui {Orientation behavior} field, determine how the application
5965 behaves when the orientation of the device display rotates between portrait
5966 and landscape, and then click \gui{Next}.
5968 \note This dialog opens only if you select \gui Maemo5 or
5969 \gui {Symbian Device} target in the \gui {Target Setup} dialog. On
5970 Harmattan, the Qt Quick Components for MeeGo provide native-looking
5973 The \gui {Symbian Specific} dialog opens.
5975 \image qtcreator-mobile-project-symbian-options.png "Symbian Specific dialog"
5977 \note Qt Creator contains a default program icon and generates an
5978 \l{Application UID}, for testing the application on a device. You only
5979 need to change the icon and UID if you deliver the application for public use.
5983 The \gui {Maemo Specific} dialog opens.
5985 \image qtcreator-mobile-project-maemo-options.png "Maemo Specific dialog"
5987 \o In the \gui {Application icon} field, select the application
5988 icon to use on Maemo 5 or Harmattan targets, or click \gui Next to use
5991 The \gui{Project Management} dialog opens.
5993 \image qtcreator-mobile-project-summary.png "Project Management dialog"
5995 \o Review the project settings, and click \gui{Finish} to create the project.
5999 The BatteryIndicator project now contains the following files:
6003 \o BatteryIndicator.pro
6005 \o BatteryIndicator.svg
6006 \o BatteryIndicator.png
6007 \o BatteryIndicator.desktop
6012 \o templates for Debian deployment files
6016 \image qtcreator-mobile-project-contents.png "Project contents"
6018 The files come with the necessary boiler plate code that you must
6019 modify, as described in the following sections.
6021 \section1 Declaring the Qt Mobility API
6023 To use the Qt Mobility APIs or develop applications for Symbian
6024 devices, you must modify the .pro file to declare the Qt Mobility APIs
6027 This example uses the System Info API, so you must declare it, as
6028 illustrated by the following code snippet:
6033 MOBILITY = systeminfo
6037 Each Mobility API has its corresponding value that you have to add
6038 as a value of MOBILITY to use the API. For a list of the APIs and the
6039 corresponding values that you can assign to MOBILITY, see the
6040 \l {http://doc.qt.nokia.com/qtmobility/quickstart.html}{Quickstart Example}.
6042 \section1 Designing the User Interface
6046 \o In the \gui{Editor} mode, double-click the mainwindow.ui
6047 file in the \gui{Projects} view to launch the integrated \QD.
6049 \o Drag and drop a \gui{Progress Bar} (\l{http://doc.qt.nokia.com/4.7/qprogressbar.html}{QProgressBar})
6052 \image qtcreator-mobile-project-widgets.png "Adding widgets to the UI"
6054 \o In the \gui Properties pane, change the \gui objectName to
6055 \bold batteryLevelBar.
6057 \o Right-click the \gui MainWindow object and select
6058 \gui {Lay Out > Lay Out Horizontally} to ensure that the battery
6059 indicator widget size is adjusted correctly on Maemo devices.
6063 \section1 Completing the Header File
6065 The mainwindow.h file contains some of the necessary #includes, a
6066 constructor, a destructor, and the \c{Ui} object. You must include
6067 the System Info header file, add a shortcut to the mobility name
6068 space, and add a private function to update the battery level value in
6069 the indicator when the battery power level changes.
6073 \o In the \gui{Projects} view, double-click the \c{mainwindow.h} file
6074 to open it for editing.
6076 \o Include the System Device Info header file, as illustrated by the following
6079 \snippet examples/batteryindicator/mainwindow.h 1
6081 \o Add a shortcut to the mobility name space, as illustrated by the
6082 following code snippet:
6084 \snippet examples/batteryindicator/mainwindow.h 2
6086 \o Declare a private function in the \c{private} section, after the
6087 \c{Ui::MainWindow} function, as illustrated by the following code
6090 \snippet examples/batteryindicator/mainwindow.h 3
6094 \section1 Completing the Source File
6096 Now that the header file is complete, move on to the source file,
6101 \o In the \gui{Projects} view, double-click the mainwindow.cpp file
6102 to open it for editing.
6104 \o Create a QSystemDeviceInfo object and set its value. Then connect the signal
6105 that indicates that battery level changed to the \c setValue
6106 slot of the progress bar. This is illustrated by the following code snippet:
6108 \snippet examples/batteryindicator/mainwindow.cpp 1
6110 \o Use the constructor to set initial values and make sure that the
6111 created object is in a defined state, as illustrated by the following
6114 \snippet examples/batteryindicator/mainwindow.cpp 2
6118 \section1 Compiling and Running Your Program
6120 Now that you have all the necessary code, select \gui {Qt Simulator}
6121 as the target and click the
6122 \inlineimage qtcreator-run.png
6123 button to build your program and run it in the Qt Simulator.
6125 In Qt Simulator, run the runOutOfBattery.qs example script
6126 to see the value change in the Battery Indicator application.
6127 Select \gui {Scripting > examples > runOutOfBattery.qs > Run}.
6129 \image qtcreator-mobile-simulated.png "Mobile example in Qt Simulator"
6131 \section1 Testing on a Symbian Device
6133 You also need to test the application on real devices. Before you can
6134 start testing on Symbian devices, you must connect them to the development
6135 PC by using a USB cable and install the necessary software on them.
6139 \o Install Qt libraries, Qt mobile libraries, and a
6140 debugging agent on the device. For more information,
6141 see \l{Connecting Symbian Devices}.
6143 \o Start the CODA debugging agent on the device.
6145 \o Click the \gui {Target Selector} and select \gui {Symbian Device}.
6147 \o Click \gui Run to build the application for the Symbian device.
6151 \section1 Testing on the Maemo or MeeGo Harmattan Emulator
6153 The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
6154 of the \QSDK. After they are installed, you can start them from Qt Creator.
6156 The Maemo emulator emulates the Nokia N900 device environment. You can test
6157 applications in conditions practically identical to running the application
6158 on a Nokia N900 device with the software update release 1.3 (V20.2010.36-2).
6160 The MeeGo Harmattan emulator emulates the Nokia N9 device environment.
6162 For more information, see \l{Using Maemo or MeeGo Harmattan Emulator}.
6167 \contentspage index.html
6168 \previouspage creator-getting-started.html
6169 \page creator-build-example-application.html
6170 \nextpage creator-writing-program.html
6172 \title Building and Running an Example Application
6174 You can test that your installation is successful by opening an existing
6175 example application project.
6179 \o On the \gui Welcome page, select \gui {Choose an Example...}
6180 in the \gui {Explore Qt Quick Examples} field, and then select
6181 \gui {Toys > Clocks}.
6183 \image qtcreator-gs-build-example-open.png "Selecting an example"
6185 \o Select targets for the project. Select at least Qt Simulator
6186 and one of the mobile targets, Symbian Device, Maemo 5, or Harmattan,
6188 the device you develop for.
6190 \image qtcreator-gs-build-example-targets.png "Selecting targets"
6192 \note You can add targets later in the \gui Projects mode.
6194 \o To test the application in Qt Simulator, click the \gui {Target
6195 Selector} and select \gui {Qt Simulator}.
6197 \image {qtcreator-gs-build-example-select-qs.png} "Selecting Qt Simulator as target"
6200 \inlineimage{qtcreator-run.png}
6201 to build the application and run it in Qt Simulator.
6203 \o To see the compilation progress, press \key{Alt+4} to open the
6204 \gui {Compile Output} pane.
6206 The \gui Build progress bar on the toolbar turns green when the project
6207 is successfully built. The application opens in Qt Simulator.
6209 \image {qt-simulator.png} "Qt Simulator"
6211 \o Change the settings in the
6212 \gui View pane. For example, rotate the device by clicking the
6213 \gui {Orientation} buttons or choose from the various Symbian and Maemo
6214 configurations in the \gui {Device} field. You can also simulate various
6215 mobile functions and create your own scripts.
6217 \o To test the application on a Symbian device, install Qt libraries
6218 and a debugging agent on the device. For more information,
6219 see \l{Connecting Symbian Devices}.
6221 \o Click the \gui {Target Selector} and select \gui {Symbian Device}.
6223 \o Click \gui Run to build the application and run it on the Symbian device.
6231 \contentspage index.html
6232 \previouspage creator-mobile-example.html
6233 \page creator-qml-application.html
6234 \nextpage creator-project-managing.html
6236 \title Creating a Qt Quick Application
6238 \note To complete this tutorial, you must have Qt 4.7 or later installed.
6240 This tutorial uses basic elements and illustrates basic concepts of
6241 \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}.
6243 This tutorial describes how to use the Qt Creator to implement the
6244 \l{http://doc.qt.nokia.com/4.7/declarative-animation-states.html}
6245 {states and transitions example application}. The example application displays a
6246 Qt logo that moves between three rectangles on the page when you click them.
6248 \image qmldesigner-tutorial.png "States and transitions example"
6250 \section1 Creating the Project
6254 \o Select \gui{File > New File or Project > Qt Quick Project > Qt Quick UI >
6257 \o Follow the instructions of the wizard to create a project called Transitions.
6259 \o Press \key {Ctrl+R} to run the application in the QML Viewer.
6263 Qt Creator generates a default QML file that you can modify to create the main view
6266 \image qmldesigner-tutorial-project.png "Transitions project in Edit mode"
6268 \section1 Creating the Main View
6270 The main view of the application displays a Qt logo in the top left corner of the
6271 screen and two empty rectangles.
6273 To use the states.png image in your application, you must copy it to the project
6274 directory (same subdirectory as the QML file) from the examples directory in the
6275 Qt installation directory. For example:
6276 \c {C:\QtSDK\Examples\4.7\declarative\animation\states}. The image appears
6277 in the \gui Resources pane. You can also use any other image or a QML element, instead.
6281 \o In the \gui Projects view, double-click the main .qml file (Transitions.qml)
6282 to open it in the code editor.
6284 \o Click \gui Design to open the file in \QMLD.
6286 \image qmldesigner-tutorial-desing-mode.png "Transitions project in Design Mode"
6288 \o In the \gui Navigator pane, select \gui Text and press \key Delete to delete it.
6290 \o Select \gui Rectangle to edit its properties.
6292 \image qmldesigner-tutorial-page.png "Page properties"
6296 \o In the \gui Id field, enter \e page, to be able to reference the rectangle
6299 \o In the \gui Colors tab, \gui Rectangle field, set the color to #343434.
6303 \o In the \gui Library view, \gui Resources tab, select states.png and
6304 drag and drop it to the canvas.
6306 \image qmldesigner-tutorial-user-icon.png "Image properties"
6310 \o In the \gui Id field, enter \e icon.
6312 \o In the \gui Position field, set \gui X to 10 and \gui Y to 20.
6318 \o In the \gui Library view, \gui Items tab, select \gui Rectangle,
6319 drag and drop it to the canvas, and edit its properties.
6321 \image qmldesigner-tutorial-topleftrect.png "Rectangle properties"
6325 \o In the \gui Id field, enter \e topLeftRect.
6327 \o In the \gui Size field, set \gui W and \gui H to 64, for the rectangle size
6328 to match the image size.
6330 \o In the \gui Colors tab, \gui Rectangle field, click the
6331 \inlineimage qmldesigner-transparent-button.png
6332 button to make the rectangle transparent.
6334 \o In the \gui Border field, set the border color to #808080.
6336 \o In the \gui Rectangle tab, \gui Border field, set the border width to
6339 \note If the \gui Border field does not appear after you set the border
6340 color, try setting the border color to solid by clicking the
6341 \inlineimage qmldesigner-solid-color-button.png
6344 \o In the \gui Radius field, select 6 to create rounded corners for the
6347 \o Click \gui {Layout}, and then click the top and left anchor buttons
6348 to anchor the rectangle to the top left corner of the page.
6350 \image qmldesigner-tutorial-topleftrect-layout.png "Layout tab"
6352 \o In the \gui Margin field, select 20 for the top anchor and 10 for
6357 \o In the \gui Navigator pane, drag and drop the \gui {Mouse Area} element from
6358 \e page to \e topLeftRect to make it apply only to the rectangle and not to the whole
6361 \o Edit \gui {Mouse Area} properties:
6365 \o Click \gui {Layout}, and then click the
6366 \inlineimage qmldesigner-anchor-fill-screen.png
6367 button to anchor the mouse area to the rectangle.
6369 \o In the code editor, edit the pointer to the clicked expression in the mouse
6370 area element, as illustrated by the following code snippet:
6374 anchors.fill: parent
6375 onClicked: page.state = ''
6379 The expression sets the state to the base state and returns the image to
6380 its initial position.
6384 \o In the \gui Navigator pane, copy topLeftRect (by pressing \key {Ctrl+C}) and
6385 paste it to the canvas twice
6386 (by pressing \key {Ctrl+V}). Qt Creator renames the new instances of the element
6387 topLeftRect1 and topLeftRect2.
6389 \o Select topLeftRect1 and edit its properties:
6393 \o In the \gui Id field, enter \e middleRightRect.
6395 \o In \gui {Layout}, select the vertical center anchor button and
6396 then the right anchor button to
6397 anchor the rectangle to the middle right margin of the screen.
6399 \o In the \gui Margin field, select 10 for the right anchor and 0 for
6400 the vertical center anchor.
6402 \o In the code editor,add a pointer to a clicked expression to the
6403 mouse area element. The following expression sets the state to \e State1:
6405 \c {onClicked: page.state = 'State1'}
6407 You will create State1 later.
6411 \o Select topLeftRect2 and edit its properties:
6415 \o In the \gui Id field, enter \e bottomLeftRect.
6417 \o In \gui {Layout}, select the bottom and left anchor buttons to
6418 anchor the rectangle to the bottom left margin of the screen.
6420 \o In the \gui Margin field, select 20 for the bottom anchor and 10 for
6423 \o In the code editor, add a pointer to a clicked expression to the
6424 mouse area element. The following expression sets the state to \e State2:
6426 \c {onClicked: page.state = 'State2'}
6428 You will create State2 later.
6432 \o Press \key {Ctrl+S} to save the changes.
6434 \o Press \key {Ctrl+R} to run the application in the QML Viewer.
6438 \image qmldesigner-tutorial.png "States and transitions example"
6440 You should see the Qt logo in the top left rectangle, and two additional
6441 rectangles in the center right and bottom left of the screen.
6443 You can now create additional states to add views to the application.
6445 \section1 Adding Views
6447 In the .qml file, you already created pointers to two additional states:
6448 State1 and State2. To create the states:
6452 \o Click the empty slot in the \gui States pane to create State1.
6454 \o Click the empty slot in the \gui States pane to create State2.
6456 \o In the code editor, bind the position of the Qt logo to the rectangle
6457 to make sure that the logo is displayed within the rectangle when the view
6458 is scaled on different sizes of screens. Set expressions for the x and y
6459 properties, as illustrated by the following code snippet:
6461 \snippet snippets/qml/states-properties.qml states
6463 \image qmldesigner-tutorial-state1.png "States"
6465 \note When you set the expressions, drag and drop is disabled for
6468 \o Press \key {Ctrl+R} to run the application in the QML Viewer.
6472 Click the rectangles to move the Qt logo from one rectangle to another.
6474 \section1 Adding Animation to the View
6476 Add transitions to define how the properties change when the Qt logo moves
6477 between states. The transitions apply animations to the Qt logo. For example,
6478 the Qt logo bounces back when it moves to the middleRightRect and eases into
6479 bottomLeftRect. Add the transitions in the code editor.
6483 \o In the code editor, add the following code to specify that when moving to
6484 State1, the x and y coordinates of the Qt logo change linearly over a duration
6487 \snippet snippets/qml/list-of-transitions.qml first transition
6489 \o You can use the Qt Quick toolbar for animation to change the easing curve
6490 type from linear to OutBounce:
6494 \o Click \gui NumberAnimation in the code editor to display the
6495 \inlineimage qml-toolbar-indicator.png
6496 icon, and then click the icon to open the toolbar:
6498 \image qmldesigner-tutorial-quick-toolbar.png "Qt Quick toolbar for animation"
6500 \o In the \gui Easing field, select \gui Bounce.
6502 \o In the \gui Subtype field, select \gui Out.
6506 \o Add the following code to specify that when moving to State2, the x and y
6507 coordinates of the Qt logo change over a duration of 2 seconds,
6508 and an InOutQuad easing function is used:
6510 \snippet snippets/qml/list-of-transitions.qml second transition
6512 \o Add the following code to specify that for any other state changes, the x
6513 and y coordinates of the Qt logo change linearly over a duration of 200
6516 \snippet snippets/qml/list-of-transitions.qml default transition
6518 \o Press \key {Ctrl+R} to run the application in the QML Viewer.
6522 Click the rectangles to view the animated transitions.
6524 \section1 Deploying the Application to Mobile Devices
6526 To deploy the application to mobile devices, use the \gui {Qt Quick Application} wizard
6527 to convert it into a Qt Quick application. For more information, see
6528 \l{Importing QML Applications}.
6534 \contentspage index.html
6535 \previouspage creator-build-example-application.html
6536 \page creator-writing-program.html
6537 \nextpage creator-mobile-example.html
6539 \title Creating a Qt Widget Based Application
6541 This tutorial describes how to use Qt Creator
6542 to create a small Qt application, Text Finder. It is a simplified version of the
6543 QtUiTools \l{http://doc.qt.nokia.com/4.7/uitools-textfinder.html}{Text Finder}
6545 The application user interface is constructed from Qt widgets by using \QD.
6546 The application logic is written in C++ by using the code editor.
6548 \image qtcreator-textfinder-screenshot.png
6550 \section1 Creating the Text Finder Project
6552 \note Create the project with two instances of Qt Creator open and the \gui{Help} mode
6553 active in one of them so that you can follow
6554 these instructions while you work.
6558 \o Select \gui{File > New File or Project > Qt Widget Project > Qt Gui
6559 Application > Choose}.
6561 \image qtcreator-new-qt-gui-application.png "New File or Project dialog"
6563 The \gui{Introduction and Project Location} dialog opens.
6565 \image qtcreator-intro-and-location-qt-gui.png "Introduction and Project Location dialog"
6567 \o In the \gui{Name} field, type \bold {TextFinder}.
6570 \o In the \gui {Create in} field, enter the path for the project files. For example,
6571 \c {C:\Qt\examples}, and then click \gui{Next}.
6573 The \gui {Target Setup} dialog opens.
6575 \image qtcreator-new-project-qt-versions-qt-gui.png "Target Setup dialog"
6577 \o Select the Qt versions to use as build targets for your project, and click
6580 \note If you have only one Qt version installed, this dialog is skipped.
6582 The \gui{Class Information} dialog opens.
6584 \image qtcreator-class-info-qt-gui.png "Class Information dialog"
6586 \o In the \gui{Class name} field, type \bold {TextFinder} as the class name.
6588 \o In the \gui{Base class} list, select \bold {QWidget} as the base class type.
6590 \note The \gui{Header file}, \gui{Source file} and
6591 \gui{Form file} fields are automatically updated to match the name of the
6594 \o Click \gui{Next}.
6596 The \gui{Project Management} dialog opens.
6598 \image qtcreator-new-project-summary-qt-gui.png "Project Management dialog"
6600 \o Review the project settings, and click \gui{Finish} to create the project.
6607 The TextFinder project now contains the following files:
6617 \image qtcreator-textfinder-contents.png "TextFinder project contents"
6619 The .h and .cpp files come with the necessary boiler plate code.
6620 The .pro file is complete.
6622 \section1 Filling in the Missing Pieces
6624 Begin by designing the user interface and then move on to filling
6625 in the missing code. Finally, add the find functionality.
6627 \section2 Designing the User Interface
6629 \image qtcreator-textfinder-ui.png "Text Finder UI"
6633 \o In the \gui{Editor} mode, double-click the textfinder.ui file in the \gui{Projects}
6634 view to launch the integrated \QD.
6636 \o Drag and drop the following widgets to the form:
6639 \o \gui{Label} (QLabel)
6640 \o \gui{Line Edit} (QLineEdit)
6641 \o \gui{Push Button} (QPushButton)
6645 \image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI"
6647 \note To easily locate the widgets, use the search box at the top of the
6648 \gui Sidebar. For example, to find the \gui Label widget, start typing
6649 the word \bold label.
6651 \image qtcreator-texfinder-filter.png "Filter field"
6653 \o Double-click the \gui{Label} widget and enter the text \bold{Keyword}.
6655 \o Double-click the \gui{Push Button} widget and enter the text \bold{Find}.
6657 \o In the \gui Properties pane, change the \gui objectName to \bold findButton.
6659 \image qtcreator-textfinder-objectname.png "Changing object names"
6661 \o Press \key {Ctrl+A} to select the widgets and click \gui{Lay out Horizontally}
6662 (or press \gui{Ctrl+H}) to apply a horizontal layout
6665 \image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout"
6667 \o Drag and drop a \gui{Text Edit} widget (QTextEdit)
6670 \o Select the screen area and click \gui{Lay out Vertically} (or press \gui{Ctrl+L})
6671 to apply a vertical layout (QVBoxLayout).
6673 \image qtcreator-textfinder-ui.png "Text Finder UI"
6675 Applying the horizontal and vertical layouts ensures that the application UI scales to different
6678 \o To call a find function when users press the \gui Find button, you use the Qt signals
6679 and slots mechanism. A signal is emitted when a particular event occurs and a slot is
6680 a function that is called in response to a particular signal. Qt widgets have predefined
6681 signals and slots that you can use directly from \QD. To add a slot for the find function:
6685 \o Right-click the \gui Find button to open a context-menu.
6686 \o Select \gui {Go to Slot > clicked()}, and then select \gui OK.
6688 A private slot, \c{on_findButton_clicked()}, is added to the header file,
6689 textfinder.h and a private function, \c{TextFinder::on_findButton_clicked()},
6690 is added to the source file, textfinder.cpp.
6694 \o Press \gui{Ctrl+S} to save your changes.
6698 For more information about designing forms with \QD, see the
6699 \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
6701 \section2 Completing the Header File
6703 The textfinder.h file already has the necessary #includes, a
6704 constructor, a destructor, and the \c{Ui} object. You need to add a private
6705 function, \c{loadTextFile()}, to read and display the
6706 contents of the input text file in the
6711 \o In the \gui{Projects} pane in the \gui {Edit view}, double-click the \c{textfinder.h} file
6712 to open it for editing.
6714 \o Add a private function
6715 to the \c{private} section, after the \c{Ui::TextFinder} pointer, as
6716 illustrated by the following code snippet:
6718 \snippet examples/textfinder/textfinder.h 0
6722 \section2 Completing the Source File
6724 Now that the header file is complete, move on to the source file,
6729 \o In the \gui{Projects} pane in the \gui Edit view, double-click the textfinder.cpp file
6730 to open it for editing.
6732 \o Add code to load a text file using
6733 QFile, read it with QTextStream, and
6734 then display it on \c{textEdit} with
6735 \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}.
6736 This is illustrated by the following code snippet:
6738 \snippet examples/textfinder/textfinder.cpp 0
6740 \o To use QFile and QTextStream, add the
6741 following #includes to textfinder.cpp:
6743 \snippet examples/textfinder/textfinder.cpp 1
6745 \o For the \c{on_findButton_clicked()} slot, add code to extract the search string and
6746 use the \l{http://doc.qt.nokia.com/4.7/qtextedit.html#find}{find()} function
6747 to look for the search string within the text file. This is illustrated by
6748 the following code snippet:
6750 \snippet examples/textfinder/textfinder.cpp 2
6752 \o Once both of these functions are complete, add a line to call \c{loadTextFile()} in
6753 the constructor, as illustrated by the following code snippet:
6755 \snippet examples/textfinder/textfinder.cpp 3
6759 The \c{on_findButton_clicked()} slot is called automatically in
6760 the uic generated ui_textfinder.h file by this line of code:
6763 QMetaObject::connectSlotsByName(TextFinder);
6766 \section2 Creating a Resource File
6768 You need a resource file (.qrc) within which you embed the input
6769 text file. The input file can be any .txt file with a paragraph of text.
6770 Create a text file called input.txt and store it in the textfinder
6773 To add a resource file:
6775 \o Select \gui{File > New File or Project > Qt > Qt Resource File > Choose}.
6776 \image qtcreator-add-resource-wizard.png "New File or Project dialog"
6778 The \gui {Choose the Location} dialog opens.
6780 \image qtcreator-add-resource-wizard2.png "Choose the Location dialog"
6782 \o In the \gui{Name} field, enter \bold{textfinder}.
6783 \o In the \gui{Path} field, enter \c{C:\Qt\examples\TextFinder},
6784 and click \gui{Next}.
6786 The \gui{Project Management} dialog opens.
6788 \image qtcreator-add-resource-wizard3.png "Project Management dialog"
6791 \o In the \gui{Add to project} field, select \bold{TextFinder.pro}
6792 and click \gui{Finish} to open the file in the code editor.
6794 \o Select \gui{Add > Add Prefix}.
6795 \o In the \gui{Prefix} field, replace the default prefix with a slash (/).
6796 \o Select \gui{Add > Add Files}, to locate and add input.txt.
6798 \image qtcreator-add-resource.png "Editing resource files"
6802 \section1 Compiling and Running Your Program
6804 Now that you have all the necessary files, click the \inlineimage qtcreator-run.png
6805 button to compile and run your program.
6811 \contentspage index.html
6812 \previouspage creator-project-generic.html
6813 \page creator-version-control.html
6814 \nextpage adding-plugins.html
6816 \title Using Version Control Systems
6818 Version control systems supported by Qt Creator are:
6821 \i Version Control System
6826 \i \l{http://bazaar.canonical.com/}
6827 \i Qt Creator 2.2 and later
6830 \i \l{http://www.cvshome.org}
6834 \i \l{http://git-scm.com/}
6838 \i \l{http://mercurial.selenic.com/}
6839 \i Qt Creator 2.0 and later
6842 \i \l{http://www.perforce.com}
6843 \i Server version 2006.1 and later
6846 \i \l{http://subversion.apache.org/}
6851 \section1 Setting Up Version Control Systems
6853 Qt Creator uses the version control system's command line clients to access
6854 your repositories. To allow access, make sure that the command line clients
6855 can be located using the \c{PATH} environment variable or specify the path to
6856 the command line client executables in \gui{Tools} > \gui{Options...} >
6857 \gui {Version Control}.
6859 After you set up the version control system, use the command line to check
6860 that everything works (for example, use the status command). If no issues arise,
6861 you should be ready to use the system also from Qt Creator.
6863 \section2 Using msysGit on Windows
6865 If you configure Git for use with \c {git bash}, only, and use SSH
6866 authorization, Git looks for the SSH keys in the directory where the
6867 \c HOME environment points to. The variable is always set by \c {git bash}.
6869 However, the variable is typically not set in a Windows command prompt.
6870 When you run Git from a Windows command prompt, it looks for the SSH keys in its
6871 installation directory, and therefore, the authorization fails.
6873 You can set the \c HOME environment variable from Qt Creator. Select \gui {Tools >
6874 Options... > Version Control > Git}. Select the \gui {Environment Variables}
6875 and the \gui {Set "HOME" environment variable} check boxes. \c HOME is set to
6876 \c %HOMEDRIVE%%HOMEPATH% when the Git executable is run and authorization works
6877 as it would with \c {git bash}.
6879 \section1 Setting Up Common Options
6881 Select \gui{Tools} > \gui{Options...} > \gui{Version Control} > \gui{Common}
6882 to specify settings for submit messages:
6884 \o \gui{Submit message check script} is a script or program that
6885 can be used to perform checks on the submit message before
6886 submitting. The submit message is passed in as the script's first
6887 parameter. If there is an error, the script should output a
6888 message on standard error and return a non-zero exit code.
6890 \o \gui{User/alias configuration file} takes a file in mailmap format
6891 that lists user names and aliases. For example:
6894 Jon Doe <Jon.Doe@company.com>
6895 Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
6898 \note The second line above specifies the alias \e{hm} and the
6899 corresponding email address for \e{Hans Mustermann}. If the
6900 user/alias configuration file is present, the submit editor
6901 displays a context menu with \gui{Insert name...} that pops up a
6902 dialog letting the user select a name.
6904 \o \gui{User fields configuration file} is a simple text file
6905 consisting of lines specifying submit message fields that take
6906 user names, for example:
6913 The fields above appear below the submit message. They provide completion
6914 for the aliases/public user names specified in the
6915 \e{User/alias configuration file} as well as a button that opens the
6916 aforementioned user name dialog.
6918 \o \gui{SSH prompt command} specifies an ssh-askpass command that you
6919 can use (on Linux) to prompt the user for a password when using SSH.
6920 For example, \c ssh-askpass or \c x11-ssh-askpass, depending on the
6921 ssh-askpass implementation that you use.
6925 \section1 Creating VCS Repositories for New Projects
6927 Qt Creator allows you to create repositories for version
6928 control systems that support local repository creation, such as
6929 Git, Mercurial, or Bazaar.
6930 When creating a new project by selecting \gui File >
6931 \gui{New File or Project...}, you can choose a version
6932 control system in the final wizard page.
6934 You can also select \gui Tools and then select \gui {Create Repository...}
6935 in the submenu for the version control system.
6937 To import a project that is under version control, choose \gui {File >
6938 New File or Project... > Project from Version Control} and select the
6939 version control system that you use. Follow the instructions of the
6940 wizard to import the project.
6942 \section1 Using Version Control Systems
6944 The \gui{Tools} menu contains a submenu for each supported version
6947 The \gui{Version Control} output pane displays the commands
6948 that are executed, a timestamp, and the relevant output.
6949 Select \gui {Window > Output Panes > Version Control} to open
6953 \image qtcreator-vcs-pane.png
6956 \section2 Adding Files
6958 When you create a new file or a new project, the wizard displays a page
6959 asking whether the files should be added to a version control system.
6960 This happens when the parent directory or the project is already
6961 under version control and the system supports the concept of adding files,
6962 for example, Perforce and Subversion. Alternatively, you can
6963 add files later by using the version control tool menus.
6965 With Git, there is no concept of adding files. Instead, all modified
6966 files must be staged for a commit.
6969 \section2 Viewing Diff Output
6971 All version control systems provide menu options to \e{diff} the current
6972 file or project: to compare it with the latest version stored in the
6973 repository and to display the differences. In Qt Creator, a diff is
6974 displayed in a read-only editor. If the file is accessible, you can
6975 double-click on a selected diff chunk and Qt Creator opens an editor
6976 displaying the file, scrolled to the line in question.
6978 \image qtcreator-vcs-diff.png
6981 \section2 Viewing Versioning History and Change Details
6983 Display the versioning history of a file by selecting \gui{Log}
6984 or \gui{Filelog}. Typically, the log output contains the date, the commit
6985 message, and a change or revision identifier. Click on the identifier to
6986 display a description of the change including the diff.
6987 Right-clicking on an identifier brings up a context menu that lets you
6988 show annotation views of previous versions (see \l{Annotating Files}).
6990 \image qtcreator-vcs-log.png
6993 \section2 Annotating Files
6995 Annotation views are obtained by selecting \gui{Annotate} or \gui{Blame}.
6996 Selecting \gui{Annotate} or \gui{Blame} displays the lines of the file
6997 prepended by the change identifier they originate from. Clicking on the
6998 change identifier shows a detailed description of the change.
7000 To show the annotation of a previous version, right-click on the
7001 version identifier at the beginning of a line and choose one of the
7002 revisions shown at the bottom of the context menu. This allows you to
7003 navigate through the history of the file and obtain previous versions of
7004 it. It also works for Git and Mercurial using SHA's.
7006 The same context menu is available when right-clicking on a version
7007 identifier in the file log view of a single file.
7010 \section2 Committing Changes
7012 Once you have finished making changes, submit them to the version control
7013 system by choosing \gui{Commit} or \gui{Submit}. Qt Creator displays a
7014 commit page containing a text editor where you can enter your commit
7015 message and a checkable list of modified files to be included.
7017 \image qtcreator-vcs-commit.png
7019 When you have finished filling out the commit page information, click on
7020 \gui{Commit} to start committing.
7022 The \gui{Diff Selected Files} button brings up a diff view of the
7023 files selected in the file list. Since the commit page is just another
7024 editor, you can go back to it by closing the diff view. You can also check
7025 a diff view from the editor combo box showing the \gui{Opened files}.
7027 \section2 Reverting Changes
7029 All supported version control system support reverting your project to
7030 known states. This functionality is generally called \e reverting.
7032 The changes discarded depend on the version control system.
7034 A version control system can replace the \gui Revert menu option with other
7037 \section3 Reverting Changes Using Git
7039 The Git version control system has an index that is used to stage
7040 changes. The index is commited on the next commit. Git allows you to revert
7041 back to the state of the last commit as well as to the state staged in the
7046 \o \gui{Undo Unstaged Changes} reverts all changes and resets the working
7047 directory to the state of the index.
7049 \o \gui{Undo Uncommitted Changes} reverts all changes, discarding the index.
7050 This returns your working copy to the state it was in right after the last commit.
7054 \section2 Viewing Status
7056 You can select \gui{Status...} to view the status of the project or
7059 \section2 Updating the Working Tree
7061 You can select \gui Update to update your working tree with the latest
7062 changes from the branch. Some version control systems allow you to choose
7063 between updating the current project and updating all projects.
7065 With Git, you stash your changes and then pull the changes from the
7068 \section2 Deleting Files
7070 You can select \gui Delete to delete obsolete files from the repository.
7072 With Git, you delete the files from the working tree and then stage the
7073 deleted files for a commit.
7075 \section2 Using Additional Bazaar Functions
7077 Bazaar is a free version control system sponsored by Canonical.
7079 The \gui Bazaar submenu contains the following additional items:
7087 \i Turn the branch into a mirror of another branch.
7090 \i Update a mirror of the branch.
7094 \section2 Using Additional CVS Functions
7096 CVS is an open source version control system.
7098 The \gui CVS submenu contains the following additional items:
7106 \i Open a file for editing.
7109 \i Push changes to the remote repository.
7112 \i Discard the changes that you made in a file.
7116 \section2 Using Additional Git Functions
7118 Git is a fast decentralized version control system. Git is available
7119 for Windows, Linux and Mac.
7121 The \gui Git submenu contains the following additional items:
7128 \i \gui {Patch > Apply from Editor/Apply from File...}
7129 \i Patches are rewriting instructions that can be applied to a set of files.
7130 You can either apply a patch file that is open in Qt Creator or select
7131 the patch file to apply from the file system.
7134 \i Pull changes from the remote repository. If there are locally
7135 modified files, you are prompted to stash those changes. Select \gui{Tools >
7136 Options... > Version Control > Git} and select the \gui {Pull with rebase}
7137 check box to perform a rebase operation while pulling.
7140 \i \gui{Clean.../Clean Project...}
7141 \i All files that are not under version control (with the exception
7142 of patches and project files) are displayed in the \gui {Clean Repository}
7143 dialog. Select the files to delete and click \gui Delete. This allows you to
7144 clean a build completely.
7146 \i \gui{Launch gitk}
7147 \i Start the commit viewer for Git, gitk.
7149 \i \gui{Branches...}
7150 \i Manage local and remote branches.
7153 \i Manage remote repositories available in Git.
7155 \i \gui {Stage File for Commit}
7156 \i Mark new or modified files for committing to the repository.
7157 To undo this function, select \gui {Unstage File from Commit}.
7159 \i \gui{Show Commit...}
7160 \i Select a commit to view. Enter the SHA of the commit
7161 in the \gui Change field.
7164 \i Store local changes temporarily.
7166 \i \gui{Amend Last Commit...}
7167 \i Revert the last commit.
7171 \section3 Working with Branches
7173 To work with Git branches, select \gui{Branches...}. The checked out branch
7174 is shown in bold and underlined in the list of branches. Double-click branch
7177 \image qtcreator-vcs-gitbranch.png "Branches dialog"
7179 The following operations are supported:
7187 \i Create new tracking and non-tracking branches.
7190 \i Check out the selected branch and make it current.
7193 \i Remove a local branch. You cannot delete remote branches.
7196 \i Show the differences between the selected and the current
7200 \i Show the changes in a branch.
7203 \i Refresh the list of branches.
7206 \section3 Working with Remote Repositories
7208 To manage remote repositories available in Git, select \gui{Remotes...}.
7209 Double-click the names and URLs of the remote repositories to edit them.
7211 The following operations are supported:
7219 \i Add a new remote repository.
7222 \i Fetch all the branches and change information from a remote
7226 \i Remove a remote repository.
7229 \i Refresh the list of remote repositories.
7233 \section3 Using Stashes
7235 With Git, you can put your current set of changes onto a virtual shelf called a \e stash.
7236 Stashes are useful, for example, to put aside a set of changes to work on higher
7237 priority tasks or to pull in new chages from another repository.
7239 Qt Creator exposes this functionality in the \gui{Tools > Git > Stash} menu.
7247 \i Display a dialog that shows all known stashes with options to restore,
7248 display or delete them.
7251 \i Stash all local changes. The working copy is then reset to
7252 the state it had right after the last commit.
7254 \i \gui{Stash Snapshot...}
7255 \i Save a snapshot of your current work under a name for later reference. The
7256 working copy is unchanged.
7258 For example, if you want to try something and find out later that it does not work,
7259 you can discard it and return to the state of the snapshot.
7262 \i Remove a single stashed state from the stash list and apply it on
7263 top of the current working tree state.
7266 \section2 Using Additional Mercurial Functionality
7268 Mercurial is a free, distributed source control management tool.
7270 The \gui Mercurial submenu contains the following additional items:
7278 \i Apply changes from a patch file.
7281 \i Monitor the status of a remote repository by listing
7282 the changes that will be pulled.
7285 \i Monitor the status of a remote repository by listing
7286 the changes that will be pushed.
7289 \i Pull changes from the remote repository.
7292 \i Push changes to the remote repository.
7295 \section2 Using Additional Perforce Functions
7297 Perforce is a fast software configuration management system developed by
7300 When you start Qt Creator, it looks for the executable specified
7301 in the \gui{P4 command} field in \gui{Tools > Options... > Version
7302 Control > Perforce}. If the file is not found, the following error
7303 message is displayed in the \gui {Version Control} output pane:
7304 \gui {Perforce: Unable to determine the repository: "p4.exe"
7305 terminated with exit code 1}. If you use Perforce, check that the
7306 path to the executable is specified correctly in the \gui{P4 command}
7309 If you do not use Perforce, you can disable the Perforce plugin to
7310 get rid of the error message. Choose \gui {Help > About Plugins} and
7311 deselect the \gui Load check box for the \gui Perforce plugin in the
7312 \gui {Version Control} group.
7314 The \gui Perforce submenu contains the following additional items:
7321 \i \gui{Describe...}
7322 \i View information about changelists and the files in them.
7325 \i Open a file for editing.
7328 \i List files that are open for editing.
7330 \i \gui{Pending Changes...}
7331 \i Group files for commit.
7334 \section2 Using Additional Subversion Functions
7336 Subversion is an open source version control system.
7338 The \gui Subversion submenu contains the following additional items:
7345 \i \gui{Describe...}
7346 \i Display commit log messages for a revision.
7353 \contentspage index.html
7354 \previouspage qt-quick-toolbars.html
7355 \page creator-editor-locator.html
7356 \nextpage creator-editor-codepasting.html
7358 \title Searching With the Locator
7360 The locator provides one of the easiest ways in Qt Creator to browse
7361 through projects, files, classes, methods, documentation and file systems.
7362 You can find the locator in the bottom left of the Qt Creator window.
7364 To activate the locator, press \key Ctrl+K (\key Cmd+K on Mac OS
7365 X) or select \gui Tools > \gui Locate....
7367 \image qtcreator-locator.png
7369 To edit the currently open project's main.cpp file using the locator:
7371 \o Activate the locator by pressing \key Ctrl+K.
7372 \o Enter \tt{main.cpp}.
7374 \image qtcreator-locator-open.png
7375 \o Press \key Return.
7377 The main.cpp file opens in the editor.
7380 It is also possible to enter only a part of a search string.
7381 As you type, the locator shows the occurrences of that string regardless
7382 of where in the name of an component it appears.
7384 To narrow down the search results, you can use the following wildcard
7387 \o To match any number of any or no characters, enter \bold{*}.
7388 \o To match a single instance of any character, enter \bold{?}.
7391 \section1 Using the Locator Filters
7393 The locator allows you to browse not only files, but any items
7394 defined by \bold{locator filters}. By default, the locator contains
7397 \o Locating any open document
7398 \o Locating files anywhere on your file system
7399 \o Locating iles belonging to your project, such as source, header resource,
7401 \o Locating class and method definitions in your project or anywhere
7404 \o Locating class and method definitions in the current document
7405 \o Locating a specific line in the document displayed in your editor
7406 \o Opening help topics, including Qt documentation
7407 \o Performing web searches
7408 \o Running text editing macros that you record and save. For more
7409 information, see \l{Using Text Editing Macros}
7412 To use a specific locator filter, type the assigned prefix followed by
7413 \key Space. The prefix is usually a single character.
7415 For example, to locate symbols matching
7418 \o Activate the locator.
7419 \o Enter \tt{\bold{: QDataStream}} (: (colon) followed by a
7420 \key Space and the symbol name (QDataStream)).
7422 The locator lists the results.
7424 \image qtcreator-navigate-popup.png
7427 By default the following filters are enabled and you do not need to use
7428 their prefixes explicitly:
7431 \o Going to a line in the current file (l).
7432 \o Going to an open file (o).
7433 \o Going to a file in any open project (a).
7436 \section2 Using the Default Locator Filters
7438 The following locator filters are available by default:
7446 \o Go to a line in the current file.
7447 \o \tt{\bold{l \e{Line number}}}
7448 \o \image qtcreator-locator-line.png
7450 \o Go to a symbol definition.
7451 \o \tt{\bold{: \e{Symbol name}}}
7452 \o \image qtcreator-locator-symbols.png
7454 \o Go to a symbol definition in the current file.
7455 \o \tt{\bold{. \e{Symbol name}}}
7456 \o \image qtcreator-locator-method-list.png
7458 \o Go to a help topic.
7459 \o \tt{\bold{? \e{Help topic}}}
7460 \o \image qtcreator-locator-help.png
7462 \o Search for a term by using a web search engine.
7463 \o \tt{\bold{r \e{Search term}}}
7464 \o \image qtcreator-locator-web.png
7466 \o Go to an open file.
7467 \o \tt{\bold{o \e{File name}}}
7468 \o \image qtcreator-locator-opendocs.png
7470 \o Go to a file in the file system (browse the file system).
7471 \o \tt{\bold{f \e{File name}}}
7472 \o \image qtcreator-locator-filesystem.png
7474 \o Go to a file in any project currently open.
7475 \o \tt{\bold{a \e{File name}}}
7476 \o \image qtcreator-locator-files.png
7478 \o Go to a file in the current project.
7479 \o \tt{\bold{p \e{File name}}}
7480 \o \image qtcreator-locator-current-project.png
7482 \o Go to a class definition.
7483 \o \tt{\bold{c \e{Class name}}}
7484 \o \image qtcreator-locator-classes.png
7486 \o Go to a method definition.
7487 \o \tt{\bold{m \e{Method name}}}
7488 \o \image qtcreator-locator-methods.png
7490 \o Execute a text editing macro.
7491 \o \tt{\bold{rm \e{Macro name}}}
7492 \o \image qtcreator-locator-macros.png
7495 \section2 Creating Locator Filters
7497 To quickly access files not directly mentioned in your project, you can
7498 create your own locator filters. That way you can locate files in a
7499 directory structure you have defined.
7501 To create a locator filter:
7503 \o In the locator, click \inlineimage qtcreator-locator-magnify.png
7504 and select \gui Configure.... to open the \gui Locator options.
7506 \image qtcreator-locator-customize.png
7509 \o In the \gui{Filter Configuration} dialog:
7511 \o Name your filter.
7512 \o Select at least one directory. The locator searches directories
7514 \o Define the file pattern as a comma separated list. For example,
7515 to search all .h and .cpp files, enter \bold{*.h,*.cpp}
7516 \o Specify the prefix string.
7518 To show only results matching this filter, select
7519 \gui{Limit to prefix}.
7521 \image qtcreator-navigate-customfilter.png
7526 \section2 Adding Web Search Engines
7528 You can use the \gui {Web Search (\c r)} locator filter to perform
7529 web searches. URLs and search commands for Bing, Google, Yahoo! Search,
7530 cplusplus.com, and Wikipedia are configured by default.
7532 To find out the format of the search command to use for your favorite
7533 web search engine, perform a search in your browser and copy the resulting
7534 URL to the locator filter configuration. Replace the search term with the
7537 To add URLs and search commands to the list:
7541 \o Select \gui {Tools > Options > Locator > Web Search (prefix: r) >
7544 \o Select \gui Add to add a new entry to the list.
7546 \image qtcreator-add-online-doc.png "Filter Configuration dialog"
7548 \o Double-click the new entry to specify a URL and a search command.
7549 For example, http://www.google.com/search?q=%1.
7555 \section2 Configuring the Locator Cache
7557 The locator searches the files matching your file pattern in the
7558 directories you have selected and caches that information. The cache for
7559 all default filters is updated as you write your code. By default,
7560 Qt Creator updates the filters created by you once an hour.
7562 To update the cached information manually, click
7563 \inlineimage qtcreator-locator-magnify.png
7564 and select \gui Refresh.
7566 To set a new cache update time:
7568 \o Select \gui Tools > \gui Options... > \gui Locator.
7569 \o In \gui{Refresh interval}, define new time in minutes.
7576 \contentspage index.html
7577 \previouspage creator-developing-symbian.html
7578 \page creator-project-managing-sessions.html
7579 \nextpage creator-coding.html
7581 \title Managing Sessions
7583 When you exit Qt Creator, a snapshot of your current workspace is stored
7584 as a \e session. To restore the session automatically when you start Qt
7585 Creator, select \gui {File > Session Manager > Restore last session on
7588 A session is an arbitrary collection of:
7591 \o Open projects with their dependencies (including SUBDIRS projects)
7593 \o Breakpoints and expressions
7597 A session is personal, that is, not meant to be shared. It is not
7598 supposed to reflect the project structure. It contains personal data, such as
7599 bookmarks and breakpoints that are usually not of interest to other developers
7600 working on the same projects.
7602 For example, if you work on a project and need to switch to another project for a
7603 while, you can save your workspace as a session. This makes it easier
7604 to return to working on the first project later.
7606 To create a new session or remove existing sessions, select \gui File >
7607 \gui{Session Manager}.
7609 \image qtcreator-session-manager.png
7611 To switch between sessions, choose
7612 \gui {File > Session Manager}. If you do not create or select a session,
7613 Qt Creator always uses the default session, which was created the
7614 last time you exited Qt Creator.
7616 When you launch Qt Creator, a list of existing sessions is displayed on the
7617 \gui{Welcome screen}.
7619 \image qtcreator-welcome-session.png
7625 \contentspage index.html
7626 \previouspage creator-build-dependencies.html
7627 \page creator-debugging.html
7628 \nextpage creator-debugging-example.html
7632 Qt Creator provides a debugger plugin that acts
7633 as an interface between the Qt Creator core and external native debuggers
7634 such as the GNU Symbolic Debugger (GDB), the Microsoft Console Debugger (CDB),
7635 and a QML/JavaScript debugger.
7637 The following sections describe debugging with Qt Creator:
7641 \o \l{Debugging the Example Application} uses an example application
7642 to illustrate how to debug Qt C++ applications in the \gui Debug
7645 \o \l{Launching the Debugger} describes the
7646 operating modes in which the debugger plugin runs, depending on
7647 where and how the process is started and run.
7649 \o \l{Interacting with the Debugger} describes the views and functions
7650 available in the \gui Debug mode.
7652 \o \l{Setting Up Debugger} summarizes the support for debugging C++
7653 code and requirements for installation. Typically, the interaction
7654 between Qt Creator and the native debugger is set up automatically
7655 and you do not need to do anything.
7657 \o \l{Using Debugging Helpers} describes how to get more detailed data
7660 \o \l{Debugging Qt Quick Projects} describes how to debug Qt Quick
7663 \o \l{Troubleshooting Debugger} lists some typical problems that you
7664 might encounter while debugging and solutions to them.
7671 \contentspage index.html
7672 \previouspage creator-debugging-example.html
7673 \page creator-debugger-operating-modes.html
7674 \nextpage creator-debug-mode.html
7676 \title Launching the Debugger
7678 To start a program under the control of the debugger, select \gui{Debug} >
7679 \gui{Start Debugging} > \gui{Start Debugging}, or press \key{F5}.
7680 Qt Creator checks whether the compiled program is up-to-date, and rebuilds
7681 it if necessary. The debugger then takes over and starts the program.
7683 \note Starting a program in the debugger can take a long
7684 time, typically in the range of several seconds to minutes if complex
7685 features (like QtWebKit) are used.
7687 The debugger is launched in the appropriate operating mode (plain, terminal,
7688 or on-device), based on the build and run settings for the active project.
7689 Select \gui Debug menu options to launch the debugger in other modes.
7691 \note Debugging QML and JavaScript is supported only in plain mode.
7693 \section1 Launching the Debugger in Different Modes
7695 The debugger plugin runs in different operating modes depending on where and
7696 how the process is started and run. Some of the modes are only available for
7697 a particular operating system or platform.
7699 You can launch the debugger in the following modes:
7703 \o \bold Plain to debug locally started applications, such as a
7704 Qt based GUI application.
7706 \o \bold Terminal to debug locally started processes that need a
7707 console, typically without a GUI.
7709 \o \bold Attach to debug local processes started outside Qt Creator.
7711 \o \bold Remote to debug a process running on a different machine.
7713 \o \bold Core to debug crashed processes on Unix.
7715 \o \bold Post-mortem to debug crashed processes on Windows.
7717 \o \bold On-device to debug processes running on a mobile device.
7721 \note Debugging QML and JavaScript is supported only in plain mode.
7723 \section2 Launching in Plain Mode
7725 To launch the debugger in the plain mode, click the \gui {Start Debugging}
7726 button for the active project, or choose
7727 \gui {Debug > Start Debugging > Start and Debug External Application...}
7728 and specify an executable.
7730 \section2 Launching in Terminal Mode
7732 To launch the debugger in the terminal mode, select \gui {Projects > Run Settings}
7733 and select the \gui {Run in terminal} check box. Then click the
7734 \gui {Start Debugging} button for the active project.
7736 \section2 Launching in Attach Mode
7738 To launch the debugger in the attach mode, select
7739 \gui {Debug > Start Debugging > Attach to Running External Application...},
7740 and then select a process by its name or process ID to attach to.
7742 You can load the source project in advance and set breakpoints in it before
7743 attaching to an already running process. For more information, see
7744 \l{Setting Breakpoints}.
7746 \section2 Launching in Remote Mode
7748 The remote mode allows you to debug processes that run on remote machines.
7752 In remote mode, the local GDB process talks to a GDB server
7753 process running on the remote machine that controls the process to be
7756 The GDB server process is started on the remote machines by passing a port
7757 number and the executable:
7760 gdbserver :1234 <executable>
7763 It then typically responds:
7765 Process bin/qtcreator created; pid = 5159
7766 Listening on port 1234
7769 On the local machine that runs Qt Creator:
7773 \o Select \gui {Debug > Start Debugging > Start and Attach to Remote
7776 \o In the \gui {Host and port} field, enter the name of the remote
7777 machine and the port number to use.
7779 \o Select \gui{OK} to start debugging.
7785 In remote mode, the local CDB process talks to a CDB process that
7786 runs on the remote machine. The process is started with special
7787 command line options that switch it into server mode. The remote CDB
7788 process must load the Qt Creator CDB extension library that is shipped with
7793 \o Install the \e{Debugging Tools for Windows} on the remote machine.
7794 The installation folder contains the CDB command line executable (cdb.exe).
7796 \o Copy the Qt Creator CDB extension library from the Qt installation
7797 directory to the a new folder on the remote machine
7798 (32 or 64 bit version depending on the version of the Debugging
7804 \o \c {\lib\qtcreatorcdbext32\qtcreatorcdbext.dll} (32 bit)
7806 \o \c {\lib\qtcreatorcdbext64\qtcreatorcdbext.dll} (64 bit)
7810 \o Set the _NT_DEBUGGER_EXTENSION_PATH environment variable to point
7813 \o To use TCP/IP as communication protocol, launch remote CDB as
7817 cdb.exe -server tcp:port=1234 <executable>
7820 \o On the local machine running Qt Creator, select
7821 \gui {Debug > Start Debugging > Attach to Remote CDB Session...}
7824 \o In the \gui Connection field enter the connection parameters.
7825 For example, for TCP/IP:
7831 If you chose some other protocol, specify one of the alternative
7835 tcp:server=Server,port=Port[,password=Password][,ipversion=6]
7836 tcp:clicon=Server,port=Port[,password=Password][,ipversion=6]
7837 npipe:server=Server,pipe=PipeName[,password=Password]
7838 com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
7839 spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
7840 ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
7841 ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
7844 \o Click \gui{OK} to start debugging.
7848 \section2 Launching in Core Mode
7850 The core mode it used to debug \e {core} files (crash dumps) that are
7851 generated from crashed processes if the system is set up to allow this.
7853 To enable the dumping of core files on a Unix system enter the following
7854 command in the shell from which the application will be launched:
7860 To launch the debugger in the core mode, select
7861 \gui{Debug > Start Debugging > Attach to Core...}.
7863 \section2 Launching in Post-Mortem Mode
7865 The post-mortem mode is available only on Windows, if you have installed
7866 the debugging tools for Windows.
7868 The Qt Creator installation program asks you whether you want to
7869 register Qt Creator as a post-mortem debugger. To change the setting, select
7870 \gui{Tools > Options... > Debugger > Common > Use Creator for post-mortem debugging}.
7872 You can launch the debugger in the post-mortem mode if an application crashes
7873 on Windows. Click the \gui {Debug in Qt Creator} button in the error message
7874 that is displayed by the Windows operating system.
7876 \section2 Launching in On-device Mode
7878 The on-device mode is a special mode available for run configurations
7879 targeting mobile devices. It debugs processes running on mobile
7880 devices using on-device debugging agents, such as CODA on Symbian and
7881 gdbserver on Linux-based devices.
7883 To launch the debugger in the on-device mode, open the project, select a
7884 run configuration that targets a mobile device, and click the
7885 \gui {Start Debugging} button.
7890 \contentspage index.html
7891 \previouspage creator-debug-mode.html
7892 \page creator-debugger-engines.html
7893 \nextpage creator-debugging-helpers.html
7895 \title Setting Up Debugger
7897 \note The information in this section applies only to debugging the C++
7900 Typically, the interaction between Qt Creator and the native debugger is set
7901 up automatically and you do not need to do anything. However, you might have an
7902 unsupported GDB version installed, your Linux environment might not have GDB
7903 installed at all, or you might want to use the debugging tools for Windows.
7905 \note To use the debugging tools for Windows, you must install them and add the
7906 Symbol Server provided by Microsoft to the symbol search path of the debugger.
7907 For more information, see \l{Setting the Symbol Server in Windows}.
7909 This section explains the
7910 options you have for debugging C++ code and provides installation notes for the
7911 supported native debuggers.
7913 \section1 Supported Native Debugger Versions
7915 The debugger plugin supports different builds of the GDB debugger, both
7916 with and without the ability to use Python scripting. The Python enabled
7917 versions are preferred, but they are not available on Mac and on older
7919 On Windows, Symbian, Maemo, and MeeGo Harmattan, only the Python version is
7922 The non-Python versions use the compiled version of the debugging helpers,
7923 that you must enable separately. For more information, see
7924 \l{Debugging Helpers Based on C++}.
7926 The Python version uses a script version of the debugging helpers
7927 that does not need any special setup.
7929 The CDB native debugger has similar funtionality to the non-Python GDB debugger
7930 engine. Specifically, it also uses compiled C++ code for the debugging
7933 The following table summarizes the support for debugging C++ code:
7947 \o Plain, Terminal, Attach, Remote, Core
7953 \o Plain, Terminal, Attach, Remote, Core
7959 \o Plain, Terminal, Attach, Core
7965 \o Plain, Terminal, Attach, Remote, Core
7968 \o Microsoft Visual C++ Compiler
7969 \o Debugging Tools for Windows/CDB
7971 \o Plain, Terminal, Attach, Post-Mortem
7992 For more information on the debugger modes, see \l{Launching the Debugger in Different Modes}.
7996 \section2 GDB Adapter Modes
8000 The GDB native debugger used internally by the debugger plugin runs in
8001 different adapter modes to cope with the variety
8002 of supported platforms and environments. All GDB adapters inherit from
8007 \o PlainGdbAdapter debugs locally started GUI processes.
8008 It is physically split into parts that are relevant only when Python is
8009 available, parts relevant only when Python is not available, and mixed code.
8011 \o TermGdbAdapter debugs locally started processes that need a
8014 \o AttachGdbAdapter debugs local processes started outside Qt Creator.
8016 \o CoreGdbAdapter debugs core files generated from crashes.
8018 \o RemoteGdbAdapter interacts with the gdbserver running on Linux.
8020 \o CodaGdbAdapter interacts with Symbian devices. The GDB protocol and
8021 the GDB serial protocol are used between GDB and the adapter. The
8022 target communication framework (TCF) protocol is used between the
8023 adapter and the CODA debugging agent running on the device.
8029 \section1 Installing Native Debuggers
8031 There are various reasons why the debugger plugin may fail to automatically
8032 pick up a suitable native debugger. The native debugger might be missing
8033 (which is usually the case for the CDB debugger on Windows which always
8034 needs to be installed manually by the user) or the installed version is not
8036 Check the table below for the supported versions and other important
8037 information about installing native debuggers.
8045 \o On Linux and Windows, use the Python-enabled GDB versions that
8046 are installed when you install Qt Creator and Qt SDK. On Mac OS X,
8047 use the GDB provided with Xcode.
8048 For a custom target, you can build your own Python-enabled GDB.
8049 Follow the instructions on
8050 \l{http://developer.qt.nokia.com/wiki/QtCreatorBuildGdb}{Building GDB}.
8051 You must use at least Python version 2.5, but we recommend that you
8055 \o Debugging tools for Windows
8056 \o Using this engine requires you to install the
8057 \e{Debugging tools for Windows}
8058 \l{http://www.microsoft.com/whdc/devtools/debugging/installx86.Mspx}
8060 \l{http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx}
8061 package (Version 6.12 for the 32-bit or the 64-bit version
8062 of Qt Creator, respectively),
8063 which are freely available for download from the
8064 \l{http://msdn.microsoft.com/en-us/default.aspx}{Microsoft Developer Network}.
8066 The Qt Creator help browser does
8067 not allow you to download files, and therefore, you must copy
8068 the above links to a browser.
8070 \note Visual Studio does not include the Debugging tools needed,
8071 and therefore, you must install them separately.
8073 The pre-built \QSDK for Windows makes use of the library if it
8074 is present on the system. When manually building Qt Creator using
8075 the Microsoft Visual C++ Compiler, the build process checks for the
8076 required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}.
8078 It is highly recommended that you add the Symbol Server provided
8079 by Microsoft to the symbol search path of the debugger. The Symbol
8080 Server provides you with debugging informaton for the operating
8081 system libraries for debugging Windows applications. For more
8082 information, see \l{Setting the Symbol Server in Windows}.
8085 \o Debugging tools for Mac OS X
8086 \o The Qt binary distribution contains both debug and release
8087 variants of the libraries. But you have to explicitly tell the
8088 runtime linker that you want to use the debug libraries even if
8089 your application is compiled as debug as release is the default
8092 If you use a qmake based project in Qt Creator, you can set a
8093 flag in your run configuration, in \gui Projects mode. In the run
8094 configuration, select \gui{Use debug version of frameworks}.
8096 For more detailed information about debugging on the Mac OS X, see:
8097 \l{http://developer.apple.com/mac/library/technotes/tn2004/tn2124.html}{Mac OS X Debugging Magic}.
8099 \note The Mac OS X Snow Leopard (10.6) has a bug that might cause the
8100 application to crash. For a workaround, see:
8101 \l{http://bugreports.qt.nokia.com/browse/QTBUG-4962}{QTBUG-4962}.
8105 \section1 Setting the Symbol Server in Windows
8107 To obtain debugging information for the operating system libraries for
8108 debugging Windows applications, add the Symbol Server provided
8109 by Microsoft to the symbol search path of the debugger:
8111 \o Select \gui Tools > \gui{Options...} > \gui Debugger > \gui CDB.
8112 \o In the \gui {Symbol paths} field, open the \gui{Insert...} menu
8113 and select \gui{Symbol Server...}.
8114 \o Select a directory where you want to store the cached information
8117 Use a subfolder in a temporary directory, such as
8118 \c {C:\temp\symbolcache}.
8121 \note Populating the cache might take a long time on a slow network
8124 \note The first time you start debugging by using the
8125 Debugging tools for Windows, Qt Creator prompts you to add the Symbol
8131 \contentspage index.html
8132 \previouspage creator-debugger-operating-modes.html
8133 \page creator-debug-mode.html
8134 \nextpage creator-debugger-engines.html
8136 \title Interacting with the Debugger
8138 In \gui Debug mode, you can use several views to interact with the
8139 program you are debugging. The availability of views depends on whether
8140 you are debugging C++ or QML. Frequently used views are shown by
8141 default and rarely used ones are hidden. To change the default settings,
8142 select \gui {Window > Views}, and then select views to display or hide.
8144 \image qtcreator-debugger-views.png "Debug mode views"
8146 By default, the views are locked into place in the workspace. Select
8147 \gui {Window > Views > Locked} to unlock the views. Drag and drop the
8148 views into new positions on the screen. Drag view borders to resize the
8149 views. The size and position of views are saved for future sessions.
8151 \section1 Using the Debugger
8153 Once the program starts running under the control of the debugger, it
8154 behaves and performs as usual. You can interrupt a running C++ program by
8155 selecting \gui{Debug} > \gui {Interrupt}. The program is automatically
8156 interrupted when a breakpoint is hit.
8158 Once the program stops, Qt Creator:
8161 \o Retrieves data representing the call stack at the program's current
8163 \o Retrieves the contents of local variables.
8164 \o Examines \gui Expressions.
8165 \o Updates the \gui Registers, \gui Modules, and \gui Disassembler
8166 views if you are debugging the C++ based applications.
8169 You can use the \gui Debug mode views to examine the data in more detail.
8171 You can use the following keyboard shortcuts:
8175 \o To finish debugging, press \key{Shift+F5}.
8176 \o To execute a line of code as a whole, press \key{F10}.
8177 \o To step into a function or a subfunction, press \key{F11}.
8178 \o To continue running the program, press \key{F5}.
8179 \o To run to the selected function when you are stepping into a nested
8180 function, press \key{Ctrl+F6}.
8184 It is also possible to continue executing the program until the current
8185 function completes or jump to an arbitrary position in the current function.
8188 \section1 Setting Breakpoints
8190 A breakpoint represents a position or sets of positions in the code that,
8191 when executed, interrupts the program being debugged and passes the control
8192 to you. You can then examine the state of the interrupted program, or
8193 continue execution either line-by-line or continuously.
8195 Qt Creator shows breakpoints in the \gui{Breakpoints} view which is enabled
8196 by default. The \gui{Breakpoints} view is also accessible when the debugger
8197 and the program being debugged is not running.
8199 \image qtcreator-debug-breakpoints.png "Breakpoints view"
8201 You can associate breakpoints with:
8205 \o Source code files and lines
8211 \o Throwing and catching exceptions
8213 \o Executing and forking processes
8215 \o Executing some system calls
8217 \o Changes in a block of memory at a particular address when a
8222 The interruption of a program by a breakpoint can be restricted with
8225 To set a breakpoint at a particular line you want the program to stop,
8226 click the left margin or press \key F9 (\key F8 for Mac OS X).
8228 To set breakpoints, select \gui {Add Breakpoint...} in
8229 the context menu in the \gui Breakpoints view.
8231 \image qtcreator-add-breakpoint.png "Add Breakpoints" dialog
8233 \note You can remove a breakpoint:
8235 \o By clicking the breakpoint marker in the text editor.
8236 \o By selecting the breakpoint in the breakpoint view and pressing
8238 \o By selecting \gui{Delete Breakpoint} from the context
8239 menu in the \gui Breakpoints view.
8242 You can set and delete breakpoints before the program starts running or
8243 while it is running under the debugger's control. Breakpoints are saved
8244 together with a session.
8246 \section2 Setting Data Breakpoints
8248 To set a data breakpoint at an address:
8252 \o Right-click in the \gui Breakpoints view to open the context menu,
8253 and select \gui {Add Breakpoint...}.
8255 \o In the \gui {Breakpoint type} field, select \gui {Break on data
8256 access at fixed address}.
8258 \o In the \gui Address field, specify the address of the memory block.
8264 If the address is displayed in the \gui {Locals and Expressions} view, you can
8265 select \gui {Add Data Breakpoint at Object's Address} in the context menu to set
8266 the data breakpoint.
8268 \section1 Viewing Call Stack Trace
8270 When the program being debugged is interrupted, Qt Creator displays the
8271 nested function calls leading to the current position as a call stack
8272 trace. This stack trace is built up from call stack frames, each
8273 representing a particular function. For each function, Qt Creator tries
8274 to retrieve the file name and line number of the corresponding source
8275 file. This data is shown in the \gui Stack view.
8277 \image qtcreator-debug-stack.png
8279 Since the call stack leading to the current position may originate or go
8280 through code for which no debug information is available, not all stack
8281 frames have corresponding source locations. Stack frames without
8282 corresponding source locations are grayed out in the \gui{Stack} view.
8284 If you click a frame with a known source location, the text editor
8285 jumps to the corresponding location and updates the \gui{Locals and Expressions}
8286 view, making it seem like the program was interrupted before entering the
8289 \section1 Locals and Expressions
8291 Whenever a program stops under the control of the debugger, it retrieves
8292 information about the topmost stack frame and displays it in the
8293 \gui{Locals and Expressions} view. The \gui{Locals and Expressions} view
8294 typically includes information about parameters of the function in that
8295 frame as well as the local variables.
8297 \image qtcreator-watcher.png "Locals and Expressions view"
8299 Compound variables of struct or class type are displayed as
8300 expandable in the view. Expand entries to show
8301 all members. Together with the display of value and type, you can
8302 examine and traverse the low-level layout of object data.
8310 \i GDB, and therefore Qt Creator's debugger works for optimized
8311 builds on Linux and Mac OS X. Optimization can lead to
8312 re-ordering of instructions or removal of some local variables,
8313 causing the \gui{Locals and Expressions} view to show unexpected
8316 \i The debug information provided by GCC does not include enough
8317 information about the time when a variable is initialized.
8318 Therefore, Qt Creator can not tell whether the contents of a
8319 local variable contains "real data", or "initial noise". If a
8320 QObject appears uninitialized, its value is reported as
8321 \gui {not in scope}. Not all uninitialized objects, however, can be
8326 The \gui{Locals and Expressions} view also provides access to the most
8327 powerful feature of the debugger: comprehensive display of data belonging
8328 to Qt's basic objects.
8330 To enable Qt's basic objects data display feature:
8332 \o Select \gui Tools > \gui {Options...} > \gui Debugger >
8333 \gui{Debugging Helper} and check the \gui{Use Debugging Helper}
8335 \o The \gui{Locals and Expressions} view is reorganized to provide a
8336 high-level view of the objects.
8339 For example, in case of QObject, instead of displaying a pointer to some
8340 private data structure, you see a list of children, signals and slots.
8342 Similarly, instead of displaying many pointers and integers, Qt Creator's
8343 debugger displays the contents of a QHash or QMap in an orderly manner.
8344 Also, the debugger displays access data for QFileInfo and provides
8345 access to the "real" contents of QVariant.
8347 You can use the \gui{Locals and Expressions} view to change the contents of
8348 variables of simple data types, for example, \c int or \c float when the
8349 program is interrupted. To do so, click the \gui Value column, modify
8350 the value with the inplace editor, and press \key Enter (or \key Return).
8352 You can enable tooltips in the main editor displaying this information.
8353 For more information, see \l{Showing Tooltips in Debug Mode}.
8355 \note The set of evaluated expressions is saved in your session.
8357 \section1 Directly Interacting with Native Debuggers
8359 In some cases, it is convenient to directly interact with the command
8360 line of the native debugger. In Qt Creator, you can use the left
8361 pane of the \gui {Debugger Log} view for that purpose. When you press
8362 \key {Ctrl+Return}, the contents of the line under the text cursor
8363 are sent directly to the native debugger. Alternatively, you
8364 can use the line edit at the bottom of the view. Output is displayed in the
8365 right pane of the \gui {Debugger Log} view.
8367 \note Usually, you do not need this feature, because Qt Creator provides
8368 you with better ways to handle the task. For example, instead of using the
8369 GDB \c print command from the command line, you can evaluate an expression
8370 in the \gui{Locals and Expressions} view.
8372 \section1 Debugging C++ Based Applications
8374 The following sections describe additional debugging functions that apply
8375 only to debugging C++.
8377 \section2 Starting the Debugger from the Command Line
8379 You can use the Qt Creator debugger interface from the command line. To
8380 attach it to a running process, specify the process ID as a parameter for
8381 the \c {-debug} option. To examine a core file, specify the file name.
8382 Qt Creator executes all the necessary steps, such as searching for
8383 the binary that belongs to a core file.
8389 \o \c {C:\qtcreator\bin>qtcreator -debug 2000}
8391 \o \c {C:\qtcreator\bin>qtcreator -debug core.2000}
8395 For more information, see \l{Using Command Line Options}.
8397 \section2 Stepping into Frameworks in Mac OS
8399 In Mac OS X, external libraries are usually built into so-called Frameworks,
8400 which may contain both release and debug versions of the library. When you run
8401 applications on the Mac OS desktop, the release version of Frameworks is used
8402 by default. To step into Frameworks, select the \gui {Use debug versions of
8403 Frameworks} option in the project run settings for \gui Desktop and
8404 \gui {Qt Simulator} targets.
8406 \section2 Viewing Threads
8408 If a multi-threaded program is interrupted, the \gui Thread view or the
8409 combobox named \gui Thread in the debugger's status bar can be used to
8410 switch from one thread to another. The \gui Stack view adjusts itself
8413 \section2 Viewing Modules
8415 The \gui{Modules} view displays information that the debugger plugin has
8416 about modules included in the application that is being debugged. A module
8417 is a dynamic link library (.dll) in Windows, a shared object (.so) in
8418 Linux, and a dynamic shared library (.dylib) in Mac OS.
8420 In addition, the view displays symbols within the modules and indicates
8421 where each module was loaded.
8423 Right-click the view to open a context menu that contains menu items for:
8427 \o Updating the module list
8429 \o Loading symbols for modules
8431 \o Examining modules
8433 \o Editing module files
8435 \o Showing symbols in modules
8437 \o Showing dependencies between modules (Windows only)
8441 By default, the \gui{Modules} view is hidden.
8443 \section2 Viewing Source Files
8445 The \gui{Source Files} view lists all the source files included in the project.
8446 If you cannot step into an instruction, you can check whether the source file is
8447 actually part of the project, or whether it was compiled
8448 elsewhere. The view shows the path to each file in the file system.
8450 Right-click the view to open a context menu that contains menu items for
8451 reloading data and opening files.
8453 By default, the \gui{Source Files} view is hidden.
8456 \section2 Viewing Disassembled Code and Register State
8458 The \gui{Disassembler} view displays disassembled code for the current
8459 function. The \gui{Registers} view displays the current state of the CPU's
8462 The \gui{Disassembler} view and the \gui{Registers} view are both useful
8463 for low-level commands for checking single instructions, such as \gui{Step Into}
8464 and \gui{Step Over}. By default, both \gui{Disassembler} and
8465 \gui{Registers} view are hidden.
8471 \contentspage index.html
8472 \previouspage creator-debugging.html
8473 \page creator-debugging-example.html
8474 \nextpage creator-debugger-operating-modes.html
8476 \title Debugging the Example Application
8478 This section uses the \l{Creating a Qt Widget Based Application}{TextFinder} example to
8479 illustrate how to debug Qt C++ applications in the \gui Debug mode.
8482 reads a text file into
8483 QString and then displays it with QTextEdit.
8484 To look at the example QString, \c{line}, and see the
8485 stored data, place a breakpoint and view the QString object
8486 data in textfinder.cpp, as follows:
8489 \o Click in between the line number and the window border on the line
8490 where we invoke \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}
8491 to set a breakpoint.
8493 \image qtcreator-setting-breakpoint1.png
8495 \o Select \gui{Debug > Start Debugging > Start Debugging} or press \key{F5}.
8498 \o To view the breakpoint, click the \gui{Breakpoints} tab.
8500 \image qtcreator-setting-breakpoint2.png
8502 \o To remove a breakpoint, right-click it and select \gui{Delete Breakpoint}.
8505 \o To view the contents of \c{line}, go to the \gui{Locals and
8508 \image qtcreator-watcher.png
8512 Modify the \c{on_findButton_clicked()} function to move back to
8513 the start of the document and continue searching once the cursor hits the
8514 end of the document. Add the following code snippet:
8517 void TextFinder::on_findButton_clicked()
8519 QString searchString = ui->lineEdit->text();
8521 QTextDocument *document = ui->textEdit->document();
8522 QTextCursor cursor = ui->textEdit->textCursor();
8523 cursor = document->find(searchString, cursor,
8524 QTextDocument::FindWholeWords);
8525 ui->textEdit->setTextCursor(cursor);
8527 bool found = cursor.isNull();
8529 if (!found && previouslyFound) {
8530 int ret = QMessageBox::question(this, tr("End of Document"),
8531 tr("I have reached the end of the document. Would you like "
8532 "me to start searching from the beginning of the document?"),
8533 QMessageBox::Yes | QMessageBox::No, QMessageBox::Yes);
8535 if (ret == QMessageBox::Yes) {
8536 cursor = document->find(searchString,
8537 QTextDocument::FindWholeWords);
8538 ui->textEdit->setTextCursor(cursor);
8542 previouslyFound = found;
8546 If you compile and run the above code, however, the application does not
8547 work correctly due to a logic error. To locate this logic error, step
8548 through the code using the following buttons:
8550 \image qtcreator-debugging-buttons.png
8556 \contentspage index.html
8557 \previouspage creator-debugger-engines.html
8558 \page creator-debugging-helpers.html
8559 \nextpage creator-debugging-qml.html
8561 \title Using Debugging Helpers
8563 Qt Creator is able to show complex data types in a customized,
8564 user-extensible manner. For this purpose, it takes advantage of
8565 two technologies, collectively referred to as \e{Debugging Helpers}.
8567 Using the debugging helpers is not \e essential for debugging
8568 with Qt Creator, but they enhance the user's ability to quickly
8569 examine complex data significantly.
8571 \section1 Debugging Helpers Based on C++
8573 This is the first and original approach to display complex data
8574 types. While it has been superseded on most platforms by the more
8575 robust and more flexible second approch using Python scripting,
8576 it is the only feasible one on Windows/MSVC, Mac OS, and
8577 old Linux distributions. Moreover, this approach will automatically
8578 be chosen as fallback in case the Python based approach fails.
8580 During debugging with the C++ based debugging helpers,
8581 Qt Creator dynamically loads a helper library in form of a DLL or a
8582 shared object into the debugged process.
8583 The \QSDK package already contains a prebuilt debugging helper
8584 library. To create your own debugging helper library, select \gui{Tools} >
8585 \gui{Options...} > \gui{Qt4} > \gui{Qt Versions}. As the internal data
8586 structures of Qt can change between versions, the debugging helper
8587 library is built for each Qt version.
8590 \section1 Debugging Helpers Based on Python
8592 Qt Creator uses GDB builds that enable Python scripting to display
8593 information in the \gui {Locals and Expressions} view. When Python scripting
8594 is used, code (Debugging helpers) does not need to be injected into the
8595 debugged process to nicely display QStringList or \c std::map contents, for
8598 The code injection caused problems and put an extra stress on the debugged
8599 process. You can now easily extend the debugging helpers to other types. No
8600 compilation is required, just adding a few lines of Python.
8602 Python scripting vastly reduces the communication overhead compared
8603 with the previous solution. However, there are some obstacles:
8607 \o There is no Python-enabled GDB for Mac OS. Mac OS continues
8608 injection with C++ based debugging helpers.
8610 \o On the Symbian platform, an on-device debugging agent restricts the
8611 communication between GDB and the device. Therefore, extracting
8612 QObject properties, for example, is not possible.
8614 \o There is no GDB to communicate with MSVC compiled applications on
8615 Windows. So information can be displayed nicely only in a limited
8616 fashion by using a cdb extension DLL.
8620 \section2 Extending the Python Based Debugging Helpers
8622 On platforms featuring a Python-enabled version of the GDB debugger,
8623 the data extraction is done by a Python script. This is more robust
8624 as the script execution is separated from the debugged process. It
8625 is also easier to extend as the script is less dependent on the
8626 actual Qt version and does not need compilation.
8628 To extend the shipped Python based debugging helpers for custom types,
8629 define one Python function per user defined type in the
8630 GDB startup file. By default, the following startup file is used:
8631 \c{~/.gdbinit}. To use another file, select \gui {Tools > Options... >
8633 and specify a filename in the \gui {GDB startup script} field.
8635 The function name has to be qdump__NS__Foo, where NS::Foo is the class
8636 or class template to be examined. Nested namespaces are possible.
8638 The debugger plugin calls this function whenever you want to
8639 display an object of this type. The function is passed the following
8642 \o \c d of type \c Dumper
8643 \o \c item of type \c Item
8646 The function has to feed the Dumper object with certain information
8647 which is used to build up the object and its children's display in the
8648 \gui{Locals and Expressions} view.
8654 def qdump__QVector(d, item):
8655 d_ptr = item.value["d"]
8656 p_ptr = item.value["p"]
8657 alloc = d_ptr["alloc"]
8658 size = d_ptr["size"]
8660 check(0 <= size and size <= alloc and alloc <= 1000 * 1000 * 1000)
8661 check(d_ptr["ref"]["_q_value"] > 0)
8663 innerType = item.value.type.template_argument(0)
8664 d.putItemCount(size)
8666 if d.isExpanded(item):
8667 p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
8668 with Children(d, [size, 2000], innerType)
8669 for i in d.childRange():
8670 d.putSubItem(Item(p.dereference(), item.iname, i))
8674 \section2 Item Class
8676 The Item Python class is a thin wrapper around values corresponding to one
8677 line in the \gui{Locals and Expressions} view. The Item members are as follows :
8681 \o \gui{__init__(self, value, parentiname, iname, name = None)} - A
8682 constructor. The object's internal name is created by concatenating
8683 \c parentiname and \c iname. If \c None is passed as \c name, a
8684 serial number is used.
8686 \o \gui{value} - An object of type gdb.Value representing the value to
8689 \o \gui{iname} - The internal name of the object, constituting a dot-separated
8690 list of identifiers, corresponding to the position of the object's
8691 representation in the view.
8693 \o \gui{name} - An optional name. If given, is used in the
8694 \gui{name} column of the view. If not, a simple number in brackets
8700 \section2 Dumper Class
8702 For each line in the \gui{Locals and Expressions} view, a string like the
8703 following needs to be created and channeled to the debugger plugin.
8705 "{iname='some internal name',
8706 addr='object address in memory',
8707 name='contents of the name column',
8708 value='contents of the value column',
8709 type='contents of the type column',
8710 numchild='number of children', // zero/nonzero is sufficient
8711 childtype='default type of children', // optional
8712 childnumchild='default number of grandchildren', // optional
8713 children=[ // only needed if item is expanded in view
8714 {iname='internal name of first child',
8716 {iname='internal name of second child',
8722 While in theory, you can build up the entire string above manually, it is
8723 easier to employ the Dumper Python class for that purpose. The Dumper
8724 Python class contains a complete framework to take care of the \c iname and
8725 \c addr fields, to handle children of simple types, references, pointers,
8726 enums, known and unknown structs as well as some convenience methods to
8727 handle common situations.
8729 The Dumper members are the following:
8733 \o \gui{__init__(self)} - Initializes the output to an empty string and
8734 empties the child stack.
8736 \o \gui{put(self, value)} - Low level method to directly append to the
8739 \o \gui{putCommaIfNeeded(self)} - Appends a comma if the current output
8740 ends in '}', '"' or ']' .
8742 \o \gui{putField(self, name, value)} - Appends a comma if needed, and a
8745 \o \gui{beginItem(self, name)} - Starts writing a field by writing \c {name='}.
8747 \o \gui{endItem(self)} - Ends writing a field by writing \c {'}.
8749 \o \gui{endChildren(self)} - Ends writing a list of children.
8751 \o \gui{childRange(self)} - Returns the range of children specified in
8752 the current \c Children scope.
8754 \o \gui{putItemCount(self, count)} - Appends a field \c {value='<%d items'}
8757 \o \gui{putEllipsis(self)} - Appends fields
8758 \c {'{name="<incomplete>",value="",type="",numchild="0"}'}. This is
8759 automatically done by \c endChildren if the number of children to
8760 print is smaller than the number of actual children.
8762 \o \gui{putName(self, name)} - Appends a \c {name='...'} field.
8764 \o \gui{putType(self, type)} - Appends a field \c {type='...'} unless the
8765 \a type coincides with the parent's default child type.
8767 \o \gui{putNumChild(self, numchild)} - Appends a field \c {numchild='...'}
8768 unless the \c numchild coincides with the parent's default child numchild
8771 \o \gui{putValue(self, value, encoding = None)} - Append a file \c {value='...'},
8772 optionally followed by a field \c {valueencoding='...'}. The \c value
8773 needs to be convertible to a string entirely consisting of
8774 alphanumerical values. The \c encoding parameter can be used to
8775 specify the encoding in case the real value had to be encoded in some
8776 way to meet the alphanumerical-only requirement.
8777 Currently the following encodings are supported:
8780 \o 0: unencoded 8 bit data, interpreted as Latin1.
8782 \o 1: base64 encoded 8 bit data, used for QByteArray,
8783 double quotes are added.
8785 \o 2: base64 encoded 16 bit data, used for QString,
8786 double quotes are added.
8788 \o 3: base64 encoded 32 bit data,
8789 double quotes are added.
8791 \o 4: base64 encoded 16 bit data, without quotes (see 2)
8793 \o 5: base64 encoded 8 bit data, without quotes (see 1)
8795 \o 6: %02x encoded 8 bit data (as with \c QByteArray::toHex),
8796 double quotes are added.
8798 \o 7: %04x encoded 16 bit data (as with \c QByteArray::toHex),
8799 double quotes are added.
8802 \o \gui{putStringValue(self, value)} - Encodes a QString and calls
8803 \c putValue with the correct \c encoding setting.
8805 \o \gui{putByteArrayValue(self, value)} - Encodes a QByteArray and calls
8806 \c putValue with the correct \c encoding setting.
8808 \o \gui{isExpanded(self, item)} - Checks whether the item with the
8809 internal name \c item.iname is expanded in the view.
8811 \o \gui{isExpandedIName(self, iname)} - Checks whether the item with the
8812 internal name \c iname is expanded in the view.
8814 \o \gui{putIntItem(self, name, value)} - Equivalent to:
8818 self.putValue(value)
8824 \o \gui{putBoolItem(self, name, value)} - Equivalent to:
8828 self.putValue(value)
8829 self.putType("bool")
8834 \o \gui{pushOutput(self)} - Moves the output string to a safe location
8835 from with it is sent to the debugger plugin even if further operations
8838 \o \gui{putCallItem(self, name, item, func)} -
8839 Uses GDB to call the function \c func on the value specified by
8840 \a {item.value} and output the resulting item. This function is
8841 not available when debugging core dumps and it is not available
8842 on the Symbian platform due to restrictions imposed by the on-device
8845 \o \gui{putItem(self, item)} - The "master function", handling
8846 basic types, references, pointers and enums directly, iterates
8847 over base classes and class members of compound types and calls
8848 \c qdump__* functions whenever appropriate.
8850 \o \gui{putSubItem(self, item)} - Equivalent to:
8855 Exceptions raised by nested function calls are caught and all
8856 output produced by \c putItem is replaced by the output of:
8859 except RuntimeError:
8860 d.put('value="<invalid>",type="<unknown>",numchild="0",')
8866 \section2 Children and SubItem Class
8868 The attempt to create child items might lead to errors if data is
8869 uninitialized or corrupted. To gracefully recover in such situations,
8870 use \c Children and \c SubItem \e{Context Managers} to create the nested items.
8872 The \c Children constructor \gui{__init__(self, dumper, numChild = 1,
8873 childType = None, childNumChild = None)} uses one mandatory argument and three
8874 optional arguments. The mandatory argument refers to the current \c Dumper
8875 object. The optional arguments can be used to specify the number \c numChild
8876 of children, with type \c childType_ and \c childNumChild_ grandchildren each.
8877 If \c numChild_ is a list of two integers, the first one specifies the actual
8878 number of children and the second the maximum number of children to print.
8880 Similarly, using the \c SubItem class helps to protect individual items.
8885 if d.isExpanded(item):
8889 d.putItem(Item(key, item.iname, "key"))
8892 d.putItem(Item(value, item.iname, "value"))
8895 \section1 Debugging Helpers for QML
8897 The debugging helpers for QML provide you with code completion for custom modules
8898 (\c qmldump) and debugging Qt Quick UI projects (\c qmlobserver).
8900 You have to build the QML Inspector once for each Qt version that you want
8902 with. Select \gui{Tools > Options... > Qt4 > Qt Versions}.
8904 \note QML Inspector requires Qt 4.7.1 or later.
8906 \section1 Enabling Debugging Helpers for Qt's Bootstrapped Applications
8908 Qt's bootstrapped applications (such as moc and qmake) are built in a way
8909 that is incompatible with the default build of the debugging helpers. To
8910 work around this, add \c{dumper.cpp} to the compiled sources in the
8911 application Makefile.
8913 Choose \gui {Tools > Options > Debugger > Debugging Helper > Use debugging
8914 helper from custom location}, and specify an invalid location, such as
8921 \contentspage index.html
8922 \previouspage creator-project-wizards.html
8923 \page creator-project-cmake.html
8924 \nextpage creator-project-generic.html
8926 \title Setting Up a CMake Project
8928 CMake is an alternative to qmake for automating the generation of build
8930 It controls the software compilation process by using simple configuration
8931 files, called CMakeLists.txt files. CMake generates native build
8933 workspaces that you can use in the compiler environment of your choice.
8935 Since Qt Creator 1.1, CMake configuration files are supported.
8936 Qt Creator 1.3 supports the Microsoft tool chain if the CMake version
8939 \section1 Setting the Path for CMake
8941 You can set the path for the \c CMake executable in \gui{Tools} >
8942 \gui{Options... > Projects > CMake}.
8944 \image qtcreator-cmakeexecutable.png
8946 \note Before you open a \c CMake project it is necessary to modify the
8947 \c{PATH} environment variable to include the bin folders of \c mingw and
8948 Qt Creator in the SDK.
8950 For instance, if you have the Qt SDK installed in your C drive,
8951 use the following command to set the environment variables in
8952 the command line prompt:
8954 set PATH=C:\qtsdk\mingw\bin;C:\qtsdk\qt\bin;
8956 Then start Qt Creator by typing:
8958 C:\qtsdk\bin\qtcreator.exe
8961 \section1 Opening CMake Projects
8963 To open a \c CMake project:
8965 \o Select \gui{File} > \gui{Open File or Project...}.
8966 \o Select the \c{CMakeLists.txt} file from your \c CMake project.
8969 A wizard guides you through the rest of the process.
8971 \note If the \c CMake project does not have an in-place build, Qt Creator
8972 lets you specify the directory in which the project is built
8973 (\l{glossary-shadow-build}{shadow build}).
8975 \image qtcreator-cmake-import-wizard1.png
8977 The screenshot below shows how you can specify command line arguments to
8978 \c CMake for your project.
8980 \image qtcreator-cmake-import-wizard2.png
8982 Normally, there is no need to pass any command line arguments for projects
8983 that are already built, as \c CMake caches that information.
8986 \section1 Building CMake Projects
8988 Qt Creator builds \c CMake projects by running \c make, \c mingw32-make, or
8989 \c nmake depending on your platform. The build errors and warnings are
8990 parsed and displayed in the \gui{Build Issues} output pane.
8992 By default, Qt Creator builds the \bold{all} target. You can specify which
8993 targets to build in \gui{Project} mode, under \gui{Build Settings}.
8995 \image qtcreator-cmake-build-settings.png
8997 Qt Creator supports multiple build configurations. The build
8998 directory can also be modified after the initial import.
9000 \section1 Running CMake Projects
9001 Qt Creator automatically adds \gui{Run Configurations} for all targets
9002 specified in the \c CMake project file.
9004 Known issues for the current version can be found
9005 \l{Known Issues}{here}.
9008 \section1 Adding External Libraries to CMake Projects
9010 Through external libraries Qt Creator can support code completion and
9011 syntax highlighting as if they were part of the current project or the Qt
9014 Qt Creator detects the external libraries using the \c FIND_PACKAGE()
9015 macro. Some libraries come with the CMake installation. You can find those
9016 in the \bold{Modules} directory of your CMake installation.
9018 \note If you provide your own libraries, you also need to provide your own
9019 \c FindFoo.cmake file. For more information, see
9020 \l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}.
9022 Syntax completion and highlighting work once your project successfully
9023 builds and links against the external library.
9028 \contentspage index.html
9029 \previouspage creator-debugging-helpers.html
9030 \page creator-debugging-qml.html
9031 \nextpage creator-troubleshooting-debugging.html
9033 \title Debugging Qt Quick Projects
9035 \note You need Qt 4.7.1 or later to debug Qt Quick projects. Debugging projects
9036 not created with the Qt Quick wizards is only supported with Qt 4.8, or later.
9038 \section1 Setting Up QML Debugging
9040 The process of setting up debugging for Qt Quick projects depends on the type of
9041 the project: Qt Quick UI or Qt Quick Application.
9043 To debug Qt Quick UI projects:
9047 \o Select \gui Projects, and then select the \gui QML check box in the
9048 \gui {Run Settings}, to enable QML debugging.
9050 \o Compile the QML Inspector debugging helper. For more information, see
9051 \l{Debugging Helpers for QML}.
9055 To debug Qt Quick Applications:
9059 \o Select \gui Projects, and then select the \gui {Link QML debugging
9060 library} check box in \gui {Build Steps}.
9062 You might have to compile the library first, by selecting the
9065 \image qml-link-debugging-library.png "Build Steps"
9067 \note Debugging requires opening a socket at a well-known port, which
9068 presents a security risk. Anyone on the Internet could connect to the
9069 application that you are debugging and execute any JavaScript
9070 functions. Therefore, you must make sure that the port is properly
9071 protected by a firewall.
9073 \o In the \gui {Run Settings}, select the \gui QML check box to enable
9076 \o Select \gui {Build > Rebuild Project} to clean and rebuild the
9081 \section1 Starting QML Debugging
9083 To start the application, choose \gui {Debug > Start Debugging
9084 > Start Debugging} or press \key F5. Once the application starts running, it behaves
9085 and performs as usual. You can then perform the following tasks:
9089 \o Debug JavaScript functions
9091 \o Preview QML changes at runtime
9093 \o Inspect QML at runtime
9097 \section1 Debugging JavaScript Functions
9099 You can use the Qt Creator \gui Debug mode to inspect the state of your
9100 application while debugging. You can interact with the debugger in several
9101 ways, as described in the following sections:
9105 \o \l{Setting Breakpoints}
9107 \o \l{Viewing Call Stack Trace}
9109 \o \l{Locals and Expressions}
9113 \section1 Executing JavaScript Expressions
9115 When the application is interrupted by a breakpoint, you can use the \gui {QML
9116 Script Console} to execute JavaScript expressions in the current context. To
9117 open it, choose \gui {Window > View > QML Script Console}.
9119 \image qml-script-console.png "QML Script Console view"
9121 You can type JavaScript expressions and use them to get information about the
9122 state or your application. For example, property values.
9124 You can see the current value of a property by hovering over it in the code editor.
9126 \section1 Applying QML Changes at Runtime
9128 If you change property values or add properties in the code editor, the changes
9129 are updated in the running application when you save them. If live preview is not supported
9130 for an element, a message appears. Click \gui Reload to preview the changes.
9132 Reloading is enabled by default. To disable it, click
9133 \inlineimage qml-observer-bar-reload.png "Apply Changes on Save button"
9136 \section1 Inspecting QML at Runtime
9138 While the application is running, you can use the \gui {QML Inspector} view to
9139 explore the object structure, debug animations, and inspect colors.
9140 To open the \gui {QML Inspector} view, choose \gui {Window > View >
9142 The view shows the properties of the currently selected QML element.
9144 \image qml-observer-view.png "QML Inspector view"
9146 When you debug complex applications, you can use the inspection
9147 mode to jump to the position in code where an element is defined. You are
9148 switched to the inspection mode, when you click the \gui Select, \gui Zoom,
9149 or \gui {Color Picker} button
9152 \image qml-observer-buttons.png "QML Inspector toolbar"
9154 When the \gui Select tool is enabled, you can click elements in the running
9155 application to jump to their definitions in the code. The properties of the
9156 selected element are displayed in the \gui {QML Inspector} view. The element
9157 hierarchy is displayed as a bread crumb path.
9159 You can also right-click an element in the running application to view the element
9160 hierarchy as a context menu.
9162 \image qml-observer-context-menu.png "QML Inspector"
9164 To switch to the zoom mode, click the \gui Zoom button. Click in the
9165 running application to zoom in. Right-click to open a context menu that
9166 contains zoom controls.
9168 To inspect colors, click the \gui {Color Picker} button. You can also click
9169 \inlineimage qml-observer-bar-copy-color.png "Copy Color button"
9170 to copy the color definition to the clipboard.
9172 To switch out of the inspection mode, deselect the \gui Select, \gui Zoom,
9173 and \gui {Color Picker} button.
9175 To move the application running in \QQV to the front, select the
9176 \gui {Show Application on Top} button.
9178 \section1 Debugging Animations
9180 \image qml-observer.png
9182 To play and pause animations in the running application, select the
9183 \gui {Play/Pause Animations} button on the toolbar or \gui {Debugging >
9184 Animations > Pause}, or press
9187 To change the speed at which animations are played, select a value in \gui {Debugging
9188 > Animations} or click and hold down the \gui {Play/Pause Animations}
9189 button to select a value.
9195 \contentspage index.html
9196 \previouspage creator-project-cmake.html
9197 \page creator-project-generic.html
9198 \nextpage creator-version-control.html
9200 \title Setting Up a Generic Project
9202 Qt Creator supports generic projects, so you can import existing projects
9203 that do not use qmake or CMake and Qt Creator ignores your build system.
9205 Generic project support allows you to use Qt Creator as a code editor. You
9206 can change the way your project is built by modifying the \c make command
9207 in the \gui{Projects} mode under \gui{Build Settings}.
9209 When you import a project, Qt Creator creates the following files that
9210 allow you to specify which files belong to your project and which include
9211 directories or defines you want to pass to your compile:
9212 \tt{.files}, \tt{.includes}, and \tt{.config}.
9215 \section1 Importing a Generic Project
9217 To import an existing generic project:
9219 \o Select \gui File > \gui{New File or Project...} >
9220 \gui{Other Project} > \gui{Import Existing Project}.
9221 \o In \gui{Import Existing Project}, enter the project name
9222 and select the location of the project file you want to import.
9224 Qt Creator automatically generates the following files in the
9227 \o \l{Specifying Files}{.files}
9228 \o \l{Specifying Include Paths}{.includes}
9229 \o \l{Specifying Defines}{.config}
9234 When the project is successfully imported, Qt Creator creates the project
9235 tree in the sidebar.
9237 After importing a generic project into Qt Creator, open it by selecting the
9241 \section1 Working with Generic Project Files
9243 For a generic project, you have to manually specify which files belong to
9244 your project and which include directories or defines you want to pass to
9248 \section1 Specifying Files
9250 The list of files for a generic project is specified in the \tt{.files}
9251 file. When you first create a generic project, Qt Creator adds any
9252 files it recognizes to your project.
9254 To add or remove files, edit the \tt{.files} file in Qt Creator.
9255 Qt Creator recreates your project tree when you save the \tt{.files} file.
9256 Alternatively, you can add and remove files using the context menu in the
9259 If you frequently need to update the \tt{.files} file, you can do so
9260 efficiently by using a script that updates the file for you. If the file
9261 is modified externally, you have to restart Qt Creator for the changes to
9264 To update the \tt{.files} on the \gui Git repository use the following
9267 git ls-files "*.cpp" "*.h" > MyProject.files
9270 \section1 Specifying Include Paths
9272 The include paths are specified in the \tt{.includes} file, one include
9273 path per line. The paths can be either absolute or relative to the
9274 \tt{.includes} file.
9276 \section1 Specifying Defines
9278 The defines are specified in the \tt{.config} file. The \tt{.config} file is
9279 a regular C++ file, prepended to all your source files when they are parsed.
9280 Only use the \tt{.config} file to add lines as in the example below:
9287 \section1 Creating a Run Configuration
9289 Qt Creator cannot automatically determine which executable to run.
9291 In the \gui{Projects} mode under \gui{Run Settings}, define the executable
9294 \o Click \gui Add and select \gui{Custom Executable}.
9295 \o Define the configuration name, the location of the executable, any
9296 additional arguments and the working directory.
9305 \contentspage index.html
9306 \previouspage creator-design-mode.html
9307 \page creator-visual-editor.html
9308 \nextpage quick-projects.html
9310 \title Developing Qt Quick Applications
9312 You can either create Qt Quick projects from scratch or import existing projects to
9315 You can use the code editor (\l{Using the Editor}{Edit mode}) or the visual editor
9316 (\l{Using Qt Quick Designer}{Design mode}) to develop Qt Quick applications.
9318 \image qtcreator-qt-quick-editors.png "Edit mode and Design mode"
9320 The following sections describe typical tasks you can do with Qt Creator.
9324 \o \l {Creating Qt Quick Projects}
9325 \o \l {Using Qt Quick Designer}
9326 \o \l {Creating Components}
9327 \o \l {Creating Buttons}
9328 \o \l {Creating Scalable Buttons and Borders}
9329 \o \l {Creating Screens}
9330 \o \l {Animating Screens}
9331 \o \l {Adding User Interaction Methods}
9332 \o \l {Exporting Designs from Graphics Software}
9333 \o \l {Implementing Application Logic}
9334 \o \l {Using QML Modules with Plugins}
9343 \contentspage index.html
9344 \previouspage creator-visual-editor.html
9345 \page quick-projects.html
9346 \nextpage creator-using-qt-quick-designer.html
9348 \title Creating Qt Quick Projects
9350 \image qmldesigner-new-project.png "New File or Project dialog"
9352 When you create a new Qt Quick project from scratch, you have the following options:
9356 \o \gui {Qt Quick Application} creates a Qt Quick application project that can
9357 contain both QML and C++ code. The project includes a QDeclarativeView. You can build
9358 the application and deploy it on desktop and mobile target platforms. For example, you
9359 can create signed Symbian Installation System (SIS) packages for this type of projects.
9361 \o \gui {Qt Quick UI} creates a Qt Quick UI project with a single QML file that
9362 contains the main view. You can review Qt Quick UI projects in the QML Viewer and you
9363 need not build them. You do not need to have the development environment installed on your
9364 computer to create and run this type of projects.
9366 \o \gui {Custom QML Extension Plugin} creates a C++ plugin that makes it possible
9367 to offer extensions that can be loaded dynamically into applications by using the
9368 QDeclarativeEngine class.
9372 If you have existing QML applications that you want to run in Qt Creator or deploy
9373 to mobile devices, use the \gui {Qt Quick Application} wizard to convert them
9374 to Qt Quick applications.
9376 \section1 Creating Qt Quick UI Projects
9380 \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick UI
9383 The \gui{Introduction and Project Location} dialog opens.
9385 \image qmldesigner-new-ui-project-location.png "Introduction and Project Location dialog"
9387 \o In the \gui Name field, give a name to the project.
9389 Do not use spaces and special characters in the project name and path.
9391 \o In the \gui {Create in} field, enter the path for the project files. For example,
9392 \c {C:\Qt\examples}. To select the path from a directory tree, click \gui Browse.
9394 \o Click \gui{Next}.
9396 \image qmldesigner-new-ui-project-summary.png "Project Management dialog"
9398 \o Review the project settings, and click \gui{Finish} to create the project.
9403 Qt Creator creates the following files:
9407 \o .qmlproject project file defines that all QML, JavaScript, and image
9408 files in the project folder belong to the project. Therefore, you do not
9409 need to individually list all the files in the project.
9411 \o .qml file defines an element, such as a component, screen, or the whole
9416 The \c import statement in the beginning of the .qml file specifies the
9417 \l {http://doc.qt.nokia.com/4.7/qdeclarativemodules.html} {Qt modules}
9418 to import. Each Qt module contains a set of default elements.
9419 Specify a version to get the features you want.
9421 To use JavaScript and image files in the application, copy them to the
9424 \section1 Creating Qt Quick Applications
9428 \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick Application
9431 The \gui{Introduction and Project Location} dialog opens.
9433 \image qmldesigner-new-project-location.png "Introduction and Project Location dialog"
9435 \o In the \gui Name field, give a name to the project.
9437 Do not use spaces and special characters in the project name and path.
9439 \o In the \gui {Create in} field, enter the path for the project files. For example,
9440 \c {C:\Qt\examples}. To select the path from a directory tree, click \gui Browse.
9442 \o Click \gui{Next}.
9444 The \gui {Application Type} dialog opens.
9446 \image qmldesigner-new-project-qml-sources.png "Application Type dialog"
9448 \o Select the Qt Quick Component Set to use in your application. The
9449 built-in elements allow you to write cross-platform applications with
9450 custom look and feel. The components for Symbian and MeeGo Harmattan
9451 allow you to create applications with a native look and feel for the
9452 selected mobile platform.
9454 You can also import an existing QML file in this dialog.
9456 \o Click \gui{Next}.
9458 The \gui {Target Setup} dialog opens.
9460 \image qmldesigner-new-project-qt-versions.png "Target Setup dialog"
9462 \o Select the Qt versions to use as build targets for your project,
9463 and then click \gui{Next}.
9465 \note Qt Quick is supported since Qt 4.7, and therefore, only Qt 4.7 and later
9466 versions are displayed. Further, if you have only one supported Qt version installed,
9467 this dialog is skipped.
9469 The \gui {Mobile Options} dialog opens.
9471 \image qmldesigner-new-app-project-mobile-options.png "Mobile Options dialog"
9473 \o In the \gui {Orientation behavior} field, determine how the application
9474 behaves when the orientation of the device display rotates between portrait
9475 and landscape, and then click \gui Next.
9477 \note This dialog opens only if you select \gui Maemo5 or
9478 \gui {Symbian Device} target in the \gui {Target Setup} dialog. On
9479 Harmattan, the Qt Quick Components for MeeGo provide native-looking
9482 The \gui {Symbian Specific} dialog opens.
9484 \image qmldesigner-new-project-symbian-options.png "Symbian Specific dialog"
9486 \o In the \gui {Application icon (.svg)} field, select an application
9487 icon for the \gui {Symbian Device} target, or use the default icon.
9489 \o In the \gui {Target UID3} field, specify the \l{Application UID}, or
9490 use the default UID.
9492 \note Qt Creator generates a UID for testing the application on a device.
9493 You need to change the UID when you deliver the application for public
9498 The \gui {Maemo Specific} dialog opens.
9500 \image qmldesigner-new-project-maemo-options.png "Maemo Specific dialog"
9502 \o In the \gui {Application icon} field, select the application
9503 icon to use on Maemo or Harmattan targets, or use the default icon.
9505 The \gui {Project Management} dialog opens.
9507 \image qmldesigner-new-project-summary.png "Project Management" dialog
9509 \o In the \gui {Add to project} field, you can add this project to another
9510 project as a subproject.
9512 \o In the \gui {Add to version control} field, you can add the project to
9513 a version control system.
9515 \o Click \gui Finish to create the project.
9519 Qt Creator creates the necessary boilerplate files. Some of the files are
9520 specific to the Symbian, Maemo, or MeeGo Harmattan platform.
9522 \section1 Importing QML Applications
9524 If you have existing QML applications that you want to run in Qt Creator or deploy
9525 to mobile devices, use the \gui {Qt Quick Application} wizard and select the main
9526 .qml file in your project. All the other files in the project are automatically added
9527 to the application project.
9529 To import QML applications:
9533 \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick Application
9536 \o Name the project and set its path, and then click \gui Next.
9538 \o In the \gui {Application Type} dialog, select the \gui {Use an
9540 option and specify the main .qml file of the project you want to import.
9542 \image qmldesigner-import-project.png "Application Type dialog"
9546 \o Select the Qt versions to use as build targets for your project, and click
9549 \o Specify options for deploying the application to mobile device targets, and
9552 \o Review the project settings, and click \gui{Finish} to create the project.
9556 Qt Creator adds references to the QML files to a project and creates the additional files
9557 necessary for deploying applications to mobile devices.
9564 \contentspage index.html
9565 \previouspage creator-using-qt-quick-designer.html
9566 \page quick-components.html
9567 \nextpage quick-buttons.html
9569 \title Creating Components
9571 A QML component provides a way of defining a new type that you can re-use in other QML
9572 files. A component is like a black box; it interacts with the outside world
9573 through properties, signals, and slots, and is generally defined in its own QML file.
9574 You can import components to screens and applications.
9576 You can use the following QML elements to create components:
9580 \o \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
9581 uses an image as a border or background.
9582 \o \l{http://doc.qt.nokia.com/4.7/qml-image.html}{Image}
9583 adds a bitmap to the scene. You can stretch and tile images.
9584 \o \l{http://doc.qt.nokia.com/4.7/qml-item.html}{Item}
9585 is the most basic of all visual items in QML. Even though it has no visual appearance,
9586 it defines all the properties that are common across visual items, such as the x and
9587 y position, width and height, anchoring, and key handling.
9588 \o \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
9589 adds a rectangle that is painted with a solid fill color and an optional border.
9590 You can also use the radius property to create rounded rectangles.
9591 \o \l{http://doc.qt.nokia.com/4.7/qml-text.html}{Text}
9592 adds formatted read-only text.
9593 \o \l{http://doc.qt.nokia.com/4.7/qml-textedit.html}{Text Edit}
9594 adds a single line of editable formatted text that can be validated.
9595 \o \l{http://doc.qt.nokia.com/4.7/qml-textinput.html}{Text Input}
9596 adds a single line of editable plain text that can be validated.
9597 \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-webview.html}{Web View}
9598 adds web content to a canvas.
9602 QML elements allow you to write cross-platform applications with custom look
9603 and feel. You can also use ready-made Qt Quick Components for Symbian and
9604 MeeGo Harmattan that allow you to create applications with a native look and
9605 feel for the selected mobile platform. You can install the components as
9608 When you use the Qt Creator project wizard to create Qt Quick applications,
9609 you can select which component set to use in your application.
9611 Even if you use the Qt Quick Components, you can still write cross-platform
9612 applications, by using different sets of QML files for each platform.
9614 You can dowload a set of commonly used UI-components for generic use in
9615 Qt Quick projects from
9616 \l{https://projects.forum.nokia.com/QMLTemplates}{QML Templates}. You can
9617 open and edit the templates in \QD.
9619 \section1 Creating Components in Qt Quick Designer
9623 \o Select \gui {File > New File or Project > Files and Classes > QML
9624 > Choose...} to create a new .qml file.
9626 \note Components are listed in the \gui {QML Components} section of the
9627 \gui Library pane only if the filename begins with a capital letter.
9629 \o Click \gui Design to open the .qml file in \QMLD.
9631 \o Drag and drop an item from the \gui Library pane to the editor.
9633 \o Edit item properties in the \gui Properties pane.
9635 The available properties depend on the item.
9639 The following sections contain examples of how to create some common components:
9643 \o \l{Creating Buttons}
9645 \o \l{Creating Scalable Buttons and Borders}
9653 \contentspage index.html
9654 \previouspage quick-components.html
9655 \page quick-buttons.html
9656 \nextpage quick-scalable-image.html
9658 \title Creating Buttons
9660 To create a button component:
9664 \o Select \gui {File > New File or Project > QML > QML File > Choose...} to
9665 create a QML file called Button.qml (for example).
9667 \note Components are listed in the \gui Library pane only if the filename
9668 begins with a capital letter.
9670 \o Click \gui {Design} to edit the file in the visual editor.
9672 \o In the \gui Navigator pane, click \gui Rectangle to set properties
9675 \o In the \gui Properties pane, modify the appearance of the button.
9679 \o In the \gui Size field, set the width (\gui W) and height (\gui H)
9682 \o In the \gui Color field, select the button color.
9684 \o In the \gui Radius field, use the slider to set the radius of the
9685 rectangle and produce rounded corners for the button.
9689 \o Drag and drop a \gui {Text} item on top of the \gui Rectangle. This
9690 creates a nested element where \gui Rectangle is the parent element of
9691 \gui Text. Elements are positioned relative to their parents.
9693 \o In the \gui Properties pane, edit the properties of the \gui Text item.
9697 \o In the \gui Text field, type \bold Button.
9699 You can select the text color, font, size, and style in the \gui Font
9702 \o In the \gui Alignment field, select the center buttons to align
9703 the text to the center of the button.
9705 \o Click \gui {Layout}, and then click the
9706 \inlineimage qmldesigner-anchor-fill-screen.png
9707 button to anchor the text to the whole button area.
9711 \o Press \key {Ctrl+S} to save the button.
9713 \image qmldesigner-button.png "Button component"
9717 \note To view the button, you must add it to a Qt Quick Application or Qt Quick UI
9720 To create a graphical button that scales beautifully without using vector graphics,
9721 use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
9722 element. For more information, see \l{Creating Scalable Buttons and Borders}.
9729 \contentspage index.html
9730 \previouspage quick-buttons.html
9731 \page quick-scalable-image.html
9732 \nextpage quick-screens.html
9734 \title Creating Scalable Buttons and Borders
9736 You can use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
9737 element to display an image, such as a PNG file, as a border and a background.
9739 Use two Border Image elements and suitable graphics to make it look like the button
9740 is pushed down when it is clicked. One of the Border Image elements is visible by default.
9741 You can specify that it is hidden and the other one becomes visible when the mouse
9744 Add a MouseArea that covers the whole area and emits the clicked signal (\c {parent.clicked()})
9745 when it detects a mouse click.
9747 You can add text to the button and set it up as a property. The text can then be initialized
9748 from the outside, making the button a reusable UI component. The font size is also available
9749 in case the default size is too big. You can scale down the button text and use smooth text
9750 rendering for some extra quality.
9752 \image qmldesigner-borderimage.png "Graphical button"
9754 To create a graphical button:
9758 \o Select \gui {File > New File or Project > QML > QML File > Choose...} to create
9759 a QML file called Button.qml (for example).
9761 \o Double-click the file to open it in the code editor.
9763 \o Replace the \gui Rectangle with an \gui Item, as illustrated by the
9764 following code snippet:
9772 \o Specify properties and set expressions for the \gui Item, as
9773 illustrated by the following code snippet:
9775 \snippet snippets/qml/quick-scalable-image.qml properties and signal definitions
9777 You will point to the properties and expression later.
9779 \o Click \gui {Design} to edit the file in the visual editor.
9781 \o Drag and drop two \gui BorderImage items from the \gui Library pane to
9784 \o Drag and drop a \gui Text item to the scene.
9786 \o Drag and drop a \gui MouseArea to the screen.
9788 \o In the \gui Navigator pane, select \gui border_image1 to specify
9789 settings for it in the \gui Properties pane:
9793 \o Select \gui {Set Expression} in the menu next to the \gui Visibility
9796 \o Enter the following expression to specify that the image is visible
9797 when the mouse is not pressed down: \c {!mouse_area1.pressed}.
9799 \o In the \gui Source field, select the image file for the
9800 button, for example button_up.png.
9802 \o Click \gui {Layout}, and then click the
9803 \inlineimage qmldesigner-anchor-fill-screen.png
9804 button to anchor the border image to the \gui Item.
9808 \o Select \gui border_image2 to specify similar settings for it:
9812 \o Set the following epression for \gui Visibility, to specify that
9813 the image is visible when the mouse is pressed down:
9814 \c {mouse_area1.pressed}.
9816 \o In the \gui Source field, select the image file for the
9817 button when it is clicked, for example button_down.png.
9819 \o Click \gui {Layout}, and then click the
9820 \inlineimage qmldesigner-anchor-fill-screen.png
9821 button to anchor the border image to the \gui Item.
9825 \o Select \gui text1 to specify font size and color, and text
9826 scaling and rendering:
9830 \o In the \gui Color field, use the color picker to select
9831 the font color, or enter a value in the field.
9833 \o In the \gui Text field, select \gui {Set Expression} and
9834 enter a pointer to the \c {text} property that you specified
9835 earlier: \c {parent.txt}.
9837 \o Select the \gui Aliasing check box to enable smooth text
9840 \o In the \gui Size field, select \gui {Pixels} to specify
9841 the font size in pixels. By default, the size is specified in
9844 \o In the \gui Size field, select \gui {Set Expression} and
9845 enter a pointer to the \c {fontSize} property that you specified
9848 \o Click \gui {Layout}, and then click the
9849 \inlineimage qmldesigner-center-in.png "Anchor buttons"
9850 buttons to inherit the vertical and horizontal centering from
9853 \o Click \gui Advanced to specify scaling for the text in the
9856 \o Select \gui {Set Expression} and enter the following expression:
9857 \c {if (!mousearea1.pressed) { 1 } else { 0.95 }}.
9859 \note You can enter long and complicated expressions also in the
9864 \o In the code editor, add to the \c MouseArea item
9865 a pointer to the \c clicked expression that you added earlier:
9866 \c {onClicked: parent.clicked()}.
9870 \note To view the button, you must add it to a Qt Quick Application or Qt
9878 \contentspage index.html
9879 \previouspage quick-scalable-image.html
9880 \page quick-screens.html
9881 \nextpage quick-animations.html
9883 \title Creating Screens
9885 You can use predefined QML elements and your own components to create screens.
9886 Typically, the main qml file in a Qt Quick project specifies the main window of an
9889 The QML files in the project folder are displayed in \gui {QML Components} in the
9892 You can also use ready-made Qt Quick Components for Symbian and
9893 MeeGo Harmattan that allow you to create screens with a native look and
9894 feel for the selected mobile platform. You can install the components as
9897 You can dowload QML templates that specify different types of screens from
9898 \l{https://projects.developer.nokia.com/QMLTemplates}{QML Templates} for use in
9899 your Qt Quick projects. You can open and edit the templates in \QD.
9901 \section1 Adding Components to Screens
9905 \o Drag and drop components from the \gui Library pane to the editor.
9907 \o Select components in the \gui Navigator pane to edit their properties
9908 in the \gui Properties pane.
9910 For example, you can anchor components to a position on the screen.
9914 \section1 Using Data Models
9916 You can create the following types of views to organize items provided by
9917 \l{http://doc.qt.nokia.com/4.7/qdeclarativemodels.html}{data models}:
9921 \o \l{http://doc.qt.nokia.com/4.7/qml-gridview.html}{Grid View}
9922 provides a grid vizualization of a model.
9924 \o \l{http://doc.qt.nokia.com/4.7/qml-listview.html}{List View}
9925 provides a list vizualization of a model.
9927 \o \l{http://doc.qt.nokia.com/4.7/qml-pathview.html}{Path View}
9928 visualizes the contents of a model along a path.
9932 In the code editor, write the code to use the data models.
9934 \section1 Positioning Items on Screens
9936 You can use the following items to arrange items on screens:
9940 \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-column.html}{Column}
9941 arranges its child items vertically.
9943 \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-row.html}{Row}
9944 arranges its child items horizontally.
9946 \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-grid.html}{Grid}
9947 arranges its child items so that they are aligned in a grid and
9948 are not overlapping.
9950 \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-flow.html}{Flow}
9951 arranges its child items side by side, wrapping as necessary.
9955 \section1 Using States
9957 Use states and transitions
9958 to navigate between screens.
9960 QML states typically describe user interface configurations, such as the UI elements,
9961 their properties and behavior and the available actions. For example, you can use
9962 states to create two screens.
9964 To add states, click the empty slot in the \gui States pane. Then modify the new state
9965 in the visual editor.
9967 \image qmldesigner-states.png "States pane"
9969 The properties that you change in a state are highlighted with blue color.
9970 In the code editor, you can see the changes recorded as changes to the base state.
9972 To keep the QML code clean, you should create a base state that contains all the
9973 elements you will need in the application. You can then create states, in
9974 which you hide and show a set of items and modify their properties.
9979 \o Align items on different screens with each other.
9981 \o Avoid excessive property changes. If an item is invisible in the base
9982 state, you must define all changes to its child elements as property changes,
9983 which leads to complicated QML code.
9985 \o Minimize the differences between the base state and the other states
9986 to keep the QML code short and readable and to improve performance.
9988 \o Avoid problems when using transitions and animation when changing
9993 To create screens for an application by using states:
9997 \o In the base state, add all elements you will need in the application.
9998 While you work on one screen, you can click the
9999 \inlineimage qmldesigner-show-hide-icon.png
10000 icon to hide elements on the canvas that are not part of a screen.
10002 \o In the \gui States pane, click the empty slot to create a new state
10003 and give it a name. For example, \c Normal.
10005 \o In the \gui Properties pane, deselect the \gui Visibility check box
10006 or set \gui Opacity to 0 for each element that is not needed in this view.
10007 If you specify the setting for the parent element, all child elements
10008 inherit it and are also hidden.
10010 \image qmldesigner-screen-design.png "Designing screens"
10012 \o Create additional states for each screen and set the visibility or
10013 opacity of the elements in the screen.
10015 \o To determine which view opens when the application starts, use the code
10016 editor to set the state of the root item of the .qml file, as specified by the
10017 following code snippet:
10033 \contentspage index.html
10034 \previouspage quick-screens.html
10035 \page quick-animations.html
10036 \nextpage quick-user-interaction.html
10038 \title Animating Screens
10040 To make movement between states smooth, you can specify transitions.
10041 You can use different types of animated transitions. For example, you can animate changes
10042 to property values and colors. You can use rotation animation to control the direction of
10043 rotation. For more information, see
10044 \l{http://doc.qt.nokia.com/4.7/qdeclarativeanimation.html}{QML Animation}.
10046 You can use the \c ParallelAnimation element to start several animations at the same time.
10047 Or use the \c SequentialAnimation element to run them one after another.
10049 You can use the code editor to specify transitions. For more information, see
10050 \l{http://doc.qt.nokia.com/4.7/qml-transition.html}{QML Transition Element}.
10058 \contentspage index.html
10059 \previouspage quick-animations.html
10060 \page quick-user-interaction.html
10061 \nextpage quick-export-to-qml.html
10063 \title Adding User Interaction Methods
10065 You can add the following basic interaction methods to scenes:
10069 \o \l{http://doc.qt.nokia.com/4.7/qml-flickable.html}{Flickable}
10070 items can be flicked horizontally or vertically.
10071 \o \l{http://doc.qt.nokia.com/4.7/qml-flipable.html}{Flipable}
10072 items can be flipped between their front and back sides by using rotation,
10073 state, and transition.
10074 \o \l{http://doc.qt.nokia.com/4.7/qml-focusscope.html}{Focus Scope}
10075 assists in keyboard focus handling when building reusable QML components.
10076 \o \l{http://doc.qt.nokia.com/4.7/qml-mousearea.html}{Mouse Area}
10077 enables simple mouse handling.
10086 \contentspage index.html
10087 \previouspage quick-user-interaction.html
10088 \page quick-export-to-qml.html
10089 \nextpage quick-application-logic.html
10091 \title Exporting Designs from Graphics Software
10093 You can export designs from graphics software, such as Adobe Photoshop and GIMP,
10094 to QML files. Each scene is converted into a single QML file with an Image or a
10095 Text element for each layer and saved on the development PC. Top-level layer
10096 groups are converted into merged QML Image elements.
10098 Note: GIMP does not support grouping, and therefore, each layer is exported as
10101 The following rules apply to the conversions:
10105 \o Layer names are used as element names. Spaces and hash marks (#) are
10106 replaced with underscore characters to create valid ids for the elements.
10108 \o Layer styles, such as drop shadows, are converted to images.
10110 \o Offset, size, ordering and opacity are preserved.
10112 \o Text layers are converted to Text elements, unless you specify that they
10113 be converted to Image elements.
10115 \o Hidden layers can be exported, and their visibility is set to hidden.
10117 \o PNG images are copied to the images subirectory.
10121 You can open the QML file in Qt Creator for editing. If you edit the file in Adobe
10122 Photoshop and export it to the same directory again, any changes you made in Qt
10123 Creator are overwritten. However, you can re-export graphical assets without
10124 recreating the QML code.
10126 If you create vector graphics with other tools that have an Adobe Photoshop export
10127 option,such as Adobe Illustrator, you can export them first to Photoshop and then
10130 \section1 Exporting from Adobe Photoshop to QML
10132 \image qml-export-photoshop.png
10134 The script has been tested to work on Adobe Photoshop CS 4 and 5, but it might also
10135 work on other versions.
10139 \o Download the export script, \e{Export QML.jx}, from
10140 \l{http://qt.gitorious.org/qt-labs/photoshop-qmlexporter/trees/master}{Gitorious}.
10142 \note Read the README.txt file in the repository for latest information about
10145 \o Double-click the export script to add the export command to the \gui Scripts
10146 menu. You can also copy the script file to the Adobe Photoshop scripts directory
10147 (typically, \c{\Presets\Scripts} in the Photoshop installation directory).
10149 \o In Adobe Photoshop, choose \gui {File > Scripts > Export to QML} to export the
10150 scene to a QML file.
10152 \o In the \gui {Export Document to QML} dialog, enter a name and location for the
10155 \o Select the \gui {Rasterize text} check box to export text layers as images,
10156 not as Text elements.
10158 \o Select the \gui {Group layers} check box to export each top-level group as a
10159 merged QML Image element.
10161 \o Select the \gui {Export hidden} check box to export hidden layers and to set
10162 their visibility property to hidden.
10164 \o Deselect the \gui {Export QML} check box if you have modified the QML document
10165 in Qt Creator, but still want to re-export graphical assets.
10167 \o Click \gui Export.
10171 The QML file is saved to the location that you specified.
10172 In Qt Creator, choose \gui {File > Open File or Project} to open the QML file.
10174 \note Existing files are replaced without warning.
10176 \section1 Exporting from GIMP to QML
10178 \image qml-export-gimp.png
10180 The script has been tested to work on GIMP 2. You can download GIMP 2 from
10181 \l{http://www.gimp.org/downloads/}{GIMP Downloads}.
10183 To use the export script on Microsoft Windows, you also need to install the
10184 GIMP Python extension (Python, PyCairo, PyGobject, PyGTK). However, GIMP is
10185 not officially supported on Windows, so we cannot guarantee that this will
10190 \o On Microsoft Windows, you must first add Python support to your GIMP
10191 installation, as instructed in
10192 \l {http://www.gimpusers.com/tutorials/install-python-for-gimp-2-6-windows}{Tutorial: Installing Python for GIMP 2.6 (Windows)}.
10194 \o Download the export script, \e qmlexporter.py, from
10195 \l{http://qt.gitorious.org/qt-labs/gimp-qmlexporter/trees/master}{Gitorious}.
10197 \note Read the INSTALL.txt in the repository for latest information about the
10200 \o Copy the export script to the plug-ins directory in the GIMP installation
10203 \o Check the properties of the file to make sure that it is executable.
10205 On Linux, run the following command: \c {chmod u+rx}
10207 \o Restart GIMP to have the export command added to the \gui File menu.
10209 \o Choose \gui {File > Export to QML} to export the design to a QML file.
10211 \o In the \gui {Export Layers to a QML Document} dialog, enter a name and
10212 location for the QML file, and click \gui Export.
10216 The QML file is saved to the location that you specified.
10217 In Qt Creator, choose \gui {File > Open File or Project} to open the QML file.
10219 \note Existing files are replaced without warning.
10226 \contentspage index.html
10227 \previouspage quick-export-to-qml.html
10228 \page quick-application-logic.html
10229 \nextpage creator-qml-modules-with-plugins.html
10231 \title Implementing Application Logic
10233 A user interface is only a part of an application, and not really useful by itself.
10234 You can use Qt or JavaScript to implement the application logic. For more information on
10235 using JavaScript, see
10236 \l {http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html} {Integrating JavaScript}.
10238 For an example of how to use JavaScript to develop a game, see the
10239 \l {http://doc.qt.nokia.com/4.7/qml-advtutorial.html} {QML Advanced Tutorial}.
10245 \contentspage index.html
10246 \previouspage quick-application-logic.html
10247 \page creator-qml-modules-with-plugins.html
10248 \nextpage creator-using-qt-designer.html
10250 \title Using QML Modules with Plugins
10252 QML modules may use plugins to expose components defined in C++ to
10253 QML applications. Since Qt Creator cannot load the plugins to determine
10254 the details of the contained components, these modules need to provide
10255 extra type information for code completion and the semantic checks to work
10258 Ideally, QML modules have a \c{plugins.qmltypes} file in the same directory
10259 as the \c qmldir file. The \c qmltypes file contains a description of the
10260 components exported by the module's plugins and is loaded by Qt Creator
10261 when the module is imported.
10263 For Qt 4.8 and later, one or more \c qmltypes files can be listed in the
10264 \c qmldir file under the \c typeinfo header. These files will be read in addition
10265 to \c{plugins.qmltypes}. For more information, see
10266 \l{http://doc.qt.nokia.com/4.8-snapshot/qdeclarativemodules.html#writing-a-qmldir-file}{Writing a qmldir File}.
10268 \section1 Generating qmltypes Files
10270 You can create and edit \c qmltypes files manually, but you are recommended
10271 to use the \c qmlplugindump tool shipped with Qt 4.8 and later to generate
10272 them automatically. For earlier versions of Qt, you can compile a version
10273 of the tool called \c qmldump from the sources in
10274 \c{<QtCreator>/share/qtcreator/qml/qmldump} if the Qt version contains private headers.
10276 Once you have obtained qmlplugindump for the Qt version the QML module's
10277 plugins were compiled with, run the following command to load My.Module
10278 version 1.0 from \c{/import/path/my/module} including all its plugins and
10279 output a description of the plugins' types to
10280 \c{/import/path/my/module/plugins.qmltypes}:
10283 qmlplugindump My.Module 1.0 /import/path > /import/path/my/module/plugins.qmltypes
10286 You can safely ignore the debug output.
10288 \section1 Dumping Plugins Automatically
10290 If a module with plugins lacks the \c qmltypes file, Qt Creator tries to
10291 generate a temporary file itself by running the \c qmldump program in the
10292 background. However, this automatic dumping is a fallback mechanism with
10293 many points of failure and cannot be relied upon.
10298 \contentspage index.html
10299 \previouspage creator-editor-refactoring.html
10300 \page qt-quick-toolbars.html
10301 \nextpage creator-editor-locator.html
10303 \title Using Qt Quick Toolbars
10305 When you edit QML code in the code editor, you specify the properties
10306 of QML components. For some properties, such as colors and font names,
10307 this is not a trivial task. For example, few people can visualize the
10310 To easily edit these properties, you can use the Qt Quick Toolbars.
10311 When you select a component in the code and a toolbar is available,
10312 a light bulb icon appears:
10313 \inlineimage qml-toolbar-indicator.png
10314 . Select the icon to open the toolbar.
10316 To open toolbars immediately when you select a component, select
10317 \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar > Always show Quick
10320 Drag the toolbar to pin it to another location. Select
10321 \inlineimage qml-toolbar-pin.png
10322 to unpin the toolbar and move it to its default location. To pin toolbars
10323 by default, select \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar
10324 > Pin Quick Toolbar}.
10326 \section1 Previewing Images
10328 The Qt Quick Toolbar for images allows you to edit the properties of
10329 \l{http://doc.qt.nokia.com/latest/qml-borderimage.html}{Border Image}
10330 and \l{http://doc.qt.nokia.com/latest/qml-image.html}{Image} components.
10331 You can scale and tile the images, replace them with other images,
10332 preview them, and change the image margins.
10334 \image qml-toolbar-image.png "Qt Quick Toolbar for images"
10336 To preview an image, double-click it on the toolbar. In the preview
10337 dialog, you can zoom the image. Drag the image margins to change them.
10339 \image qml-toolbar-image-preview.png "Image preview dialog"
10341 \section1 Formatting Text
10343 The Qt Quick Toolbar for text allows you to edit the properties of
10344 \l{http://doc.qt.nokia.com/latest/qml-text.html}{Text} components.
10345 You can change the font family and size as well as text formatting, style,
10346 alignment, and color.
10348 If a property is assigned an expression instead of a value, you
10349 cannot use the toolbar to edit it. The button for editing the property
10352 \image qml-toolbar-text.png "Qt Quick Toolbar for text"
10354 By default, font size is specified as pixels. To use points, instead,
10355 change \gui px to \gui pt in the size field.
10357 \section1 Previewing Animation
10359 The Qt Quick Toolbar for animation allows you to edit the properties of
10360 \l{http://doc.qt.nokia.com/4.7/qml-propertyanimation.html}{PropertyAnimation}
10361 components and the components that inherit it. You can change the easing curve
10362 type and duration. For some curves, you can also specify amplitude, period,
10363 and overshoot values.
10365 \image qml-toolbar-animation.png "Qt Quick Toolbar for animation"
10367 Select the play button to preview your changes.
10369 \section1 Editing Rectangles
10371 The Qt Quick Toolbar for rectangles allows you to edit the properties of
10372 \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
10373 components. You can change the fill and border colors and add
10376 \image qml-toolbar-rectangle.png "Qt Quick Toolbar for rectangles"
10378 To add gradient stop points, click above the gradient bar. To remove
10379 stop points, drag them upwards.
10385 \contentspage index.html
10386 \previouspage creator-editor-external.html
10387 \page creator-maemo-emulator.html
10388 \nextpage creator-mime-types.html
10390 \title Using Maemo or MeeGo Harmattan Emulator
10392 The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
10393 of the \QSDK. After they are installed, you can start them from Qt Creator.
10395 The Maemo 5 emulator emulates the Nokia N900 device environment. You can test
10396 applications in conditions practically identical to running the application
10397 on a Nokia N900 device with software update release 1.3 (V20.2010.36-2).
10399 The MeeGo Harmattan emulator emulates the Nokia N9 device environment.
10401 With the emulators, you can test how your application reacts to hardware
10402 controls, such as the power button, and to the touch screen.
10404 To test the application UI, user interaction with the application, and
10405 functionality that uses the mobility APIs, use the Qt Simulator,
10406 instead. For more information, see the
10407 \l{http://doc.qt.nokia.com/qtsimulator/index.html}{Qt Simulator Manual}.
10409 The difference between Qt Simulator and the emulators is that when you
10410 compile your application binary for Qt Simulator, it is compiled against a
10411 host library. The binary run on the emulator is compiled for the actual
10412 device, using the Maemo 5 or Harmattan tool chain.
10414 \section1 Starting the Emulator
10416 The \gui {Start Maemo Emulator} button is visible if you have a project
10417 open in Qt Creator for which you have added the Maemo or MeeGo Harmattan
10418 build target. It starts the Maemo or MeeGo Harmattan emulator, depending
10419 on the selected target.
10421 To start the emulator, click
10422 \inlineimage qtcreator-maemo-emulator-button.png "Start Maemo Emulator button"
10425 Test your application on the Maemo emulator as on a device. For a list of
10426 keyboard shortcuts that you can use to emulate keys and functions, see
10427 \l {Emulating Device Keys}.
10429 \section1 Rendering Graphics
10431 The emulators support OpenGL to improve graphics rendering. Hardware
10432 acceleration produces better results than software rendering. By default,
10433 Qt Creator automatically detects, whether hardware acceleration is
10434 supported on the development PC and tries to use it. However, sometimes
10435 the results of the automatic detection are not reliable, and
10436 hardware acceleration might be selected even if it is actually not
10437 available on the development PC. This causes the emulator to crash.
10439 If the emulator crashes, you are asked whether you want to try software
10440 rendering, instead.
10442 To specify the OpenGL mode, select \gui {Tools > Options... > Linux Devices
10446 \section1 Emulating Device Keys
10448 The following table summarizes the keyboard shortcuts that you can use
10449 to emulate device keys and functions.
10454 \o Keyboard Shortcut
10465 \o Respective keys on the development PC keyboard.
10468 \o Left Shift key (Maemo 5)
10473 \o Left Ctrl key (Maemo 5)
10478 \o Left Alt key (Maemo 5)
10485 \o Keypad slider open and close
10488 \o Keypad lock (Maemo 5 only)
10491 \o Camera lens open and close (Maemo 5 only)
10497 \o Camera take picture
10500 \note The actual camera functionality is not emulated.
10502 \o Stereo headphones connect and disconnect (Maemo 5 only)
10511 \o Accelerometer x axis, negative
10514 \o Accelerometer x axis, positive
10517 \o Accelerometer z axis, negative
10520 \o Accelerometer z axis, positive
10523 \o Accelerometer y axis, negative
10526 \o Accelerometer y axis, positive
10531 \note Each press of the accelerometer key turns the acceleration by 50
10534 \section1 Closing the Emulator
10536 To close the emulator, click the X at the top right corner of the device
10537 emulator view. The emulator interprets this as a press of the power button
10538 and displays the text \e {Shutting down} in the emulator window title pane.
10539 The emulator closes shortly after this.
10541 You can also select the \gui {Start Maemo Emulator} button to close the
10542 emulator. This is a faster way to close the emulator, because it does not
10543 wait for the operating system running on the emulated machine to shut down,
10544 but this also means that it is less safe.
10550 \contentspage index.html
10551 \previouspage creator-version-control.html
10552 \page adding-plugins.html
10553 \nextpage creator-editor-external.html
10555 \title Adding Qt Designer Plugins
10557 You can use Qt APIs to create plugins that extend Qt applications.
10558 This allows you to add your own widgets to \QD.
10559 The most flexible way to include a plugin with an application is to compile it
10560 into a dynamic library that is shipped separately, and detected and loaded at runtime.
10562 The applications can detect plugins that are stored in the standard plugin
10563 subdirectories. For more information on how to create and locate plugins and to
10564 change the default plugin path, see \l{How to Create Qt Plugins}.
10566 For more information about how to create plugins for \QD, see
10567 \l{http://doc.qt.nokia.com/4.7/designer-using-custom-widgets.html}{Creating and Using Components for Qt Designer}.
10569 \section1 Locating Qt Designer Plugins
10571 \QD fetches plugins from the standard locations and loads the plugins
10572 that match its build key. \QD is delivered both as a standalone application
10573 and as part of the SDK, where it is integrated into Qt Creator.
10574 The correct folder to place the plugins depends on
10577 The integrated \QD fetches plugins from the \c {%SDK%\bin\designer} folder on Windows
10578 and Linux. For information about how to configure plugins on Mac OS, see
10579 \l{Configuring Qt Designer Plugins on Mac OS}.
10581 To check which plugins
10582 were loaded successfully and which failed, choose \gui{Tools > Form Editor >
10583 About Qt Designer Plugins}.
10585 The standalone \QD is part of the Qt library used for building projects,
10586 located under \c {%SDK%\qt}. Therefore, it fetches plugins from the following folder:
10587 \c {%SDK%\qt\plugins\designer}. To check which plugins were loaded successfully and which
10588 failed, choose \gui{Help > About Plugins}.
10590 \section2 Configuring Qt Designer Plugins on Mac OS
10592 On the Mac, a GUI application must be built and run from a bundle. A bundle is a
10593 directory structure that appears as a single entity when viewed in the Finder.
10594 A bundle for an application typcially contains the executable and all the resources
10597 Qt Creator uses its own set of Qt Libraries located in the bundle, and therefore,
10598 you need to configure the \QD plugins that you want to use with Qt Creator.
10599 Fore more information about how to deploy applications on Mac OS, see
10600 \l{http://doc.qt.nokia.com/4.7/deployment-mac.html}{Deploying an Application on Mac OS X}.
10602 The following example illustrates how to configure version 5.2.1 of the
10603 \l{http://qwt.sourceforge.net/}{Qwt - Qt Widgets for Technical Applications} library
10604 for use with Qt Creator:
10608 \o To check the paths used in the Qwt library, enter the following \c otool command:
10610 \snippet examples/doc_src_plugins.qdoc 0
10612 The output for Qwt 5.2.1 indicates that the plugin uses Qt core libraries (QtDesigner,
10613 QtScript, QtXml, QtGui and QtCore) and libqwt.5.dylib:
10615 \snippet examples/doc_src_plugins.qdoc 1
10618 \o You must copy the \QD plugin and the Qwt library files to the following locations:
10621 \o \c {libqwt_designer_plugin.dylib} to \c {QtCreator.app/Contents/MacOS/designer}
10622 \o \c {libqwt.*.dylib} to \c {QtCreator.app/Contents/Frameworks}
10625 Enter the following commands:
10627 \snippet examples/doc_src_plugins.qdoc 4
10629 \o Enter the following \c otool command to check the libraries that are used by the
10632 \snippet examples/doc_src_plugins.qdoc 2
10634 The command returns the following output:
10636 \snippet examples/doc_src_plugins.qdoc 3
10638 \o Enter the following \c install_name_tool command to fix the references of the
10641 \snippet examples/doc_src_plugins.qdoc 5
10646 \section1 Matching Build Keys
10648 The Qt Creator that is included in pre-built SDK packages on Windows is built with the
10649 Microsoft Visual Studio compiler, whereas the version of Qt shipped for building applications
10650 is configured and built to use the MinGW/g++ compiler. Plugins built by using this version of
10651 Qt cannot be loaded by Qt Creator because the build-keys do not match. The plugins can only be
10652 used in the standalone version of \QD. Choose \gui{Help > About Qt Creator} to check
10653 the Qt version Qt Creator was built with.
10655 To use \QD plugins that were built for the shipped Qt version, make sure that
10656 Qt Creator is built with the same compiler by either recompiling Qt Creator using MinGW or
10657 recompiling Qt with Microsoft Visual Studio, depending on which configuration you want to
10658 use for your applications.
10664 \contentspage index.html
10665 \previouspage creator-using-qt-designer.html
10666 \page creator-usability.html
10667 \nextpage creator-building-running.html
10669 \title Optimizing Applications for Mobile Devices
10671 Before starting application development, analyze and define the requirements, scope, and
10672 functionality of the application to ensure efficient functionality and a smooth user
10673 experience. Design the application for a single purpose and analyze how it can best serve
10674 its users. Mobile devices have been designed for use when mobile. Keep the characteristics
10675 of mobile devices in mind when you create applications for them.
10677 The following guidelines help you design and develop usable applications for mobile devices
10678 with varying characteristics, such as screen size and support for input methods:
10684 Find out who will use the application, what they will use it for,
10685 and which mobile devices they have. Then design the application to fit a specific context
10688 \o Design for small screens
10690 The screen size of mobile devices is significantly smaller
10691 than that available on desktop devices. Carefully consider what is the most relevant
10692 content to present on the application UI, as it might not be reasonable to try and fit as
10693 much content into the screen as you might have in a desktop application.
10695 \o Design for multiple screen sizes
10697 Relate the position and size of each control to the
10698 dimensions of the display. This enables the same set of information to be presented on the
10699 screen in all resolutions; higher resolution devices just display finer graphics.
10701 \o Design for changing screen orientation
10703 Some devices support screen rotation. On these
10704 devices, applications can be displayed in portrait or landscape orientation. Account for
10705 orientation and dynamically adjust the display when the screen is rotated.
10707 \o Design intuitive ways of moving within applications
10709 Mobile devices lack a mouse and
10710 full-size keyboard, so users must use the touch screen or five way navigation pad to move within
10711 applications. In addition, many users control the devices with one hand. To create an optimized user
10712 experience, allow users to access information with one click; do not make them scroll and type.
10714 \o Design for limited input methods
10716 Applications collect information from users on the task
10717 at hand. In addition to touch screen input, some devices contain physical keys such
10718 as a five way navigation pad, a keypad, and a keyboard. Users enter information by using screen
10719 controls, such as lists, check boxes, radio buttons, and text fields.
10721 \o Keep response times short
10723 Latency can cause delays in user interaction. If users perceive
10724 an application as being slow, they are likely to get frustrated and stop using it.
10726 \o Save battery time
10728 Mobile devices are not constantly connected to a power source but run on
10729 battery power. Optimize power consumption to keep the total consumption at an acceptable
10730 level and to prevent users from running out of battery time.
10732 \o Consider network issues
10734 If users do not have a flat-rate data plan or WLAN support, mobile
10735 network connections cost them money. Also, when users move around with the devices, the networks
10736 available for connections constantly change.
10738 \o Remember the processing limits of the device
10741 The memory available on devices is limited
10742 and you should use it carefully. Although all mobile devices have common functionality,
10743 each device is individual in terms of both the resources available and extra features.
10744 Therefore, you must consider the constraints of all the target devices.
10748 For more information about user experience techniques for mobile devices, see the
10749 \l{http://www.developer.nokia.com/Resources/Library/Design_and_UX} on Nokia Developer.
10755 \contentspage index.html
10756 \previouspage creator-faq.html
10757 \page creator-tips.html
10758 \nextpage creator-known-issues.html
10760 \title Tips and Tricks
10763 \section1 Switching Between Modes
10765 Qt Creator uses different modes for different purposes. You can quickly
10766 switch between these modes with the following keyboard shortcuts:
10768 \o \gui Welcome mode \key Ctrl+1
10769 \o \gui Edit mode \key Ctrl+2
10770 \o \gui Design mode \key Ctrl+3
10771 \o \gui Debug mode \key Ctrl+4
10772 \o \gui Projects mode \key Ctrl+5
10773 \o \gui Help mode \key Ctrl+6
10777 For more information about Qt Creator modes, see \l {Qt Creator Modes}.
10781 \section1 Moving Between Open Files
10783 To quickly move between currently open files, press
10786 To move forward in the location history, press \key {Alt+Right}
10787 (\key {Cmd+Opt+Right} on Mac OS). To move backward, press \key {Alt+Left}
10788 (\key {Cmd+Opt+Left} on Mac OS). For example, if you use the \gui Locator
10789 to jump to a symbol in the same file, you can jump back to your original
10790 location in that file by pressing \key {Alt+Left}.
10793 \section1 Moving To the Edit Mode
10795 To move to the \gui Edit mode and currently active file, press
10798 If you already are in the \gui Edit mode:
10800 \o The first press moves focus to the editor
10801 \o The second press closes secondary windows
10804 \section1 Using the Filter in Options Dialog
10806 To find specific settings you require in \gui{Tools} > \gui{Options...}
10807 use the filter located at the top left of the \gui Options dialog box.
10809 \section1 Opening Output Panes
10811 The output panes provide a list of errors and warnings encountered during
10812 a build, detailed output from the compiler, status of a program when it is
10813 executed and debug output, as well as search results.
10815 To open output panes, use the following shortcuts:
10819 \o \gui{Build Issues} pane Alt+1 (Cmd+1 on Mac OS X)
10821 \o \gui{Search Results} pane Alt+2 (Cmd+2 on Mac OS X)
10823 \o \gui{Application Output} pane Alt+3 (Cmd+3 on Mac OS X)
10825 \o \gui{Compile Output} pane Alt+4 (Cmd+4 on Mac OS X)
10829 For more information about output panes, see \l{Viewing Output}.
10832 \section1 Using Keyboard Shortcuts
10834 Qt Creator provides \l{Keyboard Shortcuts}{many useful keyboard shortcuts}.
10835 You can see the keyboard shortcut for a menu command in the menu
10836 or the tooltip for a button.
10838 To customize, import or export keyboard shortcuts, select \gui Tools >
10839 \gui Options... > \gui Environment > \gui Keyboard.
10842 \section1 Running Qt Creator From Command Line
10844 You can launch Qt Creator from command line using the name of an
10845 existing session or \c .pro file by giving the name as the command
10848 For example, running \tt{qtcreator somesession}, launches Qt Creator and
10849 loads session somesession.
10851 \note Make sure Qt Creator is included in the PATH environment variable.
10852 This can be done by typing the following in the command line:
10854 set PATH=c:\qtsdk\mingw\bin;c:\qtsdk\qt\bin;%PATH%
10858 \section1 Showing and Hiding the Sidebar
10860 To toggle the sidebar in the \gui Edit and \gui Debug modes, click
10861 \inlineimage qtcreator-togglebutton.png
10862 or press \key Alt+0 (\key Cmd+0 on Mac OS X).
10864 For more information on using the sidebar, see \l {Browsing Project Contents}.
10868 \section1 Moving To Symbols
10870 To move straight to a symbol used in a project, select the symbol in the
10871 \gui Editor toolbar drop-down menu. For more information on the editor toolbar,
10872 see \l {Using the Editor Toolbar}.
10874 To jump to a symbol in the current file, press \key {Ctrl+K} to open the
10875 \gui Locator, enter a period (.), and start typing the symbol name. Then
10876 select the symbol in the list. For more information on using the locator,
10877 see \l{Searching With the Locator}.
10879 Press \key Ctrl (\key Cmd on Mac OS) and click a symbol to move directly to
10880 the definition or the declaration of the symbol. You can also move the cursor
10881 on the symbol and press \key {F2}. For more information, see
10882 \l{Moving to Symbol Definition or Declaration}.
10886 \section1 Displaying Signals and Slots
10888 If an instance of a class is derived from QObject, and you would like to
10889 find all other objects connected to one of your object's slots using
10890 Qt's signals and slots mechanism, select \gui Tools > \gui Options...
10891 > \gui{Debugger} > \gui{Debugging Helper} > \gui{Use Debugging Helper}.
10893 In the \gui{Locals and Expressions} view, expand the object's entry and open
10894 the slot in the \e slots subitem. The objects connected to this slot are
10895 shown as children of the slot. This method works with signals too.
10897 For more information about the \gui{Locals and Expressions} view, see
10898 \l{Locals and Expressions}.
10901 \section1 Displaying Low Level Data
10903 If special debugging of Qt objects fails due to data corruption within the
10904 debugged objects, you can switch off the debugging helpers. When debugging
10905 helpers are switched off low-level structures become visible.
10907 To switch off the debugging helpers:
10910 \o Select \gui Tools > \gui Options... > \gui Debugger >
10911 \gui{Debugging Helper}.
10912 \o Uncheck the \gui{Use Debugging Helper} checkbox.
10916 \section1 Showing Tooltips in Debug Mode
10918 To inspect the value of variables from the editor, you can turn
10919 on tooltips. Tooltips are hidden by default for performance reasons.
10922 \o Select \gui Tools > \gui Options... > \gui Debugger > \gui General.
10923 \o Select the \gui {Use tooltips in main editor while debugging} check box.
10926 When you hover over a variable in the code editor in \gui Debug mode, a
10927 tooltip is displayed. To keep the tooltip visible, click the pin button.
10928 You can expand pinned tooltips to view their full content.
10930 \image qtcreator-pin-tooltip.png
10932 Pinned tooltips are stored in the session. To close all pinned tooltips,
10933 select \gui {Close Editor Tooltips} in the context menu in the \gui {Locals
10934 and Expressions} view.
10937 \section1 Locating Files
10939 The \gui Locator provides one of the easiest ways in Qt Creator to browse
10940 through projects, files, classes, methods, documentation and file systems.
10941 To quickly access files not directly mentioned in your project, you can
10942 create your own locator filters. That way you can locate files in a
10943 directory structure you have defined.
10945 To create locator filters, select \gui {Tools > Options... > Locator > Add}.
10947 For more information, see \l{Creating Locator Filters}.
10949 \section1 Adding a License Header Template for C++ Code
10951 A file containing a license header for C++ can be specified under
10952 \gui{Tools > Options... > C++ > License Template}. It may contain special
10953 placeholders enclosed in \c{%%} that are replaced when generating a
10958 \o \c %MONTH%: Month
10959 \o \c %DAY%: Day of the month
10961 \o \c %USER%: User name
10962 \o \c %FILENAME%: File name
10963 \o \c %CLASS%: Class name (if applicable)
10964 \o \c %$VARIABLE%: Contents of environment variable \c{VARIABLE}.
10971 \contentspage index.html
10972 \previouspage creator-cli.html
10973 \page creator-keyboard-shortcuts.html
10974 \nextpage creator-faq.html
10976 \title Keyboard Shortcuts
10978 Qt Creator provides various keyboard shortcuts to speed up your development
10982 \section1 Configuring Keyboard Shortcuts
10984 To customize a keyboard shortcut:
10986 \o Select \gui Tools > \gui Options... > \gui Environment >
10988 \o Select an action from the list.
10989 \o In \gui{Key Sequence} enter the shortcut key you want to associate
10990 with the selected action.
10993 Qt Creator allows you to use different keyboard shortcut mapping schemes:
10995 \o To import a keyboard shortcut mapping scheme, click \gui Import
10996 and select the kms file containing keyboard shortcut mapping scheme
10997 you want to import.
10998 \o To export the current keyboard shortcut mapping scheme, click
10999 \gui Export and select the location where you want to save the
11004 \section1 Default Keyboard Shortcuts
11006 The following tables list the default keyboard shortcuts. They are
11007 categorized by actions.
11010 \section2 General Keyboard Shortcuts
11015 \o Keyboard shortcut
11017 \o Open file or project
11020 \o New file or project
11023 \o Open in external editor
11059 \o Next open document in history
11062 \o Goto other split
11065 \o Previous open document in history
11068 \o Activate \gui Locator
11071 \o Switch to \gui Welcome mode
11074 \o Switch to \gui Edit mode
11077 \o Switch to \gui Design mode
11080 \o Switch to \gui Debug mode
11083 \o Switch to \gui Projects mode
11086 \o Switch to \gui Help mode
11089 \o Toggle \gui{Build Issues} pane
11090 \o Alt+1 (Cmd+1 on Mac OS X)
11092 \o Toggle \gui{Search Results} pane
11093 \o Alt+2 (Cmd+2 on Mac OS X)
11095 \o Toggle \gui{Application Output} pane
11096 \o Alt+3 (Cmd+3 on Mac OS X)
11098 \o Toggle \gui{Compile Output} pane
11099 \o Alt+4 (Cmd+4 on Mac OS X)
11101 \o Activate \gui Bookmarks pane
11104 \o Activate \gui{File System} pane
11107 \o Activate \gui{Open Documents} pane
11110 \o Activate \gui Projects pane
11116 \o Toggle the sidebar
11117 \o Alt+0 (Cmd+0 on Mac OS X)
11122 \o Move to \gui Edit mode
11126 \o The first press moves focus to the editor
11127 \o The second press closes secondary windows
11133 \section2 Editing Keyboard Shortcuts
11138 \o Keyboard shortcut
11140 \o Auto-indent selection
11149 \o Trigger a completion in this scope
11164 \o Decrease font size
11165 \o Ctrl+- (Ctrl+Roll mouse wheel down)
11167 \o Increase font size
11168 \o Ctrl++ (Ctrl+Roll mouse wheel up)
11170 \o Toggle Vim-style editing
11176 \o Split side by side
11179 \o Remove all splits
11182 \o Remove current split
11191 \o Go to block start
11194 \o Go to block end with selection
11197 \o Go to block start with selection
11200 \o Move current line down
11203 \o Move current line up
11206 \o Trigger a quick fix in this scope
11209 \o Rewrap paragraph
11212 \o Select the current block
11214 The second press extends the selection to the parent block
11217 \o Enable text wrapping
11220 \o Toggle comment for selection
11223 \o Visualize whitespace
11232 \o Lay out in a grid
11235 \o Lay out horizontally
11238 \o Lay out vertically
11244 \o Edit signals and slots
11253 \o Go to next bookmark
11256 \o Go to previous bookmark
11268 \o Follow symbol under cursor
11270 Works with namespaces, classes, methods, variables, include
11271 statements and macros
11274 \o Rename symbol under cursor
11277 \o Switch between method declaration and definition
11280 \o Open type hierarchy
11283 \o Switch between header and source file
11286 \o Turn selected text into lowercase
11289 \o Turn selected text into uppercase
11293 \section2 Debugging Keyboard Shortcuts
11298 \o Keyboard shortcut
11303 \o Stop or interrupt debugger
11318 \o Toggle breakpoint
11321 \o Run to selected function
11326 \section2 Project Keyboard Shortcuts
11331 \o Keyboard shortcut
11347 \section2 Help Keyboard Shortcuts
11352 \o Keyboard shortcut
11354 \o View context-sensitive help
11357 \o Activate contents in \gui Help mode
11360 \o Add bookmark in \gui Help mode
11363 \o Activate index in \gui Help mode
11366 \o Reset font size in \gui Help mode
11369 \o Activate search in \gui Help mode
11374 \section2 Version Control Keyboard Shortcuts
11379 \o {5,1} Version control system
11410 \o Alt+G, Alt+Shift+D
11452 \o Alt+G, Alt+Shift+D
11489 \contentspage index.html
11490 \previouspage technical-support.html
11491 \page creator-glossary.html
11492 \nextpage creator-acknowledgements.html
11504 Qt in PATH
11506 \target glossary-system-qt
11508 version for the \c qmake command found in your \c PATH
11509 environment variable.
11510 This is likely to be the system's Qt version.
11518 \target glossary-project-qt
11519 \o The version of Qt configured in the \gui{Projects} mode, \gui {Build
11520 Settings}, \gui {Qt Version} field. This is the Qt version that
11521 is actually used by a particular project.
11528 \target glossary-shadow-build
11529 \o Shadow building means building a project in a separate
11530 directory, the \e{build directory}. The build directory is
11531 different from the source directory. One of the benefits of
11532 shadow building is that it keeps your source directory clean.
11533 Shadow building is the best practice if you need many build
11534 configurations for a single set of source.
11541 \contentspage index.html
11542 \previouspage creator-tips.html
11543 \page creator-known-issues.html
11544 \nextpage technical-support.html
11546 \title Known Issues
11548 This section lists known issues in Qt Creator version 2.2.0.
11549 The development team is aware of them, and therefore, you do not need to
11550 report them as bugs.
11552 For a list of fixed issues and added features, see the changelog file in
11553 the \c{qtcreator\dist} folder or the \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}.
11555 \section1 General Issues
11559 \o If you change the Input Languages in Windows, Qt Creator might not
11560 respond for 30 seconds. This is a known issue in the Advanced Text
11561 Service of Microsoft Windows.
11563 \o Qt Creator uses SQLite for storing some of its settings. SQLite is
11564 known to have problems with certain NFS servers (most notably the
11565 nfs-user-server 2.2beta), since they can lock up the application
11566 when it tries to lock the database. If your home directory is on an
11567 NFS share and you encounter this issue, one option would be to
11568 switch to the nfs-kernel-server, or create a symlink so that the
11569 settings are stored locally.
11571 \o The Okteta KDE custom widget plugin might be installed as part of
11572 some Linux distributions. It can cause Qt Designer to crash. For
11573 more information, see:
11577 \o \l{https://bugs.launchpad.net/ubuntu/+source/kdeutils/+bug/662005}{Ubuntu bug 662005}
11578 \o \l{http://bugreports.qt.nokia.com/browse/QTBUG-12025}{QTBUG-12025}
11582 To resolve the issue, enter the following command to remove the package:
11584 sudo apt-get remove okteta
11586 Or delete the following file:
11587 \c /usr/lib/kde4/plugins/designer/oktetadesignerplugin.so.
11591 \section1 Editing Issues
11595 \o Code completion does not support typedefs for nested classes.
11599 \section1 Projects Issues
11602 \o Paths or file names containing spaces or special characters
11603 (such as colons, dollar signs, and hash marks) may cause problems. This
11604 is because some of the tools Qt Creator uses in the background have
11605 restrictions on the characters allowed in file and directory names.
11606 To be on the safe side, we recommend creating projects and project
11607 items with names consisting of plain characters, numbers,
11608 underscores, and hyphens.
11610 \o Creating new CMake projects with Qt Creator is not supported.
11612 \o On Windows, you must create projects for Maemo 5 and Harmattan
11613 targets on the same partition where
11614 you installed \QSDK, Qt Creator, and MADDE.
11616 \o If error messages displayed in the \gui {Compile Output} pane contain
11617 paths where slashes are missing (for example, C:QtSDK),
11618 check your PATH variable. For more information, see
11619 \l{Troubleshooting MinGW Compilation Errors}.
11623 \section1 Debugging Issues
11627 \o Debugging large applications on Symbian devices using the Symbian^3
11628 operating system might not work, because the on-device debugging agent
11629 might not be able to
11630 access memory when the operating system starts paging. This causes breakpoint
11631 handling and symbol resolution to fail. For more information, see
11632 \l{http://bugreports.qt.nokia.com/browse/QTCREATORBUG-2158}{QTCREATORBUG-2158}.
11634 As a workaround, add the following section to the application .pro file to
11640 MMP_RULES *= UNPAGED
11644 \note You must completely clean and rebuild the project for the setting to
11647 \o When debugging executables created by the GNU Compiler version 4.5.0
11648 (all platforms), some data types will not be displayed in the
11649 \gui{Locals and Expressions} view due to missing debug information.
11651 \o GDB on Windows may not work if the 'Embassy \reg Security Center' software
11652 by 'Wave \reg Systems' is installed and active (causing crashes in \c{vxvault.dll)}).
11654 \o GDB may take long to load debugging symbols, especially from large
11657 \o Setting breakpoints in code that is compiled into the binary more
11658 than once does not work.
11660 \o Setting breakpoints in files that do not have unique absolute
11661 paths may fail. For example, remounting parts of a file system
11662 using the --bind mount option.
11666 \section1 Qt Quick Designer Issues
11670 \o \QMLD uses external processes (QML Puppet) to render and preview
11671 images and to collect data. Executing C++ code might cause the QML
11672 Puppet to crash. If it crashes, an error message is displayed and
11673 you can continue editing the QML file in the code editor.
11680 \contentspage index.html
11681 \previouspage creator-glossary.html
11682 \page creator-acknowledgements.html
11684 \title Acknowledgements
11686 \section1 Third-party Components
11688 Qt Creator contains the following third-party components:
11691 \o \bold{Open Source front-end for C++ (license MIT)}, enhanced for use in
11693 Roberto Raggi <roberto.raggi@gmail.com>\br
11694 QtCreator/src/shared/cplusplus\br\br
11696 \o \bold{Botan, a C++ crypto library. Version 1.8.8}\br
11698 \o Copyright (C) 1999-2004 The Botan Project. All rights reserved.
11699 \o Copyright (C) 1999-2009 Jack Lloyd
11700 \o 2001 Peter J Jones
11701 \o 2004-2007 Justin Karneges
11702 \o 2005 Matthew Gregan
11703 \o 2005-2006 Matt Johnston
11704 \o 2006 Luca Piccarreta
11705 \o 2007 Yves Jerschow
11706 \o 2007-2008 FlexSecure GmbH
11707 \o 2007-2008 Technische Universitat Darmstadt
11708 \o 2007-2008 Falko Strenzke
11709 \o 2007-2008 Martin Doering
11710 \o 2007 Manuel Hartl
11711 \o 2007 Christoph Ludwig
11712 \o 2007 Patrick Sona
11714 All rights reserved.\br\br
11716 Redistribution and use in source and binary forms, with or without
11717 modification, are permitted provided that the following conditions are
11720 1. Redistributions of source code must retain the above copyright
11721 notice, this list of conditions, and the following disclaimer.\br\br
11723 2. Redistributions in binary form must reproduce the above copyright
11724 notice, this list of conditions, and the following disclaimer in the
11725 documentation and/or other materials provided with the distribution.\br
11728 THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND ANY EXPRESS OR
11729 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
11730 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE,
11731 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE
11732 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
11733 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
11734 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
11735 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
11736 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
11737 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
11738 IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\br\br
11739 The source code of Botan C++ crypto library can be found
11742 \o QtCreator/src/libs/3rdparty
11743 \o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
11747 \o \bold{NetSieben SSH Library is a Secure Shell client library for C++.
11750 \o \bold{Commercial License:} For organizations who do not want to
11751 release the source code for their applications as open source/
11752 free software; in other words they do not want to comply with the
11753 GNU General Public License (GPL) or Q Public License.
11754 \o \bold{Non Commercial / Open Source License:} NetSieben believes in
11755 contributing back to the open source community, thus it has released
11756 the SSH Library under Q Public License as it is defined by Trolltech
11757 AS of Norway. The Open Source License allows the user to use software
11758 under an open source / free software license, and distribute it
11759 freely. The software can be used at no charge with the condition
11760 that if the user uses the SSH Library in an application they wish to
11761 redistribute, then the complete source code for your application must
11762 be available and freely redistributable under reasonable conditions.
11763 For more information on the used QPL License see:
11764 QtCreator/src/libs/3rdparty/net7ssh/LICENSE.QPL
11766 The source code of NetSieben Secure Shell C++ Library can be found
11769 \o QtCreator/src/libs/3rdparty
11770 \o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
11777 \contentspage index.html
11778 \previouspage creator-mime-types.html
11779 \page creator-task-lists.html
11780 \nextpage creator-cli.html
11782 \title Showing Task List Files in the Build Issues Pane
11784 Code scanning and analysis tools create report files in ASCII format.
11785 Usually, the report files consist of lines that contain a file name, a line
11786 number, and an error message. A similar format is used for stack traces
11787 obtained from crash reports. Traditionally, you would fix the errors by
11788 manually navigating to them and correcting them, which is tedious.
11790 Qt Creator makes this very easy by providing a way to load these files into
11791 the \gui{Build Issues} pane. You can navigate to the corresponding source
11792 code by clicking the error message. But first you must convert the files to
11793 the \l{Task List File Format} by using conversion scripts that based on
11794 standard text processing tools of the operating system.
11796 In addition, you can generate task list files from code.
11797 For an example of a script that checks new lines of code and matches them
11798 against regular expressions to generate a task list, see \c{scripts\mytasks.pl}
11799 in the Qt Creator repository.
11801 To open task list files, choose \gui{File} > \gui{Open}.
11803 \section1 Task List File Format
11805 The filename extension must be .tasks for Qt Creator to recognize a file as a
11808 Each line in a task list file is treated as a tab-separated list of strings with
11809 \c{\t}, \c{\n}, and \c{\\} used as escape characters. The strings are used to create
11810 one task per line. The lines can have one of the following formats:
11816 \o \c{type\tdescription}
11818 \o \c{file\ttype\tdescription}
11820 \o \c{file\tline\ttype\tdescription}
11824 The task type can have one of the following values:
11828 \o A string starting with \c err, which displays the error icon in the beginning of the line
11829 \o A string starting with \c warn, which displays the warning icon
11830 \o Any other value, which sets the task type to Unknown and does not
11835 The values are not case sensitive.
11837 Lines starting with the hash mark character (#) in the first column are ignored.
11843 \contentspage index.html
11844 \previouspage creator-task-lists.html
11845 \page creator-cli.html
11846 \nextpage creator-keyboard-shortcuts.html
11848 \title Using Command Line Options
11850 You can start Qt Creator and specify some options from the command line.
11851 For example, you can open a file to any line.
11853 To specify command line options, enter the following command in the Qt Creator
11854 installation or build directory:
11856 \c {qtcreator [option] [filename[:line_number]]}
11858 \note You can use either a colon (:) or a plus sign (+) as a separator
11859 between the filename and line number. You can also use a space between the
11860 separator and the line number.
11866 \o \c {C:\qtcreator\bin>qtcreator -help}
11868 \o \c {C:\qtcreator\bin>qtcreator C:\TextFinder\textfinder.cpp:100}
11870 \o \c {C:\qtcreator\bin>qtcreator C:\TextFinder\textfinder.cpp +100}
11874 The following table summarizes the available options:
11883 \o Display help on command line options.
11887 \o Display Qt Creator version.
11891 \o Attempt to connect to an already running instance of Qt Creator.
11894 \o -noload <plugin>
11895 \o Do not load the specified plugin.
11899 \o Output plugin start up and shut down profiling data.
11902 \o -settingspath <path>
11903 \o Override the default path where user settings are stored.
11907 \o Core plugin: override the selected UI color.
11911 \o Debugger plugin: disable the Microsoft Console Debugger (CDB)
11912 engine. For more information, see \l{Debugging}.
11916 \o Debugger plugin: disable the GNU Symbolic Debugger (GDB) engine.
11920 \o Debugger plugin: disable the Qt Script debugger engine.
11923 \o -debug <PID-or-corefile>
11924 \o Debugger plugin: attach to process ID or core file.
11927 \o -wincrashevent <event-handle>
11928 \o Debugger plugin: Attach to crashed processes by using the specified
11932 \o -customwizard-verbose
11933 \o ProjectExplorer plugin: display additional information when loading
11934 custom wizards. For more information about custom wizards, see
11935 \l{Adding New Custom Wizards}
11939 \o ProjectExplorer plugin: load the last session when Qt Creator starts.
11940 Open the projects and files that were open when you last exited Qt Creator.
11941 For more information about managing sessions, see \l{Managing Sessions}.
11950 \contentspage index.html
11951 \previouspage creator-maemo-emulator.html
11952 \page creator-mime-types.html
11953 \nextpage creator-task-lists.html
11955 \title Editing MIME Types
11957 Qt Creator uses the
11958 \l{http://en.wikipedia.org/wiki/Internet_media_type}{Internet media type}
11959 (MIME type) of the file to determine which mode and editor to use for
11960 opening the file. For example, Qt Creator opens C++ source and header files
11961 in the C++ editor, and Qt widget based UI files (.ui) in \QD.
11963 To identify the MIME type of a file, Qt Creator uses matching by pattern
11964 and matching by contents. First, Qt Creator looks at the filename to check
11965 whether it matches the patterns specified for any MIME type. If no match is
11966 found, it checks the contents of the file for magic headers specified for the
11969 The magic headers can contain text strings or bytes. The type of the
11970 header value, string or byte, determines how Qt Creator interprets the
11971 value. Qt Creator searches for the value within a specified
11972 range in the files and takes the priority of the magic header into account.
11973 If you specify wide search ranges, openging files in Qt Creator might take
11974 a long time. Therefore, you are advised to use the recommended values for
11975 the range and priority of the magic header.
11977 If your files do not match the predefined MIME types, you can edit the
11978 MIME types to add filename extensions and magic headers. You cannot
11979 add new MIME types, however.
11981 To edit MIME types:
11985 \o Select \gui {Tools > Options... > Environment > MIME Types}.
11987 \image qtcreator-mime-types.png "MIME Types"
11989 \o In \gui {MIME Type}, select a MIME type.
11991 \o In \gui Patterns, add the filename extension for the type of files
11992 that you want to identify as having this MIME type.
11994 \o Click \gui Add to add \gui {Magic Headers}.
11996 \image qtcreator-mime-types-magic-header.png "Magic Header"
11998 \o In the \gui Value field, specify a text string or bytes that
11999 appear in the files.
12001 \o In the \gui Type field, select the type of the value.
12003 \note You are recommended not to change the range and priority, because
12004 it might cause problems when opening files in Qt Creator.
12010 To revert all the changes you have made to the MIME type definitions,
12011 select \gui {Reset All}.
12013 \note If you now select \gui OK or \gui Apply, you permanently lose all
12014 your own patterns and magic headers. The changes are reverted the next
12015 time you start Qt Creator.
12021 \contentspage index.html
12022 \previouspage creator-debugging-qml.html
12023 \page creator-troubleshooting-debugging.html
12024 \nextpage creator-analyze-mode.html
12026 \title Troubleshooting Debugger
12028 This section lists some typical problems that you might encounter while
12029 debugging and solutions to them.
12031 \section1 Cannot Launch Debugger
12033 Some anti-virus applications do not allow debuggers to retrieve data. For
12034 example, on Windows, launching the debugger might fail with the following
12035 message if the Avira AntiVir is installed on the development PC: \e{The
12036 inferior stopped because it received a signal from the operating system.
12037 Signal name:? signal meaning: Unknown signal.}
12039 Some versions of Avira AntiVir Desktop-Products contain known issues in
12040 various development environments, including Qt Creator. To fix the problem,
12041 Avira instructs you to update to version \c {avipbb.sys 10.0.22.22}. For
12042 more information, see
12043 \l{http://www.avira.com/en/support-for-business-knowledgebase-detail/kbid/805}{Restricted Usability of IDE/Debuggers since 2010-12-08}.
12045 \section1 Debugger Does Not Hit Breakpoints
12047 You might have created a release build that does not contain debug
12048 information. A GNU Compiler Collection (GCC) debug build has the \c {-g}
12049 option on the compiler command line. Check that this option is present in
12050 the \gui {Compile Output} pane. If it is not, adjust your build settings
12051 in the \gui {Projects} mode.
12053 \section1 Debugger Does Not Work
12055 If the debugger does not work properly, try the following:
12059 \o Make sure you use at least Qt Creator 2.1.
12061 \o Make sure the debugger is set up properly. For more information,
12062 see \l{Setting Up Debugger}.
12064 \o In the \gui Debug mode, select \gui {Windows > Views > Debugger
12065 Log} to open the \gui {Debugger Log} view. Browse the contents of
12066 the pane on the right hand side to find out what went wrong.
12067 Always attach the contents of the pane to debugger-related
12068 questions to the Qt Creator mailing list (qt-creator@trolltech.com)
12070 \l{http://creator.pastebin.com}{creator.pastebin.com} before
12071 asking questions in the IRC (on the #qt-creator channel at
12076 \section1 Pointer Variable Members Are Not Displayed Directly
12078 When you use the \gui {Locals and Expressions} view to inspect a pointer
12079 variable and expand the variable tree item, another tree item level
12080 is displayed. To directly display the members of the pointer variable,
12081 select \gui {Dereference Pointers Automatically} in the context menu in the
12082 \gui {Locals and Expressions} view.
12084 \section1 Built-in Debugger Is Slow During Startup and Runtime
12086 The Qt Creator for Windows installation packages install GDB from MinGW.
12087 Unfortunately, GDB is quite slow on Windows. Qt Creator does not cause
12088 this, as it interacts with GDB and adds custom dumpers for Qt types.
12090 \note You can use Qt Creator with MSVC on Windows for debugging.
12092 \section1 Debugger Displays <not in scope> Message
12094 The message is created by the debugging helpers. Qt Creator posts an
12095 expression to the GDB command line to invoke the debugging helpers.
12096 The expression includes the address of the object to examine. This
12097 address might be modified by GDB before the helper function is called. It
12098 is unclear why and when this happens, but if it happens, the debugging
12099 helpers operate on wrong data and come to wrong conclusions. Most likely,
12100 they find garbage and declare the variable to be <not in scope>.
12102 \section1 Application Crashes when Debugging on Mac OS X Snow Leopard
12104 You must use a workaround to use the DYLD_IMAGE_SUFFIX option in the
12105 \gui Projects tab on Mac OS X Snow Leopard. For more information on the
12107 \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}.
12109 To use the option, enter the following commands in the Terminal
12112 sudo mv /usr/lib/libSystem.B_debug.dylib /usr/lib/libSystem.B_debug.dylib.backup
12113 sudo cp /usr/lib/libSystem.B.dylib /usr/lib/libSystem.B_debug.dylib.backup
12116 \section1 Debugger Cannot Attach to Running Process on Linux
12118 GDB uses \c ptrace to attach to running processes. Some Linux distributions
12119 do not allow this, which stops all attempts to either directly attach to an
12120 existing process or use the \gui {Run in terminal} option in Qt Creator.
12122 The reasons for this are described in
12123 \l{https://wiki.ubuntu.com/SecurityTeam/Roadmap/KernelHardening#ptrace%20Protection}{KernelHardening}.
12125 However, the usefulness of this security measure seems dubious,
12126 because this feature can be easily disabled. With root permissions, you can
12127 disable the feature immediately by writing \c{0} into
12128 \c{/proc/sys/kernel/yama/ptrace_scope}. Even if you do not have elevated
12129 permissions, you can disable the feature later by adding a library that
12130 calls \c{prctl(0x59616d61, getppid(), 0, 0, 0);}, such as the one in
12131 \c{$QTCREATORDIR/lib/libptracepreload.so} to the LD_PRELOAD environment.
12137 \contentspage index.html
12138 \previouspage creator-qml-performance-monitor.html
12139 \page creator-analyzer.html
12140 \nextpage creator-cache-profiler.html
12142 \title Detecting Memory Leaks
12144 You can use the Memcheck tool included in the
12145 \l{http://valgrind.org/info/tools.html}{Valgrind tool suite} to detect
12146 problems that are related to memory management in applications.
12148 \note Memcheck is supported on Linux and Mac OS.
12150 After you download and install Valgrind tools, you can use Memcheck from Qt
12152 To analyze applications:
12156 \o In the \gui Projects mode, select a release build configuration.
12158 \o Select \gui Analyze to open the \gui Analyze mode.
12160 \o Select \gui {Analyze Memory} on the toolbar.
12163 \inlineimage qtcreator-analyze-start-button.png "Start button"
12164 button to start the application.
12166 \o Use the application to analyze it.
12169 \inlineimage qtcreator-analyzer-stop-button.png "Stop button"
12170 button to view the results of the analysis in the
12171 \gui {Analysis} view.
12175 While the application is running, Memcheck checks all reads and writes of
12176 memory and intercepts calls that allocate or free memory or create or
12177 delete memory blocks. When you stop Memcheck, it displays the results in
12178 the \gui Analysis output pane. Click a line to view where a memory leak
12179 occurred and a stack trace that shows what caused it.
12181 \image analyzer-issues.png "Analysis view"
12183 Move the mouse on on a row to view more information about the function.
12185 For more information about using Memcheck, see
12186 \l{http://valgrind.org/docs/manual/quick-start.html#quick-start.mcrun}
12187 {Interpreting Memcheck's Output} in the Valgrind documentation.
12189 \section1 Selecting Options for Memory Analysis
12191 Stack traces can get quite large and confusing, and therefore, reading them
12192 from the bottom up can help. If the stack trace is not big enough or it is
12193 too big, select \gui {Tools > Options... > Analyzer > Memory Analysis}.
12194 Define the length of the stack trace in the \gui {Backtrace frame count}
12197 Memcheck also reports uses of uninitialised values, most commonly with the
12198 message \gui {Conditional jump or move depends on uninitialised value(s).}
12199 To determine the root cause of these errors, the \gui {Track origins of
12200 uninitialized memory} check box is selected by default. This makes Memcheck
12201 run slower, but the extra information you get often saves a lot of time
12202 figuring out where the uninitialised values are coming from.
12204 Memcheck detects numerous problems in the system libraries, such as the C
12205 library, which come pre-installed with your OS. As you cannot easily fix
12206 them, you want to suppress them. Valgrind reads a list of errors to suppress
12207 at startup. A default suppression file is created by the ./configure script
12208 when the system is built.
12210 You can write your own suppression files if parts of your project contain
12211 errors you cannot fix and you do not want to be reminded of them. Click
12212 \gui Add in the \gui {Memory Analysis} dialog to add the suppression files.
12213 For more information about writing suppression files, see
12214 \l{http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress}
12215 {Suppressing Errors} in the Valgrind documentation.
12217 \image qtcreator-valgrind-memcheck-options.png "Memory Analysis options"
12224 \contentspage index.html
12225 \previouspage creator-analyzer.html
12226 \page creator-cache-profiler.html
12227 \nextpage creator-deployment.html
12229 \title Profiling Function Execution
12231 You can use the Callgrind tool included in the
12232 \l{http://valgrind.org/info/tools.html}{Valgrind tool suite} to detect
12233 problems that are related to cache usage.
12235 After you download and install Valgrind tools, you can use Callgrind from Qt
12237 To analyze applications:
12241 \o In the \gui Projects mode, select a release build configuration.
12243 \o Select \gui Analyze to open the \gui Analyze mode.
12245 \o Select \gui Profile on the toolbar.
12248 \inlineimage qtcreator-analyze-start-button.png "Start button"
12249 button to start the application.
12251 \o Use the application to analyze it.
12254 \inlineimage qtcreator-analyzer-stop-button.png "Stop button"
12255 button to view the results of the analysis in the \gui Profile
12260 Callgrind records the call history of functions that are executed when the
12261 application is run. It collects the number of instructions that are
12262 executed, their relationship to source lines, the relationships of the
12263 caller and callee between functions, and the numbers of such calls. You can
12264 also use cache simulation or branch prediction to gather information about
12265 the runtime behavior of an application.
12267 Double-click a function to view information about the calling functions in
12268 the \gui Callers view and about the called functions in the \gui Callees
12271 \image qtcreator-valgrind-callgrind.png "Profile view"
12273 \section1 Selecting Profiling Options
12275 To specify settings for Callgrind, select \gui {Tools > Options... >
12276 Analyzer > Profiling}.
12278 \image qtcreator-valgrind-callgrind-options.png "Profiling options"
12280 In the \gui {Result view: Show events with inclusive costs higher than}
12281 field, limit the amount of results the profiler gives you to increase
12282 profiler performance.
12284 You can collect information about the system call times and the number of
12285 global bus events of the event type \c Ge that are executed.
12287 \section2 Enabling Full Cache Simulation
12289 By default, only instruction read accesses (Ir) are counted. To fully
12290 simulate the cache, select the \gui {Enable cache simulation} check box.
12291 This enables the following additional event counters:
12295 \o Cache misses on instruction reads (I1mr/I2mr)
12297 \o Data read accesses (Dr) and related cache misses (D1mr/D2mr)
12299 \o Data write accesses (Dw) and related cache misses (D1mw/D2mw)
12303 \section2 Enabling Branch Prediction Simulation
12305 To enable the following additional event counters, select the
12306 \gui {Enable branch prediction simulation} check box:
12310 \o Number of conditional branches executed and related predictor misses
12313 \o Executed indirect jumps and related misses of the jump address
12322 \contentspage index.html
12323 \previouspage creator-help.html
12324 \page creator-advanced.html
12325 \nextpage creator-os-supported-platforms.html
12327 \title Advanced Use
12329 Qt Creator attempts to meet your development needs, whether you are an
12330 experienced Qt developer or a newcomer to Qt. When you install Qt Creator
12331 as a part of \QSDK, the default configuration allows you to start coding,
12332 building, running and debugging applications with very little effort.
12334 However, you can easily change or extend the default configuration, by
12335 choosing a different build system, adding project wizards, integrating
12336 external tools, or editing the standard MIME types that Qt Creator uses
12337 to recognize your files.
12339 You can start Qt Creator and specify some options for running it from the
12342 This following topics describe advanced use of Qt Creator:
12345 \o \l{Operating Systems and Supported Platforms}
12346 \o \l{Adding New Custom Wizards}
12347 \o \l{Setting Up a CMake Project}
12348 \o \l{Setting Up a Generic Project}
12349 \o \l{Using Version Control Systems}
12350 \o \l{Adding Qt Designer Plugins}
12351 \o \l{Using External Tools}
12352 \o \l{Using Maemo or MeeGo Harmattan Emulator}
12353 \o \l{Editing MIME Types}
12354 \o \l{Showing Task List Files in the Build Issues Pane}
12355 \o \l{Using Command Line Options}
12356 \o \l{Keyboard Shortcuts}
12363 \contentspage index.html
12364 \previouspage creator-known-issues.html
12365 \page technical-support.html
12366 \nextpage creator-glossary.html
12368 \title Technical Support
12370 The following table lists Qt support sites and other useful links.
12374 \o What Do You Want to Do
12378 \o Learn more about Qt
12379 \o \l{http://qt.nokia.com/developer/learning/online/training/specialized-elearning/}
12380 {Specialized eLearning Modules Based on Qt Training Modules}
12383 \o Develop Qt applications for desktop and mobile devices
12384 \o \l{http://developer.qt.nokia.com/}{Qt Developer Network}
12387 \o Develop Qt applications for Nokia mobile devices
12388 \o \l{http://www.developer.nokia.com/Develop/Qt/}{Nokia Developer - Qt}
12391 \o Participate in Qt development
12392 \o \l{http://qt.gitorious.org/}{Qt Git Hosting}
12395 \o Find free Qt-based applications
12396 \o \l{http://qt-apps.org/}{Qt Apps}
12399 \o Buy commercial Qt support from Digia
12400 \o \l{http://qt.digia.com/}{Qt Commercial}
12407 \contentspage index.html
12408 \previouspage creator-troubleshooting-debugging.html
12409 \page creator-analyze-mode.html
12410 \nextpage creator-qml-performance-monitor.html
12412 \title Analyzing Code
12414 The memory available on mobile devices is limited and you should use it
12415 carefully. Qt Creator contains tools that you can use to analyze your code.
12417 The \gui {QML Profiler} allows you to profile your Qt
12418 Quick applications. You can inspect binding evaluations, signal handling,
12419 and painting operations when running QML code. This is useful for
12420 identifying potential bottlenecks, especially in the evaluation of bindings.
12422 In addition, Qt Creator integrates Valgrind code analysis tools for
12423 detecting memory leaks and profiling function execution. These tools are
12425 supported on Linux and Mac OS. You have to download and install them
12426 separately to use them from Qt Creator.
12428 You can use the code analysis tools in the \gui Analyze mode or from the
12429 \gui {Debug > Start Analyzer} menu. In \gui Analyze mode, you can switch
12430 between tools by selecting them in the menu on the toolbar.
12432 \image qtcreator-analyze-menu "Analyze mode menu"
12434 To run the Valgrind tools on a remote device over SSH, select \gui {Debug >
12435 Start Analyzer > Start Remote}.
12437 To stop the currently running analyzer, select \gui {Debug > Start Analyzer
12440 To select options for the Valgrind tools, select \gui {Tools > Options... >
12443 The following sections describe how to use the code analysis tools:
12447 \o \l{Profiling QML Applications} describes how to inspect binding
12448 evaluations, signal handling, and painting operations when running
12451 \o \l{Detecting Memory Leaks} describes how to use the Valgrind
12452 Memcheck tool to detect problems in memory management.
12454 \o \l{Profiling Function Execution} describes how to use the Valgrind Callgrind
12455 tool to find cache misses in the code.
12463 \contentspage index.html
12464 \previouspage creator-analyze-mode.html
12465 \page creator-qml-performance-monitor.html
12466 \nextpage creator-analyzer.html
12468 \title Profiling QML Applications
12470 To monitor the performance of an application in the QML Profiler:
12474 \o In the \gui Projects mode, select Qt 4.7.4 in the \gui {Qt version}
12477 \o Select \gui Analyze to open the \gui Analyze mode.
12480 \inlineimage qtcreator-analyze-start-button.png "Start button"
12481 button to start the application from the QML Profiler.
12483 \note: If data collection does not start automatically, select the
12484 \inlineimage qtcreator-analyzer-button.png "Analyzer button"
12489 When you start analyzing an application, the application is launched, and
12490 the QML Profiler immediately begins to collect data. This is indicated by
12491 the time running in the \gui Elapsed field.
12493 Data is collected until you select the
12494 \inlineimage qtcreator-analyzer-stop-button.png "Stop button"
12495 button. Data collection takes time, and therefore, there might be a delay
12496 before the data is displayed.
12498 \image qtcreator-qml-performance-monitor-toolbar.png "QML Profiler toolbar"
12500 Do not use application commands to exit the application, because data is
12501 sent to the QML Profiler when you select the \gui Stop button.
12502 The application continues to run for some seconds, after which it is stopped
12503 automatically. If you exit the application, the data is not sent.
12505 Select the \inlineimage qtcreator-analyzer-button.png "Analyzer button"
12506 button to disable the automatic start of the data collection when an
12507 application is launched. Data collection starts when you select the button
12510 To monitor applications running on devices:
12514 \o On the command line, enter the following command to launch the Qt
12515 Quick application with parameters:
12517 \c {<application> -qmljsdebugger=port:33456}
12519 The port number is specified in the run settings of the project in
12520 the \gui {Debug port} field.
12522 \o Select \gui {Debug > Start Analyzer > Attach...} to attach the QML
12523 Profiler to the running application.
12527 \section1 Analyzing Collected Data
12529 The \gui Timeline view displays graphical representations of:
12533 \o Painting operations
12535 \o Compiling the QML sources
12537 \o Creating elements
12539 \o Binding evaluations
12543 \o Summary of the recorded period
12547 \image qtcreator-qml-performance-monitor.png "QML Profiler"
12549 The outline summarizes the period for which data was collected. Drag the
12550 range bar or click the outline to move on the outline. Drag the borders of
12551 the range bar to zoom in and out.
12553 Additional information is displayed on the rows above the outline.
12554 Each row in the timeline describes a type of QML events that were recorded.
12555 Move the cursor on an event on a row to see how long it takes and where
12556 in the source it is being called.
12558 On the \gui Binding row, you can see when a binding is evaluated and how
12559 long the evaluation takes. Move the mouse over the binding for details
12560 about the binding: location in the source code, duration, and source
12563 Click the binding to move the cursor in the code editor to the part of the
12564 code where the binding is called.
12566 The time bar at the top of the \gui Timeline view displays the time in
12567 seconds. To see the time in milliseconds, move the mouse on the time bar.
12569 \section1 Viewing Bindings
12571 The \gui Bindings view displays the number of times each binding is called
12572 and the time the calls take. This allows you to examine which bindings you
12573 need to optimize. A high number of calls might indicate that a binding is
12574 called unnecessarily. Click on a binding to move to it in the source code
12575 in the code editor.
12577 \image qtcreator-analyzer-bindings.png "Bindings view"
12579 \section1 Viewing Calling and Called Bindings
12581 The \gui Callees and \gui Callers views show dependencies between bindings.
12582 They allow you to examine the internal functions of the application.
12584 The \gui Callees view summarizes the QML events that a binding triggers.
12585 This tells you which QML events are affected if you change a binding.
12587 \image qtcreator-qml-performance-monitor-callees.png "Callees view"
12589 The \gui Callers view summarizes the QML events that trigger a binding.
12590 This tells you what caused a change in a binding.
12592 \image qtcreator-qml-performance-monitor-callers.png "Callers view"
12594 Click on a binding to move to it in the source code in the code editor.
12596 \section2 Viewing More Data
12598 The QML JavaScript engine optimizes trivial bindings. The QML Profiler
12599 does not receive information about optimized bindings, and
12600 therefore, it displays the text \gui {<bytecode>} and the message
12601 \gui {Source code not available} in the \gui Callees and \gui {Callers}
12604 To inspect the optimized bindings, turn off the QML optimizer by setting the
12605 environment variable QML_DISABLE_OPTIMIZER to 1. To set the environment
12606 variable for the current project in the project settings:
12610 \o Select \gui {Projects > Run}.
12612 \o In \gui {Run Environment}, click \gui Add.
12614 \o Add the QML_DISABLE_OPTIMIZER variable and set its value to 1.