blob: a438ce64e913559015fa49c681192efab12bc75d [file] [log] [blame]
Bram Moolenaare0d749a2019-09-25 22:14:48 +02001*popup.txt* For Vim version 8.1. Last change: 2019 Sep 25
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|
Bram Moolenaar12034e22019-08-25 22:25:02 +020019 Position popup with textprop |popup-textprop-pos|
Bram Moolenaar931a2772019-07-04 16:54:54 +020020 Popup filter |popup-filter|
21 Popup callback |popup-callback|
22 Popup scrollbar |popup-scrollbar|
23 Popup mask |popup-mask|
244. Examples |popup-examples|
Bram Moolenaar957f85d2019-05-12 21:43:48 +020025
26
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020027{not available if the |+textprop| feature was disabled at compile time}
Bram Moolenaar957f85d2019-05-12 21:43:48 +020028
29==============================================================================
301. Introduction *popup-intro*
31
Bram Moolenaar5c017b22019-05-21 23:09:01 +020032We are talking about popup windows here, text that goes on top of the regular
33windows and is under control of a plugin. You cannot edit the text in the
34popup window like with regular windows.
35
36A popup window can be used for such things as:
Bram Moolenaar68e65602019-05-26 21:33:31 +020037- briefly show a message without overwriting the command line
Bram Moolenaar5c017b22019-05-21 23:09:01 +020038- prompt the user with a dialog
Bram Moolenaar4d784b22019-05-25 19:51:39 +020039- display contextual information while typing
Bram Moolenaar5c017b22019-05-21 23:09:01 +020040- give extra information for auto-completion
41
42The text in the popup window can be colored with |text-properties|. It is
43also possible to use syntax highlighting.
44
Bram Moolenaar4d784b22019-05-25 19:51:39 +020045The default color used is "Pmenu". If you prefer something else use the
46"highlight" argument or the 'wincolor' option, e.g.: >
47 hi MyPopupColor ctermbg=lightblue guibg=lightblue
48 call setwinvar(winid, '&wincolor', 'MyPopupColor')
49
Bram Moolenaar68d48f42019-06-12 22:42:41 +020050'hlsearch' highlighting is not displayed in a popup window.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020051
Bram Moolenaar5c017b22019-05-21 23:09:01 +020052A popup window has a window-ID like other windows, but behaves differently.
53The size can be up to the whole Vim window and it overlaps other windows.
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +020054Popup windows can also overlap each other. The "zindex" property specifies
55what goes on top of what.
Bram Moolenaar68e65602019-05-26 21:33:31 +020056
57The popup window contains a buffer, and that buffer is always associated with
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +020058the popup window. The window cannot be in Normal, Visual or Insert mode, it
59does not get keyboard focus. You can use functions like `setbufline()` to
Bram Moolenaar68e65602019-05-26 21:33:31 +020060change the text in the buffer. There are more differences from how this
61window and buffer behave compared to regular windows and buffers, see
62|popup-buffer|.
Bram Moolenaar5c017b22019-05-21 23:09:01 +020063
64If this is not what you are looking for, check out other popup functionality:
Bram Moolenaar957f85d2019-05-12 21:43:48 +020065- popup menu, see |popup-menu|
66- balloon, see |balloon-eval|
67
Bram Moolenaar5c017b22019-05-21 23:09:01 +020068
Bram Moolenaar931a2772019-07-04 16:54:54 +020069WINDOW POSITION AND SIZE *popup-position*
Bram Moolenaar4d784b22019-05-25 19:51:39 +020070
Bram Moolenaar68e65602019-05-26 21:33:31 +020071The height of the window is normally equal to the number of, possibly
72wrapping, lines in the buffer. It can be limited with the "maxheight"
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020073property. You can use empty lines to increase the height or the "minheight"
74property.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020075
76The width of the window is normally equal to the longest line in the buffer.
77It can be limited with the "maxwidth" property. You can use spaces to
Bram Moolenaar68d48f42019-06-12 22:42:41 +020078increase the width or use the "minwidth" property.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020079
Bram Moolenaar042fb4b2019-06-02 14:49:56 +020080By default the 'wrap' option is set, so that no text disappears. Otherwise,
81if there is not enough space then the window is shifted left in order to
Bram Moolenaar2e62b562019-06-30 18:07:00 +020082display more text. When right-aligned the window is shifted right to display
83more text. The shifting can be disabled with the "fixed" property.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020084
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020085Vim tries to show the popup in the location you specify. In some cases, e.g.
86when the popup would go outside of the Vim window, it will show it somewhere
Bram Moolenaar2e62b562019-06-30 18:07:00 +020087nearby. E.g. if you use `popup_atcursor()` the popup normally shows just above
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020088the current cursor position, but if the cursor is close to the top of the Vim
89window it will be placed below the cursor position.
90
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +020091When the screen scrolls up for output of an Ex command, popups move too, so
92that they will not cover the output.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020093
Bram Moolenaar68d48f42019-06-12 22:42:41 +020094The current cursor position is displayed even when it is under a popup window.
95That way you can still see where it is, even though you cannot see the text
96that it is in.
Bram Moolenaar868b7b62019-05-29 21:44:40 +020097
Bram Moolenaar5c017b22019-05-21 23:09:01 +020098
Bram Moolenaar931a2772019-07-04 16:54:54 +020099CLOSING THE POPUP WINDOW *popup-close*
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200100
101Normally the plugin that created the popup window is also in charge of closing
102it. If somehow a popup hangs around, you can close all of them with: >
103 call popup_clear()
104Some popups, such as notifications, close after a specified time. This can be
105set with the "time" property on `popup_create()`.
106Otherwise, a popup can be closed by clicking on the X in the top-right corner
107or by clicking anywhere inside the popup. This must be enabled with the
108"close" property. It is set by default for notifications.
109
110
Bram Moolenaar931a2772019-07-04 16:54:54 +0200111POPUP BUFFER AND WINDOW *popup-buffer*
112
113If a popup function is called to create a popup from text, a new buffer is
114created to hold the text and text properties of the popup window. The buffer
115is always associated with the popup window and manipulation is restricted:
116- the buffer has no name
117- 'buftype' is "popup"
118- 'swapfile' is off
119- 'bufhidden' is "hide"
120- 'buflisted' is off
121- 'undolevels' is -1: no undo at all
122- all other buffer-local and window-local options are set to their Vim default
123 value.
124
125It is possible to change the specifically mentioned options, but anything
126might break then, so better leave them alone.
127
Bram Moolenaar06fe74a2019-08-31 16:20:32 +0200128The window does have a cursor position, but the cursor is not displayed. In
129fact, the cursor in the underlying window is displayed, as if it peeks through
130the popup, so you can see where it is.
Bram Moolenaar931a2772019-07-04 16:54:54 +0200131
132To execute a command in the context of the popup window and buffer use
133`win_execute()`. Example: >
134 call win_execute(winid, 'syntax enable')
135
136Options can be set on the window with `setwinvar()`, e.g.: >
137 call setwinvar(winid, '&wrap', 0)
138And options can be set on the buffer with `setbufvar()`, e.g.: >
139 call setbufvar(winbufnr(winid), '&filetype', 'java')
Bram Moolenaare0d749a2019-09-25 22:14:48 +0200140You can also use `win_execute()` with a ":setlocal" command.
Bram Moolenaar931a2772019-07-04 16:54:54 +0200141
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200142
143==============================================================================
1442. Functions *popup-functions*
145
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200146Creating a popup window:
147 |popup_create()| centered in the screen
148 |popup_atcursor()| just above the cursor position, closes when
149 the cursor moves away
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200150 |popup_beval()| at the position indicated by v:beval_
151 variables, closes when the mouse moves away
Bram Moolenaara3fce622019-06-20 02:31:49 +0200152 |popup_notification()| show a notification for three seconds
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200153 |popup_dialog()| centered with padding and border
154 |popup_menu()| prompt for selecting an item from a list
155
156Manipulating a popup window:
157 |popup_hide()| hide a popup temporarily
158 |popup_show()| show a previously hidden popup
159 |popup_move()| change the position and size of a popup
160 |popup_setoptions()| override options of a popup
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200161 |popup_settext()| replace the popup buffer contents
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200162
163Closing popup windows:
164 |popup_close()| close one popup
165 |popup_clear()| close all popups
166
167Filter functions:
168 |popup_filter_menu()| select from a list of items
169 |popup_filter_yesno()| blocks until 'y' or 'n' is pressed
170
171Other:
172 |popup_getoptions()| get current options for a popup
173 |popup_getpos()| get actual position and size of a popup
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200174 |popup_locate()| find popup window at a screen position
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200175
176
Bram Moolenaar931a2772019-07-04 16:54:54 +0200177DETAILS *popup-function-details*
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200178
Bram Moolenaar931a2772019-07-04 16:54:54 +0200179popup_atcursor({what}, {options}) *popup_atcursor()*
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200180 Show the {what} above the cursor, and close it when the cursor
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200181 moves. This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200182 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200183 \ pos: 'botleft',
184 \ line: 'cursor-1',
185 \ col: 'cursor',
186 \ moved: 'WORD',
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200187 \ })
188< Use {options} to change the properties.
189
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200190 Can also be used as a |method|: >
191 GetText()->popup_atcursor({})
192
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200193
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200194popup_beval({what}, {options}) *popup_beval()*
195 Show the {what} above the position from 'ballooneval' and
196 close it when the mouse moves. This works like: >
197 let pos = screenpos(v:beval_winnr, v:beval_lnum, v:beval_col)
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200198 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200199 \ pos: 'botleft',
200 \ line: pos.row - 1,
201 \ col: pos.col,
202 \ mousemoved: 'WORD',
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200203 \ })
204< Use {options} to change the properties.
Bram Moolenaar8fe10002019-09-11 22:56:44 +0200205 See |popup_beval_example| for an example.
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200206
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200207 Can also be used as a |method|: >
208 GetText()->popup_beval({})
209<
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200210 *popup_clear()*
211popup_clear() Emergency solution to a misbehaving plugin: close all popup
Bram Moolenaara3fce622019-06-20 02:31:49 +0200212 windows for the current tab and global popups.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200213
214
215popup_close({id} [, {result}]) *popup_close()*
216 Close popup {id}. The window and the associated buffer will
217 be deleted.
218
219 If the popup has a callback it will be called just before the
220 popup window is deleted. If the optional {result} is present
221 it will be passed as the second argument of the callback.
222 Otherwise zero is passed to the callback.
223
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200224 Can also be used as a |method|: >
225 GetPopup()->popup_close()
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200226
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200227popup_create({what}, {options}) *popup_create()*
228 Open a popup window showing {what}, which is either:
229 - a buffer number
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200230 - a string
231 - a list of strings
232 - a list of text lines with text properties
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200233 When {what} is not a buffer number, a buffer is created with
234 'buftype' set to "popup". That buffer will be wiped out once
235 the popup closes.
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200236
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200237 {options} is a dictionary with many possible entries.
Bram Moolenaar931a2772019-07-04 16:54:54 +0200238 See |popup_create-arguments| for details.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200239
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200240 Returns a window-ID, which can be used with other popup
241 functions. Use `winbufnr()` to get the number of the buffer
242 in the window: >
243 let winid = popup_create('hello', {})
244 let bufnr = winbufnr(winid)
245 call setbufline(bufnr, 2, 'second line')
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200246< In case of failure zero is returned.
247
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200248 Can also be used as a |method|: >
249 GetText()->popup_create({})
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200250
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200251popup_dialog({what}, {options}) *popup_dialog()*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200252 Just like |popup_create()| but with these default options: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200253 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200254 \ pos: 'center',
255 \ zindex: 200,
256 \ drag: 1,
257 \ border: [],
258 \ padding: [],
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200259 \ mapping: 0,
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200260 \})
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200261< Use {options} to change the properties. E.g. add a 'filter'
Bram Moolenaara42d9452019-06-15 21:46:30 +0200262 option with value 'popup_filter_yesno'. Example: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200263 call popup_create('do you want to quit (Yes/no)?', #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200264 \ filter: 'popup_filter_yesno',
265 \ callback: 'QuitCallback',
Bram Moolenaara42d9452019-06-15 21:46:30 +0200266 \ })
267
268< By default the dialog can be dragged, so that text below it
269 can be read if needed.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200270
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200271 Can also be used as a |method|: >
272 GetText()->popup_dialog({})
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200273
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200274popup_filter_menu({id}, {key}) *popup_filter_menu()*
Bram Moolenaara730e552019-06-16 19:05:31 +0200275 Filter that can be used for a popup. These keys can be used:
Bram Moolenaara3fce622019-06-20 02:31:49 +0200276 j <Down> select item below
Bram Moolenaara730e552019-06-16 19:05:31 +0200277 k <Up> select item above
278 <Space> <Enter> accept current selection
279 x Esc CTRL-C cancel the menu
280 Other keys are ignored.
281
282 A match is set on that line to highlight it, see
283 |popup_menu()|.
284
285 When the current selection is accepted the "callback" of the
286 popup menu is invoked with the index of the selected line as
287 the second argument. The first entry has index one.
288 Cancelling the menu invokes the callback with -1.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200289
Bram Moolenaara3fce622019-06-20 02:31:49 +0200290 To add shortcut keys, see the example here:
291 |popup_menu-shortcut-example|
292
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200293
294popup_filter_yesno({id}, {key}) *popup_filter_yesno()*
295 Filter that can be used for a popup. It handles only the keys
296 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the
297 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N'
Bram Moolenaara42d9452019-06-15 21:46:30 +0200298 as the second argument. Pressing Esc and 'x' works like
299 pressing 'n'. CTRL-C invokes the callback with -1. Other
300 keys are ignored.
Bram Moolenaara3fce622019-06-20 02:31:49 +0200301 See the example here: |popup_dialog-example|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200302
303
Bram Moolenaarc7c5f102019-08-21 18:31:03 +0200304popup_findinfo() *popup_findinfo()*
305 Get the |window-ID| for the popup info window, as it used by
306 the popup menu. See |complete-popup|. The info popup is
307 hidden when not used, it can be deleted with |popup_clear()|
308 and |popup_close()|.
309 Return zero if there is none.
310
311
312popup_findpreview() *popup_findpreview()*
313 Get the |window-ID| for the popup preview window.
314 Return zero if there is none.
315
316
317
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200318popup_getoptions({id}) *popup_getoptions()*
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200319 Return the {options} for popup {id} in a Dict.
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200320 A zero value means the option was not set. For "zindex" the
321 default value is returned, not zero.
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200322
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200323 The "moved" entry is a list with line number, minimum and
324 maximum column, [0, 0, 0] when not set.
325
326 The "mousemoved" entry is a list with screen row, minimum and
327 maximum screen column, [0, 0, 0] when not set.
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200328
Bram Moolenaar06fe74a2019-08-31 16:20:32 +0200329 "firstline" is the property set on the popup, unlike the
330 "firstline" obtained with |popup_getpos()| which is the actual
331 buffer line at the top of the popup window.
332
Bram Moolenaarae943152019-06-16 22:54:14 +0200333 "border" and "padding" are not included when all values are
334 zero. When all values are one then an empty list is included.
335
336 "borderhighlight" is not included when all values are empty.
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200337 "scrollbarhighlight" and "thumbhighlight" are only included
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200338 when set.
Bram Moolenaarae943152019-06-16 22:54:14 +0200339
Bram Moolenaara3fce622019-06-20 02:31:49 +0200340 "tabpage" will be -1 for a global popup, zero for a popup on
341 the current tabpage and a positive number for a popup on
342 another tabpage.
343
Bram Moolenaar12034e22019-08-25 22:25:02 +0200344 "textprop", "textpropid" and "textpropwin" are only present
345 when "textprop" was set.
346
Bram Moolenaarae943152019-06-16 22:54:14 +0200347 If popup window {id} is not found an empty Dict is returned.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200348
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200349 Can also be used as a |method|: >
350 GetPopup()->popup_getoptions()
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200351
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200352popup_getpos({id}) *popup_getpos()*
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200353 Return the position and size of popup {id}. Returns a Dict
354 with these entries:
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200355 col screen column of the popup, one-based
356 line screen line of the popup, one-based
Bram Moolenaar2fd8e352019-06-01 20:16:48 +0200357 width width of the whole popup in screen cells
358 height height of the whole popup in screen cells
359 core_col screen column of the text box
360 core_line screen line of the text box
361 core_width width of the text box in screen cells
362 core_height height of the text box in screen cells
Bram Moolenaar68acb412019-06-26 03:40:36 +0200363 firstline line of the buffer at top (1 unless scrolled)
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200364 (not the value of the "firstline" property)
Bram Moolenaar68acb412019-06-26 03:40:36 +0200365 scrollbar non-zero if a scrollbar is displayed
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200366 visible one if the popup is displayed, zero if hidden
Bram Moolenaarbc133542019-05-29 20:26:46 +0200367 Note that these are the actual screen positions. They differ
368 from the values in `popup_getoptions()` for the sizing and
369 positioning mechanism applied.
Bram Moolenaar2fd8e352019-06-01 20:16:48 +0200370
371 The "core_" values exclude the padding and border.
372
Bram Moolenaarbc133542019-05-29 20:26:46 +0200373 If popup window {id} is not found an empty Dict is returned.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200374
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200375 Can also be used as a |method|: >
376 GetPopup()->popup_getpos()
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200377
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200378popup_hide({id}) *popup_hide()*
379 If {id} is a displayed popup, hide it now. If the popup has a
380 filter it will not be invoked for so long as the popup is
381 hidden.
382 If window {id} does not exist nothing happens. If window {id}
383 exists but is not a popup window an error is given. *E993*
384
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200385 Can also be used as a |method|: >
386 GetPopup()->popup_hide()
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200387
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200388popup_locate({row}, {col}) *popup_locate()*
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200389 Return the |window-ID| of the popup at screen position {row}
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200390 and {col}. If there are multiple popups the one with the
391 highest zindex is returned. If there are no popups at this
392 position then zero is returned.
393
394
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200395popup_menu({what}, {options}) *popup_menu()*
396 Show the {what} near the cursor, handle selecting one of the
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200397 items with cursorkeys, and close it an item is selected with
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200398 Space or Enter. {what} should have multiple lines to make this
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200399 useful. This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200400 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200401 \ pos: 'center',
402 \ zindex: 200,
403 \ drag: 1,
404 \ wrap: 0,
405 \ border: [],
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200406 \ cursorline: 1,
Bram Moolenaar03464132019-07-14 16:28:13 +0200407 \ padding: [0,1,0,1],
Bram Moolenaar396e8292019-07-13 23:04:31 +0200408 \ filter: 'popup_filter_menu',
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200409 \ mapping: 0,
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200410 \ })
Bram Moolenaara730e552019-06-16 19:05:31 +0200411< The current line is highlighted with a match using
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200412 "PopupSelected", or "PmenuSel" if that is not defined.
Bram Moolenaara730e552019-06-16 19:05:31 +0200413
414 Use {options} to change the properties. Should at least set
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200415 "callback" to a function that handles the selected item.
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200416 Example: >
417 func ColorSelected(id, result)
418 " use a:result
419 endfunc
420 call popup_menu(['red', 'green', 'blue'], #{
421 \ callback: 'ColorSelected',
422 \ })
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200423
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200424< Can also be used as a |method|: >
425 GetChoices()->popup_menu({})
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200426
427popup_move({id}, {options}) *popup_move()*
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200428 Move popup {id} to the position specified with {options}.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200429 {options} may contain the items from |popup_create()| that
Bram Moolenaarae943152019-06-16 22:54:14 +0200430 specify the popup position:
431 line
432 col
433 pos
434 maxheight
435 minheight
436 maxwidth
437 minwidth
438 fixed
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200439 For {id} see `popup_hide()`.
Bram Moolenaarae943152019-06-16 22:54:14 +0200440 For other options see |popup_setoptions()|.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200441
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200442 Can also be used as a |method|: >
443 GetPopup()->popup_move(options)
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200444
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200445popup_notification({what}, {options}) *popup_notification()*
446 Show the {what} for 3 seconds at the top of the Vim window.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200447 This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200448 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200449 \ line: 1,
450 \ col: 10,
451 \ minwidth: 20,
452 \ time: 3000,
453 \ tabpage: -1,
454 \ zindex: 300,
455 \ drag: 1,
456 \ highlight: 'WarningMsg',
457 \ border: [],
458 \ close: 'click',
459 \ padding: [0,1,0,1],
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200460 \ })
Bram Moolenaardfa97f22019-06-15 14:31:55 +0200461< The PopupNotification highlight group is used instead of
462 WarningMsg if it is defined.
Bram Moolenaara730e552019-06-16 19:05:31 +0200463
Bram Moolenaar581ba392019-09-03 22:08:33 +0200464 Without the |+timers| feature the popup will not disappear
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200465 automatically, the user has to click in it.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200466
Bram Moolenaara730e552019-06-16 19:05:31 +0200467 The position will be adjusted to avoid overlap with other
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200468 notifications.
469 Use {options} to change the properties.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200470
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200471 Can also be used as a |method|: >
472 GetText()->popup_notification({})
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200473
474popup_show({id}) *popup_show()*
475 If {id} is a hidden popup, show it now.
476 For {id} see `popup_hide()`.
477
478
479popup_setoptions({id}, {options}) *popup_setoptions()*
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200480 Override options in popup {id} with entries in {options}.
Bram Moolenaarae943152019-06-16 22:54:14 +0200481 These options can be set:
Bram Moolenaarae943152019-06-16 22:54:14 +0200482 border
Bram Moolenaarae943152019-06-16 22:54:14 +0200483 borderchars
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200484 borderhighlight
485 callback
486 close
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200487 cursorline
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200488 drag
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200489 filter
490 firstline
491 flip
492 highlight
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200493 mapping
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200494 mask
495 moved
496 padding
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200497 resize
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200498 scrollbar
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200499 scrollbarhighlight
500 thumbhighlight
Bram Moolenaarae943152019-06-16 22:54:14 +0200501 time
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200502 title
503 wrap
504 zindex
Bram Moolenaarae943152019-06-16 22:54:14 +0200505 The options from |popup_move()| can also be used.
506 For "hidden" use |popup_hide()| and |popup_show()|.
507 "tabpage" cannot be changed.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200508
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200509 Can also be used as a |method|: >
510 GetPopup()->popup_setoptions(options)
511
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200512popup_settext({id}, {text}) *popup_settext()*
Bram Moolenaar581ba392019-09-03 22:08:33 +0200513 Set the text of the buffer in popup win {id}. {text} is the
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200514 same as supplied to |popup_create()|, except that a buffer
515 number is not allowed.
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200516 Does not change the window size or position, other than caused
517 by the different text.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200518
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200519 Can also be used as a |method|: >
520 GetPopup()->popup_settext('hello')
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200521
Bram Moolenaar931a2772019-07-04 16:54:54 +0200522==============================================================================
5233. Usage *popup-usage*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200524
Bram Moolenaar931a2772019-07-04 16:54:54 +0200525POPUP_CREATE() ARGUMENTS *popup_create-arguments*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200526
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200527The first argument of |popup_create()| (and the second argument to
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200528|popup_settext()|) specifies the text to be displayed, and optionally text
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200529properties. It is in one of four forms:
530- a buffer number
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200531- a string
532- a list of strings
533- a list of dictionaries, where each dictionary has these entries:
534 text String with the text to display.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200535 props A list of text properties. Optional.
536 Each entry is a dictionary, like the third argument of
537 |prop_add()|, but specifying the column in the
538 dictionary with a "col" entry, see below:
539 |popup-props|.
540
Bram Moolenaare0d749a2019-09-25 22:14:48 +0200541If you want to create a new buffer yourself use |bufadd()| and pass the buffer
542number to popup_create().
543It is not possible to use the buffer of a terminal window. *E278*
544
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200545The second argument of |popup_create()| is a dictionary with options:
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200546 line Screen line where to position the popup. Can use a
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200547 number or "cursor", "cursor+1" or "cursor-1" to use
548 the line of the cursor and add or subtract a number of
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200549 lines. If omitted the popup is vertically centered.
550 The first line is 1.
Bram Moolenaar12034e22019-08-25 22:25:02 +0200551 When using "textprop" the number is relative to the
552 text property and can be negative.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200553 col Screen column where to position the popup. Can use a
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200554 number or "cursor" to use the column of the cursor,
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200555 "cursor+9" or "cursor-9" to add or subtract a number
556 of columns. If omitted the popup is horizontally
557 centered. The first column is 1.
Bram Moolenaar12034e22019-08-25 22:25:02 +0200558 When using "textprop" the number is relative to the
559 text property and can be negative.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200560 pos "topleft", "topright", "botleft" or "botright":
561 defines what corner of the popup "line" and "col" are
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200562 used for. When not set "topleft" is used.
563 Alternatively "center" can be used to position the
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200564 popup in the center of the Vim window, in which case
565 "line" and "col" are ignored.
Bram Moolenaar12034e22019-08-25 22:25:02 +0200566 textprop When present the popup is positioned next to a text
567 property with this name and will move when the text
568 property moves. Use an empty string to remove. See
569 |popup-textprop-pos|.
570 textpropwin What window to search for the text property. When
571 omitted or invalid the current window is used.
572 textpropid Used to identify the text property when "textprop" is
573 present. Use zero to reset.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200574 fixed When FALSE (the default), and:
575 - "pos" is "botleft" or "topleft", and
576 - "wrap" is off, and
577 - the popup would be truncated at the right edge of
578 the screen, then
579 the popup is moved to the left so as to fit the
580 contents on the screen. Set to TRUE to disable this.
581 flip When TRUE (the default) and the position is relative
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200582 to the cursor, flip to below or above the cursor to
583 avoid overlap with the |popupmenu-completion| or
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200584 another popup with a higher "zindex". When there is
585 no space above/below the cursor then show the popup to
586 the side of the popup or popup menu.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200587 {not implemented yet}
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200588 maxheight Maximum height of the contents, excluding border and
589 padding.
590 minheight Minimum height of the contents, excluding border and
591 padding.
Bram Moolenaar54775062019-07-31 21:07:14 +0200592 maxwidth Maximum width of the contents, excluding border,
593 padding and scrollbar.
594 minwidth Minimum width of the contents, excluding border,
595 padding and scrollbar.
Bram Moolenaar8d241042019-06-12 23:40:01 +0200596 firstline First buffer line to display. When larger than one it
597 looks like the text scrolled up. When out of range
598 the last buffer line will at the top of the window.
Bram Moolenaar06fe74a2019-08-31 16:20:32 +0200599 Set to zero to leave the position as set by commands.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200600 Also see "scrollbar".
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200601 hidden When TRUE the popup exists but is not displayed; use
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200602 `popup_show()` to unhide it.
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200603 tabpage When -1: display the popup on all tab pages.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200604 When 0 (the default): display the popup on the current
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +0200605 tab page.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200606 Otherwise the number of the tab page the popup is
Bram Moolenaara3fce622019-06-20 02:31:49 +0200607 displayed on; when invalid the popup is not created
Bram Moolenaarb2cda0d2019-06-24 05:06:36 +0200608 and an error is given. *E997*
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200609 title Text to be displayed above the first item in the
610 popup, on top of any border. If there is no top
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200611 border one line of padding is added to put the title
Bram Moolenaareb2310d2019-06-16 20:09:10 +0200612 on. You might want to add one or more spaces at the
613 start and end as padding.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200614 wrap TRUE to make the lines wrap (default TRUE).
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200615 drag TRUE to allow the popup to be dragged with the mouse
Bram Moolenaar581ba392019-09-03 22:08:33 +0200616 by grabbing at the border. Has no effect if the
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200617 popup does not have a border. As soon as dragging
618 starts and "pos" is "center" it is changed to
619 "topleft".
Bram Moolenaar9bcb70c2019-08-01 21:11:05 +0200620 resize TRUE to allow the popup to be resized with the mouse
Bram Moolenaar581ba392019-09-03 22:08:33 +0200621 by grabbing at the bottom right corner. Has no effect
622 if the popup does not have a border.
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200623 close When "button" an X is displayed in the top-right, on
624 top of any border, padding or text. When clicked on
625 the X the popup will close. Any callback is invoked
626 with the value -2.
627 When "click" any mouse click in the popup will close
628 it.
629 When "none" (the default) mouse clicks do not close
630 the popup window.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200631 highlight Highlight group name to use for the text, stored in
632 the 'wincolor' option.
633 padding List with numbers, defining the padding
634 above/right/below/left of the popup (similar to CSS).
635 An empty list uses a padding of 1 all around. The
636 padding goes around the text, inside any border.
637 Padding uses the 'wincolor' highlight.
638 Example: [1, 2, 1, 3] has 1 line of padding above, 2
639 columns on the right, 1 line below and 3 columns on
640 the left.
641 border List with numbers, defining the border thickness
642 above/right/below/left of the popup (similar to CSS).
643 Only values of zero and non-zero are recognized.
644 An empty list uses a border all around.
645 borderhighlight List of highlight group names to use for the border.
646 When one entry it is used for all borders, otherwise
647 the highlight for the top/right/bottom/left border.
648 Example: ['TopColor', 'RightColor', 'BottomColor,
649 'LeftColor']
650 borderchars List with characters, defining the character to use
651 for the top/right/bottom/left border. Optionally
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200652 followed by the character to use for the
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200653 topleft/topright/botright/botleft corner.
654 Example: ['-', '|', '-', '|', '┌', '┐', '┘', '└']
655 When the list has one character it is used for all.
656 When the list has two characters the first is used for
657 the border lines, the second for the corners.
658 By default a double line is used all around when
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200659 'encoding' is "utf-8" and 'ambiwidth' is "single",
Bram Moolenaara3fce622019-06-20 02:31:49 +0200660 otherwise ASCII characters are used.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200661 scrollbar non-zero: show a scrollbar when the text doesn't fit.
662 zero: do not show a scrollbar. Default is non-zero.
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200663 Also see |popup-scrollbar|.
664 scrollbarhighlight Highlight group name for the scrollbar. The
665 background color is what matters. When not given then
666 PmenuSbar is used.
667 thumbhighlight Highlight group name for the scrollbar thumb. The
668 background color is what matters. When not given then
669 PmenuThumb is used.
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200670 zindex Priority for the popup, default 50. Minimum value is
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200671 1, maximum value is 32000.
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200672 mask A list of lists with coordinates, defining parts of
673 the popup that are transparent. See |popup-mask|.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200674 time Time in milliseconds after which the popup will close.
675 When omitted |popup_close()| must be used.
Bram Moolenaar3397f742019-06-02 18:40:06 +0200676 moved Specifies to close the popup if the cursor moved:
677 - "any": if the cursor moved at all
678 - "word": if the cursor moved outside |<cword>|
679 - "WORD": if the cursor moved outside |<cWORD>|
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200680 - "expr": if the cursor moved outside |<cexpr>|
Bram Moolenaar3397f742019-06-02 18:40:06 +0200681 - [{start}, {end}]: if the cursor moved before column
682 {start} or after {end}
683 The popup also closes if the cursor moves to another
684 line or to another window.
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200685 cursorline non-zero: Highlight the cursor line. Also scrolls the
686 text to show this line (only works properly
687 when 'wrap' is off).
688 zero: Do not highlight the cursor line.
689 Default is zero, except for |popup_menu()|.
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200690 filter A callback that can filter typed characters, see
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200691 |popup-filter|.
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200692 mapping Allow for key mapping. When FALSE and the popup is
693 visible and has a filter callback key mapping is
694 disabled. Default value is TRUE.
Bram Moolenaar581ba392019-09-03 22:08:33 +0200695 filtermode In which modes the filter is used (same flags as with
696 |hasmapto()| plus "a"):
697 n Normal mode
698 v Visual and Select mode
699 x Visual mode
700 s Select mode
701 o Operator-pending mode
702 i Insert mode
703 l Language-Argument ("r", "f", "t", etc.)
704 c Command-line mode
705 a all modes
706 The default value is "a".
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200707 callback A callback that is called when the popup closes, e.g.
708 when using |popup_filter_menu()|, see |popup-callback|.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200709
710Depending on the "zindex" the popup goes under or above other popups. The
711completion menu (|popup-menu|) has zindex 100. For messages that occur for a
712short time the suggestion is to use zindex 1000.
713
714By default text wraps, which causes a line in {lines} to occupy more than one
715screen line. When "wrap" is FALSE then the text outside of the popup or
716outside of the Vim window will not be displayed, thus truncated.
717
718
719POPUP TEXT PROPERTIES *popup-props*
720
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200721These are similar to the third argument of |prop_add()| except:
722- "lnum" is always the current line in the list
723- "bufnr" is always the buffer of the popup
724- "col" is in the Dict instead of a separate argument
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200725So we get:
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200726 col starting column, counted in bytes, use one for the
727 first column.
728 length length of text in bytes; can be zero
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200729 end_lnum line number for the end of the text
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200730 end_col column just after the text; not used when "length" is
731 present; when {col} and "end_col" are equal, this is a
732 zero-width text property
733 id user defined ID for the property; when omitted zero is
734 used
735 type name of the text property type, as added with
736 |prop_type_add()|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200737
738
Bram Moolenaar12034e22019-08-25 22:25:02 +0200739POSITION POPUP WITH TEXTPROP *popup-textprop-pos*
740
741Positioning a popup next to a text property causes the popup to move when text
742is inserted or deleted. The popup functions like a tooltip.
743
744These steps are needed to make this work:
745
746- Define a text property type, it defines the name. >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200747 call prop_type_add('popupMarker', {})
Bram Moolenaar12034e22019-08-25 22:25:02 +0200748
749- Place a text property at the desired text: >
750 let lnum = {line of the text}
751 let col = {start column of the text}
752 let len = {length of the text}
753 let propId = {arbitrary but unique number}
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200754 call prop_add(lnum, col, #{
Bram Moolenaar12034e22019-08-25 22:25:02 +0200755 \ length: len,
756 \ type: 'popupMarker',
757 \ id: propId,
758 \ })
759
760- Create a popup: >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200761 let winid = popup_create('the text', #{
762 \ pos: 'botleft',
Bram Moolenaar12034e22019-08-25 22:25:02 +0200763 \ textprop: 'popupMarker',
764 \ textpropid: propId,
765 \ border: [],
766 \ padding: [0,1,0,1],
767 \ close: 'click',
768 \ })
769
770By default the popup is positioned at the corner of the text, opposite of the
771"pos" specified for the popup. Thus when the popup uses "botleft", the
772bottom-left corner of the popup is positioned next to the top-right corner of
773the text property:
774 +----------+
775 | the text |
776 +----------+
777 just some PROPERTY as an example
778
779Here the text property is on "PROPERTY". Move the popup to the left by
780passing a negative "col" value to popup_create(). With "col: -5" you get:
781
782 +----------+
783 | the text |
784 +----------+
785 just some PROPERTY as an example
786
787If the text property moves out of view then the popup will be hidden.
788If the window for which the popup was defined is closed, the popup is closed.
789
790If the popup cannot fit in the desired position, it may show at a nearby
791position.
792
793Some hints:
794- To avoid collision with other plugins the text property type name has to be
795 unique. You can also use the "bufnr" item to make it local to a buffer.
796- You can leave out the text property ID if there is only ever one text
797 property visible.
798- The popup may be in the way of what the user is doing, making it close with
799 a click, as in the example above, helps for that.
800- If the text property is removed the popup is closed. Use something like
801 this: >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200802 call prop_remove(#{type: 'popupMarker', id: propId})
Bram Moolenaar12034e22019-08-25 22:25:02 +0200803
804
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200805POPUP FILTER *popup-filter*
806
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200807A callback that gets any typed keys while a popup is displayed. The filter is
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200808not invoked when the popup is hidden.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200809
810The filter can return TRUE to indicate the key has been handled and is to be
811discarded, or FALSE to let Vim handle the key as usual in the current state.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200812In case it returns FALSE and there is another popup window visible, that
813filter is also called. The filter of the popup window with the highest zindex
814is called first.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200815
816The filter function is called with two arguments: the ID of the popup and the
Bram Moolenaara42d9452019-06-15 21:46:30 +0200817key as a string, e.g.: >
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200818 func MyFilter(winid, key)
819 if a:key == "\<F2>"
820 " do something
821 return 1
822 endif
823 if a:key == 'x'
824 call popup_close(a:winid)
825 return 1
826 endif
827 return 0
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200828 endfunc
Bram Moolenaar581ba392019-09-03 22:08:33 +0200829< *popup-filter-mode*
830The "filtermode" property can be used to specify in what mode the filter is
831invoked. The default is "a": all modes. When using "nvi" Command-line mode
832is not included, so that any command typed on the command line is not
833filtered. However, to get to Command-line mode the filter must not consume
834":". Just like it must not consume "v" to allow for entering Visual mode.
835
836 *popup-mapping*
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200837Normally the key is what results after any mapping, since the keys pass on as
838normal input if the filter does not use it. If the filter consumes all the
839keys, set the "mapping" property to zero so that mappings do not get in the
840way. This is default for |popup_menu()| and |popup_dialog()|.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200841
Bram Moolenaar581ba392019-09-03 22:08:33 +0200842Some recommended key actions:
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200843 x close the popup (see note below)
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200844 cursor keys select another entry
845 Tab accept current suggestion
846
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200847A mouse click arrives as <LeftMouse>. The coordinates are in
848v:mouse_popup_col and v:mouse_popup_row. The top-left screen cell of the
849popup is col 1, row 1 (not counting the border).
850
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200851Vim provides standard filters |popup_filter_menu()| and
852|popup_filter_yesno()|.
853
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200854Note that "x" is the normal way to close a popup. You may want to use Esc,
855but since many keys start with an Esc character, there may be a delay before
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200856Vim recognizes the Esc key. If you do use Esc, it is recommended to set the
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200857'ttimeoutlen' option to 100 and set 'timeout' and/or 'ttimeout'.
858
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200859
860POPUP CALLBACK *popup-callback*
861
Bram Moolenaara42d9452019-06-15 21:46:30 +0200862A callback that is invoked when the popup closes.
Bram Moolenaar9eaac892019-06-01 22:49:29 +0200863
864The callback is invoked with two arguments: the ID of the popup window and the
865result, which could be an index in the popup lines, or whatever was passed as
866the second argument of `popup_close()`.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200867
Bram Moolenaara42d9452019-06-15 21:46:30 +0200868If the popup is force-closed, e.g. because the cursor moved or CTRL-C was
869pressed, the number -1 is passed to the callback.
Bram Moolenaar3397f742019-06-02 18:40:06 +0200870
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200871Example: >
872 func SelectedColor(id, result)
873 echo 'choice made: ' .. a:result
874 endfunc
875
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200876
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200877POPUP SCROLLBAR *popup-scrollbar*
878
879If the text does not fit in the popup a scrollbar is displayed on the right of
880the window. This can be disabled by setting the "scrollbar" option to zero.
881When the scrollbar is displayed mouse scroll events, while the mouse pointer
882is on the popup, will cause the text to scroll up or down as you would expect.
Bram Moolenaar85850f32019-07-19 22:05:51 +0200883A click in the upper half of the scrollbar will scroll the text down one line.
884A click in the lower half will scroll the text up one line. However, this is
885limited so that the popup does not get smaller.
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200886
887
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200888POPUP MASK *popup-mask*
889
890To minimize the text that the popup covers, parts of it can be made
891transparent. This is defined by a "mask" which is a list of lists, where each
892list has four numbers:
893 col start column, positive for counting from the left, 1 for
894 leftmost, negative for counting from the right, -1 for
895 rightmost
896 endcol last column, like "col"
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200897 line start line, positive for counting from the top, 1 for top,
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200898 negative for counting from the bottom, -1 for bottom
899 endline end line, like "line"
900
901For example, to make the last 10 columns of the last line transparent:
902 [[-10, -1, -1, -1]]
903
904To make the four corners transparent:
905 [[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]
906
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200907==============================================================================
Bram Moolenaar931a2772019-07-04 16:54:54 +02009084. Examples *popup-examples*
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200909
Bram Moolenaar931a2772019-07-04 16:54:54 +0200910TODO: more interesting examples
Bram Moolenaara3fce622019-06-20 02:31:49 +0200911 *popup_dialog-example*
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200912Prompt the user to press y/Y or n/N: >
913
914 func MyDialogHandler(id, result)
915 if a:result
916 " ... 'y' or 'Y' was pressed
917 endif
918 endfunc
919
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200920 call popup_dialog('Continue? y/n', #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200921 \ filter: 'popup_filter_yesno',
922 \ callback: 'MyDialogHandler',
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200923 \ })
924<
Bram Moolenaara3fce622019-06-20 02:31:49 +0200925 *popup_menu-shortcut-example*
926Extend popup_filter_menu() with shortcut keys: >
927
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200928 call popup_menu(['Save', 'Cancel', 'Discard'], #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200929 \ filter: 'MyMenuFilter',
930 \ callback: 'MyMenuHandler',
Bram Moolenaara3fce622019-06-20 02:31:49 +0200931 \ })
932
933 func MyMenuFilter(id, key)
934 " Handle shortcuts
935 if a:key == 'S'
936 call popup_close(a:id, 1)
937 return 1
938 endif
939 if a:key == 'C'
940 call popup_close(a:id, 2)
941 return 1
942 endif
943 if a:key == 'D'
944 call popup_close(a:id, 3)
945 return 1
946 endif
947
948 " No shortcut, pass to generic filter
949 return popup_filter_menu(a:id, a:key)
950 endfunc
951<
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200952 *popup_beval_example*
953Example for using a popup window for 'ballooneval': >
954
955 set ballooneval balloonevalterm
956 set balloonexpr=BalloonExpr()
957 let s:winid = 0
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200958 let s:last_text = ''
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200959
960 func BalloonExpr()
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200961 if s:winid && popup_getpos(s:winid) != {}
962 " previous popup window still shows
963 if v:beval_text == s:last_text
964 " Still the same text, keep the existing popup
965 return ''
966 endif
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200967 call popup_close(s:winid)
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200968 endif
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200969 let s:winid = popup_beval(v:beval_text, #{mousemoved: 'word'})
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200970 let s:last_text = v:beval_text
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200971 return ''
972 endfunc
973<
974If the text has to be obtained asynchronously return an empty string from the
975expression function and call popup_beval() once the text is available. In
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200976this example simulated with a timer callback: >
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200977
978 set ballooneval balloonevalterm
979 set balloonexpr=BalloonExpr()
980 let s:winid = 0
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200981 let s:balloonText = ''
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200982
983 func BalloonExpr()
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200984 if s:winid && popup_getpos(s:winid) != {}
985 " previous popup window still shows
986 if v:beval_text == s:balloonText
987 " Still the same text, keep the existing popup
988 return ''
989 endif
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200990 call popup_close(s:winid)
991 let s:winid = 0
992 endif
Bram Moolenaar581ba392019-09-03 22:08:33 +0200993 " simulate an asynchronous lookup for the text to display
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200994 let s:balloonText = v:beval_text
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200995 call timer_start(100, 'ShowPopup')
996 return ''
997 endfunc
998
999 func ShowPopup(id)
Bram Moolenaar4c6d9042019-07-16 22:04:02 +02001000 let s:winid = popup_beval(s:balloonText, #{mousemoved: 'word'})
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001001 endfunc
1002<
Bram Moolenaar957f85d2019-05-12 21:43:48 +02001003
1004 vim:tw=78:ts=8:noet:ft=help:norl: