- Android — Drag and Drop
- The Drag/Drop Process
- The DragEvent Class
- Constants
- Methods
- Listening for Drag Event
- Starting a Drag Event
- Example
- Drag and Drop
- Quickview
- In this document
- Key classes
- Related Samples
- See also
- Overview
- The drag/drop process
- The drag event listener and callback method
- Drag events
- The drag shadow
- Designing a Drag and Drop Operation
- Starting a drag
- Responding to a drag start
- Handling events during the drag
- Responding to a drop
- Responding to a drag end
- Responding to drag events: an example
Android — Drag and Drop
Android drag/drop framework allows your users to move data from one View to another View in the current layout using a graphical drag and drop gesture. As of API 11 drag and drop of view onto other views or view groups is supported.The framework includes following three important components to support drag & drop functionality −
Drag event class.
Helper methods and classes.
The Drag/Drop Process
There are basically four steps or states in the drag and drop process −
Started − This event occurs when you start dragging an item in a layout, your application calls startDrag() method to tell the system to start a drag. The arguments inside startDrag() method provide the data to be dragged, metadata for this data, and a callback for drawing the drag shadow.
The system first responds by calling back to your application to get a drag shadow. It then displays the drag shadow on the device.
Next, the system sends a drag event with action type ACTION_DRAG_STARTED to the registered drag event listeners for all the View objects in the current layout.
To continue to receive drag events, including a possible drop event, a drag event listener must return true, If the drag event listener returns false, then it will not receive drag events for the current operation until the system sends a drag event with action type ACTION_DRAG_ENDED.
Continuing − The user continues the drag. System sends ACTION_DRAG_ENTERED action followed by ACTION_DRAG_LOCATION action to the registered drag event listener for the View where dragging point enters. The listener may choose to alter its View object’s appearance in response to the event or can react by highlighting its View.
The drag event listener receives a ACTION_DRAG_EXITED action after the user has moved the drag shadow outside the bounding box of the View.
Dropped − The user releases the dragged item within the bounding box of a View. The system sends the View object’s listener a drag event with action type ACTION_DROP.
Ended − Just after the action type ACTION_DROP, the system sends out a drag event with action type ACTION_DRAG_ENDED to indicate that the drag operation is over.
The DragEvent Class
The DragEvent represents an event that is sent out by the system at various times during a drag and drop operation. This class provides few Constants and important methods which we use during Drag/Drop process.
Constants
Following are all constants integers available as a part of DragEvent class.
Sr.No. | Constants & Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
1 |
Sr.No. | Constants & Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
1 |
Step | Description |
---|---|
1 | You will use Android studio IDE to create an Android application and name it as My Application under a package com.example.saira_000.myapplication. |
2 | Modify src/MainActivity.java file and add the code to define event listeners as well as a call back methods for the logo image used in the example. |
3 | Copy image abc.png in res/drawable-* folders. You can use images with different resolution in case you want to provide them for different devices. |
4 | Modify layout XML file res/layout/activity_main.xml to define default view of the logo images. |
5 | Run the application to launch Android emulator and verify the result of the changes done in the application. |
Following is the content of the modified main activity file src/MainActivity.java. This file can include each of the fundamental lifecycle methods.
Following will be the content of res/layout/activity_main.xml file −
In the following code abc indicates the logo of tutorialspoint.com
Following will be the content of res/values/strings.xml to define two new constants −
Following is the default content of AndroidManifest.xml −
Let’s try to run your My Application application. I assume you had created your AVD while doing environment setup. To run the app from Android Studio, open one of your project’s activity files and click Run icon from the toolbar. Android studio installs the app on your AVD and starts it and if everything is fine with your setup and application, it will display following Emulator window −
Now do long click on the displayed TutorialsPoint logo and you will see that logo image moves a little after 1 seconds long click from its place, its the time when you should start dragging the image. You can drag it around the screen and drop it at a new location.
Источник
Drag and Drop
Quickview
- Allow users to move data within your Activity layout using graphical gestures.
- Supports operations besides data movement.
- Only works within a single application.
- Requires API 11.
In this document
Key classes
Related Samples
See also
With the Android drag/drop framework, you can allow your users to move data from one View to another View in the current layout using a graphical drag and drop gesture. The framework includes a drag event class, drag listeners, and helper methods and classes.
Although the framework is primarily designed for data movement, you can use it for other UI actions. For example, you could create an app that mixes colors when the user drags a color icon over another icon. The rest of this topic, however, describes the framework in terms of data movement.
Overview
A drag and drop operation starts when the user makes some gesture that you recognize as a signal to start dragging data. In response, your application tells the system that the drag is starting. The system calls back to your application to get a representation of the data being dragged. As the user’s finger moves this representation (a «drag shadow») over the current layout, the system sends drag events to the drag event listener objects and drag event callback methods associated with the View objects in the layout. Once the user releases the drag shadow, the system ends the drag operation.
You create a drag event listener object («listeners») from a class that implements View.OnDragListener . You set the drag event listener object for a View with the View object’s setOnDragListener() method. Each View object also has a onDragEvent() callback method. Both of these are described in more detail in the section The drag event listener and callback method.
Note: For the sake of simplicity, the following sections refer to the routine that receives drag events as the «drag event listener», even though it may actually be a callback method.
When you start a drag, you include both the data you are moving and metadata describing this data as part of the call to the system. During the drag, the system sends drag events to the drag event listeners or callback methods of each View in the layout. The listeners or callback methods can use the metadata to decide if they want to accept the data when it is dropped. If the user drops the data over a View object, and that View object’s listener or callback method has previously told the system that it wants to accept the drop, then the system sends the data to the listener or callback method in a drag event.
Your application tells the system to start a drag by calling the startDrag() method. This tells the system to start sending drag events. The method also sends the data that you are dragging.
You can call startDrag() for any attached View in the current layout. The system only uses the View object to get access to global settings in your layout.
Once your application calls startDrag() , the rest of the process uses events that the system sends to the View objects in your current layout.
The drag/drop process
There are basically four steps or states in the drag and drop process:
Started In response to the user’s gesture to begin a drag, your application calls startDrag() to tell the system to start a drag. The arguments startDrag() provide the data to be dragged, metadata for this data, and a callback for drawing the drag shadow.
The system first responds by calling back to your application to get a drag shadow. It then displays the drag shadow on the device.
Next, the system sends a drag event with action type ACTION_DRAG_STARTED to the drag event listeners for all the View objects in the current layout. To continue to receive drag events, including a possible drop event, a drag event listener must return true . This registers the listener with the system. Only registered listeners continue to receive drag events. At this point, listeners can also change the appearance of their View object to show that the listener can accept a drop event.
If the drag event listener returns false , then it will not receive drag events for the current operation until the system sends a drag event with action type ACTION_DRAG_ENDED . By sending false , the listener tells the system that it is not interested in the drag operation and does not want to accept the dragged data.
Continuing The user continues the drag. As the drag shadow intersects the bounding box of a View object, the system sends one or more drag events to the View object’s drag event listener (if it is registered to receive events). The listener may choose to alter its View object’s appearance in response to the event. For example, if the event indicates that the drag shadow has entered the bounding box of the View (action type ACTION_DRAG_ENTERED ), the listener can react by highlighting its View. Dropped The user releases the drag shadow within the bounding box of a View that can accept the data. The system sends the View object’s listener a drag event with action type ACTION_DROP . The drag event contains the data that was passed to the system in the call to startDrag() that started the operation. The listener is expected to return boolean true to the system if code for accepting the drop succeeds.
Note that this step only occurs if the user drops the drag shadow within the bounding box of a View whose listener is registered to receive drag events. If the user releases the drag shadow in any other situation, no ACTION_DROP drag event is sent.
Ended After the user releases the drag shadow, and after the system sends out (if necessary) a drag event with action type ACTION_DROP , the system sends out a drag event with action type ACTION_DRAG_ENDED to indicate that the drag operation is over. This is done regardless of where the user released the drag shadow. The event is sent to every listener that is registered to receive drag events, even if the listener received the ACTION_DROP event.
Each of these four steps is described in more detail in the section Designing a Drag and Drop Operation.
The drag event listener and callback method
A View receives drag events with either a drag event listener that implements View.OnDragListener or with its onDragEvent(DragEvent) callback method. When the system calls the method or listener, it passes to them a DragEvent object.
You will probably want to use the listener in most cases. When you design UIs, you usually don’t subclass View classes, but using the callback method forces you to do this in order to override the method. In comparison, you can implement one listener class and then use it with several different View objects. You can also implement it as an anonymous inline class. To set the listener for a View object, call setOnDragListener() .
You can have both a listener and a callback method for View object. If this occurs, the system first calls the listener. The system doesn’t call the callback method unless the listener returns false .
The combination of the onDragEvent(DragEvent) method and View.OnDragListener is analogous to the combination of the onTouchEvent() and View.OnTouchListener used with touch events.
Drag events
The system sends out a drag event in the form of a DragEvent object. The object contains an action type that tells the listener what is happening in the drag/drop process. The object contains other data, depending on the action type.
To get the action type, a listener calls getAction() . There are six possible values, defined by constants in the DragEvent class. These are listed in table 1.
The DragEvent object also contains the data that your application provided to the system in the call to startDrag() . Some of the data is valid only for certain action types. The data that is valid for each action type is summarized in table 2. It is also described in detail with the event for which it is valid in the section Designing a Drag and Drop Operation.
Table 1. DragEvent action types
getAction() value | Meaning |
---|---|
ACTION_DRAG_STARTED | A View object’s drag event listener receives this event action type just after the application calls startDrag() and gets a drag shadow. |
ACTION_DRAG_ENTERED | A View object’s drag event listener receives this event action type when the drag shadow has just entered the bounding box of the View. This is the first event action type the listener receives when the drag shadow enters the bounding box. If the listener wants to continue receiving drag events for this operation, it must return boolean true to the system. |
ACTION_DRAG_LOCATION | A View object’s drag event listener receives this event action type after it receives a ACTION_DRAG_ENTERED event while the drag shadow is still within the bounding box of the View. |
ACTION_DRAG_EXITED | A View object’s drag event listener receives this event action type after it receives a ACTION_DRAG_ENTERED and at least one ACTION_DRAG_LOCATION event, and after the user has moved the drag shadow outside the bounding box of the View. |
ACTION_DROP | A View object’s drag event listener receives this event action type when the user releases the drag shadow over the View object. This action type is only sent to a View object’s listener if the listener returned boolean true in response to the ACTION_DRAG_STARTED drag event. This action type is not sent if the user releases the drag shadow on a View whose listener is not registered, or if the user releases the drag shadow on anything that is not part of the current layout. The listener is expected to return boolean true if it successfully processes the drop. Otherwise, it should return false . |
ACTION_DRAG_ENDED | A View object’s drag event listener receives this event action type when the system is ending the drag operation. This action type is not necessarily preceded by an ACTION_DROP event. If the system sent a ACTION_DROP , receiving the ACTION_DRAG_ENDED action type does not imply that the drop operation succeeded. The listener must call getResult() to get the value that was returned in response to ACTION_DROP . If an ACTION_DROP event was not sent, then getResult() returns false . |
Table 2. Valid DragEvent data by action type
getAction() value | getClipDescription() value | getLocalState() value | getX() value | getY() value | getClipData() value | getResult() value |
---|---|---|---|---|---|---|
ACTION_DRAG_STARTED | X | X | X | |||
ACTION_DRAG_ENTERED | X | X | X | X | ||
ACTION_DRAG_LOCATION | X | X | X | X | ||
ACTION_DRAG_EXITED | X | X | ||||
ACTION_DROP | X | X | X | X | X | |
ACTION_DRAG_ENDED | X | X | X |
If a method does not contain valid data for a particular action type, it returns either null or 0, depending on its result type.
The drag shadow
During a drag and drop operation, the system displays a image that the user drags. For data movement, this image represents the data being dragged. For other operations, the image represents some aspect of the drag operation.
The image is called a drag shadow. You create it with methods you declare for a View.DragShadowBuilder object, and then pass it to the system when you start a drag using startDrag() . As part of its response to startDrag() , the system invokes the callback methods you’ve defined in View.DragShadowBuilder to obtain a drag shadow.
The View.DragShadowBuilder class has two constructors:
View.DragShadowBuilder(View) This constructor accepts any of your application’s View objects. The constructor stores the View object in the View.DragShadowBuilder object, so during the callback you can access it as you construct your drag shadow. It doesn’t have to be associated with the View (if any) that the user selected to start the drag operation.
If you use this constructor, you don’t have to extend View.DragShadowBuilder or override its methods. By default, you will get a drag shadow that has the same appearance as the View you pass as an argument, centered under the location where the user is touching the screen.
View.DragShadowBuilder() If you use this constructor, no View object is available in the View.DragShadowBuilder object (the field is set to null ). If you use this constructor, and you don’t extend View.DragShadowBuilder or override its methods, you will get an invisible drag shadow. The system does not give an error.
The View.DragShadowBuilder class has two methods:
onProvideShadowMetrics() The system calls this method immediately after you call startDrag() . Use it to send to the system the dimensions and touch point of the drag shadow. The method has two arguments: dimensions A Point object. The drag shadow width goes in x and its height goes in y . touch_point A Point object. The touch point is the location within the drag shadow that should be under the user’s finger during the drag. Its X position goes in x and its Y position goes in y onDrawShadow() Immediately after the call to onProvideShadowMetrics() the system calls onDrawShadow() to get the drag shadow itself. The method has a single argument, a Canvas object that the system constructs from the parameters you provide in onProvideShadowMetrics() Use it to draw the drag shadow in the provided Canvas object.
To improve performance, you should keep the size of the drag shadow small. For a single item, you may want to use a icon. For a multiple selection, you may want to use icons in a stack rather than full images spread out over the screen.
Designing a Drag and Drop Operation
This section shows step-by-step how to start a drag, how to respond to events during the drag, how respond to a drop event, and how to end the drag and drop operation.
Starting a drag
The user starts a drag with a drag gesture, usually a long press, on a View object. In response, you should do the following:
- As necessary, create a ClipData and ClipData.Item for the data being moved. As part of the ClipData object, supply metadata that is stored in a ClipDescription object within the ClipData. For a drag and drop operation that does not represent data movement, you may want to use null instead of an actual object.
For example, this code snippet shows how to respond to a long press on a ImageView by creating a ClipData object that contains the tag or label of an ImageView. Following this snippet, the next snippet shows how to override the methods in View.DragShadowBuilder :
The following code snippet defines myDragShadowBuilder It creates a drag shadow for dragging a TextView as a small gray rectangle:
Note: Remember that you don’t have to extend View.DragShadowBuilder . The constructor View.DragShadowBuilder(View) creates a default drag shadow that’s the same size as the View argument passed to it, with the touch point centered in the drag shadow.
Responding to a drag start
During the drag operation, the system dispatches drag events to the drag event listeners of the View objects in the current layout. The listeners should react by calling getAction() to get the action type. At the start of a drag, this methods returns ACTION_DRAG_STARTED .
In response to an event with the action type ACTION_DRAG_STARTED , a listener should do the following:
- Call getClipDescription() to get the ClipDescription . Use the MIME type methods in ClipDescription to see if the listener can accept the data being dragged.
If the drag and drop operation does not represent data movement, this may not be necessary.
Note that for an ACTION_DRAG_STARTED event, these the following DragEvent methods are not valid: getClipData() , getX() , getY() , and getResult() .
Handling events during the drag
During the drag, listeners that returned true in response to the ACTION_DRAG_STARTED drag event continue to receive drag events. The types of drag events a listener receives during the drag depend on the location of the drag shadow and the visibility of the listener’s View.
During the drag, listeners primarily use drag events to decide if they should change the appearance of their View.
During the drag, getAction() returns one of three values:
- ACTION_DRAG_ENTERED : The listener receives this when the touch point (the point on the screen underneath the user’s finger) has entered the bounding box of the listener’s View.
- ACTION_DRAG_LOCATION : Once the listener receives an ACTION_DRAG_ENTERED event, and before it receives an A ACTION_DRAG_EXITED event, it receives a new ACTION_DRAG_LOCATION event every time the touch point moves. The getX() and getY() methods return the X and Y coordinates of the touch point.
- ACTION_DRAG_EXITED : This event is sent to a listener that previously received ACTION_DRAG_ENTERED , after the drag shadow is no longer within the bounding box of the listener’s View.
The listener does not need to react to any of these action types. If the listener returns a value to the system, it is ignored. Here are some guidelines for responding to each of these action types:
- In response to ACTION_DRAG_ENTERED or ACTION_DRAG_LOCATION , the listener can change the appearance of the View to indicate that it is about to receive a drop.
- An event with the action type ACTION_DRAG_LOCATION contains valid data for getX() and getY() , corresponding to the location of the touch point. The listener may want to use this information to alter the appearance of that part of the View that is at the touch point. The listener can also use this information to determine the exact position where the user is going to drop the drag shadow.
- In response to ACTION_DRAG_EXITED , the listener should reset any appearance changes it applied in response to ACTION_DRAG_ENTERED or ACTION_DRAG_LOCATION . This indicates to the user that the View is no longer an imminent drop target.
Responding to a drop
When the user releases the drag shadow on a View in the application, and that View previously reported that it could accept the content being dragged, the system dispatches a drag event to that View with the action type ACTION_DROP . The listener should do the following:
- Call getClipData() to get the ClipData object that was originally supplied in the call to startDrag() and store it. If the drag and drop operation does not represent data movement, this may not be necessary.
- Return boolean true to indicate that the drop was processed successfully, or boolean false if it was not. The returned value becomes the value returned by getResult() for an ACTION_DRAG_ENDED event.
Note that if the system does not send out an ACTION_DROP event, the value of getResult() for an ACTION_DRAG_ENDED event is false .
For an ACTION_DROP event, getX() and getY() return the X and Y position of the drag point at the moment of the drop, using the coordinate system of the View that received the drop.
The system does allow the user to release the drag shadow on a View whose listener is not receiving drag events. It will also allow the user to release the drag shadow on empty regions of the application’s UI, or on areas outside of your application. In all of these cases, the system does not send an event with action type ACTION_DROP , although it does send out an ACTION_DRAG_ENDED event.
Responding to a drag end
Immediately after the user releases the drag shadow, the system sends a drag event to all of the drag event listeners in your application, with an action type of ACTION_DRAG_ENDED . This indicates that the drag operation is over.
Each listener should do the following:
- If listener changed its View object’s appearance during the operation, it should reset the View to its default appearance. This is a visual indication to the user that the operation is over.
- The listener can optionally call getResult() to find out more about the operation. If a listener returned true in response to an event of action type ACTION_DROP , then getResult() will return boolean true . In all other cases, getResult() returns boolean false , including any case in which the system did not send out a ACTION_DROP event.
- The listener should return boolean true to the system.
Responding to drag events: an example
All drag events are initially received by your drag event method or listener. The following code snippet is a simple example of reacting to drag events in a listener:
Источник