1*popup.txt* For Vim version 8.2. Last change: 2021 Aug 15 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Displaying text in a floating window. *popup* *popup-window* *popupwin* 8 9 101. 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| 152. Functions |popup-functions| 16 Details |popup-function-details| 173. 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 mask |popup-mask| 254. Examples |popup-examples| 26 27 28{not available if the |+popupwin| feature was disabled at compile time} 29 30============================================================================== 311. Introduction *popup-intro* 32 33We are talking about popup windows here, text that goes on top of the regular 34windows and is under control of a plugin. You cannot edit the text in the 35popup window like with regular windows. 36 37A popup window can be used for such things as: 38- briefly show a message without overwriting the command line 39- prompt the user with a dialog 40- display contextual information while typing 41- give extra information for auto-completion 42 43The text in the popup window can be colored with |text-properties|. It is 44also possible to use syntax highlighting. 45 46The default color used is "Pmenu". If you prefer something else use the 47"highlight" argument or the 'wincolor' option, e.g.: > 48 hi MyPopupColor ctermbg=lightblue guibg=lightblue 49 call setwinvar(winid, '&wincolor', 'MyPopupColor') 50 51'hlsearch' highlighting is not displayed in a popup window. 52 53A popup window has a window-ID like other windows, but behaves differently. 54The size can be up to the whole Vim window and it overlaps other windows. 55Popup windows can also overlap each other. The "zindex" property specifies 56what goes on top of what. 57 58The popup window contains a buffer, and that buffer is always associated with 59the popup window. The window cannot be in Normal, Visual or Insert mode, it 60does not get keyboard focus. You can use functions like `setbufline()` to 61change the text in the buffer. There are more differences from how this 62window and buffer behave compared to regular windows and buffers, see 63|popup-buffer|. 64 65If this is not what you are looking for, check out other popup functionality: 66- popup menu, see |popup-menu| 67- balloon, see |balloon-eval| 68 69 70WINDOW POSITION AND SIZE *popup-position* 71 72The height of the window is normally equal to the number of, possibly 73wrapping, lines in the buffer. It can be limited with the "maxheight" 74property. You can use empty lines to increase the height or the "minheight" 75property. 76 77The width of the window is normally equal to the longest visible line in the 78buffer. It can be limited with the "maxwidth" property. You can use spaces 79to increase the width or use the "minwidth" property. 80 81By default the 'wrap' option is set, so that no text disappears. Otherwise, 82if there is not enough space then the window is shifted left in order to 83display more text. When right-aligned the window is shifted right to display 84more text. The shifting can be disabled with the "fixed" property. 85 86Vim tries to show the popup in the location you specify. In some cases, e.g. 87when the popup would go outside of the Vim window, it will show it somewhere 88nearby. E.g. if you use `popup_atcursor()` the popup normally shows just above 89the current cursor position, but if the cursor is close to the top of the Vim 90window it will be placed below the cursor position. 91 92When the screen scrolls up for output of an Ex command, popups move too, so 93that they will not cover the output. 94 95The current cursor position is displayed even when it is under a popup window. 96That way you can still see where it is, even though you cannot see the text 97that it is in. 98 99 100CLOSING THE POPUP WINDOW *popup-close* 101 102Normally the plugin that created the popup window is also in charge of closing 103it. If somehow a popup hangs around, you can close all of them with: > 104 call popup_clear(1) 105Some popups, such as notifications, close after a specified time. This can be 106set with the "time" property on `popup_create()`. 107Otherwise, a popup can be closed by clicking on the X in the top-right corner 108or by clicking anywhere inside the popup. This must be enabled with the 109"close" property. It is set by default for notifications. 110 111 112POPUP BUFFER AND WINDOW *popup-buffer* 113 114If a popup function is called to create a popup from text, a new buffer is 115created to hold the text and text properties of the popup window. The buffer 116is always associated with the popup window and manipulation is restricted: 117- the buffer has no name 118- 'buftype' is "popup" 119- 'swapfile' is off 120- 'bufhidden' is "hide" 121- 'buflisted' is off 122- 'undolevels' is -1: no undo at all 123- all other buffer-local and window-local options are set to their Vim default 124 value. 125 126It is possible to change the specifically mentioned options, but anything 127might break then, so better leave them alone. 128 129The window does have a cursor position, but the cursor is not displayed. In 130fact, the cursor in the underlying window is displayed, as if it peeks through 131the popup, so you can see where it is. 132 133To execute a command in the context of the popup window and buffer use 134`win_execute()`. Example: > 135 call win_execute(winid, 'syntax enable') 136 137Options can be set on the window with `setwinvar()`, e.g.: > 138 call setwinvar(winid, '&wrap', 0) 139And options can be set on the buffer with `setbufvar()`, e.g.: > 140 call setbufvar(winbufnr(winid), '&filetype', 'java') 141You can also use `win_execute()` with a ":setlocal" command. 142 143 144TERMINAL IN POPUP WINDOW *popup-terminal* 145 146A special case is running a terminal in a popup window. Many rules are then 147different: *E863* 148- The popup window always has focus, it is not possible to switch to another 149 window. 150- When the job ends, the popup window closes. 151- The popup window can be closed with `popup_close()`, the terminal buffer 152 then becomes hidden. 153- It is not possible to open a second popup window with a terminal. *E861* 154- The default Pmenu color is only used for the border and padding. To change 155 the color of the terminal itself set the Terminal highlight group before 156 creating the terminal. Setting 'wincolor' later can work but requires the 157 program in the terminal to redraw everything. 158- The default minimal size is 5 lines of 20 characters; Use the "minwidth" and 159 "minheight" parameters to set a different value. 160- The terminal size will grow if the program running in the terminal writes 161 text. Set "maxheight" and "maxwidth" to restrict the size. 162 163To run a terminal in a popup window, first create the terminal hidden. Then 164pass the buffer number to popup_create(). Example: > 165 hi link Terminal Search 166 let buf = term_start(['picker', 'Something'], #{hidden: 1, term_finish: 'close'}) 167 let winid = popup_create(buf, #{minwidth: 50, minheight: 20}) 168 169============================================================================== 1702. Functions *popup-functions* 171 172Creating a popup window: 173 |popup_create()| centered in the screen 174 |popup_atcursor()| just above the cursor position, closes when 175 the cursor moves away 176 |popup_beval()| at the position indicated by v:beval_ 177 variables, closes when the mouse moves away 178 |popup_notification()| show a notification for three seconds 179 |popup_dialog()| centered with padding and border 180 |popup_menu()| prompt for selecting an item from a list 181 182Manipulating a popup window: 183 |popup_hide()| hide a popup temporarily 184 |popup_show()| show a previously hidden popup 185 |popup_move()| change the position and size of a popup 186 |popup_setoptions()| override options of a popup 187 |popup_settext()| replace the popup buffer contents 188 189Closing popup windows: 190 |popup_close()| close one popup 191 |popup_clear()| close all popups 192 193Filter functions: 194 |popup_filter_menu()| select from a list of items 195 |popup_filter_yesno()| blocks until 'y' or 'n' is pressed 196 197Other: 198 |popup_getoptions()| get current options for a popup 199 |popup_getpos()| get actual position and size of a popup 200 |popup_locate()| find popup window at a screen position 201 |popup_list()| get list of all popups 202 203 204DETAILS *popup-function-details* 205 206popup_atcursor({what}, {options}) *popup_atcursor()* 207 Show the {what} above the cursor, and close it when the cursor 208 moves. This works like: > 209 call popup_create({what}, #{ 210 \ pos: 'botleft', 211 \ line: 'cursor-1', 212 \ col: 'cursor', 213 \ moved: 'WORD', 214 \ }) 215< Use {options} to change the properties. 216 If "pos" is passed as "topleft" then the default for "line" 217 becomes "cursor+1". 218 219 Can also be used as a |method|: > 220 GetText()->popup_atcursor({}) 221 222 223popup_beval({what}, {options}) *popup_beval()* 224 Show the {what} above the position from 'ballooneval' and 225 close it when the mouse moves. This works like: > 226 let pos = screenpos(v:beval_winnr, v:beval_lnum, v:beval_col) 227 call popup_create({what}, #{ 228 \ pos: 'botleft', 229 \ line: pos.row - 1, 230 \ col: pos.col, 231 \ mousemoved: 'WORD', 232 \ }) 233< Use {options} to change the properties. 234 See |popup_beval_example| for an example. 235 236 Can also be used as a |method|: > 237 GetText()->popup_beval({}) 238< 239 *popup_clear()* 240popup_clear([{force}]) 241 Emergency solution to a misbehaving plugin: close all popup 242 windows for the current tab and global popups. 243 Close callbacks are not invoked. 244 When {force} is not present this will fail if the current 245 window is a popup. 246 When {force} is present and |TRUE| the popup is also closed 247 when it is the current window. If a terminal is running in a 248 popup it is killed. 249 250 251popup_close({id} [, {result}]) *popup_close()* 252 Close popup {id}. The window and the associated buffer will 253 be deleted. 254 255 If the popup has a callback it will be called just before the 256 popup window is deleted. If the optional {result} is present 257 it will be passed as the second argument of the callback. 258 Otherwise zero is passed to the callback. 259 260 Can also be used as a |method|: > 261 GetPopup()->popup_close() 262 263 264popup_create({what}, {options}) *popup_create()* 265 Open a popup window showing {what}, which is either: 266 - a buffer number 267 - a string 268 - a list of strings 269 - a list of text lines with text properties 270 When {what} is not a buffer number, a buffer is created with 271 'buftype' set to "popup". That buffer will be wiped out once 272 the popup closes. 273 274 {options} is a dictionary with many possible entries. 275 See |popup_create-arguments| for details. 276 277 Returns a window-ID, which can be used with other popup 278 functions. Use `winbufnr()` to get the number of the buffer 279 in the window: > 280 let winid = popup_create('hello', {}) 281 let bufnr = winbufnr(winid) 282 call setbufline(bufnr, 2, 'second line') 283< In case of failure zero is returned. 284 285 Can also be used as a |method|: > 286 GetText()->popup_create({}) 287 288 289popup_dialog({what}, {options}) *popup_dialog()* 290 Just like |popup_create()| but with these default options: > 291 call popup_create({what}, #{ 292 \ pos: 'center', 293 \ zindex: 200, 294 \ drag: 1, 295 \ border: [], 296 \ padding: [], 297 \ mapping: 0, 298 \}) 299< Use {options} to change the properties. E.g. add a 'filter' 300 option with value 'popup_filter_yesno'. Example: > 301 call popup_create('do you want to quit (Yes/no)?', #{ 302 \ filter: 'popup_filter_yesno', 303 \ callback: 'QuitCallback', 304 \ }) 305 306< By default the dialog can be dragged, so that text below it 307 can be read if needed. 308 309 Can also be used as a |method|: > 310 GetText()->popup_dialog({}) 311 312 313popup_filter_menu({id}, {key}) *popup_filter_menu()* 314 Filter that can be used for a popup. These keys can be used: 315 j <Down> <C-N> select item below 316 k <Up> <C-P> select item above 317 <Space> <Enter> accept current selection 318 x Esc CTRL-C cancel the menu 319 Other keys are ignored. 320 Always returns |v:true|. 321 322 A match is set on that line to highlight it, see 323 |popup_menu()|. 324 325 When the current selection is accepted the "callback" of the 326 popup menu is invoked with the index of the selected line as 327 the second argument. The first entry has index one. 328 Cancelling the menu invokes the callback with -1. 329 330 To add shortcut keys, see the example here: 331 |popup_menu-shortcut-example| 332 333 334popup_filter_yesno({id}, {key}) *popup_filter_yesno()* 335 Filter that can be used for a popup. It handles only the keys 336 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the 337 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N' 338 as the second argument. Pressing Esc and 'x' works like 339 pressing 'n'. CTRL-C invokes the callback with -1. Other 340 keys are ignored. 341 See the example here: |popup_dialog-example| 342 343 344popup_findinfo() *popup_findinfo()* 345 Get the |window-ID| for the popup info window, as it used by 346 the popup menu. See |complete-popup|. The info popup is 347 hidden when not used, it can be deleted with |popup_clear()| 348 and |popup_close()|. Use |popup_show()| to reposition it to 349 the item in the popup menu. 350 Returns zero if there is none. 351 352 353popup_findpreview() *popup_findpreview()* 354 Get the |window-ID| for the popup preview window. 355 Return zero if there is none. 356 357 358popup_getoptions({id}) *popup_getoptions()* 359 Return the {options} for popup {id} in a Dict. 360 A zero value means the option was not set. For "zindex" the 361 default value is returned, not zero. 362 363 The "moved" entry is a list with line number, minimum and 364 maximum column, [0, 0, 0] when not set. 365 366 The "mousemoved" entry is a list with screen row, minimum and 367 maximum screen column, [0, 0, 0] when not set. 368 369 "firstline" is the property set on the popup, unlike the 370 "firstline" obtained with |popup_getpos()| which is the actual 371 buffer line at the top of the popup window. 372 373 "border" and "padding" are not included when all values are 374 zero. When all values are one then an empty list is included. 375 376 "borderhighlight" is not included when all values are empty. 377 "scrollbarhighlight" and "thumbhighlight" are only included 378 when set. 379 380 "tabpage" will be -1 for a global popup, zero for a popup on 381 the current tabpage and a positive number for a popup on 382 another tabpage. 383 384 "textprop", "textpropid" and "textpropwin" are only present 385 when "textprop" was set. 386 387 If popup window {id} is not found an empty Dict is returned. 388 389 Can also be used as a |method|: > 390 GetPopup()->popup_getoptions() 391 392 393popup_getpos({id}) *popup_getpos()* 394 Return the position and size of popup {id}. Returns a Dict 395 with these entries: 396 col screen column of the popup, one-based 397 line screen line of the popup, one-based 398 width width of the whole popup in screen cells 399 height height of the whole popup in screen cells 400 core_col screen column of the text box 401 core_line screen line of the text box 402 core_width width of the text box in screen cells 403 core_height height of the text box in screen cells 404 firstline line of the buffer at top (1 unless scrolled) 405 (not the value of the "firstline" property) 406 lastline line of the buffer at the bottom (updated when 407 the popup is redrawn) 408 scrollbar non-zero if a scrollbar is displayed 409 visible one if the popup is displayed, zero if hidden 410 Note that these are the actual screen positions. They differ 411 from the values in `popup_getoptions()` for the sizing and 412 positioning mechanism applied. 413 414 The "core_" values exclude the padding and border. 415 416 If popup window {id} is not found an empty Dict is returned. 417 418 Can also be used as a |method|: > 419 GetPopup()->popup_getpos() 420 421 422popup_hide({id}) *popup_hide()* 423 If {id} is a displayed popup, hide it now. If the popup has a 424 filter it will not be invoked for so long as the popup is 425 hidden. 426 If window {id} does not exist nothing happens. If window {id} 427 exists but is not a popup window an error is given. *E993* 428 If popup window {id} contains a terminal an error is given. 429 430 Can also be used as a |method|: > 431 GetPopup()->popup_hide() 432 433 434popup_list() *popup_list()* 435 Return a List with the |window-ID| of all existing popups. 436 437 438popup_locate({row}, {col}) *popup_locate()* 439 Return the |window-ID| of the popup at screen position {row} 440 and {col}. If there are multiple popups the one with the 441 highest zindex is returned. If there are no popups at this 442 position then zero is returned. 443 444 445popup_menu({what}, {options}) *popup_menu()* 446 Show the {what} near the cursor, handle selecting one of the 447 items with cursorkeys, and close it an item is selected with 448 Space or Enter. {what} should have multiple lines to make this 449 useful. This works like: > 450 call popup_create({what}, #{ 451 \ pos: 'center', 452 \ zindex: 200, 453 \ drag: 1, 454 \ wrap: 0, 455 \ border: [], 456 \ cursorline: 1, 457 \ padding: [0,1,0,1], 458 \ filter: 'popup_filter_menu', 459 \ mapping: 0, 460 \ }) 461< The current line is highlighted with a match using 462 "PopupSelected", or "PmenuSel" if that is not defined. 463 464 Use {options} to change the properties. Should at least set 465 "callback" to a function that handles the selected item. 466 Example: > 467 func ColorSelected(id, result) 468 " use a:result 469 endfunc 470 call popup_menu(['red', 'green', 'blue'], #{ 471 \ callback: 'ColorSelected', 472 \ }) 473 474< Can also be used as a |method|: > 475 GetChoices()->popup_menu({}) 476 477 478popup_move({id}, {options}) *popup_move()* 479 Move popup {id} to the position specified with {options}. 480 {options} may contain the items from |popup_create()| that 481 specify the popup position: 482 line 483 col 484 pos 485 maxheight 486 minheight 487 maxwidth 488 minwidth 489 fixed 490 For {id} see `popup_hide()`. 491 For other options see |popup_setoptions()|. 492 493 Can also be used as a |method|: > 494 GetPopup()->popup_move(options) 495 496 497popup_notification({what}, {options}) *popup_notification()* 498 Show the {what} for 3 seconds at the top of the Vim window. 499 This works like: > 500 call popup_create({what}, #{ 501 \ line: 1, 502 \ col: 10, 503 \ minwidth: 20, 504 \ time: 3000, 505 \ tabpage: -1, 506 \ zindex: 300, 507 \ drag: 1, 508 \ highlight: 'WarningMsg', 509 \ border: [], 510 \ close: 'click', 511 \ padding: [0,1,0,1], 512 \ }) 513< The PopupNotification highlight group is used instead of 514 WarningMsg if it is defined. 515 516 Without the |+timers| feature the popup will not disappear 517 automatically, the user has to click in it. 518 519 The position will be adjusted to avoid overlap with other 520 notifications. 521 Use {options} to change the properties. 522 523 Can also be used as a |method|: > 524 GetText()->popup_notification({}) 525 526 527popup_setoptions({id}, {options}) *popup_setoptions()* 528 Override options in popup {id} with entries in {options}. 529 These options can be set: 530 border 531 borderchars 532 borderhighlight 533 callback 534 close 535 cursorline 536 drag 537 filter 538 firstline 539 flip 540 highlight 541 mapping 542 mask 543 moved 544 padding 545 resize 546 scrollbar 547 scrollbarhighlight 548 thumbhighlight 549 time 550 title 551 wrap 552 zindex 553 The options from |popup_move()| can also be used. 554 Generally, setting an option to zero or an empty string resets 555 it to the default value, but there are exceptions. 556 For "hidden" use |popup_hide()| and |popup_show()|. 557 "tabpage" cannot be changed. 558 559 Can also be used as a |method|: > 560 GetPopup()->popup_setoptions(options) 561 562 563popup_settext({id}, {text}) *popup_settext()* 564 Set the text of the buffer in popup win {id}. {text} is the 565 same as supplied to |popup_create()|, except that a buffer 566 number is not allowed. 567 Does not change the window size or position, other than caused 568 by the different text. 569 570 Can also be used as a |method|: > 571 GetPopup()->popup_settext('hello') 572 573 574popup_show({id}) *popup_show()* 575 If {id} is a hidden popup, show it now. 576 For {id} see `popup_hide()`. 577 If {id} is the info popup it will be positioned next to the 578 current popup menu item. 579 580 581============================================================================== 5823. Usage *popup-usage* 583 584POPUP_CREATE() ARGUMENTS *popup_create-arguments* 585 586The first argument of |popup_create()| (and the second argument to 587|popup_settext()|) specifies the text to be displayed, and optionally text 588properties. It is in one of four forms: 589- a buffer number 590- a string 591- a list of strings 592- a list of dictionaries, where each dictionary has these entries: 593 text String with the text to display. 594 props A list of text properties. Optional. 595 Each entry is a dictionary, like the third argument of 596 |prop_add()|, but specifying the column in the 597 dictionary with a "col" entry, see below: 598 |popup-props|. 599 600If you want to create a new buffer yourself use |bufadd()| and pass the buffer 601number to popup_create(). 602 603The second argument of |popup_create()| is a dictionary with options: 604 line Screen line where to position the popup. Can use a 605 number or "cursor", "cursor+1" or "cursor-1" to use 606 the line of the cursor and add or subtract a number of 607 lines. If omitted or zero the popup is vertically 608 centered. The first line is 1. 609 When using "textprop" the number is relative to the 610 text property and can be negative. 611 col Screen column where to position the popup. Can use a 612 number or "cursor" to use the column of the cursor, 613 "cursor+9" or "cursor-9" to add or subtract a number 614 of columns. If omitted or zero the popup is 615 horizontally centered. The first column is 1. 616 When using "textprop" the number is relative to the 617 text property and can be negative. 618 pos "topleft", "topright", "botleft" or "botright": 619 defines what corner of the popup "line" and "col" are 620 used for. When not set "topleft" is used. 621 Alternatively "center" can be used to position the 622 popup in the center of the Vim window, in which case 623 "line" and "col" are ignored. 624 posinvert When FALSE the value of "pos" is always used. When 625 TRUE (the default) and the popup does not fit 626 vertically and there is more space on the other side 627 then the popup is placed on the other side of the 628 position indicated by "line". 629 textprop When present the popup is positioned next to a text 630 property with this name and will move when the text 631 property moves. Use an empty string to remove. See 632 |popup-textprop-pos|. 633 textpropwin What window to search for the text property. When 634 omitted or invalid the current window is used. Used 635 when "textprop" is present. 636 textpropid Used to identify the text property when "textprop" is 637 present. Use zero to reset. 638 fixed When FALSE (the default), and: 639 - "pos" is "botleft" or "topleft", and 640 - "wrap" is off, and 641 - the popup would be truncated at the right edge of 642 the screen, then 643 the popup is moved to the left so as to fit the 644 contents on the screen. Set to TRUE to disable this. 645 flip When TRUE (the default) and the position is relative 646 to the cursor, flip to below or above the cursor to 647 avoid overlap with the |popupmenu-completion| or 648 another popup with a higher "zindex". When there is 649 no space above/below the cursor then show the popup to 650 the side of the popup or popup menu. 651 {not implemented yet} 652 maxheight Maximum height of the contents, excluding border and 653 padding. 654 minheight Minimum height of the contents, excluding border and 655 padding. 656 maxwidth Maximum width of the contents, excluding border, 657 padding and scrollbar. 658 minwidth Minimum width of the contents, excluding border, 659 padding and scrollbar. 660 firstline First buffer line to display. When larger than one it 661 looks like the text scrolled up. When out of range 662 the last buffer line will at the top of the window. 663 Set to zero to leave the position as set by commands. 664 Also see "scrollbar". 665 hidden When TRUE the popup exists but is not displayed; use 666 `popup_show()` to unhide it. 667 tabpage When -1: display the popup on all tab pages. 668 When 0 (the default): display the popup on the current 669 tab page. 670 Otherwise the number of the tab page the popup is 671 displayed on; when invalid the popup is not created 672 and an error is given. *E997* 673 title Text to be displayed above the first item in the 674 popup, on top of any border. If there is no top 675 border one line of padding is added to put the title 676 on. You might want to add one or more spaces at the 677 start and end as padding. 678 wrap TRUE to make the lines wrap (default TRUE). 679 drag TRUE to allow the popup to be dragged with the mouse 680 by grabbing at the border. Has no effect if the 681 popup does not have a border. As soon as dragging 682 starts and "pos" is "center" it is changed to 683 "topleft". 684 resize TRUE to allow the popup to be resized with the mouse 685 by grabbing at the bottom right corner. Has no effect 686 if the popup does not have a border. 687 close When "button" an X is displayed in the top-right, on 688 top of any border, padding or text. When clicked on 689 the X the popup will close. Any callback is invoked 690 with the value -2. 691 When "click" any mouse click in the popup will close 692 it. 693 When "none" (the default) mouse clicks do not close 694 the popup window. 695 highlight Highlight group name to use for the text, stored in 696 the 'wincolor' option. 697 padding List with numbers, defining the padding 698 above/right/below/left of the popup (similar to CSS). 699 An empty list uses a padding of 1 all around. The 700 padding goes around the text, inside any border. 701 Padding uses the 'wincolor' highlight. 702 Example: [1, 2, 1, 3] has 1 line of padding above, 2 703 columns on the right, 1 line below and 3 columns on 704 the left. 705 border List with numbers, defining the border thickness 706 above/right/below/left of the popup (similar to CSS). 707 Only values of zero and non-zero are currently 708 recognized. An empty list uses a border all around. 709 borderhighlight List of highlight group names to use for the border. 710 When one entry it is used for all borders, otherwise 711 the highlight for the top/right/bottom/left border. 712 Example: ['TopColor', 'RightColor', 'BottomColor, 713 'LeftColor'] 714 borderchars List with characters, defining the character to use 715 for the top/right/bottom/left border. Optionally 716 followed by the character to use for the 717 topleft/topright/botright/botleft corner. 718 Example: ['-', '|', '-', '|', '┌', '┐', '┘', '└'] 719 When the list has one character it is used for all. 720 When the list has two characters the first is used for 721 the border lines, the second for the corners. 722 By default a double line is used all around when 723 'encoding' is "utf-8" and 'ambiwidth' is "single", 724 otherwise ASCII characters are used. 725 scrollbar 1 or true: show a scrollbar when the text doesn't fit. 726 zero: do not show a scrollbar. Default is non-zero. 727 Also see |popup-scrollbar|. 728 scrollbarhighlight Highlight group name for the scrollbar. The 729 background color is what matters. When not given then 730 PmenuSbar is used. 731 thumbhighlight Highlight group name for the scrollbar thumb. The 732 background color is what matters. When not given then 733 PmenuThumb is used. 734 zindex Priority for the popup, default 50. Minimum value is 735 1, maximum value is 32000. 736 mask A list of lists with coordinates, defining parts of 737 the popup that are transparent. See |popup-mask|. 738 time Time in milliseconds after which the popup will close. 739 When omitted |popup_close()| must be used. 740 moved Specifies to close the popup if the cursor moved: 741 - "any": if the cursor moved at all 742 - "word": if the cursor moved outside |<cword>| 743 - "WORD": if the cursor moved outside |<cWORD>| 744 - "expr": if the cursor moved outside |<cexpr>| 745 - [{start}, {end}]: if the cursor moved before column 746 {start} or after {end} 747 - [{lnum}, {start}, {end}]: if the cursor moved away 748 from line {lnum}, before column {start} or after 749 {end} 750 - [0, 0, 0] do not close the popup when the cursor 751 moves 752 The popup also closes if the cursor moves to another 753 line or to another window. 754 mousemoved Like "moved" but referring to the mouse pointer 755 position 756 cursorline TRUE: Highlight the cursor line. Also scrolls the 757 text to show this line (only works properly 758 when 'wrap' is off). 759 zero: Do not highlight the cursor line. 760 Default is zero, except for |popup_menu()|. 761 filter A callback that can filter typed characters, see 762 |popup-filter|. 763 mapping Allow for key mapping. When FALSE and the popup is 764 visible and has a filter callback key mapping is 765 disabled. Default value is TRUE. 766 filtermode In which modes the filter is used (same flags as with 767 |hasmapto()| plus "a"): 768 n Normal mode 769 v Visual and Select mode 770 x Visual mode 771 s Select mode 772 o Operator-pending mode 773 i Insert mode 774 l Language-Argument ("r", "f", "t", etc.) 775 c Command-line mode 776 a all modes 777 The default value is "a". 778 callback A callback that is called when the popup closes, e.g. 779 when using |popup_filter_menu()|, see |popup-callback|. 780 781Depending on the "zindex" the popup goes under or above other popups. The 782completion menu (|popup-menu|) has zindex 100. For messages that occur for a 783short time the suggestion is to use zindex 1000. 784 785By default text wraps, which causes a line in {lines} to occupy more than one 786screen line. When "wrap" is FALSE then the text outside of the popup or 787outside of the Vim window will not be displayed, thus truncated. 788 789 790POPUP TEXT PROPERTIES *popup-props* 791 792These are similar to the third argument of |prop_add()| except: 793- "lnum" is always the current line in the list 794- "bufnr" is always the buffer of the popup 795- "col" is in the Dict instead of a separate argument 796So we get: 797 col starting column, counted in bytes, use one for the 798 first column. 799 length length of text in bytes; can be zero 800 end_lnum line number for the end of the text 801 end_col column just after the text; not used when "length" is 802 present; when {col} and "end_col" are equal, this is a 803 zero-width text property 804 id user defined ID for the property; when omitted zero is 805 used 806 type name of the text property type, as added with 807 |prop_type_add()| 808 809 810POSITION POPUP WITH TEXTPROP *popup-textprop-pos* 811 812Positioning a popup next to a text property causes the popup to move when text 813is inserted or deleted. The popup functions like a tooltip. 814 815These steps are needed to make this work: 816 817- Define a text property type, it defines the name. > 818 call prop_type_add('popupMarker', {}) 819 820- Place a text property at the desired text: > 821 let lnum = {line of the text} 822 let col = {start column of the text} 823 let len = {length of the text} 824 let propId = {arbitrary but unique number} 825 call prop_add(lnum, col, #{ 826 \ length: len, 827 \ type: 'popupMarker', 828 \ id: propId, 829 \ }) 830 831- Create a popup: > 832 let winid = popup_create('the text', #{ 833 \ pos: 'botleft', 834 \ textprop: 'popupMarker', 835 \ textpropid: propId, 836 \ border: [], 837 \ padding: [0,1,0,1], 838 \ close: 'click', 839 \ }) 840 841By default the popup is positioned at the corner of the text, opposite of the 842"pos" specified for the popup. Thus when the popup uses "botleft", the 843bottom-left corner of the popup is positioned next to the top-right corner of 844the text property: 845 +----------+ 846 | the text | 847 +----------+ 848 just some PROPERTY as an example 849 850Here the text property is on "PROPERTY". Move the popup to the left by 851passing a negative "col" value to popup_create(). With "col: -5" you get: 852 853 +----------+ 854 | the text | 855 +----------+ 856 just some PROPERTY as an example 857 858If the text property moves out of view then the popup will be hidden. 859If the window for which the popup was defined is closed, the popup is closed. 860 861If the popup cannot fit in the desired position, it may show at a nearby 862position. 863 864Some hints: 865- To avoid collision with other plugins the text property type name has to be 866 unique. You can also use the "bufnr" item to make it local to a buffer. 867- You can leave out the text property ID if there is only ever one text 868 property visible. 869- The popup may be in the way of what the user is doing, making it close with 870 a click, as in the example above, helps for that. 871- If the text property is removed the popup is closed. Use something like 872 this: > 873 call prop_remove(#{type: 'popupMarker', id: propId}) 874 875 876POPUP FILTER *popup-filter* 877 878A callback that gets any typed keys while a popup is displayed. The filter is 879not invoked when the popup is hidden. 880 881The filter can return TRUE to indicate the key has been handled and is to be 882discarded, or FALSE to let Vim handle the key as usual in the current state. 883In case it returns FALSE and there is another popup window visible, that 884filter is also called. The filter of the popup window with the highest zindex 885is called first. 886 887The filter function is called with two arguments: the ID of the popup and the 888key as a string, e.g.: > 889 func MyFilter(winid, key) 890 if a:key == "\<F2>" 891 " do something 892 return 1 893 endif 894 if a:key == 'x' 895 call popup_close(a:winid) 896 return 1 897 endif 898 return 0 899 endfunc 900< *popup-filter-mode* 901The "filtermode" property can be used to specify in what mode the filter is 902invoked. The default is "a": all modes. When using "nvi" Command-line mode 903is not included, so that any command typed on the command line is not 904filtered. However, to get to Command-line mode the filter must not consume 905":". Just like it must not consume "v" to allow for entering Visual mode. 906 907 *popup-mapping* 908Normally the key is what results after any mapping, since the keys pass on as 909normal input if the filter does not use it. If the filter consumes all the 910keys, set the "mapping" property to zero so that mappings do not get in the 911way. This is default for |popup_menu()| and |popup_dialog()|. 912 913Some recommended key actions: 914 x close the popup (see note below) 915 cursor keys select another entry 916 Tab accept current suggestion 917 918When CTRL-C is pressed the popup is closed, the filter will not be invoked. 919 920A mouse click arrives as <LeftMouse>. The coordinates can be obtained with 921|getmousepos()|. 922 923Vim provides standard filters |popup_filter_menu()| and 924|popup_filter_yesno()|. 925 926Keys coming from a `:normal` command do not pass through the filter. This can 927be used to move the cursor in a popup where the "cursorline" option is set: > 928 call win_execute(winid, 'normal! 10Gzz') 929Keys coming from `feedkeys()` are passed through the filter. 930 931Note that "x" is the normal way to close a popup. You may want to use Esc, 932but since many keys start with an Esc character, there may be a delay before 933Vim recognizes the Esc key. If you do use Esc, it is recommended to set the 934'ttimeoutlen' option to 100 and set 'timeout' and/or 'ttimeout'. 935 936 *popup-filter-errors* 937If the filter function can't be called, e.g. because the name is wrong, then 938the popup is closed. If the filter causes an error then it is assumed to 939return zero. If this happens three times in a row the popup is closed. If 940the popup gives errors fewer than 10% of the calls then it won't be closed. 941 942 943POPUP CALLBACK *popup-callback* 944 945A callback that is invoked when the popup closes. 946 947The callback is invoked with two arguments: the ID of the popup window and the 948result, which could be an index in the popup lines, or whatever was passed as 949the second argument of `popup_close()`. 950 951If the popup is force-closed, e.g. because the cursor moved or CTRL-C was 952pressed, the number -1 is passed to the callback. 953 954Example: > 955 func SelectedColor(id, result) 956 echo 'choice made: ' .. a:result 957 endfunc 958 959 960POPUP SCROLLBAR *popup-scrollbar* 961 962If the text does not fit in the popup a scrollbar is displayed on the right of 963the window. This can be disabled by setting the "scrollbar" option to zero. 964When the scrollbar is displayed mouse scroll events, while the mouse pointer 965is on the popup, will cause the text to scroll up or down as you would expect. 966A click in the upper half of the scrollbar will scroll the text down one line. 967A click in the lower half will scroll the text up one line. However, this is 968limited so that the popup does not get smaller. 969 970 971POPUP MASK *popup-mask* 972 973To minimize the text that the popup covers, parts of it can be made 974transparent. This is defined by a "mask" which is a list of lists, where each 975list has four numbers: 976 col start column, positive for counting from the left, 1 for 977 leftmost, negative for counting from the right, -1 for 978 rightmost 979 endcol last column, like "col" 980 line start line, positive for counting from the top, 1 for top, 981 negative for counting from the bottom, -1 for bottom 982 endline end line, like "line" 983 984For example, to make the last 10 columns of the last line transparent: 985 [[-10, -1, -1, -1]] 986 987To make the four corners transparent: 988 [[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]] 989 990============================================================================== 9914. Examples *popup-examples* 992 993TODO: more interesting examples 994 *popup_dialog-example* 995Prompt the user to press y/Y or n/N: > 996 997 func MyDialogHandler(id, result) 998 if a:result 999 " ... 'y' or 'Y' was pressed 1000 endif 1001 endfunc 1002 1003 call popup_dialog('Continue? y/n', #{ 1004 \ filter: 'popup_filter_yesno', 1005 \ callback: 'MyDialogHandler', 1006 \ }) 1007< 1008 *popup_menu-shortcut-example* 1009Extend popup_filter_menu() with shortcut keys: > 1010 1011 call popup_menu(['Save', 'Cancel', 'Discard'], #{ 1012 \ filter: 'MyMenuFilter', 1013 \ callback: 'MyMenuHandler', 1014 \ }) 1015 1016 func MyMenuFilter(id, key) 1017 " Handle shortcuts 1018 if a:key == 'S' 1019 call popup_close(a:id, 1) 1020 return 1 1021 endif 1022 if a:key == 'C' 1023 call popup_close(a:id, 2) 1024 return 1 1025 endif 1026 if a:key == 'D' 1027 call popup_close(a:id, 3) 1028 return 1 1029 endif 1030 1031 " No shortcut, pass to generic filter 1032 return popup_filter_menu(a:id, a:key) 1033 endfunc 1034< 1035 *popup_beval_example* 1036Example for using a popup window for 'ballooneval': > 1037 1038 set ballooneval balloonevalterm 1039 set balloonexpr=BalloonExpr() 1040 let s:winid = 0 1041 let s:last_text = '' 1042 1043 func BalloonExpr() 1044 if s:winid && popup_getpos(s:winid) != {} 1045 " previous popup window still shows 1046 if v:beval_text == s:last_text 1047 " Still the same text, keep the existing popup 1048 return '' 1049 endif 1050 call popup_close(s:winid) 1051 endif 1052 let s:winid = popup_beval(v:beval_text, #{mousemoved: 'word'}) 1053 let s:last_text = v:beval_text 1054 return '' 1055 endfunc 1056< 1057If the text has to be obtained asynchronously return an empty string from the 1058expression function and call popup_beval() once the text is available. In 1059this example simulated with a timer callback: > 1060 1061 set ballooneval balloonevalterm 1062 set balloonexpr=BalloonExpr() 1063 let s:winid = 0 1064 let s:balloonText = '' 1065 1066 func BalloonExpr() 1067 if s:winid && popup_getpos(s:winid) != {} 1068 " previous popup window still shows 1069 if v:beval_text == s:balloonText 1070 " Still the same text, keep the existing popup 1071 return '' 1072 endif 1073 call popup_close(s:winid) 1074 let s:winid = 0 1075 endif 1076 " simulate an asynchronous lookup for the text to display 1077 let s:balloonText = v:beval_text 1078 call timer_start(100, 'ShowPopup') 1079 return '' 1080 endfunc 1081 1082 func ShowPopup(id) 1083 let s:winid = popup_beval(s:balloonText, #{mousemoved: 'word'}) 1084 endfunc 1085< 1086 1087 vim:tw=78:ts=8:noet:ft=help:norl: 1088