From 8319a6c2820cf59e5668b518f91b79e0493101ef Mon Sep 17 00:00:00 2001 From: Adam Barth Date: Thu, 4 Feb 2016 12:05:42 -0800 Subject: [PATCH] Add some more dartdoc to gestures.dart --- packages/flutter/lib/src/gestures/arena.dart | 75 +++++++++++-------- .../flutter/lib/src/gestures/binding.dart | 4 +- .../flutter/lib/src/gestures/converter.dart | 28 +++---- packages/flutter/lib/src/gestures/events.dart | 43 ++++++++--- .../flutter/lib/src/gestures/long_press.dart | 1 + 5 files changed, 96 insertions(+), 55 deletions(-) diff --git a/packages/flutter/lib/src/gestures/arena.dart b/packages/flutter/lib/src/gestures/arena.dart index c80b3f5e905..69b6da2055f 100644 --- a/packages/flutter/lib/src/gestures/arena.dart +++ b/packages/flutter/lib/src/gestures/arena.dart @@ -2,9 +2,13 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +/// Whether the gesture was accepted or rejected. enum GestureDisposition { + /// This gesture was accepted as the interpretation of the user's input. accepted, - rejected + + /// This gesture was rejected as the interpretation of the user's input. + rejected, } /// Represents an object participating in an arena. @@ -61,26 +65,33 @@ class _GestureArenaState { } /// The first member to accept or the last member to not to reject wins. +/// +/// See [https://flutter.io/gestures/#gesture-disambiguation] for more +/// information about the role this class plays in the gesture system. class GestureArena { final Map _arenas = new Map(); - GestureArenaEntry add(Object key, GestureArenaMember member) { - _GestureArenaState state = _arenas.putIfAbsent(key, () => new _GestureArenaState()); + /// Adds a new member (e.g., gesture recognizer) to the arena. + GestureArenaEntry add(Object arenaKey, GestureArenaMember member) { + _GestureArenaState state = _arenas.putIfAbsent(arenaKey, () => new _GestureArenaState()); state.add(member); - return new GestureArenaEntry._(this, key, member); + return new GestureArenaEntry._(this, arenaKey, member); } - void close(Object key) { - _GestureArenaState state = _arenas[key]; + /// Prevents new members from entering the arena. + /// + /// Called after the framework has finished dispatching the pointer down event. + void close(Object arenaKey) { + _GestureArenaState state = _arenas[arenaKey]; if (state == null) return; // This arena either never existed or has been resolved. state.isOpen = false; - _tryToResolveArena(key, state); + _tryToResolveArena(arenaKey, state); } - /// Forces resolution on this arena, giving the win to the first member. - void sweep(Object key) { - _GestureArenaState state = _arenas[key]; + /// Forces resolution of the arena, giving the win to the first member. + void sweep(Object arenaKey) { + _GestureArenaState state = _arenas[arenaKey]; if (state == null) return; // This arena either never existed or has been resolved. assert(!state.isOpen); @@ -88,13 +99,13 @@ class GestureArena { state.hasPendingSweep = true; return; // This arena is being held for a long-lived member } - _arenas.remove(key); + _arenas.remove(arenaKey); if (!state.members.isEmpty) { // First member wins - state.members.first.acceptGesture(key); + state.members.first.acceptGesture(arenaKey); // Give all the other members the bad news for (int i = 1; i < state.members.length; i++) - state.members[i].rejectGesture(key); + state.members[i].rejectGesture(arenaKey); } } @@ -110,58 +121,58 @@ class GestureArena { /// /// If a sweep was attempted on a held arena, the sweep will be done /// on release. - void release(Object key) { - _GestureArenaState state = _arenas[key]; + void release(Object arenaKey) { + _GestureArenaState state = _arenas[arenaKey]; if (state == null) return; // This arena either never existed or has been resolved. state.isHeld = false; if (state.hasPendingSweep) - sweep(key); + sweep(arenaKey); } - void _tryToResolveArena(Object key, _GestureArenaState state) { - assert(_arenas[key] == state); + void _tryToResolveArena(Object arenaKey, _GestureArenaState state) { + assert(_arenas[arenaKey] == state); assert(!state.isOpen); if (state.members.length == 1) { - _arenas.remove(key); - state.members.first.acceptGesture(key); + _arenas.remove(arenaKey); + state.members.first.acceptGesture(arenaKey); } else if (state.members.isEmpty) { - _arenas.remove(key); + _arenas.remove(arenaKey); } else if (state.eagerWinner != null) { - _resolveInFavorOf(key, state, state.eagerWinner); + _resolveInFavorOf(arenaKey, state, state.eagerWinner); } } - void _resolve(Object key, GestureArenaMember member, GestureDisposition disposition) { - _GestureArenaState state = _arenas[key]; + void _resolve(Object arenaKey, GestureArenaMember member, GestureDisposition disposition) { + _GestureArenaState state = _arenas[arenaKey]; if (state == null) return; // This arena has already resolved. assert(state.members.contains(member)); if (disposition == GestureDisposition.rejected) { state.members.remove(member); - member.rejectGesture(key); + member.rejectGesture(arenaKey); if (!state.isOpen) - _tryToResolveArena(key, state); + _tryToResolveArena(arenaKey, state); } else { assert(disposition == GestureDisposition.accepted); if (state.isOpen) { state.eagerWinner ??= member; } else { - _resolveInFavorOf(key, state, member); + _resolveInFavorOf(arenaKey, state, member); } } } - void _resolveInFavorOf(Object key, _GestureArenaState state, GestureArenaMember member) { - assert(state == _arenas[key]); + void _resolveInFavorOf(Object arenaKey, _GestureArenaState state, GestureArenaMember member) { + assert(state == _arenas[arenaKey]); assert(state != null); assert(state.eagerWinner == null || state.eagerWinner == member); assert(!state.isOpen); - _arenas.remove(key); + _arenas.remove(arenaKey); for (GestureArenaMember rejectedMember in state.members) { if (rejectedMember != member) - rejectedMember.rejectGesture(key); + rejectedMember.rejectGesture(arenaKey); } - member.acceptGesture(key); + member.acceptGesture(arenaKey); } } diff --git a/packages/flutter/lib/src/gestures/binding.dart b/packages/flutter/lib/src/gestures/binding.dart index 6d8c98bd0b0..0cc7c63c19c 100644 --- a/packages/flutter/lib/src/gestures/binding.dart +++ b/packages/flutter/lib/src/gestures/binding.dart @@ -18,6 +18,7 @@ import 'pointer_router.dart'; typedef void GesturerExceptionHandler(PointerEvent event, HitTestTarget target, dynamic exception, StackTrace stack); +/// A binding for the gesture subsystem. abstract class Gesturer extends BindingBase implements HitTestTarget, HitTestable { void initInstances() { @@ -26,8 +27,9 @@ abstract class Gesturer extends BindingBase implements HitTestTarget, HitTestabl ui.window.onPointerPacket = _handlePointerPacket; } - static Gesturer _instance; + /// The singleton instance of this object. static Gesturer get instance => _instance; + static Gesturer _instance; void _handlePointerPacket(ByteData serializedPacket) { final mojo_bindings.Message message = new mojo_bindings.Message( diff --git a/packages/flutter/lib/src/gestures/converter.dart b/packages/flutter/lib/src/gestures/converter.dart index 1a9c0e65752..67b4fbcfd4c 100644 --- a/packages/flutter/lib/src/gestures/converter.dart +++ b/packages/flutter/lib/src/gestures/converter.dart @@ -2,7 +2,7 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. -import 'package:sky_services/pointer/pointer.mojom.dart'; +import 'package:sky_services/pointer/pointer.mojom.dart' as mojom; import 'events.dart'; @@ -31,18 +31,20 @@ class _PointerState { Point lastPosition; } +/// Converts from engine pointer data to framework pointer events. class PointerEventConverter { // Map from platform pointer identifiers to PointerEvent pointer identifiers. static Map _pointers = {}; - static Iterable expand(Iterable packet) sync* { - for (Pointer datum in packet) { + /// Expand the given packet of pointer data into a sequence of framework pointer events. + static Iterable expand(Iterable packet) sync* { + for (mojom.Pointer datum in packet) { Point position = new Point(datum.x, datum.y); Duration timeStamp = new Duration(microseconds: datum.timeStamp); assert(_pointerKindMap.containsKey(datum.kind)); PointerDeviceKind kind = _pointerKindMap[datum.kind]; switch (datum.type) { - case PointerType.down: + case mojom.PointerType.down: assert(!_pointers.containsKey(datum.pointer)); _PointerState state = _pointers.putIfAbsent( datum.pointer, @@ -84,7 +86,7 @@ class PointerEventConverter { tilt: datum.tilt ); break; - case PointerType.move: + case mojom.PointerType.move: // If the service starts supporting hover pointers, then it must also // start sending us ADDED and REMOVED data points. // See also: https://github.com/flutter/flutter/issues/720 @@ -114,14 +116,14 @@ class PointerEventConverter { tilt: datum.tilt ); break; - case PointerType.up: - case PointerType.cancel: + case mojom.PointerType.up: + case mojom.PointerType.cancel: assert(_pointers.containsKey(datum.pointer)); _PointerState state = _pointers[datum.pointer]; assert(state.down); assert(position == state.lastPosition); state.setUp(); - if (datum.type == PointerType.up) { + if (datum.type == mojom.PointerType.up) { yield new PointerUpEvent( timeStamp: timeStamp, pointer: state.pointer, @@ -174,10 +176,10 @@ class PointerEventConverter { } } - static const Map _pointerKindMap = const { - PointerKind.touch: PointerDeviceKind.touch, - PointerKind.mouse: PointerDeviceKind.mouse, - PointerKind.stylus: PointerDeviceKind.stylus, - PointerKind.invertedStylus: PointerDeviceKind.invertedStylus, + static const Map _pointerKindMap = const { + mojom.PointerKind.touch: PointerDeviceKind.touch, + mojom.PointerKind.mouse: PointerDeviceKind.mouse, + mojom.PointerKind.stylus: PointerDeviceKind.stylus, + mojom.PointerKind.invertedStylus: PointerDeviceKind.invertedStylus, }; } diff --git a/packages/flutter/lib/src/gestures/events.dart b/packages/flutter/lib/src/gestures/events.dart index 2940269e913..c9dd4144952 100644 --- a/packages/flutter/lib/src/gestures/events.dart +++ b/packages/flutter/lib/src/gestures/events.dart @@ -6,17 +6,30 @@ import 'dart:ui' show Point, Offset; export 'dart:ui' show Point, Offset; -enum PointerDeviceKind { touch, stylus, invertedStylus, mouse } +/// The kind of pointer device. +enum PointerDeviceKind { + /// A touch-based pointer device. + touch, -const int primaryMouseButton = 0x01; -const int secondaryMouseButton = 0x02; -const int primaryStylusButton = 0x02; -const int middleMouseButton = 0x04; -const int secondaryStylusButton = 0x04; -const int backMouseButton = 0x08; + /// A pointer device with a stylus. + stylus, + + /// A pointer device with a stylus that has been inverted. + invertedStylus, + + /// A mouse-based pointer device. + mouse +} + +const int kPrimaryMouseButton = 0x01; +const int kSecondaryMouseButton = 0x02; +const int kPrimaryStylusButton = 0x02; +const int kMiddleMouseButton = 0x04; +const int kSecondaryStylusButton = 0x04; +const int kBackMouseButton = 0x08; const int forwardMouseButton = 0x10; -int nthMouseButton(int number) => primaryMouseButton << (number - 1); -int nthStylusButton(int number) => primaryStylusButton << (number - 1); +int nthMouseButton(int number) => kPrimaryMouseButton << (number - 1); +int nthStylusButton(int number) => kPrimaryStylusButton << (number - 1); /// Base class for touch, stylus, or mouse events. abstract class PointerEvent { @@ -186,6 +199,10 @@ abstract class PointerEvent { } } +/// The device has started tracking the pointer. +/// +/// For example, the pointer might be hovering above the device, having not yet +/// made contact with the surface of the device. class PointerAddedEvent extends PointerEvent { const PointerAddedEvent({ Duration timeStamp: Duration.ZERO, @@ -218,6 +235,10 @@ class PointerAddedEvent extends PointerEvent { ); } +/// The device is no longer tracking the pointer. +/// +/// For example, the pointer might have drifted out of the device's hover +/// detection range or might have been disconnected from the system entirely. class PointerRemovedEvent extends PointerEvent { const PointerRemovedEvent({ Duration timeStamp: Duration.ZERO, @@ -243,6 +264,7 @@ class PointerRemovedEvent extends PointerEvent { ); } +/// The pointer has made contact with the device. class PointerDownEvent extends PointerEvent { const PointerDownEvent({ Duration timeStamp: Duration.ZERO, @@ -283,6 +305,7 @@ class PointerDownEvent extends PointerEvent { ); } +/// The pointer has moved with respect to the device. class PointerMoveEvent extends PointerEvent { const PointerMoveEvent({ Duration timeStamp: Duration.ZERO, @@ -327,6 +350,7 @@ class PointerMoveEvent extends PointerEvent { ); } +/// The pointer has stopped making contact with the device. class PointerUpEvent extends PointerEvent { const PointerUpEvent({ Duration timeStamp: Duration.ZERO, @@ -361,6 +385,7 @@ class PointerUpEvent extends PointerEvent { ); } +/// The input from the pointer is no longer directed towards this receiver. class PointerCancelEvent extends PointerEvent { const PointerCancelEvent({ Duration timeStamp: Duration.ZERO, diff --git a/packages/flutter/lib/src/gestures/long_press.dart b/packages/flutter/lib/src/gestures/long_press.dart index a3010a21304..3abb49a6024 100644 --- a/packages/flutter/lib/src/gestures/long_press.dart +++ b/packages/flutter/lib/src/gestures/long_press.dart @@ -10,6 +10,7 @@ import 'recognizer.dart'; typedef void GestureLongPressCallback(); +/// The user has pressed down at this location for a long period of time. class LongPressGestureRecognizer extends PrimaryPointerGestureRecognizer { LongPressGestureRecognizer({ PointerRouter router,