basics/intents/sending.jd

page.title=Enviando o usurio para outro aplicativo
page.tags=intenes
helpoutsWidget=true

trainingnavtop=true

@jd:body


<div id="tb-wrapper">
  <div id="tb">

<h2>Esta lio ensina a</h2>
<ol>
  <li><a href="#Build">Criar uma inteno implcita</a></li>
  <li><a href="#Verify">Confirmar se h um aplicativo para receber a inteno</a></li>
  <li><a href="#StartActivity">Iniciar uma atividade com uma inteno</a></li>
  <li><a href="#AppChooser">Mostrar um selecionador de aplicativo</a></li>
</ol>

<h2>Leia tambm</h2>
<ul>
    <li><a href="{@docRoot}training/sharing/index.html">Compartilhando dados simples</a></li>
</ul>

  </div>
</div>

<p>Uma das caractersticas mais importantes do Android  a habilidade do aplicativo enviar o usurio para outro aplicativo
com base em uma ao que gostaria de executar. Por exemplo, se
o aplicativo tiver o endereo de um negcio que voc gostaria de mostrar em um mapa, no  necessrio criar
uma atividade no aplicativo que mostre um mapa. Em vez disso,  possvel criar uma solicitao para exibir o endereo
usando {@link android.content.Intent}. O sistema Android inicia um aplicativo que possa mostrar
o endereo em um mapa.</p>

<p>Como explicado na primeira lio, <a href="{@docRoot}training/basics/firstapp/index.html">Criando
seu primeiro aplicativo</a>, use intenes para navegar entre atividades no aplicativo. Geralmente
isso  feito com <em>intenes explcitas</em>, que define o nome exato da classe do
componente que deseja iniciar. No entanto, quando desejar que outro aplicativo execute uma ao, como
visualizar um mapa, use uma <em>inteno implcita</em>.</p>

<p>Esta lio mostra como criar uma inteno implcita para uma ao especfica e como utiliz-la
para iniciar uma atividade que executa a ao em outro aplicativo.</p>


<h2 id="Build">Criar uma inteno implcita</h2>

<p>Intenes implcitas no declaram o nome da classe do componente a iniciar, mas declaram uma
ao a executar. A ao especifica o que deve ser feito, como <em>visualizar</em>,
<em>editar</em>, <em>enviar</em> ou <em>obter</em> algo. Geralmente, as intenes incluem dados associados
 ao, como o endereo que deseja visualizar ou a mensagem de email a ser enviada.
Dependendo da inteno que deseja criar, os dados podem ser {@link android.net.Uri},
um dos outros tipos de dados ou a inteno pode no precisar de dado algum.</p>

<p>Se seu dados forem um {@link android.net.Uri}, h um simples construtor {@link
android.content.Intent#Intent(String,Uri) Intent()} que pode ser usado para definir a ao e
os dados.</p>

<p>Este  um exemplo de como criar uma inteno para iniciar uma chamada telefnica usando os dados {@link
android.net.Uri} para especificar o nmero de telefone:</p>

<pre>
Uri number = Uri.parse("tel:5551234");
Intent callIntent = new Intent(Intent.ACTION_DIAL, number);
</pre>

<p>Quando o aplicativo invoca a inteno chamando {@link android.app.Activity#startActivity
startActivity()}, o aplicativo Telefone inicia uma chamada para o nmero especificado.</p>

<p>Estas so algumas outras intenes e suas aes e pares de dados {@link android.net.Uri}
:</p>

<ul>
  <li>Visualizar um mapa:
<pre>
// Map point based on address
Uri location = Uri.parse("geo:0,0?q=1600+Amphitheatre+Parkway,+Mountain+View,+California");
// Or map point based on latitude/longitude
// Uri location = Uri.parse("geo:37.422219,-122.08364?z=14"); // z param is zoom level
Intent mapIntent = new Intent(Intent.ACTION_VIEW, location);
</pre>
  </li>
  <li>Visualizar uma pgina da Web:
<pre>
Uri webpage = Uri.parse("http://www.android.com");
Intent webIntent = new Intent(Intent.ACTION_VIEW, webpage);
</pre>
  </li>
</ul>

<p>Outros tipos de intenes implcitas exigem dados extras que fornecem diferentes tipos de dados,
como uma cadeia de caracteres.  possvel adicionar um ou mais dados extras utilizando vrios mtodos {@link
android.content.Intent#putExtra(String,String) putExtra()}.</p>

<p>Por padro, o sistema determina o tipo MIME adequado que uma inteno exige com base nos dados
{@link android.net.Uri} includos. Se voc no incluir um {@link android.net.Uri} na
inteno, sempre utilize {@link android.content.Intent#setType setType()} para especificar o tipo
de dado associado  inteno. Definir o tipo de MIME especifica melhor que tipos de
atividades recebero a inteno.</p>

<p>Estas so mais algumas intenes que adicionam dados extra para especificar a inteno desejada:</p>

<ul>
  <li>Enviar um email com um anexo:
<pre>
Intent emailIntent = new Intent(Intent.ACTION_SEND);
// The intent does not have a URI, so declare the "text/plain" MIME type
emailIntent.setType(HTTP.PLAIN_TEXT_TYPE);
emailIntent.putExtra(Intent.EXTRA_EMAIL, new String[] {"jon (a] example.com"}); // recipients
emailIntent.putExtra(Intent.EXTRA_SUBJECT, "Email subject");
emailIntent.putExtra(Intent.EXTRA_TEXT, "Email message text");
emailIntent.putExtra(Intent.EXTRA_STREAM, Uri.parse("content://path/to/email/attachment"));
// You can also attach multiple items by passing an ArrayList of Uris
</pre>
  </li>
  <li>Criar um evento de calendrio:
<pre>
Intent calendarIntent = new Intent(Intent.ACTION_INSERT, Events.CONTENT_URI);
Calendar beginTime = Calendar.getInstance().set(2012, 0, 19, 7, 30);
Calendar endTime = Calendar.getInstance().set(2012, 0, 19, 10, 30);
calendarIntent.putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, beginTime.getTimeInMillis());
calendarIntent.putExtra(CalendarContract.EXTRA_EVENT_END_TIME, endTime.getTimeInMillis());
calendarIntent.putExtra(Events.TITLE, "Ninja class");
calendarIntent.putExtra(Events.EVENT_LOCATION, "Secret dojo");
</pre>
<p class="note"><strong>Observao:</strong> esta inteno para evento de calendrio  suportada apenas com nvel de API
14 e superior.</p>
  </li>
</ul>

<p class="note"><strong>Observao:</strong>  importante definir seu {@link
android.content.Intent} para ser o mais especfico possvel. Por exemplo, se voc deseja exibir uma imagem
usando a inteno {@link android.content.Intent#ACTION_VIEW}, especifique o tipo de MIME do
{@code image/*}. Isto evita que aplicativos que podem exibir outros tipos de dados (como um aplicativo de mapas) seja
acionado pela inteno.</p>


<h2 id="Verify">Confirmar se h um aplicativo para receber a inteno</h2>

<p>Embora a plataforma do Android garanta que determinadas intenes sejam resolvidas com um dos
 aplicativos embutidos (como aplicativo de Telefone, Email ou Agenda), sempre inclua uma
etapa de confirmao antes de chamar uma inteno.</p>

<p class="caution"><strong>Cuidado:</strong> se voc invocar uma inteno e no houver aplicativo
disponvel no dispositivo para tratar a inteno, o aplicativo falhar.</p>

<p>Para confirmar se h atividade disponvel para responder  inteno, chame {@link
android.content.pm.PackageManager#queryIntentActivities queryIntentActivities()} para obter uma lista
de atividades que podem tratar a {@link android.content.Intent}. Se o {@link
java.util.List} retornado no estiver vazio, a inteno poder ser usada com segurana. Por exemplo:</p>

<pre>
PackageManager packageManager = {@link android.content.Context#getPackageManager()};
List<ResolveInfo> activities = packageManager.queryIntentActivities(intent,
        PackageManager.MATCH_DEFAULT_ONLY);
boolean isIntentSafe = activities.size() > 0;
</pre>

<p>Se <code>isIntentSafe</code> for <code>true</code>, pelo menos um aplicativo responder
inteno. Se for <code>false</code>, no h aplicativos disponveis para responder  inteno.</p>

<p class="note"><strong>Observao:</strong> faa essa verificao quando a atividade
iniciar, caso seja necessrio desabilitar a funcionalidade que usa a inteno antes do usurio tentar utiliz-
la. Caso conhea um aplicativo especfico que possa lidar com a inteno, fornea um link para que o
usurio baixe o aplicativo (veja como <a href="{@docRoot}distribute/tools/promote/linking.html">vincular para seus produtos no Google
Play</a>).</p>


<h2 id="StartActivity">Iniciar uma atividade com uma inteno</h2>

<div class="figure" style="width:200px;margin-top:-10px">
  <img src="{@docRoot}images/training/basics/intents-choice.png" alt="" />
  <p class="img-caption"><strong>Figura 1.</strong> Exemplo de dilogo de seleo que aparece
quando mais de um aplicativo pode tratar uma inteno.</p>
</div>

<p>Quando tiver criado sua {@link android.content.Intent} e definido as informaes extras, chame {@link
android.app.Activity#startActivity startActivity()} para envi-la ao sistema. Se o sistema
identificar mais de uma atividade que pode tratar a inteno, um dilogo exibir para que o usurio
selecione qual aplicativo usar, como mostrado na figura 1. Se houver apenas uma atividade para tratar a
inteno, o sistema a iniciar imediatamente.</p>

<pre>
startActivity(intent);
</pre>

<p>Este  um exemplo completo que mostra como criar uma inteno para exibir um mapa, confirmar se h
um aplicativo para tratar a inteno e iniciar:</p>

<pre>
// Build the intent
Uri location = Uri.parse("geo:0,0?q=1600+Amphitheatre+Parkway,+Mountain+View,+California");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, location);

// Verify it resolves
PackageManager packageManager = {@link android.content.Context#getPackageManager()};
List&lt;ResolveInfo> activities = packageManager.queryIntentActivities(mapIntent, 0);
boolean isIntentSafe = activities.size() > 0;

// Start an activity if it's safe
if (isIntentSafe) {
    startActivity(mapIntent);
}
</pre>


<h2 id="AppChooser">Mostrar um selecionador de aplicativo</h2>

<div class="figure" style="width:200px;margin-top:-10px">
  <img src="{@docRoot}images/training/basics/intent-chooser.png" alt="" />
  <p class="img-caption"><strong>Figura 2.</strong> Um dilogo seletor.</p>
</div>

<p>Observe que ao iniciar uma atividade passando seu {@link android.content.Intent} para {@link
android.app.Activity#startActivity startActivity()} e quando h mais de um aplicativo que responde
inteno, o usurio pode selecionar qual aplicativo usar por padro (marcando uma caixa de seleo na parte inferior
do dilogo, veja a figura 1). Isto  bom quando se executa uma ao para qual o usurio
deseja usar o mesmo aplicativo todas as vezes, como quando abre uma pgina da Web (o usurio
geralmente usa apenas um navegador) ou para tirar fotos (o usurio prefere uma cmera).</p>

<p>Contudo, se a ao a ser executada puder ser tratada por vrios aplicativos e o usurio
preferir um aplicativo diferente a cada vez, como a ao compartilhar onde os usurios podem ter vrios
aplicativos para compartilhar um item, voc deve exibir explicitamente um dilogo seletor
conforme mostrado na figura 2. O dilogo seletor
fora o usurio a selecionar qual aplicativo usar para a ao todas as vezes (o usurio no pode selecionar
um aplicativo padro para a ao).</p>

<p>Para exibir o seletor, crie uma {@link android.content.Intent} usando {@link
android.content.Intent#createChooser createChooser()} e transmita para {@link
android.app.Activity#startActivity startActivity()}. Por exemplo:</p>

<pre>
Intent intent = new Intent(Intent.ACTION_SEND);
...

// Always use string resources for UI text.
// This says something like "Share this photo with"
String title = getResources().getString(R.string.chooser_title);
// Create intent to show chooser
Intent chooser = Intent.createChooser(intent, title);

// Verify the intent will resolve to at least one activity
if (intent.resolveActivity(getPackageManager()) != null) {
    startActivity(chooser);
}
</pre>

<p>Isso exibe um dilogo com uma lista de aplicativos que respondem  inteno transmitida ao mtodo {@link
android.content.Intent#createChooser createChooser()} e utiliza o texto fornecido como
ttulo do dilogo.</p>