blob: 1ad4fb9f07e0d2d0dc1a4a5965fe3e7439bb75b2 [file] [log] [blame]
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001*popup.txt* For Vim version 9.1. Last change: 2024 Jun 08
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 Moolenaar2f0936c2022-01-08 21:51:59 +000057 *E366*
Bram Moolenaar68e65602019-05-26 21:33:31 +020058The 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
Bram Moolenaare7b1ea02020-08-07 19:54:59 +020077The width of the window is normally equal to the longest visible line in the
78buffer. It can be limited with the "maxwidth" property. You can use spaces
79to increase the width or use the "minwidth" property.
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: >
Bram Moolenaar4466ad62020-11-21 13:16:30 +0100104 call popup_clear(1)
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200105Some 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.
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +0100150- When the job ends, the popup window shows the buffer in Terminal-Normal
151 mode. Use `:q` to close it or use "term_finish" value "close".
Bram Moolenaar11ec8072020-02-20 20:12:29 +0100152- The popup window can be closed with `popup_close()`, the terminal buffer
153 then becomes hidden.
Bram Moolenaarb5383b12020-05-18 19:46:48 +0200154- It is not possible to open a second popup window with a terminal. *E861*
Bram Moolenaar560979e2020-02-04 22:53:05 +0100155- The default Pmenu color is only used for the border and padding. To change
Bram Moolenaar191acfd2020-03-27 20:42:43 +0100156 the color of the terminal itself set the Terminal highlight group before
157 creating the terminal. Setting 'wincolor' later can work but requires the
158 program in the terminal to redraw everything.
Bram Moolenaarff781552020-03-19 20:37:11 +0100159- The default minimal size is 5 lines of 20 characters; Use the "minwidth" and
160 "minheight" parameters to set a different value.
Bram Moolenaar191acfd2020-03-27 20:42:43 +0100161- The terminal size will grow if the program running in the terminal writes
162 text. Set "maxheight" and "maxwidth" to restrict the size.
Bram Moolenaar560979e2020-02-04 22:53:05 +0100163
164To run a terminal in a popup window, first create the terminal hidden. Then
165pass the buffer number to popup_create(). Example: >
Bram Moolenaar191acfd2020-03-27 20:42:43 +0100166 hi link Terminal Search
Bram Moolenaar560979e2020-02-04 22:53:05 +0100167 let buf = term_start(['picker', 'Something'], #{hidden: 1, term_finish: 'close'})
168 let winid = popup_create(buf, #{minwidth: 50, minheight: 20})
Bram Moolenaar560979e2020-02-04 22:53:05 +0100169
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200170==============================================================================
1712. Functions *popup-functions*
172
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200173Creating a popup window:
174 |popup_create()| centered in the screen
175 |popup_atcursor()| just above the cursor position, closes when
176 the cursor moves away
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200177 |popup_beval()| at the position indicated by v:beval_
178 variables, closes when the mouse moves away
Bram Moolenaara3fce622019-06-20 02:31:49 +0200179 |popup_notification()| show a notification for three seconds
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200180 |popup_dialog()| centered with padding and border
181 |popup_menu()| prompt for selecting an item from a list
182
183Manipulating a popup window:
184 |popup_hide()| hide a popup temporarily
185 |popup_show()| show a previously hidden popup
186 |popup_move()| change the position and size of a popup
187 |popup_setoptions()| override options of a popup
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200188 |popup_settext()| replace the popup buffer contents
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200189
190Closing popup windows:
191 |popup_close()| close one popup
192 |popup_clear()| close all popups
193
194Filter functions:
195 |popup_filter_menu()| select from a list of items
196 |popup_filter_yesno()| blocks until 'y' or 'n' is pressed
197
198Other:
199 |popup_getoptions()| get current options for a popup
200 |popup_getpos()| get actual position and size of a popup
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200201 |popup_locate()| find popup window at a screen position
Bram Moolenaaref6b9792020-05-13 16:34:15 +0200202 |popup_list()| get list of all popups
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200203
204
Bram Moolenaar931a2772019-07-04 16:54:54 +0200205DETAILS *popup-function-details*
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200206
Bram Moolenaar931a2772019-07-04 16:54:54 +0200207popup_atcursor({what}, {options}) *popup_atcursor()*
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200208 Show the {what} above the cursor, and close it when the cursor
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200209 moves. This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200210 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200211 \ pos: 'botleft',
212 \ line: 'cursor-1',
213 \ col: 'cursor',
214 \ moved: 'WORD',
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200215 \ })
216< Use {options} to change the properties.
Bram Moolenaar4dd8fe02019-11-09 15:33:31 +0100217 If "pos" is passed as "topleft" then the default for "line"
218 becomes "cursor+1".
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200219
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200220 Can also be used as a |method|: >
221 GetText()->popup_atcursor({})
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200222<
223 Return type: |Number|
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200224
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200225
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200226popup_beval({what}, {options}) *popup_beval()*
227 Show the {what} above the position from 'ballooneval' and
228 close it when the mouse moves. This works like: >
229 let pos = screenpos(v:beval_winnr, v:beval_lnum, v:beval_col)
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200230 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200231 \ pos: 'botleft',
232 \ line: pos.row - 1,
233 \ col: pos.col,
234 \ mousemoved: 'WORD',
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200235 \ })
236< Use {options} to change the properties.
Bram Moolenaar8fe10002019-09-11 22:56:44 +0200237 See |popup_beval_example| for an example.
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200238
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200239 Can also be used as a |method|: >
240 GetText()->popup_beval({})
241<
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200242 Return type: |Number|
243
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200244 *popup_clear()*
Bram Moolenaar03a9f842020-05-13 13:40:16 +0200245popup_clear([{force}])
246 Emergency solution to a misbehaving plugin: close all popup
Bram Moolenaara3fce622019-06-20 02:31:49 +0200247 windows for the current tab and global popups.
Bram Moolenaar03a9f842020-05-13 13:40:16 +0200248 Close callbacks are not invoked.
249 When {force} is not present this will fail if the current
250 window is a popup.
251 When {force} is present and |TRUE| the popup is also closed
252 when it is the current window. If a terminal is running in a
253 popup it is killed.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200254
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200255 Return type: |Number|
256
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200257
258popup_close({id} [, {result}]) *popup_close()*
259 Close popup {id}. The window and the associated buffer will
260 be deleted.
261
262 If the popup has a callback it will be called just before the
263 popup window is deleted. If the optional {result} is present
264 it will be passed as the second argument of the callback.
265 Otherwise zero is passed to the callback.
266
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200267 Can also be used as a |method|: >
268 GetPopup()->popup_close()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200269<
270 Return type: |Number|
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200271
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200272
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200273popup_create({what}, {options}) *popup_create()*
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000274 Open a popup window showing {what}, which is either: *E450*
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200275 - a buffer number
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200276 - a string
277 - a list of strings
278 - a list of text lines with text properties
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200279 When {what} is not a buffer number, a buffer is created with
280 'buftype' set to "popup". That buffer will be wiped out once
281 the popup closes.
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200282
Bram Moolenaar188639d2022-04-04 16:57:21 +0100283 if {what} is a buffer number and loading the buffer runs into
284 an existing swap file, it is silently opened read-only, as if
285 a |SwapExists| autocommand had set |v:swapchoice| to 'o'.
286 This is because we assume the buffer is only used for viewing.
287
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200288 {options} is a dictionary with many possible entries.
Bram Moolenaar931a2772019-07-04 16:54:54 +0200289 See |popup_create-arguments| for details.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200290
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200291 Returns a window-ID, which can be used with other popup
292 functions. Use `winbufnr()` to get the number of the buffer
293 in the window: >
294 let winid = popup_create('hello', {})
295 let bufnr = winbufnr(winid)
296 call setbufline(bufnr, 2, 'second line')
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200297< In case of failure zero is returned.
298
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200299 Can also be used as a |method|: >
300 GetText()->popup_create({})
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200301<
302 Return type: |Number|
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200303
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200304
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200305popup_dialog({what}, {options}) *popup_dialog()*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200306 Just like |popup_create()| but with these default options: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200307 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200308 \ pos: 'center',
309 \ zindex: 200,
310 \ drag: 1,
311 \ border: [],
312 \ padding: [],
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200313 \ mapping: 0,
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200314 \})
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200315< Use {options} to change the properties. E.g. add a 'filter'
Bram Moolenaara42d9452019-06-15 21:46:30 +0200316 option with value 'popup_filter_yesno'. Example: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200317 call popup_create('do you want to quit (Yes/no)?', #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200318 \ filter: 'popup_filter_yesno',
319 \ callback: 'QuitCallback',
Bram Moolenaara42d9452019-06-15 21:46:30 +0200320 \ })
321
322< By default the dialog can be dragged, so that text below it
323 can be read if needed.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200324
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200325 Can also be used as a |method|: >
326 GetText()->popup_dialog({})
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200327<
328 Return type: |Number|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200329
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200330
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200331popup_filter_menu({id}, {key}) *popup_filter_menu()*
Bram Moolenaara730e552019-06-16 19:05:31 +0200332 Filter that can be used for a popup. These keys can be used:
Bram Moolenaar014f6982021-01-04 13:18:30 +0100333 j <Down> <C-N> select item below
334 k <Up> <C-P> select item above
Bram Moolenaara730e552019-06-16 19:05:31 +0200335 <Space> <Enter> accept current selection
336 x Esc CTRL-C cancel the menu
337 Other keys are ignored.
Bram Moolenaarcb80aa22020-10-26 21:12:46 +0100338 Always returns |v:true|.
Bram Moolenaara730e552019-06-16 19:05:31 +0200339
340 A match is set on that line to highlight it, see
341 |popup_menu()|.
342
343 When the current selection is accepted the "callback" of the
344 popup menu is invoked with the index of the selected line as
345 the second argument. The first entry has index one.
346 Cancelling the menu invokes the callback with -1.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200347
Bram Moolenaara3fce622019-06-20 02:31:49 +0200348 To add shortcut keys, see the example here:
349 |popup_menu-shortcut-example|
350
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200351 Return type: |Number|
352
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200353
354popup_filter_yesno({id}, {key}) *popup_filter_yesno()*
355 Filter that can be used for a popup. It handles only the keys
356 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the
357 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N'
Bram Moolenaara42d9452019-06-15 21:46:30 +0200358 as the second argument. Pressing Esc and 'x' works like
359 pressing 'n'. CTRL-C invokes the callback with -1. Other
360 keys are ignored.
Bram Moolenaara3fce622019-06-20 02:31:49 +0200361 See the example here: |popup_dialog-example|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200362
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200363 Return type: |Number|
364
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200365
Bram Moolenaarbdc09a12022-10-07 14:31:45 +0100366popup_findecho() *popup_findecho()*
367 Get the |window-ID| for the popup that shows messages for the
368 `:echowindow` command. Return zero if there is none.
369 Mainly useful to hide the popup.
370
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200371 Return type: |Number|
372
Bram Moolenaarbdc09a12022-10-07 14:31:45 +0100373
Bram Moolenaarc7c5f102019-08-21 18:31:03 +0200374popup_findinfo() *popup_findinfo()*
375 Get the |window-ID| for the popup info window, as it used by
376 the popup menu. See |complete-popup|. The info popup is
377 hidden when not used, it can be deleted with |popup_clear()|
Bram Moolenaar96f45c02019-10-26 19:53:45 +0200378 and |popup_close()|. Use |popup_show()| to reposition it to
379 the item in the popup menu.
380 Returns zero if there is none.
Bram Moolenaarc7c5f102019-08-21 18:31:03 +0200381
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200382 Return type: |Number|
383
Bram Moolenaarc7c5f102019-08-21 18:31:03 +0200384
385popup_findpreview() *popup_findpreview()*
386 Get the |window-ID| for the popup preview window.
387 Return zero if there is none.
388
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200389 Return type: |Number|
390
391
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200392popup_getoptions({id}) *popup_getoptions()*
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200393 Return the {options} for popup {id} in a Dict.
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200394 A zero value means the option was not set. For "zindex" the
395 default value is returned, not zero.
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200396
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200397 The "moved" entry is a list with line number, minimum and
398 maximum column, [0, 0, 0] when not set.
399
400 The "mousemoved" entry is a list with screen row, minimum and
401 maximum screen column, [0, 0, 0] when not set.
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200402
Bram Moolenaar06fe74a2019-08-31 16:20:32 +0200403 "firstline" is the property set on the popup, unlike the
404 "firstline" obtained with |popup_getpos()| which is the actual
405 buffer line at the top of the popup window.
406
Bram Moolenaarae943152019-06-16 22:54:14 +0200407 "border" and "padding" are not included when all values are
408 zero. When all values are one then an empty list is included.
409
410 "borderhighlight" is not included when all values are empty.
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200411 "scrollbarhighlight" and "thumbhighlight" are only included
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200412 when set.
Bram Moolenaarae943152019-06-16 22:54:14 +0200413
Bram Moolenaara3fce622019-06-20 02:31:49 +0200414 "tabpage" will be -1 for a global popup, zero for a popup on
415 the current tabpage and a positive number for a popup on
416 another tabpage.
417
Bram Moolenaar12034e22019-08-25 22:25:02 +0200418 "textprop", "textpropid" and "textpropwin" are only present
419 when "textprop" was set.
420
Bram Moolenaarae943152019-06-16 22:54:14 +0200421 If popup window {id} is not found an empty Dict is returned.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200422
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200423 Can also be used as a |method|: >
424 GetPopup()->popup_getoptions()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200425<
426 Return type: dict<any>
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200427
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200428
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200429popup_getpos({id}) *popup_getpos()*
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200430 Return the position and size of popup {id}. Returns a Dict
431 with these entries:
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200432 col screen column of the popup, one-based
433 line screen line of the popup, one-based
Bram Moolenaar2fd8e352019-06-01 20:16:48 +0200434 width width of the whole popup in screen cells
435 height height of the whole popup in screen cells
436 core_col screen column of the text box
437 core_line screen line of the text box
438 core_width width of the text box in screen cells
439 core_height height of the text box in screen cells
Bram Moolenaar68acb412019-06-26 03:40:36 +0200440 firstline line of the buffer at top (1 unless scrolled)
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200441 (not the value of the "firstline" property)
Bram Moolenaar4dd8fe02019-11-09 15:33:31 +0100442 lastline line of the buffer at the bottom (updated when
443 the popup is redrawn)
Bram Moolenaar68acb412019-06-26 03:40:36 +0200444 scrollbar non-zero if a scrollbar is displayed
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200445 visible one if the popup is displayed, zero if hidden
Bram Moolenaarbc133542019-05-29 20:26:46 +0200446 Note that these are the actual screen positions. They differ
447 from the values in `popup_getoptions()` for the sizing and
448 positioning mechanism applied.
Bram Moolenaar2fd8e352019-06-01 20:16:48 +0200449
450 The "core_" values exclude the padding and border.
451
Bram Moolenaarbc133542019-05-29 20:26:46 +0200452 If popup window {id} is not found an empty Dict is returned.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200453
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200454 Can also be used as a |method|: >
455 GetPopup()->popup_getpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200456<
457 Return type: dict<number> or dict<any>
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200458
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200459
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200460popup_hide({id}) *popup_hide()*
461 If {id} is a displayed popup, hide it now. If the popup has a
462 filter it will not be invoked for so long as the popup is
463 hidden.
464 If window {id} does not exist nothing happens. If window {id}
465 exists but is not a popup window an error is given. *E993*
Bram Moolenaarebdf3c92020-02-15 21:41:42 +0100466 If popup window {id} contains a terminal an error is given.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200467
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200468 Can also be used as a |method|: >
469 GetPopup()->popup_hide()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200470<
471 Return type: |Number|
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200472
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200473
Bram Moolenaaref6b9792020-05-13 16:34:15 +0200474popup_list() *popup_list()*
475 Return a List with the |window-ID| of all existing popups.
476
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200477 Return type: list<number> or list<any>
478
Bram Moolenaaref6b9792020-05-13 16:34:15 +0200479
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200480popup_locate({row}, {col}) *popup_locate()*
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200481 Return the |window-ID| of the popup at screen position {row}
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200482 and {col}. If there are multiple popups the one with the
483 highest zindex is returned. If there are no popups at this
484 position then zero is returned.
485
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200486 Return type: |Number|
487
Bram Moolenaarb4f06282019-07-12 21:07:54 +0200488
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200489popup_menu({what}, {options}) *popup_menu()*
490 Show the {what} near the cursor, handle selecting one of the
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200491 items with cursorkeys, and close it an item is selected with
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200492 Space or Enter. {what} should have multiple lines to make this
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200493 useful. This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200494 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200495 \ pos: 'center',
496 \ zindex: 200,
497 \ drag: 1,
498 \ wrap: 0,
499 \ border: [],
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200500 \ cursorline: 1,
Bram Moolenaar03464132019-07-14 16:28:13 +0200501 \ padding: [0,1,0,1],
Bram Moolenaar396e8292019-07-13 23:04:31 +0200502 \ filter: 'popup_filter_menu',
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200503 \ mapping: 0,
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200504 \ })
Bram Moolenaara730e552019-06-16 19:05:31 +0200505< The current line is highlighted with a match using
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200506 "PopupSelected", or "PmenuSel" if that is not defined.
Bram Moolenaara730e552019-06-16 19:05:31 +0200507
508 Use {options} to change the properties. Should at least set
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200509 "callback" to a function that handles the selected item.
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200510 Example: >
511 func ColorSelected(id, result)
512 " use a:result
513 endfunc
514 call popup_menu(['red', 'green', 'blue'], #{
515 \ callback: 'ColorSelected',
516 \ })
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200517
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200518< Can also be used as a |method|: >
519 GetChoices()->popup_menu({})
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200520<
521 Return type: |Number|
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200522
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200523
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200524popup_move({id}, {options}) *popup_move()*
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200525 Move popup {id} to the position specified with {options}.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200526 {options} may contain the items from |popup_create()| that
Bram Moolenaarae943152019-06-16 22:54:14 +0200527 specify the popup position:
528 line
529 col
530 pos
531 maxheight
532 minheight
533 maxwidth
534 minwidth
535 fixed
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200536 For {id} see `popup_hide()`.
Bram Moolenaarae943152019-06-16 22:54:14 +0200537 For other options see |popup_setoptions()|.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200538
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200539 Can also be used as a |method|: >
540 GetPopup()->popup_move(options)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200541<
542 Return type: |Number|
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200543
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200544
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200545popup_notification({what}, {options}) *popup_notification()*
546 Show the {what} for 3 seconds at the top of the Vim window.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200547 This works like: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200548 call popup_create({what}, #{
Bram Moolenaar396e8292019-07-13 23:04:31 +0200549 \ line: 1,
550 \ col: 10,
551 \ minwidth: 20,
552 \ time: 3000,
553 \ tabpage: -1,
554 \ zindex: 300,
555 \ drag: 1,
556 \ highlight: 'WarningMsg',
557 \ border: [],
558 \ close: 'click',
559 \ padding: [0,1,0,1],
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200560 \ })
Bram Moolenaardfa97f22019-06-15 14:31:55 +0200561< The PopupNotification highlight group is used instead of
562 WarningMsg if it is defined.
Bram Moolenaara730e552019-06-16 19:05:31 +0200563
Bram Moolenaar581ba392019-09-03 22:08:33 +0200564 Without the |+timers| feature the popup will not disappear
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200565 automatically, the user has to click in it.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200566
Bram Moolenaara730e552019-06-16 19:05:31 +0200567 The position will be adjusted to avoid overlap with other
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200568 notifications.
569 Use {options} to change the properties.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200570
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200571 Can also be used as a |method|: >
572 GetText()->popup_notification({})
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200573<
574 Return type: |Number|
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200575
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200576
577popup_setoptions({id}, {options}) *popup_setoptions()*
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200578 Override options in popup {id} with entries in {options}.
Bram Moolenaarae943152019-06-16 22:54:14 +0200579 These options can be set:
Bram Moolenaarae943152019-06-16 22:54:14 +0200580 border
Bram Moolenaarae943152019-06-16 22:54:14 +0200581 borderchars
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200582 borderhighlight
583 callback
584 close
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200585 cursorline
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200586 drag
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200587 filter
588 firstline
589 flip
590 highlight
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200591 mapping
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200592 mask
593 moved
594 padding
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200595 resize
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200596 scrollbar
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200597 scrollbarhighlight
598 thumbhighlight
Bram Moolenaarae943152019-06-16 22:54:14 +0200599 time
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200600 title
601 wrap
602 zindex
Bram Moolenaarae943152019-06-16 22:54:14 +0200603 The options from |popup_move()| can also be used.
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200604 Generally, setting an option to zero or an empty string resets
605 it to the default value, but there are exceptions.
Bram Moolenaarae943152019-06-16 22:54:14 +0200606 For "hidden" use |popup_hide()| and |popup_show()|.
607 "tabpage" cannot be changed.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200608
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200609 Can also be used as a |method|: >
610 GetPopup()->popup_setoptions(options)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200611<
612 Return type: |Number|
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200613
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200614
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200615popup_settext({id}, {text}) *popup_settext()*
Bram Moolenaar581ba392019-09-03 22:08:33 +0200616 Set the text of the buffer in popup win {id}. {text} is the
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200617 same as supplied to |popup_create()|, except that a buffer
618 number is not allowed.
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200619 Does not change the window size or position, other than caused
620 by the different text.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200621
Bram Moolenaar6a124e62019-09-04 18:15:19 +0200622 Can also be used as a |method|: >
623 GetPopup()->popup_settext('hello')
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200624<
625 Return type: |Number|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200626
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200627
628popup_show({id}) *popup_show()*
629 If {id} is a hidden popup, show it now.
630 For {id} see `popup_hide()`.
631 If {id} is the info popup it will be positioned next to the
632 current popup menu item.
633
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200634 Return type: |Number|
635
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200636
Bram Moolenaar931a2772019-07-04 16:54:54 +0200637==============================================================================
6383. Usage *popup-usage*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200639
Bram Moolenaar931a2772019-07-04 16:54:54 +0200640POPUP_CREATE() ARGUMENTS *popup_create-arguments*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200641
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200642The first argument of |popup_create()| (and the second argument to
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200643|popup_settext()|) specifies the text to be displayed, and optionally text
Bram Moolenaar2ecbe532022-07-29 21:36:21 +0100644properties. It is in one of four forms: *E1284*
Bram Moolenaar5b8cfed2019-06-30 22:16:10 +0200645- a buffer number
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200646- a string
647- a list of strings
648- a list of dictionaries, where each dictionary has these entries:
649 text String with the text to display.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200650 props A list of text properties. Optional.
651 Each entry is a dictionary, like the third argument of
652 |prop_add()|, but specifying the column in the
653 dictionary with a "col" entry, see below:
654 |popup-props|.
655
Bram Moolenaare0d749a2019-09-25 22:14:48 +0200656If you want to create a new buffer yourself use |bufadd()| and pass the buffer
657number to popup_create().
Bram Moolenaare0d749a2019-09-25 22:14:48 +0200658
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200659The second argument of |popup_create()| is a dictionary with options:
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200660 line Screen line where to position the popup. Can use a
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200661 number or "cursor", "cursor+1" or "cursor-1" to use
662 the line of the cursor and add or subtract a number of
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200663 lines. If omitted or zero the popup is vertically
664 centered. The first line is 1.
Bram Moolenaar12034e22019-08-25 22:25:02 +0200665 When using "textprop" the number is relative to the
666 text property and can be negative.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200667 col Screen column where to position the popup. Can use a
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200668 number or "cursor" to use the column of the cursor,
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200669 "cursor+9" or "cursor-9" to add or subtract a number
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200670 of columns. If omitted or zero the popup is
671 horizontally centered. The first column is 1.
Bram Moolenaar12034e22019-08-25 22:25:02 +0200672 When using "textprop" the number is relative to the
673 text property and can be negative.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200674 pos "topleft", "topright", "botleft" or "botright":
675 defines what corner of the popup "line" and "col" are
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200676 used for. When not set "topleft" is used.
677 Alternatively "center" can be used to position the
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200678 popup in the center of the Vim window, in which case
679 "line" and "col" are ignored.
Bram Moolenaar4dd8fe02019-11-09 15:33:31 +0100680 posinvert When FALSE the value of "pos" is always used. When
681 TRUE (the default) and the popup does not fit
682 vertically and there is more space on the other side
683 then the popup is placed on the other side of the
684 position indicated by "line".
Bram Moolenaar12034e22019-08-25 22:25:02 +0200685 textprop When present the popup is positioned next to a text
686 property with this name and will move when the text
687 property moves. Use an empty string to remove. See
688 |popup-textprop-pos|.
689 textpropwin What window to search for the text property. When
Bram Moolenaar942db232021-02-13 18:14:48 +0100690 omitted or invalid the current window is used. Used
691 when "textprop" is present.
Bram Moolenaar12034e22019-08-25 22:25:02 +0200692 textpropid Used to identify the text property when "textprop" is
693 present. Use zero to reset.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200694 fixed When FALSE (the default), and:
695 - "pos" is "botleft" or "topleft", and
696 - "wrap" is off, and
697 - the popup would be truncated at the right edge of
698 the screen, then
699 the popup is moved to the left so as to fit the
700 contents on the screen. Set to TRUE to disable this.
701 flip When TRUE (the default) and the position is relative
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200702 to the cursor, flip to below or above the cursor to
703 avoid overlap with the |popupmenu-completion| or
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200704 another popup with a higher "zindex". When there is
705 no space above/below the cursor then show the popup to
706 the side of the popup or popup menu.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200707 {not implemented yet}
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200708 maxheight Maximum height of the contents, excluding border and
709 padding.
710 minheight Minimum height of the contents, excluding border and
711 padding.
Bram Moolenaar54775062019-07-31 21:07:14 +0200712 maxwidth Maximum width of the contents, excluding border,
713 padding and scrollbar.
714 minwidth Minimum width of the contents, excluding border,
715 padding and scrollbar.
Bram Moolenaar8d241042019-06-12 23:40:01 +0200716 firstline First buffer line to display. When larger than one it
717 looks like the text scrolled up. When out of range
718 the last buffer line will at the top of the window.
Bram Moolenaar06fe74a2019-08-31 16:20:32 +0200719 Set to zero to leave the position as set by commands.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200720 Also see "scrollbar".
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200721 hidden When TRUE the popup exists but is not displayed; use
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200722 `popup_show()` to unhide it.
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200723 tabpage When -1: display the popup on all tab pages.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200724 When 0 (the default): display the popup on the current
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +0200725 tab page.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200726 Otherwise the number of the tab page the popup is
Bram Moolenaara3fce622019-06-20 02:31:49 +0200727 displayed on; when invalid the popup is not created
Bram Moolenaarb2cda0d2019-06-24 05:06:36 +0200728 and an error is given. *E997*
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200729 title Text to be displayed above the first item in the
730 popup, on top of any border. If there is no top
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200731 border one line of padding is added to put the title
Bram Moolenaareb2310d2019-06-16 20:09:10 +0200732 on. You might want to add one or more spaces at the
733 start and end as padding.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200734 wrap TRUE to make the lines wrap (default TRUE).
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200735 drag TRUE to allow the popup to be dragged with the mouse
Bram Moolenaar581ba392019-09-03 22:08:33 +0200736 by grabbing at the border. Has no effect if the
Bram Moolenaardc2ce582019-06-16 15:32:14 +0200737 popup does not have a border. As soon as dragging
738 starts and "pos" is "center" it is changed to
739 "topleft".
Bram Moolenaar0b74d002021-11-29 17:38:02 +0000740 dragall TRUE to allow the popup to be dragged from every
741 position. Makes it very difficult to select text in
742 the popup.
Bram Moolenaar9bcb70c2019-08-01 21:11:05 +0200743 resize TRUE to allow the popup to be resized with the mouse
Bram Moolenaar581ba392019-09-03 22:08:33 +0200744 by grabbing at the bottom right corner. Has no effect
745 if the popup does not have a border.
Bram Moolenaar2e62b562019-06-30 18:07:00 +0200746 close When "button" an X is displayed in the top-right, on
747 top of any border, padding or text. When clicked on
748 the X the popup will close. Any callback is invoked
749 with the value -2.
750 When "click" any mouse click in the popup will close
751 it.
752 When "none" (the default) mouse clicks do not close
753 the popup window.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200754 highlight Highlight group name to use for the text, stored in
755 the 'wincolor' option.
756 padding List with numbers, defining the padding
757 above/right/below/left of the popup (similar to CSS).
758 An empty list uses a padding of 1 all around. The
759 padding goes around the text, inside any border.
760 Padding uses the 'wincolor' highlight.
761 Example: [1, 2, 1, 3] has 1 line of padding above, 2
762 columns on the right, 1 line below and 3 columns on
763 the left.
764 border List with numbers, defining the border thickness
765 above/right/below/left of the popup (similar to CSS).
Bram Moolenaar9faec4e2021-02-27 16:38:07 +0100766 Only values of zero and non-zero are currently
767 recognized. An empty list uses a border all around.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200768 borderhighlight List of highlight group names to use for the border.
769 When one entry it is used for all borders, otherwise
770 the highlight for the top/right/bottom/left border.
771 Example: ['TopColor', 'RightColor', 'BottomColor,
772 'LeftColor']
773 borderchars List with characters, defining the character to use
774 for the top/right/bottom/left border. Optionally
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200775 followed by the character to use for the
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200776 topleft/topright/botright/botleft corner.
777 Example: ['-', '|', '-', '|', '┌', '┐', '┘', '└']
778 When the list has one character it is used for all.
779 When the list has two characters the first is used for
780 the border lines, the second for the corners.
781 By default a double line is used all around when
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200782 'encoding' is "utf-8" and 'ambiwidth' is "single",
Bram Moolenaara3fce622019-06-20 02:31:49 +0200783 otherwise ASCII characters are used.
Bram Moolenaard58a3bf2020-09-28 21:48:16 +0200784 scrollbar 1 or true: show a scrollbar when the text doesn't fit.
Bram Moolenaar75fb0852019-06-25 05:15:58 +0200785 zero: do not show a scrollbar. Default is non-zero.
Bram Moolenaarf9c85f52019-06-29 07:41:35 +0200786 Also see |popup-scrollbar|.
787 scrollbarhighlight Highlight group name for the scrollbar. The
788 background color is what matters. When not given then
789 PmenuSbar is used.
790 thumbhighlight Highlight group name for the scrollbar thumb. The
791 background color is what matters. When not given then
792 PmenuThumb is used.
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200793 zindex Priority for the popup, default 50. Minimum value is
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200794 1, maximum value is 32000.
Bram Moolenaarc662ec92019-06-23 00:15:57 +0200795 mask A list of lists with coordinates, defining parts of
796 the popup that are transparent. See |popup-mask|.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200797 time Time in milliseconds after which the popup will close.
798 When omitted |popup_close()| must be used.
Bram Moolenaar3397f742019-06-02 18:40:06 +0200799 moved Specifies to close the popup if the cursor moved:
800 - "any": if the cursor moved at all
801 - "word": if the cursor moved outside |<cword>|
802 - "WORD": if the cursor moved outside |<cWORD>|
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200803 - "expr": if the cursor moved outside |<cexpr>|
Bram Moolenaar3397f742019-06-02 18:40:06 +0200804 - [{start}, {end}]: if the cursor moved before column
805 {start} or after {end}
Bram Moolenaara1396152019-10-20 18:46:05 +0200806 - [{lnum}, {start}, {end}]: if the cursor moved away
807 from line {lnum}, before column {start} or after
808 {end}
Bram Moolenaar4dd8fe02019-11-09 15:33:31 +0100809 - [0, 0, 0] do not close the popup when the cursor
810 moves
Bram Moolenaar3397f742019-06-02 18:40:06 +0200811 The popup also closes if the cursor moves to another
812 line or to another window.
Bram Moolenaara1396152019-10-20 18:46:05 +0200813 mousemoved Like "moved" but referring to the mouse pointer
814 position
Bram Moolenaar9faec4e2021-02-27 16:38:07 +0100815 cursorline TRUE: Highlight the cursor line. Also scrolls the
816 text to show this line (only works properly
817 when 'wrap' is off).
Bram Moolenaar938ae282023-02-20 20:44:55 +0000818 zero: Do not highlight the cursor line.
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +0200819 Default is zero, except for |popup_menu()|.
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200820 filter A callback that can filter typed characters, see
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200821 |popup-filter|.
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200822 mapping Allow for key mapping. When FALSE and the popup is
823 visible and has a filter callback key mapping is
824 disabled. Default value is TRUE.
Bram Moolenaar581ba392019-09-03 22:08:33 +0200825 filtermode In which modes the filter is used (same flags as with
826 |hasmapto()| plus "a"):
827 n Normal mode
828 v Visual and Select mode
829 x Visual mode
830 s Select mode
831 o Operator-pending mode
832 i Insert mode
833 l Language-Argument ("r", "f", "t", etc.)
834 c Command-line mode
835 a all modes
836 The default value is "a".
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200837 callback A callback that is called when the popup closes, e.g.
838 when using |popup_filter_menu()|, see |popup-callback|.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200839
840Depending on the "zindex" the popup goes under or above other popups. The
841completion menu (|popup-menu|) has zindex 100. For messages that occur for a
842short time the suggestion is to use zindex 1000.
843
844By default text wraps, which causes a line in {lines} to occupy more than one
845screen line. When "wrap" is FALSE then the text outside of the popup or
846outside of the Vim window will not be displayed, thus truncated.
847
848
849POPUP TEXT PROPERTIES *popup-props*
850
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200851These are similar to the third argument of |prop_add()| except:
852- "lnum" is always the current line in the list
853- "bufnr" is always the buffer of the popup
854- "col" is in the Dict instead of a separate argument
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200855So we get:
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200856 col starting column, counted in bytes, use one for the
857 first column.
858 length length of text in bytes; can be zero
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200859 end_lnum line number for the end of the text
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200860 end_col column just after the text; not used when "length" is
861 present; when {col} and "end_col" are equal, this is a
862 zero-width text property
863 id user defined ID for the property; when omitted zero is
864 used
865 type name of the text property type, as added with
866 |prop_type_add()|
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200867
868
Bram Moolenaar12034e22019-08-25 22:25:02 +0200869POSITION POPUP WITH TEXTPROP *popup-textprop-pos*
870
871Positioning a popup next to a text property causes the popup to move when text
872is inserted or deleted. The popup functions like a tooltip.
873
874These steps are needed to make this work:
875
876- Define a text property type, it defines the name. >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200877 call prop_type_add('popupMarker', {})
Bram Moolenaar12034e22019-08-25 22:25:02 +0200878
879- Place a text property at the desired text: >
880 let lnum = {line of the text}
881 let col = {start column of the text}
882 let len = {length of the text}
883 let propId = {arbitrary but unique number}
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200884 call prop_add(lnum, col, #{
Bram Moolenaar12034e22019-08-25 22:25:02 +0200885 \ length: len,
886 \ type: 'popupMarker',
887 \ id: propId,
888 \ })
889
890- Create a popup: >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200891 let winid = popup_create('the text', #{
892 \ pos: 'botleft',
Bram Moolenaar12034e22019-08-25 22:25:02 +0200893 \ textprop: 'popupMarker',
894 \ textpropid: propId,
895 \ border: [],
896 \ padding: [0,1,0,1],
897 \ close: 'click',
898 \ })
899
900By default the popup is positioned at the corner of the text, opposite of the
901"pos" specified for the popup. Thus when the popup uses "botleft", the
902bottom-left corner of the popup is positioned next to the top-right corner of
903the text property:
904 +----------+
905 | the text |
906 +----------+
907 just some PROPERTY as an example
908
909Here the text property is on "PROPERTY". Move the popup to the left by
910passing a negative "col" value to popup_create(). With "col: -5" you get:
911
912 +----------+
913 | the text |
914 +----------+
915 just some PROPERTY as an example
916
917If the text property moves out of view then the popup will be hidden.
918If the window for which the popup was defined is closed, the popup is closed.
919
920If the popup cannot fit in the desired position, it may show at a nearby
921position.
922
923Some hints:
924- To avoid collision with other plugins the text property type name has to be
925 unique. You can also use the "bufnr" item to make it local to a buffer.
926- You can leave out the text property ID if there is only ever one text
927 property visible.
928- The popup may be in the way of what the user is doing, making it close with
929 a click, as in the example above, helps for that.
930- If the text property is removed the popup is closed. Use something like
931 this: >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200932 call prop_remove(#{type: 'popupMarker', id: propId})
Bram Moolenaar12034e22019-08-25 22:25:02 +0200933
934
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200935POPUP FILTER *popup-filter*
936
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200937A callback that gets any typed keys while a popup is displayed. The filter is
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200938not invoked when the popup is hidden.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200939
940The filter can return TRUE to indicate the key has been handled and is to be
941discarded, or FALSE to let Vim handle the key as usual in the current state.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200942In case it returns FALSE and there is another popup window visible, that
943filter is also called. The filter of the popup window with the highest zindex
944is called first.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200945
946The filter function is called with two arguments: the ID of the popup and the
Bram Moolenaara42d9452019-06-15 21:46:30 +0200947key as a string, e.g.: >
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200948 func MyFilter(winid, key)
949 if a:key == "\<F2>"
950 " do something
951 return 1
952 endif
953 if a:key == 'x'
954 call popup_close(a:winid)
955 return 1
956 endif
957 return 0
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200958 endfunc
Bram Moolenaar581ba392019-09-03 22:08:33 +0200959< *popup-filter-mode*
960The "filtermode" property can be used to specify in what mode the filter is
961invoked. The default is "a": all modes. When using "nvi" Command-line mode
962is not included, so that any command typed on the command line is not
963filtered. However, to get to Command-line mode the filter must not consume
964":". Just like it must not consume "v" to allow for entering Visual mode.
965
966 *popup-mapping*
Bram Moolenaar749fa0a2019-08-03 16:18:07 +0200967Normally the key is what results after any mapping, since the keys pass on as
968normal input if the filter does not use it. If the filter consumes all the
969keys, set the "mapping" property to zero so that mappings do not get in the
970way. This is default for |popup_menu()| and |popup_dialog()|.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200971
Bram Moolenaar581ba392019-09-03 22:08:33 +0200972Some recommended key actions:
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200973 x close the popup (see note below)
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200974 cursor keys select another entry
975 Tab accept current suggestion
976
Bram Moolenaar6aa57292021-08-14 21:25:52 +0200977When CTRL-C is pressed the popup is closed, the filter will not be invoked.
978
Bram Moolenaardb3a2052019-11-16 18:22:41 +0100979A mouse click arrives as <LeftMouse>. The coordinates can be obtained with
Bram Moolenaar09c6f262019-11-17 15:55:14 +0100980|getmousepos()|.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200981
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200982Vim provides standard filters |popup_filter_menu()| and
983|popup_filter_yesno()|.
984
Bram Moolenaar4934ad02020-09-28 22:29:58 +0200985Keys coming from a `:normal` command do not pass through the filter. This can
986be used to move the cursor in a popup where the "cursorline" option is set: >
987 call win_execute(winid, 'normal! 10Gzz')
988Keys coming from `feedkeys()` are passed through the filter.
989
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200990Note that "x" is the normal way to close a popup. You may want to use Esc,
991but since many keys start with an Esc character, there may be a delay before
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200992Vim recognizes the Esc key. If you do use Esc, it is recommended to set the
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200993'ttimeoutlen' option to 100 and set 'timeout' and/or 'ttimeout'.
994
Bram Moolenaar1d59aa12020-09-19 18:50:13 +0200995 *popup-filter-errors*
996If the filter function can't be called, e.g. because the name is wrong, then
997the popup is closed. If the filter causes an error then it is assumed to
998return zero. If this happens three times in a row the popup is closed. If
999the popup gives errors fewer than 10% of the calls then it won't be closed.
1000
Bram Moolenaar957f85d2019-05-12 21:43:48 +02001001
1002POPUP CALLBACK *popup-callback*
1003
Bram Moolenaara42d9452019-06-15 21:46:30 +02001004A callback that is invoked when the popup closes.
Bram Moolenaar9eaac892019-06-01 22:49:29 +02001005
1006The callback is invoked with two arguments: the ID of the popup window and the
1007result, which could be an index in the popup lines, or whatever was passed as
1008the second argument of `popup_close()`.
Bram Moolenaar957f85d2019-05-12 21:43:48 +02001009
Bram Moolenaara42d9452019-06-15 21:46:30 +02001010If the popup is force-closed, e.g. because the cursor moved or CTRL-C was
1011pressed, the number -1 is passed to the callback.
Bram Moolenaar3397f742019-06-02 18:40:06 +02001012
Bram Moolenaar749fa0a2019-08-03 16:18:07 +02001013Example: >
1014 func SelectedColor(id, result)
1015 echo 'choice made: ' .. a:result
1016 endfunc
1017
Bram Moolenaarc662ec92019-06-23 00:15:57 +02001018
Bram Moolenaarf9c85f52019-06-29 07:41:35 +02001019POPUP SCROLLBAR *popup-scrollbar*
1020
1021If the text does not fit in the popup a scrollbar is displayed on the right of
1022the window. This can be disabled by setting the "scrollbar" option to zero.
1023When the scrollbar is displayed mouse scroll events, while the mouse pointer
1024is on the popup, will cause the text to scroll up or down as you would expect.
Bram Moolenaar85850f32019-07-19 22:05:51 +02001025A click in the upper half of the scrollbar will scroll the text down one line.
1026A click in the lower half will scroll the text up one line. However, this is
1027limited so that the popup does not get smaller.
Bram Moolenaarf9c85f52019-06-29 07:41:35 +02001028
1029
Bram Moolenaarc662ec92019-06-23 00:15:57 +02001030POPUP MASK *popup-mask*
1031
1032To minimize the text that the popup covers, parts of it can be made
1033transparent. This is defined by a "mask" which is a list of lists, where each
1034list has four numbers:
1035 col start column, positive for counting from the left, 1 for
1036 leftmost, negative for counting from the right, -1 for
1037 rightmost
1038 endcol last column, like "col"
Bram Moolenaardf9c6ca2019-07-18 13:46:42 +02001039 line start line, positive for counting from the top, 1 for top,
Bram Moolenaarc662ec92019-06-23 00:15:57 +02001040 negative for counting from the bottom, -1 for bottom
1041 endline end line, like "line"
1042
1043For example, to make the last 10 columns of the last line transparent:
1044 [[-10, -1, -1, -1]]
1045
1046To make the four corners transparent:
1047 [[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]
1048
Bram Moolenaar957f85d2019-05-12 21:43:48 +02001049==============================================================================
Bram Moolenaar931a2772019-07-04 16:54:54 +020010504. Examples *popup-examples*
Bram Moolenaar957f85d2019-05-12 21:43:48 +02001051
Bram Moolenaar016188f2022-06-06 20:52:59 +01001052These examples use |Vim9| script.
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +01001053
Bram Moolenaara3fce622019-06-20 02:31:49 +02001054 *popup_dialog-example*
Bram Moolenaar957f85d2019-05-12 21:43:48 +02001055Prompt the user to press y/Y or n/N: >
1056
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +01001057 popup_dialog('Continue? y/n', {
1058 filter: 'popup_filter_yesno',
1059 callback: (id, result) => {
1060 if result == 1
1061 echomsg "'y' or 'Y' was pressed"
1062 else
1063 echomsg "'y' or 'Y' was NOT pressed"
1064 endif
1065 },
Bram Moolenaard592deb2022-06-17 15:42:40 +01001066 padding: [2, 4, 2, 4],
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +01001067 })
Bram Moolenaar957f85d2019-05-12 21:43:48 +02001068<
Bram Moolenaara3fce622019-06-20 02:31:49 +02001069 *popup_menu-shortcut-example*
1070Extend popup_filter_menu() with shortcut keys: >
1071
Bram Moolenaard592deb2022-06-17 15:42:40 +01001072 popup_menu(['Save', 'Cancel', 'Discard'], {
1073 callback: (_, result) => {
1074 echo 'dialog result is' result
1075 },
1076 filter: (id, key) => {
1077 # Handle shortcuts
1078 if key == 'S' || key == 's'
1079 popup_close(id, 1)
1080 elseif key == 'C' || key == 'c'
1081 popup_close(id, 2)
1082 elseif key == 'D' || key == 'd'
1083 popup_close(id, 3)
1084 else
1085 # No shortcut, pass to generic filter
1086 return popup_filter_menu(id, key)
1087 endif
1088 return true
1089 },
1090 })
Bram Moolenaara3fce622019-06-20 02:31:49 +02001091<
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001092 *popup_beval_example*
1093Example for using a popup window for 'ballooneval': >
1094
1095 set ballooneval balloonevalterm
1096 set balloonexpr=BalloonExpr()
Bram Moolenaard592deb2022-06-17 15:42:40 +01001097 var winid: number
1098 var last_text: string
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001099
Bram Moolenaard592deb2022-06-17 15:42:40 +01001100 def BalloonExpr(): string
1101 # here you would use "v:beval_text" to lookup something interesting
1102 var text = v:beval_text
1103 if winid > 0 && popup_getpos(winid) != null_dict
1104 # previous popup window still shows
1105 if text == last_text
1106 # still the same text, keep the existing popup
1107 return null_string
1108 endif
1109 popup_close(winid)
Bram Moolenaarb05caa72019-07-10 21:55:54 +02001110 endif
Bram Moolenaard592deb2022-06-17 15:42:40 +01001111
1112 winid = popup_beval(text, {})
1113 last_text = text
1114 return null_string
1115 enddef
1116
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001117If the text has to be obtained asynchronously return an empty string from the
1118expression function and call popup_beval() once the text is available. In
Bram Moolenaarb05caa72019-07-10 21:55:54 +02001119this example simulated with a timer callback: >
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001120
1121 set ballooneval balloonevalterm
1122 set balloonexpr=BalloonExpr()
Bram Moolenaard592deb2022-06-17 15:42:40 +01001123 var winid: number
1124 var last_text: string
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001125
Bram Moolenaard592deb2022-06-17 15:42:40 +01001126 def BalloonExpr(): string
1127 var text = v:beval_text
1128 if winid > 0 && popup_getpos(winid) != null_dict
1129 # previous popup window still shows
1130 if text == last_text
1131 # still the same text, keep the existing popup
1132 return null_string
1133 endif
1134 popup_close(winid)
Bram Moolenaarb05caa72019-07-10 21:55:54 +02001135 endif
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001136
Bram Moolenaard592deb2022-06-17 15:42:40 +01001137 # Simulate an asynchronous lookup that takes half a second for the
1138 # text to display.
1139 last_text = text
1140 timer_start(500, 'ShowPopup')
1141 return null_string
1142 enddef
1143
1144 def ShowPopup(timerid: number)
1145 winid = popup_beval('Result: ' .. last_text, {})
1146 enddef
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001147<
Bram Moolenaar957f85d2019-05-12 21:43:48 +02001148
1149 vim:tw=78:ts=8:noet:ft=help:norl: