Preference Packs/ru

Введение

Пакет настроек — это распространяемый набор пользовательских настроек, который можно установить как дополнение и применить единым набором. Любой параметр пользователя, который можно задать в файле user.cfg, может быть включён в пакет настроек. Применение пакета настроек устанавливает все переменные из предоставленного файла CFG, не изменяя остальных пользовательских настроек. Например, такие пакеты можно использовать для создания "Тем", объединяя пользовательскую таблицу стилей с набором настроек, задающих различные цвета и стили элементов FreeCAD, которые не управляются таблицей стилей.

Основной интерфейс пакетов настроек

Большая часть взаимодействия пользователя с установленными пакетами настроек происходит через вкладку Основные в разделе Общие настройки редактора настроек.

Применение установленного пакета

Чтобы применить пакет настроек, нажмите кнопку Применить рядом с его названием на вкладке Основные в редакторе настроек. Основу пакета настроек составляет набор пользовательских настроек. При применении пакета каждая из этих настроек изменяется на значение, определённое в пакете. При необходимости автор пакета может включить макрос, выполняемый до и/или после применения. Поскольку пакеты могут вносить значительные (и, возможно, нежелательные) изменения в ваши пользовательские настройки, создаётся резервная копия ваших исходных настроек с меткой времени и сохраняется в FREECAD_USER_DATA/SavedPreferencePacks/Backups. Эти резервные копии хранятся в течение одной недели.

Создание нового пакета

Пакеты можно создавать вручную или быстро сформировать с помощью кнопки Сохранить новый... на вкладке Основные в [Preferences_Editor|редакторе настроек]. При нажатии кнопки появляется диалог, запрашивающий имя нового пакета, и отображается набор флажков, позволяющих сохранить только подмножество настроек.

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

Подробности о шаблонах

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

Структура пакета настроек

Хотя основу большинства пакетов настроек составляет один конфигурационный файл, из-за их структуры для распространения также требуется вспомогательная структура. Четыре основных файла определяют пакет, расположенный в следующей структуре каталогов (для пакета настроек с именем "SamplePreferencePack"):

• package.xml
• SamplePreferencePack/
  • SamplePreferencePack.cfg
  • pre.FCMacro
  • post.FCMacro

Файл Метаданные пакета, package.xml, определяет имя пакета настроек и позволяет назначить другие элементы метаданных, такие как номер версии, информация об авторе и теги (которые отображаются в основном пользовательском интерфейсе в виде списка, разделённого запятыми). Для пакета настроек, сохранённого с помощью графического интерфейса, как описано выше, один файл package.xml создаётся в каталоге FREECAD_USER_DATA/SavedPreferencePacks/. Этот файл используется для описания деталей, таких как имя и теги всех пользовательских сохранённых пакетов настроек. Чтобы изменить имя или теги пакета, этот файл необходимо вручную отредактировать в текстовом редакторе. Он также может служить шаблоном для распространяемых пакетов настроек: автор распространяемого пакета может начать с локального сохранения пакета, затем скопировать подкаталог пакета и этот глобальный файл package.xml в качестве отправной точки, изменив скопированный файл package.xml, чтобы он ссылался только на пакет, упаковываемый для распространения.

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

• package.xml
• resources/
  • icons/
    • DarkSide.svg
• DarkSide/
  • DarkSide.cfg
  • DarkSide.qss

Обратите внимание на отсутствие файлов pre.FCMacro и post.FCMacro, которые часто не требуются, а также на включение иконки (для отображения в Менеджере дополнений) и qss-файла (на который затем будет ссылка в файле данных конфигурации DarkSide.cfg).

Файлы макросов pre и post — это стандартные макросы FreeCAD на Python и могут содержать любые команды, допустимые в таком макросе. Если pre.FCMacro генерирует исключение (любого типа), применение пакета настроек отменяется. Если post.FCMacro генерирует исключение (любого типа), применение пакета откатывается с использованием резервной копии, созданной до его применения. Например, эти макросы могут использоваться для запроса у пользователя подтверждения принятия лицензии или для проверки того, что его устраивает конечное состояние системы после применения.

Файл package.xml для этого пакета в качестве примера может выглядеть так:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<package format="1" xmlns="https://wiki.freecad.org/Package_Metadata">
  <name>DarkSide Theme Package</name>
  <description>A preference pack including a stylesheet and other GUI color information for a Dark mode.</description>
  <version>1.0.0</version>
  <maintainer email="chennes@pioneerlibrarysystem.org">Chris Hennes</maintainer>
  <license file="LICENSE">GPLv3</license>
  <url type="repository" branch="main">https://github.com/chennes/DarkSideThemePackage</url>
  <icon>resources/icons/DarkSide.svg</icon>

  <content>
    <preferencepack>
      <name>DarkSide</name>
      <description>Dark mode color scheme</description>
      <tag>color</tag>
      <tag>stylesheet</tag>
      <tag>dark</tag>
      <file>DarkSide.qss</file>
    </preferencepack>
  </content>

</package>

Включение шаблонов в ваше дополнение

Многие дополнения имеют настраиваемую пользователем информацию о параметрах, которая добавляется в файл user.cfg. Автор дополнения также может предоставить файл шаблона пакета настроек, который перечисляет переменные конфигурации пользователя, которые могут быть автоматически сохранены с помощью метода "Save new pack", описанного выше. Чтобы включить эти файлы шаблонов, авторы дополнений должны создать подкаталог в своём пакете с именем "PreferencePackTemplates" или "preference_pack_templates". В этой папке должен находиться один или несколько файлов *.cfg: каждый должен быть допустимым, правильно сформированным XML-файлом user.cfg, содержащим одну или несколько переменных конфигурации, установленных в их значения по умолчанию. Имя файла должно отражать его назначение, например "colors.cfg", "active_tabs.cfg" и т.д. Этот набор файлов будет представлен пользователю при сохранении нового пакета настроек, при этом каждый файл получит проверяемую запись в списке элементов для сохранения. Имя файла используется для генерации записи пользовательского интерфейса, при этом подчёркивания заменяются пробелами (а расширение опускается).

Распространение пакета

Пакеты настроек распространяются так же, как Внешние верстаки через Менеджер дополнений. Для ручной установки пакета используйте git для клонирования репозитория пакета в ваш каталог данных FreeCAD (введите App.getUserAppDataDir() в консоли Python, чтобы получить этот путь) в подкаталог с именем "Preference Packs". Обратите внимание, что пакеты, установленные пользователем, с тем же именем, что и встроенные, имеют приоритет.

См. также Личные пакеты настроек.