22.17.1.2 拡張メニューアイテム

メニューアイテムの拡張フォーマットは、単純なフォーマットに比べてより柔軟かつ明快です。拡張フォーマットではシンボル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、メニューデータ構造の再表示や操作を行うすべてのタイミングでこの関数を呼び出すかもしれないので、いつ呼び出されても安全なように関数を記述すること。