Skip to content

Commit 70645e3

Browse files
scottamainscottamain
committed
Docs: Add class for Sharing Content
Change-Id: I078a02d952e652c16f84e1b3f7613f3dc9364c97
1 parent fc279e5 commit 70645e3

File tree

5 files changed

+504
-0
lines changed

5 files changed

+504
-0
lines changed

‎docs/html/images/training/sharing/share-text-screenshot.png‎

32.4 KB
Loading

‎docs/html/training/sharing/index.jd‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
page.title=Sharing Content
2+
3+
trainingnavtop=true
4+
startpage=true
5+
next.title=Sending Content to Other Apps
6+
next.link=send.html
7+
8+
@jd:body
9+
10+
<div id="tb-wrapper">
11+
<div id="tb">
12+
13+
<!-- Required platform, tools, add-ons, devices, knowledge, etc. -->
14+
<h2>Dependencies and prerequisites</h2>
15+
<ul>
16+
<li>Android 1.0 or higher (greater requirements where noted)</li>
17+
<li>Experience with <a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and
18+
Intent Filters</a></li>
19+
</ul>
20+
21+
</div>
22+
</div>
23+
24+
25+
<p>One of the great things about Android applications is their ability to communicate and
26+
integrate with each other. Why reinvent functionality that isn't core to your application when it
27+
already exists in another application?</p>
28+
29+
<p>This class shows some common ways you can send and receive content between
30+
applications using {@link android.content.Intent} APIs and the {@link
31+
android.view.ActionProvider}.</p>
32+
33+
34+
<h2>Lessons</h2>
35+
36+
<dl>
37+
<dt><b><a href="send.html">Sending Content to Other Apps</a></b></dt>
38+
<dd>Learn how to set up your application to be able to send text and binary data to other
39+
applications with intents.</dd>
40+
41+
<dt><b><a href="receive.html">Receiving Content from Other Apps</a></b></dt>
42+
<dd>Learn how to set up your application to receive text and binary data from intents.</dd>
43+
44+
<dt><b><a href="shareaction.html">Adding an Easy Share Action</a></b></dt>
45+
<dd>Learn how to add a "share" action item to your action bar.</dd>
46+
</dl>

‎docs/html/training/sharing/receive.jd‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
page.title=Receiving Content from Other Apps
2+
parent.title=Sharing Content
3+
parent.link=index.html
4+
5+
trainingnavtop=true
6+
previous.title=Sending Content to Other Apps
7+
previous.link=send.html
8+
next.title=Adding an Easy Share Action
9+
next.link=shareaction.html
10+
11+
@jd:body
12+
13+
<div id="tb-wrapper">
14+
<div id="tb">
15+
16+
<!-- table of contents -->
17+
<h2>This lesson teaches you to</h2>
18+
<ol>
19+
<li><a href="#update-manifest">Update Your Manifest</a></li>
20+
<li><a href="#handling-content">Handle the Incoming Content</a></li>
21+
</ol>
22+
23+
<!-- other docs (NOT javadocs) -->
24+
<h2>You should also read</h2>
25+
<ul>
26+
<li><a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and
27+
Intent Filters</a></li>
28+
</ul>
29+
30+
</div>
31+
</div>
32+
33+
<p>Just as your application can send data to other applications, so too can it easily receive data
34+
from applications. Think about how users interact with your application, and what data types you
35+
want to receive from other applications. For example, a social networking application would likely
36+
be interested in receiving text content, like an interesting web URL, from another app. The
37+
<a href="https://market.android.com/details?id=com.google.android.apps.plus">Google+ Android
38+
application</a>
39+
accepts both text <em>and</em> single or multiple images. With this app, a user can easily start a
40+
new Google+ post with photos from the Android Gallery app.</p>
41+
42+
43+
<h2 id="update-manifest">Update Your Manifest</h2>
44+
45+
<p>Intent filters inform the system what intents an application component is willing to accept.
46+
Just as you constructed an intent with action {@link android.content.Intent#ACTION_SEND} in the
47+
<a href="{@docRoot}training/sharing/send.html">Send Content to Other Apps Using Intents</a>
48+
lesson, you create intent filters in order to be able to receive intents with this action. You
49+
define an intent filter in your manifest, using the
50+
<code><a
51+
href="{@docRoot}guide/topics/intents/intents-filters.html#ifs">&lt;intent-filter&gt;</a></code>
52+
element. For example, if your application handles receiving text content, a single image of any
53+
type, or multiple images of any type, your manifest would look like:</p>
54+
55+
<pre>
56+
&lt;activity android:name=&quot;.ui.MyActivity&quot; &gt;
57+
&lt;intent-filter&gt;
58+
&lt;action android:name=&quot;android.intent.action.SEND&quot; /&gt;
59+
&lt;category android:name=&quot;android.intent.category.DEFAULT&quot; /&gt;
60+
&lt;data android:mimeType=&quot;image/*&quot; /&gt;
61+
&lt;/intent-filter&gt;
62+
&lt;intent-filter&gt;
63+
&lt;action android:name=&quot;android.intent.action.SEND&quot; /&gt;
64+
&lt;category android:name=&quot;android.intent.category.DEFAULT&quot; /&gt;
65+
&lt;data android:mimeType=&quot;text/plain&quot; /&gt;
66+
&lt;/intent-filter&gt;
67+
&lt;intent-filter&gt;
68+
&lt;action android:name=&quot;android.intent.action.SEND_MULTIPLE&quot; /&gt;
69+
&lt;category android:name=&quot;android.intent.category.DEFAULT&quot; /&gt;
70+
&lt;data android:mimeType=&quot;image/*&quot; /&gt;
71+
&lt;/intent-filter&gt;
72+
&lt;/activity&gt;
73+
</pre>
74+
75+
<p class="note"><strong>Note:</strong> For more information on intent filters and intent resolution
76+
please read <a href="{@docRoot}guide/topics/intents/intents-filters.html#ifs">Intents and Intent
77+
Filters</a></p>
78+
79+
<p>When another application tries to share any of these things by constructing an intent and passing
80+
it to {@link android.content.Context#startActivity(android.content.Intent) startActivity()}, your
81+
application will be listed as an option in the intent chooser (see figure 1). If the user selects
82+
your application, the corresponding activity (<code>.ui.MyActivity</code> in the example above) will
83+
be started. It is then up to you to handle the content appropriately within your code and UI.</p>
84+
85+
86+
<h2 id="handling-content">Handle the Incoming Content</h2>
87+
88+
<p>To handle the content delivered by an {@link android.content.Intent}, start by calling {@link
89+
android.content.Intent#getIntent(String) getIntent()}
90+
to get {@link android.content.Intent} object. Once you have the object, you can examine its
91+
contents to determine what to do next. Keep in mind that if this activity can be started from other
92+
parts of the system, such as the launcher, then you will need to take this into consideration when
93+
examining the intent.</p>
94+
95+
<pre>
96+
void onCreate (Bundle savedInstanceState) {
97+
...
98+
// Get intent, action and MIME type
99+
Intent intent = getIntent();
100+
String action = intent.getAction();
101+
String type = intent.getType();
102+
103+
if (Intent.ACTION_SEND.equals(action) &amp;&amp; type != null) {
104+
if (&quot;text/plain&quot;.equals(type)) {
105+
handleSendText(intent); // Handle text being sent
106+
} else if (type.startsWith(&quot;image/&quot;)) {
107+
handleSendImage(intent); // Handle single image being sent
108+
}
109+
} else if (Intent.ACTION_SEND_MULTIPLE.equals(action) &amp;&amp; type != null) {
110+
if (type.startsWith(&quot;image/&quot;)) {
111+
handleSendMultipleImages(intent); // Handle multiple images being sent
112+
}
113+
} else {
114+
// Handle other intents, such as being started from the home screen
115+
}
116+
...
117+
}
118+
119+
void handleSendText(Intent intent) {
120+
String sharedText = intent.getStringExtra(Intent.EXTRA_TEXT);
121+
if (sharedText != null) {
122+
// Update UI to reflect text being shared
123+
}
124+
}
125+
126+
void handleSendImage(Intent intent) {
127+
Uri imageUri = (Uri) intent.getParcelableExtra(Intent.EXTRA_STREAM);
128+
if (imageUri != null) {
129+
// Update UI to reflect image being shared
130+
}
131+
}
132+
133+
void handleSendMultipleImages(Intent intent) {
134+
ArrayList&lt;Uri&gt; imageUris = intent.getParcelableArrayListExtra(Intent.EXTRA_STREAM);
135+
if (imageUris != null) {
136+
// Update UI to reflect multiple images being shared
137+
}
138+
}
139+
</pre>
140+
141+
<p class="caution"><strong>Caution:</strong> Take extra care to check the incoming data, you never
142+
know what some other application may send you. For example, the wrong MIME type might be set, or the
143+
image being sent might be extremely large. Also, remember to process binary data in a separate
144+
thread rather than the main ("UI") thread.</p>
145+
146+
<p>Updating the UI can be as simple as populating an {@link android.widget.EditText}, or it can
147+
be more complicated like applying an interesting photo filter to an image. It's really specific
148+
to your application what happens next.</p>
149+

‎docs/html/training/sharing/send.jd‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
page.title=Sending Content to Other Apps
2+
parent.title=Sharing Content
3+
parent.link=index.html
4+
5+
trainingnavtop=true
6+
next.title=Receiving Content from Other Apps
7+
next.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="#send-text-content">Send Text Content</a></li>
18+
<li><a href="#send-binary-content">Send Binary Content</a></li>
19+
<li><a href="#send-multiple-content">Send Multiple Pieces of Content</a></li>
20+
</ol>
21+
22+
<!-- other docs (NOT javadocs) -->
23+
<h2>You should also read</h2>
24+
<ul>
25+
<li><a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and
26+
Intent Filters</a></li>
27+
</ul>
28+
29+
</div>
30+
</div>
31+
32+
<p>When you construct an intent, you must specify the action you want the intent to "trigger."
33+
Android defines several actions, including {@link android.content.Intent#ACTION_SEND} which, as
34+
you can probably guess, indicates that the intent is sending data from one activity to another,
35+
even across process boundaries. To send data to another activity, all you need to do is speicify
36+
the data and its type, the system will identify compatible receiving activities and display them
37+
to the user (if there are multiple options) or immediately start the activity (if there is only
38+
one option). Similarly, you can advertise the data types that your activities support receiving
39+
from other applications by specifying them in your manifest.</p>
40+
41+
<p>Sending and receiving data between applications with intents is most commonly used for social
42+
sharing of content. Intents allow users to share information quickly and easily, using their
43+
favorite social applications.</p>
44+
45+
<p><strong>Note:</strong> The best way to add a share action item to an
46+
{@link android.app.ActionBar} is to use {@link android.widget.ShareActionProvider}, which became
47+
available in API level 14. {@link android.widget.ShareActionProvider} is discussed in the lesson
48+
about <a href="shareaction.html">Adding an Easy Share Action</a>.</p>
49+
50+
51+
<h2 id="send-text-content">Send Text Content</h2>
52+
53+
<div class="figure" style="width:220px">
54+
<img src="{@docRoot}images/training/sharing/share-text-screenshot.png" alt="" id="figure1" />
55+
<p class="img-caption">
56+
<strong>Figure 1.</strong> Screenshot of {@link android.content.Intent#ACTION_SEND} intent chooser
57+
on a handset.
58+
</p>
59+
</div>
60+
61+
<p>The most straightforward and common use of the {@link android.content.Intent#ACTION_SEND}
62+
action is sending text content from one activity to another. For example, the built-in Browser
63+
app can share the URL of the currently-displayed page as text with any application. This is useful
64+
for sharing an article or website with friends via email or social networking. Here is the code to
65+
implement this type of sharing:</p>
66+
67+
<pre>
68+
Intent sendIntent = new Intent();
69+
sendIntent.setAction(Intent.ACTION_SEND);
70+
sendIntent.putExtra(Intent.EXTRA_TEXT, &quot;This is my text to send.&quot;);
71+
sendIntent.setType(&quot;text/plain&quot;);
72+
startActivity(sendIntent);
73+
</pre>
74+
75+
<p>If there's an installed application with a filter that matches
76+
{@link android.content.Intent#ACTION_SEND} and MIME type text/plain, the Android system will run
77+
it; if more than one application matches, the system displays a disambiguation dialog (a "chooser")
78+
that allows the user to choose an app. If you call
79+
{@link android.content.Intent#createChooser(android.content.Intent, CharSequence)
80+
Intent.createChooser()}
81+
for the intent, Android will <strong>always</strong> display the chooser. This has some
82+
advantages:</p>
83+
84+
<ul>
85+
<li>Even if the user has previously selected a default action for this intent, the chooser will
86+
still be displayed.</li>
87+
<li>If no applications match, Android displays a system message.</li>
88+
<li>You can specify a title for the chooser dialog.</li>
89+
</ul>
90+
91+
<p>Here's the updated code:</p>
92+
93+
<pre>
94+
Intent sendIntent = new Intent();
95+
sendIntent.setAction(Intent.ACTION_SEND);
96+
sendIntent.putExtra(Intent.EXTRA_TEXT, &quot;This is my text to send.&quot;);
97+
sendIntent.setType(&quot;text/plain&quot;);
98+
startActivity(<strong>Intent.createChooser(sendIntent, getResources().getText(R.string.send_to)</strong>);
99+
</pre>
100+
101+
<p>The resulting dialog is shown in figure 1.</p>
102+
103+
<p>Optionally, you can set some standard extras for the intent:
104+
{@link android.content.Intent#EXTRA_EMAIL}, {@link android.content.Intent#EXTRA_CC},
105+
{@link android.content.Intent#EXTRA_BCC}, {@link android.content.Intent#EXTRA_SUBJECT}. However,
106+
if the receiving application is not designed to use them, nothing will happen. You can use
107+
custom extras as well, but there's no effect unless the receiving application understands them.
108+
Typically, you'd use custom extras defined by the receiving application itself.</p>
109+
110+
<p class="note"><strong>Note:</strong> Some e-mail applications, such as Gmail, expect a
111+
{@link java.lang.String String[]} for extras like {@link android.content.Intent#EXTRA_EMAIL} and
112+
{@link android.content.Intent#EXTRA_CC}, use
113+
{@link android.content.Intent#putExtra(String,String[]) putExtra(String, String[])} to add these
114+
to your intent.</p>
115+
116+
117+
<h2 id="send-binary-content">Send Binary Content</h2>
118+
119+
<p>Binary data is shared using the {@link android.content.Intent#ACTION_SEND} action combined with
120+
setting the appropriate MIME type and placing the URI to the data in an extra named {@link
121+
android.content.Intent#EXTRA_STREAM}. This is commonly used to share an image but can be used to
122+
share any type of binary content:</p>
123+
124+
<pre>
125+
Intent shareIntent = new Intent();
126+
shareIntent.setAction(Intent.ACTION_SEND);
127+
shareIntent.putExtra(Intent.EXTRA_STREAM, uriToImage);
128+
shareIntent.setType(&quot;image/jpeg&quot;);
129+
startActivity(Intent.createChooser(shareIntent, getResources().getText(R.string.send_to)));
130+
</pre>
131+
132+
<p>Note the following:</p>
133+
<ul>
134+
<li>You can use a MIME type of {@code "*/*"}, but this will only match activities that are able to
135+
handle generic data streams.</li>
136+
<li>The receiving application needs permission to access the data the {@link android.net.Uri}
137+
points to. There are a number of ways to handle this:
138+
<ul>
139+
<li>Write the data to a file on external/shared storage (such as the SD card), which all apps
140+
can read. Use {@link android.net.Uri#fromFile(java.io.File) Uri.fromFile()} to create the
141+
{@link android.net.Uri} that can be passed to the share intent. However, keep in mind that not
142+
all applications process a {@code file://} style {@link android.net.Uri}.</li>
143+
<li>Write the data to a file in your own application directory using {@link
144+
android.content.Context#openFileOutput(java.lang.String, int) openFileOutput()} with mode {@link
145+
android.content.Context#MODE_WORLD_READABLE} after which {@link
146+
android.content.Context#getFileStreamPath(java.lang.String) getFileStreamPath()} can be used to
147+
return a {@link java.io.File}. As with the previous option, {@link
148+
android.net.Uri#fromFile(java.io.File) Uri.fromFile()} will create a {@code file://} style {@link
149+
android.net.Uri} for your share intent.</li>
150+
<li>Media files like images, videos and audio can be scanned and added to the system {@link
151+
android.provider.MediaStore} using {@link
152+
android.media.MediaScannerConnection#scanFile(android.content.Context, java.lang.String[],
153+
java.lang.String[], android.media.MediaScannerConnection.OnScanCompletedListener) scanFile()}. The
154+
{@link
155+
android.media.MediaScannerConnection.OnScanCompletedListener#onScanCompleted(java.lang.String,
156+
android.net.Uri) onScanCompleted()} callback returns a {@code content://} style {@link
157+
android.net.Uri} suitable for including in your share intent.</li>
158+
<li>Images can be inserted into the system {@link android.provider.MediaStore} using {@link
159+
android.provider.MediaStore.Images.Media#insertImage(android.content.ContentResolver,
160+
android.graphics.Bitmap, java.lang.String, java.lang.String) insertImage()} which will return a
161+
{@code content://} style {@link android.net.Uri} suitable for including in a share intent.</li>
162+
<li>Store the data in your own {@link android.content.ContentProvider}, make sure that other
163+
apps have the correct permission to access your provider (or use <a
164+
href="{@docRoot}guide/topics/security/security.html#uri">per-URI permissions</a>).</li>
165+
</ul>
166+
</li>
167+
</ul>
168+
169+
170+
<h2 id="send-multiple-content">Send Multiple Pieces of Content</h2>
171+
172+
<p>To share multiple pieces of content, use the {@link android.content.Intent#ACTION_SEND_MULTIPLE}
173+
action together with a list of URIs pointing to the content. The MIME type varies according to the
174+
mix of content you're sharing. For example, if you share 3 JPEG images, the type is still {@code
175+
"image/jpeg"}. For a mixture of image types, it should be {@code "image/*"} to match an activity
176+
that handles any type of image. You should only use {@code "*/*"} if you're sharing out a wide
177+
variety of types. As previously stated, it's up to the receiving application to parse and process
178+
your data. Here's an example:</p>
179+
180+
<pre>
181+
ArrayList&lt;Uri&gt; imageUris = new ArrayList&lt;Uri&gt;();
182+
imageUris.add(imageUri1); // Add your image URIs here
183+
imageUris.add(imageUri2);
184+
185+
Intent shareIntent = new Intent();
186+
shareIntent.setAction(Intent.ACTION_SEND_MULTIPLE);
187+
shareIntent.putParcelableArrayListExtra(Intent.EXTRA_STREAM, imageUris);
188+
shareIntent.setType(&quot;image/*&quot;);
189+
startActivity(Intent.createChooser(shareIntent, &quot;Share images to..&quot;));
190+
</pre>
191+
192+
<p>As before, make sure the provided {@link android.net.Uri URIs} point to data that a receiving
193+
application can access.</p>
194+

0 commit comments

Comments
 (0)