1 page.title=Menus 2 parent.title=Interface do usurio 3 parent.link=index.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>Neste documento</h2> 9 <ol> 10 <li><a href="#xml">Definio de um menu em XML</a></li> 11 <li><a href="#options-menu">Criao de um menu de opes</a> 12 <ol> 13 <li><a href="#RespondingOptionsMenu">Tratamento de eventos de clique</a></li> 14 <li><a href="#ChangingTheMenu">Alterao de itens de menu em tempo de execuo</a></li> 15 </ol> 16 </li> 17 <li><a href="#context-menu">Criao de menus contextuais</a> 18 <ol> 19 <li><a href="#FloatingContextMenu">Criao de um menu de contexto flutuante</a></li> 20 <li><a href="#CAB">Uso do modo de ao contextual</a></li> 21 </ol> 22 </li> 23 <li><a href="#PopupMenu">Criao de um menu pop-up</a> 24 <ol> 25 <li><a href="#PopupEvents">Tratamento de eventos de clique</a></li> 26 </ol> 27 </li> 28 <li><a href="#groups">Criao de grupos de menu</a> 29 <ol> 30 <li><a href="#checkable">Uso de itens de menu marcveis</a></li> 31 </ol> 32 </li> 33 <li><a href="#intents">Adio de itens de menu com base em uma inteno</a> 34 <ol> 35 <li><a href="#AllowingToAdd">Permisso para a atividade ser adicionada a outros menus</a></li> 36 </ol> 37 </li> 38 </ol> 39 40 <h2>Classes principais</h2> 41 <ol> 42 <li>{@link android.view.Menu}</li> 43 <li>{@link android.view.MenuItem}</li> 44 <li>{@link android.view.ContextMenu}</li> 45 <li>{@link android.view.ActionMode}</li> 46 </ol> 47 48 <h2>Veja tambm</h2> 49 <ol> 50 <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Barra de ao</a></li> 51 <li><a href="{@docRoot}guide/topics/resources/menu-resource.html">Recurso de menu</a></li> 52 <li><a href="http://android-developers.blogspot.com/2012/01/say-goodbye-to-menu-button.html">Diga 53 adeus ao boto de menu</a></li> 54 </ol> 55 </div> 56 </div> 57 58 <p>Menus so componentes comuns da interface do usurio em diversos tipos de aplicativos. Para fornecer uma experincia 59 familiar e consistente ao usurio, voc deve usar APIs de {@link android.view.Menu} para apresentar 60 aes de usurio e outras opes em suas atividades.</p> 61 62 <p>Comeando com Android 3.0 (API de nvel 11), dispositivos Android no so mais necessrios 63 para fornecer um boto de <em>Menu</em> dedicado. Com esta alterao, os aplicativos do Android devem migrar de uma dependncia 64 no painel de menu 6 itens tradicional para fornecer uma barra de ao para apresentar as aes comuns 65 de usurio.</p> 66 67 <p>Apesar de o design e a experincia do usurio para alguns dos itens do menu terem passado por mudanas, a semntica para definir 68 um conjunto de aes e opes ainda baseia-se em APIs de {@link android.view.Menu} . Este guia 69 mostra como criar os trs tipos fundamentais de menus ou apresentaes de ao 70 em todas as verses do Android:</p> 71 72 <dl> 73 <dt><strong>Menu de opes e barra de ao</strong></dt> 74 <dd>O <a href="#options-menu">menu de opes</a> a coleo principal de itens de menu 75 para uma atividade. onde deve-se colocar as aes que tm impacto global no aplicativo, 76 como "Buscar", "Escrever e-mail" e "Configuraes". 77 <p>Se estiver desenvolvendo para Android 2.3 ou anterior, os usurios 78 podem revelar o painel do menu de opes pressionando o boto <em>Menu</em>.</p> 79 <p>No Android 3.0 ou em posteriores, os itens do menu de opesso apresentados pela <a href="{@docRoot}guide/topics/ui/actionbar.html">barra de ao</a> como uma combinao de itens 80 de ao na tela e opes de estouro. A partir do Android 3.0, o boto <em>Menu</em> censurado (alguns 81 dispositivos 82 no tm), ento voc deve migrar usando a barra de ao para fornecer acesso a aes 83 e outras opes.</p> 84 <p>Consulte a seo <a href="#options-menu">Criao de um menu de opes</a>.</p> 85 </dd> 86 87 <dt><strong>Modo de ao contextual e menu de contexto</strong></dt> 88 89 <dd>Um menu de contexto um <a href="#FloatingContextMenu">menu flutuante</a> que aparece quando 90 o usurio realiza um clique longo em um elemento. Ele fornece aes que afetam o contedo selecionado 91 ou a estrutura do contexto. 92 <p>Ao desenvolver para Android 3.0 ou posterior, voc deve usar o <a href="#CAB">modo de ao contextual</a> para ativar as aes no contedo selecionado. Este modo exibe os itens de ao 93 que afetam o contedo selecionado em uma barra no topo da tela e permite que o usurio 94 selecione vrios itens.</p> 95 <p>Consulte a seo <a href="#context-menu">Criao de menus contextuais</a>.</p> 96 </dd> 97 98 <dt><strong>Menu pop-up</strong></dt> 99 <dd>Um menu pop-up exibe itens em uma lista vertical ancorada vista 100 que apresentou o menu. bom para fornecer um estouro de aes relacionado a contedo especfico 101 ou opes de fornecimento de uma segunda parte de um comando. As aes em um menu pop-up 102 <strong>no</strong> devem afetar diretamente o contedo correspondente — para isso que servem 103 as aes contextuais. Preferivelmente, o menu pop-up serve para aes estendidas que relacionam as regies de contedo 104 na atividade. 105 <p>Consulte a seo <a href="#PopupMenu">criar um menu pop-up</a>.</p> 106 </dd> 107 </dl> 108 109 110 111 <h2 id="xml">Definio de um menu em XML</h2> 112 113 <p>Para todos os tipos de menu, o Android fornece um formato XML padro para definir os itens de menu. 114 Em vez de criar um menu no cdigo da atividade, voc deve definir um menu e todos os seus itens 115 em um <a href="{@docRoot}guide/topics/resources/menu-resource.html">recurso de menu</a> XML. possvel, assim, 116 inflar o recurso do menu (carreg-lo como um objeto {@link android.view.Menu}) na atividade, ou 117 no fragmento.</p> 118 119 <p>Usar um recurso de menu uma boa prtica por alguns motivos:</p> 120 <ul> 121 <li> mais fcil para visualizar a estrutura do menu em XML.</li> 122 <li>Ele separa o contedo do menu do cdigo comportamental do aplicativo.</li> 123 <li>Ele permite criar configuraes alternativas de menu para verses diferentes de plataforma, 124 de tamanhos de tela e de outras configuraes aproveitando a estrutura dos <a href="{@docRoot}guide/topics/resources/index.html">recursos do aplicativo</a>.</li> 125 </ul> 126 127 <p>Para definir o menu, crie um arquivo XML dentro do diretrio <code>res/menu/</code> 128 do projeto e crie o menu com os seguintes elementos:</p> 129 <dl> 130 <dt><code><menu></code></dt> 131 <dd>Define um {@link android.view.Menu}, que um recipiente para os itens de menu. Um elemento 132 <code><menu></code> deve ser o ndulo raiz para o arquivo e pode reter um ou mais elementos 133 <code><item></code> e <code><group></code>.</dd> 134 135 <dt><code><item></code></dt> 136 <dd>Cria um {@link android.view.MenuItem}, que representa um nico item em um menu. Este 137 elemento pode conter um elemento <code><menu></code> aninhado para criar um submenu.</dd> 138 139 <dt><code><group></code></dt> 140 <dd>Um recipiente invisvel e opcional para os elementos {@code <item>}. Ele permite que voc categorize 141 itens de menu para que eles compartilhem propriedades como estado ativo e visibilidade. Para obter mais informaes, 142 consulte a seo <a href="#groups">Criao de grupos de menu</a>.</dd> 143 </dl> 144 145 146 <p>A seguir h um exemplo de menu chamado <code>game_menu.xml</code>:</p> 147 <pre> 148 <?xml version="1.0" encoding="utf-8"?> 149 <menu xmlns:android="http://schemas.android.com/apk/res/android"> 150 <item android:id="@+id/new_game" 151 android:icon="@drawable/ic_new_game" 152 android:title="@string/new_game" 153 android:showAsAction="ifRoom"/> 154 <item android:id="@+id/help" 155 android:icon="@drawable/ic_help" 156 android:title="@string/help" /> 157 </menu> 158 </pre> 159 160 <p>O elemento <code><item></code> compatvel com vrios atributos que voc pode usar para definir a aparncia ou o comportamento 161 de um item. Os itens no menu acima incluem os seguintes atributos:</p> 162 163 <dl> 164 <dt>{@code android:id}</dt> 165 <dd>Um ID de recurso que nico para o item. Ele permite que o aplicativo reconhea o item 166 quando o usurio o seleciona.</dd> 167 <dt>{@code android:icon}</dt> 168 <dd>Uma referncia a um desenhvel para usar como o cone do item.</dd> 169 <dt>{@code android:title}</dt> 170 <dd>Uma referncia a uma string para usar como o ttulo do item.</dd> 171 <dt>{@code android:showAsAction}</dt> 172 <dd>Especifica quando e como este item deve aparecer como um item de ao na <a href="{@docRoot}guide/topics/ui/actionbar.html">barra de ao</a>.</dd> 173 </dl> 174 175 <p>Esses so os atributos mais importantes que devem ser usados, mas h vrios outros disponveis. 176 Para obter informaes sobre todos os atributos compatveis, consulte o documento <a href="{@docRoot}guide/topics/resources/menu-resource.html">Recurso de menu</a>.</p> 177 178 <p> possvel adicionar um submenu a um item em qualquer menu (exceto a um submenu) adicionando um elemento {@code <menu>} 179 como filho de um {@code <item>}. Os submenus so teis quando o aplicativo 180 tem vrias funes que podem ser organizadas em tpicos, como itens em uma barra de menu do aplicativo do PC (arquivo, 181 editar, visualizar etc.). Por exemplo:</p> 182 183 <pre> 184 <?xml version="1.0" encoding="utf-8"?> 185 <menu xmlns:android="http://schemas.android.com/apk/res/android"> 186 <item android:id="@+id/file" 187 android:title="@string/file" > 188 <!-- "file" submenu --> 189 <menu> 190 <item android:id="@+id/create_new" 191 android:title="@string/create_new" /> 192 <item android:id="@+id/open" 193 android:title="@string/open" /> 194 </menu> 195 </item> 196 </menu> 197 </pre> 198 199 <p>Para usar o menu em sua atividade, voc precisa inflar o recurso do menu (converter o recurso 200 XML em um objeto programvel) usando {@link android.view.MenuInflater#inflate(int,Menu) 201 MenuInflater.inflate()}. Nas sees a seguir, voc ver como inflar um menu para cada 202 tipo de menu.</p> 203 204 205 206 <h2 id="options-menu">Criao de um menu de opes</h2> 207 208 <div class="figure" style="width:200px;margin:0"> 209 <img src="{@docRoot}images/options_menu.png" height="333" alt="" /> 210 <p class="img-caption"><strong>Figura 1.</strong> Menu de opes 211 no navegador, no Android 2.3.</p> 212 </div> 213 214 <p>O menu de opes onde voc deve incluir aes e outras opes que so relevantes 215 para o contexto de atividade atual, como "Buscar", "Escrever e-mail" e "Configuraes".</p> 216 217 <p>O local onde os itens no menu de opes aparecem na tela depende da verso em que o aplicativo 218 foi desenvolvido:</p> 219 220 <ul> 221 <li>Caso tenha desenvolvido o aplicativo para <strong>Android 2.3.x (API de nvel 10) ou 222 inferior</strong>, os contedos do menu de opes aparecero na parte inferior da tela, quando o usurio 223 pressionar o boto <em>Menu</em>, como exibido na figura 1. Quando aberto, a primeira parte visvel 224 o menu 225 de cones, que possui at seis itens de menu. Se o menu incluir mais de seis itens, o Android 226 colocar o sexto item e o resto em um menu flutuante, que o usurio poder abrir selecionando 227 <em>Mais</em>.</li> 228 229 <li>Se voc desenvolveu o aplicativo para <strong>Android 3.0 (API de nvel 11) ou 230 superior</strong>, os itens do menu de opes esto disponveis na <a href="{@docRoot}guide/topics/ui/actionbar.html">barra de ao</a>. Por padro, o sistema 231 posiciona todos os itens na ao de estouro, que o usurio pode revelar com o cone de estouro de ao 232 no lado direito da barra de ao (ou pressionando o boto <em>Menu</em>, se disponvel). Para 233 ativar 234 o acesso rpido a aes importantes, possvel promover alguns itens para aparecerem na barra de ao adicionando 235 {@code android:showAsAction="ifRoom"} aos elementos {@code <item>} correspondentes (veja a figura 236 2). <p>Para obter mais informaes sobre os itens de ao e outros comportamentos da barra de ao, consulte o guia <a href="{@docRoot}guide/topics/ui/actionbar.html">Barra de ao</a>. </p> 237 <p class="note"><strong>Observao:</strong> Mesmo se <em>no</em> estiver desenvolvendo para Android 3.0 ou 238 posteriores, possvel compilar seu prprio layout de barra de ao para obter um efeito semelhante. Para obter um exemplo de como possvel 239 suportar verses mais antigas do Android com uma barra de ao, consulte o exemplo <a href="{@docRoot}resources/samples/ActionBarCompat/index.html">Compatibilidade da barra de ao</a> 240 .</p> 241 </li> 242 </ul> 243 244 <img src="{@docRoot}images/ui/actionbar.png" alt="" /> 245 <p class="img-caption"><strong>Figura 2.</strong> Barra de ao do aplicativo <a href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a>, exibindo 246 guias de navegao e um item de ao de cmera (alm do boto de estouro de ao).</p> 247 248 <p> possvel declarar itens para o menu de opes da subclasse {@link android.app.Activity} 249 ou de uma subclasse {@link android.app.Fragment}. Se a atividade e os fragmentos 250 declararem itens para o menu de opes, eles estaro combinados na IU. O item da atividade aparece primeiro, 251 seguido de cada um desses fragmentos na ordem em que so adicionados 252 atividade. Se necessrio, possvel reorganizar os itens do menu com o atributo {@code android:orderInCategory} 253 em cada {@code <item>} que precisar mover.</p> 254 255 <p>Para especificar o menu de opes para uma atividade, substitua {@link 256 android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} (os fragmentos fornecem 257 o prprio retorno de chamada de {@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()}). Neste mtodo 258 , possvel inflar o recurso de menu (<a href="#xml">definido no XML</a>) em um {@link 259 android.view.Menu} fornecido no retorno de chamada. Por exemplo:</p> 260 261 <pre> 262 @Override 263 public boolean onCreateOptionsMenu(Menu menu) { 264 MenuInflater inflater = {@link android.app.Activity#getMenuInflater()}; 265 inflater.inflate(R.menu.game_menu, menu); 266 return true; 267 } 268 </pre> 269 270 <p>Tambm possvel adicionar itens de menu usando {@link android.view.Menu#add(int,int,int,int) 271 add()} e recuperar os itens com {@link android.view.Menu#findItem findItem()} para revisar 272 as propriedades com APIs de {@link android.view.MenuItem}.</p> 273 274 <p>Caso tenha desenvolvido o aplicativo para Android 2.3.x e anteriores, o sistema chamar {@link 275 android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} para criar o menu de opes 276 quando o usurio abrir o menu pela primeira vez. Caso tenha desenvolvido para Android 3.0 e posteriores, 277 o sistema chama {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} 278 ao iniciar a atividade para mostrar os itens para a barra de ao.</p> 279 280 281 282 <h3 id="RespondingOptionsMenu">Tratamento de eventos de clique</h3> 283 284 <p>Quando o usurio seleciona um item para o menu de opes (incluindo os itens de ao na barra de ao), 285 o sistema chama o mtodo {@link android.app.Activity#onOptionsItemSelected(MenuItem) 286 onOptionsItemSelected()} da atividade. Este mtodo passa o {@link android.view.MenuItem} selecionado. possvel 287 identificar o item chamando {@link android.view.MenuItem#getItemId()}, que retorna o ID nico 288 para o item de menu (definido pelo atributo {@code android:id} no recurso de menu ou em um nmero inteiro 289 dado ao mtodo {@link android.view.Menu#add(int,int,int,int) add()}). possvel combinar este ID 290 com itens de menu conhecidos para realizar a ao adequada. Por exemplo:</p> 291 292 <pre> 293 @Override 294 public boolean onOptionsItemSelected(MenuItem item) { 295 // Handle item selection 296 switch (item.getItemId()) { 297 case R.id.new_game: 298 newGame(); 299 return true; 300 case R.id.help: 301 showHelp(); 302 return true; 303 default: 304 return super.onOptionsItemSelected(item); 305 } 306 } 307 </pre> 308 309 <p>Ao lidar com um item de menu, retorne {@code true}. Se no lidar com o item de menu, 310 voc dever chamar a implementao de superclasse de {@link 311 android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} (a implementao 312 padro retornar como falsa).</p> 313 314 <p>Se a atividade incluir fragmentos, o sistema chamar primeiro {@link 315 android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} para a atividade e, em seguida, 316 para cada fragmento (na ordem em que cada fragmento foi adicionado) at um retornar como 317 {@code true} ou at todos os fragmentos serem chamados.</p> 318 319 <p class="note"><strong>Dica:</strong> o Android 3.0 adiciona a possibilidade de definir o comportamento do clique 320 para um item de menu em XML, usando o atributo {@code android:onClick}. O valor do atributo 321 deve ser o nome de um mtodo definido pela atividade usando o menu. O mtodo 322 deve ser pblico e aceitar um nico parmetro {@link android.view.MenuItem} — quando o sistema chamar este mtodo, 323 ele passar o item de menu selecionado. Para obter mais informaes e um exemplo, consulte o documento <a href="{@docRoot}guide/topics/resources/menu-resource.html">Recurso de menu</a>.</p> 324 325 <p class="note"><strong>Dica:</strong> se o aplicativo contiver vrias atividades 326 e algumas delas fornecerem o mesmo menu de opes, 327 considere criar uma atividade que no implemente nada exceto os mtodos {@link android.app.Activity#onCreateOptionsMenu(Menu) 328 onCreateOptionsMenu()} e {@link android.app.Activity#onOptionsItemSelected(MenuItem) 329 onOptionsItemSelected()}. Em seguida, estenda esta classe para cada atividade que deve compartilhar 330 o mesmo menu de opes. Desta maneira, possvel gerenciar um conjunto de cdigos para lidar com aes de menu 331 e cada classe descendente herda os comportamentos do menu. 332 Se quiser adicionar itens de menu a uma das atividades descendentes, 333 substitua {@link android.app.Activity#onCreateOptionsMenu(Menu) 334 onCreateOptionsMenu()} nesta atividade. Chame {@code super.onCreateOptionsMenu(menu)} para que os itens de menu originais 335 sejam criados e, em seguida, adicione os novos itens de menu com {@link 336 android.view.Menu#add(int,int,int,int) menu.add()}. Voc tambm pode substituir o comportamento 337 da superclasse para itens de menu individuais.</p> 338 339 340 <h3 id="ChangingTheMenu">Alterao dos itens de menu em tempo de execuo</h3> 341 342 <p>Depois que o sistema chamar {@link android.app.Activity#onCreateOptionsMenu(Menu) 343 onCreateOptionsMenu()}, ele reter uma instncia do {@link android.view.Menu} que voc popular 344 e no chamar {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} 345 novamente, a no ser que o menu seja invalidado por algum motivo. No entanto, voc deve usar {@link 346 android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} somente para criar o estado inicial do menu 347 e no para realizar alteraes durante o ciclo de vida da atividade.</p> 348 349 <p>Caso queira modificar o menu de opes com base 350 em eventos que ocorrem durante o ciclo de vida da atividade, possvel faz-lo 351 no mtodo {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}. Este mtodo 352 passa a voc o objeto {@link android.view.Menu}, j que ele existe para que seja possvel modific-lo, 353 como com adio, remoo ou desativao de itens. (Os fragmentos tambm fornecem um retorno de chamada {@link 354 android.app.Fragment#onPrepareOptionsMenu onPrepareOptionsMenu()}.)</p> 355 356 <p>No Android 2.3.x e em anteriores, o sistema chamar {@link 357 android.app.Activity#onPrepareOptionsMenu(Menu) 358 onPrepareOptionsMenu()} sempre que o usurio abrir o menu de opes (pressionar o boto <em>Menu</em> 359 ).</p> 360 361 <p>No Android 3.0 e posteriores, avalia-se o menu de opes quanto a sempre estar aberto quando os itens de menu 362 so apresentados na barra de ao. Quando um evento ocorre e voc quer realizar uma atualizao de menu, 363 voc deve chamar {@link android.app.Activity#invalidateOptionsMenu invalidateOptionsMenu()} para pedir 364 que o sistema chame {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}.</p> 365 366 <p class="note"><strong>Observao:</strong> 367 voc nunca deve alterar os itens no menu de opes com base no {@link android.view.View} atualmente 368 em foco. Quando estiver no modo de toque (quando o usurio no est usando cursor de bola ou um teclado), as vistas 369 no podem ter foco, ento voc nunca deve usar o foco como base para modificar 370 os itens no menu de opes. Se quiser fornecer itens de menu que sejam sensveis a contexto para um {@link 371 android.view.View}, use um <a href="#context-menu">menu de contexto</a>.</p> 372 373 374 375 376 <h2 id="context-menu">Criao de menus contextuais</h2> 377 378 <div class="figure" style="width:420px;margin-top:-1em"> 379 <img src="{@docRoot}images/ui/menu-context.png" alt="" /> 380 <p class="img-caption"><strong>Figura 3.</strong> Capturas de tela de um menu de contexto flutuante (esquerda) 381 e a barra de ao contextual (direita).</p> 382 </div> 383 384 <p>Um menu contextual oferece aes que afetam um item ou estrutura de contexto especfica na IU. 385 possvel fornecer um menu de contexto para qualquer vista, mas ele geralmente usado para itens em um {@link 386 android.widget.ListView}, {@link android.widget.GridView}, ou em outras colees de vistas 387 em que o usurio pode realizar aes diretas em cada item.</p> 388 389 <p>H duas formas de fornecer aes contextuais:</p> 390 <ul> 391 <li>Em um <a href="#FloatingContextMenu">menu de contexto flutuante</a>. Um menu aparece como uma lista flutuante 392 de itens de menu (semelhante a uma caixa de dilogo) quando o usurio realiza um clique longo (pressiona e segura) 393 em uma vista que declara suporte para um menu de contexto. Os usurios podem realizar uma ao contextual 394 em um item por vez.</li> 395 396 <li>No <a href="#CAB">modo de ao contextual</a>. Este modo uma implementao de sistema de 397 {@link android.view.ActionMode} que exibe uma <em>barra de ao contextual</em> no topo da tela 398 com itens de ao que afetam os itens selecionados. Quando este modo est ativo, 399 os usurios podem realizar uma ao em vrios itens por vez (se o aplicativo permitir).</li> 400 </ul> 401 402 <p class="note"><strong>Observao:</strong> o modo de ao contextual est disponvel no Android 3.0 (API 403 de nvel 11) e em posteriores e a tcnica preferencial para exibir aes contextuais 404 quando disponvel. Se o aplicativo for compatvel com verses mais antigas que a 3.0, ento voc deve retornar a um menu 405 de contexto flutuante nestes dispositivos.</p> 406 407 408 <h3 id="FloatingContextMenu">Criao de um menu de contexto flutuante</h3> 409 410 <p>Para fornecer um menu de contexto flutuante:</p> 411 <ol> 412 <li>Registre o {@link android.view.View} ao qual o menu de contexto deve estar associado 413 chamando {@link android.app.Activity#registerForContextMenu(View) registerForContextMenu()} e passe-o 414 para {@link android.view.View}. 415 <p>Se a atividade usar {@link android.widget.ListView} ou {@link android.widget.GridView} 416 e voc quiser que cada item fornea o mesmo menu de contexto, registre todos os itens para um menu de contexto 417 passando {@link android.widget.ListView} ou {@link android.widget.GridView} para {@link 418 android.app.Activity#registerForContextMenu(View) registerForContextMenu()}.</p> 419 </li> 420 421 <li>Implemente o mtodo {@link 422 android.view.View.OnCreateContextMenuListener#onCreateContextMenu onCreateContextMenu()} 423 em {@link android.app.Activity} ou {@link android.app.Fragment}. 424 <p>Quando a vista registrada receber um evento de clique longo, o sistema chamar o mtodo {@link 425 android.view.View.OnCreateContextMenuListener#onCreateContextMenu onCreateContextMenu()} 426 . aqui que voc define os itens de menu, geralmente inflando um recurso de menu. Por 427 exemplo:</p> 428 <pre> 429 @Override 430 public void onCreateContextMenu(ContextMenu menu, View v, 431 ContextMenuInfo menuInfo) { 432 super.onCreateContextMenu(menu, v, menuInfo); 433 MenuInflater inflater = getMenuInflater(); 434 inflater.inflate(R.menu.context_menu, menu); 435 } 436 </pre> 437 438 <p>{@link android.view.MenuInflater} permite que voc infle o menu de contexto de um <a href="{@docRoot}guide/topics/resources/menu-resource.html">recurso de menu</a>. Os parmetros do mtodo 439 de retorno de chamada incluem o {@link android.view.View} 440 que o usurio selecionou e um objeto {@link android.view.ContextMenu.ContextMenuInfo} que fornece 441 informaes adicionais sobre o item selecionado. Se sua atividade tiver vrias vistas, em que cada uma fornea 442 um menu de contexto diferente, voc deve usar esses parmetros para determinar qual menu de contexto 443 deve ser inflado.</p> 444 </li> 445 446 <li>Implemente {@link android.app.Activity#onContextItemSelected(MenuItem) 447 onContextItemSelected()}. 448 <p>Quando o usurio selecionar um item de menu, o sistema chamar este mtodo para que voc possa realizar 449 a ao adequada. Por exemplo:</p> 450 451 <pre> 452 @Override 453 public boolean onContextItemSelected(MenuItem item) { 454 AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo(); 455 switch (item.getItemId()) { 456 case R.id.edit: 457 editNote(info.id); 458 return true; 459 case R.id.delete: 460 deleteNote(info.id); 461 return true; 462 default: 463 return super.onContextItemSelected(item); 464 } 465 } 466 </pre> 467 468 <p>O mtodo {@link android.view.MenuItem#getItemId()} consulta o ID 469 para o item de menu selecionado, o qual pode ser atribudo a cada item de menu no XML usando o atributo {@code 470 android:id}, como exibido na seo <a href="#xml">Definio de um menu em 471 XML</a>.</p> 472 473 <p>Ao lidar com um item de menu, retorne {@code true}. Se no lidar com o item de menu, 474 voc dever passar o item de menu para a implementao de superclasse. Se a atividade incluir fragmentos, 475 ela receber este retorno de chamada primeiro. Ao chamar a superclasse ao no lidar, o sistema 476 passar o evento para o respectivo mtodo de retorno de chamada em cada fragmento, um por vez (na ordem 477 em que cada fragmento foi adicionado) at que {@code true} ou {@code false} seja retornado. (A implementao 478 padro para {@link android.app.Activity} e {@code android.app.Fragment} retorna {@code 479 false}, ento voc deve sempre chamar a superclasse ao no tratar de um item de menu.)</p> 480 </li> 481 </ol> 482 483 484 <h3 id="CAB">Uso do modo de ao contextual</h3> 485 486 <p>O modo de ao contextual uma implementao de sistema de {@link android.view.ActionMode} 487 que direciona a interao do usurio a efetuar aes contextuais. Quando um usurio 488 ativa este modo selecionando um item, uma <em>barra de ao contextual</em> aparece na parte superior da tela 489 para apresentar as aes que o usurio pode realizar nos itens selecionados. Enquanto este modo estiver ativo, 490 o usurio pode selecionar vrios itens (se voc permitir), desmarcar itens e continuar 491 a navegar dentro da atividade (o tanto que voc permitir). O modo de ao 492 desativado e a barra de ao contextual desaparece quando o usurio desmarca todos os itens, pressiona o boto VOLTAR, 493 ou seleciona a ao <em>Pronto</em> na lateral esquerda da barra.</p> 494 495 <p class="note"><strong>Observao:</strong> a barra de ao contextual no necessariamente 496 associada <a href="{@docRoot}guide/topics/ui/actionbar.html">barra de ao</a>. Elas operam de forma independente, 497 apesar de a barra de ao contextual ocupar visualmente a posio 498 da barra de ao.</p> 499 500 <p>Caso esteja desenvolvendo para Android 3.0 (API de nvel 11) e posteriores, 501 voc deve usar o modo de ao contextual para apresentar aes contextuais, em vez de usar o <a href="#FloatingContextMenu">menu de contexto flutuante</a>.</p> 502 503 <p>Para oferecer vistas que fornecem aes contextuais, voc deve invocar o modo de ao contextual 504 sobre um dos eventos (ou ambos):</p> 505 <ul> 506 <li>O usurio realiza um clique longo na vista.</li> 507 <li>O usurio seleciona uma caixa de seleo ou um componente de IU semelhante dentro da vista.</li> 508 </ul> 509 510 <p>A maneira do aplicativo de invocar o modo de ao contextual e definir o comportamento 511 para cada ao depende do seu projeto. H basicamente dois projetos:</p> 512 <ul> 513 <li>Para aes contextuais em vistas arbitrrias individuais.</li> 514 <li>Para aes contextuais de agrupadas em itens em um {@link 515 android.widget.ListView} ou {@link android.widget.GridView} (permitindo que o usurio selecione vrios itens 516 e realize uma ao em todos eles).</li> 517 </ul> 518 519 <p>As seguintes sees descrevem a configurao necessria para cada cenrio.</p> 520 521 522 <h4 id="CABforViews">Ativao do modo de ao contextual para vistas individuais</h4> 523 524 <p>Caso queira invocar o modo de ao contextual somente quando o usurio selecionar 525 vistas especficas, voc deve:</p> 526 <ol> 527 <li>Implementar a interface {@link android.view.ActionMode.Callback}. Em seus mtodos de retorno de chamada, 528 possvel especificar as aes da barra de ao contextual, responder aos eventos de clique em itens de ao, 529 e tratar de outros eventos de ciclo de vida do modo de ao.</li> 530 <li>Chame {@link android.app.Activity#startActionMode startActionMode()} quando quiser exibir 531 a barra (como quando o usurio realiza cliques longos na visualizao).</li> 532 </ol> 533 534 <p>Por exemplo:</p> 535 536 <ol> 537 <li>Implementar a interface {@link android.view.ActionMode.Callback ActionMode.Callback}: 538 <pre> 539 private ActionMode.Callback mActionModeCallback = new ActionMode.Callback() { 540 541 // Called when the action mode is created; startActionMode() was called 542 @Override 543 public boolean onCreateActionMode(ActionMode mode, Menu menu) { 544 // Inflate a menu resource providing context menu items 545 MenuInflater inflater = mode.getMenuInflater(); 546 inflater.inflate(R.menu.context_menu, menu); 547 return true; 548 } 549 550 // Called each time the action mode is shown. Always called after onCreateActionMode, but 551 // may be called multiple times if the mode is invalidated. 552 @Override 553 public boolean onPrepareActionMode(ActionMode mode, Menu menu) { 554 return false; // Return false if nothing is done 555 } 556 557 // Called when the user selects a contextual menu item 558 @Override 559 public boolean onActionItemClicked(ActionMode mode, MenuItem item) { 560 switch (item.getItemId()) { 561 case R.id.menu_share: 562 shareCurrentItem(); 563 mode.finish(); // Action picked, so close the CAB 564 return true; 565 default: 566 return false; 567 } 568 } 569 570 // Called when the user exits the action mode 571 @Override 572 public void onDestroyActionMode(ActionMode mode) { 573 mActionMode = null; 574 } 575 }; 576 </pre> 577 578 <p>Observe que esses retornos de chamada de eventos so quase exatamente iguais aos retornos de chamada do <a href="#options-menu">menu de opes</a>, exceto que cada um deles tambm passa o objeto {@link 579 android.view.ActionMode} associado ao evento. possvel usar APIs de {@link 580 android.view.ActionMode} para realizar vrias alteraes ao CAB, como revisar um ttulo e um subttulo 581 com {@link android.view.ActionMode#setTitle setTitle()} e {@link 582 android.view.ActionMode#setSubtitle setSubtitle()} (til para indicar quantos itens 583 so selecionados).</p> 584 585 <p>Observe tambm que os exemplos acima definem a varivel {@code mActionMode} como nula quando 586 o modo de ao destrudo. Na etapa a seguir, voc ver como ela inicializada 587 e quo til salvar a varivel do membro na atividade ou no fragmento pode ser.</p> 588 </li> 589 590 <li>Chame {@link android.app.Activity#startActionMode startActionMode()} para ativar o modo de ao contextual 591 quando apropriado, como em resposta a um clique longo em um {@link 592 android.view.View}:</p> 593 594 <pre> 595 someView.setOnLongClickListener(new View.OnLongClickListener() { 596 // Called when the user long-clicks on someView 597 public boolean onLongClick(View view) { 598 if (mActionMode != null) { 599 return false; 600 } 601 602 // Start the CAB using the ActionMode.Callback defined above 603 mActionMode = getActivity().startActionMode(mActionModeCallback); 604 view.setSelected(true); 605 return true; 606 } 607 }); 608 </pre> 609 610 <p>Ao chamar {@link android.app.Activity#startActionMode startActionMode()}, o sistema 611 retorna o {@link android.view.ActionMode} criado. Ao salvar isto em uma varivel do membro, 612 possvel realizar alteraes na barra de ao contextual em resposta a outros eventos. No exemplo acima, 613 {@link android.view.ActionMode} usado para garantir que a instncia {@link android.view.ActionMode} 614 no seja recriada se j estiver ativa, verificando se o membro nulo antes de iniciar 615 o modo de ao.</p> 616 </li> 617 </ol> 618 619 620 621 <h4 id="CABforListView">Ativao de aes contextuais agrupadas em ListView ou GridView</h4> 622 623 <p>Se tiver uma coleo de itens em um {@link android.widget.ListView} ou {@link 624 android.widget.GridView} (ou outra extenso de {@link android.widget.AbsListView}) e quiser 625 permitir que os usurios realizem aes de agrupamento, voc deve:</p> 626 627 <ul> 628 <li>Implementar a interface {@link android.widget.AbsListView.MultiChoiceModeListener} e defini-la 629 para o grupo de visualizao com {@link android.widget.AbsListView#setMultiChoiceModeListener 630 setMultiChoiceModeListener()}. Nos mtodos de retorno de chamada da escuta, possvel especificar as aes 631 para a barra de ao contextual, responder a eventos de clique em itens de ao e lidar com outros retornos de chamada 632 herdados da interface {@link android.view.ActionMode.Callback}.</li> 633 634 <li>Chame {@link android.widget.AbsListView#setChoiceMode setChoiceMode()} com o argumento {@link 635 android.widget.AbsListView#CHOICE_MODE_MULTIPLE_MODAL}.</li> 636 </ul> 637 638 <p>Por exemplo:</p> 639 640 <pre> 641 ListView listView = getListView(); 642 listView.setChoiceMode(ListView.CHOICE_MODE_MULTIPLE_MODAL); 643 listView.setMultiChoiceModeListener(new MultiChoiceModeListener() { 644 645 @Override 646 public void onItemCheckedStateChanged(ActionMode mode, int position, 647 long id, boolean checked) { 648 // Here you can do something when items are selected/de-selected, 649 // such as update the title in the CAB 650 } 651 652 @Override 653 public boolean onActionItemClicked(ActionMode mode, MenuItem item) { 654 // Respond to clicks on the actions in the CAB 655 switch (item.getItemId()) { 656 case R.id.menu_delete: 657 deleteSelectedItems(); 658 mode.finish(); // Action picked, so close the CAB 659 return true; 660 default: 661 return false; 662 } 663 } 664 665 @Override 666 public boolean onCreateActionMode(ActionMode mode, Menu menu) { 667 // Inflate the menu for the CAB 668 MenuInflater inflater = mode.getMenuInflater(); 669 inflater.inflate(R.menu.context, menu); 670 return true; 671 } 672 673 @Override 674 public void onDestroyActionMode(ActionMode mode) { 675 // Here you can make any necessary updates to the activity when 676 // the CAB is removed. By default, selected items are deselected/unchecked. 677 } 678 679 @Override 680 public boolean onPrepareActionMode(ActionMode mode, Menu menu) { 681 // Here you can perform updates to the CAB due to 682 // an {@link android.view.ActionMode#invalidate} request 683 return false; 684 } 685 }); 686 </pre> 687 688 <p> isso. Agora, quando o usurio selecionar um item com um clique longo, o sistema chamar o mtodo {@link 689 android.widget.AbsListView.MultiChoiceModeListener#onCreateActionMode onCreateActionMode()} 690 e exibir a barra de ao contextual com as aes especificadas. Enquanto a barra de ao contextual 691 estiver visvel, os usurios podero selecionar itens adicionais.</p> 692 693 <p>Em alguns casos em que as aes contextuais fornecem itens de ao comuns, voc pode 694 querer adicionar uma caixa de seleo ou um elemento de IU semelhante que permite que os usurios selecionem itens, 695 pois eles podem no descobrir o comportamento do clique longo. Quando um usurio seleciona a caixa de seleo, 696 possvel invocar o modo de ao contextual definindo o respectivo item de lista 697 para o estado marcado com {@link android.widget.AbsListView#setItemChecked setItemChecked()}.</p> 698 699 700 701 702 <h2 id="PopupMenu">Criao de um menu pop-up</h2> 703 704 <div class="figure" style="width:220px"> 705 <img src="{@docRoot}images/ui/popupmenu.png" alt="" /> 706 <p><strong>Figura 4.</strong> Um menu pop-up no aplicativo do Gmail, ancorado ao boto 707 de estouro no cando direito superior.</p> 708 </div> 709 710 <p>Um {@link android.widget.PopupMenu} um menu modal ancorado a uma {@link android.view.View}. 711 Ele aparece sob a vista de ncora se tiver espao, ou sobre a vista. Ele til para:</p> 712 <ul> 713 <li>Fornecer um menu de estilo de estouro para aes que <em>se relacionam</em> com o contedo especfico (como 714 cabealhos de e-mail do Gmail, exibidos na figura 4). 715 <p class="note"><strong>Observao:</strong> Isto no igual ao menu de contexto, 716 que geralmente usado para aes que <em>afetam</em> o contedo selecionado. Para aes que afetam o contedo 717 selecionado, use o <a href="#CAB">modo de ao contextual</a> ou o <a href="#FloatingContextMenu">menu de contexto flutuante</a>.</p></li> 718 <li>Fornecer uma segunda parte de uma sentena de comando (como um boto marcado como "Adicionar" 719 que produz um menu pop-up com opes diferentes de "Adicionar").</li> 720 <li>Fornecer um menu suspenso semelhante a {@link android.widget.Spinner} que no retenha 721 uma seleo persistente.</li> 722 </ul> 723 724 725 <p class="note"><strong>Observao:</strong> {@link android.widget.PopupMenu} est disponvel com a API 726 de nvel 11 ou posteriores.</p> 727 728 <p>Se <a href="#xml">definir o menu em XML</a>, abaixo exposto o modo de exibir o menu pop-up:</p> 729 <ol> 730 <li>Represente um {@link android.widget.PopupMenu} com seu construtor, 731 que usa o aplicativo {@link android.content.Context} e {@link android.view.View} atual ao qual o menu 732 deve ser ancorado.</li> 733 <li>Use {@link android.view.MenuInflater} para inflar o recurso de menu no objeto {@link 734 android.view.Menu} retornado por {@link 735 android.widget.PopupMenu#getMenu() PopupMenu.getMenu()}. Em APIs de nvel 14 ou posteriores, possvel usar 736 {@link android.widget.PopupMenu#inflate PopupMenu.inflate()}.</li> 737 <li>Chame {@link android.widget.PopupMenu#show() PopupMenu.show()}.</li> 738 </ol> 739 740 <p>Por exemplo, a seguir h um boto com o atributo {@link android.R.attr#onClick android:onClick} 741 que exibe um menu pop-up:</p> 742 743 <pre> 744 <ImageButton 745 android:layout_width="wrap_content" 746 android:layout_height="wrap_content" 747 android:src="@drawable/ic_overflow_holo_dark" 748 android:contentDescription="@string/descr_overflow_button" 749 android:onClick="showPopup" /> 750 </pre> 751 752 <p>A atividade pode ento exibir o menu pop-up desta forma:</p> 753 754 <pre> 755 public void showPopup(View v) { 756 PopupMenu popup = new PopupMenu(this, v); 757 MenuInflater inflater = popup.getMenuInflater(); 758 inflater.inflate(R.menu.actions, popup.getMenu()); 759 popup.show(); 760 } 761 </pre> 762 763 <p>Em APIs de nvel 14 ou posteriores, possvel combinar as duas linhas que inflam o menu com {@link 764 android.widget.PopupMenu#inflate PopupMenu.inflate()}.</p> 765 766 <p>O menu dispensado quando o usurio seleciona um item ou toca fora 767 da rea do menu. possvel ouvir o evento de dispensa usando {@link 768 android.widget.PopupMenu.OnDismissListener}.</p> 769 770 <h3 id="PopupEvents">Tratamento de eventos de clique</h3> 771 772 <p>Para realizar uma ao 773 quando o usurio seleciona um item de menu, voc deve implementar a interface {@link 774 android.widget.PopupMenu.OnMenuItemClickListener} e registr-la com {@link 775 android.widget.PopupMenu} chamando {@link android.widget.PopupMenu#setOnMenuItemClickListener 776 setOnMenuItemclickListener()}. Quando o usurio seleciona um item, o sistema chama o retorno de chamada {@link 777 android.widget.PopupMenu.OnMenuItemClickListener#onMenuItemClick onMenuItemClick()} 778 na interface.</p> 779 780 <p>Por exemplo:</p> 781 782 <pre> 783 public void showMenu(View v) { 784 PopupMenu popup = new PopupMenu(this, v); 785 786 // This activity implements OnMenuItemClickListener 787 popup.setOnMenuItemClickListener(this); 788 popup.inflate(R.menu.actions); 789 popup.show(); 790 } 791 792 @Override 793 public boolean onMenuItemClick(MenuItem item) { 794 switch (item.getItemId()) { 795 case R.id.archive: 796 archive(item); 797 return true; 798 case R.id.delete: 799 delete(item); 800 return true; 801 default: 802 return false; 803 } 804 } 805 </pre> 806 807 808 <h2 id="groups">Criao de grupos de menu</h2> 809 810 <p>Um grupo de menu uma coleo de itens de menu que compartilham certas peculiaridades. Com um grupo, 811 possvel:</p> 812 <ul> 813 <li>Exibir ou ocultar todos os itens com {@link android.view.Menu#setGroupVisible(int,boolean) 814 setGroupVisible()}</li> 815 <li>Ativar ou desativar todos os itens com {@link android.view.Menu#setGroupEnabled(int,boolean) 816 setGroupEnabled()}</li> 817 <li>Especificar se todos os itens so marcveis com {@link 818 android.view.Menu#setGroupCheckable(int,boolean,boolean) setGroupCheckable()}</li> 819 </ul> 820 821 <p> possvel criar um grupo aninhando elementos {@code <item>} dentro de um elemento {@code <group>} 822 no recurso de menu ou especificando um ID de grupo com o mtodo {@link 823 android.view.Menu#add(int,int,int,int) add()}.</p> 824 825 <p>Abaixo h um exemplo de recurso de menu que inclui um grupo:</p> 826 827 <pre> 828 <?xml version="1.0" encoding="utf-8"?> 829 <menu xmlns:android="http://schemas.android.com/apk/res/android"> 830 <item android:id="@+id/menu_save" 831 android:icon="@drawable/menu_save" 832 android:title="@string/menu_save" /> 833 <!-- menu group --> 834 <group android:id="@+id/group_delete"> 835 <item android:id="@+id/menu_archive" 836 android:title="@string/menu_archive" /> 837 <item android:id="@+id/menu_delete" 838 android:title="@string/menu_delete" /> 839 </group> 840 </menu> 841 </pre> 842 843 <p>Os itens que esto no grupo aparecem no mesmo nvel que o primeiro item — todos os trs itens 844 no menu so irmos. No entanto, possvel modificar as peculiaridades dos dois itens 845 no grupo mencionando o ID do grupo e usando os mtodos listados acima. O sistema 846 tambm nunca separar os itens agrupados. Por exemplo, se voc declarar {@code 847 android:showAsAction="ifRoom"} para cada item, eles aparecero na barra de ao 848 ou no estouro de ao.</p> 849 850 851 <h3 id="checkable">Uso de itens de menu marcveis</h3> 852 853 <div class="figure" style="width:200px"> 854 <img src="{@docRoot}images/radio_buttons.png" height="333" alt="" /> 855 <p class="img-caption"><strong>Figura 5.</strong> Captura de tela de um submenu 856 com itens marcveis.</p> 857 </div> 858 859 <p>Um menu como uma interface pode ser til para ativar e desativar as opes, usar uma caixa de seleo 860 para opes independentes ou botes de rdio para grupos 861 de opes mutuamente exclusivas. A figura 5 mostra um submenu com itens marcveis 862 com botes de rdio.</p> 863 864 <p class="note"><strong>Observao:</strong> os itens de menu no menu de cones (do menu de opes) 865 no podem exibir uma caixa de seleo ou um boto de rdio. Caso escolha tornar marcveis os itens no menu de cones, 866 voc dever indicar manualmente o estado marcado arrastando o cone e/ou digitando 867 sempre que o estado for alterado.</p> 868 869 <p> possvel definir o comportamento marcvel para itens individuais de menu usando o atributo {@code 870 android:checkable} no elemento {@code <item>}, ou para um grupo inteiro 871 com o atributo {@code android:checkableBehavior} no elemento {@code <group>}. Por exemplo, 872 todos os itens neste grupo de menu so marcveis com um boto de rdio:</p> 873 874 <pre> 875 <?xml version="1.0" encoding="utf-8"?> 876 <menu xmlns:android="http://schemas.android.com/apk/res/android"> 877 <group android:checkableBehavior="single"> 878 <item android:id="@+id/red" 879 android:title="@string/red" /> 880 <item android:id="@+id/blue" 881 android:title="@string/blue" /> 882 </group> 883 </menu> 884 </pre> 885 886 <p>O atributo {@code android:checkableBehavior} aceita: 887 <dl> 888 <dt>{@code single}</dt> 889 <dd>Somente um item do grupo pode ser marcado (botes de rdio)</dd> 890 <dt>{@code all}</dt> 891 <dd>Todos os itens podem ser marcados (caixas de seleo)</dd> 892 <dt>{@code none}</dt> 893 <dd>Nenhum item marcvel</dd> 894 </dl> 895 896 <p> possvel aplicar um estado marcado padro a um item usando o atributo {@code android:checked} 897 no elemento {@code <item>} e alterar o seu cdigo com o mtodo {@link 898 android.view.MenuItem#setChecked(boolean) setChecked()}.</p> 899 900 <p>Quando um item marcvel selecionado, o sistema chama o respectivo mtodo retorno de chamada do item selecionado 901 (como {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}). aqui 902 que voc deve definir o estado da caixa de seleo, pois a caixa de seleo ou o boto de rdio 903 no altera o seu estado automaticamente. possvel consultar o estado do item (como ele era antes 904 do usurio selecion-lo) com {@link android.view.MenuItem#isChecked()} e, em seguida, definir o estado marcado com 905 {@link android.view.MenuItem#setChecked(boolean) setChecked()}. Por exemplo:</p> 906 907 <pre> 908 @Override 909 public boolean onOptionsItemSelected(MenuItem item) { 910 switch (item.getItemId()) { 911 case R.id.vibrate: 912 case R.id.dont_vibrate: 913 if (item.isChecked()) item.setChecked(false); 914 else item.setChecked(true); 915 return true; 916 default: 917 return super.onOptionsItemSelected(item); 918 } 919 } 920 </pre> 921 922 <p>Caso voc no defina o estado marcado desta maneira, o estado visvel do item (a caixa de seleo 923 ou o boto de rdio) 924 no se alterar quando o usurio selecion-lo. Quando o estado definido, a atividade preserva o estado marcado 925 do item para que, quando o usurio abrir o menu posteriormente, o estado marcado 926 definido esteja visvel.</p> 927 928 <p class="note"><strong>Observao:</strong> 929 os itens de menu marcveis servem para serem usados somente em uma base por sesso e no so salvos quando 930 o aplicativo destrudo. Caso tenha configuraes de aplicativo que gostaria de salvar para o usurio, 931 voc deve armazenar os dados usando as <a href="{@docRoot}guide/topics/data/data-storage.html#pref">preferncias compartilhadas</a>.</p> 932 933 934 935 <h2 id="intents">Adio de itens de menu com base em uma inteno</h2> 936 937 <p>s vezes, voc desejar que um item de menu inicie uma atividade usando uma {@link android.content.Intent} 938 (se uma atividade no seu ou em outro aplicativo). Quando voc sabe qual inteno 939 quer usar e tem um item de menu especfico que deve iniciar a inteno, possvel execut-la 940 com {@link android.app.Activity#startActivity(Intent) startActivity()} durante 941 o mtodo de retorno de chamada selecionado no item (como o retorno de chamada {@link 942 android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}).</p> 943 944 <p>No entanto, caso no tenha certeza de que o dispositivo 945 do usurio contm um aplicativo que lida com a inteno, adicionar um item que o invoca 946 resulta em um item de menu que no funciona, pois a inteno pode no se resolver 947 em uma atividade. Para resolver isto, o Android permite que voc adicione itens de menu dinamicamente ao seu menu 948 quando encontra atividades no dispositivo que lidam com a inteno.</p> 949 950 <p>Para adicionar itens de menu com base nas atividades disponveis que aceitam uma inteno:</p> 951 <ol> 952 <li>Defina a inteno 953 com a categoria {@link android.content.Intent#CATEGORY_ALTERNATIVE} 954 e/ou {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE}, alm de quaisquer outros requisitos.</li> 955 <li>Chame {@link 956 android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) 957 Menu.addIntentOptions()}. O Android procura um aplicativo que possa realizar a inteno 958 e adiciona-o ao seu menu.</li> 959 </ol> 960 961 <p>Se no houver nenhum aplicativo instalado 962 que satisfaa a inteno, nenhum item de menu ser adicionado.</p> 963 964 <p class="note"><strong>Observao:</strong> 965 {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} usado para lidar com o elemento atualmente selecionado 966 na tela. Portanto, ele deve ser usado apenas ao criar um menu em {@link 967 android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo) 968 onCreateContextMenu()}.</p> 969 970 <p>Por exemplo:</p> 971 972 <pre> 973 @Override 974 public boolean onCreateOptionsMenu(Menu menu){ 975 super.onCreateOptionsMenu(menu); 976 977 // Create an Intent that describes the requirements to fulfill, to be included 978 // in our menu. The offering app must include a category value of Intent.CATEGORY_ALTERNATIVE. 979 Intent intent = new Intent(null, dataUri); 980 intent.addCategory(Intent.CATEGORY_ALTERNATIVE); 981 982 // Search and populate the menu with acceptable offering applications. 983 menu.addIntentOptions( 984 R.id.intent_group, // Menu group to which new items will be added 985 0, // Unique item ID (none) 986 0, // Order for the items (none) 987 this.getComponentName(), // The current activity name 988 null, // Specific items to place first (none) 989 intent, // Intent created above that describes our requirements 990 0, // Additional flags to control items (none) 991 null); // Array of MenuItems that correlate to specific items (none) 992 993 return true; 994 }</pre> 995 996 <p>Para cada atividade encontrada que fornece um filtro de inteno correspondente inteno definida, 997 um item de menu adicionado, usando o valor no <code>android:label</code> do filtro de inteno 998 como o ttulo do item e o cone do aplicativo como o cone do item de menu. O mtodo 999 {@link android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) 1000 addIntentOptions()} retorna o nmero de itens de menu adicionados.</p> 1001 1002 <p class="note"><strong>Observao:</strong> Ao chamar {@link 1003 android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) 1004 addIntentOptions()}, ele substitui todos os itens de menu no grupo do menu especificado 1005 no primeiro argumento.</p> 1006 1007 1008 <h3 id="AllowingToAdd">Permisso para a atividade ser adicionada a outros menus</h3> 1009 1010 <p>Voc pode tambm oferecer os servios da sua atividade para outros aplicativos, 1011 para que o aplicativo possa ser includo no menu de outros (revertendo as funes descritas acima).</p> 1012 1013 <p>Para ser includo nos menus de outros aplicativos, voc precisa definir 1014 um filtro de inteno como normalmente faz, mas certificando-se de incluir os valores {@link android.content.Intent#CATEGORY_ALTERNATIVE} 1015 e/ou {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} para a categoria 1016 do filtro de inteno. Por exemplo:</p> 1017 <pre> 1018 <intent-filter label="@string/resize_image"> 1019 ... 1020 <category android:name="android.intent.category.ALTERNATIVE" /> 1021 <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> 1022 ... 1023 </intent-filter> 1024 </pre> 1025 1026 <p>Leia mais sobre a criao de filtros de inteno no documento 1027 <a href="/guide/components/intents-filters.html">Intenes e filtros de intenes</a>.</p> 1028 1029 <p>Para obter um exemplo de aplicativo que usa esta tcnica, consulte o cdigo de exemplo do 1030 <a href="{@docRoot}resources/samples/NotePad/src/com/example/android/notepad/NoteEditor.html">Bloco 1031 de notas</a>.</p> 1032
