New: Drag & Drop support!

New: Drag & Drop support!

Postby Brady » Tue Mar 08, 2011 1:22 am

I'm pleased to announce the 1.06 beta is now public and ready for testing of its two main new features: Drag & drop support, and snapping scroll lists! Please see the Announcements thread for info on getting the beta and what is required.

This thread will cover drag & drop support. I will now describe how to use this new feature briefly so you can get up-and-running and start testing them out. Please report your experiences, questions, etc, to this thread.

The new drag & drop feature makes it very easy to add drag/drop support to your game. It even supports multi-touch, meaning on a touchpad device, you can drag/drop multiple objects with multiple fingers at once, and completely independently of eachother.

The quick-start steps are:
1) Check the "Is Draggable" box on a control you want to be able to drag. This object will now automatically move when you drag it.

2) Then on any (ANY!) object you want to be able to "drop" this control onto (called a "drop target"), just declare an OnEZDragDrop() function in a script attached to it (see below for a couple of basic examples of such a function). A drop target doesn't have to be an EZ GUI object. It can be ANY object that has a collider. Just make sure it's in a layer the UIManager can "see".

That's all there is to it! Now on to a more thorough explanation:

First, you will notice a few new inspector settings which have been added for drag & drop support, and easing its use:

* Default Drag Offset - This is the default distance an object being dragged will be offset toward the camera so as to ensure that it "hovers" above other objects in the scene. This can be overridden in individual objects, if desired. If you find your controls are winding up "behind" other objects in the scene when you drag it, increase this value.

* Cancel Drag Easing - The easing to use when a drag operation is canceled. If you drop an object without a suitable drop target, it will using this easing method to move back to the place from where you dragged it.

* Cancel Drag Duration - This is the number of seconds the aforementioned animation should take.

Note that all the above settings in UIManager are just defaults. All of these settings can be overridden in individual controls, if desired. But if you leave the individual controls at their defaults, the values in UIManager will be used.

All controls:
* Is Draggable - When this box is checked, the control will be dragged if you drag it, and will generate drag & drop notifications for your delegates and other scripts.

* Drag Offset - Same as in UIManager. If left at the default of NaN, the value in UIManager will be used.

* Cancel Drag Easing - Same as in UIManager. If left at "Default", the value in UIManager will be used.

* Cancel Drag Duration - Same as in UIManager. If left at the default of -1, the value in UIManager will be used.

How to use it:
Once you've checked the "Is Draggable" box, the control will drag around when you drag it with your pointer. It's that easy. To react to the dragging and dropping, you can do one, or both, of two things:
1) Simply write an OnEZDragDrop() method in your own script, attached to the object you wish to receive dropped objects (see below for more details).


2) Register a delegate to be called by either the object being dragged, the object being dropped on, or both. This is done by calling any EZ GUI control's .AddDragDropDelegate() and passing it your delegate. The advantage to using delegates is you will be informed when the object being dragged begins its drag operation. This gives you the opportunity to respond to the initiation of the drag.

Below is a code example of a suitable method to respond to drag/drop messages, and this is also what a delegate should look like for use with AddDragDropDelegate(). This is a very simple example:

Code: Select all
void OnEZDragDrop(EZDragDropParams parms)
   if(parms.evt == EZDragDropEvent.Dropped)
      parms.dragObj.DropHandled = true;
      Debug.Log( + " was dropped!");
      // Do something to/with the object
      // that was just dropped here.

First, you'll note that OnEZDragDrop() receives an EZDragDropParams structure. This contains three pieces of information:
* evt - the drag/drop event that has occurred.
* dragObj - A reference to the object being dragged.
* ptr - A POINTER_INFO structure that can contain information about the pointer dragging the object. Note, however, that some types of drag/drop events will not populate this structure with relevant information as no pointer is involved in these types of events.

Next, note that we check for the "Dropped" event. This is sent when an object is being dropped onto a "drop target". This message is sent both to the control being dropped, to any registered delegate thereof, and to the drop target object itself. This lets you place the logic of validating a drop action in a place that makes sense for your game. If it makes more sense to let the drop target object decide for itself, you can do that. If however, the item being dropped should be the one to decide, you can do that as well.

Finally, you'll note that we set the dropObj's .DropHandled property to true. This tells EZ GUI that the drop was a success and therefore not to cancel the drag by returning the object to its original position. At this point, it is up to your code to do whatever you want with the dropped object.

That's all there is to basic dragging and dropping. Of course, there's more you can do. Below you'll find a basic skeleton method that handles all the supported drag/drop events, and describes each in the comments:

Code: Select all
void OnEZDragDrop(EZDragDropParams parms)
        // Respond to each possible event:
      case EZDragDropEvent.Begin:
         // A drag operation has begun...
      case EZDragDropEvent.Update:
         // The drag operation is ongoing. This message is sent
         // for every frame that the drag operation continues in
         // which some other sort of event does not occur, such
         // as a drop.
      case EZDragDropEvent.DragEnter:
         // Sent to notify a drop target that the object being
         // dragged has entered its area. You can use this as an
         // opportunity to validate whether the dragObj can be
         // dropped at its current DropTarget, and if so, to
         // provide feedback to the player to this effect.
      case EZDragDropEvent.DragExit:
         // Sent to notify a drop target that the object being
         // dragged has exited its area. You can use this as an
         // opportunity to unset any feedback you set in response
         // to DragEnter.
      case EZDragDropEvent.Dropped:
         // Sent when the object has been dropped.  If the
         // object's .DropHandled is not set to true at this
         // point, the drop will be considered a failure and the
         // object will return to its point of origin.

         // Example validation of drop:

         // See if the item is too heavy for the player to carry:
         MyPickupInfo nfo = parms.dragObj.Data as MyPickupInfo;
         if (nfo.weight <= Player.strength)
            // Accept the drop:
            parms.dragObj.DropHandled = true;
      case EZDragDropEvent.Cancelled:
         // Sent to notify concerned objects that the drag
         // operation has been cancelled and the object is now
         // returning to its point of origin.

You can define an OnEZDragDrop() method in any script, in either C# or JS. As long as the object you attach it to has a collider and is in a layer where EZ GUI will "see" it, it can be a drop target and its OnEZDragDrop() method will be called automatically whenever an EZ GUI control is dragged over it. That means ANY object can be a drop-target, not just EZ GUI controls. So you can use this to drop EZ GUI controls onto 3D in-world objects, if you want, for example.

As shown in the example, store the data you want communicated in the drag/drop operation in the control's .Data property. .Data is of type System.Object, meaning it can point to anything. In the example above, I've used it to point to "MyPickupInfo" which would be a class containing all the information I need for the item being dropped.

There are also some new properties and methods to EZ GUI controls you may find useful when working with drag-and-drop:
* IsDragging - This indicates whether the object is currently in the midst of being dragged/dropped.

* DropTarget - When this is non-null, it points to the first GameObject detected "behind" the object being dragged. This object will have its OnEZDragDrop() called, if any, while the dragged object is over it.

* CancelDrag() - Lets you cancel a drag operation mid-stream. This will do the same thing as if the item was dropped over an invalid drop target.

One final note: the point that is checked against drop targets, etc, is the point where the touch/click is. So if you grab your draggable object at its edge, then drag it over your drop area, it won't "hit" the drop area unless your pointer itself is over the drop area, even though the majority of the visible portion of the object being dragged may be over the drop area. So be sure to keep this in mind. If you would prefer the dragged object always remain centered around the pointer so as to help avoid confusion, comment out this line at the top of EZDragDropHelper.cs:
Code: Select all

Have fun!
Posts: 5361
Joined: Tue Jul 06, 2010 11:33 pm

Re: New: Drag & Drop support!

Postby sebastian » Tue Mar 08, 2011 8:58 pm

This is super awesome, Brady!!! Thanks for continuing to improve upon already excellent functionality!!
Posts: 90
Joined: Mon Jan 24, 2011 6:23 pm
Location: Brooklyn, NY

Re: New: Drag & Drop support!

Postby Little Angel » Tue Mar 08, 2011 9:59 pm

Little Angel
Posts: 772
Joined: Thu Sep 02, 2010 10:23 pm

Re: New: Drag & Drop support!

Postby MidnightWare » Thu Mar 10, 2011 8:41 pm

Totally cool, thanks Brady!
Posts: 18
Joined: Wed Dec 01, 2010 9:23 pm

Re: New: Drag & Drop support!

Postby Malveka » Fri Mar 11, 2011 1:19 am

Really exciting and useful new feature. Looking forward to trying this out!

Posts: 152
Joined: Sun Jul 11, 2010 1:56 am

Re: New: Drag & Drop support!

Postby monkey » Fri Mar 11, 2011 7:07 am

Great feature and impeccable timing. I was just thinking about how I might be able to do this
Posts: 11
Joined: Thu Feb 10, 2011 12:20 pm

Re: New: Drag & Drop support!

Postby Crazy Robot » Sun Mar 13, 2011 3:19 am


This is awesome!

I have one question, is there a way to drag an object and when the player drops the object, it just stays where is was dropped instead of moving back to it's starting point without having an object as a target?


Crazy Robot
Posts: 26
Joined: Wed Feb 09, 2011 1:01 am

Re: New: Drag & Drop support!

Postby Brady » Sun Mar 13, 2011 5:21 am

Yes, your delegate/OnEZDragDrop() method just needs to set the .DropHandled property to true.
Posts: 5361
Joined: Tue Jul 06, 2010 11:33 pm

Re: New: Drag & Drop support!

Postby dilbertian » Mon Apr 04, 2011 4:29 am

Excellent timing! I just started to look at how I would be doing Drag and Drop tonight and stumbled across this thread!

I can't wait to give it a try. Thank you!!
Posts: 7
Joined: Tue Mar 29, 2011 3:12 pm

Re: New: Drag & Drop support!

Postby Rafe » Tue Apr 05, 2011 7:03 am


I created a cube, added a UIButton3D to it and turned on isDraggable. I then started the game and when I tried to drag the box, these errors ocurred:

First when dragging:
Code: Select all
transform.position assign attempt for 'Cube' is not valid. Input position is { NaN, NaN, NaN }.
EZDragDropHelper:DragUpdatePosition(POINTER_INFO) (at Assets/Plugins/EZ/GUI/Support/EZDragDropHelper.cs:374)
ControlBase:DragUpdatePosition(POINTER_INFO) (at Assets/Plugins/EZ/GUI/Support/ControlBase.cs:628)
UIManager:DoDragUpdate(POINTER_INFO) (at Assets/Plugins/EZ/GUI/Management/UIManager.cs:1131)
UIManager:DispatchHelper(POINTER_INFO&, Int32) (at Assets/Plugins/EZ/GUI/Management/UIManager.cs:1316)
UIManager:DispatchInput() (at Assets/Plugins/EZ/GUI/Management/UIManager.cs:1226)
UIManager:Update() (at Assets/Plugins/EZ/GUI/Management/UIManager.cs:1179)

Then after release and until I stopped the game
Code: Select all
transform.localPosition assign attempt for 'Cube' is not valid. Input localPosition is { NaN, NaN, NaN }.
AnimatePosition:DoAnim() (at Assets/Plugins/Sprite Scripts/Support/EZAnimator.cs:3090)
EZAnimation:Step(Single) (at Assets/Plugins/Sprite Scripts/Support/EZAnimator.cs:1621)
<AnimPump>c__Iterator2:MoveNext() (at Assets/Plugins/Sprite Scripts/Support/EZAnimator.cs:813)

Sorry to be the first one to post an issue! I actually do hope it is my fault :D

- Rafe
- Rafe
PoolManager Developer and EZ[everything] fan
Check out the Path-o-logical Games Asset Packages.
Posts: 174
Joined: Mon Mar 07, 2011 1:45 pm


Return to EZ GUI General

Who is online

Users browsing this forum: Jefferywek and 6 guests