qtcreator.qdoc 259 KB
Newer Older
1
2
3
4
5
6
// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

7

con's avatar
con committed
8
9
10
/*!
    \contentspage{index.html}{Qt Creator}
    \page index.html
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
11
    \nextpage creator-overview.html
con's avatar
con committed
12
13
14

    \title Qt Creator Manual

15
    \section1 Version 2.1.80
con's avatar
con committed
16

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
17
    Qt Creator provides a cross-platform, complete integrated development
18
19
    environment (IDE) for application developers to create applications for
    multiple desktop and mobile device platforms. It is available for Linux,
20
    Mac OS X and Windows operating systems. For more information, see
21
    \l{Operating Systems and Supported Platforms}.
con's avatar
con committed
22

23
    \note Please report bugs and suggestions to the
con's avatar
con committed
24
    \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}.
25
26
27
    You can also join the Qt Creator mailing list. To subscribe,
    send a message with the word \e subscribe to
    \l{mailto:qt-creator-request@trolltech.com}
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
28
    {qt-creator-request@trolltech.com}. For more information about Qt mailing
29
    lists, visit \l{http://lists.trolltech.com}{http://lists.trolltech.com}.
con's avatar
con committed
30

31
32
    \raw HTML
    <img border="0" style="float:right;" src="images/qtcreator-screenshots.png" />
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
33
    \endraw
34

con's avatar
con committed
35
    \list
Leena Miettinen's avatar
Leena Miettinen committed
36
       \o \l{Introducing Qt Creator}
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
37
       \o \l{Operating Systems and Supported Platforms}
38
       \o \l{Qt Creator User Interface}
39
40
       \o \l{Getting Started}
           \list
41
               \o \l{Building and Running an Example Application}
42
               \o \l{Creating a Qt C++ Application}
43
               \o \l{Creating a Mobile Application with Nokia Qt SDK}
44
               \o \l{Creating a Qt Quick Application}
45
           \endlist
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
46
47
48
49
50
51
       \o \l{Managing Projects}
            \list
                \o \l{Creating a Project}
                \o \l{Setting Up a qmake Project}
                \o \l{Setting Up a CMake Project}
                \o \l{Setting Up a Generic Project}
Leena Miettinen's avatar
Leena Miettinen committed
52
53
                \o \l{Setting Up Development Environment for Maemo}
                \o \l{Setting Up Development Environment for Symbian}
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
54
55
                \o \l{Managing Sessions}
            \endlist
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
       \o \l{Using the Editor}
            \list
                \o \l{Finding and Replacing}
                \o \l{Refactoring}
                \o \l{Searching With the Locator}
                \o \l{Pasting and Fetching Code Snippets}
                \o \l{Configuring the Editor}
                \o \l{Using FakeVim Mode}
                \o \l{Using an External Editor}
            \endlist
       \o \l{Developing Application UI}
       \list
           \o \l{Optimizing Applications for Mobile Devices}
           \o \l{Adding Qt Designer Plugins}
           \if defined(qtquick)
           \o \l{Developing Qt Quick Applications}
                \list
                    \o \l {Creating Qt Quick Projects}
                    \o \l {Creating Components}
                    \o \l {Creating Screens}
                    \o \l {Animating Screens}
                    \o \l {Adding User Interaction Methods}
                    \o \l {Implementing Application Logic}
                \endlist
           \endif
       \endlist
82
83
84
85
86
87
88
89
       \o \l{Building and Running Applications}
            \list
                \o \l{Building for Multiple Targets}
                \o \l{Specifying Build Settings}
                \o \l{Specifying Run Settings}
                \o \l{Specifying Editor Settings}
                \o \l{Specifying Dependencies}
            \endlist
90
       \o \l{Developing Qt Quick Applications}
Leena Miettinen's avatar
Leena Miettinen committed
91
       \o \l{Optimizing Applications for Mobile Devices}
92
       \o \l{Using the Maemo Emulator}
93

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
94
       \o \l{Debugging}
95
96
            \list
            \o \l {Debugging Qt Applications}
97
98
99
100
101
102
            \list
                \o \l{Debugging the Example Application}
                \o \l{Interacting with the Debugger}
                \o \l{Setting Up Debugger}
                \o \l{Using Debugging Helpers}
            \endlist
103
104
105
106
107
            \o \l{Debugging Qt Quick Applications}
                \list
                    \o \l{Using the QML Inspector}
                \endlist
            \endlist
108
       \o \l{Using the Maemo Emulator}
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
109
       \o \l{Using Version Control Systems}
110
111

       \o \l{Getting Help}
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
112
113
114
115
116
       \o \l{Tips and Tricks}
       \o \l{Keyboard Shortcuts}
       \o \l{Known Issues}
       \o \l{Glossary}
       \o \l{Acknowledgements}
con's avatar
con committed
117
118
119
    \endlist
*/

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
120

con's avatar
con committed
121
122
/*!
    \contentspage index.html
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
123
    \previouspage index.html
Leena Miettinen's avatar
Leena Miettinen committed
124
125
126
127
128
    \page creator-overview.html
    \nextpage creator-os-supported-platforms.html

  \title Introducing Qt Creator

Leena Miettinen's avatar
Leena Miettinen committed
129
130
131
    Qt Creator is an integrated development environment (IDE) that provides you with
    tools to design and develop complex applications for multiple desktop and mobile
    platforms.
132

133
    \image qtcreator-overview.png "Qt Creator overview"
134

Leena Miettinen's avatar
Leena Miettinen committed
135
    \section1 Projects
136

Leena Miettinen's avatar
Leena Miettinen committed
137
138
139
140
141
142
143
    One of the major advantages of Qt Creator is that it allows a team of developers
    to share a project across different development platforms with a common tool
    for development and debugging.

    But why do you need projects? To be able to build and run applications,
    Qt Creator needs the same information as a compiler would need. This information
    is specified in the project build and run settings.
144

145
    Creating a project allows you to:
146

147
        \list
148

149
            \o Group files together
150

151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
            \o Add custom build steps

            \o Include forms and resource files

            \o Specify settings for running applications

        \endlist

    You can either create a project from scratch or import an existing
    project. Qt Creator generates all the necessary files, depending on the type of
    project you create. For example, if you choose to create a graphical user
    interface (GUI) application, Qt Creator generates an empty .ui file
    that you can modify with the integrated \QD.

    Qt Creator is integrated with cross-platform systems for build automation: qmake and
    CMake. In addition, you can import generic projects that do not use qmake or CMake,
    and specify that Qt Creator ignores your build system.
168

Leena Miettinen's avatar
Leena Miettinen committed
169
170
171
172
173
174
    \section1 Editors

    Qt Creator comes with a code editor and an integrated \QD for designing and building
    graphical user interfaces (GUIs) from Qt widgets.

    \section2 Code Editor
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192

    As an IDE, Qt Creator differs from a text editor in that it knows how to build and run
    applications. It understands the C++ and QML languages as code, not just as plain text. This allows
    it to:

    \list

        \o Enable you to write well formatted code

        \o Anticipate what you are going to write and complete the code

        \o Display inline error and warning messages

        \o Enable you to semantically navigate to classes, functions, and symbols

        \o Provide you with context-sensitive help on classes, functions, and symbols

        \o Rename symbols in an intelligent way, so that other symbols with the same name
con's avatar
con committed
193
           that belong to other scopes are not renamed
Leena Miettinen's avatar
Leena Miettinen committed
194

195
        \o Show you the locations in code where a function is declared or called
Leena Miettinen's avatar
Leena Miettinen committed
196

197
    \endlist
Leena Miettinen's avatar
Leena Miettinen committed
198

Leena Miettinen's avatar
Leena Miettinen committed
199
    \section2 UI Designer
Leena Miettinen's avatar
Leena Miettinen committed
200

201
202
203
204
205
206
207
    Qt Creator provides two integrated visual editors, \QD and \QMLD.

    \QD is a tool for designing and building graphical user interfaces (GUIs) from
    Qt widgets. You can compose and customize your widgets or dialogs and test
    them using different styles and resolutions.

    Widgets and forms created with \QD are integrated seamlessly with programmed code,
Leena Miettinen's avatar
Leena Miettinen committed
208
209
210
211
    using the Qt signals and slots mechanism, that lets you easily assign behavior to
    graphical elements. All properties set in \QD can be changed dynamically within the code.
    Furthermore, features like widget promotion and custom plugins allow you to use your
    own widgets with \QD.
212

213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
    UIs that use widgets are clearly structured and enforce a platform look and feel,
    which makes them useful for traditional applications. However, they are static, and
    do not fully make use of the large high-resolution screens, touch input, and significant
    graphics power that are becoming common in portable consumer devices, such as mobile
    phones, media players, set-top boxes, and netbooks.

    \QMLD allows you to easily develop animations by using a declarative programming
    language called \l {http://doc.qt.nokia.com/4.7-snapshot/declarativeui.html}{QML}.
    In QML, a user interface is specified as a tree of objects with properties.

    You use a visual editor to create items, screens, and applications, as well as define changes
    in their state, transitions from one state to another, and user actions that change the
    states. \QMLD generates the necessary code for you.

    You can use Qt or JavaScript to implement the application logic.

con's avatar
con committed
229
      \section1 Languages
230

Leena Miettinen's avatar
Leena Miettinen committed
231
232
233
    You can use the code editor to write code in Qt C++ or in the
    \l {http://doc.qt.nokia.com/4.7-snapshot/declarativeui.html}{QML} declarative
    programming language.
234

Leena Miettinen's avatar
Leena Miettinen committed
235
    \section2 QML
236

Leena Miettinen's avatar
Leena Miettinen committed
237
238
239
240
    You can use QML to build highly dynamic, custom user interfaces from a rich set
    of QML elements. Qt Quick helps programmers and designers collaborate to build the
    fluid user interfaces that are becoming common in portable consumer devices, such as
    mobile phones, media players, set-top boxes and netbooks.
241

Leena Miettinen's avatar
Leena Miettinen committed
242
243
244
245
    QML is an extension to JavaScript, that provides a mechanism to declaratively build
    an object tree of QML elements. QML improves the integration between JavaScript and
    Qt's existing QObject based type system, adds support for automatic property bindings
    and provides network transparency at the language level.
Leena Miettinen's avatar
Leena Miettinen committed
246

Leena Miettinen's avatar
Leena Miettinen committed
247
    \section1 Targets
Leena Miettinen's avatar
Leena Miettinen committed
248

249
    Qt Creator provides support for building and running Qt applications for
Leena Miettinen's avatar
Leena Miettinen committed
250
251
    desktop environment (Windows, Linux, and Mac OS) and mobile devices (Symbian, Maemo,
    and MeeGo). Build settings allow you to quickly switch between build targets.
252

253
254
255
256
    When you build an application for a mobile device target with a device
    connected to the development PC, Qt Creator generates an installation package,
    installs in on the device, and executes it.

Leena Miettinen's avatar
Leena Miettinen committed
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
    You can publish the installation packages on the \l{https://publish.ovi.com/info/}{Ovi Store}.
    For Symbian devices, the packages must be signed.

    \section1 Tools

    Qt Creator is integrated with a set of helpful tools, such as version control
    systems and Qt Simulator.

    \section2 Version Control Systems

    The recommended way to build a project is to use a version control system.
    Qt Creator uses the version control system's command line clients to access
    your repositories. The following version control systems are supported:

    \list

        \o Git

        \o Subversion

        \o Perforce

        \o CVS

        \o Mercurial

    \endlist

    The functions available to you in Qt Creator depend on the version control
    system. Basic functions are available for all the supported systems. They include
    comparing files with the latest versions stored in the repository and displaying the
    differences, viewing versioning history and change details, annotating files,
    and committing and reverting changes.

    \section2 Qt Simulator

    You can use the Qt Simulator to test Qt applications that are intended
    for mobile devices in an environment similar to that of the device. You
    can change the information that the device has about its configuration
    and environment.
Leena Miettinen's avatar
Leena Miettinen committed
297

Leena Miettinen's avatar
Leena Miettinen committed
298
299
    The Qt Simulator is installed as part of the Nokia Qt SDK. After it is
    installed, you can select it as a build target in Qt Creator.
Leena Miettinen's avatar
Leena Miettinen committed
300

Leena Miettinen's avatar
Leena Miettinen committed
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
    \section1 Debuggers

    Qt Creator does not include a debugger. It provides a debugger plugin that acts
    as an interface between the Qt Creator core and external native debuggers:

    \list

        \o GNU Symbolic Debugger (gdb)

        \o Microsoft Console Debugger (CDB)

        \o internal Java Script debugger

    \endlist

    Qt Creator displays the raw information provided by the native debuggers
    in a clear and concise manner with the goal to simplify the debugging process
    as much as possible without losing the power of the native debuggers.
    You can use the native debuggers to debug the C++ language.

    You can connect mobile devices to your development PC and debug processes
    running on the devices.
323

Leena Miettinen's avatar
Leena Miettinen committed
324
325
326
327
328
*/

/*!
    \contentspage index.html
    \previouspage creator-overview.html
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
329
330
331
332
333
334
335
336
337
338
339
340
    \page creator-os-supported-platforms.html
    \nextpage creator-quick-tour.html

    \title Operating Systems and Supported Platforms

    \section1 Operating Systems

    Qt Creator is available in binary packages for the following operating
    systems:
    \list
        \o Windows XP Service Pack 2
        \o Windows Vista
341
        \o (K)Ubuntu Linux 7.04 (32-bit and 64-bit) or later, with the following:
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
           \list
               \o g++
               \o make
               \o libglib2.0-dev
               \o libSM-dev
               \o libxrender-dev
               \o libfontconfig1-dev
               \o libxext-dev
               \o libfreetype6-dev
               \o libx11-dev
               \o libxcursor-dev
               \o libxfixes-dev
               \o libxft-dev
               \o libxi-dev
               \o libxrandr-dev
357
               \o If you are using QtOpenGL, libgl-dev and libglu-dev
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
358
           \endlist
359
        \o Mac OS 10.5 or later with the following:
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
360
361
362
363
364
365
           \list
               \o Xcode tools for your Mac OS X version available from your Mac
                  OS X installation DVDs or at \l http://developer.apple.com.
           \endlist
    \endlist

366
367
368
         \omit  ## Are the Xcode tools still needed separately? \endomit

    \section1 Build Environment
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
369
370
371

    To build Qt Creator itself from the source, you need:
    \list
372
        \o Qt 4.7 or later
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
373
374
375
        \o On Windows, MinGW 4.4 or Microsoft Visual Studio 2008
    \endlist

376
377
378
379
380
381
382
383
384
385
386
387
388
389
    \section1 Supported Mobile Device Platforms
    You can develop applications for the following mobile device
    platforms:

    \list

    \o Symbian

    \o Maemo and Maemo Application Development and Debugging Environment (MADDE)

    \endlist

    The following table summarizes operating system support for building
    applications for mobile device platforms.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
390
391
392

    \table
        \header
393
394
            \o {1,3} Operating system
            \o {3,1} Platform
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
395
396
397
        \header
            \o Desktop
            \o Symbian
398
            \o Maemo
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
399
400
401
402
        \row
            \o Windows
            \o Yes
            \o Yes
403
            \o Yes
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
404
405
406
407
        \row
            \o Linux
            \o Yes
            \o No
408
            \o Yes
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
409
410
411
412
        \row
            \o Mac OS X
            \o Yes
            \o No
Leena Miettinen's avatar
Leena Miettinen committed
413
            \o No
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
414
415
416
417
418
419
420
    \endtable
*/


/*!
    \contentspage index.html
    \previouspage creator-os-supported-platforms.html
con's avatar
con committed
421
    \page creator-quick-tour.html
422
    \nextpage creator-getting-started.html
con's avatar
con committed
423

424
    \title Qt Creator User Interface
con's avatar
con committed
425
426
427

    \image qtcreator-breakdown.png

428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
    When you start Qt Creator, it opens to the \gui Welcome mode, where you can:

    \list

        \o Open tutorials and example projects

        \o View tips and hints on using Qt Creator

        \o Create and open projects

        \o Send feedback to the development team

        \o Open recent sessions and projects

        \o Read news from the Qt labs

        \o Ask for support

    \endlist

    You can use the mode selector to change to another Qt Creator mode.

450
451
452
453
454
    Qt Creator has been localized into several languages. If the system language
    is one of the supported languages, it is automatically selected. To change
    the language, select \gui {Tools > Options > Environment} and select a language
    in the \gui Language field. The change takes effect after you restart Qt Creator.

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
455
    \section1 Qt Creator Modes
con's avatar
con committed
456

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
457
    The mode selector allows you to quickly switch between tasks such as
458
459
    editing project and source files, designing application UIs,
    configuring how projects are built and
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
460
461
    executed, and debugging your applications. To change modes, click the
    icons, or use the \l{keyboard-shortcuts}{corresponding keyboard shortcut}.
con's avatar
con committed
462

463
464
    You can use Qt Creator in the following modes:

con's avatar
con committed
465
    \list
466
        \o \gui{\l{Using the Editor}{Edit}} mode for editing project and source files.
467
        \o \gui{\l{Developing Application UI}{Design}} mode for designing and developing
468
469
           application user interfaces. This mode is available for UI files (.ui or
           .qml).
470
471
472
        \o \gui{\l{Debugging}{Debug}} mode for inspecting the state of your program while
           debugging.
        \o \gui{\l{Managing Projects}{Projects}} mode for configuring project building and
473
           execution. This mode is available when a project is open.
474
        \o \gui{\l{Getting Help}{Help}} mode for viewing Qt documentation.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
475
476
    \endlist

477
478
    Certain actions in Qt Creator trigger a mode change. Clicking on
    \gui {Debug} > \gui {Start debugging} > \gui {Start debugging}
479
    automatically switches to \gui {Debug} mode.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
480
481


482
    \section1 Browsing Project Contents
con's avatar
con committed
483

484
    The sidebar is available in the \gui Edit and \gui Debug modes.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
485
486
    Use the sidebar to browse files, projects and bookmarks.
    \image qtcreator-sidebar.png
con's avatar
con committed
487

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
488
489
490
491
492
493
494
495
496
    You can select the content of the sidebar in the sidebar menu:
    \list
        \o \gui Projects shows a list of projects open in the current
           session.
        \o \gui{File System} shows the content of the currently selected
           directory.
        \o \gui Bookmarks shows all bookmarks for the current session.
        \o \gui{Open Documents} shows currently open files.
    \endlist
con's avatar
con committed
497

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
498
499
500
501
502
    You can change the view of the sidebar in the following ways:
    \list
        \o To toggle the sidebar, click \inlineimage qtcreator-togglebutton.png
           or press \key Alt+0 (\key Cmd+0 on Mac OS X).
        \o To split the sidebar, click \inlineimage qtcreator-splitbar.png
503
           . Select new content to view in the split view.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
504
505
506
507
        \o To close a sidebar view, click
           \inlineimage qtcreator-closesidebar.png
           .
    \endlist
con's avatar
con committed
508
509


510
    \section2 Viewing Project Files
con's avatar
con committed
511

512
513
514
    The sidebar displays projects in a project tree. The project tree contains
    a list of all projects open in the current session. The files for each
    project are grouped according to their file type.
con's avatar
con committed
515

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
516
517
    You can use the project tree in the following ways:
    \list
518
519
        \o To bring up a context menu containing the actions most commonly
           needed right-click an item in the project tree.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
520
           For example, through the menu of the project root directory you can,
521
           among other actions, build, re-build, clean and run the project.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
522
523
        \o To list all files in a project, click
           \inlineimage qtcreator-filter.png
524
525
526
527
           and select \gui{Simplify tree}.
        \o To hide source files which are automatically generated by the build
           system, during a build, click \inlineimage qtcreator-filter.png
           and select \gui{Hide generated files}.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
528
529
530
531
532
533
        \o To toggle the synchronization of your project tree with the file
           opened in the editor, click
           \inlineimage qtcreator-synchronizefocus.png
           .
        \o To see the absolute path of a file, move the mouse pointer over the
           file name.
con's avatar
con committed
534
535
536
    \endlist


537
    \section1 Viewing Output
con's avatar
con committed
538

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
539
    The task pane in Qt Creator can display one of the following panes:
540
541
542
543
544
    \list
       \o  \gui{Build Issues}
       \o  \gui{Search Results}
       \o  \gui{Application Output}
       \o  \gui{Compile Output}
545
546
       \o  \gui{General Messages}
       \o  \gui{Version Control}
547
548
549
    \endlist

    Output panes are available in all \l{Qt Creator modes}{modes}.
550
551
552
    Click the name of an output pane to open the pane. To maximize
    an open output pane, click the \gui {Maximize Output Pane} button
    or press \key {Alt+9}.
con's avatar
con committed
553

554
555
556
    To open the \gui{General Messages} and \gui{Version Control}
    panes, select \gui {Window > Output Panes}.

557

558
    \section2 Build Issues
con's avatar
con committed
559

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
560
    The \gui{Build Issues} pane provides a list of errors and warnings
561
    encountered during a build. The pane filters out irrelevant output from
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
562
    the build tools and presents the issues in an organized way.
con's avatar
con committed
563

564
565
566
567
    Right-clicking on a line brings up a context menu with options to copy
    the contents and to show a version control annotation view of the
    line that causes the error message.

568
    \image qtcreator-build-issues.png
con's avatar
con committed
569

570

con's avatar
con committed
571
572
    \section2 Search Results

573
574
575
576
577
    The \gui{Search Results} pane displays the results for global searches,
    for example, searching within a current document, files on disk, or all
    projects.

    The figure below shows an example search result for all
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
578
    occurrences of \c textfinder within the \c "/TextFinder" directory.
con's avatar
con committed
579
580
581

    \image qtcreator-search-pane.png

582

con's avatar
con committed
583
584
    \section2 Application Output

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
585
    The \gui{Application Output} pane displays the status of a program when
586
587
588
    it is executed, and the debug output.

    The figure below shows an example output from qDebug().
con's avatar
con committed
589
590
591

    \image qtcreator-application-output.png

592

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
593
    \section2 Compile Output
con's avatar
con committed
594

595
596
597
    The \gui{Compile Output} pane provides all output from the compiler.
    The \gui{Compile Output} is a more detailed version of information
    displayed in the \gui{Build Issues} pane.
con's avatar
con committed
598
599
600

    \image qtcreator-compile-pane.png

601
602
603
604
605
606
607
608
609
610
    \section1 Navigating with Keyboard

    Qt Creator caters not only to developers who are used to using the mouse,
    but also to developers who are more comfortable with the keyboard. A wide
    range of \l{keyboard-shortcuts}{keyboard} and
    \l{Searching With the Locator}{navigation} shortcuts are available to help
    speed up the process of developing your application.

*/

611

612
613
614
615
616
/*!
    \contentspage index.html
    \previouspage creator-version-control.html
    \page creator-help.html
    \nextpage creator-tips.html
617

618
    \title Getting Help
con's avatar
con committed
619

620
    Qt Creator comes fully integrated with Qt documentation and
621
    examples using the Qt Help plugin.
622
    \list
623
624
625
626
627
        \o To view documentation, switch to \gui Help mode.
        \o To obtain context sensitive help, move the text cursor to a Qt class
           or function and press \key F1. The documentation is displayed in a
           pane next to the code editor, or, if there is not enough vertical
           space, in the fullscreen \gui Help mode.
con's avatar
con committed
628

629
           \image qtcreator-context-sensitive-help.png
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
630

631
632
        \o To select and configure how the documentation is displayed in the
           \gui Help mode, select \gui Tools > \gui Options... > \gui Help.
633
634
    \endlist

635
    \section1 Adding External Documentation
con's avatar
con committed
636

637
638
    You can display external documentation in the \gui Help mode.
    To augment or replace the documentation that ships with Qt Creator and Qt:
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
639
640
641
642
643
    \list 1
        \o Create a .qch file from your documentation.

           For information on how to prepare your documentation and create a
           .qch file, see
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
644
           \l{http://doc.qt.nokia.com/4.6/qthelp-framework.html}{The Qt Help Framework}.
645
        \o To add the .qch file to Qt Creator, select \gui Tools >
646
           \gui Options... > \gui Help > \gui Documentation > \gui Add.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
647
    \endlist
con's avatar
con committed
648

649
    \section1 Using Documentation Filters
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688

    You can filter the documents displayed in the \gui Help mode to find
    relevant information faster. Select from a list of filters in the
    \gui {Filtered by} field. The contents of the \gui Index and \gui Contents
    pane in the sidebar change accordingly.

    \image qtcreator-help-filters.png "Help filters"

    You can modify the filters to include external documentation, for example,
    or you can define your own filters. To construct filters, you can use the
    filter attributes that are specified in the documentation. Each document
    contains at least one filter attribute. If several documents contain the
    same filter attribute, such as \c tools, you can use that attribute to
    include all those documents.

    To add filters:

    \list 1

        \o Select \gui {Tools > Options... > Help > Filters > Add}.

        \o Enter a name for the filter and press \gui {OK}.

        \o In \gui Attributes, select the documents that you want to include
        in the filter.

        \image qtcreator-help-filter-attributes.png "Help filter attributes"

        \o Click \gui OK.

        \o In the \gui Help mode, select the filter in the \gui {Filtered by}
        field to see the filtered documentation in the sidebar.

    \endlist

    To modify filters, select a filter in \gui Filters, select the attributes,
    and then click \gui Apply.

    To remove filters, select them in \gui Filters, and click \gui Remove.
con's avatar
con committed
689

690
*/
691

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
692

693
694
695
696
697
/*!
    \contentspage index.html
    \previouspage creator-editor-external.html
    \page creator-design-mode.html
    \nextpage creator-usability.html
698

699
    \title Developing Application UI
700

701
702
703
    You can use the integrated \QD to design and build graphical user interfaces (GUIs) from
    Qt widgets. You can compose and customize your widgets or dialogs and test
    them using different styles and resolutions.
704

705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
    Widgets and forms created with \QD are integrated seamlessly with programmed code,
    using the Qt signals and slots mechanism, that lets you easily assign behavior to
    graphical elements. All properties set in \QD can be changed dynamically within the code.
    Furthermore, features like widget promotion and custom plugins allow you to use your
    own widgets with \QD.

    UIs that use widgets are clearly structured and enforce a platform look and feel,
    which makes them useful for traditional applications. However, they are static, and
    do not fully make use of the large high-resolution screens, touch input, and significant
    graphics power that are becoming common in portable consumer devices, such as mobile
    phones, media players, set-top boxes, and netbooks.

    You can easily develop animations by using a declarative programming
    language called \l {http://doc.qt.nokia.com/4.7-snapshot/declarativeui.html}{QML}.
    In QML, a user interface is specified as a tree of objects with properties.
    You can edit QML code in the code editor. You
    can use Qt or JavaScript to implement the application logic.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
722

723
    The integration includes project management and code completion.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
724

725
    \section1 Using Qt Designer
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
726

727
    Qt Creator automatically opens all .ui files in \QD.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
728
729
730

    \image qtcreator-formedit.png

731
    To change the layout of \QD user interface elements:
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
732
    \list 1
733
        \o Select \gui Tools > \gui{Form Editor} > \gui Views >
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
734
735
736
737
738
739
740
           \gui Locked.

           When this option is unchecked, you can change the layout.
        \o Click the header of an element and drag the element to a new
           position.
    \endlist

741
    To change \QD properties, select \gui Tools > \gui Options... >
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
    \gui Designer.
    \list
        \o Set the class properties and code generation preferences in \gui
           {Class Generation}.
        \o Set an additional folder for saving templates in \gui{Template
           Paths}.
        \o Set the grid settings and preview preferences in \gui Forms. To
           preview your form with skins, enable \gui{Print/Preview
           Configuration} and select your skin. Otherwise default preview
           settings are used.

           To preview the settings, select \gui Tools > \gui{Form Editor} >
           \gui Preview, or press \key Ctrl+Alt+R.
        \o To specify embedded device profiles, such as style, font, and screen
           resolution, select \gui{Embedded Design}.
    \endlist

759
    For more information on \QD, see
760
    \l{http://doc.qt.nokia.com/4.7-snapshot/designer-manual.html}{Qt Designer Manual}.
761

762
    \section1 Using Qt Quick Designer
763

764
    You can edit .qml files in the visual \QMLD editor or in the
765
766
    code editor.

767
    In \gui Projects, double-click a .qml file to open it in the code
768
769
770
    editor. Then select the \gui {Design} mode to edit the file in the
    visual editor.

771
772
773
774
775
776
777
778
    \note The visual \QMLD editor is provided as an experimental plugin that you must
    enable to be able to edit QML files in the \gui Design mode. Enabling the
    visual editor can negatively affect the overall stability of Qt Creator.

    To enable or disable the \QMLD visual editor, select
    \gui {Help > About Plugins... > Qt Quick > QmlDesigner}. You must restart Qt Creator
    to enable or disable the visual editor.

779
780
781
782
783
784
    \image qmldesigner-visual-editor.png "Visual editor"

    Use the visual editor panes to manage your project:

    \list

785
786
    \o \gui {Navigator} pane displays the items in the scene. You can
    show and hide items to focus on specific parts of the application.
787
788
789
790
791
792

    \o \gui {Library} pane displays lists of predefined \gui {Items} and
    imported \gui {Resources} that you can use to design applications. The
    images and other files that you copy to the project folder appear in the
    \gui {Resources} pane.

793
    \o \gui {Properties} pane displays the properties of the selected component.
794
795
     You can also change the properties in the code editor.

796
    \o \gui {State} pane displays the different states of the component. To add
797
798
799
800
801
802
    states, click the empty slot. Then modify the new state in the editor.
    In the code editor, you can see the changes recorded as changes to
    the base state.

    \endlist

con's avatar
con committed
803
804
*/

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
805

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
806
807
/*!
    \contentspage index.html
808
    \previouspage creator-project-managing-sessions.html
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
809
810
    \page creator-editor-using.html
    \nextpage creator-editor-finding.html
811

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
812
    \title Using the Editor
813

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
814
    Qt Creator's code editor is designed to aid you in creating, editing and
815
816
817
    navigating code.  Qt Creator's code editor is fully equipped with syntax
    checking, code completion, context sensitive help and in-line error
    indicators while you are typing.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
818

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
819
820
    \section1 Using the Editor Toolbar

821
822
823
    The editor toolbar is located at the top of the editor view. The editor
    toolbar is context sensitive and shows items relevant to the file currently
    open in the editor.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
824
825
826
827
828

    \image qtcreator-editortoolbar-symbols.png

    Use the toolbar to navigate between open files and symbols in use:
    \list
829
        \o To browse forward or backward through your location history, click
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
830
831
832
833
834
835
836
837
838
           \inlineimage qtcreator-back.png
           and \inlineimage qtcreator-forward.png
           .
        \o To go to any open file, select it from the \gui{Open files}
           drop-down menu.
        \o To jump to any symbol used in the current file, select it from the
           \gui Symbols drop-down menu.
    \endlist

839
840
    When you create or edit forms in a \c{.ui} file, the toolbar contains
    Qt Designer specific tools.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
841
842
843
844
845
846
847
848
849


    \section1 Splitting the Editor View

    Split the editor view when you want to work on and view multiple files on
    the same screen.

    \image qtcreator-spliteditorview.png

850
    You can split the editor view in the following ways:
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
851
852
853
854
855
856
857
858
859
860
861
862
863
864
    \list
        \o To split the editor view into a top and bottom view, select
           \gui Window > \gui Split or press \key{Ctrl+E, 2}.

           Split command creates views below the currently active editor view.
        \o To split the editor view into adjacent views, select
           \gui Window > \gui{Split Side by Side} or press
           \key{Ctrl+E, 3}.

           Side by side split command creates views to the right of the
           currently active editor view.
    \endlist

    To move between split views, select \gui Window >
865
    \gui{Go to Next Split} or press \key{Ctrl+E, O}.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880

    To remove a split view, place the cursor within the view you want to
    remove and select \gui Window > \gui{Remove Current Split} or press
    \key{Ctrl+E, 0}. To remove all but the currently selected split view,
    select \gui Window > \gui{Remove All Splits} or press \key{Ctrl+E, 1}.


    \section1 Highlighting and Folding Blocks

    Use block highlighting to visually separate parts of the code that belong
    together. For example, when you place the cursor within the braces,
    the code enclosed in braces is highlighted.

    \image qtcreator-blockhighlighting.png

881
    To enable block highlighting, select \gui Tools > \gui{Options...} >
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
882
883
884
885
886
887
888
    \gui{Text Editor} > \gui Display > \gui{Highlight blocks}.

    Use the folding markers to collapse and expand blocks of code within
    braces. Click the folding marker to collapse or expand a block. In the
    figure above, the folding markers are located between the line number and
    the text pane.

889
890
891
    To show the folding markers, select \gui Tools > \gui{Options...} >
    \gui{Text Editor} > \gui Display > \gui{Display folding markers}. This
    option is enabled by default.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
892

893
894
895
896
897
    When the cursor is on a brace, the matching brace is animated
    by default. To turn off the animation and just highlight the block and
    the braces, select \gui {Tools > Options... > Text Editor > Display} and
    deselect \gui {Animate matching parentheses}.

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
898

899
    \section1 Checking Code Syntax
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
900

901
902
903
    As you write code Qt Creator checks code syntax. When Qt Creator spots a
    syntax error in your code it underlines it and shows error details when you
    move the mouse pointer over the error.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
904
905
906
    \list
        \o Syntax errors are underlined in red.

907
908
           In the following figure, a semicolon is missing at the end of the
           line.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
909
910
911
912
913
914
915
916

           \image qtcreator-syntaxerror.png
        \o Semantic errors and warnings are underlined in olive.

           In the following figure, the type is unknown.

           \image qtcreator-semanticerror.png
    \endlist
917
918


919
920
921
922
923
924
925
926
    \section1 Completing Code

    Qt Creator understands the code as code, not just as plain text. This
    allows it to help you to write well formatted code and to anticipate
    what you are going to write and complete the code. The code completion
    differs somewhat depending on whether you write Qt code or QML code.

    \section2 Completing Qt Code
927

928
929
    As you write code, Qt Creator provides a list of context-sensitive
    suggestions to the statement currently under your cursor.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
930
931
932

    \image qtcreator-codecompletion.png

933
934
    To open the list of suggestions at any time, press \key{Ctrl+Space}.
    If only one option is available, Qt Creator inserts it automatically.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
935

936
937
938
939
    When completion is invoked manually, Qt Creator completes the common prefix
    of the list of suggestions. This is especially useful for classes with
    several similarly named members. To disable this functionality, uncheck
    \gui{Autocomplete common prefix} in the code completion preferences.
940
    Select \gui Tools > \gui{Options...} > \gui{Text Editor} > \gui Completion.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
941

942
943
944
945
    By default, code completion considers only the first letter case-sensitive.
    To apply full or no case-sensitivity, select the option in the
    \gui {Case-sensitivity} field.

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
946
947
    The following table lists available types for code completion and icon
    used for each.
948
949

    \table
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
950
951
952
        \header
            \o Icon
            \o Description
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
        \row
            \i  \inlineimage completion/class.png
            \i  A class
        \row
            \i  \inlineimage completion/enum.png
            \i  An enum
        \row
            \i  \inlineimage completion/enumerator.png
            \i  An enumerator (value of an enum)
        \row
            \i  \inlineimage completion/func.png
            \i  A function
        \row
            \i  \inlineimage completion/func_priv.png
            \i  A private function
        \row
            \i  \inlineimage completion/func_prot.png
            \i  A protected function
        \row
            \i  \inlineimage completion/var.png
            \i  A variable
        \row
            \i  \inlineimage completion/var_priv.png
            \i  A private variable
        \row
            \i  \inlineimage completion/var_prot.png
            \i  A protected variable
        \row
            \i  \inlineimage completion/signal.png
            \i  A signal
        \row
            \i  \inlineimage completion/slot.png
            \i  A slot
        \row
            \i  \inlineimage completion/slot_priv.png
            \i  A private slot
        \row
            \i  \inlineimage completion/slot_prot.png
            \i  A protected slot
        \row
            \i  \inlineimage completion/keyword.png
            \i  A keyword
        \row
            \i  \inlineimage completion/macro.png
            \i  A macro
        \row
            \i  \inlineimage completion/namespace.png
            \i  A namespace
    \endtable
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
1002

1003
1004
1005
1006
1007
1008
1009
1010
1011
    \section2 Completing QML Code

    As you write QML code, Qt Creator suggests properties, IDs, and code
    snippets to complete the code. The snippets can consist of multiple
    fields that you specify values for. Select an item in the list and press
    \key Tab or \key Enter to complete the code. Press \key Tab to
    move between the fields and specify values for them.

    \image qmldesigner-code-completion.png "Completing QML code"
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
1012

1013
1014
    \section1 Using Bookmarks

1015
    To insert or delete a bookmark right-click the line number and select
1016
1017
1018
1019
    \gui{Toggle Bookmark} or press \key{Ctrl+M}.

    \image qtcreator-togglebookmark.png

1020
    To go to previous bookmark in the current session, press \key{Ctrl+,}.
1021

1022
    To go to next bookmark in the current session, press \key{Ctrl+.}.
1023
1024


Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
1025
1026
1027
1028
1029
    \section1 Moving to Symbol Definition or Declaration

    In Qt Creator you can move directly to the definition or the declaration of
    a symbol by holding the \key Ctrl and clicking the symbol.

1030
    To enable this moving function, in \gui Tools > \gui{Options...} >
1031
    \gui{Text Editor} > \gui Behavior select \gui{Enable mouse navigation}.
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
1032

Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
1033

1034
1035
1036
1037
1038
    \section1 Using Update Code Model

    To refresh the internal information in Qt Creator pertaining to your code,
    select \gui{Tools} > \gui{C++} > \gui{Update code model}.

1039
1040
    \note In Qt Creator indexing updates the code automatically. Use
    \gui{Update code model} only as an emergency command.
1041

1042
1043
*/

1044

1045
1046
1047
1048
1049
/*!
    \contentspage index.html
    \previouspage creator-editor-locator.html
    \page creator-editor-codepasting.html
    \nextpage creator-editor-options.html
1050

1051
    \title Pasting and Fetching Code Snippets
1052

Leena Miettinen's avatar