// Copyright (C) 2024 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.
// **********************************************************************

/*!
    \page creator-beautifier.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-configure-editors

    \title Beautify source code

    Beautifying code means applying indentation and style to source code files.
    Use the experimental Beautifier plugin to format your source code with the
    following external tools:

    \list

        \li \l{http://astyle.sourceforge.net}{Artistic Style}

        \li \l{ClangFormat: Documentation}{ClangFormat}

        \li \l{http://uncrustify.sourceforge.net}{Uncrustify}

    \endlist

    The Beautifier plugin parses the source code into component structures, such
    as assignment statements, if blocks, loops, and so on, and formats them
    according to the Beautifier preferences. You can use a predefined style or
    define your own style.

    To automatically format files when you save them:

    \list 1
        \li Download and install the tool to use for formatting source code:
            \list
                \li \l{http://sourceforge.net/projects/astyle/files/astyle}
                    {Artistic Style}
                \li \l{ClangFormat: Download}{ClangFormat}
                \li \l{http://sourceforge.net/projects/uncrustify/files/uncrustify}
                    {Uncrustify}
            \endlist
            \note You might have to build the tools from sources for some
            platforms.
        \li Enable the Beautifier plugin.
            \note Since \QC 10.0.0, the ClangFormat plugin is enabled by default.
            Go to \preferences > \uicontrol {C++} > \uicontrol {Formatting mode},
            and select \uicontrol Disable to turn off ClangFormat if you enable
            Beautifier because combining them can lead to unexpected results.
        \li Go to \preferences > \uicontrol Beautifier > \uicontrol General to
            select the tool to use.
            \image {qtcreator-preferences-beautifier-general.webp} {General tab in Beautifier preferences}
        \li Select \uicontrol {Automatic formatting on file save} to
            automatically beautify files when you save them using the tool you
            select in the \uicontrol Tool field.

            To temporarily disable this setting while saving a file, go to
            \uicontrol File and select \uicontrol {Save Without Formatting}.
        \li Go to \uicontrol {Artistic Style}, \uicontrol {ClangFormat}, or
            \uicontrol Uncrustify to set the path to the tool executable and
            to select the configuration file that defines the style to use.
            \image {beautifier_options.png} {Uncrustify tab in Beautifier preferences}
            \caption Beautifier Uncrustify preferences
    \endlist

    \section1 Format the currently open file

    Go to \uicontrol Tools > \uicontrol Beautifier > \uicontrol {Artistic Style},
    \uicontrol ClangFormat, or \uicontrol Uncrustify to select actions for
    formatting text in the current file.

    You can \l{Keyboard shortcuts}{create keyboard shortcuts} for the
    actions.

    Go to \uicontrol {Format Current File} to format the currently open file.

    \section2 Format at cursor with ClangFormat

    Go to \uicontrol Tools > \uicontrol Beautifier > \uicontrol ClangFormat >
    \uicontrol {Format at Cursor} when no text is selected to format the
    syntactic entity under the cursor.

    Go to \uicontrol {Format Line(s)} to format the selected lines.

    Go to \uicontrol {Disable Formatting for Selected Text} to wrap selected
    lines within \c {// clang-format off} and \c {// clang-format on}.

    \section2 Format selected text with Uncrustify

    Go to \uicontrol Tools > \uicontrol Beautifier > \uicontrol Uncrustify >
    \uicontrol {Format Selected Text} when no text is selected to format
    the whole file by default.

    To turn off this behavior, clear
    \uicontrol {Format entire file if no text was selected} in
    \preferences > \uicontrol Beautifier > \uicontrol Uncrustify.

    \sa {Enable and disable plugins}, {Beautifier}
*/

/*!
    \page creator-preferences-beautifier.html
    \previouspage creator-reference.html

    \ingroup creator-reference-editors

    \title Beautifier

    \summary {Format source code with Artistic Style, ClangFormat, or Uncrustify.}

    Automatically apply indentation and style to source code files when you save
    them. Use a predefined style or define your own style.

    \section1 Specifying Beautifier preferences

    To specify preferences for beautifying files, go to \preferences >
    \uicontrol Beautifier > \uicontrol General.

    \image {qtcreator-preferences-beautifier-general.webp} {General tab in Beautifier preferences}

    The following table describes the preferences you can set in the
    \uicontrol General tab.

    \table
    \header
        \li Preference
        \li Description
    \row
        \li \uicontrol {Automatic formatting on file save}
        \li Automatically beautify files when you save them using the tool you
            select in the \uicontrol Tool field.

            To temporarily disable this setting while saving a file, go to
            \uicontrol File and select \uicontrol {Save Without Formatting}.
    \row
        \li \uicontrol Tool
        \li The tool to use for formatting source code files. You can select
            only one tool at a time.
    \row
        \li \uicontrol {Restrict to MIME types}
        \li The MIME types of the files to beautify, separated by semicolons.
            Leave the field empty to apply the tool on all files.

            This setting is applied only when automatically beautifying files on
            save. To restrict the MIME types when selecting the menu item to
            format the currently open file, specify this option in the
            tool-specific tab.
    \row
        \li \uicontrol {Restrict to files contained in the current project}
        \li Only beautify files that belong to the current project.
    \endtable

    \section1 Beautifier tool preferences

    To set preferences for the tool you want to use, go to the \uicontrol {Artistic Style},
    \uicontrol {ClangFormat}, or \uicontrol Uncrustify tab.

    \image {beautifier_options.png} {Uncrustify tab in Beautifier preferences}

    Then, in \uicontrol Configuration:

    \list 1
        \li Specify the path to the tool executable in
            \uicontrol {Artistic Style command}, \uicontrol {ClangFormat command},
            or \uicontrol {Uncrustify command}.
        \li In \uicontrol {Restrict to MIME types}, define the MIME
            types of the files to beautify. This setting is applied when you
            select the menu item to format the currently open file.
        \li In \uicontrol Options, select the configuration file that
            defines the style to use in the source files. If you select several
            options, they are applied from top down. The available options
            depend on the tool.
    \endlist

    To set the following options, you must have one of the tools installed.

    \table
    \header
        \li Option
        \li Value
    \row
        \li \uicontrol {Use file *.astylerc defined in project files}

            \uicontrol {Use file uncrustify.cfg defined in project files}
        \li Use the configuration file \l{Specify project contents}
            {defined in the project file} as the configuration file
            for the selected tool.
    \row
        \li \uicontrol {Use specific config file}

            \uicontrol {Use file specific uncrustify.cfg}
        \li The file to use as the configuration file for the selected tool.
    \row
        \li \uicontrol {Use file uncrustify.cfg in <$HOME>}

            \uicontrol {Use file .astylerc or acstylerc in <$HOME>}
        \li Use the specified file in the user's home directory as the
            configuration file for the selected tool.
    \row
        \li \uicontrol {Use customized style}
        \li Set your own code style.
    \row
        \li \uicontrol {Format entire file if no text was selected}
        \li Format the whole file when no text is selected in the editor and
            you select \uicontrol {Format Selected Text}.
    \endtable

    \section2 Using a predefined ClangFormat style

    To use a predefined ClangFormat style, go to \uicontrol {ClangFormat} and
    select a style in \uicontrol {Use predefined style}.

    \image {qtcreator-beautifier-options-clangformat.png} {ClangFormat tab in Beautifier preferences}

    Select \uicontrol File to load the style configuration from the
    \c .clang-format or \c _clang-format file located in the same
    directory as the source file or in one of its parent directories.

    In \uicontrol {Fallback style}, select a fallback style to use if the style
    configuration file is not available. Select \uicontrol Default to use the
    default style. Select \uicontrol None to skip formatting.

    \section2 Defining a style

    To define your own style, select \uicontrol {Use customized style}, and then
    select \uicontrol Add.

    Set the code style in the \uicontrol {Add Configuration} dialog.
    It offers syntax highlighting, auto-completion, and context-sensitive
    help.

    \image {beautifier_editor.png} {Add Configuration dialog}

    \sa {Beautify source code}, {Enable and disable plugins}
*/
