creator-editors.qdoc 90.3 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
    \previouspage creator-coding-navigating.html
35 36 37 38 39
    \page creator-highlighting.html
    \nextpage creator-checking-code-syntax.html

    \title Semantic Highlighting

40
    \QC understands the C++, QML, and JavaScript languages as code, not as plain
41
    text. It reads the source code, analyzes it, and highlights it based on the
42 43 44 45
    semantic checks that it does for the following code elements:

    \list

46
        \li Types (such as classes, structs, and type definitions)
47

48
        \li Local variables
49

50
        \li Class fields
51

52
        \li Virtual functions
53 54 55 56

    \endlist

    To specify the color scheme to use for semantic highlighting, select
57 58
    \uicontrol Tools > \uicontrol Options > \uicontrol {Text Editor} >
    \uicontrol {Fonts & Color}.
59

60 61
    \QC supports syntax highlighting also for other types of files than C++,
    QML, or JavaScript.
62 63 64 65 66 67 68

    \section1 Generic Highlighting

    Generic highlighting is based on highlight definition files that are
    provided by the
    \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}
    {Kate Editor}. You can download highlight definition files for use with \QC.
Leena Miettinen's avatar
Leena Miettinen committed
69 70
    For more information about the definition files, see
    \l{http://kde-files.org/index.php?xcontentmode=680}{KDE-Files.org}.
71 72 73 74

    If you have a Unix installation that comes with the Kate Editor, you might
    already have the definition files installed. Typically, the files are
    located in a read-only directory, and therefore, you cannot manage them. \QC
75 76 77
    can try to locate them and use them as fallback files, when the primary
    location does not contain the definition for the current file type. You can
    also specify the directory that contains preinstalled highlight
78 79 80
    definition files as the primary location.

    When you open a file for editing and the editor cannot find the highlight
81 82
    definition for it, an alert appears. To suppress the alerts, you can specify
    patterns for ignoring files.
83 84 85 86 87

    To download highlight definition files:

    \list 1

88 89
        \li Select \uicontrol Tools > \uicontrol Options >
            \uicontrol {Text Editor} > \uicontrol {Generic Highlighter}.
90 91 92

            \image qtcreator-generic-highlighter.png "Generic Highlighter options"

93
        \li In the \uicontrol Location field, specify the path to the primary
94 95
            location for highlight definition files.

96
        \li Click \uicontrol {Download Definitions} to open a list of highlight
97 98 99 100
            definition files available for download.

            \image qtcreator-manage-definitions.png "Download Definitions dialog"

101
        \li Select highlight definition files in the list and click
102
            \uicontrol {Download Selected Definitions}.
103

104
        \li Select the \uicontrol {Use fallback location} check box to specify the
105 106 107
            secondary location where the editor will look for highlight
            definition files.

108 109
        \li Click \uicontrol Autodetect to allow \QC to look for highlight
            definition files on your system, or click \uicontrol Browse to locate
110 111
            them in the file system yourself.

112
        \li In the \uicontrol {Ignored file patterns} field, specify file patterns to
113
            suppress alerts if the highlight definitions for the
114 115
            specified files are not found.

116
        \li Click \uicontrol OK to save your changes.
117 118 119 120 121 122

    \endlist

    \section1 Highlighting and Folding Blocks

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

    \image qtcreator-blockhighlighting.png

128 129 130
    To enable block highlighting, select \uicontrol Tools >
    \uicontrol Options > \uicontrol {Text Editor} > \uicontrol Display >
    \uicontrol {Highlight blocks}.
131

132 133 134
    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.
135

136 137 138
    To show the folding markers, select \uicontrol Tools > \uicontrol Options >
    \uicontrol {Text Editor} > \uicontrol Display >
    \uicontrol {Display folding markers}. This option is enabled by default.
139

140 141 142 143
    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
    \uicontrol Tools > \uicontrol Options > \uicontrol {Text Editor} >
    \uicontrol Display and deselect \uicontrol {Animate matching parentheses}.
144

145 146 147 148 149 150 151 152 153 154 155
    You can use keyboard shortcuts to move within and between blocks. To go to
    block end, press \key {Ctrl+]} and to go to block start, press
    \key {Ctrl+[}. To also select the lines from the cursor position to the end
    or beginning of the block, press \key {Ctrl+Shift+]} and
    \key {Ctrl+Shift+[}, respectively.

    To select the current block, press \key Ctrl+U. A second key press extends
    the selection to the parent block. To undo the last selection, press
    \key {Ctrl+Alt+Shift+U}. To enable smart block selection, select
    \uicontrol Tools > \uicontrol Options > \uicontrol {Text Editor} >
    \uicontrol Behavior > \uicontrol {Enable smart selection changing}.
156 157 158 159
*/


/*!
160
    \contentspage {Qt Creator Manual}
161 162 163 164 165 166
    \previouspage creator-highlighting.html
    \page creator-checking-code-syntax.html
    \nextpage creator-completing-code.html

    \title Checking Code Syntax

167
    As you write code, \QC checks code syntax. When \QC spots a syntax error in
168
    your code it underlines it and shows error details when you move the mouse
169 170 171
    pointer over the error. Similarly, when you are working on an instance of a
    JavaScript object notation (JSON) entity, \QC underlines errors in JSON data
    structure.
172 173 174

    \list

175
        \li Syntax errors are underlined in red.
176 177 178 179 180 181

            In the following figure, a semicolon is missing at the end of the
            line.

            \image qtcreator-syntaxerror.png

182
        \li Semantic errors and warnings are underlined in olive.
183

184
            In the following figure, the variable is not used.
185 186 187 188 189

            \image qtcreator-semanticerror.png

    \endlist

190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
    When using the Clang code model, errors and warnings are additionally marked
    with icons and annotated. If a \l{http://clang.llvm.org/diagnostics.html}
    {Clang fix-it} is available, you can execute it by clicking the
    \inlineimage refactormarker.png
    icon and pressing \key Enter.

    In the following figure, a semicolon is missing at the end of the
    line.

    \image qtcreator-syntaxerror-clang.png

    In the following figure, the variable is not used.

    \image qtcreator-semanticerror-clang.png

    To specify the position where the annotations are displayed, select
    \uicontrol Tools > \uicontrol Options > \uicontrol {Text Editor} >
    \uicontrol Display > \uicontrol {Annotations next to lines}, and then
    select whether to display the annotations directly next to the code,
    aligned to the right of the code, or in the right margin.

    If you hide the annotations by deselecting the check box, you can move the
    mouse pointer over an icon to view them.
213 214 215

    \section1 Checking JSON Data Structure

216 217 218
    You can run static checks on the QML and JavaScript code in
    your project to find common problems.

219 220 221
    \QC validates instances of JSON entities against
    \l{http://tools.ietf.org/html/draft-zyp-json-schema-03}
    {A JSON Media Type for Describing the Structure and Meaning of JSON Documents}.
222
    However, \QC does not understand the entire specification.
223 224 225

    A JSON schema defines the structure of JSON data. It determines what JSON
    data is required for an application and how to interact with it.
226

227
    The specification does not define how to map JSON instances with JSON
228
    schemas. \QC looks for a JSON schema file with a
229
    name that matches the name of the JSON instance file in the user
230
    configuration folder. For example, \c {~/config/QtProject/qtcreator/json} on
231
    Linux and \macos and
232
    \c {C:\Users\username\AppData\Roaming\QtCreator\qtcreator\json}
233 234 235
    in Windows. To check JSON data structure, copy the JSON schema file to the
    above folder.

236
    \section2 Checking JavaScript and QML Syntax
237

238 239 240 241
    To run the checks, select \uicontrol Tools > \uicontrol {QML/JS} >
    \uicontrol {Run Checks} or press \key {Ctrl+Shift+C}. The results are shown
    in the \uicontrol {QML Analysis} filter of the \uicontrol Issues output
    pane.
242

243

244
    \section2 List of JavaScript and QML Checks
245

246
    Many of the JavaScript checks are similar to the ones in Douglas Crockford's
247
    \l{http://www.jslint.com}{JSLint} tool.
248 249 250

    \table
    \header
Tobias Hunger's avatar
Tobias Hunger committed
251 252 253 254
        \li Id
        \li Severity
        \li Message
        \li Description
255 256

    \row
Tobias Hunger's avatar
Tobias Hunger committed
257 258 259
        \li M1
        \li Error
        \li Invalid value for enum
260
        \li
261 262

    \row
Tobias Hunger's avatar
Tobias Hunger committed
263 264 265
        \li M2
        \li Error
        \li Enum value must be a string or a number
266
        \li
267 268

    \row
Tobias Hunger's avatar
Tobias Hunger committed
269 270 271
        \li M3
        \li Error
        \li Number value expected
272
        \li
273 274

    \row
Tobias Hunger's avatar
Tobias Hunger committed
275 276 277
        \li M4
        \li Error
        \li Boolean value expected
278
        \li
279 280

    \row
Tobias Hunger's avatar
Tobias Hunger committed
281 282 283
        \li M5
        \li Error
        \li String value expected
284
        \li
285 286

    \row
Tobias Hunger's avatar
Tobias Hunger committed
287 288 289
        \li M6
        \li Error
        \li Invalid URL
290
        \li
291 292

    \row
Tobias Hunger's avatar
Tobias Hunger committed
293 294 295
        \li M7
        \li Warning
        \li File or directory does not exist
296
        \li
297 298

    \row
Tobias Hunger's avatar
Tobias Hunger committed
299 300 301
        \li M8
        \li Error
        \li Invalid color
302
        \li
303 304

    \row
Tobias Hunger's avatar
Tobias Hunger committed
305 306 307
        \li M9
        \li Error
        \li Anchor line expected
308
        \li
309 310

    \row
Tobias Hunger's avatar
Tobias Hunger committed
311 312 313
        \li M10
        \li Error
        \li Duplicate property binding
314
        \li
315 316

    \row
Tobias Hunger's avatar
Tobias Hunger committed
317 318 319
        \li M11
        \li Error
        \li Id expected
320
        \li
321 322

    \row
Tobias Hunger's avatar
Tobias Hunger committed
323 324 325
        \li M14
        \li Error
        \li Invalid id
326
        \li
327 328

    \row
Tobias Hunger's avatar
Tobias Hunger committed
329 330 331 332
        \li M15
        \li Error
        \li Duplicate id
        \li Ids in a file must be unique.
333 334

    \row
Tobias Hunger's avatar
Tobias Hunger committed
335 336
        \li M16
        \li Error
337
        \li Invalid property name \c name
338
        \li
339 340

    \row
Tobias Hunger's avatar
Tobias Hunger committed
341 342
        \li M17
        \li Error
343
        \li \c Name does not have members
344
        \li
345 346

    \row
Tobias Hunger's avatar
Tobias Hunger committed
347 348
        \li M18
        \li Error
349
        \li \c Field is not a member of \c object
350
        \li
351 352

    \row
Tobias Hunger's avatar
Tobias Hunger committed
353 354 355 356 357
        \li M19
        \li Warning
        \li Assignment in condition
        \li It could be a typing error. If it is intentional, wrap the
            assignment in parentheses.
358 359

    \row
360 361 362 363 364 365 366
        \li M20
        \li Warning
        \li Unterminated non-empty case block
        \li Case blocks should either be empty or end in a flow control
            statement such as \c break, \c return or \c continue.
            Alternatively you can indicate intentional fall through by ending
            with a \c {// fall through} comment.
367 368

    \row
Tobias Hunger's avatar
Tobias Hunger committed
369 370
        \li M23
        \li Warning
371
        \li Do not use \c eval
372
        \li
373 374

    \row
375 376 377 378
        \li M28
        \li Warning
        \li Unreachable
        \li Indicates that the underlined statement will never be executed.
379 380

    \row
Tobias Hunger's avatar
Tobias Hunger committed
381 382
        \li M29
        \li Warning
383
        \li Do not use \c with
384
        \li
385 386

    \row
Tobias Hunger's avatar
Tobias Hunger committed
387 388 389
        \li M30
        \li Warning
        \li Do not use comma expressions
390
        \li
391 392

    \row
Tobias Hunger's avatar
Tobias Hunger committed
393 394 395
        \li M31
        \li Warning
        \li Unnecessary message suppression
396
        \li
397 398

    \row
Tobias Hunger's avatar
Tobias Hunger committed
399 400
        \li M103
        \li Warning
401
        \li \c Name is already a formal parameter
402
        \li
403 404

    \row
Tobias Hunger's avatar
Tobias Hunger committed
405 406
        \li M104
        \li Warning
407
        \li \c Name is already a function
408
        \li
409 410

    \row
Tobias Hunger's avatar
Tobias Hunger committed
411 412
        \li M105
        \li Warning
413
        \li Var \c name is used before its declaration
414
        \li
415 416

    \row
Tobias Hunger's avatar
Tobias Hunger committed
417 418
        \li M106
        \li Warning
419
        \li \c Name is already a var
420
        \li
421 422

    \row
423 424 425 426 427 428
        \li M107
        \li Warning
        \li \c Name is declared more than once
        \li Variables declared in a function are always visible everywhere in
            the function, even when declared in nested blocks or \c for
            statement conditions. Redeclaring a variable has no effect.
429 430

    \row
Tobias Hunger's avatar
Tobias Hunger committed
431 432
        \li M108
        \li Warning
433
        \li Function \c name is used before its declaration
434
        \li
435 436

    \row
Tobias Hunger's avatar
Tobias Hunger committed
437 438
        \li M109
        \li Warning
439
        \li Do not use \c Boolean as a constructor
440
        \li
441 442

    \row
Tobias Hunger's avatar
Tobias Hunger committed
443 444
        \li M110
        \li Warning
445
        \li Do not use \c String as a constructor
446
        \li
447 448

    \row
Tobias Hunger's avatar
Tobias Hunger committed
449 450
        \li M111
        \li Warning
451
        \li Do not use \c Object as a constructor
452
        \li
453 454

    \row
Tobias Hunger's avatar
Tobias Hunger committed
455 456
        \li M112
        \li Warning
457
        \li Do not use \c Array as a constructor
458
        \li
459 460

    \row
Tobias Hunger's avatar
Tobias Hunger committed
461 462
        \li M113
        \li Warning
463
        \li Do not use \c Function as a constructor
464
        \li
465 466

    \row
467 468 469 470
        \li M114
        \li Hint
        \li The \c function keyword and the opening parenthesis should be
            separated by a single space
471
        \li
472 473

    \row
474 475 476 477 478 479
        \li M115
        \li Warning
        \li Do not use stand-alone blocks
        \li Blocks do not affect variable scoping. Thus blocks that are not
            associated to \c if, \c while, etc. have no effect and should be
            avoided.
480 481

    \row
Tobias Hunger's avatar
Tobias Hunger committed
482 483 484
        \li M116
        \li Warning
        \li Do not use void expressions
485
        \li
486 487

    \row
Tobias Hunger's avatar
Tobias Hunger committed
488 489 490
        \li M117
        \li Warning
        \li Confusing pluses
491
        \li
492 493

    \row
Tobias Hunger's avatar
Tobias Hunger committed
494 495 496
        \li M119
        \li Warning
        \li Confusing minuses
497
        \li
498 499

    \row
Tobias Hunger's avatar
Tobias Hunger committed
500 501 502
        \li M121
        \li Hint
        \li Declare all function vars on a single line
503
        \li
504 505

    \row
Tobias Hunger's avatar
Tobias Hunger committed
506 507 508
        \li M123
        \li Hint
        \li Unnecessary parentheses
509
        \li
510

511
    \target m126
512
    \row
513 514 515 516 517 518 519 520
        \li M126
        \li Warning
        \li \c == and \c != may perform type coercion, use \c === or \c !== to
            avoid it
        \li The non-strict equality comparison is allowed to convert its
            arguments to a common type. That can lead to unexpected results such
            as \c {' \t\r\n' == 0} being true. Use the strict equality operators
            \c === and \c !== and be explicit about conversions you require.
521 522

    \row
523 524 525 526
        \li M127
        \li Warning
        \li Expression statements should be assignments, calls or delete
            expressions only
527
        \li
528

529 530 531 532 533 534
    \row
        \li M128
        \li Error
        \li A state cannot have the specified child item
        \li

535
    \row
Tobias Hunger's avatar
Tobias Hunger committed
536 537 538
        \li M201
        \li Hint
        \li Place var declarations at the start of a function
539
        \li
540 541

    \row
Tobias Hunger's avatar
Tobias Hunger committed
542 543 544
        \li M202
        \li Hint
        \li Use only one statement per line
545 546 547
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
548 549 550
        \li M203
        \li Warning
        \li Imperative code is not supported in the Qt Quick Designer
551 552 553
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
554 555 556
        \li M204
        \li Warning
        \li This QML type is not supported in the Qt Quick Designer
557 558
        \li
    \row
559 560 561 562
        \li M205
        \li Warning
        \li Reference to parent QML type cannot be resolved correctly by the Qt
            Quick Designer
563 564 565
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
566 567 568 569
        \li M206
        \li Warning
        \li This visual property binding cannot be evaluated in the local
            context and might not show up in Qt Quick Designer as expected
570 571 572
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
573 574 575
        \li M207
        \li Warning
        \li Qt Quick Designer only supports states in the root QML type
576
        \li
577

578
    \row
579 580
        \li M208
        \li Error
581 582 583 584 585 586
        \li This id might be ambiguous and is not supported in the \QMLD.
        \li

    \row
        \li M209
        \li Error
587
        \li This type (type name) is not supported as a root element by \QMLD.
588 589 590
        \li

    \row
591 592 593 594
        \li M220
        \li Error
        \li This type (type name) is not supported as a root element of a Qt
            Quick UI form.
595 596 597
        \li

    \row
598 599 600
        \li M221
        \li Error
        \li This type (type name) is not supported in a Qt Quick UI form.
601 602 603
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
604 605 606
        \li M222
        \li Error
        \li Functions are not supported in a Qt Quick UI form.
607 608 609
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
610 611 612
        \li M223
        \li Error
        \li Java Script blocks are not supported in a Qt Quick UI form.
613 614 615
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
616 617 618
        \li M224
        \li Error
        \li Behavior type is not supported in a Qt Quick UI form.
619 620 621
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
622 623 624
        \li M225
        \li Error
        \li States are only supported in the root item in a Qt Quick UI form.
625 626 627
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
628 629 630 631
        \li M226
        \li Error
        \li Referencing the parent of the root item is not supported in a Qt
            Quick UI form.
632 633
        \li

634
    \row
Tobias Hunger's avatar
Tobias Hunger committed
635 636 637
        \li M300
        \li Error
        \li Unknown component
638
        \li
639 640

    \row
Tobias Hunger's avatar
Tobias Hunger committed
641 642
        \li M301
        \li Error
643
        \li Could not resolve the prototype \c name of \c object
644
        \li
645 646

    \row
Tobias Hunger's avatar
Tobias Hunger committed
647 648
        \li M302
        \li Error
649
        \li Could not resolve the prototype \c name
650
        \li
651 652

    \row
Tobias Hunger's avatar
Tobias Hunger committed
653 654
        \li M303
        \li Error
655
        \li Prototype cycle, the last non-repeated component is \c name
656
        \li
657 658

    \row
Tobias Hunger's avatar
Tobias Hunger committed
659 660
        \li M304
        \li Error
661
        \li Invalid property type \c name
662
        \li
663
    \row
664 665 666 667 668
        \li M305
        \li Warning
        \li \c == and \c != perform type coercion, use \c === or \c !== to
            avoid it
        \li See \l{m126}{M126}.
669
    \row
670 671 672 673 674 675
        \li M306
        \li Warning
        \li Calls of functions that start with an uppercase letter should use
            \c new
        \li By convention, functions that start with an uppercase letter
            are constructor functions that should only be used with \c new.
676 677

    \row
678 679 680
        \li M307
        \li Warning
        \li Use \c new only with functions that start with an uppercase letter
681
        \li
682 683

    \row
Tobias Hunger's avatar
Tobias Hunger committed
684 685
        \li M308
        \li Warning
686
        \li Do not use \c Number as a constructor
687
        \li
688 689

    \row
Tobias Hunger's avatar
Tobias Hunger committed
690 691 692
        \li M309
        \li Hint
        \li Use spaces around binary operators
693
        \li
694 695

    \row
Tobias Hunger's avatar
Tobias Hunger committed
696 697 698
        \li M310
        \li Warning
        \li Unintentional empty block, use ({}) for empty object literal
699
        \li
700 701

    \row
702 703 704
        \li M311
        \li Hint
        \li Use \c type instead of \c var or \c variant to improve performance
705
        \li
706

707
    \row
Tobias Hunger's avatar
Tobias Hunger committed
708 709
        \li M312
        \li Error
710
        \li Missing property \c number
711 712 713
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
714 715 716
        \li M313
        \li Error
        \li Object value expected
717 718 719
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
720 721 722
        \li M314
        \li Error
        \li Array value expected
723 724 725
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
726 727
        \li M315
        \li Error
728
        \li \c Value value expected
729 730 731
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
732 733
        \li M316
        \li Error
734
        \li Maximum number value is \c number
735 736 737
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
738 739
        \li M317
        \li Error
740
        \li Minimum number value is \c number
741 742 743
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
744 745 746
        \li M318
        \li Error
        \li Maximum number value is exclusive
747 748 749
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
750 751 752
        \li M319
        \li Error
        \li Minimum number value is exclusive
753 754 755
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
756 757 758
        \li M320
        \li Error
        \li String value does not match required pattern
759 760 761
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
762 763
        \li M321
        \li Error
764
        \li Minimum string value length is \c number
765 766 767
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
768 769
        \li M322
        \li Error
770
        \li Maximum string value length is \c number
771 772 773
        \li

    \row
Tobias Hunger's avatar
Tobias Hunger committed
774 775
        \li M323
        \li Error
776
        \li \c Number elements expected in array value
777 778
        \li

779
    \row
780 781 782 783 784 785 786 787
        \li M324
        \li Warning
        \li Using Qt Quick 1 code model instead of Qt Quick 2
        \li The code model might be corrupt or the QML emulation layer might
            have been built with a different Qt version than the one selected in
            the build and run kit. For more information, see
            \l {Resetting the Code Model} and
            \l {Running QML Modules in Qt Quick Designer}.
788

789
    \endtable
790

791 792 793 794 795 796 797 798 799
    \section1 Resetting the Code Model

    If you change the build and run kit when you have QML files open in the code
    editor, the code model might become corrupt. The following error message
    indicates that this might have happened: \e{Using Qt Quick 1 code model
    instead of Qt Quick 2}.

    You can see the error message when you move the mouse pointer over code that
    \QC underlines in the code editor or when you open a QML file in the
800
    \uicontrol Design mode.
801

802 803
    To reset the code model, select \uicontrol Tools > \uicontrol {QML/JS} >
    \uicontrol {Reset Code Model}.
804 805 806 807

    If this does not help, try changing the QML emulation layer to the one that
    was built with the same Qt version as the one selected in the build and run
    kit. For more information, see \l{Running QML Modules in Qt Quick Designer}.
808 809 810 811 812 813

    \section1 Inspecting QML and JavaScript

    To inspect QML and JavaScript properties, methods, and enums, move the
    cursor over them and select \uicontrol Tools > \uicontrol {QML/JS} >
    \uicontrol {Inspect API for Element Under Cursor}.
814 815 816 817 818 819

    \section1 Automatically Formatting QML/JS Files

    To automatically format QML/JS files upon saving, select \uicontrol Tools >
    \uicontrol Options > \uicontrol {Qt Quick} > \uicontrol {QML/JS Editing} >
    \uicontrol {Enable auto format on file save}.
820 821 822 823
*/


/*!
824
    \contentspage {Qt Creator Manual}
825 826 827 828 829 830 831 832 833 834 835 836 837
    \previouspage creator-checking-code-syntax.html
    \page creator-completing-code.html
    \nextpage creator-indenting-code.html

    \title Completing Code

    As you write code, \QC suggests properties, IDs, and code snippets to
    complete the code. It provides a list of context-sensitive suggestions to
    the statement currently under your cursor. Press \key Tab
    or \key Enter to accept the selected suggestion and complete the code.

    \image qtcreator-codecompletion.png

Tobias Hunger's avatar
Tobias Hunger committed
838
    To open the list of suggestions at any time, press \key {Ctrl+Space}.
839 840
    If only one option is available, \QC inserts it automatically.

841 842 843 844 845
    When completion is invoked manually, \QC 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
    \uicontrol {Autocomplete common prefix} in the code completion preferences.
    Select \uicontrol Tools > \uicontrol Options > \uicontrol {Text Editor}
846
    > \uicontrol Completion.
847

848 849 850
    By default, code completion does not consider case. To apply full or
    first-letter case-sensitivity, select \uicontrol Full or
    \uicontrol {First Letter} in the \uicontrol {Case-sensitivity} field.
851 852 853

    \section2 Summary of Available Types

854 855
    The following table lists available types for code completion and icon used
    for each.
856 857 858

    \table
        \header
859 860
            \li  Icon
            \li  Description
861
        \row
862 863
            \li \inlineimage completion/class.png
            \li A class
864
        \row
865 866
            \li \inlineimage completion/enum.png
            \li An enum
867
        \row
868 869
            \li \inlineimage completion/enumerator.png
            \li An enumerator (value of an enum)
870
        \row
871 872
            \li \inlineimage completion/func.png
            \li A function
873
        \row
874 875
            \li \inlineimage completion/func_priv.png
            \li A private function
876
        \row
877 878
            \li \inlineimage completion/func_prot.png
            \li A protected function
879
        \row
880 881
            \li \inlineimage completion/var.png
            \li A variable
882
        \row
883 884
            \li \inlineimage completion/var_priv.png
            \li A private variable
885
        \row
886 887
            \li \inlineimage completion/var_prot.png
            \li A protected variable
888
        \row
889 890
            \li \inlineimage completion/signal.png
            \li A signal
891
        \row
892 893
            \li \inlineimage completion/slot.png
            \li A slot
894
        \row
895 896
            \li \inlineimage completion/slot_priv.png
            \li A private slot
897
        \row
898 899
            \li \inlineimage completion/slot_prot.png
            \li A protected slot
900
        \row
901 902
            \li \inlineimage completion/keyword.png
            \li A C++ keyword
903
        \row
904 905
            \li \inlineimage completion/snippet.png
            \li A C++ code snippet
906
        \row
907
            \li \inlineimage completion/element.png
908
            \li A QML type
909
        \row
910 911
            \li \inlineimage completion/qmlsnippet.png
            \li A QML code snippet
912
        \row
913 914
            \li \inlineimage completion/macro.png
            \li A macro
915
        \row
916 917
            \li \inlineimage completion/namespace.png
            \li A namespace
918 919 920 921
    \endtable

    \section2 Completing Code Snippets

922 923 924 925 926
    Code snippets can consist of multiple variables 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 variables and specify values for
    them. When you specify a value for a variable, all instances of the variable
    within the snippet are renamed.
927 928 929 930 931 932 933

    \image qmldesigner-code-completion.png "Completing QML code"

    \section2 Editing Code Snippets

    Code snippets specify C++ or QML code constructs. You can add, modify,
    and remove snippets in the snippet editor. To open the editor, select
934 935
    \uicontrol Tools > \uicontrol Options > \uicontrol {Text Editor} >
    \uicontrol Snippets.
936 937 938 939 940 941 942

    \image qtcreator-edit-code-snippets.png "Snippet options"

    \QC provides you with built-in snippets in the following categories:

    \list

943
        \li Text snippets, which can contain any text string. For example, code
944 945
            comments

946
        \li C++ code snippets, which specify C++ code constructs
947

948 949 950
        \li CMake code snippets that you can use when editing \c CMakeLists.txt
            files in the CMake editor

951
        \li QML code snippets, which specify QML code constructs
952

953 954
        \li Nim code snippets, which specify Nim code constructs

955 956 957 958 959
    \endlist

    \section3 Adding and Editing Snippets

    Select a snippet in the list to edit it in the snippet editor. To add a new
960 961 962
    snippet, select \uicontrol Add. Specify a trigger and, if the trigger is
    already in use, an optional variant, which appear in the list of suggestions
    when you write code. Also specify a text string or C++ or QML code construct
963 964
    in the snippet editor, depending on the snippet category. You can use
    \l{Using Qt Creator Variables}{predefined variables} in snippets.
965 966 967 968 969

    The snippet editor provides you with:

    \list

970
        \li Highlighting
971

972
        \li Indentation
973

974
        \li Parentheses matching
975

976
        \li Basic code completion
977 978 979 980 981

    \endlist

    Specify the variables for the snippets in the following format:

982 983 984 985 986 987 988 989 990 991 992 993
    \code
    $variable$
    \endcode

    Specify \QC variables in the following format:

    \code
    %{variable}
    \endcode

    For example, the following variable expands to the name of the current
    project: \c {%{CurrentProject:Name}}.
994 995 996 997

    Use unique variable names within a snippet, because all instances of a
    variable are renamed when you specify a value for it.

998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020
    To determine the case of values you enter in snippets, use the following
    modifiers:

    \list

        \li \c {:c} converts the initial letter of the string to upper case

        \li \c {:l} converts the string to lower case

        \li \c {:u} converts the string to upper case

    \endlist

    For example, add the following line to the \c class snippet to specify that
    the function name is converted to all lower case characters regardless of
    how you specify the value of the \c{$name$} variable:

    \code
        void $name:l$() {}
    \endcode

    \image qtcreator-snippet-modifiers.png

1021 1022 1023 1024
    The snippet editor does not check the syntax of the snippets that you edit
    or add. However, when you use the snippets, the code editor marks any
    errors by underlining them in red.