topics/ui/ui-events.jd

page.title=Eventos de entrada
parent.title=Interface do usurio
parent.link=index.html
@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>Neste documento</h2>
  <ol>
    <li><a href="#EventListeners">Escutas de evento</a></li>
    <li><a href="#EventHandlers">Manipuladores de evento</a></li>
    <li><a href="#TouchMode">Modo de toque</a></li>
    <li><a href="#HandlingFocus">Tratamento de foco</a></li>
  </ol>

</div>
</div>

<p>No Android, h mais de uma maneira de interceptar os eventos da interao de um usurio com o aplicativo.
Ao considerar os eventos dentro da interface do usurio, a abordagem  capturar os eventos
de um objeto de View especfico com o qual o usurio interage. A classe View fornece os meios para fazer isto.</p>

<p>Dentro das vrias classes View que voc usar para compor o layout,  possvel notar vrios mtodos
pblicos de retorno de chamada que parecem teis para eventos de IU. Esses mtodos so chamados pela estrutura do Android quando
a ao respectiva ocorre neste objeto. Por exemplo, quando uma View (como um boto)  tocada,
o mtodo <code>onTouchEvent()</code>  chamado neste objeto. No entanto, para interceptar isto, voc deve estender
a classe e substituir o mtodo. No entanto, estender todos os objetos de View
para lidar com tal evento no seria algo prtico.  por isso que a classe View tambm contm
uma coleo de interfaces aninhadas com retornos de chamada que podem ser definidas com muito mais facilidade. Essas interfaces,
chamadas de <a href="#EventListeners">escutas de evento</a>, so a sua passagem para capturar a interao do usurio com a IU.</p>

<p>Geralmente, as escutas de evento so usadas para escutar a interao do usurio.
No entanto, h casos em que voc pode querer estender uma classe View para criar um componente personalizado.
Talvez voc queira estender a classe {@link android.widget.Button}
para deixar algo mais extravagante. Neste caso, voc poder definir os comportamentos de evento padro
para a classe usando <a href="#EventHandlers">manipuladores de evento</a>.</p>


<h2 id="EventListeners">Escutas de evento</h2>

<p>Uma escuta de evento  uma interface na classe {@link android.view.View} que contm
um nico mtodo de retorno de chamada. Esses mtodos sero chamados pela estrutura do Android, quando a View para a qual a escuta
estiver registrada for ativada pela interao do usurio com o item na IU.</p>

<p>Inclusos nas interfaces da escuta de evento esto os seguintes mtodos de retorno de chamada:</p>

<dl>
  <dt><code>onClick()</code></dt>
    <dd>De {@link android.view.View.OnClickListener}.
    Isto  chamado quando o usurio toca no item
    (no modo de toque), ou atribui foco ao item com as teclas de navegao ou cursor de bola
    e pressiona a tecla "enter" adequada ou pressiona o cursor de bola.</dd>
  <dt><code>onLongClick()</code></dt>
    <dd>De {@link android.view.View.OnLongClickListener}.
    Isto  chamado quando o usurio toca e mantm o item pressionado (no modo de toque),
 ou atribui foco ao item com as teclas de navegao ou cursor de bola
    e mantm pressionada a tecla "enter" adequada ou o cursor de bola (por um segundo).</dd>
  <dt><code>onFocusChange()</code></dt>
    <dd>De {@link android.view.View.OnFocusChangeListener}.
    Isto  chamado quando o usurio navega no ou do item, usando as teclas de navegao ou cursor de bola.</dd>
  <dt><code>onKey()</code></dt>
    <dd>De {@link android.view.View.OnKeyListener}.
    Isto  chamado quando o usurio est com foco no item ou solta uma tecla de hardware no dispositivo.</dd>
  <dt><code>onTouch()</code></dt>
    <dd>De {@link android.view.View.OnTouchListener}.
    Isto  chamado quando o usurio realiza uma ao qualificada como um toque de evento, incluindo o pressionamento, a liberao,
    ou qualquer outro gesto de movimento na tela (dentro dos limites do item).</dd>
  <dt><code>onCreateContextMenu()</code></dt>
    <dd>De {@link android.view.View.OnCreateContextMenuListener}.
    Isto  chamado quando um menu de contexto est sendo construdo (como resultado de um "clique longo"). Consulte a discusso
    sobre menus de contexto no guia do desenvolvedor <a href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menus</a>
.</dd>
</dl>

<p>Esses mtodos so os nicos habitantes de suas respectivas interfaces. Para definir um desses mtodos
e lidar com seus eventos, implemente a interface aninhada na atividade ou defina-a como uma classe annima.
Em seguida, passe uma instncia da implementao
para o respectivo mtodo <code>View.set...Listener()</code>. (Ex.:, chame
<code>{@link android.view.View#setOnClickListener(View.OnClickListener) setOnClickListener()}</code>
e passe-o  implementao de {@link android.view.View.OnClickListener OnClickListener}.)</p>

<p>O exemplo abaixo mostra como registrar uma escuta de clique para um boto. </p>

<pre>
// Create an anonymous implementation of OnClickListener
private OnClickListener mCorkyListener = new OnClickListener() {
    public void onClick(View v) {
      // do something when the button is clicked
    }
};

protected void onCreate(Bundle savedValues) {
    ...
    // Capture our button from layout
    Button button = (Button)findViewById(R.id.corky);
    // Register the onClick listener with the implementation above
    button.setOnClickListener(mCorkyListener);
    ...
}
</pre>

<p>Voc tambm pode achar mais conveniente implementar OnClickListener como parte da atividade.
Isto evitar carga adicional na classe e a alocao do objeto. Por exemplo:</p>
<pre>
public class ExampleActivity extends Activity implements OnClickListener {
    protected void onCreate(Bundle savedValues) {
        ...
        Button button = (Button)findViewById(R.id.corky);
        button.setOnClickListener(this);
    }

    // Implement the OnClickListener callback
    public void onClick(View v) {
      // do something when the button is clicked
    }
    ...
}
</pre>

<p>Observe que o retorno de chamada <code>onClick()</code> no exemplo acima
no tem valor de retorno, mas outros mtodos de escuta de evento podem retornar um booleano. O motivo
depende do evento. Para os poucos que retornam, apresenta-se a razo:</p>
<ul>
  <li><code>{@link android.view.View.OnLongClickListener#onLongClick(View) onLongClick()}</code> -
    Isto retorna um booleano para indicar se voc consumiu o evento e se ele deve ser levado adiante.
    Ou seja, ele retorna <em>verdadeiro</em> para indicar que voc lidou com o evento e no deve seguir adiante;
    ou retorna <em>falso</em> caso voc no tenha lidado com ele e/ou o evento deva continuar para qualquer
    outra escuta de clique.</li>
  <li><code>{@link android.view.View.OnKeyListener#onKey(View,int,KeyEvent) onKey()}</code> -
    Isto retorna um booleano para indicar se voc consumiu o evento e se ele deve ser levado adiante.
        Ou seja, ele retorna <em>verdadeiro</em> para indicar que voc lidou com o evento e no deve seguir adiante;
    ou retorna <em>falso</em> caso voc no tenha lidado com ele e/ou o evento deva continuar para qualquer
    outra escuta de tecla.</li>
  <li><code>{@link android.view.View.OnTouchListener#onTouch(View,MotionEvent) onTouch()}</code> -
    Isto retorna um booleano para indicar se a escuta consome este evento. O importante  que este evento
    pode possuir vrias aes que se seguem mutuamente. Portanto, se retornar <em>falso</em> quando
    o evento de ao inferior for recebido, voc indicar que no consumiu o evento e que no est
    interessado em aes subsequentes deste evento. Logo, voc no ser chamado para outras aes
    dentro do evento, como um gesto de dedo ou um evento de ao para cima eventual.</li>
</ul>

<p>Lembre-se de que os eventos de tecla de hardware sempre so entregues  vista atualmente em foco. Eles so enviados a partir da parte superior
da hierarquia de vistas e segue  parte inferior at atingir o destino adequado. Se a vista (ou um filho da vista)
estiver em foco,  possvel ver o percurso do evento pelo mtodo <code>{@link android.view.View#dispatchKeyEvent(KeyEvent)
dispatchKeyEvent()}</code>. Como uma alternativa para capturar eventos de tecla por meio da vista, tambm  possvel
receber todos os eventos dentro da Atividade com <code>{@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown()}</code>
e <code>{@link android.app.Activity#onKeyUp(int,KeyEvent) onKeyUp()}</code>.</p>

<p>Alm disso, ao pensar sobre a entrada de texto para o aplicativo, lembre-se de que vrios dispositivos possuem apenas
mtodos de entrada de software. Tais mtodos no precisam ser baseados em teclas; alguns podem usar entrada de texto por voz, por escrita e outros. Mesmo se um mtodo de entrada
apresentar uma interface parecida com teclado, geralmente ele <strong>no</strong> ativa
a famlia de eventos <code>{@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown()}</code>. Nunca deve-se compilar
uma IU que exija pressionamentos de teclas especficas para ser controlada, a no ser que voc queira limitar o aplicativo a dispositivos
com um teclado fsico. Em particular, no confie nestes mtodos para validar a entrada quando o usurio pressiona a tecla
de retorno; em vez disso, use aes como {@link android.view.inputmethod.EditorInfo#IME_ACTION_DONE} para sinalizar
ao mtodo de entrada como o aplicativo espera reagir para que ele possa alterar a IU de forma significativa. Evite suposies
sobre como um mtodo de entrada de software deve funcionar e confie apenas no fornecimento do texto j formatado para o aplicativo.</p>

<p class="note"><strong>Observao:</strong> o Android chamar manipuladores de evento e, em seguida, manipuladores adequados padro
a partir da segunda definio de classe. Logo, retornar <em>verdadeiro</em> destas escutas de evento
interromper a propagao do evento para outras escutas de evento e tambm bloquear o retorno de chamada
para o manipulador de evento padro na vista. Portanto, certifique-se de que quer encerrar o evento ao retornar <em>verdadeiro</em>.</p>


<h2 id="EventHandlers">Manipuladores de evento</h2>

<p>Se estiver compilando um componente personalizado a partir de View, ento voc poder definir vrios mtodos de retorno de chamada
usados como manipuladores de evento padro.
No documento sobre <a href="{@docRoot}guide/topics/ui/custom-components.html">Componentes
personalizados</a>, voc aprender a ver alguns dos retornos de chamada usados para lidar com eventos,
incluindo:</p>
<ul>
  <li><code>{@link  android.view.View#onKeyDown}</code> - Chamado quando um novo evento de tecla ocorre.</li>
  <li><code>{@link  android.view.View#onKeyUp}</code> - Chamado quando um evento de tecla para cima ocorre.</li>
  <li><code>{@link  android.view.View#onTrackballEvent}</code> - Chamado quando um evento de movimento do cursor de bola ocorre.</li>
  <li><code>{@link  android.view.View#onTouchEvent}</code> - Chamado quando um evento de movimento de toque ocorre.</li>
  <li><code>{@link  android.view.View#onFocusChanged}</code> - Chamado quando a vista ganha ou perde foco.</li>
</ul>
<p>H alguns outros mtodos que voc deve ter cincia que no fazem parte da classe View,
mas podem ter impacto direto na maneira de lidar com os eventos. Portanto, ao gerenciar eventos mais complexos
dentro de um layout, considere esses outros mtodos:</p>
<ul>
  <li><code>{@link  android.app.Activity#dispatchTouchEvent(MotionEvent)
    Activity.dispatchTouchEvent(MotionEvent)}</code> - Isto permite que {@link
    android.app.Activity} intercepte todos os evento de toque antes de serem enviados  janela.</li>
  <li><code>{@link  android.view.ViewGroup#onInterceptTouchEvent(MotionEvent)
    ViewGroup.onInterceptTouchEvent(MotionEvent)}</code> - Isto permite que {@link
    android.view.ViewGroup} assista aos eventos  medida que so enviados para as vistas filho.</li>
  <li><code>{@link  android.view.ViewParent#requestDisallowInterceptTouchEvent(boolean)
    ViewParent.requestDisallowInterceptTouchEvent(boolean)}</code> - Chame isto
    sobre uma Vista pai para indicar que ela no deve interceptar eventos de toque com <code>{@link
    android.view.ViewGroup#onInterceptTouchEvent(MotionEvent)}</code>.</li>
</ul>

<h2 id="TouchMode">Modo de toque</h2>
<p>
Quando um usurio est navegando em uma interface do usurio com teclas direcionais ou cursor de bola,
 necessrio fornecer foco para itens de ao (como botes) para que o usurio possa
ver o que aceitar entrada.  Se o dispositivo tiver capacidades de toque, no entanto, e o usurio
comear a interagir com a interface por meio de toque, ento no  mais necessrio
destacar itens ou fornecer foco para uma vista especfica.  Contudo, h um modo
de interao chamado "modo de toque".
</p>
<p>
Para dispositivos com capacidades de toque, quando o usurio toca na tela, o dispositivo
entra no modo de toque.  A partir deste ponto, somente vistas que tiverem
{@link android.view.View#isFocusableInTouchMode} como verdadeiro podero ter foco, como widgets de edio de texto.
Outras vistas tocveis, como botes, no recebero foco ao serem tocadas. Em vez disso,
elas simplesmente dispararo escutas de clique quando forem pressionadas.
</p>
<p>
Sempre que um usurio pressionar teclas direcionais ou rolar com o cursor de bola, o dispositivo
sair do modo de toque e encontrar uma vista para atribuir foco. Agora, o usurio pode retomar a interao
com a interface do usurio sem tocar na tela.
</p>
<p>
O estado de modo de toque  mantido em todo o sistema (todas as janelas e atividades).
Para consultar o estado atual,  possvel chamar
{@link android.view.View#isInTouchMode} para ver se o dispositivo est no modo de toque no momento.
</p>


<h2 id="HandlingFocus">Tratamento de foco</h2>

<p>A estrutura lidar com a rotina de movimento de foco em resposta  entrada do usurio.
Isto inclui a mudana de foco  medida que as vistas so removidas ou ocultadas, ou  medida que novas
vistas se tornem disponveis. As vistas indicam a prontido para receber foco
por meio do mtodo <code>{@link android.view.View#isFocusable()}</code>. Para determinar se uma vista pode receber
foco, chame <code>{@link android.view.View#setFocusable(boolean) setFocusable()}</code>.  Quando no modo de toque,
 possvel consultar se uma vista permite foco com <code>{@link android.view.View#isFocusableInTouchMode()}</code>.
 possvel alterar isto com <code>{@link android.view.View#setFocusableInTouchMode(boolean) setFocusableInTouchMode()}</code>.
</p>

<p>O movimento de foco  baseado em um algoritmo que encontra um semelhante mais prximo
em uma dada direo. Em casos raros, o algoritmo padro pode no corresponder
ao comportamento pretendido do desenvolvedor. Nessas situaes,  possvel
fornecer substituies explcitas com os seguintes atributos XML no arquivo do layout:
<var>nextFocusDown</var>, <var>nextFocusLeft</var>, <var>nextFocusRight</var>e
<var>nextFocusUp</var>. Adicione um desses atributos  vista <em>a partir</em>
do foco que ela est abandonando. Defina o valor do atributo para ser o ID da vista
<em>para</em> o foco que deve ser fornecido. Por exemplo:</p>
<pre>
&lt;LinearLayout
    android:orientation="vertical"
    ... >
  &lt;Button android:id="@+id/top"
          android:nextFocusUp="@+id/bottom"
          ... />
  &lt;Button android:id="@+id/bottom"
          android:nextFocusDown="@+id/top"
          ... />
&lt;/LinearLayout>
</pre>

<p>Geralmente, neste layout vertical, navegar para cima a partir do primeiro boto
no resultaria em nada, nem navegar para baixo a partir do segundo boto. Agora que o boto superior
definiu o boto do fundo como <var>nextFocusUp</var> (e vice-versa), o foco da navegao
alternar de "cima para baixo" e "baixo para cima".</p>

<p>Caso queira declarar uma vista como alvo de foco na IU (quando tradicionalmente no ),
adicione o atributo XML <code>android:focusable</code>  vista, na declarao do layout.
Defina o valor <var>como verdadeiro</var>. Tambm  possvel declarar uma vista
como alvo de foco no Modo de Toque com <code>android:focusableInTouchMode</code>.</p>
<p>Para solicitar foco a uma determinada Vista, chame <code>{@link android.view.View#requestFocus()}</code>.</p>
<p>Para ouvir eventos de foco (receber notificaes quando uma vista receber ou perder foco), use
<code>{@link android.view.View.OnFocusChangeListener#onFocusChange(View,boolean) onFocusChange()}</code>,
como discutido na seo <a href="#EventListeners">Escutas de evento</a> acima.</p>


<!--
<h2 is="EventCycle">Event Cycle</h2>
   <p>The basic cycle of a View is as follows:</p>
   <ol>
    <li>An event comes in and is dispatched to the appropriate View. The View
    handles the event and notifies any listeners.</li>
    <li>If, in the course of processing the event, the View's bounds may need
    to be changed, the View will call {@link android.view.View#requestLayout()}.</li>
    <li>Similarly, if in the course of processing the event the View's appearance
    may need to be changed, the View will call {@link android.view.View#invalidate()}.</li>
    <li>If either {@link android.view.View#requestLayout()} or {@link android.view.View#invalidate()} were called,
    the framework will take care of measuring, laying out, and drawing the tree
    as appropriate.</li>
   </ol>

   <p class="note"><strong>Note:</strong> The entire View tree is single threaded. You must always be on
   the UI thread when calling any method on any View.
   If you are doing work on other threads and want to update the state of a View
   from that thread, you should use a {@link android.os.Handler}.
   </p>
-->