hs.menubar

Предварительно определённый список позиций изображений для элемента строки меню

Создаёт новый объект элемента строки меню и, по желанию, добавляет его в системную строку меню

• inMenuBar - необязательный параметр, по умолчанию установленный в true. Если true, элемент добавляется в системную строку меню, иначе — скрыт.
• autosaveName - необязательный параметр, позволяющий определить имя для автосохранения, чтобы macOS мог восстановить расположение строки меню после перезагрузки.

• объект элемента строки меню для использования с другими методами API или nil, если создание не удалось

• Вы должны вызвать hs.menubar:setTitle() или hs.menubar:setIcon() после создания объекта, иначе он будет невидимым

• Вызов этого метода с inMenuBar равным false эквивалентен вызову hs.menubar.new():removeFromMenuBar().

• Скрытый элемент строки меню можно добавить в системную строку меню, вызвав hs.menubar:returnToMenuBar(), или использовать в качестве всплывающего меню, вызвав hs.menubar:popupMenu().

Получить или установить имя автосохранения для строки меню. Определив имя автосохранения, macOS сможет восстановить положение строки меню после перезагрузки.

• name - Необязательная строка, если вы хотите установить имя автосохранения

• Элемент строки меню, если его имя автосохранения было изменено, или текущее значение имени автосохранения

Удаляет элемент строки меню из строки меню и уничтожает его.

• None

• None

Возвращает рамку элемента строки меню.

• None

• прямоугольник hs.geometry, описывающий рамку элемента строки меню, или nil, если элемент строки меню в данный момент не находится в строке меню.

• Это вернёт рамку, даже если нет иконки или заголовка.

Возвращает текущую иконку объекта элемента строки меню.

• None

• иконка элемента строки меню в качестве объекта hs.image, или nil, если её нет.

Получить или установить положение изображения строки меню относительно заголовка.

• position - Одно из значений в hs.menubar.imagePositions, которое будет установлено, или ничего, чтобы вернуть текущее положение

• Элемент строки меню, если его положение изображения было изменено, или текущее значение положения изображения

Возвращает булевое значение, указывающее, находится ли указанное меню в строке меню OS X.

• None

• булево значение, указывающее, находится ли указанное меню в строке меню OS X

Отобразить элемент строки меню как всплывающее меню в указанной точке экрана.

• point - Положение верхнего левого угла всплывающего меню для отображения.
• darkMode - (необязательно) true для принудительного переключения в тёмную тему строки меню (по умолчанию соответствует настройкам macOS)

• Элемент строки меню

• Элементы, вызывающие hs.menubar:setClickCallback(), будут вызывать функцию обратного вызова, но мы не можем контролировать позиционирование каких-либо визуальных элементов, которые может создать функция — вызов этого метода для такого объекта эквивалентен прямому вызову его функции обратного вызова.
• Этот метод блокирующий. Hammerspoon не сможет реагировать на другую активность, пока всплывающее меню отображается.
• darkMode использует недокументированный вызов API macOS, поэтому может сломаться в будущих релизах.

Удаляет меню из системной строки меню. Элемент по-прежнему может использоваться в качестве всплывающего меню, если вы также его не удалите.

• None

• Элемент строки меню

Возвращает ранее удалённое меню обратно в системную строку меню.

• None

• Элемент строки меню

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

• fn - Необязательная функция, которая будет вызываться при нажатии на элемент меню. Если этот аргумент не указан, любая существующая функция будет удалена. Функция может необязательно принимать один аргумент, который будет таблицей, содержащей логические значения, указывающие, какие модификаторы клавиатуры были нажаты при нажатии на элемент меню; Возможные клавиши:
  • cmd
  • alt
  • shift
  • ctrl
  • fn

• элемент меню

• Если к элементу меню был прикреплён контекстное меню, этот обработчик никогда не будет вызван.
• Не оказывает влияния на отображение всплывающего меню, но изменения вступят в силу, если hs.menubar:returnToMenuBar() будет вызвано для элемента меню.

Устанавливает изображение для элемента меню. Изображение будет отображаться в системном меню.

• imageData - Может быть одним из следующих:
  • Объект hs.image
  • Строка, содержащая путь к файлу изображения
  • Строка, начинающаяся с ASCII:, что указывает, что остальная часть строки интерпретируется как специальный вид ASCII-диаграммы, которая будет отрисована в изображение и использована как значок. См. примечания ниже для получения информации о специальном формате ASCII-диаграммы.
  • nil, указывающее на удаление текущего изображения
• template - Необязательное логическое значение по умолчанию true. Если оно true, предоставленное изображение будет обрабатываться как "шаблонное" изображение, что позволяет ему автоматически поддерживать тёмный режим OS X 10.10. Если оно false, изображение будет использоваться как есть, поддерживая цвет.

• элемент меню, если изображение было загружено и установлено, nil если его не удалось найти или загрузить

• ** Изменение API **

  • Этот метод раньше возвращал true при успехе — это было изменено на возврат элемента меню при успехе для облегчения цепочки методов. Поскольку Lua рассматривает любое значение, которое не nil или false, как "true", это должно затронуть только код, где значение возврата фактически сравнивалось с true, например, if result == true then..., а не (не затронутое) if result then....

• Если вы установили заголовок и значок, они оба будут отображаться рядом друг с другом

• Не оказывает влияния на отображение всплывающего меню, но изменения вступят в силу, если hs.menubar:returnToMenuBar() будет вызвано для элемента меню.

• Значки должны быть небольшими, прозрачными изображениями, примерно соответствующими размеру обычных значков меню, в противном случае они будут выглядеть очень странно. Обратите внимание, что если вы используете объект изображения hs.image в качестве значка, вы можете принудительно изменить его размер с помощью hs.image:setSize({w=16,h=16})

• Поддерживается масштабирование Retina, если изображение масштабируемое (например, PDF, созданный в Adobe Illustrator) или содержит несколько размеров (например, TIFF с маленькими и большими изображениями). Изображения не будут автоматически работать правильно, если у вас есть версия @2x.

• Значки по умолчанию задаются как "шаблоны", что позволяет им автоматически поддерживать тёмный режим OS X 10.10, но это также означает, что они не могут быть сложными цветными изображениями.

• Примеры хорошо работающих изображений см. в Hammerspoon.app/Contents/Resources/statusicon.tiff (для многоизображений TIFF-значка, совместимого с Retina) или https://github.com/jigish/slate/blob/master/Slate/status.pdf (для масштабируемого векторного PDF-значка).

• Рекомендации по размеру изображений см. в http://alastairs-place.net/blog/2013/07/23/nsstatusitem-what-size-should-your-icon-be/

Прикрепляет раскрывающееся меню к элементу меню.

• menuTable:
  • Если этот аргумент nil, удаляет любое ранее зарегистрированное меню.
  • Если этот аргумент таблица: устанавливает меню для этого элемента меню в предоставленную таблицу. Формат таблицы описан ниже.
  • Если этот аргумент функция: функция будет вызываться каждый раз, когда пользователь нажимает на элемент меню, и функция должна возвращать таблицу, которая определяет отображаемое меню. Таблица должна иметь тот же формат, что и описанный ниже. Функция может необязательно принимать один аргумент, который будет таблицей, содержащей логические значения, указывающие, какие модификаторы клавиатуры были нажаты при нажатии на элемент меню; Возможные клавиши:
  • cmd
  • alt
  • shift
  • ctrl
  • fn
  • Формат таблицы: lua { { title = "my menu item", fn = function() print("you clicked my menu item!") end }, { title = "-" }, { title = "other item", fn = some_function }, { title = "disabled item", disabled = true }, { title = "checked item", checked = true }, }
  • Доступные клавиши для каждого элемента меню (обратите внимание, что title — единственная необходимая клавиша — все остальные необязательны):
  • title - Строка или объект hs.styledtext для отображения в меню. Если это специальная строка "-", элемент будет отображаться как разделитель меню. Эта клавиша может быть установлена в пустую строку (""), но должна присутствовать.
  • fn - Функция, которая будет выполняться при нажатии на элемент меню. Функция будет вызвана с двумя аргументами. Первый аргумент будет таблицей, содержащей логические значения, указывающие, какие модификаторы клавиатуры были нажаты при нажатии на элемент меню (см. параметр menuTable для возможных клавиш), а второй — таблицей, представляющей элемент.
  • checked - Логическое значение, указывающее, должен ли элемент меню иметь галочку (по умолчанию) рядом с ним или нет. По умолчанию false.
  • state - Текстовое значение "on", "off" или "mixed", указывающее состояние элемента меню. "on" и "off" эквивалентны checked being true or false соответственно, а "mixed" будет иметь дефис (по умолчанию) рядом с ним.
  • disabled - Логическое значение, указывающее, должен ли элемент меню быть невыбираемым или нет. По умолчанию false (т. е. элементы меню выбираемы по умолчанию).
  • menu - таблица в том же формате, что и выше, которая будет представлена как подменю для этого элемента меню. * Элемент меню, который отключён и имеет подменю, будет отображать стрелку справа, указывающую, что у него есть подменю, но элементы в подменю не будут доступны, даже если элементы подменю сами по себе не отключены. * Элемент меню с подменю также является нажимаемой целью, поэтому он также может иметь клавишу fn.
  • image - Изображение для отображения в меню справа от любого изображения состояния или галочки и слева от заголовка элемента меню. Это изображение не ограничено размером, установленным с помощью hs.menubar:stateImageSize, поэтому вы должны настроить его с помощью hs.image:setSize, если ваше изображение чрезвычайно большое или маленькое.
  • tooltip - Подсказка, отображаемая при наведении курсора на элемент меню в течение нескольких секунд.
  • shortcut - Строка, содержащая один символ, который будет использоваться в качестве сочетания клавиш для элемента меню. Обратите внимание, что если вы используете прописную букву, для активации сочетания клавиш потребуется клавиша Shift.
  • indent - Целое число от 0 до 15, указывающее, насколько вправо должен быть отступом элемент меню. По умолчанию 0.
  • onStateImage - Изображение, отображаемое, когда checked имеет значение true или state имеет значение "on". Размер этого изображения ограничен размером, установленным hs.menubar:stateImageSize. Если эта клавиша не установлена, для отмеченных или "включённых" элементов меню будет отображаться галочка.
  • offStateImage - Изображение, отображаемое, когда checked имеет значение false или state имеет значение "off". Размер этого изображения ограничен размером, установленным hs.menubar:stateImageSize. Если эта клавиша не установлена, рядом с элементом меню не отображается специальная метка.
  • mixedStateImage - Изображение, отображаемое, когда state имеет значение "mixed". Размер этого изображения ограничен размером, установленным hs.menubar:stateImageSize. Если эта клавиша не установлена, для элементов меню с состоянием "mixed" будет отображаться тире.

• элемент меню

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

Устанавливает заголовок объекта элемента меню. Заголовок будет отображаться в системном меню.

• title - Строка или объект hs.styledtext для использования в качестве заголовка или nil для удаления заголовка

• элемент меню

• Если вы установили значок и заголовок, они оба будут отображаться рядом друг с другом.
• Не оказывает влияния на отображение всплывающего меню, но изменения вступят в силу, если hs.menubar:returnToMenuBar() будет вызвано для элемента меню.

Устанавливает текст всплывающей подсказки для пункта меню.

• tooltip - Строка, используемая в качестве всплывающей подсказки

• пункт меню

• Не влияет на отображение всплывающего меню, но изменения вступят в силу, если для пункта меню будет вызван hs.menubar:returnToMenuBar().

Получение или установка размера изображений состояния при отображении меню.

• size - необязательная таблица, определяющая размер изображений состояния, отображаемых при использовании ключа checked или state в определении таблицы меню. Значение по умолчанию определяется размером шрифта системного меню. Если вы явно зададите nil, размер будет сброшен до значения по умолчанию.

• если параметр предоставлен, возвращает элемент меню; в противном случае возвращает текущее значение.

• Изображение используется вместо галочки или тире только при установке с использованием ключей onStateImage, offStateImage, или mixedStateImage. Если эти ключи не используются, этот метод не повлияет на отображение меню. Подробнее см. hs.menubar:setMenu.
• Если вы устанавливаете содержимое меню с помощью статической таблицы, вы должны вызвать этот метод перед вызовом hs.menubar:setMenu, так как изменения вступят в силу только при следующем преобразовании таблицы в структуру меню.

Возвращает текущее название пункта меню.

• styled - необязательный булевый параметр, по умолчанию false, указывающий, что должен быть возвращён styledtextObject, представляющий текст заголовка меню

• заголовок пункта меню или пустая строка, если его нет. Если styled не задан или false, возвращается строка; в противном случае возвращается styledtextObject.