Skip to content

Update popup.{txt,jax} #2815

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
h-east merged 1 commit into from
Oct 7, 2026
Merged

Update popup.{txt,jax} #2815

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 63 additions & 58 deletions doc/popup.jax
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
*popup.txt* For Vim バージョン 9.2. Last change: 2026 Jul 29
*popup.txt* For Vim バージョン 9.2. Last change: 2026 Sep 30


VIM リファレンスマニュアル by Bram Moolenaar
Expand Down Expand Up @@ -435,6 +435,11 @@ popup_getoptions({id}) *popup_getoptions()*
"textprop", "textpropid" および "textpropwin" は、"textprop"
が設定されている場合にのみ与えられる。

"image" エントリは、|image_info()| が返すものと同じフィールド
を持つ辞書である。Note 画像がポップアップによって直接作成され
た場合、"id" フィールドは含まれないことに注意。|popup-image|を
参照。

ポップアップウィンドウ {id} が見つからない場合は空の辞書が返さ
れる。

Expand Down Expand Up @@ -620,6 +625,7 @@ popup_setoptions({id}, {options}) *popup_setoptions()*
firstline
flip
highlight
image
mapping
mask
moved
Expand Down Expand Up @@ -808,18 +814,9 @@ popup_create() に渡す。
れ、部分的に透明になる。'termguicolors' を設定する必要
がある。
|popup-opacity| も参照。
image ポップアップ内にレンダリングする生の RGB または RGBA
ピクセルバッファを記述する辞書。設定すると、ポップアッ
プは画像のピクセル寸法からセルボックスのサイズを自動的
に調整するため、"minwidth" / "minheight" / "maxwidth"
/ "maxheight" を手動で設定する必要はない。キーは以下:
data バイトの |Blob|。長さは幅 x 高さ x 3 (RGB)
または幅 x 高さ x 4 (RGBA) と等しくなけれ
ばならない。
width ピクセル単位の画像の幅。
height ピクセル単位の画像の高さ。
以前に設定した画像を削除するには、空の辞書を使用する。
|popup-image| を参照。
image 画像を表示するための辞書である。必須フィールドについて
は |image_add()| を参照。あるいは "id" フィールドのみ
を指定することも可能である。|popup-image| を参照。
padding ポップアップの上/右/下/左のパディングを定義する数値の
リスト(CSSと同様)。空のリストは、すべて 1 のパディング
を使用する。パディングは、テキストをボーダーの内側で囲
Expand Down Expand Up @@ -1168,42 +1165,59 @@ Note "x" はポップアップを閉じる通常の方法である。Escを使
4隅を透明にするには:
[[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]

☆ポップアップの画像 *popup-image*

ポップアップウィンドウは、|popup_create()| または |popup_setoptions()| に
"image" 辞書を渡すことで、テキストの代わり (またはテキストの上) に画像を表示で
きる。呼び出し元は既にデコードされた生のピクセルバッファを提供し、Vim は実行時
に利用可能なバックエンドを通してそれを出力する。

sixel sixel 対応端末における DEC sixel DCS シーケンス。|+image_sixel|。
自動的に検出される。また、sixel に起因する端末のスクロールを防ぐた
め、バッファは画面端の 1 セル上で切り詰められる。
kitty kitty グラフィックスプロトコル APC シーケンスは、対応する端末
(kitty、ghostty、WezTerm、Konsole など) で使用できる。
|+image_kitty|。
端末へのアクティブな問い合わせによって検出される。
GDI MS-Windows GUI 上の GUI キャンバスに StretchDIBits を配置する。
|+image_gdi|。
Cairo GTK GUI 上の cairo_image_surface_t に合成する (GTK 2 および GTK 3
に対応)。 |+image_cairo|。
GDK GPU に画像をアップロードしてレンダリングを高速化する GdkTexture
を使用する (GTK 4 のみ有効)。|+image_gdk|

Vim 自体は libpng、libjpeg、libwebp、または画像デコーダーにリンクしない。
フォーマットのデコードは呼び出し元に任されており、呼び出し元はファイルを任意の
外部ツール (GraphicsMagick、ImageMagick、ffmpeg、カスタムコンバーターなど) に
パイプで渡し、結果として得られたバイト列を |Blob| で渡すことができる。

"image" 辞書は以下を受け入れる:
data バイト単位の |Blob|。長さは、RGB の場合は幅 x 高さ x 3、
RGBA の場合は幅 x 高さ x 4 以上である必要がある。RGBA バッファ
は、ポップアップの背景画像にアルファ合成される。
width ピクセル単位の画像の幅。
height ピクセル単位の画像の高さ。

ポップアップのセルボックスはピクセル寸法と端末 / GUI セルのメトリクスから生成
されるため、呼び出し元は通常 "minwidth" / "minheight" / "maxwidth" /
"maxheight" を設定する必要はない。
☆ポップアップの画像 *image* *popup-image*

Vim は、端末と GUI の両方で画像を表示する機能を備えている。この機能を使用する
には、pixman ライブラリとのリンクが必要である。同ライブラリは、Unix 系 OS では
パッケージマネージャーから、MS-Windows では vcpkg からインストールできる。画像
表示がサポートされているかどうかは、|+image| および |+image_popup| を確認する
ことで確かめられる。

ポップアップウィンドウには、画像を表示させることもできる。そのためには、辞書を
含む "image" という名前のフィールドを |popup_create()| または
|popup_setoptions()| に渡す。この辞書には、|image_add()| と同じフィールドを含
めるか、あるいは "id" フィールドを使用して ID 経由で画像を参照させることができ
る。"id" フィールドが優先的に扱われる。|image_add()|、|image_discard()|、
|image_info()| を参照。

ポップアップウィンドウによって画像が直接作成される場合 (例えば、"id" が使用さ
れていない場合)、その画像は内部的なものとみなされ、他の場所から参照することは
できない。

ポップアップウィンドウに以前設定した画像を解除するには、空の辞書を渡す: >
call popup_setoptions(winid, #{image: {}})
<
*image-backends*
すべてのプラットフォームでサポートされている端末の画像プロトコルは 2 種類ある。
使用するプロトコルは、'imageprotocol' オプションで選択する。

sixel sixel プロトコルを使用して画像を表示する。
kitty kitty グラフィックスプロトコルを使用する。sixel よりもはるかに高い
パフォーマンスを発揮するため、使用可能な場合は、端末でこのプロトコ
ルを使用することが推奨される。

GUI を使用する場合、Vim の GTK4、GTK3、および Win32 版がサポートされている。

現在使用されている画像バックエンドを確認するには、|v:imagebackend| 変数を使用
する。

*image-options*
RGBA バッファを渡す際、Vim はそれがエンディアンに依存せず、かつ non alpha
pre-multiplied 形式であることを想定している。RGB 画像の場合、各ピクセルは正確
に 3 バイトである必要があり、パディングバイトは Vim ではサポートされていない。

画像を含むポップアップのサイズは、画像の寸法および端末や GUI のセルサイズに基
づいて自動的に計算される。ただし、"minwidth"、"minheight"、"maxwidth"、
"maxheight" の各フィールドを使用し、この設定を上書きすることも可能である。

画像は縮小されない。ポップアップウィンドウがその中の画像よりも小さい場合、画像
は切り抜かれる。

*image-animation*
|popup_setoptions()| を使用すると、実行時にポップアップウィンドウの画像を変更
できる。新しい画像が既存の画像と同じ形式、幅、高さである場合、既存の画像がその
場で書き換えられる。これは、|timer| を使用したフレーム単位のアニメーションを行
うのに十分なパフォーマンスを備えている。

エディタの実際の背景にきれいにブレンドする必要がある RGBA バッファの場合、スク
リプトは |getbgcolor()| を呼び出して現在の背景色を [r、g、b] として取得し、そ
Expand All @@ -1230,15 +1244,6 @@ Vim 自体は libpng、libjpeg、libwebp、または画像デコーダーにリ
\ line: 1, col: 1, border: [], padding: [0, 0, 0, 0],
\ })

画像は、|popup_setoptions()| を使用して実行時に置き換えることができる。新しい
バッファの幅と高さが現在のバッファと同じ場合、ピクセルがその場で交換される。こ
れは、|timer| からフレームごとのアニメーションを駆動するのに十分な速さである。
|popup_getoptions()| は同じ辞書を返す。"data" エントリは、ポップアップの内部
バッファとは独立した新しい blob のコピーである。

以前に設定した画像を削除するには、空の辞書を渡す: >
call popup_setoptions(winid, #{image: {}})

==============================================================================
4. 例 *popup-examples*

Expand Down
124 changes: 64 additions & 60 deletions en/popup.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
*popup.txt* For Vim version 9.2. Last change: 2026 Jul 29
*popup.txt* For Vim version 9.2. Last change: 2026 Sep 30


VIM REFERENCE MANUAL by Bram Moolenaar
Expand Down Expand Up @@ -427,6 +427,11 @@ popup_getoptions({id}) *popup_getoptions()*
"textprop", "textpropid" and "textpropwin" are only present
when "textprop" was set.

The "image" entry is a dictionary with the same fields as
returned by |image_info()|. Note that if the image is created
directly by the popup, the "id" field will not be present, see
|popup-image|.

If popup window {id} is not found an empty Dict is returned.

Can also be used as a |method|: >
Expand Down Expand Up @@ -609,6 +614,7 @@ popup_setoptions({id}, {options}) *popup_setoptions()*
firstline
flip
highlight
image
mapping
mask
moved
Expand Down Expand Up @@ -801,18 +807,9 @@ The second argument of |popup_create()| is a dictionary with options:
underlying text, making it partially transparent.
Requires 'termguicolors' to be set.
Also see |popup-opacity|.
image Dictionary describing a raw RGB or RGBA pixel buffer
to render inside the popup. When set the popup
auto-sizes its cell box from the image's pixel
dimensions, so "minwidth" / "minheight" / "maxwidth" /
"maxheight" do not need to be set by hand. Keys:
data |Blob| of bytes; length must equal
width*height*3 (RGB) or width*height*4
(RGBA).
width image width in pixels.
height image height in pixels.
Use an empty dictionary to remove a previously set
image. See |popup-image|.
image Dictionary for displaying an image. See |image_add()|
for required fields, or you can provide the "id" field
only, see |popup-image|.
padding List with numbers, defining the padding
above/right/below/left of the popup (similar to CSS).
An empty list uses a padding of 1 all around. The
Expand Down Expand Up @@ -1170,44 +1167,60 @@ For example, to make the last 10 columns of the last line transparent:
To make the four corners transparent:
[[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]

POPUP IMAGE *popup-image*

A popup window can render an image instead of (or on top of) text by passing
an "image" dictionary to |popup_create()| or |popup_setoptions()|. The caller
supplies an already-decoded raw pixel buffer and Vim emits it through
whichever backend is available at runtime:

sixel DEC sixel DCS sequence on a sixel-capable terminal.
|+image_sixel|. Detected automatically; the buffer is also
cropped one cell above the screen edge to avoid sixel-induced
terminal scrolling.
kitty kitty graphics protocol APC sequence on terminals that support it
(kitty, ghostty, WezTerm, Konsole, ...). |+image_kitty|.
Detected by actively querying the terminal.
GDI StretchDIBits onto the GUI canvas on the MS-Windows GUI.
|+image_gdi|.
Cairo composite onto a cairo_image_surface_t on the GTK GUI
(covers GTK 2 and GTK 3). |+image_cairo|.
GDK Use GdkTexture, which uploads the image onto the GPU for faster
rendering (only for GTK 4). |+image_gdk|

Vim itself does NOT link against libpng, libjpeg, libwebp or any image
decoder. Format decoding is left to the caller, who can pipe the file through
any external tool (GraphicsMagick, ImageMagick, ffmpeg, a custom converter,
...) and pass the resulting bytes via a |Blob|.

The "image" dictionary accepts:
data |Blob| of bytes. Length must equal width*height*3 for RGB,
or width*height*4 for RGBA. RGBA buffers are alpha-composited
over the popup's background.
width image width in pixels.
height image height in pixels.

The popup's cell box is derived from the pixel dimensions and the terminal /
GUI cell metrics, so the caller does not normally have to set "minwidth" /
"minheight" / "maxwidth" / "maxheight".

For RGBA buffers that need to blend cleanly into the editor's actual backdrop
POPUP IMAGE *image* *popup-image*

Vim is capable of displaying graphical images, in both the terminal and GUI.
To do this, it must link with the pixman library, which you may install via
your package manager on Unix, or via vcpkg on MS-Windows. You may see if
images are supported by checking |+image| and |+image_popup|.

A popup window may additionally render an image. To do this, pass a field
named "image" containing a dictionary to |popup_create()| or
|popup_setoptions()|. The dictionary may either have the same fields as in
|image_add()|, or it may reference an image via its ID using the "id" field.
The "id" field is prioritized first, see |image_add()|, |image_discard()|, and
|image_info()|.

When an image is directly created by a popup window (e.g. "id" is not used),
then it is considered internal and can not be referenced anywhere else.

To unset a previously set image from a popup window pass an empty dictionary: >
call popup_setoptions(winid, #{image: {}})
<
*image-backends*
There are two terminal image protocols supported on all platforms. The
protocol to use is chosen using the 'imageprotocol' option:

sixel Uses the sixel protocol to display images.
kitty Uses the kitty graphics protocol. This is the recommended
protocol to use in the terminal if it is available, as it is much
more performant than sixel.

When using the GUI, the GTK4, GTK3, and Win32 versions of Vim are supported.

To see what image backend is currently being used, use the |v:imagebackend|
variable.

*image-options*
When passing an RGBA buffer, Vim expects it to be endian independent and non
alpha pre-multiplied. For RGB images, each pixel should be exactly 3 bytes,
a padding byte is not supported by Vim.

The dimensions of a popup containing an image are automatically calculated
based on the image dimensions and terminal/GUI cell size. However, you may
override it using the "minwidth", "minheight", "maxwidth", and "maxheight"
fields.

Images are not scaled, if a popup window is smaller than the image it
contains, then the image will be cropped instead.

*image-animation*
The image of a popup window can be changed at runtime using
|popup_setoptions()|. When the new image has the same format, width, and
height as the existing image, the existing image will be modified in place.
This is performant enough for frame-by-frame animation, using a |timer|.

For RGBA buffers that need to blend cleanly into the editor's actual backdrop,
the script can call |getbgcolor()| to obtain the current background colour as
[r, g, b] and pre-composite anti-aliased edges against it.

Expand All @@ -1232,15 +1245,6 @@ raw RGB bytes: >
\ line: 1, col: 1, border: [], padding: [0, 0, 0, 0],
\ })

The image can be replaced at runtime via |popup_setoptions()|. When the new
buffer has the same width and height as the current one the pixels are swapped
in place, which is fast enough to drive frame-by-frame animation from a
|timer|. |popup_getoptions()| returns the same dictionary back; the "data"
entry is a fresh blob copy independent of the popup's internal buffer.

To remove a previously set image pass an empty dictionary: >
call popup_setoptions(winid, #{image: {}})

==============================================================================
4. Examples *popup-examples*

Expand Down
Loading