diff --git a/src/content/release/breaking-changes/deprecate-focusable.md b/src/content/release/breaking-changes/deprecate-focusable.md new file mode 100644 index 0000000000..ed51a3a11a --- /dev/null +++ b/src/content/release/breaking-changes/deprecate-focusable.md @@ -0,0 +1,98 @@ +--- +title: Deprecate `SemanticsProperties.focusable` and `SemanticsConfiguration.isFocusable` +description: > + The `focusable` parameter has been replaced by `isFocused`. +--- + +## Summary + +The `SemanticsProperties.focusable` and `SemanticsConfiguration.isFocusable` +parameters were deprecated in favor of the `SemanticsProperties.focused` and +`SemanticsConfiguration.isFocused` parameters. + +## Context + +The `SemanticsConfiguration.isFocusable` is a boolean to describe +whether the semantics node can have input focus, and +`SemanticsConfiguration.isFocused` is a boolean to describe if the +semantics node has input focus. + +The fix is the same with `SemanticsProperties.focusable` and `SemanticsProperties.focused`. + +## Description of change + +The `SemanticsConfiguration.isFocusable` is deprecated in +favor of `SemanticsConfiguration.isFocused`, which is a nullable boolean; +setting it to true/false automatically sets `isFocusable` to `true`, +and setting it to null sets `isFocusable` to `false`. + +## Migration guide + +Replace `SemanticsConfiguration.isFocusable` with `SemanticsConfiguration.isFocused`. + +### Example 1: setting `isFocused` to `true` automatically sets `isFocusable` to `true`. + +Code before migration: + +```dart +void describeSemanticsConfiguration(SemanticsConfiguration config) { + config.isFocusable = true; + config.isFocused = true; +} +``` + +Code after migration: + +```dart +void describeSemanticsConfiguration(SemanticsConfiguration config) { + config.isFocused = true; +} +``` + +### Example 2: setting `isFocused` to null automatically sets `isFocusable` to `false`. + +Code before migration: + +```dart +void describeSemanticsConfiguration(SemanticsConfiguration config) { + config.isFocusable = false; + config.isFocused = false; +} +``` + +Code after migration: + +```dart +void describeSemanticsConfiguration(SemanticsConfiguration config) { + config.isFocused = null; +} +``` + + +## Timeline + +Landed in version: Not yet
+In stable release: Not yet + + +## References + +API documentation: + +* [`SemanticsConfiguration`][] +* [`SemanticsProperties`][] +* [`SemanticsNode`][] + +Relevant issue: + +* [Issue 166092][] + +Relevant PR: + +* [PR 170935][] + +[`SemanticsConfiguration`]: {{site.api}}/flutter/semantics/SemanticsConfiguration-class.html +[`SemanticsProperties`]: {{site.api}}/flutter/semantics/SemanticsProperties-class.html +[`SemanticsNode`]: {{site.api}}/flutter/semantics/SemanticsNode-class.html +[Issue 166101]: {{site.repo.flutter}}/issues/166101 +[PR 168703]: {{site.repo.flutter}}/pull/170935 diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index a1cd297c20..642bdd2c4b 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -48,6 +48,7 @@ They're sorted by release and listed in alphabetical order: * [Stop generating `AssetManifest.json`][] * [UISceneDelegate adoption][] * [Component theme normalization updates][] +* [Deprecate `SemanticsProperties.focusable` and `SemanticsConfiguration.isFocusable`][] [Redesigned the Radio Widget]: /release/breaking-changes/radio-api-redesign [Removed semantics elevation and thickness]: /release/breaking-changes/remove-semantics-elevation-and-thickness @@ -55,6 +56,7 @@ They're sorted by release and listed in alphabetical order: [Stop generating `AssetManifest.json`]: /release/breaking-changes/asset-manifest-dot-json [UISceneDelegate adoption]: /release/breaking-changes/uiscenedelegate [Component theme normalization updates]: /release/breaking-changes/component-theme-normalization-updates +[Deprecate `SemanticsProperties.focusable` and `SemanticsConfiguration.isFocusable`]: /release/breaking-changes/deprecate-focusable ### Released in Flutter 3.32