From 97c56225a719da43a9a6951effb2d152200106f4 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Thu, 23 Aug 2018 11:14:02 +0200 Subject: [PATCH] Doc: Move topics in creator-editors.qdoc to individual files To enable single-sourcing of the Qt Creator Manual and Qt Design Studio Manual. No content changes were made in this patch. Change-Id: I2bc1db22310bcef539d5961e728a565142c2e2d4 Reviewed-by: Eike Ziller --- doc/src/editors/creator-code-completion.qdoc | 249 ++ doc/src/editors/creator-code-indentation.qdoc | 247 ++ doc/src/editors/creator-code-refactoring.qdoc | 829 +++++ doc/src/editors/creator-code-syntax.qdoc | 698 ++++ doc/src/editors/creator-editors.qdoc | 3146 ----------------- doc/src/editors/creator-locator.qdoc | 403 +++ .../creator-only/creator-code-pasting.qdoc | 102 + .../editors/creator-only/creator-fakevim.qdoc | 228 ++ .../creator-text-editing-macros.qdoc | 59 + doc/src/editors/creator-search.qdoc | 272 ++ .../creator-semantic-highlighting.qdoc | 134 + 11 files changed, 3221 insertions(+), 3146 deletions(-) create mode 100644 doc/src/editors/creator-code-completion.qdoc create mode 100644 doc/src/editors/creator-code-indentation.qdoc create mode 100644 doc/src/editors/creator-code-refactoring.qdoc create mode 100644 doc/src/editors/creator-code-syntax.qdoc delete mode 100644 doc/src/editors/creator-editors.qdoc create mode 100644 doc/src/editors/creator-locator.qdoc create mode 100644 doc/src/editors/creator-only/creator-code-pasting.qdoc create mode 100644 doc/src/editors/creator-only/creator-fakevim.qdoc create mode 100644 doc/src/editors/creator-only/creator-text-editing-macros.qdoc create mode 100644 doc/src/editors/creator-search.qdoc create mode 100644 doc/src/editors/creator-semantic-highlighting.qdoc diff --git a/doc/src/editors/creator-code-completion.qdoc b/doc/src/editors/creator-code-completion.qdoc new file mode 100644 index 00000000000..f99d42c7747 --- /dev/null +++ b/doc/src/editors/creator-code-completion.qdoc @@ -0,0 +1,249 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** 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. +** +****************************************************************************/ + +/*! + \contentspage index.html + \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 + + To open the list of suggestions at any time, press \key {Ctrl+Space}. + If only one option is available, \QC inserts it automatically. + + 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} + > \uicontrol Completion. + + 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. + + \section2 Summary of Available Types + + The following table lists available types for code completion and icon used + for each. + + \table + \header + \li Icon + \li Description + \row + \li \inlineimage completion/class.png + \li A class + \row + \li \inlineimage completion/enum.png + \li An enum + \row + \li \inlineimage completion/enumerator.png + \li An enumerator (value of an enum) + \row + \li \inlineimage completion/func.png + \li A function + \row + \li \inlineimage completion/func_priv.png + \li A private function + \row + \li \inlineimage completion/func_prot.png + \li A protected function + \row + \li \inlineimage completion/var.png + \li A variable + \row + \li \inlineimage completion/var_priv.png + \li A private variable + \row + \li \inlineimage completion/var_prot.png + \li A protected variable + \row + \li \inlineimage completion/signal.png + \li A signal + \row + \li \inlineimage completion/slot.png + \li A slot + \row + \li \inlineimage completion/slot_priv.png + \li A private slot + \row + \li \inlineimage completion/slot_prot.png + \li A protected slot + \row + \li \inlineimage completion/keyword.png + \li A C++ keyword + \row + \li \inlineimage completion/snippet.png + \li A C++ code snippet + \row + \li \inlineimage completion/element.png + \li A QML type + \row + \li \inlineimage completion/qmlsnippet.png + \li A QML code snippet + \row + \li \inlineimage completion/macro.png + \li A macro + \row + \li \inlineimage completion/namespace.png + \li A namespace + \endtable + + \section2 Completing Code Snippets + + 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. + + \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 + \uicontrol Tools > \uicontrol Options > \uicontrol {Text Editor} > + \uicontrol Snippets. + + \image qtcreator-edit-code-snippets.png "Snippet options" + + \QC provides you with built-in snippets in the following categories: + + \list + + \li Text snippets, which can contain any text string. For example, code + comments + + \li C++ code snippets, which specify C++ code constructs + + \li CMake code snippets that you can use when editing \c CMakeLists.txt + files in the CMake editor + + \li QML code snippets, which specify QML code constructs + + \li Nim code snippets, which specify Nim code constructs + + \endlist + + \section3 Adding and Editing Snippets + + Select a snippet in the list to edit it in the snippet editor. To add a new + 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 + in the snippet editor, depending on the snippet category. You can use + \l{Using Qt Creator Variables}{predefined variables} in snippets. + + The snippet editor provides you with: + + \list + + \li Highlighting + + \li Indentation + + \li Parentheses matching + + \li Basic code completion + + \endlist + + Specify the variables for the snippets in the following format: + + \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}}. + + Use unique variable names within a snippet, because all instances of a + variable are renamed when you specify a value for it. + + 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 + + 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. + + To discard the changes you made to a built-in snippet, select + \uicontrol {Revert Built-in}. + + \section3 Removing Snippets + + Several similar built-in snippets might be provided for different use cases. + To make the list of suggestions shorter when you write code, remove the + built-in snippets that you do not need. If you need them later, you can + restore them. + + To remove snippets, select a snippet in the list, and then select + \uicontrol Remove. To restore the removed snippets, select + \uicontrol {Restore Removed Built-ins}. + + \section3 Resetting Snippets + + To remove all added snippets and to restore all removed snippets, select + \uicontrol {Reset All}. + + \note If you now select \uicontrol OK or \uicontrol Apply, you permanently + lose all your own snippets. +*/ diff --git a/doc/src/editors/creator-code-indentation.qdoc b/doc/src/editors/creator-code-indentation.qdoc new file mode 100644 index 00000000000..2075b2e41b4 --- /dev/null +++ b/doc/src/editors/creator-code-indentation.qdoc @@ -0,0 +1,247 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** 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. +** +****************************************************************************/ + +/*! + \contentspage index.html + \previouspage creator-completing-code.html + \page creator-indenting-code.html + \nextpage qt-quick-toolbars.html + + \title Indenting Text or Code + + When you type text or code, it is indented automatically according to the + selected text editor or code style options. Select a block to indent it when + you press \key Tab. Press \key {Shift+Tab} to decrease the indentation. You + can disable automatic indentation. + + You can specify indentation for: + + \list + \li C++ files + \li QML files + \li Nim files + \li Other text files + \endlist + + You can also specify indentation separately for each project. You can + specify several sets of code style settings and easily switch between them. + In addition, you can import and export code style settings. + + \section1 Indenting C++ Files + + To specify indentation settings for the C++ editor: + + \list 1 + \li Select \uicontrol Tools > \uicontrol Options > \uicontrol {C++}. + \li In the \uicontrol {Current settings} field, select the settings to + modify and click \uicontrol Copy. + \image qtcreator-options-code-style-cpp.png "C++ Code Style options" + \li Give a name to the settings and click \uicontrol OK. + \li Click \uicontrol Edit to specify code style settings for the project. + \image qtcreator-code-style-settings-edit-cpp.png "Edit Code Style Settings dialog" + \endlist + + You can specify how to: + + \list + \li Interpret the \key Tab and \key Backspace key presses. + \li Indent the contents of classes, functions, blocks, and namespaces. + \li Indent braces in classes, namespaces, enums, functions, and blocks. + \li Control switch statements and their contents. + \li Align continuation lines. + \li Bind pointers (*) and references (&) in types and declarations to + identifiers, type names, or left or right \c const or \c volatile + keywords. + \li Name getter functions. + \endlist + + You can use the live preview to see how the options change the indentation. + + To specify different settings for a particular project, select + \uicontrol Projects > \uicontrol {Code Style Settings}. + + \section1 Indenting QML Files + + To specify settings for the Qt Quick editor: + + \list 1 + \li Select \uicontrol Tools > \uicontrol Options > + \uicontrol {Qt Quick}. + \li In the \uicontrol {Current settings} field, select the settings to + modify and click \uicontrol Copy. + \image qtcreator-options-code-style-qml.png "QML Code Style options" + \li Give a name to the settings and click \uicontrol OK. + \li Click \uicontrol Edit to specify code style settings for the project. + \image qtcreator-code-style-settings-edit-qtquick.png "Edit Code Style Settings dialog" + \endlist + + You can specify how to interpret the \key Tab key presses and how to align + continuation lines. + + To specify different settings for a particular project, select + \uicontrol Projects > \uicontrol {Code Style Settings}. + + \section1 Indenting Nim Files + + To specify settings for the Nim editor (experimental): + + \list 1 + \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Nim. + \li In the \uicontrol {Current settings} field, select the settings to + modify and click \uicontrol Copy. + \image qtcreator-options-code-style-nim.png "Nim Code Style options" + \li Give a name to the settings and click \uicontrol OK. + \li Click \uicontrol Edit to specify code style settings for the project. + \image qtcreator-code-style-settings-edit-nim.png "Edit Code Style Settings dialog" + \endlist + + You can specify how to interpret the \key Tab key presses and how to align + continuation lines. + + To specify different settings for a particular project, select + \uicontrol Projects > \uicontrol {Code Style}. + + \section1 Indenting Other Text Files + + To specify indentation settings for text files that do not contain C++ or + QML code (such as Python code files), select \uicontrol Tools > + \uicontrol Options > \uicontrol {Text Editor} > \uicontrol Behavior. + + \image qtcreator-indentation.png "Text Editor Behavior options" + + To specify different settings for a particular project, select + \uicontrol Projects > \uicontrol Editor. + + You can specify how to interpret the \key Tab and \key Backspace key + presses and how to align continuation lines. + + \section1 Specifying Tab Settings + + You can specify tab settings at the following levels: + + \list + \li For all C++ files + \li For all QML files + \li For all other text files + \li For C++ files in a project + \li For QML files in a project + \li For other text files in a project + \endlist + + \section2 Specifying Tabs and Indentation + + You can specify tab policy and tab size in the + \uicontrol {Tabs and Indentation} group. In the \uicontrol {Tab policy} + field, select whether to use only spaces or only tabs for indentation, + or to use a mixture of them. + + By default, the tab length in code editor is 8 spaces and the indent size is + 4 spaces. You can specify the tab length and indent size separately for each + project and for different types of files. + + You can have continuation lines aligned with the previous line. In the + \uicontrol {Align continuation lines} field, select + \uicontrol {Not at all} to disable automatic alignment and indent + continuation lines to the logical depth. To always use spaces for alignment, + select \uicontrol {With Spaces}. To follow the \uicontrol {Tab policy}, + select \uicontrol {With Regular Indent}. + + \section2 Specifying Typing Options + + When you type text or code, it is indented automatically according to the + selected text editor or code style options. Specify typing options in the + \uicontrol Typing group. To disable automatic indentation, deselect the + \uicontrol {Enable automatic indentation} check box. + + You can specify how the indentation is decreased when you press + \uicontrol Backspace in the \uicontrol {Backspace indentation} field. To go + back one space at a time, select \uicontrol None. To decrease indentation + in leading white space by one level, select + \uicontrol {Follows Previous Indents}. To move back one tab length if the + character to the left of the cursor is a space, select + \uicontrol Unindents. + + You can specify whether the \key Tab key automatically indents text when you + press it. To automatically indent text, select \uicontrol Always in the + \uicontrol {Tab key performs auto-indent} field. To only indent text when + the cursor is located within leading white space, select \uicontrol {In + Leading White Space}. + + \section1 Specifying Settings for Content + + You can indent public, protected, and private statements and declarations + related to them within classes. + + You can also indent statements within functions and blocks and declarations + within namespaces. + + \image qtcreator-code-style-content.png "Content options" + + \section1 Specifying Settings for Braces + + You can indent class, namespace, enum and function declarations and code + blocks. + + \image qtcreator-code-style-braces.png "Braces options" + + \section1 Specifying Settings for Switch Statements + + You can indent case or default statements, or statements or blocks related + to them within switch statements. + + \image qtcreator-code-style-switch.png "Switch options" + + \section1 Specifying Alignment + + To align continuation lines to tokens after assignments, such as \c = or + \c +=, select the \uicontrol {Align after assignments} check box. You can + specify additional settings for aligning continuation lines in the + \uicontrol General tab. + + You can also add spaces to conditional statements, so that they are not + aligned with the following line. Usually, this only affects \c if + statements. + + \image qtcreator-code-style-alignment.png "Alignment options" + + \section1 Binding Pointers and References + + To bind pointers (\c *) and references (\c &) in types and declarations to + identifiers, type names, or left or right \c const or \c volatile keywords, + select the check boxes in the \uicontrol {Pointers and References} tab. + + The \c * and \c & characters are automatically bound to identifiers of + pointers to functions and pointers to arrays. + + \image qtcreator-pointers-references.png "Pointers and References options" + + \section1 Naming Getters + + To prefer getter names without the string \e get, select the + \uicontrol {Prefer getter names without "get"} check box in the + \uicontrol {Getter and Setter} tab. + + \image qtcreator-code-style-getter-setter.png +*/ diff --git a/doc/src/editors/creator-code-refactoring.qdoc b/doc/src/editors/creator-code-refactoring.qdoc new file mode 100644 index 00000000000..5fe8c024a23 --- /dev/null +++ b/doc/src/editors/creator-code-refactoring.qdoc @@ -0,0 +1,829 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** 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. +** +****************************************************************************/ + +/*! + \contentspage index.html + \previouspage creator-editor-locator.html + \page creator-editor-refactoring.html + \nextpage creator-beautifier.html + + \title Refactoring + + Refactor code to: + + \list + \li Improve internal quality of your application + \li Improve performance and extensibility + \li Improve code readability and maintainability + \li Simplify code structure + \endlist + + \section1 Finding Symbols + + To find the use of a specific symbol or \l{glossary-component} + {QML component} in your Qt C++ or Qt Quick project: + + \list 1 + \li In the editor, place the cursor on the symbol or component, and + select: + \list + \li \uicontrol Tools > \uicontrol {C++} > \uicontrol {Find Usages} + \li \uicontrol Tools > \uicontrol {QML/JS} > + \uicontrol {Find Usages} + \li \key {Ctrl+Shift+U} + \endlist + \QC looks for the symbol in the following locations: + \list + \li Files listed as a part of the project + \li Files directly used by the project files (for example, generated + files) + \li Header files of used frameworks and libraries + \endlist + \note You can also select \uicontrol Edit > \uicontrol {Find/Replace} > + \uicontrol {Advanced Find} > \uicontrol {C++ Symbols} to search for + classes, functions, enums, and declarations either from files listed as + part of the project or from all files that are used by the code, such as + include files. + \image qtcreator-search-cpp-symbols.png + \li The \uicontrol {Search Results} pane opens and shows the location + and number of instances of the symbol in the current project. + \image qtcreator-refactoring-find.png + \endlist + + You can browse the search results in the following ways: + + \list + \li To go directly to an instance, double-click the instance in the + \uicontrol {Search Results} pane. + \li To move between instances, click the \inlineimage next.png + (\uicontrol {Next Item}) button and \inlineimage prev.png + (\uicontrol {Previous Item}) button in the + \uicontrol {Search Results} pane. + \li To expand and collapse the list of all instances, click the + \inlineimage qtcreator-expand.png + (\uicontrol {Expand All}) button. + \li To clear the search results, click the + \inlineimage clean_pane_small.png + (\uicontrol Clear) button. + \li To start a new search, click the + \inlineimage qtcreator-new-search-icon.png + (\uicontrol {New Search}) button. + \endlist + + \section1 Renaming Symbols + + You can rename symbols in all files in a project. When you rename a class, + you can also change filenames that match the class name. + + To rename a specific symbol in a Qt project: + + \list 1 + \li In the editor, place the cursor on the symbol you would like to + change and select \uicontrol Tools > \uicontrol {C++} > + \uicontrol {Rename Symbol Under Cursor} or + \uicontrol Tools > \uicontrol {QML/JS} > + \uicontrol {Rename Symbol Under Cursor}. Alternatively, press + \key {Ctrl+Shift+R}. + + The \uicontrol {Search Results} pane opens and shows the location + and number of instances of the symbol in the current project. + \image qtcreator-refactoring-replace.png + \li To replace all selected instances, enter the name of the new symbol + in the \uicontrol {Replace with} text box. + + To omit an instance, uncheck the check-box next to the instance. + \li If the symbol is a class, select the \uicontrol {Rename files} check + box to also change the filenames that match the class name. + \li Select \uicontrol Replace. + \note This action replaces all selected instances of the symbol in + all files listed in the \uicontrol {Search Results} pane. You cannot + undo this action. + \endlist + + \note Renaming local symbols does not open the \uicontrol {Search Results} + pane. The instances of the symbol are highlighted in code and you can edit + the symbol. All instances of the local symbol are changed as you type. + + \section1 Column Editing + + To apply a change to several rows in a column simultaneously, press + \key Alt, select the rows, and enter or remove text. The changes are made + simultaneously at the cursor position on all the selected rows. + + \section1 Applying Refactoring Actions + + \QC allows you to quickly and conveniently apply actions to refactor your + code by selecting them in a context menu. The actions available depend on + the position of the cursor in the code editor and on whether you are writing + C++ or QML code. + + To apply refactoring actions to C++ code, right-click an operand, + conditional statement, string, or name to open a context menu. In QML code, + click an item ID or name. + + In the context menu, select \uicontrol {Refactoring} and then select a + refactoring action. + + You can also press \key {Alt+Enter} to open a context menu that contains + refactoring actions available in the current cursor position. + + If you use the \l{Parsing C++ Files with the Clang Code Model} + {Clang code model} to parse the C++ files, the + \l{http://clang.llvm.org/diagnostics.html}{Clang fix-it hints} + that have been integrated into \QC are also available to you. In addition to + the standard ways of activating refactoring actions, you can select the + actions that are applicable on a line in the context menu in the left margin + of the code editor. + + \section2 Refactoring C++ Code + + You can apply the following types of refactoring actions to C++ code: + + \list + \li Change binary operands + \li Simplify if and while conditions (for example, move declarations out + of if conditions) + \li Modify strings (for example, set the encoding for a string to + Latin-1, mark strings translatable, and convert symbol names to + camel case) + \li Create variable declarations + \li Create function declarations and definitions + \endlist + + The following table summarizes the refactoring actions for C++ code. The + action is available when the cursor is in the position described in the + Activation column. + + \table + \header + \li Refactoring Action + \li Description + \li Activation + \row + \li Add Curly Braces + \li Adds curly braces to an if statement that does not contain a + compound statement. For example, rewrites + + \code + if (a) + b; + \endcode + + as + + \code + if (a) { + b; + } + \endcode + \li \c if + \row + \li Move Declaration out of Condition + \li Moves a declaration out of an if or while condition to simplify + the condition. For example, rewrites + + \code + if (Type name = foo()) {} + \endcode + + as + + \code + Type name = foo; + if (name) {} + \endcode + \li Name of the introduced variable + \row + \li Rewrite Condition Using || + \li Rewrites the expression according to De Morgan's laws. For + example, rewrites: + \code + !a && !b + \endcode + + as + + \code + !(a || b) + \endcode + \li \c && + \row + \li Rewrite Using \e operator + \li Rewrites an expression negating it and using the inverse + operator. For example, rewrites: + + \list + + \li \code + a op b + \endcode + + as + + \code + !(a invop b) + \endcode + + \li \code + (a op b) + \endcode + + as + + \code + !(a invop b) + \endcode + + \li \code + !(a op b) + \endcode + + as + + \code + (a invob b) + \endcode + + \endlist + + \li \c {<=}, \c {<}, \c {>}, \c {>=}, \c {==} or \c {!=} + \row + \li Split Declaration + \li Splits a simple declaration into several declarations. For + example, rewrites: + \code + int *a, b; + \endcode + + as + + \code + int *a; + int b; + \endcode + \li Type name or variable name + \row + \li Split if Statement + \li Splits an if statement into several statements. For example, + rewrites: + + \code + if (something && something_else) { + } + \endcode + + as + + \code + if (something) { + if (something_else) { + } + } + \endcode + + and + + \code + if (something || something_else) + x; + \endcode + + with + + \code + if (something) + x; + else if (something_else) + x; + \endcode + + \li \c && or \c || + \row + \li Swap Operands + \li Rewrites an expression in the inverse order using the inverse + operator. For example, rewrites: + \code + a op b + \endcode + + as + \code + b flipop a + \endcode + \li \c {<=}, \c {<}, \c {>}, \c {>=}, \c {==}, \c {!=}, \c {&&} + or \c {||} + \row + \li Convert to Decimal + \li Converts an integer literal to decimal representation + \li Numeric literal + \row + \li Convert to Hexadecimal + \li Converts an integer literal to hexadecimal representation + \li Numeric literal + \row + \li Convert to Octal + \li Converts an integer literal to octal representation + \li Numeric literal + \row + \li Convert to Objective-C String Literal + \li Converts a string literal to an Objective-C string literal if + the file type is Objective-C(++). For example, rewrites the + following strings + + \code + "abcd" + QLatin1String("abcd") + QLatin1Literal("abcd") + \endcode + + as + + \code + @"abcd" + \endcode + \li String literal + \row + \li Enclose in QLatin1Char() + \li Sets the encoding for a character to Latin-1, unless the + character is already enclosed in QLatin1Char, QT_TRANSLATE_NOOP, + tr, trUtf8, QLatin1Literal, or QLatin1String. For example, + rewrites + + \code + 'a' + \endcode + + as + + \code + QLatin1Char('a') + \endcode + \li String literal + \row + \li Enclose in QLatin1String() + \li Sets the encoding for a string to Latin-1, unless the string is + already enclosed in QLatin1Char, QT_TRANSLATE_NOOP, tr, trUtf8, + QLatin1Literal, or QLatin1String. For example, rewrites + \code + "abcd" + \endcode + + as + + \code + QLatin1String("abcd") + \endcode + + \li String literal + + \row + \li Mark as Translatable + \li Marks a string translatable. For example, rewrites \c "abcd" + with one of the following options, depending on which of them is + available: + + \code + tr("abcd") + QCoreApplication::translate("CONTEXT", "abcd") + QT_TRANSLATE_NOOP("GLOBAL", "abcd") + \endcode + + \li String literal + + \row + \li Add Definition in ... + \li Inserts a definition stub for a function declaration either in + the header file (inside or outside the class) or in the + implementation file. For free functions, inserts the definition + after the declaration of the function or in the implementation + file. Qualified names are minimized when possible, instead of + always being fully expanded. + + For example, rewrites + + \code + Class Foo { + void bar(); + }; + \endcode + + as (inside class) + + \code + Class Foo { + void bar() { + + } + }; + \endcode + + as (outside class) + + \code + Class Foo { + void bar(); + }; + + void Foo::bar() + { + + } + \endcode + + as (in implementation file) + + \code + // Header file + Class Foo { + void bar(); + }; + + // Implementation file + void Foo::bar() + { + + } + \endcode + + \li Function name + \row + \li Add \c Function Declaration + \li Inserts the member function declaration that matches the member + function definition into the class declaration. The function can + be \c {public}, \c {protected}, \c {private}, \c {public slot}, + \c {protected slot}, or \c {private slot}. + \li Function name + \row + \li Switch with Next/Previous Parameter + \li Moves a parameter down or up one position in a parameter list. + \li Parameter in the declaration or definition of a function + \row + \li Extract Function + \li Moves the selected code to a new function and replaces the block + of code with a call to the new function. Enter a name for the + function in the \uicontrol {Extract Function Refactoring} + dialog. + \li Block of code selected + \row + \li Extract Constant as Function Parameter + \li Replaces the selected literal and all its occurrences with the + function parameter \c{newParameter}. The parameter + \c{newParameter} will have the original literal as the default + value. + \li Block of code selected + \row + \li Add Local Declaration + \li Adds the type of an assignee, if the type of the right-hand + side of the assignment is known. For example, rewrites + + \code + a = foo(); + \endcode + + as + + \code + Type a = foo(); + \endcode + + where Type is the return type of \c {foo()} + + \li Assignee + + \row + \li Convert to Camel Case + \li Converts a symbol name to camel case, where elements of the name + are joined without delimiter characters and the initial + character of each element is capitalized. For example, rewrites + \c an_example_symbol as \c anExampleSymbol and + \c AN_EXAMPLE_SYMBOL as \c AnExampleSymbol + \li Identifier + \row + \li Complete Switch Statement + \li Adds all possible cases to a switch statement of the type + \c enum + \li \c switch + \row + \li Generate Missing Q_PROPERTY Members + \li Adds missing members to a \c Q_PROPERTY: + \list + \li \c read function + \li \c write function, if there is a WRITE + \li \c {onChanged} signal, if there is a NOTIFY + \li data member with the name \c {m_} + \endlist + \li \c Q_PROPERTY + \row + \li Apply Changes + \li Keeps function declarations and definitions synchronized by + checking for the matching declaration or definition when you + edit a function signature and by applying the changes to the + matching code. + \li Function signature. When this action is available, a light bulb + icon appears: \inlineimage refactormarker.png + \row + \li Add #include for undeclared or forward declared identifier + \li Adds an \c {#include} directive to the current file to make the + definition of a symbol available. + \li Undeclared identifier + \row + \li Reformat Pointers or References + \li Reformats declarations with pointers or references according + to the code style settings for the current project. In case no + project is open, the current global code style settings are + used. + + For example, rewrites: + + \code + char*s; + \endcode + + as + + \code + char *s; + \endcode + + When applied to selections, all suitable declarations in the + selection are rewritten. + + \li Declarations with pointers or references and selections + containing such declarations + \row + \li Create Getter and Setter Member Functions + \li Creates either both getter and setter member functions for + member variables or only a getter or setter. + \li Member variable in class definition + \row + \li Move Function Definition + \li Moves a function definition to the implementation file, outside + the class or back to its declaration. For example, rewrites: + \code + class Foo + { + void bar() + { + // do stuff here + } + }; + \endcode + + as + \code + class Foo + { + void bar(); + }; + + void Foo::bar() { + // do stuff here + } + \endcode + + \li Function signature + \row + \li Move All Function Definitions + \li Moves all function definitions to the implementation file or + outside the class. For example, rewrites: + \code + class Foo + { + void bar() + { + // do stuff here + } + void baz() + { + // do stuff here + } + }; + \endcode + + as + + \code + class Foo + { + void bar(); + void baz(); + }; + + void Foo::bar() { + // do stuff here + } + + void Foo::baz() { + // do stuff here + } + \endcode + + \li Class name + \row + \li Assign to Local Variable + \li Adds a local variable which stores the return value of a + function call or a new expression. For example, rewrites: + + \code + QString s; + s.toLatin1(); + \endcode + + as + + \code + QString s; + QByteArray latin1 = s.toLatin1(); + \endcode + + and + + \code + new Foo; + \endcode + + as + + \code + Foo * localFoo = new Foo; + \endcode + + \li Function call or class name + \row + \li Insert (Pure) Virtual Functions + \li Select an insertion mode: + \list + \li Insert only declarations. + \li Insert declarations and the corresponding definitions inside the class. + \li Insert declarations and the corresponding definitions outside the class. + \li Insert declarations and the corresponding definitions in the implementation file + (only if an implementation file exists). + \endlist + \image qtcreator-refactoring-virtual-function-dialog.png + + \li Class or base class name + \row + \li Optimize for-Loop + \li Rewrites post increment operators as pre increment operators and + post decrement operators as pre decrement operators. It also + moves other than string or numeric literals and id expressions + from the condition of a for loop to its initializer. For + example, rewrites: + + \code + for (int i = 0; i < 3 * 2; i++) + \endcode + + as + + \code + for (int i = 0, total = 3 * 2; i < total; ++i) + \endcode + \li \c for + + \row + \li Escape String Literal as UTF-8 + \li Escapes non-ASCII characters in a string literal to hexadecimal + escape sequences. String Literals are handled as UTF-8. + \li String literal + + \row + \li Unescape String Literal as UTF-8 + \li Unescapes octal or hexadecimal escape sequences in a string + literal. String Literals are handled as UTF-8. + \li String literal + + \row + \li Convert to Stack Variable + \li Converts the selected pointer to a stack variable. For example, + rewrites: + + \code + QByteArray *foo = new QByteArray("foo"); + foo->append("bar"); + \endcode + + as + + \code + QByteArray foo = "foo"; + foo.append("bar"); + \endcode + + This operation is limited to work only within function scope. + Also, the coding style for pointers and references is not + respected yet. + \li Pointer Variable + + \row + \li Convert to Pointer + \li Converts the selected stack variable to a pointer. For example, + rewrites: + + \code + QByteArray foo = "foo"; + foo.append("bar"); + \endcode + + as + + \code + QByteArray *foo = new QByteArray("foo"); + foo->append("bar"); + \endcode + + This operation is limited to work only within function scope. + Also, the coding style for pointers and references is not + respected yet. + \li Stack Variable + \row + \li Convert connect() to Qt 5 Style + \li Converts a Qt 4 QObject::connect() to Qt 5 style. + \li QObject::connect() (Qt 4 style) + \endtable + + \section2 Refactoring QML Code + + You can apply the following types of refactoring actions to QML code: + + \list + \li Rename IDs + \li Split initializers + \li Move a QML type into a separate file to reuse it in other .qml files + \endlist + + The following table summarizes the refactoring actions for QML code. The + action is available when the cursor is in the position described in the + Activation column. + + \table + \header + \li Refactoring Action + \li Description + \li Activation + + \row + \li Move Component into Separate File + \li Moves a QML type into a separate file. Give the new component a + name and select whether properties are set for the new component + or for the original one. + + \image qtcreator-move-component-into-separate-file.png + + \li QML type name. This action is also available in the + \uicontrol {Form Editor} in the Design mode. + \row + \li Split Initializer + \li Reformats a one-line type into a multi-line type. For example, + rewrites + + \code + Item { x: 10; y: 20; width: 10 } + \endcode + + as + + \code + Item { + x: 10; + y: 20; + width: 10 + } + \endcode + + \li QML type property + \row + \li Wrap Component in Loader + \li Wraps the type in a Component type and loads it dynamically in a + Loader type. This is usually done to improve startup time. + \li QML type name + \row + \li Add a message suppression comment + \li Prepends the line with an annotation comment that stops the + message from being generated. + \li Error, warning or hint from static analysis + + \endtable + */ diff --git a/doc/src/editors/creator-code-syntax.qdoc b/doc/src/editors/creator-code-syntax.qdoc new file mode 100644 index 00000000000..4373891018c --- /dev/null +++ b/doc/src/editors/creator-code-syntax.qdoc @@ -0,0 +1,698 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** 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. +** +****************************************************************************/ + +/*! + \contentspage index.html + \previouspage creator-highlighting.html + \page creator-checking-code-syntax.html + \nextpage creator-completing-code.html + + \title Checking Code Syntax + + As you write code, \QC checks code syntax. When \QC spots a syntax error in + your code it underlines it and shows error details when you move the mouse + 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. + + \list + \li Syntax errors are underlined in red. + + In the following figure, a semicolon is missing at the end of the + line. + \image qtcreator-syntaxerror.png + \li Semantic errors and warnings are underlined in olive. + + In the following figure, the variable is not used. + \image qtcreator-semanticerror.png + \endlist + + 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 {Line annotations}, 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. Showing annotations + between lines can be useful if there is usually not enough space to + display annotations next to the text. + + If you hide the annotations by deselecting the check box, you can move the + mouse pointer over an icon to view them. + + \section1 Checking JSON Data Structure + + You can run static checks on the QML and JavaScript code in + your project to find common problems. + + \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}. + However, \QC does not understand the entire specification. + + 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. + + The specification does not define how to map JSON instances with JSON + schemas. \QC looks for a JSON schema file with a name that matches the + name of the JSON instance file in the user configuration folder. For + example, \c {~/config/QtProject/qtcreator/json} on Linux and \macos and + \c {C:\Users\username\AppData\Roaming\QtCreator\qtcreator\json} on + Windows. To check JSON data structure, copy the JSON schema file to the + above folder. + + \section2 Checking JavaScript and QML Syntax + + 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. + + \section2 List of JavaScript and QML Checks + + Many of the JavaScript checks are similar to the ones in Douglas Crockford's + \l{http://www.jslint.com}{JSLint} tool. For more information about JSLint + errors, see \l{http://linterrors.com/js}{JSLint Error Explanations}. + + \table + \header + \li Id + \li Severity + \li Message + \li Description + + \row + \li M1 + \li Error + \li Invalid value for enum + \li + + \row + \li M2 + \li Error + \li Enum value must be a string or a number + \li + + \row + \li M3 + \li Error + \li Number value expected + \li + + \row + \li M4 + \li Error + \li Boolean value expected + \li + + \row + \li M5 + \li Error + \li String value expected + \li + + \row + \li M6 + \li Error + \li Invalid URL + \li + + \row + \li M7 + \li Warning + \li File or directory does not exist + \li + + \row + \li M8 + \li Error + \li Invalid color + \li + + \row + \li M9 + \li Error + \li Anchor line expected + \li + + \row + \li M10 + \li Error + \li Duplicate property binding + \li See also: \l{http://linterrors.com/js/duplicate-key-a} + {Duplicate key '{a}'}. + + \row + \li M11 + \li Error + \li Id expected + \li See also: + \l{http://linterrors.com/js/expected-an-identifier-and-instead-saw-a-a-reserved-word} + {Expected an identifier and instead saw '{a}' (a reserved word)}. + + \row + \li M14 + \li Error + \li Invalid id + \li See also: + \l{http://linterrors.com/js/expected-an-identifier-and-instead-saw-a-a-reserved-word} + {Expected an identifier and instead saw '{a}' (a reserved word)}. + + + \row + \li M15 + \li Error + \li Duplicate id + \li Ids in a file must be unique. + See also: \l{http://linterrors.com/js/duplicate-key-a} + {Duplicate key '{a}'}. + + \row + \li M16 + \li Error + \li Invalid property name \c name + \li + + \row + \li M17 + \li Error + \li \c Name does not have members + \li + + \row + \li M18 + \li Error + \li \c Field is not a member of \c object + \li + + \row + \li M19 + \li Warning + \li Assignment in condition + \li It could be a typing error. If it is intentional, wrap the + assignment in parentheses. + + \row + \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. + + \row + \li M23 + \li Warning + \li Do not use \c eval + \li See also: \l{http://linterrors.com/js/eval-is-evil}{eval is evil}. + + \row + \li M28 + \li Warning + \li Unreachable + \li Indicates that the underlined statement will never be executed. + + \row + \li M29 + \li Warning + \li Do not use \c with + \li See also: \l{http://linterrors.com/js/unexpected-with} + {Unexpected 'with'}. + + \row + \li M30 + \li Warning + \li Do not use comma expressions + \li + + \row + \li M31 + \li Warning + \li Unnecessary message suppression + \li + + \row + \li M103 + \li Warning + \li \c Name is already a formal parameter + \li + + \row + \li M104 + \li Warning + \li \c Name is already a function + \li + + \row + \li M105 + \li Warning + \li Var \c name is used before its declaration + \li + + \row + \li M106 + \li Warning + \li \c Name is already a var + \li + + \row + \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. + + \row + \li M108 + \li Warning + \li Function \c name is used before its declaration + \li See also: \l{http://linterrors.com/js/a-was-used-before-it-was-defined} + {{a} was used before it was defined}. + + \row + \li M109 + \li Warning + \li Do not use \c Boolean as a constructor + \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} + {Do not use {a} as a constructor}. + + \row + \li M110 + \li Warning + \li Do not use \c String as a constructor + \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} + {Do not use {a} as a constructor}. + + \row + \li M111 + \li Warning + \li Do not use \c Object as a constructor + \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} + {Do not use {a} as a constructor}. + + \row + \li M112 + \li Warning + \li Do not use \c Array as a constructor + \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} + {Do not use {a} as a constructor}. + + \row + \li M113 + \li Warning + \li Do not use \c Function as a constructor + \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} + {Do not use {a} as a constructor}. + + \row + \li M114 + \li Hint + \li The \c function keyword and the opening parenthesis should be + separated by a single space + \li See also: \l{http://linterrors.com/js/expected-exactly-one-space-between-a-and-b} + {Expected exactly one space between {a} and {b}}. + + \row + \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. + + \row + \li M116 + \li Warning + \li Do not use void expressions + \li + + \row + \li M117 + \li Warning + \li Confusing pluses + \li See also: \l{http://linterrors.com/js/confusing-pluses} + {Confusing pluses}. + + \row + \li M119 + \li Warning + \li Confusing minuses + \li See also: \l{http://linterrors.com/js/confusing-minuses} + {Confusing minuses}. + + \row + \li M121 + \li Hint + \li Declare all function vars on a single line + \li + + \row + \li M123 + \li Hint + \li Unnecessary parentheses + \li + + \target m126 + \row + \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. + + \row + \li M127 + \li Warning + \li Expression statements should be assignments, calls or delete + expressions only + \li + + \row + \li M128 + \li Error + \li A state cannot have the specified child item + \li + + \row + \li M201 + \li Hint + \li Place var declarations at the start of a function + \li See also: + \l{http://linterrors.com/js/move-var-declarations-to-the-top-of-the-function} + {Move 'var' declarations to the top of the function}. + + \row + \li M202 + \li Hint + \li Use only one statement per line + \li + + \row + \li M203 + \li Warning + \li Imperative code is not supported in the Design mode + \li + + \row + \li M204 + \li Warning + \li This QML type is not supported in the Design mode + \li + \row + \li M205 + \li Warning + \li Reference to parent QML type cannot be resolved correctly by the + Design mode + \li + + \row + \li M206 + \li Warning + \li This visual property binding cannot be evaluated in the local + context and might not show up in Design mode as expected + \li + + \row + \li M207 + \li Warning + \li Design mode only supports states in the root QML type + \li + + \row + \li M208 + \li Error + \li This id might be ambiguous and is not supported in the Design mode. + \li + + \row + \li M209 + \li Error + \li This type (type name) is not supported as a root element in the + Design mode. + \li + + \row + \li M220 + \li Error + \li This type (type name) is not supported as a root element of a Qt + Quick UI form. + \li + + \row + \li M221 + \li Error + \li This type (type name) is not supported in a Qt Quick UI form. + \li + + \row + \li M222 + \li Error + \li Functions are not supported in a Qt Quick UI form. + \li + + \row + \li M223 + \li Error + \li Java Script blocks are not supported in a Qt Quick UI form. + \li + + \row + \li M224 + \li Error + \li Behavior type is not supported in a Qt Quick UI form. + \li + + \row + \li M225 + \li Error + \li States are only supported in the root item in a Qt Quick UI form. + \li + + \row + \li M226 + \li Error + \li Referencing the parent of the root item is not supported in a Qt + Quick UI form. + \li + + \row + \li M300 + \li Error + \li Unknown component + \li + + \row + \li M301 + \li Error + \li Could not resolve the prototype \c name of \c object + \li + + \row + \li M302 + \li Error + \li Could not resolve the prototype \c name + \li + + \row + \li M303 + \li Error + \li Prototype cycle, the last non-repeated component is \c name + \li + + \row + \li M304 + \li Error + \li Invalid property type \c name + \li + \row + \li M305 + \li Warning + \li \c == and \c != perform type coercion, use \c === or \c !== to + avoid it + \li See \l{m126}{M126}. + \row + \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. + + \row + \li M307 + \li Warning + \li Use \c new only with functions that start with an uppercase letter + \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} + {Do not use {a} as a constructor}. + + \row + \li M308 + \li Warning + \li Do not use \c Number as a constructor + \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} + {Do not use {a} as a constructor}. + + \row + \li M309 + \li Hint + \li Use spaces around binary operators + \li + + \row + \li M310 + \li Warning + \li Unintentional empty block, use ({}) for empty object literal + \li + + \row + \li M311 + \li Hint + \li Use \c type instead of \c var or \c variant to improve performance + \li + + \row + \li M312 + \li Error + \li Missing property \c number + \li + + \row + \li M313 + \li Error + \li Object value expected + \li + + \row + \li M314 + \li Error + \li Array value expected + \li + + \row + \li M315 + \li Error + \li \c Value value expected + \li + + \row + \li M316 + \li Error + \li Maximum number value is \c number + \li + + \row + \li M317 + \li Error + \li Minimum number value is \c number + \li + + \row + \li M318 + \li Error + \li Maximum number value is exclusive + \li + + \row + \li M319 + \li Error + \li Minimum number value is exclusive + \li + + \row + \li M320 + \li Error + \li String value does not match required pattern + \li + + \row + \li M321 + \li Error + \li Minimum string value length is \c number + \li + + \row + \li M322 + \li Error + \li Maximum string value length is \c number + \li + + \row + \li M323 + \li Error + \li \c Number elements expected in array value + \li See also: + \l{http://linterrors.com/js/the-array-literal-notation-is-preferrable} + {The array literal notation [] is preferable}. + + \endtable + + \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 Design + mode. + + To reset the code model, select \uicontrol Tools > \uicontrol {QML/JS} > + \uicontrol {Reset Code Model}. + + 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 Design Mode}. + + \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}. + + \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}. +*/ diff --git a/doc/src/editors/creator-editors.qdoc b/doc/src/editors/creator-editors.qdoc deleted file mode 100644 index c27a787c587..00000000000 --- a/doc/src/editors/creator-editors.qdoc +++ /dev/null @@ -1,3146 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** 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. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** 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. -** -****************************************************************************/ - -// ********************************************************************** -// 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. -// ********************************************************************** - -/*! - \contentspage index.html - \previouspage creator-coding-navigating.html - \page creator-highlighting.html - \nextpage creator-checking-code-syntax.html - - \title Semantic Highlighting - - \QC understands the C++, QML, and JavaScript languages as code, not as plain - text. It reads the source code, analyzes it, and highlights it based on the - semantic checks that it does for the following code elements: - - \list - - \li Types (such as classes, structs, and type definitions) - - \li Local variables - - \li Class fields - - \li Virtual functions - - \endlist - - To specify the color scheme to use for semantic highlighting, select - \uicontrol Tools > \uicontrol Options > \uicontrol {Text Editor} > - \uicontrol {Fonts & Color}. - - \QC supports syntax highlighting also for other types of files than C++, - QML, or JavaScript. - - \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. - For more information about the definition files, see - \l{http://kde-files.org/index.php?xcontentmode=680}{KDE-Files.org}. - - 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 - 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 - definition files as the primary location. - - When you open a file for editing and the editor cannot find the highlight - definition for it, an alert appears. To suppress the alerts, you can specify - patterns for ignoring files. - - To download highlight definition files: - - \list 1 - - \li Select \uicontrol Tools > \uicontrol Options > - \uicontrol {Text Editor} > \uicontrol {Generic Highlighter}. - - \image qtcreator-generic-highlighter.png "Generic Highlighter options" - - \li In the \uicontrol Location field, specify the path to the primary - location for highlight definition files. - - \li Click \uicontrol {Download Definitions} to open a list of highlight - definition files available for download. - - \image qtcreator-manage-definitions.png "Download Definitions dialog" - - \li Select highlight definition files in the list and click - \uicontrol {Download Selected Definitions}. - - \li Select the \uicontrol {Use fallback location} check box to specify the - secondary location where the editor will look for highlight - definition files. - - \li Click \uicontrol Autodetect to allow \QC to look for highlight - definition files on your system, or click \uicontrol Browse to locate - them in the file system yourself. - - \li In the \uicontrol {Ignored file patterns} field, specify file patterns to - suppress alerts if the highlight definitions for the - specified files are not found. - - \li Click \uicontrol OK to save your changes. - - \endlist - - \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 - - To enable block highlighting, select \uicontrol Tools > - \uicontrol Options > \uicontrol {Text Editor} > \uicontrol Display > - \uicontrol {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. - - 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. - - 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}. - - 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}. -*/ - - -/*! - \contentspage index.html - \previouspage creator-highlighting.html - \page creator-checking-code-syntax.html - \nextpage creator-completing-code.html - - \title Checking Code Syntax - - As you write code, \QC checks code syntax. When \QC spots a syntax error in - your code it underlines it and shows error details when you move the mouse - 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. - - \list - - \li Syntax errors are underlined in red. - - In the following figure, a semicolon is missing at the end of the - line. - - \image qtcreator-syntaxerror.png - - \li Semantic errors and warnings are underlined in olive. - - In the following figure, the variable is not used. - - \image qtcreator-semanticerror.png - - \endlist - - 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 {Line annotations}, 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. Showing annotations - between lines can be useful if there is usually not enough space to - display annotations next to the text. - - If you hide the annotations by deselecting the check box, you can move the - mouse pointer over an icon to view them. - - \section1 Checking JSON Data Structure - - You can run static checks on the QML and JavaScript code in - your project to find common problems. - - \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}. - However, \QC does not understand the entire specification. - - 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. - - The specification does not define how to map JSON instances with JSON - schemas. \QC looks for a JSON schema file with a - name that matches the name of the JSON instance file in the user - configuration folder. For example, \c {~/config/QtProject/qtcreator/json} on - Linux and \macos and - \c {C:\Users\username\AppData\Roaming\QtCreator\qtcreator\json} - in Windows. To check JSON data structure, copy the JSON schema file to the - above folder. - - \section2 Checking JavaScript and QML Syntax - - 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. - - - \section2 List of JavaScript and QML Checks - - Many of the JavaScript checks are similar to the ones in Douglas Crockford's - \l{http://www.jslint.com}{JSLint} tool. For more information about JSLint - errors, see \l{http://linterrors.com/js}{JSLint Error Explanations}. - - \table - \header - \li Id - \li Severity - \li Message - \li Description - - \row - \li M1 - \li Error - \li Invalid value for enum - \li - - \row - \li M2 - \li Error - \li Enum value must be a string or a number - \li - - \row - \li M3 - \li Error - \li Number value expected - \li - - \row - \li M4 - \li Error - \li Boolean value expected - \li - - \row - \li M5 - \li Error - \li String value expected - \li - - \row - \li M6 - \li Error - \li Invalid URL - \li - - \row - \li M7 - \li Warning - \li File or directory does not exist - \li - - \row - \li M8 - \li Error - \li Invalid color - \li - - \row - \li M9 - \li Error - \li Anchor line expected - \li - - \row - \li M10 - \li Error - \li Duplicate property binding - \li See also: \l{http://linterrors.com/js/duplicate-key-a} - {Duplicate key '{a}'}. - - \row - \li M11 - \li Error - \li Id expected - \li See also: - \l{http://linterrors.com/js/expected-an-identifier-and-instead-saw-a-a-reserved-word} - {Expected an identifier and instead saw '{a}' (a reserved word)}. - - \row - \li M14 - \li Error - \li Invalid id - \li See also: - \l{http://linterrors.com/js/expected-an-identifier-and-instead-saw-a-a-reserved-word} - {Expected an identifier and instead saw '{a}' (a reserved word)}. - - - \row - \li M15 - \li Error - \li Duplicate id - \li Ids in a file must be unique. - See also: \l{http://linterrors.com/js/duplicate-key-a} - {Duplicate key '{a}'}. - - \row - \li M16 - \li Error - \li Invalid property name \c name - \li - - \row - \li M17 - \li Error - \li \c Name does not have members - \li - - \row - \li M18 - \li Error - \li \c Field is not a member of \c object - \li - - \row - \li M19 - \li Warning - \li Assignment in condition - \li It could be a typing error. If it is intentional, wrap the - assignment in parentheses. - - \row - \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. - - \row - \li M23 - \li Warning - \li Do not use \c eval - \li See also: \l{http://linterrors.com/js/eval-is-evil}{eval is evil}. - - \row - \li M28 - \li Warning - \li Unreachable - \li Indicates that the underlined statement will never be executed. - - \row - \li M29 - \li Warning - \li Do not use \c with - \li See also: \l{http://linterrors.com/js/unexpected-with} - {Unexpected 'with'}. - - \row - \li M30 - \li Warning - \li Do not use comma expressions - \li - - \row - \li M31 - \li Warning - \li Unnecessary message suppression - \li - - \row - \li M103 - \li Warning - \li \c Name is already a formal parameter - \li - - \row - \li M104 - \li Warning - \li \c Name is already a function - \li - - \row - \li M105 - \li Warning - \li Var \c name is used before its declaration - \li - - \row - \li M106 - \li Warning - \li \c Name is already a var - \li - - \row - \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. - - \row - \li M108 - \li Warning - \li Function \c name is used before its declaration - \li See also: \l{http://linterrors.com/js/a-was-used-before-it-was-defined} - {{a} was used before it was defined}. - - \row - \li M109 - \li Warning - \li Do not use \c Boolean as a constructor - \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} - {Do not use {a} as a constructor}. - - \row - \li M110 - \li Warning - \li Do not use \c String as a constructor - \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} - {Do not use {a} as a constructor}. - - \row - \li M111 - \li Warning - \li Do not use \c Object as a constructor - \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} - {Do not use {a} as a constructor}. - - \row - \li M112 - \li Warning - \li Do not use \c Array as a constructor - \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} - {Do not use {a} as a constructor}. - - \row - \li M113 - \li Warning - \li Do not use \c Function as a constructor - \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} - {Do not use {a} as a constructor}. - - \row - \li M114 - \li Hint - \li The \c function keyword and the opening parenthesis should be - separated by a single space - \li See also: \l{http://linterrors.com/js/expected-exactly-one-space-between-a-and-b} - {Expected exactly one space between {a} and {b}}. - - \row - \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. - - \row - \li M116 - \li Warning - \li Do not use void expressions - \li - - \row - \li M117 - \li Warning - \li Confusing pluses - \li See also: \l{http://linterrors.com/js/confusing-pluses} - {Confusing pluses}. - - \row - \li M119 - \li Warning - \li Confusing minuses - \li See also: \l{http://linterrors.com/js/confusing-minuses} - {Confusing minuses}. - - \row - \li M121 - \li Hint - \li Declare all function vars on a single line - \li - - \row - \li M123 - \li Hint - \li Unnecessary parentheses - \li - - \target m126 - \row - \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. - - \row - \li M127 - \li Warning - \li Expression statements should be assignments, calls or delete - expressions only - \li - - \row - \li M128 - \li Error - \li A state cannot have the specified child item - \li - - \row - \li M201 - \li Hint - \li Place var declarations at the start of a function - \li See also: - \l{http://linterrors.com/js/move-var-declarations-to-the-top-of-the-function} - {Move 'var' declarations to the top of the function}. - - \row - \li M202 - \li Hint - \li Use only one statement per line - \li - - \row - \li M203 - \li Warning - \li Imperative code is not supported in the Design mode - \li - - \row - \li M204 - \li Warning - \li This QML type is not supported in the Design mode - \li - \row - \li M205 - \li Warning - \li Reference to parent QML type cannot be resolved correctly by the - Design mode - \li - - \row - \li M206 - \li Warning - \li This visual property binding cannot be evaluated in the local - context and might not show up in Design mode as expected - \li - - \row - \li M207 - \li Warning - \li Design mode only supports states in the root QML type - \li - - \row - \li M208 - \li Error - \li This id might be ambiguous and is not supported in the Design mode. - \li - - \row - \li M209 - \li Error - \li This type (type name) is not supported as a root element in the - Design mode. - \li - - \row - \li M220 - \li Error - \li This type (type name) is not supported as a root element of a Qt - Quick UI form. - \li - - \row - \li M221 - \li Error - \li This type (type name) is not supported in a Qt Quick UI form. - \li - - \row - \li M222 - \li Error - \li Functions are not supported in a Qt Quick UI form. - \li - - \row - \li M223 - \li Error - \li Java Script blocks are not supported in a Qt Quick UI form. - \li - - \row - \li M224 - \li Error - \li Behavior type is not supported in a Qt Quick UI form. - \li - - \row - \li M225 - \li Error - \li States are only supported in the root item in a Qt Quick UI form. - \li - - \row - \li M226 - \li Error - \li Referencing the parent of the root item is not supported in a Qt - Quick UI form. - \li - - \row - \li M300 - \li Error - \li Unknown component - \li - - \row - \li M301 - \li Error - \li Could not resolve the prototype \c name of \c object - \li - - \row - \li M302 - \li Error - \li Could not resolve the prototype \c name - \li - - \row - \li M303 - \li Error - \li Prototype cycle, the last non-repeated component is \c name - \li - - \row - \li M304 - \li Error - \li Invalid property type \c name - \li - \row - \li M305 - \li Warning - \li \c == and \c != perform type coercion, use \c === or \c !== to - avoid it - \li See \l{m126}{M126}. - \row - \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. - - \row - \li M307 - \li Warning - \li Use \c new only with functions that start with an uppercase letter - \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} - {Do not use {a} as a constructor}. - - \row - \li M308 - \li Warning - \li Do not use \c Number as a constructor - \li See also: \l{http://linterrors.com/js/do-not-use-a-as-a-constructor} - {Do not use {a} as a constructor}. - - \row - \li M309 - \li Hint - \li Use spaces around binary operators - \li - - \row - \li M310 - \li Warning - \li Unintentional empty block, use ({}) for empty object literal - \li - - \row - \li M311 - \li Hint - \li Use \c type instead of \c var or \c variant to improve performance - \li - - \row - \li M312 - \li Error - \li Missing property \c number - \li - - \row - \li M313 - \li Error - \li Object value expected - \li - - \row - \li M314 - \li Error - \li Array value expected - \li - - \row - \li M315 - \li Error - \li \c Value value expected - \li - - \row - \li M316 - \li Error - \li Maximum number value is \c number - \li - - \row - \li M317 - \li Error - \li Minimum number value is \c number - \li - - \row - \li M318 - \li Error - \li Maximum number value is exclusive - \li - - \row - \li M319 - \li Error - \li Minimum number value is exclusive - \li - - \row - \li M320 - \li Error - \li String value does not match required pattern - \li - - \row - \li M321 - \li Error - \li Minimum string value length is \c number - \li - - \row - \li M322 - \li Error - \li Maximum string value length is \c number - \li - - \row - \li M323 - \li Error - \li \c Number elements expected in array value - \li See also: - \l{http://linterrors.com/js/the-array-literal-notation-is-preferrable} - {The array literal notation [] is preferable}. - - \endtable - - \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 Design - mode. - - To reset the code model, select \uicontrol Tools > \uicontrol {QML/JS} > - \uicontrol {Reset Code Model}. - - 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 Design Mode}. - - \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}. - - \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}. -*/ - - -/*! - \contentspage index.html - \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 - - To open the list of suggestions at any time, press \key {Ctrl+Space}. - If only one option is available, \QC inserts it automatically. - - 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} - > \uicontrol Completion. - - 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. - - \section2 Summary of Available Types - - The following table lists available types for code completion and icon used - for each. - - \table - \header - \li Icon - \li Description - \row - \li \inlineimage completion/class.png - \li A class - \row - \li \inlineimage completion/enum.png - \li An enum - \row - \li \inlineimage completion/enumerator.png - \li An enumerator (value of an enum) - \row - \li \inlineimage completion/func.png - \li A function - \row - \li \inlineimage completion/func_priv.png - \li A private function - \row - \li \inlineimage completion/func_prot.png - \li A protected function - \row - \li \inlineimage completion/var.png - \li A variable - \row - \li \inlineimage completion/var_priv.png - \li A private variable - \row - \li \inlineimage completion/var_prot.png - \li A protected variable - \row - \li \inlineimage completion/signal.png - \li A signal - \row - \li \inlineimage completion/slot.png - \li A slot - \row - \li \inlineimage completion/slot_priv.png - \li A private slot - \row - \li \inlineimage completion/slot_prot.png - \li A protected slot - \row - \li \inlineimage completion/keyword.png - \li A C++ keyword - \row - \li \inlineimage completion/snippet.png - \li A C++ code snippet - \row - \li \inlineimage completion/element.png - \li A QML type - \row - \li \inlineimage completion/qmlsnippet.png - \li A QML code snippet - \row - \li \inlineimage completion/macro.png - \li A macro - \row - \li \inlineimage completion/namespace.png - \li A namespace - \endtable - - \section2 Completing Code Snippets - - 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. - - \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 - \uicontrol Tools > \uicontrol Options > \uicontrol {Text Editor} > - \uicontrol Snippets. - - \image qtcreator-edit-code-snippets.png "Snippet options" - - \QC provides you with built-in snippets in the following categories: - - \list - - \li Text snippets, which can contain any text string. For example, code - comments - - \li C++ code snippets, which specify C++ code constructs - - \li CMake code snippets that you can use when editing \c CMakeLists.txt - files in the CMake editor - - \li QML code snippets, which specify QML code constructs - - \li Nim code snippets, which specify Nim code constructs - - \endlist - - \section3 Adding and Editing Snippets - - Select a snippet in the list to edit it in the snippet editor. To add a new - 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 - in the snippet editor, depending on the snippet category. You can use - \l{Using Qt Creator Variables}{predefined variables} in snippets. - - The snippet editor provides you with: - - \list - - \li Highlighting - - \li Indentation - - \li Parentheses matching - - \li Basic code completion - - \endlist - - Specify the variables for the snippets in the following format: - - \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}}. - - Use unique variable names within a snippet, because all instances of a - variable are renamed when you specify a value for it. - - 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 - - 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. - - To discard the changes you made to a built-in snippet, select - \uicontrol {Revert Built-in}. - - \section3 Removing Snippets - - Several similar built-in snippets might be provided for different use cases. - To make the list of suggestions shorter when you write code, remove the - built-in snippets that you do not need. If you need them later, you can - restore them. - - To remove snippets, select a snippet in the list, and then select - \uicontrol Remove. To restore the removed snippets, select - \uicontrol {Restore Removed Built-ins}. - - \section3 Resetting Snippets - - To remove all added snippets and to restore all removed snippets, select - \uicontrol {Reset All}. - - \note If you now select \uicontrol OK or \uicontrol Apply, you permanently - lose all your own snippets. - -*/ - - -/*! - \contentspage index.html - \previouspage qt-quick-toolbars.html - \page creator-editor-codepasting.html - \nextpage creator-macros.html - - \title Pasting and Fetching Code Snippets - - In \QC, you can paste snippets of code to a server or fetch snippets of code - from the server. To paste and fetch snippets of code, \QC uses the - following: - - \list - - \li \uicontrol {Pastebin.Com} - - \li \uicontrol {Pastebin.Ca} - - \li \uicontrol {Paste.KDE.Org} - - \li \uicontrol {Shared network drives} - - \endlist - - \section1 Specifying Settings for Code Pasting - - To specify settings for the code pasting service: - - \list 1 - - \li Select \uicontrol Tools > \uicontrol Options > - \uicontrol {Code Pasting}. - - \image qtcreator-code-pasting-options.png "Code Pasting options" - - \li In the \uicontrol {Default protocol} field, select a code pasting - service to use by default. - - \li In the \uicontrol Username field, enter your username. - - \li In the \uicontrol {Expires after} field, specify the time to keep - the pasted snippet on the server. - - \li Select the \uicontrol {Copy-paste URL to clipboard} check box to - copy the URL of the post on the code pasting service to the - clipboard when you paste a post. - - \li Select the \uicontrol {Display Output pane after sending a post} - check box to display the URL in the \uicontrol {General Messages} - output pane when you paste a post. - - \endlist - - Select \uicontrol Fileshare to specify the path to a shared network drive. - The code snippets are copied to the drive as simple files. You have to - delete obsolete files from the drive manually. - - \section1 Using Code Pasting Services - - To paste a snippet of code onto the server, select \uicontrol Tools > - \uicontrol {Code Pasting} > \uicontrol {Paste Snippet} or press - \key {Alt+C,Alt+P}. By default, \QC copies the URL of the snippet to the - clipboard and displays the URL in the \uicontrol {General Messages} output - pane. - - To paste any content that you copied to the clipboard, select - \uicontrol Tools > \uicontrol {Code Pasting} > \uicontrol {Paste Snippet}. - - To paste content from the \l{Comparing Files}{diff editor}, right-click a - chunk and select \uicontrol {Send Chunk to CodePaster} in the context menu. - - To fetch a snippet of code from the server, select \uicontrol Tools > - \uicontrol {Code Pasting} > \uicontrol {Fetch Snippet} or press - \key {Alt+C,Alt+F}. Select the snippet to fetch from the list. - - To fetch the content stored at an URL, select \uicontrol Tools > - \uicontrol {Code Pasting} > \uicontrol {Fetch from URL}. - - For example, you might ask colleagues to review a change that you plan to - submit to a version control system. If you use the Git version control - system, you can create a \e{diff} view by selecting \uicontrol Tools > - \uicontrol Git > \uicontrol {Local Repository} > \uicontrol Diff. You can - then upload its contents to the server by selecting \uicontrol Tools > - \uicontrol {Code Pasting} > \uicontrol {Paste Snippet}. The reviewers can - retrieve the code snippet by selecting \uicontrol Tools > - \uicontrol {Code Pasting} > \uicontrol {Fetch Snippet}. If they have the - project currently opened in \QC, they can apply and test the change by - choosing \uicontrol Tools > \uicontrol Git > \uicontrol {Patch} > - \uicontrol {Apply from Editor}. - -*/ - - -/*! - \contentspage index.html - \previouspage creator-editor-codepasting.html - \page creator-macros.html - \nextpage creator-diff-editor.html - - \title Using Text Editing Macros - - To record a text editing macro, select \uicontrol Tools > - \uicontrol {Text Editing Macros} > \uicontrol {Record Macro} - or press \key {Alt+(}. To stop recording, select \uicontrol Tools > - \uicontrol {Text Editing Macros} > \uicontrol {Stop Recording Macro} or - press \key {Alt+)}. - - \note The macro recorder does not support code completion. - - To play the last macro, select \uicontrol Tools > - \uicontrol {Text Editing Macros} > \uicontrol {Play Last Macro} or - press \key {Alt+R}. - - To save the last macro, select \uicontrol Tools > - \uicontrol {Text Editing Macros} > \uicontrol {Save Last Macro}. - - To assign a keyboard shortcut to a text editing macro, select - \uicontrol Tools > \uicontrol Options > \uicontrol Environment > - \uicontrol Keyboard. For more information, see - \l{Configuring Keyboard Shortcuts}. - - You can also use the \c rm locator filter to run a macro. For more - information, see \l{Searching with the Locator}. - - To view and remove saved macros, select \uicontrol Tools > - \uicontrol Options > \uicontrol {Text Editor} > \uicontrol Macros. - -*/ - - -/*! - \contentspage index.html - \previouspage creator-editor-options-text.html - \page creator-editor-fakevim.html - \nextpage creator-mime-types.html - - \title Using FakeVim Mode - - In the \uicontrol FakeVim mode, you can run the main editor in a manner - similar to the Vim editor. To run the editor in the \uicontrol FakeVim - mode, select \uicontrol Edit > \uicontrol Advanced > - \uicontrol {Use Vim-style Editing} or press \key {Alt+V,Alt+V}. - - \section1 Supported Modes and Commands - - In the \uicontrol FakeVim mode, most keystrokes in the main editor will be - intercepted and interpreted in a way that resembles Vim. Most of the - supported commands can be followed by a motion command or executed in visual - mode, or they work with registers or can be prefixed with a number of - repetitions. - - The following sections describe the commands emulated in the supported modes - and how they diverge from Vim in functionality: - - \list - \li Normal - \li Visual - \li Command line (:) - \li Insert and replace - \endlist - - For more information on using Vim, see \l{http://www.vim.org/docs.php} - {Documentation} on the Vim web site. - - \section2 Normal and Visual Modes - - \list - \li Basic movement, such as \c h/j/k/l, \c , \c , \c , - \c , \c gg, \c G, \c 0, \c ^, \c $ - \li Word movement, such as \c w, \c e, \c b - \li \e Inner/a movement, such as \c ciw, \c 3daw, ya{ - \li \c f and \c t movement - \li \c [ and \c ] movement - \li { and } paragraph movement - \li Delete/change/yank/paste with register - \li Undo and redo - \li \c and \c increase or decrease a number in decimal, - octal, or hexadecimal format (for example \c 128 on or before - \c "0x0ff" changes it to \c "0x17f") - \li \c . repeats the last change - \li \c /search, \c ?search, \c *, \c #, \c n, \c N - most of regular - expression syntax is used in Vim except that \c \< and \c \> are - the same as \c {\b} in QRegExp - \li \c @ and \c q (macro recording and execution) special keys are saved - as \c - \li Marks - \li \c gv goes to last visual selection; can differ if text is edited - around it - \li Indentation using \c =, \c <<, \c >>, with movement, count, and in - visual mode - \li \e {to upper/lower}, such as \c ~, \c gU, \c gu - \li \c i, \c a, \c o, \c I, \c A, and \c O enter insert mode - \li Scroll window, such as \c zt, \c zb, \c zz - \li Wrap line movement, such as \c gj, \c gk, \c g0, \c g^, \c g$ - \endlist - - \section2 Command Line Mode - - \list - \li \c :map, \c :unmap, \c :inoremap, and so on - \li \c :source provides very basic line-by-line sourcing of vimrc files - \li \c :substitute substitutes an expression in a range - \li \c :'<,'>!cmd filters through an external command (for example, - sorts the lines in a file with \c :%!sort) - \li \c :sor[t][!] - \li \c :.!cmd inserts the standard output of an external command - \li \c :read - \li \c :yank, \c :delete, \c :change - \li \c :move, \c :join - \li \c :20 goes to an address - \li \c :history - \li \c :registers, \c :display - \li \c :nohlsearch - \li \c :undo, \c :redo - \li \c :normal - \li \c :<, \c :> - \endlist - - \section2 Insert Mode - - \list - \li \c executes a single command and returns to insert mode - \li \c inserts a raw character - \li \c toggles replace mode - \endlist - - \section2 Options - - Use \c {:set ...} to set the following options: - - \list - \li \c autoindent - \li \c clipboard - \li \c backspace - \li \c expandtab - \li \c hlsearch - \li \c ignorecase - \li \c incsearch - \li \c indent - \li \c iskeyword - \li \c scrolloff - \li \c shiftwidth - \li \c showcmd - \li \c smartcase - \li \c smartindent - \li \c smarttab - \li \c startofline - \li \c tabstop - \li \c tildeop - \li \c wrapscan - \endlist - - \section2 Vimrc Example - - \code - " highlight matched - set hlsearch - " case insensitive search - set ignorecase - set smartcase - " search while typing - set incsearch - " wrap-around when searching - set wrapscan - " show pressed keys in lower right corner - set showcmd - " tab -> spaces - set expandtab - set tabstop=4 - set shiftwidth=4 - " keep a 5 line buffer for the cursor from top/bottom of window - set scrolloff=5 - " X11 clipboard - set clipboard=unnamed - " use ~ with movement - set tildeop - - " mappings - nnoremap ; : - inoremap jj - - " clear highlighted search term on space - noremap :nohls - - " reselect visual block after indent - vnoremap < >gv - - " MOVE LINE/BLOCK - nnoremap :m+== - nnoremap :m-2== - inoremap :m+==gi - inoremap :m-2==gi - vnoremap :m'>+gv=gv - vnoremap :m-2gv=gv - \endcode - - \section1 Mapping FakeVim Commands - - To map commands entered on the \uicontrol FakeVim command line to actions - of the \QC core, select \uicontrol Tools > \uicontrol Options > - \uicontrol FakeVim > \uicontrol {Ex Command Mapping}. - - To map \e {user commands} to keyboard shortcuts, select \uicontrol Tools > - \uicontrol Options > \uicontrol FakeVim > - \uicontrol {User Command Mapping}. The user command mapped to the shortcut - is executed by FakeVim as if you were typing it (as when replaying a macro). - - \section1 Specifying FakeVim Options - - To make changes to the Vim-style settings, select \uicontrol Tools > - \uicontrol Options > \uicontrol FakeVim > \uicontrol General. - - \image qtcreator-fakevim-options.png "FakeVim options" - - To preselect the indentation settings specified for the text editor, select - \uicontrol {Copy Text Editor Settings}. To preselect the Qt coding style, - select \uicontrol {Set Qt Style}. To preselect a simple indentation style, - select \uicontrol {Set Plain Style}. You can then change any of the - preselected settings. - - To use a Vim-style color scheme, select \uicontrol Tools > - \uicontrol Options > \uicontrol {Text Editor} > \uicontrol {Fonts & Color}. - In the \uicontrol {Color Scheme} list, select \uicontrol {Vim (dark)}. - - \section1 Quitting FakeVim Mode - - To quit the FakeVim mode, unselect \uicontrol Tools > \uicontrol Options > - \uicontrol FakeVim > \uicontrol {Use FakeVim} or press \key {Alt+V,Alt+V}. - - You can temporarily escape FakeVim mode to access the normal \QC keyboard - shortcuts like \key {Ctrl-R} for \uicontrol Run by pressing \key {,} first. - - */ - -/*! - \contentspage index.html - \previouspage creator-completing-code.html - \page creator-indenting-code.html - \nextpage qt-quick-toolbars.html - - \title Indenting Text or Code - - When you type text or code, it is indented automatically according to the - selected text editor or code style options. Select a block to indent it when - you press \key Tab. Press \key {Shift+Tab} to decrease the indentation. You - can disable automatic indentation. - - You can specify indentation for: - - \list - - \li C++ files - - \li QML files - - \li Nim files - - \li Other text files - - \endlist - - You can also specify indentation separately for each project. You can - specify several sets of code style settings and easily switch between them. - In addition, you can import and export code style settings. - - \section1 Indenting C++ Files - - To specify indentation settings for the C++ editor: - - \list 1 - - \li Select \uicontrol Tools > \uicontrol Options > \uicontrol {C++}. - - \li In the \uicontrol {Current settings} field, select the settings to - modify and click \uicontrol Copy. - - \image qtcreator-options-code-style-cpp.png "C++ Code Style options" - - \li Give a name to the settings and click \uicontrol OK. - - \li Click \uicontrol Edit to specify code style settings for the project. - - \image qtcreator-code-style-settings-edit-cpp.png "Edit Code Style Settings dialog" - - - \endlist - - You can specify how to: - - \list - - \li Interpret the \key Tab and \key Backspace key presses. - - \li Indent the contents of classes, functions, blocks, and namespaces. - - \li Indent braces in classes, namespaces, enums, functions, and blocks. - - \li Control switch statements and their contents. - - \li Align continuation lines. - - \li Bind pointers (*) and references (&) in types and declarations to - identifiers, type names, or left or right \c const or \c volatile - keywords. - - \li Name getter functions. - - \endlist - - You can use the live preview to see how the options change the indentation. - - To specify different settings for a particular project, select - \uicontrol Projects > \uicontrol {Code Style Settings}. - - \section1 Indenting QML Files - - To specify settings for the Qt Quick editor: - - \list 1 - - \li Select \uicontrol Tools > \uicontrol Options > - \uicontrol {Qt Quick}. - - \li In the \uicontrol {Current settings} field, select the settings to - modify and click \uicontrol Copy. - - \image qtcreator-options-code-style-qml.png "QML Code Style options" - - \li Give a name to the settings and click \uicontrol OK. - - \li Click \uicontrol Edit to specify code style settings for the project. - - \image qtcreator-code-style-settings-edit-qtquick.png "Edit Code Style Settings dialog" - - \endlist - - You can specify how to interpret the \key Tab key presses and how to align - continuation lines. - - To specify different settings for a particular project, select - \uicontrol Projects > \uicontrol {Code Style Settings}. - - \section1 Indenting Nim Files - - To specify settings for the Nim editor (experimental): - - \list 1 - - \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Nim. - - \li In the \uicontrol {Current settings} field, select the settings to - modify and click \uicontrol Copy. - - \image qtcreator-options-code-style-nim.png "Nim Code Style options" - - \li Give a name to the settings and click \uicontrol OK. - - \li Click \uicontrol Edit to specify code style settings for the project. - - \image qtcreator-code-style-settings-edit-nim.png "Edit Code Style Settings dialog" - - \endlist - - You can specify how to interpret the \key Tab key presses and how to align - continuation lines. - - To specify different settings for a particular project, select - \uicontrol Projects > \uicontrol {Code Style}. - - \section1 Indenting Other Text Files - - To specify indentation settings for text files that do not contain C++ or - QML code (such as Python code files), select \uicontrol Tools > - \uicontrol Options > \uicontrol {Text Editor} > \uicontrol Behavior. - - \image qtcreator-indentation.png "Text Editor Behavior options" - - To specify different settings for a particular project, select - \uicontrol Projects > \uicontrol Editor. - - You can specify how to interpret the \key Tab and \key Backspace key - presses and how to align continuation lines. - - \section1 Specifying Tab Settings - - You can specify tab settings at the following levels: - - \list - - \li For all C++ files - - \li For all QML files - - \li For all other text files - - \li For C++ files in a project - - \li For QML files in a project - - \li For other text files in a project - - \endlist - - \section2 Specifying Tabs and Indentation - - You can specify tab policy and tab size in the - \uicontrol {Tabs and Indentation} group. In - the \uicontrol {Tab policy} field, select whether to use only spaces or - only tabs for indentation, or to use a mixture of them. - - By default, the tab length in code editor is 8 spaces and the indent size is - 4 spaces. You can specify the tab length and indent size separately for each - project and for different types of files. - - You can have continuation lines aligned with the previous line. In the - \uicontrol {Align continuation lines} field, select - \uicontrol {Not at all} to disable automatic alignment and indent - continuation lines to the logical depth. To always use spaces for alignment, - select \uicontrol {With Spaces}. To follow the \uicontrol {Tab policy}, - select \uicontrol {With Regular Indent}. - - \section2 Specifying Typing Options - - When you type text or code, it is indented automatically according to the - selected text editor or code style options. Specify typing options in the - \uicontrol Typing group. To disable automatic indentation, deselect the - \uicontrol {Enable automatic indentation} check box. - - You can specify how the indentation is decreased when you press - \uicontrol Backspace in the \uicontrol {Backspace indentation} field. To go - back one space at a time, select \uicontrol None. To decrease indentation - in leading white space by one level, select - \uicontrol {Follows Previous Indents}. To move back one tab length if the - character to the left of the cursor is a space, select - \uicontrol Unindents. - - You can specify whether the \key Tab key automatically indents text when you - press it. To automatically indent text, select \uicontrol Always in the - \uicontrol {Tab key performs auto-indent} field. To only indent text when - the cursor is located within leading white space, select \uicontrol {In - Leading White Space}. - - \section1 Specifying Settings for Content - - You can indent public, protected, and private statements and declarations - related to them within classes. - - You can also indent statements within functions and blocks and declarations - within namespaces. - - \image qtcreator-code-style-content.png "Content options" - - \section1 Specifying Settings for Braces - - You can indent class, namespace, enum and function declarations and code - blocks. - - \image qtcreator-code-style-braces.png "Braces options" - - \section1 Specifying Settings for Switch Statements - - You can indent case or default statements, or statements or blocks related - to them within switch statements. - - \image qtcreator-code-style-switch.png "Switch options" - - \section1 Specifying Alignment - - To align continuation lines to tokens after assignments, such as \c = or - \c +=, select the \uicontrol {Align after assignments} check box. You can - specify additional settings for aligning continuation lines in the - \uicontrol General tab. - - You can also add spaces to conditional statements, so that they are not - aligned with the following line. Usually, this only affects \c if - statements. - - \image qtcreator-code-style-alignment.png "Alignment options" - - \section1 Binding Pointers and References - - To bind pointers (\c *) and references (\c &) in types and declarations to - identifiers, type names, or left or right \c const or \c volatile keywords, - select the check boxes in the \uicontrol {Pointers and References} tab. - - The \c * and \c & characters are automatically bound to identifiers of - pointers to functions and pointers to arrays. - - \image qtcreator-pointers-references.png "Pointers and References options" - - \section1 Naming Getters - - To prefer getter names without the string \e get, select the - \uicontrol {Prefer getter names without "get"} check box in the - \uicontrol {Getter and Setter} tab. - - \image qtcreator-code-style-getter-setter.png - -*/ - - -/*! - \contentspage index.html - \previouspage creator-finding-overview.html - \page creator-editor-finding.html - \nextpage creator-editor-locator.html - - \title Finding and Replacing - - To search through the currently open file: - - \list 1 - - \li Press \key {Ctrl+F} or select \uicontrol Edit > - \uicontrol {Find/Replace} > \uicontrol {Find/Replace}. - - \li Enter the text you are looking for. - - If the text is found, all occurrences are highlighted as you type. - - \li To go to the next occurrence, click \inlineimage next.png - (\uicontrol {Find Next}), or press \key F3. To go to the previous - occurrence click \inlineimage prev.png - (\uicontrol {Find Previous}), or press \key {Shift+F3}. - - \endlist - - You can restrict the search in the \uicontrol Find field by selecting one - or several search criteria: - - \list - - \li To make your search case sensitive, select - \uicontrol {Case Sensitive}. - - \li To search only whole words, select \uicontrol {Whole Words Only}. - - \li To search using regular expressions, select - \uicontrol {Use Regular Expressions}. Regular expressions used in \QC - are modeled on Perl regular expressions. For more information on - using regular expressions, see the documentation for the - QRegularExpression Class. - - \endlist - - \note If you have selected text before selecting \uicontrol {Find/Replace}, the - search is conducted within the selection. - - To replace occurrences of the existing text, enter the new text in the - \uicontrol {Replace with} field. - - \list - - \li To replace the selected occurrence and move to the next one, - click \uicontrol {Find Next} or press \key {Ctrl+=}. - - \li To replace the selected occurrence and move to the previous one, - click \uicontrol {Find Previous}. - - \li To replace all occurrences in the file, click - \uicontrol {Replace All}. - - \endlist - - The \uicontrol {Preserve Case when Replacing} option can be selected to - preserve the case of the original text when replacing. This option is not - compatible with the \uicontrol {Use Regular Expressions} search option, and will - thus be disabled when regular expressions are used. When the option is used, - the case of the occurrence will be conserved, according to the following - rules: - - \list - - \li All upper-case occurrences are replaced with the upper-case new - text. - \li All lower-case occurrences are replaced with the lower-case new - text. - - \li Capitalized occurrences are replaced with the capitalized new text. - - \li Other occurrences are replaced with the new text as entered. - - \li If an occurrence and the new text have the same prefix or suffix, - then the case of the prefix and/or suffix are preserved, and the - other rules are applied on the rest of the occurrence only. - - \endlist - - The locations of search hits, breakpoints, and bookmarks in your document - are highlighted on the editor scroll bar. To turn highlighting off, select - \uicontrol Tools > \uicontrol Options > \uicontrol {Text Editor} > - \uicontrol Display > \uicontrol {Highlight search results on the scrollbar}. - - \section1 Advanced Search - - To search through projects, files on a file system or currently open files: - - \list 1 - - \li Press \key {Ctrl+Shift+F} or select \uicontrol Edit > - \uicontrol {Find/Replace} > \uicontrol {Advanced Find} > - \uicontrol {Open Advanced Find}. - - \li Select the scope of your search: - - \list - - \li \uicontrol {All Projects} searches from all currently open - projects. - - \image qtcreator-search-allprojects.png - - \li \uicontrol {Current Project} searches from the project you - are currently editing. - - \li \uicontrol {Files in File System} recursively searches from - the selected directory. - - \image qtcreator-search-filesystem.png - - In the \uicontrol {Search engine} field, select the search - engine to use: - - \list - \li Select \uicontrol Internal to use the \QC search - engine. - - \li Select \uicontrol {Git Grep} to use Git to only - search tracked files in the Git work tree. To - restrict the search to the HEAD, a tag, a local or - remote branch, or a commit hash, enter a reference. - Leave the field empty to search through the file - system. - - \li Select \uicontrol {Silver Searcher} to use the - experimental Silver Searcher plugin. For more - information, see \l{Enabling Silver Searcher}. - - \endlist - - \li \uicontrol {Current File} searches only from the current - file. - - \li \uicontrol {Open Documents} searches from all open files. - - \li \uicontrol {Clang Query Project} explores the Clang abstract - syntax tree (AST) using AST matcher expressions. For more - information, see \l{Exploring Clang AST}. - - \endlist - - \li In the \uicontrol {File pattern} field, specify file patterns to - restrict the search to files that match the pattern. For example, to - search for a string only in \c {.cpp} and \c {.h} files, enter - \c {*.cpp,*.h}. - - \li In the \uicontrol {Exclusion pattern} field, specify file patterns - to omit files from the search. - - \li Enter the text you are looking for and click \uicontrol Search. - - \image qtcreator-searchresults.png - - A list of files containing the searched text is displayed in the - \uicontrol {Search Results} pane. - - \list - - \li To see all occurrences in a file, double-click the file name - in the list. - - \li To go to an occurrence, double-click it. - - \li To repeat the search after you have made changes to the - listed files, for example, select - \uicontrol {Search Again}. - - \endlist - - \endlist - - The search results are stored in the search history from which you can - select earlier searches. - - To clear the search results, select the \inlineimage clean_pane_small.png - (\uicontrol Clear) button. - - To start a new search, select the \inlineimage qtcreator-new-search-icon.png - (\uicontrol {New Search}) button. - - \note You can use \uicontrol {Advanced Find} also to search for symbols. For - more information, see \l{Finding Symbols}. - - \section1 Enabling Silver Searcher - - You can use Silver Searcher as a search engine in \QC if you install - Silver Searcher on the development PC and enable the experimental plugin. - - To use Silver Searcher: - - \list 1 - - \li Download and install Silver Searcher from - \l {https://geoff.greer.fm/ag/}{The Silver Searcher} or - \l {https://github.com/ggreer/the_silver_searcher}{GitHub}. - - You might have to build Silver Searcher from sources for some - platforms. - - \li Select \uicontrol Help > \uicontrol {About Plugins} > - \uicontrol {Utilities} > \uicontrol {SilverSearcher} to enable the - plugin. - - \li Restart \QC to be able to use the plugin. - - \li When searching, select \uicontrol {Silver Searcher} in the - \uicontrol {Search engine} field. - - \endlist - - \section1 Exploring Clang AST - - You can use the experimental Clang Refactoring plugin to explore the Clang - AST using AST matcher expressions. For more information about constructing - matcher expressions, see - \l {http://clang.llvm.org/docs/LibASTMatchersReference.html} - {AST Matcher Reference}. - - To explore the AST: - - \list 1 - - \li Select \uicontrol Help > \uicontrol {About Plugins} > \uicontrol C++ - > \uicontrol {ClangRefactoring} to enable the plugin. - - \li Restart \QC to be able to use the plugin. - - \li When searching, select \uicontrol {Clang Query Project} in the - \uicontrol {Scope} field. - - \li Enter an AST matcher expression in the \uicontrol {Search for} - field. - - \endlist - - You can view the results of the query as links to code positions in the - \uicontrol {Search Results} output pane. -*/ - - -/*! - \contentspage index.html - \previouspage creator-editor-locator.html - \page creator-editor-refactoring.html - \nextpage creator-beautifier.html - - \title Refactoring - - Refactor code to: - - \list - - \li Improve internal quality of your application - - \li Improve performance and extensibility - - \li Improve code readability and maintainability - - \li Simplify code structure - - \endlist - - \section1 Finding Symbols - - To find the use of a specific symbol or \l{glossary-component} - {QML component} in your Qt C++ or Qt Quick project: - - \list 1 - - \li In the editor, place the cursor on the symbol or component, and - select: - - \list - - \li \uicontrol Tools > \uicontrol {C++} > \uicontrol {Find Usages} - - \li \uicontrol Tools > \uicontrol {QML/JS} > - \uicontrol {Find Usages} - - \li \key {Ctrl+Shift+U} - - \endlist - - \QC looks for the symbol in the following locations: - - \list - - \li Files listed as a part of the project - - \li Files directly used by the project files (for example, generated - files) - - \li Header files of used frameworks and libraries - - \endlist - - \note You can also select \uicontrol Edit > \uicontrol {Find/Replace} > - \uicontrol {Advanced Find} > \uicontrol {C++ Symbols} to search for - classes, functions, enums, and declarations either from files listed as - part of the project or from all files that are used by the code, such as - include files. - - \image qtcreator-search-cpp-symbols.png - - \li The \uicontrol {Search Results} pane opens and shows the location - and number of instances of the symbol in the current project. - - \image qtcreator-refactoring-find.png - - \endlist - - You can browse the search results in the following ways: - - \list - - \li To go directly to an instance, double-click the instance in the - \uicontrol {Search Results} pane. - - \li To move between instances, click the \inlineimage next.png - (\uicontrol {Next Item}) button and \inlineimage prev.png - (\uicontrol {Previous Item}) button in the - \uicontrol {Search Results} pane. - - \li To expand and collapse the list of all instances, click the - \inlineimage qtcreator-expand.png - (\uicontrol {Expand All}) button. - - \li To clear the search results, click the - \inlineimage clean_pane_small.png - (\uicontrol Clear) button. - - \li To start a new search, click the - \inlineimage qtcreator-new-search-icon.png - (\uicontrol {New Search}) button. - \endlist - - \section1 Renaming Symbols - - You can rename symbols in all files in a project. When you rename a class, - you can also change filenames that match the class name. - - To rename a specific symbol in a Qt project: - - \list 1 - - \li In the editor, place the cursor on the symbol you would like to - change and select \uicontrol Tools > \uicontrol {C++} > - \uicontrol {Rename Symbol Under Cursor} or - \uicontrol Tools > \uicontrol {QML/JS} > - \uicontrol {Rename Symbol Under Cursor}. Alternatively, press - \key {Ctrl+Shift+R}. - - The \uicontrol {Search Results} pane opens and shows the location - and number of instances of the symbol in the current project. - - \image qtcreator-refactoring-replace.png - - \li To replace all selected instances, enter the name of the new symbol - in the \uicontrol {Replace with} text box. - - To omit an instance, uncheck the check-box next to the instance. - - \li If the symbol is a class, select the \uicontrol {Rename files} check - box to also change the filenames that match the class name. - - \li Select \uicontrol Replace. - - \note This action replaces all selected instances of the symbol in - all files listed in the \uicontrol {Search Results} pane. You cannot - undo this action. - \endlist - - \note Renaming local symbols does not open the \uicontrol {Search Results} - pane. The instances of the symbol are highlighted in code and you can edit - the symbol. All instances of the local symbol are changed as you type. - - \section1 Column Editing - - To apply a change to several rows in a column simultaneously, press - \key Alt, select the rows, and enter or remove text. The changes are made - simultaneously at the cursor position on all the selected rows. - - \section1 Applying Refactoring Actions - - \QC allows you to quickly and conveniently apply actions to refactor your - code by selecting them in a context menu. The actions available depend on - the position of the cursor in the code editor and on whether you are writing - C++ or QML code. - - To apply refactoring actions to C++ code, right-click an operand, - conditional statement, string, or name to open a context menu. In QML code, - click an item ID or name. - - In the context menu, select \uicontrol {Refactoring} and then select a - refactoring action. - - You can also press \key {Alt+Enter} to open a context menu that contains - refactoring actions available in the current cursor position. - - If you use the \l{Parsing C++ Files with the Clang Code Model}{Clang code model} to parse the C++ - files, the \l{http://clang.llvm.org/diagnostics.html}{Clang fix-it hints} - that have been integrated into \QC are also available to you. In addition to - the standard ways of activating refactoring actions, you can select the - actions that are applicable on a line in the context menu in the left margin - of the code editor. - - \section2 Refactoring C++ Code - - You can apply the following types of refactoring actions to C++ code: - - \list - - \li Change binary operands - - \li Simplify if and while conditions (for example, move declarations out - of if conditions) - - \li Modify strings (for example, set the encoding for a string to - Latin-1, mark strings translatable, and convert symbol names to - camel case) - - \li Create variable declarations - - \li Create function declarations and definitions - - \endlist - - The following table summarizes the refactoring actions for C++ code. The - action is available when the cursor is in the position described in the - Activation column. - - \table - \header - \li Refactoring Action - \li Description - \li Activation - \row - \li Add Curly Braces - \li Adds curly braces to an if statement that does not contain a - compound statement. For example, rewrites - - \code - if (a) - b; - \endcode - - as - - \code - if (a) { - b; - } - \endcode - \li \c if - \row - \li Move Declaration out of Condition - \li Moves a declaration out of an if or while condition to simplify - the condition. For example, rewrites - - \code - if (Type name = foo()) {} - \endcode - - as - - \code - Type name = foo; - if (name) {} - \endcode - \li Name of the introduced variable - \row - \li Rewrite Condition Using || - \li Rewrites the expression according to De Morgan's laws. For - example, rewrites: - \code - !a && !b - \endcode - - as - - \code - !(a || b) - \endcode - \li \c && - \row - \li Rewrite Using \e operator - \li Rewrites an expression negating it and using the inverse - operator. For example, rewrites: - - \list - - \li \code - a op b - \endcode - - as - - \code - !(a invop b) - \endcode - - \li \code - (a op b) - \endcode - - as - - \code - !(a invop b) - \endcode - - \li \code - !(a op b) - \endcode - - as - - \code - (a invob b) - \endcode - - \endlist - - \li \c {<=}, \c {<}, \c {>}, \c {>=}, \c {==} or \c {!=} - \row - \li Split Declaration - \li Splits a simple declaration into several declarations. For - example, rewrites: - \code - int *a, b; - \endcode - - as - - \code - int *a; - int b; - \endcode - \li Type name or variable name - \row - \li Split if Statement - \li Splits an if statement into several statements. For example, - rewrites: - - \code - if (something && something_else) { - } - \endcode - - as - - \code - if (something) { - if (something_else) { - } - } - \endcode - - and - - \code - if (something || something_else) - x; - \endcode - - with - - \code - if (something) - x; - else if (something_else) - x; - \endcode - - \li \c && or \c || - \row - \li Swap Operands - \li Rewrites an expression in the inverse order using the inverse - operator. For example, rewrites: - \code - a op b - \endcode - - as - \code - b flipop a - \endcode - \li \c {<=}, \c {<}, \c {>}, \c {>=}, \c {==}, \c {!=}, \c {&&} - or \c {||} - \row - \li Convert to Decimal - \li Converts an integer literal to decimal representation - \li Numeric literal - \row - \li Convert to Hexadecimal - \li Converts an integer literal to hexadecimal representation - \li Numeric literal - \row - \li Convert to Octal - \li Converts an integer literal to octal representation - \li Numeric literal - \row - \li Convert to Objective-C String Literal - \li Converts a string literal to an Objective-C string literal if - the file type is Objective-C(++). For example, rewrites the - following strings - - \code - "abcd" - QLatin1String("abcd") - QLatin1Literal("abcd") - \endcode - - as - - \code - @"abcd" - \endcode - \li String literal - \row - \li Enclose in QLatin1Char() - \li Sets the encoding for a character to Latin-1, unless the - character is already enclosed in QLatin1Char, QT_TRANSLATE_NOOP, - tr, trUtf8, QLatin1Literal, or QLatin1String. For example, - rewrites - - \code - 'a' - \endcode - - as - - \code - QLatin1Char('a') - \endcode - \li String literal - \row - \li Enclose in QLatin1String() - \li Sets the encoding for a string to Latin-1, unless the string is - already enclosed in QLatin1Char, QT_TRANSLATE_NOOP, tr, trUtf8, - QLatin1Literal, or QLatin1String. For example, rewrites - \code - "abcd" - \endcode - - as - - \code - QLatin1String("abcd") - \endcode - - \li String literal - - \row - \li Mark as Translatable - \li Marks a string translatable. For example, rewrites \c "abcd" - with one of the following options, depending on which of them is - available: - - \code - tr("abcd") - QCoreApplication::translate("CONTEXT", "abcd") - QT_TRANSLATE_NOOP("GLOBAL", "abcd") - \endcode - - \li String literal - - \row - \li Add Definition in ... - \li Inserts a definition stub for a function declaration either in - the header file (inside or outside the class) or in the - implementation file. For free functions, inserts the definition - after the declaration of the function or in the implementation - file. Qualified names are minimized when possible, instead of - always being fully expanded. - - For example, rewrites - - \code - Class Foo { - void bar(); - }; - \endcode - - as (inside class) - - \code - Class Foo { - void bar() { - - } - }; - \endcode - - as (outside class) - - \code - Class Foo { - void bar(); - }; - - void Foo::bar() - { - - } - \endcode - - as (in implementation file) - - \code - // Header file - Class Foo { - void bar(); - }; - - // Implementation file - void Foo::bar() - { - - } - \endcode - - \li Function name - \row - \li Add \c Function Declaration - \li Inserts the member function declaration that matches the member - function definition into the class declaration. The function can - be \c {public}, \c {protected}, \c {private}, \c {public slot}, - \c {protected slot}, or \c {private slot}. - \li Function name - \row - \li Switch with Next/Previous Parameter - \li Moves a parameter down or up one position in a parameter list. - \li Parameter in the declaration or definition of a function - \row - \li Extract Function - \li Moves the selected code to a new function and replaces the block - of code with a call to the new function. Enter a name for the - function in the \uicontrol {Extract Function Refactoring} - dialog. - \li Block of code selected - \row - \li Extract Constant as Function Parameter - \li Replaces the selected literal and all its occurrences with the - function parameter \c{newParameter}. The parameter - \c{newParameter} will have the original literal as the default - value. - \li Block of code selected - \row - \li Add Local Declaration - \li Adds the type of an assignee, if the type of the right-hand - side of the assignment is known. For example, rewrites - - \code - a = foo(); - \endcode - - as - - \code - Type a = foo(); - \endcode - - where Type is the return type of \c {foo()} - - \li Assignee - - \row - \li Convert to Camel Case - \li Converts a symbol name to camel case, where elements of the name - are joined without delimiter characters and the initial - character of each element is capitalized. For example, rewrites - \c an_example_symbol as \c anExampleSymbol and - \c AN_EXAMPLE_SYMBOL as \c AnExampleSymbol - \li Identifier - \row - \li Complete Switch Statement - \li Adds all possible cases to a switch statement of the type - \c enum - \li \c switch - \row - \li Generate Missing Q_PROPERTY Members - \li Adds missing members to a \c Q_PROPERTY: - \list - \li \c read function - \li \c write function, if there is a WRITE - \li \c {onChanged} signal, if there is a NOTIFY - \li data member with the name \c {m_} - \endlist - \li \c Q_PROPERTY - \row - \li Apply Changes - \li Keeps function declarations and definitions synchronized by - checking for the matching declaration or definition when you - edit a function signature and by applying the changes to the - matching code. - \li Function signature. When this action is available, a light bulb - icon appears: \inlineimage refactormarker.png - \row - \li Add #include for undeclared or forward declared identifier - \li Adds an \c {#include} directive to the current file to make the - definition of a symbol available. - \li Undeclared identifier - \row - \li Reformat Pointers or References - \li Reformats declarations with pointers or references according - to the code style settings for the current project. In case no - project is open, the current global code style settings are - used. - - For example, rewrites: - - \code - char*s; - \endcode - - as - - \code - char *s; - \endcode - - When applied to selections, all suitable declarations in the - selection are rewritten. - - \li Declarations with pointers or references and selections - containing such declarations - \row - \li Create Getter and Setter Member Functions - \li Creates either both getter and setter member functions for - member variables or only a getter or setter. - \li Member variable in class definition - \row - \li Move Function Definition - \li Moves a function definition to the implementation file, outside - the class or back to its declaration. For example, rewrites: - \code - class Foo - { - void bar() - { - // do stuff here - } - }; - \endcode - - as - \code - class Foo - { - void bar(); - }; - - void Foo::bar() { - // do stuff here - } - \endcode - - \li Function signature - \row - \li Move All Function Definitions - \li Moves all function definitions to the implementation file or - outside the class. For example, rewrites: - \code - class Foo - { - void bar() - { - // do stuff here - } - void baz() - { - // do stuff here - } - }; - \endcode - - as - - \code - class Foo - { - void bar(); - void baz(); - }; - - void Foo::bar() { - // do stuff here - } - - void Foo::baz() { - // do stuff here - } - \endcode - - \li Class name - \row - \li Assign to Local Variable - \li Adds a local variable which stores the return value of a - function call or a new expression. For example, rewrites: - - \code - QString s; - s.toLatin1(); - \endcode - - as - - \code - QString s; - QByteArray latin1 = s.toLatin1(); - \endcode - - and - - \code - new Foo; - \endcode - - as - - \code - Foo * localFoo = new Foo; - \endcode - - \li Function call or class name - \row - \li Insert (Pure) Virtual Functions - \li Select an insertion mode: - \list - \li Insert only declarations. - \li Insert declarations and the corresponding definitions inside the class. - \li Insert declarations and the corresponding definitions outside the class. - \li Insert declarations and the corresponding definitions in the implementation file - (only if an implementation file exists). - \endlist - \image qtcreator-refactoring-virtual-function-dialog.png - - \li Class or base class name - \row - \li Optimize for-Loop - \li Rewrites post increment operators as pre increment operators and - post decrement operators as pre decrement operators. It also - moves other than string or numeric literals and id expressions - from the condition of a for loop to its initializer. For - example, rewrites: - - \code - for (int i = 0; i < 3 * 2; i++) - \endcode - - as - - \code - for (int i = 0, total = 3 * 2; i < total; ++i) - \endcode - \li \c for - - \row - \li Escape String Literal as UTF-8 - \li Escapes non-ASCII characters in a string literal to hexadecimal - escape sequences. String Literals are handled as UTF-8. - \li String literal - - \row - \li Unescape String Literal as UTF-8 - \li Unescapes octal or hexadecimal escape sequences in a string - literal. String Literals are handled as UTF-8. - \li String literal - - \row - \li Convert to Stack Variable - \li Converts the selected pointer to a stack variable. For example, - rewrites: - - \code - QByteArray *foo = new QByteArray("foo"); - foo->append("bar"); - \endcode - - as - - \code - QByteArray foo = "foo"; - foo.append("bar"); - \endcode - - This operation is limited to work only within function scope. - Also, the coding style for pointers and references is not - respected yet. - \li Pointer Variable - - \row - \li Convert to Pointer - \li Converts the selected stack variable to a pointer. For example, - rewrites: - - \code - QByteArray foo = "foo"; - foo.append("bar"); - \endcode - - as - - \code - QByteArray *foo = new QByteArray("foo"); - foo->append("bar"); - \endcode - - This operation is limited to work only within function scope. - Also, the coding style for pointers and references is not - respected yet. - \li Stack Variable - \row - \li Convert connect() to Qt 5 Style - \li Converts a Qt 4 QObject::connect() to Qt 5 style. - \li QObject::connect() (Qt 4 style) - \endtable - - - - \section2 Refactoring QML Code - - You can apply the following types of refactoring actions to QML code: - - \list - - \li Rename IDs - - \li Split initializers - - \li Move a QML type into a separate file to reuse it in other .qml files - - \endlist - - The following table summarizes the refactoring actions for QML code. The - action is available when the cursor is in the position described in the - Activation column. - - \table - \header - \li Refactoring Action - \li Description - \li Activation - - \row - \li Move Component into Separate File - \li Moves a QML type into a separate file. Give the new component a - name and select whether properties are set for the new component - or for the original one. - - \image qtcreator-move-component-into-separate-file.png - - \li QML type name. This action is also available in the - \uicontrol {Form Editor} in the Design mode. - \row - \li Split Initializer - \li Reformats a one-line type into a multi-line type. For example, - rewrites - - \code - Item { x: 10; y: 20; width: 10 } - \endcode - - as - - \code - Item { - x: 10; - y: 20; - width: 10 - } - \endcode - - \li QML type property - \row - \li Wrap Component in Loader - \li Wraps the type in a Component type and loads it dynamically in a - Loader type. This is usually done to improve startup time. - \li QML type name - \row - \li Add a message suppression comment - \li Prepends the line with an annotation comment that stops the - message from being generated. - \li Error, warning or hint from static analysis - - \endtable - */ - - -/*! - \contentspage index.html - \previouspage creator-editor-finding.html - \page creator-editor-locator.html - \nextpage creator-editor-refactoring.html - - \title Searching with the Locator - - You can find the locator in the bottom left of the \QC window. - - \image qtcreator-locator.png - - To activate the locator: - - \list - - \li Press \key {Ctrl+K} (\key {Cmd+K} on \macos). - - \li Select \uicontrol Tools > \uicontrol Locate. - - \li Select \uicontrol Edit > \uicontrol {Go to Line}. - - \li Click the line and column indicator on the - \l{Using the Editor Toolbar}{editor toolbar}. - - \endlist - - To edit the currently open project's main.cpp file using the locator: - - \list 1 - - \li Activate the locator by pressing \key {Ctrl+K}. - - \li Enter \c {main.cpp}. - - \image qtcreator-locator-open.png - - \li Press \key Enter. - - The \c {main.cpp} file opens in the editor. - - \li To move to a line in the file, enter the line number in the locator. - - \endlist - - To move directly to a particular line and column in the document when you - open the document, append them to the file name in the locator, separated by - plus signs (+) or colons (:). For example, to open main.cpp to line 41 and - column 2, enter: \c {main.cpp:41:2}. - - If the path to a file is very long, it might not fit into the locator - window. To view the full path, press \key Alt when the filename is selected - or use the handle next to the locator window to increase the window width. - - It is also possible to enter only a part of a search string. As you type, - the locator shows the occurrences of that string regardless of where in the - name of an component it appears. Some locator filters, such as colon and - \c m, support \e fuzzy matching, which means that you can enter the - uppercase letters to locate a symbol when using camel case or the letters - after the underscore when using snake case. - - To narrow down the search results, you can use the following wildcard - characters: - - \list - - \li To match any number of any or no characters, enter \c{*}. - - \li To match a single instance of any character, enter \c{?}. - - \endlist - - \section1 Using Locator Filters - - The locator enables you to browse not only files, but any items defined by - \b{locator filters}. By default, the locator contains filters for: - - \list - - \li Locating any open document (\c {o}) - - \li Locating files anywhere on your file system (\c {f}) - - \li Locating files belonging to your project (\c {p}), such as source, - header resource, and \c {.ui} files, or to any project (\c {a}) - - \li Locating bookmarks (\c {b}). - For more information, see \l{Using Bookmarks}. - - \li Locating class (\c {c}), enum, and function (m) definitions in your - project or anywhere referenced from your project (\c {:}) - - \li Locating symbols in the current document (\c {.}) - - \li Locating a specific line and column in the document displayed in - your editor (\c {l :}) - - \li Opening help topics, including Qt documentation (\c {?}) - - \li Performing web searches (\c {r}) - - \li Running text editing macros that you record and save (\c {rm}). For - more information, see \l{Using Text Editing Macros} - - \li Executing JavaScript (\c {=}), especially useful for calculations. - For more information, see \l{Executing JavaScript}. - - \li Executing shell commands (\c {!}) - - \li Executing version control system commands (\c {git}). For more - information, see \l{Using Version Control Systems} - - \li Triggering menu items from the main menu (\c {t}) - - \li Running external tools (\c x) - - \endlist - - To use a specific locator filter, type the assigned prefix followed by - \key Space. The prefix is usually a single character. Then type the search - string (typically, a filename or class name) or the command to execute. - - You can also double-click a locator filter in the filter list to use it. You - can use the up and down arrow keys or the \key Ctrl+P and \key Ctrl+N - keyboard shortcuts to move up and down the list, and then press \key Enter - to use the selected filter. - - For example, to locate symbols matching QDataStream: - - \list 1 - - \li Activate the locator. - - \li Enter a colon (:) followed by a space and the upper case letters in - the symbol name (QDataStream): - - \code - : qds - \endcode - - The locator lists the results. - - \image qtcreator-navigate-popup.png - - \endlist - - Filters locating files also accept paths, such as \c {tools/*main.cpp}. - Filters locating class and function definitions also accept namespaces, - such as \c {Utils::*View}. - - For example, to create a new file and open it in the editor, type \c f - followed by \key Space, followed by path and file name, and then press - \key Enter. - - You can use the filter that triggers menu commands to open sessions. Enter - \c {t yoursess} or \c {t sess yoursess} to trigger \uicontrol File > - \uicontrol Sessions > \e yoursessionname. - - By default, the following filters are enabled and you do not need to use - their prefixes explicitly: - - \list - - \li Going to a line and column in the current file (\c {l}). - - \li Going to an open file (\c {o}). - - \li Going to a file in any open project (\c {a}). - - \endlist - - If locator does not find some files, you can add them to the \c DISTFILES - variable in the \c .pro file to include them into the distribution tarball - of your project and thus make them known to \QC as well. - - \section1 Configuring Locator Filters - - If the default filters do not match your use case, you can check whether you - can change them. For all filters, you can change the filter prefix and - restrict the search to items that match the filter. - - To configure a locator filter: - - \list 1 - - \li In the locator, click \inlineimage magnifier.png - (\uicontrol Options) and select \uicontrol Configure to open the - \uicontrol Locator options. - - \li Select a filter, and then select \uicontrol Edit. - - \li Specify the prefix string. - - \li To implicitly include the filter even when not typing a prefix as a - part of the search string, select \uicontrol {Include by default}. - - \li Specify other available options. For more information, see - \l{Adding Web Search Engines}. - - \endlist - - \section2 Adding Web Search Engines - - You can use the \uicontrol {Web Search (r)} locator filter to perform - web searches. URLs and search commands for Bing, Google, Yahoo! Search, - cplusplus.com, and Wikipedia are configured by default. - - To find out the format of the search command to use for your favorite - web search engine, perform a search in your browser and copy the resulting - URL to the locator filter configuration. Replace the search term with the - variable \c {%1}. - - To add URLs and search commands to the list: - - \list 1 - - \li Select \uicontrol Tools > \uicontrol Options > - \uicontrol Environment > \uicontrol Locator > - \uicontrol {Web Search (prefix: r)} > \uicontrol Edit. - - \li Select \uicontrol Add to add a new entry to the list. - - \image qtcreator-add-online-doc.png "Filter Configuration dialog" - - \li Double-click the new entry to specify a URL and a search command. - For example, \c {http://www.google.com/search?q=%1}. - - \li Click \uicontrol OK. - - \endlist - - \section1 Creating Locator Filters - - To quickly access files not directly mentioned in your project, you can - create your own locator filters. That way you can locate files in a - directory structure you have defined. - - To create a locator filter: - - \list 1 - - \li In the locator, select \uicontrol Options > - \uicontrol Configure to open the \uicontrol Locator options. - - \image qtcreator-locator-customize.png - - \li Click \uicontrol Add. - - \li In the \uicontrol {Filter Configuration} dialog: - - \list - - \li Name your filter. - - \li Select at least one directory. The locator searches directories - recursively. - - \li Define the file pattern as a comma separated list. For example, - to search all \c {.h} and \c {.cpp} files, enter \c{*.h,*.cpp} - - \li Specify the prefix string. - - To implicitly include the filter even when not typing a prefix - as a part of the search string, select - \uicontrol {Include by default}. - - \image qtcreator-navigate-customfilter.png - - \endlist - - \li Click \uicontrol OK. - - \endlist - - \section1 Configuring Locator Cache - - The locator searches the files matching your file pattern in the directories - you have selected and caches that information. The cache for all default - filters is updated as you write your code. By default, \QC updates the - filters created by you once an hour. - - To update the cached information manually, select \uicontrol Options > - \uicontrol Refresh in the locator. - - To set a new cache update time: - - \list 1 - - \li Select \uicontrol Tools > \uicontrol Options > - \uicontrol Environment > \uicontrol Locator. - - \li In \uicontrol {Refresh interval}, define new time in minutes. - - \endlist - - \section1 Executing JavaScript - - The locator provides access to a JavaScript interpreter, that can be used to - perform calculations. - - Beside simple mathematical operations, like ((1 + 2) * 3), the following - built-in functions exist: - - \table - \header - \li Function - \li Purpose - \row - \li abs(x) - \li Returns the absolute value of x - \row - \li acos(x) - \li Returns the arccosine of x, in radians - \row - \li asin(x) - \li Returns the arcsine of x, in radians - \row - \li atan(x) - \li Returns the arctangent of x, in radians - \row - \li atan2(x, y) - \li Returns the arctangent of the quotient of its arguments - \row - \li bin(x) - \li Returns the binary representation of x - \row - \li ceil(x) - \li Returns the value of x rounded up to the next integer - \row - \li cos(x) - \li Returns the cosine of x (x is in radians) - \row - \li exp(x) - \li Returns the value of E to the power of x - \row - \li e() - \li Returns Euler's number E (2.71828...) - \row - \li floor(x) - \li Returns the value of x rounded down to the next integer - \row - \li hex(x) - \li Returns the hexadecimal representation of x - \row - \li log(x) - \li Returns the natural logarithm (base E) of x - \row - \li max([value1[, value2[, ...]]]) - \li Returns the highest value of the given numbers - \row - \li min([value1[, value2[, ...]]]) - \li Returns the lowest value of the given numbers - \row - \li oct(x) - \li Returns the octal representation of x - \row - \li pi() - \li Returns PI (3.14159...) - \row - \li pow(x, y) - \li Returns the value of x to the power of y - \row - \li random() - \li Returns a random number between 0 and 1 - \row - \li round(x) - \li Returns the value of x rounded to the next integer - \row - \li sin(x) - \li Returns the sine of x (x is in radians) - \row - \li sqrt(x) - \li Returns the square root of x - \row - \li tan(x) - \li Returns the tangent of x (x is in radians) - \endtable -*/ diff --git a/doc/src/editors/creator-locator.qdoc b/doc/src/editors/creator-locator.qdoc new file mode 100644 index 00000000000..e46628ba423 --- /dev/null +++ b/doc/src/editors/creator-locator.qdoc @@ -0,0 +1,403 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** 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. +** +****************************************************************************/ + +/*! + \contentspage index.html + \previouspage creator-editor-finding.html + \page creator-editor-locator.html + \nextpage creator-editor-refactoring.html + + \title Searching with the Locator + + You can find the locator in the bottom left of the \QC window. + + \image qtcreator-locator.png + + To activate the locator: + + \list + + \li Press \key {Ctrl+K} (\key {Cmd+K} on \macos). + + \li Select \uicontrol Tools > \uicontrol Locate. + + \li Select \uicontrol Edit > \uicontrol {Go to Line}. + + \li Click the line and column indicator on the + \l{Using the Editor Toolbar}{editor toolbar}. + + \endlist + + To edit the currently open project's main.cpp file using the locator: + + \list 1 + + \li Activate the locator by pressing \key {Ctrl+K}. + + \li Enter \c {main.cpp}. + + \image qtcreator-locator-open.png + + \li Press \key Enter. + + The \c {main.cpp} file opens in the editor. + + \li To move to a line in the file, enter the line number in the locator. + + \endlist + + To move directly to a particular line and column in the document when you + open the document, append them to the file name in the locator, separated by + plus signs (+) or colons (:). For example, to open main.cpp to line 41 and + column 2, enter: \c {main.cpp:41:2}. + + If the path to a file is very long, it might not fit into the locator + window. To view the full path, press \key Alt when the filename is selected + or use the handle next to the locator window to increase the window width. + + It is also possible to enter only a part of a search string. As you type, + the locator shows the occurrences of that string regardless of where in the + name of an component it appears. Some locator filters, such as colon and + \c m, support \e fuzzy matching, which means that you can enter the + uppercase letters to locate a symbol when using camel case or the letters + after the underscore when using snake case. + + To narrow down the search results, you can use the following wildcard + characters: + + \list + + \li To match any number of any or no characters, enter \c{*}. + + \li To match a single instance of any character, enter \c{?}. + + \endlist + + \section1 Using Locator Filters + + The locator enables you to browse not only files, but any items defined by + \b{locator filters}. By default, the locator contains filters for: + + \list + + \li Locating any open document (\c {o}) + + \li Locating files anywhere on your file system (\c {f}) + + \li Locating files belonging to your project (\c {p}), such as source, + header resource, and \c {.ui} files, or to any project (\c {a}) + + \li Locating bookmarks (\c {b}). + For more information, see \l{Using Bookmarks}. + + \li Locating class (\c {c}), enum, and function (m) definitions in your + project or anywhere referenced from your project (\c {:}) + + \li Locating symbols in the current document (\c {.}) + + \li Locating a specific line and column in the document displayed in + your editor (\c {l :}) + + \li Opening help topics, including Qt documentation (\c {?}) + + \li Performing web searches (\c {r}) + + \li Running text editing macros that you record and save (\c {rm}). For + more information, see \l{Using Text Editing Macros} + + \li Executing JavaScript (\c {=}), especially useful for calculations. + For more information, see \l{Executing JavaScript}. + + \li Executing shell commands (\c {!}) + + \li Executing version control system commands (\c {git}). For more + information, see \l{Using Version Control Systems} + + \li Triggering menu items from the main menu (\c {t}) + + \li Running external tools (\c x) + + \endlist + + To use a specific locator filter, type the assigned prefix followed by + \key Space. The prefix is usually a single character. Then type the search + string (typically, a filename or class name) or the command to execute. + + You can also double-click a locator filter in the filter list to use it. You + can use the up and down arrow keys or the \key Ctrl+P and \key Ctrl+N + keyboard shortcuts to move up and down the list, and then press \key Enter + to use the selected filter. + + For example, to locate symbols matching QDataStream: + + \list 1 + + \li Activate the locator. + + \li Enter a colon (:) followed by a space and the upper case letters in + the symbol name (QDataStream): + + \code + : qds + \endcode + + The locator lists the results. + + \image qtcreator-navigate-popup.png + + \endlist + + Filters locating files also accept paths, such as \c {tools/*main.cpp}. + Filters locating class and function definitions also accept namespaces, + such as \c {Utils::*View}. + + For example, to create a new file and open it in the editor, type \c f + followed by \key Space, followed by path and file name, and then press + \key Enter. + + You can use the filter that triggers menu commands to open sessions. Enter + \c {t yoursess} or \c {t sess yoursess} to trigger \uicontrol File > + \uicontrol Sessions > \e yoursessionname. + + By default, the following filters are enabled and you do not need to use + their prefixes explicitly: + + \list + + \li Going to a line and column in the current file (\c {l}). + + \li Going to an open file (\c {o}). + + \li Going to a file in any open project (\c {a}). + + \endlist + + If locator does not find some files, you can add them to the \c DISTFILES + variable in the \c .pro file to include them into the distribution tarball + of your project and thus make them known to \QC as well. + + \section1 Configuring Locator Filters + + If the default filters do not match your use case, you can check whether you + can change them. For all filters, you can change the filter prefix and + restrict the search to items that match the filter. + + To configure a locator filter: + + \list 1 + + \li In the locator, click \inlineimage magnifier.png + (\uicontrol Options) and select \uicontrol Configure to open the + \uicontrol Locator options. + + \li Select a filter, and then select \uicontrol Edit. + + \li Specify the prefix string. + + \li To implicitly include the filter even when not typing a prefix as a + part of the search string, select \uicontrol {Include by default}. + + \li Specify other available options. For more information, see + \l{Adding Web Search Engines}. + + \endlist + + \section2 Adding Web Search Engines + + You can use the \uicontrol {Web Search (r)} locator filter to perform + web searches. URLs and search commands for Bing, Google, Yahoo! Search, + cplusplus.com, and Wikipedia are configured by default. + + To find out the format of the search command to use for your favorite + web search engine, perform a search in your browser and copy the resulting + URL to the locator filter configuration. Replace the search term with the + variable \c {%1}. + + To add URLs and search commands to the list: + + \list 1 + + \li Select \uicontrol Tools > \uicontrol Options > + \uicontrol Environment > \uicontrol Locator > + \uicontrol {Web Search (prefix: r)} > \uicontrol Edit. + + \li Select \uicontrol Add to add a new entry to the list. + + \image qtcreator-add-online-doc.png "Filter Configuration dialog" + + \li Double-click the new entry to specify a URL and a search command. + For example, \c {http://www.google.com/search?q=%1}. + + \li Click \uicontrol OK. + + \endlist + + \section1 Creating Locator Filters + + To quickly access files not directly mentioned in your project, you can + create your own locator filters. That way you can locate files in a + directory structure you have defined. + + To create a locator filter: + + \list 1 + + \li In the locator, select \uicontrol Options > + \uicontrol Configure to open the \uicontrol Locator options. + + \image qtcreator-locator-customize.png + + \li Click \uicontrol Add. + + \li In the \uicontrol {Filter Configuration} dialog: + + \list + + \li Name your filter. + + \li Select at least one directory. The locator searches directories + recursively. + + \li Define the file pattern as a comma separated list. For example, + to search all \c {.h} and \c {.cpp} files, enter \c{*.h,*.cpp} + + \li Specify the prefix string. + + To implicitly include the filter even when not typing a prefix + as a part of the search string, select + \uicontrol {Include by default}. + + \image qtcreator-navigate-customfilter.png + + \endlist + + \li Click \uicontrol OK. + + \endlist + + \section1 Configuring Locator Cache + + The locator searches the files matching your file pattern in the directories + you have selected and caches that information. The cache for all default + filters is updated as you write your code. By default, \QC updates the + filters created by you once an hour. + + To update the cached information manually, select \uicontrol Options > + \uicontrol Refresh in the locator. + + To set a new cache update time: + + \list 1 + + \li Select \uicontrol Tools > \uicontrol Options > + \uicontrol Environment > \uicontrol Locator. + + \li In \uicontrol {Refresh interval}, define new time in minutes. + + \endlist + + \section1 Executing JavaScript + + The locator provides access to a JavaScript interpreter, that can be used to + perform calculations. + + Beside simple mathematical operations, like ((1 + 2) * 3), the following + built-in functions exist: + + \table + \header + \li Function + \li Purpose + \row + \li abs(x) + \li Returns the absolute value of x + \row + \li acos(x) + \li Returns the arccosine of x, in radians + \row + \li asin(x) + \li Returns the arcsine of x, in radians + \row + \li atan(x) + \li Returns the arctangent of x, in radians + \row + \li atan2(x, y) + \li Returns the arctangent of the quotient of its arguments + \row + \li bin(x) + \li Returns the binary representation of x + \row + \li ceil(x) + \li Returns the value of x rounded up to the next integer + \row + \li cos(x) + \li Returns the cosine of x (x is in radians) + \row + \li exp(x) + \li Returns the value of E to the power of x + \row + \li e() + \li Returns Euler's number E (2.71828...) + \row + \li floor(x) + \li Returns the value of x rounded down to the next integer + \row + \li hex(x) + \li Returns the hexadecimal representation of x + \row + \li log(x) + \li Returns the natural logarithm (base E) of x + \row + \li max([value1[, value2[, ...]]]) + \li Returns the highest value of the given numbers + \row + \li min([value1[, value2[, ...]]]) + \li Returns the lowest value of the given numbers + \row + \li oct(x) + \li Returns the octal representation of x + \row + \li pi() + \li Returns PI (3.14159...) + \row + \li pow(x, y) + \li Returns the value of x to the power of y + \row + \li random() + \li Returns a random number between 0 and 1 + \row + \li round(x) + \li Returns the value of x rounded to the next integer + \row + \li sin(x) + \li Returns the sine of x (x is in radians) + \row + \li sqrt(x) + \li Returns the square root of x + \row + \li tan(x) + \li Returns the tangent of x (x is in radians) + \endtable +*/ diff --git a/doc/src/editors/creator-only/creator-code-pasting.qdoc b/doc/src/editors/creator-only/creator-code-pasting.qdoc new file mode 100644 index 00000000000..bedf2869fb8 --- /dev/null +++ b/doc/src/editors/creator-only/creator-code-pasting.qdoc @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** 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. +** +****************************************************************************/ + +/*! + \contentspage index.html + \previouspage qt-quick-toolbars.html + \page creator-editor-codepasting.html + \nextpage creator-macros.html + + \title Pasting and Fetching Code Snippets + + In \QC, you can paste snippets of code to a server or fetch snippets of + code from the server. To paste and fetch snippets of code, \QC uses the + following: + + \list + \li \uicontrol {Pastebin.Com} + \li \uicontrol {Pastebin.Ca} + \li \uicontrol {Paste.KDE.Org} + \li \uicontrol {Shared network drives} + \endlist + + \section1 Specifying Settings for Code Pasting + + To specify settings for the code pasting service: + + \list 1 + \li Select \uicontrol Tools > \uicontrol Options > + \uicontrol {Code Pasting}. + \image qtcreator-code-pasting-options.png "Code Pasting options" + \li In the \uicontrol {Default protocol} field, select a code pasting + service to use by default. + \li In the \uicontrol Username field, enter your username. + \li In the \uicontrol {Expires after} field, specify the time to keep + the pasted snippet on the server. + \li Select the \uicontrol {Copy-paste URL to clipboard} check box to + copy the URL of the post on the code pasting service to the + clipboard when you paste a post. + \li Select the \uicontrol {Display Output pane after sending a post} + check box to display the URL in the \uicontrol {General Messages} + output pane when you paste a post. + \endlist + + Select \uicontrol Fileshare to specify the path to a shared network drive. + The code snippets are copied to the drive as simple files. You have to + delete obsolete files from the drive manually. + + \section1 Using Code Pasting Services + + To paste a snippet of code onto the server, select \uicontrol Tools > + \uicontrol {Code Pasting} > \uicontrol {Paste Snippet} or press + \key {Alt+C,Alt+P}. By default, \QC copies the URL of the snippet to the + clipboard and displays the URL in the \uicontrol {General Messages} output + pane. + + To paste any content that you copied to the clipboard, select + \uicontrol Tools > \uicontrol {Code Pasting} > \uicontrol {Paste Snippet}. + + To paste content from the \l{Comparing Files}{diff editor}, right-click a + chunk and select \uicontrol {Send Chunk to CodePaster} in the context menu. + + To fetch a snippet of code from the server, select \uicontrol Tools > + \uicontrol {Code Pasting} > \uicontrol {Fetch Snippet} or press + \key {Alt+C,Alt+F}. Select the snippet to fetch from the list. + + To fetch the content stored at an URL, select \uicontrol Tools > + \uicontrol {Code Pasting} > \uicontrol {Fetch from URL}. + + For example, you might ask colleagues to review a change that you plan to + submit to a version control system. If you use the Git version control + system, you can create a \e{diff} view by selecting \uicontrol Tools > + \uicontrol Git > \uicontrol {Local Repository} > \uicontrol Diff. You can + then upload its contents to the server by selecting \uicontrol Tools > + \uicontrol {Code Pasting} > \uicontrol {Paste Snippet}. The reviewers can + retrieve the code snippet by selecting \uicontrol Tools > + \uicontrol {Code Pasting} > \uicontrol {Fetch Snippet}. If they have the + project currently opened in \QC, they can apply and test the change by + choosing \uicontrol Tools > \uicontrol Git > \uicontrol {Patch} > + \uicontrol {Apply from Editor}. +*/ diff --git a/doc/src/editors/creator-only/creator-fakevim.qdoc b/doc/src/editors/creator-only/creator-fakevim.qdoc new file mode 100644 index 00000000000..dfd7dcbb787 --- /dev/null +++ b/doc/src/editors/creator-only/creator-fakevim.qdoc @@ -0,0 +1,228 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** 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. +** +****************************************************************************/ + +/*! + \contentspage index.html + \previouspage creator-editor-options-text.html + \page creator-editor-fakevim.html + \nextpage creator-mime-types.html + + \title Using FakeVim Mode + + In the \uicontrol FakeVim mode, you can run the main editor in a manner + similar to the Vim editor. To run the editor in the \uicontrol FakeVim + mode, select \uicontrol Edit > \uicontrol Advanced > + \uicontrol {Use Vim-style Editing} or press \key {Alt+V,Alt+V}. + + \section1 Supported Modes and Commands + + In the \uicontrol FakeVim mode, most keystrokes in the main editor will be + intercepted and interpreted in a way that resembles Vim. Most of the + supported commands can be followed by a motion command or executed in visual + mode, or they work with registers or can be prefixed with a number of + repetitions. + + The following sections describe the commands emulated in the supported modes + and how they diverge from Vim in functionality: + + \list + \li Normal + \li Visual + \li Command line (:) + \li Insert and replace + \endlist + + For more information on using Vim, see \l{http://www.vim.org/docs.php} + {Documentation} on the Vim web site. + + \section2 Normal and Visual Modes + + \list + \li Basic movement, such as \c h/j/k/l, \c , \c , \c , + \c , \c gg, \c G, \c 0, \c ^, \c $ + \li Word movement, such as \c w, \c e, \c b + \li \e Inner/a movement, such as \c ciw, \c 3daw, ya{ + \li \c f and \c t movement + \li \c [ and \c ] movement + \li { and } paragraph movement + \li Delete/change/yank/paste with register + \li Undo and redo + \li \c and \c increase or decrease a number in decimal, + octal, or hexadecimal format (for example \c 128 on or before + \c "0x0ff" changes it to \c "0x17f") + \li \c . repeats the last change + \li \c /search, \c ?search, \c *, \c #, \c n, \c N - most of regular + expression syntax is used in Vim except that \c \< and \c \> are + the same as \c {\b} in QRegExp + \li \c @ and \c q (macro recording and execution) special keys are saved + as \c + \li Marks + \li \c gv goes to last visual selection; can differ if text is edited + around it + \li Indentation using \c =, \c <<, \c >>, with movement, count, and in + visual mode + \li \e {to upper/lower}, such as \c ~, \c gU, \c gu + \li \c i, \c a, \c o, \c I, \c A, and \c O enter insert mode + \li Scroll window, such as \c zt, \c zb, \c zz + \li Wrap line movement, such as \c gj, \c gk, \c g0, \c g^, \c g$ + \endlist + + \section2 Command Line Mode + + \list + \li \c :map, \c :unmap, \c :inoremap, and so on + \li \c :source provides very basic line-by-line sourcing of vimrc files + \li \c :substitute substitutes an expression in a range + \li \c :'<,'>!cmd filters through an external command (for example, + sorts the lines in a file with \c :%!sort) + \li \c :sor[t][!] + \li \c :.!cmd inserts the standard output of an external command + \li \c :read + \li \c :yank, \c :delete, \c :change + \li \c :move, \c :join + \li \c :20 goes to an address + \li \c :history + \li \c :registers, \c :display + \li \c :nohlsearch + \li \c :undo, \c :redo + \li \c :normal + \li \c :<, \c :> + \endlist + + \section2 Insert Mode + + \list + \li \c executes a single command and returns to insert mode + \li \c inserts a raw character + \li \c toggles replace mode + \endlist + + \section2 Options + + Use \c {:set ...} to set the following options: + + \list + \li \c autoindent + \li \c clipboard + \li \c backspace + \li \c expandtab + \li \c hlsearch + \li \c ignorecase + \li \c incsearch + \li \c indent + \li \c iskeyword + \li \c scrolloff + \li \c shiftwidth + \li \c showcmd + \li \c smartcase + \li \c smartindent + \li \c smarttab + \li \c startofline + \li \c tabstop + \li \c tildeop + \li \c wrapscan + \endlist + + \section2 Vimrc Example + + \code + " highlight matched + set hlsearch + " case insensitive search + set ignorecase + set smartcase + " search while typing + set incsearch + " wrap-around when searching + set wrapscan + " show pressed keys in lower right corner + set showcmd + " tab -> spaces + set expandtab + set tabstop=4 + set shiftwidth=4 + " keep a 5 line buffer for the cursor from top/bottom of window + set scrolloff=5 + " X11 clipboard + set clipboard=unnamed + " use ~ with movement + set tildeop + + " mappings + nnoremap ; : + inoremap jj + + " clear highlighted search term on space + noremap :nohls + + " reselect visual block after indent + vnoremap < >gv + + " MOVE LINE/BLOCK + nnoremap :m+== + nnoremap :m-2== + inoremap :m+==gi + inoremap :m-2==gi + vnoremap :m'>+gv=gv + vnoremap :m-2gv=gv + \endcode + + \section1 Mapping FakeVim Commands + + To map commands entered on the \uicontrol FakeVim command line to actions + of the \QC core, select \uicontrol Tools > \uicontrol Options > + \uicontrol FakeVim > \uicontrol {Ex Command Mapping}. + + To map \e {user commands} to keyboard shortcuts, select \uicontrol Tools > + \uicontrol Options > \uicontrol FakeVim > + \uicontrol {User Command Mapping}. The user command mapped to the shortcut + is executed by FakeVim as if you were typing it (as when replaying a macro). + + \section1 Specifying FakeVim Options + + To make changes to the Vim-style settings, select \uicontrol Tools > + \uicontrol Options > \uicontrol FakeVim > \uicontrol General. + + \image qtcreator-fakevim-options.png "FakeVim options" + + To preselect the indentation settings specified for the text editor, select + \uicontrol {Copy Text Editor Settings}. To preselect the Qt coding style, + select \uicontrol {Set Qt Style}. To preselect a simple indentation style, + select \uicontrol {Set Plain Style}. You can then change any of the + preselected settings. + + To use a Vim-style color scheme, select \uicontrol Tools > + \uicontrol Options > \uicontrol {Text Editor} > \uicontrol {Fonts & Color}. + In the \uicontrol {Color Scheme} list, select \uicontrol {Vim (dark)}. + + \section1 Quitting FakeVim Mode + + To quit the FakeVim mode, unselect \uicontrol Tools > \uicontrol Options > + \uicontrol FakeVim > \uicontrol {Use FakeVim} or press \key {Alt+V,Alt+V}. + + You can temporarily escape FakeVim mode to access the normal \QC keyboard + shortcuts like \key {Ctrl-R} for \uicontrol Run by pressing \key {,} first. +*/ diff --git a/doc/src/editors/creator-only/creator-text-editing-macros.qdoc b/doc/src/editors/creator-only/creator-text-editing-macros.qdoc new file mode 100644 index 00000000000..dba49c516c3 --- /dev/null +++ b/doc/src/editors/creator-only/creator-text-editing-macros.qdoc @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** 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. +** +****************************************************************************/ + +/*! + \contentspage index.html + \previouspage creator-editor-codepasting.html + \page creator-macros.html + \nextpage creator-diff-editor.html + + \title Using Text Editing Macros + + To record a text editing macro, select \uicontrol Tools > + \uicontrol {Text Editing Macros} > \uicontrol {Record Macro} + or press \key {Alt+(}. To stop recording, select \uicontrol Tools > + \uicontrol {Text Editing Macros} > \uicontrol {Stop Recording Macro} or + press \key {Alt+)}. + + \note The macro recorder does not support code completion. + + To play the last macro, select \uicontrol Tools > + \uicontrol {Text Editing Macros} > \uicontrol {Play Last Macro} or + press \key {Alt+R}. + + To save the last macro, select \uicontrol Tools > + \uicontrol {Text Editing Macros} > \uicontrol {Save Last Macro}. + + To assign a keyboard shortcut to a text editing macro, select + \uicontrol Tools > \uicontrol Options > \uicontrol Environment > + \uicontrol Keyboard. For more information, see + \l{Configuring Keyboard Shortcuts}. + + You can also use the \c rm locator filter to run a macro. For more + information, see \l{Searching with the Locator}. + + To view and remove saved macros, select \uicontrol Tools > + \uicontrol Options > \uicontrol {Text Editor} > \uicontrol Macros. +*/ diff --git a/doc/src/editors/creator-search.qdoc b/doc/src/editors/creator-search.qdoc new file mode 100644 index 00000000000..33ca79fc652 --- /dev/null +++ b/doc/src/editors/creator-search.qdoc @@ -0,0 +1,272 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** 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. +** +****************************************************************************/ + +/*! + \contentspage index.html + \previouspage creator-finding-overview.html + \page creator-editor-finding.html + \nextpage creator-editor-locator.html + + \title Finding and Replacing + + To search through the currently open file: + + \list 1 + + \li Press \key {Ctrl+F} or select \uicontrol Edit > + \uicontrol {Find/Replace} > \uicontrol {Find/Replace}. + + \li Enter the text you are looking for. + + If the text is found, all occurrences are highlighted as you type. + + \li To go to the next occurrence, click \inlineimage next.png + (\uicontrol {Find Next}), or press \key F3. To go to the previous + occurrence click \inlineimage prev.png + (\uicontrol {Find Previous}), or press \key {Shift+F3}. + + \endlist + + You can restrict the search in the \uicontrol Find field by selecting one + or several search criteria: + + \list + + \li To make your search case sensitive, select + \uicontrol {Case Sensitive}. + + \li To search only whole words, select \uicontrol {Whole Words Only}. + + \li To search using regular expressions, select + \uicontrol {Use Regular Expressions}. Regular expressions used in \QC + are modeled on Perl regular expressions. For more information on + using regular expressions, see the documentation for the + QRegularExpression Class. + + \endlist + + \note If you have selected text before selecting \uicontrol {Find/Replace}, the + search is conducted within the selection. + + To replace occurrences of the existing text, enter the new text in the + \uicontrol {Replace with} field. + + \list + + \li To replace the selected occurrence and move to the next one, + click \uicontrol {Find Next} or press \key {Ctrl+=}. + + \li To replace the selected occurrence and move to the previous one, + click \uicontrol {Find Previous}. + + \li To replace all occurrences in the file, click + \uicontrol {Replace All}. + + \endlist + + The \uicontrol {Preserve Case when Replacing} option can be selected to + preserve the case of the original text when replacing. This option is not + compatible with the \uicontrol {Use Regular Expressions} search option, and will + thus be disabled when regular expressions are used. When the option is used, + the case of the occurrence will be conserved, according to the following + rules: + + \list + + \li All upper-case occurrences are replaced with the upper-case new + text. + \li All lower-case occurrences are replaced with the lower-case new + text. + + \li Capitalized occurrences are replaced with the capitalized new text. + + \li Other occurrences are replaced with the new text as entered. + + \li If an occurrence and the new text have the same prefix or suffix, + then the case of the prefix and/or suffix are preserved, and the + other rules are applied on the rest of the occurrence only. + + \endlist + + The locations of search hits, breakpoints, and bookmarks in your document + are highlighted on the editor scroll bar. To turn highlighting off, select + \uicontrol Tools > \uicontrol Options > \uicontrol {Text Editor} > + \uicontrol Display > \uicontrol {Highlight search results on the scrollbar}. + + \section1 Advanced Search + + To search through projects, files on a file system or currently open files: + + \list 1 + + \li Press \key {Ctrl+Shift+F} or select \uicontrol Edit > + \uicontrol {Find/Replace} > \uicontrol {Advanced Find} > + \uicontrol {Open Advanced Find}. + + \li Select the scope of your search: + + \list + + \li \uicontrol {All Projects} searches from all currently open + projects. + + \image qtcreator-search-allprojects.png + + \li \uicontrol {Current Project} searches from the project you + are currently editing. + + \li \uicontrol {Files in File System} recursively searches from + the selected directory. + + \image qtcreator-search-filesystem.png + + In the \uicontrol {Search engine} field, select the search + engine to use: + + \list + \li Select \uicontrol Internal to use the \QC search + engine. + + \li Select \uicontrol {Git Grep} to use Git to only + search tracked files in the Git work tree. To + restrict the search to the HEAD, a tag, a local or + remote branch, or a commit hash, enter a reference. + Leave the field empty to search through the file + system. + + \li Select \uicontrol {Silver Searcher} to use the + experimental Silver Searcher plugin. For more + information, see \l{Enabling Silver Searcher}. + + \endlist + + \li \uicontrol {Current File} searches only from the current + file. + + \li \uicontrol {Open Documents} searches from all open files. + + \li \uicontrol {Clang Query Project} explores the Clang abstract + syntax tree (AST) using AST matcher expressions. For more + information, see \l{Exploring Clang AST}. + + \endlist + + \li In the \uicontrol {File pattern} field, specify file patterns to + restrict the search to files that match the pattern. For example, to + search for a string only in \c {.cpp} and \c {.h} files, enter + \c {*.cpp,*.h}. + + \li In the \uicontrol {Exclusion pattern} field, specify file patterns + to omit files from the search. + + \li Enter the text you are looking for and click \uicontrol Search. + + \image qtcreator-searchresults.png + + A list of files containing the searched text is displayed in the + \uicontrol {Search Results} pane. + + \list + + \li To see all occurrences in a file, double-click the file name + in the list. + + \li To go to an occurrence, double-click it. + + \li To repeat the search after you have made changes to the + listed files, for example, select + \uicontrol {Search Again}. + + \endlist + + \endlist + + The search results are stored in the search history from which you can + select earlier searches. + + To clear the search results, select the \inlineimage clean_pane_small.png + (\uicontrol Clear) button. + + To start a new search, select the \inlineimage qtcreator-new-search-icon.png + (\uicontrol {New Search}) button. + + \note You can use \uicontrol {Advanced Find} also to search for symbols. For + more information, see \l{Finding Symbols}. + + \section1 Enabling Silver Searcher + + You can use Silver Searcher as a search engine in \QC if you install + Silver Searcher on the development PC and enable the experimental plugin. + + To use Silver Searcher: + + \list 1 + + \li Download and install Silver Searcher from + \l {https://geoff.greer.fm/ag/}{The Silver Searcher} or + \l {https://github.com/ggreer/the_silver_searcher}{GitHub}. + + You might have to build Silver Searcher from sources for some + platforms. + + \li Select \uicontrol Help > \uicontrol {About Plugins} > + \uicontrol {Utilities} > \uicontrol {SilverSearcher} to enable the + plugin. + + \li Restart \QC to be able to use the plugin. + + \li When searching, select \uicontrol {Silver Searcher} in the + \uicontrol {Search engine} field. + + \endlist + + \section1 Exploring Clang AST + + You can use the experimental Clang Refactoring plugin to explore the Clang + AST using AST matcher expressions. For more information about constructing + matcher expressions, see + \l {http://clang.llvm.org/docs/LibASTMatchersReference.html} + {AST Matcher Reference}. + + To explore the AST: + + \list 1 + + \li Select \uicontrol Help > \uicontrol {About Plugins} > \uicontrol C++ + > \uicontrol {ClangRefactoring} to enable the plugin. + + \li Restart \QC to be able to use the plugin. + + \li When searching, select \uicontrol {Clang Query Project} in the + \uicontrol {Scope} field. + + \li Enter an AST matcher expression in the \uicontrol {Search for} + field. + + \endlist + + You can view the results of the query as links to code positions in the + \uicontrol {Search Results} output pane. +*/ diff --git a/doc/src/editors/creator-semantic-highlighting.qdoc b/doc/src/editors/creator-semantic-highlighting.qdoc new file mode 100644 index 00000000000..86e3dc0a588 --- /dev/null +++ b/doc/src/editors/creator-semantic-highlighting.qdoc @@ -0,0 +1,134 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** 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. +** +****************************************************************************/ + +/*! + \contentspage index.html + \previouspage creator-coding-navigating.html + \page creator-highlighting.html + \nextpage creator-checking-code-syntax.html + + \title Semantic Highlighting + + \QC understands the C++, QML, and JavaScript languages as code, not as plain + text. It reads the source code, analyzes it, and highlights it based on the + semantic checks that it does for the following code elements: + + \list + \li Types (such as classes, structs, and type definitions) + \li Local variables + \li Class fields + \li Virtual functions + \endlist + + To specify the color scheme to use for semantic highlighting, select + \uicontrol Tools > \uicontrol Options > \uicontrol {Text Editor} > + \uicontrol {Fonts & Color}. + + \QC supports syntax highlighting also for other types of files than C++, + QML, or JavaScript. + + \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. + For more information about the definition files, see + \l{http://kde-files.org/index.php?xcontentmode=680}{KDE-Files.org}. + + 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 + 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 + definition files as the primary location. + + When you open a file for editing and the editor cannot find the highlight + definition for it, an alert appears. To suppress the alerts, you can specify + patterns for ignoring files. + + To download highlight definition files: + + \list 1 + \li Select \uicontrol Tools > \uicontrol Options > + \uicontrol {Text Editor} > \uicontrol {Generic Highlighter}. + \image qtcreator-generic-highlighter.png "Generic Highlighter options" + \li In the \uicontrol Location field, specify the path to the primary + location for highlight definition files. + \li Click \uicontrol {Download Definitions} to open a list of highlight + definition files available for download. + \image qtcreator-manage-definitions.png "Download Definitions dialog" + \li Select highlight definition files in the list and click + \uicontrol {Download Selected Definitions}. + \li Select the \uicontrol {Use fallback location} check box to specify + the secondary location where the editor will look for highlight + definition files. + \li Click \uicontrol Autodetect to allow \QC to look for highlight + definition files on your system, or click \uicontrol Browse to + locate them in the file system yourself. + \li In the \uicontrol {Ignored file patterns} field, specify file + patterns to suppress alerts if the highlight definitions for the + specified files are not found. + \li Click \uicontrol OK to save your changes. + \endlist + + \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 + + To enable block highlighting, select \uicontrol Tools > + \uicontrol Options > \uicontrol {Text Editor} > \uicontrol Display > + \uicontrol {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. + + 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. + + 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}. + + 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}. +*/