[Spec] DragGestureRecognizer DropGestureRecognizer

[PureWeen]

DragGestureRecognizer

• Allow users to activate a view for dragging

DropGestureRecognizer

• Allow users to react to a view being dragged over it and then react

API

VisualStates associated with target drop

<VisualStateGroup x:Name="DragAndDropStates">
            <VisualState x:Name="IsDragging">
            </VisualState>
            <VisualState x:Name="DragOver">
            </VisualState>
</VisualStateGroup>

DropGestureRecognizer

public class DropGestureRecognizer
{
     public bool AllowDrop;
     public DragEventArgs DragOver;
     public DropEventArgs Drop;
}

Properties

API	Description
AllowDrop	This sets up a view to be receiver of a view that's being dropped.

Events

API	Description
DragOver	This fires when a dragged view is over the receiver view. This fires on the target view
Drop	This fires on the target when the user let's go of the view being dragged

DragGestureRecognizer

public class DragGestureRecognizer
{
     public bool CanDrag;
     public DropCompletedEventArgs DropCompleted;
     public DragItemsStartingEventArgs DragStarting;
}

Properties

API	Description
CanDrag	This indicates that this view will be the draggable one.

Events

API	Description
DropCompleted	This fire once the drop operation has completed
DragStarting	This fires once it's detected that the user wants to initiate a drag operation.

DragState

public enum DragState
{
     Started, Dragging, Completed, Cancelled
}

DragItemsStartingEventArgs

public class DragItemsStartingEventArgs
{
     bool Cancel;
     DataPackage Data;
}

Properties

API	Description
Cancel	Don't activate the drag operation.
DataPackage	Setup the data package to be dragged. If user doesn't specify anything then we just try our best to infer what it should be based on the source

DataPackageOperation

public enum DataPackageOperation
{
     None, Copy, Move
}

DragEventArgs

public class DragEventArgs
{
     DataPackage Data;
     DragState State;
     DataPackageOperation AcceptedOperation
}

Properties

API	Description
Data	This is the data package associated with the view being dragged. If someone drags an image to an image we'll just load the image into the target. If someone drags a label the data will be text and we'll apply the text. If it's just a view then the data will be a reference to that view and users can then just do something with it
State	This will indicate the state of the drag operation
AcceptedOperation	Indicates the types of actions this element will accept for the given data package. This is how you indicate that a given view will accept the given item.

DropCompletedEventArgs

public class DropCompletedEventArgs
{
     DataPackageOperation DropResult { get; }
}

Properties

API	Description
DataPackageOperation	Indicates the type of operation and whether or not it was successful. None means unsuccessful

DropEventArgs

public class DropEventArgs
{
     DataPackageView Data;
     bool Handled;
}

Properties

API	Description
Data	Readonly view of the data dropped on the target view
Handled	Set this to true if you've handled the data in the handler otherwise Forms will try to process the data itself based on the source/target combination

DataPackage

This is used to setup the data for transfer

public class DataPackage
{
     public void SetImage(ImageSource source);
     public void SetText(string value);
     public void SetUri(Uri value);
     public DataPackageView GetView()
}

DataPackageView

This is a read-only copy of the DataPackage object.
This is all the user gets on the drop event to retrieve the data. They can't modify the package

public class DataPackageView
{
     public ImageSource GetImageAsync();
     public string GetTextAsync();
     public Uri GetUriAsynci();
}

Examples

Basic Xaml Example

<StackLayout>
        <Image
           HorizontalOptions="Center"
           VerticalOptions="CenterAndExpand">
            <Image.GestureRecognizers>
                <DragGestureRecognizer CanDrag="{Binding EnableDragging}"></DragAndDropGestureRecognizer>
            </Image.GestureRecognizers>
        </Image>
         <StackLayout
           HorizontalOptions="Center"
           VerticalOptions="CenterAndExpand">
            <StackLayout.GestureRecognizers>
                <DropGestureRecognizer DragOver="DragOverStackLayout"  AllowDrop="true"></DropGestureRecognizer>
            </StackLayout.GestureRecognizers>
        </StackLayout>
        <Image
           HorizontalOptions="Center"
           VerticalOptions="CenterAndExpand">
            <Image.GestureRecognizers>
                <DropGestureRecognizer DragOver="DragOver" Drop="FiresWhenDropped"  AllowDrop="{Binding EnableDrop}"></DropGestureRecognizer>
            </Image.GestureRecognizers>
        </Image>
    </StackLayout>

Workflow

• User LongPresses on the drag target
• DragStarting event fires and the user doesn't do anything
  • Because the user doesn't do anything the ImageSource on the image is set on the data package
• user drags image over the StackLayout but inside DragOverStackLayout the user doesn't do anything so the SL won't receive the element if the user drops it herre
• once the finger is over the image DragOver fires and the user sets the accepted operation to something other than None
• Once the user lifts up their finger FiresWhenDropped fires
  • At this point if the user doesn't do anything than forms will set the ImageSource on the target
  • If they set Handled to True then forms does nothing

CollectionView considerations

First implementation won't have tight integration with CV

[dersia]

What about additional commands to the events?

I really like the specs, just would like to have commands as well as events.

[PureWeen]

@dersia

https://github.com/xamarin/Xamarin.Forms/pull/11537/files#diff-eaca5f8f9dd0e23a11bddbe989c5badaR15

I added commands for all the events

Thank you for the reminder 👍