Home | History | Annotate | Download | only in sharing 
      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 Simple Data 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}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}
     33 is 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
     35 bar, handles both the appearance and behavior of that item. In the case of {@link
     36 android.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
     39 starting 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">;
     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>
     95 private ShareActionProvider mShareActionProvider;
     96 ...
     97 
     98 &#64;Override
     99 public 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
    114 private 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
    122 want to set it and then update it as the UI changes. For example, when you view photos full screen
    123 in 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}
    126 object, see <a href="{@docRoot}training/appbar/action-views.html">Action Views
    127 and Action Providers</a>.</p>
    128 
    129 
    130