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
17package android.provider;
18
19import 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
176public 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
305    private LiveFolders() {
306    }
307}
308