blob: b58ade69d260123c73f4db2cf60feb147d95ad28 [file] [log] [blame]
Bram Moolenaar9bcb70c2019-08-01 21:11:05 +02001*popup.txt* For Vim version 8.1. Last change: 2019 Aug 01
Bram Moolenaar957f85d2019-05-12 21:43:48 +02002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
Bram Moolenaar931a2772019-07-04 16:54:54 +02007Displaying text in a floating window. *popup* *popup-window*
Bram Moolenaar957f85d2019-05-12 21:43:48 +02008
Bram Moolenaar957f85d2019-05-12 21:43:48 +02009
101. Introduction |popup-intro|
Bram Moolenaar931a2772019-07-04 16:54:54 +020011 Window position and size |popup-position|
12 Closing the popup window |popup-close|
13 Popup buffer and window |popup-buffer|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200142. Functions |popup-functions|
Bram Moolenaar931a2772019-07-04 16:54:54 +020015 Details |popup-function-details|
163. Usage |popup-usage|
17 popup_create() arguments |popup_create-arguments|
18 Popup text properties |popup-props|
19 Popup filter |popup-filter|
20 Popup callback |popup-callback|
21 Popup scrollbar |popup-scrollbar|
22 Popup mask |popup-mask|
234. Examples |popup-examples|
Bram Moolenaar957f85d2019-05-12 21:43:48 +020024
25
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020026{not available if the |+textprop| feature was disabled at compile time}
Bram Moolenaar957f85d2019-05-12 21:43:48 +020027
28==============================================================================
291. Introduction *popup-intro*
30
Bram Moolenaar5c017b22019-05-21 23:09:01 +020031We are talking about popup windows here, text that goes on top of the regular
32windows and is under control of a plugin. You cannot edit the text in the
33popup window like with regular windows.
34
35A popup window can be used for such things as:
Bram Moolenaar68e65602019-05-26 21:33:31 +020036- briefly show a message without overwriting the command line
Bram Moolenaar5c017b22019-05-21 23:09:01 +020037- prompt the user with a dialog
Bram Moolenaar4d784b22019-05-25 19:51:39 +020038- display contextual information while typing
Bram Moolenaar5c017b22019-05-21 23:09:01 +020039- give extra information for auto-completion
40
41The text in the popup window can be colored with |text-properties|. It is
42also possible to use syntax highlighting.
43
Bram Moolenaar4d784b22019-05-25 19:51:39 +020044The default color used is "Pmenu". If you prefer something else use the
45"highlight" argument or the 'wincolor' option, e.g.: >
46 hi MyPopupColor ctermbg=lightblue guibg=lightblue
47 call setwinvar(winid, '&wincolor', 'MyPopupColor')
48
Bram Moolenaar68d48f42019-06-12 22:42:41 +020049'hlsearch' highlighting is not displayed in a popup window.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020050
Bram Moolenaar5c017b22019-05-21 23:09:01 +020051A popup window has a window-ID like other windows, but behaves differently.
52The size can be up to the whole Vim window and it overlaps other windows.
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +020053Popup windows can also overlap each other. The "zindex" property specifies
54what goes on top of what.
Bram Moolenaar68e65602019-05-26 21:33:31 +020055
56The popup window contains a buffer, and that buffer is always associated with
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +020057the popup window. The window cannot be in Normal, Visual or Insert mode, it
58does not get keyboard focus. You can use functions like `setbufline()` to
Bram Moolenaar68e65602019-05-26 21:33:31 +020059change the text in the buffer. There are more differences from how this
60window and buffer behave compared to regular windows and buffers, see
61|popup-buffer|.
Bram Moolenaar5c017b22019-05-21 23:09:01 +020062
63If this is not what you are looking for, check out other popup functionality:
Bram Moolenaar957f85d2019-05-12 21:43:48 +020064- popup menu, see |popup-menu|
65- balloon, see |balloon-eval|
66
Bram Moolenaar5c017b22019-05-21 23:09:01 +020067
Bram Moolenaar931a2772019-07-04 16:54:54 +020068WINDOW POSITION AND SIZE *popup-position*
Bram Moolenaar4d784b22019-05-25 19:51:39 +020069
Bram Moolenaar68e65602019-05-26 21:33:31 +020070The height of the window is normally equal to the number of, possibly
71wrapping, lines in the buffer. It can be limited with the "maxheight"
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020072property. You can use empty lines to increase the height or the "minheight"
73property.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020074
75The width of the window is normally equal to the longest line in the buffer.
76It can be limited with the "maxwidth" property. You can use spaces to
Bram Moolenaar68d48f42019-06-12 22:42:41 +020077increase the width or use the "minwidth" property.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020078
Bram Moolenaar042fb4b2019-06-02 14:49:56 +020079By default the 'wrap' option is set, so that no text disappears. Otherwise,
80if there is not enough space then the window is shifted left in order to
Bram Moolenaar2e62b562019-06-30 18:07:00 +020081display more text. When right-aligned the window is shifted right to display
82more text. The shifting can be disabled with the "fixed" property.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020083
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020084Vim tries to show the popup in the location you specify. In some cases, e.g.
85when the popup would go outside of the Vim window, it will show it somewhere
Bram Moolenaar2e62b562019-06-30 18:07:00 +020086nearby. E.g. if you use `popup_atcursor()` the popup normally shows just above
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020087the current cursor position, but if the cursor is close to the top of the Vim
88window it will be placed below the cursor position.
89
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +020090When the screen scrolls up for output of an Ex command, popups move too, so
91that they will not cover the output.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020092
Bram Moolenaar68d48f42019-06-12 22:42:41 +020093The current cursor position is displayed even when it is under a popup window.
94That way you can still see where it is, even though you cannot see the text
95that it is in.
Bram Moolenaar868b7b62019-05-29 21:44:40 +020096
Bram Moolenaar5c017b22019-05-21 23:09:01 +020097
Bram Moolenaar931a2772019-07-04 16:54:54 +020098CLOSING THE POPUP WINDOW *popup-close*
Bram Moolenaar2e62b562019-06-30 18:07:00 +020099
100Normally the plugin that created the popup window is also in charge of closing
101it. If somehow a popup hangs around, you can close all of them with: >
102 call popup_clear()
103Some popups, such as notifications, close after a specified time. This can be
104set with the "time" property on `popup_create()`.
105Otherwise, a popup can be closed by clicking on the X in the top-right corner
106or by clicking anywhere inside the popup. This must be enabled with the
107"close" property. It is set by default for notifications.
108
109
Bram Moolenaar931a2772019-07-04 16:54:54 +0200110POPUP BUFFER AND WINDOW *popup-buffer*
111
112If a popup function is called to create a popup from text, a new buffer is
113created to hold the text and text properties of the popup window. The buffer
114is always associated with the popup window and manipulation is restricted:
115- the buffer has no name
116- 'buftype' is "popup"
117- 'swapfile' is off
118- 'bufhidden' is "hide"
119- 'buflisted' is off
120- 'undolevels' is -1: no undo at all
121- all other buffer-local and window-local options are set to their Vim default
122 value.
123
124It is possible to change the specifically mentioned options, but anything
125might break then, so better leave them alone.
126
127The window does have a cursor position, but the cursor is not displayed.
128
129To execute a command in the context of the popup window and buffer use
130`win_execute()`. Example: >
131 call win_execute(winid, 'syntax enable')
132
133Options can be set on the window with `setwinvar()`, e.g.: >
134 call setwinvar(winid, '&wrap', 0)
135And options can be set on the buffer with `setbufvar()`, e.g.: >
136 call setbufvar(winbufnr(winid), '&filetype', 'java')
137Note that this does not trigger autocommands. Use `win_execute()` if you do
138need them.
139
140
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200141
142==============================================================================
1432. Functions *popup-functions*
144
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200145Creating a popup window:
146 |popup_create()| centered in the screen
147 |popup_atcursor()| just above the cursor position, closes when
148 the cursor moves away
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200149 |popup_beval()| at the position indicated by v:beval_
150 variables, closes when the mouse moves away
Bram Moolenaara3fce622019-06-20 02:31:49 +0200151 |popup_notification()| show a notification for three seconds
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200152 |popup_dialog()| centered with padding and border
153 |popup_menu()| prompt for selecting an item from a list
154
155Manipulating a popup window:
156 |popup_hide()| hide a popup temporarily
157 |popup_show()| show a previously hidden popup
158 |popup_move()| change the position and size of a popup
159 |popup_setoptions()| override options of a popup
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200160 |popup_settext()| replace the popup buffer contents
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200161
162Closing popup windows:
163 |popup_close()| close one popup
164 |popup_clear()| close all popups
165
166Filter functions:
167 |popup_filter_menu()| select from a list of items
168 |popup_filter_yesno()| blocks until 'y' or 'n' is pressed
169
170Other:
171 |popup_getoptions()| get current options for a popup
172 |popup_getpos()| get actual position and size of a popup
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200173 |popup_locate()| find popup window at a screen position
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200174
175
Bram Moolenaar931a2772019-07-04 16:54:54 +0200176DETAILS *popup-function-details*
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200177
Bram Moolenaar931a2772019-07-04 16:54:54 +0200178popup_atcursor({what}, {options}) *popup_atcursor()*
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200179 Show the {what} above the cursor, and close it when the cursor
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200180 moves. This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200181 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200182 \ pos: 'botleft',
183 \ line: 'cursor-1',
184 \ col: 'cursor',
185 \ moved: 'WORD',
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200186 \ })
187< Use {options} to change the properties.
188
189
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200190popup_beval({what}, {options}) *popup_beval()*
191 Show the {what} above the position from 'ballooneval' and
192 close it when the mouse moves. This works like: >
193 let pos = screenpos(v:beval_winnr, v:beval_lnum, v:beval_col)
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200194 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200195 \ pos: 'botleft',
196 \ line: pos.row - 1,
197 \ col: pos.col,
198 \ mousemoved: 'WORD',
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200199 \ })
200< Use {options} to change the properties.
201 See |popup_beval_example| for an example use.
202
203
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200204 *popup_clear()*
205popup_clear() Emergency solution to a misbehaving plugin: close all popup
Bram Moolenaara3fce622019-06-20 02:31:49 +0200206 windows for the current tab and global popups.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200207
208
209popup_close({id} [, {result}]) *popup_close()*
210 Close popup {id}. The window and the associated buffer will
211 be deleted.
212
213 If the popup has a callback it will be called just before the
214 popup window is deleted. If the optional {result} is present
215 it will be passed as the second argument of the callback.
216 Otherwise zero is passed to the callback.
217
218
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200219popup_create({what}, {options}) *popup_create()*
220 Open a popup window showing {what}, which is either:
221 - a buffer number
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200222 - a string
223 - a list of strings
224 - a list of text lines with text properties
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200225 When {what} is not a buffer number, a buffer is created with
226 'buftype' set to "popup". That buffer will be wiped out once
227 the popup closes.
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200228
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200229 {options} is a dictionary with many possible entries.
Bram Moolenaar931a2772019-07-04 16:54:54 +0200230 See |popup_create-arguments| for details.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200231
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200232 Returns a window-ID, which can be used with other popup
233 functions. Use `winbufnr()` to get the number of the buffer
234 in the window: >
235 let winid = popup_create('hello', {})
236 let bufnr = winbufnr(winid)
237 call setbufline(bufnr, 2, 'second line')
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200238< In case of failure zero is returned.
239
240
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200241popup_dialog({what}, {options}) *popup_dialog()*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200242 Just like |popup_create()| but with these default options: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200243 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200244 \ pos: 'center',
245 \ zindex: 200,
246 \ drag: 1,
247 \ border: [],
248 \ padding: [],
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200249 \})
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200250< Use {options} to change the properties. E.g. add a 'filter'
Bram Moolenaara42d9452019-06-15 21:46:30 +0200251 option with value 'popup_filter_yesno'. Example: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200252 call popup_create('do you want to quit (Yes/no)?', #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200253 \ filter: 'popup_filter_yesno',
254 \ callback: 'QuitCallback',
Bram Moolenaara42d9452019-06-15 21:46:30 +0200255 \ })
256
257< By default the dialog can be dragged, so that text below it
258 can be read if needed.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200259
260
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200261popup_filter_menu({id}, {key}) *popup_filter_menu()*
Bram Moolenaara730e552019-06-16 19:05:31 +0200262 Filter that can be used for a popup. These keys can be used:
Bram Moolenaara3fce622019-06-20 02:31:49 +0200263 j <Down> select item below
Bram Moolenaara730e552019-06-16 19:05:31 +0200264 k <Up> select item above
265 <Space> <Enter> accept current selection
266 x Esc CTRL-C cancel the menu
267 Other keys are ignored.
268
269 A match is set on that line to highlight it, see
270 |popup_menu()|.
271
272 When the current selection is accepted the "callback" of the
273 popup menu is invoked with the index of the selected line as
274 the second argument. The first entry has index one.
275 Cancelling the menu invokes the callback with -1.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200276
Bram Moolenaara3fce622019-06-20 02:31:49 +0200277 To add shortcut keys, see the example here:
278 |popup_menu-shortcut-example|
279
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200280
281popup_filter_yesno({id}, {key}) *popup_filter_yesno()*
282 Filter that can be used for a popup. It handles only the keys
283 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the
284 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N'
Bram Moolenaara42d9452019-06-15 21:46:30 +0200285 as the second argument. Pressing Esc and 'x' works like
286 pressing 'n'. CTRL-C invokes the callback with -1. Other
287 keys are ignored.
Bram Moolenaara3fce622019-06-20 02:31:49 +0200288 See the example here: |popup_dialog-example|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200289
290
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200291popup_getoptions({id}) *popup_getoptions()*
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200292 Return the {options} for popup {id} in a Dict.
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200293 A zero value means the option was not set. For "zindex" the
294 default value is returned, not zero.
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200295
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200296 The "moved" entry is a list with line number, minimum and
297 maximum column, [0, 0, 0] when not set.
298
299 The "mousemoved" entry is a list with screen row, minimum and
300 maximum screen column, [0, 0, 0] when not set.
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200301
Bram Moolenaarae943152019-06-16 22:54:14 +0200302 "border" and "padding" are not included when all values are
303 zero. When all values are one then an empty list is included.
304
305 "borderhighlight" is not included when all values are empty.
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200306 "scrollbarhighlight" and "thumbhighlight" are only included
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200307 when set.
Bram Moolenaarae943152019-06-16 22:54:14 +0200308
Bram Moolenaara3fce622019-06-20 02:31:49 +0200309 "tabpage" will be -1 for a global popup, zero for a popup on
310 the current tabpage and a positive number for a popup on
311 another tabpage.
312
Bram Moolenaarae943152019-06-16 22:54:14 +0200313 If popup window {id} is not found an empty Dict is returned.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200314
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200315
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200316popup_getpos({id}) *popup_getpos()*
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200317 Return the position and size of popup {id}. Returns a Dict
318 with these entries:
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200319 col screen column of the popup, one-based
320 line screen line of the popup, one-based
Bram Moolenaar2fd8e352019-06-01 20:16:48 +0200321 width width of the whole popup in screen cells
322 height height of the whole popup in screen cells
323 core_col screen column of the text box
324 core_line screen line of the text box
325 core_width width of the text box in screen cells
326 core_height height of the text box in screen cells
Bram Moolenaar68acb412019-06-26 03:40:36 +0200327 firstline line of the buffer at top (1 unless scrolled)
328 scrollbar non-zero if a scrollbar is displayed
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200329 visible one if the popup is displayed, zero if hidden
Bram Moolenaarbc133542019-05-29 20:26:46 +0200330 Note that these are the actual screen positions. They differ
331 from the values in `popup_getoptions()` for the sizing and
332 positioning mechanism applied.
Bram Moolenaar2fd8e352019-06-01 20:16:48 +0200333
334 The "core_" values exclude the padding and border.
335
Bram Moolenaarbc133542019-05-29 20:26:46 +0200336 If popup window {id} is not found an empty Dict is returned.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200337
Bram Moolenaar56c0c472019-07-28 17:57:43 +0200338popup_getpreview() *popup_getpreview()*
339 Get the |window-ID| for the popup preview window.
340 Return zero if there is none.
341
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200342
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200343popup_hide({id}) *popup_hide()*
344 If {id} is a displayed popup, hide it now. If the popup has a
345 filter it will not be invoked for so long as the popup is
346 hidden.
347 If window {id} does not exist nothing happens. If window {id}
348 exists but is not a popup window an error is given. *E993*
349
350
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200351popup_locate({row}, {col}) *popup_locate()*
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200352 Return the |window-ID| of the popup at screen position {row}
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200353 and {col}. If there are multiple popups the one with the
354 highest zindex is returned. If there are no popups at this
355 position then zero is returned.
356
357
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200358popup_menu({what}, {options}) *popup_menu()*
359 Show the {what} near the cursor, handle selecting one of the
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200360 items with cursorkeys, and close it an item is selected with
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200361 Space or Enter. {what} should have multiple lines to make this
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200362 useful. This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200363 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200364 \ pos: 'center',
365 \ zindex: 200,
366 \ drag: 1,
367 \ wrap: 0,
368 \ border: [],
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200369 \ cursorline: 1,
Bram Moolenaar03464132019-07-14 16:28:13 +0200370 \ padding: [0,1,0,1],
Bram Moolenaar396e8292019-07-13 23:04:31 +0200371 \ filter: 'popup_filter_menu',
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200372 \ })
Bram Moolenaara730e552019-06-16 19:05:31 +0200373< The current line is highlighted with a match using
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200374 "PopupSelected", or "PmenuSel" if that is not defined.
Bram Moolenaara730e552019-06-16 19:05:31 +0200375
376 Use {options} to change the properties. Should at least set
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200377 "callback" to a function that handles the selected item.
378
379
380popup_move({id}, {options}) *popup_move()*
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200381 Move popup {id} to the position specified with {options}.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200382 {options} may contain the items from |popup_create()| that
Bram Moolenaarae943152019-06-16 22:54:14 +0200383 specify the popup position:
384 line
385 col
386 pos
387 maxheight
388 minheight
389 maxwidth
390 minwidth
391 fixed
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200392 For {id} see `popup_hide()`.
Bram Moolenaarae943152019-06-16 22:54:14 +0200393 For other options see |popup_setoptions()|.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200394
395
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200396popup_notification({what}, {options}) *popup_notification()*
397 Show the {what} for 3 seconds at the top of the Vim window.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200398 This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200399 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200400 \ line: 1,
401 \ col: 10,
402 \ minwidth: 20,
403 \ time: 3000,
404 \ tabpage: -1,
405 \ zindex: 300,
406 \ drag: 1,
407 \ highlight: 'WarningMsg',
408 \ border: [],
409 \ close: 'click',
410 \ padding: [0,1,0,1],
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200411 \ })
Bram Moolenaardfa97f22019-06-15 14:31:55 +0200412< The PopupNotification highlight group is used instead of
413 WarningMsg if it is defined.
Bram Moolenaara730e552019-06-16 19:05:31 +0200414
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200415 Without the |+timers| feature the poup will not disappear
416 automatically, the user has to click in it.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200417
Bram Moolenaara730e552019-06-16 19:05:31 +0200418 The position will be adjusted to avoid overlap with other
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200419 notifications.
420 Use {options} to change the properties.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200421
422
423popup_show({id}) *popup_show()*
424 If {id} is a hidden popup, show it now.
425 For {id} see `popup_hide()`.
426
427
428popup_setoptions({id}, {options}) *popup_setoptions()*
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200429 Override options in popup {id} with entries in {options}.
Bram Moolenaarae943152019-06-16 22:54:14 +0200430 These options can be set:
Bram Moolenaarae943152019-06-16 22:54:14 +0200431 border
Bram Moolenaarae943152019-06-16 22:54:14 +0200432 borderchars
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200433 borderhighlight
434 callback
435 close
436 drag
Bram Moolenaar9bcb70c2019-08-01 21:11:05 +0200437 resize
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200438 cursorline
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200439 filter
440 firstline
441 flip
442 highlight
443 mask
444 moved
445 padding
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200446 scrollbar
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200447 scrollbarhighlight
448 thumbhighlight
Bram Moolenaarae943152019-06-16 22:54:14 +0200449 time
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200450 title
451 wrap
452 zindex
Bram Moolenaarae943152019-06-16 22:54:14 +0200453 The options from |popup_move()| can also be used.
454 For "hidden" use |popup_hide()| and |popup_show()|.
455 "tabpage" cannot be changed.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200456
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200457popup_settext({id}, {text}) *popup_settext()*
458 Set the text of the buffer in poup win {id}. {text} is the
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200459 same as supplied to |popup_create()|, except that a buffer
460 number is not allowed.
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200461 Does not change the window size or position, other than caused
462 by the different text.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200463
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200464
Bram Moolenaar931a2772019-07-04 16:54:54 +0200465==============================================================================
4663. Usage *popup-usage*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200467
Bram Moolenaar931a2772019-07-04 16:54:54 +0200468POPUP_CREATE() ARGUMENTS *popup_create-arguments*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200469
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200470The first argument of |popup_create()| (and the second argument to
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200471|popup_settext()|) specifies the text to be displayed, and optionally text
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200472properties. It is in one of four forms:
473- a buffer number
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200474- a string
475- a list of strings
476- a list of dictionaries, where each dictionary has these entries:
477 text String with the text to display.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200478 props A list of text properties. Optional.
479 Each entry is a dictionary, like the third argument of
480 |prop_add()|, but specifying the column in the
481 dictionary with a "col" entry, see below:
482 |popup-props|.
483
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200484The second argument of |popup_create()| is a dictionary with options:
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200485 line Screen line where to position the popup. Can use a
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200486 number or "cursor", "cursor+1" or "cursor-1" to use
487 the line of the cursor and add or subtract a number of
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200488 lines. If omitted the popup is vertically centered.
489 The first line is 1.
490 col Screen column where to position the popup. Can use a
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200491 number or "cursor" to use the column of the cursor,
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200492 "cursor+9" or "cursor-9" to add or subtract a number
493 of columns. If omitted the popup is horizontally
494 centered. The first column is 1.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200495 pos "topleft", "topright", "botleft" or "botright":
496 defines what corner of the popup "line" and "col" are
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200497 used for. When not set "topleft" is used.
498 Alternatively "center" can be used to position the
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200499 popup in the center of the Vim window, in which case
500 "line" and "col" are ignored.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200501 fixed When FALSE (the default), and:
502 - "pos" is "botleft" or "topleft", and
503 - "wrap" is off, and
504 - the popup would be truncated at the right edge of
505 the screen, then
506 the popup is moved to the left so as to fit the
507 contents on the screen. Set to TRUE to disable this.
508 flip When TRUE (the default) and the position is relative
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200509 to the cursor, flip to below or above the cursor to
510 avoid overlap with the |popupmenu-completion| or
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200511 another popup with a higher "zindex". When there is
512 no space above/below the cursor then show the popup to
513 the side of the popup or popup menu.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200514 {not implemented yet}
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200515 maxheight Maximum height of the contents, excluding border and
516 padding.
517 minheight Minimum height of the contents, excluding border and
518 padding.
Bram Moolenaar54775062019-07-31 21:07:14 +0200519 maxwidth Maximum width of the contents, excluding border,
520 padding and scrollbar.
521 minwidth Minimum width of the contents, excluding border,
522 padding and scrollbar.
Bram Moolenaar8d241042019-06-12 23:40:01 +0200523 firstline First buffer line to display. When larger than one it
524 looks like the text scrolled up. When out of range
525 the last buffer line will at the top of the window.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200526 Also see "scrollbar".
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200527 hidden When TRUE the popup exists but is not displayed; use
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200528 `popup_show()` to unhide it.
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200529 tabpage When -1: display the popup on all tab pages.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200530 When 0 (the default): display the popup on the current
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +0200531 tab page.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200532 Otherwise the number of the tab page the popup is
Bram Moolenaara3fce622019-06-20 02:31:49 +0200533 displayed on; when invalid the popup is not created
Bram Moolenaarb2cda0d2019-06-24 05:06:36 +0200534 and an error is given. *E997*
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200535 title Text to be displayed above the first item in the
536 popup, on top of any border. If there is no top
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200537 border one line of padding is added to put the title
Bram Moolenaareb2310d2019-06-16 20:09:10 +0200538 on. You might want to add one or more spaces at the
539 start and end as padding.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200540 wrap TRUE to make the lines wrap (default TRUE).
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200541 drag TRUE to allow the popup to be dragged with the mouse
542 by grabbing at at the border. Has no effect if the
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200543 popup does not have a border. As soon as dragging
544 starts and "pos" is "center" it is changed to
545 "topleft".
Bram Moolenaar9bcb70c2019-08-01 21:11:05 +0200546 resize TRUE to allow the popup to be resized with the mouse
547 by grabbing at at the bottom right cornder. Has no
548 effect if the popup does not have a border.
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200549 close When "button" an X is displayed in the top-right, on
550 top of any border, padding or text. When clicked on
551 the X the popup will close. Any callback is invoked
552 with the value -2.
553 When "click" any mouse click in the popup will close
554 it.
555 When "none" (the default) mouse clicks do not close
556 the popup window.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200557 highlight Highlight group name to use for the text, stored in
558 the 'wincolor' option.
559 padding List with numbers, defining the padding
560 above/right/below/left of the popup (similar to CSS).
561 An empty list uses a padding of 1 all around. The
562 padding goes around the text, inside any border.
563 Padding uses the 'wincolor' highlight.
564 Example: [1, 2, 1, 3] has 1 line of padding above, 2
565 columns on the right, 1 line below and 3 columns on
566 the left.
567 border List with numbers, defining the border thickness
568 above/right/below/left of the popup (similar to CSS).
569 Only values of zero and non-zero are recognized.
570 An empty list uses a border all around.
571 borderhighlight List of highlight group names to use for the border.
572 When one entry it is used for all borders, otherwise
573 the highlight for the top/right/bottom/left border.
574 Example: ['TopColor', 'RightColor', 'BottomColor,
575 'LeftColor']
576 borderchars List with characters, defining the character to use
577 for the top/right/bottom/left border. Optionally
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200578 followed by the character to use for the
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200579 topleft/topright/botright/botleft corner.
580 Example: ['-', '|', '-', '|', '┌', '┐', '┘', '└']
581 When the list has one character it is used for all.
582 When the list has two characters the first is used for
583 the border lines, the second for the corners.
584 By default a double line is used all around when
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200585 'encoding' is "utf-8" and 'ambiwidth' is "single",
Bram Moolenaara3fce622019-06-20 02:31:49 +0200586 otherwise ASCII characters are used.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200587 scrollbar non-zero: show a scrollbar when the text doesn't fit.
588 zero: do not show a scrollbar. Default is non-zero.
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200589 Also see |popup-scrollbar|.
590 scrollbarhighlight Highlight group name for the scrollbar. The
591 background color is what matters. When not given then
592 PmenuSbar is used.
593 thumbhighlight Highlight group name for the scrollbar thumb. The
594 background color is what matters. When not given then
595 PmenuThumb is used.
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200596 zindex Priority for the popup, default 50. Minimum value is
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200597 1, maximum value is 32000.
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200598 mask A list of lists with coordinates, defining parts of
599 the popup that are transparent. See |popup-mask|.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200600 time Time in milliseconds after which the popup will close.
601 When omitted |popup_close()| must be used.
Bram Moolenaar3397f742019-06-02 18:40:06 +0200602 moved Specifies to close the popup if the cursor moved:
603 - "any": if the cursor moved at all
604 - "word": if the cursor moved outside |<cword>|
605 - "WORD": if the cursor moved outside |<cWORD>|
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200606 - "expr": if the cursor moved outside |<cexpr>|
Bram Moolenaar3397f742019-06-02 18:40:06 +0200607 - [{start}, {end}]: if the cursor moved before column
608 {start} or after {end}
609 The popup also closes if the cursor moves to another
610 line or to another window.
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200611 cursorline non-zero: Highlight the cursor line. Also scrolls the
612 text to show this line (only works properly
613 when 'wrap' is off).
614 zero: Do not highlight the cursor line.
615 Default is zero, except for |popup_menu()|.
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200616 filter A callback that can filter typed characters, see
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200617 |popup-filter|.
618 callback A callback that is called when the popup closes, e.g.
619 when using |popup_filter_menu()|, see |popup-callback|.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200620
621Depending on the "zindex" the popup goes under or above other popups. The
622completion menu (|popup-menu|) has zindex 100. For messages that occur for a
623short time the suggestion is to use zindex 1000.
624
625By default text wraps, which causes a line in {lines} to occupy more than one
626screen line. When "wrap" is FALSE then the text outside of the popup or
627outside of the Vim window will not be displayed, thus truncated.
628
629
630POPUP TEXT PROPERTIES *popup-props*
631
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200632These are similar to the third argument of |prop_add()| except:
633- "lnum" is always the current line in the list
634- "bufnr" is always the buffer of the popup
635- "col" is in the Dict instead of a separate argument
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200636So we get:
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200637 col starting column, counted in bytes, use one for the
638 first column.
639 length length of text in bytes; can be zero
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200640 end_lnum line number for the end of the text
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200641 end_col column just after the text; not used when "length" is
642 present; when {col} and "end_col" are equal, this is a
643 zero-width text property
644 id user defined ID for the property; when omitted zero is
645 used
646 type name of the text property type, as added with
647 |prop_type_add()|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200648
649
650POPUP FILTER *popup-filter*
651
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200652A callback that gets any typed keys while a popup is displayed. The filter is
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200653not invoked when the popup is hidden.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200654
655The filter can return TRUE to indicate the key has been handled and is to be
656discarded, or FALSE to let Vim handle the key as usual in the current state.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200657In case it returns FALSE and there is another popup window visible, that
658filter is also called. The filter of the popup window with the highest zindex
659is called first.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200660
661The filter function is called with two arguments: the ID of the popup and the
Bram Moolenaara42d9452019-06-15 21:46:30 +0200662key as a string, e.g.: >
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200663 func MyFilter(winid, key)
664 if a:key == "\<F2>"
665 " do something
666 return 1
667 endif
668 if a:key == 'x'
669 call popup_close(a:winid)
670 return 1
671 endif
672 return 0
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200673 endfunc
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200674
675Currently the key is what results after any mapping. This may change...
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200676
677Some common key actions:
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200678 x close the popup (see note below)
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200679 cursor keys select another entry
680 Tab accept current suggestion
681
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200682A mouse click arrives as <LeftMouse>. The coordinates are in
683v:mouse_popup_col and v:mouse_popup_row. The top-left screen cell of the
684popup is col 1, row 1 (not counting the border).
685
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200686Vim provides standard filters |popup_filter_menu()| and
687|popup_filter_yesno()|.
688
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200689Note that "x" is the normal way to close a popup. You may want to use Esc,
690but since many keys start with an Esc character, there may be a delay before
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200691Vim recognizes the Esc key. If you do use Esc, it is recommended to set the
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200692'ttimeoutlen' option to 100 and set 'timeout' and/or 'ttimeout'.
693
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200694
695POPUP CALLBACK *popup-callback*
696
Bram Moolenaara42d9452019-06-15 21:46:30 +0200697A callback that is invoked when the popup closes.
Bram Moolenaar9eaac892019-06-01 22:49:29 +0200698
699The callback is invoked with two arguments: the ID of the popup window and the
700result, which could be an index in the popup lines, or whatever was passed as
701the second argument of `popup_close()`.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200702
Bram Moolenaara42d9452019-06-15 21:46:30 +0200703If the popup is force-closed, e.g. because the cursor moved or CTRL-C was
704pressed, the number -1 is passed to the callback.
Bram Moolenaar3397f742019-06-02 18:40:06 +0200705
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200706
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200707POPUP SCROLLBAR *popup-scrollbar*
708
709If the text does not fit in the popup a scrollbar is displayed on the right of
710the window. This can be disabled by setting the "scrollbar" option to zero.
711When the scrollbar is displayed mouse scroll events, while the mouse pointer
712is on the popup, will cause the text to scroll up or down as you would expect.
Bram Moolenaar85850f32019-07-19 22:05:51 +0200713A click in the upper half of the scrollbar will scroll the text down one line.
714A click in the lower half will scroll the text up one line. However, this is
715limited so that the popup does not get smaller.
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200716
717
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200718POPUP MASK *popup-mask*
719
720To minimize the text that the popup covers, parts of it can be made
721transparent. This is defined by a "mask" which is a list of lists, where each
722list has four numbers:
723 col start column, positive for counting from the left, 1 for
724 leftmost, negative for counting from the right, -1 for
725 rightmost
726 endcol last column, like "col"
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200727 line start line, positive for counting from the top, 1 for top,
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200728 negative for counting from the bottom, -1 for bottom
729 endline end line, like "line"
730
731For example, to make the last 10 columns of the last line transparent:
732 [[-10, -1, -1, -1]]
733
734To make the four corners transparent:
735 [[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]
736
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200737==============================================================================
Bram Moolenaar931a2772019-07-04 16:54:54 +02007384. Examples *popup-examples*
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200739
Bram Moolenaar931a2772019-07-04 16:54:54 +0200740TODO: more interesting examples
Bram Moolenaara3fce622019-06-20 02:31:49 +0200741 *popup_dialog-example*
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200742Prompt the user to press y/Y or n/N: >
743
744 func MyDialogHandler(id, result)
745 if a:result
746 " ... 'y' or 'Y' was pressed
747 endif
748 endfunc
749
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200750 call popup_dialog('Continue? y/n', #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200751 \ filter: 'popup_filter_yesno',
752 \ callback: 'MyDialogHandler',
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200753 \ })
754<
Bram Moolenaara3fce622019-06-20 02:31:49 +0200755 *popup_menu-shortcut-example*
756Extend popup_filter_menu() with shortcut keys: >
757
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200758 call popup_menu(['Save', 'Cancel', 'Discard'], #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200759 \ filter: 'MyMenuFilter',
760 \ callback: 'MyMenuHandler',
Bram Moolenaara3fce622019-06-20 02:31:49 +0200761 \ })
762
763 func MyMenuFilter(id, key)
764 " Handle shortcuts
765 if a:key == 'S'
766 call popup_close(a:id, 1)
767 return 1
768 endif
769 if a:key == 'C'
770 call popup_close(a:id, 2)
771 return 1
772 endif
773 if a:key == 'D'
774 call popup_close(a:id, 3)
775 return 1
776 endif
777
778 " No shortcut, pass to generic filter
779 return popup_filter_menu(a:id, a:key)
780 endfunc
781<
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200782 *popup_beval_example*
783Example for using a popup window for 'ballooneval': >
784
785 set ballooneval balloonevalterm
786 set balloonexpr=BalloonExpr()
787 let s:winid = 0
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200788 let s:last_text = ''
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200789
790 func BalloonExpr()
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200791 if s:winid && popup_getpos(s:winid) != {}
792 " previous popup window still shows
793 if v:beval_text == s:last_text
794 " Still the same text, keep the existing popup
795 return ''
796 endif
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200797 call popup_close(s:winid)
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200798 endif
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200799 let s:winid = popup_beval(v:beval_text, #{mousemoved: 'word'})
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200800 let s:last_text = v:beval_text
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200801 return ''
802 endfunc
803<
804If the text has to be obtained asynchronously return an empty string from the
805expression function and call popup_beval() once the text is available. In
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200806this example simulated with a timer callback: >
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200807
808 set ballooneval balloonevalterm
809 set balloonexpr=BalloonExpr()
810 let s:winid = 0
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200811 let s:balloonText = ''
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200812
813 func BalloonExpr()
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200814 if s:winid && popup_getpos(s:winid) != {}
815 " previous popup window still shows
816 if v:beval_text == s:balloonText
817 " Still the same text, keep the existing popup
818 return ''
819 endif
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200820 call popup_close(s:winid)
821 let s:winid = 0
822 endif
823 " simulate an asynchronous loopup for the text to display
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200824 let s:balloonText = v:beval_text
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200825 call timer_start(100, 'ShowPopup')
826 return ''
827 endfunc
828
829 func ShowPopup(id)
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200830 let s:winid = popup_beval(s:balloonText, #{mousemoved: 'word'})
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200831 endfunc
832<
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200833
834 vim:tw=78:ts=8:noet:ft=help:norl: