21.17.1.2 Extended Menu Items

メニューアイテムの拡張フォーマットは、単純なフォーマットに比べて、より柔軟かつ明快です。拡張フォーマットでは、メニューアイテムにバインドのイベント型に、シンボルmenu-itemで始まるシンボルのリストを指定します。選択できない文字列にたいしては、以下のようなバインディングになります:

(menu-item item-name)

2つ以上のダッシュで始まる文字列は、リストのセパレーターを指定します。Menu Separatorsを参照してください。

選択可能な実際のメニューアイテムを定義するには、以下のような拡張フォーマットでバインドします:

(menu-item item-name real-binding
    . item-property-list)

ここで、item-nameはメニューアイテム文字列を評価する式です。つまり、文字列は底数である必要はありません。3つ目の引数real-bindingは、実行するコマンドです。リストの最後の要素item-property-listは、プロパティリストの形式をもつ、その他の情報を含みます。

以下は、サポートされるプロパティのテーブルです:

:enable form

formの評価結果は、そのアイテムを有効にするかどうかを決定する(非nilの場合は有効)。アイテムが無効な場合は、実際にクリックできない。

:visible form

formの評価結果は、そのアイテムを実際にメニューに表示するかどうかを決定する(非nilの場合は表示)。アイテムが非表示の場合は、そのアイテムが定義されていないかのようにメニューが表示される。

:help help

このプロパティhelpの値は、そのアイテム上にマウスがある間表示する“help-echo”文字列を指定する。この文字列は、help-echoテキストプロパティ(Help displayを参照)と同じ方法で表示される。これは、テキストやoverlayにたいするhelp-echoプロパティと異なり、文字列定数でなければならないことに注意されたい。

:button (type . selected)

このプロパティは、ラジオボタンおよびトグルボタンを定義する手段を提供する。CARのtypeは、:toggleか:radioのいずれかを指定する。CDRのselectedはフォームで、評価結果によりそのボタンがカレントで選択されているかどうかを指定する。

トグル(toggle)は、selectedの値に応じて“on”か“off”のいずれかがラベルされるメニューアイテムである。コマンド自身は、selectedがnilならtに、tならnilにselectedを切り替える(toggle)こと。以下は、debug-on-errorフラグが定義されているときに、メニューアイテムをトグルする方法の例である:

(menu-item "Debug on Error" toggle-debug-on-error
           :button (:toggle
                    . (and (boundp 'debug-on-error)
                           debug-on-error)))

これは、toggle-debug-on-errorが変数debug-on-errorをトグルするコマンドとして定義されていることにより機能する。

ラジオボタンとは、メニューアイテムのグループであり、常にただ1つのメニューアイテムだけが“選択される(selected)”。そのためには、どのメニューアイテムが選択されているかを示す変数が存在する必要がある。グループ内の各ラジオボタンにたいするselectedフォームは、そのボタンを選択するために、その変数が正しい値をもつかどうかをチェックする。そして、ボタンのクリックにより変数をセットして、クリックされたボタンが選択される。

:key-sequence key-sequence

このプロパティは、そのメニューアイテムにより呼び出されるのと同じコマンドにバインドされるかもしれないキーシーケンスを指定する。正しいキーシーケンスを指定した場合は、メニュー表示の準備がより高速になる。

間違ったキーシーケンスを指定した場合は、何の効果もない。Emacsは、メニュー内のkey-sequenceを表示する前に、実際にそのkey-sequenceがそのメニューアイテムと等価なのか検証する。

:key-sequence nil

このプロパティは、そのメニューアイテムには等価なキーバインディングが通常は存在しないことを示す。このプロパティを使用することにより、Emacsはそのメニューアイテムにたいして等価なキーボード入力をキーマップから検索する必要がなくなるので、メニュー表示の準備時間が短縮される。

しかし、ユーザーがそのアイテムの定義をキーシーケンスにリバインドした場合、Emacsは:keysプロパティを無視して、結局は等価なキーボード入力を見つけ出す。

:keys string

このプロパティは、そのメニューにたいする等価なキーボード入力として表示される文字列stringを指定する。string内では、ドキュメント構成‘\\[...]’を使用できる。

:filter filter-fn

このプロパティは、メニューアイテムを直接計算する手段を提供する。このプロパティの値filter-fnは、引数が1つの関数で、呼び出し時の引数はreal-bindingである。この関数は、かわりに使用するバインディングをリターンするべきである。

Emacsは、メニューデータ構造を再表示、または操作する任意のタイミングでこの関数を呼び出し得るので、いつ呼び出されても安全なように関数を記述すべきである。