ShareActionProvider.java revision 961dd11895ce72e59bca124ef5bea4e4c1183099 
1/*
2 * Copyright (C) 2011 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.widget;
18
19import com.android.internal.R;
20
21import android.content.Context;
22import android.content.Intent;
23import android.graphics.drawable.Drawable;
24import android.util.TypedValue;
25import android.view.ActionProvider;
26import android.view.MenuItem;
27import android.view.SubMenu;
28import android.view.View;
29
30/**
31 * This is a provider for a share action. It is responsible for creating views
32 * that enable data sharing and also to perform a default action for showing
33 * a share dialog.
34 * <p>
35 * Here is how to use the action provider with custom backing file in a {@link MenuItem}:
36 * </p>
37 * <p>
38 * <pre>
39 * <code>
40 *  // In Activity#onCreateOptionsMenu
41 *  public boolean onCreateOptionsMenu(Menu menu) {
42 *      // Get the menu item.
43 *      MenuItem menuItem = menu.findItem(R.id.my_menu_item);
44 *      // Get the provider and hold onto it to set/change the share intent.
45 *      mShareActionProvider = (ShareActionProvider) menuItem.getActionProvider();
46 *      // Set history different from the default before getting the action
47 *      // view since a call to {@link MenuItem#getActionView() MenuItem.getActionView()} calls
48 *      // {@link ActionProvider#onCreateActionView()} which uses the backing file name. Omit this
49 *      // line if using the default share history file is desired.
50 *      mShareActionProvider.setShareHistoryFileName("custom_share_history.xml");
51 *      // Get the action view and hold onto it to set the share intent.
52 *      mActionView = menuItem.getActionView();
53 *      . . .
54 *  }
55 *
56 *  // Somewhere in the application.
57 *  public void doShare(Intent shareIntent) {
58 *      // When you want to share set the share intent.
59 *      mShareActionProvider.setShareIntent(mActionView, shareIntent);
60 *  }
61 * </pre>
62 * </code>
63 * </p>
64 * <p>
65 * <strong>Note:</strong> While the sample snippet demonstrates how to use this provider
66 * in the context of a menu item, the use of the provider is not limited to menu items.
67 * </p>
68 *
69 * @see ActionProvider
70 */
71public class ShareActionProvider extends ActionProvider {
72
73    /**
74     * The default name for storing share history.
75     */
76    public static final String DEFAULT_SHARE_HISTORY_FILE_NAME = "share_history.xml";
77
78    private final Context mContext;
79    private String mShareHistoryFileName = DEFAULT_SHARE_HISTORY_FILE_NAME;
80
81    /**
82     * Creates a new instance.
83     *
84     * @param context Context for accessing resources.
85     */
86    public ShareActionProvider(Context context) {
87        super(context);
88        mContext = context;
89    }
90
91    /**
92     * {@inheritDoc}
93     */
94    @Override
95    public View onCreateActionView() {
96        ActivityChooserModel dataModel = ActivityChooserModel.get(mContext, mShareHistoryFileName);
97        ActivityChooserView activityChooserView = new ActivityChooserView(mContext);
98        activityChooserView.setActivityChooserModel(dataModel);
99        TypedValue outTypedValue = new TypedValue();
100        mContext.getTheme().resolveAttribute(R.attr.actionModeShareDrawable, outTypedValue, true);
101        Drawable drawable = mContext.getResources().getDrawable(outTypedValue.resourceId);
102        activityChooserView.setExpandActivityOverflowButtonDrawable(drawable);
103        return activityChooserView;
104    }
105
106    @Override
107    public boolean hasSubMenu() {
108        return true;
109    }
110
111    @Override
112    public void onPrepareSubMenu(SubMenu subMenu) {
113        // TODO Implement me
114    }
115
116    /**
117     * Sets the file name of a file for persisting the share history which
118     * history will be used for ordering share targets. This file will be used
119     * for all view created by {@link #onCreateActionView()}. Defaults to
120     * {@link #DEFAULT_SHARE_HISTORY_FILE_NAME}. Set to <code>null</code>
121     * if share history should not be persisted between sessions.
122     * <p>
123     * <strong>Note:</strong> The history file name can be set any time, however
124     * only the action views created by {@link #onCreateActionView()} after setting
125     * the file name will be backed by the provided file.
126     * <p>
127     *
128     * @param shareHistoryFile The share history file name.
129     */
130    public void setShareHistoryFileName(String shareHistoryFile) {
131        mShareHistoryFileName = shareHistoryFile;
132    }
133
134    /**
135     * Sets an intent with information about the share action. Here is a
136     * sample for constructing a share intent:
137     * <p>
138     * <pre>
139     * <code>
140     *  Intent shareIntent = new Intent(Intent.ACTION_SEND);
141     *  shareIntent.setType("image/*");
142     *  Uri uri = Uri.fromFile(new File(getFilesDir(), "foo.jpg"));
143     *  shareIntent.putExtra(Intent.EXTRA_STREAM, uri.toString());
144     * </pre>
145     * </code>
146     * </p>
147     *
148     * @param actionView An action view created by {@link #onCreateActionView()}.
149     * @param shareIntent The share intent.
150     *
151     * @see Intent#ACTION_SEND
152     * @see Intent#ACTION_SEND_MULTIPLE
153     */
154    public void setShareIntent(View actionView, Intent shareIntent) {
155        if (actionView instanceof ActivityChooserView) {
156            ActivityChooserView activityChooserView = (ActivityChooserView) actionView;
157            activityChooserView.getDataModel().setIntent(shareIntent);
158        } else {
159            throw new IllegalArgumentException("actionView not instance of ActivityChooserView");
160        }
161    }
162}
163