DropTarget.java revision 440c360bc395c43683fa9ca226e59f9e35f9e926 
1/*
2 * Copyright (C) 2008 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.android.launcher2;
18
19import android.graphics.Rect;
20
21/**
22 * Interface defining an object that can receive a drag.
23 *
24 */
25public interface DropTarget {
26
27    /**
28     * Handle an object being dropped on the DropTarget
29     *
30     * @param source DragSource where the drag started
31     * @param x X coordinate of the drop location
32     * @param y Y coordinate of the drop location
33     * @param xOffset Horizontal offset with the object being dragged where the original
34     *          touch happened
35     * @param yOffset Vertical offset with the object being dragged where the original
36     *          touch happened
37     * @param dragView The DragView that's being dragged around on screen.
38     * @param dragInfo Data associated with the object being dragged
39     *
40     */
41    void onDrop(DragSource source, int x, int y, int xOffset, int yOffset,
42            DragView dragView, Object dragInfo);
43
44    void onDragEnter(DragSource source, int x, int y, int xOffset, int yOffset,
45            DragView dragView, Object dragInfo);
46
47    void onDragOver(DragSource source, int x, int y, int xOffset, int yOffset,
48            DragView dragView, Object dragInfo);
49
50    void onDragExit(DragSource source, int x, int y, int xOffset, int yOffset,
51            DragView dragView, Object dragInfo);
52
53    /**
54     * Allows a DropTarget to delegate drag and drop events to another object.
55     *
56     * Most subclasses will should just return null from this method.
57     *
58     * @param source DragSource where the drag started
59     * @param x X coordinate of the drop location
60     * @param y Y coordinate of the drop location
61     * @param xOffset Horizontal offset with the object being dragged where the original
62     *          touch happened
63     * @param yOffset Vertical offset with the object being dragged where the original
64     *          touch happened
65     * @param dragView The DragView that's being dragged around on screen.
66     * @param dragInfo Data associated with the object being dragged
67     *
68     * @return The DropTarget to delegate to, or null to not delegate to another object.
69     */
70    DropTarget getDropTargetDelegate(DragSource source, int x, int y, int xOffset, int yOffset,
71            DragView dragView, Object dragInfo);
72
73    /**
74     * Check if a drop action can occur at, or near, the requested location.
75     * This may be called repeatedly during a drag, so any calls should return
76     * quickly.
77     *
78     * @param source DragSource where the drag started
79     * @param x X coordinate of the drop location
80     * @param y Y coordinate of the drop location
81     * @param xOffset Horizontal offset with the object being dragged where the
82     *            original touch happened
83     * @param yOffset Vertical offset with the object being dragged where the
84     *            original touch happened
85     * @param dragView The DragView that's being dragged around on screen.
86     * @param dragInfo Data associated with the object being dragged
87     * @return True if the drop will be accepted, false otherwise.
88     */
89    boolean acceptDrop(DragSource source, int x, int y, int xOffset, int yOffset,
90            DragView dragView, Object dragInfo);
91
92    /**
93     * Estimate the surface area where this object would land if dropped at the
94     * given location.
95     *
96     * @param source DragSource where the drag started
97     * @param x X coordinate of the drop location
98     * @param y Y coordinate of the drop location
99     * @param xOffset Horizontal offset with the object being dragged where the
100     *            original touch happened
101     * @param yOffset Vertical offset with the object being dragged where the
102     *            original touch happened
103     * @param dragView The DragView that's being dragged around on screen.
104     * @param dragInfo Data associated with the object being dragged
105     * @param recycle {@link Rect} object to be possibly recycled.
106     * @return Estimated area that would be occupied if object was dropped at
107     *         the given location. Should return null if no estimate is found,
108     *         or if this target doesn't provide estimations.
109     */
110    Rect estimateDropLocation(DragSource source, int x, int y, int xOffset, int yOffset,
111            DragView dragView, Object dragInfo, Rect recycle);
112
113    // These methods are implemented in Views
114    void getHitRect(Rect outRect);
115    void getLocationOnScreen(int[] loc);
116    int getLeft();
117    int getTop();
118}
119