Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 83827705 authored by TreeHugger Robot's avatar TreeHugger Robot Committed by Android (Google) Code Review
Browse files

Merge "More fixes in drag/drop docs."

parents 33f6104d ad57431f

core/java/android/view/DragEvent.java

+16 −11
Original line number Diff line number Diff line
@@ -26,7 +26,7 @@ import com.android.internal.view.IDragAndDropPermissions; 
//TODO: Improve Javadoc

/**

 * Represents an event that is sent out by the system at various times during a drag and drop

 * operation. It is a complex data structure that contains several important pieces of data about

 * operation. It is a data structure that contains several important pieces of data about

 * the operation and the underlying data.

 * <p>

 *  View objects that receive a DragEvent call {@link #getAction()}, which returns
@@ -161,8 +161,8 @@ public class DragEvent implements Parcelable { 
     *  event when they are added or becoming visible.

     * </p>

     * <p>

     *  A View only receives further drag events if it returns {@code true} in response to

     *  ACTION_DRAG_STARTED.

     *  A View only receives further drag events for the drag operation if it returns {@code true}

     *  in response to ACTION_DRAG_STARTED.

     * </p>

     * @see #ACTION_DRAG_ENDED

     * @see #getX()
@@ -172,8 +172,9 @@ public class DragEvent implements Parcelable { 


    /**

     * Action constant returned by {@link #getAction()}: Sent to a View after

     * {@link #ACTION_DRAG_ENTERED} if the drag shadow is still within the View object's bounding

     * box. The {@link #getX()} and {@link #getY()} methods supply

     * {@link #ACTION_DRAG_ENTERED} while the drag shadow is still within the View object's bounding

     * box, but not within a descendant view that can accept the data. The {@link #getX()} and

     * {@link #getY()} methods supply

     * the X and Y position of of the drag point within the View object's bounding box.

     * <p>

     * A View receives an {@link #ACTION_DRAG_ENTERED} event before receiving any
@@ -355,9 +356,10 @@ public class DragEvent implements Parcelable { 
    /**

     * Returns the {@link android.content.ClipData} object sent to the system as part of the call

     * to

     * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}.

     * {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

     * startDragAndDrop()}.

     * This method only returns valid data if the event action is {@link #ACTION_DROP}.

     * @return The ClipData sent to the system by startDrag().

     * @return The ClipData sent to the system by startDragAndDrop().

     */

    public ClipData getClipData() {

        return mClipData;
@@ -366,12 +368,14 @@ public class DragEvent implements Parcelable { 
    /**

     * Returns the {@link android.content.ClipDescription} object contained in the

     * {@link android.content.ClipData} object sent to the system as part of the call to

     * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}.

     * {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

     * startDragAndDrop()}.

     * The drag handler or listener for a View can use the metadata in this object to decide if the

     * View can accept the dragged View object's data.

     * <p>

     * This method returns valid data for all event actions except for {@link #ACTION_DRAG_ENDED}.

     * @return The ClipDescription that was part of the ClipData sent to the system by startDrag().

     * @return The ClipDescription that was part of the ClipData sent to the system by

     *     startDragAndDrop().

     */

    public ClipDescription getClipDescription() {

        return mClipDescription;
@@ -384,7 +388,8 @@ public class DragEvent implements Parcelable { 


    /**

     * Returns the local state object sent to the system as part of the call to

     * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}.

     * {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

     * startDragAndDrop()}.

     * The object is intended to provide local information about the drag and drop operation. For

     * example, it can indicate whether the drag and drop operation is a copy or a move.

     * <p>
@@ -394,7 +399,7 @@ public class DragEvent implements Parcelable { 
     * <p>

     *  This method returns valid data for all event actions except for {@link #ACTION_DRAG_ENDED}.

     * </p>

     * @return The local state object sent to the system by startDrag().

     * @return The local state object sent to the system by startDragAndDrop().

     */

    public Object getLocalState() {

        return mLocalState;

core/java/android/view/View.java

+3 −0
Original line number Diff line number Diff line
@@ -20832,6 +20832,9 @@ public class View implements Drawable.Callback, KeyEvent.Callback, 
     *  {@link android.view.DragEvent#ACTION_DROP} if it consumed the drop, or

     *  {@code false} if it didn't.

     * </p>

     * <p>

     *  For all other events, the return value is ignored.

     * </p>

     */

    public boolean onDragEvent(DragEvent event) {

        return false;

docs/html/guide/topics/ui/drag-drop.jd

+49 −39
Original line number Diff line number Diff line
@@ -157,19 +157,22 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm 
</p>

<p>

    Your application tells the system to start a drag by calling the

    {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}

    {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

    startDragAndDrop()}

    method. This tells the system to start sending drag events. The method also sends the data that

    you are dragging.

</p>

<p>

    You can call

    {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}

    {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

    startDragAndDrop()}

    for any attached View in the current layout. The system only uses the View object to get access

    to global settings in your layout.

</p>

<p>

    Once your application calls

    {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()},

    {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

    startDragAndDrop()},

    the rest of the process uses events that the system sends to the View objects in your current

    layout.

</p>
@@ -183,11 +186,13 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm 
    </dt>

    <dd>

        In response to the user's gesture to begin a drag, your application calls

        {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}

        to tell the system to start a drag. The arguments

        {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}

        provide the data to be dragged, metadata for this data, and a callback for drawing the

        drag shadow.

        {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

        startDragAndDrop()}

        to tell the system to start a drag. The

        {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

        startDragAndDrop()}

        arguments provide the data to be dragged, metadata for this data, and a callback for drawing

        the drag shadow.

        <p>

            The system first responds by calling back to your application to get a drag shadow. It

            then displays the drag shadow on the device.
@@ -199,12 +204,13 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm 
            including a possible drop event, a drag event listener must return <code>true</code>.

            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.

            View object to show that the listener can accept the dragged data.

        </p>

        <p>

            If the drag event listener returns <code>false</code>, then it will not receive drag

            events for the current operation until the system sends a drag event with action type

            {@link android.view.DragEvent#ACTION_DRAG_ENDED}. By sending <code>false</code>, the

            events for the current operation, including the drag event with action type

            {@link android.view.DragEvent#ACTION_DRAG_ENDED} that will conclude the

            operation. By sending <code>false</code>, the

            listener tells the system that it is not interested in the drag operation and

            does not want to accept the dragged data.

        </p>
@@ -230,7 +236,8 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm 
        object's listener a drag event with action type

        {@link android.view.DragEvent#ACTION_DROP}. The drag event contains the data that was

        passed to the system in the call to

        {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}

        {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

        startDragAndDrop()}

        that started the operation. The listener is expected to return boolean <code>true</code> to

        the system if code for accepting the drop succeeds.

        <p>
@@ -297,7 +304,8 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm 
<p>

    The {@link android.view.DragEvent} object also contains the data that your application provided

    to the system in the call to

    {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}.

    {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

    startDragAndDrop()}.

    Some of the data is valid only for certain action types. The data that is valid for each action

    type is summarized in <a href="#table2">table 2</a>. It is also described in detail with

    the event for which it is valid in the section
@@ -316,8 +324,9 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm 
        <td>

            A View object's drag event listener receives this event action type just after the

            application calls

{@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()} and

            gets a drag shadow.

            {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

            startDragAndDrop()}

            and gets a drag shadow.

            <p>

                If the listener wants to continue receiving drag events for this operation, it must

                return boolean <code>true</code> to the system.
@@ -345,8 +354,7 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm 
        <td>{@link android.view.DragEvent#ACTION_DRAG_EXITED}</td>

        <td>

            A View object's drag event listener receives this event action type after it receives a

            {@link android.view.DragEvent#ACTION_DRAG_ENTERED} and at least one

            {@link android.view.DragEvent#ACTION_DRAG_LOCATION} event, and after the user has moved

            {@link android.view.DragEvent#ACTION_DRAG_ENTERED} event, and after the user has moved

            the drag shadow outside the bounding box of the View or into a descendant view that can

            accept the data.

        </td>
@@ -355,7 +363,8 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm 
        <td>{@link android.view.DragEvent#ACTION_DROP}</td>

        <td>

            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

            releases the drag shadow over the View object and not over its descendant view that can

            accept the drag data. This action type is only sent to a View

            object's listener if the listener returned boolean <code>true</code> in response to the

            {@link android.view.DragEvent#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,
@@ -472,9 +481,11 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm 
    The image is called a drag shadow. You create it with methods you declare for a

    {@link android.view.View.DragShadowBuilder} object, and then pass it to the system when you

    start a drag using

    {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}.

    {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

    startDragAndDrop()}.

    As part of its response to

    {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()},

    {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

    startDragAndDrop()},

    the system invokes the callback methods you've defined in

    {@link android.view.View.DragShadowBuilder} to obtain a drag shadow.

</p>
@@ -516,7 +527,8 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm 
    </dt>

    <dd>

        The system calls this method immediately after you call

{@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}. Use it

        {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int)

        startDragAndDrop()}. Use it

        to send to the system the dimensions and touch point of the drag shadow. The method has two

        arguments:

        <dl>
@@ -616,7 +628,7 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() { 


    // Starts the drag



            v.startDrag(dragData,  // the data to be dragged

            v.startDragAndDrop(dragData,  // the data to be dragged

                               myShadow,  // the drag shadow builder

                               null,      // no need to use local data

                               0          // flags (not currently used, set to 0)
@@ -722,8 +734,7 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() { 
<p>

    Note that for an {@link android.view.DragEvent#ACTION_DRAG_STARTED} event, these

    the following {@link android.view.DragEvent} methods are not valid:

    {@link android.view.DragEvent#getClipData()}, {@link android.view.DragEvent#getX()},

    {@link android.view.DragEvent#getY()}, and {@link android.view.DragEvent#getResult()}.

    {@link android.view.DragEvent#getClipData()} and {@link android.view.DragEvent#getResult()}.

</p>

<h3 id="HandleDuring">Handling events during the drag</h3>

<p>
@@ -751,7 +762,9 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() { 
        {@link android.view.DragEvent#ACTION_DRAG_LOCATION}: Once the listener receives an

        {@link android.view.DragEvent#ACTION_DRAG_ENTERED} event, and before it receives an

        A{@link android.view.DragEvent#ACTION_DRAG_EXITED} event, it receives a new

        {@link android.view.DragEvent#ACTION_DRAG_LOCATION} event every time the touch point moves.

        {@link android.view.DragEvent#ACTION_DRAG_LOCATION} event immediately after the

        {@link android.view.DragEvent#ACTION_DRAG_ENTERED} event, and then every time the touch

        point moves.

        The {@link android.view.DragEvent#getX()} and {@link android.view.DragEvent#getY()} methods

        return the X and Y coordinates of the touch point.

    </li>
@@ -769,9 +782,9 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() { 
</p>

<ul>

    <li>

        In response to {@link android.view.DragEvent#ACTION_DRAG_ENTERED} or

        {@link android.view.DragEvent#ACTION_DRAG_LOCATION}, the listener can change the appearance

        of the View to indicate that it is about to receive a drop.

        In response to {@link android.view.DragEvent#ACTION_DRAG_ENTERED}, the listener can change

        the appearance

        of the View to indicate that it is ready to receive a drop.

    </li>

    <li>

        An event with the action type {@link android.view.DragEvent#ACTION_DRAG_LOCATION} contains
@@ -784,14 +797,14 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() { 
    <li>

        In response to {@link android.view.DragEvent#ACTION_DRAG_EXITED}, the listener should reset

        any appearance changes it applied in response to

        {@link android.view.DragEvent#ACTION_DRAG_ENTERED} or

        {@link android.view.DragEvent#ACTION_DRAG_LOCATION}. This indicates to the user that

        {@link android.view.DragEvent#ACTION_DRAG_ENTERED}. This indicates to the user that

        the View is no longer an imminent drop target.

    </li>

</ul>

<h3 id="HandleDrop">Responding to a drop</h3>

<p>

    When the user releases the drag shadow on a View in the application, and that View previously

    When the user releases the drag shadow on a View in the application, but not on its descendant

    view that can accept the data, 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 {@link android.view.DragEvent#ACTION_DROP}. The listener

    should do the following:
@@ -800,8 +813,8 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() { 
    <li>

        Call {@link android.view.DragEvent#getClipData()} to get the

        {@link android.content.ClipData} object that was originally supplied in the call

        to

{@link android.view.View#startDrag(ClipData, View.DragShadowBuilder, Object, int) startDrag()}

        to {@link android.view.View#startDragAndDrop(ClipData, View.DragShadowBuilder, Object, int)

        startDragAndDrop()}

        and store it. If the drag and drop operation does not represent data movement,

        this may not be necessary.

    </li>
@@ -856,9 +869,6 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() { 
        including any case in which the system did not send out a

        {@link android.view.DragEvent#ACTION_DROP} event.

    </li>

    <li>

        The listener should return boolean <code>true</code> to the system.

    </li>

</ol>

<p>

</p>