path: root/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc

// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

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

/*!
    \previouspage creator-faq.html
    \page creator-how-tos.html
    \nextpage creator-reference.html

    \title How To

    The following topics describe how to use \QC to perform a particular task.

    \section1 Analyze

    \QC integrates code analysis tools for detecting memory leaks, profiling
    function execution, analyzing CPU use, and eliminating unnecessary
    complexity of code. Other integrated tools provide code coverage and
    visualize trace events.

    \generatelist creator-how-to-analyze

    \section1 Build and Run

    \generatelist creator-how-to-build

    \section2 Build with CMake

    \generatelist creator-how-to-build-with-cmake

    \section2 Build with qmake

    \generatelist creator-how-to-build-with-qmake

    \section2 Run applications

    \generatelist creator-how-to-run

    \section1 Create Models and Diagrams

    \generatelist creator-how-to-models

    \section1 Debug

    \generatelist creator-how-to-debug

    \section1 Design UIs

    \generatelist creator-how-to-design

    \section1 Edit Code

    \generatelist creator-how-to-edit

    \section2 Configure Editors

    \generatelist creator-how-to-configure-editors

    \section2 Manage Language Servers

    \generatelist creator-how-to-lsp

    \section2 Search

    \generatelist creator-how-to-search

    \section1 Manage Kits

    \generatelist creator-how-to-manage-kits

    \section1 Manage Projects

    \generatelist creator-how-to-projects

    \section2 Create Projects

    \generatelist creator-how-to-projects-create

    \section2 Add Files

    \generatelist creator-how-to-projects-files

    \section2 Configure Projects

    \generatelist creator-how-to-projects-configure

    \section1 Read Documentation

    \generatelist creator-how-to-get-help

    \section1 Use \QC

    \generatelist creator-how-to-use

    \section1 Use the UI

    \generatelist creator-how-to-ui
*/

/*!
    \page creator-how-to-switch-to-edit-mode.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-edit

    \title Switch to Edit mode

    To move to the \uicontrol Edit mode and currently active file, press
    \key Esc.

    If you already are in the \uicontrol Edit mode:

    \list

        \li The first press moves focus to the editor

        \li The second press closes secondary windows

    \endlist

    \sa {Edit Code}{How To: Edit Code}, {Edit Mode}
*/

/*!
    \page creator-how-to-run-from-cli.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-use

    \title Run \QC from the command line

    You can start \QC and specify some options from the command line. For
    example, you can open a file to any line and column.

    To use command-line options, enter the following command in the
    directory that contains the \QC executable or specify the path to
    \QC as a part of the command:

    \badcode
    qtcreator [option] [filename[:line_number[:column_number]]]
    \endcode

    \note You can use either a colon (:) or a plus sign (+) as a separator
    between the filename and line number and the line number and the column
    number. You can also use a space between the separator and the line number.

    \section1 Examples of CLI commands

    On Windows:

    \list

        \li \c {C:\qtcreator\bin>qtcreator -help}

        \li \c {C:\qtcreator\bin>qtcreator C:\TextFinder\textfinder.cpp:100:2}

        \li \c {C:\qtcreator\bin>qtcreator C:\TextFinder\textfinder.cpp +100+2}

    \endlist

    On \macos:

    \list

        \li \c {Qt\ Creator.app/Contents/MacOS/Qt\ Creator -help}

    \endlist

    \section1 Open a project from a directory

    To open a project that is located in a particular directory, you can
    pass on the directory name as a command-line argument. \QC looks for
    a \l{Manage sessions}{session} that matches the directory name and
    loads it. Or it looks for a project file in the directory and opens it.

    For example, on Windows:

    \c {C:\qtcreator\bin>qtcreator.exe C:\Examples\alarms}

    \sa {Command-Line Options}
*/

/*!
    \page creator-how-to-locate-files-using-keyboard.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-edit

    \title Locate files using the keyboard

    Use the \uicontrol Locator to browse
    through projects, files, classes, functions, documentation, and file systems.

    \image qtcreator-locator-open.webp "List of found files"

    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 locator filters, select \preferences >
    \uicontrol Environment > \uicontrol Locator > \uicontrol Add.

    \image qtcreator-locator-customize.webp "Locator preferences"

    \sa {Creating Locator Filters}, {Edit Code}{How To: Edit Code}, {Edit Mode}
*/

/*!
    \page creator-how-to-perform-calculations.html
    \previouspage creator-how-to-move-between-open-files.html

    \ingroup creator-how-to-edit

    \title Perform calculations

    Open the \uicontrol Locator with \key {Ctrl+K} and type =, followed by a space.
    You can now do basic calculations, with options to copy the results to the clipboard
    by navigating through the entries and pressing \key {Enter}.

    \image qtcreator-locator.webp "List of locator filters"

    \sa {Executing JavaScript}
*/

/*!
    \page creator-how-to-navigate-qml-code.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-edit

    \title Move in QML code

    Find QML methods and types, and move to the C++ implementation of a QML type.

    \section1 Locate QML methods

    To locate a QML method:

    \list 1
        \li Press \key {Ctrl+K} to activate the locator.
        \li Type m, followed by a space.
            \image qtcreator-locator-m-filter.webp {The m filter in the locator}
        \li Double-click a QML method in the list to move to it in the editor.
    \endlist

    \section1 Find QML types

    To find instances of a QML type in a project, place the cursor on
    the type and and do one of the following:

    \list
        \li Press \key {Ctrl+Shift+U}.
        \li Go to \uicontrol Tools > \uicontrol {QML/JS} >
            \uicontrol {Find References to Symbol Under Cursor}.
    \endlist

    \section1 Move between QML and C++

    To move to the C++ implementation of a QML type in the code editor, place the
    cursor on the type and do one of the following:

    \list
        \li Press \key F2.
        \li Go to \uicontrol {Follow Symbol Under Cursor} in the context menu.
    \endlist

    \sa {Edit Code}{How To: Edit Code}, {Edit Mode}, {Searching with the Locator}
*/

/*!
    \page creator-how-to-add-license-header-templates.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-projects-files

    \title Add a license header template for C++ code

    Specify a file that has a license header for C++ in \preferences >
    \uicontrol C++ > \uicontrol {File Naming} > \uicontrol {License template}.

    \image qtcreator-options-cpp-files.png "File Naming preferences"

    The license file may have special placeholders enclosed
    in \c{%%} that are replaced when generating a new file:

    \list 1

        \li \c %YEAR%: Year
        \li \c %MONTH%: Month
        \li \c %DAY%: Day of the month
        \li \c %DATE%: Date
        \li \c %USER%: Username
        \li \c %FILENAME%: File name
        \li \c %CLASS%: Class name (if applicable)
        \li \c %$VARIABLE%: Contents of environment variable \c{VARIABLE}.

    \endlist
*/

/*!
    \page creator-how-to-paste-text-from-clipboard-history.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-edit

    \title Paste text from clipboard history

    \QC stores copied text in clipboard history. To retrieve clips from the
    history, press \key {Ctrl+Shift+V} until the clip appears.
    The number of clips in the history is fixed to 10.

    \sa {Edit Code}{How To: Edit Code}, {Edit Mode}
*/

/*!
    \page creator-enclose-code-in-characters.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-edit

    \title Enclose code in brackets or quotes

    Select code and enter one of the following opening characters to add
    the matching closing character at the end of the selection:

    \list
        \li (
        \li {
        \li [
        \li <
        \li "
        \li '
    \endlist

    To specify whether to automatically insert matching characters,
    select \preferences > \uicontrol {Text Editor} > \uicontrol Completion.

    \image qtcreator-preferences-texteditor-completion.webp "Completion preferences"

    \sa {Completion}, {Edit Code}{How To: Edit Code}, {Edit Mode}
*/

/*!
    \page creator-how-to-select-enclosing-block.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-edit

    \title Select the enclosing block in C++

    Press \key {Ctrl+U}.

    \sa {Edit Code}{How To: Edit Code}, {Edit Mode}
*/

/*!
    \page creator-how-to-write-notes.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-edit

    \title Write down notes

    To write down notes without having to worry about deleting the file
    later, create a new empty text file and save it to a temporary directory
    on your machine.

    \image qtcreator-scratch-buffer.webp {Scratch file open in the text editor}

    To create a scratch file and open it in the text editor:

    \list
        \li Select \uicontrol File > \uicontrol {New File} > \uicontrol General >
            \uicontrol {Scratch Buffer}.
        \li Press \key {Ctrl+N}.
    \endlist

    Use the up and down arrow keys and the tab key to navigate in the editor.

    The operating system will eventually remove the file automatically. To keep
    the file, save it as a new file somewhere else. If you accidentally close the
    file, find it in \uicontrol File > \uicontrol {Recent Files}.
*/

/*!
    \page creator-how-to-set-recent-files.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-ui

    \title Set the number of recent files shown

    To set the number of files to list in \uicontrol File >
    \uicontrol {Recent Files}:

    \list 1
        \li Select \preferences > \uicontrol Environment > \uicontrol System.
            \image qtcreator-preferences-environment-system.webp {System preferences}
        \li In \uicontrol {Maximum number of entries in "Recent Files"}, set
            the number of files to show.
    \endlist
*/

/*!
    \page creator-how-to-search-and-replace-using-regexp.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-search

    \title Search and replace using a regular expression

    Search and replace across files using regular expressions in the
    \uicontrol {Search Results} view.

    Regular expressions used in \QC are modeled on Perl regular expressions.
    For more information about using regular expressions, see
    \l QRegularExpression.

    For example, to replace equality checks (\c {foo == bar}) with a function
    (\c {foo.equals(bar)}):

    \list 1
    \li Commit your changes to version control, as you cannot undo the
        replace action.
    \li Press \key {Ctrl+Shift+F} or go to \uicontrol Edit >
        \uicontrol {Find/Replace} > \uicontrol {Advanced Find} >
        \uicontrol {Open Advanced Find} to open \uicontrol {Search Results}.
        \image qtcreator-search-reg-exp.webp {Regular expression in Search Results view}
    \li In \uicontrol Scope, select whatever is appropriate for your search.
    \li Select \uicontrol {Use regular expressions}.
    \li Enter the following text in \uicontrol {Search for}:
        \badcode
        if \((.*) == (.*)\)
        \endcode
    \li Select \uicontrol {Search & Replace} to see a list of search results.
        \image qtcreator-search-results-reg-exp.webp {Search results for the regular expression}
    \li In \uicontrol {Replace with}, enter the following text:
        \badcode
        if (\1.strictlyEquals(\2))
        \endcode
    \li Select \uicontrol Replace to replace all instances of the text.
    \endlist

    \sa {Edit Code}{How To: Edit Code}, {Search}{How To: Search}, {Edit Mode}
*/