Scott Main | 70645e3 | 2011-12-13 16:06:16 -0800 | [diff] [blame] | 1 | page.title=Adding an Easy Share Action |
| 2 | parent.title=Sharing Content |
| 3 | parent.link=index.html |
| 4 | |
| 5 | trainingnavtop=true |
| 6 | previous.title=Receiving Content from Other Apps |
| 7 | previous.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} |
| 32 | is 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 |
| 34 | bar, handles both the appearance and behavior of that item. In the case of {@link |
| 35 | android.widget.ShareActionProvider}, you provide a share intent and it does the rest.</p> |
| 36 | |
| 37 | <p class="note"><strong>Note: </strong> {@link android.widget.ShareActionProvider} is available |
| 38 | starting 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>To get started with {@link android.widget.ShareActionProvider ShareActionProviders}, define the <code>android:actionProviderClass</code> attribute for the corresponding <code><item></code> in your <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> file:</p> |
| 51 | |
| 52 | <pre> |
| 53 | <menu xmlns:android="http://schemas.android.com/apk/res/android"> |
| 54 | <item android:id="@+id/menu_item_share" |
| 55 | android:showAsAction="ifRoom" |
| 56 | android:title="Share" |
| 57 | <strong>android:actionProviderClass="android.widget.ShareActionProvider"</strong> /> |
| 58 | ... |
| 59 | </menu> |
| 60 | </pre> |
| 61 | |
| 62 | <p>This delegates responsibility for the item's appearance and function to |
| 63 | {@link android.widget.ShareActionProvider}. However, you will need to tell the provider what you |
| 64 | would like to share.</p> |
| 65 | |
| 66 | |
| 67 | <h2 id="set-share-intent">Set the Share Intent</h2> |
| 68 | |
| 69 | <p>In order for {@link android.widget.ShareActionProvider} to function, you must provide it a share |
| 70 | intent. This share intent should be the same as described in the <a |
| 71 | href="{@docRoot}training/sharing/send.html">Sending Content to Other Apps</a> |
| 72 | lesson, with action {@link android.content.Intent#ACTION_SEND} and additional data set via extras |
| 73 | like {@link android.content.Intent#EXTRA_TEXT} and {@link android.content.Intent#EXTRA_STREAM}. To |
| 74 | assign a share intent, first find the corresponding {@link android.view.MenuItem} while inflating |
| 75 | your menu resource in your {@link android.app.Activity} or {@link android.app.Fragment}. Next, call |
| 76 | {@link android.view.MenuItem#getActionProvider() MenuItem.getActionProvider()} to retreive an |
| 77 | instance of {@link android.widget.ShareActionProvider}. Use {@link |
| 78 | android.widget.ShareActionProvider#setShareIntent(android.content.Intent) setShareIntent()} to |
| 79 | update the share intent associated with that action item. Here's an example:</p> |
| 80 | |
| 81 | <pre> |
| 82 | private ShareActionProvider mShareActionProvider; |
| 83 | ... |
| 84 | |
| 85 | @Override |
| 86 | public boolean onCreateOptionsMenu(Menu menu) { |
| 87 | // Inflate menu resource file. |
| 88 | getMenuInflater().inflate(R.menu.share_menu, menu); |
| 89 | |
| 90 | // Locate MenuItem with ShareActionProvider |
| 91 | MenuItem item = menu.findItem(R.id.menu_item_share); |
| 92 | |
| 93 | // Fetch and store ShareActionProvider |
| 94 | mShareActionProvider = (ShareActionProvider) item.getActionProvider(); |
| 95 | |
| 96 | // Return true to display menu |
| 97 | return true; |
| 98 | } |
| 99 | |
| 100 | // Call to update the share intent |
| 101 | private void setShareIntent(Intent shareIntent) { |
| 102 | if (mShareActionProvider != null) { |
| 103 | mShareActionProvider.setShareIntent(shareIntent); |
| 104 | } |
| 105 | } |
| 106 | </pre> |
| 107 | |
| 108 | <p>You may only need to set the share intent once during the creation of your menus, or you may |
| 109 | want to set it and then update it as the UI changes. For example, when you view photos full screen |
| 110 | in the Gallery app, the sharing intent changes as you flip between photos.</p> |
| 111 | |
Adam Koch | 909fe93 | 2011-12-15 15:54:52 -0500 | [diff] [blame] | 112 | <p>For further discussion about the {@link android.widget.ShareActionProvider} object, see the <a |
Scott Main | 70645e3 | 2011-12-13 16:06:16 -0800 | [diff] [blame] | 113 | href="{@docRoot}guide/topics/ui/actionbar.html#ActionProvider">Action Bar</a> guide.</p> |
| 114 | |
| 115 | |