From b01cb301cfa2de0b2ac13296b79bdfe4c60c8678 Mon Sep 17 00:00:00 2001 From: chunhtai <47866232+chunhtai@users.noreply.github.com> Date: Mon, 7 Aug 2023 16:59:48 -0700 Subject: [PATCH] Adds more documentations around ignoreSemantics deprecations. (#131287) migration guide update https://github.com/flutter/website/pull/9124 fixes the concerns in https://github.com/flutter/flutter/pull/120619 --- .../flutter/lib/src/rendering/proxy_box.dart | 26 +++++-- .../lib/src/rendering/proxy_sliver.dart | 13 +++- packages/flutter/lib/src/widgets/basic.dart | 69 +++++++++++++------ packages/flutter/lib/src/widgets/sliver.dart | 13 +++- 4 files changed, 88 insertions(+), 33 deletions(-) diff --git a/packages/flutter/lib/src/rendering/proxy_box.dart b/packages/flutter/lib/src/rendering/proxy_box.dart index 5e6f2e740f5..25c32741b7b 100644 --- a/packages/flutter/lib/src/rendering/proxy_box.dart +++ b/packages/flutter/lib/src/rendering/proxy_box.dart @@ -3547,7 +3547,14 @@ class RenderRepaintBoundary extends RenderProxyBox { /// as usual. It just cannot be the target of located events, because its render /// object returns false from [hitTest]. /// -/// {@macro flutter.widgets.IgnorePointer.Semantics} +/// ## Semantics +/// +/// Using this class may also affect how the semantics subtree underneath is +/// collected. +/// +/// {@macro flutter.widgets.IgnorePointer.semantics} +/// +/// {@macro flutter.widgets.IgnorePointer.ignoringSemantics} /// /// See also: /// @@ -3574,7 +3581,7 @@ class RenderIgnorePointer extends RenderProxyBox { /// Regardless of whether this render object is ignored during hit testing, it /// will still consume space during layout and be visible during painting. /// - /// {@macro flutter.widgets.IgnorePointer.Semantics} + /// {@macro flutter.widgets.IgnorePointer.semantics} bool get ignoring => _ignoring; bool _ignoring; set ignoring(bool value) { @@ -3589,7 +3596,7 @@ class RenderIgnorePointer extends RenderProxyBox { /// Whether the semantics of this render object is ignored when compiling the semantics tree. /// - /// {@macro flutter.widgets.IgnorePointer.Semantics} + /// {@macro flutter.widgets.IgnorePointer.ignoringSemantics} /// /// See [SemanticsNode] for additional information about the semantics tree. @Deprecated( @@ -3790,7 +3797,14 @@ class RenderOffstage extends RenderProxyBox { /// its children from being the target of located events, because its render /// object returns true from [hitTest]. /// -/// {@macro flutter.widgets.AbsorbPointer.Semantics} +/// ## Semantics +/// +/// Using this class may also affect how the semantics subtree underneath is +/// collected. +/// +/// {@macro flutter.widgets.AbsorbPointer.semantics} +/// +/// {@macro flutter.widgets.AbsorbPointer.ignoringSemantics} /// /// See also: /// @@ -3818,7 +3832,7 @@ class RenderAbsorbPointer extends RenderProxyBox { /// testing, it will still consume space during layout and be visible during /// painting. /// - /// {@macro flutter.widgets.AbsorbPointer.Semantics} + /// {@macro flutter.widgets.AbsorbPointer.semantics} bool get absorbing => _absorbing; bool _absorbing; set absorbing(bool value) { @@ -3834,7 +3848,7 @@ class RenderAbsorbPointer extends RenderProxyBox { /// Whether the semantics of this render object is ignored when compiling the /// semantics tree. /// - /// {@macro flutter.widgets.AbsorbPointer.Semantics} + /// {@macro flutter.widgets.AbsorbPointer.ignoringSemantics} /// /// See [SemanticsNode] for additional information about the semantics tree. @Deprecated( diff --git a/packages/flutter/lib/src/rendering/proxy_sliver.dart b/packages/flutter/lib/src/rendering/proxy_sliver.dart index bd7feec4cd4..2425cb8ebc7 100644 --- a/packages/flutter/lib/src/rendering/proxy_sliver.dart +++ b/packages/flutter/lib/src/rendering/proxy_sliver.dart @@ -205,7 +205,14 @@ class RenderSliverOpacity extends RenderProxySliver { /// child as usual. It just cannot be the target of located events, because its /// render object returns false from [hitTest]. /// -/// {@macro flutter.widgets.IgnorePointer.Semantics} +/// ## Semantics +/// +/// Using this class may also affect how the semantics subtree underneath is +/// collected. +/// +/// {@macro flutter.widgets.IgnorePointer.semantics} +/// +/// {@macro flutter.widgets.IgnorePointer.ignoringSemantics} class RenderSliverIgnorePointer extends RenderProxySliver { /// Creates a render object that is invisible to hit testing. /// @@ -228,7 +235,7 @@ class RenderSliverIgnorePointer extends RenderProxySliver { /// Regardless of whether this render object is ignored during hit testing, it /// will still consume space during layout and be visible during painting. /// - /// {@macro flutter.widgets.IgnorePointer.Semantics} + /// {@macro flutter.widgets.IgnorePointer.semantics} bool get ignoring => _ignoring; bool _ignoring; set ignoring(bool value) { @@ -244,7 +251,7 @@ class RenderSliverIgnorePointer extends RenderProxySliver { /// Whether the semantics of this render object is ignored when compiling the /// semantics tree. /// - /// {@macro flutter.widgets.IgnorePointer.Semantics} + /// {@macro flutter.widgets.IgnorePointer.ignoringSemantics} @Deprecated( 'Create a custom sliver ignore pointer widget instead. ' 'This feature was deprecated after v3.8.0-12.0.pre.' diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart index bd69cf4ea25..a8820921e7c 100644 --- a/packages/flutter/lib/src/widgets/basic.dart +++ b/packages/flutter/lib/src/widgets/basic.dart @@ -6839,20 +6839,33 @@ class RepaintBoundary extends SingleChildRenderObjectWidget { /// /// ## Semantics /// -/// Using this widget may also affect how the semantics subtree underneath this -/// widget is collected. +/// Using this class may also affect how the semantics subtree underneath is +/// collected. +/// +/// {@template flutter.widgets.IgnorePointer.semantics} +/// If [ignoring] is true, pointer-related [SemanticsAction]s are removed from +/// the semantics subtree. Otherwise, the subtree remains untouched. +/// {@endtemplate} +/// +/// {@template flutter.widgets.IgnorePointer.ignoringSemantics} +/// The usages of [ignoringSemantics] are deprecated and not recommended. This +/// property was introduced to workaround the semantics behavior of the +/// [IgnorePointer] and its friends before v3.8.0-12.0.pre. +/// +/// Before that version, entire semantics subtree is dropped if [ignoring] is +/// true. Developers can only use [ignoringSemantics] to preserver the semantics +/// subtrees. +/// +/// After that version, with [ignoring] set to true, it only prevents semantics +/// user actions in the semantics subtree but leaves the other +/// [SemanticsProperties] intact. Therefore, the [ignoringSemantics] is no +/// longer needed. /// -/// {@template flutter.widgets.IgnorePointer.Semantics} /// If [ignoringSemantics] is true, the semantics subtree is dropped. Therefore, /// the subtree will be invisible to assistive technologies. /// /// If [ignoringSemantics] is false, the semantics subtree is collected as /// usual. -/// -/// If [ignoringSemantics] is not set, then [ignoring] decides how the -/// semantics subtree is collected. If [ignoring] is true, pointer-related -/// [SemanticsAction]s are removed from the semantics subtree. Otherwise, the -/// subtree remains untouched. /// {@endtemplate} /// /// See also: @@ -6880,7 +6893,7 @@ class IgnorePointer extends SingleChildRenderObjectWidget { /// Regardless of whether this widget is ignored during hit testing, it will /// still consume space during layout and be visible during painting. /// - /// {@macro flutter.widgets.IgnorePointer.Semantics} + /// {@macro flutter.widgets.IgnorePointer.semantics} /// /// Defaults to true. final bool ignoring; @@ -6888,7 +6901,7 @@ class IgnorePointer extends SingleChildRenderObjectWidget { /// Whether the semantics of this widget is ignored when compiling the /// semantics subtree. /// - /// {@macro flutter.widgets.IgnorePointer.Semantics} + /// {@macro flutter.widgets.IgnorePointer.ignoringSemantics} /// /// See [SemanticsNode] for additional information about the semantics tree. @Deprecated( @@ -6943,19 +6956,33 @@ class IgnorePointer extends SingleChildRenderObjectWidget { /// /// ## Semantics /// -/// Using this widget may also affect how the semantics subtree underneath this -/// widget is collected. +/// Using this class may also affect how the semantics subtree underneath is +/// collected. /// -/// {@template flutter.widgets.AbsorbPointer.Semantics} -/// If [ignoringSemantics] is true, the semantics subtree is dropped. +/// {@template flutter.widgets.AbsorbPointer.semantics} +/// If [absorbing] is true, pointer-related [SemanticsAction]s are removed from +/// the semantics subtree. Otherwise, the subtree remains untouched. +/// {@endtemplate} +/// +/// {@template flutter.widgets.AbsorbPointer.ignoringSemantics} +/// The usages of [ignoringSemantics] are deprecated and not recommended. This +/// property was introduced to workaround the semantics behavior of the +/// [IgnorePointer] and its friends before v3.8.0-12.0.pre. +/// +/// Before that version, entire semantics subtree is dropped if [absorbing] is +/// true. Developers can only use [ignoringSemantics] to preserver the semantics +/// subtrees. +/// +/// After that version, with [absorbing] set to true, it only prevents semantics +/// user actions in the semantics subtree but leaves the other +/// [SemanticsProperties] intact. Therefore, the [ignoringSemantics] is no +/// longer needed. +/// +/// If [ignoringSemantics] is true, the semantics subtree is dropped. Therefore, +/// the subtree will be invisible to assistive technologies. /// /// If [ignoringSemantics] is false, the semantics subtree is collected as /// usual. -/// -/// If [ignoringSemantics] is not set, then [absorbing] decides how the -/// semantics subtree is collected. If [absorbing] is true, pointer-related -/// [SemanticsAction]s are removed from the semantics subtree. Otherwise, the -/// subtree remains untouched. /// {@endtemplate} /// /// See also: @@ -6983,7 +7010,7 @@ class AbsorbPointer extends SingleChildRenderObjectWidget { /// testing, it will still consume space during layout and be visible during /// painting. /// - /// {@macro flutter.widgets.AbsorbPointer.Semantics} + /// {@macro flutter.widgets.AbsorbPointer.semantics} /// /// Defaults to true. final bool absorbing; @@ -6991,7 +7018,7 @@ class AbsorbPointer extends SingleChildRenderObjectWidget { /// Whether the semantics of this render object is ignored when compiling the /// semantics tree. /// - /// {@macro flutter.widgets.AbsorbPointer.Semantics} + /// {@macro flutter.widgets.AbsorbPointer.ignoringSemantics} /// /// See [SemanticsNode] for additional information about the semantics tree. @Deprecated( diff --git a/packages/flutter/lib/src/widgets/sliver.dart b/packages/flutter/lib/src/widgets/sliver.dart index 0090198cb38..f5240dd7b73 100644 --- a/packages/flutter/lib/src/widgets/sliver.dart +++ b/packages/flutter/lib/src/widgets/sliver.dart @@ -1178,7 +1178,14 @@ class SliverOpacity extends SingleChildRenderObjectWidget { /// child as usual. It just cannot be the target of located events, because it /// returns false from [RenderSliver.hitTest]. /// -/// {@macro flutter.widgets.IgnorePointer.Semantics} +/// ## Semantics +/// +/// Using this class may also affect how the semantics subtree underneath is +/// collected. +/// +/// {@macro flutter.widgets.IgnorePointer.semantics} +/// +/// {@macro flutter.widgets.IgnorePointer.ignoringSemantics} /// /// See also: /// @@ -1203,13 +1210,13 @@ class SliverIgnorePointer extends SingleChildRenderObjectWidget { /// Regardless of whether this sliver is ignored during hit testing, it will /// still consume space during layout and be visible during painting. /// - /// {@macro flutter.widgets.IgnorePointer.Semantics} + /// {@macro flutter.widgets.IgnorePointer.semantics} final bool ignoring; /// Whether the semantics of this sliver is ignored when compiling the /// semantics tree. /// - /// {@macro flutter.widgets.IgnorePointer.Semantics} + /// {@macro flutter.widgets.IgnorePointer.ignoringSemantics} @Deprecated( 'Create a custom sliver ignore pointer widget instead. ' 'This feature was deprecated after v3.8.0-12.0.pre.'