drag_details.dart 9.27 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
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'package:flutter/foundation.dart';

import 'velocity_tracker.dart';

9 10 11 12
export 'dart:ui' show Offset, PointerDeviceKind;

export 'velocity_tracker.dart' show Velocity;

13 14 15 16 17 18 19 20 21 22 23 24
/// Details object for callbacks that use [GestureDragDownCallback].
///
/// See also:
///
///  * [DragGestureRecognizer.onDown], which uses [GestureDragDownCallback].
///  * [DragStartDetails], the details for [GestureDragStartCallback].
///  * [DragUpdateDetails], the details for [GestureDragUpdateCallback].
///  * [DragEndDetails], the details for [GestureDragEndCallback].
class DragDownDetails {
  /// Creates details for a [GestureDragDownCallback].
  ///
  /// The [globalPosition] argument must not be null.
25 26
  DragDownDetails({
    this.globalPosition = Offset.zero,
27
    Offset? localPosition,
28
  }) : localPosition = localPosition ?? globalPosition;
29 30 31 32

  /// The global position at which the pointer contacted the screen.
  ///
  /// Defaults to the origin if not specified in the constructor.
33 34 35 36 37
  ///
  /// See also:
  ///
  ///  * [localPosition], which is the [globalPosition] transformed to the
  ///    coordinate space of the event receiver.
38 39
  final Offset globalPosition;

40 41 42 43 44 45
  /// The local position in the coordinate system of the event receiver at
  /// which the pointer contacted the screen.
  ///
  /// Defaults to [globalPosition] if not specified in the constructor.
  final Offset localPosition;

46
  @override
47
  String toString() => '${objectRuntimeType(this, 'DragDownDetails')}($globalPosition)';
48 49 50 51 52 53 54 55
}

/// Signature for when a pointer has contacted the screen and might begin to
/// move.
///
/// The `details` object provides the position of the touch.
///
/// See [DragGestureRecognizer.onDown].
56
typedef GestureDragDownCallback = void Function(DragDownDetails details);
57 58 59 60 61 62 63 64 65 66 67 68 69

/// Details object for callbacks that use [GestureDragStartCallback].
///
/// See also:
///
///  * [DragGestureRecognizer.onStart], which uses [GestureDragStartCallback].
///  * [DragDownDetails], the details for [GestureDragDownCallback].
///  * [DragUpdateDetails], the details for [GestureDragUpdateCallback].
///  * [DragEndDetails], the details for [GestureDragEndCallback].
class DragStartDetails {
  /// Creates details for a [GestureDragStartCallback].
  ///
  /// The [globalPosition] argument must not be null.
70 71 72
  DragStartDetails({
    this.sourceTimeStamp,
    this.globalPosition = Offset.zero,
73
    Offset? localPosition,
74
    this.kind,
75
  }) : localPosition = localPosition ?? globalPosition;
76

77 78 79 80
  /// Recorded timestamp of the source pointer event that triggered the drag
  /// event.
  ///
  /// Could be null if triggered from proxied events such as accessibility.
81
  final Duration? sourceTimeStamp;
82

83 84 85
  /// The global position at which the pointer contacted the screen.
  ///
  /// Defaults to the origin if not specified in the constructor.
86 87 88 89 90
  ///
  /// See also:
  ///
  ///  * [localPosition], which is the [globalPosition] transformed to the
  ///    coordinate space of the event receiver.
91 92
  final Offset globalPosition;

93 94 95 96 97 98
  /// The local position in the coordinate system of the event receiver at
  /// which the pointer contacted the screen.
  ///
  /// Defaults to [globalPosition] if not specified in the constructor.
  final Offset localPosition;

99 100 101
  /// The kind of the device that initiated the event.
  final PointerDeviceKind? kind;

102 103 104 105
  // TODO(ianh): Expose the current position, so that you can have a no-jump
  // drag even when disambiguating (though of course it would lag the finger
  // instead).

106
  @override
107
  String toString() => '${objectRuntimeType(this, 'DragStartDetails')}($globalPosition)';
108 109
}

110
/// {@template flutter.gestures.dragdetails.GestureDragStartCallback}
111 112 113 114
/// Signature for when a pointer has contacted the screen and has begun to move.
///
/// The `details` object provides the position of the touch when it first
/// touched the surface.
115
/// {@endtemplate}
116 117
///
/// See [DragGestureRecognizer.onStart].
118
typedef GestureDragStartCallback = void Function(DragStartDetails details);
119 120 121 122 123 124 125 126 127 128

/// Details object for callbacks that use [GestureDragUpdateCallback].
///
/// See also:
///
///  * [DragGestureRecognizer.onUpdate], which uses [GestureDragUpdateCallback].
///  * [DragDownDetails], the details for [GestureDragDownCallback].
///  * [DragStartDetails], the details for [GestureDragStartCallback].
///  * [DragEndDetails], the details for [GestureDragEndCallback].
class DragUpdateDetails {
129
  /// Creates details for a [GestureDragUpdateCallback].
130 131 132 133 134 135 136 137
  ///
  /// The [delta] argument must not be null.
  ///
  /// If [primaryDelta] is non-null, then its value must match one of the
  /// coordinates of [delta] and the other coordinate must be zero.
  ///
  /// The [globalPosition] argument must be provided and must not be null.
  DragUpdateDetails({
138
    this.sourceTimeStamp,
139
    this.delta = Offset.zero,
140
    this.primaryDelta,
141 142
    required this.globalPosition,
    Offset? localPosition,
143
  }) : assert(
144
         primaryDelta == null
145
           || (primaryDelta == delta.dx && delta.dy == 0.0)
146 147
           || (primaryDelta == delta.dy && delta.dx == 0.0),
       ),
148
       localPosition = localPosition ?? globalPosition;
149

150 151 152 153
  /// Recorded timestamp of the source pointer event that triggered the drag
  /// event.
  ///
  /// Could be null if triggered from proxied events such as accessibility.
154
  final Duration? sourceTimeStamp;
155

156 157
  /// The amount the pointer has moved in the coordinate space of the event
  /// receiver since the previous update.
158 159 160 161 162 163 164 165
  ///
  /// If the [GestureDragUpdateCallback] is for a one-dimensional drag (e.g.,
  /// a horizontal or vertical drag), then this offset contains only the delta
  /// in that direction (i.e., the coordinate in the other direction is zero).
  ///
  /// Defaults to zero if not specified in the constructor.
  final Offset delta;

166 167
  /// The amount the pointer has moved along the primary axis in the coordinate
  /// space of the event receiver since the previous
168 169 170 171 172 173 174 175 176
  /// update.
  ///
  /// If the [GestureDragUpdateCallback] is for a one-dimensional drag (e.g.,
  /// a horizontal or vertical drag), then this value contains the component of
  /// [delta] along the primary axis (e.g., horizontal or vertical,
  /// respectively). Otherwise, if the [GestureDragUpdateCallback] is for a
  /// two-dimensional drag (e.g., a pan), then this value is null.
  ///
  /// Defaults to null if not specified in the constructor.
177
  final double? primaryDelta;
178 179

  /// The pointer's global position when it triggered this update.
180 181 182 183 184
  ///
  /// See also:
  ///
  ///  * [localPosition], which is the [globalPosition] transformed to the
  ///    coordinate space of the event receiver.
185
  final Offset globalPosition;
186 187 188 189 190 191

  /// The local position in the coordinate system of the event receiver at
  /// which the pointer contacted the screen.
  ///
  /// Defaults to [globalPosition] if not specified in the constructor.
  final Offset localPosition;
192 193

  @override
194
  String toString() => '${objectRuntimeType(this, 'DragUpdateDetails')}($delta)';
195 196
}

197
/// {@template flutter.gestures.dragdetails.GestureDragUpdateCallback}
198 199 200 201
/// Signature for when a pointer that is in contact with the screen and moving
/// has moved again.
///
/// The `details` object provides the position of the touch and the distance it
202
/// has traveled since the last update.
203
/// {@endtemplate}
204 205
///
/// See [DragGestureRecognizer.onUpdate].
206
typedef GestureDragUpdateCallback = void Function(DragUpdateDetails details);
207 208 209 210 211 212 213 214 215 216 217 218

/// Details object for callbacks that use [GestureDragEndCallback].
///
/// See also:
///
///  * [DragGestureRecognizer.onEnd], which uses [GestureDragEndCallback].
///  * [DragDownDetails], the details for [GestureDragDownCallback].
///  * [DragStartDetails], the details for [GestureDragStartCallback].
///  * [DragUpdateDetails], the details for [GestureDragUpdateCallback].
class DragEndDetails {
  /// Creates details for a [GestureDragEndCallback].
  ///
219 220 221 222
  /// If [primaryVelocity] is non-null, its value must match one of the
  /// coordinates of `velocity.pixelsPerSecond` and the other coordinate
  /// must be zero.
  ///
223 224
  /// The [velocity] argument must not be null.
  DragEndDetails({
225
    this.velocity = Velocity.zero,
226
    this.primaryVelocity,
227
  }) : assert(
228
         primaryVelocity == null
229 230
           || (primaryVelocity == velocity.pixelsPerSecond.dx && velocity.pixelsPerSecond.dy == 0)
           || (primaryVelocity == velocity.pixelsPerSecond.dy && velocity.pixelsPerSecond.dx == 0),
231
       );
232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247

  /// The velocity the pointer was moving when it stopped contacting the screen.
  ///
  /// Defaults to zero if not specified in the constructor.
  final Velocity velocity;

  /// The velocity the pointer was moving along the primary axis when it stopped
  /// contacting the screen, in logical pixels per second.
  ///
  /// If the [GestureDragEndCallback] is for a one-dimensional drag (e.g., a
  /// horizontal or vertical drag), then this value contains the component of
  /// [velocity] along the primary axis (e.g., horizontal or vertical,
  /// respectively). Otherwise, if the [GestureDragEndCallback] is for a
  /// two-dimensional drag (e.g., a pan), then this value is null.
  ///
  /// Defaults to null if not specified in the constructor.
248
  final double? primaryVelocity;
249 250

  @override
251
  String toString() => '${objectRuntimeType(this, 'DragEndDetails')}($velocity)';
252
}