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

/*!
    \page creator-how-to-edit-vim-style.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-configure-editors

    \title Edit like in Vim

    To run the main editor in a manner similar to the Vim editor, go to
    \uicontrol Edit > \uicontrol Advanced and select \uicontrol {Use FakeVim},
    or select \key {Alt+Y,Alt+Y}.

    \section1 Escape FakeVim mode

    To temporarily escape FakeVim mode to access the normal \QC keyboard
    shortcuts like \key {Ctrl+R} for \uicontrol Run, select \key {,} before
    selecting the shortcut.

    \section1 Quit FakeVim mode

    To quit the FakeVim mode, go to \uicontrol Edit > \uicontrol Advanced and
    clear \uicontrol {Use FakeVim}, or select \key {Alt+Y,Alt+Y}.

    \sa {FakeVim modes and commands}, {FakeVim}, {Change editor colors}
*/

/*!
    \page creator-editor-fakevim.html
    \previouspage creator-reference.html

    \ingroup creator-reference-editors

    \title FakeVim modes and commands

    \brief Supported Vim modes and emulated commands.

    In the \uicontrol FakeVim mode, most keystrokes in the main editor are
    intercepted and interpreted in a way that resembles Vim. Most of the
    supported commands can be followed by a motion command or executed in visual
    mode, or they work with registers, or can be prefixed with a number of
    repetitions.

    The following sections describe the commands emulated in the supported modes
    and how they diverge from Vim in functionality:

    \list
        \li Normal
        \li Visual
        \li Command line (:)
        \li Insert and replace
    \endlist

    For more information about using Vim, see \l{http://www.vim.org/docs.php}
    {Documentation} on the Vim web site.

    \section1 Normal and visual modes

    \list
        \li Basic movement, such as \c h/j/k/l, \c <C-U>, \c <C-D>, \c <C-F>,
            \c <C-B>, \c gg, \c G, \c 0, \c ^, \c $
        \li Word movement, such as \c w, \c e, \c b
        \li \e Inner/a movement, such as \c ciw, \c 3daw, ya{
        \li \c f and \c t movement
        \li \c [ and \c ] movement
        \li { and } paragraph movement
        \li Delete/change/yank/paste with register
        \li Undo and redo
        \li \c <C-A> and \c <C-X> increase or decrease a number in decimal,
            octal, or hexadecimal format (for example \c 128<C-A> on or before
            \c "0x0ff" changes it to \c "0x17f")
        \li \c . repeats the last change
        \li \c /search, \c ?search, \c *, \c #, \c n, \c N - most of regular
            expression syntax is used in Vim except that \c \< and \c \> are
            the same as \c {\b} in QRegExp
        \li \c @ and \c q (macro recording and execution) special keys are saved
            as \c <S-Left>
        \li Marks
        \li \c gv goes to last visual selection; can differ if text is edited
            around it
        \li Indentation using \c =, \c <<, \c >>, with movement, count, and in
            visual mode
        \li \e {to upper/lower}, such as \c ~, \c gU, \c gu
        \li \c i, \c a, \c o, \c I, \c A, and \c O enter insert mode
        \li Scroll window, such as \c zt, \c zb, \c zz
        \li Wrap line movement, such as \c gj, \c gk, \c g0, \c g^, \c g$
    \endlist

    \section1 Command-line mode

    \list
        \li \c :map, \c :unmap, \c :inoremap, and so on
        \li \c :source sources vimrc files line-by-line
        \li \c :substitute substitutes an expression in a range
        \li \c :'<,'>!cmd filters through an external command (for example,
            sorts the lines in a file with \c :%!sort)
        \li \c :<range>sor[t][!]
        \li \c :.!cmd inserts the standard output of an external command
        \li \c :read
        \li \c :yank, \c :delete, \c :change
        \li \c :move, \c :join
        \li \c :20 goes to an address
        \li \c :history
        \li \c :registers, \c :display
        \li \c :nohlsearch
        \li \c :undo, \c :redo
        \li \c :normal
        \li \c :<, \c :>
        \li \c{set formatoptions=}, see \c{:h fo-table} in the Vim documentation.
            Currently supported letters: \c fo-j
    \endlist

    \section1 Insert mode

    \list
        \li \c <C-O> executes a single command and returns to insert mode
        \li \c <C-V> inserts a raw character
        \li \c <insert> toggles replace mode
    \endlist

    \section1 Options

    Use \c {:set ...} to set the options listed in the following table:

    \table
    \header
        \li Long Name
        \li Short Name
        \li Arguments
    \row
        \li \c autoindent
        \li \c ai
        \li
    \row
        \li \c backspace
        \li \c bs
        \li \c indent, \c eol, \c start
    \row
        \li \c blinkingcursor
        \li \c bc
        \li
    \row
        \li \c clipboard
        \li \c cb
        \li
    \row
        \li \c expandtab
        \li \c et
        \li
    \row
        \li \c hlsearch
        \li \c hls
        \li
    \row
        \li \c ignorecase
        \li \c ic
        \li
    \row
        \li \c incsearch
        \li \c is
        \li
    \row
        \li \c iskeyword
        \li \c isk
        \li A combination of the following characters: \c @, \c 48-57, \c _,
            \c 192-255, \c a-z, \c A-Z
    \row
        \li \c relativenumber
        \li \c rnu
        \li
    \row
        \li \c scrolloff
        \li \c so
        \li
    \row
        \li \c shiftwidth
        \li \c sw
        \li
    \row
        \li \c showcmd
        \li \c sc
        \li
    \row
        \li \c smartcase
        \li \c scs
        \li
    \row
        \li \c smartindent
        \li \c si
        \li
    \row
        \li \c smarttab
        \li \c sta
        \li
    \row
        \li \c startofline
        \li \c sol
        \li
    \row
        \li \c tabstop
        \li \c ts
        \li
    \row
        \li \c tildeop
        \li \c top
        \li
    \row
        \li \c usecoresearch
        \li \c ucs
        \li
    \row
        \li \c wrapscan
        \li \c ws
        \li
    \endtable

    \section1 Vimrc example

    \code
    " highlight matched
    set hlsearch
    " case insensitive search
    set ignorecase
    set smartcase
    " search while typing
    set incsearch
    " wrap-around when searching
    set wrapscan
    " show pressed keys in lower right corner
    set showcmd
    " tab -> spaces
    set expandtab
    set tabstop=4
    set shiftwidth=4
    " keep a 5 line buffer for the cursor from top/bottom of window
    set scrolloff=5
    " X11 clipboard
    set clipboard=unnamed
    " use ~ with movement
    set tildeop

    " mappings
    nnoremap ; :
    inoremap jj <Esc>

    " clear highlighted search term on space
    noremap <silent> <Space> :nohls<CR>

    " reselect visual block after indent
    vnoremap < <gv
    vnoremap > >gv

    " MOVE LINE/BLOCK
    nnoremap <C-S-J> :m+<CR>==
    nnoremap <C-S-K> :m-2<CR>==
    inoremap <C-S-J> <Esc>:m+<CR>==gi
    inoremap <C-S-K> <Esc>:m-2<CR>==gi
    vnoremap <C-S-J> :m'>+<CR>gv=gv
    vnoremap <C-S-K> :m-2<CR>gv=gv
    \endcode

    \sa {Edit like in Vim}, {FakeVim}
*/

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

    \ingroup creator-reference-editors

    \title FakeVim

    \brief Set indentation for Vim-style editing and map vim commands
    to \QC functions.

    To set prerences for Vim-style editing, go to \preferences >
    \uicontrol FakeVim.

    \section1 Setting Vim behavior

    To set Vim behavior, go to \preferences > \uicontrol FakeVim >
    \uicontrol General.

    \image {qtcreator-preferences-fakevim-general.webp} {General tab in FakeVim preferences}

    To use presets:

     \list
        \li To preselect the indentation settings specified for the text editor,
            select \uicontrol {Copy Text Editor Settings}.
        \li To preselect the Qt coding style, select \uicontrol {Set Qt Style}.
        \li To preselect a simple indentation style, select
            \uicontrol {Set Plain Style}.
    \endlist

    Then change the preselected settings.

    \section1 Emulating plugins

    Select popular vim plugins to emulate in \uicontrol {Plugin Emulation}.

    The following table describes the available plugins with links to them.

    \table
    \header
        \li Vim Plugin
        \li Description
    \row
        \li \l{https://github.com/tpope/vim-commentary}{vim-commentary}
        \li \c gc action to comment code regions. For example, \c gcc, \c gc2j,
            \c gcip
    \row
        \li \l{https://github.com/vim-scripts/ReplaceWithRegister}
            {ReplaceWithRegister}
        \li
            \list
                \li \c [count]["x]gr{motion} to replace \c {motion} with the
                contents of register \c x.
                \li ["x]grr to replace the current line.
            \endlist
    \row
        \li \l{https://github.com/vim-scripts/argtextobj.vim}{argtextobj.vim}
        \li Defines the \c ia and \c aa text objects for function parameters.
    \row
        \li \l{https://github.com/tommcdo/vim-exchange}{vim-exchange}
        \li A text exchange operator for vim.
    \row
        \li \l{https://github.com/tpope/vim-surround}{vim-surround}
        \li Adds mappings for deleting, adding, and changing surroundings.
    \endtable

    \section1 Mapping FakeVim commands

    To map commands entered on the \uicontrol FakeVim command line to
    \QC functions:

    \list 1
        \li Go to \preferences > \uicontrol FakeVim >
            \uicontrol {Ex Command Mapping}.
        \li Enter a string in the \uicontrol Filter field to find a \QC function.
            \image {qtcreator-fakevim-options-ex-command-mapping.png} {Ex Command Mapping tab in FakeVim preferences}
        \li Select a function in the list
        \li In the \uicontrol {Regular expression} field, nter a string that will
            trigger the function.

            You can see the trigger expression in the
            \uicontrol {Ex Trigger Expression} field.
    \endlist

    To remove the selected trigger expression, select \uicontrol Reset.

    To reset the trigger expressions for all functions, select
    \uicontrol {Reset All}.

    \section1 Mapping user commands

    To map \e {user commands} to keyboard shortcuts, go to \preferences >
    \uicontrol FakeVim > \uicontrol {User Command Mapping}. The user command
    mapped to the shortcut is executed by FakeVim as if you were typing it
    (as when replaying a macro).

    \image {qtcreator-fakevim-options-user-command-mapping.png} {User Command Mapping tab FakeVim preferences}

    \sa {Edit like in Vim}, {FakeVim modes and commands}
*/
