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 }