Mercurial > vim

comparison runtime/doc/popup.txt @ 17863:08f1dd29550e v8.1.1928

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.1.1928: popup windows don't move with the text when making changes Commit: https://github.com/vim/vim/commit/12034e22dd80cf533ac1c681be521ab299383f63 Author: Bram Moolenaar <Bram@vim.org> Date: Sun Aug 25 22:25:02 2019 +0200 patch 8.1.1928: popup windows don't move with the text when making changes Problem: Popup windows don't move with the text when making changes. Solution: Add the 'textprop" property to the popup window options, position the popup relative to a text property. (closes #4560) No tests yet.
author Bram Moolenaar <Bram@vim.org>
date Sun, 25 Aug 2019 22:30:03 +0200
parents e8a7029efa40
children cc953757ed2a
comparison
equal deleted inserted replaced
17862:debebb1dcef1 17863:08f1dd29550e
14 2. Functions |popup-functions| 14 2. Functions |popup-functions|
15 Details |popup-function-details| 15 Details |popup-function-details|
16 3. Usage |popup-usage| 16 3. Usage |popup-usage|
17 popup_create() arguments |popup_create-arguments| 17 popup_create() arguments |popup_create-arguments|
18 Popup text properties |popup-props| 18 Popup text properties |popup-props|
19 Position popup with textprop |popup-textprop-pos|
19 Popup filter |popup-filter| 20 Popup filter |popup-filter|
20 Popup callback |popup-callback| 21 Popup callback |popup-callback|
21 Popup scrollbar |popup-scrollbar| 22 Popup scrollbar |popup-scrollbar|
22 Popup mask |popup-mask| 23 Popup mask |popup-mask|
23 4. Examples |popup-examples| 24 4. Examples |popup-examples|
322 when set. 323 when set.
323 324
324 "tabpage" will be -1 for a global popup, zero for a popup on 325 "tabpage" will be -1 for a global popup, zero for a popup on
325 the current tabpage and a positive number for a popup on 326 the current tabpage and a positive number for a popup on
326 another tabpage. 327 another tabpage.
328
329 "textprop", "textpropid" and "textpropwin" are only present
330 when "textprop" was set.
327 331
328 If popup window {id} is not found an empty Dict is returned. 332 If popup window {id} is not found an empty Dict is returned.
329 333
330 334
331 popup_getpos({id}) *popup_getpos()* 335 popup_getpos({id}) *popup_getpos()*
505 line Screen line where to position the popup. Can use a 509 line Screen line where to position the popup. Can use a
506 number or "cursor", "cursor+1" or "cursor-1" to use 510 number or "cursor", "cursor+1" or "cursor-1" to use
507 the line of the cursor and add or subtract a number of 511 the line of the cursor and add or subtract a number of
508 lines. If omitted the popup is vertically centered. 512 lines. If omitted the popup is vertically centered.
509 The first line is 1. 513 The first line is 1.
514 When using "textprop" the number is relative to the
515 text property and can be negative.
510 col Screen column where to position the popup. Can use a 516 col Screen column where to position the popup. Can use a
511 number or "cursor" to use the column of the cursor, 517 number or "cursor" to use the column of the cursor,
512 "cursor+9" or "cursor-9" to add or subtract a number 518 "cursor+9" or "cursor-9" to add or subtract a number
513 of columns. If omitted the popup is horizontally 519 of columns. If omitted the popup is horizontally
514 centered. The first column is 1. 520 centered. The first column is 1.
521 When using "textprop" the number is relative to the
522 text property and can be negative.
515 pos "topleft", "topright", "botleft" or "botright": 523 pos "topleft", "topright", "botleft" or "botright":
516 defines what corner of the popup "line" and "col" are 524 defines what corner of the popup "line" and "col" are
517 used for. When not set "topleft" is used. 525 used for. When not set "topleft" is used.
518 Alternatively "center" can be used to position the 526 Alternatively "center" can be used to position the
519 popup in the center of the Vim window, in which case 527 popup in the center of the Vim window, in which case
520 "line" and "col" are ignored. 528 "line" and "col" are ignored.
529 textprop When present the popup is positioned next to a text
530 property with this name and will move when the text
531 property moves. Use an empty string to remove. See
532 |popup-textprop-pos|.
533 textpropwin What window to search for the text property. When
534 omitted or invalid the current window is used.
535 textpropid Used to identify the text property when "textprop" is
536 present. Use zero to reset.
521 fixed When FALSE (the default), and: 537 fixed When FALSE (the default), and:
522 - "pos" is "botleft" or "topleft", and 538 - "pos" is "botleft" or "topleft", and
523 - "wrap" is off, and 539 - "wrap" is off, and
524 - the popup would be truncated at the right edge of 540 - the popup would be truncated at the right edge of
525 the screen, then 541 the screen, then
668 used 684 used
669 type name of the text property type, as added with 685 type name of the text property type, as added with
670 |prop_type_add()| 686 |prop_type_add()|
671 687
672 688
689 POSITION POPUP WITH TEXTPROP *popup-textprop-pos*
690
691 Positioning a popup next to a text property causes the popup to move when text
692 is inserted or deleted. The popup functions like a tooltip.
693
694 These steps are needed to make this work:
695
696 - Define a text property type, it defines the name. >
697 call prop_type_add('popupMarker', {})
698
699 - Place a text property at the desired text: >
700 let lnum = {line of the text}
701 let col = {start column of the text}
702 let len = {length of the text}
703 let propId = {arbitrary but unique number}
704 call prop_add(lnum, col, #{
705 \ length: len,
706 \ type: 'popupMarker',
707 \ id: propId,
708 \ })
709
710 - Create a popup: >
711 let winid = popup_create('the text', #{
712 \ pos: 'botleft',
713 \ textprop: 'popupMarker',
714 \ textpropid: propId,
715 \ border: [],
716 \ padding: [0,1,0,1],
717 \ close: 'click',
718 \ })
719
720 By default the popup is positioned at the corner of the text, opposite of the
721 "pos" specified for the popup. Thus when the popup uses "botleft", the
722 bottom-left corner of the popup is positioned next to the top-right corner of
723 the text property:
724 +----------+
725 | the text |
726 +----------+
727 just some PROPERTY as an example
728
729 Here the text property is on "PROPERTY". Move the popup to the left by
730 passing a negative "col" value to popup_create(). With "col: -5" you get:
731
732 +----------+
733 | the text |
734 +----------+
735 just some PROPERTY as an example
736
737 If the text property moves out of view then the popup will be hidden.
738 If the window for which the popup was defined is closed, the popup is closed.
739
740 If the popup cannot fit in the desired position, it may show at a nearby
741 position.
742
743 Some hints:
744 - To avoid collision with other plugins the text property type name has to be
745 unique. You can also use the "bufnr" item to make it local to a buffer.
746 - You can leave out the text property ID if there is only ever one text
747 property visible.
748 - The popup may be in the way of what the user is doing, making it close with
749 a click, as in the example above, helps for that.
750 - If the text property is removed the popup is closed. Use something like
751 this: >
752 call prop_remove(#{type: 'popupMarker', id: propId})
753
754
673 POPUP FILTER *popup-filter* 755 POPUP FILTER *popup-filter*
674 756
675 A callback that gets any typed keys while a popup is displayed. The filter is 757 A callback that gets any typed keys while a popup is displayed. The filter is
676 not invoked when the popup is hidden. 758 not invoked when the popup is hidden.
677 759