Mercurial > vim

comparison runtime/doc/popup.txt @ 16654:7d54a66c95d7 v8.1.1329

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.1.1329: plans for popup window support are spread out commit https://github.com/vim/vim/commit/957f85d54ebd5a3bd0d930de9603190f0876f977 Author: Bram Moolenaar <Bram@vim.org> Date: Sun May 12 21:43:48 2019 +0200 patch 8.1.1329: plans for popup window support are spread out Problem: Plans for popup window support are spread out. Solution: Add a first version of the popup window help.
author Bram Moolenaar <Bram@vim.org>
date Sun, 12 May 2019 21:45:05 +0200
parents
children 6030631a1541
comparison
equal deleted inserted replaced
16653:8011a4319da6 16654:7d54a66c95d7
1 *popup.txt* For Vim version 8.1. Last change: 2019 May 12
2
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7 Displaying text with properties attached. *popup* *popup-window*
8
9 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
10
11 1. Introduction |popup-intro|
12 2. Functions |popup-functions|
13 3. Examples |popup-examples|
14
15
16 {not able to use text properties when the |+textprop| feature was
17 disabled at compile time}
18
19 ==============================================================================
20 1. Introduction *popup-intro*
21
22 We are talking about popup windows here, text that goes on top of the buffer
23 text and is under control of a plugin. Other popup functionality:
24 - popup menu, see |popup-menu|
25 - balloon, see |balloon-eval|
26
27 TODO
28
29 ==============================================================================
30 2. Functions *popup-functions*
31
32 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
33
34 Proposal and discussion on issue #4063: https://github.com/vim/vim/issues/4063
35
36 [to be moved to eval.txt later]
37
38 popup_show({lines}, {options}) *popup_show()*
39 Open a popup window showing {lines}, which is a list of lines,
40 where each line has text and text properties.
41
42 {options} is a dictionary with many possible entries.
43
44 Returns a unique ID to be used with |popup_close()|.
45
46 See |popup_show-usage| for details.
47
48
49 popup_dialog({lines}, {options}) *popup_dialog()*
50 Just like |popup_show()| but with different default options:
51 pos "center"
52 zindex 200
53 border []
54
55
56 popup_notification({text}, {options}) *popup_notification()*
57 Show the string {text} for 3 seconds at the top of the Vim
58 window. This works like: >
59 call popup_show([{'text': {text}}], {
60 \ 'line': 1,
61 \ 'col': 10,
62 \ 'time': 3000,
63 \ 'zindex': 200,
64 \ 'highlight': 'WarningMsg',
65 \ 'border: [],
66 \ })
67 < Use {options} to change the properties.
68
69 popup_atcursor({text}, {options}) *popup_atcursor()*
70 Show the string {text} above the cursor, and close it when the
71 cursor moves. This works like: >
72 call popup_show([{'text': {text}}], {
73 \ 'line': 'cursor-1',
74 \ 'col': 'cursor',
75 \ 'zindex': 50,
76 \ 'moved': 'WORD',
77 \ })
78 < Use {options} to change the properties.
79
80
81 popup_menu({lines}, {options}) *popup_atcursor()*
82 Show the {lines} near the cursor, handle selecting one of the
83 items with cursorkeys, and close it an item is selected with
84 Space or Enter. This works like: >
85 call popup_show({lines}, {
86 \ 'pos': 'center',
87 \ 'zindex': 200,
88 \ 'wrap': 0,
89 \ 'border': [],
90 \ 'filter': 'popup_filter_menu',
91 \ })
92 < Use {options} to change the properties. Should at least set
93 "callback" to a function that handles the selected item.
94
95
96 popup_move({id}, {options}) *popup_move()*
97 Move popup {id} to the position speficied with {options}.
98 {options} may contain the items from |popup_show()| that
99 specify the popup position: "line", "col", "pos", "maxheight",
100 "minheight", "maxwidth" and "minwidth".
101
102
103 popup_filter_menu({id}, {key}) *popup_filter_menu()*
104 Filter that can be used for a popup. It handles the cursor
105 keys to move the selected index in the popup. Space and Enter
106 can be used to select an item. Invokes the "callback" of the
107 popup menu with the index of the selected line as the second
108 argument.
109
110
111 popup_filter_yesno({id}, {key}) *popup_filter_yesno()*
112 Filter that can be used for a popup. It handles only the keys
113 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the
114 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
116 pressing 'n'.
117
118
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()*
135 Override options in popup {id} with entries in {options}.
136
137
138 popup_getoptions({id}) *popup_getoptions()*
139 Return the {options} for popup {id}.
140
141
142 popup_close({id}) *popup_close()*
143 Close popup {id}.
144
145
146 POPUP_SHOW() ARGUMENTS *popup_show-usage*
147
148 The first argument of |popup_show()| is a list of text lines. Each item in
149 the list is a dictionary with these entries:
150 text The text to display.
151 props A list of text properties. Optional.
152 Each entry is a dictionary, like the third argument of
153 |prop_add()|, but specifying the column in the
154 dictionary with a "col" entry, see below:
155 |popup-props|.
156
157 The second argument of |popup_show()| is a dictionary with options:
158 line screen line where to position the popup; can use
159 "cursor", "cursor+1" or "cursor-1" to use the line of
160 the cursor and add or subtract a number of lines;
161 default is "cursor-1".
162 col screen column where to position the popup; can use
163 "cursor" to use the column of the cursor, "cursor+99"
164 and "cursor-99" to add or subtract a number of
165 columns; default is "cursor"
166 pos "topleft", "topright", "botleft" or "botright":
167 defines what corner of the popup "line" and "col" are
168 used for. Default is "botleft". Alternatively
169 "center" can be used to position the popup somewhere
170 near the cursor.
171 maxheight maximum height
172 minheight minimum height
173 maxwidth maximum width
174 minwidth minimum width
175 title text to be displayed above the first item in the
176 popup, on top of any border
177 wrap TRUE to make the lines wrap (default TRUE)
178 highlight highlight group name to use for the text, defines the
179 background and foreground color
180 border list with numbers, defining the border thickness
181 above/right/below/left of the popup; an empty list
182 uses a border of 1 all around
183 borderhighlight highlight group name to use for the border
184 borderchars list with characters, defining the character to use
185 for the top/right/bottom/left border; optionally
186 followed by the character to use for the
187 topright/botright/botleft/topleft corner; an empty
188 list can be used to show a double line all around
189 zindex priority for the popup, default 50
190 time time in milliseconds after which the popup will close;
191 when omitted |popup_close()| must be used.
192 moved "cell": close the popup if the cursor moved at least
193 one screen cell; "word" allows for moving within
194 |<cword>|, "WORD" allows for moving within |<cWORD>|,
195 a list with two numbers specifies the start and end
196 column
197 filter a callback that can filter typed characters, see
198 |popup-filter|
199 callback a callback to be used when the popup closes, e.g. when
200 using |popup_filter_menu()|, see |popup-callback|.
201
202 Depending on the "zindex" the popup goes under or above other popups. The
203 completion menu (|popup-menu|) has zindex 100. For messages that occur for a
204 short time the suggestion is to use zindex 1000.
205
206 By default text wraps, which causes a line in {lines} to occupy more than one
207 screen line. When "wrap" is FALSE then the text outside of the popup or
208 outside of the Vim window will not be displayed, thus truncated.
209
210
211 POPUP TEXT PROPERTIES *popup-props*
212
213 These are similar to the third argument of |prop_add()|, but not exactly the
214 same, since they only apply to one line.
215 col starting column, counted in bytes, use one for the
216 first column.
217 length length of text in bytes; can be zero
218 end_col column just after the text; not used when "length" is
219 present; when {col} and "end_col" are equal, this is a
220 zero-width text property
221 id user defined ID for the property; when omitted zero is
222 used
223 type name of the text property type, as added with
224 |prop_type_add()|
225 transparent do not show these characters, show the text under it;
226 if there is an border character to the right or below
227 it will be made transparent as well
228
229
230 POPUP FILTER *popup-filter*
231
232 A callback that gets any typed keys while a popup is displayed. It can return
233 TRUE to indicate the key has been handled and is to be discarded, or FALSE to
234 let Vim handle the key as usual in the current state.
235
236 The filter function is called with two arguments: the ID of the popup and the
237 key.
238
239 Some common key actions:
240 Esc close the popup
241 cursor keys select another entry
242 Tab accept current suggestion
243
244 Vim provides standard filters |popup_filter_menu()| and
245 |popup_filter_yesno()|.
246
247
248 POPUP CALLBACK *popup-callback*
249
250 A callback that is invoked when the popup closes. Used by
251 |popup_filter_menu()|. Invoked with two arguments: the ID of the popup and
252 the result, which would usually be an index in the popup lines, or whatever
253 the filter wants to pass.
254
255 ==============================================================================
256 3. Examples *popup-examples*
257
258 TODO
259
260 Prompt the user to press y/Y or n/N: >
261
262 func MyDialogHandler(id, result)
263 if a:result
264 " ... 'y' or 'Y' was pressed
265 endif
266 endfunc
267
268 call popup_show([{'text': 'Continue? y/n'}], {
269 \ 'filter': 'popup_filter_yesno',
270 \ 'callback': 'MyDialogHandler',
271 \ })
272 <
273
274 vim:tw=78:ts=8:noet:ft=help:norl: