Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create migration guide for BoxDecoration.shape #7704

Closed
wants to merge 3 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
101 changes: 101 additions & 0 deletions src/release/breaking-changes/boxdecoration-shape-migration.md
@@ -0,0 +1,101 @@
---
title: Migration guide for BoxDecoration.circle
description: Removal of BoxDecoration.circle and how to migrate
---

## Summary

The `shape` parameter of `BoxDecoration` has been deprecated. Existing uses
of `BoxDecoration(shape: BoxShape.circle)` should use
`ShapeDecoration(shape: CircleBorder())` instead.

## Context

The enum property `BoxShape shape` from `BoxDecoration` has been deprecated,
as increasing the number of supported shapes through enums created
unnecessary complexity and performance costs.
Users should migrate to use `ShapeDecoration` in conjunction with
`ShapeBorder`, the replacement for `BoxShape`.

## Description of change

Remove `BoxDecoration(shape: BoxShape.circle)` and `BoxDecoration.shape`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What should the user replace it with? Are there other cases of using BoxShape that users may need to migrate?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No because we are not changing InkWell.


- Replace `BoxDecoration(shape: BoxShape.circle)` with
`ShapeDecoration(shape: CircleBorder())`.
- Remove the `BoxDecoration.shape` property from
`BoxDecoration(shape: BoxShape.rectangle)`.
bernaferrari marked this conversation as resolved.
Show resolved Hide resolved

## Migration guide

When you use `Border`,
`CircleBorder(width: ..., color: ..., strokeAlign: ...)` inherits
the `Border.all(width: ..., color: ..., strokeAlign: ...)` values.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure where this fits into the context of this guide. Can you explain more?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you have BoxDecoration(shape: BoxShape.circle, border: Border.all(width: 20), this becomes now ShapeDecoration(shape: CircleBorder(side: BorderSide(width: 20))). In this scenario, Border becomes BorderSide.


Code before migration:

<!-- skip -->
```dart
BoxDecoration(
shape: BoxShape.circle,
)

BoxDecoration(
shape: BoxShape.circle,
border: Border.all(width: 20, color: Colors.red),
boxShadow: [],
)

BoxDecoration(
shape: BoxShape.rectangle,
)
```

Code after migration:

<!-- skip -->
```dart
ShapeDecoration(
border: CircleBorder(),
)

ShapeDecoration(
border: CircleBorder(width: 20, color: Colors.red),
shadows: [],
)

BoxDecoration()
```

## Timeline

Landed in version: TBD<br>
In stable release: not yet

## References

{% include docs/master-api.md %}

API documentation:

* [`BoxDecoration` stable][]
* [`BoxDecoration` main][]

Relevant issues:

* [Deprecate `BoxDecoration.shape` issue][]

Relevant PRs:

* [Deprecate `BoxDecoration.shape` PR][]

<!-- Stable channel link: -->
[`BoxDecoration` stable]: {{site.api}}/flutter/lib/src/painting/BoxDecoration-class.html

<!-- Master channel link: -->
{% include docs/master-api.md %}

[`BoxDecoration` main]: {{site.master-api}}/flutter/lib/src/painting/BoxDecoration-class.html

[Deprecate `BoxDecoration.shape` issue]: {{site.repo.flutter}}/issues/108051
[Deprecate `BoxDecoration.shape` PR]: {{site.repo.flutter}}/pull/108052
1 change: 1 addition & 0 deletions src/release/breaking-changes/index.md
Expand Up @@ -28,6 +28,7 @@ release, and listed in alphabetical order:
[Deprecated API removed after v3.3]: {{site.url}}/release/breaking-changes/3-3-deprecations
[ThemeData's toggleableActiveColor property has been deprecated]: {{site.url}}/release/breaking-changes/toggleable-active-color
[iOS FlutterViewController splashScreenView made nullable]: {{site.url}}/release/breaking-changes/ios-flutterviewcontroller-splashscreenview-nullable
[Deprecate BoxDecoration.shape]: {{site.url}}/release/breaking-changes/boxdecoration-shape-migration.md

### Released in Flutter 3.3

Expand Down