Mercurial > vim

comparison runtime/doc/popup.txt @ 16724:6030631a1541 v8.1.1364

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.1.1364: design for popup window support needs more details commit https://github.com/vim/vim/commit/5c017b2de28d19dfa4af58b8973e32f31bb1477e Author: Bram Moolenaar <Bram@vim.org> Date: Tue May 21 23:09:01 2019 +0200 patch 8.1.1364: design for popup window support needs more details Problem: Design for popup window support needs more details. Solution: Add details about using a window and buffer. Rename popup_show() to popup_create() and add popup_show() and popup_hide().
author Bram Moolenaar <Bram@vim.org>
date Tue, 21 May 2019 23:15:05 +0200
parents 7d54a66c95d7
children eda4d65f232c
comparison
equal deleted inserted replaced
16723:14c2eca9dd59 16724:6030631a1541
1 *popup.txt* For Vim version 8.1. Last change: 2019 May 12 1 *popup.txt* For Vim version 8.1. Last change: 2019 May 21
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 with properties attached. *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
15 15
16 {not able to use text properties when the |+textprop| feature was 16 {not available if the |+eval| feature was disabled at compile time}
17 disabled at compile time} 17 {not able to use text properties if the |+textprop| feature was disabled at
18 compile time}
18 19
19 ============================================================================== 20 ==============================================================================
20 1. Introduction *popup-intro* 21 1. Introduction *popup-intro*
21 22
22 We are talking about popup windows here, text that goes on top of the buffer 23 We are talking about popup windows here, text that goes on top of the regular
23 text and is under control of a plugin. Other popup functionality: 24 windows and is under control of a plugin. You cannot edit the text in the
25 popup window like with regular windows.
26
27 A popup window can be used for such things as:
28 - briefly show a message without changing the command line
29 - prompt the user with a dialog
30 - display information while typing
31 - give extra information for auto-completion
32
33 The text in the popup window can be colored with |text-properties|. It is
34 also possible to use syntax highlighting.
35
36 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.
38 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
40 not get keyboard focus. You can use functions like `setbufline()` to change
41 the text in the buffer. There are more differences from how this window and
42 buffer behave compared to regular windows and buffers, see |popup-buffer|.
43
44 If this is not what you are looking for, check out other popup functionality:
24 - popup menu, see |popup-menu| 45 - popup menu, see |popup-menu|
25 - balloon, see |balloon-eval| 46 - balloon, see |balloon-eval|
26 47
27 TODO 48
49 TODO:
50
51 Example how to use syntax highlighting of a code snippet.
52
53 Scrolling: When the screen scrolls up for output of an Ex command, what
54 happens with popups?
55 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
57 the scroll offset into account.
58 Probably 2. is the best choice.
59
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
64 IMPLEMENTATION:
65 - Put code in popupwin.c
66 - Use win_update() for displaying
67 - At first redraw all windows NOT_VALID when the popup moves or hides.
68 - At first always display the popup windows at the end of update_screen(),
69 lowest zindex first.
70 - Later make it more efficient and avoid flicker
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
28 77
29 ============================================================================== 78 ==============================================================================
30 2. Functions *popup-functions* 79 2. Functions *popup-functions*
31 80
32 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE 81 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
33 82
34 Proposal and discussion on issue #4063: https://github.com/vim/vim/issues/4063 83 Proposal and discussion on issue #4063: https://github.com/vim/vim/issues/4063
35 84
36 [to be moved to eval.txt later] 85 [functions to be moved to eval.txt later, keep list of functions here]
37 86
38 popup_show({lines}, {options}) *popup_show()* 87 popup_create({text}, {options}) *popup_create()*
39 Open a popup window showing {lines}, which is a list of lines, 88 Open a popup window showing {text}, which is either:
40 where each line has text and text properties. 89 - a string
41 90 - a list of strings
91 - a list of text lines with text properties
42 {options} is a dictionary with many possible entries. 92 {options} is a dictionary with many possible entries.
43 93 See |popup_create-usage| for details.
44 Returns a unique ID to be used with |popup_close()|. 94
45 95 Returns a window-ID, which can be used with other popup
46 See |popup_show-usage| for details. 96 functions. Use `winbufnr()` to get the number of the buffer
47 97 in the window: >
48 98 let winid = popup_create('hello', {})
49 popup_dialog({lines}, {options}) *popup_dialog()* 99 let bufnr = winbufnr(winid)
50 Just like |popup_show()| but with different default options: 100 call setbufline(bufnr, 2, 'second line')
51 pos "center" 101
52 zindex 200 102
53 border [] 103 popup_dialog({text}, {options}) *popup_dialog()*
104 Just like |popup_create()| but with these default options: >
105 call popup_create({text}, {
106 \ 'pos': 'center',
107 \ 'zindex': 200,
108 \ 'border': [],
109 \})
110 < Use {options} to change the properties.
54 111
55 112
56 popup_notification({text}, {options}) *popup_notification()* 113 popup_notification({text}, {options}) *popup_notification()*
57 Show the string {text} for 3 seconds at the top of the Vim 114 Show the {text} for 3 seconds at the top of the Vim window.
58 window. This works like: > 115 This works like: >
59 call popup_show([{'text': {text}}], { 116 call popup_create({text}, {
60 \ 'line': 1, 117 \ 'line': 1,
61 \ 'col': 10, 118 \ 'col': 10,
62 \ 'time': 3000, 119 \ 'time': 3000,
120 \ 'tab': -1,
63 \ 'zindex': 200, 121 \ 'zindex': 200,
64 \ 'highlight': 'WarningMsg', 122 \ 'highlight': 'WarningMsg',
65 \ 'border: [], 123 \ 'border: [],
66 \ }) 124 \ })
67 < Use {options} to change the properties. 125 < Use {options} to change the properties.
68 126
127
69 popup_atcursor({text}, {options}) *popup_atcursor()* 128 popup_atcursor({text}, {options}) *popup_atcursor()*
70 Show the string {text} above the cursor, and close it when the 129 Show the {text} above the cursor, and close it when the cursor
71 cursor moves. This works like: > 130 moves. This works like: >
72 call popup_show([{'text': {text}}], { 131 call popup_create({text}, {
73 \ 'line': 'cursor-1', 132 \ 'line': 'cursor-1',
74 \ 'col': 'cursor', 133 \ 'col': 'cursor',
75 \ 'zindex': 50,
76 \ 'moved': 'WORD', 134 \ 'moved': 'WORD',
77 \ }) 135 \ })
78 < Use {options} to change the properties. 136 < Use {options} to change the properties.
79 137
80 138
81 popup_menu({lines}, {options}) *popup_atcursor()* 139 popup_menu({text}, {options}) *popup_menu()*
82 Show the {lines} near the cursor, handle selecting one of the 140 Show the {text} near the cursor, handle selecting one of the
83 items with cursorkeys, and close it an item is selected with 141 items with cursorkeys, and close it an item is selected with
84 Space or Enter. This works like: > 142 Space or Enter. {text} should have multiple lines to make this
85 call popup_show({lines}, { 143 useful. This works like: >
144 call popup_create({text}, {
86 \ 'pos': 'center', 145 \ 'pos': 'center',
87 \ 'zindex': 200, 146 \ 'zindex': 200,
88 \ 'wrap': 0, 147 \ 'wrap': 0,
89 \ 'border': [], 148 \ 'border': [],
90 \ 'filter': 'popup_filter_menu', 149 \ 'filter': 'popup_filter_menu',
91 \ }) 150 \ })
92 < Use {options} to change the properties. Should at least set 151 < Use {options} to change the properties. Should at least set
93 "callback" to a function that handles the selected item. 152 "callback" to a function that handles the selected item.
94 153
95 154
155 popup_show({id}) *popup_show()*
156 If {id} is a hidden popup, show it now.
157
158 popup_hide({id}) *popup_hide()*
159 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
161 hidden.
162
96 popup_move({id}, {options}) *popup_move()* 163 popup_move({id}, {options}) *popup_move()*
97 Move popup {id} to the position speficied with {options}. 164 Move popup {id} to the position speficied with {options}.
98 {options} may contain the items from |popup_show()| that 165 {options} may contain the items from |popup_create()| that
99 specify the popup position: "line", "col", "pos", "maxheight", 166 specify the popup position: "line", "col", "pos", "maxheight",
100 "minheight", "maxwidth" and "minwidth". 167 "minheight", "maxwidth" and "minwidth".
101 168
102 169
103 popup_filter_menu({id}, {key}) *popup_filter_menu()* 170 popup_filter_menu({id}, {key}) *popup_filter_menu()*
114 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'
115 as the second argument. Pressing Esc and CTRL-C works like 182 as the second argument. Pressing Esc and CTRL-C works like
116 pressing 'n'. 183 pressing 'n'.
117 184
118 185
119 popup_setlines({id}, {lnum}, {lines}) *popup_setlines()*
120 In popup {id} set line {lnum} and following to {lines}.
121
122 {lnum} is one-based and must be either an existing line or
123 just one below the last line, in which case the line gets
124 appended.
125
126 {lines} has the same format as one item in {lines} of
127 |popup_show()|. Existing lines are replaced. When {lines}
128 extends below the last line of the popup lines are appended.
129
130 popup_getlines({id}) *popup_getlines()*
131 Return the {lines} for popup {id}.
132
133
134 popup_setoptions({id}, {options}) *popup_setoptions()* 186 popup_setoptions({id}, {options}) *popup_setoptions()*
135 Override options in popup {id} with entries in {options}. 187 Override options in popup {id} with entries in {options}.
136 188
137 189
138 popup_getoptions({id}) *popup_getoptions()* 190 popup_getoptions({id}) *popup_getoptions()*
140 192
141 193
142 popup_close({id}) *popup_close()* 194 popup_close({id}) *popup_close()*
143 Close popup {id}. 195 Close popup {id}.
144 196
145 197 *:popupclear* *:popupc*
146 POPUP_SHOW() ARGUMENTS *popup_show-usage* 198 :popupc[lear] Emergency solution to a misbehaving plugin: close all popup
147 199 windows.
148 The first argument of |popup_show()| is a list of text lines. Each item in 200
149 the list is a dictionary with these entries: 201
150 text The text to display. 202 POPUP BUFFER AND WINDOW *popup-buffer*
203
204 A new buffer is created to hold the text and text properties of the popup
205 window. The buffer is always associated with the popup window and
206 manipulation is restricted:
207 - the buffer has no name
208 - 'buftype' is "popup"
209 - 'swapfile' is off
210 - 'bufhidden' is "hide"
211 - 'buflisted' is off
212 TODO: more
213
214 The window does have a cursor position, but the cursor is not displayed.
215
216 Options can be set on the window with `setwinvar()`, e.g.: >
217 call setwinvar(winid, '&wrap', 0)
218 And options can be set on the buffer with `setbufvar()`, e.g.: >
219 call setbufvar(winbufnr(winid), '&filetype', 'java')
220
221
222 POPUP_CREATE() ARGUMENTS *popup_create-usage*
223
224 The first argument of |popup_create()| specifies the text to be displayed, and
225 optionally text properties. It is in one of three forms:
226 - a string
227 - a list of strings
228 - a list of dictionaries, where each dictionary has these entries:
229 text String with the text to display.
151 props A list of text properties. Optional. 230 props A list of text properties. Optional.
152 Each entry is a dictionary, like the third argument of 231 Each entry is a dictionary, like the third argument of
153 |prop_add()|, but specifying the column in the 232 |prop_add()|, but specifying the column in the
154 dictionary with a "col" entry, see below: 233 dictionary with a "col" entry, see below:
155 |popup-props|. 234 |popup-props|.
156 235
157 The second argument of |popup_show()| is a dictionary with options: 236 The second argument of |popup_create()| is a dictionary with options:
158 line screen line where to position the popup; can use 237 line screen line where to position the popup; can use
159 "cursor", "cursor+1" or "cursor-1" to use the line of 238 "cursor", "cursor+1" or "cursor-1" to use the line of
160 the cursor and add or subtract a number of lines; 239 the cursor and add or subtract a number of lines;
161 default is "cursor-1". 240 default is "cursor-1".
162 col screen column where to position the popup; can use 241 col screen column where to position the popup; can use
166 pos "topleft", "topright", "botleft" or "botright": 245 pos "topleft", "topright", "botleft" or "botright":
167 defines what corner of the popup "line" and "col" are 246 defines what corner of the popup "line" and "col" are
168 used for. Default is "botleft". Alternatively 247 used for. Default is "botleft". Alternatively
169 "center" can be used to position the popup somewhere 248 "center" can be used to position the popup somewhere
170 near the cursor. 249 near the cursor.
250 flip when TRUE (the default) and the position is relative
251 to the cursor, flip to below or above the cursor to
252 avoid overlap with the |popupmenu-completion| or
253 another popup with a higher "zindex"
171 maxheight maximum height 254 maxheight maximum height
172 minheight minimum height 255 minheight minimum height
173 maxwidth maximum width 256 maxwidth maximum width
174 minwidth minimum width 257 minwidth minimum width
258 hidden when TRUE the popup exists but is not displayed; use
259 `popup_show()` to unhide it.
260 tab when -1: display the popup on all tabs; when 0 (the
261 default): display the popup on the current tab;
262 otherwise the number of the tab page the popup is
263 displayed on; when invalid the current tab is used
175 title text to be displayed above the first item in the 264 title text to be displayed above the first item in the
176 popup, on top of any border 265 popup, on top of any border
177 wrap TRUE to make the lines wrap (default TRUE) 266 wrap TRUE to make the lines wrap (default TRUE)
178 highlight highlight group name to use for the text, defines the 267 highlight highlight group name to use for the text, defines the
179 background and foreground color 268 background and foreground color
227 it will be made transparent as well 316 it will be made transparent as well
228 317
229 318
230 POPUP FILTER *popup-filter* 319 POPUP FILTER *popup-filter*
231 320
232 A callback that gets any typed keys while a popup is displayed. It can return 321 A callback that gets any typed keys while a popup is displayed. The filter is
233 TRUE to indicate the key has been handled and is to be discarded, or FALSE to 322 not invoked for as long as the popup is hidden.
234 let Vim handle the key as usual in the current state. 323
324 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.
235 326
236 The filter function is called with two arguments: the ID of the popup and the 327 The filter function is called with two arguments: the ID of the popup and the
237 key. 328 key.
238 329
239 Some common key actions: 330 Some common key actions:
240 Esc close the popup 331 Esc close the popup
241 cursor keys select another entry 332 cursor keys select another entry
242 Tab accept current suggestion 333 Tab accept current suggestion
334
335 A mouse click arrives as <LeftMouse>. The coordinates are in
336 v:mouse_popup_col and v:mouse_popup_row. The top-left screen cell of the
337 popup is col 1, row 1 (not counting the border).
243 338
244 Vim provides standard filters |popup_filter_menu()| and 339 Vim provides standard filters |popup_filter_menu()| and
245 |popup_filter_yesno()|. 340 |popup_filter_yesno()|.
246 341
247 342
263 if a:result 358 if a:result
264 " ... 'y' or 'Y' was pressed 359 " ... 'y' or 'Y' was pressed
265 endif 360 endif
266 endfunc 361 endfunc
267 362
268 call popup_show([{'text': 'Continue? y/n'}], { 363 call popup_create(['Continue? y/n'], {
269 \ 'filter': 'popup_filter_yesno', 364 \ 'filter': 'popup_filter_yesno',
270 \ 'callback': 'MyDialogHandler', 365 \ 'callback': 'MyDialogHandler',
271 \ }) 366 \ })
272 < 367 <
273 368