// 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.webp} {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 download prompt for particular files, go to \preferences >
    \uicontrol {Text Editor} > \uicontrol {Generic Highlighter} and add a
    wildcard file pattern to \uicontrol {Skip update check for files
    matching}, separated by a comma.

    To turn off syntax highlighting entirely for particular files, add a
    wildcard file pattern to \uicontrol {Skip syntax highlighting for files
    matching} instead.

    For example, to skip text files, license files, and README files:
    \c {*.txt, LICENSE*, README}

    \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}, {Generic Highlighter}
*/

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

    \ingroup creator-reference-editors

    \title Generic Highlighter

    \brief Manage generic syntax highlight definitions and choose which files
    to exclude from highlighting.

    \QC uses the \l {KSyntaxHighlighting} engine with Kate syntax definitions
    to highlight code in files that do not have dedicated support, such as
    Python or shell script files. To manage the highlight definitions that
    this engine uses, select \preferences > \uicontrol {Text Editor} >
    \uicontrol {Generic Highlighter}.

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

    The following table describes the preferences you can set.

    \table
    \header
        \li Preference
        \li Description
    \row
        \li \uicontrol {Download Definitions}
        \li Download missing and update existing syntax definition files.
    \row
        \li \uicontrol {User Highlight Definition Files}
        \li Set the folder where \QC looks for your own highlight definition
            files, in addition to the downloaded ones.
    \row
        \li \uicontrol {Reload Definitions}
        \li Reload definition files that were modified outside \QC.
    \row
        \li \uicontrol {Reset Remembered Definitions}
        \li Reset the highlight definitions that \QC remembered for files
            that can be associated with more than one definition. See
            \l{Download highlight definitions}.
    \row
        \li \uicontrol {Skip update check for files matching}
        \li List wildcard-aware file patterns, separated by commas, for which
            \QC does not prompt you to download a missing highlight
            definition.
    \row
        \li \uicontrol {Skip syntax highlighting for files matching}
        \li List wildcard-aware file patterns, separated by commas, for which
            \QC does not apply generic syntax highlighting at all.
    \endtable

    \sa {Configure editors}{How to: Configure editors}, {Configuring editors},
    {Download highlight definitions}
*/

/*!
    \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}
*/
