Mercurial > vim

comparison runtime/doc/popup.txt @ 17036:235cbf491430

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update runtime files commit https://github.com/vim/vim/commit/12ee7ff00b91d852e060bb24951d1c94239863eb Author: Bram Moolenaar <Bram@vim.org> Date: Mon Jun 10 22:47:40 2019 +0200 Update runtime files
author Bram Moolenaar <Bram@vim.org>
date Mon, 10 Jun 2019 23:00:08 +0200
parents 905e1b154058
children 7fe328ad5573
comparison
equal deleted inserted replaced
17035:a4b23aa54dca 17036:235cbf491430
1 *popup.txt* For Vim version 8.1. Last change: 2019 Jun 09 1 *popup.txt* For Vim version 8.1. Last change: 2019 Jun 10
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
7 Displaying text in floating window. *popup* *popup-window* 7 Displaying text in floating window. *popup* *popup-window*
8 8
9 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE 9 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
10 10
11 1. Introduction |popup-intro| 11 1. Introduction |popup-intro|
12 2. Functions |popup-functions| 12 2. Functions |popup-functions|
13 3. Examples |popup-examples| 13 3. Examples |popup-examples|
14 14
74 when the popup would go outside of the Vim window, it will show it somewhere 74 when the popup would go outside of the Vim window, it will show it somewhere
75 else. E.g. if you use `popup_atcursor()` the popup normally shows just above 75 else. E.g. if you use `popup_atcursor()` the popup normally shows just above
76 the current cursor position, but if the cursor is close to the top of the Vim 76 the current cursor position, but if the cursor is close to the top of the Vim
77 window it will be placed below the cursor position. 77 window it will be placed below the cursor position.
78 78
79 79 When the screen scrolls up for output of an Ex command, popups move too, so
80 80 that they will not cover the output.
81 TODO: 81
82 82
83 Scrolling: When the screen scrolls up for output of an Ex command, what
84 happens with popups?
85 1. Stay where they are. Problem: listed text may go behind and can't be read.
86 2. Scroll with the page. What if they get updated? Either postpone, or take
87 the scroll offset into account.
88 Probably 2. is the best choice.
89 83
90 84
91 IMPLEMENTATION: 85 IMPLEMENTATION:
92 - buffers remain after popup was deleted. 86 - buffers remain after a popup was deleted.
93 - do not redraw whole window when popup was changed, mark affected lines for
94 redraw.
95 - Why does 'nrformats' leak from the popup window buffer??? 87 - Why does 'nrformats' leak from the popup window buffer???
96 - Add 'balloonpopup': instead of showing text, let the callback open a balloon 88 - Add 'balloonpopup': instead of showing text, let the callback open a popup
97 and return the window ID. The popup will then be closed when the mouse 89 window and return the window ID. The popup will then be closed when the
98 moves, except when it moves inside the popup. 90 mouse moves, except when it moves inside the popup.
99 - For the "moved" property also include mouse movement? 91 - For the "moved" property also include mouse movement?
100 - Make redrawing more efficient and avoid flicker: 92 - Make redrawing more efficient and avoid flicker:
101 - put popup menu also put in popup_mask? 93 - put popup menu also put in popup_mask?
102 - Use changes in popup_mask to decide what windows and range of lines to
103 redraw?
104 - Disable commands, feedkeys(), CTRL-W, etc. in a popup window. 94 - Disable commands, feedkeys(), CTRL-W, etc. in a popup window.
105 Use NOT_IN_POPUP_WINDOW for more commands. 95 Use NOT_IN_POPUP_WINDOW for more commands.
106 - Invoke filter with character before mapping? 96 - Invoke filter with character before mapping?
107 - Figure out the size and position better. 97 - Figure out the size and position better.
108 if wrapping splits a double-wide character 98 if wrapping splits a double-wide character
112 102
113 103
114 ============================================================================== 104 ==============================================================================
115 2. Functions *popup-functions* 105 2. Functions *popup-functions*
116 106
117 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE 107 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
118 108
119 [functions to be moved to eval.txt later, keep overview of functions here] 109 [functions to be moved to eval.txt later, keep overview of functions here]
120 110
121 popup_atcursor({text}, {options}) *popup_atcursor()* 111 popup_atcursor({text}, {options}) *popup_atcursor()*
122 Show the {text} above the cursor, and close it when the cursor 112 Show the {text} above the cursor, and close it when the cursor
162 call setbufline(bufnr, 2, 'second line') 152 call setbufline(bufnr, 2, 'second line')
163 < In case of failure zero is returned. 153 < In case of failure zero is returned.
164 154
165 155
166 popup_dialog({text}, {options}) *popup_dialog()* 156 popup_dialog({text}, {options}) *popup_dialog()*
167 {not implemented yet} 157 {not implemented yet}
168 Just like |popup_create()| but with these default options: > 158 Just like |popup_create()| but with these default options: >
169 call popup_create({text}, { 159 call popup_create({text}, {
170 \ 'pos': 'center', 160 \ 'pos': 'center',
171 \ 'zindex': 200, 161 \ 'zindex': 200,
172 \ 'border': [], 162 \ 'border': [],
174 \}) 164 \})
175 < Use {options} to change the properties. 165 < Use {options} to change the properties.
176 166
177 167
178 popup_filter_menu({id}, {key}) *popup_filter_menu()* 168 popup_filter_menu({id}, {key}) *popup_filter_menu()*
179 {not implemented yet} 169 {not implemented yet}
180 Filter that can be used for a popup. It handles the cursor 170 Filter that can be used for a popup. It handles the cursor
181 keys to move the selected index in the popup. Space and Enter 171 keys to move the selected index in the popup. Space and Enter
182 can be used to select an item. Invokes the "callback" of the 172 can be used to select an item. Invokes the "callback" of the
183 popup menu with the index of the selected line as the second 173 popup menu with the index of the selected line as the second
184 argument. 174 argument.
185 175
186 176
187 popup_filter_yesno({id}, {key}) *popup_filter_yesno()* 177 popup_filter_yesno({id}, {key}) *popup_filter_yesno()*
188 {not implemented yet} 178 {not implemented yet}
189 Filter that can be used for a popup. It handles only the keys 179 Filter that can be used for a popup. It handles only the keys
190 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the 180 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the
191 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N' 181 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N'
192 as the second argument. Pressing Esc and CTRL-C works like 182 as the second argument. Pressing Esc and CTRL-C works like
193 pressing 'n'. 183 pressing 'n'.
214 height height of the whole popup in screen cells 204 height height of the whole popup in screen cells
215 core_col screen column of the text box 205 core_col screen column of the text box
216 core_line screen line of the text box 206 core_line screen line of the text box
217 core_width width of the text box in screen cells 207 core_width width of the text box in screen cells
218 core_height height of the text box in screen cells 208 core_height height of the text box in screen cells
219 visible one if the popup is displayed, zero if hidden 209 visible one if the popup is displayed, zero if hidden
220 Note that these are the actual screen positions. They differ 210 Note that these are the actual screen positions. They differ
221 from the values in `popup_getoptions()` for the sizing and 211 from the values in `popup_getoptions()` for the sizing and
222 positioning mechanism applied. 212 positioning mechanism applied.
223 213
224 The "core_" values exclude the padding and border. 214 The "core_" values exclude the padding and border.
233 If window {id} does not exist nothing happens. If window {id} 223 If window {id} does not exist nothing happens. If window {id}
234 exists but is not a popup window an error is given. *E993* 224 exists but is not a popup window an error is given. *E993*
235 225
236 226
237 popup_menu({text}, {options}) *popup_menu()* 227 popup_menu({text}, {options}) *popup_menu()*
238 {not implemented yet} 228 {not implemented yet}
239 Show the {text} near the cursor, handle selecting one of the 229 Show the {text} near the cursor, handle selecting one of the
240 items with cursorkeys, and close it an item is selected with 230 items with cursorkeys, and close it an item is selected with
241 Space or Enter. {text} should have multiple lines to make this 231 Space or Enter. {text} should have multiple lines to make this
242 useful. This works like: > 232 useful. This works like: >
243 call popup_create({text}, { 233 call popup_create({text}, {
258 "minheight", "maxwidth" and "minwidth". 248 "minheight", "maxwidth" and "minwidth".
259 For {id} see `popup_hide()`. 249 For {id} see `popup_hide()`.
260 250
261 251
262 popup_notification({text}, {options}) *popup_notification()* 252 popup_notification({text}, {options}) *popup_notification()*
263 {not implemented yet} 253 {not implemented yet}
264 Show the {text} for 3 seconds at the top of the Vim window. 254 Show the {text} for 3 seconds at the top of the Vim window.
265 This works like: > 255 This works like: >
266 call popup_create({text}, { 256 call popup_create({text}, {
267 \ 'line': 1, 257 \ 'line': 1,
268 \ 'col': 10, 258 \ 'col': 10,
279 If {id} is a hidden popup, show it now. 269 If {id} is a hidden popup, show it now.
280 For {id} see `popup_hide()`. 270 For {id} see `popup_hide()`.
281 271
282 272
283 popup_setoptions({id}, {options}) *popup_setoptions()* 273 popup_setoptions({id}, {options}) *popup_setoptions()*
284 {not implemented yet} 274 {not implemented yet}
285 Override options in popup {id} with entries in {options}. 275 Override options in popup {id} with entries in {options}.
286 276
287 277
288 278
289 POPUP BUFFER AND WINDOW *popup-buffer* 279 POPUP BUFFER AND WINDOW *popup-buffer*
290 280
291 A new buffer is created to hold the text and text properties of the popup 281 A new buffer is created to hold the text and text properties of the popup
292 window. The buffer is always associated with the popup window and 282 window. The buffer is always associated with the popup window and
293 manipulation is restricted: 283 manipulation is restricted:
294 - the buffer has no name 284 - the buffer has no name
295 - 'buftype' is "popup" 285 - 'buftype' is "popup"
296 - 'swapfile' is off 286 - 'swapfile' is off
297 - 'bufhidden' is "hide" 287 - 'bufhidden' is "hide"
298 - 'buflisted' is off 288 - 'buflisted' is off
299 - 'undolevels' is -1: no undo at all 289 - 'undolevels' is -1: no undo at all
300 - all other buffer-local and window_local options are set to their Vim default 290 - all other buffer-local and window_local options are set to their Vim default
422 - "WORD": if the cursor moved outside |<cWORD>| 412 - "WORD": if the cursor moved outside |<cWORD>|
423 - [{start}, {end}]: if the cursor moved before column 413 - [{start}, {end}]: if the cursor moved before column
424 {start} or after {end} 414 {start} or after {end}
425 The popup also closes if the cursor moves to another 415 The popup also closes if the cursor moves to another
426 line or to another window. 416 line or to another window.
427 filter A callback that can filter typed characters, see 417 filter A callback that can filter typed characters, see
428 |popup-filter|. 418 |popup-filter|.
429 callback A callback that is called when the popup closes, e.g. 419 callback A callback that is called when the popup closes, e.g.
430 when using |popup_filter_menu()|, see |popup-callback|. 420 when using |popup_filter_menu()|, see |popup-callback|.
431 421
432 Depending on the "zindex" the popup goes under or above other popups. The 422 Depending on the "zindex" the popup goes under or above other popups. The
484 if a:key == 'x' 474 if a:key == 'x'
485 call popup_close(a:winid) 475 call popup_close(a:winid)
486 return 1 476 return 1
487 endif 477 endif
488 return 0 478 return 0
489 endfunc 479 endfunc
490 480
491 Currently the key is what results after any mapping. This may change... 481 Currently the key is what results after any mapping. This may change...
492 482
493 Some common key actions: 483 Some common key actions:
494 x close the popup (see note below) 484 x close the popup (see note below)