Mercurial > vim

comparison runtime/doc/popup.txt @ 16808:c002c4899529

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update runtime files. commit https://github.com/vim/vim/commit/68e6560b84f196c82e27a72669684d5506a3a837 Author: Bram Moolenaar <Bram@vim.org> Date: Sun May 26 21:33:31 2019 +0200 Update runtime files.
author Bram Moolenaar <Bram@vim.org>
date Sun, 26 May 2019 21:45:07 +0200
parents 306766ed0f70
children 5ff14f96f1c9
comparison
equal deleted inserted replaced
16807:ce0eea70294d 16808:c002c4899529
1 *popup.txt* For Vim version 8.1. Last change: 2019 May 21 1 *popup.txt* For Vim version 8.1. Last change: 2019 May 26
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
23 We are talking about popup windows here, text that goes on top of the regular 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 24 windows and is under control of a plugin. You cannot edit the text in the
25 popup window like with regular windows. 25 popup window like with regular windows.
26 26
27 A popup window can be used for such things as: 27 A popup window can be used for such things as:
28 - briefly show a message without changing the command line 28 - briefly show a message without overwriting the command line
29 - prompt the user with a dialog 29 - prompt the user with a dialog
30 - display contextual information while typing 30 - display contextual information while typing
31 - give extra information for auto-completion 31 - give extra information for auto-completion
32 32
33 The text in the popup window can be colored with |text-properties|. It is 33 The text in the popup window can be colored with |text-properties|. It is
40 40
41 'hlsearch' and match highlighting are not displayed in a popup window. 41 'hlsearch' and match highlighting are not displayed in a popup window.
42 42
43 A popup window has a window-ID like other windows, but behaves differently. 43 A popup window has a window-ID like other windows, but behaves differently.
44 The size can be up to the whole Vim window and it overlaps other windows. 44 The size can be up to the whole Vim window and it overlaps other windows.
45 It contains a buffer, and that buffer is always associated with the popup 45 Popup windows can also overlap each other.
46 window. The window cannot be used in Normal, Visual or Insert mode, it does 46
47 not get keyboard focus. You can use functions like `setbufline()` to change 47 The popup window contains a buffer, and that buffer is always associated with
48 the text in the buffer. There are more differences from how this window and 48 the popup window. The window cannot be used in Normal, Visual or Insert mode,
49 buffer behave compared to regular windows and buffers, see |popup-buffer|. 49 it does not get keyboard focus. You can use functions like `setbufline()` to
50 change the text in the buffer. There are more differences from how this
51 window and buffer behave compared to regular windows and buffers, see
52 |popup-buffer|.
50 53
51 If this is not what you are looking for, check out other popup functionality: 54 If this is not what you are looking for, check out other popup functionality:
52 - popup menu, see |popup-menu| 55 - popup menu, see |popup-menu|
53 - balloon, see |balloon-eval| 56 - balloon, see |balloon-eval|
54 57
55 58
56 WINDOW POSITION AND SIZE *popup-position* 59 WINDOW POSITION AND SIZE *popup-position*
57 60
58 The height of the window is normally equal to the number of lines in the 61 The height of the window is normally equal to the number of, possibly
59 buffer. It can be limited with the "maxheight" property. You can use empty 62 wrapping, lines in the buffer. It can be limited with the "maxheight"
60 lines to increase the height. 63 property. You can use empty lines to increase the height.
61 64
62 The width of the window is normally equal to the longest line in the buffer. 65 The width of the window is normally equal to the longest line in the buffer.
63 It can be limited with the "maxwidth" property. You can use spaces to 66 It can be limited with the "maxwidth" property. You can use spaces to
64 increase the width. 67 increase the width.
65 68
79 Probably 2. is the best choice. 82 Probably 2. is the best choice.
80 83
81 84
82 IMPLEMENTATION: 85 IMPLEMENTATION:
83 - Code is in popupwin.c 86 - Code is in popupwin.c
84 - handle screen resize in screenalloc(). 87 - Implement list of lines with text properties
85 - Support tab-local popup windows, use tp_first_popupwin and 88 - Implement popup_hide() and popup_show()
86 first_tab_popupwin. Swap like with firstwin/curwin. 89 - Implement filter.
90 - Handle screen resize in screenalloc().
87 - Make redrawing more efficient and avoid flicker. 91 - Make redrawing more efficient and avoid flicker.
88 - implement all the unimplemented features. 92 - Properly figure out the size and position.
93 - Implement all the unimplemented options and features.
89 94
90 95
91 ============================================================================== 96 ==============================================================================
92 2. Functions *popup-functions* 97 2. Functions *popup-functions*
93 98
94 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE 99 THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
95 100
96 Proposal and discussion on issue #4063: https://github.com/vim/vim/issues/4063 101 [functions to be moved to eval.txt later, keep overview of functions here]
97
98 [functions to be moved to eval.txt later, keep list of functions here]
99 102
100 popup_create({text}, {options}) *popup_create()* 103 popup_create({text}, {options}) *popup_create()*
101 Open a popup window showing {text}, which is either: 104 Open a popup window showing {text}, which is either:
102 - a string 105 - a string
103 - a list of strings 106 - a list of strings
254 - 'swapfile' is off 257 - 'swapfile' is off
255 - 'bufhidden' is "hide" 258 - 'bufhidden' is "hide"
256 - 'buflisted' is off 259 - 'buflisted' is off
257 - 'undolevels' is -1: no undo at all 260 - 'undolevels' is -1: no undo at all
258 TODO: more 261 TODO: more
262
263 It is possible to change these options, but anything might break then, so
264 better leave them alone.
259 265
260 The window does have a cursor position, but the cursor is not displayed. 266 The window does have a cursor position, but the cursor is not displayed.
261 267
262 Options can be set on the window with `setwinvar()`, e.g.: > 268 Options can be set on the window with `setwinvar()`, e.g.: >
263 call setwinvar(winid, '&wrap', 0) 269 call setwinvar(winid, '&wrap', 0)