Skip to content

Commit

Permalink
Add Android 14 nonlinear font scaling migration guide (#9425)
Browse files Browse the repository at this point in the history
## Presubmit checklist

- [ ] This PR doesn’t contain automatically generated corrections
(Grammarly or similar).
- [ ] This PR follows the [Google Developer Documentation Style
Guidelines](https://developers.google.com/style) — for example, it
doesn’t use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first person).
- [ ] This PR uses [semantic line
breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks)
of 80 characters or fewer.

---------

Co-authored-by: Anthony Sansone <atsansone@users.noreply.github.com>
  • Loading branch information
LongCatIsLooong and atsansone authored Sep 28, 2023
1 parent 7fa68b1 commit 000cfe9
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 0 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
title: Android 14 nonlinear font scaling enabled after v3.14
description: >
New Android 14 nonlinear font scaling feature is enabled in Flutter after v3.14.
---

## Summary

Android 14 introduced nonlinear font scaling up to 200%.
It may change how your app looks when the user changes
the accessibility text scaling in system preferences.

## Background

The [Android 14 nonlinear font scaling][] feature prevents excessive accessibility
font scaling by scaling larger text at a lesser rate when the user increases the
text scaling value in system preferences.

## Migration guide

As the [Android 14 feature overview][Android 14 nonlinear font scaling] suggests,
test your UI with the maximum font size enabled (200%).
This should verify that your app can apply the font sizes correctly
and can accommodate larger font sizes without impacting usability.

To adopt nonlinear font scaling in your app and custom widgets,
consider migrating from `textScaleFactor` to `TextScaler`.
This migration guide outlines the process:
[Deprecate `textScaleFactor` in favor of `TextScaler`][], .

**Temporarily Opting Out**
To opt-out of nonlinear text scaling on Android 14 until you migrate your app,
add a modified `MediaQuery` at the top of your app's widget tree:

```dart
runApp(
Builder(builder: (context) {
final mediaQueryData = MediaQuery.of(context);
final mediaQueryDataWithLinearTextScaling = mediaQueryData
.copyWith(textScaler: TextScaler.linear(mediaQueryData.textScaler.textScaleFactor));
return MediaQuery(data: mediaQueryDataWithLinearTextScaling, child: realWidgetTree);
}),
);
```
This uses the deprecated `textScaleFactor` API.
It will stop working once that API is removed from the Flutter API.

## Timeline

Landed in version: 3.14.0-11.0.pre<br>
In stable release: not yet (Not in 3.13)

## References

API documentation:

* [`TextScaler`][]

Relevant issues:

* [New font scaling system (Issue 116231)][]

Relevant PRs:

* [Implementing TextScaler for nonlinear text scaling][]

Seealso:

* [Deprecate `textScaleFactor` in favor of `TextScaler`][]

[Android 14 nonlinear font scaling]: https://developer.android.com/about/versions/14/features#non-linear-font-scaling
[Deprecate `textScaleFactor` in favor of `TextScaler`]: {{site.url}}/release/breaking-changes/deprecate-textscalefactor
[`TextScaler`]: {{site.master-api}}/flutter/painting/TextScaler-class.html
[New font scaling system (Issue 116231)]: {{site.repo.flutter}}/issues/116231
[Implementing TextScaler for nonlinear text scaling]: {{site.repo.engine}}/pull/44907
2 changes: 2 additions & 0 deletions src/release/breaking-changes/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ release, and listed in alphabetical order:

* [Customize tabs alignment using the new `TabBar.tabAlignment` property][]
* [Deprecate `textScaleFactor` in favor of `TextScaler`][]
* [Android 14 nonlinear font scaling enabled after v3.14][]
* [Deprecate TextField.canRequestFocus][]
* [Deprecate `describeEnum` and update `EnumProperty` to be type strict][]
* [Deprecated just-in-time navigation pop APIs for Android Predictive Back][]
Expand All @@ -44,6 +45,7 @@ release, and listed in alphabetical order:

[Customize tabs alignment using the new `TabBar.tabAlignment` property]: {{site.url}}/release/breaking-changes/tab-alignment
[Deprecate `textScaleFactor` in favor of `TextScaler`]: {{site.url}}/release/breaking-changes/deprecate-textscalefactor
[Android 14 nonlinear font scaling enabled after v3.14]: {{site.url}}/release/breaking-changes/android-14-nonlinear-text-scaling-migration
[Deprecate TextField.canRequestFocus]: {{site.url}}/release/breaking-changes/can-request-focus
[Deprecate `describeEnum` and update `EnumProperty` to be type strict]: {{site.url}}/release/breaking-changes/describe-enum
[Deprecated just-in-time navigation pop APIs for Android Predictive Back]: {{site.url}}/release/breaking-changes/android-predictive-back
Expand Down

0 comments on commit 000cfe9

Please sign in to comment.