key.dart 3.11 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 8 9 10 11 12 13
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'dart:ui' show hashValues;

import 'package:meta/meta.dart';

/// A [Key] is an identifier for [Widget]s, [Element]s and [SemanticsNode]s.
///
/// A new widget will only be used to update an existing element if its key is
/// the same as the key of the current widget associated with the element.
///
14 15
/// {@youtube 560 315 https://www.youtube.com/watch?v=kn0EOS-ZiIc}
///
16 17 18 19
/// Keys must be unique amongst the [Element]s with the same parent.
///
/// Subclasses of [Key] should either subclass [LocalKey] or [GlobalKey].
///
20 21 22
/// See also:
///
///  * [Widget.key], which discusses how widgets use keys.
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
@immutable
abstract class Key {
  /// Construct a [ValueKey<String>] with the given [String].
  ///
  /// This is the simplest way to create keys.
  const factory Key(String value) = ValueKey<String>;

  /// Default constructor, used by subclasses.
  ///
  /// Useful so that subclasses can call us, because the [new Key] factory
  /// constructor shadows the implicit constructor.
  @protected
  const Key.empty();
}

/// A key that is not a [GlobalKey].
///
/// Keys must be unique amongst the [Element]s with the same parent. By
/// contrast, [GlobalKey]s must be unique across the entire app.
///
43 44 45
/// See also:
///
///  * [Widget.key], which discusses how widgets use keys.
46
abstract class LocalKey extends Key {
47 48
  /// Abstract const constructor. This constructor enables subclasses to provide
  /// const constructors so that they can be used in const expressions.
49 50 51 52 53 54 55 56 57 58 59 60 61 62
  const LocalKey() : super.empty();
}

/// A key that uses a value of a particular type to identify itself.
///
/// A [ValueKey<T>] is equal to another [ValueKey<T>] if, and only if, their
/// values are [operator==].
///
/// This class can be subclassed to create value keys that will not be equal to
/// other value keys that happen to use the same value. If the subclass is
/// private, this results in a value key type that cannot collide with keys from
/// other sources, which could be useful, for example, if the keys are being
/// used as fallbacks in the same scope as keys supplied from another widget.
///
63 64 65
/// See also:
///
///  * [Widget.key], which discusses how widgets use keys.
66 67 68 69 70 71 72 73
class ValueKey<T> extends LocalKey {
  /// Creates a key that delegates its [operator==] to the given value.
  const ValueKey(this.value);

  /// The value to which this key delegates its [operator==]
  final T value;

  @override
74
  bool operator ==(Object other) {
75 76
    if (other.runtimeType != runtimeType)
      return false;
77 78
    return other is ValueKey<T>
        && other.value == value;
79 80 81 82 83 84 85
  }

  @override
  int get hashCode => hashValues(runtimeType, value);

  @override
  String toString() {
86
    final String valueString = T == String ? "<'$value'>" : '<$value>';
87
    // The crazy on the next line is a workaround for
88
    // https://github.com/dart-lang/sdk/issues/33297
89
    if (runtimeType == _TypeLiteral<ValueKey<T>>().type)
90 91 92 93 94
      return '[$valueString]';
    return '[$T $valueString]';
  }
}

95 96 97
class _TypeLiteral<T> {
  Type get type => T;
}