Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 1 | *popup.txt* For Vim version 8.1. Last change: 2019 May 21 |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 2 | |
| 3 | |
| 4 | VIM REFERENCE MANUAL by Bram Moolenaar |
| 5 | |
| 6 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 7 | Displaying text in floating window. *popup* *popup-window* |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 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 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 16 | {not available if the |+eval| feature was disabled at compile time} |
| 17 | {not able to use text properties if the |+textprop| feature was disabled at |
| 18 | compile time} |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 19 | |
| 20 | ============================================================================== |
| 21 | 1. Introduction *popup-intro* |
| 22 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 23 | We are talking about popup windows here, text that goes on top of the regular |
| 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: |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 45 | - popup menu, see |popup-menu| |
| 46 | - balloon, see |balloon-eval| |
| 47 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 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 | |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 77 | |
| 78 | ============================================================================== |
| 79 | 2. Functions *popup-functions* |
| 80 | |
| 81 | THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE |
| 82 | |
| 83 | Proposal and discussion on issue #4063: https://github.com/vim/vim/issues/4063 |
| 84 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 85 | [functions to be moved to eval.txt later, keep list of functions here] |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 86 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 87 | popup_create({text}, {options}) *popup_create()* |
| 88 | Open a popup window showing {text}, which is either: |
| 89 | - a string |
| 90 | - a list of strings |
| 91 | - a list of text lines with text properties |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 92 | {options} is a dictionary with many possible entries. |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 93 | See |popup_create-usage| for details. |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 94 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 95 | Returns a window-ID, which can be used with other popup |
| 96 | functions. Use `winbufnr()` to get the number of the buffer |
| 97 | in the window: > |
| 98 | let winid = popup_create('hello', {}) |
| 99 | let bufnr = winbufnr(winid) |
| 100 | call setbufline(bufnr, 2, 'second line') |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 101 | |
| 102 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 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. |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 111 | |
| 112 | |
| 113 | popup_notification({text}, {options}) *popup_notification()* |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 114 | Show the {text} for 3 seconds at the top of the Vim window. |
| 115 | This works like: > |
| 116 | call popup_create({text}, { |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 117 | \ 'line': 1, |
| 118 | \ 'col': 10, |
| 119 | \ 'time': 3000, |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 120 | \ 'tab': -1, |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 121 | \ 'zindex': 200, |
| 122 | \ 'highlight': 'WarningMsg', |
| 123 | \ 'border: [], |
| 124 | \ }) |
| 125 | < Use {options} to change the properties. |
| 126 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 127 | |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 128 | popup_atcursor({text}, {options}) *popup_atcursor()* |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 129 | Show the {text} above the cursor, and close it when the cursor |
| 130 | moves. This works like: > |
| 131 | call popup_create({text}, { |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 132 | \ 'line': 'cursor-1', |
| 133 | \ 'col': 'cursor', |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 134 | \ 'moved': 'WORD', |
| 135 | \ }) |
| 136 | < Use {options} to change the properties. |
| 137 | |
| 138 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 139 | popup_menu({text}, {options}) *popup_menu()* |
| 140 | Show the {text} near the cursor, handle selecting one of the |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 141 | items with cursorkeys, and close it an item is selected with |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 142 | Space or Enter. {text} should have multiple lines to make this |
| 143 | useful. This works like: > |
| 144 | call popup_create({text}, { |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 145 | \ 'pos': 'center', |
| 146 | \ 'zindex': 200, |
| 147 | \ 'wrap': 0, |
| 148 | \ 'border': [], |
| 149 | \ 'filter': 'popup_filter_menu', |
| 150 | \ }) |
| 151 | < Use {options} to change the properties. Should at least set |
| 152 | "callback" to a function that handles the selected item. |
| 153 | |
| 154 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 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 | |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 163 | popup_move({id}, {options}) *popup_move()* |
| 164 | Move popup {id} to the position speficied with {options}. |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 165 | {options} may contain the items from |popup_create()| that |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 166 | specify the popup position: "line", "col", "pos", "maxheight", |
| 167 | "minheight", "maxwidth" and "minwidth". |
| 168 | |
| 169 | |
| 170 | popup_filter_menu({id}, {key}) *popup_filter_menu()* |
| 171 | Filter that can be used for a popup. It handles the cursor |
| 172 | keys to move the selected index in the popup. Space and Enter |
| 173 | can be used to select an item. Invokes the "callback" of the |
| 174 | popup menu with the index of the selected line as the second |
| 175 | argument. |
| 176 | |
| 177 | |
| 178 | popup_filter_yesno({id}, {key}) *popup_filter_yesno()* |
| 179 | Filter that can be used for a popup. It handles only the keys |
| 180 | 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the |
| 181 | popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N' |
| 182 | as the second argument. Pressing Esc and CTRL-C works like |
| 183 | pressing 'n'. |
| 184 | |
| 185 | |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 186 | popup_setoptions({id}, {options}) *popup_setoptions()* |
| 187 | Override options in popup {id} with entries in {options}. |
| 188 | |
| 189 | |
| 190 | popup_getoptions({id}) *popup_getoptions()* |
| 191 | Return the {options} for popup {id}. |
| 192 | |
| 193 | |
| 194 | popup_close({id}) *popup_close()* |
| 195 | Close popup {id}. |
| 196 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 197 | *:popupclear* *:popupc* |
| 198 | :popupc[lear] Emergency solution to a misbehaving plugin: close all popup |
| 199 | windows. |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 200 | |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 201 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 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. |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 230 | props A list of text properties. Optional. |
| 231 | Each entry is a dictionary, like the third argument of |
| 232 | |prop_add()|, but specifying the column in the |
| 233 | dictionary with a "col" entry, see below: |
| 234 | |popup-props|. |
| 235 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 236 | The second argument of |popup_create()| is a dictionary with options: |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 237 | line screen line where to position the popup; can use |
| 238 | "cursor", "cursor+1" or "cursor-1" to use the line of |
| 239 | the cursor and add or subtract a number of lines; |
| 240 | default is "cursor-1". |
| 241 | col screen column where to position the popup; can use |
| 242 | "cursor" to use the column of the cursor, "cursor+99" |
| 243 | and "cursor-99" to add or subtract a number of |
| 244 | columns; default is "cursor" |
| 245 | pos "topleft", "topright", "botleft" or "botright": |
| 246 | defines what corner of the popup "line" and "col" are |
| 247 | used for. Default is "botleft". Alternatively |
| 248 | "center" can be used to position the popup somewhere |
| 249 | near the cursor. |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 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" |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 254 | maxheight maximum height |
| 255 | minheight minimum height |
| 256 | maxwidth maximum width |
| 257 | minwidth minimum width |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 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 |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 264 | title text to be displayed above the first item in the |
| 265 | popup, on top of any border |
| 266 | wrap TRUE to make the lines wrap (default TRUE) |
| 267 | highlight highlight group name to use for the text, defines the |
| 268 | background and foreground color |
| 269 | border list with numbers, defining the border thickness |
| 270 | above/right/below/left of the popup; an empty list |
| 271 | uses a border of 1 all around |
| 272 | borderhighlight highlight group name to use for the border |
| 273 | borderchars list with characters, defining the character to use |
| 274 | for the top/right/bottom/left border; optionally |
| 275 | followed by the character to use for the |
| 276 | topright/botright/botleft/topleft corner; an empty |
| 277 | list can be used to show a double line all around |
| 278 | zindex priority for the popup, default 50 |
| 279 | time time in milliseconds after which the popup will close; |
| 280 | when omitted |popup_close()| must be used. |
| 281 | moved "cell": close the popup if the cursor moved at least |
| 282 | one screen cell; "word" allows for moving within |
| 283 | |<cword>|, "WORD" allows for moving within |<cWORD>|, |
| 284 | a list with two numbers specifies the start and end |
| 285 | column |
| 286 | filter a callback that can filter typed characters, see |
| 287 | |popup-filter| |
| 288 | callback a callback to be used when the popup closes, e.g. when |
| 289 | using |popup_filter_menu()|, see |popup-callback|. |
| 290 | |
| 291 | Depending on the "zindex" the popup goes under or above other popups. The |
| 292 | completion menu (|popup-menu|) has zindex 100. For messages that occur for a |
| 293 | short time the suggestion is to use zindex 1000. |
| 294 | |
| 295 | By default text wraps, which causes a line in {lines} to occupy more than one |
| 296 | screen line. When "wrap" is FALSE then the text outside of the popup or |
| 297 | outside of the Vim window will not be displayed, thus truncated. |
| 298 | |
| 299 | |
| 300 | POPUP TEXT PROPERTIES *popup-props* |
| 301 | |
| 302 | These are similar to the third argument of |prop_add()|, but not exactly the |
| 303 | same, since they only apply to one line. |
| 304 | col starting column, counted in bytes, use one for the |
| 305 | first column. |
| 306 | length length of text in bytes; can be zero |
| 307 | end_col column just after the text; not used when "length" is |
| 308 | present; when {col} and "end_col" are equal, this is a |
| 309 | zero-width text property |
| 310 | id user defined ID for the property; when omitted zero is |
| 311 | used |
| 312 | type name of the text property type, as added with |
| 313 | |prop_type_add()| |
| 314 | transparent do not show these characters, show the text under it; |
| 315 | if there is an border character to the right or below |
| 316 | it will be made transparent as well |
| 317 | |
| 318 | |
| 319 | POPUP FILTER *popup-filter* |
| 320 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 321 | A callback that gets any typed keys while a popup is displayed. The filter is |
| 322 | not invoked for as long as the popup is hidden. |
| 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. |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 326 | |
| 327 | The filter function is called with two arguments: the ID of the popup and the |
| 328 | key. |
| 329 | |
| 330 | Some common key actions: |
| 331 | Esc close the popup |
| 332 | cursor keys select another entry |
| 333 | Tab accept current suggestion |
| 334 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 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). |
| 338 | |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 339 | Vim provides standard filters |popup_filter_menu()| and |
| 340 | |popup_filter_yesno()|. |
| 341 | |
| 342 | |
| 343 | POPUP CALLBACK *popup-callback* |
| 344 | |
| 345 | A callback that is invoked when the popup closes. Used by |
| 346 | |popup_filter_menu()|. Invoked with two arguments: the ID of the popup and |
| 347 | the result, which would usually be an index in the popup lines, or whatever |
| 348 | the filter wants to pass. |
| 349 | |
| 350 | ============================================================================== |
| 351 | 3. Examples *popup-examples* |
| 352 | |
| 353 | TODO |
| 354 | |
| 355 | Prompt the user to press y/Y or n/N: > |
| 356 | |
| 357 | func MyDialogHandler(id, result) |
| 358 | if a:result |
| 359 | " ... 'y' or 'Y' was pressed |
| 360 | endif |
| 361 | endfunc |
| 362 | |
Bram Moolenaar | 5c017b2 | 2019-05-21 23:09:01 +0200 | [diff] [blame] | 363 | call popup_create(['Continue? y/n'], { |
Bram Moolenaar | 957f85d | 2019-05-12 21:43:48 +0200 | [diff] [blame] | 364 | \ 'filter': 'popup_filter_yesno', |
| 365 | \ 'callback': 'MyDialogHandler', |
| 366 | \ }) |
| 367 | < |
| 368 | |
| 369 | vim:tw=78:ts=8:noet:ft=help:norl: |