Mercurial > vim

comparison runtime/doc/popup.txt @ 16778:eda4d65f232c v8.1.1391

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.1.1391: no popup window support commit https://github.com/vim/vim/commit/4d784b21d14fc66e98a2b07f70343cdd4acd62aa Author: Bram Moolenaar <Bram@vim.org> Date: Sat May 25 19:51:39 2019 +0200 patch 8.1.1391: no popup window support Problem: No popup window support. Solution: Add initial code for popup windows. Add the 'wincolor' option.
author Bram Moolenaar <Bram@vim.org>
date Sat, 25 May 2019 20:00:08 +0200
parents 6030631a1541
children 12e3a3afdb6a
comparison
equal deleted inserted replaced
16777:20d51e99dd6a 16778:eda4d65f232c
25 popup window like with regular windows. 25 popup window like with regular windows.
26 26
27 A popup window can be used for such things as: 27 A popup window can be used for such things as:
28 - briefly show a message without changing the command line 28 - briefly show a message without changing the command line
29 - prompt the user with a dialog 29 - prompt the user with a dialog
30 - display information while typing 30 - display contextual information while typing
31 - give extra information for auto-completion 31 - give extra information for auto-completion
32 32
33 The text in the popup window can be colored with |text-properties|. It is 33 The text in the popup window can be colored with |text-properties|. It is
34 also possible to use syntax highlighting. 34 also possible to use syntax highlighting.
35
36 The default color used is "Pmenu". If you prefer something else use the
37 "highlight" argument or the 'wincolor' option, e.g.: >
38 hi MyPopupColor ctermbg=lightblue guibg=lightblue
39 call setwinvar(winid, '&wincolor', 'MyPopupColor')
40
41 'hlsearch' and match highlighting are not displayed in a popup window.
35 42
36 A popup window has a window-ID like other windows, but behaves differently. 43 A popup window has a window-ID like other windows, but behaves differently.
37 The size can be up to the whole Vim window and it overlaps other windows. 44 The size can be up to the whole Vim window and it overlaps other windows.
38 It contains a buffer, and that buffer is always associated with the popup 45 It contains a buffer, and that buffer is always associated with the popup
39 window. The window cannot be used in Normal, Visual or Insert mode, it does 46 window. The window cannot be used in Normal, Visual or Insert mode, it does
44 If this is not what you are looking for, check out other popup functionality: 51 If this is not what you are looking for, check out other popup functionality:
45 - popup menu, see |popup-menu| 52 - popup menu, see |popup-menu|
46 - balloon, see |balloon-eval| 53 - balloon, see |balloon-eval|
47 54
48 55
56 WINDOW POSITION AND SIZE *popup-position*
57
58 The height of the window is normally equal to the number of lines in the
59 buffer. It can be limited with the "maxheight" property. You can use empty
60 lines to increase the height.
61
62 The width of the window is normally equal to the longest line in the buffer.
63 It can be limited with the "maxwidth" property. You can use spaces to
64 increase the width.
65
66 By default the 'wrap' option is set, so that no text disappears. However, if
67 there is not enough space, some text may be invisible.
68
69
49 TODO: 70 TODO:
50 71
51 Example how to use syntax highlighting of a code snippet. 72 Example how to use syntax highlighting of a code snippet.
52 73
53 Scrolling: When the screen scrolls up for output of an Ex command, what 74 Scrolling: When the screen scrolls up for output of an Ex command, what
55 1. Stay where they are. Problem: listed text may go behind and can't be read. 76 1. Stay where they are. Problem: listed text may go behind and can't be read.
56 2. Scroll with the page. What if they get updated? Either postpone, or take 77 2. Scroll with the page. What if they get updated? Either postpone, or take
57 the scroll offset into account. 78 the scroll offset into account.
58 Probably 2. is the best choice. 79 Probably 2. is the best choice.
59 80
60 Positioning relative to the popup-menu to avoid overlapping with it; add a
61 function to get the position and size of the popup-menu.
62
63 81
64 IMPLEMENTATION: 82 IMPLEMENTATION:
65 - Put code in popupwin.c 83 - Code is in popupwin.c
66 - Use win_update() for displaying 84 - handle screen resize in screenalloc().
67 - At first redraw all windows NOT_VALID when the popup moves or hides. 85 - Support tab-local popup windows, use tp_first_popupwin and
68 - At first always display the popup windows at the end of update_screen(), 86 first_tab_popupwin. Swap like with firstwin/curwin.
69 lowest zindex first. 87 - Make redrawing more efficient and avoid flicker.
70 - Later make it more efficient and avoid flicker 88 - implement all the unimplemented features.
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 89
77 90
78 ============================================================================== 91 ==============================================================================
79 2. Functions *popup-functions* 92 2. Functions *popup-functions*
80 93
87 popup_create({text}, {options}) *popup_create()* 100 popup_create({text}, {options}) *popup_create()*
88 Open a popup window showing {text}, which is either: 101 Open a popup window showing {text}, which is either:
89 - a string 102 - a string
90 - a list of strings 103 - a list of strings
91 - a list of text lines with text properties 104 - a list of text lines with text properties
105 {not implemented yet}
92 {options} is a dictionary with many possible entries. 106 {options} is a dictionary with many possible entries.
93 See |popup_create-usage| for details. 107 See |popup_create-usage| for details.
94 108
95 Returns a window-ID, which can be used with other popup 109 Returns a window-ID, which can be used with other popup
96 functions. Use `winbufnr()` to get the number of the buffer 110 functions. Use `winbufnr()` to get the number of the buffer
97 in the window: > 111 in the window: >
98 let winid = popup_create('hello', {}) 112 let winid = popup_create('hello', {})
99 let bufnr = winbufnr(winid) 113 let bufnr = winbufnr(winid)
100 call setbufline(bufnr, 2, 'second line') 114 call setbufline(bufnr, 2, 'second line')
115 < In case of failure zero is returned.
116
117
118 popup_close({id}) *popup_close()*
119 Close popup {id}. The window and the associated buffer will
120 be deleted.
101 121
102 122
103 popup_dialog({text}, {options}) *popup_dialog()* 123 popup_dialog({text}, {options}) *popup_dialog()*
124 {not implemented yet}
104 Just like |popup_create()| but with these default options: > 125 Just like |popup_create()| but with these default options: >
105 call popup_create({text}, { 126 call popup_create({text}, {
106 \ 'pos': 'center', 127 \ 'pos': 'center',
107 \ 'zindex': 200, 128 \ 'zindex': 200,
108 \ 'border': [], 129 \ 'border': [],
109 \}) 130 \})
110 < Use {options} to change the properties. 131 < Use {options} to change the properties.
111 132
112 133
113 popup_notification({text}, {options}) *popup_notification()* 134 popup_notification({text}, {options}) *popup_notification()*
135 {not implemented yet}
114 Show the {text} for 3 seconds at the top of the Vim window. 136 Show the {text} for 3 seconds at the top of the Vim window.
115 This works like: > 137 This works like: >
116 call popup_create({text}, { 138 call popup_create({text}, {
117 \ 'line': 1, 139 \ 'line': 1,
118 \ 'col': 10, 140 \ 'col': 10,
124 \ }) 146 \ })
125 < Use {options} to change the properties. 147 < Use {options} to change the properties.
126 148
127 149
128 popup_atcursor({text}, {options}) *popup_atcursor()* 150 popup_atcursor({text}, {options}) *popup_atcursor()*
151 {not implemented yet}
129 Show the {text} above the cursor, and close it when the cursor 152 Show the {text} above the cursor, and close it when the cursor
130 moves. This works like: > 153 moves. This works like: >
131 call popup_create({text}, { 154 call popup_create({text}, {
132 \ 'line': 'cursor-1', 155 \ 'line': 'cursor-1',
133 \ 'col': 'cursor', 156 \ 'col': 'cursor',
135 \ }) 158 \ })
136 < Use {options} to change the properties. 159 < Use {options} to change the properties.
137 160
138 161
139 popup_menu({text}, {options}) *popup_menu()* 162 popup_menu({text}, {options}) *popup_menu()*
163 {not implemented yet}
140 Show the {text} near the cursor, handle selecting one of the 164 Show the {text} near the cursor, handle selecting one of the
141 items with cursorkeys, and close it an item is selected with 165 items with cursorkeys, and close it an item is selected with
142 Space or Enter. {text} should have multiple lines to make this 166 Space or Enter. {text} should have multiple lines to make this
143 useful. This works like: > 167 useful. This works like: >
144 call popup_create({text}, { 168 call popup_create({text}, {
151 < Use {options} to change the properties. Should at least set 175 < Use {options} to change the properties. Should at least set
152 "callback" to a function that handles the selected item. 176 "callback" to a function that handles the selected item.
153 177
154 178
155 popup_show({id}) *popup_show()* 179 popup_show({id}) *popup_show()*
180 {not implemented yet}
156 If {id} is a hidden popup, show it now. 181 If {id} is a hidden popup, show it now.
157 182
158 popup_hide({id}) *popup_hide()* 183 popup_hide({id}) *popup_hide()*
184 {not implemented yet}
159 If {id} is a displayed popup, hide it now. If the popup has a 185 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 186 filter it will not be invoked for so long as the popup is
161 hidden. 187 hidden.
162 188
163 popup_move({id}, {options}) *popup_move()* 189 popup_move({id}, {options}) *popup_move()*
190 {not implemented yet}
164 Move popup {id} to the position speficied with {options}. 191 Move popup {id} to the position speficied with {options}.
165 {options} may contain the items from |popup_create()| that 192 {options} may contain the items from |popup_create()| that
166 specify the popup position: "line", "col", "pos", "maxheight", 193 specify the popup position: "line", "col", "pos", "maxheight",
167 "minheight", "maxwidth" and "minwidth". 194 "minheight", "maxwidth" and "minwidth".
168 195
169 196
170 popup_filter_menu({id}, {key}) *popup_filter_menu()* 197 popup_filter_menu({id}, {key}) *popup_filter_menu()*
198 {not implemented yet}
171 Filter that can be used for a popup. It handles the cursor 199 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 200 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 201 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 202 popup menu with the index of the selected line as the second
175 argument. 203 argument.
176 204
177 205
178 popup_filter_yesno({id}, {key}) *popup_filter_yesno()* 206 popup_filter_yesno({id}, {key}) *popup_filter_yesno()*
207 {not implemented yet}
179 Filter that can be used for a popup. It handles only the keys 208 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 209 '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' 210 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 211 as the second argument. Pressing Esc and CTRL-C works like
183 pressing 'n'. 212 pressing 'n'.
184 213
185 214
186 popup_setoptions({id}, {options}) *popup_setoptions()* 215 popup_setoptions({id}, {options}) *popup_setoptions()*
216 {not implemented yet}
187 Override options in popup {id} with entries in {options}. 217 Override options in popup {id} with entries in {options}.
188 218
189 219
190 popup_getoptions({id}) *popup_getoptions()* 220 popup_getoptions({id}) *popup_getoptions()*
221 {not implemented yet}
191 Return the {options} for popup {id}. 222 Return the {options} for popup {id}.
192 223
193 224 popup_getposition({id}) *popup_getposition()*
194 popup_close({id}) *popup_close()* 225 {not implemented yet}
195 Close popup {id}. 226 Return the position and size of popup {id}. Returns a Dict
227 with these entries:
228 col screen column of the popup, one-based
229 line screen line of the popup, one-based
230 width width of the popup in screen cells
231 height height of the popup in screen cells
232
233 win_execute({id}, {command})
234 {not implemented yet}
235 Like `execute()` but in the context of window {id}.
236 The window will temporarily be made the current window,
237 without triggering autocommands.
238 Example: >
239 call win_execute(winid, 'syntax enable')
240 <
196 241
197 *:popupclear* *:popupc* 242 *:popupclear* *:popupc*
198 :popupc[lear] Emergency solution to a misbehaving plugin: close all popup 243 :popupc[lear] Emergency solution to a misbehaving plugin: close all popup
199 windows. 244 windows.
200 245
207 - the buffer has no name 252 - the buffer has no name
208 - 'buftype' is "popup" 253 - 'buftype' is "popup"
209 - 'swapfile' is off 254 - 'swapfile' is off
210 - 'bufhidden' is "hide" 255 - 'bufhidden' is "hide"
211 - 'buflisted' is off 256 - 'buflisted' is off
257 - 'undolevels' is -1: no undo at all
212 TODO: more 258 TODO: more
213 259
214 The window does have a cursor position, but the cursor is not displayed. 260 The window does have a cursor position, but the cursor is not displayed.
215 261
216 Options can be set on the window with `setwinvar()`, e.g.: > 262 Options can be set on the window with `setwinvar()`, e.g.: >
224 The first argument of |popup_create()| specifies the text to be displayed, and 270 The first argument of |popup_create()| specifies the text to be displayed, and
225 optionally text properties. It is in one of three forms: 271 optionally text properties. It is in one of three forms:
226 - a string 272 - a string
227 - a list of strings 273 - a list of strings
228 - a list of dictionaries, where each dictionary has these entries: 274 - a list of dictionaries, where each dictionary has these entries:
275 {not implemented yet}
229 text String with the text to display. 276 text String with the text to display.
230 props A list of text properties. Optional. 277 props A list of text properties. Optional.
231 Each entry is a dictionary, like the third argument of 278 Each entry is a dictionary, like the third argument of
232 |prop_add()|, but specifying the column in the 279 |prop_add()|, but specifying the column in the
233 dictionary with a "col" entry, see below: 280 dictionary with a "col" entry, see below:
236 The second argument of |popup_create()| is a dictionary with options: 283 The second argument of |popup_create()| is a dictionary with options:
237 line screen line where to position the popup; can use 284 line screen line where to position the popup; can use
238 "cursor", "cursor+1" or "cursor-1" to use the line of 285 "cursor", "cursor+1" or "cursor-1" to use the line of
239 the cursor and add or subtract a number of lines; 286 the cursor and add or subtract a number of lines;
240 default is "cursor-1". 287 default is "cursor-1".
288 {only number is implemented}
241 col screen column where to position the popup; can use 289 col screen column where to position the popup; can use
242 "cursor" to use the column of the cursor, "cursor+99" 290 "cursor" to use the column of the cursor, "cursor+99"
243 and "cursor-99" to add or subtract a number of 291 and "cursor-99" to add or subtract a number of
244 columns; default is "cursor" 292 columns; default is "cursor"
293 {only number is implemented}
245 pos "topleft", "topright", "botleft" or "botright": 294 pos "topleft", "topright", "botleft" or "botright":
246 defines what corner of the popup "line" and "col" are 295 defines what corner of the popup "line" and "col" are
247 used for. Default is "botleft". Alternatively 296 used for. Default is "botleft". Alternatively
248 "center" can be used to position the popup somewhere 297 "center" can be used to position the popup in the
249 near the cursor. 298 center of the Vim window.
299 {not implemented yet}
250 flip when TRUE (the default) and the position is relative 300 flip when TRUE (the default) and the position is relative
251 to the cursor, flip to below or above the cursor to 301 to the cursor, flip to below or above the cursor to
252 avoid overlap with the |popupmenu-completion| or 302 avoid overlap with the |popupmenu-completion| or
253 another popup with a higher "zindex" 303 another popup with a higher "zindex"
304 {not implemented yet}
254 maxheight maximum height 305 maxheight maximum height
255 minheight minimum height 306 minheight minimum height
307 {not implemented yet}
256 maxwidth maximum width 308 maxwidth maximum width
257 minwidth minimum width 309 minwidth minimum width
310 {not implemented yet}
258 hidden when TRUE the popup exists but is not displayed; use 311 hidden when TRUE the popup exists but is not displayed; use
259 `popup_show()` to unhide it. 312 `popup_show()` to unhide it.
313 {not implemented yet}
260 tab when -1: display the popup on all tabs; when 0 (the 314 tab when -1: display the popup on all tabs; when 0 (the
261 default): display the popup on the current tab; 315 default): display the popup on the current tab;
262 otherwise the number of the tab page the popup is 316 otherwise the number of the tab page the popup is
263 displayed on; when invalid the current tab is used 317 displayed on; when invalid the current tab is used
318 {only -1 and 0 are implemented}
264 title text to be displayed above the first item in the 319 title text to be displayed above the first item in the
265 popup, on top of any border 320 popup, on top of any border
321 {not implemented yet}
266 wrap TRUE to make the lines wrap (default TRUE) 322 wrap TRUE to make the lines wrap (default TRUE)
267 highlight highlight group name to use for the text, defines the 323 {not implemented yet}
268 background and foreground color 324 highlight highlight group name to use for the text, stored in
325 'wincolor'
326 {not implemented yet}
269 border list with numbers, defining the border thickness 327 border list with numbers, defining the border thickness
270 above/right/below/left of the popup; an empty list 328 above/right/below/left of the popup; an empty list
271 uses a border of 1 all around 329 uses a border of 1 all around
330 {not implemented yet}
272 borderhighlight highlight group name to use for the border 331 borderhighlight highlight group name to use for the border
332 {not implemented yet}
273 borderchars list with characters, defining the character to use 333 borderchars list with characters, defining the character to use
274 for the top/right/bottom/left border; optionally 334 for the top/right/bottom/left border; optionally
275 followed by the character to use for the 335 followed by the character to use for the
276 topright/botright/botleft/topleft corner; an empty 336 topright/botright/botleft/topleft corner; an empty
277 list can be used to show a double line all around 337 list can be used to show a double line all around
338 {not implemented yet}
278 zindex priority for the popup, default 50 339 zindex priority for the popup, default 50
279 time time in milliseconds after which the popup will close; 340 time time in milliseconds after which the popup will close;
280 when omitted |popup_close()| must be used. 341 when omitted |popup_close()| must be used.
342 {not implemented yet}
281 moved "cell": close the popup if the cursor moved at least 343 moved "cell": close the popup if the cursor moved at least
282 one screen cell; "word" allows for moving within 344 one screen cell; "word" allows for moving within
283 |<cword>|, "WORD" allows for moving within |<cWORD>|, 345 |<cword>|, "WORD" allows for moving within |<cWORD>|,
284 a list with two numbers specifies the start and end 346 a list with two numbers specifies the start and end
285 column 347 column
348 {not implemented yet}
286 filter a callback that can filter typed characters, see 349 filter a callback that can filter typed characters, see
287 |popup-filter| 350 |popup-filter|
351 {not implemented yet}
288 callback a callback to be used when the popup closes, e.g. when 352 callback a callback to be used when the popup closes, e.g. when
289 using |popup_filter_menu()|, see |popup-callback|. 353 using |popup_filter_menu()|, see |popup-callback|.
354 {not implemented yet}
290 355
291 Depending on the "zindex" the popup goes under or above other popups. The 356 Depending on the "zindex" the popup goes under or above other popups. The
292 completion menu (|popup-menu|) has zindex 100. For messages that occur for a 357 completion menu (|popup-menu|) has zindex 100. For messages that occur for a
293 short time the suggestion is to use zindex 1000. 358 short time the suggestion is to use zindex 1000.
294 359
297 outside of the Vim window will not be displayed, thus truncated. 362 outside of the Vim window will not be displayed, thus truncated.
298 363
299 364
300 POPUP TEXT PROPERTIES *popup-props* 365 POPUP TEXT PROPERTIES *popup-props*
301 366
367 {not implemented yet}
302 These are similar to the third argument of |prop_add()|, but not exactly the 368 These are similar to the third argument of |prop_add()|, but not exactly the
303 same, since they only apply to one line. 369 same, since they only apply to one line.
304 col starting column, counted in bytes, use one for the 370 col starting column, counted in bytes, use one for the
305 first column. 371 first column.
306 length length of text in bytes; can be zero 372 length length of text in bytes; can be zero
316 it will be made transparent as well 382 it will be made transparent as well
317 383
318 384
319 POPUP FILTER *popup-filter* 385 POPUP FILTER *popup-filter*
320 386
387 {not implemented yet}
321 A callback that gets any typed keys while a popup is displayed. The filter is 388 A callback that gets any typed keys while a popup is displayed. The filter is
322 not invoked for as long as the popup is hidden. 389 not invoked when the popup is hidden.
323 390
324 The filter can return TRUE to indicate the key has been handled and is to be 391 The filter can return TRUE to indicate the key has been handled and is to be
325 discarded, or FALSE to let Vim handle the key as usual in the current state. 392 discarded, or FALSE to let Vim handle the key as usual in the current state.
393 In case it returns FALSE and there is another popup window visible, that
394 filter is also called. The filter of the popup window with the highest zindex
395 is called first.
326 396
327 The filter function is called with two arguments: the ID of the popup and the 397 The filter function is called with two arguments: the ID of the popup and the
328 key. 398 key.
329 399
330 Some common key actions: 400 Some common key actions:
340 |popup_filter_yesno()|. 410 |popup_filter_yesno()|.
341 411
342 412
343 POPUP CALLBACK *popup-callback* 413 POPUP CALLBACK *popup-callback*
344 414
415 {not implemented yet}
345 A callback that is invoked when the popup closes. Used by 416 A callback that is invoked when the popup closes. Used by
346 |popup_filter_menu()|. Invoked with two arguments: the ID of the popup and 417 |popup_filter_menu()|. Invoked with two arguments: the ID of the popup and
347 the result, which would usually be an index in the popup lines, or whatever 418 the result, which would usually be an index in the popup lines, or whatever
348 the filter wants to pass. 419 the filter wants to pass.
349 420