blob: fc00ecffcdbc1e29e639992502113e8125fab742 [file] [log] [blame]
Bram Moolenaar30efcf32019-11-03 22:29:38 +01001*popup.txt* For Vim version 8.1. Last change: 2019 Nov 03
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()|
Bram Moolenaar96f45c02019-10-26 19:53:45 +0200308 and |popup_close()|. Use |popup_show()| to reposition it to
309 the item in the popup menu.
310 Returns zero if there is none.
Bram Moolenaarc7c5f102019-08-21 18:31:03 +0200311
312
313popup_findpreview() *popup_findpreview()*
314 Get the |window-ID| for the popup preview window.
315 Return zero if there is none.
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 Moolenaar30efcf32019-11-03 22:29:38 +0100365 lastline line of the buffer at the bottom
Bram Moolenaar68acb412019-06-26 03:40:36 +0200366 scrollbar non-zero if a scrollbar is displayed
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200367 visible one if the popup is displayed, zero if hidden
Bram Moolenaarbc133542019-05-29 20:26:46 +0200368 Note that these are the actual screen positions. They differ
369 from the values in `popup_getoptions()` for the sizing and
370 positioning mechanism applied.
Bram Moolenaar2fd8e352019-06-01 20:16:48 +0200371
372 The "core_" values exclude the padding and border.
373
Bram Moolenaarbc133542019-05-29 20:26:46 +0200374 If popup window {id} is not found an empty Dict is returned.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200375
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200376 Can also be used as a |method|: >
377 GetPopup()->popup_getpos()
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200378
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200379popup_hide({id}) *popup_hide()*
380 If {id} is a displayed popup, hide it now. If the popup has a
381 filter it will not be invoked for so long as the popup is
382 hidden.
383 If window {id} does not exist nothing happens. If window {id}
384 exists but is not a popup window an error is given. *E993*
385
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200386 Can also be used as a |method|: >
387 GetPopup()->popup_hide()
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200388
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200389popup_locate({row}, {col}) *popup_locate()*
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200390 Return the |window-ID| of the popup at screen position {row}
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200391 and {col}. If there are multiple popups the one with the
392 highest zindex is returned. If there are no popups at this
393 position then zero is returned.
394
395
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200396popup_menu({what}, {options}) *popup_menu()*
397 Show the {what} near the cursor, handle selecting one of the
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200398 items with cursorkeys, and close it an item is selected with
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200399 Space or Enter. {what} should have multiple lines to make this
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200400 useful. This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200401 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200402 \ pos: 'center',
403 \ zindex: 200,
404 \ drag: 1,
405 \ wrap: 0,
406 \ border: [],
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200407 \ cursorline: 1,
Bram Moolenaar03464132019-07-14 16:28:13 +0200408 \ padding: [0,1,0,1],
Bram Moolenaar396e8292019-07-13 23:04:31 +0200409 \ filter: 'popup_filter_menu',
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200410 \ mapping: 0,
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200411 \ })
Bram Moolenaara730e552019-06-16 19:05:31 +0200412< The current line is highlighted with a match using
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200413 "PopupSelected", or "PmenuSel" if that is not defined.
Bram Moolenaara730e552019-06-16 19:05:31 +0200414
415 Use {options} to change the properties. Should at least set
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200416 "callback" to a function that handles the selected item.
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200417 Example: >
418 func ColorSelected(id, result)
419 " use a:result
420 endfunc
421 call popup_menu(['red', 'green', 'blue'], #{
422 \ callback: 'ColorSelected',
423 \ })
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200424
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200425< Can also be used as a |method|: >
426 GetChoices()->popup_menu({})
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200427
428popup_move({id}, {options}) *popup_move()*
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200429 Move popup {id} to the position specified with {options}.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200430 {options} may contain the items from |popup_create()| that
Bram Moolenaarae943152019-06-16 22:54:14 +0200431 specify the popup position:
432 line
433 col
434 pos
435 maxheight
436 minheight
437 maxwidth
438 minwidth
439 fixed
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200440 For {id} see `popup_hide()`.
Bram Moolenaarae943152019-06-16 22:54:14 +0200441 For other options see |popup_setoptions()|.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200442
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200443 Can also be used as a |method|: >
444 GetPopup()->popup_move(options)
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200445
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200446popup_notification({what}, {options}) *popup_notification()*
447 Show the {what} for 3 seconds at the top of the Vim window.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200448 This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200449 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200450 \ line: 1,
451 \ col: 10,
452 \ minwidth: 20,
453 \ time: 3000,
454 \ tabpage: -1,
455 \ zindex: 300,
456 \ drag: 1,
457 \ highlight: 'WarningMsg',
458 \ border: [],
459 \ close: 'click',
460 \ padding: [0,1,0,1],
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200461 \ })
Bram Moolenaardfa97f22019-06-15 14:31:55 +0200462< The PopupNotification highlight group is used instead of
463 WarningMsg if it is defined.
Bram Moolenaara730e552019-06-16 19:05:31 +0200464
Bram Moolenaar581ba392019-09-03 22:08:33 +0200465 Without the |+timers| feature the popup will not disappear
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200466 automatically, the user has to click in it.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200467
Bram Moolenaara730e552019-06-16 19:05:31 +0200468 The position will be adjusted to avoid overlap with other
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200469 notifications.
470 Use {options} to change the properties.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200471
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200472 Can also be used as a |method|: >
473 GetText()->popup_notification({})
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200474
475popup_show({id}) *popup_show()*
476 If {id} is a hidden popup, show it now.
477 For {id} see `popup_hide()`.
Bram Moolenaara1396152019-10-20 18:46:05 +0200478 If {id} is the info popup it will be positioned next to the
479 current popup menu item.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200480
481
482popup_setoptions({id}, {options}) *popup_setoptions()*
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200483 Override options in popup {id} with entries in {options}.
Bram Moolenaarae943152019-06-16 22:54:14 +0200484 These options can be set:
Bram Moolenaarae943152019-06-16 22:54:14 +0200485 border
Bram Moolenaarae943152019-06-16 22:54:14 +0200486 borderchars
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200487 borderhighlight
488 callback
489 close
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200490 cursorline
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200491 drag
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200492 filter
493 firstline
494 flip
495 highlight
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200496 mapping
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200497 mask
498 moved
499 padding
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200500 resize
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200501 scrollbar
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200502 scrollbarhighlight
503 thumbhighlight
Bram Moolenaarae943152019-06-16 22:54:14 +0200504 time
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200505 title
506 wrap
507 zindex
Bram Moolenaarae943152019-06-16 22:54:14 +0200508 The options from |popup_move()| can also be used.
509 For "hidden" use |popup_hide()| and |popup_show()|.
510 "tabpage" cannot be changed.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200511
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200512 Can also be used as a |method|: >
513 GetPopup()->popup_setoptions(options)
514
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200515popup_settext({id}, {text}) *popup_settext()*
Bram Moolenaar581ba392019-09-03 22:08:33 +0200516 Set the text of the buffer in popup win {id}. {text} is the
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200517 same as supplied to |popup_create()|, except that a buffer
518 number is not allowed.
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200519 Does not change the window size or position, other than caused
520 by the different text.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200521
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200522 Can also be used as a |method|: >
523 GetPopup()->popup_settext('hello')
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200524
Bram Moolenaar931a2772019-07-04 16:54:54 +0200525==============================================================================
5263. Usage *popup-usage*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200527
Bram Moolenaar931a2772019-07-04 16:54:54 +0200528POPUP_CREATE() ARGUMENTS *popup_create-arguments*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200529
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200530The first argument of |popup_create()| (and the second argument to
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200531|popup_settext()|) specifies the text to be displayed, and optionally text
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200532properties. It is in one of four forms:
533- a buffer number
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200534- a string
535- a list of strings
536- a list of dictionaries, where each dictionary has these entries:
537 text String with the text to display.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200538 props A list of text properties. Optional.
539 Each entry is a dictionary, like the third argument of
540 |prop_add()|, but specifying the column in the
541 dictionary with a "col" entry, see below:
542 |popup-props|.
543
Bram Moolenaare0d749a2019-09-25 22:14:48 +0200544If you want to create a new buffer yourself use |bufadd()| and pass the buffer
545number to popup_create().
546It is not possible to use the buffer of a terminal window. *E278*
547
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200548The second argument of |popup_create()| is a dictionary with options:
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200549 line Screen line where to position the popup. Can use a
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200550 number or "cursor", "cursor+1" or "cursor-1" to use
551 the line of the cursor and add or subtract a number of
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200552 lines. If omitted the popup is vertically centered.
553 The first line is 1.
Bram Moolenaar12034e22019-08-25 22:25:02 +0200554 When using "textprop" the number is relative to the
555 text property and can be negative.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200556 col Screen column where to position the popup. Can use a
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200557 number or "cursor" to use the column of the cursor,
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200558 "cursor+9" or "cursor-9" to add or subtract a number
559 of columns. If omitted the popup is horizontally
560 centered. The first column is 1.
Bram Moolenaar12034e22019-08-25 22:25:02 +0200561 When using "textprop" the number is relative to the
562 text property and can be negative.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200563 pos "topleft", "topright", "botleft" or "botright":
564 defines what corner of the popup "line" and "col" are
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200565 used for. When not set "topleft" is used.
566 Alternatively "center" can be used to position the
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200567 popup in the center of the Vim window, in which case
568 "line" and "col" are ignored.
Bram Moolenaar12034e22019-08-25 22:25:02 +0200569 textprop When present the popup is positioned next to a text
570 property with this name and will move when the text
571 property moves. Use an empty string to remove. See
572 |popup-textprop-pos|.
573 textpropwin What window to search for the text property. When
574 omitted or invalid the current window is used.
575 textpropid Used to identify the text property when "textprop" is
576 present. Use zero to reset.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200577 fixed When FALSE (the default), and:
578 - "pos" is "botleft" or "topleft", and
579 - "wrap" is off, and
580 - the popup would be truncated at the right edge of
581 the screen, then
582 the popup is moved to the left so as to fit the
583 contents on the screen. Set to TRUE to disable this.
584 flip When TRUE (the default) and the position is relative
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200585 to the cursor, flip to below or above the cursor to
586 avoid overlap with the |popupmenu-completion| or
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200587 another popup with a higher "zindex". When there is
588 no space above/below the cursor then show the popup to
589 the side of the popup or popup menu.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200590 {not implemented yet}
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200591 maxheight Maximum height of the contents, excluding border and
592 padding.
593 minheight Minimum height of the contents, excluding border and
594 padding.
Bram Moolenaar54775062019-07-31 21:07:14 +0200595 maxwidth Maximum width of the contents, excluding border,
596 padding and scrollbar.
597 minwidth Minimum width of the contents, excluding border,
598 padding and scrollbar.
Bram Moolenaar8d241042019-06-12 23:40:01 +0200599 firstline First buffer line to display. When larger than one it
600 looks like the text scrolled up. When out of range
601 the last buffer line will at the top of the window.
Bram Moolenaar06fe74a2019-08-31 16:20:32 +0200602 Set to zero to leave the position as set by commands.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200603 Also see "scrollbar".
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200604 hidden When TRUE the popup exists but is not displayed; use
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200605 `popup_show()` to unhide it.
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200606 tabpage When -1: display the popup on all tab pages.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200607 When 0 (the default): display the popup on the current
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +0200608 tab page.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200609 Otherwise the number of the tab page the popup is
Bram Moolenaara3fce622019-06-20 02:31:49 +0200610 displayed on; when invalid the popup is not created
Bram Moolenaarb2cda0d2019-06-24 05:06:36 +0200611 and an error is given. *E997*
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200612 title Text to be displayed above the first item in the
613 popup, on top of any border. If there is no top
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200614 border one line of padding is added to put the title
Bram Moolenaareb2310d2019-06-16 20:09:10 +0200615 on. You might want to add one or more spaces at the
616 start and end as padding.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200617 wrap TRUE to make the lines wrap (default TRUE).
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200618 drag TRUE to allow the popup to be dragged with the mouse
Bram Moolenaar581ba392019-09-03 22:08:33 +0200619 by grabbing at the border. Has no effect if the
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200620 popup does not have a border. As soon as dragging
621 starts and "pos" is "center" it is changed to
622 "topleft".
Bram Moolenaar9bcb70c2019-08-01 21:11:05 +0200623 resize TRUE to allow the popup to be resized with the mouse
Bram Moolenaar581ba392019-09-03 22:08:33 +0200624 by grabbing at the bottom right corner. Has no effect
625 if the popup does not have a border.
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200626 close When "button" an X is displayed in the top-right, on
627 top of any border, padding or text. When clicked on
628 the X the popup will close. Any callback is invoked
629 with the value -2.
630 When "click" any mouse click in the popup will close
631 it.
632 When "none" (the default) mouse clicks do not close
633 the popup window.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200634 highlight Highlight group name to use for the text, stored in
635 the 'wincolor' option.
636 padding List with numbers, defining the padding
637 above/right/below/left of the popup (similar to CSS).
638 An empty list uses a padding of 1 all around. The
639 padding goes around the text, inside any border.
640 Padding uses the 'wincolor' highlight.
641 Example: [1, 2, 1, 3] has 1 line of padding above, 2
642 columns on the right, 1 line below and 3 columns on
643 the left.
644 border List with numbers, defining the border thickness
645 above/right/below/left of the popup (similar to CSS).
646 Only values of zero and non-zero are recognized.
647 An empty list uses a border all around.
648 borderhighlight List of highlight group names to use for the border.
649 When one entry it is used for all borders, otherwise
650 the highlight for the top/right/bottom/left border.
651 Example: ['TopColor', 'RightColor', 'BottomColor,
652 'LeftColor']
653 borderchars List with characters, defining the character to use
654 for the top/right/bottom/left border. Optionally
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200655 followed by the character to use for the
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200656 topleft/topright/botright/botleft corner.
657 Example: ['-', '|', '-', '|', '┌', '┐', '┘', '└']
658 When the list has one character it is used for all.
659 When the list has two characters the first is used for
660 the border lines, the second for the corners.
661 By default a double line is used all around when
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200662 'encoding' is "utf-8" and 'ambiwidth' is "single",
Bram Moolenaara3fce622019-06-20 02:31:49 +0200663 otherwise ASCII characters are used.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200664 scrollbar non-zero: show a scrollbar when the text doesn't fit.
665 zero: do not show a scrollbar. Default is non-zero.
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200666 Also see |popup-scrollbar|.
667 scrollbarhighlight Highlight group name for the scrollbar. The
668 background color is what matters. When not given then
669 PmenuSbar is used.
670 thumbhighlight Highlight group name for the scrollbar thumb. The
671 background color is what matters. When not given then
672 PmenuThumb is used.
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200673 zindex Priority for the popup, default 50. Minimum value is
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200674 1, maximum value is 32000.
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200675 mask A list of lists with coordinates, defining parts of
676 the popup that are transparent. See |popup-mask|.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200677 time Time in milliseconds after which the popup will close.
678 When omitted |popup_close()| must be used.
Bram Moolenaar3397f742019-06-02 18:40:06 +0200679 moved Specifies to close the popup if the cursor moved:
680 - "any": if the cursor moved at all
681 - "word": if the cursor moved outside |<cword>|
682 - "WORD": if the cursor moved outside |<cWORD>|
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200683 - "expr": if the cursor moved outside |<cexpr>|
Bram Moolenaar3397f742019-06-02 18:40:06 +0200684 - [{start}, {end}]: if the cursor moved before column
685 {start} or after {end}
Bram Moolenaara1396152019-10-20 18:46:05 +0200686 - [{lnum}, {start}, {end}]: if the cursor moved away
687 from line {lnum}, before column {start} or after
688 {end}
Bram Moolenaar3397f742019-06-02 18:40:06 +0200689 The popup also closes if the cursor moves to another
690 line or to another window.
Bram Moolenaara1396152019-10-20 18:46:05 +0200691 mousemoved Like "moved" but referring to the mouse pointer
692 position
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200693 cursorline non-zero: Highlight the cursor line. Also scrolls the
694 text to show this line (only works properly
695 when 'wrap' is off).
696 zero: Do not highlight the cursor line.
697 Default is zero, except for |popup_menu()|.
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200698 filter A callback that can filter typed characters, see
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200699 |popup-filter|.
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200700 mapping Allow for key mapping. When FALSE and the popup is
701 visible and has a filter callback key mapping is
702 disabled. Default value is TRUE.
Bram Moolenaar581ba392019-09-03 22:08:33 +0200703 filtermode In which modes the filter is used (same flags as with
704 |hasmapto()| plus "a"):
705 n Normal mode
706 v Visual and Select mode
707 x Visual mode
708 s Select mode
709 o Operator-pending mode
710 i Insert mode
711 l Language-Argument ("r", "f", "t", etc.)
712 c Command-line mode
713 a all modes
714 The default value is "a".
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200715 callback A callback that is called when the popup closes, e.g.
716 when using |popup_filter_menu()|, see |popup-callback|.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200717
718Depending on the "zindex" the popup goes under or above other popups. The
719completion menu (|popup-menu|) has zindex 100. For messages that occur for a
720short time the suggestion is to use zindex 1000.
721
722By default text wraps, which causes a line in {lines} to occupy more than one
723screen line. When "wrap" is FALSE then the text outside of the popup or
724outside of the Vim window will not be displayed, thus truncated.
725
726
727POPUP TEXT PROPERTIES *popup-props*
728
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200729These are similar to the third argument of |prop_add()| except:
730- "lnum" is always the current line in the list
731- "bufnr" is always the buffer of the popup
732- "col" is in the Dict instead of a separate argument
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200733So we get:
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200734 col starting column, counted in bytes, use one for the
735 first column.
736 length length of text in bytes; can be zero
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200737 end_lnum line number for the end of the text
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200738 end_col column just after the text; not used when "length" is
739 present; when {col} and "end_col" are equal, this is a
740 zero-width text property
741 id user defined ID for the property; when omitted zero is
742 used
743 type name of the text property type, as added with
744 |prop_type_add()|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200745
746
Bram Moolenaar12034e22019-08-25 22:25:02 +0200747POSITION POPUP WITH TEXTPROP *popup-textprop-pos*
748
749Positioning a popup next to a text property causes the popup to move when text
750is inserted or deleted. The popup functions like a tooltip.
751
752These steps are needed to make this work:
753
754- Define a text property type, it defines the name. >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200755 call prop_type_add('popupMarker', {})
Bram Moolenaar12034e22019-08-25 22:25:02 +0200756
757- Place a text property at the desired text: >
758 let lnum = {line of the text}
759 let col = {start column of the text}
760 let len = {length of the text}
761 let propId = {arbitrary but unique number}
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200762 call prop_add(lnum, col, #{
Bram Moolenaar12034e22019-08-25 22:25:02 +0200763 \ length: len,
764 \ type: 'popupMarker',
765 \ id: propId,
766 \ })
767
768- Create a popup: >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200769 let winid = popup_create('the text', #{
770 \ pos: 'botleft',
Bram Moolenaar12034e22019-08-25 22:25:02 +0200771 \ textprop: 'popupMarker',
772 \ textpropid: propId,
773 \ border: [],
774 \ padding: [0,1,0,1],
775 \ close: 'click',
776 \ })
777
778By default the popup is positioned at the corner of the text, opposite of the
779"pos" specified for the popup. Thus when the popup uses "botleft", the
780bottom-left corner of the popup is positioned next to the top-right corner of
781the text property:
782 +----------+
783 | the text |
784 +----------+
785 just some PROPERTY as an example
786
787Here the text property is on "PROPERTY". Move the popup to the left by
788passing a negative "col" value to popup_create(). With "col: -5" you get:
789
790 +----------+
791 | the text |
792 +----------+
793 just some PROPERTY as an example
794
795If the text property moves out of view then the popup will be hidden.
796If the window for which the popup was defined is closed, the popup is closed.
797
798If the popup cannot fit in the desired position, it may show at a nearby
799position.
800
801Some hints:
802- To avoid collision with other plugins the text property type name has to be
803 unique. You can also use the "bufnr" item to make it local to a buffer.
804- You can leave out the text property ID if there is only ever one text
805 property visible.
806- The popup may be in the way of what the user is doing, making it close with
807 a click, as in the example above, helps for that.
808- If the text property is removed the popup is closed. Use something like
809 this: >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200810 call prop_remove(#{type: 'popupMarker', id: propId})
Bram Moolenaar12034e22019-08-25 22:25:02 +0200811
812
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200813POPUP FILTER *popup-filter*
814
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200815A callback that gets any typed keys while a popup is displayed. The filter is
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200816not invoked when the popup is hidden.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200817
818The filter can return TRUE to indicate the key has been handled and is to be
819discarded, or FALSE to let Vim handle the key as usual in the current state.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200820In case it returns FALSE and there is another popup window visible, that
821filter is also called. The filter of the popup window with the highest zindex
822is called first.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200823
824The filter function is called with two arguments: the ID of the popup and the
Bram Moolenaara42d9452019-06-15 21:46:30 +0200825key as a string, e.g.: >
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200826 func MyFilter(winid, key)
827 if a:key == "\<F2>"
828 " do something
829 return 1
830 endif
831 if a:key == 'x'
832 call popup_close(a:winid)
833 return 1
834 endif
835 return 0
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200836 endfunc
Bram Moolenaar581ba392019-09-03 22:08:33 +0200837< *popup-filter-mode*
838The "filtermode" property can be used to specify in what mode the filter is
839invoked. The default is "a": all modes. When using "nvi" Command-line mode
840is not included, so that any command typed on the command line is not
841filtered. However, to get to Command-line mode the filter must not consume
842":". Just like it must not consume "v" to allow for entering Visual mode.
843
844 *popup-mapping*
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200845Normally the key is what results after any mapping, since the keys pass on as
846normal input if the filter does not use it. If the filter consumes all the
847keys, set the "mapping" property to zero so that mappings do not get in the
848way. This is default for |popup_menu()| and |popup_dialog()|.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200849
Bram Moolenaar581ba392019-09-03 22:08:33 +0200850Some recommended key actions:
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200851 x close the popup (see note below)
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200852 cursor keys select another entry
853 Tab accept current suggestion
854
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200855A mouse click arrives as <LeftMouse>. The coordinates are in
856v:mouse_popup_col and v:mouse_popup_row. The top-left screen cell of the
857popup is col 1, row 1 (not counting the border).
858
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200859Vim provides standard filters |popup_filter_menu()| and
860|popup_filter_yesno()|.
861
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200862Note that "x" is the normal way to close a popup. You may want to use Esc,
863but since many keys start with an Esc character, there may be a delay before
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200864Vim recognizes the Esc key. If you do use Esc, it is recommended to set the
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200865'ttimeoutlen' option to 100 and set 'timeout' and/or 'ttimeout'.
866
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200867
868POPUP CALLBACK *popup-callback*
869
Bram Moolenaara42d9452019-06-15 21:46:30 +0200870A callback that is invoked when the popup closes.
Bram Moolenaar9eaac892019-06-01 22:49:29 +0200871
872The callback is invoked with two arguments: the ID of the popup window and the
873result, which could be an index in the popup lines, or whatever was passed as
874the second argument of `popup_close()`.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200875
Bram Moolenaara42d9452019-06-15 21:46:30 +0200876If the popup is force-closed, e.g. because the cursor moved or CTRL-C was
877pressed, the number -1 is passed to the callback.
Bram Moolenaar3397f742019-06-02 18:40:06 +0200878
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200879Example: >
880 func SelectedColor(id, result)
881 echo 'choice made: ' .. a:result
882 endfunc
883
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200884
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200885POPUP SCROLLBAR *popup-scrollbar*
886
887If the text does not fit in the popup a scrollbar is displayed on the right of
888the window. This can be disabled by setting the "scrollbar" option to zero.
889When the scrollbar is displayed mouse scroll events, while the mouse pointer
890is on the popup, will cause the text to scroll up or down as you would expect.
Bram Moolenaar85850f32019-07-19 22:05:51 +0200891A click in the upper half of the scrollbar will scroll the text down one line.
892A click in the lower half will scroll the text up one line. However, this is
893limited so that the popup does not get smaller.
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200894
895
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200896POPUP MASK *popup-mask*
897
898To minimize the text that the popup covers, parts of it can be made
899transparent. This is defined by a "mask" which is a list of lists, where each
900list has four numbers:
901 col start column, positive for counting from the left, 1 for
902 leftmost, negative for counting from the right, -1 for
903 rightmost
904 endcol last column, like "col"
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200905 line start line, positive for counting from the top, 1 for top,
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200906 negative for counting from the bottom, -1 for bottom
907 endline end line, like "line"
908
909For example, to make the last 10 columns of the last line transparent:
910 [[-10, -1, -1, -1]]
911
912To make the four corners transparent:
913 [[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]
914
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200915==============================================================================
Bram Moolenaar931a2772019-07-04 16:54:54 +02009164. Examples *popup-examples*
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200917
Bram Moolenaar931a2772019-07-04 16:54:54 +0200918TODO: more interesting examples
Bram Moolenaara3fce622019-06-20 02:31:49 +0200919 *popup_dialog-example*
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200920Prompt the user to press y/Y or n/N: >
921
922 func MyDialogHandler(id, result)
923 if a:result
924 " ... 'y' or 'Y' was pressed
925 endif
926 endfunc
927
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200928 call popup_dialog('Continue? y/n', #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200929 \ filter: 'popup_filter_yesno',
930 \ callback: 'MyDialogHandler',
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200931 \ })
932<
Bram Moolenaara3fce622019-06-20 02:31:49 +0200933 *popup_menu-shortcut-example*
934Extend popup_filter_menu() with shortcut keys: >
935
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200936 call popup_menu(['Save', 'Cancel', 'Discard'], #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200937 \ filter: 'MyMenuFilter',
938 \ callback: 'MyMenuHandler',
Bram Moolenaara3fce622019-06-20 02:31:49 +0200939 \ })
940
941 func MyMenuFilter(id, key)
942 " Handle shortcuts
943 if a:key == 'S'
944 call popup_close(a:id, 1)
945 return 1
946 endif
947 if a:key == 'C'
948 call popup_close(a:id, 2)
949 return 1
950 endif
951 if a:key == 'D'
952 call popup_close(a:id, 3)
953 return 1
954 endif
955
956 " No shortcut, pass to generic filter
957 return popup_filter_menu(a:id, a:key)
958 endfunc
959<
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200960 *popup_beval_example*
961Example for using a popup window for 'ballooneval': >
962
963 set ballooneval balloonevalterm
964 set balloonexpr=BalloonExpr()
965 let s:winid = 0
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200966 let s:last_text = ''
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200967
968 func BalloonExpr()
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200969 if s:winid && popup_getpos(s:winid) != {}
970 " previous popup window still shows
971 if v:beval_text == s:last_text
972 " Still the same text, keep the existing popup
973 return ''
974 endif
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200975 call popup_close(s:winid)
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200976 endif
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200977 let s:winid = popup_beval(v:beval_text, #{mousemoved: 'word'})
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200978 let s:last_text = v:beval_text
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200979 return ''
980 endfunc
981<
982If the text has to be obtained asynchronously return an empty string from the
983expression function and call popup_beval() once the text is available. In
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200984this example simulated with a timer callback: >
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200985
986 set ballooneval balloonevalterm
987 set balloonexpr=BalloonExpr()
988 let s:winid = 0
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200989 let s:balloonText = ''
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200990
991 func BalloonExpr()
Bram Moolenaarb05caa72019-07-10 21:55:54 +0200992 if s:winid && popup_getpos(s:winid) != {}
993 " previous popup window still shows
994 if v:beval_text == s:balloonText
995 " Still the same text, keep the existing popup
996 return ''
997 endif
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200998 call popup_close(s:winid)
999 let s:winid = 0
1000 endif
Bram Moolenaar581ba392019-09-03 22:08:33 +02001001 " simulate an asynchronous lookup for the text to display
Bram Moolenaarb05caa72019-07-10 21:55:54 +02001002 let s:balloonText = v:beval_text
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001003 call timer_start(100, 'ShowPopup')
1004 return ''
1005 endfunc
1006
1007 func ShowPopup(id)
Bram Moolenaar4c6d9042019-07-16 22:04:02 +02001008 let s:winid = popup_beval(s:balloonText, #{mousemoved: 'word'})
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001009 endfunc
1010<
Bram Moolenaar957f85d2019-05-12 21:43:48 +02001011
1012 vim:tw=78:ts=8:noet:ft=help:norl: