blob: 5950c4753dc5be2bf3058290f93d9059a66aa4a3 [file] [log] [blame]
Bram Moolenaar47e13952020-05-12 22:49:12 +02001*popup.txt* For Vim version 8.2. Last change: 2020 May 12
Bram Moolenaar957f85d2019-05-12 21:43:48 +02002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
Bram Moolenaar91359012019-11-30 17:57:03 +01007Displaying text in a floating window. *popup* *popup-window* *popupwin*
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 Moolenaar560979e2020-02-04 22:53:05 +010014 Terminal in popup window |popup-terminal|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200152. Functions |popup-functions|
Bram Moolenaar931a2772019-07-04 16:54:54 +020016 Details |popup-function-details|
173. Usage |popup-usage|
18 popup_create() arguments |popup_create-arguments|
19 Popup text properties |popup-props|
Bram Moolenaar12034e22019-08-25 22:25:02 +020020 Position popup with textprop |popup-textprop-pos|
Bram Moolenaar931a2772019-07-04 16:54:54 +020021 Popup filter |popup-filter|
22 Popup callback |popup-callback|
23 Popup scrollbar |popup-scrollbar|
24 Popup mask |popup-mask|
254. Examples |popup-examples|
Bram Moolenaar957f85d2019-05-12 21:43:48 +020026
27
Bram Moolenaar4ceaa3a2019-12-03 22:49:09 +010028{not available if the |+popupwin| feature was disabled at compile time}
Bram Moolenaar957f85d2019-05-12 21:43:48 +020029
30==============================================================================
311. Introduction *popup-intro*
32
Bram Moolenaar5c017b22019-05-21 23:09:01 +020033We are talking about popup windows here, text that goes on top of the regular
34windows and is under control of a plugin. You cannot edit the text in the
35popup window like with regular windows.
36
37A popup window can be used for such things as:
Bram Moolenaar68e65602019-05-26 21:33:31 +020038- briefly show a message without overwriting the command line
Bram Moolenaar5c017b22019-05-21 23:09:01 +020039- prompt the user with a dialog
Bram Moolenaar4d784b22019-05-25 19:51:39 +020040- display contextual information while typing
Bram Moolenaar5c017b22019-05-21 23:09:01 +020041- give extra information for auto-completion
42
43The text in the popup window can be colored with |text-properties|. It is
44also possible to use syntax highlighting.
45
Bram Moolenaar4d784b22019-05-25 19:51:39 +020046The default color used is "Pmenu". If you prefer something else use the
47"highlight" argument or the 'wincolor' option, e.g.: >
48 hi MyPopupColor ctermbg=lightblue guibg=lightblue
49 call setwinvar(winid, '&wincolor', 'MyPopupColor')
50
Bram Moolenaar68d48f42019-06-12 22:42:41 +020051'hlsearch' highlighting is not displayed in a popup window.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020052
Bram Moolenaar5c017b22019-05-21 23:09:01 +020053A popup window has a window-ID like other windows, but behaves differently.
54The size can be up to the whole Vim window and it overlaps other windows.
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +020055Popup windows can also overlap each other. The "zindex" property specifies
56what goes on top of what.
Bram Moolenaar68e65602019-05-26 21:33:31 +020057
58The popup window contains a buffer, and that buffer is always associated with
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +020059the popup window. The window cannot be in Normal, Visual or Insert mode, it
60does not get keyboard focus. You can use functions like `setbufline()` to
Bram Moolenaar68e65602019-05-26 21:33:31 +020061change the text in the buffer. There are more differences from how this
62window and buffer behave compared to regular windows and buffers, see
63|popup-buffer|.
Bram Moolenaar5c017b22019-05-21 23:09:01 +020064
65If this is not what you are looking for, check out other popup functionality:
Bram Moolenaar957f85d2019-05-12 21:43:48 +020066- popup menu, see |popup-menu|
67- balloon, see |balloon-eval|
68
Bram Moolenaar5c017b22019-05-21 23:09:01 +020069
Bram Moolenaar931a2772019-07-04 16:54:54 +020070WINDOW POSITION AND SIZE *popup-position*
Bram Moolenaar4d784b22019-05-25 19:51:39 +020071
Bram Moolenaar68e65602019-05-26 21:33:31 +020072The height of the window is normally equal to the number of, possibly
73wrapping, lines in the buffer. It can be limited with the "maxheight"
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020074property. You can use empty lines to increase the height or the "minheight"
75property.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020076
77The width of the window is normally equal to the longest line in the buffer.
78It can be limited with the "maxwidth" property. You can use spaces to
Bram Moolenaar68d48f42019-06-12 22:42:41 +020079increase the width or use the "minwidth" property.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020080
Bram Moolenaar042fb4b2019-06-02 14:49:56 +020081By default the 'wrap' option is set, so that no text disappears. Otherwise,
82if there is not enough space then the window is shifted left in order to
Bram Moolenaar2e62b562019-06-30 18:07:00 +020083display more text. When right-aligned the window is shifted right to display
84more text. The shifting can be disabled with the "fixed" property.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020085
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020086Vim tries to show the popup in the location you specify. In some cases, e.g.
87when the popup would go outside of the Vim window, it will show it somewhere
Bram Moolenaar2e62b562019-06-30 18:07:00 +020088nearby. E.g. if you use `popup_atcursor()` the popup normally shows just above
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020089the current cursor position, but if the cursor is close to the top of the Vim
90window it will be placed below the cursor position.
91
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +020092When the screen scrolls up for output of an Ex command, popups move too, so
93that they will not cover the output.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020094
Bram Moolenaar68d48f42019-06-12 22:42:41 +020095The current cursor position is displayed even when it is under a popup window.
96That way you can still see where it is, even though you cannot see the text
97that it is in.
Bram Moolenaar868b7b62019-05-29 21:44:40 +020098
Bram Moolenaar5c017b22019-05-21 23:09:01 +020099
Bram Moolenaar931a2772019-07-04 16:54:54 +0200100CLOSING THE POPUP WINDOW *popup-close*
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200101
102Normally the plugin that created the popup window is also in charge of closing
103it. If somehow a popup hangs around, you can close all of them with: >
104 call popup_clear()
105Some popups, such as notifications, close after a specified time. This can be
106set with the "time" property on `popup_create()`.
107Otherwise, a popup can be closed by clicking on the X in the top-right corner
108or by clicking anywhere inside the popup. This must be enabled with the
109"close" property. It is set by default for notifications.
110
111
Bram Moolenaar931a2772019-07-04 16:54:54 +0200112POPUP BUFFER AND WINDOW *popup-buffer*
113
114If a popup function is called to create a popup from text, a new buffer is
115created to hold the text and text properties of the popup window. The buffer
116is always associated with the popup window and manipulation is restricted:
117- the buffer has no name
118- 'buftype' is "popup"
119- 'swapfile' is off
120- 'bufhidden' is "hide"
121- 'buflisted' is off
122- 'undolevels' is -1: no undo at all
123- all other buffer-local and window-local options are set to their Vim default
124 value.
125
126It is possible to change the specifically mentioned options, but anything
127might break then, so better leave them alone.
128
Bram Moolenaar06fe74a2019-08-31 16:20:32 +0200129The window does have a cursor position, but the cursor is not displayed. In
130fact, the cursor in the underlying window is displayed, as if it peeks through
131the popup, so you can see where it is.
Bram Moolenaar931a2772019-07-04 16:54:54 +0200132
133To execute a command in the context of the popup window and buffer use
134`win_execute()`. Example: >
135 call win_execute(winid, 'syntax enable')
136
137Options can be set on the window with `setwinvar()`, e.g.: >
138 call setwinvar(winid, '&wrap', 0)
139And options can be set on the buffer with `setbufvar()`, e.g.: >
140 call setbufvar(winbufnr(winid), '&filetype', 'java')
Bram Moolenaare0d749a2019-09-25 22:14:48 +0200141You can also use `win_execute()` with a ":setlocal" command.
Bram Moolenaar931a2772019-07-04 16:54:54 +0200142
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200143
Bram Moolenaar560979e2020-02-04 22:53:05 +0100144TERMINAL IN POPUP WINDOW *popup-terminal*
145
146A special case is running a terminal in a popup window. Many rules are then
147different: *E863*
148- The popup window always has focus, it is not possible to switch to another
149 window.
150- When the job ends, the popup window closes.
Bram Moolenaar11ec8072020-02-20 20:12:29 +0100151- The popup window can be closed with `popup_close()`, the terminal buffer
152 then becomes hidden.
Bram Moolenaar47e13952020-05-12 22:49:12 +0200153- It is not possible to enter Terminal-Normal mode.
Bram Moolenaar560979e2020-02-04 22:53:05 +0100154- The default Pmenu color is only used for the border and padding. To change
Bram Moolenaar191acfd2020-03-27 20:42:43 +0100155 the color of the terminal itself set the Terminal highlight group before
156 creating the terminal. Setting 'wincolor' later can work but requires the
157 program in the terminal to redraw everything.
Bram Moolenaarff781552020-03-19 20:37:11 +0100158- The default minimal size is 5 lines of 20 characters; Use the "minwidth" and
159 "minheight" parameters to set a different value.
Bram Moolenaar191acfd2020-03-27 20:42:43 +0100160- The terminal size will grow if the program running in the terminal writes
161 text. Set "maxheight" and "maxwidth" to restrict the size.
Bram Moolenaar560979e2020-02-04 22:53:05 +0100162
163To run a terminal in a popup window, first create the terminal hidden. Then
164pass the buffer number to popup_create(). Example: >
Bram Moolenaar191acfd2020-03-27 20:42:43 +0100165 hi link Terminal Search
Bram Moolenaar560979e2020-02-04 22:53:05 +0100166 let buf = term_start(['picker', 'Something'], #{hidden: 1, term_finish: 'close'})
167 let winid = popup_create(buf, #{minwidth: 50, minheight: 20})
Bram Moolenaar560979e2020-02-04 22:53:05 +0100168
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200169==============================================================================
1702. Functions *popup-functions*
171
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200172Creating a popup window:
173 |popup_create()| centered in the screen
174 |popup_atcursor()| just above the cursor position, closes when
175 the cursor moves away
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200176 |popup_beval()| at the position indicated by v:beval_
177 variables, closes when the mouse moves away
Bram Moolenaara3fce622019-06-20 02:31:49 +0200178 |popup_notification()| show a notification for three seconds
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200179 |popup_dialog()| centered with padding and border
180 |popup_menu()| prompt for selecting an item from a list
181
182Manipulating a popup window:
183 |popup_hide()| hide a popup temporarily
184 |popup_show()| show a previously hidden popup
185 |popup_move()| change the position and size of a popup
186 |popup_setoptions()| override options of a popup
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200187 |popup_settext()| replace the popup buffer contents
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200188
189Closing popup windows:
190 |popup_close()| close one popup
191 |popup_clear()| close all popups
192
193Filter functions:
194 |popup_filter_menu()| select from a list of items
195 |popup_filter_yesno()| blocks until 'y' or 'n' is pressed
196
197Other:
198 |popup_getoptions()| get current options for a popup
199 |popup_getpos()| get actual position and size of a popup
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200200 |popup_locate()| find popup window at a screen position
Bram Moolenaaref6b9792020-05-13 16:34:15 +0200201 |popup_list()| get list of all popups
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200202
203
Bram Moolenaar931a2772019-07-04 16:54:54 +0200204DETAILS *popup-function-details*
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200205
Bram Moolenaar931a2772019-07-04 16:54:54 +0200206popup_atcursor({what}, {options}) *popup_atcursor()*
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200207 Show the {what} above the cursor, and close it when the cursor
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200208 moves. This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200209 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200210 \ pos: 'botleft',
211 \ line: 'cursor-1',
212 \ col: 'cursor',
213 \ moved: 'WORD',
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200214 \ })
215< Use {options} to change the properties.
Bram Moolenaar4dd8fe02019-11-09 15:33:31 +0100216 If "pos" is passed as "topleft" then the default for "line"
217 becomes "cursor+1".
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200218
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200219 Can also be used as a |method|: >
220 GetText()->popup_atcursor({})
221
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200222
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200223popup_beval({what}, {options}) *popup_beval()*
224 Show the {what} above the position from 'ballooneval' and
225 close it when the mouse moves. This works like: >
226 let pos = screenpos(v:beval_winnr, v:beval_lnum, v:beval_col)
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200227 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200228 \ pos: 'botleft',
229 \ line: pos.row - 1,
230 \ col: pos.col,
231 \ mousemoved: 'WORD',
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200232 \ })
233< Use {options} to change the properties.
Bram Moolenaar8fe10002019-09-11 22:56:44 +0200234 See |popup_beval_example| for an example.
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200235
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200236 Can also be used as a |method|: >
237 GetText()->popup_beval({})
238<
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200239 *popup_clear()*
Bram Moolenaar03a9f842020-05-13 13:40:16 +0200240popup_clear([{force}])
241 Emergency solution to a misbehaving plugin: close all popup
Bram Moolenaara3fce622019-06-20 02:31:49 +0200242 windows for the current tab and global popups.
Bram Moolenaar03a9f842020-05-13 13:40:16 +0200243 Close callbacks are not invoked.
244 When {force} is not present this will fail if the current
245 window is a popup.
246 When {force} is present and |TRUE| the popup is also closed
247 when it is the current window. If a terminal is running in a
248 popup it is killed.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200249
250
251popup_close({id} [, {result}]) *popup_close()*
252 Close popup {id}. The window and the associated buffer will
253 be deleted.
254
255 If the popup has a callback it will be called just before the
256 popup window is deleted. If the optional {result} is present
257 it will be passed as the second argument of the callback.
258 Otherwise zero is passed to the callback.
259
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200260 Can also be used as a |method|: >
261 GetPopup()->popup_close()
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200262
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200263popup_create({what}, {options}) *popup_create()*
264 Open a popup window showing {what}, which is either:
265 - a buffer number
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200266 - a string
267 - a list of strings
268 - a list of text lines with text properties
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200269 When {what} is not a buffer number, a buffer is created with
270 'buftype' set to "popup". That buffer will be wiped out once
271 the popup closes.
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200272
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200273 {options} is a dictionary with many possible entries.
Bram Moolenaar931a2772019-07-04 16:54:54 +0200274 See |popup_create-arguments| for details.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200275
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200276 Returns a window-ID, which can be used with other popup
277 functions. Use `winbufnr()` to get the number of the buffer
278 in the window: >
279 let winid = popup_create('hello', {})
280 let bufnr = winbufnr(winid)
281 call setbufline(bufnr, 2, 'second line')
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200282< In case of failure zero is returned.
283
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200284 Can also be used as a |method|: >
285 GetText()->popup_create({})
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200286
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200287popup_dialog({what}, {options}) *popup_dialog()*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200288 Just like |popup_create()| but with these default options: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200289 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200290 \ pos: 'center',
291 \ zindex: 200,
292 \ drag: 1,
293 \ border: [],
294 \ padding: [],
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200295 \ mapping: 0,
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200296 \})
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200297< Use {options} to change the properties. E.g. add a 'filter'
Bram Moolenaara42d9452019-06-15 21:46:30 +0200298 option with value 'popup_filter_yesno'. Example: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200299 call popup_create('do you want to quit (Yes/no)?', #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200300 \ filter: 'popup_filter_yesno',
301 \ callback: 'QuitCallback',
Bram Moolenaara42d9452019-06-15 21:46:30 +0200302 \ })
303
304< By default the dialog can be dragged, so that text below it
305 can be read if needed.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200306
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200307 Can also be used as a |method|: >
308 GetText()->popup_dialog({})
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200309
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200310popup_filter_menu({id}, {key}) *popup_filter_menu()*
Bram Moolenaara730e552019-06-16 19:05:31 +0200311 Filter that can be used for a popup. These keys can be used:
Bram Moolenaara3fce622019-06-20 02:31:49 +0200312 j <Down> select item below
Bram Moolenaara730e552019-06-16 19:05:31 +0200313 k <Up> select item above
314 <Space> <Enter> accept current selection
315 x Esc CTRL-C cancel the menu
316 Other keys are ignored.
317
318 A match is set on that line to highlight it, see
319 |popup_menu()|.
320
321 When the current selection is accepted the "callback" of the
322 popup menu is invoked with the index of the selected line as
323 the second argument. The first entry has index one.
324 Cancelling the menu invokes the callback with -1.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200325
Bram Moolenaara3fce622019-06-20 02:31:49 +0200326 To add shortcut keys, see the example here:
327 |popup_menu-shortcut-example|
328
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200329
330popup_filter_yesno({id}, {key}) *popup_filter_yesno()*
331 Filter that can be used for a popup. It handles only the keys
332 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the
333 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N'
Bram Moolenaara42d9452019-06-15 21:46:30 +0200334 as the second argument. Pressing Esc and 'x' works like
335 pressing 'n'. CTRL-C invokes the callback with -1. Other
336 keys are ignored.
Bram Moolenaara3fce622019-06-20 02:31:49 +0200337 See the example here: |popup_dialog-example|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200338
339
Bram Moolenaarc7c5f102019-08-21 18:31:03 +0200340popup_findinfo() *popup_findinfo()*
341 Get the |window-ID| for the popup info window, as it used by
342 the popup menu. See |complete-popup|. The info popup is
343 hidden when not used, it can be deleted with |popup_clear()|
Bram Moolenaar96f45c02019-10-26 19:53:45 +0200344 and |popup_close()|. Use |popup_show()| to reposition it to
345 the item in the popup menu.
346 Returns zero if there is none.
Bram Moolenaarc7c5f102019-08-21 18:31:03 +0200347
348
349popup_findpreview() *popup_findpreview()*
350 Get the |window-ID| for the popup preview window.
351 Return zero if there is none.
352
353
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200354popup_getoptions({id}) *popup_getoptions()*
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200355 Return the {options} for popup {id} in a Dict.
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200356 A zero value means the option was not set. For "zindex" the
357 default value is returned, not zero.
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200358
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200359 The "moved" entry is a list with line number, minimum and
360 maximum column, [0, 0, 0] when not set.
361
362 The "mousemoved" entry is a list with screen row, minimum and
363 maximum screen column, [0, 0, 0] when not set.
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200364
Bram Moolenaar06fe74a2019-08-31 16:20:32 +0200365 "firstline" is the property set on the popup, unlike the
366 "firstline" obtained with |popup_getpos()| which is the actual
367 buffer line at the top of the popup window.
368
Bram Moolenaarae943152019-06-16 22:54:14 +0200369 "border" and "padding" are not included when all values are
370 zero. When all values are one then an empty list is included.
371
372 "borderhighlight" is not included when all values are empty.
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200373 "scrollbarhighlight" and "thumbhighlight" are only included
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200374 when set.
Bram Moolenaarae943152019-06-16 22:54:14 +0200375
Bram Moolenaara3fce622019-06-20 02:31:49 +0200376 "tabpage" will be -1 for a global popup, zero for a popup on
377 the current tabpage and a positive number for a popup on
378 another tabpage.
379
Bram Moolenaar12034e22019-08-25 22:25:02 +0200380 "textprop", "textpropid" and "textpropwin" are only present
381 when "textprop" was set.
382
Bram Moolenaarae943152019-06-16 22:54:14 +0200383 If popup window {id} is not found an empty Dict is returned.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200384
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200385 Can also be used as a |method|: >
386 GetPopup()->popup_getoptions()
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200387
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200388popup_getpos({id}) *popup_getpos()*
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200389 Return the position and size of popup {id}. Returns a Dict
390 with these entries:
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200391 col screen column of the popup, one-based
392 line screen line of the popup, one-based
Bram Moolenaar2fd8e352019-06-01 20:16:48 +0200393 width width of the whole popup in screen cells
394 height height of the whole popup in screen cells
395 core_col screen column of the text box
396 core_line screen line of the text box
397 core_width width of the text box in screen cells
398 core_height height of the text box in screen cells
Bram Moolenaar68acb412019-06-26 03:40:36 +0200399 firstline line of the buffer at top (1 unless scrolled)
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200400 (not the value of the "firstline" property)
Bram Moolenaar4dd8fe02019-11-09 15:33:31 +0100401 lastline line of the buffer at the bottom (updated when
402 the popup is redrawn)
Bram Moolenaar68acb412019-06-26 03:40:36 +0200403 scrollbar non-zero if a scrollbar is displayed
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200404 visible one if the popup is displayed, zero if hidden
Bram Moolenaarbc133542019-05-29 20:26:46 +0200405 Note that these are the actual screen positions. They differ
406 from the values in `popup_getoptions()` for the sizing and
407 positioning mechanism applied.
Bram Moolenaar2fd8e352019-06-01 20:16:48 +0200408
409 The "core_" values exclude the padding and border.
410
Bram Moolenaarbc133542019-05-29 20:26:46 +0200411 If popup window {id} is not found an empty Dict is returned.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200412
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200413 Can also be used as a |method|: >
414 GetPopup()->popup_getpos()
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200415
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200416popup_hide({id}) *popup_hide()*
417 If {id} is a displayed popup, hide it now. If the popup has a
418 filter it will not be invoked for so long as the popup is
419 hidden.
420 If window {id} does not exist nothing happens. If window {id}
421 exists but is not a popup window an error is given. *E993*
Bram Moolenaarebdf3c92020-02-15 21:41:42 +0100422 If popup window {id} contains a terminal an error is given.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200423
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200424 Can also be used as a |method|: >
425 GetPopup()->popup_hide()
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200426
Bram Moolenaaref6b9792020-05-13 16:34:15 +0200427popup_list() *popup_list()*
428 Return a List with the |window-ID| of all existing popups.
429
430
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200431popup_locate({row}, {col}) *popup_locate()*
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200432 Return the |window-ID| of the popup at screen position {row}
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200433 and {col}. If there are multiple popups the one with the
434 highest zindex is returned. If there are no popups at this
435 position then zero is returned.
436
437
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200438popup_menu({what}, {options}) *popup_menu()*
439 Show the {what} near the cursor, handle selecting one of the
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200440 items with cursorkeys, and close it an item is selected with
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200441 Space or Enter. {what} should have multiple lines to make this
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200442 useful. This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200443 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200444 \ pos: 'center',
445 \ zindex: 200,
446 \ drag: 1,
447 \ wrap: 0,
448 \ border: [],
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200449 \ cursorline: 1,
Bram Moolenaar03464132019-07-14 16:28:13 +0200450 \ padding: [0,1,0,1],
Bram Moolenaar396e8292019-07-13 23:04:31 +0200451 \ filter: 'popup_filter_menu',
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200452 \ mapping: 0,
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200453 \ })
Bram Moolenaara730e552019-06-16 19:05:31 +0200454< The current line is highlighted with a match using
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200455 "PopupSelected", or "PmenuSel" if that is not defined.
Bram Moolenaara730e552019-06-16 19:05:31 +0200456
457 Use {options} to change the properties. Should at least set
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200458 "callback" to a function that handles the selected item.
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200459 Example: >
460 func ColorSelected(id, result)
461 " use a:result
462 endfunc
463 call popup_menu(['red', 'green', 'blue'], #{
464 \ callback: 'ColorSelected',
465 \ })
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200466
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200467< Can also be used as a |method|: >
468 GetChoices()->popup_menu({})
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200469
470popup_move({id}, {options}) *popup_move()*
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200471 Move popup {id} to the position specified with {options}.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200472 {options} may contain the items from |popup_create()| that
Bram Moolenaarae943152019-06-16 22:54:14 +0200473 specify the popup position:
474 line
475 col
476 pos
477 maxheight
478 minheight
479 maxwidth
480 minwidth
481 fixed
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200482 For {id} see `popup_hide()`.
Bram Moolenaarae943152019-06-16 22:54:14 +0200483 For other options see |popup_setoptions()|.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200484
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200485 Can also be used as a |method|: >
486 GetPopup()->popup_move(options)
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200487
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200488popup_notification({what}, {options}) *popup_notification()*
489 Show the {what} for 3 seconds at the top of the Vim window.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200490 This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200491 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200492 \ line: 1,
493 \ col: 10,
494 \ minwidth: 20,
495 \ time: 3000,
496 \ tabpage: -1,
497 \ zindex: 300,
498 \ drag: 1,
499 \ highlight: 'WarningMsg',
500 \ border: [],
501 \ close: 'click',
502 \ padding: [0,1,0,1],
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200503 \ })
Bram Moolenaardfa97f22019-06-15 14:31:55 +0200504< The PopupNotification highlight group is used instead of
505 WarningMsg if it is defined.
Bram Moolenaara730e552019-06-16 19:05:31 +0200506
Bram Moolenaar581ba392019-09-03 22:08:33 +0200507 Without the |+timers| feature the popup will not disappear
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200508 automatically, the user has to click in it.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200509
Bram Moolenaara730e552019-06-16 19:05:31 +0200510 The position will be adjusted to avoid overlap with other
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200511 notifications.
512 Use {options} to change the properties.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200513
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200514 Can also be used as a |method|: >
515 GetText()->popup_notification({})
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200516
517popup_show({id}) *popup_show()*
518 If {id} is a hidden popup, show it now.
519 For {id} see `popup_hide()`.
Bram Moolenaara1396152019-10-20 18:46:05 +0200520 If {id} is the info popup it will be positioned next to the
521 current popup menu item.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200522
523
524popup_setoptions({id}, {options}) *popup_setoptions()*
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200525 Override options in popup {id} with entries in {options}.
Bram Moolenaarae943152019-06-16 22:54:14 +0200526 These options can be set:
Bram Moolenaarae943152019-06-16 22:54:14 +0200527 border
Bram Moolenaarae943152019-06-16 22:54:14 +0200528 borderchars
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200529 borderhighlight
530 callback
531 close
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200532 cursorline
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200533 drag
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200534 filter
535 firstline
536 flip
537 highlight
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200538 mapping
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200539 mask
540 moved
541 padding
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200542 resize
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200543 scrollbar
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200544 scrollbarhighlight
545 thumbhighlight
Bram Moolenaarae943152019-06-16 22:54:14 +0200546 time
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200547 title
548 wrap
549 zindex
Bram Moolenaarae943152019-06-16 22:54:14 +0200550 The options from |popup_move()| can also be used.
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200551 Generally, setting an option to zero or an empty string resets
552 it to the default value, but there are exceptions.
Bram Moolenaarae943152019-06-16 22:54:14 +0200553 For "hidden" use |popup_hide()| and |popup_show()|.
554 "tabpage" cannot be changed.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200555
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200556 Can also be used as a |method|: >
557 GetPopup()->popup_setoptions(options)
558
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200559popup_settext({id}, {text}) *popup_settext()*
Bram Moolenaar581ba392019-09-03 22:08:33 +0200560 Set the text of the buffer in popup win {id}. {text} is the
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200561 same as supplied to |popup_create()|, except that a buffer
562 number is not allowed.
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200563 Does not change the window size or position, other than caused
564 by the different text.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200565
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200566 Can also be used as a |method|: >
567 GetPopup()->popup_settext('hello')
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200568
Bram Moolenaar931a2772019-07-04 16:54:54 +0200569==============================================================================
5703. Usage *popup-usage*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200571
Bram Moolenaar931a2772019-07-04 16:54:54 +0200572POPUP_CREATE() ARGUMENTS *popup_create-arguments*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200573
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200574The first argument of |popup_create()| (and the second argument to
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200575|popup_settext()|) specifies the text to be displayed, and optionally text
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200576properties. It is in one of four forms:
577- a buffer number
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200578- a string
579- a list of strings
580- a list of dictionaries, where each dictionary has these entries:
581 text String with the text to display.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200582 props A list of text properties. Optional.
583 Each entry is a dictionary, like the third argument of
584 |prop_add()|, but specifying the column in the
585 dictionary with a "col" entry, see below:
586 |popup-props|.
587
Bram Moolenaare0d749a2019-09-25 22:14:48 +0200588If you want to create a new buffer yourself use |bufadd()| and pass the buffer
589number to popup_create().
Bram Moolenaarff781552020-03-19 20:37:11 +0100590It is not possible to use the buffer of a terminal window. *E278* You CAN
591create a hidden terminal buffer and use that one in a popup window.
Bram Moolenaare0d749a2019-09-25 22:14:48 +0200592
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200593The second argument of |popup_create()| is a dictionary with options:
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200594 line Screen line where to position the popup. Can use a
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200595 number or "cursor", "cursor+1" or "cursor-1" to use
596 the line of the cursor and add or subtract a number of
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200597 lines. If omitted or zero the popup is vertically
598 centered. The first line is 1.
Bram Moolenaar12034e22019-08-25 22:25:02 +0200599 When using "textprop" the number is relative to the
600 text property and can be negative.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200601 col Screen column where to position the popup. Can use a
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200602 number or "cursor" to use the column of the cursor,
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200603 "cursor+9" or "cursor-9" to add or subtract a number
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200604 of columns. If omitted or zero the popup is
605 horizontally centered. The first column is 1.
Bram Moolenaar12034e22019-08-25 22:25:02 +0200606 When using "textprop" the number is relative to the
607 text property and can be negative.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200608 pos "topleft", "topright", "botleft" or "botright":
609 defines what corner of the popup "line" and "col" are
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200610 used for. When not set "topleft" is used.
611 Alternatively "center" can be used to position the
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200612 popup in the center of the Vim window, in which case
613 "line" and "col" are ignored.
Bram Moolenaar4dd8fe02019-11-09 15:33:31 +0100614 posinvert When FALSE the value of "pos" is always used. When
615 TRUE (the default) and the popup does not fit
616 vertically and there is more space on the other side
617 then the popup is placed on the other side of the
618 position indicated by "line".
Bram Moolenaar12034e22019-08-25 22:25:02 +0200619 textprop When present the popup is positioned next to a text
620 property with this name and will move when the text
621 property moves. Use an empty string to remove. See
622 |popup-textprop-pos|.
623 textpropwin What window to search for the text property. When
624 omitted or invalid the current window is used.
625 textpropid Used to identify the text property when "textprop" is
626 present. Use zero to reset.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200627 fixed When FALSE (the default), and:
628 - "pos" is "botleft" or "topleft", and
629 - "wrap" is off, and
630 - the popup would be truncated at the right edge of
631 the screen, then
632 the popup is moved to the left so as to fit the
633 contents on the screen. Set to TRUE to disable this.
634 flip When TRUE (the default) and the position is relative
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200635 to the cursor, flip to below or above the cursor to
636 avoid overlap with the |popupmenu-completion| or
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200637 another popup with a higher "zindex". When there is
638 no space above/below the cursor then show the popup to
639 the side of the popup or popup menu.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200640 {not implemented yet}
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200641 maxheight Maximum height of the contents, excluding border and
642 padding.
643 minheight Minimum height of the contents, excluding border and
644 padding.
Bram Moolenaar54775062019-07-31 21:07:14 +0200645 maxwidth Maximum width of the contents, excluding border,
646 padding and scrollbar.
647 minwidth Minimum width of the contents, excluding border,
648 padding and scrollbar.
Bram Moolenaar8d241042019-06-12 23:40:01 +0200649 firstline First buffer line to display. When larger than one it
650 looks like the text scrolled up. When out of range
651 the last buffer line will at the top of the window.
Bram Moolenaar06fe74a2019-08-31 16:20:32 +0200652 Set to zero to leave the position as set by commands.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200653 Also see "scrollbar".
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200654 hidden When TRUE the popup exists but is not displayed; use
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200655 `popup_show()` to unhide it.
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200656 tabpage When -1: display the popup on all tab pages.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200657 When 0 (the default): display the popup on the current
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +0200658 tab page.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200659 Otherwise the number of the tab page the popup is
Bram Moolenaara3fce622019-06-20 02:31:49 +0200660 displayed on; when invalid the popup is not created
Bram Moolenaarb2cda0d2019-06-24 05:06:36 +0200661 and an error is given. *E997*
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200662 title Text to be displayed above the first item in the
663 popup, on top of any border. If there is no top
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200664 border one line of padding is added to put the title
Bram Moolenaareb2310d2019-06-16 20:09:10 +0200665 on. You might want to add one or more spaces at the
666 start and end as padding.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200667 wrap TRUE to make the lines wrap (default TRUE).
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200668 drag TRUE to allow the popup to be dragged with the mouse
Bram Moolenaar581ba392019-09-03 22:08:33 +0200669 by grabbing at the border. Has no effect if the
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200670 popup does not have a border. As soon as dragging
671 starts and "pos" is "center" it is changed to
672 "topleft".
Bram Moolenaar9bcb70c2019-08-01 21:11:05 +0200673 resize TRUE to allow the popup to be resized with the mouse
Bram Moolenaar581ba392019-09-03 22:08:33 +0200674 by grabbing at the bottom right corner. Has no effect
675 if the popup does not have a border.
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200676 close When "button" an X is displayed in the top-right, on
677 top of any border, padding or text. When clicked on
678 the X the popup will close. Any callback is invoked
679 with the value -2.
680 When "click" any mouse click in the popup will close
681 it.
682 When "none" (the default) mouse clicks do not close
683 the popup window.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200684 highlight Highlight group name to use for the text, stored in
685 the 'wincolor' option.
686 padding List with numbers, defining the padding
687 above/right/below/left of the popup (similar to CSS).
688 An empty list uses a padding of 1 all around. The
689 padding goes around the text, inside any border.
690 Padding uses the 'wincolor' highlight.
691 Example: [1, 2, 1, 3] has 1 line of padding above, 2
692 columns on the right, 1 line below and 3 columns on
693 the left.
694 border List with numbers, defining the border thickness
695 above/right/below/left of the popup (similar to CSS).
696 Only values of zero and non-zero are recognized.
697 An empty list uses a border all around.
698 borderhighlight List of highlight group names to use for the border.
699 When one entry it is used for all borders, otherwise
700 the highlight for the top/right/bottom/left border.
701 Example: ['TopColor', 'RightColor', 'BottomColor,
702 'LeftColor']
703 borderchars List with characters, defining the character to use
704 for the top/right/bottom/left border. Optionally
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200705 followed by the character to use for the
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200706 topleft/topright/botright/botleft corner.
707 Example: ['-', '|', '-', '|', '┌', '┐', '┘', '└']
708 When the list has one character it is used for all.
709 When the list has two characters the first is used for
710 the border lines, the second for the corners.
711 By default a double line is used all around when
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200712 'encoding' is "utf-8" and 'ambiwidth' is "single",
Bram Moolenaara3fce622019-06-20 02:31:49 +0200713 otherwise ASCII characters are used.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200714 scrollbar non-zero: show a scrollbar when the text doesn't fit.
715 zero: do not show a scrollbar. Default is non-zero.
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200716 Also see |popup-scrollbar|.
717 scrollbarhighlight Highlight group name for the scrollbar. The
718 background color is what matters. When not given then
719 PmenuSbar is used.
720 thumbhighlight Highlight group name for the scrollbar thumb. The
721 background color is what matters. When not given then
722 PmenuThumb is used.
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200723 zindex Priority for the popup, default 50. Minimum value is
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200724 1, maximum value is 32000.
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200725 mask A list of lists with coordinates, defining parts of
726 the popup that are transparent. See |popup-mask|.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200727 time Time in milliseconds after which the popup will close.
728 When omitted |popup_close()| must be used.
Bram Moolenaar3397f742019-06-02 18:40:06 +0200729 moved Specifies to close the popup if the cursor moved:
730 - "any": if the cursor moved at all
731 - "word": if the cursor moved outside |<cword>|
732 - "WORD": if the cursor moved outside |<cWORD>|
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200733 - "expr": if the cursor moved outside |<cexpr>|
Bram Moolenaar3397f742019-06-02 18:40:06 +0200734 - [{start}, {end}]: if the cursor moved before column
735 {start} or after {end}
Bram Moolenaara1396152019-10-20 18:46:05 +0200736 - [{lnum}, {start}, {end}]: if the cursor moved away
737 from line {lnum}, before column {start} or after
738 {end}
Bram Moolenaar4dd8fe02019-11-09 15:33:31 +0100739 - [0, 0, 0] do not close the popup when the cursor
740 moves
Bram Moolenaar3397f742019-06-02 18:40:06 +0200741 The popup also closes if the cursor moves to another
742 line or to another window.
Bram Moolenaara1396152019-10-20 18:46:05 +0200743 mousemoved Like "moved" but referring to the mouse pointer
744 position
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200745 cursorline non-zero: Highlight the cursor line. Also scrolls the
746 text to show this line (only works properly
747 when 'wrap' is off).
748 zero: Do not highlight the cursor line.
749 Default is zero, except for |popup_menu()|.
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200750 filter A callback that can filter typed characters, see
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200751 |popup-filter|.
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200752 mapping Allow for key mapping. When FALSE and the popup is
753 visible and has a filter callback key mapping is
754 disabled. Default value is TRUE.
Bram Moolenaar581ba392019-09-03 22:08:33 +0200755 filtermode In which modes the filter is used (same flags as with
756 |hasmapto()| plus "a"):
757 n Normal mode
758 v Visual and Select mode
759 x Visual mode
760 s Select mode
761 o Operator-pending mode
762 i Insert mode
763 l Language-Argument ("r", "f", "t", etc.)
764 c Command-line mode
765 a all modes
766 The default value is "a".
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200767 callback A callback that is called when the popup closes, e.g.
768 when using |popup_filter_menu()|, see |popup-callback|.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200769
770Depending on the "zindex" the popup goes under or above other popups. The
771completion menu (|popup-menu|) has zindex 100. For messages that occur for a
772short time the suggestion is to use zindex 1000.
773
774By default text wraps, which causes a line in {lines} to occupy more than one
775screen line. When "wrap" is FALSE then the text outside of the popup or
776outside of the Vim window will not be displayed, thus truncated.
777
778
779POPUP TEXT PROPERTIES *popup-props*
780
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200781These are similar to the third argument of |prop_add()| except:
782- "lnum" is always the current line in the list
783- "bufnr" is always the buffer of the popup
784- "col" is in the Dict instead of a separate argument
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200785So we get:
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200786 col starting column, counted in bytes, use one for the
787 first column.
788 length length of text in bytes; can be zero
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200789 end_lnum line number for the end of the text
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200790 end_col column just after the text; not used when "length" is
791 present; when {col} and "end_col" are equal, this is a
792 zero-width text property
793 id user defined ID for the property; when omitted zero is
794 used
795 type name of the text property type, as added with
796 |prop_type_add()|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200797
798
Bram Moolenaar12034e22019-08-25 22:25:02 +0200799POSITION POPUP WITH TEXTPROP *popup-textprop-pos*
800
801Positioning a popup next to a text property causes the popup to move when text
802is inserted or deleted. The popup functions like a tooltip.
803
804These steps are needed to make this work:
805
806- Define a text property type, it defines the name. >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200807 call prop_type_add('popupMarker', {})
Bram Moolenaar12034e22019-08-25 22:25:02 +0200808
809- Place a text property at the desired text: >
810 let lnum = {line of the text}
811 let col = {start column of the text}
812 let len = {length of the text}
813 let propId = {arbitrary but unique number}
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200814 call prop_add(lnum, col, #{
Bram Moolenaar12034e22019-08-25 22:25:02 +0200815 \ length: len,
816 \ type: 'popupMarker',
817 \ id: propId,
818 \ })
819
820- Create a popup: >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200821 let winid = popup_create('the text', #{
822 \ pos: 'botleft',
Bram Moolenaar12034e22019-08-25 22:25:02 +0200823 \ textprop: 'popupMarker',
824 \ textpropid: propId,
825 \ border: [],
826 \ padding: [0,1,0,1],
827 \ close: 'click',
828 \ })
829
830By default the popup is positioned at the corner of the text, opposite of the
831"pos" specified for the popup. Thus when the popup uses "botleft", the
832bottom-left corner of the popup is positioned next to the top-right corner of
833the text property:
834 +----------+
835 | the text |
836 +----------+
837 just some PROPERTY as an example
838
839Here the text property is on "PROPERTY". Move the popup to the left by
840passing a negative "col" value to popup_create(). With "col: -5" you get:
841
842 +----------+
843 | the text |
844 +----------+
845 just some PROPERTY as an example
846
847If the text property moves out of view then the popup will be hidden.
848If the window for which the popup was defined is closed, the popup is closed.
849
850If the popup cannot fit in the desired position, it may show at a nearby
851position.
852
853Some hints:
854- To avoid collision with other plugins the text property type name has to be
855 unique. You can also use the "bufnr" item to make it local to a buffer.
856- You can leave out the text property ID if there is only ever one text
857 property visible.
858- The popup may be in the way of what the user is doing, making it close with
859 a click, as in the example above, helps for that.
860- If the text property is removed the popup is closed. Use something like
861 this: >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200862 call prop_remove(#{type: 'popupMarker', id: propId})
Bram Moolenaar12034e22019-08-25 22:25:02 +0200863
864
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200865POPUP FILTER *popup-filter*
866
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200867A callback that gets any typed keys while a popup is displayed. The filter is
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200868not invoked when the popup is hidden.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200869
870The filter can return TRUE to indicate the key has been handled and is to be
871discarded, or FALSE to let Vim handle the key as usual in the current state.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200872In case it returns FALSE and there is another popup window visible, that
873filter is also called. The filter of the popup window with the highest zindex
874is called first.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200875
876The filter function is called with two arguments: the ID of the popup and the
Bram Moolenaara42d9452019-06-15 21:46:30 +0200877key as a string, e.g.: >
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200878 func MyFilter(winid, key)
879 if a:key == "\<F2>"
880 " do something
881 return 1
882 endif
883 if a:key == 'x'
884 call popup_close(a:winid)
885 return 1
886 endif
887 return 0
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200888 endfunc
Bram Moolenaar581ba392019-09-03 22:08:33 +0200889< *popup-filter-mode*
890The "filtermode" property can be used to specify in what mode the filter is
891invoked. The default is "a": all modes. When using "nvi" Command-line mode
892is not included, so that any command typed on the command line is not
893filtered. However, to get to Command-line mode the filter must not consume
894":". Just like it must not consume "v" to allow for entering Visual mode.
895
896 *popup-mapping*
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200897Normally the key is what results after any mapping, since the keys pass on as
898normal input if the filter does not use it. If the filter consumes all the
899keys, set the "mapping" property to zero so that mappings do not get in the
900way. This is default for |popup_menu()| and |popup_dialog()|.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200901
Bram Moolenaar581ba392019-09-03 22:08:33 +0200902Some recommended key actions:
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200903 x close the popup (see note below)
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200904 cursor keys select another entry
905 Tab accept current suggestion
906
Bram Moolenaardb3a2052019-11-16 18:22:41 +0100907A mouse click arrives as <LeftMouse>. The coordinates can be obtained with
Bram Moolenaar09c6f262019-11-17 15:55:14 +0100908|getmousepos()|.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200909
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200910Vim provides standard filters |popup_filter_menu()| and
911|popup_filter_yesno()|.
912
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200913Note that "x" is the normal way to close a popup. You may want to use Esc,
914but since many keys start with an Esc character, there may be a delay before
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200915Vim recognizes the Esc key. If you do use Esc, it is recommended to set the
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200916'ttimeoutlen' option to 100 and set 'timeout' and/or 'ttimeout'.
917
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200918
919POPUP CALLBACK *popup-callback*
920
Bram Moolenaara42d9452019-06-15 21:46:30 +0200921A callback that is invoked when the popup closes.
Bram Moolenaar9eaac892019-06-01 22:49:29 +0200922
923The callback is invoked with two arguments: the ID of the popup window and the
924result, which could be an index in the popup lines, or whatever was passed as
925the second argument of `popup_close()`.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200926
Bram Moolenaara42d9452019-06-15 21:46:30 +0200927If the popup is force-closed, e.g. because the cursor moved or CTRL-C was
928pressed, the number -1 is passed to the callback.
Bram Moolenaar3397f742019-06-02 18:40:06 +0200929
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200930Example: >
931 func SelectedColor(id, result)
932 echo 'choice made: ' .. a:result
933 endfunc
934
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200935
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200936POPUP SCROLLBAR *popup-scrollbar*
937
938If the text does not fit in the popup a scrollbar is displayed on the right of
939the window. This can be disabled by setting the "scrollbar" option to zero.
940When the scrollbar is displayed mouse scroll events, while the mouse pointer
941is on the popup, will cause the text to scroll up or down as you would expect.
Bram Moolenaar85850f32019-07-19 22:05:51 +0200942A click in the upper half of the scrollbar will scroll the text down one line.
943A click in the lower half will scroll the text up one line. However, this is
944limited so that the popup does not get smaller.
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200945
946
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200947POPUP MASK *popup-mask*
948
949To minimize the text that the popup covers, parts of it can be made
950transparent. This is defined by a "mask" which is a list of lists, where each
951list has four numbers:
952 col start column, positive for counting from the left, 1 for
953 leftmost, negative for counting from the right, -1 for
954 rightmost
955 endcol last column, like "col"
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200956 line start line, positive for counting from the top, 1 for top,
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200957 negative for counting from the bottom, -1 for bottom
958 endline end line, like "line"
959
960For example, to make the last 10 columns of the last line transparent:
961 [[-10, -1, -1, -1]]
962
963To make the four corners transparent:
964 [[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]
965
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200966==============================================================================
Bram Moolenaar931a2772019-07-04 16:54:54 +02009674. Examples *popup-examples*
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200968
Bram Moolenaar931a2772019-07-04 16:54:54 +0200969TODO: more interesting examples
Bram Moolenaara3fce622019-06-20 02:31:49 +0200970 *popup_dialog-example*
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200971Prompt the user to press y/Y or n/N: >
972
973 func MyDialogHandler(id, result)
974 if a:result
975 " ... 'y' or 'Y' was pressed
976 endif
977 endfunc
978
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200979 call popup_dialog('Continue? y/n', #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200980 \ filter: 'popup_filter_yesno',
981 \ callback: 'MyDialogHandler',
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200982 \ })
983<
Bram Moolenaara3fce622019-06-20 02:31:49 +0200984 *popup_menu-shortcut-example*
985Extend popup_filter_menu() with shortcut keys: >
986
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200987 call popup_menu(['Save', 'Cancel', 'Discard'], #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200988 \ filter: 'MyMenuFilter',
989 \ callback: 'MyMenuHandler',
Bram Moolenaara3fce622019-06-20 02:31:49 +0200990 \ })
991
992 func MyMenuFilter(id, key)
993 " Handle shortcuts
994 if a:key == 'S'
995 call popup_close(a:id, 1)
996 return 1
997 endif
998 if a:key == 'C'
999 call popup_close(a:id, 2)
1000 return 1
1001 endif
1002 if a:key == 'D'
1003 call popup_close(a:id, 3)
1004 return 1
1005 endif
1006
1007 " No shortcut, pass to generic filter
1008 return popup_filter_menu(a:id, a:key)
1009 endfunc
1010<
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001011 *popup_beval_example*
1012Example for using a popup window for 'ballooneval': >
1013
1014 set ballooneval balloonevalterm
1015 set balloonexpr=BalloonExpr()
1016 let s:winid = 0
Bram Moolenaarb05caa72019-07-10 21:55:54 +02001017 let s:last_text = ''
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001018
1019 func BalloonExpr()
Bram Moolenaarb05caa72019-07-10 21:55:54 +02001020 if s:winid && popup_getpos(s:winid) != {}
1021 " previous popup window still shows
1022 if v:beval_text == s:last_text
1023 " Still the same text, keep the existing popup
1024 return ''
1025 endif
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001026 call popup_close(s:winid)
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001027 endif
Bram Moolenaar4c6d9042019-07-16 22:04:02 +02001028 let s:winid = popup_beval(v:beval_text, #{mousemoved: 'word'})
Bram Moolenaarb05caa72019-07-10 21:55:54 +02001029 let s:last_text = v:beval_text
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001030 return ''
1031 endfunc
1032<
1033If the text has to be obtained asynchronously return an empty string from the
1034expression function and call popup_beval() once the text is available. In
Bram Moolenaarb05caa72019-07-10 21:55:54 +02001035this example simulated with a timer callback: >
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001036
1037 set ballooneval balloonevalterm
1038 set balloonexpr=BalloonExpr()
1039 let s:winid = 0
Bram Moolenaarb05caa72019-07-10 21:55:54 +02001040 let s:balloonText = ''
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001041
1042 func BalloonExpr()
Bram Moolenaarb05caa72019-07-10 21:55:54 +02001043 if s:winid && popup_getpos(s:winid) != {}
1044 " previous popup window still shows
1045 if v:beval_text == s:balloonText
1046 " Still the same text, keep the existing popup
1047 return ''
1048 endif
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001049 call popup_close(s:winid)
1050 let s:winid = 0
1051 endif
Bram Moolenaar581ba392019-09-03 22:08:33 +02001052 " simulate an asynchronous lookup for the text to display
Bram Moolenaarb05caa72019-07-10 21:55:54 +02001053 let s:balloonText = v:beval_text
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001054 call timer_start(100, 'ShowPopup')
1055 return ''
1056 endfunc
1057
1058 func ShowPopup(id)
Bram Moolenaar4c6d9042019-07-16 22:04:02 +02001059 let s:winid = popup_beval(s:balloonText, #{mousemoved: 'word'})
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001060 endfunc
1061<
Bram Moolenaar957f85d2019-05-12 21:43:48 +02001062
1063 vim:tw=78:ts=8:noet:ft=help:norl: