ShareActionProvider

public class ShareActionProvider
extends ActionProvider

Provides a share action, which is suitable for an activity's app bar. Creates views that enable data sharing. If the provider appears in the overflow menu, it creates a submenu with the appropriate sharing actions.

Adding a share action

To add a "share" action to your activity, put a ShareActionProvider in the app bar's menu resource. For example:

 <item android:id="@+id/action_share"
      android:title="@string/share"
      app:showAsAction="ifRoom"
      app:actionProviderClass="android.support.v7.widget.ShareActionProvider"/>
 

You do not need to specify an icon, since the ShareActionProvider widget takes care of its own appearance and behavior. However, you do need to specify a title with android:title, in case the action ends up in the overflow menu.

Next, set up the intent that contains the content your activity is able to share. You should create this intent in your handler for onCreateOptionsMenu(), and update it every time the shareable content changes. To set up the intent:

1. Get a reference to the ShareActionProvider by calling getActionProvider() and passing the share action's MenuItem. For example:

    MenuItem shareItem = menu.findItem(R.id.action_share);
    ShareActionProvider myShareActionProvider =
        (ShareActionProvider) MenuItemCompat.getActionProvider(shareItem);

2. Create an intent with the ACTION_SEND action, and attach the content shared by the activity. For example, the following intent shares an image:

    Intent myShareIntent = new Intent(Intent.ACTION_SEND);
    myShareIntent.setType("image/*");
    myShareIntent.putExtra(Intent.EXTRA_STREAM, myImageUri);

3. Call setShareIntent() to attach this intent to the action provider:

    myShareActionProvider.setShareIntent(myShareIntent);
    

4. When the content changes, modify the intent or create a new one, and call setShareIntent() again. For example:

    // Image has changed! Update the intent:
    myShareIntent.putExtra(Intent.EXTRA_STREAM, myNewImageUri);
    myShareActionProvider.setShareIntent(myShareIntent);

Share target rankings

The share action provider retains a ranking for each share target, based on how often the user chooses each one. The more often a user chooses a target, the higher its rank; the most-commonly used target appears in the app bar as the default target.

By default, the target ranking information is stored in a private file with the name specified by DEFAULT_SHARE_HISTORY_FILE_NAME. Ordinarily, the share action provider stores all the history in this single file. However, using a single set of rankings may not make sense if the share action provider is used for different kinds of content. For example, if the activity sometimes shares images and sometimes shares contacts, you would want to maintain two different sets of rankings.

To set the history file, call setShareHistoryFileName() and pass the name of an XML file. The file you specify is used until the next time you call setShareHistoryFileName().

Summary

Inherited methods
From class android.support.v4.view.ActionProvider Context getContext() Gets the context associated with this action provider. boolean hasSubMenu() Determines if this ActionProvider has a submenu associated with it. boolean isVisible() If overridesItemVisibility() returns true, the return value of this method will help determine the visibility of the MenuItem this ActionProvider is bound to. abstract View onCreateActionView() Factory method for creating new action views. View onCreateActionView(MenuItem forItem) Factory method called by the Android framework to create new action views. boolean onPerformDefaultAction() Performs an optional default action. void onPrepareSubMenu(SubMenu subMenu) Called to prepare an associated submenu for the menu item backed by this ActionProvider. boolean overridesItemVisibility() The result of this method determines whether or not isVisible() will be used by the MenuItem this ActionProvider is bound to help determine its visibility. void refreshVisibility() If this ActionProvider is associated with an item in a menu, refresh the visibility of the item based on overridesItemVisibility() and isVisible(). void setVisibilityListener(ActionProvider.VisibilityListener listener) Set a listener to be notified when this ActionProvider's overridden visibility changes.
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long millis, int nanos) Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. final void wait(long millis) Causes the current thread to wait until either another thread invokes the notify() method or the notifyAll() method for this object, or a specified amount of time has elapsed. final void wait() Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object.

Constants

String DEFAULT_SHARE_HISTORY_FILE_NAME

Public constructors

ShareActionProvider (Context context)

Public methods

boolean hasSubMenu ()

View onCreateActionView ()

void onPrepareSubMenu (SubMenu subMenu)

void setOnShareTargetSelectedListener (ShareActionProvider.OnShareTargetSelectedListener listener)

void setShareHistoryFileName (String shareHistoryFile)

 private void doShare(Intent intent) {
     if (IMAGE.equals(intent.getMimeType())) {
         mShareActionProvider.setHistoryFileName(SHARE_IMAGE_HISTORY_FILE_NAME);
     } else if (TEXT.equals(intent.getMimeType())) {
         mShareActionProvider.setHistoryFileName(SHARE_TEXT_HISTORY_FILE_NAME);
     }
     mShareActionProvider.setIntent(intent);
     supportInvalidateOptionsMenu();
 }
 

void setShareIntent (Intent shareIntent)

  Intent shareIntent = new Intent(Intent.ACTION_SEND);
  shareIntent.setType("image/*");
  Uri uri = Uri.fromFile(new File(getFilesDir(), "foo.jpg"));
  shareIntent.putExtra(Intent.EXTRA_STREAM, uri.toString());