1 page.title=Live Folders 2 @jd:body 3 4 <p>Live folders, introduced in Android 1.5 (API Level 3), let you display any source of data 5 on the Home screen without forcing the user to launch an application. A live 6 folder is simply a real-time view of a {@link android.content.ContentProvider}. 7 As such, a live folder can be used to display all of the user's contacts or 8 bookmarks, email, playlists, an RSS feed, and so on. The possibilities are 9 endless! </p> 10 11 <p>The platform includes several standard folders for displaying contacts. For 12 instance, the screenshot below shows the content of the live folders that 13 displays all contacts with a phone number:</p> 14 15 <img style="margin: 0px auto 10px; display: block; text-align: center; cursor: pointer; width: 267px; height: 400px;" src="images/contacts.png" alt="" id="BLOGGER_PHOTO_ID_5323287788220889218" border="0"> 16 17 <p>If a contacts sync happens in the background while the user is browsing this live 18 folder, the user will see the change happen in real-time. Live folders are not 19 only useful, but they are also easy to add to to your application and data. 20 21 This articles shows how to add a live folder to an example application called 22 Shelves. To better understand how live folders work, you can <a 23 href="http://code.google.com/p/shelves">download the source code of the 24 application</a> and modify it by following the instructions below.</p> 25 26 <p>To give the user the option to create a new live folder for an application, 27 you first need to create a new activity with an intent filter whose action is 28 <code>android.intent.action.CREATE_LIVE_FOLDER</code>. To do so, simply open 29 <code>AndroidManifest.xml</code> and add something similar to this:</p> 30 31 <pre><activity 32 android:name=".activity.BookShelfLiveFolder" 33 android:label="BookShelf"> 34 <intent-filter> 35 <action android:name="android.intent.action.CREATE_LIVE_FOLDER" /> 36 <category android:name="android.intent.category.DEFAULT" /> 37 </intent-filter> 38 </activity></pre> 39 40 <p>The label and icon of this activity are what the user will see on the Home 41 screen when choosing a live folder to create:</p> 42 43 <img style="margin: 0px auto 10px; display: block; text-align: center; cursor: pointer; width: 267px; height: 400px;" src="images/device_002.png" alt="" id="BLOGGER_PHOTO_ID_5323289217773103922" border="0"> 44 45 <p>Since you just need an intent filter, it is possible, and sometimes advised, 46 to reuse an existing activity. In the case of Shelves, we will create a new 47 activity, <code>org.curiouscreature.android.shelves.activity.BookShelfLiveFolder</code>. 48 The role of this activity is to send an <code>Intent</code> result to Home 49 containing the description of the live folder: its name, icon, display mode and 50 content URI. The content URI is very important as it describes what 51 <code>ContentProvider</code> will be used to populate the live folder. The code 52 of the activity is very simple as you can see here:</p> 53 54 <pre>public class BookShelfLiveFolder extends Activity { 55 public static final Uri CONTENT_URI = Uri.parse("content://shelves/live_folders/books"); 56 57 @Override 58 protected void onCreate(Bundle savedInstanceState) { 59 super.onCreate(savedInstanceState); 60 61 final Intent intent = getIntent(); 62 final String action = intent.getAction(); 63 64 if (LiveFolders.ACTION_CREATE_LIVE_FOLDER.equals(action)) { 65 setResult(RESULT_OK, createLiveFolder(this, CONTENT_URI, 66 "Books", R.drawable.ic_live_folder)); 67 } else { 68 setResult(RESULT_CANCELED); 69 } 70 71 finish(); 72 } 73 74 private static Intent createLiveFolder(Context context, Uri uri, String name, int icon) { 75 final Intent intent = new Intent(); 76 77 intent.setData(uri); 78 intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_NAME, name); 79 intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_ICON, 80 Intent.ShortcutIconResource.fromContext(context, icon)); 81 intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_DISPLAY_MODE, LiveFolders.DISPLAY_MODE_LIST); 82 83 return intent; 84 } 85 }</pre> 86 87 <p>This activity, when invoked with the<code>ACTION_CREATE_LIVE_FOLDER</code> 88 intent, returns an intent with a URI, 89 <code>content://shelves/live_folders/books</code>, and three extras to describe 90 the live folder. There are other extras and constants you can use and you should 91 refer to the documentation of <code>android.provider.LiveFolders</code> for more 92 details. When Home receives this intent, a new live folder is created on the 93 user's desktop, with the name and icon you provided. Then, when the user clicks 94 on the live folder to open it, Home queries the content provider referenced by 95 the provided URI.</p> 96 97 <p>Live folders' content providers must obey specific naming rules. The 98 <code>Cursor</code> returned by the <code>query()</code> method must have at 99 least two columns named <code>LiveFolders._ID</code> and 100 <code>LiveFolders.NAME</code>. The first one is the unique identifier of each 101 item in the live folder and the second one is the name of the item. There are 102 other column names you can use to specify an icon, a description, the intent to 103 associate with the item (fired when the user clicks that item), etc. Again, 104 refer to the documentation of <code>android.provider.LiveFolders</code> for more 105 details.</p><p>In our example, all we need to do is modify the existing provider 106 in Shelves called 107 <code>org.curiouscreature.android.shelves.provider.BooksProvider</code>. First, 108 we need to modify the <code>URI_MATCHER</code> to recognize our 109 <code>content://shelves/live_folders/books</code> content URI:</p> 110 111 <pre>private static final int LIVE_FOLDER_BOOKS = 4; 112 // ... 113 URI_MATCHER.addURI(AUTHORITY, "live_folders/books", LIVE_FOLDER_BOOKS);</pre> 114 115 <p>Then we need to create a new projection map for the cursor. A projection map 116 can be used to "rename" columns. In our case, we will replace 117 <code>BooksStore.Book._ID</code>, <code>BooksStore.Book.TITLE</code> and 118 <code>BooksStore.Book.AUTHORS</code> with <code>LiveFolders._ID</code>, 119 <code>LiveFolders.TITLE</code> and <code>LiveFolders.DESCRIPTION</code>:</p> 120 121 <pre>private static final HashMap<string, string=""> LIVE_FOLDER_PROJECTION_MAP; 122 static { 123 LIVE_FOLDER_PROJECTION_MAP = new HashMap<string, string="">(); 124 LIVE_FOLDER_PROJECTION_MAP.put(LiveFolders._ID, BooksStore.Book._ID + 125 " AS " + LiveFolders._ID); 126 LIVE_FOLDER_PROJECTION_MAP.put(LiveFolders.NAME, BooksStore.Book.TITLE + 127 " AS " + LiveFolders.NAME); 128 LIVE_FOLDER_PROJECTION_MAP.put(LiveFolders.DESCRIPTION, BooksStore.Book.AUTHORS + 129 " AS " + LiveFolders.DESCRIPTION); 130 }</pre> 131 132 <p>Because we are providing a title and a description for each row, Home will 133 automatically display each item of the live folder with two lines of text. 134 Finally, we implement the <code>query()</code> method by supplying our 135 projection map to the SQL query builder:</p> 136 137 <pre>public Cursor query(Uri uri, String[] projection, String selection, 138 String[] selectionArgs, String sortOrder) { 139 140 SQLiteQueryBuilder qb = new SQLiteQueryBuilder(); 141 142 switch (URI_MATCHER.match(uri)) { 143 // ... 144 case LIVE_FOLDER_BOOKS: 145 qb.setTables("books"); 146 qb.setProjectionMap(LIVE_FOLDER_PROJECTION_MAP); 147 break; 148 default: 149 throw new IllegalArgumentException("Unknown URI " + uri); 150 } 151 152 SQLiteDatabase db = mOpenHelper.getReadableDatabase(); 153 Cursor c = qb.query(db, projection, selection, selectionArgs, null, null, BooksStore.Book.DEFAULT_SORT_ORDER); 154 c.setNotificationUri(getContext().getContentResolver(), uri); 155 156 return c; 157 }</pre> 158 159 <p>You can now compile and deploy the application, go to the Home screen and 160 try to add a live folder. You can add a books live folder to your Home screen 161 and when you open it, see the list of all of your books, with their 162 titles and authors, and all it took was a few lines of code:</p> 163 164 <img style="margin: 0px auto 10px; display: block; text-align: center; cursor: pointer; width: 267px; height: 400px;" src="images/device.png" alt="" id="BLOGGER_PHOTO_ID_5323293545495859234" border="0"></p> 165 166 <p>The live folders API is extremely simple and relies only on intents and 167 content URI. If you want to see more examples of live folders 168 implementation, you can read the source code of the <a href="http://android.git.kernel.org/?p=platform/packages/apps/Contacts.git;a=tree;h=refs/heads/cupcake;hb=cupcake">Contacts application</a> and of the <a href="http://android.git.kernel.org/?p=platform/packages/providers/ContactsProvider.git;a=tree;h=refs/heads/cupcake;hb=cupcake">Contacts provider</a>.</p><p>You can also download the result of our exercise, the <a href="http://jext.free.fr/CupcakeShelves.zip">modified version of Shelves with live folders support</a>.</p>
