• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1page.title=Adding an Easy Share Action
2parent.title=Sharing Content
3parent.link=index.html
4
5trainingnavtop=true
6previous.title=Receiving Simple Data from Other Apps
7previous.link=receive.html
8
9@jd:body
10
11<div id="tb-wrapper">
12<div id="tb">
13
14<!-- table of contents -->
15<h2>This lesson teaches you to</h2>
16<ol>
17  <li><a href="#update-menus">Update Menu Declarations</a></li>
18  <li><a href="#set-share-intent">Set the Share Intent</a></li>
19</ol>
20
21<!-- other docs (NOT javadocs) -->
22<h2>You should also read</h2>
23<ul>
24  <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li>
25</ul>
26
27</div>
28</div>
29
30
31<p>Implementing an effective and user friendly share action in your {@link android.app.ActionBar}
32is made even easier with the introduction of {@link  android.view.ActionProvider} in Android 4.0
33(API Level 14). An {@link android.view.ActionProvider}, once attached to a menu item in the action
34bar, handles both the appearance and behavior of that item. In the case of {@link
35android.widget.ShareActionProvider}, you provide a share intent and it does the rest.</p>
36
37<p class="note"><strong>Note:&nbsp;</strong> {@link android.widget.ShareActionProvider} is available
38starting with API Level 14 and higher.</p>
39
40
41<div class="figure" style="width:200px">
42<img src="{@docRoot}images/ui/actionbar-shareaction.png" alt="" id="figure1" />
43<p class="img-caption">
44  <strong>Figure 1.</strong> The {@link android.widget.ShareActionProvider} in the Gallery app.
45</p>
46</div>
47
48<h2 id="update-menus">Update Menu Declarations</h2>
49
50<p>
51    To get started with {@link android.widget.ShareActionProvider ShareActionProviders},
52    define the <code>android:actionProviderClass</code> attribute for the corresponding
53    <code>&lt;item&gt;</code> in your <a href="{@docRoot}guide/topics/resources/menu-resource.html"
54    >menu resource</a> file:</p>
55
56<pre>
57&lt;menu xmlns:android=&quot;http://schemas.android.com/apk/res/android&quot;&gt;
58    &lt;item
59            android:id=&quot;@+id/menu_item_share&quot;
60            android:showAsAction=&quot;ifRoom&quot;
61            android:title=&quot;Share&quot;
62            <b>android:actionProviderClass=
63                "android.widget.ShareActionProvider"</b> /&gt;
64    ...
65&lt;/menu&gt;
66</pre>
67
68<p>
69    This delegates responsibility for the item's appearance and function to
70    {@link android.widget.ShareActionProvider}. However, you will need to tell the provider what you
71    would like to share.
72</p>
73
74
75<h2 id="set-share-intent">Set the Share Intent</h2>
76
77<p>
78    In order for {@link android.widget.ShareActionProvider} to function, you must provide it a share
79    intent. This share intent should be the same as described in the
80    <a href="{@docRoot}training/sharing/send.html">Sending Simple Data to Other Apps</a> lesson,
81    with action {@link android.content.Intent#ACTION_SEND} and additional data set via extras
82    like {@link android.content.Intent#EXTRA_TEXT} and {@link android.content.Intent#EXTRA_STREAM}.
83    To assign a share intent, first find the corresponding {@link android.view.MenuItem} while
84    inflating your menu resource in your {@link android.app.Activity} or
85    {@link android.app.Fragment}. Next, call {@link android.view.MenuItem#getActionProvider
86    MenuItem.getActionProvider()} to retrieve an instance of
87    {@link android.widget.ShareActionProvider}. Use
88    {@link android.widget.ShareActionProvider#setShareIntent(android.content.Intent)
89    setShareIntent()} to update the share intent associated with that action item. Here's an
90    example:
91</p>
92
93<pre>
94private ShareActionProvider mShareActionProvider;
95...
96
97&#64;Override
98public boolean onCreateOptionsMenu(Menu menu) {
99    // Inflate menu resource file.
100    getMenuInflater().inflate(R.menu.share_menu, menu);
101
102    // Locate MenuItem with ShareActionProvider
103    MenuItem item = menu.findItem(R.id.menu_item_share);
104
105    // Fetch and store ShareActionProvider
106    mShareActionProvider = (ShareActionProvider) item.getActionProvider();
107
108    // Return true to display menu
109    return true;
110}
111
112// Call to update the share intent
113private void setShareIntent(Intent shareIntent) {
114    if (mShareActionProvider != null) {
115        mShareActionProvider.setShareIntent(shareIntent);
116    }
117}
118</pre>
119
120<p>You may only need to set the share intent once during the creation of your menus, or you may
121want to set it and then update it as the UI changes. For example, when you view photos full screen
122in the Gallery app, the sharing intent changes as you flip between photos.</p>
123
124<p>For further discussion about the {@link android.widget.ShareActionProvider} object, see the <a
125href="{@docRoot}guide/topics/ui/actionbar.html#ActionProvider">Action Bar</a> guide.</p>
126
127
128