Mercurial > vim

comparison runtime/doc/popup.txt @ 17026:905e1b154058 v8.1.1513

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.1.1513: all popup functionality is in functions, except :popupclear commit https://github.com/vim/vim/commit/3ff5f0f05d437a6b3eaf3caa5dc2762b49314617 Author: Bram Moolenaar <Bram@vim.org> Date: Mon Jun 10 13:11:22 2019 +0200 patch 8.1.1513: all popup functionality is in functions, except :popupclear Problem: All popup functionality is in functions, except :popupclear. Solution: Add popup_clear() for consistency. Also rename sound_stopall() to sound_clear().
author Bram Moolenaar <Bram@vim.org>
date Mon, 10 Jun 2019 13:15:07 +0200
parents d23afa4d8b63
children 235cbf491430
comparison
equal deleted inserted replaced
17025:2e3d41442033 17026:905e1b154058
1 *popup.txt* For Vim version 8.1. Last change: 2019 Jun 02 1 *popup.txt* For Vim version 8.1. Last change: 2019 Jun 09
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
87 the scroll offset into account. 87 the scroll offset into account.
88 Probably 2. is the best choice. 88 Probably 2. is the best choice.
89 89
90 90
91 IMPLEMENTATION: 91 IMPLEMENTATION:
92 - Code is in popupwin.c 92 - buffers remain after popup was deleted.
93 - do not redraw whole window when popup was changed, mark affected lines for
94 redraw.
93 - Why does 'nrformats' leak from the popup window buffer??? 95 - Why does 'nrformats' leak from the popup window buffer???
94 - Make redrawing more efficient and avoid flicker. 96 - Add 'balloonpopup': instead of showing text, let the callback open a balloon
95 First draw popups, creating a mask, use the mask in screen_line() when 97 and return the window ID. The popup will then be closed when the mouse
96 drawing other windows and stuff. Mask contains zindex of popups. 98 moves, except when it moves inside the popup.
97 Keep mask until next update_screen(), use when drawing status lines. 99 - For the "moved" property also include mouse movement?
98 Remove update_popup() calls after draw_tabline()/updating statusline 100 - Make redrawing more efficient and avoid flicker:
99 Fix redrawing problem with completion. 101 - put popup menu also put in popup_mask?
100 Fix redrawing problem when scrolling non-current window 102 - Use changes in popup_mask to decide what windows and range of lines to
103 redraw?
101 - Disable commands, feedkeys(), CTRL-W, etc. in a popup window. 104 - Disable commands, feedkeys(), CTRL-W, etc. in a popup window.
102 Use NOT_IN_POPUP_WINDOW for more commands. 105 Use NOT_IN_POPUP_WINDOW for more commands.
103 - Invoke filter with character before mapping? 106 - Invoke filter with character before mapping?
104 - Figure out the size and position better. 107 - Figure out the size and position better.
105 if wrapping splits a double-wide character 108 if wrapping splits a double-wide character
113 116
114 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE 117 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
115 118
116 [functions to be moved to eval.txt later, keep overview of functions here] 119 [functions to be moved to eval.txt later, keep overview of functions here]
117 120
121 popup_atcursor({text}, {options}) *popup_atcursor()*
122 Show the {text} above the cursor, and close it when the cursor
123 moves. This works like: >
124 call popup_create({text}, {
125 \ 'pos': 'botleft',
126 \ 'line': 'cursor-1',
127 \ 'col': 'cursor',
128 \ 'moved': 'WORD',
129 \ })
130 < Use {options} to change the properties.
131
132
133 *popup_clear()*
134 popup_clear() Emergency solution to a misbehaving plugin: close all popup
135 windows.
136
137
138 popup_close({id} [, {result}]) *popup_close()*
139 Close popup {id}. The window and the associated buffer will
140 be deleted.
141
142 If the popup has a callback it will be called just before the
143 popup window is deleted. If the optional {result} is present
144 it will be passed as the second argument of the callback.
145 Otherwise zero is passed to the callback.
146
147
118 popup_create({text}, {options}) *popup_create()* 148 popup_create({text}, {options}) *popup_create()*
119 Open a popup window showing {text}, which is either: 149 Open a popup window showing {text}, which is either:
120 - a string 150 - a string
121 - a list of strings 151 - a list of strings
122 - a list of text lines with text properties 152 - a list of text lines with text properties
129 in the window: > 159 in the window: >
130 let winid = popup_create('hello', {}) 160 let winid = popup_create('hello', {})
131 let bufnr = winbufnr(winid) 161 let bufnr = winbufnr(winid)
132 call setbufline(bufnr, 2, 'second line') 162 call setbufline(bufnr, 2, 'second line')
133 < In case of failure zero is returned. 163 < In case of failure zero is returned.
134
135
136 popup_close({id} [, {result}]) *popup_close()*
137 Close popup {id}. The window and the associated buffer will
138 be deleted.
139
140 If the popup has a callback it will be called just before the
141 popup window is deleted. If the optional {result} is present
142 it will be passed as the second argument of the callback.
143 Otherwise zero is passed to the callback.
144 164
145 165
146 popup_dialog({text}, {options}) *popup_dialog()* 166 popup_dialog({text}, {options}) *popup_dialog()*
147 {not implemented yet} 167 {not implemented yet}
148 Just like |popup_create()| but with these default options: > 168 Just like |popup_create()| but with these default options: >
153 \ 'padding': [], 173 \ 'padding': [],
154 \}) 174 \})
155 < Use {options} to change the properties. 175 < Use {options} to change the properties.
156 176
157 177
158 popup_notification({text}, {options}) *popup_notification()* 178 popup_filter_menu({id}, {key}) *popup_filter_menu()*
159 {not implemented yet} 179 {not implemented yet}
160 Show the {text} for 3 seconds at the top of the Vim window. 180 Filter that can be used for a popup. It handles the cursor
161 This works like: > 181 keys to move the selected index in the popup. Space and Enter
162 call popup_create({text}, { 182 can be used to select an item. Invokes the "callback" of the
163 \ 'line': 1, 183 popup menu with the index of the selected line as the second
164 \ 'col': 10, 184 argument.
165 \ 'time': 3000, 185
166 \ 'tab': -1, 186
167 \ 'zindex': 200, 187 popup_filter_yesno({id}, {key}) *popup_filter_yesno()*
168 \ 'highlight': 'WarningMsg', 188 {not implemented yet}
169 \ 'border': [], 189 Filter that can be used for a popup. It handles only the keys
170 \ }) 190 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the
171 < Use {options} to change the properties. 191 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N'
172 192 as the second argument. Pressing Esc and CTRL-C works like
173 193 pressing 'n'.
174 popup_atcursor({text}, {options}) *popup_atcursor()* 194
175 Show the {text} above the cursor, and close it when the cursor 195
176 moves. This works like: > 196 popup_getoptions({id}) *popup_getoptions()*
177 call popup_create({text}, { 197 Return the {options} for popup {id} in a Dict.
178 \ 'pos': 'botleft', 198 A zero value means the option was not set. For "zindex" the
179 \ 'line': 'cursor-1', 199 default value is returned, not zero.
180 \ 'col': 'cursor', 200
181 \ 'moved': 'WORD', 201 The "highlight" entry is omitted, use the 'wincolor' option
182 \ }) 202 for that: >
183 < Use {options} to change the properties. 203 let hl = getwinvar(winid, '&wincolor')
204
205 < If popup window {id} is not found an empty Dict is returned.
206
207
208 popup_getpos({id}) *popup_getpos()*
209 Return the position and size of popup {id}. Returns a Dict
210 with these entries:
211 col screen column of the popup, one-based
212 line screen line of the popup, one-based
213 width width of the whole popup in screen cells
214 height height of the whole popup in screen cells
215 core_col screen column of the text box
216 core_line screen line of the text box
217 core_width width of the text box in screen cells
218 core_height height of the text box in screen cells
219 visible one if the popup is displayed, zero if hidden
220 Note that these are the actual screen positions. They differ
221 from the values in `popup_getoptions()` for the sizing and
222 positioning mechanism applied.
223
224 The "core_" values exclude the padding and border.
225
226 If popup window {id} is not found an empty Dict is returned.
227
228
229 popup_hide({id}) *popup_hide()*
230 If {id} is a displayed popup, hide it now. If the popup has a
231 filter it will not be invoked for so long as the popup is
232 hidden.
233 If window {id} does not exist nothing happens. If window {id}
234 exists but is not a popup window an error is given. *E993*
184 235
185 236
186 popup_menu({text}, {options}) *popup_menu()* 237 popup_menu({text}, {options}) *popup_menu()*
187 {not implemented yet} 238 {not implemented yet}
188 Show the {text} near the cursor, handle selecting one of the 239 Show the {text} near the cursor, handle selecting one of the
198 \ }) 249 \ })
199 < Use {options} to change the properties. Should at least set 250 < Use {options} to change the properties. Should at least set
200 "callback" to a function that handles the selected item. 251 "callback" to a function that handles the selected item.
201 252
202 253
203 popup_hide({id}) *popup_hide()*
204 If {id} is a displayed popup, hide it now. If the popup has a
205 filter it will not be invoked for so long as the popup is
206 hidden.
207 If window {id} does not exist nothing happens. If window {id}
208 exists but is not a popup window an error is given. *E993*
209
210 popup_show({id}) *popup_show()*
211 If {id} is a hidden popup, show it now.
212 For {id} see `popup_hide()`.
213
214 popup_move({id}, {options}) *popup_move()* 254 popup_move({id}, {options}) *popup_move()*
215 Move popup {id} to the position speficied with {options}. 255 Move popup {id} to the position speficied with {options}.
216 {options} may contain the items from |popup_create()| that 256 {options} may contain the items from |popup_create()| that
217 specify the popup position: "line", "col", "pos", "maxheight", 257 specify the popup position: "line", "col", "pos", "maxheight",
218 "minheight", "maxwidth" and "minwidth". 258 "minheight", "maxwidth" and "minwidth".
219 For {id} see `popup_hide()`. 259 For {id} see `popup_hide()`.
220 260
221 261
222 popup_filter_menu({id}, {key}) *popup_filter_menu()* 262 popup_notification({text}, {options}) *popup_notification()*
223 {not implemented yet} 263 {not implemented yet}
224 Filter that can be used for a popup. It handles the cursor 264 Show the {text} for 3 seconds at the top of the Vim window.
225 keys to move the selected index in the popup. Space and Enter 265 This works like: >
226 can be used to select an item. Invokes the "callback" of the 266 call popup_create({text}, {
227 popup menu with the index of the selected line as the second 267 \ 'line': 1,
228 argument. 268 \ 'col': 10,
229 269 \ 'time': 3000,
230 270 \ 'tab': -1,
231 popup_filter_yesno({id}, {key}) *popup_filter_yesno()* 271 \ 'zindex': 200,
232 {not implemented yet} 272 \ 'highlight': 'WarningMsg',
233 Filter that can be used for a popup. It handles only the keys 273 \ 'border': [],
234 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the 274 \ })
235 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N' 275 < Use {options} to change the properties.
236 as the second argument. Pressing Esc and CTRL-C works like 276
237 pressing 'n'. 277
278 popup_show({id}) *popup_show()*
279 If {id} is a hidden popup, show it now.
280 For {id} see `popup_hide()`.
238 281
239 282
240 popup_setoptions({id}, {options}) *popup_setoptions()* 283 popup_setoptions({id}, {options}) *popup_setoptions()*
241 {not implemented yet} 284 {not implemented yet}
242 Override options in popup {id} with entries in {options}. 285 Override options in popup {id} with entries in {options}.
243 286
244
245 popup_getoptions({id}) *popup_getoptions()*
246 Return the {options} for popup {id} in a Dict.
247 A zero value means the option was not set. For "zindex" the
248 default value is returned, not zero.
249
250 The "highlight" entry is omitted, use the 'wincolor' option
251 for that: >
252 let hl = getwinvar(winid, '&wincolor')
253
254 < If popup window {id} is not found an empty Dict is returned.
255
256 popup_getpos({id}) *popup_getpos()*
257 Return the position and size of popup {id}. Returns a Dict
258 with these entries:
259 col screen column of the popup, one-based
260 line screen line of the popup, one-based
261 width width of the whole popup in screen cells
262 height height of the whole popup in screen cells
263 core_col screen column of the text box
264 core_line screen line of the text box
265 core_width width of the text box in screen cells
266 core_height height of the text box in screen cells
267 visible one if the popup is displayed, zero if hidden
268 Note that these are the actual screen positions. They differ
269 from the values in `popup_getoptions()` for the sizing and
270 positioning mechanism applied.
271
272 The "core_" values exclude the padding and border.
273
274 If popup window {id} is not found an empty Dict is returned.
275
276
277 *:popupclear* *:popupc*
278 :popupc[lear] Emergency solution to a misbehaving plugin: close all popup
279 windows.
280 287
281 288
282 POPUP BUFFER AND WINDOW *popup-buffer* 289 POPUP BUFFER AND WINDOW *popup-buffer*
283 290
284 A new buffer is created to hold the text and text properties of the popup 291 A new buffer is created to hold the text and text properties of the popup
403 When the list has two characters the first is used for 410 When the list has two characters the first is used for
404 the border lines, the second for the corners. 411 the border lines, the second for the corners.
405 By default a double line is used all around when 412 By default a double line is used all around when
406 'encoding' is "utf-8", otherwise ASCII characters are 413 'encoding' is "utf-8", otherwise ASCII characters are
407 used. 414 used.
408 zindex Priority for the popup, default 50. 415 zindex Priority for the popup, default 50. Mininum value is
416 1, maximum value is 32000.
409 time Time in milliseconds after which the popup will close. 417 time Time in milliseconds after which the popup will close.
410 When omitted |popup_close()| must be used. 418 When omitted |popup_close()| must be used.
411 moved Specifies to close the popup if the cursor moved: 419 moved Specifies to close the popup if the cursor moved:
412 - "any": if the cursor moved at all 420 - "any": if the cursor moved at all
413 - "word": if the cursor moved outside |<cword>| 421 - "word": if the cursor moved outside |<cword>|
494 Vim provides standard filters |popup_filter_menu()| and 502 Vim provides standard filters |popup_filter_menu()| and
495 |popup_filter_yesno()|. 503 |popup_filter_yesno()|.
496 504
497 Note that "x" is the normal way to close a popup. You may want to use Esc, 505 Note that "x" is the normal way to close a popup. You may want to use Esc,
498 but since many keys start with an Esc character, there may be a delay before 506 but since many keys start with an Esc character, there may be a delay before
499 Vim recognizes the Esc key. If you do use Esc, it is reecommended to set the 507 Vim recognizes the Esc key. If you do use Esc, it is recommended to set the
500 'ttimeoutlen' option to 100 and set 'timeout' and/or 'ttimeout'. 508 'ttimeoutlen' option to 100 and set 'timeout' and/or 'ttimeout'.
501 509
502 510
503 POPUP CALLBACK *popup-callback* 511 POPUP CALLBACK *popup-callback*
504 512