mirror of
https://github.com/neovim/neovim.git
synced 2026-05-23 21:30:11 +00:00
docs: vim.ui.select, misc
This commit is contained in:
Justin M. Keyes
@@ -3226,7 +3226,7 @@ nvim_buf_set_extmark({buf}, {ns_id}, {line}, {col}, {opts})
|
||||
• id : id of the extmark to edit.
|
||||
• end_row : ending line of the mark, 0-based inclusive.
|
||||
• end_col : ending col of the mark, 0-based exclusive, or -1
|
||||
to extend the range to end of line.
|
||||
to extend the range to end of line (if strict=false).
|
||||
• hl_group : highlight group used for the text range. This
|
||||
and below highlight groups can be supplied either as a
|
||||
string or as an integer, the latter of which can be
|
||||
|
||||
@@ -5166,6 +5166,13 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()*
|
||||
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
|
||||
vim.ui.select({ 'tabs', 'spaces' }, {
|
||||
prompt = 'Select tabs or spaces:',
|
||||
@@ -5187,31 +5194,35 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()*
|
||||
|
||||
Parameters: ~
|
||||
• {items} (`any[]`) Arbitrary items
|
||||
• {opts} (`table`) Additional options
|
||||
• {prompt}? (`string`) Text of the prompt. Defaults to
|
||||
`Select one of:`
|
||||
• {format_item}? (`fun(item: any):string`) Function to
|
||||
format an individual item from `items`. Defaults to
|
||||
`tostring`.
|
||||
• {preview_item}? (`fun(item: any):table`) 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 }`.
|
||||
• {opts} (`table`) Options
|
||||
• {prompt}? (`string`, default: `"Select one of:"`)
|
||||
Prompt text.
|
||||
• {format_item}? (`fun(item: any):string`, default:
|
||||
`tostring`) Decides how to format items when displayed
|
||||
in the picker.
|
||||
• {preview_item}?
|
||||
(`fun(item: any):{buf?:integer, pos?:[integer,integer], pos_end?:[integer,integer]}`)
|
||||
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.
|
||||
• {kind}? (`string`) 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.
|
||||
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.
|
||||
• {on_choice} (`fun(item: T?, idx: integer?)`) Called once the user
|
||||
made a choice. `idx` is the 1-based index of `item`
|
||||
within `items`. `nil` if the user aborted the dialog.
|
||||
within `items`, or `nil` if the user aborted the dialog.
|
||||
|
||||
|
||||
==============================================================================
|
||||
|
||||
2
runtime/lua/vim/_meta/api.gen.lua
generated
2
runtime/lua/vim/_meta/api.gen.lua
generated
@@ -597,7 +597,7 @@ function vim.api.nvim_buf_line_count(buf) end
|
||||
--- @param opts vim.api.keyset.set_extmark Optional parameters.
|
||||
--- - id : id of the extmark to edit.
|
||||
--- - end_row : ending line of the mark, 0-based inclusive.
|
||||
--- - end_col : ending col of the mark, 0-based exclusive, or -1 to extend the range to end of line.
|
||||
--- - end_col : ending col of the mark, 0-based exclusive, or -1 to extend the range to end of line (if strict=false).
|
||||
--- - hl_group : highlight group used for the text range. This and below
|
||||
--- highlight groups can be supplied either as a string or as an integer,
|
||||
--- the latter of which can be obtained using `nvim_get_hl_id_by_name()`.
|
||||
|
||||
@@ -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')
|
||||
|
||||
@@ -402,7 +402,7 @@ ArrayOf(DictAs(get_extmark_item)) nvim_buf_get_extmarks(Buffer buf, Integer ns_i
|
||||
/// @param opts Optional parameters.
|
||||
/// - id : id of the extmark to edit.
|
||||
/// - end_row : ending line of the mark, 0-based inclusive.
|
||||
/// - end_col : ending col of the mark, 0-based exclusive, or -1 to extend the range to end of line.
|
||||
/// - end_col : ending col of the mark, 0-based exclusive, or -1 to extend the range to end of line (if strict=false).
|
||||
/// - hl_group : highlight group used for the text range. This and below
|
||||
/// highlight groups can be supplied either as a string or as an integer,
|
||||
/// the latter of which can be obtained using |nvim_get_hl_id_by_name()|.
|
||||
|
||||
Reference in New Issue
Block a user