1page.title=Obtendo resultados de uma atividade
2page.tags=intenções
3helpoutsWidget=true
4
5trainingnavtop=true
6
7@jd:body
8
9<div id="tb-wrapper">
10  <div id="tb">
11
12<h2>Esta lição ensina a</h2>
13<ol>
14  <li><a href="#StartActivity">Iniciar a atividade</a></li>
15  <li><a href="#ReceiveResult">Receber o resultado</a></li>
16</ol>
17
18<h2>Leia também</h2>
19<ul>
20    <li><a href="{@docRoot}training/sharing/index.html">Compartilhando dados simples</a></li>
21    <li><a href="{@docRoot}training/secure-file-sharing/index.html">Compartilhando arquivos</a>
22</ul>
23
24  </div>
25</div>
26
27<p>Iniciar outra atividade não precisa ser a única forma. Pode-se também iniciar outra atividade e
28receber um resultado de volta. Para receber um resultado, chame {@link android.app.Activity#startActivityForResult
29startActivityForResult()} (em vez de {@link android.app.Activity#startActivity
30startActivity()}).</p>
31
32<p>Por exemplo, o aplicativo pode iniciar um aplicativo de câmera e receber a foto capturada como resultado. Ou,
33ao iniciar o aplicativo Pessoas para que o usuário selecione um
34contato, você receberá os detalhes do contato como resultado.</p>
35
36<p>Evidentemente a atividade que responde deve ser projetada para retornar um resultado. Quando isso acontecer, ela
37enviará o resultado para outro objeto {@link android.content.Intent}. A atividade recebe o resultado no
38retorno de chamada {@link android.app.Activity#onActivityResult onActivityResult()}.</p>
39
40<p class="note"><strong>Observação:</strong> pode-se usar intenções explícitas ou implícitas ao chamar
41{@link android.app.Activity#startActivityForResult startActivityForResult()}. Ao iniciar uma de
42suas próprias atividades que recebem um resultado, use uma intenção explícita para garantir que o
43resultado esperado será recebido.</p>
44
45
46<h2 id="StartActivity">Iniciar a atividade</h2>
47
48<p>Não há nada especial no objeto {@link android.content.Intent} utilizado para iniciar
49uma atividade para um resultado, mas é preciso transmitir um argumento de número inteiro adicional ao método {@link
50android.app.Activity#startActivityForResult startActivityForResult()}.</p>
51
52<p>O argumento de número inteiro é um “código de pedido” que identifica o pedido. Quando você recebe o
53resultado {@link android.content.Intent}, o retorno de chamada fornece o mesmo código de pedido para que o
54aplicativo possa identificar adequadamente o resultado e determinar como responder a ele.</p>
55
56<p>Essa é uma forma de iniciar uma atividade que permite ao usuário escolher um contato:</p>
57
58<pre>
59static final int PICK_CONTACT_REQUEST = 1;  // The request code
60...
61private void pickContact() {
62    Intent pickContactIntent = new Intent(Intent.ACTION_PICK, Uri.parse("content://contacts"));
63    pickContactIntent.setType(Phone.CONTENT_TYPE); // Show user only contacts w/ phone numbers
64    startActivityForResult(pickContactIntent, PICK_CONTACT_REQUEST);
65}
66</pre>
67
68
69<h2 id="ReceiveResult">Receber o resultado</h2>
70
71<p>Quando o usuário termina a atividade subsequente e retorna, o sistema chama o método
72{@link android.app.Activity#onActivityResult onActivityResult()} da atividade. Esse método inclui três
73argumentos:</p>
74
75<ul>
76  <li>O código de pedido passado para {@link
77android.app.Activity#startActivityForResult startActivityForResult()}.</li>
78  <li>Um código de resultado especificado pela segunda atividade. Se a operação for bem sucedida, será {@link
79android.app.Activity#RESULT_OK} ou {@link
80android.app.Activity#RESULT_CANCELED} se o usuário tiver desistido ou a operação tiver falhado por algum
81motivo.</li>
82  <li>Um {@link android.content.Intent} que transporta os dados do resultado.</li>
83</ul>
84
85<p>Esta é uma forma de responder ao resultado para a intenção “escolher um contato”:</p>
86
87<pre>
88&#64;Override
89protected void onActivityResult(int requestCode, int resultCode, Intent data) {
90    // Check which request we're responding to
91    if (requestCode == PICK_CONTACT_REQUEST) {
92        // Make sure the request was successful
93        if (resultCode == RESULT_OK) {
94            // The user picked a contact.
95            // The Intent's data Uri identifies which contact was selected.
96
97            // Do something with the contact here (bigger example below)
98        }
99    }
100}
101</pre>
102
103<p>Nesse exemplo, o resultado {@link android.content.Intent} retornado pelos
104aplicativos Contatos ou Pessoas do Android fornece um conteúdo {@link android.net.Uri} que identifica o
105contato escolhido pelo usuário.</p>
106
107<p>Para que o resultado seja tratado de forma adequada, é preciso saber o formato do resultado
108{@link android.content.Intent}. Isso é fácil quando umas das suas atividades
109retorna o resultado. Os aplicativos incluídos na plataforma Android oferecem suas próprias APIs que
110podem ser usadas para dados de resultado específicos. Por exemplo, o aplicativo Pessoas (Contatos em algumas versões mais
111antigas) sempre retorna um resultado com URI de conteúdo que identifica o contato escolhido e o aplicativo
112Câmera retorna um {@link android.graphics.Bitmap} no {@code "data"} extra (consulte a lição
113<a href="{@docRoot}training/camera/index.html">Capturando fotografias</a>).</p>
114
115
116<h4>Bônus: Ler os dados do contato</h4>
117
118<p>O código acima que mostra como obter um resultado pelo aplicativo Pessoas não
119traz muitos detalhes sobre como exatamente ler os dados do resultado porque exige uma discussão mais avançada
120sobre <a href="{@docRoot}guide/topics/providers/content-providers.html">provedores
121de conteúdo</a>. No entanto, se você desejar saber mais, aqui estão alguns códigos que mostram como consultar os
122dados de resultado para obter o número de telefone do contato selecionado:</p>
123
124<pre>
125&#64;Override
126protected void onActivityResult(int requestCode, int resultCode, Intent data) {
127    // Check which request it is that we're responding to
128    if (requestCode == PICK_CONTACT_REQUEST) {
129        // Make sure the request was successful
130        if (resultCode == RESULT_OK) {
131            // Get the URI that points to the selected contact
132            Uri contactUri = data.getData();
133            // We only need the NUMBER column, because there will be only one row in the result
134            String[] projection = {Phone.NUMBER};
135
136            // Perform the query on the contact to get the NUMBER column
137            // We don't need a selection or sort order (there's only one result for the given URI)
138            // CAUTION: The query() method should be called from a separate thread to avoid blocking
139            // your app's UI thread. (For simplicity of the sample, this code doesn't do that.)
140            // Consider using {@link android.content.CursorLoader} to perform the query.
141            Cursor cursor = getContentResolver()
142                    .query(contactUri, projection, null, null, null);
143            cursor.moveToFirst();
144
145            // Retrieve the phone number from the NUMBER column
146            int column = cursor.getColumnIndex(Phone.NUMBER);
147            String number = cursor.getString(column);
148
149            // Do something with the phone number...
150        }
151    }
152}
153</pre>
154
155<p class="note"><strong>Observação:</strong> antes do Android 2.3 (API nível 9), executar uma consulta
156no {@link android.provider.ContactsContract.Contacts Contacts Provider} (como mostrado
157acima) exige que o aplicativo declare a permissão {@link
158android.Manifest.permission#READ_CONTACTS} (consulte <a href="{@docRoot}guide/topics/security/security.html">Segurança e permissões</a>). Contudo,
159iniciar com Android 2.3, o aplicativo Contatos/Pessoas dá ao aplicativo permissão
160temporária para ler no Provedor de Contatos quando retornar um resultado. A permissão temporária
161aplica-se apenas a pedidos de contato específicos, portanto, não é possível consultar um contato diferente daquele
162especificado pelo {@link android.net.Uri} da intenção, a menos que você declare a permissão {@link
163android.Manifest.permission#READ_CONTACTS}.</p>
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179