feat! drag item image API clean-up (#105)

super_drag_and_drop/README.md

@@ -86,9 +86,6 @@ class MyDraggableWidget extends StatelessWidget {
       dragItemProvider: (request) async {
         // DragItem represents the content bein dragged.
         final item = DragItem(
-          // snapshot() will return image snapshot of the DragItemWidget.
-          // You can use any other drag image if your wish.
-          image: request.dragImage(),
           // This data is only accessible when dropping within same
           // application. (optional)
           localData: {'x': 3, 'y': 4},

super_drag_and_drop/example/lib/main.dart

@@ -209,9 +209,9 @@ class _MyHomePageState extends State<MyHomePage> {
       return null;
     }
     final item = DragItem(
-        image: request.dragImage(),
-        localData: 'text-item',
-        suggestedName: 'PlainText.txt');
+      localData: 'text-item',
+      suggestedName: 'PlainText.txt',
+    );
     item.add(Formats.plainText('Plain Text Value'));
     return item;
   }
@@ -222,7 +222,6 @@ class _MyHomePageState extends State<MyHomePage> {
       return null;
     }
     final item = DragItem(
-      image: request.dragImage(),
       localData: 'image-item',
       suggestedName: 'Green.png',
     );
@@ -236,7 +235,6 @@ class _MyHomePageState extends State<MyHomePage> {
       return null;
     }
     final item = DragItem(
-      image: await request.dragImage(),
       localData: 'lazy-image-item',
       suggestedName: 'LazyBlue.png',
     );
@@ -253,7 +251,6 @@ class _MyHomePageState extends State<MyHomePage> {
       return null;
     }
     final item = DragItem(
-      image: request.dragImage(),
       localData: 'virtual-file-item',
       suggestedName: 'VirtualFile.txt',
     );
@@ -283,7 +280,6 @@ class _MyHomePageState extends State<MyHomePage> {
       return null;
     }
     final item = DragItem(
-      image: request.dragImage(),
       localData: 'multiple-representations-item',
     );
     item.add(Formats.png(await createImageData(Colors.pink)));

super_drag_and_drop/lib/src/base_draggable_widget.dart

@@ -9,7 +9,7 @@ import 'drag_configuration.dart';
 typedef LocationIsDraggable = bool Function(Offset position);
 typedef DragConfigurationProvider = Future<DragConfiguration?> Function(
     Offset position, DragSession session);
-typedef AdditionalItemsProvider = Future<List<DragItem>?> Function(
+typedef AdditionalItemsProvider = Future<List<DragConfigurationItem>?> Function(
     Offset position, DragSession session);
 
 /// This is the most basic draggable widget. It gives you complete control
@@ -44,7 +44,7 @@ class BaseDraggableWidget extends StatelessWidget {
   /// dragging item for current session.
   final AdditionalItemsProvider additionalItems;
 
-  static Future<List<DragItem>?> _defaultAdditionalItems(
+  static Future<List<DragConfigurationItem>?> _defaultAdditionalItems(
       Offset position, DragSession session) async {
     return null;
   }
@@ -77,19 +77,19 @@ class BaseDraggableWidget extends StatelessWidget {
     child = Listener(
       behavior: HitTestBehavior.translucent,
       onPointerDown: (_) {
-        Snapshotter.of(context)?.prepareFor({
+        Snapshotter.of(context)?.prepare({
           SnapshotType.drag,
           if (defaultTargetPlatform == TargetPlatform.iOS) SnapshotType.lift,
         });
       },
       onPointerCancel: (_) {
         if (context.mounted) {
-          Snapshotter.of(context)?.prepareFor({});
+          Snapshotter.of(context)?.prepare({});
         }
       },
       onPointerUp: (_) {
         if (context.mounted) {
-          Snapshotter.of(context)?.prepareFor({});
+          Snapshotter.of(context)?.prepare({});
         }
       },
       child: child,

super_drag_and_drop/lib/src/drag_configuration.dart

@@ -1,29 +1,13 @@
-import 'dart:async';
-
 import 'package:flutter/foundation.dart';
 import 'package:flutter/services.dart';
 import 'package:super_clipboard/super_clipboard.dart';
 import 'package:super_drag_and_drop/super_drag_and_drop.dart';
 import 'package:super_native_extensions/raw_drag_drop.dart' as raw;
 
-class DragImage {
-  DragImage({
-    required this.image,
-    this.liftImage,
-  });
-
-  /// Image used while dragging
-  raw.TargetedImage image;
-
-  /// If specified this image will be used for lift animation on iOS.
-  raw.TargetedImage? liftImage;
-}
-
 /// Represent single item being dragged in a [DragSession].
 class DragItem extends DataWriterItem {
   DragItem({
     super.suggestedName,
-    required this.image,
     this.localData,
   });
 
@@ -34,15 +18,38 @@ class DragItem extends DataWriterItem {
           defaultTargetPlatform == TargetPlatform.windows ||
           defaultTargetPlatform == TargetPlatform.iOS);
 
-  final FutureOr<DragImage> image;
-
   /// Data associated with this drag item that can be only read when dropping
   /// within same application. The data must be serializable with
   /// [StandardMessageCodec]. It is possible to read [localData] from
   /// one isolate in another isolate.
   final Object? localData;
 }
 
+class DragImage {
+  DragImage({
+    required this.image,
+    this.liftImage,
+  });
+
+  /// Image used while dragging
+  raw.TargetedImage image;
+
+  /// If specified this image will be used for lift animation on iOS.
+  raw.TargetedImage? liftImage;
+}
+
+/// Single item of [DragConfiguration] consisting of drag item and coresponing
+/// image.
+class DragConfigurationItem {
+  DragConfigurationItem({
+    required this.item,
+    required this.image,
+  });
+
+  final DragItem item;
+  final DragImage image;
+}
+
 /// Addtional options for drag session.
 class DragOptions {
   const DragOptions({
@@ -66,7 +73,7 @@ class DragConfiguration {
   });
 
   /// List of items in this session.
-  final List<DragItem> items;
+  final List<DragConfigurationItem> items;
 
   /// Allowed drop operation for this session.
   final List<raw.DropOperation> allowedOperations;

super_drag_and_drop/lib/src/draggable_widget.dart

@@ -13,28 +13,18 @@ import 'base_draggable_widget.dart';
 
 class DragItemRequest {
   DragItemRequest({
-    required this.dragImage,
     required this.location,
     required this.session,
   });
 
-  /// Provides snapshot image of the containing [DragItemWidget].
-  ///
-  /// If you want to customize the drag image you can wrap the [DragItemWidget]
-  /// in a [CustomSnapshotWidget].
-  ///
-  /// Note that using [dragImage] is optional, you can generate your own drag
-  /// image from scratch  when constructing [DragItem].
-  final Future<DragImage> Function() dragImage;
-
   /// Drag location in global coordinates.
   final Offset location;
 
   /// Current drag session.
   final raw.DragSession session;
 }
 
-typedef DragItemProvider = Future<DragItem?> Function(DragItemRequest);
+typedef DragItemProvider = FutureOr<DragItem?> Function(DragItemRequest);
 
 /// Widget that provides [DragItem] for a [DraggableWidget].
 ///
@@ -96,17 +86,8 @@ class DragItemWidget extends StatefulWidget {
   State<StatefulWidget> createState() => DragItemWidgetState();
 }
 
-class _SnapshotException implements Exception {
-  _SnapshotException(this.message);
-
-  final String message;
-
-  @override
-  String toString() => message;
-}
-
 class DragItemWidgetState extends State<DragItemWidget> {
-  Future<DragImage> _getSnapshot(Offset location) async {
+  Future<DragImage?> _getSnapshot(Offset location) async {
     final snapshotter = Snapshotter.of(_innerContext!)!;
     final dragSnapshot =
         await snapshotter.getSnapshot(location, SnapshotType.drag);
@@ -132,25 +113,30 @@ class DragItemWidgetState extends State<DragItemWidget> {
     }
 
     if (snapshot == null) {
-      // This might happen if widget is removed before snapshot is ready.
-      // TODO(knopp): Handle this better.
-      throw _SnapshotException('Failed get drag snapshot.');
+      return null;
     }
 
     return DragImage(image: snapshot, liftImage: liftSnapshot);
   }
 
-  Future<DragItem?> createItem(Offset location, raw.DragSession session) async {
+  Future<DragConfigurationItem?> createItem(
+      Offset location, raw.DragSession session) async {
     final request = DragItemRequest(
-      dragImage: () => _getSnapshot(location),
       location: location,
       session: session,
     );
-    try {
-      return widget.dragItemProvider(request);
-    } on _SnapshotException {
-      return null;
+
+    final item = await widget.dragItemProvider(request);
+    if (item != null) {
+      final image = await _getSnapshot(location);
+      if (image != null) {
+        return DragConfigurationItem(
+          item: item,
+          image: image,
+        );
+      }
     }
+    return null;
   }
 
   Future<List<raw.DropOperation>> getAllowedOperations() async {
@@ -176,8 +162,8 @@ typedef DragItemsProvider = List<DragItemWidgetState> Function(
 typedef OnDragConfiguration = FutureOr<DragConfiguration?> Function(
     DragConfiguration configuration, raw.DragSession session);
 
-typedef OnAdditonalItems = FutureOr<List<DragItem>?> Function(
-    List<DragItem> items, raw.DragSession session);
+typedef OnAdditonalItems = FutureOr<List<DragConfigurationItem>?> Function(
+    List<DragConfigurationItem> items, raw.DragSession session);
 
 /// Widget that represents user-draggable area.
 
@@ -240,7 +226,7 @@ class DraggableWidget extends StatelessWidget {
     }
 
     if (allowedOperations?.isNotEmpty == true) {
-      final dragItems = <DragItem>[];
+      final dragItems = <DragConfigurationItem>[];
       for (final item in items) {
         final dragItem = await item.createItem(location, session);
         if (dragItem != null) {
@@ -249,7 +235,9 @@ class DraggableWidget extends StatelessWidget {
       }
       if (dragItems.isNotEmpty) {
         final configuration = DragConfiguration(
-            items: dragItems, allowedOperations: allowedOperations!);
+          items: dragItems,
+          allowedOperations: allowedOperations!,
+        );
         if (onDragConfiguration != null) {
           return onDragConfiguration!(configuration, session);
         } else {
@@ -260,9 +248,11 @@ class DraggableWidget extends StatelessWidget {
     return null;
   }
 
-  Future<List<DragItem>?> additionalItems(List<DragItemWidgetState> items,
-      Offset location, raw.DragSession session) async {
-    final dragItems = <DragItem>[];
+  Future<List<DragConfigurationItem>?> additionalItems(
+      List<DragItemWidgetState> items,
+      Offset location,
+      raw.DragSession session) async {
+    final dragItems = <DragConfigurationItem>[];
     for (final item in items) {
       if (item.widget.canAddItemToExistingSession) {
         final dragItem = await item.createItem(location, session);

super_drag_and_drop/lib/src/into_raw.dart

@@ -16,27 +16,24 @@ extension DragImageIntoRaw on DragImage {
   }
 }
 
-extension DragItemsIntoRaw on List<DragItem> {
+extension DragItemsIntoRaw on List<DragConfigurationItem> {
   Future<List<raw.DragItem>> intoRaw(double devicePixelRatio) async {
     final providers = <raw.DataProvider>[];
     for (final item in this) {
-      providers.add(await item.asDataProvider());
+      providers.add(await item.item.asDataProvider());
     }
     final handles = <raw.DataProviderHandle>[];
     for (final item in indexed()) {
       final handle =
-          await item.value.registerWithDataProvider(providers[item.index]);
+          await item.value.item.registerWithDataProvider(providers[item.index]);
       handles.add(handle);
     }
     final items = <raw.DragItem>[];
     for (final item in indexed()) {
-      final image = item.value.image is Future
-          ? await item.value.image
-          : item.value.image as DragImage;
       items.add(raw.DragItem(
         dataProvider: handles[item.index],
-        image: await image.intoRaw(devicePixelRatio),
-        localData: item.value.localData,
+        image: await item.value.image.intoRaw(devicePixelRatio),
+        localData: item.value.item.localData,
       ));
     }
     return items;

super_drag_and_drop/lib/super_drag_and_drop.dart

@@ -4,6 +4,7 @@ export 'package:super_clipboard/src/format.dart';
 export 'package:super_clipboard/src/standard_formats.dart';
 export 'package:super_native_extensions/widgets.dart'
     show
+        RawCustomSnapshotWidget,
         CustomSnapshotWidget,
         SnapshotType,
         SnapshotBuilder,