1
2Android DirectorySelection Sample
3===================================
4
5A basic app showing how to use Directory Selection API to let users
6select an entire directory subtree, which extends the Storage Access Framework
7introduced in Android 4.4 (API level 19).
8
9Introduction
10------------
11
12The [Directory Selection][1] API, which was introduced in Android 5.0 (API level 21)
13extends the [Storage Access Framework][2] to let users select an entire directory subtree,
14giving apps read/write access to all contained documents without requiring user
15confirmation for each item.
16
17To select a directory subtree, build and send an [OPEN_DOCUMENT_TREE intent][3] like in the
18following code:
19
20```java
21Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT_TREE);
22startActivityForResult(intent, REQUEST_CODE_OPEN_DIRECTORY);
23```
24
25The system displays all [DocumentsProvider][4] instances that support subtree selection,
26 letting the user browse and select a directory.
27
28The returned URI represents access to the selected subtree. You can then use
29[buildChildDocumentsUriUsingTree()][5] to access to the child documents and
30[buildDocumentUriUsingTree()][6] to access to the selected directory itself along with [query()][7]
31to explore the subtree.
32
33This example explores the child documents and the selected document by following code:
34
35```java
36@Override
37public void onActivityResult(int requestCode, int resultCode, Intent data) {
38    super.onActivityResult(requestCode, resultCode, data);
39    if (requestCode == REQUEST_CODE_OPEN_DIRECTORY && resultCode == Activity.RESULT_OK) {
40        updateDirectoryEntries(data.getData());
41    }
42}
43
44void updateDirectoryEntries(Uri uri) {
45    ContentResolver contentResolver = getActivity().getContentResolver();
46    Uri docUri = DocumentsContract.buildDocumentUriUsingTree(uri,
47            DocumentsContract.getTreeDocumentId(uri));
48    Uri childrenUri = DocumentsContract.buildChildDocumentsUriUsingTree(uri,
49            DocumentsContract.getTreeDocumentId(uri));
50
51    Cursor docCursor = contentResolver.query(docUri, new String[]{
52            Document.COLUMN_DISPLAY_NAME, Document.COLUMN_MIME_TYPE}, null, null, null);
53    try {
54        while (docCursor.moveToNext()) {
55            Log.d(TAG, "found doc =" + docCursor.getString(0) + ", mime=" + docCursor
56                    .getString(1));
57            mCurrentDirectoryUri = uri;
58            mCurrentDirectoryTextView.setText(docCursor.getString(0));
59            mCreateDirectoryButton.setEnabled(true);
60        }
61    } finally {
62        closeQuietly(docCursor);
63    }
64
65    Cursor childCursor = contentResolver.query(childrenUri, new String[]{
66            Document.COLUMN_DISPLAY_NAME, Document.COLUMN_MIME_TYPE}, null, null, null);
67    try {
68        List<DirectoryEntry> directoryEntries = new ArrayList<>();
69        while (childCursor.moveToNext()) {
70            Log.d(TAG, "found child=" + childCursor.getString(0) + ", mime=" + childCursor
71                    .getString(1));
72            DirectoryEntry entry = new DirectoryEntry();
73            entry.fileName = childCursor.getString(0);
74            entry.mimeType = childCursor.getString(1);
75            directoryEntries.add(entry);
76        }
77        mAdapter.setDirectoryEntries(directoryEntries);
78        mAdapter.notifyDataSetChanged();
79    } finally {
80        closeQuietly(childCursor);
81    }
82}
83```
84
85Also, the new [createDocument()][8] method lets you create new documents or directories
86anywhere under the subtree.
87
88This example creates a new directory by following code:
89
90```java
91ContentResolver contentResolver = getActivity().getContentResolver();
92Uri docUri = DocumentsContract.buildDocumentUriUsingTree(uri,
93        DocumentsContract.getTreeDocumentId(uri));
94Uri directoryUri = DocumentsContract
95        .createDocument(contentResolver, docUri, Document.MIME_TYPE_DIR, directoryName);
96```
97
98[1]: https://developer.android.com/about/versions/android-5.0.html#Storage
99[2]: https://developer.android.com/guide/topics/providers/document-provider.html
100[3]: https://developer.android.com/reference/android/content/Intent.html#ACTION_OPEN_DOCUMENT_TREE
101[4]: https://developer.android.com/reference/android/provider/DocumentsProvider.html
102[5]: https://developer.android.com/reference/android/provider/DocumentsContract.html#buildChildDocumentsUriUsingTree(android.net.Uri%2C%20java.lang.String)
103[6]: https://developer.android.com/reference/android/provider/DocumentsContract.html#buildDocumentUriUsingTree(android.net.Uri%2C%20java.lang.String)
104[7]: https://developer.android.com/reference/android/content/ContentResolver.html#query(android.net.Uri%2C%20java.lang.String%5B%5D%2C%20java.lang.String%2C%20java.lang.String%5B%5D%2C%20java.lang.String)
105[8]: https://developer.android.com/reference/android/provider/DocumentsContract.html#createDocument(android.content.ContentResolver%2C%20android.net.Uri%2C%20java.lang.String%2C%20java.lang.String)
106
107Pre-requisites
108--------------
109
110- Android SDK 23
111- Android Build Tools v23.0.3
112- Android Support Repository
113
114Screenshots
115-------------
116
117<img src="screenshots/screenshot-1.png" height="400" alt="Screenshot"/> <img src="screenshots/screenshot-2.png" height="400" alt="Screenshot"/> <img src="screenshots/screenshot-3.png" height="400" alt="Screenshot"/>
118
119Getting Started
120---------------
121
122This sample uses the Gradle build system. To build this project, use the
123"gradlew build" command or use "Import Project" in Android Studio.
124
125Support
126-------
127
128- Google+ Community: https://plus.google.com/communities/105153134372062985968
129- Stack Overflow: http://stackoverflow.com/questions/tagged/android
130
131If you've found an error in this sample, please file an issue:
132https://github.com/googlesamples/android-DirectorySelection
133
134Patches are encouraged, and may be submitted by forking this project and
135submitting a pull request through GitHub. Please see CONTRIBUTING.md for more details.
136
137License
138-------
139
140Copyright 2016 The Android Open Source Project, Inc.
141
142Licensed to the Apache Software Foundation (ASF) under one or more contributor
143license agreements.  See the NOTICE file distributed with this work for
144additional information regarding copyright ownership.  The ASF licenses this
145file to you under the Apache License, Version 2.0 (the "License"); you may not
146use this file except in compliance with the License.  You may obtain a copy of
147the License at
148
149http://www.apache.org/licenses/LICENSE-2.0
150
151Unless required by applicable law or agreed to in writing, software
152distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
153WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
154License for the specific language governing permissions and limitations under
155the License.
156