btv.win

btv.win.current()

No documentation comment in the prelude.

_{Defined in api.lua.}

btv.win.list()

No documentation comment in the prelude.

_{Defined in api.lua.}

btv.win.set_current(win)

btv.win.set_current(win): focus win (make it the current window) [alias nvim_set_current_win]. win is a window id (0 / nil = the current window, a no-op). The switch is queued and applied after the Lua chunk like the other window ops; the mirror is updated write-through so an immediate btv.win.current() / current-buffer read in the same chunk reflects the new focus.

_{Defined in api.lua.}

btv.win.buf(win)

No documentation comment in the prelude.

_{Defined in api.lua.}

btv.win.width(win)

No documentation comment in the prelude.

_{Defined in api.lua.}

btv.win.height(win)

No documentation comment in the prelude.

_{Defined in api.lua.}

btv.win.textoff(win)

btv.win.textoff(win) -> the number of cells the window’s left gutter takes before its text: the fold column, the sign column and the number column together (what neovim reports as getwininfo()[1].textoff). btv.win.width(win) includes the gutter, so the text area is btv.win.width(win) - btv.win.textoff(win) wide, the width to centre content in. 0 for an unknown window.

_{Defined in api.lua.}

btv.win.call(win, fn)

nvim_win_call(win, fn) / nvim_buf_call(buf, fn): run fn as if win/buf were current, returning fn’s result. In neovim these temporarily switch the editor’s current window/buffer for the duration of the callback; in bemtvi the callback runs synchronously in-VM, where “current” is the mirror the server pushed (btv._cur_win / btv._cur_buf / btv._cur_cursor). So these swap that mirror context for the call, run fn, and restore it — which makes every read inside the callback (nvim_win_get_cursor, nvim_get_current_buf, vim.fn.line/col/winnr, …) resolve against the requested window/buffer, and every explicit-handle write that bemtvi does expose (vim.bo[buf] option sets, nvim_buf_set_extmark(buf, …)) resolves the swapped mirror at call time and queues that concrete handle — so it, too, targets the right place.

What bemtvi CAN’T do is retarget a mutation that binds to “current” only at DRAIN time — an ex-command (vim.cmd), feedkeys, or an LSP buf request — since the queued-ops model applies those against the editor’s real current buffer/window after the chunk, which this call never actually switched. Rather than silently mutate the wrong context, btv._call_ctx_lock is set for the duration of a call whose target differs from the real current, and those funnels raise while it is set (see btv._assert_call_ctx). Plugins use these calls to read a window’s view/dimensions, which is fully faithful.

_{Defined in api.lua.}

btv.win.config(win)

nvim_win_get_config(win): the float placement of win as neovim’s config map, or { relative = "" } for a tiled window. Reads the btv._wins mirror (the server pushes each float’s config into w.float; nvim_open_win / nvim_win_set_config write through it so a read within the same chunk agrees).

_{Defined in api.lua.}

btv.win.saveview()

btv.win.saveview() [alias vim.fn.winsaveview]: the current window’s view — cursor position, scroll (topline/leftcol), and the cursor-restore fields neovim returns. bemtvi has no separate curswant/coladd/skipcol state, so those mirror col / are 0.

_{Defined in api.lua.}

btv.win.set_topline(win, topline)

btv.win.set_topline(win, topline): scroll win so its first visible buffer line is topline (1-based, neovim/winsaveview convention; clamped to the last line).

_{Defined in api.lua.}

btv.win.set_leftcol(win, leftcol)

btv.win.set_leftcol(win, leftcol): horizontally scroll win so its first visible screen column is leftcol (0-based). Only meaningful under 'nowrap'.

_{Defined in api.lua.}

btv.win.set_cursor(win, line, col)

btv.win.set_cursor(win, line[, col]): move win’s cursor to line (1-based) / col (0-based byte column, default 0). The explicit-win counterpart of the (intentionally-absent) nvim_win_set_cursor, and the sanctioned caret primitive a pure-Lua editor feature drives with. It works mid-insert (a col one past the last char is legal there), so a snippet engine owning its own tabstop session jumps between tabstops by calling this from its insert-mode jump key — the caret moves and further typing lands at the new spot.

_{Defined in api.lua.}

btv.win.selection(win)

btv.win.selection([win]) -> { s_row, s_col, e_row, e_col } or nil: the live selection in the current window (a Visual or Select selection, a modeless Shift selection), as the 0-based, end-exclusive byte range btv.win.select_range takes and btv.buf.text reads. Both ends fall on grapheme boundaries (a combining sequence or a ZWJ emoji is selected whole), so the text between them is never a cut character. A linewise selection runs from column 0 of its first line to column 0 of the line after its last. nil when nothing is selected. Only the current window has a live selection, so win must be 0, nil or its id.

_{Defined in api.lua.}

btv.win.select_range(win, s_row, s_col, e_row, e_col, opts)

btv.win.select_range(win, s_row, s_col, e_row, e_col[, opts]): enter Select mode over the 0-based, end-exclusive byte range (s_row, s_col) .. (e_row, e_col) in win. The range is highlighted like a charwise Visual selection, but the next printable key / <CR> / <BS> replaces it (deletes the range and enters Insert with that input) — vim’s v_CTRL-G behavior. This is the Select-mode sibling of btv.win.set_cursor and the P6 snippet-engine primitive: a consumer selecting a non-empty placeholder ${1:default} calls this (so typing replaces the default); an empty range degrades to caret-plus-Insert at the start (an empty tabstop uses btv.win.set_cursor instead).

opts.on_escape controls where <Esc> (with nothing typed) leaves the kept selection:

"normal"   -- (default) keep the text, drop to Normal on the selection — vim's v_CTRL-G
"insert"   -- keep the text, park the caret in Insert past it (a snippet engine wants this,
           --   so it can keep editing the placeholder)

_{Defined in api.lua.}

btv.win.restview(win, view)

btv.win.restview(win, view): restore win’s view from a winsaveview-shaped table (topline 1-based, leftcol 0-based, optional lnum/col cursor) — the explicit-win winrestview analogue. Only the present fields are applied.

_{Defined in api.lua.}

btv.win.nr(arg)

btv.win.nr([arg]) [alias vim.fn.winnr]: the current window’s 1-based number (its index in the layout order), or with "$" the number of windows. (vim’s "#" previous-window form needs window history the mirror doesn’t keep, so it errors.)

_{Defined in api.lua.}

btv.win.width_nr(nr)

No documentation comment in the prelude.

_{Defined in api.lua.}

btv.win.height_nr(nr)

No documentation comment in the prelude.

_{Defined in api.lua.}

btv.win.is_valid(win)

nvim_win_is_valid(win): whether win names a window the mirror knows about (0/nil is the current window, always valid while one exists). The window analogue of nvim_buf_is_valid — picker teardown/resize guards call it constantly.

_{Defined in api.lua.}

btv.win.position(win)

nvim_win_get_position(win): the window’s top-left as 0-based {row, col} screen coordinates. Exact for a float (its placement); a tiled window’s screen origin isn’t carried in the mirror, so it reports {0, 0} — a documented approximation (a float-positioning plugin positions its own floats and reads their config directly, so the value it cares about is exact). 0/nil is the current window.

_{Defined in api.lua.}

btv.win.getid(winnr, _tabnr)

btv.win.getid([winnr[, tabnr]]) [alias vim.fn.win_getid]: the window id for a 1-based window number (default: the current window). tabnr is accepted but only the current tab’s layout order is consulted (the global window mirror carries it).

_{Defined in api.lua.}

btv.win.findbuf(bufnr)

btv.win.findbuf(bufnr) [alias vim.fn.win_findbuf]: the ids of every window currently displaying bufnr, in any tab (vim spans tabpages here).

_{Defined in api.lua.}

btv.win.gettype(winid)

btv.win.gettype([winid]) [alias vim.fn.win_gettype]: "popup" for a float, "" for a normal window — the distinction a plugin draws to know whether a window is one of its own floats.

_{Defined in api.lua.}

btv.win.screenpos(winnr)

btv.win.screenpos(winnr) [alias vim.fn.win_screenpos]: the 1-based (row, col) screen position of a window’s top-left text cell. Known exactly for a float (its placement); a tiled window’s screen origin isn’t carried in the mirror, so it reports {1, 1} (top-left) — a documented approximation float-positioning plugins tolerate (they position their own floats and read their config directly).

_{Defined in api.lua.}