From fe95b2e225dc4099267e27a28bbf2257463d62e3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Sharma?=
 <737941+loic-sharma@users.noreply.github.com>
Date: Thu, 24 Oct 2024 11:53:07 -0700
Subject: [PATCH] Add example to SafeArea docs (#157228)

---
 .../flutter/lib/src/widgets/safe_area.dart    | 35 +++++++++++++++----
 1 file changed, 28 insertions(+), 7 deletions(-)

diff --git a/packages/flutter/lib/src/widgets/safe_area.dart b/packages/flutter/lib/src/widgets/safe_area.dart
index 93048ea3a7..023e8fe1f1 100644
--- a/packages/flutter/lib/src/widgets/safe_area.dart
+++ b/packages/flutter/lib/src/widgets/safe_area.dart
@@ -11,8 +11,10 @@ import 'debug.dart';
 import 'framework.dart';
 import 'media_query.dart';
 
-/// A widget that insets its child by sufficient padding to avoid intrusions by
-/// the operating system.
+/// A widget that insets its child with sufficient padding to avoid intrusions
+/// by the operating system.
+///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=lkF0TQJO0bA}
 ///
 /// For example, this will indent the child by enough to avoid the status bar at
 /// the top of the screen.
@@ -23,21 +25,40 @@ import 'media_query.dart';
 /// When a [minimum] padding is specified, the greater of the minimum padding
 /// or the safe area padding will be applied.
 ///
-/// {@youtube 560 315 https://www.youtube.com/watch?v=lkF0TQJO0bA}
+/// {@tool snippet}
+///
+/// This example creates a blue box containing text that is sufficiently padded
+/// to avoid instrusions by the operating system.
+///
+/// ```dart
+/// SafeArea(
+///   child: Container(
+///     constraints: const BoxConstraints.expand(),
+///     alignment: Alignment.center,
+///     color: Colors.blue,
+///     child: const Text('Hello, World!'),
+///   ),
+/// )
+/// ```
+/// {@end-tool}
+///
+/// ### [MediaQuery] impact
+///
+/// The padding on the [MediaQuery] for the [child] will be suitably adjusted
+/// to zero out any sides that were avoided by this widget.
+///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=ceCo8U0XHqw}
 ///
 /// See also:
 ///
 ///  * [SliverSafeArea], for insetting slivers to avoid operating system
 ///    intrusions.
 ///  * [Padding], for insetting widgets in general.
-///  * [MediaQuery], from which the window padding is obtained.
+///  * [MediaQuery], from which the view padding is obtained.
 ///  * [dart:ui.FlutterView.padding], which reports the padding from the operating
 ///    system.
 class SafeArea extends StatelessWidget {
   /// Creates a widget that avoids operating system interfaces.
-  ///
-  /// The [left], [top], [right], [bottom], and [minimum] arguments must not be
-  /// null.
   const SafeArea({
     super.key,
     this.left = true,