diff options
author | Bram Moolenaar <Bram@vim.org> | 2019-07-04 16:54:54 +0200 |
---|---|---|
committer | Bram Moolenaar <Bram@vim.org> | 2019-07-04 16:54:54 +0200 |
commit | 931a277145d8fc9544765047116afe557eb606d2 (patch) | |
tree | b5725fc51adf546d2e2890c3a91b5f5661440569 /runtime/doc/popup.txt | |
parent | 6cb39f924a10912a615573230e906e8089975198 (diff) |
patch 8.1.1628: popup window functions not in list of functionsv8.1.1628
Problem: Popup window functions not in list of functions.
Solution: Add popup window functins to the list of functions. Reorganise
the popup window help.
Diffstat (limited to 'runtime/doc/popup.txt')
-rw-r--r-- | runtime/doc/popup.txt | 127 |
1 files changed, 55 insertions, 72 deletions
diff --git a/runtime/doc/popup.txt b/runtime/doc/popup.txt index cfa84d7fe7..3fb6f6bf8e 100644 --- a/runtime/doc/popup.txt +++ b/runtime/doc/popup.txt @@ -1,16 +1,26 @@ -*popup.txt* For Vim version 8.1. Last change: 2019 Jun 30 +*popup.txt* For Vim version 8.1. Last change: 2019 Jul 04 VIM REFERENCE MANUAL by Bram Moolenaar -Displaying text in floating window. *popup* *popup-window* +Displaying text in a floating window. *popup* *popup-window* -THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE 1. Introduction |popup-intro| + Window position and size |popup-position| + Closing the popup window |popup-close| + Popup buffer and window |popup-buffer| 2. Functions |popup-functions| -3. Examples |popup-examples| + Details |popup-function-details| +3. Usage |popup-usage| + popup_create() arguments |popup_create-arguments| + Popup text properties |popup-props| + Popup filter |popup-filter| + Popup callback |popup-callback| + Popup scrollbar |popup-scrollbar| + Popup mask |popup-mask| +4. Examples |popup-examples| {not available if the |+textprop| feature was disabled at compile time} @@ -55,7 +65,7 @@ If this is not what you are looking for, check out other popup functionality: - balloon, see |balloon-eval| -WINDOW POSITION AND SIZE *popup-position* +WINDOW POSITION AND SIZE *popup-position* The height of the window is normally equal to the number of, possibly wrapping, lines in the buffer. It can be limited with the "maxheight" @@ -85,7 +95,7 @@ That way you can still see where it is, even though you cannot see the text that it is in. -CLOSING THE POPUP WINDOW *popup-close* +CLOSING THE POPUP WINDOW *popup-close* Normally the plugin that created the popup window is also in charge of closing it. If somehow a popup hangs around, you can close all of them with: > @@ -97,40 +107,41 @@ or by clicking anywhere inside the popup. This must be enabled with the "close" property. It is set by default for notifications. -TODO: -- Add test for when popup with mask is off the left and off the right of the - screen. -- check padding/border when popup is off the left and right of the screen. -- Have a way to scroll to the bottom? (#4577) -- Why does 'nrformats' leak from the popup window buffer??? -- Disable commands, feedkeys(), CTRL-W, etc. in a popup window. - Use ERROR_IF_POPUP_WINDOW for more commands. -- Add 'balloonpopup': instead of showing text, let the callback open a popup - window and return the window ID. The popup will then be closed when the - mouse moves, except when it moves inside the popup. -- For the "moved" property also include mouse movement? -- Can the buffer be re-used, to avoid using up lots of buffer numbers? -- Have an option to attach the popup to a text position, like text properties - do. (#4560) -- Make redrawing more efficient and avoid flicker: - - put popup menu also put in popup_mask? -- Invoke filter with character before mapping? -- Figure out the size and position better. - if wrapping splits a double-wide character - if wrapping inserts indent -- When drawing on top half a double-wide character, display ">" or "<" in the - incomplete cell. -- Use a popup window for the "info" item of completion instead of using a - preview window. Ideas in issue #4544. - How to add highlighting? -- Implement: - flip option +POPUP BUFFER AND WINDOW *popup-buffer* + +If a popup function is called to create a popup from text, a new buffer is +created to hold the text and text properties of the popup window. The buffer +is always associated with the popup window and manipulation is restricted: +- the buffer has no name +- 'buftype' is "popup" +- 'swapfile' is off +- 'bufhidden' is "hide" +- 'buflisted' is off +- 'undolevels' is -1: no undo at all +- all other buffer-local and window-local options are set to their Vim default + value. + +It is possible to change the specifically mentioned options, but anything +might break then, so better leave them alone. + +The window does have a cursor position, but the cursor is not displayed. + +To execute a command in the context of the popup window and buffer use +`win_execute()`. Example: > + call win_execute(winid, 'syntax enable') + +Options can be set on the window with `setwinvar()`, e.g.: > + call setwinvar(winid, '&wrap', 0) +And options can be set on the buffer with `setbufvar()`, e.g.: > + call setbufvar(winbufnr(winid), '&filetype', 'java') +Note that this does not trigger autocommands. Use `win_execute()` if you do +need them. + + ============================================================================== 2. Functions *popup-functions* -THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE - Creating a popup window: |popup_create()| centered in the screen |popup_atcursor()| just above the cursor position, closes when @@ -159,9 +170,9 @@ Other: |popup_getpos()| get actual position and size of a popup -[functions help to be moved to eval.txt later] +DETAILS *popup-function-details* -popup_atcursor({what}, {options}) *popup_atcursor()* +popup_atcursor({what}, {options}) *popup_atcursor()* Show the {what} above the cursor, and close it when the cursor moves. This works like: > call popup_create({what}, { @@ -199,7 +210,7 @@ popup_create({what}, {options}) *popup_create()* the popup closes. {options} is a dictionary with many possible entries. - See |popup_create-usage| for details. + See |popup_create-arguments| for details. Returns a window-ID, which can be used with other popup functions. Use `winbufnr()` to get the number of the buffer @@ -417,38 +428,10 @@ popup_settext({id}, {text}) *popup_settext()* by the different text. -POPUP BUFFER AND WINDOW *popup-buffer* - -A new buffer is created to hold the text and text properties of the popup -window. The buffer is always associated with the popup window and -manipulation is restricted: -- the buffer has no name -- 'buftype' is "popup" -- 'swapfile' is off -- 'bufhidden' is "hide" -- 'buflisted' is off -- 'undolevels' is -1: no undo at all -- all other buffer-local and window-local options are set to their Vim default - value. - -It is possible to change the specifically mentioned options, but anything -might break then, so better leave them alone. - -The window does have a cursor position, but the cursor is not displayed. - -To execute a command in the context of the popup window and buffer use -`win_execute()`. Example: > - call win_execute(winid, 'syntax enable') - -Options can be set on the window with `setwinvar()`, e.g.: > - call setwinvar(winid, '&wrap', 0) -And options can be set on the buffer with `setbufvar()`, e.g.: > - call setbufvar(winbufnr(winid), '&filetype', 'java') -Note that this does not trigger autocommands. Use `win_execute()` if you do -need them. - +============================================================================== +3. Usage *popup-usage* -POPUP_CREATE() ARGUMENTS *popup_create-usage* +POPUP_CREATE() ARGUMENTS *popup_create-arguments* The first argument of |popup_create()| (and the second argument to |popup_settext()|) specifies the text to be displayed, and optionally text @@ -709,9 +692,9 @@ To make the four corners transparent: [[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]] ============================================================================== -3. Examples *popup-examples* +4. Examples *popup-examples* -TODO +TODO: more interesting examples *popup_dialog-example* Prompt the user to press y/Y or n/N: > |