• Home
  • History
  • Annotate
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2013 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.support.v7.widget;
18 
19 import android.content.Context;
20 import android.content.Intent;
21 import android.content.pm.PackageManager;
22 import android.content.pm.ResolveInfo;
23 import android.graphics.drawable.Drawable;
24 import android.os.Build;
25 import android.support.v4.view.ActionProvider;
26 import android.support.v7.appcompat.R;
27 import android.support.v7.internal.widget.ActivityChooserModel;
28 import android.support.v7.internal.widget.ActivityChooserView;
29 import android.support.v7.internal.widget.TintManager;
30 import android.util.TypedValue;
31 import android.view.Menu;
32 import android.view.MenuItem;
33 import android.view.MenuItem.OnMenuItemClickListener;
34 import android.view.SubMenu;
35 import android.view.View;
36 import android.support.v7.internal.widget.ActivityChooserModel.OnChooseActivityListener;
37 
38 /**
39  * This is a provider for a share action. It is responsible for creating views
40  * that enable data sharing and also to show a sub menu with sharing activities
41  * if the hosting item is placed on the overflow menu.
42  *
43  * <p class="note"><strong>Note:</strong> This class is included in the <a
44  * href="{@docRoot}tools/extras/support-library.html">support library</a> for compatibility
45  * with API level 7 and higher. If you're developing your app for API level 14 and higher
46  * <em>only</em>, you should instead use the framework {@link android.widget.ShareActionProvider}
47  * class.</p>
48  *
49  * <p>
50  * Here is how to use the action provider with custom backing file in a {@link MenuItem}:
51  * </p>
52  * <pre><code>
53  *  // In {@link android.app.Activity#onCreateOptionsMenu Activity.onCreateOptionsMenu()}
54  *  public boolean onCreateOptionsMenu(Menu menu) {
55  *      // Get the menu item.
56  *      MenuItem menuItem = menu.findItem(R.id.my_menu_item);
57  *      // Get the provider and hold onto it to set/change the share intent.
58  *      mShareActionProvider = (ShareActionProvider) MenuItemCompat.getActionProvider(menuItem);
59  *      // Set history different from the default before getting the action
60  *      // view since a call to {@link android.support.v4.view.MenuItemCompat#getActionView(android.view.MenuItem) MenuItemCompat.getActionView()} calls
61  *      // {@link ActionProvider#onCreateActionView()} which uses the backing file name. Omit this
62  *      // line if using the default share history file is desired.
63  *      mShareActionProvider.setShareHistoryFileName("custom_share_history.xml");
64  *      . . .
65  *  }
66  *
67  *  // Somewhere in the application.
68  *  public void doShare(Intent shareIntent) {
69  *      // When you want to share set the share intent.
70  *      mShareActionProvider.setShareIntent(shareIntent);
71  *  }
72  * </code></pre>
73  * <p>
74  * <strong>Note:</strong> While the sample snippet demonstrates how to use this provider
75  * in the context of a menu item, the use of the provider is not limited to menu items.
76  * </p>
77  *
78  * <div class="special reference">
79  * <h3>Developer Guides</h3>
80  *
81  * <p>For information about how to use {@link ShareActionProvider}, see the
82  * <a href="{@docRoot}guide/topics/ui/actionbar.html#ActionProvider">Action Bar</a> API guide.</p>
83  * </div>
84  *
85  * @see ActionProvider
86  */
87 public class ShareActionProvider extends ActionProvider {
88 
89     /**
90      * Listener for the event of selecting a share target.
91      */
92     public interface OnShareTargetSelectedListener {
93 
94         /**
95          * Called when a share target has been selected. The client can
96          * decide whether to perform some action before the sharing is
97          * actually performed.
98          * <p>
99          * <strong>Note:</strong> Modifying the intent is not permitted and
100          *     any changes to the latter will be ignored.
101          * </p>
102          * <p>
103          * <strong>Note:</strong> You should <strong>not</strong> handle the
104          *     intent here. This callback aims to notify the client that a
105          *     sharing is being performed, so the client can update the UI
106          *     if necessary.
107          * </p>
108          *
109          * @param source The source of the notification.
110          * @param intent The intent for launching the chosen share target.
111          * @return The return result is ignored. Always return false for consistency.
112          */
onShareTargetSelected(ShareActionProvider source, Intent intent)113         public boolean onShareTargetSelected(ShareActionProvider source, Intent intent);
114     }
115 
116     /**
117      * The default for the maximal number of activities shown in the sub-menu.
118      */
119     private static final int DEFAULT_INITIAL_ACTIVITY_COUNT = 4;
120 
121     /**
122      * The the maximum number activities shown in the sub-menu.
123      */
124     private int mMaxShownActivityCount = DEFAULT_INITIAL_ACTIVITY_COUNT;
125 
126     /**
127      * Listener for handling menu item clicks.
128      */
129     private final ShareMenuItemOnMenuItemClickListener mOnMenuItemClickListener =
130             new ShareMenuItemOnMenuItemClickListener();
131 
132     /**
133      * The default name for storing share history.
134      */
135     public static final String DEFAULT_SHARE_HISTORY_FILE_NAME = "share_history.xml";
136 
137     /**
138      * Context for accessing resources.
139      */
140     private final Context mContext;
141 
142     /**
143      * The name of the file with share history data.
144      */
145     private String mShareHistoryFileName = DEFAULT_SHARE_HISTORY_FILE_NAME;
146 
147     private OnShareTargetSelectedListener mOnShareTargetSelectedListener;
148 
149     private OnChooseActivityListener mOnChooseActivityListener;
150 
151     /**
152      * Creates a new instance.
153      *
154      * @param context Context for accessing resources.
155      */
ShareActionProvider(Context context)156     public ShareActionProvider(Context context) {
157         super(context);
158         mContext = context;
159     }
160 
161     /**
162      * Sets a listener to be notified when a share target has been selected.
163      * The listener can optionally decide to handle the selection and
164      * not rely on the default behavior which is to launch the activity.
165      * <p>
166      * <strong>Note:</strong> If you choose the backing share history file
167      *     you will still be notified in this callback.
168      * </p>
169      * @param listener The listener.
170      */
setOnShareTargetSelectedListener(OnShareTargetSelectedListener listener)171     public void setOnShareTargetSelectedListener(OnShareTargetSelectedListener listener) {
172         mOnShareTargetSelectedListener = listener;
173         setActivityChooserPolicyIfNeeded();
174     }
175 
176     /**
177      * {@inheritDoc}
178      */
179     @Override
onCreateActionView()180     public View onCreateActionView() {
181         // Create the view and set its data model.
182         ActivityChooserView activityChooserView = new ActivityChooserView(mContext);
183         if (!activityChooserView.isInEditMode()) {
184             ActivityChooserModel dataModel = ActivityChooserModel.get(mContext, mShareHistoryFileName);
185             activityChooserView.setActivityChooserModel(dataModel);
186         }
187 
188         // Lookup and set the expand action icon.
189         TypedValue outTypedValue = new TypedValue();
190         mContext.getTheme().resolveAttribute(R.attr.actionModeShareDrawable, outTypedValue, true);
191         Drawable drawable = TintManager.getDrawable(mContext, outTypedValue.resourceId);
192         activityChooserView.setExpandActivityOverflowButtonDrawable(drawable);
193         activityChooserView.setProvider(this);
194 
195         // Set content description.
196         activityChooserView.setDefaultActionButtonContentDescription(
197                 R.string.abc_shareactionprovider_share_with_application);
198         activityChooserView.setExpandActivityOverflowButtonContentDescription(
199                 R.string.abc_shareactionprovider_share_with);
200 
201         return activityChooserView;
202     }
203 
204     /**
205      * {@inheritDoc}
206      */
207     @Override
hasSubMenu()208     public boolean hasSubMenu() {
209         return true;
210     }
211 
212     /**
213      * {@inheritDoc}
214      */
215     @Override
onPrepareSubMenu(SubMenu subMenu)216     public void onPrepareSubMenu(SubMenu subMenu) {
217         // Clear since the order of items may change.
218         subMenu.clear();
219 
220         ActivityChooserModel dataModel = ActivityChooserModel.get(mContext, mShareHistoryFileName);
221         PackageManager packageManager = mContext.getPackageManager();
222 
223         final int expandedActivityCount = dataModel.getActivityCount();
224         final int collapsedActivityCount = Math.min(expandedActivityCount, mMaxShownActivityCount);
225 
226         // Populate the sub-menu with a sub set of the activities.
227         for (int i = 0; i < collapsedActivityCount; i++) {
228             ResolveInfo activity = dataModel.getActivity(i);
229             subMenu.add(0, i, i, activity.loadLabel(packageManager))
230                     .setIcon(activity.loadIcon(packageManager))
231                     .setOnMenuItemClickListener(mOnMenuItemClickListener);
232         }
233 
234         if (collapsedActivityCount < expandedActivityCount) {
235             // Add a sub-menu for showing all activities as a list item.
236             SubMenu expandedSubMenu = subMenu.addSubMenu(Menu.NONE, collapsedActivityCount,
237                     collapsedActivityCount,
238                     mContext.getString(R.string.abc_activity_chooser_view_see_all));
239             for (int i = 0; i < expandedActivityCount; i++) {
240                 ResolveInfo activity = dataModel.getActivity(i);
241                 expandedSubMenu.add(0, i, i, activity.loadLabel(packageManager))
242                         .setIcon(activity.loadIcon(packageManager))
243                         .setOnMenuItemClickListener(mOnMenuItemClickListener);
244             }
245         }
246     }
247 
248     /**
249      * Sets the file name of a file for persisting the share history which
250      * history will be used for ordering share targets. This file will be used
251      * for all view created by {@link #onCreateActionView()}. Defaults to
252      * {@link #DEFAULT_SHARE_HISTORY_FILE_NAME}. Set to <code>null</code>
253      * if share history should not be persisted between sessions.
254      * <p>
255      * <strong>Note:</strong> The history file name can be set any time, however
256      * only the action views created by {@link #onCreateActionView()} after setting
257      * the file name will be backed by the provided file. Therefore, if you want to
258      * use different history files for sharing specific types of content, every time
259      * you change the history file {@link #setShareHistoryFileName(String)} you must
260      * call {@link android.app.Activity#invalidateOptionsMenu()} to recreate the
261      * action view. You should <strong>not</strong> call
262      * {@link android.app.Activity#invalidateOptionsMenu()} from
263      * {@link android.app.Activity#onCreateOptionsMenu(Menu)}."
264      * <p>
265      * <code>
266      * private void doShare(Intent intent) {
267      *     if (IMAGE.equals(intent.getMimeType())) {
268      *         mShareActionProvider.setHistoryFileName(SHARE_IMAGE_HISTORY_FILE_NAME);
269      *     } else if (TEXT.equals(intent.getMimeType())) {
270      *         mShareActionProvider.setHistoryFileName(SHARE_TEXT_HISTORY_FILE_NAME);
271      *     }
272      *     mShareActionProvider.setIntent(intent);
273      *     invalidateOptionsMenu();
274      * }
275      * <code>
276      *
277      * @param shareHistoryFile The share history file name.
278      */
setShareHistoryFileName(String shareHistoryFile)279     public void setShareHistoryFileName(String shareHistoryFile) {
280         mShareHistoryFileName = shareHistoryFile;
281         setActivityChooserPolicyIfNeeded();
282     }
283 
284     /**
285      * Sets an intent with information about the share action. Here is a
286      * sample for constructing a share intent:
287      * <p>
288      * <pre>
289      * <code>
290      *  Intent shareIntent = new Intent(Intent.ACTION_SEND);
291      *  shareIntent.setType("image/*");
292      *  Uri uri = Uri.fromFile(new File(getFilesDir(), "foo.jpg"));
293      *  shareIntent.putExtra(Intent.EXTRA_STREAM, uri.toString());
294      * </pre>
295      * </code>
296      * </p>
297      *
298      * @param shareIntent The share intent.
299      *
300      * @see Intent#ACTION_SEND
301      * @see Intent#ACTION_SEND_MULTIPLE
302      */
setShareIntent(Intent shareIntent)303     public void setShareIntent(Intent shareIntent) {
304         if (shareIntent != null) {
305             final String action = shareIntent.getAction();
306             if (Intent.ACTION_SEND.equals(action) || Intent.ACTION_SEND_MULTIPLE.equals(action)) {
307                 updateIntent(shareIntent);
308             }
309         }
310         ActivityChooserModel dataModel = ActivityChooserModel.get(mContext,
311                 mShareHistoryFileName);
312         dataModel.setIntent(shareIntent);
313     }
314 
315     /**
316      * Reusable listener for handling share item clicks.
317      */
318     private class ShareMenuItemOnMenuItemClickListener implements OnMenuItemClickListener {
319         @Override
onMenuItemClick(MenuItem item)320         public boolean onMenuItemClick(MenuItem item) {
321             ActivityChooserModel dataModel = ActivityChooserModel.get(mContext,
322                     mShareHistoryFileName);
323             final int itemId = item.getItemId();
324             Intent launchIntent = dataModel.chooseActivity(itemId);
325             if (launchIntent != null) {
326                 final String action = launchIntent.getAction();
327                 if (Intent.ACTION_SEND.equals(action) ||
328                         Intent.ACTION_SEND_MULTIPLE.equals(action)) {
329                     updateIntent(launchIntent);
330                 }
331                 mContext.startActivity(launchIntent);
332             }
333             return true;
334         }
335     }
336 
337     /**
338      * Set the activity chooser policy of the model backed by the current
339      * share history file if needed which is if there is a registered callback.
340      */
setActivityChooserPolicyIfNeeded()341     private void setActivityChooserPolicyIfNeeded() {
342         if (mOnShareTargetSelectedListener == null) {
343             return;
344         }
345         if (mOnChooseActivityListener == null) {
346             mOnChooseActivityListener = new ShareActivityChooserModelPolicy();
347         }
348         ActivityChooserModel dataModel = ActivityChooserModel.get(mContext, mShareHistoryFileName);
349         dataModel.setOnChooseActivityListener(mOnChooseActivityListener);
350     }
351 
352     /**
353      * Policy that delegates to the {@link OnShareTargetSelectedListener}, if such.
354      */
355     private class ShareActivityChooserModelPolicy implements OnChooseActivityListener {
356         @Override
onChooseActivity(ActivityChooserModel host, Intent intent)357         public boolean onChooseActivity(ActivityChooserModel host, Intent intent) {
358             if (mOnShareTargetSelectedListener != null) {
359                 mOnShareTargetSelectedListener.onShareTargetSelected(
360                         ShareActionProvider.this, intent);
361             }
362             return false;
363         }
364     }
365 
updateIntent(Intent intent)366     private void updateIntent(Intent intent) {
367         if (Build.VERSION.SDK_INT >= 21) {
368             // If we're on Lollipop, we can open the intent as a document
369             intent.addFlags(Intent.FLAG_ACTIVITY_NEW_DOCUMENT |
370                     Intent.FLAG_ACTIVITY_MULTIPLE_TASK);
371         } else {
372             // Else, we will use the old CLEAR_WHEN_TASK_RESET flag
373             intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET);
374         }
375     }
376 }