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

/*!
    \page creator-preferences-text-editor-behavior.html
    \previouspage creator-reference.html

    \ingroup creator-reference-editors

    \title Behavior

    \brief Set preferences for indentation, typing, saving, file encoding,
    and mouse and keyboard behavior in the text editor.

    To set indentation preferences for text files that do not have C++ or
    QML code (such as Python code files), select \preferences >
    \uicontrol {Text Editor} > \uicontrol Behavior.

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

    You can set how to interpret the \key Tab and \key Backspace key
    presses and how to align continuation lines.

    \section1 Setting tab preferences

    You can set tab preferences 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 Setting tabs and indentation

    You can set tab policy and tab size in the
    \uicontrol {Tabs and Indentation} group. In the \uicontrol {Default 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 set 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}.

    \section1 Setting typing preferences

    When you type text or code, it is indented automatically according to the
    selected text editor or code style preferences. To set typing preferences,
    select \preferences > \uicontrol {Text Editor} >
    \uicontrol Behavior > \uicontrol Typing.

    The following table describes the typing preferences you can set.

    \table
    \header
        \li Preference
        \li Description
    \row
        \li \uicontrol {Enable automatic indentation}
        \li Automatically indent new lines according to the text editor or code
            style preferences.
    \row
        \li \uicontrol {Backspace indentation}
        \li set how the indentation is decreased when you select
            \uicontrol Backspace:
            \list
                \li To go back one space at a time, select \uicontrol None.
                \li To decrease indentation in leading white space by one
                    level, select \uicontrol {Follows Previous Indents}.
                \li To move back one tab length if the character to the left
                    of the cursor is a space, select \uicontrol Unindents.
            \endlist
    \row
        \li \uicontrol {Tab key performs auto-indent}
        \li set when the \key Tab key automatically indents text:
            \list
                \li To always indent text, select \uicontrol Always.
                \li To only indent text when the cursor is located within leading
                    white space, select \uicontrol {In Leading White Space}.
                \li To never indent text, select \uicontrol Never.
            \endlist
    \row
        \li \uicontrol {Prefer single line comments}
        \li When your highlight definition file has definitions for both multi
            and single line comments, select this option to apply the single
            line comment definition when commenting out a selection.
    \row
        \li \uicontrol {Preferred comment position}
        \li Set the position of single line comments when you comment out a
            selection:
            \list
                \li To let the highlight definition for the file determine the
                    position of single line comments, select \uicontrol Automatic.
                    If no highlight definition is available, the comments are
                    placed after leading whitespace.
                \li To always place single line comments after leading whitespace,
                    select \uicontrol {After Whitespace}.
                \li To place single line comments at the end of the line, select
                    \uicontrol {At Line Start}.
            \endlist
    \endtable

    \section1 Cleaning up whitespace upon saving

    To automatically clean up whitespace each time you save a file, select
    \preferences > \uicontrol {Text Editor} > \uicontrol Behavior, and go to
    \uicontrol {Cleanups Upon Saving}.

    The following table describes the cleanup preferences you can set.

    \table
    \header
        \li Preference
        \li Description
    \row
        \li \uicontrol {Clean whitespace}
        \li Remove trailing whitespace upon saving.
    \row
        \li \uicontrol {In entire document}
        \li Clean whitespace in the entire document instead of only in the
            parts that you changed. Available when \uicontrol {Clean whitespace}
            is selected.
    \row
        \li \uicontrol {Clean indentation}
        \li Correct leading whitespace according to the tab settings.
            Available when \uicontrol {Clean whitespace} is selected.
    \row
        \li \uicontrol {Skip clean whitespace for file types}
        \li List wildcard-aware file patterns, separated by commas or
            semicolons, for which trailing whitespace is not trimmed. By
            default, \c {*.md, *.MD, Makefile} are skipped. Available when
            \uicontrol {Clean whitespace} is selected.
    \row
        \li \uicontrol {Ensure newline at end of file}
        \li Always write a newline character at the end of the file.
    \endtable

    \section1 Setting file encoding preferences

    To set the default text encoding, byte order mark (BOM), and line ending
    style used when creating or saving files, select \preferences >
    \uicontrol {Text Editor} > \uicontrol Behavior, and go to
    \uicontrol {File Encodings}.

    The following table describes the file encoding preferences you can set.

    \table
    \header
        \li Preference
        \li Description
    \row
        \li \uicontrol {Default encoding}
        \li Select the text encoding to use for new files and for files whose
            encoding cannot be detected automatically.
    \row
        \li \uicontrol {UTF-8 BOM}
        \li Set how to handle UTF-8 byte order marks:
            \list
                \li \uicontrol {Add If Encoding Is UTF-8} always adds a BOM
                    when saving a file in UTF-8 encoding. This does not work
                    if the encoding is \uicontrol System, because the text
                    editor does not know what encoding that actually is.
                \li \uicontrol {Keep If Already Present} saves the file with a
                    BOM if it already had one when it was loaded.
                \li \uicontrol {Always Delete} never writes a UTF-8 BOM,
                    possibly deleting a pre-existing one.
            \endlist
            UTF-8 BOMs are uncommon and are treated incorrectly by some
            editors, so it usually makes little sense to add one. This
            setting does not affect the use of UTF-16 and UTF-32 BOMs.
    \row
        \li \uicontrol {Default line endings}
        \li Select \uicontrol {Unix (LF)} or \uicontrol {Windows (CRLF)} as
            the default line ending style for new files.
    \endtable

    \section1 Setting mouse and keyboard preferences

    To set preferences for using the mouse and keyboard in the text editor,
    select \preferences > \uicontrol {Text Editor} > \uicontrol Behavior, and
    go to \uicontrol {Mouse and Keyboard}.

    The following table describes the mouse and keyboard preferences you can
    set.

    \table
    \header
        \li Preference
        \li Description
    \row
        \li \uicontrol {Hide mouse cursor while typing}
        \li Hide the mouse cursor while you type. Not available on \macos.
    \row
        \li \uicontrol {Enable mouse navigation}
        \li Use the mouse to navigate in the editor, for example, to follow
            links with \key {Ctrl+click} (or \key {Cmd+click} on \macos).
    \row
        \li \uicontrol {Enable scroll wheel zooming}
        \li Zoom the text in the editor by holding \key Ctrl while rotating
            the mouse wheel.
    \row
        \li \uicontrol {Enable built-in camel case navigation}
        \li Move within camelCase and snake_case names one hump or word part
            at a time when using cursor navigation and selection.
    \row
        \li \uicontrol {Enable smart selection changing}
        \li Make \uicontrol {Select Block Up} and \uicontrol {Select Block
            Down} provide smarter selections.
    \row
        \li \uicontrol {Show help tooltips using keyboard shortcut (Alt)}
        \li Show context-sensitive help or type information as a tooltip when
            you press \key Alt.
    \row
        \li \uicontrol {Show help tooltips using the mouse}
        \li Select \uicontrol {On Mouseover} to show context-sensitive help or
            type information on mouseover, or \uicontrol {On Shift+Mouseover}
            to show it only when you press \key Shift while hovering.
    \endtable

    \sa {Configure editors}{How to: Configure editors}, {Find preferences},
    {Indent text or code}, {Specify Qt Quick code style}, {Configuring editors},
    {C++ code style}, {Nim}
*/
