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 17 package android.provider; 18 19 import android.annotation.SdkConstant; 20 21 /** 22 * <p>A LiveFolder is a special folder whose content is provided by a 23 * {@link android.content.ContentProvider}. To create a live folder, two components 24 * are required:</p> 25 * <ul> 26 * <li>An activity that can respond to the intent action {@link #ACTION_CREATE_LIVE_FOLDER}. The 27 * activity is responsible for creating the live folder.</li> 28 * <li>A {@link android.content.ContentProvider} to provide the live folder items.</li> 29 * </ul> 30 * 31 * <h3>Lifecycle</h3> 32 * <p>When a user wants to create a live folder, the system looks for all activities with the 33 * intent filter action {@link #ACTION_CREATE_LIVE_FOLDER} and presents the list to the user. 34 * When the user chooses one of the activities, the activity is invoked with the 35 * {@link #ACTION_CREATE_LIVE_FOLDER} action. The activity then creates the live folder and 36 * passes it back to the system by setting it as an 37 * {@link android.app.Activity#setResult(int, android.content.Intent) activity result}. The 38 * live folder is described by a content provider URI, a name, an icon and a display mode. 39 * Finally, when the user opens the live folder, the system queries the content provider 40 * to retrieve the folder's content.</p> 41 * 42 * <h3>Setting up the live folder activity</h3> 43 * <p>The following code sample shows how to write an activity that creates a live folder:</p> 44 * <pre> 45 * public static class MyLiveFolder extends Activity { 46 * public static final Uri CONTENT_URI = Uri.parse("content://my.app/live"); 47 * 48 * protected void onCreate(Bundle savedInstanceState) { 49 * super.onCreate(savedInstanceState); 50 * 51 * final Intent intent = getIntent(); 52 * final String action = intent.getAction(); 53 * 54 * if (LiveFolders.ACTION_CREATE_LIVE_FOLDER.equals(action)) { 55 * setResult(RESULT_OK, createLiveFolder(this, CONTENT_URI, "My LiveFolder", 56 * R.drawable.ic_launcher_contacts_phones)); 57 * } else { 58 * setResult(RESULT_CANCELED); 59 * } 60 * 61 * finish(); 62 * } 63 * 64 * private static Intent createLiveFolder(Context context, Uri uri, String name, 65 * int icon) { 66 * 67 * final Intent intent = new Intent(); 68 * 69 * intent.setData(uri); 70 * intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_NAME, name); 71 * intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_ICON, 72 * Intent.ShortcutIconResource.fromContext(context, icon)); 73 * intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_DISPLAY_MODE, LiveFolders.DISPLAY_MODE_LIST); 74 * 75 * return intent; 76 * } 77 * } 78 * </pre> 79 * <p>The live folder is described by an {@link android.content.Intent} as follows:</p> 80 * <table border="2" width="85%" align="center" frame="hsides" rules="rows"> 81 * <thead> 82 * <tr><th>Component</th> <th>Type</th> <th>Description</th> <th>Required</th></tr> 83 * </thead> 84 * 85 * <tbody> 86 * <tr><th>URI</th> 87 * <td>URI</td> 88 * <td>The ContentProvider URI</td> 89 * <td align="center">Yes</td> 90 * </tr> 91 * <tr><th>{@link #EXTRA_LIVE_FOLDER_NAME}</th> 92 * <td>Extra String</td> 93 * <td>The name of the live folder</td> 94 * <td align="center">Yes</td> 95 * </tr> 96 * <tr><th>{@link #EXTRA_LIVE_FOLDER_ICON}</th> 97 * <td>Extra {@link android.content.Intent.ShortcutIconResource}</td> 98 * <td>The icon of the live folder</td> 99 * <td align="center">Yes</td> 100 * </tr> 101 * <tr><th>{@link #EXTRA_LIVE_FOLDER_DISPLAY_MODE}</th> 102 * <td>Extra int</td> 103 * <td>The display mode of the live folder. The value must be either 104 * {@link #DISPLAY_MODE_GRID} or {@link #DISPLAY_MODE_LIST}.</td> 105 * <td align="center">Yes</td> 106 * </tr> 107 * <tr><th>{@link #EXTRA_LIVE_FOLDER_BASE_INTENT}</th> 108 * <td>Extra Intent</td> 109 * <td>When the user clicks an item inside a live folder, the system will either fire 110 * the intent associated with that item or, if present, the live folder's base intent 111 * with the id of the item appended to the base intent's URI.</td> 112 * <td align="center">No</td> 113 * </tr> 114 * </tbody> 115 * </table> 116 * 117 * <h3>Setting up the content provider</h3> 118 * <p>The live folder's content provider must, upon query, return a {@link android.database.Cursor} 119 * whose columns match the following names:</p> 120 * <table border="2" width="85%" align="center" frame="hsides" rules="rows"> 121 * <thead> 122 * <tr><th>Column</th> <th>Type</th> <th>Description</th> <th>Required</th></tr> 123 * </thead> 124 * 125 * <tbody> 126 * <tr><th>{@link #NAME}</th> 127 * <td>String</td> 128 * <td>The name of the item</td> 129 * <td align="center">Yes</td> 130 * </tr> 131 * <tr><th>{@link #DESCRIPTION}</th> 132 * <td>String</td> 133 * <td>The description of the item. The description is ignored when the live folder's 134 * display mode is {@link #DISPLAY_MODE_GRID}.</td> 135 * <td align="center">No</td> 136 * </tr> 137 * <tr><th>{@link #INTENT}</th> 138 * <td>{@link android.content.Intent}</td> 139 * <td>The intent to fire when the item is clicked. Ignored when the live folder defines 140 * a base intent.</td> 141 * <td align="center">No</td> 142 * </tr> 143 * <tr><th>{@link #ICON_BITMAP}</th> 144 * <td>Bitmap</td> 145 * <td>The icon for the item. When this column value is not null, the values for the 146 * columns {@link #ICON_PACKAGE} and {@link #ICON_RESOURCE} must be null.</td> 147 * <td align="center">No</td> 148 * </tr> 149 * <tr><th>{@link #ICON_PACKAGE}</th> 150 * <td>String</td> 151 * <td>The package of the item's icon. When this value is not null, the value for the 152 * column {@link #ICON_RESOURCE} must be specified and the value for the column 153 * {@link #ICON_BITMAP} must be null.</td> 154 * <td align="center">No</td> 155 * </tr> 156 * <tr><th>{@link #ICON_RESOURCE}</th> 157 * <td>String</td> 158 * <td>The resource name of the item's icon. When this value is not null, the value for the 159 * column {@link #ICON_PACKAGE} must be specified and the value for the column 160 * {@link #ICON_BITMAP} must be null.</td> 161 * <td align="center">No</td> 162 * </tr> 163 * </tbody> 164 * </table> 165 * 166 * @deprecated Live folders are no longer supported by Android. These have been 167 * replaced by the new 168 * <a href="{@docRoot}guide/topics/appwidgets/index.html#collections">AppWidget Collection</a> 169 * APIs introduced in {@link android.os.Build.VERSION_CODES#HONEYCOMB}. These provide 170 * all of the features of live folders plus many more. The use of live folders is greatly 171 * discouraged because of security issues they introduce -- publishing a live folder requires 172 * making all data show for the live folder available to all applications with no 173 * permissions protecting it. 174 */ 175 @Deprecated 176 public final class LiveFolders implements BaseColumns { 177 /** 178 * <p>Content provider column.</p> 179 * <p>Name of the live folder item.</p> 180 * <p>Required.</p> 181 * <p>Type: String.</p> 182 */ 183 public static final String NAME = "name"; 184 185 /** 186 * <p>Content provider column.</p> 187 * <p>Description of the live folder item. This value is ignored if the 188 * live folder's display mode is {@link LiveFolders#DISPLAY_MODE_GRID}.</p> 189 * <p>Optional.</p> 190 * <p>Type: String.</p> 191 * 192 * @see LiveFolders#EXTRA_LIVE_FOLDER_DISPLAY_MODE 193 */ 194 public static final String DESCRIPTION = "description"; 195 196 /** 197 * <p>Content provider column.</p> 198 * <p>Intent of the live folder item.</p> 199 * <p>Optional if the live folder has a base intent.</p> 200 * <p>Type: {@link android.content.Intent}.</p> 201 * 202 * @see LiveFolders#EXTRA_LIVE_FOLDER_BASE_INTENT 203 */ 204 public static final String INTENT = "intent"; 205 206 /** 207 * <p>Content provider column.</p> 208 * <p>Icon of the live folder item, as a custom bitmap.</p> 209 * <p>Optional.</p> 210 * <p>Type: {@link android.graphics.Bitmap}.</p> 211 */ 212 public static final String ICON_BITMAP = "icon_bitmap"; 213 214 /** 215 * <p>Content provider column.</p> 216 * <p>Package where to find the icon of the live folder item. This value can be 217 * obtained easily using 218 * {@link android.content.Intent.ShortcutIconResource#fromContext(android.content.Context, int)}.</p> 219 * <p>Optional.</p> 220 * <p>Type: String.</p> 221 * 222 * @see #ICON_RESOURCE 223 * @see android.content.Intent.ShortcutIconResource 224 */ 225 public static final String ICON_PACKAGE = "icon_package"; 226 227 /** 228 * <p>Content provider column.</p> 229 * <p>Resource name of the live folder item. This value can be obtained easily using 230 * {@link android.content.Intent.ShortcutIconResource#fromContext(android.content.Context, int)}.</p> 231 * <p>Optional.</p> 232 * <p>Type: String.</p> 233 * 234 * @see #ICON_PACKAGE 235 * @see android.content.Intent.ShortcutIconResource 236 */ 237 public static final String ICON_RESOURCE = "icon_resource"; 238 239 /** 240 * Displays a live folder's content in a grid. 241 * 242 * @see LiveFolders#EXTRA_LIVE_FOLDER_DISPLAY_MODE 243 */ 244 public static final int DISPLAY_MODE_GRID = 0x1; 245 246 /** 247 * Displays a live folder's content in a list. 248 * 249 * @see LiveFolders#EXTRA_LIVE_FOLDER_DISPLAY_MODE 250 */ 251 public static final int DISPLAY_MODE_LIST = 0x2; 252 253 /** 254 * The name of the extra used to define the name of a live folder. 255 * 256 * @see #ACTION_CREATE_LIVE_FOLDER 257 */ 258 public static final String EXTRA_LIVE_FOLDER_NAME = "android.intent.extra.livefolder.NAME"; 259 260 /** 261 * The name of the extra used to define the icon of a live folder. 262 * 263 * @see #ACTION_CREATE_LIVE_FOLDER 264 */ 265 public static final String EXTRA_LIVE_FOLDER_ICON = "android.intent.extra.livefolder.ICON"; 266 267 /** 268 * The name of the extra used to define the display mode of a live folder. 269 * 270 * @see #ACTION_CREATE_LIVE_FOLDER 271 * @see #DISPLAY_MODE_GRID 272 * @see #DISPLAY_MODE_LIST 273 */ 274 public static final String EXTRA_LIVE_FOLDER_DISPLAY_MODE = 275 "android.intent.extra.livefolder.DISPLAY_MODE"; 276 277 /** 278 * The name of the extra used to define the base Intent of a live folder. 279 * 280 * @see #ACTION_CREATE_LIVE_FOLDER 281 */ 282 public static final String EXTRA_LIVE_FOLDER_BASE_INTENT = 283 "android.intent.extra.livefolder.BASE_INTENT"; 284 285 /** 286 * Activity Action: Creates a live folder. 287 * <p>Input: Nothing.</p> 288 * <p>Output: An Intent representing the live folder. The intent must contain four 289 * extras: EXTRA_LIVE_FOLDER_NAME (value: String), 290 * EXTRA_LIVE_FOLDER_ICON (value: ShortcutIconResource), 291 * EXTRA_LIVE_FOLDER_URI (value: String) and 292 * EXTRA_LIVE_FOLDER_DISPLAY_MODE (value: int). The Intent can optionnally contain 293 * EXTRA_LIVE_FOLDER_BASE_INTENT (value: Intent).</p> 294 * 295 * @see #EXTRA_LIVE_FOLDER_NAME 296 * @see #EXTRA_LIVE_FOLDER_ICON 297 * @see #EXTRA_LIVE_FOLDER_DISPLAY_MODE 298 * @see #EXTRA_LIVE_FOLDER_BASE_INTENT 299 * @see android.content.Intent.ShortcutIconResource 300 */ 301 @SdkConstant(SdkConstant.SdkConstantType.ACTIVITY_INTENT_ACTION) 302 public static final String ACTION_CREATE_LIVE_FOLDER = 303 "android.intent.action.CREATE_LIVE_FOLDER"; 304 LiveFolders()305 private LiveFolders() { 306 } 307 } 308