public class ShareActionProvider extends ActionProvider
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:
getActionProvider()
and
passing the share action's MenuItem
. For
example:
MenuItem shareItem = menu.findItem(R.id.action_share); ShareActionProvider myShareActionProvider = (ShareActionProvider) MenuItemCompat.getActionProvider(shareItem);
Intent.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);
setShareIntent()
to attach this intent to
the action provider:
myShareActionProvider.setShareIntent(myShareIntent);
setShareIntent()
again. For example:
// Image has changed! Update the intent: myShareIntent.putExtra(Intent.EXTRA_STREAM, myNewImageUri); myShareActionProvider.setShareIntent(myShareIntent);
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()
.
ActionProvider
Modifier and Type | Class and Description |
---|---|
static interface |
ShareActionProvider.OnShareTargetSelectedListener
Listener for the event of selecting a share target.
|
ActionProvider.SubUiVisibilityListener, ActionProvider.VisibilityListener
Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_SHARE_HISTORY_FILE_NAME
The default name for storing share history.
|
Constructor and Description |
---|
ShareActionProvider(Context context)
Creates a new instance.
|
Modifier and Type | Method and Description |
---|---|
boolean |
hasSubMenu()
Determines if this ActionProvider has a submenu associated with it.
|
View |
onCreateActionView()
Factory method for creating new action views.
|
void |
onPrepareSubMenu(SubMenu subMenu)
Called to prepare an associated submenu for the menu item backed by this ActionProvider.
|
void |
setOnShareTargetSelectedListener(ShareActionProvider.OnShareTargetSelectedListener listener)
Sets a listener to be notified when a share target has been selected.
|
void |
setShareHistoryFileName(String shareHistoryFile)
Sets the file name of a file for persisting the share history which
history will be used for ordering share targets.
|
void |
setShareIntent(Intent shareIntent)
Sets an intent with information about the share action.
|
getContext, isVisible, onCreateActionView, onPerformDefaultAction, overridesItemVisibility, refreshVisibility, reset, setSubUiVisibilityListener, setVisibilityListener, subUiVisibilityChanged
public static final String DEFAULT_SHARE_HISTORY_FILE_NAME
public ShareActionProvider(Context context)
context
- Context for accessing resources.public void setOnShareTargetSelectedListener(ShareActionProvider.OnShareTargetSelectedListener listener)
Note: If you choose the backing share history file you will still be notified in this callback.
listener
- The listener.public View onCreateActionView()
onCreateActionView
in class ActionProvider
public boolean hasSubMenu()
Associated submenus will be shown when an action view is not. This provider instance will
receive a call to ActionProvider.onPrepareSubMenu(SubMenu)
after the call to ActionProvider.onPerformDefaultAction()
and before a submenu is displayed to the user.
hasSubMenu
in class ActionProvider
public void onPrepareSubMenu(SubMenu subMenu)
if ActionProvider.hasSubMenu()
returns true, this method will be called when the menu item is
selected to prepare the submenu for presentation to the user. Apps may use this to create or
alter submenu content right before display.
onPrepareSubMenu
in class ActionProvider
subMenu
- Submenu that will be displayedpublic void setShareHistoryFileName(String shareHistoryFile)
onCreateActionView()
. Defaults to
DEFAULT_SHARE_HISTORY_FILE_NAME
. Set to null
if share history should not be persisted between sessions.
Note: The history file name can be set any time, however
only the action views created by onCreateActionView()
after setting
the file name will be backed by the provided file. Therefore, if you want to
use different history files for sharing specific types of content, every time
you change the history file with setShareHistoryFileName(String)
you must
call AppCompatActivity.supportInvalidateOptionsMenu()
to recreate the action view. You should not call
AppCompatActivity.supportInvalidateOptionsMenu()
from
Activity.onCreateOptionsMenu(Menu)
.
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(); }
shareHistoryFile
- The share history file name.public 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());
shareIntent
- The share intent.Intent.ACTION_SEND
,
Intent.ACTION_SEND_MULTIPLE