Merge pull request #2627 from h-east/update-popup

Update popup.{txt,jax}

Author: h-east

doc/popup.jax

@@ -1,4 +1,4 @@
-*popup.txt*	For Vim バージョン 9.2.  Last change: 2026 May 01
+*popup.txt*	For Vim バージョン 9.2.  Last change: 2026 May 10
 
 
 		  VIM リファレンスマニュアル	by Bram Moolenaar
@@ -721,6 +721,15 @@ popup_create() に渡す。
 			定された場合に使用される。
 	textpropid	"textprop" が指定された場合にテキストプロパティを識別
 			するために使用される。0 を使用してリセットする。
+	clipwindow	"textprop" が設定されている場合にのみ使用される。TRUE
+			の場合、ポップアップはテキストプロパティを含むウィンド
+			ウ内に留まる。テキストプロパティがウィンドウの上端、下
+			端、左端、または右端を超えてスクロールすると、ポップ
+			アップはその端で切り取られ、ウィンドウの外に描画されな
+			い。テキストプロパティがウィンドウの外にスクロールする
+			と、ポップアップは非表示になる。
+			デフォルトは FALSE である。
+			|popup-clipwindow| を参照。
 	fixed		FALSE (デフォルト)の場合は:
 			 - "pos" は "botleft" または "topleft" で、
 			 - ポップアップは画面の右端で切り捨てられ、
@@ -945,6 +954,33 @@ popup_create() に渡す。
 
 ポップアップが目的の位置に収まらない場合、近くの位置に表示される場合がある。
 
+
+							*popup-clipwindow*
+☆テキストプロパティのポップアップをホストウィンドウ内に収める
+
+分割ウィンドウ内のテキストプロパティにポップアップを固定すると、ポップアップは
+デフォルトでは画面全体を基準に描画され、テキストプロパティを含むウィンドウ
+("ホストウィンドウ") の端を超えて広がる場合がある。"clipwindow" を TRUE に設定
+すると、ポップアップはウィンドウのコンテンツ領域内に収まる。ウィンドウからはみ
+出したポップアップの部分は切り取られ、テキストプロパティがウィンドウの端を完全
+に超えてスクロールすると、ポップアップは非表示になる。
+
+例: カーソルの上に固定された背の高いポップアップで、分割ウィンドウの下の領域に
+は決してはみ出さないもの: >
+	call popup_create(body, #{
+		\ textprop: 'marker',
+		\ textpropid: id,
+		\ pos: 'topleft',
+		\ line: -1, col: 0,
+		\ posinvert: v:false,
+		\ clipwindow: v:true,
+		\ })
+<
+"posinvert" をデフォルト値 (TRUE) のままにしておくと、十分なスペースがない場合
+にポップアップがテキストプロパティの反対側へ反転される可能性がある。指定された
+側を維持し、"clipwindow" ではみ出した部分をクリップするには、これを FALSE に設
+定する。
+
 いくつかのヒント:
 - 他のプラグインとの衝突を避けるために、テキストプロパティタイプ名は一意である
   必要がある。"bufnr" 項目を使用して、バッファに対してローカルにすることもでき

en/popup.txt

@@ -1,4 +1,4 @@
-*popup.txt*	For Vim version 9.2.  Last change: 2026 May 01
+*popup.txt*	For Vim version 9.2.  Last change: 2026 May 10
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -712,6 +712,15 @@ The second argument of |popup_create()| is a dictionary with options:
 			when "textprop" is present.
 	textpropid	Used to identify the text property when "textprop" is
 			present.  Use zero to reset.
+	clipwindow	Only used when "textprop" is set.  When TRUE the popup
+			is kept within the window containing the text
+			property: if the text property scrolls past that
+			window's top, bottom, left or right edge, the popup
+			is clipped at that edge instead of being drawn
+			outside it.  Once the text property has scrolled out
+			of the window the popup is hidden.
+			Default FALSE.
+			See |popup-clipwindow|.
 	fixed		When FALSE (the default), and:
 			 - "pos" is "botleft" or "topleft", and
 			 - the popup would be truncated at the right edge of
@@ -949,6 +958,31 @@ If the window for which the popup was defined is closed, the popup is closed.
 If the popup cannot fit in the desired position, it may show at a nearby
 position.
 
+
+CLIP TEXTPROP POPUP TO HOST WINDOW			*popup-clipwindow*
+
+When the popup is anchored to a text property in a split window, the popup is
+by default drawn relative to the whole screen and may extend past the edges of
+the window that contains the text property (the "host window").  Setting
+"clipwindow" to TRUE keeps the popup within window's content area:
+parts of the popup that fall outside the window are clipped, and the popup is
+hidden once the text property has scrolled entirely past one of the edges.
+
+Example: a tall popup anchored above the cursor that should never spill into
+the window below the split: >
+	call popup_create(body, #{
+		\ textprop: 'marker',
+		\ textpropid: id,
+		\ pos: 'topleft',
+		\ line: -1, col: 0,
+		\ posinvert: v:false,
+		\ clipwindow: v:true,
+		\ })
+<
+With "posinvert" left at its default (TRUE) the popup may be flipped to the
+opposite side of the text property when there is no room; set it to FALSE to
+keep the requested side and rely on "clipwindow" to clip the overflow.
+
 Some hints:
 - To avoid collision with other plugins the text property type name has to be
   unique.  You can also use the "bufnr" item to make it local to a buffer.