Lispプログラムでは、メニューを表示してユーザーがマウスで選択肢を選べるようにできます。テキスト端末でマウスが利用できない場合は、キーボードのカーソル移動キー—C-n、C-p、または上下矢印キー—を使って選択肢を選ぶことができます。
この関数はポップアップメニューを表示し、ユーザーがどの項目を選択したかを示す値を返します。
引数 position
は、メニューの左上隅を画面上のどこに配置するかを指定します。指定できるのは、マウスボタンまたは touchscreen-begin
イベント（ユーザーがボタンを押した位置にメニューを配置することを指定するもの）、あるいは以下のような形式のリストです：
((xoffset yoffset) window)
ここで、xoffset と yoffset は window の左上隅を起点としてピクセル単位で計測した座標です。window はウィンドウまたはフレームである場合があります。
position が t
の場合、現在のマウス位置（テキスト端末でマウスが利用できない場合はフレームの左上隅）を使用することを意味します。position が nil
の場合、メニューを実際に表示したりポップアップさせたりすることなく、menu
で指定されたキーマップに対応するキーバインドを事前に計算することを意味します。
引数 menu は、メニューに表示する内容を指定します。これはキーマップ、またはキーマップのリスト（メニューキーマップ
を参照）を指定できます。この場合、戻り値はユーザーの選択に対応するイベントのリストとなります。選択がサブメニューで行われた場合、このリストには複数の要素が含まれます。（なお、x-popup-menu
は実際にはそのイベントシーケンスにバインドされたコマンドを実行するわけではない点に注意してください。）メニュータイトルをサポートするテキスト端末やツールキットでは、menu がキーマップの場合は menu
のプロンプト文字列から、キーマップのリストの場合は menu
の最初のキーマップのプロンプト文字列から、タイトルが取得されます（メニューの定義 を参照）。
あるいは、menu は以下の形式を取ることができます。
(title pane1 pane2...)
各ペインがフォームのリストであるところ
(title item1 item2...)
各 item はコンスセル (line . value) であるべきであり、ここで
line は文字列、value はその line が選択された際に返す値となります。メニューキーマップとは異なり、nil と value
があってもメニュー項目が選択不能になることはありません。あるいは、各 item
をコンスセルではなく文字列にすることも可能で、これによりメニュー項目が選択不能になります。
ユーザーが有効な選択を行わずにメニューを閉じた場合（例えば、有効な選択肢からマウスを離したり、C-g
と入力したりした場合）、通常は終了となり、x-popup-menu は返りません。しかし、position
がマウスボタンイベント（ユーザーがマウスでメニューを呼び出したことを示す）である場合は、終了は発生せず、x-popup-menu は nil を返します。
使用上の注意：
メニューキーマップで定義したプレフィックスキーで実現できる場合は、メニューの表示に x-popup-menu を使用しないでください。メニューキーマップを用いてメニューを実装した場合、C-h c と C-h a
はそのメニュー内の個々の項目を認識し、ヘルプを提供できます。一方、x-popup-menu
を呼び出すコマンドを定義してメニューを実装した場合、ヘルプ機能はそのコマンド内部で何が行われているかを把握できないため、メニュー項目に対するヘルプを提供することができません。
マウス操作でサブメニューを切り替えられるメニューバーの仕組みは、コマンドの定義内を確認して x-popup-menu を呼び出しているかどうかを判断することができません。そのため、x-popup-menu
を用いてサブメニューを実装しようとしても、メニューバーと統合的に動作させることはできません。こうした理由から、すべてのメニューバー用サブメニューは親メニュー内のメニューキーマップで実装されており、x-popup-menu が用いられることはありません。メニューバーを参照してください。
メニューバーのサブメニューの内容を動的に変更したい場合は、引き続きメニューキーマップを使用して実装してください。内容を動的に変更するには、menu-bar-update-hook
にフック関数を追加し、必要に応じてメニューキーマップの内容を更新するようにしてください。
ポップアップメニューが表示される直前に、x-popup-menuを直接呼び出すか、あるいはメニューキーマップを介して、通常のフックが実行されます。x-popup-menuがポップアップメニューを表示せずに別の理由で復帰した場合は、このフックは呼び出されません。