1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 Copyright 2013 The Android Open Source Project
4
5 Licensed under the Apache License, Version 2.0 (the "License");
6 you may not use this file except in compliance with the License.
7 You may obtain a copy of the License at
8
9     http://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS,
13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 See the License for the specific language governing permissions and
15 limitations under the License.
16-->
17
18<sample>
19    <name>DragAndDropAcrossApps-new</name>
20    <group>ui</group>
21    <package>com.example.android.droptarget</package>
22
23    <minSdk>24</minSdk>
24
25    <template src="base-build" />
26
27    <strings>
28        <intro>
29<![CDATA[
30This sample demonstrates how data can be moved between views within an
31app or between different apps via drag and drop.
32This sample contains two separate Android applications: DragSource and
33DropTarget. DragSource contains images and text that can be dropped into the DropTarget
34app. Images are shared between the two apps through a URI for which the receiving app
35must request permission first, before it can be used.
36
37It also demonstrates the use of the DragStartHelper from the v13 support library to easily
38handle drag and drop events.
39]]>
40        </intro>
41    </strings>
42
43    <metadata>
44        <status>PUBLISHED</status>
45        <categories>UI</categories>
46        <technologies>Android</technologies>
47        <languages>Java</languages>
48        <solutions>Mobile</solutions>
49        <level>ADVANCED</level>
50        <icon>screenshots/big_icon.png</icon>
51        <screenshots>
52            <img>screenshots/phone.png</img>
53            <img>screenshots/tablet.png</img>
54        </screenshots>
55        <api_refs>
56            <android>android.content.ClipDescription</android>
57            <android>android.os.PersistableBundle</android>
58            <android>android.view.DragEvent</android>
59            <android>android.support.v13.view.DragAndDropPermissionsCompat</android>
60            <android>android.support.v13.view.DragStartHelper</android>
61        </api_refs>
62
63        <description>
64<![CDATA[
65This sample contains two separate Android applications: DragSource and
66DropTarget. DragSource contains images and text that can be dropped into the DropTarget
67app. Images are shared between the two apps through a URI for which the receiving app
68must request permission first, before it can be used.
69
70It also demonstrates the use of the DragStartHelper from the v13 support library to easily
71handle drag and drop events.
72]]>
73        </description>
74
75        <intro>
76<![CDATA[
77Android N introduces support for drag and drop between applications,
78augmenting the existing APIs that have enabled this within a single
79window before.
80
81To start a drag operation you need to call `View.startDragAndDrop`.
82Which gesture or action triggers this is up to you as an app developer.
83The API guide recommends doing this from
84`View.OnLongClickListener.onLongClick` and this seems to be the de-facto
85standard, but you are free to use other gestures (single tap, tap and drag
86etc).
87However, if you go for a unconventional drag start gesture, note that
88the framework implementation assumes that the pointer (touch or mouse)
89is down while the drag is starting, and the most recent touch/click
90position is used as the original position of the drag shadow.
91
92See also `android.support.v13.view.DragStartHelper` which uses different
93gestures for touch and mouse (click and drag works better for mouse
94than a long click).
95
96By default a drag and drop operation is constrained by the window
97containing the view that started the drag.
98To enable cross-window and cross-app drag and drop add
99`View.DRAG_FLAG_GLOBAL` to the flags passed to the `View.startDragAndDrop`
100call.
101
102If a Uri requiring permission grants is being sent, then the
103`android.view.View.DRAG_FLAG_GLOBAL_URI_READ` and/or the
104`android.view.View.DRAG_FLAG_GLOBAL_URI_WRITE` flags must be used also.
105To access content URIs requiring permissions on the receiving side, the target
106app needs to request the `android.view.DropPermissions` from the activity via
107`android.app.Activity.requestDropPermissions`. This permission will stay either
108until the activity is alive, or until the `release()` method is called on the
109`android.view.DropPermissions` object.
110]]>
111        </intro>
112    </metadata>
113</sample>
114