From d960ae676073354b7a844cf59cfe534ac1392aa6 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 25 Apr 2026 19:39:35 +0200 Subject: docs: vim.ui.select, misc --- runtime/lua/vim/ui.lua | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) (limited to 'runtime/lua/vim/ui.lua') diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua index bf4728c4d8..e4f18b9b3a 100644 --- a/runtime/lua/vim/ui.lua +++ b/runtime/lua/vim/ui.lua @@ -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') -- cgit