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

/*!
    \page creator-preferences-cpp-code-style.html
    \previouspage creator-reference.html

    \ingroup creator-reference-editors

    \title C++ code style

    \brief Set global code style for C++ files.

    \QC uses the Clang \l{LibFormat: Documentation}{LibFormat}
    library to automatically format and indent C++ code. It enforces a coding
    style for a project or the whole organization.

    To specify global indentation settings for the C++ editor, go to
    \preferences > \uicontrol {C++} > \uicontrol {Code Style}.

    The following table describes the available preferences.

    \table
        \header
            \li Preference
            \li Description
        \row
            \li \uicontrol {Formatting mode}
            \li Select:
                \list
                    \li \uicontrol {Indenting Only} to only indent code.
                    \li \uicontrol {Full Formatting} to use the \key {Ctrl+I}
                        keyboard shortcut to format code instead of indenting.
                    \li \uicontrol {Use Built-In Indenter} to turn off
                        \l{ClangFormat: Documentation}{ClangFormat}.
                \endlist
        \row
            \li \uicontrol {Ignore files greater than}
            \li Make parsing faster by ignoring big files. Specify the maximum
                size of files to parse.
        \row
            \li \uicontrol {Format while typing}
            \li Apply the formatting while you type.
        \row
            \li \uicontrol {Format edited code on file save}
            \li Apply the formatting to the edited code when you save the file.
                To temporarily disable this setting while saving a file, go to
                \uicontrol File and select \uicontrol {Save Without Formatting}.
        \row
            \li \uicontrol {Use custom settings}
            \li Change the ClangFormat style globally for all projects.
        \row
            \li \uicontrol {Custom settings}
            \li Select the settings to change, then select \uicontrol Copy.
                Give a name to the settings, and select \uicontrol OK.
        \row
            \li \uicontrol ClangFormat
            \li Edit the \l {ClangFormat Style Options}. The live preview shows
                how the preferences change the indentation. If you enter invalid
                values, you see warning messages.
    \endtable

    \section1 Using built-in indenter

    \image {qtcreator-code-style-built-in-indenter.webp} {Code Style preferences for built-in indenter}

    If you select \uicontrol {Use Built-In Indenter} in
    \uicontrol {Formatting mode}, you can specify how to:

    \list
        \li Interpret the \key Tab and \key Backspace key presses.
        \li Add macros that the indenter interprets as complete statements that
            don't require a semicolon at the end.
        \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.
    \endlist

    \section2 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 tab in the Code Style tab in C++ preferences}

    \section2 Specifying settings for braces

    You can indent class, namespace, enum and function declarations and code
    blocks.

    \image {qtcreator-code-style-braces.png} {Braces tab in the Code Style tab in C++ preferences}

    \section2 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" tab in the Code Style tab in C++ preferences}

    \section2 Specifying alignment

    To align continuation lines to tokens after assignments, such as \c = or
    \c +=, select \uicontrol {Align after assignments}. 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 tab in the Code Style tab in C++ preferences}

    \section2 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 checkboxes 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 tab in the Code Style tab in C++ preferences}

    \section1 Creating ClangFormat files from command line

    You can create \c {.clang-format} files that have the configuration
    options of a certain predefined style from the command line. For example,
    to create a format file for the LLVM style, enter the following command:

    \code [shell]
    clang-format -style=llvm -dump-config > .clang-format
    \endcode

    \sa {Indent text or code}, {Specify code style}, {Behavior},
    {Specify Qt Quick code style}, {Nim}
*/
