input_border.dart 17.9 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4 5 6 7
// 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;
import 'dart:ui' show lerpDouble;

8
import 'package:flutter/foundation.dart' show clampDouble;
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
import 'package:flutter/widgets.dart';

/// Defines the appearance of an [InputDecorator]'s border.
///
/// An input decorator's border is specified by [InputDecoration.border].
///
/// The border is drawn relative to the input decorator's "container" which
/// is the optionally filled area above the decorator's helper, error,
/// and counter.
///
/// Input border's are decorated with a line whose weight and color are defined
/// by [borderSide]. The input decorator's renderer animates the input border's
/// appearance in response to state changes, like gaining or losing the focus,
/// by creating new copies of its input border with [copyWith].
///
/// See also:
///
///  * [UnderlineInputBorder], the default [InputDecorator] border which
///    draws a horizontal line at the bottom of the input decorator's container.
///  * [OutlineInputBorder], an [InputDecorator] border which draws a
///    rounded rectangle around the input decorator's container.
///  * [InputDecoration], which is used to configure an [InputDecorator].
abstract class InputBorder extends ShapeBorder {
  /// Creates a border for an [InputDecorator].
  ///
  /// The [borderSide] parameter must not be null. Applications typically do
  /// not specify a [borderSide] parameter because the input decorator
  /// substitutes its own, using [copyWith], based on the current theme and
  /// [InputDecorator.isFocused].
  const InputBorder({
39
    this.borderSide = BorderSide.none,
40 41
  }) : assert(borderSide != null);

42 43 44
  /// No input border.
  ///
  /// Use this value with [InputDecoration.border] to specify that no border
45
  /// should be drawn. The [InputDecoration.collapsed] constructor sets
46 47 48
  /// its border to this value.
  static const InputBorder none = _NoInputBorder();

49 50 51 52 53 54 55
  /// Defines the border line's color and weight.
  ///
  /// The [InputDecorator] creates copies of its input border, using [copyWith],
  /// based on the current theme and [InputDecorator.isFocused].
  final BorderSide borderSide;

  /// Creates a copy of this input border with the specified `borderSide`.
56
  InputBorder copyWith({ BorderSide? borderSide });
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74

  /// True if this border will enclose the [InputDecorator]'s container.
  ///
  /// This property affects the alignment of container's contents. For example
  /// when an input decorator is configured with an [OutlineInputBorder] its
  /// label is centered with its container.
  bool get isOutline;

  /// Paint this input border on [canvas].
  ///
  /// The [rect] parameter bounds the [InputDecorator]'s container.
  ///
  /// The additional `gap` parameters reflect the state of the [InputDecorator]'s
  /// floating label. When an input decorator gains the focus, its label
  /// animates upwards, to make room for the input child. The [gapStart] and
  /// [gapExtent] parameters define a floating label width interval, and
  /// [gapPercentage] defines the animation's progress (0.0 to 1.0).
  @override
75 76 77
  void paint(
    Canvas canvas,
    Rect rect, {
78
    double? gapStart,
79 80
    double gapExtent = 0.0,
    double gapPercentage = 0.0,
81
    TextDirection? textDirection,
82 83 84
  });
}

85 86 87 88 89
// Used to create the InputBorder.none singleton.
class _NoInputBorder extends InputBorder {
  const _NoInputBorder() : super(borderSide: BorderSide.none);

  @override
90
  _NoInputBorder copyWith({ BorderSide? borderSide }) => const _NoInputBorder();
91 92 93 94 95 96 97 98 99 100 101

  @override
  bool get isOutline => false;

  @override
  EdgeInsetsGeometry get dimensions => EdgeInsets.zero;

  @override
  _NoInputBorder scale(double t) => const _NoInputBorder();

  @override
102
  Path getInnerPath(Rect rect, { TextDirection? textDirection }) {
103
    return Path()..addRect(rect);
104 105 106
  }

  @override
107
  Path getOuterPath(Rect rect, { TextDirection? textDirection }) {
108
    return Path()..addRect(rect);
109 110 111
  }

  @override
112 113 114
  void paint(
    Canvas canvas,
    Rect rect, {
115
    double? gapStart,
116 117
    double gapExtent = 0.0,
    double gapPercentage = 0.0,
118
    TextDirection? textDirection,
119 120 121 122 123
  }) {
    // Do not paint.
  }
}

124 125
/// Draws a horizontal line at the bottom of an [InputDecorator]'s container and
/// defines the container's shape.
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141
///
/// The input decorator's "container" is the optionally filled area above the
/// decorator's helper, error, and counter.
///
/// See also:
///
///  * [OutlineInputBorder], an [InputDecorator] border which draws a
///    rounded rectangle around the input decorator's container.
///  * [InputDecoration], which is used to configure an [InputDecorator].
class UnderlineInputBorder extends InputBorder {
  /// Creates an underline border for an [InputDecorator].
  ///
  /// The [borderSide] parameter defaults to [BorderSide.none] (it must not be
  /// null). Applications typically do not specify a [borderSide] parameter
  /// because the input decorator substitutes its own, using [copyWith], based
  /// on the current theme and [InputDecorator.isFocused].
142 143 144 145
  ///
  /// The [borderRadius] parameter defaults to a value where the top left
  /// and right corners have a circular radius of 4.0. The [borderRadius]
  /// parameter must not be null.
146
  const UnderlineInputBorder({
147
    super.borderSide = const BorderSide(),
148
    this.borderRadius = const BorderRadius.only(
149 150
      topLeft: Radius.circular(4.0),
      topRight: Radius.circular(4.0),
151
    ),
152
  }) : assert(borderRadius != null);
153 154 155 156 157 158 159 160 161 162 163

  /// The radii of the border's rounded rectangle corners.
  ///
  /// When this border is used with a filled input decorator, see
  /// [InputDecoration.filled], the border radius defines the shape
  /// of the background fill as well as the bottom left and right
  /// edges of the underline itself.
  ///
  /// By default the top right and top left corners have a circular radius
  /// of 4.0.
  final BorderRadius borderRadius;
164 165 166 167 168

  @override
  bool get isOutline => false;

  @override
169
  UnderlineInputBorder copyWith({ BorderSide? borderSide, BorderRadius? borderRadius }) {
170
    return UnderlineInputBorder(
171 172 173
      borderSide: borderSide ?? this.borderSide,
      borderRadius: borderRadius ?? this.borderRadius,
    );
174 175 176 177
  }

  @override
  EdgeInsetsGeometry get dimensions {
178
    return EdgeInsets.only(bottom: borderSide.width);
179 180 181 182
  }

  @override
  UnderlineInputBorder scale(double t) {
183
    return UnderlineInputBorder(borderSide: borderSide.scale(t));
184 185 186
  }

  @override
187
  Path getInnerPath(Rect rect, { TextDirection? textDirection }) {
188 189
    return Path()
      ..addRect(Rect.fromLTWH(rect.left, rect.top, rect.width, math.max(0.0, rect.height - borderSide.width)));
190 191 192
  }

  @override
193
  Path getOuterPath(Rect rect, { TextDirection? textDirection }) {
194
    return Path()..addRRect(borderRadius.resolve(textDirection).toRRect(rect));
195 196 197
  }

  @override
198
  ShapeBorder? lerpFrom(ShapeBorder? a, double t) {
199
    if (a is UnderlineInputBorder) {
200
      return UnderlineInputBorder(
201
        borderSide: BorderSide.lerp(a.borderSide, borderSide, t),
202
        borderRadius: BorderRadius.lerp(a.borderRadius, borderRadius, t)!,
203 204 205 206 207 208
      );
    }
    return super.lerpFrom(a, t);
  }

  @override
209
  ShapeBorder? lerpTo(ShapeBorder? b, double t) {
210
    if (b is UnderlineInputBorder) {
211
      return UnderlineInputBorder(
212
        borderSide: BorderSide.lerp(borderSide, b.borderSide, t),
213
        borderRadius: BorderRadius.lerp(borderRadius, b.borderRadius, t)!,
214 215 216 217 218 219 220 221 222 223
      );
    }
    return super.lerpTo(b, t);
  }

  /// Draw a horizontal line at the bottom of [rect].
  ///
  /// The [borderSide] defines the line's color and weight. The `textDirection`
  /// `gap` and `textDirection` parameters are ignored.
  @override
224 225 226
  void paint(
    Canvas canvas,
    Rect rect, {
227
    double? gapStart,
228 229
    double gapExtent = 0.0,
    double gapPercentage = 0.0,
230
    TextDirection? textDirection,
231
  }) {
232
    if (borderRadius.bottomLeft != Radius.zero || borderRadius.bottomRight != Radius.zero) {
233
      canvas.clipPath(getOuterPath(rect, textDirection: textDirection));
234
    }
235 236 237 238
    canvas.drawLine(rect.bottomLeft, rect.bottomRight, borderSide.toPaint());
  }

  @override
239
  bool operator ==(Object other) {
240
    if (identical(this, other)) {
241
      return true;
242 243
    }
    if (other.runtimeType != runtimeType) {
244
      return false;
245
    }
246 247
    return other is InputBorder
        && other.borderSide == borderSide;
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269
  }

  @override
  int get hashCode => borderSide.hashCode;
}

/// Draws a rounded rectangle around an [InputDecorator]'s container.
///
/// When the input decorator's label is floating, for example because its
/// input child has the focus, the label appears in a gap in the border outline.
///
/// The input decorator's "container" is the optionally filled area above the
/// decorator's helper, error, and counter.
///
/// See also:
///
///  * [UnderlineInputBorder], the default [InputDecorator] border which
///    draws a horizontal line at the bottom of the input decorator's container.
///  * [InputDecoration], which is used to configure an [InputDecorator].
class OutlineInputBorder extends InputBorder {
  /// Creates a rounded rectangle outline border for an [InputDecorator].
  ///
270 271 272 273 274 275 276
  /// If the [borderSide] parameter is [BorderSide.none], it will not draw a
  /// border. However, it will still define a shape (which you can see if
  /// [InputDecoration.filled] is true).
  ///
  /// If an application does not specify a [borderSide] parameter of
  /// value [BorderSide.none], the input decorator substitutes its own, using
  /// [copyWith], based on the current theme and [InputDecorator.isFocused].
277
  ///
278 279 280 281
  /// The [borderRadius] parameter defaults to a value where all four
  /// corners have a circular radius of 4.0. The [borderRadius] parameter
  /// must not be null and the corner radii must be circular, i.e. their
  /// [Radius.x] and [Radius.y] values must be the same.
282 283
  ///
  /// See also:
284
  ///
285 286 287
  ///  * [InputDecoration.floatingLabelBehavior], which should be set to
  ///    [FloatingLabelBehavior.never] when the [borderSide] is
  ///    [BorderSide.none]. If let as [FloatingLabelBehavior.auto], the label
288 289
  ///    will extend beyond the container as if the border were still being
  ///    drawn.
290
  const OutlineInputBorder({
291
    super.borderSide = const BorderSide(),
292
    this.borderRadius = const BorderRadius.all(Radius.circular(4.0)),
293
    this.gapPadding = 4.0,
294
  }) : assert(borderRadius != null),
295
       assert(gapPadding != null && gapPadding >= 0.0);
296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326

  // The label text's gap can extend into the corners (even both the top left
  // and the top right corner). To avoid the more complicated problem of finding
  // how far the gap penetrates into an elliptical corner, just require them
  // to be circular.
  //
  // This can't be checked by the constructor because const constructor.
  static bool _cornersAreCircular(BorderRadius borderRadius) {
    return borderRadius.topLeft.x == borderRadius.topLeft.y
        && borderRadius.bottomLeft.x == borderRadius.bottomLeft.y
        && borderRadius.topRight.x == borderRadius.topRight.y
        && borderRadius.bottomRight.x == borderRadius.bottomRight.y;
  }

  /// Horizontal padding on either side of the border's
  /// [InputDecoration.labelText] width gap.
  ///
  /// This value is used by the [paint] method to compute the actual gap width.
  final double gapPadding;

  /// The radii of the border's rounded rectangle corners.
  ///
  /// The corner radii must be circular, i.e. their [Radius.x] and [Radius.y]
  /// values must be the same.
  final BorderRadius borderRadius;

  @override
  bool get isOutline => true;

  @override
  OutlineInputBorder copyWith({
327 328 329
    BorderSide? borderSide,
    BorderRadius? borderRadius,
    double? gapPadding,
330
  }) {
331
    return OutlineInputBorder(
332 333 334 335 336 337 338 339
      borderSide: borderSide ?? this.borderSide,
      borderRadius: borderRadius ?? this.borderRadius,
      gapPadding: gapPadding ?? this.gapPadding,
    );
  }

  @override
  EdgeInsetsGeometry get dimensions {
340
    return EdgeInsets.all(borderSide.width);
341 342 343 344
  }

  @override
  OutlineInputBorder scale(double t) {
345
    return OutlineInputBorder(
346 347 348 349 350 351 352
      borderSide: borderSide.scale(t),
      borderRadius: borderRadius * t,
      gapPadding: gapPadding * t,
    );
  }

  @override
353
  ShapeBorder? lerpFrom(ShapeBorder? a, double t) {
354 355
    if (a is OutlineInputBorder) {
      final OutlineInputBorder outline = a;
356
      return OutlineInputBorder(
357
        borderRadius: BorderRadius.lerp(outline.borderRadius, borderRadius, t)!,
358 359 360 361 362 363 364 365
        borderSide: BorderSide.lerp(outline.borderSide, borderSide, t),
        gapPadding: outline.gapPadding,
      );
    }
    return super.lerpFrom(a, t);
  }

  @override
366
  ShapeBorder? lerpTo(ShapeBorder? b, double t) {
367 368
    if (b is OutlineInputBorder) {
      final OutlineInputBorder outline = b;
369
      return OutlineInputBorder(
370
        borderRadius: BorderRadius.lerp(borderRadius, outline.borderRadius, t)!,
371 372 373 374 375 376 377 378
        borderSide: BorderSide.lerp(borderSide, outline.borderSide, t),
        gapPadding: outline.gapPadding,
      );
    }
    return super.lerpTo(b, t);
  }

  @override
379
  Path getInnerPath(Rect rect, { TextDirection? textDirection }) {
380
    return Path()
381 382 383 384
      ..addRRect(borderRadius.resolve(textDirection).toRRect(rect).deflate(borderSide.width));
  }

  @override
385
  Path getOuterPath(Rect rect, { TextDirection? textDirection }) {
386
    return Path()
387 388 389 390
      ..addRRect(borderRadius.resolve(textDirection).toRRect(rect));
  }

  Path _gapBorderPath(Canvas canvas, RRect center, double start, double extent) {
391 392 393 394 395
    // When the corner radii on any side add up to be greater than the
    // given height, each radius has to be scaled to not exceed the
    // size of the width/height of the RRect.
    final RRect scaledRRect = center.scaleRadii();

396
    final Rect tlCorner = Rect.fromLTWH(
397 398 399 400
      scaledRRect.left,
      scaledRRect.top,
      scaledRRect.tlRadiusX * 2.0,
      scaledRRect.tlRadiusY * 2.0,
401
    );
402
    final Rect trCorner = Rect.fromLTWH(
403 404 405 406
      scaledRRect.right - scaledRRect.trRadiusX * 2.0,
      scaledRRect.top,
      scaledRRect.trRadiusX * 2.0,
      scaledRRect.trRadiusY * 2.0,
407
    );
408
    final Rect brCorner = Rect.fromLTWH(
409 410 411 412
      scaledRRect.right - scaledRRect.brRadiusX * 2.0,
      scaledRRect.bottom - scaledRRect.brRadiusY * 2.0,
      scaledRRect.brRadiusX * 2.0,
      scaledRRect.brRadiusY * 2.0,
413
    );
414
    final Rect blCorner = Rect.fromLTWH(
415 416 417 418
      scaledRRect.left,
      scaledRRect.bottom - scaledRRect.blRadiusY * 2.0,
      scaledRRect.blRadiusX * 2.0,
      scaledRRect.blRadiusX * 2.0,
419 420
    );

421 422
    // This assumes that the radius is circular (x and y radius are equal).
    // Currently, BorderRadius only supports circular radii.
423
    const double cornerArcSweep = math.pi / 2.0;
424
    final double tlCornerArcSweep = math.acos(
425
      clampDouble(1 - start / scaledRRect.tlRadiusX, 0.0, 1.0),
426
    );
427

428
    final Path path = Path()
429
      ..addArc(tlCorner, math.pi, tlCornerArcSweep);
430

431
    if (start > scaledRRect.tlRadiusX) {
432
      path.lineTo(scaledRRect.left + start, scaledRRect.top);
433
    }
434

435 436
    const double trCornerArcStart = (3 * math.pi) / 2.0;
    const double trCornerArcSweep = cornerArcSweep;
437
    if (start + extent < scaledRRect.width - scaledRRect.trRadiusX) {
438 439 440
      path.moveTo(scaledRRect.left + start + extent, scaledRRect.top);
      path.lineTo(scaledRRect.right - scaledRRect.trRadiusX, scaledRRect.top);
      path.addArc(trCorner, trCornerArcStart, trCornerArcSweep);
441 442
    } else if (start + extent < scaledRRect.width) {
      final double dx = scaledRRect.width - (start + extent);
443
      final double sweep = math.asin(
444
        clampDouble(1 - dx / scaledRRect.trRadiusX, 0.0, 1.0),
445
      );
446 447 448 449
      path.addArc(trCorner, trCornerArcStart + sweep, trCornerArcSweep - sweep);
    }

    return path
450 451
      ..moveTo(scaledRRect.right, scaledRRect.top + scaledRRect.trRadiusY)
      ..lineTo(scaledRRect.right, scaledRRect.bottom - scaledRRect.brRadiusY)
452
      ..addArc(brCorner, 0.0, cornerArcSweep)
453
      ..lineTo(scaledRRect.left + scaledRRect.blRadiusX, scaledRRect.bottom)
454
      ..addArc(blCorner, math.pi / 2.0, cornerArcSweep)
455
      ..lineTo(scaledRRect.left, scaledRRect.top + scaledRRect.tlRadiusY);
456 457 458 459 460 461 462 463 464 465 466
  }

  /// Draw a rounded rectangle around [rect] using [borderRadius].
  ///
  /// The [borderSide] defines the line's color and weight.
  ///
  /// The top side of the rounded rectangle may be interrupted by a single gap
  /// if [gapExtent] is non-null. In that case the gap begins at
  /// `gapStart - gapPadding` (assuming that the [textDirection] is [TextDirection.ltr]).
  /// The gap's width is `(gapPadding + gapExtent + gapPadding) * gapPercentage`.
  @override
467 468 469
  void paint(
    Canvas canvas,
    Rect rect, {
470
    double? gapStart,
471 472
    double gapExtent = 0.0,
    double gapPercentage = 0.0,
473
    TextDirection? textDirection,
474 475 476 477 478 479 480 481 482 483 484
  }) {
    assert(gapExtent != null);
    assert(gapPercentage >= 0.0 && gapPercentage <= 1.0);
    assert(_cornersAreCircular(borderRadius));

    final Paint paint = borderSide.toPaint();
    final RRect outer = borderRadius.toRRect(rect);
    final RRect center = outer.deflate(borderSide.width / 2.0);
    if (gapStart == null || gapExtent <= 0.0 || gapPercentage == 0.0) {
      canvas.drawRRect(center, paint);
    } else {
485 486
      final double extent = lerpDouble(0.0, gapExtent + gapPadding * 2.0, gapPercentage)!;
      switch (textDirection!) {
487
        case TextDirection.rtl:
488
          final Path path = _gapBorderPath(canvas, center, math.max(0.0, gapStart + gapPadding - extent), extent);
489 490
          canvas.drawPath(path, paint);
          break;
491 492

        case TextDirection.ltr:
493
          final Path path = _gapBorderPath(canvas, center, math.max(0.0, gapStart - gapPadding), extent);
494 495 496 497 498 499 500
          canvas.drawPath(path, paint);
          break;
      }
    }
  }

  @override
501
  bool operator ==(Object other) {
502
    if (identical(this, other)) {
503
      return true;
504 505
    }
    if (other.runtimeType != runtimeType) {
506
      return false;
507
    }
508 509 510 511
    return other is OutlineInputBorder
        && other.borderSide == borderSide
        && other.borderRadius == borderRadius
        && other.gapPadding == gapPadding;
512 513 514
  }

  @override
515
  int get hashCode => Object.hash(borderSide, borderRadius, gapPadding);
516
}