1 /****************************************************************************
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
11 ** Licensees holding valid Qt Commercial licenses may use this file in
12 ** accordance with the Qt Commercial License Agreement provided with the
13 ** Software or, alternatively, in accordance with the terms contained in a
14 ** written agreement between you and Nokia.
16 ** GNU Free Documentation License
17 ** Alternatively, this file may be used under the terms of the GNU Free
18 ** Documentation License version 1.3 as published by the Free Software
19 ** Foundation and appearing in the file included in the packaging of this
22 ** If you have questions regarding the use of this file, please contact
23 ** Nokia at qt-info@nokia.com.
26 ****************************************************************************/
28 // **********************************************************************
29 // NOTE: the sections are not ordered by their logical order to avoid
30 // reshuffling the file each time the index order changes (i.e., often).
31 // Run the fixnavi.pl script to adjust the links to the index order.
32 // **********************************************************************
36 \contentspage{index.html}{Qt Creator}
38 \nextpage creator-overview.html
40 \title Qt Creator Manual
42 \section1 Version \qtcversion
44 Qt Creator provides a cross-platform, complete integrated development
45 environment (IDE) for application developers to create applications for
46 multiple desktop and mobile device platforms. It is available for Linux,
47 Mac OS X and Windows operating systems. For more information, see
48 \l{Operating Systems and Supported Platforms}.
50 \note Please report bugs and suggestions to the
51 \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}.
52 You can also join the Qt Creator mailing list. To subscribe,
53 send a message with the word \e subscribe to
54 \l{mailto:qt-creator-request@trolltech.com}
55 {qt-creator-request@trolltech.com}. For more information about Qt mailing
56 lists, visit \l{http://lists.trolltech.com}{http://lists.trolltech.com}.
59 <img border="0" style="float:right;" src="images/qtcreator-screenshots.png" />
63 \o \l{Introducing Qt Creator}
64 \o \l{Operating Systems and Supported Platforms}
65 \o \l{Qt Creator User Interface}
66 \o \l{Getting Started}
68 \o \l{Building and Running an Example Application}
69 \o \l{Creating a Qt C++ Application}
70 \o \l{Creating a Mobile Application with Qt SDK}
71 \o \l{Creating a Qt Quick Application}
73 \o \l{Managing Projects}
75 \o \l{Creating a Project}
76 \o \l{Setting Up a qmake Project}
77 \o \l{Adding Libraries to qmake Projects}
78 \o \l{Setting Up a CMake Project}
79 \o \l{Setting Up a Generic Project}
80 \o \l{Setting Up Development Environment for Maemo}
81 \o \l{Setting Up Development Environment for Symbian}
82 \o \l{Managing Sessions}
83 \o \l{Adding New Custom Wizards}
85 \o \l{Using the Editor}
87 \o \l{Finding and Replacing}
89 \o \l{Using Qt Quick Toolbars}
90 \o \l{Searching With the Locator}
91 \o \l{Pasting and Fetching Code Snippets}
92 \o \l{Configuring the Editor}
93 \o \l{Using FakeVim Mode}
94 \o \l{Using an External Editor}
96 \o \l{Developing Application UI}
98 \o \l{Optimizing Applications for Mobile Devices}
99 \o \l{Using Qt Designer}
100 \o \l{Adding Qt Designer Plugins}
102 \o \l{Developing Qt Quick Applications}
104 \o \l {Creating Qt Quick Projects}
105 \o \l {Using Qt Quick Designer}
106 \o \l {Creating Components}
107 \o \l {Creating Screens}
108 \o \l {Animating Screens}
109 \o \l {Adding User Interaction Methods}
110 \o \l {Implementing Application Logic}
114 \o \l{Building and Running Applications}
116 \o \l{Building for and Running on Multiple Targets}
117 \o \l{Specifying Build Settings}
118 \o \l{Specifying Run Settings}
119 \o \l{Specifying Editor Settings}
120 \o \l{Specifying Dependencies}
125 \o \l{Debugging the Example Application}
126 \o \l{Interacting with the Debugger}
127 \o \l{Setting Up Debugger}
128 \o \l{Debugger Modes of Operation}
129 \o \l{Using Debugging Helpers}
130 \o \l{Debugging Qt Quick Projects}
132 \o \l{Using the Maemo Emulator}
133 \o \l{Using Version Control Systems}
134 \o \l{Creating Task List Files}
135 \o \l{Using Command Line Options}
137 \o \l{Tips and Tricks}
138 \o \l{Keyboard Shortcuts}
141 \o \l{Acknowledgements}
147 \contentspage index.html
148 \previouspage index.html
149 \page creator-overview.html
150 \nextpage creator-os-supported-platforms.html
152 \title Introducing Qt Creator
154 Qt Creator is an integrated development environment (IDE) that provides you with
155 tools to design and develop complex applications for multiple desktop and mobile
158 \image qtcreator-overview.png "Qt Creator overview"
160 \section1 Cross-platform Development
162 One of the major advantages of Qt Creator is that it allows a team of developers
163 to share a project across different development platforms with a common tool
164 for development and debugging.
166 The recommended way to build a project is to use a version control system.
167 Store and edit only project source files and the .pro and .pri files (for qmake)
168 or CMakeLists.txt and *.cmake files (for CMake). Do not store
169 files generated by the build system or Qt Creator, such as makefiles,
170 .pro.user, and object files. Other approaches are possible,
171 but we recommend that you do not use network resources, for example.
173 Qt Creator allows you to specify separate build settings
174 for each development platform. By default, \l{glossary-shadow-build}{shadow builds} are used to
175 keep the build specific files separate from the source.
177 You can create separate versions of project files to keep platform-dependent
178 code separate. You can use qmake
179 \l{http://qt.nokia.com/doc/4.7/qmake-tutorial.html#adding-platform-specific-source-files}{scopes}
180 to select the file to process depending on which platform qmake is run on.
182 Items such as open files, breakpoints, and watches are stored in
183 sessions. They are not considered to be part of the
184 information shared across platforms.
186 Qt Creator is integrated with cross-platform systems for build automation:
187 qmake and CMake. In addition, you can import generic projects that do not use qmake
188 or CMake, and specify that Qt Creator ignores your build system.
190 In addition to Qt libraries, you can link your application to other
191 libraries, such as system libraries or your own libraries. Further, your
192 own libraries might link to other libraries. To be able to compile your
193 project, you must add the libraries to your project. This also enables
194 code completion and syntax highlighting for the libraries.
195 The procedure of adding a library to a project depends on the the build
198 Qt Creator provides support for building and running Qt applications for
199 desktop environment and mobile devices. When you install the \QSDK,
200 the build and run settings for the Maemo and Symbian targets are set up
201 automatically. However, you need to install and configure some additional software
204 \note The only supported build system for mobile applications in Qt
207 Once your mobile application is ready, you can test it in the Qt Simulator.
208 You can also connect Maemo and Symbian devices to your development PC and
209 debug applications on the devices. After you have tested the application,
210 you can deploy it on mobile devices.
212 Developing applications for mobile devices is different from developing
213 desktop applications. For more information, see
214 \l{Optimizing Applications for Mobile Devices}.
218 But why do you need projects? To be able to build and run applications,
219 Qt Creator needs the same information as a compiler would need. This information
220 is specified in the project build and run settings.
222 Creating a project allows you to:
226 \o Group files together
228 \o Add custom build steps
230 \o Include forms and resource files
232 \o Specify settings for running applications
236 You can either create a project from scratch or import an existing
237 project. Qt Creator generates all the necessary files, depending on the type of
238 project you create. For example, if you choose to create a graphical user
239 interface (GUI) application, Qt Creator generates an empty .ui file
240 that you can modify with the integrated \QD.
242 Qt Creator is integrated with cross-platform systems for build automation: qmake and
243 CMake. In addition, you can import generic projects that do not use qmake or CMake,
244 and specify that Qt Creator ignores your build system.
248 Qt Creator comes with a code editor and two integrated visual editors for designing
250 graphical user interfaces (GUIs) from Qt widgets.
252 \section2 Code Editor
254 As an IDE, Qt Creator differs from a text editor in that it knows how to build and run
255 applications. It understands the C++ and QML languages as code, not just as plain text. This allows
260 \o Enable you to write well formatted code
262 \o Anticipate what you are going to write and complete the code
264 \o Display inline error and warning messages
266 \o Enable you to semantically navigate to classes, functions, and symbols
268 \o Provide you with context-sensitive help on classes, functions, and symbols
270 \o Rename symbols in an intelligent way, so that other symbols with the same name
271 that belong to other scopes are not renamed
273 \o Show you the locations in code where a function is declared or called
277 \section2 UI Designer
279 Qt Creator provides two integrated visual editors, \QD and \QMLD.
281 \QD is a tool for designing and building graphical user interfaces (GUIs) from
282 Qt widgets. You can compose and customize your widgets or dialogs and test
283 them using different styles and resolutions.
285 Widgets and forms created with \QD are integrated seamlessly with programmed code,
286 using the Qt signals and slots mechanism, that lets you easily assign behavior to
287 graphical elements. All properties set in \QD can be changed dynamically within the code.
288 Furthermore, features like widget promotion and custom plugins allow you to use your
289 own widgets with \QD.
291 UIs that use widgets are clearly structured and enforce a platform look and feel,
292 which makes them useful for traditional applications. However, they are static, and
293 do not fully make use of the large high-resolution screens, touch input, and significant
294 graphics power that are becoming common in portable consumer devices, such as mobile
295 phones, media players, set-top boxes, and netbooks.
297 \QMLD allows you to easily develop animations by using a declarative programming
298 language called \l {http://doc.qt.nokia.com/4.7/qtquick.html}{QML}.
299 In QML, a user interface is specified as a tree of objects with properties.
301 You use a visual editor to create items, screens, and applications, as well as define changes
302 in their state, transitions from one state to another, and user actions that change the
303 states. \QMLD generates the necessary code for you.
305 You can use Qt or JavaScript to implement the application logic.
309 You can use the code editor to write code in Qt C++ or in the
310 \l {http://doc.qt.nokia.com/4.7/qtquick.html}{QML} declarative
311 programming language.
315 You can use QML to build highly dynamic, custom user interfaces from a rich set
316 of QML elements. Qt Quick helps programmers and designers collaborate to build the
317 fluid user interfaces that are becoming common in portable consumer devices, such as
318 mobile phones, media players, set-top boxes and netbooks.
320 QML is an extension to JavaScript, that provides a mechanism to declaratively build
321 an object tree of QML elements. QML improves the integration between JavaScript and
322 Qt's existing QObject based type system, adds support for automatic property bindings
323 and provides network transparency at the language level.
327 Qt Creator provides support for building and running Qt applications for
328 desktop environment (Windows, Linux, and Mac OS) and mobile devices (Symbian, Maemo,
329 and MeeGo). Build settings allow you to quickly switch between build targets.
331 When you build an application for a mobile device target with a device
332 connected to the development PC, Qt Creator generates an installation package,
333 installs in on the device, and executes it.
335 You can publish the installation packages on the \l{https://publish.ovi.com/info/}{Ovi Store}.
336 For Symbian devices, the packages must be signed.
340 Qt Creator is integrated with a set of helpful tools, such as version control
341 systems and Qt Simulator.
343 \section2 Version Control Systems
345 Qt Creator uses the version control system's command line clients to access
346 your repositories. The following version control systems are supported:
362 The functions available to you in Qt Creator depend on the version control
363 system. Basic functions are available for all the supported systems. They include
364 comparing files with the latest versions stored in the repository and displaying the
365 differences, viewing versioning history and change details, annotating files,
366 and committing and reverting changes.
368 \section2 Qt Simulator
370 You can use the Qt Simulator to test Qt applications that are intended
371 for mobile devices in an environment similar to that of the device. You
372 can change the information that the device has about its configuration
375 The Qt Simulator is installed as part of the \QSDK. After it is
376 installed, you can select it as a build target in Qt Creator.
380 Qt Creator does not include a debugger. It provides a debugger plugin that acts
381 as an interface between the Qt Creator core and 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 watchers, 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 If you install Qt Creator as part of a \QSDK, the GNU Symbolic Debugger
426 is installed automatically and you should be ready to start debugging after
427 you create a new project. However, you can change the setup to use debugging
428 tools for Windows, for example.
430 You can connect mobile devices to your development PC and debug processes
431 running on the devices.
436 \contentspage index.html
437 \previouspage creator-overview.html
438 \page creator-os-supported-platforms.html
439 \nextpage creator-quick-tour.html
441 \title Operating Systems and Supported Platforms
443 \section1 Operating Systems
445 Qt Creator is available in binary packages for the following operating
448 \o Windows XP Service Pack 2
450 \o (K)Ubuntu Linux 8.04 (32-bit and 64-bit) or later, with the following:
457 \o libfontconfig1-dev
466 \o If you are using QtOpenGL, libgl-dev and libglu-dev
468 \o Mac OS 10.5 or later with the following:
470 \o Xcode tools for your Mac OS X version available from your Mac
471 OS X installation DVDs or at \l http://developer.apple.com.
475 \omit ## Are the Xcode tools still needed separately? \endomit
477 \section1 Build Environment
479 To build Qt Creator itself from the source, you need:
482 \o On Windows, MinGW 4.4 or Microsoft Visual Studio 2008
485 \section1 Supported Mobile Device Platforms
486 You can develop applications for the following mobile device
493 \o Maemo and Maemo Application Development and Debugging Environment (MADDE)
497 The following table summarizes operating system support for building
498 applications for mobile device platforms.
502 \o {1,3} Operating system
528 \contentspage index.html
529 \previouspage creator-os-supported-platforms.html
530 \page creator-quick-tour.html
531 \nextpage creator-getting-started.html
533 \title Qt Creator User Interface
535 \image qtcreator-breakdown.png
537 When you start Qt Creator, it opens to the \gui Welcome mode, where you can:
541 \o Open tutorials and example projects
543 \o View tips and hints on using Qt Creator
545 \o Create and open projects
547 \o Send feedback to the development team
549 \o Open recent sessions and projects
551 \o Read news from the Qt labs
557 You can use the mode selector to change to another Qt Creator mode.
559 Qt Creator has been localized into several languages. If the system language
560 is one of the supported languages, it is automatically selected. To change
561 the language, select \gui {Tools > Options > Environment} and select a language
562 in the \gui Language field. The change takes effect after you restart Qt Creator.
564 \section1 Qt Creator Modes
566 The mode selector allows you to quickly switch between tasks such as
567 editing project and source files, designing application UIs,
568 configuring how projects are built and
569 executed, and debugging your applications. To change modes, click the
570 icons, or use the \l{keyboard-shortcuts}{corresponding keyboard shortcut}.
572 You can use Qt Creator in the following modes:
575 \o \gui{\l{Using the Editor}{Edit}} mode for editing project and source files.
576 \o \gui{\l{Developing Application UI}{Design}} mode for designing and developing
577 application user interfaces. This mode is available for UI files (.ui or
579 \o \gui{\l{Debugging}{Debug}} mode for inspecting the state of your program while
581 \o \gui{\l{Managing Projects}{Projects}} mode for configuring project building and
582 execution. This mode is available when a project is open.
583 \o \gui{\l{Getting Help}{Help}} mode for viewing Qt documentation.
586 Certain actions in Qt Creator trigger a mode change. Clicking on
587 \gui {Debug} > \gui {Start Debugging} > \gui {Start Debugging}
588 automatically switches to \gui {Debug} mode.
591 \section1 Browsing Project Contents
593 The sidebar is available in the \gui Edit and \gui Debug modes.
594 Use the sidebar to browse projects, files, and bookmarks, and to view
596 \image qtcreator-sidebar.png
598 You can select the content of the sidebar in the sidebar menu:
600 \o \gui Projects shows a list of projects open in the current
602 \o \gui{Open Documents} shows currently open files.
603 \o \gui Bookmarks shows all bookmarks for the current session.
604 \o \gui{File System} shows all files in the currently selected
606 \o \gui {Class View} shows the class hierarchy of the currently
608 \o \gui Outline shows the element hierarchy of a QML file.
609 \o \gui {Type Hierarchy} shows the base classes of a class. For
610 more information, see \l{Viewing Type Hierarchy}.
614 You can change the view of the sidebar in the following ways:
616 \o To toggle the sidebar, click \inlineimage qtcreator-togglebutton.png
617 or press \key Alt+0 (\key Cmd+0 on Mac OS X).
618 \o To split the sidebar, click \inlineimage qtcreator-splitbar.png
619 . Select new content to view in the split view.
620 \o To close a sidebar view, click
621 \inlineimage qtcreator-closesidebar.png
625 The additional options in each view are described in the following
628 \section2 Viewing Project Files
630 The sidebar displays projects in a project tree. The project tree contains
631 a list of all projects open in the current session. The files for each
632 project are grouped according to their file type.
634 You can use the project tree in the following ways:
636 \o To bring up a context menu containing the actions most commonly
637 needed right-click an item in the project tree.
638 For example, through the menu of the project root directory you can,
639 among other actions, build, re-build, clean and run the project.
640 \o To hide the categories and sort project files alphabetically, click
641 \inlineimage qtcreator-filter.png
642 and select \gui{Simplify Tree}.
643 \o To hide source files which are automatically generated by the build
644 system, during a build, click \inlineimage qtcreator-filter.png
645 and select \gui{Hide Generated Files}.
646 \o To keep the position in the project tree synchronized with the file
647 currently opened in the editor, click
648 \inlineimage qtcreator-synchronizefocus.png
650 \o To see the absolute path of a file, move the mouse pointer over the
654 \section2 Viewing the File System
656 If you cannot see a file in the \gui Projects view, switch to the
657 \gui {File System} view, which shows all the files in the file system.
659 To keep the position in the tree synchronized with the file
660 opened in the editor, click
661 \inlineimage qtcreator-synchronizefocus.png
664 \section2 Viewing the Class Hierarchy
666 The \gui {Class View} shows the class hierarchy of the currently
667 open projects. To organize the view by subprojects, click
668 \inlineimage qtcreator-show-subprojects.png
671 \section2 Viewing QML Elements
673 The \gui Outline view shows the element hierarchy in a QML file.
677 \o To see a complete list of all bindings, click
678 \inlineimage qtcreator-filter.png
679 and select \gui{Show All Bindings}.
681 \o To keep the position in the view synchronized with the element
682 selected in the editor, click
683 \inlineimage qtcreator-synchronizefocus.png
688 \section1 Viewing Output
690 The task pane in Qt Creator can display one of the following panes:
692 \o \gui{Build Issues}
693 \o \gui{Search Results}
694 \o \gui{Application Output}
695 \o \gui{Compile Output}
696 \o \gui{General Messages}
697 \o \gui{Version Control}
700 Output panes are available in all \l{Qt Creator modes}{modes}.
701 Click the name of an output pane to open the pane. To maximize
702 an open output pane, click the \gui {Maximize Output Pane} button
703 or press \key {Alt+9}.
705 To search within the \gui{Application Output} and \gui{Compile Output}
706 panes, press \key {Ctrl+F} when the pane is active. Enter search
707 criteria in the \gui Find field and click the left and right arrows to
708 search down and up in the pane.
710 To open the \gui{General Messages} and \gui{Version Control}
711 panes, select \gui {Window > Output Panes}.
714 \section2 Build Issues
716 The \gui{Build Issues} pane provides a list of errors and warnings
717 encountered during a build. The pane filters out irrelevant output from
718 the build tools and presents the issues in an organized way.
720 Right-clicking on a line brings up a context menu with options to copy
721 the contents and to show a version control annotation view of the
722 line that causes the error message.
724 \image qtcreator-build-issues.png
726 To view task lists in the \gui{Build Issues} pane, click
727 \inlineimage qtcreator-filter.png
728 and select \gui{My Tasks}. Entries from a task list file (.tasks) are
729 imported to the pane. Press \key F6 and \key Shift+F6 to jump from one issue
732 For more information about creating task files, see \l{Creating Task List Files}.
734 \section2 Search Results
736 The \gui{Search Results} pane displays the results for global searches,
737 for example, searching within a current document, files on disk, or all
740 The figure below shows an example search result for all
741 occurrences of \c textfinder within the \c "/TextFinder" directory.
743 \image qtcreator-search-pane.png
746 \section2 Application Output
748 The \gui{Application Output} pane displays the status of a program when
749 it is executed, and the debug output.
751 The figure below shows an example output from qDebug().
753 \image qtcreator-application-output.png
756 \section2 Compile Output
758 The \gui{Compile Output} pane provides all output from the compiler.
759 The \gui{Compile Output} is a more detailed version of information
760 displayed in the \gui{Build Issues} pane.
762 \image qtcreator-compile-pane.png
764 \section1 Navigating with Keyboard
766 Qt Creator caters not only to developers who are used to using the mouse,
767 but also to developers who are more comfortable with the keyboard. A wide
768 range of \l{keyboard-shortcuts}{keyboard} and
769 \l{Searching With the Locator}{navigation} shortcuts are available to help
770 speed up the process of developing your application.
776 \contentspage index.html
777 \previouspage creator-task-lists.html
778 \page creator-help.html
779 \nextpage creator-tips.html
783 Qt Creator comes fully integrated with Qt documentation and
784 examples using the Qt Help plugin.
786 \o To view documentation, switch to \gui Help mode.
787 \o To obtain context sensitive help, move the text cursor to a Qt class
788 or function and press \key F1. The documentation is displayed in a
789 pane next to the code editor, or, if there is not enough vertical
790 space, in the fullscreen \gui Help mode.
792 \image qtcreator-context-sensitive-help.png
794 \o To select and configure how the documentation is displayed in the
795 \gui Help mode, select \gui Tools > \gui Options... > \gui Help.
798 \section1 Finding Information in Qt Documentation
800 Qt Creator, \QSDK and other Qt deliverables contain documentation
801 as .qch files. All the documentation is accessible in the \gui Help mode.
803 To find information in the documentation, select:
807 \o \gui Bookmarks to view a list of pages on which you have added bookmarks.
809 \o \gui Contents to see all the documentation installed on the development
810 PC and to browse the documentation contents.
812 \o \gui Index to find information based on a list of keywords in all the
815 \o \gui {Open Pages} to view a list of currently open documentation pages.
817 \o \gui Search to search from all the installed documents.
821 \section2 Adding Bookmarks to Help Pages
823 You can add bookmarks to useful help pages to easily find them later
824 in the \gui Bookmarks view. You can either use the page title as the
825 bookmark or change it to any text. You can organize the bookmarks in
828 \image qtcreator-help-add-bookmark-dlg.png "Add Bookmark dialog"
830 To add a bookmark to an open help page:
835 \inlineimage qtcreator-help-add-bookmark.png
836 (\gui {Add Bookmark}) button on the toolbar.
838 \o In the \gui {Add Bookmark} dialog, click \gui OK to save the
839 page title as a bookmark in the \gui Bookmarks folder.
843 To import and export bookmarks, select \gui {Tools > Options... > Help >
844 General Settings > Import} or \gui Export.
846 \section1 Adding External Documentation
848 You can display external documentation in the \gui Help mode.
849 To augment or replace the documentation that ships with Qt Creator and Qt:
851 \o Create a .qch file from your documentation.
853 For information on how to prepare your documentation and create a
855 \l{http://doc.qt.nokia.com/4.7/qthelp-framework.html}{The Qt Help Framework}.
856 \o To add the .qch file to Qt Creator, select \gui Tools >
857 \gui Options... > \gui Help > \gui Documentation > \gui Add.
860 \section1 Detaching the Help Window
862 By default, context-sensitive help is opened in a window next to the
863 code editor when you press \key F1. If there is not enough vertical
864 space, the help opens in the full-screen help mode.
866 You can specify that the help always opens in full-screen mode or
867 is detached to an external window. Select \gui {Tools > Options... > Help >
868 General Settings} and specify settings for displaying context-sensitive help
869 in the \gui {On context help} field. To detach the help window, select
870 \gui {Always Show Help in External Window}.
872 You can select the help page to open upon startup in the \gui {Home Page}
875 \section1 Using Documentation Filters
877 You can filter the documents displayed in the \gui Help mode to find
878 relevant information faster. Select from a list of filters in the
879 \gui {Filtered by} field. The contents of the \gui Index and \gui Contents
880 pane in the sidebar change accordingly.
882 \image qtcreator-help-filters.png "Help filters"
884 You can modify the filters to include external documentation, for example,
885 or you can define your own filters. To construct filters, you can use the
886 filter attributes that are specified in the documentation. Each document
887 contains at least one filter attribute. If several documents contain the
888 same filter attribute, such as \c tools, you can use that attribute to
889 include all those documents.
895 \o Select \gui {Tools > Options... > Help > Filters > Add}.
897 \o Enter a name for the filter and press \gui {OK}.
899 \o In \gui Attributes, select the documents that you want to include
902 \image qtcreator-help-filter-attributes.png "Help filter attributes"
906 \o In the \gui Help mode, select the filter in the \gui {Filtered by}
907 field to see the filtered documentation in the sidebar.
911 To modify filters, select a filter in \gui Filters, select the attributes,
912 and then click \gui Apply.
914 To remove filters, select them in \gui Filters, and click \gui Remove.
920 \contentspage index.html
921 \previouspage creator-editor-external.html
922 \page creator-design-mode.html
923 \nextpage creator-usability.html
925 \title Developing Application UI
927 You can use the integrated \QD to design and build graphical user interfaces (GUIs) from
928 Qt widgets. You can compose and customize your widgets or dialogs and test
929 them using different styles and resolutions.
931 Widgets and forms created with \QD are integrated seamlessly with programmed code,
932 using the Qt signals and slots mechanism, that lets you easily assign behavior to
933 graphical elements. All properties set in \QD can be changed dynamically within the code.
934 Furthermore, features like widget promotion and custom plugins allow you to use your
935 own widgets with \QD.
937 UIs that use widgets are clearly structured and enforce a platform look and feel,
938 which makes them useful for traditional applications. However, they are static, and
939 do not fully make use of the large high-resolution screens, touch input, and significant
940 graphics power that are becoming common in portable consumer devices, such as mobile
941 phones, media players, set-top boxes, and netbooks.
943 You can easily develop animations by using a declarative programming
944 language called \l {http://doc.qt.nokia.com/4.7/qtquick.html}{QML}.
945 In QML, a user interface is specified as a tree of objects with properties.
946 You can edit QML code in the code editor or in the integrated \QMLD. You
947 can use Qt or JavaScript to implement the application logic.
949 The integration includes project management and code completion.
951 The following sections describe how to develop application UI:
955 \o \l{Optimizing Applications for Mobile Devices}
956 \o \l{Using Qt Designer}
957 \o \l{Adding Qt Designer Plugins}
958 \o \l{Developing Qt Quick Applications}
966 \contentspage index.html
967 \previouspage creator-usability.html
968 \page creator-using-qt-designer.html
969 \nextpage adding-plugins.html
971 \title Using Qt Designer
973 Qt Creator automatically opens all .ui files in \QD.
975 \image qtcreator-formedit.png
977 To change the layout of \QD user interface elements:
979 \o Select \gui Tools > \gui{Form Editor} > \gui Views >
982 When this option is unchecked, you can change the layout.
983 \o Click the header of an element and drag the element to a new
987 To change \QD properties, select \gui Tools > \gui Options... >
990 \o Set the class properties and code generation preferences in \gui
992 \o Set an additional folder for saving templates in \gui{Template
994 \o Set the grid settings and preview preferences in \gui Forms. To
995 preview your form with skins, enable \gui{Print/Preview
996 Configuration} and select your skin. Otherwise default preview
999 To preview the settings, select \gui Tools > \gui{Form Editor} >
1000 \gui Preview, or press \key Alt+Shift+R.
1001 \o To specify embedded device profiles, such as style, font, and screen
1002 resolution, select \gui{Embedded Design}.
1005 To switch between forms and code, use \key Shift+F4.
1007 For more information on \QD, see
1008 \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
1014 \contentspage index.html
1015 \previouspage quick-projects.html
1016 \page creator-using-qt-quick-designer.html
1017 \nextpage quick-components.html
1019 \title Using Qt Quick Designer
1021 You can edit .qml files in the visual \QMLD editor or in the
1024 In \gui Projects, double-click a .qml file to open it in the code
1025 editor. Then select the \gui {Design} mode to edit the file in the
1028 \image qmldesigner-visual-editor.png "Visual editor"
1030 Use the visual editor panes to manage your project:
1034 \o \gui {Navigator} pane displays the QML elements in the current QML file.
1035 You can show and hide items to focus on specific parts of the application.
1036 To view lists of files or projects, instead, select \gui {File System},
1037 \gui {Open Documents}, or \gui Projects in the menu.
1039 \o \gui {Library} pane displays the building blocks that you can use to design
1040 applications: predefined QML elements, your own QML components, and other
1043 \o \gui {Properties} pane organizes the properties of the selected QML element
1044 or QML component. You can also change the properties in the code editor.
1046 \o \gui {State} pane displays the different states of the component. To add
1047 states, click the empty slot. Then modify the new state in the editor.
1048 In the code editor, you can see the changes recorded as changes to
1053 \section1 Element Library
1055 The \gui {Library} pane contains two tabs: \gui {Items} and \gui {Resources}.
1056 The \gui Items pane displays the QML elements grouped by type: your own QML
1057 components, basic elements, interaction elements, views, and widgets.
1059 \image qmldesigner-qml-components.png "QML Components pane"
1061 The \gui {Resources} pane displays the images and other files that you copy to
1064 \section1 Specifying Element Properties
1066 The \gui Properties pane displays all the properties of the selected QML element.
1067 The properties are grouped by type. The top part of the pane displays properties
1068 that are common to all elements, such as element type, position, size,
1071 The bottom part of the pane displays properties that are specific to each element
1072 type. For example, the following image displays the properties you can set for
1073 \gui Rectangle and \gui Text elements.
1075 \image qmldesigner-element-properties.png
1077 For more information on the properties available for an element, press \key {F1}.
1079 \section2 Setting Expressions
1081 You can set JavaScript expressions as values of some properties. Click the circle
1082 icon next to a property to open a context menu, and select \gui {Set Expression}.
1084 \image qmldesigner-set-expression.png "Element properties context menu"
1086 For more information on the JavaScript environment provided by QML, see
1087 \l{http://doc.qt.nokia.com/4.7-snapshot/qdeclarativejavascript.html}{Integrating JavaScript}.
1089 \section2 Setting Anchors and Margins
1091 The \gui Layout pane allows you to set anchors and margins for elements. To set
1092 the anchors of an item, click the anchor buttons. You can combine the top/bottom
1093 and left/right anchors to anchor objects in the corners of the parent element.
1095 \inlineimage qmldesigner-anchor-buttons.png "Anchor buttons"
1097 \section2 Building Transformations on Items
1099 The \gui Advanced pane allows you configure advanced transformations, such as
1100 rotation, scale, and translation. You can assign any number of transformations
1101 to an item. Each transformation is applied in order, one at a time.
1103 For more information on Transform elements, see
1104 \l {http://doc.qt.nokia.com/4.7/qml-transform.html}{QML Transform Element}.
1110 \contentspage index.html
1111 \previouspage creator-project-wizards.html
1112 \page creator-editor-using.html
1113 \nextpage creator-editor-finding.html
1115 \title Using the Editor
1117 Qt Creator's code editor is designed to aid you in creating, editing and
1118 navigating code. Qt Creator's code editor is fully equipped with syntax
1119 checking, code completion, context sensitive help and in-line error
1120 indicators while you are typing.
1122 \section1 Using the Editor Toolbar
1124 The editor toolbar is located at the top of the editor view. The editor
1125 toolbar is context sensitive and shows items relevant to the file currently
1128 \image qtcreator-editortoolbar-symbols.png
1130 Use the toolbar to navigate between open files and symbols in use.
1131 To browse forward or backward through your location history, click
1132 \inlineimage qtcreator-back.png
1133 and \inlineimage qtcreator-forward.png
1136 To go to any open file, select it from the \gui{Open files} drop-down menu.
1137 Right-click the menu title and select \gui {Copy Full Path to Clipboard} to
1138 copy the path and name of the current file to the clipboard.
1140 To jump to any symbol used in the current file, select it from the
1141 \gui Symbols drop-down menu. By default, the symbols are displayed in the
1142 order in which they appear in the file. Right-click the menu title and select
1143 \gui {Sort Alphabetically} to arrange the symbols in alphabetic order.
1145 \section1 Splitting the Editor View
1147 Split the editor view when you want to work on and view multiple files on
1150 \image qtcreator-spliteditorview.png
1152 You can split the editor view in the following ways:
1154 \o To split the editor view into a top and bottom view, select
1155 \gui Window > \gui Split or press \key{Ctrl+E, 2}.
1157 Split command creates views below the currently active editor view.
1158 \o To split the editor view into adjacent views, select
1159 \gui Window > \gui{Split Side by Side} or press
1162 Side by side split command creates views to the right of the
1163 currently active editor view.
1166 To move between split views, select \gui Window >
1167 \gui{Go to Next Split} or press \key{Ctrl+E, O}.
1169 To remove a split view, place the cursor within the view you want to
1170 remove and select \gui Window > \gui{Remove Current Split} or press
1171 \key{Ctrl+E, 0}. To remove all but the currently selected split view,
1172 select \gui Window > \gui{Remove All Splits} or press \key{Ctrl+E, 1}.
1174 \section1 Semantic Highlighting
1176 Qt Creator understands the C++ and QML languages as code, not as plain text.
1177 It reads the source code, analyzes it, and highlights it based on the
1178 semantic checks that it does for the following code elements:
1182 \o Types (such as classes, structs, and type definitions)
1192 To specify the color scheme to use for semantic highlighting, select
1193 \gui {Tools > Options... > Text Editor > Fonts & Color}.
1195 Qt Creator supports syntax highlighting also for other types of files than
1196 C++ or QML. For more information, see \l{Generic Highlighting}.
1198 \section1 Highlighting and Folding Blocks
1200 Use block highlighting to visually separate parts of the code that belong
1201 together. For example, when you place the cursor within the braces,
1202 the code enclosed in braces is highlighted.
1204 \image qtcreator-blockhighlighting.png
1206 To enable block highlighting, select \gui Tools > \gui{Options...} >
1207 \gui{Text Editor} > \gui Display > \gui{Highlight blocks}.
1209 Use the folding markers to collapse and expand blocks of code within
1210 braces. Click the folding marker to collapse or expand a block. In the
1211 figure above, the folding markers are located between the line number and
1214 To show the folding markers, select \gui Tools > \gui{Options...} >
1215 \gui{Text Editor} > \gui Display > \gui{Display folding markers}. This
1216 option is enabled by default.
1218 When the cursor is on a brace, the matching brace is animated
1219 by default. To turn off the animation and just highlight the block and
1220 the braces, select \gui {Tools > Options... > Text Editor > Display} and
1221 deselect \gui {Animate matching parentheses}.
1224 \section1 Checking Code Syntax
1226 As you write code Qt Creator checks code syntax. When Qt Creator spots a
1227 syntax error in your code it underlines it and shows error details when you
1228 move the mouse pointer over the error.
1230 \o Syntax errors are underlined in red.
1232 In the following figure, a semicolon is missing at the end of the
1235 \image qtcreator-syntaxerror.png
1236 \o Semantic errors and warnings are underlined in olive.
1238 In the following figure, the type is unknown.
1240 \image qtcreator-semanticerror.png
1244 \section1 Completing Code
1246 As you write code, Qt Creator suggests properties, IDs, and code
1247 snippets to complete the code. It provides a list of context-sensitive
1248 suggestions to the statement currently under your cursor.
1250 \image qtcreator-codecompletion.png
1252 To open the list of suggestions at any time, press \key{Ctrl+Space}.
1253 If only one option is available, Qt Creator inserts it automatically.
1255 When completion is invoked manually, Qt Creator completes the common prefix
1256 of the list of suggestions. This is especially useful for classes with
1257 several similarly named members. To disable this functionality, uncheck
1258 \gui{Autocomplete common prefix} in the code completion preferences.
1259 Select \gui Tools > \gui{Options...} > \gui{Text Editor} > \gui Completion.
1261 By default, code completion considers only the first letter case-sensitive.
1262 To apply full or no case-sensitivity, select the option in the
1263 \gui {Case-sensitivity} field.
1265 \section2 Summary of Available Types
1267 The following table lists available types for code completion and icon
1275 \i \inlineimage completion/class.png
1278 \i \inlineimage completion/enum.png
1281 \i \inlineimage completion/enumerator.png
1282 \i An enumerator (value of an enum)
1284 \i \inlineimage completion/func.png
1287 \i \inlineimage completion/func_priv.png
1288 \i A private function
1290 \i \inlineimage completion/func_prot.png
1291 \i A protected function
1293 \i \inlineimage completion/var.png
1296 \i \inlineimage completion/var_priv.png
1297 \i A private variable
1299 \i \inlineimage completion/var_prot.png
1300 \i A protected variable
1302 \i \inlineimage completion/signal.png
1305 \i \inlineimage completion/slot.png
1308 \i \inlineimage completion/slot_priv.png
1311 \i \inlineimage completion/slot_prot.png
1314 \i \inlineimage completion/keyword.png
1317 \i \inlineimage completion/snippet.png
1318 \i A C++ code snippet
1320 \i \inlineimage completion/element.png
1323 \i \inlineimage completion/qmlsnippet.png
1324 \i A QML code snippet
1326 \i \inlineimage completion/macro.png
1329 \i \inlineimage completion/namespace.png
1333 \section2 Completing Code Snippets
1335 Code snippets can consist of multiple
1336 fields that you specify values for. Select an item in the list and press
1337 \key Tab or \key Enter to complete the code. Press \key Tab to
1338 move between the fields and specify values for them.
1340 \image qmldesigner-code-completion.png "Completing QML code"
1342 \section1 Using Bookmarks
1344 To insert or delete a bookmark right-click the line number and select
1345 \gui{Toggle Bookmark} or press \key{Ctrl+M}.
1347 \image qtcreator-togglebookmark.png
1349 To go to previous bookmark in the current session, press \key{Ctrl+,}.
1351 To go to next bookmark in the current session, press \key{Ctrl+.}.
1354 \section1 Moving to Symbol Definition or Declaration
1356 In Qt Creator you can move directly to the definition or the declaration of
1357 a symbol by holding the \key Ctrl and clicking the symbol.
1359 To enable this moving function, in \gui Tools > \gui{Options...} >
1360 \gui{Text Editor} > \gui Behavior, select \gui{Enable mouse navigation}.
1362 You can also select the symbol and press \key F2, or right-click the symbol
1363 and select \gui {Follow Symbol Under Cursor} to move to its definition or declaration.
1364 This is supported for namespaces, classes, methods, variables, include statements,
1367 To switch between the definition and declaration of a symbol, press \key {Shift+F2}
1368 or right-click the symbol and select \gui {Switch Between Method Declaration/Definition}.
1370 \section1 Viewing Type Hierarchy
1372 To view the base classes of a class, right-click the class and select
1373 \gui {Open Type Hierarchy} or press \key {Ctrl+Shift+T}.
1375 \section1 Using Update Code Model
1377 To refresh the internal information in Qt Creator pertaining to your code,
1378 select \gui{Tools} > \gui{C++} > \gui{Update Code Model}.
1380 \note In Qt Creator indexing updates the code automatically. Use
1381 \gui{Update Code Model} only as an emergency command.
1387 \contentspage index.html
1388 \previouspage creator-editor-locator.html
1389 \page creator-editor-codepasting.html
1390 \nextpage creator-editor-options.html
1392 \title Pasting and Fetching Code Snippets
1394 In Qt Creator, you can paste snippets of code to a server or fetch
1395 snippets of code from the server. To paste and fetch snippets of code,
1396 Qt Creator uses the following:
1399 \o \gui{Pastebin.Com}
1400 \o \gui{Pastebin.Ca}
1403 To configure the server, select \gui{Tools} > \gui{Options...} >
1406 To paste a snippet of code onto the server, select \gui{Tools} >
1407 \gui{Code Pasting} > \gui{Paste Snippet...} or press \key{Alt+C,Alt+P}.
1409 To fetch a snippet of code from the server, select \gui{Tools} >
1410 \gui{Code Pasting} > \gui{Fetch Snippet...} or press \key{Alt+C,Alt+F}.
1412 \note To use \gui{Pastebin.Com}, configure the domain
1413 prefix in \gui{Tools} > \gui{Options...} > \gui{Code Pasting} >
1416 For example, you might ask colleagues to review a change that you plan to
1417 submit to a version control system. If you use the Git version control system,
1418 you can create a \e{diff} view by selecting \gui{Tools} > \gui{Git} >
1419 \gui{Diff Repository}. You can then upload its contents to the server by choosing
1420 \gui{Tools} > \gui{Code Pasting} > \gui{Paste Snippet...}. The reviewers can retrieve
1421 the code snippet by selecting \gui{Tools} > \gui{Code Pasting} > \gui{Fetch Snippet...}.
1422 If they have the project currently opened in Qt Creator, they can apply and test
1423 the change by choosing \gui{Tools} > \gui{Git} > \gui{Apply Patch}.
1429 \contentspage index.html
1430 \previouspage creator-editor-options.html
1431 \page creator-editor-fakevim.html
1432 \nextpage creator-editor-external.html
1434 \title Using FakeVim Mode
1436 In the \gui{FakeVim} mode, you can run the main editor in a manner similar
1437 to the Vim editor. To run the editor in the \gui{FakeVim} mode, select
1438 \gui{Edit} > \gui{Advanced} > \gui{Use Vim-style Editing} or press
1441 In the \gui{FakeVim} mode, most keystrokes in the main editor will be
1442 intercepted and interpreted in a way that resembles Vim. Documentation for
1443 Vim is not included in Qt Creator. For more information on using Vim,
1444 see \l{http://www.vim.org/docs.php}{Documentation} on the Vim web site.
1446 To map commands entered on the \gui{FakeVim} command line to actions of the
1447 Qt Creator core, select \gui{Tools} > \gui{Options...} > \gui{FakeVim} >
1448 \gui{Ex Command Mapping}.
1450 To make changes to the Vim-style settings, select \gui{Tools} >
1451 \gui{Options...} > \gui FakeVim > \gui{General}.
1453 To use a Vim-style color scheme, select \gui {Tools > Options... >
1454 Text Editor > Fonts & Color}. In the \gui {Color Scheme} list, select
1457 To quit the FakeVim mode, click \gui {Quit FakeVim} or press
1464 \contentspage index.html
1465 \previouspage creator-editor-fakevim.html
1466 \page creator-editor-external.html
1467 \nextpage creator-design-mode.html
1469 \title Using an External Editor
1471 To open the file you are currently viewing in an external editor, select
1472 \gui Edit > \gui Advanced > \gui{Open in External Editor}.
1474 To use the external editor of your choice:
1476 \o Add the editor path to the \c{PATH} environment variable of your
1478 \o In Qt Creator select \gui Tools > \gui Options... >
1479 \gui Environment > \gui General.
1480 \o In \gui{External editor} enter the name of the application followed
1481 by \key Space and \tt{\bold %f}. For example, to open the file in
1482 Smultron, enter \tt{\bold{smultron %f}}.
1484 To further define how to open the file in the external editor, you
1485 can use the following variables separated by a space:
1487 \o Current line number \tt{\bold %l}
1488 \o Current column number \tt{\bold %c}
1489 \o Editor's x position on the screen \tt{\bold %x}
1490 \o Editor's y position on the screen \tt{\bold %y}
1491 \o Editor's width in pixels \tt{\bold %w}
1492 \o Editor's height in pixels \tt{\bold %h}
1493 \o Editor's width in characters \tt{\bold %W}
1494 \o Editor's height in characters \tt{\bold %H}
1495 \o To pass % symbol to the editor \tt{\bold %%}
1498 \note Not all variables work with all editors.
1504 \contentspage index.html
1505 \previouspage creator-editor-codepasting.html
1506 \page creator-editor-options.html
1507 \nextpage creator-editor-fakevim.html
1509 \title Configuring the Editor
1511 Qt Creator allows you to configure the text editor to suit your specific
1512 needs. To configure the editor, select \gui Tools > \gui{Options...} >
1515 \image qtcreator-font-colors.png "Text editor options"
1517 You can perform the following configuration actions:
1519 \o Set the font preferences and apply color schemes for syntax highlighting in
1520 \gui{Font & Colors}.
1521 \o Specify definition files for syntax highlighting for other types of files than
1522 C++ or QML in \gui{Generic Highlighter}.
1523 \o Set tabs, indentation, the handling of whitespace, and mouse operations in
1525 \o Set various display properties, for example,
1526 \l{Highlighting and folding blocks}{highlighting and folding blocks},
1527 text wrapping or \l{Moving to symbol definition or declaration}
1528 {moving to symbol definition or declaration}
1530 \o Configure \l{Completing Code}{code completion} in \gui Completion.
1533 \section2 Configuring Fonts
1535 You can select the font family and size. You can specify a zoom setting in
1536 percentage for viewing the text. You can also zoom in or out by pressing
1537 \key {Ctrl++} or \key {Ctrl +-}, or by pressing \key Ctrl and rolling
1538 the mouse button up or down. To disable the mouse wheel function, select
1539 \gui {Tools > Options... > Text Editor > Behavior} and deselect the
1540 \gui {Enable scroll wheel zooming} check box.
1542 Antialiasing is used by default to make text look smoother and more
1543 readable on the screen. Deselect the \gui Antialias check box to
1544 turn off antialiasing.
1546 \section2 Defining Color Schemes
1548 You can select one of the predefined color schemes for syntax highlighting
1549 or create customized color schemes. The color schemes apply to highlighting
1550 both C++ and QML files and generic files.
1552 To create a color scheme:
1556 \o Select \gui {Tools > Options... > Text Editor > Fonts & Color > Copy}.
1558 \o Enter a name for the color scheme and click \gui OK.
1560 \o In the \gui Foreground field, specify the color of the selected
1563 \o In the \gui Background field, select the background
1564 color for the code element.
1566 The backgound of the \gui Text element determines the background of the
1571 When you copy code from Qt Creator, it is copied in both plain text and HTML
1572 format. The latter makes sure that syntax highlighting is preserved when
1573 pasting to a rich-text editor.
1575 \section2 Generic Highlighting
1577 Generic highlighting is based on highlight definition files that are provided by the
1578 \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}{Kate Editor}.
1579 You can download highlight definition files for use with Qt Creator.
1581 If you have a Unix installation that comes with the Kate Editor, you might already
1582 have the definition files installed. Typically, the files are in a read-only directory,
1583 and therefore, you cannot manage them. Qt Creator can try to locate them and use them
1584 as fallback files, when the primary location does not contain the definition for the
1585 current file type. You can also specify the directory that contains preinstalled
1586 highlight definition files as the primary location.
1588 When you open a file for editing and the editor cannot find the highlight definition
1589 for it, an alert appears. You can turn off the alerts. You can also specify patterns
1590 for ignoring files. The editor will not alert you if highlight definitions for the
1591 ignored files are not found.
1593 To download highlight definition files:
1597 \o Select \gui {Tools > Options... > Text Editor > Generic Highlighter}.
1599 \image qtcreator-generic-highlighter.png "Generic Highlighter options"
1601 \o In the \gui Location field, specify the path to the primary location for
1602 highlight definition files.
1604 \o Click \gui {Download Definitions} to open a list of highlight definition files available for
1607 \image qtcreator-manage-definitions.png "Download Definitions dialog"
1609 \o Select highlight definition files in the list and click \gui{Download Selected
1612 \o Select the \gui {Use fallback location} check box to specify the secondary location
1613 where the editor will look for highlight definition files.
1615 \o Click \gui Autodetect to allow Qt Creator to look for highlight definition
1616 files on your system, or click \gui Browse to locate them in the file system
1619 \o In the \gui {Ignored file patterns} field, specify file patterns. You will not
1620 receive alerts if the highlight definitions for the specified files are not found.
1622 \o Click \gui OK to save your changes.
1627 \section2 Indenting Code
1629 \image qtcreator-indentation.png "Text Editor Behavior options"
1631 When you type code, it is indented automatically according to the selected
1632 options. Select a block to indent it when you press \key Tab.
1633 Press \key {Shift+Tab} to decrease the indentation.
1635 When you press \gui Backspace the indentation is decreased by one level,
1636 instead of one space, by default.
1638 By default, the tab-length in code editor is 8 spaces, but you can change
1639 it. The code editor can also determine whether tabs or spaces are used
1640 on the previous or next line and copy the style.
1642 You can determine whether the block indent style includes braces,
1643 or you can use the GNU indent style. The GNU style places braces on a separate
1644 line, indented by 2 spaces, except when they open a function definition, where
1645 they are not indented.
1647 You can also specify whether continuation lines are aligned with the previous
1648 code or just indented to the logical depth. You can always use spaces for
1649 alignment or use spaces or tabs depending on the other options you selected.
1651 The following code snippet illustrates excluding braces from the indented block:
1655 void foobar(bool zoo)
1665 The following code snippet illustrates including braces in the indented block:
1669 void foobar(bool zoo)
1679 The following code snippet illustrates the GNU style:
1683 void foobar(bool zoo)
1697 \contentspage index.html
1698 \previouspage creator-editor-using.html
1699 \page creator-editor-finding.html
1700 \nextpage creator-editor-refactoring.html
1702 \title Finding and Replacing
1704 To search through the currently open file:
1706 \o Press \key Ctrl+F or select \gui Edit > \gui Find/Replace >
1708 \o Enter the text you are looking for.
1710 If the text is found, all occurrences are highlighted as you type.
1711 \o To go to the next occurrence, click \inlineimage qtcreator-next.png
1712 , or press \key F3. To go to the previous occurrence click
1713 \inlineimage qtcreator-previous.png
1714 , or press \key Shift+F3.
1717 You can restrict the search in the \gui Find field by selecting one
1718 or several search criteria:
1720 \o To make your search case sensitive, select
1721 \inlineimage qtcreator-editor-casesensitive.png
1723 \o To search only whole words, select
1724 \inlineimage qtcreator-editor-wholewords.png
1726 \o To search using regular expressions, select
1727 \inlineimage qtcreator-editor-regularexpressions.png
1729 Regular expressions used in Qt Creator are modeled on Perl regular
1730 expressions. For more information on using regular expressions, see
1731 \l {http://doc.qt.nokia.com/4.7/qregexp.html#details}
1732 {Detailed Description} in the QRegExp Class Reference.
1735 \note If you have selected text before selecting \gui Find/Replace, the
1736 search is conducted within the selection.
1738 To replace occurrences of the existing text, enter the new text in the
1739 \gui{Replace with} field.
1741 \o To replace the selected occurrence and move to the next one,
1742 click \inlineimage qtcreator-next.png
1743 or press \key Ctrl+=.
1744 \o To replace the selected occurrence and move to the previous one,
1745 click \inlineimage qtcreator-previous.png
1747 \o To replace all occurrences in the file, click \gui{Replace All}.
1750 \section1 Advanced Search
1752 To search through projects, files on a file system or the currently open
1755 \o Press \key Ctrl+Shift+F or select \gui Edit >
1756 \gui Find/Replace > \gui{Advanced Find} >
1757 \gui{Open Advanced Find...}.
1758 \o Select the scope of your search:
1760 \o \gui{All Projects} searches files matching the defined file
1761 pattern in all currently open projects.
1763 For example, to search for \tt previewer only in \tt .cpp
1764 and \tt .h files, enter in \gui{File pattern}
1767 \image qtcreator-search-allprojects.png
1769 \o \gui{Current Project} searches files matching the defined file
1770 pattern only in the project you are currently editing.
1771 \o \gui{Files on File System} recursively searches files matching
1772 the defined file pattern in the selected directory.
1773 \o \gui{Current File} searches only the current file.
1775 \o Enter the text you are looking for and click \gui Search.
1777 \image qtcreator-searchresults.png
1779 A list of files containing the searched text is displayed in the
1780 \gui{Search Results} pane.
1782 \o To see all occurrences in a file, double-click the file name in
1784 \o To go to an occurrence, double-click it.
1788 \note You can use \gui{Advanced Find} also to search for symbols. For more
1789 information, see \l{Finding Symbols}.
1795 \contentspage index.html
1796 \previouspage creator-editor-finding.html
1797 \page creator-editor-refactoring.html
1798 \nextpage qt-quick-toolbars.html
1802 Code refactoring is the process of changing the code without modifying the
1803 existing functionality of your application. By refactoring your code you
1806 \o Improve internal quality of your application
1807 \o Improve performance and extensibility
1808 \o Improve code readability and maintainability
1809 \o Simplify code structure
1812 \section1 Finding Symbols
1814 To find the use of a specific symbol in your project:
1816 \o In the editor place the cursor on the symbol and select \gui Tools
1817 > \gui C++ > \gui{Find Usages} or press
1820 Qt Creator looks for the symbol in the following locations:
1822 \o Files listed as a part of the project
1823 \o Files directly used by the project files (for example, generated
1825 \o Header files of used frameworks and libraries
1828 \note You can also select \gui{Edit > Find/Replace > Advanced Find >
1829 C++ Symbols} to search for classes, methods, enums, and declarations
1830 either from files listed as part of the project or from all files that
1831 are used by the code, such as include files.
1833 \image qtcreator-search-cpp-symbols.png
1835 \o The \gui{Search Results} pane opens and shows the location and
1836 number of instances of the symbol in the current project.
1838 \image qtcreator-refactoring-find.png
1841 You can browse the search results in the following ways:
1843 \o To go directly to an instance, double-click the instance in the
1844 \gui{Search Results} pane.
1845 \o To move between instances, click
1846 \inlineimage qtcreator-forward.png
1848 \inlineimage qtcreator-back.png
1849 in the \gui{Search Results} pane.
1850 \o To expand and collapse the list of all instances, click
1851 \inlineimage qtcreator-expand.png
1853 \o To clear the search results, click \inlineimage qtcreator-clear.png
1857 \section1 Renaming Symbols
1859 The functions available for renaming symbols depend on whether you are
1860 writing C++ or QML code. For QML, you can only rename IDs.
1862 To rename a specific symbol in a Qt project:
1864 \o In the editor, place the cursor on the symbol you would like to
1865 change and select \gui Tools > \gui C++ >
1866 \gui{Rename Symbol Under Cursor} or press \key Ctrl+Shift+R.
1868 The \gui{Search Results} pane opens and shows the location and
1869 number of instances of the symbol in the current project.
1871 \image qtcreator-refactoring-replace.png
1872 \o To replace all selected instances, enter the name of the new symbol
1873 in the \gui{Replace with} text box and click \gui Replace.
1875 To omit an instance, uncheck the check-box next to the instance.
1877 \note This action replaces all selected instances of the symbol in
1878 all files listed in the \gui{Search Results} pane. You cannot
1882 \note Renaming local symbols does not open the \gui{Search Results} pane.
1883 The instances of the symbol are highlighted in code and you can edit the
1884 symbol. All instances of the local symbol are changed as you type.
1886 To rename an ID in a Qt Quick project:
1890 \o Right-click an ID in the QML code and select
1893 \o In the \gui {Rename id} field, enter the new ID.
1897 \section1 Applying Refactoring Actions
1899 Qt Creator allows you to quickly and conveniently apply actions to refactor
1900 your code by selecting them in a context menu. The actions available depend on
1901 the position of the cursor in the code editor and on whether you are writing
1904 To apply refactoring actions to C++ code, right-click an operand, conditional
1905 statement, string, or name to open a context menu. In QML code, click an element
1908 In the context menu, select \gui {Refactoring} and then select a refactoring action.
1910 You can also press \gui {Alt+Enter} to open a context menu that contains refactoring
1913 \section2 Refactoring C++ Code
1915 You can apply the following types of refactoring actions to C++ code:
1919 \o Change binary operands
1921 \o Simplify if and when conditions (for example, move declarations out of
1924 \o Modify strings (for example, set the encoding for a string to Latin-1, mark
1925 strings translatable, and convert strings to camel case)
1927 \o Create variable declarations
1929 \o Create method declarations and definitions
1933 \section2 Refactoring QML Code
1935 You can apply the following types of refactoring actions to QML code:
1941 \o Split initializers
1943 \o Move a QML element into a separate file to reuse it in other
1951 \contentspage index.html
1952 \previouspage creator-qml-application.html
1953 \page creator-project-managing.html
1954 \nextpage creator-project-creating.html
1956 \title Managing Projects
1958 One of the major advantages of Qt Creator is that it allows a team of
1959 developers to share a project across different development platforms with a common
1960 tool for development and debugging.
1962 The following sections describe how to manage projects:
1965 \o \l{Creating a Project}
1966 \o \l{Setting Up a qmake Project}
1967 \o \l{Adding Libraries to qmake Projects}
1968 \o \l{Setting Up a CMake Project}
1969 \o \l{Setting Up a Generic Project}
1970 \o \l{Setting Up Development Environment for Maemo}
1971 \o \l{Setting Up Development Environment for Symbian}
1972 \o \l{Managing Sessions}
1973 \o \l{Adding New Custom Wizards}
1980 \contentspage index.html
1981 \previouspage creator-project-managing.html
1982 \page creator-project-creating.html
1983 \nextpage creator-project-qmake.html
1985 \title Creating a Project
1987 You use wizards to create and import several types of projects and files, such
1988 as Qt GUI or console applications and Qt Quick applications.
1989 You can use wizards also to add individual files to your projects.
1991 The wizards prompt you to enter the settings needed
1992 for that particular type of project and create the necessary files for you.
1993 To display other types of files in the \gui Projects pane, specify them in
1996 \image qtcreator-new-project.png
1998 To change the location of the project directory, and to make changes in
1999 the build and run settings, select \gui{Tools} > \gui{Options...} >
2000 \gui{Projects} > \gui{General}.
2002 \section1 Using Project Wizards
2004 To create a new project:
2006 \o Select \gui File > \gui{New File or Project} and select the type of your
2009 The contents of the following dialogs depend on the project type.
2010 Follow the instructions of the wizard.
2011 This example uses \gui {Qt Gui Application}.
2013 \o Name the project and set its path, and then click \gui Next.
2015 Do not use spaces and special characters in the project name and
2018 \image qtcreator-intro-and-location.png
2020 \o Select the Qt versions to use as build targets for your project, and click
2023 \image qtcreator-new-project-qt-versions.png "Qt Versions dialog"
2025 \note If you have only one Qt version installed, this dialog is skipped.
2027 \o Specify the name of the class you want to create and using the
2028 drop-down menu select its base class type.
2030 Note that the \gui{Header file}, \gui{Source file} and
2031 \gui{Form file} fields are automatically updated as you name your
2034 \image qtcreator-class-info.png
2035 \o Review the project settings.
2037 To create the project, click \gui Finish.
2039 \image qtcreator-new-project-summary.png
2042 \section1 Adding Files to Projects
2044 You can create the following types of files:
2048 \o Qt resource files, which allow you to store binary files in the
2049 application executable
2051 \o \QD forms and Qt QML files, which specify parts of application user
2054 \o C++ class, source, or header files
2060 \section2 Creating C++ Classes
2062 The \gui {C++ Class Wizard} allows you to create a C++ header and source file for
2063 a new class that you can add to a C++ project. Specify the class name, base
2064 class, and header and source files for the class.
2066 The wizard supports namespaces. To use a namespace, enter a qualified
2067 class name in the \gui {Class name} field. For example:
2068 MyNamespace::MySubNamespace::MyClass.
2070 \image qtcreator-cpp-class-wizard.png "Enter Class Name dialog"
2072 The names of the header and source file are based on the class name. To change the
2073 default suffix of a file, click \gui Configure.
2075 You can create your own project and class wizards. For more information,
2076 see \l{Adding New Custom Wizards}.
2078 \section2 Displaying Additional File Types in Projects Pane
2080 Qt Creator determines whether to display files from the project folder
2081 in the \gui Projects pane depending on the file type (.pro, .pri, .cpp,
2082 .h, .ui, .qrc, and so on). To display other types of files, edit the the
2083 project file. Add filenames as values of the \c {OTHER_FILES} variable.
2084 You can also use wildcards.
2086 For example, the following code specifies that text files are displayed
2087 in the \gui Projects pane:
2091 OTHER_FILES += *.txt
2095 This also makes the files available in the \gui Locator.
2097 \section1 Adding Subprojects to Projects
2099 When you create a new project, you can add it to another project as a subproject
2100 in the \gui{Project Management} dialog. However, you first have to edit the
2101 .pro file of the parent project to specify that qmake uses the \c subdirs template
2102 to build the project.
2104 The \c subdirs template creates a Makefile for building subprojects. They can be
2105 located either in subdirectories of the project directory or in any other directory.
2106 The location of the targets is specified using the SUBDIRS variable. If the project file
2107 has the same name as the directory, you can just specify the directory name. If the project
2108 name and directory name are different, you must specify the project file name (.pro).
2110 For more information on the SUBDIRS variable, see the
2111 \l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#subdirs}{qmake Variable Reference}.
2113 For example, the following code specifies that plugin_coreplugin/plugin_coreplugin.pro
2114 and mylogin.pro belong to the project:
2119 SUBDIRS = plugin_coreplugin \
2120 ../another/plugin/myplugin.pro
2123 To specify dependencies, use the \gui{Add Library} wizard. For more information,
2124 see \l{Adding Libraries to qmake Projects}.
2130 \contentspage index.html
2131 \previouspage creator-project-managing-sessions.html
2132 \page creator-project-wizards.html
2133 \nextpage creator-editor-using.html
2135 \title Adding New Custom Wizards
2137 If you have a team working on a large application or several applications,
2138 you might want to standardize the way the team members create projects
2141 You can copy the wizard templates in the template folders
2142 to create your own project and class wizards. They are displayed in the
2143 \gui New dialog that opens when you choose \gui {File > New File or Project}.
2145 In a project wizard, you can specify the files needed in a project.
2146 You can add wizard pages to allow developers to specify settings for the
2149 In a class wizard, you can allow developers to specify the class name, base
2150 class, and header and source files for the class.
2152 To see how this works, rename wizard_example.xml as wizard.xml in the helloworld
2153 and listmodels folders. After you restart Qt Creator, the \gui {Custom Classes}
2154 and \gui {Custom Projects} categories appear in the \gui New dialog.
2156 \image qtcreator-custom-project-wizards.png "The New dialog with custom projects and classes"
2158 \section1 Overview of Custom Wizards
2160 A custom wizard defines the user interface of a wizard page. The values the user enters
2161 in the wizard are assigned field names. Field name and value pairs are then passed to
2162 the file creation process. File creation can happen in the following ways:
2166 \o Template-based, where source files that contain placeholders for
2167 the field names are provided. During processing, the placeholders are replaced
2168 by the values from the wizard page. Optionally, modifier
2169 characters are applied. For more information, see \l{Processing Template Files}.
2171 \o Generator script, where a script is called to create the files.
2173 \note This option mainly exists to accommodate existing generator scripts or
2174 cases where complicated algorithmic logic is required when generating files. Writing
2175 cross-platform scripts is inherently difficult, and therefore, it is not recommended
2176 for new wizards. For more information, see \l{Using Generator Scripts}.
2180 Custom wizards are located in subdirectories of the following directories:
2184 \o \c{share/qtcreator/templates/wizards}
2186 \o the local user's configuration folder,
2187 \c{$HOME/.config/Nokia/qtcreator/templates/wizards}
2189 \o \c{%APPDATA%\Nokia\qtcreator\templates\wizards}
2193 They contain an XML configuration file called wizard.xml, the
2194 template source files, and optionally, the generator script.
2196 \section1 Creating Project Wizards
2198 To create a project wizard:
2202 \o Make a copy of the \c {share/qtcreator/templates/wizards/helloworld} or
2203 \c {share/qtcreator/templates/wizards/listmodel} folder.
2205 \o Modify the wizard_example.xml file.
2207 \o The following code determines the type of the wizard and its place
2208 in the \gui New dialog:
2212 <wizard version="1" kind="project"
2213 class="qt4project" firstpage="10"
2214 id="A.HelloWorld" category="B.CustomProjects">
2220 \o \c version is the version of the file contents. Do not modify this value.
2222 \o \c kind specifies the type of the wizard: \c project or \c class.
2224 \o \c class specifies the type of the project. Currently the only available
2225 type is \c qt4project, which specifies a Qt console project.
2227 \o \c firstpage specifies the place of the new page in the standard project
2228 wizard. The value 10 ensures that the custom page appears after the standard
2229 pages, as the last page of the wizard.
2231 \o \c id is the unique identifier for your wizard. The letter specifies the
2232 position of the wizard within the \c category. The HelloWorld wizard appears
2233 as the first wizard in the second category in the \gui New dialog.
2235 \o \c category is the category in which to place the wizard in the list.
2236 The letter specifies the position of the category in the list in the \gui New
2241 \o The following code specifies the icon and text that appear in the \gui New
2246 <icon>console.png</icon>
2247 <description>Creates a hello-world-project with custom message.</description>
2248 <description xml:lang="de">Erzeugt ein Hello-Welt-Projekt mit einer Nachricht.</description>
2249 <displayname>Hello World</displayname>;
2250 <displayname xml:lang="de">Hallo Welt</displayname>;
2251 <displaycategory>Custom Projects</displaycategory>
2252 <displaycategory xml:lang="de">Benutzerdefinierte Projekte</displaycategory>
2259 \o \c icon appears next to the \c displayName.
2261 \o \c description appears at the bottom of the \gui New dialog when you
2262 select the display name.
2264 \o \c displayName appears in the \gui New dialog, under the
2267 You can add translations as values for the text elements. Specify the target
2268 language as an attribute for the element. Use locale names (QLocale).
2269 For example, \c {xml:lang="de"}.
2273 \o Files to be added to the project:
2276 \o Template-based: The following code specifies the files to add to the project:
2279 <file source="main.cpp" openeditor="true" />
2280 <file source="project.pro" target="%ProjectName%.pro" openproject="true" />
2281 <file source="icon.png" target="%ProjectName%.png" binary="true" />
2285 \o \c source specifies the file to copy to the project. The files must be
2286 located in the wizard folder.
2288 \o \c openeditor indicates that the file is to be opened in an editor after
2289 the wizard has finished.
2291 \o \c binary indicates that the file is a binary file (for example, an
2292 image file). It is to be copied to the target folder as is. Placeholders
2293 are not replaced with values.
2295 \o \c target specifies the new filename for the file. The \c {%ProjectName%}
2296 variable is replaced with the string that users specify in the \gui Name
2297 field on the first page of the wizard.
2299 \o \c openproject indicates that the file is a project file which is to be opened
2300 after the wizard has finished.
2304 See also \l{Processing Template Files}.
2306 \o Generator-script: The following code specifies that the script \c generate.pl is to be used
2307 to create the files:
2309 <generatorscript binary="generate.pl">
2310 <argument value="--class-name=%ClassName%"/>
2311 <argument value="--project-name=%ProjectName%"/>
2312 <argument value="--header-suffix=%CppHeaderSuffix%" omit-empty="true"/>
2313 <argument value="--source-suffix=%CppSourceSuffix%" omit-empty="true"/>
2314 <argument value="--description=%Description%" omit-empty="true" write-file="true"/>
2317 In each argument, the field placeholders are replaced by the field
2318 values. There are additional boolean attributes which give fine-grained control:
2321 \o \c omit-empty specifies that complete argument is to be omitted when all
2322 placeholders expand to empty values. In the above example,
2323 the option \c --source-suffix will not be passed to the script if the value is empty.
2325 \o \c write-file indicates that instead of the expanded value,
2326 the value will be written to a temporary file and its file name will be
2327 passed to the script instead. This is useful for multi-line text fields.
2330 See also \l{Using Generator Scripts}.
2333 \o The following code creates a page that specifies settings for the project:
2337 <!-- Create a 2nd wizard page with parameters -->
2338 <fieldpagetitle>Hello World Parameters</fieldpagetitle>
2339 <fieldpagetitle xml:lang="de">Hallo Welt Parameter</fieldpagetitle>
2341 <field mandatory="true" name="MESSAGE">
2342 <fieldcontrol class="QLineEdit" validator='^[^"]+$' defaulttext="Hello world!" />
2343 <fielddescription>Hello world message:</fielddescription>
2344 <fielddescription xml:lang="de">Hallo-Welt-Nachricht:</fielddescription>
2352 \o \c fieldpagetitle specifies the title of the page.
2354 \o \c field specifies whether the field is mandatory (\c true or \c false).
2355 You can use the value of the \c name field as a variable in other files (for
2356 example, \c {%MESSAGE%}.
2358 \o \c fieldcontrol specifies the field. \c class specifies the field type.
2359 You can use interface objects from the QWidget class to create fields. This
2360 example uses QLineEdit to create an input field.
2362 \o \c validator specifies a regular expression to check the characters allowed in
2365 \o \c defaulttext specifies text that appears in the field by default.
2367 \o \c fielddescription specifies the field name that appears on the wizard page.
2373 \section1 Creating Class Wizards
2375 The widget.xml file for a class wizard is very similar to that for a project
2376 wizard. The differences are discussed below.
2378 To create a class wizard:
2382 \o The following code specifies settings for the wizard:
2386 <wizard version="1" kind="class" id="A.ListModel" category="B.CustomClasses">
2388 <description>Creates a QAbstractListModel implementation.</description>
2389 <description xml:lang="de">Erzeugt eine Implementierung von QAbstractListModel.</description>
2391 <displayname>QAbstractListModel implementation</displayname>
2392 <displayname xml:lang="de">Implementierung von QAbstractListModel</displayname>
2394 <displaycategory>Custom Classes</displaycategory>
2395 <displaycategory xml:lang="de">Benutzerdefinierte Klassen</displaycategory>
2399 For more information about the elements and their values, see
2400 \l {Creating Project Wizards}.
2402 \o The following code specifies the files to add to the project:
2407 <file source="listmodel.cpp" target="%ClassName:l%.%CppSourceSuffix%" openeditor="true" />
2408 <file source="listmodel.h" target="%ClassName:l%.%CppHeaderSuffix%" openeditor="true" />
2413 Here, \c target contains the following variables that are used to construct
2418 \o \c {%ClassName:l%} is replaced with the value of the \c ClassName field.
2419 The modifier \c l converts the string to lower case, to observe Qt
2422 \o \c {%CppSourceSuffix%} and \c {%CppHeaderSuffix%} are pre-defined.
2423 For more information, see \l{Pre-defined Standard Variables}.
2429 <!-- Create parameter wizard page -->
2431 <fieldpagetitle>ListModel parameters</fieldpagetitle>
2432 <fieldpagetitle xml:lang="de">Parameter des ListModel</fieldpagetitle>
2434 <field name="ClassName">
2436 <fieldcontrol class="QLineEdit" validator="^[a-zA-Z0-9_]+$" defaulttext="MyListModel" />
2438 <fielddescription>Class name:</fielddescription>
2439 <fielddescription xml:lang="de">Klassenname:</fielddescription>
2441 <field name="Datatype">
2443 <fieldcontrol class="QComboBox" combochoices="QString,int" defaultindex="0" />
2445 <fielddescription>Data type:</fielddescription>
2446 <fielddescription xml:lang="de">Datentyp:</fielddescription>
2452 In addition to QLineEdit, QComboBox is used in the class wizard to create
2453 a field. \c combochoices specifies the options in the combobox and
2454 \c defaultindex specifies that QString is the default value.
2458 \section1 Processing Template Files
2460 When processing a template source file, placeholders specifying the field names
2461 in the format \c{%FIELDNAME%} are replaced by the values entered by the user.
2462 In addition, modifier characters are supported. For example, \c{%FIELDNAME:u%}
2463 specifies that the value is converted to upper case. This enables generating header
2464 guards for C++ header files.
2466 The following modifier characters are supported:
2469 \o \c{l} for lower case.
2470 \o \c{u} for upper case.
2471 \o \c{c} for upper case initial letter ("project" > "Project").
2474 You can use conditions to add sections of the file depending on field values.
2475 Use a syntax that is similar to C++ preprocessing, as demonstrated in
2476 the profile of the \c{helloworld} example:
2480 @if "%SCRIPT%" == "true"
2486 The value of the Boolean (QCheckBox) field labeled \c{SCRIPT} determines
2487 whether the script module is added. The expressions must expand to valid
2488 Javascript expressions after field replacement.
2490 \section1 Pre-defined Standard Variables
2492 In addition to the field values entered by the user, you can use
2493 the following pre-defined standard values:
2497 \o \c {%ProjectName%} is replaced by the name of the project in the case
2500 \o \c {%Path%} is replaced by the path to the target directory.
2501 For classes, this is the directory, where the files
2502 are created. For project wizards, an additional subdirectory
2503 named after the project is created.
2505 \o \c {%TargetPath%} is replaced by the path to the directory where the actual files
2506 are created. For non-project wizards, it is identical to \c %Path%.
2507 For project wizards, it is \c %Path%/%ProjectName%.
2509 \o \c {%CppSourceSuffix%} is replaced by the default source suffix, which
2510 is defined in Qt Creator in \gui {Tools > Options... > C++ > File Naming}.
2511 For example, if users enter \bold MyClass, the filename becomes myclass.cpp
2512 when the project is created.
2514 \o \c {%CppHeaderSuffix%} is replaced by the default header suffix, which
2515 is also defined in \gui {File Naming}.
2519 \section1 Validating User Input
2521 You can specify validation rules for user input. The rules consist of a Boolean
2522 JavaScript expression and an error message. The placeholders in them are
2523 replaced with values before they are evaluated or displayed.
2525 Consider the following rule used in the \l{Creating Class Wizards} example:
2529 <validationrule condition='"%ClassName%" != "QAbstractListModel"'>
2530 <message>%ClassName% cannot be used as class name.</message>
2531 <message xml:lang="de">%ClassName% kann nicht als Klassenname verwendet werden.</message>
2536 It ensures that the class name entered by the user does not match the name of
2537 the base class. If the validation fails, a red label displaying the message appears
2538 at the bottom of the wizard page.
2540 \section1 Using Generator Scripts
2542 The values entered in the wizard page are passed to the script
2543 as command line arguments as defined by the wizard configuration file.
2545 In addition, the script must implement a \c{--dry-run} command line option.
2547 Qt Creator needs to know the file names before the files are created to check
2548 whether files with identical names already exist, for example. Therefore,
2549 script file generation is a two-step process:
2553 \o Determine file names and attributes: The script is called with the command line
2554 \c{--dry-run} option and the field values. It then prints the relative path
2555 names of the files it intends to create, followed by comma-separated attributes
2556 matching those of the \c{<file>} element, for example:
2559 myclass.cpp,openeditor
2560 myclass.h,openeditor
2561 myproject.pro,openproject
2564 \o Create files: The script is called with the parameters only in the working directory.
2565 It then actually creates the files. If directories are needed, the script
2566 should create them, too.
2570 The \c{scriptgeneratedproject} sample wizard illustrates the usage.
2571 A typical script invocation for this example (obtained by running Qt Creator with
2572 \c{--customwizard-verbose}) looks as follows:
2575 generate.pl --class-name=TestClass --project-name=TestProject --header-suffix=h --source-suffix=cpp --description=/tmp/qtcreatorj26629.txt
2578 By default, the scripts are run in the directory corresponding to
2579 \c %TargetPath%. This can be overriden by specifying the
2580 attribute \c workingdirectory on the element \c generatorscript.
2581 For example, if the script creates the project directory by itself,
2582 %Path% can be specified. In that case, \c --dry-run should output
2583 the correct relative paths or absolute paths constructed using the value of
2590 \contentspage index.html
2591 \previouspage creator-project-creating.html
2592 \page creator-project-qmake.html
2593 \nextpage creator-project-qmake-libraries.html
2595 \title Setting Up a qmake Project
2597 The qmake tool helps simplify the build process for development projects
2598 across different platforms. qmake automates the generation of makefiles
2599 so that only a few lines of information are needed to create each makefile.
2600 qmake can be used for any software project, whether it is written in Qt or not.
2602 The qmake tool generates a makefile based on the information in a project
2603 file that is generated by Qt Creator. It can generate makefiles for MinGW,
2604 Microsoft Visual studio, and CSL ARM in Windows, and GNU Compiler Collection
2605 (GCC) in Linux and Mac OS X.
2607 For more information about qmake, see the
2608 \l{http://qt.nokia.com/doc/4.7/qmake-manual.html}{qmake Manual}.
2610 \section1 Selecting the Qt Version
2612 Qt Creator allows you to have multiple versions of Qt installed on
2613 your development PC and use different versions for each of your projects.
2615 If Qt Creator finds \bold qmake in the \c{PATH} environment variable, it uses
2616 that version. The \l{glossary-system-qt}{ qmake version of Qt} is referred
2617 to as \bold{Qt in PATH}. If you intend to use only one version of Qt and it
2618 is already in the \c{PATH} and correctly set up for command line use, you do
2619 not need to manually configure your Qt version.
2621 \section2 Compiling Projects with MinGW in Windows
2623 To add a Qt version for \bold MinGW:
2625 \o Select \gui Tools > \gui Options... > \gui Qt4 >
2627 \o Click \inlineimage qtcreator-windows-add.png
2628 and enter the name of the version in the \gui{Version name} field.
2629 \o Enter the qmake binary path in the \gui{qmake location} field.
2630 \o Enter the MinGW installation path in the \gui{MinGW directory} field.
2632 \image qtcreator-qt4-qtversions-win-mingw.png
2635 \section3 Troubleshooting MinGW Compilation Errors
2637 If error messages displayed in the \gui {Compile Output} pane contain
2638 paths where slashes are missing (for example, C:QtSDK),
2639 check your PATH variable. At the command line, enter the following commands:
2644 where mingw32-make.exe
2647 If these commands show paths, they have been added to the global PATH variable
2648 during the installation of a toolkit based on Cygwin or MinGW, even though
2649 this is against Windows conventions.
2651 To keep working with the third-party toolkit, create a new shell link
2652 that adds the required paths (as Visual Studio and Qt do). The shell link
2653 must point to cmd.exe, as illustrated by the following example:
2655 \c {C:\Windows\System32\cmd.exe /K C:\path_to\myenv.bat}
2657 where the /K parameter carries out the command specified in the bat file.
2659 Create the myenv.bat file at \e path_to, which should be in a convenient location.
2660 In the file, specify the paths to the toolkits. For example,
2662 \c {set PATH=C:\path1;C:\path2;%PATH%}
2664 where \e path1 and \e path2 are paths to the toolkits.
2666 Finally, remove the paths from the global PATH, reboot the computer, and
2667 run the \c where commands again to verify that the global PATH is now clean.
2669 You can use the shell link to run the tools in the third-party toolkits.
2671 \section2 Compiling Projects with Microsoft Visual C++
2673 To add a Qt version for a \bold{Microsoft Visual C++} compiler:
2675 \o Select \gui Tools > \gui Options... > \gui Qt4 >
2677 \o Qt Creator automatically sets the correct environment variables for
2678 compilation. Select the internal version number of the installed
2679 Microsoft Visual C++ tool chain in the \gui Toolchain list.
2681 \image qtcreator-qt4-qtversions-win-msvc.png
2683 \o If the \gui {Debugging helper} is not in use, click \gui Rebuild
2684 to take it to use. For more information, see \l{Using Debugging Helpers}.
2688 \section2 Compiling Qt for Symbian Projects
2690 If you are using \bold{Qt for Symbian} and your Symbian SDK is registered
2691 with devices.exe, Qt Creator automatically detects the Qt version. To add a
2692 Qt for Symbian version:
2694 \o Select \gui Tools > \gui Options... > \gui Qt4 >
2696 \o Select the \gui{S60 SDK} you want the Qt Creator to use.
2698 \image qtcreator-qt4-qtversions-win-symbian.png
2699 \o To build an application for your device using GCCE, enter the path
2700 to the CSL ARM toolchain directory in
2701 \gui{CSL\\GCCE Directory}.
2703 You do not need to specify this path if the compiler is included in
2704 the \c{PATH} environment variable.
2705 \o To build an application for the emulator (WINSCW toolchain), enter
2706 the path to your Carbide C++ installation directory in
2707 \gui{Carbide directory}.
2709 \note You need to have Carbide C++ version 2.0 or later installed.
2712 \section2 Compiling Projects With Linux
2714 To compile a project in Qt Creator, Linux uses GNU Compiler Collection
2715 (GCC). Intel Compiler Collection (ICC) is supported as a drop-in
2716 replacement for GCC.
2718 To add a Qt version:
2720 \o Select \gui Tools > \gui Options... > \gui Qt4 >
2722 \o Click \inlineimage qtcreator-linux-add.png
2723 and enter the name of the version in \gui{Version Name}.
2724 \o Enter the path to the qmake binary in \gui{Path to qmake}.
2727 \section2 Compiling Projects With Mac OS X
2729 To compile a project in Qt Creator, Mac OS X uses GNU Compiler Collection
2730 (GCC), which is part of Xcode.
2732 To add a Qt version:
2734 \o Select \gui{Qt Creator} > \gui Preferences... > \gui{Qt Versions}.
2735 \o Click \inlineimage qtcreator-macosx-add.png
2736 and enter the name of the version in \gui{Version Name}.
2737 \o Enter the path to the qmake binary in \gui{Path to Qmake}.
2739 \image qtcreator-qt4-qtversions.png
2746 \contentspage index.html
2747 \previouspage creator-project-qmake.html
2748 \page creator-project-qmake-libraries.html
2749 \nextpage creator-project-cmake.html
2751 \title Adding Libraries to qmake Projects
2753 In addition to Qt libraries, you can add other libraries to your projects.
2754 The way the library is added depends on whether it is a system library or
2755 your own library or a 3rd party library located in the build tree of the
2756 current project or in another build tree.
2758 \image qtcreator-add-library-wizard.png "Add Library wizard"
2760 Because system libraries do not typically change and are often found by
2761 default, you do not need to specify the path to the library or to its includes
2764 For your own libraries and 3rd party libraries, you need to specify
2765 the paths. Qt Creator tries to quess the include path for an external library,
2766 but you need to check it and modify it if necessary. Qt Creator automatically
2767 adds the include path for an internal library.
2769 For all libraries, select the target platforms for the application, library,
2772 Specify whether the library is statically or dynamically linked. For a
2773 statically linked internal library, Qt Creator adds dependencies
2774 (PRE_TARGETDEPS) in the project file.
2776 Depending on the development platform, some options might be detected
2777 automatically. For example, on Mac OS, the library type (\gui Library or
2778 \gui Framework) is detected automatically and the option is hidden. However,
2779 if you develop on another platform than Mac OS and want to build your
2780 project for the Mac OS, you must specify the library type.
2782 The default convention on Windows is that the debug and release versions
2783 of a library have the same name,
2784 but are placed in different subdirectories, usually called \e debug and
2785 \e release. If the library path does not contain either of these folders,
2786 you cannot select the option to place the libraries in separate
2789 Alternatively, the letter \e d can be added to the library name for the debug
2790 version. For example, if the release version is called example.lib, the
2791 debug version is called exampled.lib. You can specify that the letter
2792 is added for the debug version and removed for the release version.
2793 If the library name ends in \e d, deselect the \gui {Remove "d" suffix
2794 for release version} option.
2796 Qt Creator supports code completion and syntax highlighting for the added
2797 libraries once your project successfully builds and links to them.
2799 \section1 To Add Libraries
2803 \o In the \gui Projects pane, open the project file (.pro).
2805 \o Right-click in the code editor to open the context menu and select
2806 \gui {Add Library...}.
2808 \o Follow the instructions of the wizard.
2812 For more information about the project file settings, see
2813 \l{http://doc.qt.nokia.com/4.7/qmake-project-files.html#declaring-other-libraries}{Declaring other Libraries}.
2815 \section1 Example of Adding Internal Libraries
2817 The following example describes how to add a statically linked internal
2818 library to your project.
2822 \o Choose \gui {File > New File or Project... > Other Projects >
2823 C++ Library} to create the library.
2825 The \gui {Introduction and Product Location} dialog opens.
2827 \image qtcreator-add-library-wizard-ex-1.png "Introduction and Product Location dialog"
2829 \o In the \gui Type field, select \gui {Statically Linked Library}.
2831 \o In the \gui Name field, give a name for the library. For example,
2834 \o Follow the instructions of the wizard until you get to the
2835 \gui {Project Management} dialog. In the \gui {Add to project}
2836 list, select a project. For example, \bold myapp.
2838 \o In the \gui Projects pane, open the project file (.pro).
2839 For example, \bold myapp.pro.
2841 \o Right-click in the code editor to open the context menu and select
2842 \gui {Add Library... > Internal Library > Next}.
2844 \o In the \gui Library field, select \bold mylib and click \gui Next.
2846 \o Click \gui Finish to add the following library declaration to the
2850 win32:CONFIG(release, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/release/ -lmylib
2851 else:win32:CONFIG(debug, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/debug/ -lmylib
2852 else:symbian: LIBS += -lmylib
2853 else:unix: LIBS += -L$$OUT_PWD/../../../projects/mylib/ -lmylib
2855 INCLUDEPATH += $$PWD/../../../projects/mylib
2856 DEPENDPATH += $$PWD/../../../projects/mylib
2858 win32:CONFIG(release, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/release/mylib.lib
2859 else:win32:CONFIG(debug, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/debug/mylib.lib
2860 else:unix:!symbian: PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/libmylib.a
2869 \contentspage index.html
2870 \previouspage quick-application-logic.html
2871 \page creator-building-running.html
2872 \nextpage creator-building-targets.html
2874 \title Building and Running Applications
2876 Qt Creator provides support for building and running Qt applications for
2877 desktop environment and mobile devices. When you install the \QSDK,
2878 the build and run settings for the Maemo and Symbian targets are
2879 set up automatically.
2881 You can add a target if the necessary tool chain is installed on the
2882 development PC and the Qt version is configured. Click
2883 \inlineimage qtcreator-qt4-addbutton.png "Add Target button"
2884 and select from a list of available
2885 targets. To remove a target, select it and click
2886 \inlineimage qtcreator-target-remove.png "Remove Target button"
2889 You can select the targets and click the \gui Run button to build and
2890 run the applications on the targets. You can click the \gui {Build All}
2891 button to build all open projects, one after another.
2893 \section1 Setting Up a Project
2895 To view and modify the settings for currently open projects, switch to the
2896 \gui Projects mode by pressing \key Ctrl+5.
2898 \image qtcreator-projectpane.png
2900 The project pane consists of the following tabs:
2902 \o \l{Building for and Running on Multiple Targets}{Targets}
2903 \note If you have installed only one tool chain, the \gui Targets
2904 tab is replaced by a \gui {Build and Run} tab.
2905 \o \l{Specifying Editor Settings}{Editor Settings}
2906 \o \l{Specifying Dependencies}{Dependencies}
2909 Use the \gui Build and \gui Run buttons to switch between
2910 the build and run settings for the active project.
2912 If you have multiple projects open in Qt Creator, use
2913 \gui{Select a Project} option at the top to navigate between different
2920 \contentspage index.html
2921 \previouspage creator-building-running.html
2922 \page creator-building-targets.html
2923 \nextpage creator-build-settings.html
2925 \title Building for and Running on Multiple Targets
2927 You can build your application for multiple targets and run and debug it
2928 on the desktop and mobile devices. When you run the application on the
2929 \gui{Maemo} or \gui {Symbian Devices} target, Qt Creator copies the necessary
2930 files to the device that is connected to the deveopment PC. In addition, Qt
2931 Creator generates an installation package in the build directory. You can
2932 specify settings for deploying the files and creating the installation package.
2934 \section1 Building for and Running on Desktop
2938 \o Select \gui Desktop as the target.
2940 \o Click the \gui Run button.
2944 \section1 Building for and Running on Qt Simulator
2946 You can use the Qt Simulator to test Qt applications that are intended
2947 for mobile devices in an environment similar to that of the device. You
2948 can change the information that the device has about its configuration
2953 \o Select \gui {Qt Simulator} as the target.
2955 \o Click the \gui Run button.
2959 For more information about using the Qt Simulator, see the
2960 \l{http://doc.qt.nokia.com/qt-simulator-beta/index.html}{Qt Simulator Manual}.
2962 \section1 Building for and Running on Maemo
2966 \o Build and run the application for \l{Building for and Running on Qt Simulator}{Qt Simulator}.
2968 \o Build and run the application for \l{Using the Maemo Emulator}{Maemo Emulator}.
2970 \o Alternatively, you can build and run the application for a device:
2974 \o Set up the MADDE development environment and specify a connection
2975 to the device. For more information, see
2976 \l{Setting Up Development Environment for Maemo}.
2978 \o Connect the device to the development PC.
2980 \o Click the \gui Run button.
2986 Qt Creator uses the compiler specified in the MADDE toolchain to
2987 build the application.
2989 Qt Creator generates an installation package, installs it on the device,
2990 and executes the selected application.
2991 The application views are displayed on the Nokia N900.
2993 output is visible in the Qt Creator \gui {Application Output} view.
2995 Choose \gui {Projects > Maemo Run} to view the settings for deploying the
2996 application on the connected device and creating the installation package.
2997 For more information, see \l{Specifying Run Settings for Maemo Devices}.
2999 Debugging also works transparently.
3001 \section1 Building for and Running on Symbian
3005 \o Build and run the application for \l{Building for and Running on Qt Simulator}{Qt Simulator}.
3007 \o If no problems are found, build and run the application for a device.
3009 \o To test functionality that uses Symbian APIs, you can build and
3010 run the application for Symbian Emulator.
3014 The build configuration for the \gui{Symbian Device} target
3015 uses the GCCE tool chain by default. If you want to build
3016 for the device using RVCT, select it in the \gui {Tool chain} field
3017 in the \gui{General} section.
3019 \section2 Building and Running for a Device
3023 \o Install the required software on the device. For more information, see
3024 \l{Setting Up Development Environment for Symbian}.
3026 \o Connect the device to the development PC through a USB cable.
3027 The target selector displays a green check mark when a
3028 device is connected.
3030 \image qtcreator-qt4-symbian-device-connected.png
3032 The tool tip of the target selector shows more details about the actual
3033 device that will be used when you run your application.
3035 \o Start the \gui{App TRK} application on your device.
3037 \o Click the \gui Run button.
3041 You can connect several devices to your development PC simultaneously.
3042 In the details of the run configuration for the \gui{Symbian Device} target,
3043 select the device to run your application on.
3045 When you build the application for the \gui{Symbian Device} target, Qt
3046 Creator automatically generates a Symbian installation system (SIS) file
3047 in the project folder. You can deliver the installation file to users for
3048 installation on Symbian devices.
3050 When your application is ready for delivery to users, specify run settings
3051 for creating the final SIS installation packages. For more information,
3052 see \l{Creating SIS Installation Packages}.
3054 \section2 Building and Running for Symbian Emulator
3057 the \gui{Symbian Emulator} target as the active one, and build and run your
3060 \section2 Troubleshooting
3062 If you cannot build the application, check if:
3064 \o You selected the Symbian Device target for building the application.
3065 \o The settings for the Qt version you use to build your project are
3066 correct. The path to the Symbian SDK must point to the Symbian SDK
3067 installation directory. Select \gui Tools > \gui Options...
3068 > \gui Debugger > \gui{Symbian TRK} and check if it points to the
3071 If you cannot run the application on a device, check if:
3073 \o The device is connected through the USB cable in \e{PC Suite} mode.
3074 \o \gui{App TRK} is running on the device, using the USB connection,
3075 with the status \e connected.
3076 \o The device is detected and selected in the run configuration
3080 If you cannot run the application in the emulator, check if:
3082 \o You selected the \gui{Symbian Emulator} target for your application.
3084 \o If you cannot select \gui {Symbian Emulator} as target, check that
3085 Carbide.c++ is installed correctly and that the path to the Carbide.c++
3086 installation directory is specified in the \gui{Carbide directory} field
3087 in the build settings.
3089 \o If the emulator process cannot be started, try closing Qt Creator and
3090 starting the application directly from your file manager. Having
3091 done this, Qt Creator should be able to run your projects in the
3096 \note Qt Creator does not create release configurations for the
3097 \gui {Symbian Emulator} target, because Symbian Emulator supports only debug
3100 If this does not help to solve your problem, search the qt-creator@trolltech.com
3101 mailing list archives or provide feedback to us via the methods described on the
3102 \l{http://qt.gitorious.org/qt-creator/pages/Home}{Qt Creator Development Wiki}.
3105 \section1 Building with Remote Compiler
3107 The \gui {Remote Compiler} target is an interface to a compilation service at
3108 Forum Nokia. It provides a simple, standardized environment for building Qt
3109 applications and creating installation packages for Symbian and Maemo devices
3110 when you do not have the necessary tool chains and SDKs installed or they are
3111 not supported on the development PC. You can choose from a set of supported
3112 devices, such as S60 3rd Edition or S60 5th Edition devices.
3114 \note Remote Compiler is an experimental component that you must install
3115 separately from the package that is included in the \QSDK.
3119 \o In the \QSDK installation directory, double-click
3120 SDKMaintenanceTool.exe to install \gui {Experimental APIs}.
3122 \o In Qt Creator, choose \gui {Tools > Options > Projects > Remote Compiler}
3123 to log on to Forum Nokia.
3125 \image remotecompiler-fn-logon.png "Remote Compiler options"
3127 \o Choose \gui {Projects}.
3130 \inlineimage qtcreator-qt4-addbutton.png "Add Target button"
3131 and select \gui {Remote Compiler} to add Remote Compiler as a target.
3133 \o Click \gui Add to add mobile device platforms as build configurations.
3135 \o Click the \gui {Target Selector} and select a build configuration.
3137 \o Choose \gui {Build > Build All}.
3141 The installation package is generated in the \gui {Build directory} on
3144 For more information about Remote Compiler, choose \gui {Help > Contents >
3145 Remote Compiler}. The document is added during the installation of experimental
3152 \contentspage index.html
3153 \previouspage creator-building-targets.html
3154 \page creator-build-settings.html
3155 \nextpage creator-run-settings.html
3157 \title Specifying Build Settings
3159 Different build configurations allow you to quickly switch between
3160 different build settings. By default, Qt Creator creates \bold debug
3161 and \bold release build configurations.
3163 You specify build settings in the \gui Projects mode.
3165 \image qtcreator-projectpane.png
3167 To add a new build configuration, click \gui Add and select the type of
3168 configuration you would like to add. You can add as many build
3169 configurations as you need.
3171 To delete the build configuration currently selected, click \gui Remove.
3173 \section1 Editing Build Configurations
3175 To edit a build configuration:
3177 \o Select the build configuration you want to edit in
3178 \gui{Edit Build Configuration}.
3179 \o In section \gui General, you can specify:
3181 \o The \l{glossary-project-qt}{Qt version} you want to use to
3182 build your project. For more information, see
3183 \l{Selecting the Qt version}.
3184 \o The tool chain required to build the project.
3185 \o By default, projects are built in a separate directory
3186 from the source directory, as \l{glossary-shadow-build}{shadow builds}.
3187 This keeps the files generated for each target platform separate.
3189 \note Shadow building is not supported by the Symbian build system.
3190 Also, shadow building on Windows is not supported for Maemo.
3191 If you only build for one target platform, you can deselect
3192 the \gui{Shadow build} checkbox.
3196 \section1 Build Steps
3198 The build system of Qt Creator is built on qmake and make. In
3199 \gui{Build Steps} you can change the settings for qmake and make. Qt
3200 Creator runs the make command using the Qt version defined for the current
3201 build configuration.
3203 \image qtcreator-build-steps.png "Build steps"
3205 \section2 Adding Custom Build Steps
3207 To add custom steps to the build settings, select \gui {Add Build Step >
3208 Custom Process Step}.
3210 By default, custom steps are disabled. To activate a custom step, select
3211 the \gui{Enable custom process step} check-box.
3213 \image qtcreator-build-steps-custom.png "Custom Process Step"
3215 You can use any environment variables as values in the fields. For a list
3216 of variable names, click \gui {Build Environment > Details}. Variables are
3217 referenced using the platform's native syntax: $VARNAME or ${VARNAME} on
3218 Unix and %VARNAME% on Windows.
3220 \section1 Clean Steps
3222 You can use the cleaning process to remove intermediate files. This process
3223 might help you to fix obscure issues during the process of building a
3226 \image qtcreator-clean-steps.png "Clean steps"
3228 You can define the cleaning steps for your builds in the \gui{Clean Steps}:
3230 \o To add a clean step using make or a custom process, click
3231 \gui{Add Clean Step} and select the type of step you want to add.
3233 By default, custom steps are disabled. To activate a custom step,
3234 select the \gui{Enable custom process step} check-box.
3235 \o To remove a clean step, click \gui{Remove Item}.
3236 \o To change the order of steps, click
3237 \inlineimage qtcreator-movestep.png
3241 \section1 Build Environment
3243 You can specify the environment you want to use for building in the
3244 \bold{Build Environment} section. By default, the environment in which Qt
3245 Creator was started is used and modified to include the Qt version.
3246 Depending on the selected Qt version, Qt Creator automatically sets the
3247 necessary environment variables. You can edit existing environment
3248 variables or add, reset and unset new variables based on your project
3251 \image qtcreator-build-environment.png "Build Environment"
3257 \contentspage index.html
3258 \previouspage creator-build-settings.html
3259 \page creator-run-settings.html
3260 \nextpage creator-editor-settings.html
3262 \title Specifying Run Settings
3264 Qt Creator automatically creates run configurations for your project.
3265 To view and modify the settings, select \gui {Projects > Run}.
3267 The settings to specify depend on the type of the project: qmake project
3268 or Qt Quick project.
3270 Click \gui Add to add run settings for a project and \gui Remove to remove
3271 the current settings.
3273 \section1 Specifying Run Settings for qmake Projects
3275 The run configurations for qmake projects derive their executable from the parsed .pro
3278 \section2 Specifying Run Settings for Desktop Targets
3280 You can specify command line arguments to be passed to the executable
3281 and the working directory to use. The working directory defaults to
3282 the directory of the build result.
3284 For console applications, check the \gui{Run in Terminal} check box.
3285 If you need to run with special environment variables set up, you
3286 also do it in the run configuration settings.
3288 \image qtcreator-pprunsettings.png
3290 You can also create custom executable run configurations where you
3291 can set the executable to be run. For more information, see
3292 \l{Specifying a Custom Executable to Run}.
3294 \section2 Specifying Run Settings for Symbian Devices
3296 Qt Creator automatically detects Symbian devices that are connected to
3297 the development PC with an USB cable.
3298 If only one device is detected, the application is deployed
3299 and run on it. If multiple devices are connected to the PC,
3300 make sure that the correct device is selected in the
3301 \gui {Symbian Device} run settings for your project.
3303 You can also pass command line arguments to your application on the device.
3304 Press the \gui{Device info button} to get more information about the selected
3305 device, such as the CPU type and the running TRK version.
3307 \image qtcreator-symbian-run-settings.png "Run settings for Symbian devices"
3309 \section3 Creating SIS Installation Packages
3311 When you build the application for the \gui{Symbian Device} target, Qt
3312 Creator automatically generates a Symbian installation system (SIS) file
3313 in the project folder. You can deliver the installation file to users for
3314 installation on Symbian devices.
3316 The name of the installation file is displayed in the \gui {Installation file}
3317 field. In the \gui {Installation drive} field, select the drive on the device
3318 to install the application to. To suppress notifications on the device during the
3319 installation, select the \gui {Silent installation} check box. If the silent
3320 installation fails, Qt Creator attempts installation again, this time displaying
3321 notifications and error messages.
3323 Only installation files signed with a certificate and private key are
3324 allowed to be installed onto Symbian devices. By default, Qt Creator
3325 self-signs the installation file. This self-signing allows you to install
3326 the application on a mobile device but places limits on what you can do
3327 with the installation file, including:
3329 \o Self-signed applications cannot access the more sensitive
3330 \l{Capabilities and Signing}{capabilities} of the mobile device.
3331 \o Security warnings will be displayed when you install the self-signed
3332 application on a mobile device.
3333 \o Self-signed applications cannot be distributed commercially on Ovi
3337 To get around these limitations, you need to go through the Symbian Signed
3338 process. The Symbian Signed organisation manages a public key
3339 infrastructure to provide public authentication of the information in the
3340 application signing certificates. Their security partner can validate your
3341 certificate and give you a Publisher ID. Then, when you sign an
3342 application, other people can be confident that the information in your
3343 certificate is correct and that the application does actually come from you.
3345 There are also options that do not require you to get a Publisher ID. For
3346 more detail about how the Symbian Signed process works, see
3347 \l{http://developer.symbian.org/wiki/index.php/Complete_Guide_To_Symbian_Signed}
3348 {Complete Guide to Symbian Signed}.
3350 When you have your own certificate and private key, you can specify them in
3351 the \gui{Create SIS Package} step in the run settings.
3353 \image qtcreator-qt4-symbian-signing.png
3356 If your private key is protected by a passphrase, Qt Creator asks you for the
3357 passphrase when the package is signed and offers to store it. However, storing
3358 passphrases in Qt Creator presents a security risk. To make Qt Creator forget
3359 all saved passphrases, click \gui {Reset Passphrases}.
3361 \section3 Capabilities and Signing
3363 Capabilities allow the Symbian platform to control access by applications to
3364 the functionality provided by the platform APIs. Access to capabilities is
3365 determined by the device configuration and how the application has been signed.
3367 Symbian Signed offers the following signing options depending on the
3368 capabilities that the application accesses:
3372 \o \bold{Express signed} for applications that access only user and system
3375 \o \bold{Certified signed} for applications that access also restricted or
3376 device manufacturer capabilities.
3378 \note You need to request the rights to access device manufacturer
3379 capabilities from the manufacturer.
3383 For more information about how to choose the appropriate signing option, see
3384 \l{http://developer.symbian.org/wiki/index.php/Symbian_Signed_For_Distributing_Your_Application}{Symbian Signed For Distributing Your Application}.
3386 If you select a signing option that does not allow the application to access
3387 the defined capabilities, installing the application on mobile devices
3388 fails. To avoid problems, only define capabilities and link libraries to a project
3389 if you really need them.
3391 For more information about capabilities and how you can check which ones you
3393 \l{http://developer.symbian.org/wiki/index.php/Capabilities_(Symbian_Signed)}{Capabilities (Symbian Signed)}
3395 \l{http://doc.qt.nokia.com/4.7/platform-notes-symbian.html#required-capabilities}{Required Capabilities for Qt Applications}.
3397 For more information on how to define capabilities for a project, see
3398 \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#capabilities}{Capabilities}.
3400 \section3 Creating Smart Installer for Symbian Packages
3402 To deploy Qt applications on Symbian devices, you must install the software that Qt applications
3403 require, typically Qt, QtWebkit, and Open C. Nokia Smart Installer for Symbian makes it easier
3404 for users to install Qt applications to Symbian phones by checking whether the device contains
3405 the necessary software and by installing the missing pieces.
3407 For this to work, the Nokia Smart Installer must be packaged with the Qt application. The
3408 application SIS file must first be Symbian Signed. The capabilities used in the applications
3409 determine, which signing option must be selected. The wrapper package must be signed using
3410 either the same option or a more extensive option than the application SIS.
3412 To package Nokia Smart Installer with the application, select the \gui {Create Smart Installer
3413 package} check box. This ensures that up-to-date and appropriate versions of Qt and its
3414 dependencies are installed on devices. Further, it reduces the file size of the application you
3415 publish, because you do not have to deliver the required applications.
3417 For more information about the Nokia Smart Installer, see the \e {Nokia Smart Installer for
3420 Note: Nokia Smart Installer for Symbian is only available on Windows.
3422 \section3 Application UID
3424 A UID is a globally unique identifier that is used to
3425 uniquely identify, for example, an object or file type. In Symbian development,
3426 objects are identified by compound identifiers that are constructed from three
3427 UIDs, namely UID1, UID2, and UID3. UID1 and UID2 specify the category of an
3428 object, whereas UID3 identifies a particular object, such as an application.
3430 When you create a \gui {Mobile Qt Application}, Qt Creator adds a UID3 suitable for
3431 development and debugging automatically to the application .pro file. However, to
3432 distribute your application and get it Symbian signed, you must apply for a UID
3433 from Symbian Signed, which manages the allocation of UIDs. You can request UIDs either one
3434 at a time or as preallocated blocks on the \l{https://www.symbiansigned.com/app/page}{Symbian Signed}
3437 Replace the testing UID with the distribution UID in the .pro file before you
3438 build the final installation package. For more information, see
3439 \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#unique-identifiers}{Unique Identifiers}.
3441 \section2 Specifying Run Settings for Maemo Devices
3443 To run an application on a Maemo device, create and select
3444 a device configuration in the Maemo run settings for your project.
3445 You can also pass command line arguments to your application.
3447 \image qtcreator-screenshot-run-settings.png "Run settings for Maemo devices"
3449 \section3 Deploying Applications to Maemo Devices
3451 You can specify settings for deploying applications to Maemo devices in the
3452 project .pro file. You can view the settings in the \gui {Run Settings}.
3454 The files to be installed are listed in the
3455 \gui {Deploy to Device} step, the \gui {Files to install} field. The
3456 \gui {Local File Path} field displays the location of the file on the development
3457 PC. The \gui {Remote Directory} field displays the folder where the file is installed on
3460 \image qtcreator-maemo-deployment.png "Deploy to device"
3462 If you develop your own libraries, Qt Creator needs to be able to access them
3463 during compilation. When you install MADDE, an instance of the device file
3464 system, called sysroot, is installed to the development PC. Libraries are copied to
3465 sysroot if the \gui {Also deploy to sysroot} check box is selected.
3467 \section3 Creating Debian Installation Packages
3469 When you run the application on the \gui{Maemo} target, Qt Creator generates
3470 a debian installation package in the build directory by default. You can deliver
3471 the installation package to users for installation on Maemo devices that are of
3472 the same type and run the same firmware as the connected device.
3474 \image qtcreator-maemo-deb-package.png "Create installation package"
3476 The name of the installation package is displayed in the \gui {Create Package}
3477 field in the \gui {Run Settings}. You can change the version number in the \gui {Version number} field.
3479 Qt Creator provides templates for a set of files that must be included
3480 in debian packages. To edit the files, select a file in \gui {Adapt debian
3481 file} and click \gui Edit. The file opens in the text editor.
3483 The debian control file contains an application icon in encoded form. To add the
3484 application icon to the file, select it in the \gui {Package manager icon} field.
3485 For more information about icon files and adding them manually, see
3486 \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}.
3488 \note Qt Creator automates this process for you.
3490 \section1 Specifying a Custom Executable to Run
3492 If you use cmake or the generic project type in Qt Creator, or want
3493 to run a custom desktop executable, create a \gui {Custom Executable}
3494 run configuration for your project.
3496 Specify the executable to run, command line arguments, working directory,
3497 and environment variables to use.
3499 \image qmldesigner-run-custom-exe.png "Run settings for custom executables"
3501 \section1 Specifying Run Settings for Qt Quick Projects
3503 Select run settings in the \gui {Run configuration} field. The settings
3504 are specified automatically and, you mostly need to change them if you
3505 develop applications that use both C++ and QML:
3509 \o \gui {Custom QML Viewer} is the path to the \QQV executable.
3510 Qt Creator ships with a specific version of \QQV and imported
3511 modules, which is used by default. If you develop Qt Quick applications
3512 that contain C++ plugins, you must select the \QQV version
3513 shipped with your Qt version here.
3515 \o \gui {QML Viewer arguments} sets arguments for running \QQV.
3516 The \c{-I <directory>} argument searches for C++ or QML plugins from
3517 the project folder. For a list of available arguments, enter \c {qml --help}
3518 on the command line.
3520 \o \gui {Main QML file} is the Qt Quick project file.
3522 \o \gui Debugger allows you to select the languages to debug:
3523 \gui{C++} and \gui QML. \gui {Debug port} is the port to access \QQV.
3524 You can use any free port in the registered port range.
3528 \note Opening a socket at a well-known port presents a security risk. Anyone
3529 on the Internet could connect to the application that you are debugging and
3530 execute any JavaScript functions. Therefore, you must make sure that the port
3531 is properly protected by a firewall.
3533 \image qmldesigner-run-settings.png "Run settings for Qt Quick projects"
3539 \contentspage index.html
3540 \previouspage creator-run-settings.html
3541 \page creator-editor-settings.html
3542 \nextpage creator-build-dependencies.html
3544 \title Specifying Editor Settings
3546 To define the default file encoding, select the desired encoding in \gui Projects >
3547 \gui{Editor Settings}. By default, the Qt Creator uses the file encoding
3548 used by your system.
3550 \image qtcreator-editor-settings.png "Editor Settings view"
3556 \contentspage index.html
3557 \previouspage creator-editor-settings.html
3558 \page creator-build-dependencies.html
3559 \nextpage creator-debugging.html
3561 \title Specifying Dependencies
3563 If you have multiple projects loaded in your session, you can define the
3564 dependencies between them. Inter-project dependencies affect the build
3565 order of your projects.
3567 \note Inter-project dependencies are unrelated inside a qmake
3570 \image qtcreator-build-dependencies.png "Dependencies view"
3572 To define the dependencies between projects:
3574 \o In \gui Projects, select a project.
3575 \o Click \gui Dependencies.
3576 \o Select projects as dependencies.
3583 \contentspage index.html
3584 \previouspage creator-quick-tour.html
3585 \page creator-getting-started.html
3586 \nextpage creator-build-example-application.html
3588 \title Getting Started
3590 This section contains examples that illustrate how to use Qt Creator
3591 to create, build, and run simple
3595 \o \l{Building and Running an Example Application}
3596 \o \l{Creating a Qt C++ Application}
3597 \o \l{Creating a Mobile Application with Qt SDK}
3598 \o \l{Creating a Qt Quick Application}
3605 \contentspage index.html
3606 \previouspage creator-writing-program.html
3607 \page creator-mobile-example.html
3608 \nextpage creator-qml-application.html
3610 \title Creating a Mobile Application with Qt SDK
3612 \note To complete this tutorial, you must install \QSDK.
3613 The installation program installs and configures the necessary tool chains
3614 for mobile application development.
3616 This tutorial describes how to use Qt Creator to create a small Qt
3617 application, Battery Indicator, that uses the System Information
3618 Mobility API to fetch battery information from the device.
3620 \image qtcreator-batteryindicator-screenshot.png
3622 \section1 Creating the Battery Indicator Project
3624 \note Create the project with the \gui{Help} mode active so that you can follow
3625 these instructions while you work.
3629 \o Select \gui{File > New File or Project > Qt C++ Project > Mobile Qt
3630 Application > Choose}.
3632 \image qtcreator-new-mobile-project.png "New File or Project dialog"
3634 The \gui{Introduction and Project Location} dialog opens.
3636 \image qtcreator-mobile-intro-and-location.png "Introduction and Project Location dialog"
3638 \o In the \gui{Name} field, type \bold {BatteryIndicator}.
3640 \o In the \gui {Create in} field, enter the path for the project files. For example,
3641 \c {C:\Qt\examples}, and then click \gui{Next}.
3643 The \gui{Qt Versions} dialog opens.
3645 \image qtcreator-mobile-project-qt-versions.png "Qt Versions dialog"
3647 \o Select \gui Maemo, \gui {Qt Simulator}, and \gui {Symbian Device} targets,
3648 and click \gui{Next}.
3650 \note Targets are listed if you installed the appropriate development
3651 environment, for example, as part of the \QSDK. You can add targets
3652 later in the \gui Projects mode.
3654 The \gui {Application Options} dialog opens.
3656 \image qtcreator-mobile-project-app-options.png "Application Options dialog"
3658 \o In the \gui {Orientation behavior} field, determine how the application
3659 behaves when the orientation of the device display rotates between portrait
3660 and landscape, and then click \gui{Next}.
3662 \note Qt Creator contains a default program icon and generates a UID for testing
3663 the application on a device. You only need to specify the \gui {Symbian Specific}
3664 and \gui {Maemo Specific} settings if you deliver the application for public use.
3666 The \gui{Project Management} dialog opens.
3668 \image qtcreator-mobile-project-summary.png "Project Management dialog"
3670 \o Review the project settings, and click \gui{Finish} to create the project.
3674 The BatteryIndicator project now contains the following files:
3678 \o BatteryIndicator.pro
3680 \o BatteryIndicator.svg
3681 \o BatteryIndicator.png
3682 \o BatteryIndicator.desktop
3687 \o templates for debian deployment files
3691 \image qtcreator-mobile-project-contents.png "Project contents"
3693 The files come with the necessary boiler plate code that you must
3694 modify, as described in the following sections.
3696 \section1 Declaring the Qt Mobility API
3698 To use the Qt Mobility APIs or develop applications for Symbian
3699 devices, you must modify the .pro file to declare the Qt Mobility APIs
3702 This example uses the System Info API, so you must declare it, as
3703 illustrated by the following code snippet:
3708 MOBILITY = systeminfo
3712 Each Mobility API has its corresponding value that you have to add
3713 as a value of MOBILITY to use the API. For a list of the APIs and the
3714 corresponding values that you can assign to MOBILITY, see the
3715 \l {http://doc.qt.nokia.com/qtmobility-1.0/quickstart.html}{Quickstart Example}.
3717 \section1 Designing the User Interface
3721 \o In the \gui{Editor} mode, double-click the mainwindow.ui
3722 file in the \gui{Projects} view to launch the integrated \QD.
3724 \o Drag and drop a \gui{Progress Bar} (\l{http://doc.qt.nokia.com/4.7/qprogressbar.html}{QProgressBar})
3727 \image qtcreator-mobile-project-widgets.png "Adding widgets to the UI"
3729 \o In the \gui Properties pane, change the \gui objectName to
3730 \bold batteryLevelBar.
3732 \o Right-click the \gui MainWindow object and select
3733 \gui {Lay Out > Lay Out Horizontally} to ensure that the battery
3734 indicator widget size is adjusted correctly on Maemo devices.
3738 \section1 Completing the Header File
3740 The mainwindow.h file contains some of the necessary #includes, a
3741 constructor, a destructor, and the \c{Ui} object. You must include
3742 the System Info header file, add a shortcut to the mobility name
3743 space, and add a private function to update the battery level value in
3744 the indicator when the battery power level changes.
3748 \o In the \gui{Projects} view, double-click the \c{mainwindow.h} file
3749 to open it for editing.
3751 \o Include the System Info header file, as illustrated by the following
3754 \snippet examples/batteryindicator/mainwindow.h 1
3756 \o Add a shortcut to the mobility name space, as illustrated by the
3757 following code snippet:
3759 \snippet examples/batteryindicator/mainwindow.h 2
3761 \o Declare a private function in the \c{private} section, after the
3762 \c{Ui::MainWindow} function, as illustrated by the following code
3765 \snippet examples/batteryindicator/mainwindow.h 3
3769 \section1 Completing the Source File
3771 Now that the header file is complete, move on to the source file,
3776 \o In the \gui{Projects} view, double-click the mainwindow.cpp file
3777 to open it for editing.
3779 \o Create a QSystemDeviceInfo object and set its value. Then connect the signal
3780 that indicates that battery level changed to the \c setValue
3781 slot of the progress bar. This is illustrated by the following code snippet:
3783 \snippet examples/batteryindicator/mainwindow.cpp 1
3785 \o Use the constructor to set initial values and make sure that the
3786 created object is in a defined state, as illustrated by the following
3789 \snippet examples/batteryindicator/mainwindow.cpp 2
3793 \section1 Compiling and Running Your Program
3795 Now that you have all the necessary code, select \gui {Qt Simulator}
3796 as the target and click the
3797 \inlineimage qtcreator-run.png
3798 button to build your program and run it in the Qt Simulator.
3800 In Qt Simulator, run the runOutOfBattery.qs example script
3801 to see the value change in the Battery Indicator application.
3802 Select \gui {Scripting > examples > runOutOfBattery.qs > Run}.
3804 \image qtcreator-mobile-simulated.png "Mobile example in Qt Simulator"
3806 \section1 Testing on a Symbian Device
3808 You also need to test the application on real devices. Before you can
3809 start testing on Symbian devices, you must connect them to the development
3810 PC by using an USB cable and install the necessary software on them.
3814 \o Install Qt libraries, Qt mobile libraries, and the TRK
3815 debugging application on the device. For more information,
3816 see \l{Setting Up Development Environment for Symbian}.
3818 \o Start TRK on the device.
3820 \o Click the \gui {Target Selector} and select \gui {Symbian Device}.
3822 \o Click \gui Run to build the application for the Symbian device.
3826 \section1 Testing on the Maemo Emulator
3828 The Maemo emulator emulates the Nokia N900 device environment. You can test
3829 applications in conditions practically identical to running the application
3830 on a Nokia N900 device with the software update release 1.2 (V10.2010.19-1).
3832 For more information, see \l{Using the Maemo Emulator}.
3837 \contentspage index.html
3838 \previouspage creator-getting-started.html
3839 \page creator-build-example-application.html
3840 \nextpage creator-writing-program.html
3842 \title Building and Running an Example Application
3844 You can test that your installation is successful by opening an existing
3845 example application project.
3849 \o On the \gui Welcome page, select \gui {Choose an Example... >
3850 Animation Framework > Animated Tiles}.
3852 \image qtcreator-gs-build-example-open.png "Selecting an example"
3854 \o Select targets for the project. Select at least Qt Simulator
3855 and one of the mobile targets, Maemo or Symbian Device, depending on
3856 the device you develop for.
3858 \image qtcreator-gs-build-example-targets.png "Selecting targets"
3860 \note You can add targets later in the \gui Projects mode.
3862 \o To test the application in Qt Simulator, click the \gui {Target
3863 Selector} and select \gui {Qt Simulator}.
3865 \image {qtcreator-gs-build-example-select-qs.png} "Selecting Qt Simulator as target"
3868 \inlineimage{qtcreator-run.png}
3869 to build the application and run it in Qt Simulator.
3871 \o To see the compilation progress, press \key{Alt+4} to open the
3872 \gui Compile Output pane.
3874 The \gui Build progress bar on the toolbar turns green when the project
3875 is successfully built. The application opens in Qt Simulator.
3877 \image {qt-simulator.png} "Qt Simulator"
3879 \o Change the settings in the
3880 \gui View pane, for example, to toggle the orientation by clicking
3881 \gui {Rotate Device}, or choose from the various Symbian and Maemo
3882 configurations by clicking \gui {Device}. You can also simulate various
3883 mobile functions and create your own scripts.
3885 \o To test the application on a Symbian device install Qt libraries
3886 and the TRK debugging application on the device. For more information,
3887 see \l{Setting Up Development Environment for Symbian}.
3889 \o Click the \gui {Target Selector} and select \gui {Symbian Device}.
3891 \o Click \gui Run to build the application for the Symbian device.
3899 \contentspage index.html
3900 \previouspage creator-mobile-example.html
3901 \page creator-qml-application.html
3902 \nextpage creator-project-managing.html
3904 \title Creating a Qt Quick Application
3906 \note To complete this tutorial, you must have Qt 4.7 or later installed.
3908 This tutorial uses basic elements and illustrates basic concepts of the
3909 \l {http://doc.qt.nokia.com/4.7/qtquick.html}{QML declarative language}.
3911 This tutorial describes how to use the Qt Creator to implement the
3912 \l{http://doc.qt.nokia.com/4.7-snapshot/declarative-animation-states.html}
3913 {states and transitions example application}. The example application displays a user
3914 icon that moves between three rectangles on the page when you click them.
3916 \image qmldesigner-tutorial.png "States and transitions example"
3918 \section1 Creating the Project
3922 \o Select \gui{File > New File or Project > Qt Quick Project > Qt Quick UI >
3925 \o Follow the instructions of the wizard to create a project called Transitions.
3927 \o Press \key {Ctrl+R} to run the application in the QML Viewer.
3931 Qt Creator generates a default QML file that you can modify to create the main view
3934 \image qmldesigner-tutorial-project.png "Transitions project in Edit mode"
3936 \section1 Creating the Main View
3938 The main view of the application displays a user icon in the top left corner of the
3939 screen and two empty rectangles.
3941 To use the user.png image in your application, you must copy it to the project
3942 directory from the \c {\qt\examples\declarative\animation\states} directory in the
3943 Qt installation directory. For example:
3944 \c {C:\Qt\2010.05\qt\examples\declarative\animation\states}. The image appears
3945 in the \gui Resources pane. You can also use any other image or a QML element, instead.
3949 \o In the \gui Projects view, double-click the main .qml file (Transitions.qml)
3950 to open it in the code editor.
3952 \o Click \gui Design to open the file in \QMLD.
3954 \image qmldesigner-tutorial-desing-mode.png "Transitions project in Design Mode"
3956 \o In the \gui Navigator pane, select \gui Text and press \key Delete to delete it.
3958 \o Select \gui Rectangle to edit its properties.
3960 \image qmldesigner-tutorial-page.png "Page properties"
3964 \o In the \gui Id field, enter \e page, to be able to reference the rectangle
3967 \o In the \gui Size field, set \gui W to 640 and \gui H to 480.
3969 \o In the \gui Colors tab, \gui Rectangle field, set the color to #343434.
3973 \o Drag and drop user.png from \gui Resources to the canvas.
3975 \o In the \gui Id field, enter \e userIcon.
3977 \image qmldesigner-tutorial-user-icon.png "User icon properties"
3979 \o Drag and drop a \gui Rectangle element to the canvas, and edit its properties.
3981 \image qmldesigner-tutorial-topleftrect.png "Rectangle properties"
3985 \o In the \gui Id field, enter \e topLeftRect.
3987 \o In the \gui Size field, set \gui W and \gui H to 64, for the rectangle size
3988 to match the image size.
3990 \o In the \gui Colors tab, \gui Rectangle field, click the
3991 \inlineimage qmldesigner-transparent-button.png
3992 button to make the rectangle transparent.
3994 \o In the \gui Border field, set the border color to #808080.
3996 \o In the \gui Rectangle tab, \gui Border field, set the border width to
3999 \o In the \gui Radius field, select 6 to create rounded corners for the
4002 \o Click \gui {Layout}, and then click the top and left anchor buttons
4003 to anchor the rectangle to the top left corner of the page.
4005 \image qmldesigner-tutorial-topleftrect-layout.png "Layout tab"
4007 \o In the \gui Margin field for the top anchor, select 20.
4011 \o Drag and drop a \gui {Mouse Area} element on top of the rectangle,
4012 and edit its properties:
4016 \o Click \gui {Layout}, and then click the
4017 \inlineimage qmldesigner-anchor-fill-screen.png
4018 button to anchor the mouse area to the rectangle.
4020 \o In the code editor, add a pointer to a clicked expression to the mouse
4021 area element, as illustrated by the following code snippet:
4027 anchors.fill: parent
4028 onClicked: page.state = ''
4033 The expression sets the state to the base state and returns the image to
4034 its initial position.
4038 \o To make sure that the user icon appears within the rectangle even if the screen
4039 size changes, you can anchor the icon to the x and y coordinates of the rectangle:
4043 \o In the \gui Navigator, select userIcon.
4045 \o In the \gui Geometry tab, \gui {Position X} field, open the menu and select
4046 \gui {Set Expression}.
4048 \o Enter the following expression: \c {topLeftRect.x}
4050 \o In the \gui Y field, set the following expression: \c {topLeftRect.y}
4054 \o Copy topLeftRect (by pressing \key {Ctrl+C}) and paste it to the canvas twice
4055 (by pressing \key {Ctrl+V}). Qt Creator renames the new instances of the element
4056 topLeftRect1 and topLeftRect2.
4058 \o Select topLeftRect1 and edit its properties:
4062 \o In the \gui Id field, enter \e middleRightRect.
4064 \o In \gui {Layout}, select the right and vertical center anchor buttons to
4065 anchor the rectangle to the middle right margin of the screen.
4067 \o In the code editor, modify the pointer to the clicked expression in the
4068 mouse area element. The following expression sets the state to \e State1:
4070 \c {onClicked: page.state = 'State1'}
4072 You will create State1 later.
4076 \o Select topLeftRect2 and edit its properties:
4080 \o In the \gui Id field, enter \e bottomLeftRect.
4082 \o In \gui {Layout}, select the bottom and left anchor buttons to
4083 anchor the rectangle to the bottom left margin of the screen.
4085 \o In the code editor, modify the pointer to a clicked expression in the
4086 mouse area element. The following expression sets the state to \e State2:
4088 \c {onClicked: page.state = 'State2'}
4090 You will create State2 later.
4094 \o Press \key {Ctrl+R} to run the application in the QML Viewer.
4098 \image qmldesigner-tutorial.png "States and transitions example"
4100 You should see the user icon in the top left rectangle, and two additional
4101 rectangles in the center right and bottom left of the screen.
4103 You can now create additional states to add views to the application.
4105 \section1 Adding Views
4107 In the .qml file, you already created pointers to two additional states:
4108 State1 and State2. To create the states:
4112 \o Click the empty slot in the \gui States pane to create State1.
4114 \o Drag and drop the user icon on top of middleRightRect.
4116 \image qmldesigner-tutorial-state1.png "State 1"
4118 \o Click the empty slot in the \gui States pane to create State2.
4120 \o Drag and drop the user icon on top of bottomLeftRect.
4122 \o Press \key {Ctrl+R} to run the application in the QML Viewer.
4126 Click the rectangles to move the user icon from one rectangle to another.
4128 \section1 Adding Animation to the View
4130 Add transitions to define how the properties change when the user icon moves
4131 between states. The transitions apply animations to the user icon. For example,
4132 the user icon bounces back when it moves to the middleRightRect and eases into
4133 bottomLeftRect. Add the transitions in the code editor.
4137 \o In the code editor, add the following code to specify that when moving to
4138 State1, the x and y coordinates of the user icon change linearly over a duration
4145 from: "*"; to: "State1"
4154 \o You can use the Qt Quick toolbar for animation to change the easing curve
4155 type from linear to OutBounce:
4159 \o Select NumberAnimation and click
4160 \inlineimage qml-toolbar-indicator.png
4161 to open the toolbar:
4163 \image qmldesigner-tutorial-quick-toolbar.png "Qt Quick toolbar for animation"
4165 \o In the \gui Easing field, select \gui Bounce.
4167 \o In the \gui Subtype field, select \gui Out.
4171 \o Add the following code to specify that when moving to State2, the x and y
4172 coordinates of the user icon change over a duration of 2 seconds,
4173 and an InOutQuad easing function is used:
4178 from: "*"; to: "State2"
4181 easing.type: Easing.InOutQuad;
4188 \o Add the following code to specify that for any other state changes, the x
4189 and y coordinates of the user icon change linearly over a duration of 200
4203 \o Press \key {Ctrl+R} to run the application in the QML Viewer.
4207 Click the rectangles to view the animated transitions.
4209 \section1 Deploying the Application to Mobile Devices
4211 To deploy the application to mobile devices, use the \gui {Qt Quick Application} wizard
4212 to convert it into a Qt Quick application. For more information, see
4213 \l{Importing QML Applications}.
4219 \contentspage index.html
4220 \previouspage creator-build-example-application.html
4221 \page creator-writing-program.html
4222 \nextpage creator-mobile-example.html
4224 \title Creating a Qt C++ Application
4226 This tutorial describes how to use Qt Creator
4227 to create a small Qt application, Text Finder. It is a simplified version of the
4228 QtUiTools \l{http://doc.qt.nokia.com/4.7/uitools-textfinder.html}{Text Finder}
4231 \image qtcreator-textfinder-screenshot.png
4233 \section1 Creating the Text Finder Project
4235 \note Create the project with two instances of Qt Creator open and the \gui{Help} mode
4236 active in one of them so that you can follow
4237 these instructions while you work.
4241 \o Select \gui{File > New File or Project > Qt C++ Project > Qt Gui
4242 Application > Choose}.
4244 \image qtcreator-new-project.png "New File or Project dialog"
4246 The \gui{Introduction and Project Location} dialog opens.
4248 \image qtcreator-intro-and-location.png "Introduction and Project Location dialog"
4250 \o In the \gui{Name} field, type \bold {TextFinder}.
4253 \o In the \gui {Create in} field, enter the path for the project files. For example,
4254 \c {C:\Qt\examples}, and then click \gui{Next}.
4256 The \gui {Qt Versions} dialog opens.
4258 \image qtcreator-new-project-qt-versions.png "Qt Versions dialog"
4260 \o Select the Qt versions to use as build targets for your project, and click
4263 \note If you have only one Qt version installed, this dialog is skipped.
4265 The \gui{Class Information} dialog opens.
4267 \image qtcreator-class-info.png "Class Information dialog"
4269 \o In the \gui{Class name} field, type \bold {TextFinder} as the class name.
4271 \o In the \gui{Base class} list, select \bold {QWidget} as the base class type.
4273 \note The \gui{Header file}, \gui{Source file} and
4274 \gui{Form file} fields are automatically updated to match the name of the
4277 \o Click \gui{Next}.
4279 The \gui{Project Management} dialog opens.
4281 \image qtcreator-new-project-summary.png "Project Management dialog"
4283 \o Review the project settings, and click \gui{Finish} to create the project.
4290 The TextFinder project now contains the following files:
4300 \image qtcreator-textfinder-contents.png "TextFinder project contents"
4302 The .h and .cpp files come with the necessary boiler plate code.
4303 The .pro file is complete.
4305 \section1 Filling in the Missing Pieces
4307 Begin by designing the user interface and then move on to filling
4308 in the missing code. Finally, add the find functionality.
4310 \section2 Designing the User Interface
4312 \image qtcreator-textfinder-ui.png "Text Finder UI"
4316 \o In the \gui{Editor} mode, double-click the textfinder.ui file in the \gui{Projects}
4317 view to launch the integrated \QD.
4319 \o Drag and drop the following widgets to the form:
4322 \o \gui{Label} (QLabel)
4323 \o \gui{Line Edit} (QLineEdit)
4324 \o \gui{Push Button} (QPushButton)
4328 \image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI"
4330 \note To easily locate the widgets, use the search box at the top of the
4331 \gui Sidebar. For example, to find the \gui Label widget, start typing
4332 the word \bold label.
4334 \image qtcreator-texfinder-filter.png "Filter field"
4336 \o Double-click the \gui{Label} widget and enter the text \bold{Keyword}.
4338 \o Double-click the \gui{Push Button} widget and enter the text \bold{Find}.
4340 \o In the \gui Properties pane, change the \gui objectName to \bold findButton.
4342 \image qtcreator-textfinder-objectname.png "Changing object names"
4344 \o Press \key {Ctrl+A} to select the widgets and click \gui{Lay out Horizontally}
4345 (or press \gui{Ctrl+H}) to apply a horizontal layout
4348 \image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout"
4350 \o Drag and drop a \gui{Text Edit} widget (QTextEdit)
4353 \o Select the screen area and click \gui{Lay out Vertically} (or press \gui{Ctrl+L})
4354 to apply a vertical layout (QVBoxLayout).
4356 \image qtcreator-textfinder-ui.png "Text Finder UI"
4358 Applying the horizontal and vertical layouts ensures that the application UI scales to different
4361 \o To call a find function when users press the \gui Find button, you use the Qt signals
4362 and slots mechanism. A signal is emitted when a particular event occurs and a slot is
4363 a function that is called in response to a particular signal. Qt widgets have predefined
4364 signals and slots that you can use directly from \QD. To add a slot for the find function:
4368 \o Right-click the \gui Find button to open a context-menu.
4369 \o Select \gui {Go to Slot > clicked()}, and then select \gui OK.
4371 A private slot, \c{on_findButton_clicked()}, is added to the header file,
4372 textfinder.h and a private function, \c{TextFinder::on_findButton_clicked()},
4373 is added to the source file, textfinder.cpp.
4377 \o Press \gui{Ctrl+S} to save your changes.
4381 For more information about designing forms with \QD, see the
4382 \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
4384 \section2 Completing the Header File
4386 The textfinder.h file already has the necessary #includes, a
4387 constructor, a destructor, and the \c{Ui} object. You need to add a private
4388 function, \c{loadTextFile()}, to read and display the
4389 contents of the input text file in the
4394 \o In the \gui{Projects} pane in the \gui {Edit view}, double-click the \c{textfinder.h} file
4395 to open it for editing.
4397 \o Add a private function
4398 to the \c{private} section, after the \c{Ui::TextFinder} pointer, as
4399 illustrated by the following code snippet:
4401 \snippet examples/textfinder/textfinder.h 0
4405 \section2 Completing the Source File
4407 Now that the header file is complete, move on to the source file,
4412 \o In the \gui{Projects} pane in the \gui Edit view, double-click the textfinder.cpp file
4413 to open it for editing.
4415 \o Add code to load a text file using
4416 QFile, read it with QTextStream, and
4417 then display it on \c{textEdit} with
4418 \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}.
4419 This is illustrated by the following code snippet:
4421 \snippet examples/textfinder/textfinder.cpp 0
4423 \o To use QFile and QTextStream, add the
4424 following #includes to textfinder.cpp:
4426 \snippet examples/textfinder/textfinder.cpp 1
4428 \o For the \c{on_findButton_clicked()} slot, add code to extract the search string and
4429 use the \l{http://doc.qt.nokia.com/4.7/qtextedit.html#find}{find()} function
4430 to look for the search string within the text file. This is illustrated by
4431 the following code snippet:
4433 \snippet examples/textfinder/textfinder.cpp 2
4435 \o Once both of these functions are complete, add a line to call \c{loadTextFile()} in
4436 the constructor, as illustrated by the following code snippet:
4438 \snippet examples/textfinder/textfinder.cpp 3
4442 The \c{on_findButton_clicked()} slot is called automatically in
4443 the uic generated ui_textfinder.h file by this line of code:
4446 QMetaObject::connectSlotsByName(TextFinder);
4449 \section2 Creating a Resource File
4451 You need a resource file (.qrc) within which you embed the input
4452 text file. The input file can be any .txt file with a paragraph of text.
4453 Create a text file called input.txt and store it in the textfinder
4456 To add a resource file:
4458 \o Select \gui{File > New File or Project > Qt > Qt Resource File > Choose}.
4459 \image qtcreator-add-resource-wizard.png "New File or Project dialog"
4461 The \gui {Choose the Location} dialog opens.
4463 \image qtcreator-add-resource-wizard2.png "Choose the Location dialog"
4465 \o In the \gui{Name} field, enter \bold{textfinder}.
4466 \o In the \gui{Path} field, enter \c{C:\Qt\examples\TextFinder},
4467 and click \gui{Next}.
4469 The \gui{Project Management} dialog opens.
4471 \image qtcreator-add-resource-wizard3.png "Project Management dialog"
4474 \o In the \gui{Add to project} field, select \bold{TextFinder.pro}
4475 and click \gui{Finish} to open the file in the code editor.
4477 \o Select \gui{Add > Add Prefix}.
4478 \o In the \gui{Prefix} field, replace the default prefix with a slash (/).
4479 \o Select \gui{Add > Add Files}, to locate and add input.txt.
4481 \image qtcreator-add-resource.png "Editing resource files"
4485 \section1 Compiling and Running Your Program
4487 Now that you have all the necessary files, click the \inlineimage qtcreator-run.png
4488 button to compile and run your program.
4494 \contentspage index.html
4495 \previouspage creator-maemo-emulator.html
4496 \page creator-version-control.html
4497 \nextpage creator-task-lists.html
4499 \title Using Version Control Systems
4501 Version control systems supported by Qt Creator are:
4504 \i \bold{Version Control System}
4509 \i \l{http://git-scm.com/}
4512 \i \bold{Subversion}
4513 \i \l{http://subversion.tigris.org/}
4517 \i \l{http://www.perforce.com}
4518 \i Server version 2006.1 and later
4521 \i \l{http://www.cvshome.org}
4525 \i \l{http://mercurial.selenic.com/}
4526 \i Qt Creator 2.0 and later
4530 \section1 Setting Up Version Control Systems
4532 Qt Creator uses the version control system's command line clients to access
4533 your repositories. To allow access, make sure that the command line clients
4534 can be located using the \c{PATH} environment variable or specify the path to
4535 the command line client executables in \gui{Tools} > \gui{Options...} >
4536 \gui {Version Control}.
4538 After you set up the version control system, use the command line to check
4539 that everything works (for example, use the status command). If no issues arise,
4540 you should be ready to use the system also from Qt Creator.
4542 \section2 Using msysGit on Windows
4544 If you configure Git for use with \c {git bash}, only, and use SSH
4545 authorization, Git looks for the SSH keys in the directory where the
4546 \c HOME environment points to. The variable is always set by \c {git bash}.
4548 However, the variable is typically not set in a Windows command prompt.
4549 When you run Git from a Windows command prompt, it looks for the SSH keys in its
4550 installation directory, and therefore, the authorization fails.
4552 You can set the \c HOME environment variable from Qt Creator. Select \gui {Tools >
4553 Options... > Version Control > Git}. Select the \gui {Environment Variables}
4554 and the \gui {Set "HOME" environment variable} check boxes. \c HOME is set to
4555 \c %HOMEDRIVE%%HOMEPATH% when the Git executable is run and authorization works
4556 as it would with \c {git bash}.
4558 \section1 Setting Up Common Options
4560 Select \gui{Tools} > \gui{Options...} > \gui{Version Control} > \gui{Common}
4561 to specify settings for submit messages:
4563 \o \gui{Submit message check script} is a script or program that
4564 can be used to perform checks on the submit message before
4565 submitting. The submit message is passed in as the script's first
4566 parameter. If there is an error, the script should output a
4567 message on standard error and return a non-zero exit code.
4569 \o \gui{User/alias configuration file} takes a file in mailmap format
4570 that lists user names and aliases. For example:
4573 Jon Doe <Jon.Doe@company.com>
4574 Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
4577 \note The second line above specifies the alias \e{hm} and the
4578 corresponding email address for \e{Hans Mustermann}. If the
4579 user/alias configuration file is present, the submit editor
4580 displays a context menu with \gui{Insert name...} that pops up a
4581 dialog letting the user select a name.
4583 \o \gui{User fields configuration file} is a simple text file
4584 consisting of lines specifying submit message fields that take
4585 user names, for example:
4593 The fields above appear below the submit message. They provide completion
4594 for the aliases/public user names specified in the
4595 \e{User/alias configuration file} as well as a button that opens the
4596 aforementioned user name dialog.
4598 \section1 Creating VCS Repositories for New Projects
4600 Qt Creator allows for creating VCS repositories for version
4601 control systems that support local repository creation, such as
4603 When creating a new project by selecting \gui File >
4604 \gui{New File or Project...}, you can choose a version
4605 control system in the final wizard page.
4607 \section1 Using Version Control Systems
4609 The \gui{Tools} menu contains a submenu for each supported version
4612 The \gui{Version Control} output pane displays the commands
4613 that are executed, a timestamp, and the relevant output.
4614 Select \gui {Window > Output Panes > Version Control} to open
4618 \image qtcreator-vcs-pane.png
4621 \section2 Adding Files
4623 When you create a new file or a new project, the wizard displays a page
4624 asking whether the files should be added to a version control system.
4625 This happens when the parent directory or the project is already
4626 under version control and the system supports the concept of adding files,
4627 for example, Perforce and Subversion. Alternatively, you can
4628 add files later by using the version control tool menus.
4630 With Git, there is no concept of adding files. Instead, all modified
4631 files must be staged for a commit.
4634 \section2 Viewing Diff Output
4636 All version control systems provide menu options to \e{diff} the current
4637 file or project: to compare it with the latest version stored in the
4638 repository and to display the differences. In Qt Creator, a diff is
4639 displayed in a read-only editor. If the file is accessible, you can
4640 double-click on a selected diff chunk and Qt Creator opens an editor
4641 displaying the file, scrolled to the line in question.
4643 \image qtcreator-vcs-diff.png
4646 \section2 Viewing Versioning History and Change Details
4648 Display the versioning history of a file by selecting \gui{Log}
4649 (for Git and Mercurial) or \gui{Filelog} (for CVS, Perforce, and
4650 Subversion). Typically, the log output contains the date, the commit
4651 message, and a change or revision identifier. Click on the identifier to
4652 display a description of the change including the diff.
4653 Right-clicking on an identifier brings up a context menu that lets you
4654 show annotation views of previous versions (see \l{Annotating Files}).
4656 \image qtcreator-vcs-log.png
4659 \section2 Annotating Files
4661 Annotation views are obtained by selecting \gui{Annotate} or \gui{Blame}.
4662 Selecting \gui{Annotate} or \gui{Blame} displays the lines of the file
4663 prepended by the change identifier they originate from. Clicking on the
4664 change identifier shows a detailed description of the change.
4666 To show the annotation of a previous version, right-click on the
4667 version identifier at the beginning of a line and choose one of the
4668 revisions shown at the bottom of the context menu. This allows you to
4669 navigate through the history of the file and obtain previous versions of
4670 it. It also works for Git and Mercurial using SHA's.
4672 The same context menu is available when right-clicking on a version
4673 identifier in the file log view of a single file.
4676 \section2 Committing Changes
4678 Once you have finished making changes, submit them to the version control
4679 system by choosing \gui{Commit} or \gui{Submit}. Qt Creator displays a
4680 commit page containing a text editor where you can enter your commit
4681 message and a checkable list of modified files to be included.
4683 \image qtcreator-vcs-commit.png
4685 When you have finished filling out the commit page information, click on
4686 \gui{Commit} to start committing.
4688 The \gui{Diff Selected Files} button brings up a diff view of the
4689 files selected in the file list. Since the commit page is just another
4690 editor, you can go back to it by closing the diff view. You can also check
4691 a diff view from the editor combo box showing the \gui{Opened files}.
4693 \section2 Reverting Changes
4695 All supported version control system support reverting your project to
4696 known states. This functionality is generally called \e reverting.
4698 The changes discarded depend on the version control system.
4700 A version control system can replace the \gui Revert menu option with other
4703 \section3 Reverting Changes Using Git
4705 The Git version control system has an index that is used to stage
4706 changes. The index is commited on the next commit. Git allows you to revert
4707 back to the state of the last commit as well as to the state staged in the
4712 \o \gui{Undo Unstaged Changes} reverts all changes and resets the working
4713 directory to the state of the index.
4715 \o \gui{Undo Uncommitted Changes} reverts all changes, discarding the index.
4716 This returns your working copy to the state it was in right after the last commit.
4720 \section2 Using Additional Git Functions
4722 Git is a fast decentralized version control system. Git is available
4723 for Windows, Linux and Mac.
4725 The \gui Git submenu contains the following additional items:
4730 \i \gui {Patch > Apply from Editor/Apply from File...}
4731 \i Patches are rewriting instructions that can be applied to a set of files.
4732 You can either apply a patch file that is open in Qt Creator or select
4733 the patch file to apply from the file system.
4736 \i Pull changes from the remote repository. If there are locally
4737 modified files, you are prompted to stash those changes. Select \gui{Tools >
4738 Options... > Version Control > Git} and select the \gui {Pull with rebase}
4739 check box to perform a rebase operation while pulling.
4742 \i \gui{Clean.../Clean Project...}
4743 \i All files that are not under version control (with the exception
4744 of patches and project files) are displayed in the \gui {Clean Repository}
4745 dialog. Select the files to delete and click \gui Delete. This allows you to
4746 clean a build completely.
4749 \i \gui{Branches...}
4750 \i Display the \gui Branch dialog that shows the local branches at the
4751 top and remote branches at the bottom. To switch to a local branch,
4752 double-click it. Double-clicking on a remote branch first creates a local
4753 branch with the same name that tracks the remote branch, and then switches
4756 \image qtcreator-vcs-gitbranch.png
4759 \i \gui {Stage File for Commit}
4760 \i Mark new or modified files for committing to the repository.
4761 To undo this function, select \gui {Unstage File from Commit}.
4763 \i \gui{Show Commit...}
4764 \i Select a commit to view. Enter the SHA of the commit
4765 in the \gui Change field.
4768 \section3 Using Stashes
4770 With Git, you can put your current set of changes onto a virtual shelf called a \e stash.
4771 Stashes are useful, for example, to put aside a set of changes to work on higher
4772 priority tasks or to pull in new chages from another repository.
4774 Qt Creator exposes this functionality in the \gui{Tools > Git > Stash} menu.
4779 \i Display a dialog that shows all known stashes with options to restore,
4780 display or delete them.
4783 \i Stash all local changes. The working copy is then reset to
4784 the state it had right after the last commit.
4786 \i \gui{Stash Snapshot...}
4787 \i Save a snapshot of your current work under a name for later reference. The
4788 working copy is unchanged.
4790 For example, if you want to try something and find out later that it does not work,
4791 you can discard it and return to the state of the snapshot.
4794 \i Remove a single stashed state from the stash list and apply it on
4795 top of the current working tree state.
4798 \section2 Using Additional Mercurial Functionality
4800 The \gui Mercurial submenu contains the following additional items:
4805 \i Apply changes from a patch file.
4808 \i Monitor the status of a remote repository by listing
4809 the changes that will be pulled.
4812 \i Monitor the status of a remote repository by listing
4813 the changes that will be pushed.
4816 \i Pull changes from the remote repository.
4819 \i Look at an earlier version of the code.
4822 \section2 Using Additional Perforce Functions
4824 When you start Qt Creator, it looks for the executable specified
4825 in the \gui{P4 command} field in \gui{Tools > Options... > Version
4826 Control > Perforce}. If you do not use Perforce and want to turn
4827 off the check, clear this field.
4829 The \gui Perforce submenu contains the following additional items:
4833 \i \gui{Describe...}
4834 \i View information about changelists and the files in them.
4837 \i Open a file for editing.
4840 \i List files that are open for editing.
4842 \i \gui{Pending Changes...}
4843 \i Group files for commit.
4845 \i \gui{Update All/Update Current Project}
4846 \i Fetch the current version of the current project or all
4847 projects from the repository.
4851 \section2 Using Additional Subversion Functions
4853 The \gui Subversion submenu contains the following additional items:
4857 \i \gui{Describe...}
4858 \i Display commit log messages for a revision.
4860 \i \gui{Update Project/Update Repository}
4861 \i Update your working copy.
4870 \contentspage index.html
4871 \previouspage qt-quick-toolbars.html
4872 \page creator-editor-locator.html
4873 \nextpage creator-editor-codepasting.html
4875 \title Searching With the Locator
4877 The locator provides one of the easiest ways in Qt Creator to browse
4878 through projects, files, classes, methods, documentation and file systems.
4879 You can find the locator in the bottom left of the Qt Creator window.
4881 To activate the locator, press \key Ctrl+K (\key Cmd+K on Mac OS
4882 X) or select \gui Tools > \gui Locate....
4884 \image qtcreator-locator.png
4886 To edit the currently open project's main.cpp file using the locator:
4888 \o Activate the locator by pressing \key Ctrl+K.
4889 \o Enter \tt{main.cpp}.
4891 \image qtcreator-locator-open.png
4892 \o Press \key Return.
4894 The main.cpp file opens in the editor.
4897 It is also possible to enter only a part of a search string.
4898 As you type, the locator shows the occurrences of that string regardless
4899 of where in the name of an component it appears.
4901 To narrow down the search results, you can use the following wildcard
4904 \o To match any number of any or no characters, enter \bold{*}.
4905 \o To match a single instance of any character, enter \bold{?}.
4908 \section1 Using the Locator Filters
4910 The locator allows you to browse not only files, but any items
4911 defined by \bold{locator filters}. By default, the locator contains
4912 filters which locate:
4914 \o Any open document
4915 \o Files anywhere on your file system
4916 \o Files belonging to your project, such as source, header resource,
4918 \o Class and method definitions in your project or anywhere referenced
4920 \o Help topics, including Qt documentation
4921 \o Specific line in the document displayed in your editor
4924 To use a specific locator filter, type the assigned prefix followed by
4925 \key Space. The prefix is usually a single character.
4927 For example, to locate symbols matching
4930 \o Activate the locator.
4931 \o Enter \tt{\bold{: QDataStream}} (: (colon) followed by a
4932 \key Space and the symbol name (QDataStream)).
4934 The locator lists the results.
4936 \image qtcreator-navigate-popup.png
4939 By default the following filters are enabled and you do not need to use
4940 their prefixes explicitly:
4942 \o Going to a line in the current file (l).
4943 \o Going to an open file (o).
4944 \o Going to a file in any open project (a).
4947 \section2 Using the Default Locator Filters
4949 The following locator filters are available by default:
4957 \o Go to a line in the current file.
4958 \o \tt{\bold{l \e{Line number}}}
4959 \o \image qtcreator-locator-line.png
4961 \o Go to a symbol definition.
4962 \o \tt{\bold{: \e{Symbol name}}}
4963 \o \image qtcreator-locator-symbols.png
4965 \o Go to a help topic.
4966 \o \tt{\bold{? \e{Help topic}}}
4967 \o \image qtcreator-locator-help.png
4969 \o Go to an open file.
4970 \o \tt{\bold{o \e{File name}}}
4971 \o \image qtcreator-locator-opendocs.png
4973 \o Go to a file in the file system (browse the file system).
4974 \o \tt{\bold{f \e{File name}}}
4975 \o \image qtcreator-locator-filesystem.png
4977 \o Go to a file in any project currently open.
4978 \o \tt{\bold{a \e{File name}}}
4979 \o \image qtcreator-locator-files.png
4981 \o Go to a file in the current project.
4982 \o \tt{\bold{p \e{File name}}}
4983 \o \image qtcreator-locator-current-project.png
4985 \o Go to a class definition.
4986 \o \tt{\bold{c \e{Class name}}}
4987 \o \image qtcreator-locator-classes.png
4989 \o Go to a method definition.
4990 \o \tt{\bold{m \e{Method name}}}
4991 \o \image qtcreator-locator-methods.png
4994 \section2 Creating Locator Filters
4996 To quickly access files not directly mentioned in your project, you can
4997 create your own locator filters. That way you can locate files in a
4998 directory structure you have defined.
5000 To create a locator filter:
5002 \o In the locator, click \inlineimage qtcreator-locator-magnify.png
5003 and select \gui Configure.... to open the \gui Locator options.
5005 \image qtcreator-locator-customize.png
5008 \o In the \gui{Filter Configuration} dialog:
5010 \o Name your filter.
5011 \o Select at least one directory. The locator searches directories
5013 \o Define the file pattern as a comma separated list. For example,
5014 to search all .h and .cpp files, enter \bold{*.h,*.cpp}
5015 \o Specify the prefix string.
5017 To show only results matching this filter, select
5018 \gui{Limit to prefix}.
5020 \image qtcreator-navigate-customfilter.png
5025 \section3 Configuring the Locator Cache
5027 The locator searches the files matching your file pattern in the
5028 directories you have selected and caches that information. The cache for
5029 all default filters is updated as you write your code. By default,
5030 Qt Creator updates the filters created by you once an hour.
5032 To update the cached information manually, click
5033 \inlineimage qtcreator-locator-magnify.png
5034 and select \gui Refresh.
5036 To set a new cache update time:
5038 \o Select \gui Tools > \gui Options... > \gui Locator.
5039 \o In \gui{Refresh interval}, define new time in minutes.
5046 \contentspage index.html
5047 \previouspage creator-developing-symbian.html
5048 \page creator-project-managing-sessions.html
5049 \nextpage creator-project-wizards.html
5051 \title Managing Sessions
5053 When you exit Qt Creator, a snapshot of your current workspace is stored
5054 as a \e session. A session is an arbitrary collection of:
5057 \o Open projects with their dependencies (including SUBDIRS projects)
5059 \o Breakpoints and watches
5063 A session is personal, that is, not meant to be shared. It is not
5064 supposed to reflect the project structure. It contains personal data, such as
5065 bookmarks and breakpoints that are usually not of interest to other developers
5066 working on the same projects.
5068 For example, if you work on a project and need to switch to another project for a
5069 while, you can save your workspace as a session. This makes it easier
5070 to return to working on the first project later.
5072 To create a new session or remove existing sessions, select \gui File >
5073 \gui Sessions > \gui{Session Manager}.
5075 \image qtcreator-session-manager.png
5077 To switch between sessions, choose
5078 \gui File > \gui Session. If you do not create or select a session,
5079 Qt Creator always uses the default session, which was created the
5080 last time you exited Qt Creator.
5082 When you launch Qt Creator, a list of existing sessions is displayed on the
5083 \gui{Welcome screen}.
5085 \image qtcreator-welcome-session.png
5091 \contentspage index.html
5092 \previouspage creator-build-dependencies.html
5093 \page creator-debugging.html
5094 \nextpage creator-debugging-example.html
5098 Qt Creator does not include a debugger. It provides a debugger plugin that acts
5099 as an interface between the Qt Creator core and external native debuggers
5100 such as the GNU Symbolic Debugger (gdb), the Microsoft Console Debugger (CDB),
5101 and a QML/JavaScript debugger.
5103 The following sections describe debugging with Qt Creator:
5107 \o \l{Debugging the Example Application} uses an example application to illustrate
5108 how to debug Qt C++ applications in the \gui Debug mode.
5110 \o \l{Interacting with the Debugger} describes the views and functions available
5111 in the \gui Debug mode.
5113 \o \l{Setting Up Debugger} summarizes the support for debugging C++ code and
5114 requirements for installation. Typically, the interaction between Qt Creator
5115 and the native debugger is set up automatically and you do not need to do anything.
5117 \o \l{Debugger Modes of Operation} describes the operating modes in which the
5118 debugger plugin runs, depending on where and how the process is started and run.
5120 \o \l{Using Debugging Helpers} describes how to get more detailed data
5123 \o \l{Debugging Qt Quick Projects} describes how to debug Qt Quick projects.
5130 \contentspage index.html
5131 \previouspage creator-debugger-engines.html
5132 \page creator-debugger-operating-modes.html
5133 \nextpage creator-debugging-helpers.html
5135 \title Debugger Modes of Operation
5137 The debugger plugin runs in different operating modes depending on where and
5138 how the process is started and run. Some of the modes are only available for
5139 a particular operating system or platform.
5141 You can launch the debugger in the following modes:
5145 \o \bold Plain to debug locally started applications, such as a
5146 Qt based GUI application.
5148 \o \bold Terminal to debug locally started processes that need a
5149 console, typically without a GUI.
5151 \o \bold Attach to debug local processes started outside Qt Creator.
5153 \o \bold Remote to debug a process running on a different machine.
5155 \o \bold Core to debug crashed processes on Unix.
5157 \o \bold Post-mortem to debug crashed processes on Windows.
5159 \o \bold TRK to debug processes running on a Symbian device.
5163 \note Debugging QML and JavaScript is supported only in plain mode.
5165 When you click the \gui {Start Debugging} button, the debugger is launched
5166 in the appropriate operating mode (plain, terminal, or TRK), based on the
5167 build and run settings for the active project. Select \gui Debug menu options
5168 to launch the debugger in the other modes.
5170 \section2 Plain Mode
5172 To launch the debugger in the plain mode, click the \gui {Start Debugging}
5173 button for the active project, or choose
5174 \gui {Debug > Start Debugging > Start and Debug External Application...}
5175 and specify an executable.
5177 \section2 Terminal Mode
5179 To launch the debugger in the terminal mode, select \gui {Projects > Run Settings}
5180 and select the \gui {Run in terminal} check box. Then click the
5181 \gui {Start Debugging} button for the active project.
5183 \section2 Attach Mode
5185 To launch the debugger in the attach mode, select
5186 \gui {Debug > Start Debugging > Attach to Running External Application...},
5187 and then select a process by its name or process ID to attach to.
5189 \section2 Remote Mode
5191 The remote mode uses a \e{gdbserver} daemon that runs on the remote machine.
5193 To launch the debugger in the remote mode, select
5194 \gui {Debug > Start Debugging > Start and Attach to Remote Application...}.
5198 The core mode is available only in Unix. It debugs crashed processes using
5199 the \e {core} files (crash dumps) that are generated if the setting
5200 is enabled in the shell.
5202 To enable the dumping of core files, enter the following command in the
5203 shell from which the application will be launched:
5209 To launch the debugger in the core mode, select
5210 \gui{Debug > Start Debugging > Attach to Core...}.
5212 \section2 Post-Mortem Mode
5214 The post-mortem mode is available only on Windows, if you have installed
5215 the debugging tools for Windows.
5217 The Qt Creator installation program asks you whether you want to
5218 register Qt Creator as a post-mortem debugger. To change the setting, select
5219 \gui{Tools > Options... > Debugger > Common > Use Creator for post-mortem debugging}.
5221 You can launch the debugger in the post-mortem mode if an application crashes
5222 on Windows. Click the \gui {Debug in Qt Creator} button in the error message
5223 that is displayed by the Windows operating system.
5227 The TRK mode is a special mode available only for Symbian. It
5228 debugs processes running on a Symbian
5229 device using the App TRK application that runs on the device.
5231 To launch the debugger in the TRK mode, open the project, select Symbian as the
5232 target, and click the \gui {Start Debugging} button.
5234 For more information on setting up Symbian projects, see
5235 \l{Setting Up Development Environment for Symbian}.
5241 \contentspage index.html
5242 \previouspage creator-debug-mode.html
5243 \page creator-debugger-engines.html
5244 \nextpage creator-debugger-operating-modes.html
5246 \title Setting Up Debugger
5248 \note The information in this section applies only to debugging the C++
5251 Typically, the interaction between Qt Creator and the native debugger is set
5252 up automatically and you do not need to do anything. However, you might have an
5253 unsupported gdb version installed, your Linux environment might not have gdb
5254 installed at all, or you might want to use the debugging tools for Windows.
5256 \note To use the debugging tools for Windows, you must install them and add the
5257 Symbol Server provided by Microsoft to the symbol search path of the debugger.
5258 For more information, see \l{Setting the Symbol Server in Windows}.
5260 This section explains the
5261 options you have for debugging C++ code and provides installation notes for the
5262 supported native debuggers.
5264 \section1 Supported Native Debugger Versions
5266 The debugger plugin supports different builds of the gdb debugger, both
5267 with and without the ability to use Python scripting. The Python enabled
5268 versions are preferred, but they are not available on Mac and on older
5270 On Windows, Symbian, and Maemo, only the Python version is supported.
5272 The non-Python versions use the compiled version of the debugging helpers,
5273 that you must enable separately. For more information, see
5274 \l{Debugging Helpers Based on C++}.
5276 The Python version uses a script version of the debugging helpers
5277 that does not need any special setup.
5279 The CDB native debugger has similar funtionality to the non-Python gdb debugger
5280 engine. Specifically, it also uses compiled C++ code for the debugging
5283 The following table summarizes the support for debugging C++ code:
5297 \o Plain, Terminal, Attach, Remote, Core
5303 \o Plain, Terminal, Attach, Remote, Core
5309 \o Plain, Terminal, Attach, Core
5315 \o Plain, Terminal, Attach, Remote, Core
5318 \o Microsoft Visual C++ Compiler
5319 \o Debugging Tools for Windows/CDB
5321 \o Plain, Terminal, Attach, Post-Mortem
5336 For more information on the the debugger modes, see \l{Debugger Modes of Operation}.
5340 \section2 Gdb Adapter Modes
5344 The gdb native debugger used internally by the debugger plugin runs in
5345 different adapter modes to cope with the variety
5346 of supported platforms and environments. All gdb adapters inherit from
5351 \o PlainGdbAdapter debugs locally started GUI processes.
5352 It is physically split into parts that are relevant only when Python is
5353 available, parts relevant only when Python is not available, and mixed code.
5355 \o TermGdbAdapter debugs locally started processes that need a
5358 \o AttachGdbAdapter debugs local processes started outside Qt Creator.
5360 \o CoreGdbAdapter debugs core files generated from crashes.
5362 \o RemoteGdbAdapter interacts with the gdbserver running on Linux.
5364 \o TrkGdbAdapter interacts with Symbian devices. The gdb protocol and
5365 the gdb serial protocol are used between gdb and the adapter. The TRK
5366 protocol is used between the adapter and AppTRK running on the device.
5372 \section1 Installing Native Debuggers
5374 There are various reasons why the debugger plugin may fail to automatically
5375 pick up a suitable native debugger. The native debugger might be missing
5376 (which is usually the case for the CDB debugger on Windows which always
5377 needs to be installed manually by the user) or the installed version is not
5379 Check the table below for the supported versions and other important
5380 information about installing native debuggers.
5388 \o On Linux, install version 6.8, 7.0.1 (version 7.0 is not supported),
5389 7.1, or later. On Mac OS X, install Apple gdb version 6.3.50-20050815
5390 (build 1344) or later.
5393 \o Debugging tools for Windows
5394 \o Using this engine requires you to install the
5395 \e{Debugging tools for Windows}
5396 \l{http://www.microsoft.com/whdc/devtools/debugging/installx86.Mspx}{32-bit}
5398 \l{http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx}{64-bit}
5399 package (Version 6.11.1.404 for the 32-bit or the 64-bit version of Qt Creator, respectively),
5400 which is freely available for download from the
5401 \l{http://msdn.microsoft.com/en-us/default.aspx}
5402 {Microsoft Developer Network}. The Qt Creator help browser does
5403 not allow you to download files, and therefore, you must copy the above links to
5406 \note Visual Studio does not include the Debugging tools needed,
5407 and therefore, you must install them separately.
5409 The pre-built \QSDK for Windows makes use
5410 of the library if it is present on the system. When manually building Qt
5411 Creator using the Microsoft Visual C++ Compiler, the build process checks
5412 for the required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}.
5414 It is highly recommended that you add the Symbol Server provided by Microsoft to the symbol
5415 search path of the debugger. The Symbol Server provides you
5416 with debugging informaton for the operating system libraries for debugging
5417 Windows applications. For more information, see
5418 \l{Setting the Symbol Server in Windows}.
5421 \o Debugging tools for Mac OS X
5422 \o The Qt binary distribution contains both debug and release
5423 variants of the libraries. But you have to explicitly tell the
5424 runtime linker that you want to use the debug libraries even if
5425 your application is compiled as debug as release is the default
5428 If you use a qmake based project in Qt Creator, you can set a
5429 flag in your run configuration, in \gui Projects mode. In the run
5430 configuration, select \gui{Use debug version of frameworks}.
5432 For more detailed information about debugging on the Mac, see:
5433 \l http://developer.apple.com/mac/library/technotes/tn2004/tn2124.html
5435 \note The Mac OS X Snow Leopard (10.6) has a bug, that can be worked
5436 around as described in the link provided below:
5437 \l http://bugreports.qt.nokia.com/browse/QTBUG-4962.
5441 \section1 Setting the Symbol Server in Windows
5443 To obtain debugging information for the operating system libraries for
5444 debugging Windows applications, add the Symbol Server provided
5445 by Microsoft to the symbol search path of the debugger:
5447 \o Select \gui Tools > \gui{Options...} > \gui Debugger > \gui Cdb.
5448 \o In the \gui {Symbol paths} field, open the \gui{Insert...} menu
5449 and select \gui{Symbol Server...}.
5450 \o Select a directory where you want to store the cached information
5453 Use a subfolder in a temporary directory, such as
5454 \c {C:\temp\symbolcache}.
5457 \note Populating the cache might take a long time on a slow network
5460 \note The first time you start debugging by using the
5461 Debugging tools for Windows, Qt Creator prompts you to add the Symbol
5467 \contentspage index.html
5468 \previouspage creator-debugging-example.html
5469 \page creator-debug-mode.html
5470 \nextpage creator-debugger-engines.html
5472 \title Interacting with the Debugger
5474 In \gui Debug mode, you can use several views to interact with the
5475 program you are debugging. The availability of views depends on whether
5476 you are debugging C++ or QML. Frequently used views are shown by
5477 default and rarely used ones are hidden. To change the default settings,
5478 select \gui {Window > Views}, and then select views to display or hide.
5480 \image qtcreator-debugger-views.png "Debug mode views"
5482 By default, the views are locked into place in the workspace. Select
5483 \gui {Window > Views > Locked} to unlock the views. Drag and drop the
5484 views into new positions on the screen. Drag view borders to resize the
5485 views. The size and position of views are saved for future sessions.
5487 \section1 Starting the Debugger
5489 To start a program under the debugger's control, select \gui{Debug} >
5490 \gui{Start Debugging} > \gui{Start Debugging}, or press \key{F5}.
5491 Qt Creator checks whether the compiled program is up-to-date, rebuilding
5492 it if necessary. The debugger then takes over and starts the program.
5494 \note Starting a program in the debugger can take a considerable amount of
5495 time, typically in the range of several seconds to minutes if complex
5496 features (like QtWebKit) are used.
5498 The debugger is launched in the appropriate operating mode (plain, terminal,
5499 or TRK), based on the build and run settings for the active project.
5500 Select \gui Debug menu options to launch the debugger in other modes.
5501 For more information, see \l{Debugger Modes of Operation}.
5503 \note Debugging QML and JavaScript is supported only in plain mode.
5505 Once the program starts running, it behaves and performs as usual.
5506 You can interrupt a running C++ program by selecting \gui{Debug} >
5507 \gui {Interrupt}. The program is automatically interrupted as soon as a
5510 \section1 Using the Debugger
5512 Once the program stops, Qt Creator:
5515 \o Retrieves data representing the call stack at the program's current
5517 \o Retrieves the contents of local variables.
5518 \o Examines \gui Watchers.
5519 \o Updates the \gui Registers, \gui Modules, and \gui Disassembler
5520 views if you are debugging the C++ language.
5523 You can use the \gui Debug mode views to examine the data in more detail.
5525 You can use the following keyboard shortcuts:
5529 \o To finish debugging, press \key{Shift+F5}.
5530 \o To execute a line of code as a whole, press \key{F10}.
5531 \o To step into a function or a subfunction, press \key{F11}.
5532 \o To continue running the program, press \key{F5}.
5536 It is also possible to continue executing the program until the current
5537 function completes or jump to an arbitrary position in the current function.
5540 \section1 Setting Breakpoints
5542 A breakpoint represents a position or sets of positions in the code that,
5543 when executed, interrupts the program being debugged and passes the control
5544 to you. You can then examine the state of the interrupted program, or
5545 continue execution either line-by-line or continuously.
5547 Qt Creator shows breakpoints in the \gui{Breakpoints} view which is enabled
5548 by default. The \gui{Breakpoints} view is also accessible when the debugger
5549 and the program being debugged is not running.
5551 \image qtcreator-debug-breakpoints.png "Breakpoints view"
5553 Typically, breakpoints are associated with a source code file and line, or
5554 the start of a function -- both are allowed in Qt Creator.
5556 The interruption of a program by a breakpoint can be restricted with
5559 To set a breakpoint:
5562 \o At a particular line you want the program to stop, click the
5563 left margin or press \key F9 (\key F8 for Mac OS X).
5564 \o At a function that you want the program to interrupt, enter the
5565 function's name in \gui{Set Breakpoint at Function...} located in the
5566 context menu of the \gui{Breakpoints} view.
5569 \note You can remove a breakpoint:
5571 \o By clicking the breakpoint marker in the text editor.
5572 \o By selecting the breakpoint in the breakpoint view and pressing
5574 \o By selecting \gui{Delete Breakpoint} from the context
5575 menu in the \gui Breakpoints view.
5578 You can set and delete breakpoints before the program starts running or
5579 while it is running under the debugger's control. Breakpoints are saved
5580 together with a session.
5582 \section1 Viewing Call Stack Trace
5584 When the program being debugged is interrupted, Qt Creator displays the
5585 nested function calls leading to the current position as a call stack
5586 trace. This stack trace is built up from call stack frames, each
5587 representing a particular function. For each function, Qt Creator tries
5588 to retrieve the file name and line number of the corresponding source
5589 file. This data is shown in the \gui Stack view.
5591 \image qtcreator-debug-stack.png
5593 Since the call stack leading to the current position may originate or go
5594 through code for which no debug information is available, not all stack
5595 frames have corresponding source locations. Stack frames without
5596 corresponding source locations are grayed out in the \gui{Stack} view.
5598 If you click a frame with a known source location, the text editor
5599 jumps to the corresponding location and updates the \gui{Locals and Watchers}
5600 view, making it seem like the program was interrupted before entering the
5603 \section1 Locals and Watchers
5605 Whenever a program stops under the control of the debugger, it retrieves
5606 information about the topmost stack frame and displays it in the
5607 \gui{Locals and Watchers} view. The \gui{Locals and Watchers} view
5608 typically includes information about parameters of the function in that
5609 frame as well as the local variables.
5611 \image qtcreator-watcher.png "Locals and Watchers view"
5613 Compound variables of struct or class type are displayed as
5614 expandable in the view. Expand entries to show
5615 all members. Together with the display of value and type, you can
5616 examine and traverse the low-level layout of object data.
5624 \i Gdb, and therefore Qt Creator's debugger works for optimized
5625 builds on Linux and Mac OS X. Optimization can lead to
5626 re-ordering of instructions or removal of some local variables,
5627 causing the \gui{Locals and Watchers} view to show unexpected
5630 \i The debug information provided by gcc does not include enough
5631 information about the time when a variable is initialized.
5632 Therefore, Qt Creator can not tell whether the contents of a
5633 local variable contains "real data", or "initial noise". If a
5634 QObject appears uninitialized, its value is reported as
5635 \gui {not in scope}. Not all uninitialized objects, however, can be
5640 The \gui{Locals and Watchers} view also provides access to the most
5641 powerful feature of the debugger: comprehensive display of data belonging
5642 to Qt's basic objects.
5644 To enable Qt's basic objects data display feature:
5646 \o Select \gui Tools > \gui {Options...} > \gui Debugger >
5647 \gui{Debugging Helper} and check the \gui{Use Debugging Helper}
5649 \o The \gui{Locals and Watchers} view is reorganized to provide a
5650 high-level view of the objects.
5653 For example, in case of QObject, instead of displaying a pointer to some
5654 private data structure, you see a list of children, signals and slots.
5656 Similarly, instead of displaying many pointers and integers, Qt Creator's
5657 debugger displays the contents of a QHash or QMap in an orderly manner.
5658 Also, the debugger displays access data for QFileInfo and provides
5659 access to the "real" contents of QVariant.
5661 You can use the \gui{Locals and Watchers} view to change the contents of
5662 variables of simple data types, for example, \c int or \c float when the
5663 program is interrupted. To do so, click the \gui Value column, modify
5664 the value with the inplace editor, and press \key Enter (or \key Return).
5666 You can enable tooltips in the main editor displaying this information.
5667 For more information, see \l{Showing Tooltips in Debug Mode}.
5669 \note The set of watched items is saved in your session.
5671 \section1 Debugging the C++ Language
5673 The following sections describe additional debugging functions that apply
5674 only to debugging C++.
5676 \section2 Starting the Debugger from the Command Line
5678 You can use the Qt Creator debugger interface from the command line. To
5679 attach it to a running process, specify the process ID as a parameter for
5680 the \c {-debug} option. To examine a core file, specify the file name.
5681 Qt Creator executes all the necessary steps, such as searching for
5682 the binary that belongs to a core file.
5688 \o \c {C:\qtcreator-2.1\bin>qtcreator -debug 2000}
5690 \o \c {C:\qtcreator-2.1\bin>qtcreator -debug core.2000}
5694 For more information, see \l{Using Command Line Options}.
5696 \section2 Stepping into Frameworks in Mac OS
5698 In Mac OS X, external libraries are usually built into so-called Frameworks,
5699 which may contain both release and debug versions of the library. When you run
5700 applications on the Mac OS desktop, the release version of Frameworks is used
5701 by default. To step into Frameworks, select the \gui {Use debug versions of
5702 Frameworks} option in the project run settings for \gui Desktop and
5703 \gui {Qt Simulator} targets.
5705 \section2 Viewing Threads
5707 If a multi-threaded program is interrupted, the \gui Thread view or the
5708 combobox named \gui Thread in the debugger's status bar can be used to
5709 switch from one thread to another. The \gui Stack view adjusts itself
5712 \section2 Viewing Modules and Source Files
5714 The \gui{Modules} view and \gui{Source Files} views display information
5715 that the debugger plugin has about modules and source files included in
5716 the project. The \gui{Modules} view lists the modules in the project and
5717 symbols within the modules. In addition, it indicates where the module
5720 The \gui{Source Files} view lists all the source files included in the project.
5721 If you cannot step into an instruction, you can check whether the source file is
5722 actually part of the project, or whether it was compiled
5723 elsewhere. The view shows the path to each file in the file system.
5725 By default, the \gui{Modules} view and \gui{Source Files} view are hidden.
5728 \section2 Viewing Disassembled Code and Register State
5730 The \gui{Disassembler} view displays disassembled code for the current
5731 function. The \gui{Registers} view displays the current state of the CPU's
5734 The \gui{Disassembler} view and the \gui{Registers} view are both useful
5735 for low-level commands for checking single instructions, such as \gui{Step Into}
5736 and \gui{Step Over}. By default, both \gui{Disassembler} and
5737 \gui{Registers} view are hidden.
5743 \contentspage index.html
5744 \previouspage creator-debugging.html
5745 \page creator-debugging-example.html
5746 \nextpage creator-debug-mode.html
5748 \title Debugging the Example Application
5750 This section uses the \l{Creating a Qt C++ Application}{TextFinder} example to
5751 illustrate how to debug Qt C++ applications in the \gui Debug mode.
5754 reads a text file into
5755 QString and then displays it with QTextEdit.
5756 To look at the example QString, \c{line}, and see the
5757 stored data, place a breakpoint and view the QString object
5761 \o Click in between the line number and the window border on the line
5762 where we invoke \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}
5763 to set a breakpoint.
5765 \image qtcreator-setting-breakpoint1.png
5767 \o Select \gui{Debug > Start Debugging > Start Debugging} or press \key{F5}.
5770 \o To view the breakpoint, click the \gui{Breakpoints} tab.
5772 \image qtcreator-setting-breakpoint2.png
5774 \o To remove a breakpoint, right-click it and select \gui{Delete Breakpoint}.
5777 \o To view the contents of \c{line}, go to the \gui{Locals and
5780 \image qtcreator-watcher.png
5784 Modify the \c{on_findButton_clicked()} function to move back to
5785 the start of the document and continue searching once the cursor hits the
5786 end of the document. Add the following code snippet:
5789 void TextFinder::on_findButton_clicked()
5791 QString searchString = ui->lineEdit->text();
5793 QTextDocument *document = ui->textEdit->document();
5794 QTextCursor cursor = ui->textEdit->textCursor();
5795 cursor = document->find(searchString, cursor,
5796 QTextDocument::FindWholeWords);
5797 ui->textEdit->setTextCursor(cursor);
5799 bool found = cursor.isNull();
5801 if (!found && previouslyFound) {
5802 int ret = QMessageBox::question(this, tr("End of Document"),
5803 tr("I have reached the end of the document. Would you like "
5804 "me to start searching from the beginning of the document?"),
5805 QMessageBox::Yes | QMessageBox::No, QMessageBox::Yes);
5807 if (ret == QMessageBox::Yes) {
5808 cursor = document->find(searchString,
5809 QTextDocument::FindWholeWords);
5810 ui->textEdit->setTextCursor(cursor);
5814 previouslyFound = found;
5818 If you compile and run the above code, however, the application does not
5819 work correctly due to a logic error. To locate this logic error, step
5820 through the code using the following buttons:
5822 \image qtcreator-debugging-buttons.png
5828 \contentspage index.html
5829 \previouspage creator-debugger-operating-modes.html
5830 \page creator-debugging-helpers.html
5831 \nextpage creator-debugging-qml.html
5833 \title Using Debugging Helpers
5835 Qt Creator is able to show complex data types in a customized,
5836 user-extensible manner. For this purpose, it takes advantage of
5837 two technologies, collectively referred to as \e{Debugging Helpers}.
5839 Using the debugging helpers is not \e essential for debugging
5840 with Qt Creator, but they enhance the user's ability to quickly
5841 examine complex data significantly.
5843 \section1 Debugging Helpers Based on C++
5845 This is the first and original approach to display complex data
5846 types. While it has been superseded on most platforms by the more
5847 robust and more flexible second approch using Python scripting,
5848 it is the only feasible one on Windows/MSVC, Mac OS, and
5849 old Linux distributions. Moreover, this approach will automatically
5850 be chosen as fallback in case the Python based approach fails.
5852 During debugging with the C++ based debugging helpers,
5853 Qt Creator dynamically loads a helper library in form of a DLL or a
5854 shared object into the debugged process.
5855 The \QSDK package already contains a prebuilt debugging helper
5856 library. To create your own debugging helper library, select \gui{Tools} >
5857 \gui{Options...} > \gui{Qt4} > \gui{Qt Versions}. As the internal data
5858 structures of Qt can change between versions, the debugging helper
5859 library is built for each Qt version.
5862 \section1 Debugging Helpers Based on Python
5864 On platforms featuring a Python-enabled version of the gdb debugger,
5865 the data extraction is done by a Python script. This is more robust
5866 as the script execution is separated from the debugged process. It
5867 is also easier to extend as the script is less dependent on the
5868 actual Qt version and does not need compilation.
5870 To extend the shipped Python based debugging helpers for custom types,
5871 define one Python function per user defined type in the
5872 gdb startup file. By default, the following startup file is used:
5873 \c{~/.gdbinit}. To use another file, select \gui {Tools > Options... > Gdb}
5874 and specify a filename in the \gui {Gdb startup script} field.
5876 The function name has to be qdump__NS__Foo, where NS::Foo is the class
5877 or class template to be examined. Nested namespaces are possible.
5879 The debugger plugin calls this function whenever you want to
5880 display an object of this type. The function is passed the following
5883 \o \c d of type \c Dumper
5884 \o \c item of type \c Item
5887 The function has to feed the Dumper object with certain information
5888 which is used to build up the object and its children's display in the
5889 \gui{Locals and Watchers} view.
5895 def qdump__QVector(d, item):
5896 d_ptr = item.value["d"]
5897 p_ptr = item.value["p"]
5898 alloc = d_ptr["alloc"]
5899 size = d_ptr["size"]
5901 check(0 <= size and size <= alloc and alloc <= 1000 * 1000 * 1000)
5902 check(d_ptr["ref"]["_q_value"] > 0)
5904 innerType = item.value.type.template_argument(0)
5905 d.putItemCount(size)
5907 if d.isExpanded(item):
5908 p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
5909 with Children(d, [size, 2000], innerType)
5910 for i in d.childRange():
5911 d.putSubItem(Item(p.dereference(), item.iname, i))
5915 \section2 Item Class
5917 The Item Python class is a thin wrapper around values corresponding to one
5918 line in the \gui{Locals and Watchers} view. The Item members are as follows :
5922 \o \gui{__init__(self, value, parentiname, iname, name = None)} - A
5923 constructor. The object's internal name is created by concatenating
5924 \c parentiname and \c iname. If \c None is passed as \c name, a
5925 serial number is used.
5927 \o \gui{value} - An object of type gdb.Value representing the value to
5930 \o \gui{iname} - The internal name of the object, constituting a dot-separated
5931 list of identifiers, corresponding to the position of the object's
5932 representation in the view.
5934 \o \gui{name} - An optional name. If given, is used in the
5935 \gui{name} column of the view. If not, a simple number in brackets
5941 \section2 Dumper Class
5943 For each line in the \gui{Locals and Watchers} view, a string like the
5944 following needs to be created and channeled to the debugger plugin.
5946 "{iname='some internal name',
5947 addr='object address in memory',
5948 name='contents of the name column',
5949 value='contents of the value column',
5950 type='contents of the type column',
5951 numchild='number of children', // zero/nonzero is sufficient
5952 childtype='default type of children', // optional
5953 childnumchild='default number of grandchildren', // optional
5954 children=[ // only needed if item is expanded in view
5955 {iname='internal name of first child',
5957 {iname='internal name of second child',
5963 While in theory, you can build up the entire string above manually, it is
5964 easier to employ the Dumper Python class for that purpose. The Dumper
5965 Python class contains a complete framework to take care of the \c iname and
5966 \c addr fields, to handle children of simple types, references, pointers,
5967 enums, known and unknown structs as well as some convenience methods to
5968 handle common situations.
5970 The Dumper members are the following:
5974 \o \gui{__init__(self)} - Initializes the output to an empty string and
5975 empties the child stack.
5977 \o \gui{put(self, value)} - Low level method to directly append to the
5980 \o \gui{putCommaIfNeeded(self)} - Appends a comma if the current output
5981 ends in '}', '"' or ']' .
5983 \o \gui{putField(self, name, value)} - Appends a comma if needed, and a
5986 \o \gui{beginItem(self, name)} - Starts writing a field by writing \c {name='}.
5988 \o \gui{endItem(self)} - Ends writing a field by writing \c {'}.
5990 \o \gui{endChildren(self)} - Ends writing a list of children.
5992 \o \gui{childRange(self)} - Returns the range of children specified in
5993 the current \c Children scope.
5995 \o \gui{putItemCount(self, count)} - Appends a field \c {value='<%d items'}
5998 \o \gui{putEllipsis(self)} - Appends fields
5999 \c {'{name="<incomplete>",value="",type="",numchild="0"}'}. This is
6000 automatically done by \c endChildren if the number of children to
6001 print is smaller than the number of actual children.
6003 \o \gui{putName(self, name)} - Appends a \c {name='...'} field.
6005 \o \gui{putType(self, type)} - Appends a field \c {type='...'} unless the
6006 \a type coincides with the parent's default child type.
6008 \o \gui{putNumChild(self, numchild)} - Appends a field \c {numchild='...'}
6009 unless the \c numchild coincides with the parent's default child numchild
6012 \o \gui{putValue(self, value, encoding = None)} - Append a file \c {value='...'},
6013 optionally followed by a field \c {valueencoding='...'}. The \c value
6014 needs to be convertible to a string entirely consisting of
6015 alphanumerical values. The \c encoding parameter can be used to
6016 specify the encoding in case the real value had to be encoded in some
6017 way to meet the alphanumerical-only requirement.
6018 Currently the following encodings are supported:
6021 \o 0: unencoded 8 bit data, interpreted as Latin1.
6023 \o 1: base64 encoded 8 bit data, used for QByteArray,
6024 double quotes are added.
6026 \o 2: base64 encoded 16 bit data, used for QString,
6027 double quotes are added.
6029 \o 3: base64 encoded 32 bit data,
6030 double quotes are added.
6032 \o 4: base64 encoded 16 bit data, without quotes (see 2)
6034 \o 5: base64 encoded 8 bit data, without quotes (see 1)
6036 \o 6: %02x encoded 8 bit data (as with \c QByteArray::toHex),
6037 double quotes are added.
6039 \o 7: %04x encoded 16 bit data (as with \c QByteArray::toHex),
6040 double quotes are added.
6043 \o \gui{putStringValue(self, value)} - Encodes a QString and calls
6044 \c putValue with the correct \c encoding setting.
6046 \o \gui{putByteArrayValue(self, value)} - Encodes a QByteArray and calls
6047 \c putValue with the correct \c encoding setting.
6049 \o \gui{isExpanded(self, item)} - Checks whether the item with the
6050 internal name \c item.iname is expanded in the view.
6052 \o \gui{isExpandedIName(self, iname)} - Checks whether the item with the
6053 internal name \c iname is expanded in the view.
6055 \o \gui{putIntItem(self, name, value)} - Equivalent to:
6059 self.putValue(value)
6065 \o \gui{putBoolItem(self, name, value)} - Equivalent to:
6069 self.putValue(value)
6070 self.putType("bool")
6075 \o \gui{pushOutput(self)} - Moves the output string to a safe location
6076 from with it is sent to the debugger plugin even if further operations
6079 \o \gui{putCallItem(self, name, item, func)} -
6080 Uses gdb to call the function \c func on the value specified by
6081 \a {item.value} and output the resulting item. This function is
6082 not available when debugging core dumps and it is not available
6083 on the Symbian platform due to restrictions imposed by AppTRK.
6085 \o \gui{putItem(self, item)} - The "master function", handling
6086 basic types, references, pointers and enums directly, iterates
6087 over base classes and class members of compound types and calls
6088 \c qdump__* functions whenever appropriate.
6090 \o \gui{putSubItem(self, item)} - Equivalent to:
6095 Exceptions raised by nested function calls are caught and all
6096 output produced by \c putItem is replaced by the output of:
6099 except RuntimeError:
6100 d.put('value="<invalid>",type="<unknown>",numchild="0",')
6106 \section2 Children and SubItem Class
6108 The attempt to create child items might lead to errors if data is
6109 uninitialized or corrupted. To gracefully recover in such situations,
6110 use \c Children and \c SubItem \e{Context Managers} to create the nested items.
6112 The \c Children constructor \gui{__init__(self, dumper, numChild = 1,
6113 childType = None, childNumChild = None)} uses one mandatory argument and three
6114 optional arguments. The mandatory argument refers to the current \c Dumper
6115 object. The optional arguments can be used to specify the number \c numChild
6116 of children, with type \c childType_ and \c childNumChild_ grandchildren each.
6117 If \c numChild_ is a list of two integers, the first one specifies the actual
6118 number of children and the second the maximum number of children to print.
6120 Similarly, using the \c SubItem class helps to protect individual items.
6125 if d.isExpanded(item):
6129 d.putItem(Item(key, item.iname, "key"))
6132 d.putItem(Item(value, item.iname, "value"))
6135 \section1 Debugging Helpers for QML
6137 The debugging helpers for QML provide you with code completion for custom modules
6138 (\c qmldump) and debugging Qt Quick UI projects (\c qmlobserver).
6140 You have to build the QML Observer once for each Qt version that you want to debug
6141 with. Select \gui{Tools > Options... > Qt4 > Qt Versions}.
6143 \note QML Observer requires Qt 4.7.1 or later.
6149 \contentspage index.html
6150 \previouspage creator-project-qmake.html
6151 \page creator-project-cmake.html
6152 \nextpage creator-project-generic.html
6154 \title Setting Up a CMake Project
6156 CMake is an alternative to qmake for automating the generation of makefiles.
6157 It controls the software compilation process by using simple configuration
6158 files, called CMakeLists.txt files. CMake generates native makefiles and
6159 workspaces that you can use in the compiler environment of your choice.
6161 Since Qt Creator 1.1, CMake configuration files are supported.
6162 Qt Creator 1.3 supports the Microsoft Toolchain if the CMake version
6165 \section1 Setting the Path for CMake
6167 You can set the path for the \c CMake executable in \gui{Tools} >
6168 \gui{Options... > Projects > CMake}.
6170 \image qtcreator-cmakeexecutable.png
6172 \note Before you open a \c CMake project it is necessary to modify the
6173 \c{PATH} environment variable to include the bin folders of \c mingw and
6174 Qt Creator in the SDK.
6176 For instance, if you have the Qt Creator SDK installed in your C drive,
6177 use the following command to set the environment variables in
6178 the command line prompt:
6180 set PATH=C:\qtsdk\mingw\bin;C:\qtsdk\qt\bin;
6182 Then start Qt Creator by typing:
6184 C:\qtsdk\bin\qtcreator.exe
6187 \section1 Opening CMake Projects
6189 To open a \c CMake project:
6191 \o Select \gui{File} > \gui{Open File or Project...}.
6192 \o Select the \c{CMakeLists.txt} file from your \c CMake project.
6195 A wizard guides you through the rest of the process.
6197 \note If the \c CMake project does not have an in-place build, Qt Creator
6198 lets you specify the directory in which the project is built
6199 (\l{glossary-shadow-build}{shadow build}).
6201 \image qtcreator-cmake-import-wizard1.png
6203 The screenshot below shows how you can specify command line arguments to
6204 \c CMake for your project.
6206 \image qtcreator-cmake-import-wizard2.png
6208 Normally, there is no need to pass any command line arguments for projects
6209 that are already built, as \c CMake caches that information.
6212 \section1 Building CMake Projects
6214 Qt Creator builds \c CMake projects by running \c make, \c mingw32-make, or
6215 \c nmake depending on your platform. The build errors and warnings are
6216 parsed and displayed in the \gui{Build Issues} output pane.
6218 By default, Qt Creator builds the \bold{all} target. You can specify which
6219 targets to build in \gui{Project} mode, under \gui{Build Settings}.
6221 \image qtcreator-cmake-build-settings.png
6223 Qt Creator supports multiple build configurations. The build
6224 directory can also be modified after the initial import.
6226 \section1 Running CMake Projects
6227 Qt Creator automatically adds \gui{Run Configurations} for all targets
6228 specified in the \c CMake project file.
6230 Known issues for the current version can be found
6231 \l{Known Issues}{here}.
6234 \section1 Adding External Libraries to CMake Projects
6236 Through external libraries Qt Creator can support code completion and
6237 syntax highlighting as if they were part of the current project or the Qt
6240 Qt Creator detects the external libraries using the \c FIND_PACKAGE()
6241 macro. Some libraries come with the CMake installation. You can find those
6242 in the \bold{Modules} directory of your CMake installation.
6244 \note If you provide your own libraries, you also need to provide your own
6245 \c FindFoo.cmake file. For more information, see
6246 \l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}.
6248 Syntax completion and highlighting work once your project successfully
6249 builds and links against the external library.
6254 \contentspage index.html
6255 \previouspage creator-debugging-helpers.html
6256 \page creator-debugging-qml.html
6257 \nextpage creator-maemo-emulator.html
6259 \title Debugging Qt Quick Projects
6261 \note You need Qt 4.7.1 or later to debug Qt Quick projects.
6263 \section1 Setting Up QML Debugging
6265 The process of setting up debugging for Qt Quick projects depends on the type of
6266 the project: Qt Quick UI or Qt Quick Application.
6268 To debug Qt Quick UI projects, you must compile the debugging helpers. For more
6269 information, see \l{Debugging Helpers for QML}.
6271 To debug Qt Quick Applications, you must modify the project file to comment in the
6274 \c {DEFINES += QMLJSDEBUGGER}.
6276 Then you must rebuild the project.
6278 To enable QML debugging for both types of projects, select \gui Projects, and
6279 then select the \gui QML check box in the run settings.
6281 \section1 Starting QML Debugging
6283 To start the application, choose \gui {Debug > Start Debugging
6284 > Start Debugging} or press \key F5. Once the application starts running, it behaves
6285 and performs as usual. You can then perform the following tasks:
6289 \o Debug JavaScript functions
6291 \o Preview QML changes at runtime
6293 \o Inspect QML at runtime
6297 \section1 Debugging JavaScript Functions
6299 You can use the Qt Creator \gui Debug mode to inspect the state of your
6300 application while debugging. You can interact with the debugger in several
6301 ways, as described in the following sections:
6305 \o \l{Setting Breakpoints}
6307 \o \l{Viewing Call Stack Trace}
6309 \o \l{Locals and Watchers}
6313 \section1 Executing JavaScript Expressions
6315 When the application is interrupted by a breakpoint, you can use the \gui {QML
6316 Script Console} to execute JavaScript expressions in the current context. To
6317 open it, choose \gui {Window > View > QML Script Console}.
6319 \image qml-script-console.png "QML Script Console view"
6321 You can type JavaScript expressions and use them to get information about the
6322 state or your application. For example, property values.
6324 You can see the current value of a property by hovering over it in the code editor.
6326 \section1 Previewing QML Changes at Runtime
6328 If you change property values or add properties in the code editor, the changes
6329 are updated in the running application when you save them. If live preview is not supported
6330 for an element, a message appears. Click \gui Reload to preview the changes.
6332 Reloading is enabled by default. To disable it, click
6333 \inlineimage qml-observer-bar-reload.png "Apply Changes on Save button"
6334 in the \gui {QML Observer} view.
6336 \section1 Inspecting QML at Runtime
6338 While the application is running, you can use the \gui {QML Observer} view to
6339 explore the object structure, debug animations, and inspect colors.
6340 To open the \gui {QML Observer} view, choose \gui {Window > View > QML Observer}.
6342 \image qml-observer-view.png "QML Observer view"
6344 When you debug complex applications, you can use the observe
6345 mode to jump to the position in code where an element is defined. To switch to
6346 the observe mode, click
6347 \inlineimage qml-observer-bar-observe.png
6348 in the \gui {QML Observer} view.
6350 Click elements in the running application to jump to their definitions in the code.
6351 Double-click elements to browse the element hierarchy. The hierarchy is displayed
6352 as bread crumbs in the \gui {QML Observer} view.
6354 You can also right-click an element in the running application to view the element
6355 hierarchy as a context menu. Select an element to jump to its definition in code.
6357 To zoom in and out of the application, click the \gui Zoom button.
6359 To inspect colors, click the \gui {Color Picker} button. You can also the click
6360 \inlineimage qml-observer-bar-copy-color.png "Copy Color button"
6361 to copy the color definition to the clipboard.
6363 \section1 Debugging Animations
6365 \image qml-observer.png
6367 To play and pause animations in the running application, click the \gui {Play/Pause Animations}
6368 button in the \gui {QML Observer} view or \gui {Debugging > Animations > Pause} or press
6371 To step through an animation, select \gui {Debugging > Animations > Pause & Step}
6372 or press \key {Ctrl+,}.
6374 To set step duration in milliseconds, select \gui {Debugging > Animations > Set Step}.
6375 To change the speed at which animations are played, select a value in \gui {Debugging
6382 \contentspage index.html
6383 \previouspage creator-project-cmake.html
6384 \page creator-project-generic.html
6385 \nextpage creator-developing-maemo.html
6387 \title Setting Up a Generic Project
6389 Qt Creator supports generic projects, so you can import existing projects
6390 that do not use qmake or CMake and Qt Creator ignores your build system.
6392 Generic project support allows you to use Qt Creator as a code editor. You
6393 can change the way your project is built by modifying the \c make command
6394 in the \gui{Projects} mode under \gui{Build Settings}.
6396 When you import a project, Qt Creator creates the following files that
6397 allow you to specify which files belong to your project and which include
6398 directories or defines you want to pass to your compile:
6399 \tt{.files}, \tt{.includes}, and \tt{.config}.
6402 \section1 Importing a Generic Project
6404 To import an existing generic project:
6406 \o Select \gui File > \gui{New File or Project...} >
6407 \gui{Other Project} > \gui{Import Existing Project}.
6408 \o In \gui{Import Existing Project}, enter the project name
6409 and select the location of the project file you want to import.
6411 Qt Creator automatically generates the following files in the
6414 \o \l{Specifying Files}{.files}
6415 \o \l{Specifying Include Paths}{.includes}
6416 \o \l{Specifying Defines}{.config}
6421 When the project is successfully imported, Qt Creator creates the project
6422 tree in the sidebar.
6424 After importing a generic project into Qt Creator, open it by selecting the
6428 \section1 Working with Generic Project Files
6430 For a generic project, you have to manually specify which files belong to
6431 your project and which include directories or defines you want to pass to
6435 \section1 Specifying Files
6437 The list of files for a generic project is specified in the \tt{.files}
6438 file. When you first create a generic project, Qt Creator adds any
6439 files it recognizes to your project.
6441 To add or remove files, edit the \tt{.files} file in Qt Creator.
6442 Qt Creator recreates your project tree when you save the \tt{.files} file.
6443 Alternatively, you can add and remove files using the context menu in the
6446 If you frequently need to update the \tt{.files} file, you can do so
6447 efficiently by using a script that updates the file for you. If the file
6448 is modified externally, you have to restart Qt Creator for the changes to
6451 To update the \tt{.files} on the \gui Git repository use the following
6454 git ls-files *.cpp *.h > MyProject.files
6457 \section1 Specifying Include Paths
6459 The include paths are specified in the \tt{.includes} file, one include
6460 path per line. The paths can be either absolute or relative to the
6461 \tt{.includes} file.
6463 \section1 Specifying Defines
6465 The defines are specified in the \tt{.config} file. The \tt{.config} file is
6466 a regular C++ file, prepended to all your source files when they are parsed.
6467 Only use the \tt{.config} file to add lines as in the example below:
6474 \section1 Creating a Run Configuration
6476 Qt Creator cannot automatically determine which executable to run.
6478 In the \gui{Projects} mode under \gui{Run Settings}, define the executable
6481 \o Click \gui Add and select \gui{Custom Executable}.
6482 \o Define the configuration name, the location of the executable, any
6483 additional arguments and the working directory.
6492 \contentspage index.html
6493 \previouspage adding-plugins.html
6494 \page creator-visual-editor.html
6495 \nextpage quick-projects.html
6497 \title Developing Qt Quick Applications
6499 You can either create Qt Quick projects from scratch or import existing projects to
6502 You can use the code editor (\l{Using the Editor}{Edit mode}) or the visual editor
6503 (\l{Using Qt Quick Designer}{Design mode}) to develop Qt Quick applications.
6504 The following sections describe typical tasks you can do with Qt Creator.
6508 \o \l {Creating Qt Quick Projects}
6509 \o \l {Using Qt Quick Designer}
6510 \o \l {Creating Components}
6511 \o \l {Creating Screens}
6512 \o \l {Animating Screens}
6513 \o \l {Adding User Interaction Methods}
6514 \o \l {Implementing Application Logic}
6523 \contentspage index.html
6524 \previouspage creator-visual-editor.html
6525 \page quick-projects.html
6526 \nextpage creator-using-qt-quick-designer.html
6528 \title Creating Qt Quick Projects
6530 \image qmldesigner-new-project.png "New File or Project dialog"
6532 When you create a new Qt Quick project from scratch, you have the following options:
6536 \o \gui {Qt Quick UI} creates a Qt Quick UI project with a single QML file that
6537 contains the main view. You can review Qt Quick UI projects in the QML Viewer and you
6538 need not build them. You do not need to have the development environment installed on your
6539 computer to create and run this type of projects.
6541 \o \gui {Qt Quick Application} creates a Qt Quick application project that can
6542 contain both QML and C++ code. The project includes a QDeclarativeView. You can build
6543 the application and deploy it on desktop and mobile target platforms. For example, you
6544 can create signed Symbian Installation System (SIS) packages for this type of projects.
6546 \o \gui {Custom QML Extension Plugin} creates a C++ plugin that makes it possible
6547 to offer extensions that can be loaded dynamically into applications by using the
6548 QDeclarativeEngine class.
6552 If you have existing QML applications that you want to run in Qt Creator or deploy
6553 to mobile devices, use the \gui {Qt Quick Application} wizard to convert them
6554 to Qt Quick applications.
6556 \section1 Creating Qt Quick UI Projects
6560 \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick UI
6563 The \gui{Introduction and Project Location} dialog opens.
6565 \image qmldesigner-new-project-location.png "Introduction and Project Location dialog"
6567 \o In the \gui Name field, give a name to the project.
6569 Do not use spaces and special characters in the project name and path.
6571 \o In the \gui {Create in} field, enter the path for the project files. For example,
6572 \c {C:\Qt\examples}. To select the path from a directory tree, click \gui Browse.
6574 \o Click \gui{Next}.
6576 \image qmldesigner-new-ui-project-summary.png "Project Management dialog"
6578 \o Review the project settings, and click \gui{Finish} to create the project.
6583 Qt Creator creates the following files:
6587 \o .qmlproject project file defines that all QML, JavaScript, and image
6588 files in the project folder belong to the project. Therefore, you do not
6589 need to individually list all the files in the project.
6591 \o .qml file defines an element, such as a component, screen, or the whole
6596 The \c import statement in the beginning of the .qml file specifies the
6597 \l {http://doc.qt.nokia.com/4.7/qdeclarativemodules.html} {Qt modules}
6598 to import. Each Qt module contains a set of default elements.
6599 Specify a version to get the features you want.
6601 To use JavaScript and image files in the application, copy them to the
6604 \section1 Creating Qt Quick Applications
6608 \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick Application
6611 The \gui{Introduction and Project Location} dialog opens.
6613 \image qmldesigner-new-project-location.png "Introduction and Project Location dialog"
6615 \o In the \gui Name field, give a name to the project.
6617 Do not use spaces and special characters in the project name and path.
6619 \o In the \gui {Create in} field, enter the path for the project files. For example,
6620 \c {C:\Qt\examples}. To select the path from a directory tree, click \gui Browse.
6622 \o Click \gui{Next}.
6624 The \gui {Qt Versions} dialog opens.
6626 \image qmldesigner-new-project-qt-versions.png "Qt Versions dialog"
6628 \o Select the Qt versions to use as build targets for your project,
6629 and then click \gui{Next}.
6631 \note Qt Quick is supported since Qt 4.7, and therefore, only Qt 4.7 and later
6632 versions are displayed. Further, if you have only one supported Qt version installed,
6633 this dialog is skipped.
6635 The \gui{Application Options} dialog opens.
6637 \image qtcreator-mobile-project-app-options.png "Application Options dialog"
6639 \o In the \gui {Orientation behavior} field, determine how the application
6640 behaves when the orientation of the device display rotates between portrait
6643 \o In the \gui {Application icon} field, select an application icon.
6645 \o In the \gui {Target UID3} field, specify the \l{Application UID}.
6647 \note Qt Creator generates a UID for testing the application on a device.
6648 You need to change the UID when you deliver the application for public
6651 \o If the application needs network connectivity, select the
6652 \gui {Enable network access} check box, and then click \gui{Next}.
6654 The \gui {QML Sources} dialog opens.
6656 \image qmldesigner-new-project-qml-sources.png "QML Sources" dialog
6658 \o In the \gui {QML Main File} group, select \gui {Generate a .qml file},
6659 and then click \gui{Next}.
6661 The \gui {Project Management} dialog opens.
6663 \image qmldesigner-new-project-summary.png "Project Management" dialog
6665 \o In the \gui {Add to project} field, you can add this project to another
6666 project as a subproject.
6668 \o In the \gui {Add to version control} field, you can add the project to
6669 a version control system.
6671 \o Click \gui Finish to create the project.
6675 Qt Creator creates the necessary boilerplate files. Some of the files are
6676 specific to the Symbian or Maemo platform.
6678 \section1 Importing QML Applications
6680 If you have existing QML applications that you want to run in Qt Creator or deploy
6681 to mobile devices, use the \gui {Qt Quick Application} wizard and select the main
6682 .qml file in your project. All the other files in the project are automatically added
6683 to the application project.
6685 For example, you can open and run the
6686 \l {http://doc.qt.nokia.com/4.7/qdeclarativeexamples.html} {QML examples and demos}
6687 to learn how to use various aspects of QML. To run the examples in the QML Viewer
6688 on the desktop, open them in the \gui Welcome mode. To view the examples on
6689 mobile devices, use the \gui {Qt Quick Application} wizard to convert them into
6690 Qt Quick Applications.
6692 To import QML applications:
6696 \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick Application
6699 \o Name the project and set its path, and then click \gui Next.
6701 \o Select the Qt versions to use as build targets for your project, and click
6704 \o Specify options for deploying the application to mobile device targets, and
6707 \o In the \gui {QML Sources} dialog, select the \gui {Import an existing .qml file}
6708 option and specify the main .qml file of the project you want to import.
6710 \image qmldesigner-import-project.png "QML Sources" dialog
6714 \o Review the project settings, and click \gui{Finish} to create the project.
6718 Qt Creator adds references to the QML files to a project and creates the additional files
6719 necessary for deploying applications on mobile devices.
6726 \contentspage index.html
6727 \previouspage creator-using-qt-quick-designer.html
6728 \page quick-components.html
6729 \nextpage quick-buttons.html
6731 \title Creating Components
6733 A QML component provides a way of defining a new type that you can re-use in other QML
6734 files. A component is like a black box; it interacts with the outside world
6735 through properties, signals, and slots, and is generally defined in its own QML file.
6736 You can import components to screens and applications.
6738 You can use the following QML elements to create components:
6742 \o \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
6743 uses an image as a border or background.
6744 \o \l{http://doc.qt.nokia.com/4.7/qml-image.html}{Image}
6745 adds a bitmap to the scene. You can stretch and tile images.
6746 \o \l{http://doc.qt.nokia.com/4.7/qml-item.html}{Item}
6747 is the most basic of all visual items in QML. Even though it has no visual appearance,
6748 it defines all the properties that are common across visual items, such as the x and
6749 y position, width and height, anchoring, and key handling.
6750 \o \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
6751 adds a rectangle that is painted with a solid fill color and an optional border.
6752 You can also use the radius property to create rounded rectangles.
6753 \o \l{http://doc.qt.nokia.com/4.7/qml-text.html}{Text}
6754 adds formatted read-only text.
6755 \o \l{http://doc.qt.nokia.com/4.7/qml-textedit.html}{Text Edit}
6756 adds a single line of editable formatted text that can be validated.
6757 \o \l{http://doc.qt.nokia.com/4.7/qml-textinput.html}{Text Input}
6758 adds a single line of editable plain text that can be validated.
6762 \section1 Creating Components in Qt Quick Designer
6766 \o Select \gui {File > New File or Project > Files and Classes > QML
6767 > Choose...} to create a new .qml file.
6769 \note Components are listed in the \gui {QML Components} section of the
6770 \gui Library pane only if the filename begins with a capital letter.
6772 \o Click \gui Design to open the .qml file in \QMLD.
6774 \o Drag and drop an item from the \gui Library pane to the editor.
6776 \o Edit item properties in the \gui Properties pane.
6778 The available properties depend on the item.
6782 The following sections contain examples of how to create some common components:
6786 \o \l{Creating Buttons}
6788 \o \l{Creating Scalable Buttons and Borders}
6796 \contentspage index.html
6797 \previouspage quick-components.html
6798 \page quick-buttons.html
6799 \nextpage quick-scalable-image.html
6801 \title Creating Buttons
6803 To create a button component:
6807 \o Select \gui {File > New File or Project > QML > QML File > Choose...} to
6808 create a QML file called Button.qml (for example).
6810 \note Components are listed in the \gui Library pane only if the filename
6811 begins with a capital letter.
6813 \o Click \gui {Design} to edit the file in the visual editor.
6815 \o In the \gui Navigator pane, click \gui Rectangle to set properties
6818 \o In the \gui Properties pane, modify the appearance of the button.
6822 \o In the \gui Size field, set the width (\gui W) and height (\gui H)
6825 \o In the \gui Color field, select the button color.
6827 \o In the \gui Radius field, use the slider to set the radius of the
6828 rectangle and produce rounded corners for the button.
6832 \o Drag and drop a \gui {Text} item on top of the \gui Rectangle. This
6833 creates a nested element where \gui Rectangle is the parent element of
6834 \gui Text. Elements are positioned relative to their parents.
6836 \o In the \gui Properties pane, edit the properties of the \gui Text item.
6840 \o In the \gui Text field, type \bold Button.
6842 You can select the text color, font, size, and style in the \gui Font
6845 \o In the \gui Alignment field, select the center buttons to align
6846 the text to the center of the button.
6848 \o Click \gui {Layout}, and then click the
6849 \inlineimage qmldesigner-anchor-fill-screen.png
6850 button to anchor the text to the whole button area.
6854 \o Press \key {Ctrl+S} to save the button.
6856 \image qmldesigner-button.png "Button component"
6860 \note To view the button, you must add it to a Qt Quick Application or Qt Quick UI
6863 To create a graphical button that scales beautifully without using vector graphics,
6864 use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
6865 element. For more information, see \l{Creating Scalable Buttons and Borders}.
6872 \contentspage index.html
6873 \previouspage quick-buttons.html
6874 \page quick-scalable-image.html
6875 \nextpage quick-screens.html
6877 \title Creating Scalable Buttons and Borders
6879 You can use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
6880 element to display an image, such as a PNG file, as a border and a background.
6882 Use two Border Image elements and suitable graphics to make it look like the button
6883 is pushed down when it is clicked. One of the Border Image elements is visible by default.
6884 You can specify that it is hidden and the other one becomes visible when the mouse
6887 Add a MouseArea that covers the whole area and emits the clicked signal (\c {parent.clicked()})
6888 when it detects a mouse click.
6890 You can add text to the button and set it up as a property. The text can then be initialized
6891 from the outside, making the button a reusable UI component. The font size is also available
6892 in case the default size is too big. You can scale down the button text and use smooth text
6893 rendering for some extra quality.
6895 \image qmldesigner-borderimage.png "Graphical button"
6897 To create a graphical button:
6901 \o Select \gui {File > New File or Project > QML > QML File > Choose...} to create
6902 a QML file called Button.qml (for example).
6904 \o Double-click the file to open it in the code editor.
6906 \o Replace the \gui Rectangle with an \gui Item, as illustrated by the
6907 following code snippet:
6917 \o Specify properties and set expressions for the \gui Item, as
6918 illustrated by the following code snippet:
6922 property string text: ""
6923 property int fontSize: 44
6929 You will point to the properties and expression later.
6931 \o Click \gui {Design} to edit the file in the visual editor.
6933 \o Drag and drop two \gui BorderImage items from the \gui Library pane to
6936 \o Drag and drop a \gui Text item to the scene.
6938 \o Drag and drop a \gui MouseArea to the screen.
6940 \o In the \gui Navigator pane, select \gui border_image1 to specify
6941 settings for it in the \gui Properties pane:
6945 \o Select \gui {Set Expression} in the menu next to the \gui Visibility
6948 \o Enter the following expression to specify that the image is visible
6949 when the mouse is not pressed down: \c {!mouse_area1.pressed}.
6951 \o In the \gui Source field, select the image file for the
6952 button, for example button_up.png.
6954 \o Click \gui {Layout}, and then click the
6955 \inlineimage qmldesigner-anchor-fill-screen.png
6956 button to anchor the border image to the \gui Item.
6960 \o Select \gui border_image2 to specify similar settings for it:
6964 \o Set the following epression for \gui Visibility, to specify that
6965 the the image is visible when the mouse is pressed down:
6966 \c {mouse_area1.pressed}.
6968 \o In the \gui Source field, select the image file for the
6969 button when it is clicked, for example button_down.png.
6971 \o Click \gui {Layout}, and then click the
6972 \inlineimage qmldesigner-anchor-fill-screen.png
6973 button to anchor the border image to the \gui Item.
6977 \o Select \gui text1 to specify font size and color, and text
6978 scaling and rendering:
6982 \o In the \gui Color field, use the color picker to select
6983 the font color, or enter a value in the field.
6985 \o In the \gui Text field, select \gui {Set Expression} and
6986 enter a pointer to the \c {text} property that you specified
6987 earlier: \c {parent.txt}.
6989 \o Select the \gui Aliasing check box to enable smooth text
6992 \o In the \gui Size field, select \gui {Pixels} to specify
6993 the font size in pixels. By default, the size is specified in
6996 \o In the \gui Size field, select \gui {Set Expression} and
6997 enter a pointer to the \c {fontSize} property that you specified
7000 \o Click \gui {Layout}, and then click the
7001 \inlineimage qmldesigner-center-in.png "Anchor buttons"
7002 buttons to inherit the vertical and horizontal centering from
7005 \o Click \gui Advanced to specify scaling for the text in the
7008 \o Select \gui {Set Expression} and enter the following expression:
7009 \c {if (!mousearea1.pressed) { 1 } else { 0.95 }}.
7011 \note You can enter long and complicated expressions also in the
7016 \o In the code editor, add to the \c MouseArea item
7017 a pointer to the \c clicked expression that you added earlier:
7018 \c {onClicked: parent.clicked()}.
7022 \note To view the button, you must add it to a Qt Quick Application or Qt
7030 \contentspage index.html
7031 \previouspage quick-components.html
7032 \page quick-screens.html
7033 \nextpage quick-animations.html
7035 \title Creating Screens
7037 You can use predefined QML elements and your own components to create screens.
7038 Typically, the main qml file in a Qt Quick project specifies the main window of an
7041 The QML files in the project folder are displayed in \gui {QML Components} in the
7044 \section1 Adding Components to Screens
7048 \o Drag and drop components from the \gui Library pane to the editor.
7050 \o Select components in the \gui Navigator pane to edit their properties
7051 in the \gui Properties pane.
7053 For example, you can anchor components to a position on the screen.
7057 \section1 Organizing Items on Screens
7059 You can create the following types of views to organize items provided by
7060 \l{http://doc.qt.nokia.com/4.7/qdeclarativemodels.html}{data models}:
7064 \o \l{http://doc.qt.nokia.com/4.7/qml-gridview.html}{Grid View}
7065 \o \l{http://doc.qt.nokia.com/4.7/qml-listview.html}{List View}
7066 \o \l{http://doc.qt.nokia.com/4.7/qml-pathview.html}{Path View}
7070 In the code editor, write the code to use the data models.
7072 \section1 Using States
7074 Use states and transitions
7075 to navigate between screens.
7077 QML states typically describe user interface configurations, such as the UI elements,
7078 their properties and behavior and the available actions. For example, you can use
7079 states to create two screens.
7081 To add states, click the empty slot in the \gui States pane. Then modify the new state
7082 in the visual editor.
7084 \image qmldesigner-states.png "States pane"
7086 The properties that you change in a state are highlighted with blue color.
7087 In the code editor, you can see the changes recorded as changes to the base state.
7093 \contentspage index.html
7094 \previouspage quick-screens.html
7095 \page quick-animations.html
7096 \nextpage quick-user-interaction.html
7098 \title Animating Screens
7100 To make movement between states smooth, you can specify transitions.
7101 You can use different types of animated transitions. For example, you can animate changes
7102 to property values and colors. You can use rotation animation to control the direction of
7103 rotation. For more information, see
7104 \l{http://doc.qt.nokia.com/4.7/qdeclarativeanimation.html}{QML Animation}.
7106 You can use the \c ParallelAnimation element to start several animations at the same time.
7107 Or use the \c SequentialAnimation element to run them one after another.
7109 You can use the code editor to specify transitions. For more information, see
7110 \l{http://doc.qt.nokia.com/4.7/qml-transition.html}{QML Transition Element}.
7118 \contentspage index.html
7119 \previouspage quick-animations.html
7120 \page quick-user-interaction.html
7121 \nextpage quick-application-logic.html
7123 \title Adding User Interaction Methods
7125 You can add the following basic interaction methods to scenes:
7129 \o \l{http://doc.qt.nokia.com/4.7/qml-flickable.html}{Flickable}
7130 items can be flicked horizontally or vertically.
7131 \o \l{http://doc.qt.nokia.com/4.7/qml-flipable.html}{Flipable}
7132 items can be flipped between their front and back sides by using rotation,
7133 state, and transition.
7134 \o \l{http://doc.qt.nokia.com/4.7/qml-focusscope.html}{Focus Scope}
7135 assists in keyboard focus handling when building reusable QML components.
7136 \o \l{http://doc.qt.nokia.com/4.7/qml-mousearea.html}{Mouse Area}
7137 enables simple mouse handling.
7146 \contentspage index.html
7147 \previouspage quick-user-interaction.html
7148 \page quick-application-logic.html
7149 \nextpage creator-building-running.html
7151 \title Implementing Application Logic
7153 A user interface is only a part of an application, and not really useful by itself.
7154 You can use Qt or JavaScript to implement the application logic. For more information on
7155 using JavaScript, see
7156 \l {http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html} {Integrating JavaScript}.
7158 For an example of how to use JavaScript to develop a game, see the
7159 \l {http://doc.qt.nokia.com/4.7/qml-advtutorial.html} {QML Advanced Tutorial}.
7165 \contentspage index.html
7166 \previouspage creator-editor-refactoring.html
7167 \page qt-quick-toolbars.html
7168 \nextpage creator-editor-locator.html
7170 \title Using Qt Quick Toolbars
7172 When you edit QML code in the code editor, you specify the properties
7173 of QML components. For some properties, such as colors and font names,
7174 this is not a trivial task. For example, few people can visualize the
7177 To easily edit these properties, you can use the Qt Quick Toolbars.
7178 When you select a component in the code and a toolbar is available,
7179 a light bulb icon appears:
7180 \inlineimage qml-toolbar-indicator.png
7181 . Select the icon to open the toolbar.
7183 To open toolbars immediately when you select a component, select
7184 \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar > Always show Quick
7187 Drag the toolbar to pin it to another location. Select
7188 \inlineimage qml-toolbar-pin.png
7189 to unpin the toolbar and move it to its default location. To pin toolbars
7190 by default, select \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar
7191 > Pin Quick Toolbar}.
7193 \section1 Previewing Images
7195 The Qt Quick Toolbar for images allows you to edit the properties of
7196 \l{http://doc.qt.nokia.com/latest/qml-borderimage.html}{Border Image}
7197 and \l{http://doc.qt.nokia.com/latest/qml-image.html}{Image} components.
7198 You can scale and tile the images, replace them with other images,
7199 preview them, and change the image margins.
7201 \image qml-toolbar-image.png "Qt Quick Toolbar for images"
7203 To preview an image, double-click it on the toolbar. In the preview
7204 dialog, you can zoom the image. Drag the image margins to change them.
7206 \image qml-toolbar-image-preview.png "Image preview dialog"
7208 \section1 Formatting Text
7210 The Qt Quick Toolbar for text allows you to edit the properties of
7211 \l{http://doc.qt.nokia.com/latest/qml-text.html}{Text} components.
7212 You can change the font family and size as well as text formatting, style,
7213 alignment, and color.
7215 If a property is assigned an expression instead of a value, you
7216 cannot use the toolbar to edit it. The button for editing the property
7219 \image qml-toolbar-text.png "Qt Quick Toolbar for text"
7221 By default, font size is specified as pixels. To use points, instead,
7222 change \gui px to \gui pt in the size field.
7224 \section1 Previewing Animation
7226 The Qt Quick Toolbar for animation allows you to edit the properties of
7227 \l{http://doc.qt.nokia.com/4.7/qml-propertyanimation.html}{PropertyAnimation}
7228 components and the components that inherit it. You can change the easing curve
7229 type and duration. For some curves, you can also specify amplitude, period,
7230 and overshoot values.
7232 \image qml-toolbar-animation.png "Qt Quick Toolbar for animation"
7234 Select the play button to preview your changes.
7236 \section1 Editing Rectangles
7238 The Qt Quick Toolbar for rectangles allows you to edit the properties of
7239 \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
7240 components. You can change the fill and border colors and add
7243 \image qml-toolbar-rectangle.png "Qt Quick Toolbar for rectangles"
7245 To add gradient stop points, click above the gradient bar. To remove
7246 stop points, drag them upwards.
7252 \contentspage index.html
7253 \previouspage creator-debugging-helpers.html
7254 \page creator-maemo-emulator.html
7255 \nextpage creator-version-control.html
7257 \title Using the Maemo Emulator
7259 The Maemo emulator emulates the Nokia N900 device environment. You can test
7260 applications in conditions practically identical to running the application
7261 on a Nokia N900 device with software update release 1.2 (V10.2010.19-1).
7262 You can test user interaction by using the keypad and
7265 To test the application UI, user interaction with the application, and
7266 functionality that uses the mobility APIs, use the Qt Simulator,
7267 instead. For more information, see the
7268 \l{http://doc.qt.nokia.com/qt-simulator-beta/index.html}{Qt Simulator Manual}.
7270 The Maemo emulator is installed and configured as part of the \QSDK
7271 package. You can also install and configure the MADDE environment and
7272 Maemo emulator separately. For more information, see
7273 \l{Setting Up Development Environment for Maemo}.
7275 \section1 Starting the Maemo Emulator
7277 The \gui {Start Maemo Emulator} button is visible if you have a project
7278 open in Qt Creator for which you have added the Maemo build target
7279 and if you have configured a connection between Qt Creator and the Maemo
7282 To start the Maemo emulator:
7287 \inlineimage qtcreator-maemo-emulator-button.png "Start Maemo Emulator button"
7290 \o Select \gui {Mad Developer} on the Maemo emulator, to start the Mad Developer
7293 \o If you have not deployed an SSH key to protect the connection between
7294 Qt Creator and the Maemo emulator, select \gui {Developer Password} to generate
7297 \o In Qt Creator, enter the password in the connection settings:
7298 \gui {Tools > Options... > Projects > Maemo Device Configurations}.
7302 Test your application on the Maemo emulator as on a device. For a list of
7303 keyboard shortcuts that you can use to emulate Nokia N900 keys and functions, see
7304 \l {Emulating Nokia N900 Keys}.
7306 \section1 Emulating Nokia N900 Keys
7308 The following table summarizes the keyboard shortcuts that you can use
7309 to emulate Nokia N900 keys and functions.
7314 \o Keyboard Shortcut
7325 \o Respective keys on the development PC keyboard.
7339 \o Keypad slider open and close
7345 \o Camera lens open and close
7351 \o Camera take picture
7353 \note The actual camera functionality is not emulated.
7355 \o Stereo headphones connect and disconnect
7364 \o Accelerometer x axis, negative
7367 \o Accelerometer x axis, positive
7370 \o Accelerometer z axis, negative
7373 \o Accelerometer z axis, positive
7376 \o Accelerometer y axis, negative
7379 \o Accelerometer y axis, positive
7389 \contentspage index.html
7390 \previouspage creator-using-qt-designer.html
7391 \page adding-plugins.html
7392 \nextpage creator-visual-editor.html
7394 \title Adding Qt Designer Plugins
7396 You can use Qt APIs to create plugins that extend Qt applications.
7397 This allows you to add your own widgets to \QD.
7398 The most flexible way to include a plugin with an application is to compile it
7399 into a dynamic library that is shipped separately, and detected and loaded at runtime.
7401 The applications can detect plugins that are stored in the standard plugin
7402 subdirectories. For more information on how to create and locate plugins and to
7403 change the default plugin path, see \l{How to Create Qt Plugins}.
7405 For more information about how to create plugins for \QD, see
7406 \l{http://doc.qt.nokia.com/4.7/designer-using-custom-widgets.html}{Creating and Using Components for Qt Designer}.
7408 \section1 Locating Qt Designer Plugins
7410 \QD fetches plugins from the standard locations and loads the plugins
7411 that match its build key. \QD is delivered both as a standalone application
7412 and as part of the SDK, where it is integrated into Qt Creator.
7413 The correct folder to place the plugins depends on
7416 The integrated \QD fetches plugins from the \c {%SDK%\bin\designer} folder on Windows
7417 and Linux. For information about how to configure plugins on Mac OS, see
7418 \l{Configuring Qt Designer Plugins on Mac OS}.
7420 To check which plugins
7421 were loaded successfully and which failed, choose \gui{Tools > Form Editor >
7422 About Qt Designer Plugins}.
7424 The standalone \QD is part of the Qt library used for building projects,
7425 located under \c {%SDK%\qt}. Therefore, it fetches plugins from the following folder:
7426 \c {%SDK%\qt\plugins\designer}. To check which plugins were loaded successfully and which
7427 failed, choose \gui{Help > About Plugins}.
7429 \section2 Configuring Qt Designer Plugins on Mac OS
7431 On the Mac, a GUI application must be built and run from a bundle. A bundle is a
7432 directory structure that appears as a single entity when viewed in the Finder.
7433 A bundle for an application typcially contains the executable and all the resources
7436 Qt Creator uses its own set of Qt Libraries located in the bundle, and therefore,
7437 you need to configure the \QD plugins that you want to use with Qt Creator.
7438 Fore more information about how to deploy applications on Mac OS, see
7439 \l{http://doc.qt.nokia.com/4.7/deployment-mac.html}{Deploying an Application on Mac OS X}.
7441 The following example illustrates how to configure version 5.2.1 of the
7442 \l{http://qwt.sourceforge.net/}{Qwt - Qt Widgets for Technical Applications} library
7443 for use with Qt Creator:
7447 \o To check the paths used in the Qwt library, enter the following \c otool command:
7449 \snippet examples/doc_src_plugins.qdoc 0
7451 The output for Qwt 5.2.1 indicates that the plugin uses Qt core libraries (QtDesigner,
7452 QtScript, QtXml, QtGui and QtCore) and libqwt.5.dylib:
7454 \snippet examples/doc_src_plugins.qdoc 1
7457 \o You must copy the \QD plugin and the Qwt library files to the following locations:
7460 \o \c {libqwt_designer_plugin.dylib} to \c {QtCreator.app/Contents/MacOS/designer}
7461 \o \c {libqwt.*.dylib} to \c {QtCreator.app/Contents/Frameworks}
7464 Enter the following commands:
7466 \snippet examples/doc_src_plugins.qdoc 4
7468 \o Enter the following \c otool command to check the libraries that are used by the
7471 \snippet examples/doc_src_plugins.qdoc 2
7473 The command returns the following output:
7475 \snippet examples/doc_src_plugins.qdoc 3
7477 \o Enter the following \c install_name_tool command to fix the references of the
7480 \snippet examples/doc_src_plugins.qdoc 5
7485 \section1 Matching Build Keys
7487 The Qt Creator that is included in pre-built SDK packages on Windows is built with the
7488 Microsoft Visual Studio compiler, whereas the version of Qt shipped for building applications
7489 is configured and built to use the MinGW/g++ compiler. Plugins built by using this version of
7490 Qt cannot be loaded by Qt Creator because the build-keys do not match. The plugins can only be
7491 used in the standalone version of \QD. Choose \gui{Help > About Qt Creator} to check
7492 the Qt version Qt Creator was built with.
7494 To use \QD plugins that were built for the shipped Qt version, make sure that
7495 Qt Creator is built with the same compiler by either recompiling Qt Creator using MinGW or
7496 recompiling Qt with Microsoft Visual Studio, depending on which configuration you want to
7497 use for your applications.
7503 \contentspage index.html
7504 \previouspage creator-design-mode.html
7505 \page creator-usability.html
7506 \nextpage creator-using-qt-designer.html
7508 \title Optimizing Applications for Mobile Devices
7510 Before starting application development, analyze and define the requirements, scope, and
7511 functionality of the application to ensure efficient functionality and a smooth user
7512 experience. Design the application for a single purpose and analyze how it can best serve
7513 its users. Mobile devices have been designed for use when mobile. Keep the characteristics
7514 of mobile devices in mind when you create applications for them.
7516 The following guidelines help you design and develop usable applications for mobile devices
7517 with varying characteristics, such as screen size and support for input methods:
7523 Find out who will use the application, what they will use it for,
7524 and which mobile devices they have. Then design the application to fit a specific context
7527 \o Design for small screens
7529 The screen size of mobile devices is significantly smaller
7530 than that available on desktop devices. Carefully consider what is the most relevant
7531 content to present on the application UI, as it might not be reasonable to try and fit as
7532 much content into the screen as you might have in a desktop application.
7534 \o Design for multiple screen sizes
7536 Relate the position and size of each control to the
7537 dimensions of the display. This enables the same set of information to be presented on the
7538 screen in all resolutions; higher resolution devices just display finer graphics.
7540 \o Design for changing screen orientation
7542 Some devices support screen rotation. On these
7543 devices, applications can be displayed in portrait or landscape orientation. Account for
7544 orientation and dynamically adjust the display when the screen is rotated.
7546 \o Design intuitive ways of moving within applications
7548 Mobile devices lack a mouse and
7549 full-size keyboard, so users must use the touch screen or five way navigation pad to move within
7550 applications. In addition, many users control the devices with one hand. To create an optimized user
7551 experience, allow users to access information with one click; do not make them scroll and type.
7553 \o Design for limited input methods
7555 Applications collect information from users on the task
7556 at hand. In addition to touch screen input, some devices contain physical keys such
7557 as a five way navigation pad, a keypad, and a keyboard. Users enter information by using screen
7558 controls, such as lists, check boxes, radio buttons, and text fields.
7560 \o Keep response times short
7562 Latency can cause delays in user interaction. If users perceive
7563 an application as being slow, they are likely to get frustrated and stop using it.
7565 \o Save battery time
7567 Mobile devices are not constantly connected to a power source but run on
7568 battery power. Optimize power consumption to keep the total consumption at an acceptable
7569 level and to prevent users from running out of battery time.
7571 For more information and code examples on how to minimize power consumption, see
7572 \l{http://developer.symbian.org/wiki/index.php/Creating_Energy_Efficient_Apps_Using_Qt}{Creating Energy Efficient Apps Using Qt}.
7574 \o Consider network issues
7576 If users do not have a flat-rate data plan or WLAN support, mobile
7577 network connections cost them money. Also, when users move around with the devices, the networks
7578 available for connections constantly change.
7580 \o Remember the processing limits of the device
7582 The memory available on devices is limited
7583 and you should use it carefully. Although all mobile devices have common functionality,
7584 each device is individual in terms of both the resources available and extra features.
7585 Therefore, you must consider the constraints of all the target devices.
7589 For more information about user experience techniques for mobile devices, see the
7590 \l{http://library.forum.nokia.com/topic/Design_and_User_Experience_Library/GUID-A8DF3EB8-E97C-4DA0-95F6-F464ECC995BC_cover.html}{Design and User Experience Library}
7597 \contentspage index.html
7598 \previouspage creator-help.html
7599 \page creator-tips.html
7600 \nextpage creator-keyboard-shortcuts.html
7602 \title Tips and Tricks
7605 \section1 Switching Between Modes
7607 Qt Creator uses different modes for different purposes. You can quickly
7608 switch between these modes with the following keyboard shortcuts:
7610 \o \gui Welcome mode \key Ctrl+1
7611 \o \gui Edit mode \key Ctrl+2
7612 \o \gui Design mode \key Ctrl+3
7613 \o \gui Debug mode \key Ctrl+4
7614 \o \gui Projects mode \key Ctrl+5
7615 \o \gui Help mode \key Ctrl+6
7619 For more information about Qt Creator modes, see \l {Qt Creator Modes}.
7623 \section1 Moving Between Open Files
7625 To quickly move between currently open files, press
7628 To move forward in the location history, press \key {Alt+Right}
7629 (\key {Cmd+Opt+Right} on Mac OS). To move backward, press \key {Alt+Left}
7630 (\key {Cmd+Opt+Left} on Mac OS). For example, if you use the \gui Locator
7631 to jump to a symbol in the same file, you can jump back to your original
7632 location in that file by pressing \key {Alt+Left}.
7635 \section1 Moving To the Edit Mode
7637 To move to the \gui Edit mode and currently active file, press
7640 If you already are in the \gui Edit mode:
7642 \o The first press moves focus to the editor
7643 \o The second press closes secondary windows
7646 \section1 Using the Filter in Options Dialog
7648 To find specific settings you require in \gui{Tools} > \gui{Options...}
7649 use the filter located at the top left of the \gui Options dialog box.
7651 \section1 Opening Output Panes
7653 The output panes provide a list of errors and warnings encountered during
7654 a build, detailed output from the compiler, status of a program when it is
7655 executed and debug output, as well as search results.
7657 To open output panes, use the following shortcuts:
7661 \o \gui{Build Issues} pane Alt+1 (Cmd+1 on Mac OS X)
7663 \o \gui{Search Results} pane Alt+2 (Cmd+2 on Mac OS X)
7665 \o \gui{Application Output} pane Alt+3 (Cmd+3 on Mac OS X)
7667 \o \gui{Compile Output} pane Alt+4 (Cmd+4 on Mac OS X)
7671 For more information about output panes, see \l{Viewing Output}.
7674 \section1 Using Keyboard Shortcuts
7676 Qt Creator provides \l{Keyboard Shortcuts}{many useful keyboard shortcuts}.
7677 You can see the keyboard shortcut for a menu command in the menu
7678 or the tooltip for a button.
7680 To customize, import or export keyboard shortcuts, select \gui Tools >
7681 \gui Options... > \gui Environment > \gui Keyboard.
7684 \section1 Running Qt Creator From Command Line
7686 You can launch Qt Creator from command line using the name of an
7687 existing session or \c .pro file by giving the name as the command
7690 For example, running \tt{qtcreator somesession}, launches Qt Creator and
7691 loads session somesession.
7693 \note Make sure Qt Creator is included in the PATH environment variable.
7694 This can be done by typing the following in the command line:
7696 set PATH=c:\qtsdk\mingw\bin;c:\qtsdk\qt\bin;%PATH%
7700 \section1 Showing and Hiding the Sidebar
7702 To toggle the sidebar in the \gui Edit and \gui Debug modes, click
7703 \inlineimage qtcreator-togglebutton.png
7704 or press \key Alt+0 (\key Cmd+0 on Mac OS X).
7706 For more information on using the sidebar, see \l {Browsing Project Contents}.
7710 \section1 Moving To Symbols
7712 To move straight to a symbol used in a project, select the symbol in the
7713 \gui Editor toolbar drop-down menu. For more information on the editor toolbar,
7714 see \l {Using the Editor Toolbar}.
7716 To jump to a symbol in the current file, press \key {Ctrl+K} to open the
7717 \gui Locator, enter a period (.), and start typing the symbol name. Then
7718 select the symbol in the list. For more information on using the locator,
7719 see \l{Searching With the Locator}.
7721 Press \key Ctrl (\key Cmd on Mac OS) and click a symbol to move directly to
7722 the definition or the declaration of the symbol. You can also move the cursor
7723 on the symbol and press \key {F2}. For more information, see
7724 \l{Moving to Symbol Definition or Declaration}.
7728 \section1 Displaying Signals and Slots
7730 If an instance of a class is derived from QObject, and you would like to
7731 find all other objects connected to one of your object's slots using
7732 Qt's signals and slots mechanism, select \gui Tools > \gui Options...
7733 > \gui{Debugger} > \gui{Debugging Helper} > \gui{Use Debugging Helper}.
7735 In the \gui{Locals and Watchers} view, expand the object's entry and open
7736 the slot in the \e slots subitem. The objects connected to this slot are
7737 shown as children of the slot. This method works with signals too.
7739 For more information about the \gui{Locals and Watchers} view, see
7740 \l{Locals and Watchers}.
7743 \section1 Displaying Low Level Data
7745 If special debugging of Qt objects fails due to data corruption within the
7746 debugged objects, you can switch off the debugging helpers. When debugging
7747 helpers are switched off low-level structures become visible.
7749 To switch off the debugging helpers:
7751 \o Select \gui Tools > \gui Options... > \gui Debugger >
7752 \gui{Debugging Helper}.
7753 \o Uncheck the \gui{Use Debugging Helper} checkbox.
7756 \section1 Showing Tooltips in Debug Mode
7758 To inspect the value of variables from the editor, you can turn
7759 on tooltips. Tooltips are hidden by default for performance reasons.
7762 \o Select \gui Tools > \gui Options... > \gui Debugger > \gui General.
7763 \o Select the \gui {Use tooltips in main editor while debugging} check box.
7766 \section1 Locating Files
7768 The \gui Locator provides one of the easiest ways in Qt Creator to browse
7769 through projects, files, classes, methods, documentation and file systems.
7770 To quickly access files not directly mentioned in your project, you can
7771 create your own locator filters. That way you can locate files in a
7772 directory structure you have defined.
7774 To create locator filters, select \gui {Tools > Options... > Locator > Add}.
7776 For more information, see \l{Creating Locator Filters}.
7778 \section1 Adding a License Header Template for C++ Code
7780 A file containing a license header for C++ can be specified under
7781 \gui{Tools > Options... > C++ > License Template}. It may contain special
7782 placeholders enclosed in \c{%%} that are replaced when generating a
7787 \o \c %MONTH%: Month
7788 \o \c %DAY%: Day of the month
7790 \o \c %USER%: User name
7791 \o \c %FILENAME%: File name
7792 \o \c %CLASS%: Class name (if applicable)
7793 \o \c %$VARIABLE%: Contents of environment variable \c{VARIABLE}.
7800 \contentspage index.html
7801 \previouspage creator-tips.html
7802 \page creator-keyboard-shortcuts.html
7803 \nextpage creator-known-issues.html
7805 \title Keyboard Shortcuts
7807 Qt Creator provides various keyboard shortcuts to speed up your development
7811 \section1 Configuring Keyboard Shortcuts
7813 To customize a keyboard shortcut:
7815 \o Select \gui Tools > \gui Options... > \gui Environment >
7817 \o Select an action from the list.
7818 \o In \gui{Key Sequence} enter the shortcut key you want to associate
7819 with the selected action.
7822 Qt Creator allows you to use different keyboard shortcut mapping schemes:
7824 \o To import a keyboard shortcut mapping scheme, click \gui Import
7825 and select the kms file containing keyboard shortcut mapping scheme
7827 \o To export the current keyboard shortcut mapping scheme, click
7828 \gui Export and select the location where you want to save the
7833 \section1 Default Keyboard Shortcuts
7835 The following tables list the default keyboard shortcuts. They are
7836 categorized by actions.
7839 \section2 General Keyboard Shortcuts
7844 \o Keyboard shortcut
7846 \o Open file or project
7849 \o New file or project
7852 \o Open in external editor
7888 \o Next open document in history
7894 \o Previous open document in history
7897 \o Activate \gui Locator
7900 \o Switch to \gui Welcome mode
7903 \o Switch to \gui Edit mode
7906 \o Switch to \gui Design mode
7909 \o Switch to \gui Debug mode
7912 \o Switch to \gui Projects mode
7915 \o Switch to \gui Help mode
7918 \o Toggle \gui{Build Issues} pane
7919 \o Alt+1 (Cmd+1 on Mac OS X)
7921 \o Toggle \gui{Search Results} pane
7922 \o Alt+2 (Cmd+2 on Mac OS X)
7924 \o Toggle \gui{Application Output} pane
7925 \o Alt+3 (Cmd+3 on Mac OS X)
7927 \o Toggle \gui{Compile Output} pane
7928 \o Alt+4 (Cmd+4 on Mac OS X)
7930 \o Activate \gui Bookmarks pane
7933 \o Activate \gui{File System} pane
7936 \o Activate \gui{Open Documents} pane
7939 \o Activate \gui Projects pane
7945 \o Toggle the sidebar
7946 \o Alt+0 (Cmd+0 on Mac OS X)
7951 \o Move to \gui Edit mode
7955 \o The first press moves focus to the editor
7956 \o The second press closes secondary windows
7962 \section2 Editing Keyboard Shortcuts
7967 \o Keyboard shortcut
7969 \o Auto-indent selection
7978 \o Trigger a completion in this scope
7993 \o Decrease font size
7994 \o Ctrl+- (Ctrl+Roll mouse wheel down)
7996 \o Increase font size
7997 \o Ctrl++ (Ctrl+Roll mouse wheel up)
7999 \o Toggle Vim-style editing
8005 \o Split side by side
8008 \o Remove all splits
8011 \o Remove current split
8020 \o Go to block start
8023 \o Go to block end with selection
8026 \o Go to block start with selection
8029 \o Move current line down
8032 \o Move current line up
8035 \o Trigger a quick fix in this scope
8041 \o Select the current block
8043 The second press extends the selection to the parent block
8046 \o Enable text wrapping
8049 \o Toggle comment for selection
8052 \o Visualize whitespace
8061 \o Lay out in a grid
8064 \o Lay out horizontally
8067 \o Lay out vertically
8073 \o Edit signals and slots
8082 \o Go to next bookmark
8085 \o Go to previous bookmark
8097 \o Follow symbol under cursor
8099 Works with namespaces, classes, methods, variables, include
8100 statements and macros
8103 \o Rename symbol under cursor
8106 \o Switch between method declaration and definition
8109 \o Open type hierarchy
8112 \o Switch between header and source file
8116 \section2 Debugging Keyboard Shortcuts
8121 \o Keyboard shortcut
8126 \o Stop or interrupt debugger
8141 \o Toggle breakpoint
8146 \section2 Project Keyboard Shortcuts
8151 \o Keyboard shortcut
8167 \section2 Help Keyboard Shortcuts
8172 \o Keyboard shortcut
8174 \o View context-sensitive help
8177 \o Activate contents in \gui Help mode
8180 \o Add bookmark in \gui Help mode
8183 \o Activate index in \gui Help mode
8186 \o Reset font size in \gui Help mode
8189 \o Activate search in \gui Help mode
8194 \section2 Version Control Keyboard Shortcuts
8199 \o {5,1} Version control system
8230 \o Alt+G, Alt+Shift+D
8272 \o Alt+G, Alt+Shift+D
8309 \contentspage index.html
8310 \previouspage creator-known-issues.html
8311 \page creator-glossary.html
8312 \nextpage creator-acknowledgements.html
8324 Qt in PATH
8326 \target glossary-system-qt
8328 version for the \c qmake command found in your \c PATH
8329 environment variable.
8330 This is likely to be the system's Qt version.
8338 \target glossary-project-qt
8339 \o The version of Qt configured in the \gui{Projects} mode, \gui {Build
8340 Settings}, \gui {Qt Version} field. This is the Qt version that
8341 is actually used by a particular project.
8348 \target glossary-shadow-build
8349 \o Shadow building means building a project in a separate
8350 directory, the \e{build directory}. The build directory is
8351 different from the source directory. One of the benefits of
8352 shadow building is that it keeps your source directory clean.
8353 Shadow building is the best practice if you need many build
8354 configurations for a single set of source.
8361 \contentspage index.html
8362 \previouspage creator-keyboard-shortcuts.html
8363 \page creator-known-issues.html
8364 \nextpage creator-glossary.html
8368 This section lists known issues in Qt Creator version 2.1.0.
8369 The development team is aware of them, and therefore, you do not need to
8370 report them as bugs.
8372 For a list of fixed issues and added features, see the changelog file in
8373 the \c{qtcreator\dist} folder or the \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}.
8375 \section1 General Issues
8379 \o Qt Creator uses SQLite for storing some of its settings. SQLite is
8380 known to have problems with certain NFS servers (most notably the
8381 nfs-user-server 2.2beta), since they can lock up the application
8382 when it tries to lock the database. If your home directory is on an
8383 NFS share and you encounter this issue, one option would be to
8384 switch to the nfs-kernel-server, or create a symlink so that the
8385 settings are stored locally.
8389 \section1 Editing Issues
8393 \o Code completion does not support typedefs for nested classes.
8397 \section1 Projects Issues
8400 \o Paths or file names containing spaces or special characters
8401 (such as colons, dollar signs, and hash marks) may cause problems. This
8402 is because some of the tools Qt Creator uses in the background have
8403 restrictions on the characters allowed in file and directory names.
8404 To be on the safe side, we recommend creating projects and project
8405 items with names consisting of plain characters, numbers,
8406 underscores, and hyphens.
8408 \o There is no IDE support for adding or removing subprojects. Project
8409 hierarchies (SUBDIRS template) have to be created manually.
8411 \o Creating new CMake projects with Qt Creator is not supported.
8413 \o Building and packaging subprojects is not supported for Maemo devices.
8415 \o You must create projects for Maemo targets on the same partition where
8416 you installed \QSDK, Qt Creator, and MADDE.
8418 \o If error messages displayed in the \gui {Compile Output} pane contain
8419 paths where slashes are missing (for example, C:QtSDK),
8420 check your PATH variable. For more information, see
8421 \l{Troubleshooting MinGW Compilation Errors}.
8425 \section1 Debugging Issues
8429 \o Debugging large applications on Symbian devices using the Symbian S^3
8430 operating system might not work, because the TRK debug agent might not be able to
8431 access memory when the operating system starts paging. This causes breakpoint
8432 handling and symbol resolution to fail. For more information, see
8433 \l{http://bugreports.qt.nokia.com/browse/QTCREATORBUG-2158}{QTCREATORBUG-2158}.
8435 As a workaround, add the following section to the application .pro file to
8441 MMP_RULES *= UNPAGED
8445 \note You must completely clean and rebuild the project for the setting to
8448 \o When debugging executables created by the GNU Compiler version 4.5.0
8449 (all platforms), some data types will not be displayed in the
8450 \gui{Locals and Watchers} view due to missing debug information.
8452 \o Gdb on Windows may not work if the 'Embassy \reg Security Center' software
8453 by 'Wave \reg Systems' is installed and active (causing crashes in \c{vxvault.dll)}).
8455 \o Gdb may take long to load debugging symbols, especially from large
8456 libraries like \c libQtWebKit. Starting the debugging module can
8457 take up to several minutes without visible progress.
8459 \o Setting breakpoints in code that is compiled into the binary more
8460 than once does not work.
8462 \o Setting breakpoints in files that do not have unique absolute
8463 paths may fail. For example, remounting parts of a file system
8464 using the --bind mount option.
8472 \contentspage index.html
8473 \previouspage creator-glossary.html
8474 \page creator-acknowledgements.html
8476 \title Acknowledgements
8478 \section1 Third-party Components
8480 Qt Creator contains the following third-party components:
8483 \o \bold{Open Source front-end for C++ (license MIT)}, enhanced for use in
8485 Roberto Raggi <roberto.raggi@gmail.com>\br
8486 QtCreator/src/shared/cplusplus\br\br
8488 \o \bold{Botan, a C++ crypto library. Version 1.8.8}\br
8490 \o Copyright (C) 1999-2004 The Botan Project. All rights reserved.
8491 \o Copyright (C) 1999-2009 Jack Lloyd
8492 \o 2001 Peter J Jones
8493 \o 2004-2007 Justin Karneges
8494 \o 2005 Matthew Gregan
8495 \o 2005-2006 Matt Johnston
8496 \o 2006 Luca Piccarreta
8497 \o 2007 Yves Jerschow
8498 \o 2007-2008 FlexSecure GmbH
8499 \o 2007-2008 Technische Universitat Darmstadt
8500 \o 2007-2008 Falko Strenzke
8501 \o 2007-2008 Martin Doering
8502 \o 2007 Manuel Hartl
8503 \o 2007 Christoph Ludwig
8504 \o 2007 Patrick Sona
8506 All rights reserved.\br\br
8508 Redistribution and use in source and binary forms, with or without
8509 modification, are permitted provided that the following conditions are
8512 1. Redistributions of source code must retain the above copyright
8513 notice, this list of conditions, and the following disclaimer.\br\br
8515 2. Redistributions in binary form must reproduce the above copyright
8516 notice, this list of conditions, and the following disclaimer in the
8517 documentation and/or other materials provided with the distribution.\br
8520 THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND ANY EXPRESS OR
8521 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
8522 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE,
8523 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE
8524 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
8525 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
8526 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
8527 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
8528 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
8529 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
8530 IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\br\br
8531 The source code of Botan C++ crypto library can be found
8534 \o QtCreator/src/libs/3rdparty
8535 \o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
8539 \o \bold{NetSieben SSH Library is a Secure Shell client library for C++.
8542 \o \bold{Commercial License:} For organizations who do not want to
8543 release the source code for their applications as open source/
8544 free software; in other words they do not want to comply with the
8545 GNU General Public License (GPL) or Q Public License.
8546 \o \bold{Non Commercial / Open Source License:} NetSieben believes in
8547 contributing back to the open source community, thus it has released
8548 the SSH Library under Q Public License as it is defined by Trolltech
8549 AS of Norway. The Open Source License allows the user to use software
8550 under an open source / free software license, and distribute it
8551 freely. The software can be used at no charge with the condition
8552 that if the user uses the SSH Library in an application they wish to
8553 redistribute, then the complete source code for your application must
8554 be available and freely redistributable under reasonable conditions.
8555 For more information on the used QPL License see:
8556 QtCreator/src/libs/3rdparty/net7ssh/LICENSE.QPL
8558 The source code of NetSieben Secure Shell C++ Library can be found
8561 \o QtCreator/src/libs/3rdparty
8562 \o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
8569 \contentspage index.html
8570 \previouspage creator-version-control.html
8571 \page creator-task-lists.html
8572 \nextpage creator-cli.html
8574 \title Creating Task List Files
8576 You can load tasks from task lists to the \gui{Build Issues} pane. You can
8577 either create the task lists manually or create scripts to generate them from
8578 output of static code analysis tools, for example.
8580 For an example of a script that checks new lines of code and matches them
8581 against regular expressions to generate a task list, see \c{scripts\mytasks.pl}
8582 in the Qt Creator repository.
8584 \section1 Task List File Format
8586 The filename extension must be .tasks for Qt Creator to recognize a file as a
8589 Each line in a task list file is treated as a tab-separated list of strings with
8590 \c{\t}, \c{\n}, and \c{\\} used as escape characters. The strings are used to create
8591 one task per line. The lines can have one of the following formats:
8597 \o \c{type\tdescription}
8599 \o \c{file\ttype\tdescription}
8601 \o \c{file\tline\ttype\tdescription}
8605 The task type can have one of the following values:
8609 \o A string starting with \c err, which displays the error icon in the beginning of the line
8610 \o A string starting with \c warn, which displays the warning icon
8611 \o Any other value, which sets the task type to Unknown and does not
8616 The values are not case sensitive.
8618 Lines starting with the hash mark character (#) in the first column are ignored.
8624 \contentspage index.html
8625 \previouspage creator-task-lists.html
8626 \page creator-cli.html
8627 \nextpage creator-help.html
8629 \title Using Command Line Options
8631 You can start Qt Creator and specify some options from the command line.
8633 To specify command line options, enter the following command in the Qt Creator
8634 installation or build directory:
8636 \c {qtcreator [option] [filename]}
8640 \c {C:\qtcreator-2.1\bin>qtcreator -help}
8642 The following table summarizes the available options:
8651 \o Display help on command line options.
8655 \o Display Qt Creator version.
8659 \o Attempt to connect to an already running instance of Qt Creator.
8663 \o Do not load the specified plugin.
8667 \o Output plugin start up and shut down profiling data.
8670 \o -settingspath <path>
8671 \o Override the default path where user settings are stored.
8675 \o Core plugin: override the selected UI color.
8679 \o Debugger plugin: disable the Microsoft Console Debugger (CDB)
8680 engine. For more information, see \l{Debugging}.
8684 \o Debugger plugin: disable the GNU Symbolic Debugger (gdb) engine.
8688 \o Debugger plugin: disable the Qt Script debugger engine.
8691 \o -debug <PID-or-corefile>
8692 \o Debugger plugin: attach to process ID or core file.
8695 \o -wincrashevent <event-handle>
8696 \o Debugger plugin: Attach to crashed processes by using the specified
8700 \o -customwizard-verbose
8701 \o ProjectExplorer plugin: display additional information when loading
8702 custom wizards. For more information about custom wizards, see
8703 \l{Adding New Custom Wizards}
8707 \o ProjectExplorer plugin: load the last session when Qt Creator starts.
8708 Open the projects and files that were open when you last exited Qt Creator.
8709 For more information about managing sessions, see \l{Managing Sessions}.