Mercurial > vim

comparison runtime/doc/popup.txt @ 17257:cb0ca75f0c26 v8.1.1628

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.1.1628: popup window functions not in list of functions commit https://github.com/vim/vim/commit/931a277145d8fc9544765047116afe557eb606d2 Author: Bram Moolenaar <Bram@vim.org> Date: Thu Jul 4 16:54:54 2019 +0200 patch 8.1.1628: popup window functions not in list of functions Problem: Popup window functions not in list of functions. Solution: Add popup window functins to the list of functions. Reorganise the popup window help.
author Bram Moolenaar <Bram@vim.org>
date Thu, 04 Jul 2019 17:00:05 +0200
parents 09fa437d33d8
children 8a095d343c59
comparison
equal deleted inserted replaced
17256:9575e2bc52cc 17257:cb0ca75f0c26
1 *popup.txt* For Vim version 8.1. Last change: 2019 Jun 30 1 *popup.txt* For Vim version 8.1. Last change: 2019 Jul 04
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 a floating window. *popup* *popup-window*
8 8
9 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
10 9
11 1. Introduction |popup-intro| 10 1. Introduction |popup-intro|
11 Window position and size |popup-position|
12 Closing the popup window |popup-close|
13 Popup buffer and window |popup-buffer|
12 2. Functions |popup-functions| 14 2. Functions |popup-functions|
13 3. Examples |popup-examples| 15 Details |popup-function-details|
16 3. Usage |popup-usage|
17 popup_create() arguments |popup_create-arguments|
18 Popup text properties |popup-props|
19 Popup filter |popup-filter|
20 Popup callback |popup-callback|
21 Popup scrollbar |popup-scrollbar|
22 Popup mask |popup-mask|
23 4. Examples |popup-examples|
14 24
15 25
16 {not available if the |+textprop| feature was disabled at compile time} 26 {not available if the |+textprop| feature was disabled at compile time}
17 27
18 ============================================================================== 28 ==============================================================================
53 If this is not what you are looking for, check out other popup functionality: 63 If this is not what you are looking for, check out other popup functionality:
54 - popup menu, see |popup-menu| 64 - popup menu, see |popup-menu|
55 - balloon, see |balloon-eval| 65 - balloon, see |balloon-eval|
56 66
57 67
58 WINDOW POSITION AND SIZE *popup-position* 68 WINDOW POSITION AND SIZE *popup-position*
59 69
60 The height of the window is normally equal to the number of, possibly 70 The height of the window is normally equal to the number of, possibly
61 wrapping, lines in the buffer. It can be limited with the "maxheight" 71 wrapping, lines in the buffer. It can be limited with the "maxheight"
62 property. You can use empty lines to increase the height or the "minheight" 72 property. You can use empty lines to increase the height or the "minheight"
63 property. 73 property.
83 The current cursor position is displayed even when it is under a popup window. 93 The current cursor position is displayed even when it is under a popup window.
84 That way you can still see where it is, even though you cannot see the text 94 That way you can still see where it is, even though you cannot see the text
85 that it is in. 95 that it is in.
86 96
87 97
88 CLOSING THE POPUP WINDOW *popup-close* 98 CLOSING THE POPUP WINDOW *popup-close*
89 99
90 Normally the plugin that created the popup window is also in charge of closing 100 Normally the plugin that created the popup window is also in charge of closing
91 it. If somehow a popup hangs around, you can close all of them with: > 101 it. If somehow a popup hangs around, you can close all of them with: >
92 call popup_clear() 102 call popup_clear()
93 Some popups, such as notifications, close after a specified time. This can be 103 Some popups, such as notifications, close after a specified time. This can be
95 Otherwise, a popup can be closed by clicking on the X in the top-right corner 105 Otherwise, a popup can be closed by clicking on the X in the top-right corner
96 or by clicking anywhere inside the popup. This must be enabled with the 106 or by clicking anywhere inside the popup. This must be enabled with the
97 "close" property. It is set by default for notifications. 107 "close" property. It is set by default for notifications.
98 108
99 109
100 TODO: 110 POPUP BUFFER AND WINDOW *popup-buffer*
101 - Add test for when popup with mask is off the left and off the right of the 111
102 screen. 112 If a popup function is called to create a popup from text, a new buffer is
103 - check padding/border when popup is off the left and right of the screen. 113 created to hold the text and text properties of the popup window. The buffer
104 - Have a way to scroll to the bottom? (#4577) 114 is always associated with the popup window and manipulation is restricted:
105 - Why does 'nrformats' leak from the popup window buffer??? 115 - the buffer has no name
106 - Disable commands, feedkeys(), CTRL-W, etc. in a popup window. 116 - 'buftype' is "popup"
107 Use ERROR_IF_POPUP_WINDOW for more commands. 117 - 'swapfile' is off
108 - Add 'balloonpopup': instead of showing text, let the callback open a popup 118 - 'bufhidden' is "hide"
109 window and return the window ID. The popup will then be closed when the 119 - 'buflisted' is off
110 mouse moves, except when it moves inside the popup. 120 - 'undolevels' is -1: no undo at all
111 - For the "moved" property also include mouse movement? 121 - all other buffer-local and window-local options are set to their Vim default
112 - Can the buffer be re-used, to avoid using up lots of buffer numbers? 122 value.
113 - Have an option to attach the popup to a text position, like text properties 123
114 do. (#4560) 124 It is possible to change the specifically mentioned options, but anything
115 - Make redrawing more efficient and avoid flicker: 125 might break then, so better leave them alone.
116 - put popup menu also put in popup_mask? 126
117 - Invoke filter with character before mapping? 127 The window does have a cursor position, but the cursor is not displayed.
118 - Figure out the size and position better. 128
119 if wrapping splits a double-wide character 129 To execute a command in the context of the popup window and buffer use
120 if wrapping inserts indent 130 `win_execute()`. Example: >
121 - When drawing on top half a double-wide character, display ">" or "<" in the 131 call win_execute(winid, 'syntax enable')
122 incomplete cell. 132
123 - Use a popup window for the "info" item of completion instead of using a 133 Options can be set on the window with `setwinvar()`, e.g.: >
124 preview window. Ideas in issue #4544. 134 call setwinvar(winid, '&wrap', 0)
125 How to add highlighting? 135 And options can be set on the buffer with `setbufvar()`, e.g.: >
126 - Implement: 136 call setbufvar(winbufnr(winid), '&filetype', 'java')
127 flip option 137 Note that this does not trigger autocommands. Use `win_execute()` if you do
138 need them.
139
140
128 141
129 ============================================================================== 142 ==============================================================================
130 2. Functions *popup-functions* 143 2. Functions *popup-functions*
131
132 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
133 144
134 Creating a popup window: 145 Creating a popup window:
135 |popup_create()| centered in the screen 146 |popup_create()| centered in the screen
136 |popup_atcursor()| just above the cursor position, closes when 147 |popup_atcursor()| just above the cursor position, closes when
137 the cursor moves away 148 the cursor moves away
157 Other: 168 Other:
158 |popup_getoptions()| get current options for a popup 169 |popup_getoptions()| get current options for a popup
159 |popup_getpos()| get actual position and size of a popup 170 |popup_getpos()| get actual position and size of a popup
160 171
161 172
162 [functions help to be moved to eval.txt later] 173 DETAILS *popup-function-details*
163 174
164 popup_atcursor({what}, {options}) *popup_atcursor()* 175 popup_atcursor({what}, {options}) *popup_atcursor()*
165 Show the {what} above the cursor, and close it when the cursor 176 Show the {what} above the cursor, and close it when the cursor
166 moves. This works like: > 177 moves. This works like: >
167 call popup_create({what}, { 178 call popup_create({what}, {
168 \ 'pos': 'botleft', 179 \ 'pos': 'botleft',
169 \ 'line': 'cursor-1', 180 \ 'line': 'cursor-1',
197 When {what} is not a buffer number, a buffer is created with 208 When {what} is not a buffer number, a buffer is created with
198 'buftype' set to "popup". That buffer will be wiped out once 209 'buftype' set to "popup". That buffer will be wiped out once
199 the popup closes. 210 the popup closes.
200 211
201 {options} is a dictionary with many possible entries. 212 {options} is a dictionary with many possible entries.
202 See |popup_create-usage| for details. 213 See |popup_create-arguments| for details.
203 214
204 Returns a window-ID, which can be used with other popup 215 Returns a window-ID, which can be used with other popup
205 functions. Use `winbufnr()` to get the number of the buffer 216 functions. Use `winbufnr()` to get the number of the buffer
206 in the window: > 217 in the window: >
207 let winid = popup_create('hello', {}) 218 let winid = popup_create('hello', {})
415 number is not allowed. 426 number is not allowed.
416 Does not change the window size or position, other than caused 427 Does not change the window size or position, other than caused
417 by the different text. 428 by the different text.
418 429
419 430
420 POPUP BUFFER AND WINDOW *popup-buffer* 431 ==============================================================================
421 432 3. Usage *popup-usage*
422 A new buffer is created to hold the text and text properties of the popup 433
423 window. The buffer is always associated with the popup window and 434 POPUP_CREATE() ARGUMENTS *popup_create-arguments*
424 manipulation is restricted:
425 - the buffer has no name
426 - 'buftype' is "popup"
427 - 'swapfile' is off
428 - 'bufhidden' is "hide"
429 - 'buflisted' is off
430 - 'undolevels' is -1: no undo at all
431 - all other buffer-local and window-local options are set to their Vim default
432 value.
433
434 It is possible to change the specifically mentioned options, but anything
435 might break then, so better leave them alone.
436
437 The window does have a cursor position, but the cursor is not displayed.
438
439 To execute a command in the context of the popup window and buffer use
440 `win_execute()`. Example: >
441 call win_execute(winid, 'syntax enable')
442
443 Options can be set on the window with `setwinvar()`, e.g.: >
444 call setwinvar(winid, '&wrap', 0)
445 And options can be set on the buffer with `setbufvar()`, e.g.: >
446 call setbufvar(winbufnr(winid), '&filetype', 'java')
447 Note that this does not trigger autocommands. Use `win_execute()` if you do
448 need them.
449
450
451 POPUP_CREATE() ARGUMENTS *popup_create-usage*
452 435
453 The first argument of |popup_create()| (and the second argument to 436 The first argument of |popup_create()| (and the second argument to
454 |popup_settext()|) specifies the text to be displayed, and optionally text 437 |popup_settext()|) specifies the text to be displayed, and optionally text
455 properties. It is in one of four forms: 438 properties. It is in one of four forms:
456 - a buffer number 439 - a buffer number
707 690
708 To make the four corners transparent: 691 To make the four corners transparent:
709 [[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]] 692 [[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]
710 693
711 ============================================================================== 694 ==============================================================================
712 3. Examples *popup-examples* 695 4. Examples *popup-examples*
713 696
714 TODO 697 TODO: more interesting examples
715 *popup_dialog-example* 698 *popup_dialog-example*
716 Prompt the user to press y/Y or n/N: > 699 Prompt the user to press y/Y or n/N: >
717 700
718 func MyDialogHandler(id, result) 701 func MyDialogHandler(id, result)
719 if a:result 702 if a:result