23.18.1.2 Расширенные элементы меню

Элемент меню расширенного формата — это более гибкая и более чистая альтернатива простому формату. Вы определяете тип события с привязкой, которая является списком, начинающимся с символа menu-item. Для невыбираемой строки привязка выглядит следующим образом:

(menu-item item-name)

Строка, начинающаяся с двух или более дефисов, указывает разделительную линию; см. Разделители меню.

Чтобы определить настоящий элемент меню, который можно выбрать, привязка расширенного формата выглядит следующим образом:

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

Здесь item-name — это выражение, которое вычисляется в строку элемента меню. Таким образом, строка не обязательно должна быть константой.

Третий элемент, real-binding, может быть командой для выполнения (в этом случае вы получаете обычный элемент меню). Он также может быть картой клавиш, что приведет к подменю, и item-name используется как имя подменю. Наконец, он может быть nil, в этом случае вы получите невыбираемый элемент меню. Это в основном полезно при создании разделительных линий и тому подобного.

Хвостовая часть списка, item-property-list, имеет форму списка свойств (см. Списки свойств), который содержит другую информацию.

Вот таблица поддерживаемых свойств:

:enable form

Результат вычисления form определяет, включен ли элемент (не-nil означает да). Если элемент не включен, вы на самом деле не сможете на него нажать.

:visible form

Результат вычисления form определяет, должен ли элемент фактически отображаться в меню (не-nil означает да). Если элемент не отображается, то меню отображается так, как если бы этот элемент вообще не был определен.

:help help

Значение этого свойства, help, указывает строку помощи, которая отображается, пока курсор находится над этим элементом. Это отображается так же, как и текстовые свойства help-echo (см. Отображение справки). Обратите внимание, что это должна быть константная строка, в отличие от свойства help-echo для текста и наложений.

:button (type . selected)

Это свойство предоставляет способ определения переключателей (radio buttons) и переключаемых кнопок (toggle buttons). CAR, type, указывает, какой из них: это должно быть :toggle или :radio. CDR, selected, должна быть формой; результат ее вычисления показывает, выбран ли этот переключатель в данный момент.

Toggle — это элемент меню, который помечен как включенный или выключенный в зависимости от значения selected. Сама команда должна переключать selected, устанавливая ее в t, если она nil, и в nil, если она t. Вот как определяется элемент меню для переключения флага 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.

Переключатели — это группа элементов меню, в которой в любой момент времени выбран только один. Должна быть переменная, значение которой указывает, какой из них выбран в данный момент. Форма selected для каждой радиокнопки в группе должна проверять, имеет ли переменная правильное значение для выбора этой кнопки. Нажатие на кнопку должно установить переменную таким образом, чтобы нажатая вами кнопка стала выбранной.

:key-sequence key-sequence

Это свойство указывает, какую последовательность клавиш отображать как эквивалент клавиатуры. Прежде чем Emacs отобразит key-sequence в меню, он проверяет, что key-sequence действительно эквивалентен этому элементу меню, поэтому это имеет эффект только в том случае, если вы указали правильную последовательность клавиш. Указание nil для key-sequence эквивалентно отсутствию атрибута :key-sequence.

:keys string

Это свойство указывает, что string — это строка, отображаемая как эквивалент клавиатуры для этого элемента меню. Вы можете использовать конструкцию документации ‘\\[...]’ в string.

Это свойство также может быть функцией (которая будет вызвана без аргументов). Эта функция должна возвращать строку. Эта функция будет вызываться каждый раз, когда меню вычисляется, поэтому использование функции, которая требует много времени для вычисления, не является хорошей идеей, и она должна ожидать вызова из любого контекста.

:filter filter-fn

Это свойство предоставляет способ динамического вычисления элемента меню. Значение свойства filter-fn должно быть функцией с одним аргументом; когда она вызывается, ее аргументом будет real-binding. Функция должна вернуть привязку, которую следует использовать вместо этого.

Emacs может вызвать эту функцию в любое время, когда он повторно отображает или работает с структурами данных меню, поэтому вы должны написать ее так, чтобы ее можно было безопасно вызывать в любое время.

:wrap wrap-p

Если wrap-p не равен nil внутри панели инструментов, элемент меню не отображается, а вместо этого вызывает отображение последующих элементов на новой строке. Это не поддерживается, когда Emacs использует наборы инструментов GTK+ или Nextstep.