1// Copyright 2014 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5import 'basic.dart';
6import 'framework.dart';
7
8/// Spacer creates an adjustable, empty spacer that can be used to tune the
9/// spacing between widgets in a [Flex] container, like [Row] or [Column].
10///
11/// The [Spacer] widget will take up any available space, so setting the
12/// [Flex.mainAxisAlignment] on a flex container that contains a [Spacer] to
13/// [MainAxisAlignment.spaceAround], [MainAxisAlignment.spaceBetween], or
14/// [MainAxisAlignment.spaceEvenly] will not have any visible effect: the
15/// [Spacer] has taken up all of the additional space, therefore there is none
16/// left to redistribute.
17///
18/// {@tool snippet}
19///
20/// ```dart
21/// const Row(
22/// children: <Widget>[
23/// Text('Begin'),
24/// Spacer(), // Defaults to a flex of one.
25/// Text('Middle'),
26/// // Gives twice the space between Middle and End than Begin and Middle.
27/// Spacer(flex: 2),
28/// Text('End'),
29/// ],
30/// )
31/// ```
32/// {@end-tool}
33///
34/// {@youtube 560 315 https://www.youtube.com/watch?v=7FJgd7QN1zI}
35///
36/// See also:
37///
38/// * [Row] and [Column], which are the most common containers to use a Spacer
39/// in.
40/// * [SizedBox], to create a box with a specific size and an optional child.
41class Spacer extends StatelessWidget {
42 /// Creates a flexible space to insert into a [Flexible] widget.
43 ///
44 /// The [flex] parameter may not be null or less than one.
45 const Spacer({super.key, this.flex = 1}) : assert(flex > 0);
46
47 /// The flex factor to use in determining how much space to take up.
48 ///
49 /// The amount of space the [Spacer] can occupy in the main axis is determined
50 /// by dividing the free space proportionately, after placing the inflexible
51 /// children, according to the flex factors of the flexible children.
52 ///
53 /// Defaults to one.
54 final int flex;
55
56 @override
57 Widget build(BuildContext context) {
58 return Expanded(flex: flex, child: const SizedBox.shrink());
59 }
60}
61