box_fit.dart 7.34 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4 5 6
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'dart:math' as math;

7 8
import 'package:flutter/foundation.dart';

9 10
import 'basic_types.dart';

11
/// How a box should be inscribed into another box.
12
///
13 14 15 16
/// See also:
///
///  * [applyBoxFit], which applies the sizing semantics of these values (though
///    not the alignment semantics).
17 18
enum BoxFit {
  /// Fill the target box by distorting the source's aspect ratio.
19
  ///
20
  /// ![](https://flutter.github.io/assets-for-api-docs/assets/painting/box_fit_fill.png)
21 22
  fill,

23 24
  /// As large as possible while still containing the source entirely within the
  /// target box.
25
  ///
26
  /// ![](https://flutter.github.io/assets-for-api-docs/assets/painting/box_fit_contain.png)
27 28
  contain,

29
  /// As small as possible while still covering the entire target box.
30
  ///
31
  /// ![](https://flutter.github.io/assets-for-api-docs/assets/painting/box_fit_cover.png)
32 33
  cover,

34 35
  /// Make sure the full width of the source is shown, regardless of
  /// whether this means the source overflows the target box vertically.
36
  ///
37
  /// ![](https://flutter.github.io/assets-for-api-docs/assets/painting/box_fit_fitWidth.png)
38 39
  fitWidth,

40 41
  /// Make sure the full height of the source is shown, regardless of
  /// whether this means the source overflows the target box horizontally.
42
  ///
43
  /// ![](https://flutter.github.io/assets-for-api-docs/assets/painting/box_fit_fitHeight.png)
44 45
  fitHeight,

46 47
  /// Align the source within the target box (by default, centering) and discard
  /// any portions of the source that lie outside the box.
48 49 50
  ///
  /// The source image is not resized.
  ///
51
  /// ![](https://flutter.github.io/assets-for-api-docs/assets/painting/box_fit_none.png)
52 53
  none,

54 55 56
  /// Align the source within the target box (by default, centering) and, if
  /// necessary, scale the source down to ensure that the source fits within the
  /// box.
57 58 59 60
  ///
  /// This is the same as `contain` if that would shrink the image, otherwise it
  /// is the same as `none`.
  ///
61
  /// ![](https://flutter.github.io/assets-for-api-docs/assets/painting/box_fit_scaleDown.png)
62
  scaleDown,
63 64
}

65
/// The pair of sizes returned by [applyBoxFit].
66
@immutable
67 68
class FittedSizes {
  /// Creates an object to store a pair of sizes,
69
  /// as would be returned by [applyBoxFit].
70 71 72 73 74 75 76 77 78
  const FittedSizes(this.source, this.destination);

  /// The size of the part of the input to show on the output.
  final Size source;

  /// The size of the part of the output on which to show the input.
  final Size destination;
}

79
/// Apply a [BoxFit] value.
80
///
81 82 83
/// The arguments to this method, in addition to the [BoxFit] value to apply,
/// are two sizes, ostensibly the sizes of an input box and an output box.
/// Specifically, the `inputSize` argument gives the size of the complete source
84
/// that is being fitted, and the `outputSize` gives the size of the rectangle
85
/// into which the source is to be drawn.
86 87 88 89 90
///
/// This function then returns two sizes, combined into a single [FittedSizes]
/// object.
///
/// The [FittedSizes.source] size is the subpart of the `inputSize` that is to
91 92
/// be shown. If the entire input source is shown, then this will equal the
/// `inputSize`, but if the input source is to be cropped down, this may be
93 94 95
/// smaller.
///
/// The [FittedSizes.destination] size is the subpart of the `outputSize` in
96
/// which to paint the (possibly cropped) source. If the
97
/// [FittedSizes.destination] size is smaller than the `outputSize` then the
98
/// source is being letterboxed (or pillarboxed).
99 100 101 102
///
/// This method does not express an opinion regarding the alignment of the
/// source and destination sizes within the input and output rectangles.
/// Typically they are centered (this is what [BoxDecoration] does, for
103 104 105
/// instance, and is how [BoxFit] is defined). The [Alignment] class provides a
/// convenience function, [Alignment.inscribe], for resolving the sizes to
/// rects, as shown in the example below.
106
///
107
/// {@tool snippet}
108
///
109 110
/// This function paints a [dart:ui.Image] `image` onto the [Rect] `outputRect` on a
/// [Canvas] `canvas`, using a [Paint] `paint`, applying the [BoxFit] algorithm
111 112 113
/// `fit`:
///
/// ```dart
114
/// void paintImage(ui.Image image, Rect outputRect, Canvas canvas, Paint paint, BoxFit fit) {
115
///   final Size imageSize = Size(image.width.toDouble(), image.height.toDouble());
116
///   final FittedSizes sizes = applyBoxFit(fit, imageSize, outputRect.size);
117 118
///   final Rect inputSubrect = Alignment.center.inscribe(sizes.source, Offset.zero & imageSize);
///   final Rect outputSubrect = Alignment.center.inscribe(sizes.destination, outputRect);
119 120
///   canvas.drawImageRect(image, inputSubrect, outputSubrect, paint);
/// }
121
/// ```
122
/// {@end-tool}
Ian Hickson's avatar
Ian Hickson committed
123 124 125 126 127 128 129
///
/// See also:
///
///  * [FittedBox], a widget that applies this algorithm to another widget.
///  * [paintImage], a function that applies this algorithm to images for painting.
///  * [DecoratedBox], [BoxDecoration], and [DecorationImage], which together
///    provide access to [paintImage] at the widgets layer.
130
FittedSizes applyBoxFit(BoxFit fit, Size inputSize, Size outputSize) {
131 132 133
  if (inputSize.height <= 0.0 || inputSize.width <= 0.0 || outputSize.height <= 0.0 || outputSize.width <= 0.0)
    return const FittedSizes(Size.zero, Size.zero);

134 135
  Size sourceSize, destinationSize;
  switch (fit) {
136
    case BoxFit.fill:
137 138 139
      sourceSize = inputSize;
      destinationSize = outputSize;
      break;
140
    case BoxFit.contain:
141 142
      sourceSize = inputSize;
      if (outputSize.width / outputSize.height > sourceSize.width / sourceSize.height)
143
        destinationSize = Size(sourceSize.width * outputSize.height / sourceSize.height, outputSize.height);
144
      else
145
        destinationSize = Size(outputSize.width, sourceSize.height * outputSize.width / sourceSize.width);
146
      break;
147
    case BoxFit.cover:
148
      if (outputSize.width / outputSize.height > inputSize.width / inputSize.height) {
149
        sourceSize = Size(inputSize.width, inputSize.width * outputSize.height / outputSize.width);
150
      } else {
151
        sourceSize = Size(inputSize.height * outputSize.width / outputSize.height, inputSize.height);
152 153 154
      }
      destinationSize = outputSize;
      break;
155
    case BoxFit.fitWidth:
156 157
      sourceSize = Size(inputSize.width, inputSize.width * outputSize.height / outputSize.width);
      destinationSize = Size(outputSize.width, sourceSize.height * outputSize.width / sourceSize.width);
158
      break;
159
    case BoxFit.fitHeight:
160 161
      sourceSize = Size(inputSize.height * outputSize.width / outputSize.height, inputSize.height);
      destinationSize = Size(sourceSize.width * outputSize.height / sourceSize.height, outputSize.height);
162
      break;
163
    case BoxFit.none:
164
      sourceSize = Size(math.min(inputSize.width, outputSize.width),
165 166 167
                            math.min(inputSize.height, outputSize.height));
      destinationSize = sourceSize;
      break;
168
    case BoxFit.scaleDown:
169 170 171 172
      sourceSize = inputSize;
      destinationSize = inputSize;
      final double aspectRatio = inputSize.width / inputSize.height;
      if (destinationSize.height > outputSize.height)
173
        destinationSize = Size(outputSize.height * aspectRatio, outputSize.height);
174
      if (destinationSize.width > outputSize.width)
175
        destinationSize = Size(outputSize.width, outputSize.width / aspectRatio);
176 177
      break;
  }
178
  return FittedSizes(sourceSize, destinationSize);
Adam Barth's avatar
Adam Barth committed
179
}