vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

popup.txt (49472B)


      1 *popup.txt*	For Vim version 9.2.  Last change: 2026 Sep 30
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
      5 
      6 
      7 Displaying text in a popup window.	*popup* *popup-window* *popupwin*
      8 
      9 
     10 1. Introduction			|popup-intro|
     11    Window position and size	|popup-position|
     12    Closing the popup window	|popup-close|
     13    Popup buffer and window	|popup-buffer|
     14    Terminal in popup window	|popup-terminal|
     15 2. Functions			|popup-functions|
     16    Details			|popup-function-details|
     17 3. Usage			|popup-usage|
     18    popup_create() arguments	|popup_create-arguments|
     19    Popup text properties	|popup-props|
     20    Position popup with textprop	|popup-textprop-pos|
     21    Popup filter			|popup-filter|
     22    Popup callback		|popup-callback|
     23    Popup scrollbar		|popup-scrollbar|
     24    Popup opacity		|popup-opacity|
     25    Popup mask			|popup-mask|
     26    Popup image			|popup-image|
     27 4. Examples			|popup-examples|
     28 
     29 
     30 {not available if the |+popupwin| feature was disabled at compile time}
     31 
     32 ==============================================================================
     33 1. Introduction						*popup-intro*
     34 
     35 We are talking about popup windows here, text that goes on top of the regular
     36 windows and is under control of a plugin.  You cannot edit the text in the
     37 popup window like with regular windows.
     38 
     39 A popup window can be used for such things as:
     40 - briefly show a message without overwriting the command line
     41 - prompt the user with a dialog
     42 - display contextual information while typing
     43 - give extra information for auto-completion
     44 
     45 The text in the popup window can be colored with |text-properties|.  It is
     46 also possible to use syntax highlighting.
     47 
     48 The default colors are taken from |hl-Popup| (body), |hl-PopupBorder|
     49 (border) and |hl-PopupTitle| (title), which all link to |hl-Pmenu| by
     50 default for backward compatibility.  Override them to give general popup
     51 windows a different look than the popup completion menu, or use the
     52 "highlight" argument or the 'wincolor' option for a per-popup override: >
     53 	hi MyPopupColor ctermbg=lightblue guibg=lightblue
     54 	call setwinvar(winid, '&wincolor', 'MyPopupColor')
     55 
     56 'hlsearch' highlighting is not displayed in a popup window.
     57 
     58 A popup window has a window-ID like other windows, but behaves differently.
     59 The size can be up to the whole Vim window and it overlaps other windows.
     60 Popup windows can also overlap each other.  The "zindex" property specifies
     61 what goes on top of what.
     62 							*E366*
     63 The popup window contains a buffer, and that buffer is always associated with
     64 the popup window.  The window cannot be in Normal, Visual or Insert mode, it
     65 does not get keyboard focus.  You can use functions like `setbufline()` to
     66 change the text in the buffer.  There are more differences from how this
     67 window and buffer behave compared to regular windows and buffers, see
     68 |popup-buffer|.
     69 
     70 If this is not what you are looking for, check out other popup functionality:
     71 - popup menu, see |popup-menu|
     72 - balloon, see |balloon-eval|
     73 
     74 
     75 WINDOW POSITION AND SIZE				*popup-position*
     76 
     77 The height of the window is normally equal to the number of, possibly
     78 wrapping, lines in the buffer.  It can be limited with the "maxheight"
     79 property.  You can use empty lines to increase the height or the "minheight"
     80 property.
     81 
     82 The width of the window is normally equal to the longest line in the buffer,
     83 also when that line is not displayed.  This keeps the width the same while
     84 scrolling through the popup.  It can be limited with the "maxwidth" property,
     85 which is a good idea when the buffer may contain long lines.  You can use
     86 spaces to increase the width or use the "minwidth" property.
     87 
     88 By default the 'wrap' option is set, so that no text disappears.  Otherwise,
     89 if there is not enough space then the window is shifted left in order to
     90 display more text.  When right-aligned the window is shifted right to display
     91 more text.  The shifting can be disabled with the "fixed" property.
     92 
     93 Vim tries to show the popup in the location you specify.  In some cases, e.g.
     94 when the popup would go outside of the Vim window, it will show it somewhere
     95 nearby.  E.g. if you use `popup_atcursor()` the popup normally shows just above
     96 the current cursor position, but if the cursor is close to the top of the Vim
     97 window it will be placed below the cursor position.
     98 
     99 When the screen scrolls up for output of an Ex command, popups move too, so
    100 that they will not cover the output.
    101 
    102 The current cursor position is displayed even when it is under a popup window.
    103 That way you can still see where it is, even though you cannot see the text
    104 that it is in.
    105 
    106 
    107 CLOSING THE POPUP WINDOW				*popup-close*
    108 
    109 Normally the plugin that created the popup window is also in charge of closing
    110 it.  If somehow a popup hangs around, you can close all of them with: >
    111 	call popup_clear(1)
    112 Some popups, such as notifications, close after a specified time.  This can be
    113 set with the "time" property on `popup_create()`.
    114 Otherwise, a popup can be closed by clicking on the X in the top-right corner
    115 or by clicking anywhere inside the popup.  This must be enabled with the
    116 "close" property.  It is set by default for notifications.
    117 
    118 
    119 POPUP BUFFER AND WINDOW					*popup-buffer*
    120 
    121 If a popup function is called to create a popup from text, a new buffer is
    122 created to hold the text and text properties of the popup window.  The buffer
    123 is always associated with the popup window and manipulation is restricted:
    124 - the buffer has no name
    125 - 'buftype' is "popup"
    126 - 'swapfile' is off
    127 - 'bufhidden' is "hide"
    128 - 'buflisted' is off
    129 - 'undolevels' is -1: no undo at all
    130 - all other buffer-local and window-local options are set to their Vim default
    131   value.
    132 
    133 It is possible to change the specifically mentioned options, but anything
    134 might break then, so better leave them alone.
    135 
    136 The window does have a cursor position, but the cursor is not displayed.  In
    137 fact, the cursor in the underlying window is displayed, as if it peeks through
    138 the popup, so you can see where it is.
    139 
    140 To execute a command in the context of the popup window and buffer use
    141 `win_execute()`.  Example: >
    142 	call win_execute(winid, 'syntax enable')
    143 
    144 Options can be set on the window with `setwinvar()`, e.g.: >
    145 	call setwinvar(winid, '&wrap', 0)
    146 And options can be set on the buffer with `setbufvar()`, e.g.: >
    147 	call setbufvar(winbufnr(winid), '&filetype', 'java')
    148 You can also use `win_execute()` with a ":setlocal" command.
    149 
    150 
    151 TERMINAL IN POPUP WINDOW				 *popup-terminal*
    152 
    153 A special case is running a terminal in a popup window.  Many rules are then
    154 different:						*E863*
    155 - The popup window always has focus, it is not possible to switch to another
    156   window.
    157 - When the job ends, the popup window shows the buffer in Terminal-Normal
    158   mode.  Use `:q` to close it or use "term_finish" value "close".
    159 - The popup window can be closed with `popup_close()`, the terminal buffer
    160   then becomes hidden.
    161 - It is not possible to open a second popup window with a terminal. *E861*
    162 - The default Pmenu color is only used for the border and padding.  To change
    163   the color of the terminal itself set the Terminal highlight group before
    164   creating the terminal.  Setting 'wincolor' later can work but requires the
    165   program in the terminal to redraw everything.
    166 - The default minimal size is 5 lines of 20 characters; Use the "minwidth" and
    167   "minheight" parameters to set a different value.
    168 - The terminal size will grow if the program running in the terminal writes
    169   text.  Set "maxheight" and "maxwidth" to restrict the size.
    170 
    171 To run a terminal in a popup window, first create the terminal hidden.  Then
    172 pass the buffer number to popup_create().  Example: >
    173 	hi link Terminal Search
    174 	let buf = term_start(['picker', 'Something'], #{hidden: 1, term_finish: 'close'})
    175 	let winid = popup_create(buf, #{minwidth: 50, minheight: 20})
    176 
    177 ==============================================================================
    178 2. Functions						*popup-functions*
    179 
    180 Creating a popup window:
    181 	|popup_create()|	centered in the screen
    182 	|popup_atcursor()|	just above the cursor position, closes when
    183 				the cursor moves away
    184 	|popup_beval()|		at the position indicated by v:beval_
    185 				variables, closes when the mouse moves away
    186 	|popup_notification()|	show a notification for three seconds
    187 	|popup_dialog()|	centered with padding and border
    188 	|popup_menu()|		prompt for selecting an item from a list
    189 
    190 Manipulating a popup window:
    191 	|popup_hide()|		hide a popup temporarily
    192 	|popup_show()|		show a previously hidden popup
    193 	|popup_move()|		change the position and size of a popup
    194 	|popup_setoptions()|	override options of a popup
    195 	|popup_settext()|	replace the popup buffer contents
    196 	|popup_setbuf()|	set the buffer for the popup window
    197 
    198 Closing popup windows:
    199 	|popup_close()|		close one popup
    200 	|popup_clear()|		close all popups
    201 
    202 Filter functions:
    203 	|popup_filter_menu()|	select from a list of items
    204 	|popup_filter_yesno()|	blocks until 'y' or 'n' is pressed
    205 
    206 Other:
    207 	|popup_getoptions()|	get current options for a popup
    208 	|popup_getpos()|	get actual position and size of a popup
    209 	|popup_locate()|	find popup window at a screen position
    210 	|popup_list()|		get list of all popups
    211 
    212 
    213 DETAILS						*popup-function-details*
    214 
    215 popup_atcursor({what}, {options})			*popup_atcursor()*
    216 		Show the {what} above the cursor, and close it when the cursor
    217 		moves.  This works like: >
    218 			call popup_create({what}, #{
    219 				\ pos: 'botleft',
    220 				\ line: 'cursor-1',
    221 				\ col: 'cursor',
    222 				\ moved: 'WORD',
    223 				\ })
    224 <		Use {options} to change the properties.
    225 		If "pos" is passed as "topleft" then the default for "line"
    226 		becomes "cursor+1".
    227 
    228 		Can also be used as a |method|: >
    229 			GetText()->popup_atcursor({})
    230 <
    231 		Return type: |Number|
    232 
    233 
    234 popup_beval({what}, {options})			*popup_beval()*
    235 		Show the {what} above the position from 'ballooneval' and
    236 		close it when the mouse moves.  This works like: >
    237 		  let pos = screenpos(v:beval_winnr, v:beval_lnum, v:beval_col)
    238 		  call popup_create({what}, #{
    239 			\ pos: 'botleft',
    240 			\ line: pos.row - 1,
    241 			\ col: pos.col,
    242 			\ mousemoved: 'WORD',
    243 			\ })
    244 <		Use {options} to change the properties.
    245 		See |popup_beval_example| for an example.
    246 
    247 		Can also be used as a |method|: >
    248 			GetText()->popup_beval({})
    249 <
    250 		Return type: |Number|
    251 
    252 							*popup_clear()*
    253 popup_clear([{force}])
    254 		Emergency solution to a misbehaving plugin: close all popup
    255 		windows for the current tab and global popups.
    256 		Close callbacks are not invoked.
    257 		When {force} is not present this will fail if the current
    258 		window is a popup.
    259 		When {force} is present and |TRUE| the popup is also closed
    260 		when it is the current window.  If a terminal is running in a
    261 		popup it is killed.
    262 
    263 		Return type: void
    264 
    265 
    266 popup_close({id} [, {result}])				*popup_close()*
    267 		Close popup {id}.  The window will be deleted.  The associated
    268 		buffer will be deleted, if the popup created a new buffer.
    269 
    270 		If the popup has a callback it will be called just before the
    271 		popup window is deleted.  If the optional {result} is present
    272 		it will be passed as the second argument of the callback.
    273 		Otherwise zero is passed to the callback.
    274 
    275 		Can also be used as a |method|: >
    276 			GetPopup()->popup_close()
    277 <
    278 		Return type: void
    279 
    280 
    281 popup_create({what}, {options})				*popup_create()*
    282 		Open a popup window showing {what}, which is either: *E450*
    283 		- a buffer number
    284 		- a string
    285 		- a list of strings
    286 		- a list of text lines with text properties
    287 		When {what} is not a buffer number, a buffer is created with
    288 		'buftype' set to "popup".  That buffer will be wiped out once
    289 		the popup closes.
    290 
    291 		if {what} is a buffer number and loading the buffer runs into
    292 		an existing swap file, it is silently opened read-only, as if
    293 		a |SwapExists| autocommand had set |v:swapchoice| to 'o'.
    294 		This is because we assume the buffer is only used for viewing.
    295 		The buffer number cannot refer to a closing buffer.	*E1551*
    296 
    297 		{options} is a dictionary with many possible entries.
    298 		See |popup_create-arguments| for details.
    299 
    300 		Returns a window-ID, which can be used with other popup
    301 		functions.  Use `winbufnr()` to get the number of the buffer
    302 		in the window: >
    303 			let winid = popup_create('hello', {})
    304 			let bufnr = winbufnr(winid)
    305 			call setbufline(bufnr, 2, 'second line')
    306 <		In case of failure zero is returned.
    307 
    308 		Can also be used as a |method|: >
    309 			GetText()->popup_create({})
    310 <
    311 		Return type: |Number|
    312 
    313 
    314 popup_dialog({what}, {options})				*popup_dialog()*
    315 		Just like |popup_create()| but with these default options: >
    316 			call popup_create({what}, #{
    317 				\ pos: 'center',
    318 				\ zindex: 200,
    319 				\ drag: 1,
    320 				\ border: [],
    321 				\ padding: [],
    322 				\ mapping: 0,
    323 				\})
    324 <		Use {options} to change the properties.  E.g. add a 'filter'
    325 		option with value 'popup_filter_yesno'.  Example: >
    326 			call popup_create('do you want to quit (Yes/no)?', #{
    327 				\ filter: 'popup_filter_yesno',
    328 				\ callback: 'QuitCallback',
    329 				\ })
    330 
    331 <		By default the dialog can be dragged, so that text below it
    332 		can be read if needed.
    333 
    334 		Can also be used as a |method|: >
    335 			GetText()->popup_dialog({})
    336 <
    337 		Return type: |Number|
    338 
    339 
    340 popup_filter_menu({id}, {key})				*popup_filter_menu()*
    341 		Filter that can be used for a popup.  These keys can be used:
    342 		    j <Down> <C-N>	select item below
    343 		    k <Up> <C-P>	select item above
    344 		    <Space> <Enter>	accept current selection
    345 		    x Esc CTRL-C	cancel the menu
    346 		Other keys are ignored.
    347 		Always returns |v:true|.
    348 
    349 		A match is set on that line to highlight it, see
    350 		|popup_menu()|.
    351 
    352 		When the current selection is accepted the "callback" of the
    353 		popup menu is invoked with the index of the selected line as
    354 		the second argument.  The first entry has index one.
    355 		Cancelling the menu invokes the callback with -1.
    356 
    357 		To add shortcut keys, see the example here:
    358 		|popup_menu-shortcut-example|
    359 
    360 		Return type: |vim9-boolean|
    361 
    362 
    363 popup_filter_yesno({id}, {key})				*popup_filter_yesno()*
    364 		Filter that can be used for a popup.  It handles only the keys
    365 		'y', 'Y' and 'n' or 'N'.  Invokes the "callback" of the
    366 		popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N'
    367 		as the second argument.  Pressing Esc and 'x' works like
    368 		pressing 'n'.  CTRL-C invokes the callback with -1.  Other
    369 		keys are ignored.
    370 		See the example here: |popup_dialog-example|
    371 
    372 		Return type: |vim9-boolean|
    373 
    374 
    375 popup_findecho()					*popup_findecho()*
    376 		Get the |window-ID| for the popup that shows messages for the
    377 		`:echowindow` command.  Return zero if there is none.
    378 		Mainly useful to hide the popup.
    379 
    380 		Return type: |Number|
    381 
    382 
    383 popup_findinfo()					*popup_findinfo()*
    384 		Get the |window-ID| for the popup info window, as it used by
    385 		the popup menu.  See |complete-popup|.  The info popup is
    386 		hidden when not used, it can be deleted with |popup_clear()|
    387 		and |popup_close()|.  Use |popup_show()| to reposition it to
    388 		the item in the popup menu.
    389 		Returns zero if there is none.
    390 
    391 		Return type: |Number|
    392 
    393 
    394 popup_findpreview()					*popup_findpreview()*
    395 		Get the |window-ID| for the popup preview window.
    396 		Return zero if there is none.
    397 
    398 		Return type: |Number|
    399 
    400 
    401 popup_getoptions({id})					*popup_getoptions()*
    402 		Return the {options} for popup {id} in a Dict.
    403 		A zero value means the option was not set.  For "zindex" the
    404 		default value is returned, not zero.
    405 
    406 		The "moved" entry is a list with line number, minimum and
    407 		maximum column, [0, 0, 0] when not set.
    408 
    409 		The "mousemoved" entry is a list with screen row, minimum and
    410 		maximum screen column, [0, 0, 0] when not set.
    411 
    412 		"firstline" is the property set on the popup, unlike the
    413 		"firstline" obtained with |popup_getpos()| which is the actual
    414 		buffer line at the top of the popup window.
    415 
    416 		"border" and "padding" are not included when all values are
    417 		zero.  When all values are one then an empty list is included.
    418 
    419 		"borderhighlight" is not included when all values are empty.
    420 		"scrollbarhighlight" and "thumbhighlight" are only included
    421 		when set.
    422 
    423 		"tabpage" will be -1 for a global popup, zero for a popup on
    424 		the current tabpage and a positive number for a popup on
    425 		another tabpage.
    426 
    427 		"textprop", "textpropid" and "textpropwin" are only present
    428 		when "textprop" was set.
    429 
    430 		The "image" entry is a dictionary with the same fields as
    431 		returned by |image_info()|.  Note that if the image is created
    432 		directly by the popup, the "id" field will not be present, see
    433 		|popup-image|.
    434 
    435 		If popup window {id} is not found an empty Dict is returned.
    436 
    437 		Can also be used as a |method|: >
    438 			GetPopup()->popup_getoptions()
    439 <
    440 		Return type: dict<any>
    441 
    442 
    443 popup_getpos({id})					*popup_getpos()*
    444 		Return the position and size of popup {id}.  Returns a Dict
    445 		with these entries:
    446 		    col		screen column of the popup, one-based
    447 		    line	screen line of the popup, one-based
    448 		    width	width of the whole popup in screen cells
    449 		    height	height of the whole popup in screen cells
    450 		    core_col	screen column of the text box
    451 		    core_line	screen line of the text box
    452 		    core_width	width of the text box in screen cells
    453 		    core_height	height of the text box in screen cells
    454 		    firstline	line of the buffer at top (1 unless scrolled)
    455 				(not the value of the "firstline" property)
    456 		    lastline	line of the buffer at the bottom (updated when
    457 				the popup is redrawn)
    458 		    scrollbar	non-zero if a scrollbar is displayed
    459 		    visible	one if the popup is displayed, zero if hidden
    460 		Note that these are the actual screen positions.  They differ
    461 		from the values in `popup_getoptions()` for the sizing and
    462 		positioning mechanism applied.
    463 
    464 		The "core_" values exclude the padding and border.
    465 
    466 		If popup window {id} is not found an empty Dict is returned.
    467 
    468 		Can also be used as a |method|: >
    469 			GetPopup()->popup_getpos()
    470 <
    471 		Return type: dict<number> or dict<any>
    472 
    473 
    474 popup_hide({id})						*popup_hide()*
    475 		If {id} is a displayed popup, hide it now.  If the popup has a
    476 		filter it will not be invoked for so long as the popup is
    477 		hidden.
    478 		If window {id} does not exist nothing happens.  If window {id}
    479 		exists but is not a popup window an error is given. *E993*
    480 		If popup window {id} contains a terminal an error is given.
    481 
    482 		Can also be used as a |method|: >
    483 			GetPopup()->popup_hide()
    484 <
    485 		Return type: void
    486 
    487 
    488 popup_list()						 *popup_list()*
    489 		Return a List with the |window-ID| of all existing popups.
    490 
    491 		Return type: list<number> or list<any>
    492 
    493 
    494 popup_locate({row}, {col})				 *popup_locate()*
    495 		Return the |window-ID| of the popup at screen position {row}
    496 		and {col}.  If there are multiple popups the one with the
    497 		highest zindex is returned.  If there are no popups at this
    498 		position then zero is returned.
    499 
    500 		Return type: |Number|
    501 
    502 
    503 popup_menu({what}, {options})				 *popup_menu()*
    504 		Show the {what} near the cursor, handle selecting one of the
    505 		items with cursorkeys, and close it an item is selected with
    506 		Space or Enter.  {what} should have multiple lines to make
    507 		this useful.  This works like: >
    508 			call popup_create({what}, #{
    509 				\ pos: 'center',
    510 				\ zindex: 200,
    511 				\ drag: 1,
    512 				\ wrap: 0,
    513 				\ border: [],
    514 				\ cursorline: 1,
    515 				\ padding: [0,1,0,1],
    516 				\ filter: 'popup_filter_menu',
    517 				\ mapping: 0,
    518 				\ })
    519 <		The current line is highlighted with a match using
    520 		|hl-PopupSelected| which is linked to "PmenuSel" by default.
    521 
    522 		Use {options} to change the properties.  Should at least set
    523 		"callback" to a function that handles the selected item.
    524 		Example: >
    525 			func ColorSelected(id, result)
    526 			   " use a:result
    527 			endfunc
    528 			call popup_menu(['red', 'green', 'blue'], #{
    529 				\ callback: 'ColorSelected',
    530 				\ })
    531 
    532 <		Can also be used as a |method|: >
    533 			GetChoices()->popup_menu({})
    534 <
    535 		Return type: |Number|
    536 
    537 
    538 popup_move({id}, {options})					*popup_move()*
    539 		Move popup {id} to the position specified with {options}.
    540 		{options} may contain the items from |popup_create()| that
    541 		specify the popup position:
    542 			line
    543 			col
    544 			pos
    545 			maxheight
    546 			minheight
    547 			maxwidth
    548 			minwidth
    549 			fixed
    550 		For {id} see `popup_hide()`.
    551 		For other options see |popup_setoptions()|.
    552 
    553 		Can also be used as a |method|: >
    554 			GetPopup()->popup_move(options)
    555 <
    556 		Return type: void
    557 
    558 
    559 popup_notification({what}, {options})			 *popup_notification()*
    560 		Show the {what} for 3 seconds at the top of the Vim window.
    561 		This works like: >
    562 			call popup_create({what}, #{
    563 				\ line: 1,
    564 				\ col: 10,
    565 				\ minwidth: 20,
    566 				\ time: 3000,
    567 				\ tabpage: -1,
    568 				\ zindex: 300,
    569 				\ drag: 1,
    570 				\ highlight: 'WarningMsg',
    571 				\ border: [],
    572 				\ close: 'click',
    573 				\ padding: [0,1,0,1],
    574 				\ })
    575 <		The |hl-PopupNotification| highlight group is used instead of
    576 		WarningMsg if it is defined.
    577 
    578 		Without the |+timers| feature the popup will not disappear
    579 		automatically, the user has to click in it.
    580 
    581 		The position will be adjusted to avoid overlap with other
    582 		notifications.
    583 		Use {options} to change the properties.
    584 
    585 		Can also be used as a |method|: >
    586 			GetText()->popup_notification({})
    587 <
    588 		Return type: |Number|
    589 
    590 
    591 popup_setbuf({id}, {buf})				*popup_setbuf()*
    592 		Set buffer {buf} to be displayed in popup win {id}.  For the
    593 		use of {buf}, see |bufname()| function.
    594 		May change window size or position to adjust for the size
    595 		of the buffer text.
    596 
    597 		Can also be used as a |method|: >
    598 			GetPopup()->popup_setbuf(bufnr('foobar'))
    599 <
    600 		Return type: |vim9-boolean|
    601 
    602 
    603 popup_setoptions({id}, {options})			*popup_setoptions()*
    604 		Override options in popup {id} with entries in {options}.
    605 		These options can be set:
    606 			border
    607 			borderchars
    608 			borderhighlight
    609 			callback
    610 			close
    611 			cursorline
    612 			drag
    613 			filter
    614 			firstline
    615 			flip
    616 			highlight
    617 			image
    618 			mapping
    619 			mask
    620 			moved
    621 			padding
    622 			resize
    623 			scrollbar
    624 			scrollbarhighlight
    625 			thumbhighlight
    626 			time
    627 			title
    628 			wrap
    629 			zindex
    630 		The options from |popup_move()| can also be used.
    631 		Generally, setting an option to zero or an empty string resets
    632 		it to the default value, but there are exceptions.
    633 		For "hidden" use |popup_hide()| and |popup_show()|.
    634 		"tabpage" cannot be changed.
    635 
    636 		Can also be used as a |method|: >
    637 			GetPopup()->popup_setoptions(options)
    638 <
    639 		Return type: void
    640 
    641 
    642 popup_settext({id}, {text})				*popup_settext()*
    643 		Set the text of the buffer in popup win {id}.  {text} is
    644 		a string or a list of strings to be displayed in the popup.
    645 		Does not change the window size or position, other than caused
    646 		by the different text.
    647 
    648 		Can also be used as a |method|: >
    649 			GetPopup()->popup_settext('hello')
    650 <
    651 		Return type: void
    652 
    653 
    654 popup_show({id})						*popup_show()*
    655 		Show a hidden popup window identified by {id}.
    656 		Use {id} as returned by |popup_create()|.
    657 
    658 		If the popup is currently hidden, it will be made visible.
    659 		See |popup_hide()| to hide a popup.
    660 
    661 		If {id} refers to an info popup, it will be positioned next to
    662 		the currently selected item in the popup menu.
    663 
    664 		Returns -1 if a popup window with {id} does not exist.
    665 		Returns 0 on success.
    666 
    667 		Return type: |Number|
    668 
    669 
    670 ==============================================================================
    671 3. Usage						*popup-usage*
    672 
    673 POPUP_CREATE() ARGUMENTS			 *popup_create-arguments*
    674 
    675 The first argument of |popup_create()| (and the second argument to
    676 |popup_settext()|) specifies the text to be displayed, and optionally text
    677 properties.  It is in one of four forms:  *E1284*
    678 - a buffer number
    679 - a string
    680 - a list of strings
    681 - a list of dictionaries, where each dictionary has these entries:
    682 	text		String with the text to display.
    683 	props		A list of text properties.  Optional.
    684 			Each entry is a dictionary, like the third argument of
    685 			|prop_add()|, but specifying the column in the
    686 			dictionary with a "col" entry, see below:
    687 			|popup-props|.
    688 
    689 If you want to create a new buffer yourself use |bufadd()| and pass the buffer
    690 number to popup_create().
    691 
    692 The second argument of |popup_create()| is a dictionary with options:
    693 	line		Screen line where to position the popup.  Can use a
    694 			number or "cursor", "cursor+1" or "cursor-1" to use
    695 			the line of the cursor and add or subtract a number of
    696 			lines.  If omitted or zero the popup is vertically
    697 			centered.  The first line is 1.
    698 			When using "textprop" the number is relative to the
    699 			text property and can be negative.
    700 	col		Screen column where to position the popup.  Can use a
    701 			number or "cursor" to use the column of the cursor,
    702 			"cursor+9" or "cursor-9" to add or subtract a number
    703 			of columns.  If omitted or zero the popup is
    704 			horizontally centered.  The first column is 1.
    705 			When using "textprop" the number is relative to the
    706 			text property and can be negative.
    707 	pos		"topleft", "topright", "botleft" or "botright":
    708 			defines what corner of the popup "line" and "col" are
    709 			used for.  When not set "topleft" is used.
    710 			Alternatively "center" can be used to position the
    711 			popup in the center of the Vim window, in which case
    712 			"line" and "col" are ignored.
    713 	posinvert	When FALSE the value of "pos" is always used.  When
    714 			TRUE (the default) and the popup does not fit
    715 			vertically and there is more space on the other side
    716 			then the popup is placed on the other side of the
    717 			position indicated by "line".
    718 	textprop	When present the popup is positioned next to a text
    719 			property with this name and will move when the text
    720 			property moves.  Use an empty string to remove.  See
    721 			|popup-textprop-pos|.
    722 	textpropwin	What window to search for the text property.  When
    723 			omitted or invalid the current window is used.  Used
    724 			when "textprop" is present.
    725 	textpropid	Used to identify the text property when "textprop" is
    726 			present.  Use zero to reset.
    727 	clipwindow	Only used when "textprop" is set.  When TRUE the popup
    728 			is kept within the window containing the text
    729 			property: if the text property scrolls past that
    730 			window's top, bottom, left or right edge, the popup
    731 			is clipped at that edge instead of being drawn
    732 			outside it.  Once the text property has scrolled out
    733 			of the window the popup is hidden.
    734 			Default FALSE.
    735 			See |popup-clipwindow|.
    736 	fixed		When FALSE (the default), and:
    737 			 - "pos" is "botleft" or "topleft", and
    738 			 - the popup would be truncated at the right edge of
    739 			   the screen, then
    740 			the popup is moved to the left so as to fit the
    741 			contents on the screen.  Set to TRUE to disable this.
    742 	flip		When TRUE (the default) and the position is relative
    743 			to the cursor, flip to below or above the cursor to
    744 			avoid overlap with the |popupmenu-completion| or
    745 			another popup with a higher "zindex".  When there is
    746 			no space above/below the cursor then show the popup to
    747 			the side of the popup or popup menu.
    748 			{not implemented yet}
    749 	maxheight	Maximum height of the contents, excluding border and
    750 			padding.
    751 	minheight	Minimum height of the contents, excluding border and
    752 			padding.
    753 	maxwidth	Maximum width of the contents, excluding border,
    754 			padding and scrollbar.
    755 	minwidth	Minimum width of the contents, excluding border,
    756 			padding and scrollbar.
    757 	firstline	First buffer line to display.  When larger than one it
    758 			looks like the text scrolled up.  When out of range
    759 			the last buffer line will at the top of the window.
    760 			Set to zero to leave the position as set by commands.
    761 			Also see "scrollbar".
    762 	hidden		When TRUE the popup exists but is not displayed; use
    763 			`popup_show()` to unhide it.
    764 	tabpage		When -1: display the popup on all tab pages.
    765 			When 0 (the default): display the popup on the current
    766 			tab page.
    767 			Otherwise the number of the tab page the popup is
    768 			displayed on; when invalid the popup is not created
    769 			and an error is given. *E997*
    770 	title		Text to be displayed above the first item in the
    771 			popup, on top of any border.  If there is no top
    772 			border one line of padding is added to put the title
    773 			on.  You might want to add one or more spaces at the
    774 			start and end as padding.
    775 			The title uses |hl-PopupTitle| by default; if
    776 			"borderhighlight" is set the top border highlight is
    777 			used instead, and if "highlight"/'wincolor' is set
    778 			that is used.
    779 	wrap		TRUE to make the lines wrap (default TRUE).
    780 	drag		TRUE to allow the popup to be dragged with the mouse
    781 			by grabbing at the border.  Has no effect if the
    782 			popup does not have a border.  As soon as dragging
    783 			starts and "pos" is "center" it is changed to
    784 			"topleft".
    785 	dragall		TRUE to allow the popup to be dragged from every
    786 			position.  Makes it very difficult to select text in
    787 			the popup.
    788 	resize		TRUE to allow the popup to be resized with the mouse
    789 			by grabbing at the bottom right corner.  Has no effect
    790 			if the popup does not have a border.
    791 	close		When "button" an X is displayed in the top-right, on
    792 			top of any border, padding or text.  When clicked on
    793 			the X the popup will close.  Any callback is invoked
    794 			with the value -2.
    795 			When "click" any mouse click in the popup will close
    796 			it.
    797 			When "none" (the default) mouse clicks do not close
    798 			the popup window.
    799 	highlight	Highlight group name to use for the text, stored in
    800 			the 'wincolor' option.
    801 	highlights	Highlight group overrides, stored in the
    802 			'winhighlight' option (same format).
    803 	opacity		Opacity of the popup, a value between 0 and 100:
    804 			0 is fully transparent (background text fully visible)
    805 			100 is fully opaque (default, no transparency)
    806 			Values in between blend the popup background with the
    807 			underlying text, making it partially transparent.
    808 			Requires 'termguicolors' to be set.
    809 			Also see |popup-opacity|.
    810 	image		Dictionary for displaying an image.  See |image_add()|
    811 			for required fields, or you can provide the "id" field
    812 			only, see |popup-image|.
    813 	padding		List with numbers, defining the padding
    814 			above/right/below/left of the popup (similar to CSS).
    815 			An empty list uses a padding of 1 all around.  The
    816 			padding goes around the text, inside any border.
    817 			Padding uses the 'wincolor' highlight.
    818 			Example: [1, 2, 1, 3] has 1 line of padding above, 2
    819 			columns on the right, 1 line below and 3 columns on
    820 			the left.
    821 	border		List with numbers, defining the border thickness
    822 			above/right/below/left of the popup (similar to CSS).
    823 			Only values of zero and non-zero are currently
    824 			recognized.  An empty list uses a border all around.
    825 	borderhighlight	List of highlight group names to use for the border.
    826 			When one entry it is used for all borders, otherwise
    827 			the highlight for the top/right/bottom/left border.
    828 			Example: ['TopColor', 'RightColor', 'BottomColor,
    829 			'LeftColor']
    830 			When not given and "highlight"/'wincolor' is also not
    831 			set, |hl-PopupBorder| is used.
    832 	borderchars	List with characters, defining the character to use
    833 			for the top/right/bottom/left border.  Optionally
    834 			followed by the character to use for the
    835 			topleft/topright/botright/botleft corner.
    836 			Example: ['-', '|', '-', '|', '┌', '┐', '┘', '└']
    837 			When the list has one character it is used for all.
    838 			When the list has two characters the first is used for
    839 			the border lines, the second for the corners.
    840 			By default a double line is used all around when
    841 			'encoding' is "utf-8" and 'ambiwidth' is "single",
    842 			otherwise ASCII characters are used.
    843 	scrollbar	1 or true: show a scrollbar when the text doesn't fit.
    844 			zero: do not show a scrollbar.  Default is non-zero.
    845 			Also see |popup-scrollbar|.
    846 	scrollbarhighlight  Highlight group name for the scrollbar.  The
    847 			background color is what matters.  When not given then
    848 			PmenuSbar is used.
    849 	thumbhighlight  Highlight group name for the scrollbar thumb.  The
    850 			background color is what matters.  When not given then
    851 			PmenuThumb is used.
    852 	zindex		Priority for the popup, default 50.  Minimum value is
    853 			1, maximum value is 32000.
    854 	mask		A list of lists with coordinates, defining parts of
    855 			the popup that are transparent.  See |popup-mask|.
    856 	time		Time in milliseconds after which the popup will close.
    857 			When omitted |popup_close()| must be used.
    858 	moved		Specifies to close the popup if the cursor moved:
    859 			- "any": if the cursor moved at all
    860 			- "word": if the cursor moved outside |<cword>|
    861 			- "WORD": if the cursor moved outside |<cWORD>|
    862 			- "expr": if the cursor moved outside |<cexpr>|
    863 			- [{start}, {end}]: if the cursor moved before column
    864 			  {start} or after {end}
    865 			- [{lnum}, {start}, {end}]: if the cursor moved away
    866 			  from line {lnum}, before column {start} or after
    867 			  {end}
    868 			- [0, 0, 0] do not close the popup when the cursor
    869 			  moves
    870 			The popup also closes if the cursor moves to another
    871 			line or to another window.
    872 	mousemoved	Like "moved" but referring to the mouse pointer
    873 			position
    874 	cursorline	TRUE:	 Highlight the cursor line.  Also scrolls the
    875 				 text to show this line (only works properly
    876 				 when 'wrap' is off).
    877 			zero:	 Do not highlight the cursor line.
    878 			Default is zero, except for |popup_menu()|.
    879 	filter		A callback that can filter typed characters, see
    880 			|popup-filter|.
    881 	mapping		Allow for key mapping.  When FALSE and the popup is
    882 			visible and has a filter callback key mapping is
    883 			disabled.  Default value is TRUE.
    884 	filtermode	In which modes the filter is used (same flags as with
    885 			|hasmapto()| plus "a"):
    886 				n	Normal mode
    887 				v	Visual and Select mode
    888 				x	Visual mode
    889 				s	Select mode
    890 				o	Operator-pending mode
    891 				i	Insert mode
    892 				l	Language-Argument ("r", "f", "t", etc.)
    893 				c	Command-line mode
    894 				a	all modes
    895 			The default value is "a".
    896 	callback	A callback that is called when the popup closes, e.g.
    897 			when using |popup_filter_menu()|, see |popup-callback|.
    898 
    899 Depending on the "zindex" the popup goes under or above other popups.  The
    900 completion menu (|popup-menu|) has zindex 100.  For messages that occur for a
    901 short time the suggestion is to use zindex 1000.
    902 
    903 By default text wraps, which causes a line in {lines} to occupy more than one
    904 screen line.  When "wrap" is FALSE then the text outside of the popup or
    905 outside of the Vim window will not be displayed, thus truncated.
    906 
    907 
    908 POPUP TEXT PROPERTIES					*popup-props*
    909 
    910 These are similar to the third argument of |prop_add()| except:
    911 - "lnum" is always the current line in the list
    912 - "bufnr" is always the buffer of the popup
    913 - "col" is in the Dict instead of a separate argument
    914 So we get:
    915 	col		starting column, counted in bytes, use one for the
    916 			first column.
    917 	length		length of text in bytes; can be zero
    918 	end_lnum	line number for the end of the text
    919 	end_col		column just after the text; not used when "length" is
    920 			present; when {col} and "end_col" are equal, this is a
    921 			zero-width text property
    922 	id		user defined ID for the property; when omitted zero is
    923 			used
    924 	type		name of the text property type, as added with
    925 			|prop_type_add()|
    926 
    927 
    928 POSITION POPUP WITH TEXTPROP				*popup-textprop-pos*
    929 
    930 Positioning a popup next to a text property causes the popup to move when text
    931 is inserted or deleted.  The popup functions like a tooltip.
    932 
    933 These steps are needed to make this work:
    934 
    935 - Define a text property type, it defines the name. >
    936 	call prop_type_add('popupMarker', {})
    937 
    938 - Place a text property at the desired text: >
    939 	let lnum = {line of the text}
    940 	let col = {start column of the text}
    941 	let len = {length of the text}
    942 	let propId = {arbitrary but unique number}
    943 	call prop_add(lnum, col, #{
    944 		\ length: len,
    945 		\ type: 'popupMarker',
    946 		\ id: propId,
    947 		\ })
    948 
    949 - Create a popup: >
    950 	let winid = popup_create('the text', #{
    951 		\ pos: 'botleft',
    952 		\ textprop: 'popupMarker',
    953 		\ textpropid: propId,
    954 		\ border: [],
    955 		\ padding: [0,1,0,1],
    956 		\ close: 'click',
    957 		\ })
    958 
    959 By default the popup is positioned at the corner of the text, opposite of the
    960 "pos" specified for the popup.  Thus when the popup uses "botleft", the
    961 bottom-left corner of the popup is positioned next to the top-right corner of
    962 the text property:
    963 			  +----------+
    964 			  | the text |
    965 			  +----------+
    966 	just some PROPERTY as an example
    967 
    968 Here the text property is on "PROPERTY".  Move the popup to the left by
    969 passing a negative "col" value to popup_create().  With "col: -5" you get:
    970 
    971 		     +----------+
    972 		     | the text |
    973 		     +----------+
    974 	just some PROPERTY as an example
    975 
    976 If the text property moves out of view then the popup will be hidden.
    977 If the window for which the popup was defined is closed, the popup is closed.
    978 
    979 If the popup cannot fit in the desired position, it may show at a nearby
    980 position.
    981 
    982 
    983 CLIP TEXTPROP POPUP TO HOST WINDOW			*popup-clipwindow*
    984 
    985 When the popup is anchored to a text property in a split window, the popup is
    986 by default drawn relative to the whole screen and may extend past the edges of
    987 the window that contains the text property (the "host window").  Setting
    988 "clipwindow" to TRUE keeps the popup within window's content area:
    989 parts of the popup that fall outside the window are clipped, and the popup is
    990 hidden once the text property has scrolled entirely past one of the edges.
    991 
    992 Example: a tall popup anchored above the cursor that should never spill into
    993 the window below the split: >
    994 	call popup_create(body, #{
    995 		\ textprop: 'marker',
    996 		\ textpropid: id,
    997 		\ pos: 'topleft',
    998 		\ line: -1, col: 0,
    999 		\ posinvert: v:false,
   1000 		\ clipwindow: v:true,
   1001 		\ })
   1002 <
   1003 With "posinvert" left at its default (TRUE) the popup may be flipped to the
   1004 opposite side of the text property when there is no room; set it to FALSE to
   1005 keep the requested side and rely on "clipwindow" to clip the overflow.
   1006 
   1007 Some hints:
   1008 - To avoid collision with other plugins the text property type name has to be
   1009   unique.  You can also use the "bufnr" item to make it local to a buffer.
   1010 - You can leave out the text property ID if there is only ever one text
   1011   property visible.
   1012 - The popup may be in the way of what the user is doing, making it close with
   1013   a click, as in the example above, helps for that.
   1014 - If the text property is removed the popup is closed.  Use something like
   1015   this: >
   1016 	call prop_remove(#{type: 'popupMarker', id: propId})
   1017 
   1018 
   1019 POPUP FILTER						*popup-filter*
   1020 
   1021 A callback that gets any typed keys while a popup is displayed.  The filter is
   1022 not invoked when the popup is hidden.
   1023 
   1024 The filter can return TRUE to indicate the key has been handled and is to be
   1025 discarded, or FALSE to let Vim handle the key as usual in the current state.
   1026 In case it returns FALSE and there is another popup window visible, that
   1027 filter is also called.  The filter of the popup window with the highest zindex
   1028 is called first.
   1029 
   1030 The filter function is called with two arguments: the ID of the popup and the
   1031 key as a string, e.g.: >
   1032 	func MyFilter(winid, key)
   1033 	  if a:key == "\<F2>"
   1034 	    " do something
   1035 	    return 1
   1036 	  endif
   1037 	  if a:key == 'x'
   1038 	    call popup_close(a:winid)
   1039 	    return 1
   1040 	  endif
   1041 	  return 0
   1042 	endfunc
   1043 <							*popup-filter-mode*
   1044 The "filtermode" property can be used to specify in what mode the filter is
   1045 invoked.  The default is "a": all modes.  When using "nvi" Command-line mode
   1046 is not included, so that any command typed on the command line is not
   1047 filtered.  However, to get to Command-line mode the filter must not consume
   1048 ":".  Just like it must not consume "v" to allow for entering Visual mode.
   1049 
   1050 							*popup-mapping*
   1051 Normally the key is what results after any mapping, since the keys pass on as
   1052 normal input if the filter does not use it.  If the filter consumes all the
   1053 keys, set the "mapping" property to zero so that mappings do not get in the
   1054 way.  This is default for |popup_menu()| and |popup_dialog()|.
   1055 
   1056 Some recommended key actions:
   1057 	x		close the popup (see note below)
   1058 	cursor keys	select another entry
   1059 	Tab		accept current suggestion
   1060 
   1061 When CTRL-C is pressed the popup is closed, the filter will not be invoked.
   1062 
   1063 A mouse click arrives as <LeftMouse>.  The coordinates can be obtained with
   1064 |getmousepos()|.
   1065 
   1066 Vim provides standard filters |popup_filter_menu()| and
   1067 |popup_filter_yesno()|.
   1068 
   1069 Keys coming from a `:normal` command do not pass through the filter.  This can
   1070 be used to move the cursor in a popup where the "cursorline" option is set: >
   1071 	call win_execute(winid, 'normal! 10Gzz')
   1072 Keys coming from `feedkeys()` are passed through the filter.
   1073 
   1074 Note that "x" is the normal way to close a popup.  You may want to use Esc,
   1075 but since many keys start with an Esc character, there may be a delay before
   1076 Vim recognizes the Esc key.  If you do use Esc, it is recommended to set the
   1077 'ttimeoutlen' option to 100 and set 'timeout' and/or 'ttimeout'.
   1078 
   1079 							*popup-filter-errors*
   1080 If the filter function can't be called, e.g. because the name is wrong, then
   1081 the popup is closed.  If the filter causes an error then it is assumed to
   1082 return zero.  If this happens three times in a row the popup is closed.  If
   1083 the popup gives errors fewer than 10% of the calls then it won't be closed.
   1084 
   1085 
   1086 POPUP CALLBACK						*popup-callback*
   1087 
   1088 A callback that is invoked when the popup closes.
   1089 
   1090 The callback is invoked with two arguments: the ID of the popup window and the
   1091 result, which could be an index in the popup lines, or whatever was passed as
   1092 the second argument of `popup_close()`.
   1093 
   1094 If the popup is force-closed, e.g. because the cursor moved or CTRL-C was
   1095 pressed, the number -1 is passed to the callback.
   1096 
   1097 Example: >
   1098 	func SelectedColor(id, result)
   1099 	   echo 'choice made: ' .. a:result
   1100 	endfunc
   1101 
   1102 
   1103 POPUP SCROLLBAR						*popup-scrollbar*
   1104 
   1105 If the text does not fit in the popup a scrollbar is displayed on the right of
   1106 the window.  This can be disabled by setting the "scrollbar" option to zero.
   1107 When the scrollbar is displayed mouse scroll events, while the mouse pointer
   1108 is on the popup, will cause the text to scroll up or down as you would expect.
   1109 A click in the upper half of the scrollbar will scroll the text down one line.
   1110 A click in the lower half will scroll the text up one line.  However, this is
   1111 limited so that the popup does not get smaller.
   1112 
   1113 
   1114 
   1115 POPUP OPACITY						*popup-opacity*
   1116 
   1117 A popup window can be made semi-transparent by setting the "opacity" option.
   1118 The opacity value ranges from 0 to 100:
   1119     0		Fully transparent - the popup background is invisible and the
   1120 		text behind the popup is fully visible.
   1121     100		Fully opaque (default) - the popup is not transparent at all.
   1122     1-99	Partially transparent - the popup background is blended with
   1123 		the underlying text, making both partially visible.
   1124 
   1125 The transparency effect requires using the GUI, having 'termguicolors'
   1126 enabled, or running in a 256-color terminal.  On terminals with fewer
   1127 than 256 colors the opacity setting has no effect.
   1128 
   1129 When a popup is transparent:
   1130 - The popup's background color is blended with the background text
   1131 - The popup's text (foreground) remains fully visible and unblended
   1132 - Text behind the popup is visible through transparent areas
   1133 - The more transparent the popup (lower opacity), the more clearly the
   1134   background text can be seen
   1135 
   1136 This can be useful for:
   1137 - Creating overlay windows that don't completely obscure underlying text
   1138 - Showing contextual information without blocking the view
   1139 - Creating visual effects and modern UI designs
   1140 
   1141 Example with 50% opacity: >
   1142 	let winid = popup_create('Semi-transparent text', #{
   1143 	\ line: 5,
   1144 	\ col: 10,
   1145 	\ opacity: 50,
   1146 	\ })
   1147 
   1148 The opacity can be changed dynamically using |popup_setoptions()|: >
   1149 	call popup_setoptions(winid, #{opacity: 80})
   1150 
   1151 POPUP MASK						*popup-mask*
   1152 
   1153 To minimize the text that the popup covers, parts of it can be made
   1154 transparent.  This is defined by a "mask" which is a list of lists, where each
   1155 list has four numbers:
   1156     col		start column, positive for counting from the left, 1 for
   1157 		leftmost, negative for counting from the right, -1 for
   1158 		rightmost
   1159     endcol	last column, like "col"
   1160     line	start line, positive for counting from the top, 1 for top,
   1161 		negative for counting from the bottom, -1 for bottom
   1162     endline	end line, like "line"
   1163 
   1164 For example, to make the last 10 columns of the last line transparent:
   1165 	[[-10, -1, -1, -1]]
   1166 
   1167 To make the four corners transparent:
   1168 	[[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]
   1169 
   1170 POPUP IMAGE						*image* *popup-image*
   1171 
   1172 Vim is capable of displaying graphical images, in both the terminal and GUI.
   1173 To do this, it must link with the pixman library, which you may install via
   1174 your package manager on Unix, or via vcpkg on MS-Windows.  You may see if
   1175 images are supported by checking |+image| and |+image_popup|.
   1176 
   1177 A popup window may additionally render an image.  To do this, pass a field
   1178 named "image" containing a dictionary to |popup_create()| or
   1179 |popup_setoptions()|.  The dictionary may either have the same fields as in
   1180 |image_add()|, or it may reference an image via its ID using the "id" field.
   1181 The "id" field is prioritized first, see |image_add()|, |image_discard()|, and
   1182 |image_info()|.
   1183 
   1184 When an image is directly created by a popup window (e.g. "id" is not used),
   1185 then it is considered internal and can not be referenced anywhere else.
   1186 
   1187 To unset a previously set image from a popup window pass an empty dictionary: >
   1188 	call popup_setoptions(winid, #{image: {}})
   1189 <
   1190 							*image-backends*
   1191 There are two terminal image protocols supported on all platforms.  The
   1192 protocol to use is chosen using the 'imageprotocol' option:
   1193 
   1194     sixel   Uses the sixel protocol to display images.
   1195     kitty   Uses the kitty graphics protocol.  This is the recommended
   1196 	    protocol to use in the terminal if it is available, as it is much
   1197 	    more performant than sixel.
   1198 
   1199 When using the GUI, the GTK4, GTK3, and Win32 versions of Vim are supported.
   1200 
   1201 To see what image backend is currently being used, use the |v:imagebackend|
   1202 variable.
   1203 
   1204 							*image-options*
   1205 When passing an RGBA buffer, Vim expects it to be endian independent and non
   1206 alpha pre-multiplied.  For RGB images, each pixel should be exactly 3 bytes,
   1207 a padding byte is not supported by Vim.
   1208 
   1209 The dimensions of a popup containing an image are automatically calculated
   1210 based on the image dimensions and terminal/GUI cell size.  However, you may
   1211 override it using the "minwidth", "minheight", "maxwidth", and "maxheight"
   1212 fields.
   1213 
   1214 Images are not scaled, if a popup window is smaller than the image it
   1215 contains, then the image will be cropped instead.
   1216 
   1217 							*image-animation*
   1218 The image of a popup window can be changed at runtime using
   1219 |popup_setoptions()|.  When the new image has the same format, width, and
   1220 height as the existing image, the existing image will be modified in place.
   1221 This is performant enough for frame-by-frame animation, using a |timer|.
   1222 
   1223 For RGBA buffers that need to blend cleanly into the editor's actual backdrop,
   1224 the script can call |getbgcolor()| to obtain the current background colour as
   1225 [r, g, b] and pre-composite anti-aliased edges against it.
   1226 
   1227 Minimal RGB example - a 4x4 red square popped at the cursor: >
   1228 	let pixels = repeat([0xff, 0x00, 0x00], 4 * 4)->list2blob()
   1229 	call popup_create('', #{
   1230 	      \ image: #{ data: pixels, width: 4, height: 4 },
   1231 	      \ line: 'cursor+1', col: 'cursor',
   1232 	      \ })
   1233 
   1234 Real-world example - pipe a PNG through GraphicsMagick and pop the resulting
   1235 raw RGB bytes: >
   1236 	let png = 'cat.png'
   1237 	let dim = split(system('gm identify -format "%w %h" '
   1238 		\ .. shellescape(png)))
   1239 	let [w, h] = [str2nr(dim[0]), str2nr(dim[1])]
   1240 	call system('gm convert ' .. shellescape(png)
   1241 		\ .. ' -depth 8 rgb:/tmp/cat.rgb')
   1242 	let blob = readblob('/tmp/cat.rgb')
   1243 	call popup_create('', #{
   1244 	      \ image: #{ data: blob, width: w, height: h },
   1245 	      \ line: 1, col: 1, border: [], padding: [0, 0, 0, 0],
   1246 	      \ })
   1247 
   1248 ==============================================================================
   1249 4. Examples						*popup-examples*
   1250 
   1251 These examples use |Vim9| script.
   1252 
   1253 					*popup_dialog-example*
   1254 Prompt the user to press y/Y or n/N: >
   1255 
   1256 	popup_dialog('Continue? y/n', {
   1257 		 filter: 'popup_filter_yesno',
   1258 		 callback: (id, result) => {
   1259 				if result == 1
   1260 				  echomsg "'y' or 'Y' was pressed"
   1261 				else
   1262 				  echomsg "'y' or 'Y' was NOT pressed"
   1263 				endif
   1264 			     },
   1265 		 padding: [2, 4, 2, 4],
   1266 		 })
   1267 <
   1268 					*popup_menu-shortcut-example*
   1269 Extend popup_filter_menu() with shortcut keys: >
   1270 
   1271 	popup_menu(['Save', 'Cancel', 'Discard'], {
   1272 	    callback: (_, result) => {
   1273 		echo 'dialog result is' result
   1274 	    },
   1275 	    filter: (id, key) => {
   1276 		# Handle shortcuts
   1277 		if key == 'S' || key == 's'
   1278 		    popup_close(id, 1)
   1279 		elseif key == 'C' || key == 'c'
   1280 		    popup_close(id, 2)
   1281 		elseif key == 'D' || key == 'd'
   1282 		    popup_close(id, 3)
   1283 		else
   1284 		    # No shortcut, pass to generic filter
   1285 		    return popup_filter_menu(id, key)
   1286 		endif
   1287 		return true
   1288 	    },
   1289 	})
   1290 <
   1291 					*popup_beval_example*
   1292 Example for using a popup window for 'ballooneval': >
   1293 
   1294 	set ballooneval balloonevalterm
   1295 	set balloonexpr=BalloonExpr()
   1296 	var winid: number
   1297 	var last_text: string
   1298 
   1299 	def BalloonExpr(): string
   1300 	    # here you would use "v:beval_text" to lookup something interesting
   1301 	    var text = v:beval_text
   1302 	    if winid > 0 && popup_getpos(winid) != null_dict
   1303 		# previous popup window still shows
   1304 		if text == last_text
   1305 		    # still the same text, keep the existing popup
   1306 		    return null_string
   1307 		endif
   1308 		popup_close(winid)
   1309 	    endif
   1310 
   1311 	    winid = popup_beval(text, {})
   1312 	    last_text = text
   1313 	    return null_string
   1314 	enddef
   1315 
   1316 If the text has to be obtained asynchronously return an empty string from the
   1317 expression function and call popup_beval() once the text is available.  In
   1318 this example simulated with a timer callback: >
   1319 
   1320 	set ballooneval balloonevalterm
   1321 	set balloonexpr=BalloonExpr()
   1322 	var winid: number
   1323 	var last_text: string
   1324 
   1325 	def BalloonExpr(): string
   1326 	    var text = v:beval_text
   1327 	    if winid > 0 && popup_getpos(winid) != null_dict
   1328 		# previous popup window still shows
   1329 		if text == last_text
   1330 		    # still the same text, keep the existing popup
   1331 		    return null_string
   1332 		endif
   1333 		popup_close(winid)
   1334 	    endif
   1335 
   1336 	    # Simulate an asynchronous lookup that takes half a second for the
   1337 	    # text to display.
   1338 	    last_text = text
   1339 	    timer_start(500, 'ShowPopup')
   1340 	    return null_string
   1341 	enddef
   1342 
   1343 	def ShowPopup(timerid: number)
   1344 	    winid = popup_beval('Result: ' .. last_text, {})
   1345 	enddef
   1346 <
   1347 
   1348  vim:tw=78:ts=8:noet:ft=help:norl: