Repository navigation
docs: Document CupertinoSlidingSegmentedControl translucent unselected segments (#164073) - #186645
Closed
NadeemIqbal wants to merge 6 commits into
Closed
NadeemIqbal wants to merge 6 commits into
NadeemIqbal wants to merge 6 commits into
Conversation
…d segments The default backgroundColor (CupertinoColors.tertiarySystemFill) is translucent (alpha 0.12 in light mode), matching the native UISegmentedControl. This intentional behavior was not surfaced in the dartdoc, so users assumed it was a Flutter-side bug when content behind a segmented control showed through. Add a paragraph to the class-level dartdoc and clarify backgroundColor's description so the translucency is discoverable, and document how to obtain an opaque background (pass an opaque Color to backgroundColor). Fixes flutter#164073.
github-actions
Bot
added
framework
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for CupertinoSlidingSegmentedControl to clarify that the default backgroundColor is translucent, matching native iOS behavior. The review feedback identifies a violation of the Flutter style guide regarding the use of future tense in documentation and points out an inaccuracy where the documentation suggests a non-nullable property can be null.
| /// The default [backgroundColor], [CupertinoColors.tertiarySystemFill], is | ||
| /// intentionally translucent (alpha 0.12 in light mode) to match the native | ||
| /// `UISegmentedControl`. As a result, content placed behind the segmented | ||
| /// control — for example a [Stack] child beneath it — will show through the |
Contributor
There was a problem hiding this comment.
According to the Flutter style guide, documentation should use the present tense and avoid "will". Additionally, "for example" is typically followed by a comma for better readability.
/// control — for example, a [Stack] child beneath it — shows through theReferences
- The Flutter style guide recommends using the present tense and avoiding 'will', 'shall', 'can', or 'may' in documentation. (link)
Comment on lines
+475
to
+477
| /// [Color] is supplied here. | ||
| /// | ||
| /// The background will not be painted if null is specified. |
Contributor
There was a problem hiding this comment.
The backgroundColor property is non-nullable (final Color), so it cannot be null. This statement is misleading and should be removed.
/// [Color] is supplied here.References
- Documentation should accurately reflect the API's constraints. Stating that a property can be null when it is non-nullable is misleading.
Address review feedback (flutter#186645): use present tense per the Flutter style guide ("shows through" instead of "will show through"), add the missing comma after "for example", and drop the misleading "if null" line on the non-nullable backgroundColor field.
victorsanni
previously approved these changes
May 21, 2026
| /// | ||
| /// The default [backgroundColor], [CupertinoColors.tertiarySystemFill], is | ||
| /// intentionally translucent (alpha 0.12 in light mode) to match the native | ||
| /// `UISegmentedControl`. As a result, content placed behind the segmented |
Contributor
There was a problem hiding this comment.
| /// will not be painted if null is specified. | ||
| /// The default value is [CupertinoColors.tertiarySystemFill], which is | ||
| /// translucent (alpha 0.12 in light mode) to match the native | ||
| /// `UISegmentedControl`. Content placed behind the segmented control is |
…tedControl Address review feedback on flutter#186645: add the UISegmentedControl reference URL next to both mentions in the class-level dartdoc and the backgroundColor field doc, so readers can jump to Apple's documentation of the native control whose behavior the Flutter widget mirrors.
Piinks
added
the
Decoupling: Not ready to port yet
Contributor
|
I've marked this PR as not ready to port to flutter/packages yet. |
dkwingsmt
self-requested a review
July 8, 2026 18:09
victorsanni
approved these changes
Jul 30, 2026
Contributor
|
This PR is ready to port to flutter/packages! 🥳 |
dkwingsmt
added
Decoupling: Port to flutter/packages
dkwingsmt
marked this pull request as draft
September 24, 2026 19:14
11 tasks done
auto-submit Bot
pushed a commit
to flutter/packages
that referenced
this pull request
Oct 28, 2026
…idingSegmentedControl (#13178) Fixes flutter/flutter#164073 Ports flutter/flutter#186645. Part of flutter/flutter#188444. Documents that the default background of CupertinoSlidingSegmentedControl is translucent, so content behind unselected segments shows through unless an opaque color is passed. The original issue is flutter/flutter#164073. Tracking issue: flutter/flutter#188444. cc @NadeemIqbal Docs-only change, so this is test-exempt. I used AI assistance to port the approved documentation. ## Pre-Review Checklist **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
Contributor
|
Closing this PR because it has been ported to |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The default
CupertinoSlidingSegmentedControl.backgroundColorisCupertinoColors.tertiarySystemFill, which is translucent (alpha 0.12 in light mode) to match the nativeUISegmentedControl. The translucency was not documented, which led users to report it as a Flutter-side bug when content placed behind the control became visible through the unselected segments. Added a paragraph to the class-level dartdoc and to thebackgroundColordoc making the intentional translucency explicit and showing how to obtain an opaque background (pass an opaqueColortobackgroundColor). Triage on #164073 confirmed the behavior matches the native control.Fixes #164073.
Pre-launch Checklist
///).Documentation-only change, so I am claiming the test-exempt policy. Touches
packages/flutter/lib/src/cupertino/, which is currently under code freeze; needs theoverride code freezelabel to merge.