Миграция проектов для использования новых тем в 1.19.0.0
By Yaroslav Brovin in Общая
· 507 views
Добрый день,
В ближайшее время выйдет большой релиз 1.19.0.0, который полностью будет посвящен большим изменения в работе с темами приложения, упростит ваш код и сделает управлением темами удобнее и понятнее.
Предварительно мы разработали полное руководство по темам:
Обязательно прочитайте это руководство, потому что в этой теме будет затронута только миграции проектов на 1.19.0.0.
Внимание: В данном релизе 1.19.0.0 введены изменения, которые ломают совместимость проектов этой версии со старыми версиями. Поэтому переход на 1.19.0.0 является необратимым. Перед тем, как открыть ваш проект необходимо ОБЯЗАТЕЛЬНО сделать резервную копию на случай необходимости временного возврата к предыдущим версиям.
Новый ресурс - тема
Не смотря на то, что есть несколько статей о том, как настраивать темы и как их использовать, концепция темы не была до конца закончена. Связано это прежде всего было с тем, что как таковой сущности "тема" в FGX Native не существовало до 1.19.0.0. Это создавало внутренние трудности в реализации FGX Native и требовало использовать не всегда очевидные подходы в определении, что есть тема в FGX Native.
Вы можете возразить, что понятие темы существует уже много лет. Однако, ответ очень прост. Вы никаким способом не можете определить программно до текущего релиза, названия тем приложения. Именно это и является камнем преткновения.
Теперь мы ввели полноценное понятие темы. При открытии старого проекта в 1.19.0.0 мигратор автоматически создает сущность темы на основании ваших ресурсов для каждой потенциальной темы.
Тема обозначается специальным значком. Тему можно добавить одним из трех способов:
(1) Сгенерировать тему (по старому способу). Контекстное меню дерева ресурсов -> "Сгенерировать тему".
(2) Добавить пустую тему. Все ресурсы темы вы должны добавить самостоятельно по вашему усмотрению. Контекстное меню дерева ресурсов -> "Добавить тему".
В этом случае создается пустая тема без какого-либо ресурса. Все необходимые ресурсы вы должны добавить туда самостоятельно.
(3) Сконвертировать каталог с ресурсами в тему. Контекстное меню дерева ресурсов -> "Конвертировать в тему".
Как только тема добавлена в менеджере ресурсов, так сразу вы можете ее использовать ее в вашем приложении. Темы могут располагаться в любом месте, в том числе во вложенных папках.
Доступ к темам
На уровне TfgAssetsManager добавлен новый метод, позволяющий получить список тем:
/// <summary>Возвращает названия всех доступных тем.</summary>
function GetThemesNames: TArray<TfgThemeName>;Применение темы
Теперь тема может быть применена на уровне приложения без необходимости указывать ее на уровне каждой формы. Для этого добавлено новое свойство Application.ThemeSettings. Новые объект позволяет указать светлую и темную темы через свойства:
/// <summary>Название светлой темы FGX Native, используемой по умолчанию во всех формах.</summary>
property LightThemeName: TfgThemeName read FLightThemeName write SetLightThemeName;
/// <summary>Название темной темы FGX Native, используемой по умолчанию во всех формах.</summary>
property DarkThemeName: TfgThemeName read FDarkThemeName write SetDarkThemeName;За выборе темы при старте приложения отвечает свойство
/// <summary>Применяемая тема по умолчанию.</summary>
/// <remarks>
/// Если приложение не поддерживает темную тему (Темная тема не включена в настроках проекта), то вид темы
/// будет всегда <c>Light</c>.
/// </remarks>
property ThemeKind: TfgThemeKind read FThemeKind write SetThemeKind;Теперь вы можете указать, чтобы тема автоматически была согласована с системной темой устройства, либо же принудительно применить светлую или темную тему.
Основным способом указания темы, является появление нового окна настроек Project -> FGX Options... -> Приложение -> Темы
Помимо задания темы на уровне приложения, вы так же можете указывать ее на уровне формы, если по каким-то причинам, вы хотите использовать другой вариант темы на какой-то форме.
Использование файла Assets.Consts
Начиная с 1.19.0.0 изменена логика генерации файла констант с именами ресурсов.
В этом релизе мы провели унификацию названий полей.
R.Fonts->R.FontR.Images->R.ImageR.LottieAnimations->R.LottieAnimationR.Files->R.&File
Так же теперь R.Theme не возвращает ресурсы текущей темы. За это отвечает новое поле R.CurrentTheme, которое возвращает имя ресурса темы в зависимости от теущей темы приложения. Таким образом, вам больше не нужно вручную динамически формировать имя ресурса в зависимости от светлой или темной темы.
R.Theme теперь выдает доступ ко всем темам приложения.
TfgCurrentTheme = record
/// <summary>Identifiers with current theme colors assets.</summary>
class var Color: TfgThemeColors;
end;
TfgThemes = record
class var ThemeDark: TfgThemeThemeDark;
class var ThemeLight: TfgThemeThemeLight;
end;
/// <summary>Identifiers with current theme assets.</summary>
class var CurrentTheme: TfgCurrentTheme;
/// <summary>Identifiers with themes names.</summary>
class var Theme: TfgThemes;Использование ресурсов темы
Теперь, при использовании ресурсов темы допускается два способа указания имени:
Адаптированное имя под текущую тему. Если вы хотите, чтобы при смены темы, используемый ресурс так же брался из новой темы, то в качестве разделителя названия темы и ресурса нужно использовать ":".
Например: "Themes\Light\Green:Background".Фиксированное имя. Если вы не хотите изменения названия ресурса темы при смене темы, то используйте старый способ указания имени "Themes\Light\Green\Background".
Миграция
Важно: Перед выполнением миграции вашего проекта ОБЯЗАТЕЛЬНО сделать резервную копию проекта, чтобы в случае чего можно было откатиться обратно.
Чтобы облегчить миграцию ваших проектов для поддержки новых тем, мы разработали мастер, который поможет автоматически выявить все места использования ресурсов тем.
Мастер:
Распознает все свойства (из библиотеки), связанные с ресурсами.
Извлекает текущее значение имени ресурса.
Для DFM/XFM файлов форм и фреймов проверяет имя ресурса на предмет принадлежности темы - вхождение слова "Theme" (без учета регистра). Если у вас в названии темы не фигурирует слово "Theme", пожалуйста, сообщите в комментариях под этой статьёй.
Для обнаруженных имен ресурсов (только для XFM) автоматически формирует новое имя с учетом нового синтаксиса и предлагает автоматическую замену .
При открытии старого проекта автоматически запускается миграция проекта на новую версию, в рамках чего будет отображен мастер только если в вашем проекте будут найдены потенциальные места использования ресурсов из тем.
Важно: Мастер сканирует только файлы добавленные в проект напрямую. Другими словами, все файлы, которые используются в проекте, но не добавлены в него анализироваться не будут.
Адаптация DFM/XFM файлов
Если вы не хотите применять предложенное изменение, снимите галку напротив строки с предложенным изменение в левом дереве. Мы применили наш мастер на все демонстрационные проекты, а так же проверили его на наших больших демонстрационных проектах с вебинаров. Ошибок в адаптации найдено не было.
Допускаем, что какие-то варианты могут быть не учтены, поэтому, важно делать резервные копии. По умолчанию мы создаем копию затрагиваемых оригинальных файлов и добавляем окончание ".backup". Если вы уверены в предложенных изменения, вы можете отключить резервные копии файлов через снятия галки чекбокса в футере окна.
Адаптация PAS файлов
Отдельно изучите найденные изменения в PAS файле и выполните адаптацию самостоятельно. Поскольку вариантов формирования имени ресурса из темы большое количество и ограничено только вашей фантазией, мы не можем корректно проанализировать ваш код, но можем предположительно найти только потенциальные места, где идет программное изменение свойств, затрагивающих работу с названием ресурсов.
Вот несколько советов, которые вам помогут:
Если вы используете константы из файла
Assets.Consts.R, то в этом релизе мы провели унификацию названий полей. Если вы используете программный доступ к этим ресурсам, переименуйте их согласно схеме выше.R.Fonts->R.FontR.Images->R.ImageR.LottieAnimations->R.LottieAnimationR.Files->R.&File
Изменена логика использования
R.Theme. Теперь она содержит не ресурсы текущей темы, а все темы приложения, с возможностью получить доступ к ресурсам каждой темы. Если вы используете в проектаR.Theme, вам необходимо его заменить наR.CurrentTheme.
Важно: Адаптацию pas файлов нужно выполнить самостоятельно.
TfgControl.UpdateTheme
В некоторых проектах используется метод TfgControl.UpdateTheme, который был добавлен для временного решения проблемы с применением тем при динамическом встраивании компонентов и фреймов
В новой версии 1.19.0.0 этого метода больше нет, так как теперь адаптация применения темы выполняется библиотекой самостоятельно. Поэтому вам НЕ ТРЕБУЕТСЯ больше вызывать этот метод. Поэтому удалите использование этого метода из вашего проекта.
Дизайнер формы
В этом релизе так же добавлена возможность быстрого переключения тем вашего приложения в дизайнере формы. Таким образом вы можете в одно нажатие посмотреть, как выглядит форма в темной или светлой темах. Для этого воспользуйтесь новыми кнопками переключения темы на панели инструментов в дизайнере формы:
При переключении темы для формы меняется выбранная тема по умолчанию. А именно, светлая или темная тема берется из настроек проекта. Поэтому, чтобы это переключение сработало нужно:
Темная и светлая темы были добавлены в дизайнере ресурсов
Темная и светлая темы были указаны в настройках проекта.
Если оба условия не выполнены, то переключение тем никак не приведет к изменению отображени
Так же мы обновили дизайнер выбора ресурса. Теперь он открывается в отдельном окне.
Если ресурс применяется из темы, то в его имени используется ":", как разделитель названия темы и ресурса внутри него.
Помимо этого мы мы добавили ряд небольших изменений в сам дизайнер формы, которые, возможно, вам пригодятся.
(1) Теперь при выделении компонента, отображается его имя и размер. А при перетаскивании имя теперь не выводится.
Если вы нехотите, чтобы выводился размер или название. Вы можете отключить это поведение в общих настройках среды: Tools -> Options -> Third Party -> Form Designer
(2) Добавлена возможность быстрого переключения формы в текстовый режим. Теперь при нажатии на кнопку "Как текст", дизайнер переключиться на режим отображения текста формы.
(3) Теперь режим отображения сетки, границ компонентов, темы, стиля и тд. синхронизируется между дизайнерами форм. И например отображение сетки в одной форме приводит к отображению сетки на всех формах.
Заключение
Если в ходе миграции или проверки ваших приложений на 1.19.0.0 вы столкнулись с трудностями или у вас есть предложения, пожалуйста, дайте нам знать.
-
1
Recommended Comments