Lispプログラムがポップアップメニューを表示して、ユーザーがマウスで候補を選択できます。テキスト端末上では、マウスが利用不可ならキーボードのモーションキーC-nやC-p、上矢印キーや下矢印キーで候補を選択できます。
この関数はポップアップメニューを表示して、ユーザーが何を選択したかの指標をリターンする。
引数positionには、メニュー左上隅をスクリーン上のどこに置くか指定する。これはマウスボタンイベント(ユーザーがボタンを操作した位置にメニューを置くよう指示する)、または以下の形式のリストのいずれか:
((xoffset yoffset) window)
ここでxoffsetとyoffsetはwindowの左上隅からピクセル単位で測られた座標である。windowはウィンドウかフレーム。
positionがtなら、それはマウスのカレント位置の使用を意味する(テキスト端末上でマウスが利用不可ならフレーム左上隅)。positionがnilなら、それは実際にメニューをポップアップせずに、menu内で指定されたキーマップと等価なキーバインディングを事前に計算することを意味する。
引数menuはメニュー内で何を表示するかを意味する。これはキーマップかキーマップのリストを指定できる(メニューキーマップを参照)。この場合にはリターン値はユーザー選択に対応するイベントのリスト。選択がサブメニュー内で発生した場合には、このリストには複数の要素がある(x-popup-menuはそのイベントシーケンスにバインドされたコマンドを実際には実行しないことに注意)。テキスト端末やメニュータイトルをサポートするツールキットでは、menuがキーマップならタイトルはmenuのプロンプト文字列、menuがキーマップのリストなら最初のキーマップのプロンプト文字列から取得される(メニューの定義を参照)。
かわりにmenuは以下の形式をもつこともできる:
(title pane1 pane2...)
ここでpaneはそれぞれ以下の形式のリストである
(title item1 item2...)
itemはそれぞれコンスセル(line
.
value)であること。ここでlineは文字列、valueはlineが選択された場合にリターンされる値。メニューキーマップとは異なりnilのvalueは選択不可のメニューアイテムを作成しない。かわりにitemにコンスセルではなく文字列を指定できる。これは選択不可のメニューアイテムを作成する。
たとえば有効な選択からマウスを外してクリックしたり、C-gをタイプすることにより、有効な選択を行うことなくユーザーがメニューを取り除いた場合は、通常はquitしてx-popup-menuはリターンしない。しかしpositionがマウスボタンイベント(ユーザーがマウスでメニューを呼び出したことを示す)なら、quitは発生せずにx-popup-menuはリターンする。
使用上の注意:
メニューキーマップで定義したプレフィクスキー処理を行える場合には、メニューの表示に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に追加してください。