Home | History | Annotate | Download | only in DirectorySelection 
      1 
      2 Android DirectorySelection Sample
      3 ===================================
      4 
      5 A basic app showing how to use Directory Selection API to let users
      6 select an entire directory subtree, which extends the Storage Access Framework
      7 introduced in Android 4.4 (API level 19).
      8 
      9 Introduction
     10 ------------
     11 
     12 The [Directory Selection][1] API, which was introduced in Android 5.0 (API level 21)
     13 extends the [Storage Access Framework][2] to let users select an entire directory subtree,
     14 giving apps read/write access to all contained documents without requiring user
     15 confirmation for each item.
     16 
     17 To select a directory subtree, build and send an [OPEN_DOCUMENT_TREE intent][3] like in the
     18 following code:
     19 
     20 ```java
     21 Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT_TREE);
     22 startActivityForResult(intent, REQUEST_CODE_OPEN_DIRECTORY);
     23 ```
     24 
     25 The system displays all [DocumentsProvider][4] instances that support subtree selection,
     26  letting the user browse and select a directory.
     27 
     28 The 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]
     31 to explore the subtree.
     32 
     33 This example explores the child documents and the selected document by following code:
     34 
     35 ```java
     36 @Override
     37 public 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 
     44 void 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 
     85 Also, the new [createDocument()][8] method lets you create new documents or directories
     86 anywhere under the subtree.
     87 
     88 This example creates a new directory by following code:
     89 
     90 ```java
     91 ContentResolver contentResolver = getActivity().getContentResolver();
     92 Uri docUri = DocumentsContract.buildDocumentUriUsingTree(uri,
     93         DocumentsContract.getTreeDocumentId(uri));
     94 Uri 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 
    107 Pre-requisites
    108 --------------
    109 
    110 - Android SDK 25
    111 - Android Build Tools v25.0.3
    112 - Android Support Repository
    113 
    114 Screenshots
    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 
    119 Getting Started
    120 ---------------
    121 
    122 This sample uses the Gradle build system. To build this project, use the
    123 "gradlew build" command or use "Import Project" in Android Studio.
    124 
    125 Support
    126 -------
    127 
    128 - Google+ Community: https://plus.google.com/communities/105153134372062985968
    129 - Stack Overflow: http://stackoverflow.com/questions/tagged/android
    130 
    131 If you've found an error in this sample, please file an issue:
    132 https://github.com/googlesamples/android-DirectorySelection
    133 
    134 Patches are encouraged, and may be submitted by forking this project and
    135 submitting a pull request through GitHub. Please see CONTRIBUTING.md for more details.
    136 
    137 License
    138 -------
    139 
    140 Copyright 2017 The Android Open Source Project, Inc.
    141 
    142 Licensed to the Apache Software Foundation (ASF) under one or more contributor
    143 license agreements.  See the NOTICE file distributed with this work for
    144 additional information regarding copyright ownership.  The ASF licenses this
    145 file to you under the Apache License, Version 2.0 (the "License"); you may not
    146 use this file except in compliance with the License.  You may obtain a copy of
    147 the License at
    148 
    149 http://www.apache.org/licenses/LICENSE-2.0
    150 
    151 Unless required by applicable law or agreed to in writing, software
    152 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
    153 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
    154 License for the specific language governing permissions and limitations under
    155 the License.
    156