AccentManager (Менеджер ударений)

Обзор

Дополнение Accent Manager для NVDA предоставляет удобный способ ввода символов с ударениями без использования международной раскладки Windows, которая может быть неудобной и приводить к случайным изменениям раскладки. Это дополнение особенно полезно для ввода имён и слов с ударениями на различных языках.

Возможности

• Вставка символов с ударениями (акут, тильда, гравис) для распространённых гласных и буквы “n”.
• Переключение между типами ударений с помощью горячих клавиш.
• Переключение между заглавными и строчными символами с ударениями.
• Многоуровневый ввод: выбор типа ударения, затем ввод символа для добавления ударения.
• Обратная связь через речь NVDA для действий и ошибок.
• Буферизация: создание строки символов с ударениями перед отправкой.
• Удаление последнего символа из буфера.

Инструкция по использованию

1. Активация Accent Manager

   • Нажмите NVDA + / (клавиша NVDA и слэш), чтобы войти в режим Accent Manager.

2. Выбор типа ударения

   • Используйте Стрелку вверх и Стрелку вниз для переключения между типами ударений:
   • Акут (например, á, é, í)
   • Тильда (например, ã, ñ, õ)
   • Гравис (например, à, è, ì)

3. Переключение регистра

   • Нажмите NVDA + c, чтобы переключиться между заглавными и строчными символами с ударениями.

4. Вставка символов с ударениями

   • Введите букву, которую нужно снабдить ударением (a, e, i, n, o, u). Соответствующий символ с ударением будет добавлен в буфер.
   • Если комбинация ударения и буквы недопустима, NVDA произнесёт “invalid”.

5. Удаление последнего символа

   • Нажмите Backspace, чтобы удалить последний символ из буфера.

6. Отправка символов с ударениями

   • При выходе из режима Accent Manager нажатием клавиши Escape буфер отправляется в приложение с использованием эмуляции ввода шрифтом Брайля. Это также происходит, если фокус уходит с виртуального интерфейса.

Пример работы

1. Нажмите NVDA + /, чтобы активировать Accent Manager.
2. Используйте Стрелку вниз, чтобы выбрать “тильду”.
3. Нажмите n, чтобы добавить “ñ” в буфер.
4. Нажмите NVDA + c, чтобы включить заглавные буквы, затем a, чтобы добавить “Ô.
5. Нажмите Backspace, чтобы удалить последний символ, если это необходимо.
6. Уберите фокус или завершите работу, чтобы отправить буфер в приложение.

Поддерживаемые символы

Заглавные версии доступны при включённом режиме заглавных букв.

Установка

1. Загрузите последний файл .nvda-addon из раздела релизов.
2. В NVDA откройте меню “Сервис” > “Управление дополнениями”.
3. Нажмите “Установить…” и выберите загруженный файл.
4. Перезапустите NVDA при запросе.

Лицензия

Информацию о лицензии см. в файле COPYING.txt.

Поддержка

По вопросам или проблемам, пожалуйста, создайте issue в репозитории или свяжитесь с автором.

• Автоматическое создание пакета дополнения с именем и версией, загруженными из централизованного файла переменных сборки (buildVars.py) или через интерфейс командной строки.
  • Подробности об использовании параметров командной строки при упаковке дополнений с пользовательской информацией о версии см. в разделе упаковки.
  • Этот процесс будет выполняться автоматически при получении pull request, а также есть возможность ручного запуска.
  • Чтобы workflow запускался автоматически при пуше в ветки main или master (разработка), удалите комментарий для строки branches в GitHub Actions (.github/workflows/build_addon.yml).
  • Если вы создали тег (например: git tag v1.0 && git push --tag), то релиз будет создан автоматически, а файл дополнения будет загружен как ассет.
  • В противном случае, при обычных коммитах или ручном запуске, вы можете загрузить артефакты со страницы Actions вашего репозитория.
• Создание манифест-файла с использованием шаблона (manifest.ini.tpl). Переменные сборки заменяются в этом шаблоне. См. ниже спецификацию манифеста дополнения.
• Компиляция gettext mo файлов перед распространением, если требуется.
  • Для создания gettext pot файла выполните команду scons pot. Будет создан файл addon-name.pot со всеми сообщениями gettext для вашего дополнения. Убедитесь, что переменная buildVars.i18nSources соответствует вашим требованиям.
• Автоматическое создание файлов локализации манифеста напрямую из gettext po файлов. Убедитесь, что buildVars.py включён в i18nFiles.
• Автоматическое создание HTML документов из markdown (.md) файлов для управления документацией на разных языках.

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

• Ruff (pyproject.toml/tool.ruff разделы): линтер для Python, написанный на Rust. Разделы, начинающиеся с tool.ruff, содержат параметры конфигурации для Ruff.
• Конфигурация для VS Code. Требуется, чтобы репозиторий NVDA находился на том же уровне, что и папка дополнения, содержащая ваши исходные файлы, с подготовленным исходным кодом (scons source). Подготовка исходного кода — это шаг в инструкциях по сборке NVDA, см. Репозиторий NVDA для подробностей.
  • Поместите папку .vscode из этого репозитория в папку дополнения, где находятся ваши исходные файлы дополнения. Файл настроек в этой папке предполагает, что репозиторий NVDA находится в родительской папке этой папки. Если ваша папка дополнения находится внутри папки addonTemplate, то папка репозитория NVDA также должна находиться внутри папки addonTemplate, иначе исходный код не будет найден.
  • Откройте папку дополнения в VS Code. Это должно инициализировать VS Code с правильными настройками и предоставить вам автодополнение кода и другие функции VS Code.
  • Нажмите control+shift+m после сохранения файла, чтобы найти проблемы.
  • Используйте стрелки и клавишу Tab для функции автодополнения.
  • Нажмите control+shift+p, чтобы открыть палитру команд и найти рекомендуемые расширения для установки или проверки их установки.
• Pyright (pyproject.toml/tool.pyright разделы): статический анализатор типов для Python. Разделы, начинающиеся с tool.pyright, содержат параметры конфигурации для Pyright.

Требования

Для использования этого кода при разработке и упаковке дополнений NVDA вам потребуется следующее программное обеспечение:

• Дистрибутив Python (рекомендуется версия 3.11 или новее). Проверьте сайт Python для установщиков Windows. Обратите внимание, что в настоящее время подготовка исходного кода NVDA требует 32-битной версии Python 3.11, а 64-битная версия планируется.
• Scons - Сайт - версия 4.9.1 или новее. Можно установить через PIP.
• Инструменты GNU Gettext, если требуется поддержка локализации для вашего дополнения — рекомендуется. Любой дистрибутив Linux или Cygwin уже имеет их. Windows-сборки можно найти здесь.
• Markdown 3.8 или новее, если требуется конвертировать файлы документации в HTML документы. Можно установить через PIP.
• Опционально: дополнительные инструменты, такие как линтеры и анализаторы типов, определённые в файле pyproject.toml.

Обратите внимание, что эти инструменты могут не понадобиться в локальной среде сборки, если вы используете Appveyor или GitHub Actions для сборки и упаковки дополнений.

Использование

Для создания нового дополнения NVDA с использованием этого шаблона:

1. Создайте пустую папку для хранения файлов вашего дополнения.
2. Скопируйте папку:

site_scons

и следующие файлы в новую пустую папку:

buildVars.py
manifest.ini.tpl
manifest-translated.ini.tpl
sconstruct
.gitignore
.gitattributes

3. Если вы планируете использовать предоставленный GitHub workflow, также скопируйте папку:

.github

и файл:

.pre-commit-config.yaml

4. Создайте папку addon внутри вашей новой папки. Вы поместите свой код в обычные папки для расширений NVDA внутри папки addon. Например: globalPlugins, synthDrivers и т.д.
5. В файле buildVars.py измените переменную addon_info на информацию о вашем дополнении (имя, описание, версия, автор, URL, исходный URL, лицензия и URL лицензии). Также обязательно тщательно задайте пути, указанные в других переменных этого файла. Если вам нужно использовать пользовательские расширения Markdown, исходный язык интерфейса дополнения не английский или включить пользовательские таблицы перевода Брайля, обязательно заполните список markdown, переменную базового языка и словарь таблиц Брайля соответственно.
6. Переводы Gettext должны быть помещены в addon\locale\<язык>/LC_MESSAGES\nvda.po.

Спецификация манифеста дополнения

Манифест дополнения, созданный вручную или через buildVars.py, должен включать следующую информацию:

• Имя (строка): уникальный внутренний идентификатор дополнения. Должен использовать camel case (например, someModule). Также используется в магазине дополнений для уникальной идентификации.
• Краткое описание (строка): имя, отображаемое в магазине дополнений NVDA.
• Описание (строка): краткое детализированное описание дополнения.
• Версия (строка), желательно в формате число.число с опциональным третьим числом, обозначающим major.minor.patch.
• Журнал изменений (строка): изменения между предыдущими и текущими релизами дополнения.
• Автор (строка и email адрес): контактная информация одного или нескольких авторов дополнения в формате “имя ”.
• URL (строка): веб-адрес, где можно найти информацию о дополнении, например, репозиторий.
• docFileName (строка): имя файла документации.
• minimumNVDAVersion (год.мажор или год.мажор.минор): самая ранняя версия NVDA, с которой совместимо дополнение (например, 2019.3). Ожидается, что дополнения используют функции, введённые в этой версии NVDA, или объявляют совместимость с ней.
• lastTestedNVDAVersion (год.мажор или год.мажор.минор): последняя или последняя протестированная версия NVDA, с которой дополнение совместимо (например, 2020.3). Авторы дополнений должны объявлять это значение после тестирования дополнений с указанной версией NVDA.
• addon_updateChannel (строка или None): канал обновлений для релиза дополнения.

Кроме того, следующая информация должна быть заполнена (не используется в манифесте, но используется в других местах, например, в магазине дополнений) в buildVars:

• sourceURL (строка): URL репозитория исходного кода дополнения.
• license (строка): лицензия дополнения и его исходного кода.
• licenseURL: URL файла лицензии.

Пользовательская информация дополнения

В дополнение к основной информации манифеста можно указать пользовательскую информацию о дополнении.

Таблицы перевода Брайля

Информация о пользовательских таблицах Брайля должна быть указана в buildVars в словаре brailleTables следующим образом:

• Имя таблицы (строковый ключ для вложенного словаря): каждая запись brailleTables — это имя файла для включённой пользовательской таблицы Брайля, помещённой в папку brailleTables внутри папки addon. Этот вложенный словарь должен указывать:
  • displayName (строка): имя таблицы, отображаемое пользователям и переводимое.
  • contracted (True/False): является ли эта таблица сокращённой (True) или несокращённой (False).
  • output (True/False): таблица может быть указана в списке выходных таблиц в настройках Брайля NVDA.
  • input (True/False): Брайль можно вводить с использованием этой таблицы, и она будет указана в списке входных таблиц в настройках Брайля NVDA.

Примечание: вы должны заполнить этот словарь, если в дополнении включена хотя бы одна пользовательская таблица Брайля. Если нет, оставьте словарь пустым.

Словари символов речи

Информация о пользовательских словарях символов должна быть указана в buildVars в словаре symbolDictionaries следующим образом:

• Имя словаря (строковый ключ для вложенного словаря): каждая запись symbolDictionaries — это имя для включённого пользовательского словаря символов, помещённого в папку locale\<язык> внутри папки addon. Файл называется symbols-<имя_словаря>.dic. Этот вложенный словарь должен указывать:
  • displayName (строка): имя словаря, отображаемое пользователям и переводимое.
  • mandatory (True/False): Всегда включён (True) или опционален и виден в GUI (False).

Примечание: вы должны заполнить этот словарь, если в дополнении включён хотя бы один пользовательский словарь символов. Если нет, оставьте словарь пустым.

Для управления файлами документации вашего дополнения:

1. Скопируйте файл readme.md для вашего дополнения в первую созданную папку, куда вы скопировали buildVars.py. Вы также можете скопировать style.css, чтобы улучшить представление HTML документов.
2. Файлы документации (именованные readme.md) должны быть помещены в addon\doc\<язык>/.

Для упаковки дополнения для распространения:

1. Откройте командную строку, перейдите в папку с файлом sconstruct (обычно корневая папка вашего проекта дополнения) и выполните команду scons. Созданное дополнение, если не было ошибок, будет помещено в текущую директорию.
2. Вы можете дополнительно настроить переменные в файле buildVars.py.
3. Вы также можете настроить информацию о версии и канале обновлений из командной строки, передав следующие параметры при запуске scons:
   • version: строка версии дополнения в формате мажор.минор или мажор.минор.патч (все числа).
   • channel: канал обновлений (не используйте этот параметр, если не уверены в своих действиях).
   • dev: подходит для сборок разработки, называет дополнение согласно текущей дате (yyyymmdd) и устанавливает канал обновлений в “dev”.

Дополнительные инструменты

Шаблон включает конфигурационные файлы для использования с дополнительными инструментами, такими как линтеры. К ним относятся:

• Ruff: линтер для Python, написанный на Rust (0.4.10 или новее, можно установить через PIP).
• Pyright: статический анализатор типов для Python (1.1.402 или новее, можно установить через PIP).

Прочитайте документацию для инструментов, которые вы хотите использовать при сборке и разработке дополнений.

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

Если у вас есть какие-либо вопросы, пожалуйста, используйте список дополнений NVDA, упомянутый выше.