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