blob: 3ee92f2698083b53053d5c3de8f0e696ca69bdbe [file] [log] [blame]
Bram Moolenaardfa97f22019-06-15 14:31:55 +02001*popup.txt* For Vim version 8.1. Last change: 2019 Jun 15
Bram Moolenaar957f85d2019-05-12 21:43:48 +02002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
Bram Moolenaar5c017b22019-05-21 23:09:01 +02007Displaying text in floating window. *popup* *popup-window*
Bram Moolenaar957f85d2019-05-12 21:43:48 +02008
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +02009THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
Bram Moolenaar957f85d2019-05-12 21:43:48 +020010
111. Introduction |popup-intro|
122. Functions |popup-functions|
133. Examples |popup-examples|
14
15
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020016{not available if the |+textprop| feature was disabled at compile time}
Bram Moolenaar957f85d2019-05-12 21:43:48 +020017
18==============================================================================
191. Introduction *popup-intro*
20
Bram Moolenaar5c017b22019-05-21 23:09:01 +020021We are talking about popup windows here, text that goes on top of the regular
22windows and is under control of a plugin. You cannot edit the text in the
23popup window like with regular windows.
24
25A popup window can be used for such things as:
Bram Moolenaar68e65602019-05-26 21:33:31 +020026- briefly show a message without overwriting the command line
Bram Moolenaar5c017b22019-05-21 23:09:01 +020027- prompt the user with a dialog
Bram Moolenaar4d784b22019-05-25 19:51:39 +020028- display contextual information while typing
Bram Moolenaar5c017b22019-05-21 23:09:01 +020029- give extra information for auto-completion
30
31The text in the popup window can be colored with |text-properties|. It is
32also possible to use syntax highlighting.
33
Bram Moolenaar4d784b22019-05-25 19:51:39 +020034The default color used is "Pmenu". If you prefer something else use the
35"highlight" argument or the 'wincolor' option, e.g.: >
36 hi MyPopupColor ctermbg=lightblue guibg=lightblue
37 call setwinvar(winid, '&wincolor', 'MyPopupColor')
38
Bram Moolenaar68d48f42019-06-12 22:42:41 +020039'hlsearch' highlighting is not displayed in a popup window.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020040
Bram Moolenaar5c017b22019-05-21 23:09:01 +020041A popup window has a window-ID like other windows, but behaves differently.
42The size can be up to the whole Vim window and it overlaps other windows.
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +020043Popup windows can also overlap each other. The "zindex" property specifies
44what goes on top of what.
Bram Moolenaar68e65602019-05-26 21:33:31 +020045
46The popup window contains a buffer, and that buffer is always associated with
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +020047the popup window. The window cannot be in Normal, Visual or Insert mode, it
48does not get keyboard focus. You can use functions like `setbufline()` to
Bram Moolenaar68e65602019-05-26 21:33:31 +020049change the text in the buffer. There are more differences from how this
50window and buffer behave compared to regular windows and buffers, see
51|popup-buffer|.
Bram Moolenaar5c017b22019-05-21 23:09:01 +020052
53If this is not what you are looking for, check out other popup functionality:
Bram Moolenaar957f85d2019-05-12 21:43:48 +020054- popup menu, see |popup-menu|
55- balloon, see |balloon-eval|
56
Bram Moolenaar5c017b22019-05-21 23:09:01 +020057
Bram Moolenaar4d784b22019-05-25 19:51:39 +020058WINDOW POSITION AND SIZE *popup-position*
59
Bram Moolenaar68e65602019-05-26 21:33:31 +020060The height of the window is normally equal to the number of, possibly
61wrapping, lines in the buffer. It can be limited with the "maxheight"
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020062property. You can use empty lines to increase the height or the "minheight"
63property.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020064
65The width of the window is normally equal to the longest line in the buffer.
66It can be limited with the "maxwidth" property. You can use spaces to
Bram Moolenaar68d48f42019-06-12 22:42:41 +020067increase the width or use the "minwidth" property.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020068
Bram Moolenaar042fb4b2019-06-02 14:49:56 +020069By default the 'wrap' option is set, so that no text disappears. Otherwise,
70if there is not enough space then the window is shifted left in order to
71display more text. This can be disabled with the "fixed" property. Also
72disabled when right-aligned.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020073
Bram Moolenaar7dd64a32019-05-31 21:41:05 +020074Vim tries to show the popup in the location you specify. In some cases, e.g.
75when the popup would go outside of the Vim window, it will show it somewhere
76else. E.g. if you use `popup_atcursor()` the popup normally shows just above
77the current cursor position, but if the cursor is close to the top of the Vim
78window it will be placed below the cursor position.
79
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +020080When the screen scrolls up for output of an Ex command, popups move too, so
81that they will not cover the output.
Bram Moolenaar4d784b22019-05-25 19:51:39 +020082
Bram Moolenaar68d48f42019-06-12 22:42:41 +020083The current cursor position is displayed even when it is under a popup window.
84That way you can still see where it is, even though you cannot see the text
85that it is in.
Bram Moolenaar868b7b62019-05-29 21:44:40 +020086
Bram Moolenaar5c017b22019-05-21 23:09:01 +020087
Bram Moolenaar5c017b22019-05-21 23:09:01 +020088
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +020089TODO:
Bram Moolenaarbf0eff02019-06-01 17:13:36 +020090- Why does 'nrformats' leak from the popup window buffer???
Bram Moolenaar68d48f42019-06-12 22:42:41 +020091- Disable commands, feedkeys(), CTRL-W, etc. in a popup window.
92 Use NOT_IN_POPUP_WINDOW for more commands.
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +020093- Add 'balloonpopup': instead of showing text, let the callback open a popup
94 window and return the window ID. The popup will then be closed when the
95 mouse moves, except when it moves inside the popup.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +020096- For the "moved" property also include mouse movement?
97- Make redrawing more efficient and avoid flicker:
98 - put popup menu also put in popup_mask?
Bram Moolenaar2fd8e352019-06-01 20:16:48 +020099- Invoke filter with character before mapping?
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200100- Figure out the size and position better.
101 if wrapping splits a double-wide character
Bram Moolenaarcc31ad92019-05-30 19:25:06 +0200102 if wrapping inserts indent
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200103- When drawing on top half a double-wide character, display ">" or "<" in the
104 incomplete cell.
Bram Moolenaarbc133542019-05-29 20:26:46 +0200105- Can the buffer be re-used, to avoid using up lots of buffer numbers?
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +0200106- Implement:
107 popup_dialog({text}, {options})
108 popup_filter_menu({id}, {key})
109 popup_filter_yesno({id}, {key})
110 popup_menu({text}, {options})
111 popup_setoptions({id}, {options})
112 flip option
113 hidden option
114 tabpage option with number
115 title option
116 transparent text property
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200117
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200118
119==============================================================================
1202. Functions *popup-functions*
121
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200122THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200123
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200124Creating a popup window:
125 |popup_create()| centered in the screen
126 |popup_atcursor()| just above the cursor position, closes when
127 the cursor moves away
128 |popup_notifiation()| show a notification for three seconds
129 |popup_dialog()| centered with padding and border
130 |popup_menu()| prompt for selecting an item from a list
131
132Manipulating a popup window:
133 |popup_hide()| hide a popup temporarily
134 |popup_show()| show a previously hidden popup
135 |popup_move()| change the position and size of a popup
136 |popup_setoptions()| override options of a popup
137
138Closing popup windows:
139 |popup_close()| close one popup
140 |popup_clear()| close all popups
141
142Filter functions:
143 |popup_filter_menu()| select from a list of items
144 |popup_filter_yesno()| blocks until 'y' or 'n' is pressed
145
146Other:
147 |popup_getoptions()| get current options for a popup
148 |popup_getpos()| get actual position and size of a popup
149
150
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +0200151[functions help to be moved to eval.txt later]
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200152
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200153popup_atcursor({text}, {options}) *popup_atcursor()*
154 Show the {text} above the cursor, and close it when the cursor
155 moves. This works like: >
156 call popup_create({text}, {
157 \ 'pos': 'botleft',
158 \ 'line': 'cursor-1',
159 \ 'col': 'cursor',
160 \ 'moved': 'WORD',
161 \ })
162< Use {options} to change the properties.
163
164
165 *popup_clear()*
166popup_clear() Emergency solution to a misbehaving plugin: close all popup
167 windows.
168
169
170popup_close({id} [, {result}]) *popup_close()*
171 Close popup {id}. The window and the associated buffer will
172 be deleted.
173
174 If the popup has a callback it will be called just before the
175 popup window is deleted. If the optional {result} is present
176 it will be passed as the second argument of the callback.
177 Otherwise zero is passed to the callback.
178
179
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200180popup_create({text}, {options}) *popup_create()*
181 Open a popup window showing {text}, which is either:
182 - a string
183 - a list of strings
184 - a list of text lines with text properties
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200185
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200186 {options} is a dictionary with many possible entries.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200187 See |popup_create-usage| for details.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200188
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200189 Returns a window-ID, which can be used with other popup
190 functions. Use `winbufnr()` to get the number of the buffer
191 in the window: >
192 let winid = popup_create('hello', {})
193 let bufnr = winbufnr(winid)
194 call setbufline(bufnr, 2, 'second line')
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200195< In case of failure zero is returned.
196
197
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200198popup_dialog({text}, {options}) *popup_dialog()*
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200199 {not implemented yet}
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200200 Just like |popup_create()| but with these default options: >
201 call popup_create({text}, {
202 \ 'pos': 'center',
203 \ 'zindex': 200,
204 \ 'border': [],
Bram Moolenaar9eaac892019-06-01 22:49:29 +0200205 \ 'padding': [],
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200206 \})
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200207< Use {options} to change the properties. E.g. add a 'filter'
208 option with value 'popup_filter_yesno'.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200209
210
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200211popup_filter_menu({id}, {key}) *popup_filter_menu()*
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200212 {not implemented yet}
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200213 Filter that can be used for a popup. It handles the cursor
214 keys to move the selected index in the popup. Space and Enter
215 can be used to select an item. Invokes the "callback" of the
216 popup menu with the index of the selected line as the second
217 argument.
218
219
220popup_filter_yesno({id}, {key}) *popup_filter_yesno()*
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200221 {not implemented yet}
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200222 Filter that can be used for a popup. It handles only the keys
223 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the
224 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N'
225 as the second argument. Pressing Esc and CTRL-C works like
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200226 pressing 'n'. Other keys are ignored.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200227
228
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200229popup_getoptions({id}) *popup_getoptions()*
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200230 Return the {options} for popup {id} in a Dict.
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200231 A zero value means the option was not set. For "zindex" the
232 default value is returned, not zero.
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200233
234 The "highlight" entry is omitted, use the 'wincolor' option
235 for that: >
236 let hl = getwinvar(winid, '&wincolor')
237
238< If popup window {id} is not found an empty Dict is returned.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200239
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200240
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200241popup_getpos({id}) *popup_getpos()*
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200242 Return the position and size of popup {id}. Returns a Dict
243 with these entries:
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200244 col screen column of the popup, one-based
245 line screen line of the popup, one-based
Bram Moolenaar2fd8e352019-06-01 20:16:48 +0200246 width width of the whole popup in screen cells
247 height height of the whole popup in screen cells
248 core_col screen column of the text box
249 core_line screen line of the text box
250 core_width width of the text box in screen cells
251 core_height height of the text box in screen cells
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200252 visible one if the popup is displayed, zero if hidden
Bram Moolenaarbc133542019-05-29 20:26:46 +0200253 Note that these are the actual screen positions. They differ
254 from the values in `popup_getoptions()` for the sizing and
255 positioning mechanism applied.
Bram Moolenaar2fd8e352019-06-01 20:16:48 +0200256
257 The "core_" values exclude the padding and border.
258
Bram Moolenaarbc133542019-05-29 20:26:46 +0200259 If popup window {id} is not found an empty Dict is returned.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200260
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200261
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200262popup_hide({id}) *popup_hide()*
263 If {id} is a displayed popup, hide it now. If the popup has a
264 filter it will not be invoked for so long as the popup is
265 hidden.
266 If window {id} does not exist nothing happens. If window {id}
267 exists but is not a popup window an error is given. *E993*
268
269
270popup_menu({text}, {options}) *popup_menu()*
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200271 {not implemented yet}
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200272 Show the {text} near the cursor, handle selecting one of the
273 items with cursorkeys, and close it an item is selected with
274 Space or Enter. {text} should have multiple lines to make this
275 useful. This works like: >
276 call popup_create({text}, {
277 \ 'pos': 'center',
278 \ 'zindex': 200,
279 \ 'wrap': 0,
280 \ 'border': [],
281 \ 'filter': 'popup_filter_menu',
282 \ })
283< Use {options} to change the properties. Should at least set
284 "callback" to a function that handles the selected item.
285
286
287popup_move({id}, {options}) *popup_move()*
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200288 Move popup {id} to the position specified with {options}.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200289 {options} may contain the items from |popup_create()| that
290 specify the popup position: "line", "col", "pos", "maxheight",
291 "minheight", "maxwidth" and "minwidth".
292 For {id} see `popup_hide()`.
293
294
295popup_notification({text}, {options}) *popup_notification()*
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200296 Show the {text} for 3 seconds at the top of the Vim window.
297 This works like: >
298 call popup_create({text}, {
299 \ 'line': 1,
300 \ 'col': 10,
Bram Moolenaardfa97f22019-06-15 14:31:55 +0200301 \ 'minwidth': 20,
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200302 \ 'time': 3000,
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +0200303 \ 'tabpage': -1,
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200304 \ 'zindex': 200,
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200305 \ 'drag': 1,
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200306 \ 'highlight': 'WarningMsg',
307 \ 'border': [],
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200308 \ 'padding': [0,1,0,1],
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200309 \ })
Bram Moolenaardfa97f22019-06-15 14:31:55 +0200310< The PopupNotification highlight group is used instead of
311 WarningMsg if it is defined.
Bram Moolenaar68d48f42019-06-12 22:42:41 +0200312< The position will be adjusted to avoid overlap with other
313 notifications.
314 Use {options} to change the properties.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200315
316
317popup_show({id}) *popup_show()*
318 If {id} is a hidden popup, show it now.
319 For {id} see `popup_hide()`.
320
321
322popup_setoptions({id}, {options}) *popup_setoptions()*
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200323 {not implemented yet}
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200324 Override options in popup {id} with entries in {options}.
325
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200326
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200327
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200328POPUP BUFFER AND WINDOW *popup-buffer*
329
330A new buffer is created to hold the text and text properties of the popup
331window. The buffer is always associated with the popup window and
332manipulation is restricted:
333- the buffer has no name
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200334- 'buftype' is "popup"
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200335- 'swapfile' is off
336- 'bufhidden' is "hide"
337- 'buflisted' is off
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200338- 'undolevels' is -1: no undo at all
Bram Moolenaarcc31ad92019-05-30 19:25:06 +0200339- all other buffer-local and window_local options are set to their Vim default
340 value.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200341
Bram Moolenaarcc31ad92019-05-30 19:25:06 +0200342It is possible to change the specifically mentioned options, but anything
343might break then, so better leave them alone.
Bram Moolenaar68e65602019-05-26 21:33:31 +0200344
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200345The window does have a cursor position, but the cursor is not displayed.
346
Bram Moolenaar868b7b62019-05-29 21:44:40 +0200347To execute a command in the context of the popup window and buffer use
348`win_execute()`. Example: >
349 call win_execute(winid, 'syntax enable')
350
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200351Options can be set on the window with `setwinvar()`, e.g.: >
352 call setwinvar(winid, '&wrap', 0)
353And options can be set on the buffer with `setbufvar()`, e.g.: >
354 call setbufvar(winbufnr(winid), '&filetype', 'java')
Bram Moolenaarc6896e22019-05-30 22:32:34 +0200355Note that this does not trigger autocommands. Use `win_execute()` if you do
356need them.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200357
358
359POPUP_CREATE() ARGUMENTS *popup_create-usage*
360
361The first argument of |popup_create()| specifies the text to be displayed, and
362optionally text properties. It is in one of three forms:
363- a string
364- a list of strings
365- a list of dictionaries, where each dictionary has these entries:
366 text String with the text to display.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200367 props A list of text properties. Optional.
368 Each entry is a dictionary, like the third argument of
369 |prop_add()|, but specifying the column in the
370 dictionary with a "col" entry, see below:
371 |popup-props|.
372
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200373The second argument of |popup_create()| is a dictionary with options:
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200374 line Screen line where to position the popup. Can use a
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200375 number or "cursor", "cursor+1" or "cursor-1" to use
376 the line of the cursor and add or subtract a number of
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200377 lines. If omitted the popup is vertically centered.
378 The first line is 1.
379 col Screen column where to position the popup. Can use a
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200380 number or "cursor" to use the column of the cursor,
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200381 "cursor+9" or "cursor-9" to add or subtract a number
382 of columns. If omitted the popup is horizontally
383 centered. The first column is 1.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200384 pos "topleft", "topright", "botleft" or "botright":
385 defines what corner of the popup "line" and "col" are
Bram Moolenaar8c2a6002019-05-30 14:29:45 +0200386 used for. When not set "topleft" is used.
387 Alternatively "center" can be used to position the
Bram Moolenaarac1f1bc2019-05-30 21:24:26 +0200388 popup in the center of the Vim window, in which case
389 "line" and "col" are ignored.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200390 fixed When FALSE (the default), and:
391 - "pos" is "botleft" or "topleft", and
392 - "wrap" is off, and
393 - the popup would be truncated at the right edge of
394 the screen, then
395 the popup is moved to the left so as to fit the
396 contents on the screen. Set to TRUE to disable this.
397 flip When TRUE (the default) and the position is relative
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200398 to the cursor, flip to below or above the cursor to
399 avoid overlap with the |popupmenu-completion| or
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200400 another popup with a higher "zindex".
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200401 {not implemented yet}
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200402 maxheight Maximum height of the contents, excluding border and
403 padding.
404 minheight Minimum height of the contents, excluding border and
405 padding.
406 maxwidth Maximum width of the contents, excluding border and
407 padding.
408 minwidth Minimum width of the contents, excluding border and
409 padding.
Bram Moolenaar8d241042019-06-12 23:40:01 +0200410 firstline First buffer line to display. When larger than one it
411 looks like the text scrolled up. When out of range
412 the last buffer line will at the top of the window.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200413 hidden When TRUE the popup exists but is not displayed; use
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200414 `popup_show()` to unhide it.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200415 {not implemented yet}
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +0200416 tabpage When -1: display the popup on all tabs.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200417 When 0 (the default): display the popup on the current
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +0200418 tab page.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200419 Otherwise the number of the tab page the popup is
Bram Moolenaarfc06cbb2019-06-15 14:14:31 +0200420 displayed on; when invalid the current tab page is used.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200421 {only -1 and 0 are implemented}
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200422 title Text to be displayed above the first item in the
423 popup, on top of any border. If there is no top
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200424 border one line of padding is added to put the title
425 on.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200426 {not implemented yet}
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200427 wrap TRUE to make the lines wrap (default TRUE).
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200428 drag TRUE to allow the popup to be dragged with the mouse
429 by grabbing at at the border. Has no effect if the
430 popup does not have a border.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200431 highlight Highlight group name to use for the text, stored in
432 the 'wincolor' option.
433 padding List with numbers, defining the padding
434 above/right/below/left of the popup (similar to CSS).
435 An empty list uses a padding of 1 all around. The
436 padding goes around the text, inside any border.
437 Padding uses the 'wincolor' highlight.
438 Example: [1, 2, 1, 3] has 1 line of padding above, 2
439 columns on the right, 1 line below and 3 columns on
440 the left.
441 border List with numbers, defining the border thickness
442 above/right/below/left of the popup (similar to CSS).
443 Only values of zero and non-zero are recognized.
444 An empty list uses a border all around.
445 borderhighlight List of highlight group names to use for the border.
446 When one entry it is used for all borders, otherwise
447 the highlight for the top/right/bottom/left border.
448 Example: ['TopColor', 'RightColor', 'BottomColor,
449 'LeftColor']
450 borderchars List with characters, defining the character to use
451 for the top/right/bottom/left border. Optionally
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200452 followed by the character to use for the
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200453 topleft/topright/botright/botleft corner.
454 Example: ['-', '|', '-', '|', '┌', '┐', '┘', '└']
455 When the list has one character it is used for all.
456 When the list has two characters the first is used for
457 the border lines, the second for the corners.
458 By default a double line is used all around when
459 'encoding' is "utf-8", otherwise ASCII characters are
460 used.
Bram Moolenaarb53fb312019-06-13 23:59:52 +0200461 zindex Priority for the popup, default 50. Minimum value is
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200462 1, maximum value is 32000.
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200463 time Time in milliseconds after which the popup will close.
464 When omitted |popup_close()| must be used.
Bram Moolenaar3397f742019-06-02 18:40:06 +0200465 moved Specifies to close the popup if the cursor moved:
466 - "any": if the cursor moved at all
467 - "word": if the cursor moved outside |<cword>|
468 - "WORD": if the cursor moved outside |<cWORD>|
469 - [{start}, {end}]: if the cursor moved before column
470 {start} or after {end}
471 The popup also closes if the cursor moves to another
472 line or to another window.
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200473 filter A callback that can filter typed characters, see
Bram Moolenaar042fb4b2019-06-02 14:49:56 +0200474 |popup-filter|.
475 callback A callback that is called when the popup closes, e.g.
476 when using |popup_filter_menu()|, see |popup-callback|.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200477
478Depending on the "zindex" the popup goes under or above other popups. The
479completion menu (|popup-menu|) has zindex 100. For messages that occur for a
480short time the suggestion is to use zindex 1000.
481
482By default text wraps, which causes a line in {lines} to occupy more than one
483screen line. When "wrap" is FALSE then the text outside of the popup or
484outside of the Vim window will not be displayed, thus truncated.
485
486
487POPUP TEXT PROPERTIES *popup-props*
488
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200489These are similar to the third argument of |prop_add()| except:
490- "lnum" is always the current line in the list
491- "bufnr" is always the buffer of the popup
492- "col" is in the Dict instead of a separate argument
493- "transparent" is extra
494So we get:
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200495 col starting column, counted in bytes, use one for the
496 first column.
497 length length of text in bytes; can be zero
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200498 end_lnum line number for the end of the text
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200499 end_col column just after the text; not used when "length" is
500 present; when {col} and "end_col" are equal, this is a
501 zero-width text property
502 id user defined ID for the property; when omitted zero is
503 used
504 type name of the text property type, as added with
505 |prop_type_add()|
506 transparent do not show these characters, show the text under it;
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200507 if there is a border character to the right or below
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200508 it will be made transparent as well
Bram Moolenaar7a8d0272019-05-26 23:32:06 +0200509 {not implemented yet}
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200510
511
512POPUP FILTER *popup-filter*
513
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200514A callback that gets any typed keys while a popup is displayed. The filter is
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200515not invoked when the popup is hidden.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200516
517The filter can return TRUE to indicate the key has been handled and is to be
518discarded, or FALSE to let Vim handle the key as usual in the current state.
Bram Moolenaar4d784b22019-05-25 19:51:39 +0200519In case it returns FALSE and there is another popup window visible, that
520filter is also called. The filter of the popup window with the highest zindex
521is called first.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200522
523The filter function is called with two arguments: the ID of the popup and the
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200524key, e.g.: >
525 func MyFilter(winid, key)
526 if a:key == "\<F2>"
527 " do something
528 return 1
529 endif
530 if a:key == 'x'
531 call popup_close(a:winid)
532 return 1
533 endif
534 return 0
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +0200535 endfunc
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200536
537Currently the key is what results after any mapping. This may change...
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200538
539Some common key actions:
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200540 x close the popup (see note below)
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200541 cursor keys select another entry
542 Tab accept current suggestion
543
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200544A mouse click arrives as <LeftMouse>. The coordinates are in
545v:mouse_popup_col and v:mouse_popup_row. The top-left screen cell of the
546popup is col 1, row 1 (not counting the border).
547
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200548Vim provides standard filters |popup_filter_menu()| and
549|popup_filter_yesno()|.
550
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200551Note that "x" is the normal way to close a popup. You may want to use Esc,
552but since many keys start with an Esc character, there may be a delay before
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +0200553Vim recognizes the Esc key. If you do use Esc, it is recommended to set the
Bram Moolenaarbf0eff02019-06-01 17:13:36 +0200554'ttimeoutlen' option to 100 and set 'timeout' and/or 'ttimeout'.
555
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200556
557POPUP CALLBACK *popup-callback*
558
559A callback that is invoked when the popup closes. Used by
Bram Moolenaar9eaac892019-06-01 22:49:29 +0200560|popup_filter_menu()|.
561
562The callback is invoked with two arguments: the ID of the popup window and the
563result, which could be an index in the popup lines, or whatever was passed as
564the second argument of `popup_close()`.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200565
Bram Moolenaar3397f742019-06-02 18:40:06 +0200566If the popup is closed because the cursor moved, the number -1 is passed to
567the callback.
568
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200569==============================================================================
5703. Examples *popup-examples*
571
572TODO
573
574Prompt the user to press y/Y or n/N: >
575
576 func MyDialogHandler(id, result)
577 if a:result
578 " ... 'y' or 'Y' was pressed
579 endif
580 endfunc
581
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200582 call popup_create(['Continue? y/n'], {
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200583 \ 'filter': 'popup_filter_yesno',
584 \ 'callback': 'MyDialogHandler',
585 \ })
586<
587
588 vim:tw=78:ts=8:noet:ft=help:norl: