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: