/* * Copyright (C) 2008 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.provider; import android.annotation.SdkConstant; /** *

A LiveFolder is a special folder whose content is provided by a * {@link android.content.ContentProvider}. To create a live folder, two components * are required:

An activity that can respond to the intent action {@link #ACTION_CREATE_LIVE_FOLDER}. The * activity is responsible for creating the live folder.
A {@link android.content.ContentProvider} to provide the live folder items.

* *

Lifecycle

When a user wants to create a live folder, the system looks for all activities with the * intent filter action {@link #ACTION_CREATE_LIVE_FOLDER} and presents the list to the user. * When the user chooses one of the activities, the activity is invoked with the * {@link #ACTION_CREATE_LIVE_FOLDER} action. The activity then creates the live folder and * passes it back to the system by setting it as an * {@link android.app.Activity#setResult(int, android.content.Intent) activity result}. The * live folder is described by a content provider URI, a name, an icon and a display mode. * Finally, when the user opens the live folder, the system queries the content provider * to retrieve the folder's content.

* *

Setting up the live folder activity

The following code sample shows how to write an activity that creates a live folder:

 * public static class MyLiveFolder extends Activity {
 *     public static final Uri CONTENT_URI = Uri.parse("content://my.app/live");
 *
 *     protected void onCreate(Bundle savedInstanceState) {
 *         super.onCreate(savedInstanceState);
 *
 *         final Intent intent = getIntent();
 *         final String action = intent.getAction();
 *
 *         if (LiveFolders.ACTION_CREATE_LIVE_FOLDER.equals(action)) {
 *             setResult(RESULT_OK, createLiveFolder(this, CONTENT_URI, "My LiveFolder",
 *                     R.drawable.ic_launcher_contacts_phones));
 *         } else {
 *             setResult(RESULT_CANCELED);
 *         }
 *
 *         finish();
 *     }
 *
 *     private static Intent createLiveFolder(Context context, Uri uri, String name,
 *             int icon) {
 *
 *         final Intent intent = new Intent();
 *
 *         intent.setData(uri);
 *         intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_NAME, name);
 *         intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_ICON,
 *                 Intent.ShortcutIconResource.fromContext(context, icon));
 *         intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_DISPLAY_MODE, LiveFolders.DISPLAY_MODE_LIST);
 *
 *         return intent;
 *     }
 * }
 *

The live folder is described by an {@link android.content.Intent} as follows:

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

Component	Type	Description	Required
URI	URI	The ContentProvider URI	Yes
{@link #EXTRA_LIVE_FOLDER_NAME}	Extra String	The name of the live folder	Yes
{@link #EXTRA_LIVE_FOLDER_ICON}	Extra {@link android.content.Intent.ShortcutIconResource}	The icon of the live folder	Yes
{@link #EXTRA_LIVE_FOLDER_DISPLAY_MODE}	Extra int	The display mode of the live folder. The value must be either * {@link #DISPLAY_MODE_GRID} or {@link #DISPLAY_MODE_LIST}.	Yes
{@link #EXTRA_LIVE_FOLDER_BASE_INTENT}	Extra Intent	When the user clicks an item inside a live folder, the system will either fire * the intent associated with that item or, if present, the live folder's base intent * with the id of the item appended to the base intent's URI.	No

* *

Setting up the content provider

The live folder's content provider must, upon query, return a {@link android.database.Cursor} * whose columns match the following names:

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

Column	Type	Description	Required
{@link #NAME}	String	The name of the item	Yes
{@link #DESCRIPTION}	String	The description of the item. The description is ignored when the live folder's * display mode is {@link #DISPLAY_MODE_GRID}.	No
{@link #INTENT}	{@link android.content.Intent}	The intent to fire when the item is clicked. Ignored when the live folder defines * a base intent.	No
{@link #ICON_BITMAP}	Bitmap	The icon for the item. When this column value is not null, the values for the * columns {@link #ICON_PACKAGE} and {@link #ICON_RESOURCE} must be null.	No
{@link #ICON_PACKAGE}	String	The package of the item's icon. When this value is not null, the value for the * column {@link #ICON_RESOURCE} must be specified and the value for the column * {@link #ICON_BITMAP} must be null.	No
{@link #ICON_RESOURCE}	String	The resource name of the item's icon. When this value is not null, the value for the * column {@link #ICON_PACKAGE} must be specified and the value for the column * {@link #ICON_BITMAP} must be null.	No

*/ public final class LiveFolders implements BaseColumns { /** *

Content provider column.

Name of the live folder item.

Required.

Type: String.

*/ public static final String NAME = "name"; /** *

Content provider column.

Description of the live folder item. This value is ignored if the * live folder's display mode is {@link LiveFolders#DISPLAY_MODE_GRID}.

Optional.

Type: String.

* * @see LiveFolders#EXTRA_LIVE_FOLDER_DISPLAY_MODE */ public static final String DESCRIPTION = "description"; /** *

Content provider column.

Intent of the live folder item.

Optional if the live folder has a base intent.

Type: {@link android.content.Intent}.

* * @see LiveFolders#EXTRA_LIVE_FOLDER_BASE_INTENT */ public static final String INTENT = "intent"; /** *

Content provider column.

Icon of the live folder item, as a custom bitmap.

Optional.

Type: {@link android.graphics.Bitmap}.

*/ public static final String ICON_BITMAP = "icon_bitmap"; /** *

Content provider column.

Package where to find the icon of the live folder item. This value can be * obtained easily using * {@link android.content.Intent.ShortcutIconResource#fromContext(android.content.Context, int)}.

Optional.

Type: String.

* * @see #ICON_RESOURCE * @see android.content.Intent.ShortcutIconResource */ public static final String ICON_PACKAGE = "icon_package"; /** *

Content provider column.

Resource name of the live folder item. This value can be obtained easily using * {@link android.content.Intent.ShortcutIconResource#fromContext(android.content.Context, int)}.

Optional.

Type: String.

* * @see #ICON_PACKAGE * @see android.content.Intent.ShortcutIconResource */ public static final String ICON_RESOURCE = "icon_resource"; /** * Displays a live folder's content in a grid. * * @see LiveFolders#EXTRA_LIVE_FOLDER_DISPLAY_MODE */ public static final int DISPLAY_MODE_GRID = 0x1; /** * Displays a live folder's content in a list. * * @see LiveFolders#EXTRA_LIVE_FOLDER_DISPLAY_MODE */ public static final int DISPLAY_MODE_LIST = 0x2; /** * The name of the extra used to define the name of a live folder. * * @see #ACTION_CREATE_LIVE_FOLDER */ public static final String EXTRA_LIVE_FOLDER_NAME = "android.intent.extra.livefolder.NAME"; /** * The name of the extra used to define the icon of a live folder. * * @see #ACTION_CREATE_LIVE_FOLDER */ public static final String EXTRA_LIVE_FOLDER_ICON = "android.intent.extra.livefolder.ICON"; /** * The name of the extra used to define the display mode of a live folder. * * @see #ACTION_CREATE_LIVE_FOLDER * @see #DISPLAY_MODE_GRID * @see #DISPLAY_MODE_LIST */ public static final String EXTRA_LIVE_FOLDER_DISPLAY_MODE = "android.intent.extra.livefolder.DISPLAY_MODE"; /** * The name of the extra used to define the base Intent of a live folder. * * @see #ACTION_CREATE_LIVE_FOLDER */ public static final String EXTRA_LIVE_FOLDER_BASE_INTENT = "android.intent.extra.livefolder.BASE_INTENT"; /** * Activity Action: Creates a live folder. *

Input: Nothing.

Output: An Intent representing the live folder. The intent must contain four * extras: EXTRA_LIVE_FOLDER_NAME (value: String), * EXTRA_LIVE_FOLDER_ICON (value: ShortcutIconResource), * EXTRA_LIVE_FOLDER_URI (value: String) and * EXTRA_LIVE_FOLDER_DISPLAY_MODE (value: int). The Intent can optionnally contain * EXTRA_LIVE_FOLDER_BASE_INTENT (value: Intent).

* * @see #EXTRA_LIVE_FOLDER_NAME * @see #EXTRA_LIVE_FOLDER_ICON * @see #EXTRA_LIVE_FOLDER_DISPLAY_MODE * @see #EXTRA_LIVE_FOLDER_BASE_INTENT * @see android.content.Intent.ShortcutIconResource */ @SdkConstant(SdkConstant.SdkConstantType.ACTIVITY_INTENT_ACTION) public static final String ACTION_CREATE_LIVE_FOLDER = "android.intent.action.CREATE_LIVE_FOLDER"; private LiveFolders() { } }