Mercurial > vim

comparison runtime/doc/popup.txt @ 17149:c90fdb999393 v8.1.1574

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.1.1574: tabpage option not yet implemented for popup window commit https://github.com/vim/vim/commit/a3fce62c911c204ae144b55018f6dc9295088850 Author: Bram Moolenaar <Bram@vim.org> Date: Thu Jun 20 02:31:49 2019 +0200 patch 8.1.1574: tabpage option not yet implemented for popup window Problem: Tabpage option not yet implemented for popup window. Solution: Implement tabpage option, also for popup_getoptions().
author Bram Moolenaar <Bram@vim.org>
date Thu, 20 Jun 2019 02:45:05 +0200
parents efc6f5e3b543
children 9ccb1ea9b2fc
comparison
equal deleted inserted replaced
17148:34404b7bbde7 17149:c90fdb999393
86 86
87 87
88 88
89 TODO: 89 TODO:
90 - Why does 'nrformats' leak from the popup window buffer??? 90 - Why does 'nrformats' leak from the popup window buffer???
91 - When the lines do not fit show a scrollbar (like in the popup menu).
92 Use the mouse wheel for scrolling.
91 - Disable commands, feedkeys(), CTRL-W, etc. in a popup window. 93 - Disable commands, feedkeys(), CTRL-W, etc. in a popup window.
92 Use ERROR_IF_POPUP_WINDOW for more commands. 94 Use ERROR_IF_POPUP_WINDOW for more commands.
93 - Add 'balloonpopup': instead of showing text, let the callback open a popup 95 - 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 96 window and return the window ID. The popup will then be closed when the
95 mouse moves, except when it moves inside the popup. 97 mouse moves, except when it moves inside the popup.
96 - For the "moved" property also include mouse movement? 98 - For the "moved" property also include mouse movement?
99 - Can the buffer be re-used, to avoid using up lots of buffer numbers?
100 - Have an option to attach the popup to a text position, like text properties
101 do. (#4560)
97 - Make redrawing more efficient and avoid flicker: 102 - Make redrawing more efficient and avoid flicker:
98 - put popup menu also put in popup_mask? 103 - put popup menu also put in popup_mask?
99 - Invoke filter with character before mapping? 104 - Invoke filter with character before mapping?
100 - Figure out the size and position better. 105 - Figure out the size and position better.
101 if wrapping splits a double-wide character 106 if wrapping splits a double-wide character
102 if wrapping inserts indent 107 if wrapping inserts indent
103 - When drawing on top half a double-wide character, display ">" or "<" in the 108 - When drawing on top half a double-wide character, display ">" or "<" in the
104 incomplete cell. 109 incomplete cell.
105 - Can the buffer be re-used, to avoid using up lots of buffer numbers?
106 - Use a popup window for the "info" item of completion instead of using a 110 - Use a popup window for the "info" item of completion instead of using a
107 preview window. Ideas in issue #4544. 111 preview window. Ideas in issue #4544.
108 How to add highlighting? 112 How to add highlighting?
109 - When the lines do not fit show a scrollbar (like in the popup menu).
110 Use the mouse wheel for scrolling.
111 - Implement: 113 - Implement:
112 tabpage option with number
113 flip option 114 flip option
114 transparent text property 115 transparent area, to minimize covering text. Define rectangles?
115
116 116
117 ============================================================================== 117 ==============================================================================
118 2. Functions *popup-functions* 118 2. Functions *popup-functions*
119 119
120 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE 120 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
121 121
122 Creating a popup window: 122 Creating a popup window:
123 |popup_create()| centered in the screen 123 |popup_create()| centered in the screen
124 |popup_atcursor()| just above the cursor position, closes when 124 |popup_atcursor()| just above the cursor position, closes when
125 the cursor moves away 125 the cursor moves away
126 |popup_notifiation()| show a notification for three seconds 126 |popup_notification()| show a notification for three seconds
127 |popup_dialog()| centered with padding and border 127 |popup_dialog()| centered with padding and border
128 |popup_menu()| prompt for selecting an item from a list 128 |popup_menu()| prompt for selecting an item from a list
129 129
130 Manipulating a popup window: 130 Manipulating a popup window:
131 |popup_hide()| hide a popup temporarily 131 |popup_hide()| hide a popup temporarily
161 < Use {options} to change the properties. 161 < Use {options} to change the properties.
162 162
163 163
164 *popup_clear()* 164 *popup_clear()*
165 popup_clear() Emergency solution to a misbehaving plugin: close all popup 165 popup_clear() Emergency solution to a misbehaving plugin: close all popup
166 windows. 166 windows for the current tab and global popups.
167 167
168 168
169 popup_close({id} [, {result}]) *popup_close()* 169 popup_close({id} [, {result}]) *popup_close()*
170 Close popup {id}. The window and the associated buffer will 170 Close popup {id}. The window and the associated buffer will
171 be deleted. 171 be deleted.
214 can be read if needed. 214 can be read if needed.
215 215
216 216
217 popup_filter_menu({id}, {key}) *popup_filter_menu()* 217 popup_filter_menu({id}, {key}) *popup_filter_menu()*
218 Filter that can be used for a popup. These keys can be used: 218 Filter that can be used for a popup. These keys can be used:
219 j <Down> select item below 219 j <Down> select item below
220 k <Up> select item above 220 k <Up> select item above
221 <Space> <Enter> accept current selection 221 <Space> <Enter> accept current selection
222 x Esc CTRL-C cancel the menu 222 x Esc CTRL-C cancel the menu
223 Other keys are ignored. 223 Other keys are ignored.
224 224
227 227
228 When the current selection is accepted the "callback" of the 228 When the current selection is accepted the "callback" of the
229 popup menu is invoked with the index of the selected line as 229 popup menu is invoked with the index of the selected line as
230 the second argument. The first entry has index one. 230 the second argument. The first entry has index one.
231 Cancelling the menu invokes the callback with -1. 231 Cancelling the menu invokes the callback with -1.
232
233 To add shortcut keys, see the example here:
234 |popup_menu-shortcut-example|
232 235
233 236
234 popup_filter_yesno({id}, {key}) *popup_filter_yesno()* 237 popup_filter_yesno({id}, {key}) *popup_filter_yesno()*
235 Filter that can be used for a popup. It handles only the keys 238 Filter that can be used for a popup. It handles only the keys
236 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the 239 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the
237 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N' 240 popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N'
238 as the second argument. Pressing Esc and 'x' works like 241 as the second argument. Pressing Esc and 'x' works like
239 pressing 'n'. CTRL-C invokes the callback with -1. Other 242 pressing 'n'. CTRL-C invokes the callback with -1. Other
240 keys are ignored. 243 keys are ignored.
244 See the example here: |popup_dialog-example|
241 245
242 246
243 popup_getoptions({id}) *popup_getoptions()* 247 popup_getoptions({id}) *popup_getoptions()*
244 Return the {options} for popup {id} in a Dict. 248 Return the {options} for popup {id} in a Dict.
245 A zero value means the option was not set. For "zindex" the 249 A zero value means the option was not set. For "zindex" the
250 254
251 "border" and "padding" are not included when all values are 255 "border" and "padding" are not included when all values are
252 zero. When all values are one then an empty list is included. 256 zero. When all values are one then an empty list is included.
253 257
254 "borderhighlight" is not included when all values are empty. 258 "borderhighlight" is not included when all values are empty.
259
260 "tabpage" will be -1 for a global popup, zero for a popup on
261 the current tabpage and a positive number for a popup on
262 another tabpage.
255 263
256 If popup window {id} is not found an empty Dict is returned. 264 If popup window {id} is not found an empty Dict is returned.
257 265
258 266
259 popup_getpos({id}) *popup_getpos()* 267 popup_getpos({id}) *popup_getpos()*
388 - 'buftype' is "popup" 396 - 'buftype' is "popup"
389 - 'swapfile' is off 397 - 'swapfile' is off
390 - 'bufhidden' is "hide" 398 - 'bufhidden' is "hide"
391 - 'buflisted' is off 399 - 'buflisted' is off
392 - 'undolevels' is -1: no undo at all 400 - 'undolevels' is -1: no undo at all
393 - all other buffer-local and window_local options are set to their Vim default 401 - all other buffer-local and window-local options are set to their Vim default
394 value. 402 value.
395 403
396 It is possible to change the specifically mentioned options, but anything 404 It is possible to change the specifically mentioned options, but anything
397 might break then, so better leave them alone. 405 might break then, so better leave them alone.
398 406
472 {not implemented yet} 480 {not implemented yet}
473 tabpage When -1: display the popup on all tabs. 481 tabpage When -1: display the popup on all tabs.
474 When 0 (the default): display the popup on the current 482 When 0 (the default): display the popup on the current
475 tab page. 483 tab page.
476 Otherwise the number of the tab page the popup is 484 Otherwise the number of the tab page the popup is
477 displayed on; when invalid the current tab page is used. 485 displayed on; when invalid the popup is not created
478 {only -1 and 0 are implemented} 486 and an error is given. *E996*
479 title Text to be displayed above the first item in the 487 title Text to be displayed above the first item in the
480 popup, on top of any border. If there is no top 488 popup, on top of any border. If there is no top
481 border one line of padding is added to put the title 489 border one line of padding is added to put the title
482 on. You might want to add one or more spaces at the 490 on. You might want to add one or more spaces at the
483 start and end as padding. 491 start and end as padding.
513 Example: ['-', '|', '-', '|', '┌', '┐', '┘', '└'] 521 Example: ['-', '|', '-', '|', '┌', '┐', '┘', '└']
514 When the list has one character it is used for all. 522 When the list has one character it is used for all.
515 When the list has two characters the first is used for 523 When the list has two characters the first is used for
516 the border lines, the second for the corners. 524 the border lines, the second for the corners.
517 By default a double line is used all around when 525 By default a double line is used all around when
518 'encoding' is "utf-8", otherwise ASCII characters are 526 'encoding' is "utf-8" and 'ambiwidth' is "single,
519 used. 527 otherwise ASCII characters are used.
520 zindex Priority for the popup, default 50. Minimum value is 528 zindex Priority for the popup, default 50. Minimum value is
521 1, maximum value is 32000. 529 1, maximum value is 32000.
522 time Time in milliseconds after which the popup will close. 530 time Time in milliseconds after which the popup will close.
523 When omitted |popup_close()| must be used. 531 When omitted |popup_close()| must be used.
524 moved Specifies to close the popup if the cursor moved: 532 moved Specifies to close the popup if the cursor moved:
626 634
627 ============================================================================== 635 ==============================================================================
628 3. Examples *popup-examples* 636 3. Examples *popup-examples*
629 637
630 TODO 638 TODO
631 639 *popup_dialog-example*
632 Prompt the user to press y/Y or n/N: > 640 Prompt the user to press y/Y or n/N: >
633 641
634 func MyDialogHandler(id, result) 642 func MyDialogHandler(id, result)
635 if a:result 643 if a:result
636 " ... 'y' or 'Y' was pressed 644 " ... 'y' or 'Y' was pressed
637 endif 645 endif
638 endfunc 646 endfunc
639 647
640 call popup_create(['Continue? y/n'], { 648 call popup_dialog('Continue? y/n', {
641 \ 'filter': 'popup_filter_yesno', 649 \ 'filter': 'popup_filter_yesno',
642 \ 'callback': 'MyDialogHandler', 650 \ 'callback': 'MyDialogHandler',
643 \ }) 651 \ })
644 < 652 <
653 *popup_menu-shortcut-example*
654 Extend popup_filter_menu() with shortcut keys: >
655
656 call popup_menu('Save', 'Cancel', 'Discard'], {
657 \ 'filter': 'MyMenuFilter',
658 \ 'callback': 'MyMenuHandler',
659 \ })
660
661 func MyMenuFilter(id, key)
662 " Handle shortcuts
663 if a:key == 'S'
664 call popup_close(a:id, 1)
665 return 1
666 endif
667 if a:key == 'C'
668 call popup_close(a:id, 2)
669 return 1
670 endif
671 if a:key == 'D'
672 call popup_close(a:id, 3)
673 return 1
674 endif
675
676 " No shortcut, pass to generic filter
677 return popup_filter_menu(a:id, a:key)
678 endfunc
679 <
645 680
646 vim:tw=78:ts=8:noet:ft=help:norl: 681 vim:tw=78:ts=8:noet:ft=help:norl: