ポップアップウィンドウのサポート

*popup.txt*    For Vim バージョン 8.1.  Last change: 2019 Nov 17


		  VIMリファレンスマニュアル    by Bram Moolenaar

フローティングウィンドウにテキストを表示します。

{|+textprop| 機能が無效でコンパイルされたときは使用できません}

1. 前書き

ここではポップアップウィンドウ、つまり通常のウィンドウの上に表示され、プラグインの管理下にあるテキストについて話しをします。通常のウィンドウのやうにポップアップウィンドウのテキストを編輯することはできません。

ポップアップウィンドウは、次のやうな用途に使用できます:

• コマンドラインを上書きせずに簡單にメッセージを表示する
• ユーザーにダイアログを表示する
• タイプ中にコンテキスト情報を表示する
• 自動補完のための追加情報を與へる

ポップアップウィンドウのテキストは |text-properties| で色を付けることができます。構文ハイライトを使用することもできます。

デフォルトの色は "Pmenu" です。他の何かを好むならば、"highlight" 引數または ’wincolor’ オプションを使用してください。例:

hi MyPopupColor ctermbg=lightblue guibg=lightblue
call setwinvar(winid, '&wincolor', 'MyPopupColor')

’hlsearch’ ハイライトはポップアップウィンドウに表示されません。

ポップアップウィンドウは他のウィンドウと同樣にウィンドウ ID を持ちますが、動作が異なります。サイズは Vim ウィンドウ全體に及ぶことがあり、それは他のウィンドウと重なります。ポップアップウィンドウも互ひに重なり合ふことがあります。"zindex" プロパティは、何の上に何があるかを指定します。

ポップアップウィンドウにはバッファがあり、そのバッファは常にポップアップウィンドウに關聯付けられてゐます。このウィンドウはノーマル、ビジュアル、插入モードにはできません。キーボードフォーカスは得られません。‘setbufline()‘ のやうな函數を使つてバッファ內のテキストを變更することができます。このウィンドウとバッファは通常のウィンドウとバッファの振る舞ひと比較して、たくさんの違ひがあります。|popup-buffer| を參照してください。

これがあなたが探してゐるものではない場合は、他のポップアップ機能をチェックしてください。

• ポップアップメニューは |popup-menu| を參照してください。
• バルーンは |balloon-eval| を參照してください。

ウィンドウの位置とサイズ

ウィンドウの高さは、通常、バッファ內の折り返しの行數と同じです。"maxheight" プロパティで制限することができます。高さを增やすために空の行を使ふか、または "minheight" プロパティを使ふことができます。

ウィンドウの幅は、通常、バッファ內の最長の行と同じです。"maxwidth" プロパティで制限することができます。スペースを使つて幅を廣げるか、または "minwidth" プロパティを使ふことができます。

デフォルトでは ’wrap’ オプションが設定されてゐるのでテキストは消えません。または、十分なスペースがない場合、ウィンドウは左に移動してテキストをさらに表示します。右寄せの場合、ウィンドウは右に移動してテキストをさらに表示します。この移動については "fixed" プロパティで無效にすることができます。

Vim は指定した場所にポップアップを表示しようとします。場合によつては、ポップアップが Vim のウィンドウの外側に出ると、他の近い場所に表示されます。例へば、‘popup_atcursor()‘ を使用すると、ポップアップは現在のカーソル位置のすぐ上に表示されますが、カーソルが Vim のウィンドウの最上部に近い場合は、カーソル位置の下に配置されます。

Ex コマンドの出力のために畫面がスクロールアップすると、ポップアップも移動するので、ポップアップは出力を隱しません。

現在のカーソル位置はポップアップウィンドウの下にあつても表示されます。この方法では、テキストが表示されてゐない場合でも、その場所を確認することができます。

ポップアップウィンドウを閉ぢる

通常、ポップアップウィンドウを生成したプラグインは、これを閉ぢることもまた擔當します。もしもプラグインがどういふわけかハングアップしてしまつたなら、次のやうにしてポップアップウィンドウのすべてを閉ぢることができます:

call popup_clear()

通知のやうなポップアップは一定時閒後に閉ぢます。これは ‘popup_create()‘ の "time" プロパティで設定することができます。

一方で、ポップアップは右上角の X をクリックしたり、ポップアップの內側のどこかをクリックすることによつて閉ぢることもできます。このためには "close" プロパティを有效にする必要があります。既定では通知に設定されてゐます。{譯注: "close" の値が "none" になつてゐる}

ポップアップバッファとウィンドウ

もしもポップアップ函數がテキストからポップアップを作成するために呼ばれた場合は、ポップアップウィンドウのテキストとテキストプロパティを保持するための新しいバッファが作成されます。バッファは常にポップアップウィンドウに關聯付けられてゐて、操作は制限されてゐます:

• 無名バッファ
• ’buftype’ は "popup"
• ’swapfile’ は off
• ’bufhidden’ は "hide"
• ’buflisted’ は off
• ’undolevels’ は -1: アンドゥはできません
• 他のすべてのバッファローカルおよびウィンドウローカルオプションは Vim のデフォルト値に設定されてゐます

具體的に言及されたオプションを變更することは可能ですが、何かが壞れてしまふ可能性があるので、そのままにしておくはうが望ましいでせう。

ウィンドウにはカーソル位置がありますが、カーソルは表示されません。實際、下にあるウィンドウのカーソルは、ポップアップを覗くやうに表示されるため、どこにあるかを確認できます。

ポップアップウィンドウとバッファのコンテキストでコマンドを實行するには ‘win_execute()‘ を使用してください。例:

call win_execute(winid, 'syntax enable')

オプションは ‘setwinvar()‘ を使つてウィンドウ上で設定することができます。例:

call setwinvar(winid, '&wrap', 0)

そしてオプションは ‘setbufvar()‘ を使つてバッファに設定することができます。例:

call setbufvar(winbufnr(winid), '&filetype', 'java')

":setlocal" コマンドを ‘win_execute()‘ で使用することもできます。

2. 函數

ポップアップウィンドウを作成:

ポップアップウィンドウの操作:

ポップアップウィンドウを閉ぢる:

フィルタ函數:

その他:

詳細

popup_atcursor({what}, {options})

カーソルの上に {what} を表示して、カーソルが移動したら閉ぢます。これは次のやうに動作します:

call popup_create({what}, {
        \ 'pos': 'botleft',
        \ 'line': 'cursor-1',
        \ 'col': 'cursor',
        \ 'moved': 'WORD',
        \ })

プロパティを變更するには {options} を使用します。もしも "pos" が "topleft" として渡されたなら、"line" へのデフォルトは "cursor+1" になります。

|method| としても使用できます:

GetText()->popup_atcursor({})

popup_beval({what}, {options})

’ballooneval’ からの位置 {what} を表示して、マウスが移動した時に閉ぢます。これは次のやうに動作します:

let pos = screenpos(v:beval_winnr, v:beval_lnum, v:beval_col)
call popup_create({what}, #{
      \ pos: 'botleft',
      \ line: pos.row - 1,
      \ col: pos.col,
      \ mousemoved: 'WORD',
      \ })

特性を變更するには {options} を使ひます。例については |popup_beval_example| を參照してください。

|method| としても使用できます:

GetText()->popup_beval({})

popup_clear()

不作法にふるまふプラグインに對する緊急の解決策: グローバルポップアップとカレントタブポップアップをすべて閉ぢます。

popup_close({id} [, {result}])

ポップアップ {id} を閉ぢます。ウィンドウと關聯するバッファは削除されます。

ポップアップがコールバックを持つ場合は、ポップアップウィンドウが削除される直前に呼び出されます。オプションの {result} が存在する場合、それはコールバックの第 2 引數として渡されます。さうでなければ、ゼロがコールバックに渡されます。

|method| としても使用できます:

GetPopup()->popup_close()

popup_create({what}, {options})

次のどれかである {what} を見せるポップアップウィンドウを開きます:

• バッファ番號
• 文字列
• 文字列のリスト
• テキストプロパティを持つテキスト行のリスト

{what} がバッファ番號ではない場合、バッファは ’buftype’ オプションに "popup" を設定した狀態で作成されます。ひとたびポップアップが閉ぢられると、このバッファは消去されるでせう。

{options} は多くのエントリがある辭書です。詳細は |popup_create-arguments| を參照してください。

ウィンドウ ID を返します。これは他のポップアップ函數で使用することができます。ウィンドウ內のバッファの番號を取得するには ‘winbufnr()‘ を使用してください:

let winid = popup_create('hello', {})
let bufnr = winbufnr(winid)
call setbufline(bufnr, 2, 'second line')

失敗した場合はゼロが返されます。

|method| としても使用できます:

GetText()->popup_create({})

popup_dialog({what}, {options})

|popup_create()| と同じですが、これらのデフォルトのオプションになります:

call popup_create({what}, #{
        \ pos: 'center',
        \ zindex: 200,
        \ drag: 1,
        \ border: [],
        \ padding: [],
        \ mapping: 0,
        \})

プロパティを變更するには {options} を使用します。例: 値 ’popup_filter_yesno’ を持つ ’filter’ オプションを追加します。例:

call popup_create('do you want to quit (Yes/no)?', #{
        \ filter: 'popup_filter_yesno',
        \ callback: 'QuitCallback',
        \ })

デフォルトではダイアログはドラッグすることができるので、必要であればその下のテキストを讀むことができます。

|method| としても使用できます:

GetText()->popup_dialog({})

popup_filter_menu({id}, {key})

ポップアップに使用できるフィルタ。これらのキーを使用することができます:

j <Down>	下の項目を選擇する
k <Up>	上の項目を選擇する
<Space> <Enter>	現在の選擇を受け入れる
x Esc CTRL-C	メニューをキャンセルする

他のキーは無視されます。

行をハイライトするためにマッチがセットされます。|popup_menu()| を參照してください。

現在の選擇が受け入れられると、選擇された行のインデックスを第 2 引數としてポップアップメニューの "callback" が呼び出されます。最初のエントリのインデックスは 1 です。メニューをキャンセルすると、-1 でコールバックが呼び出されます。

ショートカットキーを追加する場合: |popup_menu-shortcut-example| を參照してください。

popup_filter_yesno({id}, {key})

ポップアップに使用できるフィルタ。キー ’y’、’Y’ および ’n’ または ’N’ のみを處理します。第 2 引數として ’y’ または ’Y’ に 1、’n’ または ’N’ に 0 を指定して、ポップアップメニューの "callback" を呼び出します。Esc と ’x’ を押すと、’n’ を押すのと同じやうに機能します。CTRL-C は -1 でコールバックを呼び出します。他のキーは無視されます。

|popup_dialog-example| を參照してください。

popup_findinfo()

ポップアップメニューで使用されてゐるポップアップ情報ウィンドウの |window-ID| を取得します。|complete-popup| を參照してください。ポップアップ情報は、使用されてゐない場合は非表示になり、|popup_clear()| または |popup_close()| で削除できます。ポップアップメニューの項目に再配置するには |popup_show()| を使用します。ない場合は 0 を返します。

popup_findpreview()

ポップアッププレビューウィンドウの |window-ID| を取得します。ない場合は 0 を返します。

popup_getoptions({id})

popup {id} の {options} を辭書で返します。ゼロ値はオプションが設定されなかつたことを意味します。"zindex" の場合、デフォルト値が返されます。ゼロではありません。

"moved" エントリは、行番號、最小桁と最大桁のリストで、未設定時は [0, 0, 0] です。

"mousemoved" エントリはスクリーン行、最小桁と最大桁のリストで、未設定時は [0, 0, 0] です。

"firstline" は、ポップアップウィンドウの上部にある實際のバッファ行である |popup_getpos()| で取得される "firstline" とは異なり、ポップアップに設定されたプロパティです。

すべての値がゼロの場合、"border" と "padding" は含まれません。すべての値が 1 の場合、空のリストが含まれます。

すべての値が空の場合、"borderhighlight" は含まれません。設定されてゐるときのみ "scrollbarhighlight" と "thumbhighlight" が含まれます。

グローバルポップアップの場合 "tabpage" には -1 が設定され、カレントタブページの場合は 0 、別のタブページの場合は正の整數が設定されます。

"textprop", "textpropid" および "textpropwin" は、"textprop" が設定されてゐる場合にのみ與へられます。

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

|method| としても使用できます:

GetPopup()->popup_getoptions()

popup_getpos({id})

ポップアップ {id} の位置とサイズを返します。これらのエントリを持つ辭書を返します:

col	ポップアップの畫面の桁、1 から始まる
line	ポップアップの畫面の行、1 から始まる
width	畫面セル內のポップアップ全體の幅
height	畫面セル內のポップアップ全體の高さ
core_col	テキストボックスの畫面の桁
core_line	テキストボックスの畫面の行
core_width	畫面セル內のテキストボックスの幅
core_height	畫面セル內のテキストボックスの高さ
firstline	トップにおけるバッファの行 (スクロールされてゐなければ 1) ("firstline" のプロパティの値ではありません)
lastline	下端のバッファの行
scrollbar	スクロールバーが表示されてゐるなら非ゼロ
visible	ポップアップが表示されてゐる場合は 1、非表示の場合は 0

Note:
これらは實際の畫面位置です。適用されるサイズと位置のメカニズムに關して ‘popup_getoptions()‘ の値とは異なります。

"core_" 値はパディングとボーダーを除外してゐます。

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

|method| としても使用できます:

GetPopup()->popup_getpos()

popup_hide({id})

{id} がポップアップ表示されてゐる場合、それを非表示にします。ポップアップがフィルタを持つてゐる場合は、ポップアップが非表示になつてゐる限り呼び出されません。 ウィンドウ {id} が存在しない場合は何も起こりません。ウィンドウ {id} が存在するがポップアップウィンドウではない場合、エラーが發生します。

|method| としても使用できます:

GetPopup()->popup_hide()

popup_locate({row}, {col})

スクリーン位置 {row} と {col} におけるポップアップの |window-ID| を返します。もしも複數のポップアップがあるなら、一番大きい zindex をもつものが返されます。もしもこの位置にポップアップがないのなら、ゼロが返されます。

popup_menu({what}, {options})

カーソルの近くに {what} を表示し、カーソルキーで項目の 1 つを選擇して處理し、それを閉ぢるには、Space または Enter で項目を選擇します。これを有效にするには、{what} に複數の行が必要です。これは次のやうに機能します:

call popup_create({what}, #{
        \ pos: 'center',
        \ zindex: 200,
        \ drag: 1,
        \ wrap: 0,
        \ border: [],
        \ cursorline: 1,
        \ padding: [0,1,0,1],
        \ filter: 'popup_filter_menu',
        \ mapping: 0,
        \ })

現在行は、"PopupSelected" を使用してマッチでハイライトされます。"PopupSelected" が未定義の場合は、"PmenuSel" が使はれます。

プロパティを變更するには {options} を使用します。少なくとも "callback" を選擇された項目を扱ふ函數に設定するべきです。 例:

func ColorSelected(id, result)
   " use a:result
endfunc
call popup_menu(['red', 'green', 'blue'], #{
        \ callback: 'ColorSelected',
        \ })

|method| としても使用できます:

GetChoices()->popup_menu({})

popup_move({id}, {options})

ポップアップ {id} を {options} で指定された位置に移動します。{options} にはポップアップ位置を指定する |popup_create()| 由來の項目を含むことができます:

line
col
pos
maxheight
minheight
maxwidth
minwidth
fixed

{id} については ‘popup_hide()‘ を參照してください。その他のオプションについては |popup_setoptions()| を參照してください。

|method| としても使用できます:

GetPopup()->popup_move(options)

popup_notification({what}, {options})

Vim のウィンドウの上部に {what} を 3 秒閒表示します。これは次のやうに動作します:

call popup_create({what}, #{
        \ line: 1,
        \ col: 10,
        \ minwidth: 20,
        \ time: 3000,
        \ tabpage: -1,
        \ zindex: 300,
        \ drag: 1,
        \ highlight: 'WarningMsg',
        \ border: [],
        \ close: 'click',
        \ padding: [0,1,0,1],
        \ })

PopupNotification ハイライトグループが定義されてゐる場合は、WarningMsg の代はりに使用されます。

|+timers| 機能がないと、ポップアップは自動的に消えないでせう。ユーザーはこれをクリックしなければなりません。

他の通知と重ならないやうに位置が調整されます。プロパティを變更するには {options} を使用します。

|method| としても使用できます:

GetText()->popup_notification({})

popup_show({id})

{id} が非表示のポップアップの場合はそれを表示します。{id} については ‘popup_hide()‘ を參照してください。

{id} が情報ポップアップの場合、現在のポップアップメニュー項目の隣に配置されます。

popup_setoptions({id}, {options})

ポップアップ {id} のオプションを {options} のエントリで上書きします。これらのオプションを設定することができます:

border
borderchars
borderhighlight
callback
close
cursorline
drag
filter
firstline
flip
highlight
mapping
mask
moved
resize
padding
scrollbar
scrollbarhighlight
thumbhighlight
time
title
wrap
zindex

|popup_move()| からのオプションも使用することができます。"hidden" のために |popup_hide()| と |popup_show()| を使用します。"tabpage" は變更することはできません。

|method| としても使用できます:

GetPopup()->popup_setoptions(options)

popup_settext({id}, {text})

ポップアップウィンドウ {id} でバッファのテキストを設定します。{text} は |popup_create()| に提供されるものと同じです。ただしバッファ番號は認められてゐません。

テキストの違ひが生じる以外ではウィンドウのサイズや位置を變更しません。

|method| としても使用できます:

GetPopup()->popup_settext('hello')

3. 使用方法

POPUP_CREATE() の引數

|popup_create()| の最初の引數 (と |popup_settext()| の第 2 引數) は表示されるテキストと、オプションでテキストプロパティを指定します。それは 4 つの形式のうちの 1 つです:

• バッファ番號
• 文字列
• 文字列のリスト
• 辭書のリスト。各辭書は次のエントリを持ちます:

  text	表示するテキストを含む文字列。
  props	テキストプロパティのリスト。任意。各エントリは |prop_add()| の第 3 引數のやうな辭書ですが、辭書の "col" エントリを使つて桁を指定します。以下を參照してください: |popup-props|。

自分で新しいバッファを作成したい場合は、|bufadd()| を使用して、バッファ番號を popup_create() に渡します。 端末ウィンドウのバッファを使用することはできません。

|popup_create()| の第 2 引數は任意の辭書です:

"zindex" に應じて、ポップアップは他のポップアップの下または上に移動します。補完メニュー (|popup-menu|) は zindex 100 です。短時閒表示されるメッセージについては、zindex 1000 を使用することを薦めます。

デフォルトではテキストは折り返され、それによつて {lines} の行が複數の畫面行を占めるやうになります。"wrap" が FALSE の場合、ポップアップの外側または Vim のウィンドウの外側のテキストは、表示されずに切り捨てられます。

ポップアップテキストプロパティ

これらは |prop_add()| の第 3 引數と同じです。ただし:

• "lnum" は常にリストの現在の行
• "bufnr" は常にポップアップのバッファ
• "col" は別の引數ではなく辭書內

さういふわけで、以下が得られます:

ポップアップと textprop の位置

テキストプロパティの隣にポップアップを配置すると、テキストが插入または削除されたときにポップアップが移動します。ポップアップはツールチップのやうに機能します。

この動作をさせるには、次の手順が必要です:

• テキストプロパティタイプを定義して、その名前を定義する:

  call prop_type_add('popupMarker', {})
  

• 目的のテキストにテキストプロパティを配置する:

  let lnum = {line of the text}
  let col = {start column of the text}
  let len = {length of the text}
  let propId = {arbitrary but unique number}
  call prop_add(lnum, col, #{
          \ length: len,
          \ type: 'popupMarker',
          \ id: propId,
          \ })
  

• ポップアップを作成する:

  let winid = popup_create('the text', #{
          \ pos: 'botleft',
          \ textprop: 'popupMarker',
          \ textpropid: propId,
          \ border: [],
          \ padding: [0,1,0,1],
          \ close: 'click',
          \ })
  

デフォルトでは、ポップアップは、ポップアップに指定された "pos" の反對側のテキストの隅に配置されます。したがつて、ポップアップが "botleft" を使用する場合、ポップアップの左下隅はテキストプロパティの右上隅の隣に配置されます。

                  +----------+
                  | the text |
                  +----------+
just some PROPERTY as an example

ここで、テキストプロパティは "PROPERTY" にあります。負の "col" 値を popup_create() に渡すことにより、ポップアップを左に移動します。"col: -5" を使用すると、以下が得られます:

             +----------+
             | the text |
             +----------+
just some PROPERTY as an example

テキストプロパティがビューの外に移動すると、ポップアップは非表示になります。ポップアップが定義されたウィンドウが閉ぢられた場合、ポップアップは閉ぢられます。

ポップアップが目的の位置に收まらない場合、近くの位置に表示される場合があります。

いくつかのヒント:

• 他のプラグインとの衝突を避けるために、テキストプロパティタイプ名は一意である必要があります。"bufnr" 項目を使用して、バッファに對してローカルにすることもできます。
• テキストプロパティが 1 つしか表示されてゐない場合は、テキストプロパティ ID を省略できます。
• ポップアップは、ユーザーの操作の邪魔になる場合があります。上記の例のやうに、クリックするだけで閉ぢることができるのが役立ちます。
• テキストプロパティが削除されると、ポップアップは閉ぢられます。このやうな感じで使用します:

  call prop_remove(#{type: 'popupMarker', id: propId})
  

ポップアップフィルタ

ポップアップが表示されてゐる閒にタイプされたキーを取得するコールバック。ポップアップが非表示になつてゐると、フィルタは呼び出されません。

フィルタは、キーが處理されて破毀されることを示すために TRUE を返すか、または現在の狀態で Vim に通常通りキーを處理させるために FALSE を返します。FALSE が返され、別のポップアップウィンドウが表示されてゐる場合は、そのフィルタも呼び出されます。最も高い zindex を持つポップアップウィンドウのフィルタが最初に呼び出されます。

フィルタ函數は 2 つの引數、ポップアップ ID と文字列としてのキーで呼び出されます。例:

func MyFilter(winid, key)
  if a:key == "\<F2>"
    " do something
    return 1
  endif
  if a:key == 'x'
    call popup_close(a:winid)
    return 1
  endif
  return 0
endfunc

"filtermode" プロパティを使用して、フィルターを呼び出すモードを指定できます。デフォルトは "a": すべてのモードです。"nvi" コマンドラインモードが含まれない場合、コマンドラインで入力されたコマンドはフィルタリングされません。ただし、コマンドラインモードに移行するには、フィルターで ":" を使用しないでください。ビジュアルモードに入るために "v" を消費してはいけないやうに。

通常、キーは、フィルターが使用しない場合にキーが通常の入力として渡されるため、マッピング後に結果として得られるものです。フィルターがすべてのキーを消費する場合、マッピングが邪魔にならないやうに、"mapping" プロパティを 0 に設定します。これは、|popup_menu()| および |popup_dialog()| のデフォルトです。

いくつかの推奬されるキー動作:

マウスクリックは <LeftMouse> として屆きます。座標は |getmousepos()| から得ることができます。

Vim は標準のフィルタ |popup_filter_menu()| と |popup_filter_yesno()| を提供します。

Note:
"x" はポップアップを閉ぢる通常の方法です。Esc を使ひたくなるかもしれませんが、多くのキーは Esc 文字で始まるので、Vim が Esc キーを認識するまでに時閒がかかることがあります。Esc を使用する場合は、’ttimeoutlen’ オプションを 100 に設定し、’timeout’ または ’ttimeout’、あるいはその兩方を設定することを薦めます。

ポップアップコールバック

ポップアップが閉ぢたときに呼び出されるコールバック。

コールバックは 2 つの引數で呼び出されます: ポップアップウィンドウ ID と結果、それはポップアップ行のインデックスか、あるいは ‘popup_close()‘ の第 2 引數として渡されたものです。

ポップアップが强制終了された場合、例へば、カーソルが移動したか CTRL-C が押された場合、-1 がコールバックに渡されます。

例:

func SelectedColor(id, result)
   echo 'choice made: ' .. a:result
endfunc

ポップアップスクロールバー

テキストがポップアップの大きさに適應してゐないなら、ウィンドウの右側にスクロールバーが表示されます。これは "scrollbar" オプションをゼロに設定することで表示することができます。スクロールバーが表示されてゐるときに、マウスポインタがポップアップの上にある閒は、マウススクロールのイベントはあなたが期待する通りに、テキストを上下にスクロールさせる動作になります。スクロールバーの上半分をクリックすると、テキストを 1 行下にスクロールします。スクロールバーの下半分をクリックすると、テキストを 1 行上にスクロールします。しかしながら、これは制限されてゐますので、ポップアップは小さくはなりません。

ポップアップマスク

ポップアップに被せるテキストを最小化するために、この一部分は透明化することができます。これは リストのリストである "mask" によつて定義されてゐます。それぞれのリストは 4 つの項目を持ちます:

例へば、最終行のうしろ 10 桁を透明化するには:

[[-10, -1, -1, -1]]

4 つの角を透明化するには:

[[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]

3. 例

やること: 興味深い例をもつと

ユーザーに y/Y か n/N を押すやうに促す:

func MyDialogHandler(id, result)
   if a:result
      " ... 'y' or 'Y' was pressed
   endif
endfunc

call popup_dialog('Continue? y/n', #{
        \ filter: 'popup_filter_yesno',
        \ callback: 'MyDialogHandler',
        \ })

popup_filter_menu() をショートカットで擴張できるやうにする:

call popup_menu(['Save', 'Cancel', 'Discard'], #{
        \ filter: 'MyMenuFilter',
        \ callback: 'MyMenuHandler',
        \ })

func MyMenuFilter(id, key)
  " Handle shortcuts
  if a:key == 'S'
     call popup_close(a:id, 1)
     return 1
  endif
  if a:key == 'C'
     call popup_close(a:id, 2)
     return 1
  endif
  if a:key == 'D'
     call popup_close(a:id, 3)
     return 1
  endif

  " No shortcut, pass to generic filter
  return popup_filter_menu(a:id, a:key)
endfunc

’ballooneval’ のためのポップアップウィンドウの使用例:

set ballooneval balloonevalterm
set balloonexpr=BalloonExpr()
let s:winid = 0
let s:last_text = ''

func BalloonExpr()
  if s:winid && popup_getpos(s:winid) != {}
    " previous popup window still shows
    if v:beval_text == s:last_text
      " Still the same text, keep the existing popup
      return ''
    endif
    call popup_close(s:winid)
  endif
  let s:winid = popup_beval(v:beval_text, #{mousemoved: 'word'})
  let s:last_text = v:beval_text
  return ''
endfunc

ひとたびテキストが利用できるやうにな、もしもテキストを非同期的に得られるなら、式函數から空の文字列を返し、popup_beval() を呼び出します。タイマーコールバックをシミュレートした例：

set ballooneval balloonevalterm
set balloonexpr=BalloonExpr()
let s:winid = 0
let s:balloonText = ''

func BalloonExpr()
  if s:winid && popup_getpos(s:winid) != {}
    " 以前のポップアップウィンドウはまだ見えてゐます
    if  v:beval_text == s:balloonText
      " テキストを默らせて、ポップアップはそのまま
      return ''
    endif
    call popup_close(s:winid)
    let s:winid = 0
  endif
  " テキストを表示するために非同期的なループをシミュレート
  let s:balloonText = v:beval_text
  call timer_start(100, 'ShowPopup')
  return ''
endfunc

func ShowPopup(id)
  let s:winid = popup_beval(s:balloonText, #{mousemoved: 'word'})
endfunc