Расширенные пункты меню

Пункт меню в расширенном формате — более гибкая и аккуратная альтернатива простому формату. Определите тип события с привязкой, представляющей собой список, начинающийся с символа 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)

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

Переключатель — это пункт меню, помеченный как включённый или выключенный в зависимости от значения 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

Это свойство задаёт последовательность клавиш, отображаемую в качестве клавиатурного эквивалента. Перед отображением key-sequence в меню Emacs проверяет, действительно ли 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.