*winshift.txt*  WinShift.nvim

Rearrange your windows with ease.

Author: Sindre T. Strøm

==============================================================================

INTRODUCTION                                    *winshift.nvim* *winshift*

WinShift lets you move windows, not only around each other, but also in and
out of rows and columns.

USAGE                                           *Win-Move-mode* *winshift-usage*

Enter Win-Move mode by calling `:WinShift`. This will target your current
window for moving. You can move the window either by using |hjkl| or the arrow
keys. You can move the window to any of the far ends of the viewport by
pressing one of `HJKL`, or shift + any arrow key. Exit Win-Move mode by
pressing `q` / `<esc>` / `<C-c>`.

CONFIGURATION                                   *winshift-config*

Example configuration with default settings:
>
    -- Lua
    require("winshift").setup({
      highlight_moving_win = true,  -- Highlight the window being moved
      focused_hl_group = "Visual",  -- The highlight group used for the moving window
      moving_win_options = {
        -- These are local options applied to the moving window while it's
        -- being moved. They are unset when you leave move mode.
        wrap = false,
        cursorline = false,
        cursorcolumn = false,
        colorcolumn = "",
      },
      keymaps = {
        disable_defaults = false, -- Disable the default keymaps
        win_move_mode = {
          ["h"] = "left",
          ["j"] = "down",
          ["k"] = "up",
          ["l"] = "right",
          ["H"] = "far_left",
          ["J"] = "far_down",
          ["K"] = "far_up",
          ["L"] = "far_right",
          ["<left>"] = "left",
          ["<down>"] = "down",
          ["<up>"] = "up",
          ["<right>"] = "right",
          ["<S-left>"] = "far_left",
          ["<S-down>"] = "far_down",
          ["<S-up>"] = "far_up",
          ["<S-right>"] = "far_right",
        },
      },
      ---A function that should prompt the user to select a window.
      ---
      ---The window picker is used to select a window while swapping windows with
      ---`:WinShift swap`.
      ---@return integer? winid # Either the selected window ID, or `nil` to
      ---   indicate that the user cancelled / gave an invalid selection.
      window_picker = function()
        return require("winshift.lib").pick_window({
          -- A string of chars used as identifiers by the window picker.
          picker_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
          filter_rules = {
            -- This table allows you to indicate to the window picker that a window
            -- should be ignored if its buffer matches any of the following criteria.
            cur_win = true, -- Filter out the current window
            floats = true,  -- Filter out floating windows
            filetype = {},  -- List of ignored file types
            buftype = {},   -- List of ignored buftypes
            bufname = {},   -- List of vim regex patterns matching ignored buffer names
          },
          ---A function used to filter the list of selectable windows.
          ---@param winids integer[] # The list of selectable window IDs.
          ---@return integer[] filtered # The filtered list of window IDs.
          filter_func = nil,
        })
      end,
    })
<

COMMANDS                                        *winshift-commands*

                                                *:WinShift*
:WinShift [direction]
                        When called without [direction]: starts Win-Move mode
                        targeting the current window for moving. For how to
                        use Win-Move mode, see |Win-Move-mode|. With
                        [direction] perform a one-shot move operation on the
                        current window, moving it in the given direction.
                        [direction] can be one of:
                            `left`, `right`, `up`, `down`, `far_left`,
                            `far_right`, `far_up`, `far_down`

                        The `far_` variants will move the window to the far
                        end of the viewport in the given direction.

:WinShift swap
                        Swap the current window with another. When this
                        command is called, you'll be prompted to select the
                        window you want to swap with. A selection is made by
                        pressing the character displayed in the statusline of
                        the target window. The input is case-insensitive.

CAVEATS                                         *winshift-caveats*

Moving through windows with 'winfixwidth' and / or 'winfixheight' can be a bit
wonky. It will work, but it can be a bit hard to follow the movement, and the
fixed window might end up with different dimensions after. This is simply a
consequence of vim being forced to resize the window due to there not being
enough space to adhere to the fixed window's preferred dimensions.

 vim:tw=78:ts=8:ft=help:norl: