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

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

    \ingroup creator-how-to-edit

    \title Download highlight definitions

    \QC uses the \l {KSyntaxHighlighting}
    syntax highlighting engine with Kate syntax definitions.
    It comes with most of the commonly used Kate definitions, and you can download
    more definitions. For more information about the definition files, see
    \l {Working with Syntax Highlighting}.

    Font attributes that a syntax definition file explicitly specifies, such as
    bold, italic, underline, or strike through, are applied. Colors are applied
    if they are readable with \QC themes.

    \section2 Remember preferred definitions

    If more than one highlight definition is available for the file that you
    open for editing, the editor asks you to select the one to use.

    To save the selection, select \uicontrol {Remember My Choice}.

    To reset the remembered definitions, go to \preferences >
    \uicontrol {Text Editor} > \uicontrol {Generic Highlighter} and select
    \uicontrol {Reset Remembered Definitions}.

    \image {qtcreator-syntax-highlighter.png} {Generic Highlighter tab in Text Editor preferences}

    \section2 Download definitions

    If the editor cannot find the highlight definition for a file that you open
    for editing, it prompts you to download additional highlight definition
    files. Select \uicontrol {Download Definitions} to download the files.

    To view information about the downloaded files, open the \l{View output}
    {General Messages} view.

    \section2 Ignore file patterns

    To suppress the message for a particular file pattern, go to \preferences >
    \uicontrol {Text Editor} > \uicontrol {Generic Highlighter} and add the
    pattern to \uicontrol {Ignored file patterns}, separated by a comma.

    To ignore files according to their extension, add:
    \c {\A(?:(?s:[^/\\]*\.<extension>))\z}

    To ignore files according to their filename, add:
    \c {\A(?:(?s:<string>[^/\\]*))\z}

    For example:
    \c {\A(?:[^/\\]*\.txt)\z,\A(?:LICENSE[^/\\]*)\z,\A(?:README)\z,\A(?:qmldir)\z}

    \section2 Add your own definitions

    If you have written your own syntax definition files, add a definition search
    path in \uicontrol {User Highlight Definition Files}.

    To apply the changes you make to the definition files, select
    \uicontrol {Reload Definitions}.

    \sa {Edit code}{How to: Edit code}, {Editing code}
*/

/*!
    \page creator-how-to-use-code-blocks.html

    \previouspage creator-how-tos.html

    \ingroup creator-how-to-edit

    \title Highlight code blocks

    Block highlighting visually separates parts of the code that belong together.
    For example, when you place the cursor within a set of braces, the code
    enclosed in braces is highlighted.

    \image {qtcreator-blockhighlighting.png} {A code block highlighted in the editor}

    To enable block highlighting, go to \preferences > \uicontrol {Text Editor}
    > \uicontrol Display and select \uicontrol {Highlight blocks}.

    \section1 Fold code blocks

    Select the folding markers to collapse and expand blocks of code within braces.
    In the image above, the folding markers are located between the line number
    and the text pane.

    To show the folding markers, go to \preferences >
    \uicontrol {Text Editor} > \uicontrol Display and select
    \uicontrol {Display folding markers}. This option is enabled by default.

    \image {qtcreator-preferences-text-editor-display.webp} {Display tab in Text Editor preferences}

    \section1 Fold all comment blocks

    To fold all comment blocks, go to \uicontrol Tools > \uicontrol C++ >
    \uicontrol {Fold All Comment Blocks}.

    To unfold all comment blocks, select \uicontrol {Unfold All Comment Blocks}.

    \section1 Animate matching braces

    When the cursor is on a brace, the matching brace is animated by default.

    To turn off the animation and just highlight the block and the braces, go to
    \preferences > \uicontrol {Text Editor} > \uicontrol Display and clear
    \uicontrol {Animate matching parentheses}.

    \section1 Move between code blocks

    Use keyboard shortcuts to move within and between code blocks:

    \list
        \li To go to block end, select \key {Ctrl+]}.
        \li To go to block start, select \key {Ctrl+[}.
    \endlist

    To also select the lines from the cursor position to the end
    or beginning of the block, select \key {Ctrl+Shift+]} and
    \key {Ctrl+Shift+[}, respectively.

    \sa {Edit code}{How to: Edit code}, {Editing code}
*/
