blob: 4813308903990582901b6f7a962366f6397190cb [file] [log] [blame]
Bram Moolenaar5c017b22019-05-21 23:09:01 +02001*popup.txt* For Vim version 8.1. Last change: 2019 May 21
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
9THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
10
111. Introduction |popup-intro|
122. Functions |popup-functions|
133. Examples |popup-examples|
14
15
Bram Moolenaar5c017b22019-05-21 23:09:01 +020016{not available if the |+eval| feature was disabled at compile time}
17{not able to use text properties if the |+textprop| feature was disabled at
18compile time}
Bram Moolenaar957f85d2019-05-12 21:43:48 +020019
20==============================================================================
211. Introduction *popup-intro*
22
Bram Moolenaar5c017b22019-05-21 23:09:01 +020023We are talking about popup windows here, text that goes on top of the regular
24windows and is under control of a plugin. You cannot edit the text in the
25popup window like with regular windows.
26
27A popup window can be used for such things as:
28- briefly show a message without changing the command line
29- prompt the user with a dialog
30- display information while typing
31- give extra information for auto-completion
32
33The text in the popup window can be colored with |text-properties|. It is
34also possible to use syntax highlighting.
35
36A popup window has a window-ID like other windows, but behaves differently.
37The size can be up to the whole Vim window and it overlaps other windows.
38It contains a buffer, and that buffer is always associated with the popup
39window. The window cannot be used in Normal, Visual or Insert mode, it does
40not get keyboard focus. You can use functions like `setbufline()` to change
41the text in the buffer. There are more differences from how this window and
42buffer behave compared to regular windows and buffers, see |popup-buffer|.
43
44If this is not what you are looking for, check out other popup functionality:
Bram Moolenaar957f85d2019-05-12 21:43:48 +020045- popup menu, see |popup-menu|
46- balloon, see |balloon-eval|
47
Bram Moolenaar5c017b22019-05-21 23:09:01 +020048
49TODO:
50
51Example how to use syntax highlighting of a code snippet.
52
53Scrolling: When the screen scrolls up for output of an Ex command, what
54happens with popups?
551. Stay where they are. Problem: listed text may go behind and can't be read.
562. Scroll with the page. What if they get updated? Either postpone, or take
57 the scroll offset into account.
58Probably 2. is the best choice.
59
60Positioning relative to the popup-menu to avoid overlapping with it; add a
61function to get the position and size of the popup-menu.
62
63
64IMPLEMENTATION:
65- Put code in popupwin.c
66- Use win_update() for displaying
67- At first redraw all windows NOT_VALID when the popup moves or hides.
68- At first always display the popup windows at the end of update_screen(),
69 lowest zindex first.
70- Later make it more efficient and avoid flicker
71- Use a separate list of windows, one for each tab and one global. Also put
72 "aucmd_win" in there.
73- add optional {buf} command to execute(). Only works for a buffer that is
74 visible in a window in the current tab or in a popup window.
75 E.g. for execute('syntax enable', 'silent', bufnr)
76
Bram Moolenaar957f85d2019-05-12 21:43:48 +020077
78==============================================================================
792. Functions *popup-functions*
80
81THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
82
83Proposal and discussion on issue #4063: https://github.com/vim/vim/issues/4063
84
Bram Moolenaar5c017b22019-05-21 23:09:01 +020085[functions to be moved to eval.txt later, keep list of functions here]
Bram Moolenaar957f85d2019-05-12 21:43:48 +020086
Bram Moolenaar5c017b22019-05-21 23:09:01 +020087popup_create({text}, {options}) *popup_create()*
88 Open a popup window showing {text}, which is either:
89 - a string
90 - a list of strings
91 - a list of text lines with text properties
Bram Moolenaar957f85d2019-05-12 21:43:48 +020092 {options} is a dictionary with many possible entries.
Bram Moolenaar5c017b22019-05-21 23:09:01 +020093 See |popup_create-usage| for details.
Bram Moolenaar957f85d2019-05-12 21:43:48 +020094
Bram Moolenaar5c017b22019-05-21 23:09:01 +020095 Returns a window-ID, which can be used with other popup
96 functions. Use `winbufnr()` to get the number of the buffer
97 in the window: >
98 let winid = popup_create('hello', {})
99 let bufnr = winbufnr(winid)
100 call setbufline(bufnr, 2, 'second line')
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200101
102
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200103popup_dialog({text}, {options}) *popup_dialog()*
104 Just like |popup_create()| but with these default options: >
105 call popup_create({text}, {
106 \ 'pos': 'center',
107 \ 'zindex': 200,
108 \ 'border': [],
109 \})
110< Use {options} to change the properties.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200111
112
113popup_notification({text}, {options}) *popup_notification()*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200114 Show the {text} for 3 seconds at the top of the Vim window.
115 This works like: >
116 call popup_create({text}, {
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200117 \ 'line': 1,
118 \ 'col': 10,
119 \ 'time': 3000,
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200120 \ 'tab': -1,
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200121 \ 'zindex': 200,
122 \ 'highlight': 'WarningMsg',
123 \ 'border: [],
124 \ })
125< Use {options} to change the properties.
126
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200127
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200128popup_atcursor({text}, {options}) *popup_atcursor()*
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200129 Show the {text} above the cursor, and close it when the cursor
130 moves. This works like: >
131 call popup_create({text}, {
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200132 \ 'line': 'cursor-1',
133 \ 'col': 'cursor',
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200134 \ 'moved': 'WORD',
135 \ })
136< Use {options} to change the properties.
137
138
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200139popup_menu({text}, {options}) *popup_menu()*
140 Show the {text} near the cursor, handle selecting one of the
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200141 items with cursorkeys, and close it an item is selected with
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200142 Space or Enter. {text} should have multiple lines to make this
143 useful. This works like: >
144 call popup_create({text}, {
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200145 \ 'pos': 'center',
146 \ 'zindex': 200,
147 \ 'wrap': 0,
148 \ 'border': [],
149 \ 'filter': 'popup_filter_menu',
150 \ })
151< Use {options} to change the properties. Should at least set
152 "callback" to a function that handles the selected item.
153
154
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200155popup_show({id}) *popup_show()*
156 If {id} is a hidden popup, show it now.
157
158popup_hide({id}) *popup_hide()*
159 If {id} is a displayed popup, hide it now. If the popup has a
160 filter it will not be invoked for so long as the popup is
161 hidden.
162
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200163popup_move({id}, {options}) *popup_move()*
164 Move popup {id} to the position speficied with {options}.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200165 {options} may contain the items from |popup_create()| that
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200166 specify the popup position: "line", "col", "pos", "maxheight",
167 "minheight", "maxwidth" and "minwidth".
168
169
170popup_filter_menu({id}, {key}) *popup_filter_menu()*
171 Filter that can be used for a popup. It handles the cursor
172 keys to move the selected index in the popup. Space and Enter
173 can be used to select an item. Invokes the "callback" of the
174 popup menu with the index of the selected line as the second
175 argument.
176
177
178popup_filter_yesno({id}, {key}) *popup_filter_yesno()*
179 Filter that can be used for a popup. It handles only the keys
180 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the
181 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N'
182 as the second argument. Pressing Esc and CTRL-C works like
183 pressing 'n'.
184
185
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200186popup_setoptions({id}, {options}) *popup_setoptions()*
187 Override options in popup {id} with entries in {options}.
188
189
190popup_getoptions({id}) *popup_getoptions()*
191 Return the {options} for popup {id}.
192
193
194popup_close({id}) *popup_close()*
195 Close popup {id}.
196
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200197 *:popupclear* *:popupc*
198:popupc[lear] Emergency solution to a misbehaving plugin: close all popup
199 windows.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200200
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200201
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200202POPUP BUFFER AND WINDOW *popup-buffer*
203
204A new buffer is created to hold the text and text properties of the popup
205window. The buffer is always associated with the popup window and
206manipulation is restricted:
207- the buffer has no name
208- 'buftype' is "popup"
209- 'swapfile' is off
210- 'bufhidden' is "hide"
211- 'buflisted' is off
212TODO: more
213
214The window does have a cursor position, but the cursor is not displayed.
215
216Options can be set on the window with `setwinvar()`, e.g.: >
217 call setwinvar(winid, '&wrap', 0)
218And options can be set on the buffer with `setbufvar()`, e.g.: >
219 call setbufvar(winbufnr(winid), '&filetype', 'java')
220
221
222POPUP_CREATE() ARGUMENTS *popup_create-usage*
223
224The first argument of |popup_create()| specifies the text to be displayed, and
225optionally text properties. It is in one of three forms:
226- a string
227- a list of strings
228- a list of dictionaries, where each dictionary has these entries:
229 text String with the text to display.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200230 props A list of text properties. Optional.
231 Each entry is a dictionary, like the third argument of
232 |prop_add()|, but specifying the column in the
233 dictionary with a "col" entry, see below:
234 |popup-props|.
235
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200236The second argument of |popup_create()| is a dictionary with options:
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200237 line screen line where to position the popup; can use
238 "cursor", "cursor+1" or "cursor-1" to use the line of
239 the cursor and add or subtract a number of lines;
240 default is "cursor-1".
241 col screen column where to position the popup; can use
242 "cursor" to use the column of the cursor, "cursor+99"
243 and "cursor-99" to add or subtract a number of
244 columns; default is "cursor"
245 pos "topleft", "topright", "botleft" or "botright":
246 defines what corner of the popup "line" and "col" are
247 used for. Default is "botleft". Alternatively
248 "center" can be used to position the popup somewhere
249 near the cursor.
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200250 flip when TRUE (the default) and the position is relative
251 to the cursor, flip to below or above the cursor to
252 avoid overlap with the |popupmenu-completion| or
253 another popup with a higher "zindex"
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200254 maxheight maximum height
255 minheight minimum height
256 maxwidth maximum width
257 minwidth minimum width
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200258 hidden when TRUE the popup exists but is not displayed; use
259 `popup_show()` to unhide it.
260 tab when -1: display the popup on all tabs; when 0 (the
261 default): display the popup on the current tab;
262 otherwise the number of the tab page the popup is
263 displayed on; when invalid the current tab is used
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200264 title text to be displayed above the first item in the
265 popup, on top of any border
266 wrap TRUE to make the lines wrap (default TRUE)
267 highlight highlight group name to use for the text, defines the
268 background and foreground color
269 border list with numbers, defining the border thickness
270 above/right/below/left of the popup; an empty list
271 uses a border of 1 all around
272 borderhighlight highlight group name to use for the border
273 borderchars list with characters, defining the character to use
274 for the top/right/bottom/left border; optionally
275 followed by the character to use for the
276 topright/botright/botleft/topleft corner; an empty
277 list can be used to show a double line all around
278 zindex priority for the popup, default 50
279 time time in milliseconds after which the popup will close;
280 when omitted |popup_close()| must be used.
281 moved "cell": close the popup if the cursor moved at least
282 one screen cell; "word" allows for moving within
283 |<cword>|, "WORD" allows for moving within |<cWORD>|,
284 a list with two numbers specifies the start and end
285 column
286 filter a callback that can filter typed characters, see
287 |popup-filter|
288 callback a callback to be used when the popup closes, e.g. when
289 using |popup_filter_menu()|, see |popup-callback|.
290
291Depending on the "zindex" the popup goes under or above other popups. The
292completion menu (|popup-menu|) has zindex 100. For messages that occur for a
293short time the suggestion is to use zindex 1000.
294
295By default text wraps, which causes a line in {lines} to occupy more than one
296screen line. When "wrap" is FALSE then the text outside of the popup or
297outside of the Vim window will not be displayed, thus truncated.
298
299
300POPUP TEXT PROPERTIES *popup-props*
301
302These are similar to the third argument of |prop_add()|, but not exactly the
303same, since they only apply to one line.
304 col starting column, counted in bytes, use one for the
305 first column.
306 length length of text in bytes; can be zero
307 end_col column just after the text; not used when "length" is
308 present; when {col} and "end_col" are equal, this is a
309 zero-width text property
310 id user defined ID for the property; when omitted zero is
311 used
312 type name of the text property type, as added with
313 |prop_type_add()|
314 transparent do not show these characters, show the text under it;
315 if there is an border character to the right or below
316 it will be made transparent as well
317
318
319POPUP FILTER *popup-filter*
320
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200321A callback that gets any typed keys while a popup is displayed. The filter is
322not invoked for as long as the popup is hidden.
323
324The filter can return TRUE to indicate the key has been handled and is to be
325discarded, or FALSE to let Vim handle the key as usual in the current state.
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200326
327The filter function is called with two arguments: the ID of the popup and the
328key.
329
330Some common key actions:
331 Esc close the popup
332 cursor keys select another entry
333 Tab accept current suggestion
334
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200335A mouse click arrives as <LeftMouse>. The coordinates are in
336v:mouse_popup_col and v:mouse_popup_row. The top-left screen cell of the
337popup is col 1, row 1 (not counting the border).
338
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200339Vim provides standard filters |popup_filter_menu()| and
340|popup_filter_yesno()|.
341
342
343POPUP CALLBACK *popup-callback*
344
345A callback that is invoked when the popup closes. Used by
346|popup_filter_menu()|. Invoked with two arguments: the ID of the popup and
347the result, which would usually be an index in the popup lines, or whatever
348the filter wants to pass.
349
350==============================================================================
3513. Examples *popup-examples*
352
353TODO
354
355Prompt the user to press y/Y or n/N: >
356
357 func MyDialogHandler(id, result)
358 if a:result
359 " ... 'y' or 'Y' was pressed
360 endif
361 endfunc
362
Bram Moolenaar5c017b22019-05-21 23:09:01 +0200363 call popup_create(['Continue? y/n'], {
Bram Moolenaar957f85d2019-05-12 21:43:48 +0200364 \ 'filter': 'popup_filter_yesno',
365 \ 'callback': 'MyDialogHandler',
366 \ })
367<
368
369 vim:tw=78:ts=8:noet:ft=help:norl: