mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-05-24 22:00:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: vim.ui.select, misc

Browse Source
This commit is contained in:
Justin M. Keyes
2026-04-25 19:39:35 +02:00
parent 825bfba789
commit d960ae6760
5 changed files with 57 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
runtime/lua/vim/ui.lua
View File

@@ -3,33 +3,35 @@ local M = {}
---@class vim.ui.select.Opts
---@inlinedoc
---
--- Text of the prompt.
--- (default: `Select one of:`)
--- Prompt text.
--- (default: `"Select one of:"`)
---@field prompt? string
---
--- Formats an individual item from `items`.
--- Decides how to format items when displayed in the picker.
--- (default: `tostring`)
---@field format_item? fun(item: any):string
---
--- Function to preview an individual item from `items`.
--- If missing, no special preview is used.
--- Should ensure a buffer with contents (text, highlighting) providing details about an item.
--- Should return a table with information that `vim.ui.select` implementations may
--- use to show the preview buffer in the way they see fit:
--- - {buf}? (`integer`) - buffer id with preview. If missing, no preview should be shown.
--- - {pos}? (`[integer, integer]`) - (1,0)-indexed tuple of where to position cursor
--- in the preview buffer. If missing, should be treated as `{ 1, 0 }`.
---@field preview_item? fun(item: any):table
--- Decides how to preview an item by preparing a scratch buffer with the item details (including text, highlighting, etc.).
--- When the picker decides to "preview" an item, it should call this function.
--- Must return a table with these keys:
--- - {buf}? (`integer`) Buffer containing the previewed item details, or nil if no preview should be shown.
--- - {pos}? (`[integer, integer]`) Specifies the (1,0)-indexed cursor position in the preview buffer. If nil, should be treated as `{ 1, 0 }`.
--- - {pos_end}? (`[integer, integer]`) Specifies the (1,0)-indexed (end-exclusive) end position of the preview range. If nil, no range is intended for a preview.
---@field preview_item? fun(item: any):{buf?:integer, pos?:[integer,integer], pos_end?:[integer,integer]}
---
--- Arbitrary hint string indicating the item shape.
--- Plugins reimplementing `vim.ui.select` may wish to
--- use this to infer the structure or semantics of
--- `items`, or the context in which select() was called.
--- Arbitrary hint string indicating the item shape. The picker may wish to use this to infer the
--- structure or semantics of `items`, or the context in which select() was called.
---@field kind? string
--- Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous)
--- work until `on_choice`.
---
--- Plugins may override `vim.ui.select` to provide a custom "picker" interface; they are expected
--- to call the `format_item` and `preview_item` handlers (if any) provided by the caller. They may
--- also use the `kind` hint (if provided by the caller) to decide how to handle some items.
---
--- Note: the default `vim.ui.select` currently doesn't support preview.
---
--- Example:
---
--- ```lua
@@ -53,11 +55,9 @@ local M = {}
---
---@generic T
---@param items T[] Arbitrary items
---@param opts vim.ui.select.Opts Additional options
---@param on_choice fun(item: T|nil, idx: integer|nil)
--- Called once the user made a choice.
--- `idx` is the 1-based index of `item` within `items`.
--- `nil` if the user aborted the dialog.
---@param opts vim.ui.select.Opts Options
---@param on_choice fun(item: T|nil, idx: integer|nil) Called once the user made a choice.
--- `idx` is the 1-based index of `item` within `items`, or `nil` if the user aborted the dialog.
function M.select(items, opts, on_choice)
vim.validate('items', items, 'table')
vim.validate('on_choice', on_choice, 'function')