# HG changeset patch # User Bram Moolenaar # Date 1557690305 -7200 # Node ID 7d54a66c95d7f0ea9f8bc20389f83a3bebd5a36c # Parent 8011a4319da6bb60b0e6e8af75f285306ed8b6da patch 8.1.1329: plans for popup window support are spread out commit https://github.com/vim/vim/commit/957f85d54ebd5a3bd0d930de9603190f0876f977 Author: Bram Moolenaar 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. diff --git a/runtime/doc/Makefile b/runtime/doc/Makefile --- a/runtime/doc/Makefile +++ b/runtime/doc/Makefile @@ -83,6 +83,7 @@ DOCS = \ pi_tar.txt \ pi_vimball.txt \ pi_zip.txt \ + popup.txt \ print.txt \ quickfix.txt \ quickref.txt \ @@ -220,6 +221,7 @@ HTMLS = \ pi_tar.html \ pi_vimball.html \ pi_zip.html \ + popup.html \ print.html \ quickfix.html \ quickref.html \ diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -143,6 +143,7 @@ Special issues ~ |remote.txt| using Vim as a server or client |term.txt| using different terminals and mice |terminal.txt| Terminal window support +|popup.txt| popop window support Programming language support ~ |indent.txt| automatic indenting for C and other languages diff --git a/runtime/doc/popup.txt b/runtime/doc/popup.txt new file mode 100644 --- /dev/null +++ b/runtime/doc/popup.txt @@ -0,0 +1,274 @@ +*popup.txt* For Vim version 8.1. Last change: 2019 May 12 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Displaying text with properties attached. *popup* *popup-window* + +THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE + +1. Introduction |popup-intro| +2. Functions |popup-functions| +3. Examples |popup-examples| + + +{not able to use text properties when the |+textprop| feature was +disabled at compile time} + +============================================================================== +1. Introduction *popup-intro* + +We are talking about popup windows here, text that goes on top of the buffer +text and is under control of a plugin. Other popup functionality: +- popup menu, see |popup-menu| +- balloon, see |balloon-eval| + +TODO + +============================================================================== +2. Functions *popup-functions* + +THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE + +Proposal and discussion on issue #4063: https://github.com/vim/vim/issues/4063 + +[to be moved to eval.txt later] + +popup_show({lines}, {options}) *popup_show()* + Open a popup window showing {lines}, which is a list of lines, + where each line has text and text properties. + + {options} is a dictionary with many possible entries. + + Returns a unique ID to be used with |popup_close()|. + + See |popup_show-usage| for details. + + +popup_dialog({lines}, {options}) *popup_dialog()* + Just like |popup_show()| but with different default options: + pos "center" + zindex 200 + border [] + + +popup_notification({text}, {options}) *popup_notification()* + Show the string {text} for 3 seconds at the top of the Vim + window. This works like: > + call popup_show([{'text': {text}}], { + \ 'line': 1, + \ 'col': 10, + \ 'time': 3000, + \ 'zindex': 200, + \ 'highlight': 'WarningMsg', + \ 'border: [], + \ }) +< Use {options} to change the properties. + +popup_atcursor({text}, {options}) *popup_atcursor()* + Show the string {text} above the cursor, and close it when the + cursor moves. This works like: > + call popup_show([{'text': {text}}], { + \ 'line': 'cursor-1', + \ 'col': 'cursor', + \ 'zindex': 50, + \ 'moved': 'WORD', + \ }) +< Use {options} to change the properties. + + +popup_menu({lines}, {options}) *popup_atcursor()* + Show the {lines} near the cursor, handle selecting one of the + items with cursorkeys, and close it an item is selected with + Space or Enter. This works like: > + call popup_show({lines}, { + \ 'pos': 'center', + \ 'zindex': 200, + \ 'wrap': 0, + \ 'border': [], + \ 'filter': 'popup_filter_menu', + \ }) +< Use {options} to change the properties. Should at least set + "callback" to a function that handles the selected item. + + +popup_move({id}, {options}) *popup_move()* + Move popup {id} to the position speficied with {options}. + {options} may contain the items from |popup_show()| that + specify the popup position: "line", "col", "pos", "maxheight", + "minheight", "maxwidth" and "minwidth". + + +popup_filter_menu({id}, {key}) *popup_filter_menu()* + Filter that can be used for a popup. It handles the cursor + keys to move the selected index in the popup. Space and Enter + can be used to select an item. Invokes the "callback" of the + popup menu with the index of the selected line as the second + argument. + + +popup_filter_yesno({id}, {key}) *popup_filter_yesno()* + Filter that can be used for a popup. It handles only the keys + 'y', 'Y' and 'n' or 'N'. Invokes the "callback" of the + popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N' + as the second argument. Pressing Esc and CTRL-C works like + pressing 'n'. + + +popup_setlines({id}, {lnum}, {lines}) *popup_setlines()* + In popup {id} set line {lnum} and following to {lines}. + + {lnum} is one-based and must be either an existing line or + just one below the last line, in which case the line gets + appended. + + {lines} has the same format as one item in {lines} of + |popup_show()|. Existing lines are replaced. When {lines} + extends below the last line of the popup lines are appended. + +popup_getlines({id}) *popup_getlines()* + Return the {lines} for popup {id}. + + +popup_setoptions({id}, {options}) *popup_setoptions()* + Override options in popup {id} with entries in {options}. + + +popup_getoptions({id}) *popup_getoptions()* + Return the {options} for popup {id}. + + +popup_close({id}) *popup_close()* + Close popup {id}. + + +POPUP_SHOW() ARGUMENTS *popup_show-usage* + +The first argument of |popup_show()| is a list of text lines. Each item in +the list is a dictionary with these entries: + text The text to display. + props A list of text properties. Optional. + Each entry is a dictionary, like the third argument of + |prop_add()|, but specifying the column in the + dictionary with a "col" entry, see below: + |popup-props|. + +The second argument of |popup_show()| is a dictionary with options: + line screen line where to position the popup; can use + "cursor", "cursor+1" or "cursor-1" to use the line of + the cursor and add or subtract a number of lines; + default is "cursor-1". + col screen column where to position the popup; can use + "cursor" to use the column of the cursor, "cursor+99" + and "cursor-99" to add or subtract a number of + columns; default is "cursor" + pos "topleft", "topright", "botleft" or "botright": + defines what corner of the popup "line" and "col" are + used for. Default is "botleft". Alternatively + "center" can be used to position the popup somewhere + near the cursor. + maxheight maximum height + minheight minimum height + maxwidth maximum width + minwidth minimum width + title text to be displayed above the first item in the + popup, on top of any border + wrap TRUE to make the lines wrap (default TRUE) + highlight highlight group name to use for the text, defines the + background and foreground color + border list with numbers, defining the border thickness + above/right/below/left of the popup; an empty list + uses a border of 1 all around + borderhighlight highlight group name to use for the border + borderchars list with characters, defining the character to use + for the top/right/bottom/left border; optionally + followed by the character to use for the + topright/botright/botleft/topleft corner; an empty + list can be used to show a double line all around + zindex priority for the popup, default 50 + time time in milliseconds after which the popup will close; + when omitted |popup_close()| must be used. + moved "cell": close the popup if the cursor moved at least + one screen cell; "word" allows for moving within + ||, "WORD" allows for moving within ||, + a list with two numbers specifies the start and end + column + filter a callback that can filter typed characters, see + |popup-filter| + callback a callback to be used when the popup closes, e.g. when + using |popup_filter_menu()|, see |popup-callback|. + +Depending on the "zindex" the popup goes under or above other popups. The +completion menu (|popup-menu|) has zindex 100. For messages that occur for a +short time the suggestion is to use zindex 1000. + +By default text wraps, which causes a line in {lines} to occupy more than one +screen line. When "wrap" is FALSE then the text outside of the popup or +outside of the Vim window will not be displayed, thus truncated. + + +POPUP TEXT PROPERTIES *popup-props* + +These are similar to the third argument of |prop_add()|, but not exactly the +same, since they only apply to one line. + col starting column, counted in bytes, use one for the + first column. + length length of text in bytes; can be zero + end_col column just after the text; not used when "length" is + present; when {col} and "end_col" are equal, this is a + zero-width text property + id user defined ID for the property; when omitted zero is + used + type name of the text property type, as added with + |prop_type_add()| + transparent do not show these characters, show the text under it; + if there is an border character to the right or below + it will be made transparent as well + + +POPUP FILTER *popup-filter* + +A callback that gets any typed keys while a popup is displayed. It can return +TRUE to indicate the key has been handled and is to be discarded, or FALSE to +let Vim handle the key as usual in the current state. + +The filter function is called with two arguments: the ID of the popup and the +key. + +Some common key actions: + Esc close the popup + cursor keys select another entry + Tab accept current suggestion + +Vim provides standard filters |popup_filter_menu()| and +|popup_filter_yesno()|. + + +POPUP CALLBACK *popup-callback* + +A callback that is invoked when the popup closes. Used by +|popup_filter_menu()|. Invoked with two arguments: the ID of the popup and +the result, which would usually be an index in the popup lines, or whatever +the filter wants to pass. + +============================================================================== +3. Examples *popup-examples* + +TODO + +Prompt the user to press y/Y or n/N: > + + func MyDialogHandler(id, result) + if a:result + " ... 'y' or 'Y' was pressed + endif + endfunc + + call popup_show([{'text': 'Continue? y/n'}], { + \ 'filter': 'popup_filter_yesno', + \ 'callback': 'MyDialogHandler', + \ }) +< + + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/src/version.c b/src/version.c --- a/src/version.c +++ b/src/version.c @@ -768,6 +768,8 @@ static char *(features[]) = static int included_patches[] = { /* Add new patch number below this line */ /**/ + 1329, +/**/ 1328, /**/ 1327,