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

    Use integrated code analysis tools to detect memory leaks, profile
    function execution, analyze CPU use, and eliminate unnecessary
    complexity of code. Other integrated tools provide code coverage and
    visualize trace events.

    \generatelist creator-how-to-analyze

    \section1 Build and Run

    Use integrated cross-platform systems for build automation to compile your
    source code for different target platforms or with different compilers,
    debuggers, or Qt versions. Deploy applications to the target platforms
    and run them there.

    \generatelist creator-how-to-build

    \section2 Build with CMake

    CMake controls the software compilation process by using simple configuration
    files, called \c CMakeLists.txt files.

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

    \section2 Build with qmake

    qmake automates the generation of Makefiles based on the information in a
    project file that has the extension \c .pro.

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

    \section2 Run applications

    Run applications on local and remote desktop systems, as well as on
    embedded and mobile devices that you connect to the computer.

    \generatelist creator-how-to-run

    \section1 Create Models and Diagrams

    Create Universal Modeling Language (UML) style models with structured and
    behavioral diagrams that offer different views to your system. Or, use a
    file wizard to create State Chart XML (SCXML) files with boilerplate code
    and edit them with an SCXML editor.

    \generatelist creator-how-to-models

    \section1 Debug

    Use debuggers to inspect the state of your application while it is running.

    \generatelist creator-how-to-debug

    \section1 Design UIs

    Design UIs with either \l{User Interfaces}{Qt Quick or Qt Widgets}.
    \QC integrates a visual editor, \QD, for designing widget-based UIs
    in the \uicontrol Design mode. For Qt Quick UIs, use a separate visual
    editor, \l{\QDS Manual}{\QDS}, or the \uicontrol Edit mode.

    \generatelist creator-how-to-design

    \section1 Develop for Devices

    Install the toolchain for building applications for the targeted
    embedded or mobile platform on the computer, and use \QOI to
    install Qt libraries that are built for the platform. Then add a
    kit with the toolchain and the Qt version for the device's architecture.
    When possible, \QOI creates suitable kits for you. Connect the devices
    to the computer to run, debug, and analyze applications on them.

    \section2 Android

    Install \l {Qt for Android} and Android tools, and connect Android devices to
    the computer.

    \generatelist creator-how-to-android

    \section2 Bare Metal

    Run and debug applications on small Linux devices that are not supported
    by the remote Linux device plugin by using GDB or a hardware debugger.

    \generatelist creator-how-to-bare-metal

    \section2 \B2Q

    Run, debug, and analyze applications on \l{\B2Q: Documentation}{\B2Q}
    devices.

    \generatelist creator-how-to-b2qt

    \section2 Docker

    Create \e {Docker devices} from \e {Docker images} and use them to build,
    run, and debug applications.

    \generatelist creator-how-to-docker

    \section2 iOS

    Install \l {Qt for iOS} and Xcode, and connect iOS devices to the computer.

    \generatelist creator-how-to-ios

    \section2 MCUs

    Install \l {Qt for MCUs}, and connect microcontrollers to the computer.

    \generatelist creator-how-to-mcu

    \section2 QNX Neutrino

    Install \l {Qt for QNX}, and connect QNX Neutrino devices to the computer.

    \generatelist creator-how-to-qnx

    \section2 Remote Linux

    Add kits for toolchains for building applications for generic Linux
    devices, and connect the devices to the computer.

    \generatelist creator-how-to-remote-linux

    \section2 SDKs

    Manage SDKs for application development for different platforms.

    \generatelist creator-how-to-sdks

    \section2 VxWorks

    Build \l {Qt for VxWorks}, and create VxWorks build and run kits.

    \generatelist creator-how-to-vxworks

    \section2 WebAssembly

    Install \l{Qt for WebAssembly} to build applications for the web and run them
    in a web browser.

    \generatelist creator-how-to-webassembly

    \section1 Edit Code

    The code editor offers useful features for editing C++ and QML code, such
    as semantic highlighting, checking code syntax, code completion, and quick
    fixes. Some of these features are also for other programming languages, such
    as Python, for which a \e {language server} is available that provides
    information about the code to IDEs.

    \generatelist creator-how-to-edit

    \section2 Configure Editors

    Configure the code and text editor to suit your specific needs by
    changing the fonts, colors, highlighting, and indentation.

    \generatelist creator-how-to-configure-editors

    \section2 Manage Language Servers

    Configure language servers that \QC adds by default or add more of them.

    \generatelist creator-how-to-lsp

    \section2 Search

    Use the incremental and advanced search to search in currently open projects
    or files on the file system or use the locator to browse through projects,
    files, classes, functions, documentation, and file systems.

    \generatelist creator-how-to-search

    \section1 Manage Kits

    \QC groups build and run specific settings as kits to make cross-platform
    development easier. Each kit consists of a set of values that define one
    environment, such as a device, toolchain, Qt version, and debugger command
    to use.

    \generatelist creator-how-to-manage-kits

    \section1 Manage Projects

    Create projects for developing applications and libraries. Then configure
    the projects for building and running the applications on target platforms.

    \generatelist creator-how-to-projects

    \section2 Create Projects

    Use preset wizards to create projects or add custom wizards. You can also
    import projects from version control systems.

    \generatelist creator-how-to-projects-create

    \section2 Add Files

    Add files to projects.

    \generatelist creator-how-to-projects-files

    \section2 Configure Projects

    Change the default configurations that installation programs and project
    wizards create.

    \generatelist creator-how-to-projects-configure

    \section1 Read Documentation

    \QC integrates the reference documentation for the Qt versions that you
    install. You can add documentation from other sources.

    \generatelist creator-how-to-get-help

    \section1 Test

    Create and run \e {code based tests} and \e {build system based tests}.
    Code based testing offers special handling for particular testing
    frameworks that strongly ties to the underlying code models or
    specialized parsers. Build system based testing is independent from any
    testing frameworks. It retrieves information directly from the underlying
    build system and uses it or even the build system as such to execute the
    respective tests.

    \generatelist creator-how-to-test

    \section1 Use Git

    \l{Git} is a fast decentralized version control system
    that is available for Windows, Linux, and \macos. You can use the
    \l {Gerrit Code Review} tool for projects that use Git.

    \generatelist creator-how-to-git

    \section2 Current file

    \generatelist creator-how-to-git-current-file

    \section2 Current project

    \generatelist creator-how-to-git-current-project

    \section2 Local repositories

    \generatelist creator-how-to-git-local-repository

    \section2 Commits

    \generatelist creator-how-to-git-commits

    \section2 Remote repositories

    \generatelist creator-how-to-git-remote-repository

    \section1 Use \QC

    Use basic \QC features and preinstalled plugins. Install more plugins and
    configure external tools for use.

    \generatelist creator-how-to-use

    \section1 Use the UI

    Navigate the UI or change its appearance and behavior.

    \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, select
    \key Esc.

    If you already are in the \uicontrol Edit mode:

    \list

        \li The first time you select \key Esc, the focus moves to the editor

        \li The second time you select \key Esc, secondary windows are closed

    \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

    The following are examples of the commands on supported platforms when you
    install \QC with \l{Get and Install Qt}{\QOI} to the default location. Change
    the paths as necessary.

    On Windows:

    \list

        \li \c {C:\Qt\Tools\QtCreator\bin\qtcreator -help}

        \li \c {C:\Qt\Tools\QtCreator\bin\qtcreator C:\TextFinder\textfinder.cpp:100:2}

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

    \endlist

    On Linux:

    \list

        \li \c {~/Qt/Tools/QtCreator/bin/qtcreator -help}

        \li \c {~/Qt/Tools/QtCreator/bin/qtcreator /src/TextFinder/textfinder.cpp:100:2}

        \li \c {~/Qt/Tools/QtCreator/bin/qtcreator /src/TextFinder/textfinder.cpp+100+2}

    \endlist

    On \macos:

    \list

        \li \c {~/Qt/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 in the locator}

    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 tab in Environment 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

    To do basic calculations in the locator:

    \list 1
        \li Select \key {Ctrl+K} (\key {Cmd+K} on \macos) to activate the locator.
        \li Enter \c =, followed by a space.
        \image {qtcreator-locator.webp} {List of locator filters}
        \li Perform calculations.
    \endlist

    Navigate through the entries and select \key {Enter} to copy the results to
    the clipboard

    \section1 Built-in functions

    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

    \sa {Navigate with locator}, {Locator}
*/

/*!
    \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 Select \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 Select \key {Ctrl+Shift+U}.
        \li Go to \uicontrol Tools > \uicontrol {QML/JS} >
            \uicontrol {Find References to Symbol Under Cursor}.
    \endlist

    \section1 Inspect QML and JavaScript

    To inspect QML and JavaScript properties, methods, and enums, place the
    cursor over them and go to \uicontrol Tools > \uicontrol {QML/JS} >
    \uicontrol {Inspect API for Element Under Cursor}.

    \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 Select \key F2.
        \li Go to \uicontrol {Follow Symbol Under Cursor} in the context menu.
    \endlist

    \sa {Edit Code}{How To: Edit Code}, {Clangd}, {Edit Mode},
    {Navigate with 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 tab in C++ 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

    In addition, placeholders in the form %{..} are replaced by the
    value of the corresponding \QC variable.

    \sa {Use \QC variables}
*/

/*!
    \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, select \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 tab in Text Editor preferences}

    Also, \QC automatically inserts the closing character of a raw string literal
    prefix.

    \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 current code block

    To select the current block of C++ code in the code editor, select
    \key Ctrl+U.

    Select \key Ctrl+U a second time to extend the selection to the parent block.

    To undo the last selection, select \key {Ctrl+Alt+Shift+U}.

    \section1 Turn on smart block selection

    To turn on smart block selection, go to \preferences
    > \uicontrol {Text Editor} > \uicontrol Behavior and select
    \uicontrol {Enable smart selection changing}.

    \image {qtcreator-preferences-texteditor-behavior.webp} {Behavior tab in Text Editor preferences}

    \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 Select \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 tab in Environment 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 Select \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}
*/
