creator-ui.qdoc 22.2 KB
Newer Older
1
2
/****************************************************************************
**
3
4
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
5
**
6
** This file is part of the Qt Creator documentation.
7
**
8
9
10
11
12
13
14
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
15
**
16
** GNU Free Documentation License Usage
17
18
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
19
20
21
22
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
23
24
25
26
27
28
29
30
31
32
**
****************************************************************************/

// **********************************************************************
// 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.
// **********************************************************************

/*!
33
    \contentspage {Qt Creator Manual}
34
35
    \previouspage creator-overview.html
    \page creator-quick-tour.html
36
    \nextpage creator-configuring.html
37
38
39

    \title User Interface

40
    When you start \QC, it opens to the \uicontrol Welcome mode, where you can:
41
42
43

    \list

44
        \li Open recent sessions and projects
45

46
        \li Create and open projects
47

48
        \li Open tutorials and example projects
49

50
        \li Read news from the online community and Qt labs
51
52
53

    \endlist

54
    \image qtcreator-breakdown.png
55

56
    You can use the mode selector (1) to change to another \QC mode.
57

58
59
    You can use the kit selector (2) to select the
    \l{glossary-buildandrun-kit}{kit} for running (3), debugging (4), or
60
61
62
63
    building (5) the application. Output from these actions is displayed in the
    output panes (7).

    You can use the locator (6) to to browse through projects, files, classes,
64
    functions, documentation, and file systems.
65
66
67
68
69
70
71
72
73

    \section1 Modes

    The mode selector allows you to quickly switch between tasks such as editing
    project and source files, designing application UIs, configuring how
    projects are built and executed, and debugging your applications. To change
    modes, click the icons, or use the \l{keyboard-shortcuts}
    {corresponding keyboard shortcut}.

74
    To hide the mode selector and to save space on the display, select
75
    \uicontrol Window > \uicontrol {Show Mode Selector}.
76

77
78
    The following image displays an example application in \uicontrol Edit mode (1)
    and \uicontrol Design mode (2).
79
80
81

    \image qtcreator-qt-quick-editors.png "Edit mode and Design mode"

82
83
84
85
    You can use \QC in the following modes:

    \list

86
        \li \uicontrol Welcome mode for opening projects.
87

88
        \li \uicontrol{\l{Coding}{Edit}} mode for editing project and source
89
90
            files.

91
        \li \uicontrol{\l{Designing User Interfaces}{Design}} mode for designing and
92
93
94
            developing application user interfaces. This mode is available for
            UI files.

95
        \li \uicontrol{\l{Debugging}{Debug}} mode for inspecting the state of your
96
97
            application while debugging and for using code analysis tools
            to detect memory leaks and profile C++ or QML code.
98

99
        \li \uicontrol{\l{Specifying Build Settings}{Projects}} mode for configuring
100
101
102
            project building and execution. This mode is available when a
            project is open.

103
        \li \uicontrol{\l{Getting Help}{Help}} mode for viewing Qt documentation.
104
105
106

    \endlist

107
108
109
    Certain actions in \QC trigger a mode change. Clicking on \uicontrol {Debug} >
    \uicontrol {Start Debugging} > \uicontrol {Start Debugging} automatically switches to
    \uicontrol {Debug} mode.
110
111
112

    \section1 Browsing Project Contents

113
114
    The sidebar is available in the \uicontrol Edit and \uicontrol Debug modes, and with a
    different set of views in the \uicontrol Design mode. Use the
115
116
117
118
119
    sidebar to browse projects, files, and bookmarks, and to view the class
    hierarchy.

    \image qtcreator-sidebar.png

120
    You can select the content of the sidebar in the sidebar menu (1):
121
122
123

    \list

124
        \li \uicontrol Projects shows a list of projects open in the current
125
126
            session.

127
        \li \uicontrol{Open Documents} shows currently open files.
128

129
        \li \uicontrol Bookmarks shows all bookmarks for the current session.
130

131
        \li \uicontrol{File System} shows all files in the currently selected
132
133
             directory.

134
        \li \uicontrol {Class View} shows the class hierarchy of the currently
135
136
            open projects.

137
        \li \uicontrol Outline shows the symbol hierarchy of a C++ file and the type
138
139
            hierarchy of a QML file.

140
        \li \uicontrol Tests lists autotests and Qt Quick tests in the project.
141

142
        \li \uicontrol {Type Hierarchy} shows the base classes of a class.
143

144
        \li \uicontrol {Include Hierarchy} shows which files are included in the current file
145
146
            and which files include the current file.

147
148
    \endlist

149
150
151
    For more information about the sidebar views that are only available in
    \QMLD, see \l{Using Qt Quick Designer}.

152
153
154
155
    You can change the view of the sidebar in the following ways:

    \list

156
        \li To toggle the sidebar, click \inlineimage qtcreator-togglebutton.png
157
            (\uicontrol {Hide Sidebar/Show Sidebar}) or press \key Alt+0
158
            (\key Cmd+0 on OS X).
159

160
        \li To split the sidebar, click \inlineimage qtcreator-splitbar.png
161
            (\uicontrol {Split}). Select new content to view in the split view.
162

163
        \li To close a sidebar view, click
164
            \inlineimage qtcreator-remove-split-button.png
165
            (\uicontrol {Close}).
166
167
168
169
170
171

    \endlist

    The additional options in each view are described in the following
    sections.

172
173
174
    In some views, right-clicking opens a context menu that contains functions
    for managing the objects listed in the view.

175
176
177
178
179
180
    \section2 Viewing Project Files

    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.

181
182
183
    If the project is under version control, information from the version control system
    might be displayed in brackets after the project name. This is currently implemented for
    Git (the branch name or a tag is displayed) and ClearCase (the view name is displayed).
Leena Miettinen's avatar
Leena Miettinen committed
184

185
186
187
188
    You can use the project tree in the following ways:

    \list

189
        \li To open files that belong to a project, double-click them in the
Leena Miettinen's avatar
Leena Miettinen committed
190
191
192
193
            project tree. Files open in the appropriate editor, according to the
            file type. For example, code source files open in the code editor
            and image files in the \l{Viewing Images}{image viewer}.

194
        \li To bring up a context menu containing the actions most commonly
195
196
197
198
            needed right-click an item in the project tree. For example, through
            the menu of the project root directory you can, among other actions,
            build, re-build, clean and run the project.

199
        \li To hide the categories and sort project files alphabetically, click
200
            \inlineimage qtcreator-filter.png
201
            (\uicontrol {Filter Tree}) and select \uicontrol{Simplify Tree}.
202

203
        \li To hide source files which are automatically generated by the build
204
            system, select \uicontrol {Filter Tree > Hide Generated Files}.
205

206
        \li To keep the position in the project tree synchronized with the file
207
208
            currently opened in the editor, click
            \inlineimage qtcreator-synchronizefocus.png
209
            (\uicontrol {Synchronize with Editor}).
210

211
        \li To see the absolute path of a file, move the mouse pointer over the
212
213
214
215
            file name.

    \endlist

216
217
218
    Files that are not sources or data can be still included into a project's
    distribution tarball by adding their paths to the \c DISTFILES variable in
    the .pro file. This way they also become known to \QC, so that they are
219
    visible in the \uicontrol Projects view and are known to the locator and search.
Leena Miettinen's avatar
Leena Miettinen committed
220

221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
    The \uicontrol Projects view contains context menus for managing projects,
    subprojects, folders, and files. The following functions are available for
    managing projects and subprojects:

    \list

        \li Set a project as the active project.

        \li Execute the \uicontrol Build menu commands.

        \li Add subprojects, libraries, directories, and files.

        \li Remove subprojects.

        \li Search from the selected directory.

        \li Close projects.

    \endlist

    For managing files and directories, the same functions are available as in
    the \uicontrol {File System} view. In addition, you can remove and rename
    files.

245
246
    \section2 Viewing the File System

247
248
    If you cannot see a file in the \uicontrol Projects view, switch to the
    \uicontrol {File System} view, which shows all the files in the file system.
249

250
    To also show hidden files, select \uicontrol {Filter Files} > \uicontrol {Show Hidden Files}.
251

252
    To keep the position in the tree synchronized with the file
253
    opened in the editor, select \uicontrol {Synchronize with Editor}.
254

255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
    Use the context menu functions to:

    \list

        \li Open files with the default editor or some other editor.

        \li Show the file or directory in the file explorer.

        \li Open a terminal window in the selected directory or in the directory
            that contains the file.

        \li Search from the selected directory.

    \endlist

270
271
    \section2 Viewing the Class Hierarchy

272
    The \uicontrol {Class View} shows the class hierarchy of the currently
273
274
    open projects. To organize the view by subprojects, click
    \inlineimage qtcreator-show-subprojects.png
275
    (\uicontrol {Show Subprojects}).
276

277
278
279
    To visit all parts of a namespace, double-click on the namespace item
    multiple times.

280
    \section2 Viewing QML Types
281

282
    The \uicontrol Outline view shows the type hierarchy in a QML file.
283
284
285

    \list

286
        \li To see a complete list of all bindings, select \uicontrol {Filter Tree >
287
            Show All Bindings}.
288

289
        \li To keep the position in the view synchronized with the QML type
290
            selected in the editor, select \uicontrol {Synchronize with Editor}.
291
292
293

    \endlist

294
295
296
    \section2 Viewing Tests

    The \uicontrol Tests view shows the autotests and Qt Quick tests in the
297
    current project. Select the test cases to run. If a Qt
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
    Quick test case does not have a name, it is marked \uicontrol Unnamed in the
    list. Unnamed test cases are always executed when the application that
    contains them is run, and therefore you cannot select or deselect them.

    To show or hide init and cleanup or data functions, select
    \uicontrol {Filter Test Tree} > \uicontrol {Show Init and Cleanup Functions}
    or \uicontrol {Show Data Functions}. Double-click a function in the list
    to open its source code in the code editor.

    The test cases are listed in alphabetic order. To list them in the order in
    which they are defined in the source code, select
    \inlineimage qtcreator-autotests-sort-naturally.png
    (\uicontrol {Sort Naturally}).

    To run tests, select \uicontrol {Run All Tests} or
    \uicontrol {Run Selected Tests} in the context menu.

    To refresh the view, select \uicontrol {Rescan Tests} in the context menu.

317
318
319
    \section2 Viewing Type Hierarchy

    To view the base classes of a class, right-click the class and select
320
    \uicontrol {Open Type Hierarchy}  or press \key {Ctrl+Shift+T}.
321

322
323
324
    \section2 Viewing Include Hierarchy

    To view which files are included in the current file and which files include
325
    the current file, right-click in the editor and select \uicontrol {Open Include Hierarchy}
326
327
    or press \key {Ctrl+Shift+I}.

328
329
330
331
332
333
    \section1 Viewing Output

    The task pane in \QC can display one of the following panes:

    \list

334
       \li \uicontrol{Issues}
335

336
       \li \uicontrol{Search Results}
337

338
       \li \uicontrol{Application Output}
339

340
       \li \uicontrol{Compile Output}
341

hjk's avatar
hjk committed
342
       \li \uicontrol {Debugger Console}
343

344
       \li \uicontrol {To-Do Entries}
345

346
       \li \uicontrol{Version Control}
347

348
       \li \uicontrol{General Messages}
349

350
       \li \uicontrol{Test Results}
351

352
353
354
355
    \endlist

    Output panes are available in all \l{Modes}{modes}. Click the name of an
    output pane to open the pane. To maximize an open output pane, click the
356
    \uicontrol {Maximize Output Pane} button or press \key {Alt+9}.
357

358
    To search within the \uicontrol{Application Output} and \uicontrol{Compile Output}
359
    panes, press \key {Ctrl+F} when the pane is active. Enter search criteria in
360
    the \uicontrol Find field and click the left and right arrows to search down and
361
362
    up in the pane. In these panes, you can also use the zoom buttons to increase and
    decrease the text size of the output.
363

364
    To open the \uicontrol{General Messages} and \l{Using Version Control Systems}
365
    {Version Control} panes, select
366
    \uicontrol {Window > Output Panes}. To display the \uicontrol {To-Do Entries} pane,
367
368
    enable the Todo plugin and to display the \l{Running Autotests}
    {Test Results} pane, enable the Auto Tests plugin.
369

Leena Miettinen's avatar
Leena Miettinen committed
370
    \section2 Issues
371

372
    The \uicontrol{Issues} pane provides lists of following types of issues:
373

Leena Miettinen's avatar
Leena Miettinen committed
374
    \list
375

376
        \li \uicontrol {Build System} - Errors and warnings encountered during a
Leena Miettinen's avatar
Leena Miettinen committed
377
378
            build.

379
380
        \li \uicontrol Compile - Selected output from the compiler. Open the
            \uicontrol {Compile Output} pane for more detailed information.
Leena Miettinen's avatar
Leena Miettinen committed
381

382
       \li \uicontrol{Debug Information} - Lists debug information packages that might
383
384
            be missing.

385
386
387
        \li \uicontrol Debugger - Errors encountered while running the
            \l{Analyzing Code}{Valgrind code analysis tools}.

388
       \li \uicontrol{Debugger Runtime} - Errors encountered when starting \QC. For
389
390
            example, information about missing DLLs.

391
       \li \uicontrol Deployment - Errors encountered between building an application
392
393
            successfully and starting it on a device.

394
        \li \uicontrol {My Tasks} - Entries from a task list file (.tasks) generated
Leena Miettinen's avatar
Leena Miettinen committed
395
396
397
            by \l{Showing Task List Files in Issues Pane}
            {code scanning and analysis tools}.

398
        \li \uicontrol QML - Errors in QML syntax.
399

400
        \li \uicontrol {QML Analysis} - Results of the JavaScript
Leena Miettinen's avatar
Leena Miettinen committed
401
402
            \l{Checking JavaScript and QML Syntax}
            {code syntax and validation checks}
Leena Miettinen's avatar
Leena Miettinen committed
403
404
405
406
407

    \endlist

    The pane filters out irrelevant output from the build tools and presents the
    issues in an organized way. To further filter the output by type, select
408
    \uicontrol {Filter Tree}
Leena Miettinen's avatar
Leena Miettinen committed
409
410
411
412
    and then select a filter.

    \image qtcreator-build-issues.png

413
414
415
416
417
    Right-clicking on a line brings up a context menu with actions that you can
    apply to the contents of the line. You can remove a line, copy its contents
    to the clipboard, or search the Internet for a solution using the contents
    of the line as search criteria. In addition, you can show a version control
    annotation view of the line that causes the error message.
418

419
    To navigate to the corresponding source code, click an issue or
420
    select \uicontrol {Show in Editor} in the context menu. The entry must contain the
421
422
    name of the file where the issue was found.

423
424
    To view more information about an issue in the \uicontrol {Compile Output} pane,
    select \uicontrol {Show Output} in the context menu.
425

Leena Miettinen's avatar
Leena Miettinen committed
426
427
    To jump from one issue to the next or previous one, press \key F6 and
    \key Shift+F6.
428
429
430

    \section2 Search Results

431
    In the \uicontrol{Search Results} pane, you can search through projects, files on
432
433
434
435
436
437
    a file system or the currently open file:

    \image qtcreator-search-results.png "Search Results output pane"

    The search results are stored in the search history (1) from which you can
    select earlier searches.
438
439
440
441
442
443
444
445

    The figure below shows an example search result for all
    occurrences of \c textfinder within the \c "/TextFinder" directory.

    \image qtcreator-search-pane.png

    \section2 Application Output

446
    The \uicontrol{Application Output} pane displays the status of a program when
447
448
449
450
    it is executed, and the debug output.

    \image qtcreator-application-output.png

451
452
453
    Select toolbar buttons to run applications, to attach the debugger to the
    running application, and to stop running or debugging.

454
455
456
457
458
459
460
    To specify settings for displaying application output, select
    \uicontrol Tools > \uicontrol Options > \uicontrol {Build & Run} >
    \uicontrol General. You can select whether to open the
    \uicontrol{Application Output} pane on output when running or debugging
    applications, to clear old output on a new run, to word-wrap output, and to
    limit output to the specified number of lines.

461
462
    \section2 Compile Output

463
464
465
    The \uicontrol{Compile Output} pane provides all output from the compiler.
    The \uicontrol{Compile Output} is a more detailed version of information
    displayed in the \uicontrol{Issues} pane.
466
467
468

    \image qtcreator-compile-pane.png

469
470
471
    Double-click on a file name in an error message to open the file in the
    code editor.

472
    Select the \uicontrol {Cancel Build} button to cancel the build.
473

474
475
476
477
478
    To specify whether to open the \uicontrol {Compile Output} pane on output
    when building applications, select \uicontrol Tools > \uicontrol Options >
    \uicontrol {Build & Run} > \uicontrol General, and then select the
    \uicontrol {Open Compile Output pane when building} check box.

hjk's avatar
hjk committed
479
    \section2 Debugger Console
480

hjk's avatar
hjk committed
481
    In the \uicontrol {Debugger Console}, you can type JavaScript expressions and use them to get
482
483
484
485
    information about the state of your application during debugging. You can change property
    values temporarily, without editing the source, and view the results in the running
    application.

hjk's avatar
hjk committed
486
    \image qml-script-console.png "Debugger Console"
487
488
489

    You can change the property values permanently in the code editor.

490
491
    \section2 To-Do List

492
    The \uicontrol {To-Do List Entries} pane lists the BUG, FIXME, NOTE, TODO, and
493
494
495
496
497
    WARNING keywords from the current file or from all project files. The
    keywords are organized into information, warning, and error categories.

    \image qtcreator-todo-pane.png

498
499
    To add keywords, select \uicontrol Tools > \uicontrol Options >
    \uicontrol {To-Do} > \uicontrol Add.
500
    Set an icon and a line background color for the keyword. To change the icons
501
    and colors set for an existing keyword, select \uicontrol Edit.
502
503

    To determine whether the keywords in the whole project or in the current
504
    file are displayed by default, select \uicontrol {Scanning scope}.
505

506
    To exclude files from scanning, select \uicontrol {To-Do} in the
507
508
509
510
    \uicontrol Projects mode. Select \uicontrol Add and enter a regular
    expression that matches the path to files to exclude. Use a forward slash
    (/) as a separator in the path also on Windows.

511
    The Todo plugin is disabled by default. To enable the plugin, select
512
513
    \uicontrol Help > \uicontrol {About Plugins} > \uicontrol Utilities >
    \uicontrol Todo and restart
514
515
516
    \QC.

    In addition, you can open task list files generated by code scanning and
517
    analysis tools in the \uicontrol Issues pane. For more information, see
518
519
    \l{Showing Task List Files in Issues Pane}.

520
521
522
523
    \section1 Changing Languages

    \QC has been localized into several languages. If the system language is one
    of the supported languages, it is automatically selected. To change the
524
525
    language, select \uicontrol {Tools > Options > Environment} and select a language
    in the \uicontrol Language field. The change takes effect after you restart \QC.
526

Leena Miettinen's avatar
Leena Miettinen committed
527
528
529
530
531
532
    \section1 Viewing Images

    \QC opens image files in the image viewer.

    \image qtcreator-image-viewer.png "Image viewer"

533
534
    Use the toolbar buttons (1) or \l{Keyboard Shortcuts}{keyboard shortcuts}
    to:
Leena Miettinen's avatar
Leena Miettinen committed
535
536
537

    \list

538
539
        \li Export SVG images to pixmaps

540
        \li Switch between background and outline modes
Leena Miettinen's avatar
Leena Miettinen committed
541

542
        \li Zoom in and out
Leena Miettinen's avatar
Leena Miettinen committed
543

544
        \li Fit images to screen
Leena Miettinen's avatar
Leena Miettinen committed
545

546
        \li Return to original size
Leena Miettinen's avatar
Leena Miettinen committed
547

548
        \li Play and pause animated GIF and MNG images
549

Leena Miettinen's avatar
Leena Miettinen committed
550
551
    \endlist

552
553
554
555
556
557
558
    \section2 Exporting SVG Images

    If you receive a freely scalable icon in the SVG format from an UI designer,
    you can export it to several images of different sizes to create a set of
    pixmaps. You can then use QIcon::addPixmap() to add the pixmaps to icons in
    different modes and states.

559
560
561
562
563
    \section1 Navigating with Keyboard

    \QC 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
564
    \l{Searching with the Locator}{navigation} shortcuts are available to help
565
566
    speed up the process of developing your application.

567
568
569
570
571
    \section1 Useful Features

    For a list of useful \QC features described in other parts of the
    documentation, see \l{Tips and Tricks}.

572
573
574
575
576
577
578
579
580
581
582
583
584
    \section1 Platform Notes

    \QC uses standard names and locations for standard features, such as
    \e options or \e preferences. In this manual, the names and locations on
    Windows and Linux are usually used to keep the instructions short. Here are
    some places to check if you cannot find a function, dialog, or keyboard
    shortcut on OS X when following the instructions:

    \table
        \header
            \li For
            \li Look In
        \row
585
586
            \li \uicontrol Tools > \uicontrol Options
            \li \uicontrol {Qt Creator} > \uicontrol Preferences
587
        \row
588
589
            \li \uicontrol Help > \uicontrol {About Plugins}
            \li \uicontrol {Qt Creator} > \uicontrol {About Plugins}
590
591
        \row
            \li Keyboard shortcuts
592
593
            \li \uicontrol {Qt Creator} > \uicontrol Preferences > \uicontrol Environment >
                \uicontrol Keyboard
594
595
    \endtable

596
*/