Visão geral da entradaInput Overview

O subsistema de Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) fornece uma API poderosa para obter a entrada de uma variedade de dispositivos, incluindo o mouse, o teclado, o toque e a caneta.The Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) subsystem provides a powerful API for obtaining input from a variety of devices, including the mouse, keyboard, touch, and stylus. Este tópico descreve os serviços fornecidos pelo WPFWPF e explica a arquitetura dos sistemas de entrada.This topic describes the services provided by WPFWPF and explains the architecture of the input systems.

API de entradaInput API

A exposição da API de entrada primária é encontrada nas classes do elemento base: UIElement, ContentElement, FrameworkElemente FrameworkContentElement.The primary input API exposure is found on the base element classes: UIElement, ContentElement, FrameworkElement, and FrameworkContentElement. Para obter mais informações sobre os elementos base, consulte Visão geral de elementos base.For more information about the base elements, see Base Elements Overview. Essas classes fornecem funcionalidade para eventos de entrada relacionados a pressionamentos de tecla, botões do mouse, roda do mouse, movimento do mouse, gerenciamento de foco e captura do mouse, para citar alguns.These classes provide functionality for input events related to key presses, mouse buttons, mouse wheel, mouse movement, focus management, and mouse capture, to name a few. Colocando a API de entrada nos elementos base, em vez de tratar todos os eventos de entrada como um serviço, a arquitetura de entrada permite que os eventos de entrada sejam originados por um objeto específico na interface do usuário e ofereçam suporte a um esquema de roteamento de eventos, no qual mais de um elemento tem um opp ortunity para manipular um evento de entrada.By placing the input API on the base elements, rather than treating all input events as a service, the input architecture enables the input events to be sourced by a particular object in the UI, and to support an event routing scheme whereby more than one element has an opportunity to handle an input event. Muitos eventos de entrada têm um par de eventos associados a eles.Many input events have a pair of events associated with them. Por exemplo, o evento de tecla para baixo está associado aos eventos KeyDown e PreviewKeyDown.For example, the key down event is associated with the KeyDown and PreviewKeyDown events. A diferença nesses eventos está em como eles são roteados para o elemento de destino.The difference in these events is in how they are routed to the target element. Eventos de visualização são roteados por túnel pela árvore de elementos, do elemento raiz ao elemento de destino.Preview events tunnel down the element tree from the root element to the target element. Eventos por propagação propagam-se para cima, do elemento de destino até o elemento raiz.Bubbling events bubble up from the target element to the root element. O roteamento de eventos no WPFWPF é discutido em mais detalhes posteriormente nesta visão geral e na Visão geral de eventos roteados.Event routing in WPFWPF is discussed in more detail later in this overview and in the Routed Events Overview.

Classes de mouse e tecladoKeyboard and Mouse Classes

Além da API de entrada nas classes de elemento base, a classe Keyboard e as classes de Mouse fornecem uma API adicional para trabalhar com entrada de teclado e mouse.In addition to the input API on the base element classes, the Keyboard class and Mouse classes provide additional API for working with keyboard and mouse input.

Exemplos de API de entrada na classe Keyboard são a propriedade Modifiers, que retorna o ModifierKeys atualmente pressionado e o método IsKeyDown, que determina se uma chave especificada é pressionada.Examples of input API on the Keyboard class are the Modifiers property, which returns the ModifierKeys currently pressed, and the IsKeyDown method, which determines whether a specified key is pressed.

O exemplo a seguir usa o método GetKeyStates para determinar se um Key está no estado inoperante.The following example uses the GetKeyStates method to determine if a Key is in the down state.

// Uses the Keyboard.GetKeyStates to determine if a key is down.
// A bitwise AND operation is used in the comparison. 
// e is an instance of KeyEventArgs.
if ((Keyboard.GetKeyStates(Key.Return) & KeyStates.Down) > 0)
{
    btnNone.Background = Brushes.Red;
}
' Uses the Keyboard.GetKeyStates to determine if a key is down.
' A bitwise AND operation is used in the comparison. 
' e is an instance of KeyEventArgs.
If (Keyboard.GetKeyStates(Key.Return) And KeyStates.Down) > 0 Then
    btnNone.Background = Brushes.Red

Os exemplos de API de entrada na classe Mouse são MiddleButton, que obtém o estado do botão do meio do mouse e DirectlyOver, que obtém o elemento no qual o ponteiro do mouse está no momento.Examples of input API on the Mouse class are MiddleButton, which obtains the state of the middle mouse button, and DirectlyOver, which gets the element the mouse pointer is currently over.

O exemplo a seguir determina se a LeftButton do mouse está no estado Pressed.The following example determines whether the LeftButton on the mouse is in the Pressed state.

if (Mouse.LeftButton == MouseButtonState.Pressed)
{
    UpdateSampleResults("Left Button Pressed");
}
If Mouse.LeftButton = MouseButtonState.Pressed Then
    UpdateSampleResults("Left Button Pressed")
End If

As classes Mouse e Keyboard são abordadas em mais detalhes em toda essa visão geral.The Mouse and Keyboard classes are covered in more detail throughout this overview.

Entrada de canetaStylus Input

o WPFWPF tem suporte integrado para o Stylus.WPFWPF has integrated support for the Stylus. A Stylus é uma entrada de caneta que se tornou popular pelo Tablet PC.The Stylus is a pen input made popular by the Tablet PC. WPFWPF aplicativos podem tratar a caneta como um mouse usando a API do mouse, mas WPFWPF também expõe uma abstração de dispositivo de caneta que usa um modelo semelhante ao teclado e ao mouse.applications can treat the stylus as a mouse by using the mouse API, but WPFWPF also exposes a stylus device abstraction that use a model similar to the keyboard and mouse. Todas as APIs relacionadas à caneta contêm a palavra "Stylus".All stylus-related APIs contain the word "Stylus".

Já que a caneta pode atuar como um mouse, aplicativos que dão suporte apenas à entrada de mouse ainda podem obter algum nível de suporte à caneta automaticamente.Because the stylus can act as a mouse, applications that support only mouse input can still obtain some level of stylus support automatically. Quando a caneta é usada desse modo, o aplicativo tem a oportunidade de manipular o evento de caneta apropriado e, em seguida, manipular o evento de mouse correspondente.When the stylus is used in such a manner, the application is given the opportunity to handle the appropriate stylus event and then handles the corresponding mouse event. Além disso, os serviços de alto nível, por exemplo, a entrada de tinta, também estão disponíveis por meio da abstração do dispositivo de caneta.In addition, higher-level services such as ink input are also available through the stylus device abstraction. Para obter mais informações sobre a tinta como entrada, consulte Introdução à tinta.For more information about ink as input, see Getting Started with Ink.

Roteamento de eventosEvent Routing

Um FrameworkElement pode conter outros elementos como elementos filho em seu modelo de conteúdo, formando uma árvore de elementos.A FrameworkElement can contain other elements as child elements in its content model, forming a tree of elements. Em WPFWPF, o elemento pai pode participar de uma entrada direcionada a seus elementos filho ou outros descendentes por meio da manipulação de eventos.In WPFWPF, the parent element can participate in input directed to its child elements or other descendants by handing events. Isso é especialmente útil para a criação de controles com base em controles menores, um processo conhecido como "composição de controle" ou "composição".This is especially useful for building controls out of smaller controls, a process known as "control composition" or "compositing." Para obter mais informações sobre árvores de elementos e como árvores de elementos se relacionam a rotas de evento, consulte Árvores no WPF.For more information about element trees and how element trees relate to event routes, see Trees in WPF.

Roteamento de eventos é o processo de encaminhamento de eventos para vários elementos para que um determinado objeto ou elemento ao longo da rota possa optar por oferecer uma resposta significativa (por meio de manipulação) a um evento que possa ter sido originado de um elemento diferente.Event routing is the process of forwarding events to multiple elements, so that a particular object or element along the route can choose to offer a significant response (through handling) to an event that might have been sourced by a different element. Eventos roteados usam um de três mecanismos de roteamento: direto, por propagação e por túnel.Routed events use one of three routing mechanisms: direct, bubbling, and tunneling. No roteamento direto, o elemento de origem é o único elemento notificado e o evento não será roteado para nenhum outro elemento.In direct routing, the source element is the only element notified, and the event is not routed to any other elements. No entanto, o evento roteado direto ainda oferece alguns recursos adicionais que estão presentes apenas para eventos roteados em vez de eventos CLR padrão.However, the direct routed event still offers some additional capabilities that are only present for routed events as opposed to standard CLR events. O roteamento por propagação ocorre de baixo para cima na árvore de elementos, notificando primeiro o elemento que originou o evento, depois o elemento pai e assim por diante.Bubbling works up the element tree by first notifying the element that sourced the event, then the parent element, and so on. O roteamento por túnel começa na raiz da árvore de elementos prossegue de cima para baixo, terminando com o elemento de origem original.Tunneling starts at the root of the element tree and works down, ending with the original source element. Para obter mais informações sobre os eventos roteados, consulte Visão geral de eventos roteados.For more information about routed events, see Routed Events Overview.

Eventos WPFWPF de entrada geralmente vêm em pares que consistem em um evento por túnel e um evento por propagação.WPFWPF input events generally come in pairs that consists of a tunneling event and a bubbling event. Eventos por túnel são diferenciados dos eventos por propagação com o prefixo "Preview".Tunneling events are distinguished from bubbling events with the "Preview" prefix. Por exemplo, PreviewMouseMove é a versão de túnel de um evento de movimentação do mouse e MouseMove é a versão de bolha desse evento.For instance, PreviewMouseMove is the tunneling version of a mouse move event and MouseMove is the bubbling version of this event. Esse emparelhamento de eventos é uma convenção que é implementada no nível de elemento e não é uma funcionalidade inerente ao sistema de eventos WPFWPF.This event pairing is a convention that is implemented at the element level and is not an inherent capability of the WPFWPF event system. Para obter detalhes, consulte a seção Eventos WPF de entrada em Visão geral de eventos roteados.For details, see the WPF Input Events section in Routed Events Overview.

Manipulação de eventos de entradaHandling Input Events

Para receber a entrada em um elemento, um manipulador de eventos deve estar associado a esse evento específico.To receive input on an element, an event handler must be associated with that particular event. Em XAMLXAML isso é fácil: você referencia o nome do evento como um atributo do elemento que escutará esse evento.In XAMLXAML this is straightforward: you reference the name of the event as an attribute of the element that will be listening for this event. Em seguida, você deverá definir o valor do atributo para o nome do manipulador de eventos que você definir, com base em um delegado.Then, you set the value of the attribute to the name of the event handler that you define, based on a delegate. O manipulador de eventos deve ser escrito em código como C# e pode ser incluído em um arquivo code-behind.The event handler must be written in code such as C# and can be included in a code-behind file.

Eventos de teclado ocorrem quando o sistema operacional relata ações de tecla que ocorrem enquanto o foco do teclado está em um elemento.Keyboard events occur when the operating system reports key actions that occur while keyboard focus is on an element. Tanto eventos de mouse quanto de caneta podem ser divididos em duas categorias: eventos relatam alterações na posição do ponteiro com relação ao elemento e eventos que relatam alterações no estado dos botões do dispositivo.Mouse and stylus events each fall into two categories: events that report changes in pointer position relative to the element, and events that report changes in the state of device buttons.

Exemplo de evento de entrada do tecladoKeyboard Input Event Example

O exemplo a seguir escuta um pressionamento de tecla de seta para a esquerda.The following example listens for a left arrow key press. Um StackPanel é criado com um Button.A StackPanel is created that has a Button. Um manipulador de eventos para escutar o pressionamento da tecla de seta para a esquerda é anexado à instância de Button.An event handler to listen for the left arrow key press is attached to the Button instance.

A primeira seção do exemplo cria o StackPanel e o Button e anexa o manipulador de eventos para o KeyDown.The first section of the example creates the StackPanel and the Button and attaches the event handler for the KeyDown.

<StackPanel>
  <Button Background="AliceBlue"
          KeyDown="OnButtonKeyDown"
          Content="Button1"/>
</StackPanel>
// Create the UI elements.
StackPanel keyboardStackPanel = new StackPanel();
Button keyboardButton1 = new Button();

// Set properties on Buttons.
keyboardButton1.Background = Brushes.AliceBlue;
keyboardButton1.Content = "Button 1";

// Attach Buttons to StackPanel.
keyboardStackPanel.Children.Add(keyboardButton1);

// Attach event handler.
keyboardButton1.KeyDown += new KeyEventHandler(OnButtonKeyDown);
' Create the UI elements.
Dim keyboardStackPanel As New StackPanel()
Dim keyboardButton1 As New Button()

' Set properties on Buttons.
keyboardButton1.Background = Brushes.AliceBlue
keyboardButton1.Content = "Button 1"

' Attach Buttons to StackPanel.
keyboardStackPanel.Children.Add(keyboardButton1)

' Attach event handler.
AddHandler keyboardButton1.KeyDown, AddressOf OnButtonKeyDown

A segunda seção é escrita em código e define o manipulador de eventos.The second section is written in code and defines the event handler. Quando a tecla de seta para a esquerda é pressionada e o Button tem foco no teclado, o manipulador é executado e a cor de Background do Button é alterada.When the left arrow key is pressed and the Button has keyboard focus, the handler runs and the Background color of the Button is changed. Se a tecla for pressionada, mas não for a tecla de seta para a esquerda, a cor Background da Button será alterada de volta para a cor inicial.If the key is pressed, but it is not the left arrow key, the Background color of the Button is changed back to its starting color.

private void OnButtonKeyDown(object sender, KeyEventArgs e)
{
    Button source = e.Source as Button;
    if (source != null)
    {
        if (e.Key == Key.Left)
        {
            source.Background = Brushes.LemonChiffon;
        }
        else
        {
            source.Background = Brushes.AliceBlue;
        }
    }
}
Private Sub OnButtonKeyDown(ByVal sender As Object, ByVal e As KeyEventArgs)
    Dim source As Button = TryCast(e.Source, Button)
    If source IsNot Nothing Then
        If e.Key = Key.Left Then
            source.Background = Brushes.LemonChiffon
        Else
            source.Background = Brushes.AliceBlue
        End If
    End If
End Sub

Exemplo de evento de entrada do mouseMouse Input Event Example

No exemplo a seguir, a cor Background de um Button é alterada quando o ponteiro do mouse entra no Button.In the following example, the Background color of a Button is changed when the mouse pointer enters the Button. A cor Background é restaurada quando o mouse sai do Button.The Background color is restored when the mouse leaves the Button.

A primeira seção do exemplo cria a StackPanel e o controle de Button e anexa os manipuladores de eventos para os eventos MouseEnter e MouseLeave à Button.The first section of the example creates the StackPanel and the Button control and attaches the event handlers for the MouseEnter and MouseLeave events to the Button.

<StackPanel>
  <Button Background="AliceBlue"
          MouseEnter="OnMouseExampleMouseEnter"
          MouseLeave="OnMosueExampleMouseLeave">Button
          
  </Button>
</StackPanel>
// Create the UI elements.
StackPanel mouseMoveStackPanel = new StackPanel();
Button mouseMoveButton = new Button();

// Set properties on Button.
mouseMoveButton.Background = Brushes.AliceBlue;
mouseMoveButton.Content = "Button";

// Attach Buttons to StackPanel.
mouseMoveStackPanel.Children.Add(mouseMoveButton);

// Attach event handler.
mouseMoveButton.MouseEnter += new MouseEventHandler(OnMouseExampleMouseEnter);
mouseMoveButton.MouseLeave += new MouseEventHandler(OnMosueExampleMouseLeave);
' Create the UI elements.
Dim mouseMoveStackPanel As New StackPanel()
Dim mouseMoveButton As New Button()

' Set properties on Button.
mouseMoveButton.Background = Brushes.AliceBlue
mouseMoveButton.Content = "Button"

' Attach Buttons to StackPanel.
mouseMoveStackPanel.Children.Add(mouseMoveButton)

' Attach event handler.
AddHandler mouseMoveButton.MouseEnter, AddressOf OnMouseExampleMouseEnter
AddHandler mouseMoveButton.MouseLeave, AddressOf OnMosueExampleMouseLeave

A segunda seção do exemplo é escrita em código e define os manipuladores de eventos.The second section of the example is written in code and defines the event handlers. Quando o mouse entra na Button, a cor de Background da Button é alterada para SlateGray.When the mouse enters the Button, the Background color of the Button is changed to SlateGray. Quando o mouse sai do Button, a cor Background da Button é alterada para AliceBlue.When the mouse leaves the Button, the Background color of the Button is changed back to AliceBlue.

private void OnMouseExampleMouseEnter(object sender, MouseEventArgs e)
{
    // Cast the source of the event to a Button.
    Button source = e.Source as Button;

    // If source is a Button.
    if (source != null)
    {
        source.Background = Brushes.SlateGray;
    }
}
Private Sub OnMouseExampleMouseEnter(ByVal sender As Object, ByVal e As MouseEventArgs)
    ' Cast the source of the event to a Button.
    Dim source As Button = TryCast(e.Source, Button)

    ' If source is a Button.
    If source IsNot Nothing Then
        source.Background = Brushes.SlateGray
    End If
End Sub
private void OnMosueExampleMouseLeave(object sender, MouseEventArgs e)
{
    // Cast the source of the event to a Button.
    Button source = e.Source as Button;

    // If source is a Button.
    if (source != null)
    {
        source.Background = Brushes.AliceBlue;
    }
}
Private Sub OnMosueExampleMouseLeave(ByVal sender As Object, ByVal e As MouseEventArgs)
    ' Cast the source of the event to a Button.
    Dim source As Button = TryCast(e.Source, Button)

    ' If source is a Button.
    If source IsNot Nothing Then
        source.Background = Brushes.AliceBlue
    End If
End Sub

Entrada de TextoText Input

O evento TextInput permite que você ouça a entrada de texto de maneira independente de dispositivo.The TextInput event enables you to listen for text input in a device-independent manner. O teclado é o método primário de entrada de texto; no entanto, fala, manuscrito e outros dispositivos de entrada também podem gerar entrada de texto.The keyboard is the primary means of text input, but speech, handwriting, and other input devices can generate text input also.

Para entrada de teclado, WPFWPF primeiro envia o KeyDownapropriado /eventos de KeyUp.For keyboard input, WPFWPF first sends the appropriate KeyDown/KeyUp events. Se esses eventos não forem manipulados e a chave for textual (em vez de uma chave de controle, como setas direcionais ou teclas de função), um evento de TextInput será gerado.If those events are not handled and the key is textual (rather than a control key such as directional arrows or function keys), then a TextInput event is raised. Nem sempre há um mapeamento simples de um-para-um entre KeyDown/KeyUp e eventos de TextInput porque vários pressionamentos de teclas podem gerar um único caractere de entrada de texto e pressionamentos de teclas únicos podem gerar cadeias de caracteres com várias aspas.There is not always a simple one-to-one mapping between KeyDown/KeyUp and TextInput events because multiple keystrokes can generate a single character of text input and single keystrokes can generate multi-character strings. Isso é especialmente verdadeiro para linguagens como chinês, japonês e coreano, que usam IMEs (Input Method Editors) para gerar os milhares de caracteres possíveis em seus alfabetos correspondentes.This is especially true for languages such as Chinese, Japanese, and Korean which use Input Method Editors (IMEs) to generate the thousands of possible characters in their corresponding alphabets.

Quando WPFWPF envia um evento de KeyDown de /de KeyUp, Key é definido como Key.System se os pressionamentos de tecla podem se tornar parte de um evento de TextInput (se ALT + S for pressionado, por exemplo).When WPFWPF sends a KeyUp/KeyDown event, Key is set to Key.System if the keystrokes could become part of a TextInput event (if ALT+S is pressed, for example). Isso permite que o código em um manipulador de eventos KeyDown Verifique Key.System e, se encontrado, deixe o processamento do manipulador do evento de TextInput gerado subsequentemente.This allows code in a KeyDown event handler to check for Key.System and, if found, leave processing for the handler of the subsequently raised TextInput event. Nesses casos, as várias propriedades do argumento TextCompositionEventArgs podem ser usadas para determinar os pressionamentos de tecla originais.In these cases, the various properties of the TextCompositionEventArgs argument can be used to determine the original keystrokes. Da mesma forma, se um IME estiver ativo, Key tem o valor de Key.ImeProcessede ImeProcessedKey fornece a tecla ou pressionamentos de teclas originais.Similarly, if an IME is active, Key has the value of Key.ImeProcessed, and ImeProcessedKey gives the original keystroke or keystrokes.

O exemplo a seguir define um manipulador para o evento Click e um manipulador para o evento KeyDown.The following example defines a handler for the Click event and a handler for the KeyDown event.

O primeiro segmento de código ou marcação cria a interface do usuário.The first segment of code or markup creates the user interface.

<StackPanel KeyDown="OnTextInputKeyDown">
  <Button Click="OnTextInputButtonClick"
          Content="Open" />
  <TextBox> . . . </TextBox>
</StackPanel>
// Create the UI elements.
StackPanel textInputStackPanel = new StackPanel();
Button textInputeButton = new Button();
TextBox textInputTextBox = new TextBox();
textInputeButton.Content = "Open";

// Attach elements to StackPanel.
textInputStackPanel.Children.Add(textInputeButton);
textInputStackPanel.Children.Add(textInputTextBox);

// Attach event handlers.
textInputStackPanel.KeyDown += new KeyEventHandler(OnTextInputKeyDown);
textInputeButton.Click += new RoutedEventHandler(OnTextInputButtonClick);
' Create the UI elements.
Dim textInputStackPanel As New StackPanel()
Dim textInputeButton As New Button()
Dim textInputTextBox As New TextBox()
textInputeButton.Content = "Open"

' Attach elements to StackPanel.
textInputStackPanel.Children.Add(textInputeButton)
textInputStackPanel.Children.Add(textInputTextBox)

' Attach event handlers.
AddHandler textInputStackPanel.KeyDown, AddressOf OnTextInputKeyDown
AddHandler textInputeButton.Click, AddressOf OnTextInputButtonClick

O segundo segmento de código contém os manipuladores de eventos.The second segment of code contains the event handlers.

private void OnTextInputKeyDown(object sender, KeyEventArgs e)
{
    if (e.Key == Key.O && Keyboard.Modifiers == ModifierKeys.Control)
    {
        handle();
        e.Handled = true;
    }
}

private void OnTextInputButtonClick(object sender, RoutedEventArgs e)
{
    handle();
    e.Handled = true;
} 

public void handle()
{
    MessageBox.Show("Pretend this opens a file");
}
Private Sub OnTextInputKeyDown(ByVal sender As Object, ByVal e As KeyEventArgs)
    If e.Key = Key.O AndAlso Keyboard.Modifiers = ModifierKeys.Control Then
        handle()
        e.Handled = True
    End If
End Sub

Private Sub OnTextInputButtonClick(ByVal sender As Object, ByVal e As RoutedEventArgs)
    handle()
    e.Handled = True
End Sub

Public Sub handle()
    MessageBox.Show("Pretend this opens a file")
End Sub

Como os eventos de entrada emergim a rota de eventos, o StackPanel recebe a entrada independentemente de qual elemento tem o foco do teclado.Because input events bubble up the event route, the StackPanel receives the input regardless of which element has keyboard focus. O controle de TextBox é notificado primeiro e o manipulador de OnTextInputKeyDown será chamado somente se o TextBox não tratar a entrada.The TextBox control is notified first and the OnTextInputKeyDown handler is called only if the TextBox did not handle the input. Se o evento PreviewKeyDown for usado em vez do evento KeyDown, o manipulador de OnTextInputKeyDown será chamado primeiro.If the PreviewKeyDown event is used instead of the KeyDown event, the OnTextInputKeyDown handler is called first.

Neste exemplo, a lógica de tratamento é gravada duas vezes – uma vez para CTRL + O e novamente para o evento de clique do botão.In this example, the handling logic is written two times—one time for CTRL+O, and again for button's click event. Isso pode ser simplificado usando comandos em vez de manipular os eventos de entrada diretamente.This can be simplified by using commands, instead of handling the input events directly. Comandos são discutidos nesta visão geral e na Visão geral dos comandos.Commands are discussed in this overview and in Commanding Overview.

Toque e manipulaçãoTouch and Manipulation

Novo hardware e a API no sistema operacional Windows 7 fornecem a aplicativos a capacidade de receber entradas de vários toques simultaneamente.New hardware and API in the Windows 7 operating system provide applications the ability to receive input from multiple touches simultaneously. WPFWPF permite que os aplicativos detectem e respondam ao toque de maneira semelhante à que respondem a outras entradas como o mouse ou teclado, acionando eventos quando o toque ocorre.enables applications to detect and respond to touch in a manner similar to responding to other input, such as the mouse or keyboard, by raising events when touch occurs.

WPFWPF expõe dois tipos de eventos quando o toque ocorre: eventos de toque e eventos de manipulação.exposes two types of events when touch occurs: touch events and manipulation events. Eventos de toque fornecem dados brutos sobre cada dedo e seu movimento em uma tela touch.Touch events provide raw data about each finger on a touchscreen and its movement. Eventos de manipulação interpretam a entrada como determinadas ações.Manipulation events interpret the input as certain actions. Ambos os tipos de eventos são discutidos nesta seção.Both types of events are discussed in this section.

{1>{2>Pré-requisitos<2}<1}Prerequisites

Você precisará dos componentes a seguir para desenvolver um aplicativo que responde ao toque.You need the following components to develop an application that responds to touch.

  • Visual Studio 2010.Visual Studio 2010.

  • Windows 7.Windows 7.

  • Um dispositivo, como uma tela touch, que dê suporte a Windows Touch.A device, such as a touchscreen, that supports Windows Touch.

TerminologiaTerminology

Os termos a seguir são usados quando o toque é discutido.The following terms are used when touch is discussed.

  • Toque é um tipo de entrada do usuário que é reconhecida pelo Windows 7.Touch is a type of user input that is recognized by Windows 7. Geralmente o toque é iniciado colocando-se os dedos em uma tela sensível ao toque.Usually, touch is initiated by putting fingers on a touch-sensitive screen. Observe que dispositivos como um touchpad, comuns em computadores laptop, não dão suporte ao toque se o dispositivo simplesmente converte a posição e movimentação do dedo como entrada de mouse.Note that devices such as a touchpad that is common on laptop computers do not support touch if the device merely converts the finger's position and movement as mouse input.

  • Multitoque é toque que ocorre em mais de um ponto, simultaneamente.Multitouch is touch that occurs from more than one point simultaneously. O Windows 7 e o WPFWPF dão suporte a multitoque.Windows 7 and WPFWPF supports multitouch. Sempre que o toque é discutido na documentação do WPFWPF, os conceitos se aplicam para multitoque.Whenever touch is discussed in the documentation for WPFWPF, the concepts apply to multitouch.

  • Uma manipulação ocorre quando o toque é interpretado como uma ação física que é aplicada a um objeto.A manipulation occurs when touch is interpreted as a physical action that is applied to an object. Em WPFWPF, eventos de manipulação interpretam a entrada como uma manipulação de translação, expansão ou rotação.In WPFWPF, manipulation events interpret input as a translation, expansion, or rotation manipulation.

  • Um touch device representa um dispositivo que produz a entrada de toque, por exemplo, um único dedo em uma tela touch.A touch device represents a device that produces touch input, such as a single finger on a touchscreen.

Controles que respondem ao toqueControls that Respond to Touch

É possível rolar pelos controles a seguir arrastando um dedo pelo controle, caso ele tenha conteúdo que está fora da exibição.The following controls can be scrolled by dragging a finger across the control if it has content that is scrolled out of view.

O ScrollViewer define a propriedade ScrollViewer.PanningMode anexada que permite que você especifique se o movimento panorâmico por toque está habilitado horizontalmente, verticalmente, ambos ou nenhum deles.The ScrollViewer defines the ScrollViewer.PanningMode attached property that enables you to specify whether touch panning is enabled horizontally, vertically, both, or neither. A propriedade ScrollViewer.PanningDeceleration especifica a rapidez com que a rolagem diminui quando o usuário levanta o dedo da tela touch.The ScrollViewer.PanningDeceleration property specifies how quickly the scrolling slows down when the user lifts the finger from the touchscreen. A propriedade anexada ScrollViewer.PanningRatio especifica a proporção de deslocamento de rolagem para converter o deslocamento de manipulação.The ScrollViewer.PanningRatio attached property specifies the ratio of scrolling offset to translate manipulation offset.

Eventos de ToqueTouch Events

As classes base, UIElement, UIElement3De ContentElement, definem eventos que você pode assinar para que seu aplicativo responda ao toque.The base classes, UIElement, UIElement3D, and ContentElement, define events that you can subscribe to so your application will respond to touch. Eventos de toque são úteis quando seu aplicativo interpreta toque como algo diferente de manipular um objeto.Touch events are useful when your application interprets touch as something other than manipulating an object. Por exemplo, um aplicativo que permite que um usuário desenhe com um ou mais dedos assinaria eventos de toque.For example, an application that enables a user to draw with one or more fingers would subscribe to touch events.

Todas as três classes definem os eventos a seguir, que se comportam da mesma forma independentemente da classe que os define.All three classes define the following events, which behave similarly, regardless of the defining class.

Assim como os eventos de teclado e mouse, os eventos de toque são eventos roteados.Like keyboard and mouse events, the touch events are routed events. Os eventos que começam com Preview são eventos por túnel e os eventos que começam com Touch são eventos por propagação.The events that begin with Preview are tunneling events and the events that begin with Touch are bubbling events. Para obter mais informações sobre os eventos roteados, consulte Visão geral de eventos roteados.For more information about routed events, see Routed Events Overview. Ao lidar com esses eventos, você pode obter a posição da entrada, em relação a qualquer elemento, chamando o método GetTouchPoint ou GetIntermediateTouchPoints.When you handle these events, you can get the position of the input, relative to any element, by calling the GetTouchPoint or GetIntermediateTouchPoints method.

Para compreender a interação entre os eventos de toque, considere o cenário em que um usuário coloca um dedo em um elemento, move o dedo pelo elemento e, em seguida, levanta o dedo do elemento.To understand the interaction among the touch events, consider the scenario where a user puts one finger on an element, moves the finger in the element, and then lifts the finger from the element. A ilustração a seguir mostra a execução dos eventos por propagação (os eventos por túnel são omitidos por questão de simplicidade).The following illustration shows the execution of the bubbling events (the tunneling events are omitted for simplicity).

A sequência de eventos de toque. Eventos de toqueThe sequence of touch events. Touch events

A lista a seguir descreve a sequência de eventos na ilustração anterior.The following list describes the sequence of the events in the preceding illustration.

  1. O evento TouchEnter ocorre uma vez quando o usuário coloca um dedo no elemento.The TouchEnter event occurs one time when the user puts a finger on the element.

  2. O evento TouchDown ocorre uma vez.The TouchDown event occurs one time.

  3. O evento TouchMove ocorre várias vezes quando o usuário move o dedo dentro do elemento.The TouchMove event occurs multiple times as the user moves the finger within the element.

  4. O evento TouchUp ocorre uma vez quando o usuário levanta o dedo do elemento.The TouchUp event occurs one time when the user lifts the finger from the element.

  5. O evento TouchLeave ocorre uma vez.The TouchLeave event occurs one time.

Quando mais de dois dedos são usados, os eventos ocorrem para cada dedo.When more than two fingers are used, the events occur for each finger.

Eventos de ManipulaçãoManipulation Events

Para casos em que um aplicativo permite que um usuário manipule um objeto, a classe UIElement define eventos de manipulação.For cases where an application enables a user to manipulate an object, the UIElement class defines manipulation events. Diferentemente de eventos de toque que simplesmente relatam a posição do toque, os eventos de manipulação relatam como a entrada pode ser interpretada.Unlike the touch events that simply report the position of touch, the manipulation events report how the input can be interpreted. Há três tipos de manipulação: rotação, translação e expansão.There are three types of manipulations, translation, expansion, and rotation. A lista a seguir descreve como invocar os três tipos de manipulação.The following list describes how to invoke the three types of manipulations.

  • Coloque um dedo em um objeto e mova o dedo na tela touch para invocar uma manipulação de translação.Put a finger on an object and move the finger across the touchscreen to invoke a translation manipulation. Geralmente, isso move o objeto.This usually moves the object.

  • Coloque dois dedos em um objeto e mova os dedos mais próximos ou mais distantes um do outro para invocar uma manipulação de expansão.Put two fingers on an object and move the fingers closer together or farther apart from one another to invoke an expansion manipulation. Isso geralmente redimensiona o objeto.This usually resizes the object.

  • Coloque dois dedos em um objeto e gire os dedos em torno um do outro para invocar uma manipulação de rotação.Put two fingers on an object and rotate the fingers around each other to invoke a rotation manipulation. Isso geralmente gira o objeto.This usually rotates the object.

É possível que mais de um tipo de manipulação ocorram simultaneamente.More than one type of manipulation can occur simultaneously.

Quando você faz com que objetos respondam a manipulações, você pode fazer com que o objeto pareça ter inércia.When you cause objects to respond to manipulations, you can have the object appear to have inertia. Isso pode fazer com que seus objetos simulem o mundo físico.This can make your objects simulate the physical world. Por exemplo, quando você empurra um livro por uma mesa, o livro continua a mover-se depois de você liberá-lo, caso você o empurre com força suficiente.For example, when you push a book across a table, if you push hard enough the book will continue to move after you release it. WPFWPF permite simular esse comportamento, acionando eventos de manipulação após os dedos do usuário liberarem o objeto.enables you to simulate this behavior by raising manipulation events after the user's fingers releases the object.

Para obter informações sobre como criar um aplicativo que permite que o usuário mova, redimensione e gire um objeto, consulte Passo a passo: criar seu primeiro aplicativo de toque.For information about how to create an application that enables the user to move, resize, and rotate an object, see Walkthrough: Creating Your First Touch Application.

O UIElement define os eventos de manipulação a seguir.The UIElement defines the following manipulation events.

Por padrão, um UIElement não recebe esses eventos de manipulação.By default, a UIElement does not receive these manipulation events. Para receber eventos de manipulação em um UIElement, defina UIElement.IsManipulationEnabled como true.To receive manipulation events on a UIElement, set UIElement.IsManipulationEnabled to true.

O caminho de execução de eventos de manipulaçãoThe Execution Path of Manipulation Events

Considere um cenário em que um usuário "lança" um objeto.Consider a scenario where a user "throws" an object. O usuário coloca um dedo no objeto, move o dedo pela tela touch por uma distância curta e, em seguida, levanta o dedo enquanto ele está se movendo.The user puts a finger on the object, moves the finger across the touchscreen for a short distance, and then lifts the finger while it is moving. O resultado disso é que o objeto se moverá sob o dedo do usuário e continuará a mover-se depois que o usuário levantar o dedo.The result of this is that the object will move under the user's finger and continue to move after the user lifts the finger.

A ilustração a seguir mostra o caminho de execução de eventos de manipulação e informações importantes sobre cada evento.The following illustration shows the execution path of manipulation events and important information about each event.

A sequência de eventos de manipulação. Eventos de manipulaçãoThe sequence of manipulation events. Manipulation events

A lista a seguir descreve a sequência de eventos na ilustração anterior.The following list describes the sequence of the events in the preceding illustration.

  1. O evento ManipulationStarting ocorre quando o usuário coloca um dedo no objeto.The ManipulationStarting event occurs when the user places a finger on the object. Entre outras coisas, esse evento permite que você defina a propriedade ManipulationContainer.Among other things, this event allows you to set the ManipulationContainer property. Nos eventos subsequentes, a posição da manipulação será relativa à ManipulationContainer.In the subsequent events, the position of the manipulation will be relative to the ManipulationContainer. Em eventos diferentes de ManipulationStarting, essa propriedade é somente leitura, portanto, o evento de ManipulationStarting é a única vez que você pode definir essa propriedade.In events other than ManipulationStarting, this property is read-only, so the ManipulationStarting event is the only time that you can set this property.

  2. O evento ManipulationStarted ocorre em seguida.The ManipulationStarted event occurs next. Esse evento relata a origem da manipulação.This event reports the origin of the manipulation.

  3. O evento ManipulationDelta ocorre várias vezes enquanto os dedos de um usuário se movem em uma tela de toque.The ManipulationDelta event occurs multiple times as a user's fingers move on a touchscreen. A propriedade DeltaManipulation da classe ManipulationDeltaEventArgs relata se a manipulação é interpretada como movimento, expansão ou tradução.The DeltaManipulation property of the ManipulationDeltaEventArgs class reports whether the manipulation is interpreted as movement, expansion, or translation. É aqui que você realiza a maior parte do trabalho envolvido na manipulação de um objeto.This is where you perform most of the work of manipulating an object.

  4. O evento ManipulationInertiaStarting ocorre quando os dedos do usuário perdem contato com o objeto.The ManipulationInertiaStarting event occurs when the user's fingers lose contact with the object. Esse evento permite que você especifique a desaceleração das manipulações durante a inércia.This event enables you to specify the deceleration of the manipulations during inertia. Isso é para que seu objeto possa emular espaços físicos ou atributos diferentes, se você assim escolher.This is so your object can emulate different physical spaces or attributes if you choose. Por exemplo, suponha que seu aplicativo tem dois objetos que representam itens no mundo físico e um deles é mais pesado que o outro.For example, suppose your application has two objects that represent items in the physical world, and one is heavier than the other. Você pode fazer com que o objeto mais pesado desacelere mais rápido do que o objeto mais leve.You can make the heavier object decelerate faster than the lighter object.

  5. O evento ManipulationDelta ocorre várias vezes, uma vez que inércia ocorre.The ManipulationDelta event occurs multiple times as inertia occurs. Observe que este evento ocorre quando os dedos do usuário se movem pela tela touch e quando WPFWPF simula inércia.Note that this event occurs when the user's fingers move across the touchscreen and when WPFWPF simulates inertia. Em outras palavras, ManipulationDelta ocorre antes e depois do evento ManipulationInertiaStarting.In other words, ManipulationDelta occurs before and after the ManipulationInertiaStarting event. A propriedade ManipulationDeltaEventArgs.IsInertial relata se o evento de ManipulationDelta ocorre durante inércia, para que você possa verificar essa propriedade e executar ações diferentes, dependendo de seu valor.The ManipulationDeltaEventArgs.IsInertial property reports whether the ManipulationDelta event occurs during inertia, so you can check that property and perform different actions, depending on its value.

  6. O evento ManipulationCompleted ocorre quando a manipulação e qualquer inércia termina.The ManipulationCompleted event occurs when the manipulation and any inertia ends. Ou seja, depois que todos os eventos de ManipulationDelta ocorrerem, o evento ManipulationCompleted ocorrerá para sinalizar que a manipulação foi concluída.That is, after all the ManipulationDelta events occur, the ManipulationCompleted event occurs to signal that the manipulation is complete.

O UIElement também define o evento ManipulationBoundaryFeedback.The UIElement also defines the ManipulationBoundaryFeedback event. Esse evento ocorre quando o método ReportBoundaryFeedback é chamado no evento ManipulationDelta.This event occurs when the ReportBoundaryFeedback method is called in the ManipulationDelta event. O evento ManipulationBoundaryFeedback permite que aplicativos ou componentes forneçam comentários visuais quando um objeto atinge um limite.The ManipulationBoundaryFeedback event enables applications or components to provide visual feedback when an object hits a boundary. Por exemplo, a classe Window manipula o evento ManipulationBoundaryFeedback para fazer com que a janela se mova ligeiramente quando sua borda for encontrada.For example, the Window class handles the ManipulationBoundaryFeedback event to cause the window to slightly move when its edge is encountered.

Você pode cancelar a manipulação chamando o método Cancel nos argumentos do evento em qualquer evento de manipulação, exceto ManipulationBoundaryFeedback evento.You can cancel the manipulation by calling the Cancel method on the event arguments in any manipulation event except ManipulationBoundaryFeedback event. Quando você chama Cancel, os eventos de manipulação não são mais gerados e eventos de mouse ocorrem para toque.When you call Cancel, the manipulation events are no longer raised and mouse events occur for touch. A tabela a seguir descreve a relação entre a hora em que a manipulação é cancelada e os eventos de mouse que ocorrem.The following table describes the relationship between the time the manipulation is canceled and the mouse events that occur.

O evento no qual Cancel é chamadoThe event that Cancel is called in Os eventos de mouse que ocorrem para entrada e que já ocorreramThe mouse events that occur for input that already occurred
ManipulationStarting e ManipulationStartedManipulationStarting and ManipulationStarted Eventos de pressionamento do mouse.Mouse down events.
ManipulationDelta Eventos de pressionamento do mouse e eventos de movimentação do mouse.Mouse down and mouse move events.
ManipulationInertiaStarting e ManipulationCompletedManipulationInertiaStarting and ManipulationCompleted Pressionamento do mouse, movimentação do mouse e liberação do mouse.Mouse down, mouse move, and mouse up events.

Observe que se você chamar Cancel quando a manipulação estiver em inércia, o método retornará false e a entrada não gerará eventos do mouse.Note that if you call Cancel when the manipulation is in inertia, the method returns false and the input does not raise mouse events.

A relação entre eventos de toque e eventos de manipulaçãoThe Relationship Between Touch and Manipulation Events

Uma UIElement sempre pode receber eventos de toque.A UIElement can always receive touch events. Quando a propriedade IsManipulationEnabled é definida como true, uma UIElement pode receber eventos de toque e manipulação.When the IsManipulationEnabled property is set to true, a UIElement can receive both touch and manipulation events. Se o evento TouchDown não for tratado (ou seja, a propriedade Handled for false), a lógica de manipulação capturará o toque para o elemento e gerará os eventos de manipulação.If the TouchDown event is not handled (that is, the Handled property is false), the manipulation logic captures the touch to the element and generates the manipulation events. Se a propriedade Handled for definida como true no evento TouchDown, a lógica de manipulação não gerará eventos de manipulação.If the Handled property is set to true in the TouchDown event, the manipulation logic does not generate manipulation events. A ilustração a seguir mostra a relação entre os eventos de toque e os eventos de manipulação.The following illustration shows the relationship between touch events and manipulation events.

Relação entre eventos de toque e manipulação eventos de manipulação e toqueRelationship between touch and manipulation events Touch and manipulation events

A lista a seguir descreve a relação entre os eventos de toque e de manipulação que é mostrada na ilustração anterior.The following list describes the relationship between the touch and manipulation events that is shown in the preceding illustration.

FocoFocus

Há dois conceitos principais relativos ao foco em WPFWPF: foco do teclado e foco lógico.There are two main concepts that pertain to focus in WPFWPF: keyboard focus and logical focus.

Foco do tecladoKeyboard Focus

O foco do teclado refere-se ao elemento que está recebendo entrada do teclado.Keyboard focus refers to the element that is receiving keyboard input. Em toda a área de trabalho, pode haver apenas um elemento que tem o foco do teclado.There can be only one element on the whole desktop that has keyboard focus. No WPFWPF, o elemento que tem o foco do teclado terá IsKeyboardFocused definido como true.In WPFWPF, the element that has keyboard focus will have IsKeyboardFocused set to true. O método de Keyboard estático FocusedElement retorna o elemento que atualmente tem o foco do teclado.The static Keyboard method FocusedElement returns the element that currently has keyboard focus.

O foco do teclado pode ser obtido por tabulação para um elemento ou clicando com o mouse em determinados elementos, como um TextBox.Keyboard focus can be obtained by tabbing to an element or by clicking the mouse on certain elements, such as a TextBox. O foco do teclado também pode ser obtido programaticamente usando o método Focus na classe Keyboard.Keyboard focus can also be obtained programmatically by using the Focus method on the Keyboard class. Focus tenta dar o foco do teclado do elemento especificado.Focus attempts to give the specified element keyboard focus. O elemento retornado por Focus é o elemento que atualmente tem o foco do teclado.The element returned by Focus is the element that currently has keyboard focus.

Para que um elemento obtenha o foco do teclado, a propriedade Focusable e as propriedades de IsVisible devem ser definidas como true.In order for an element to obtain keyboard focus the Focusable property and the IsVisible properties must be set to true. Algumas classes, como Panel, têm Focusable definido como false por padrão; Portanto, talvez seja necessário definir essa propriedade como true se você quiser que esse elemento seja capaz de obter o foco.Some classes, such as Panel, have Focusable set to false by default; therefore, you may have to set this property to true if you want that element to be able to obtain focus.

O exemplo a seguir usa Focus para definir o foco do teclado em um Button.The following example uses Focus to set keyboard focus on a Button. O local recomendado para definir o foco inicial em um aplicativo está no manipulador de eventos Loaded.The recommended place to set initial focus in an application is in the Loaded event handler.

private void OnLoaded(object sender, RoutedEventArgs e)
{
    // Sets keyboard focus on the first Button in the sample.
    Keyboard.Focus(firstButton);
}
Private Sub OnLoaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
    ' Sets keyboard focus on the first Button in the sample.
    Keyboard.Focus(firstButton)
End Sub

Para obter mais informações sobre o foco do teclado, consulte Visão geral do foco.For more information about keyboard focus, see Focus Overview.

Foco lógicoLogical Focus

Foco lógico refere-se à FocusManager.FocusedElement em um escopo de foco.Logical focus refers to the FocusManager.FocusedElement in a focus scope. Pode haver vários elementos que têm foco lógico em um aplicativo, mas pode haver apenas um elemento com foco lógico em um escopo de foco específico.There can be multiple elements that have logical focus in an application, but there may only be one element that has logical focus in a particular focus scope.

Um escopo de foco é um elemento de contêiner que controla o FocusedElement dentro de seu escopo.A focus scope is a container element that keeps track of the FocusedElement within its scope. Quando o foco deixar um escopo de foco, o elemento com foco perderá o foco do teclado mas manterá o foco lógico.When focus leaves a focus scope, the focused element will lose keyboard focus but will retain logical focus. Quando o foco retornar para o escopo de foco, o elemento com foco obterá o foco do teclado.When focus returns to the focus scope, the focused element will obtain keyboard focus. Isso permite que o foco do teclado seja alterado entre vários escopos de foco, mas assegura que o elemento com foco dentro do escopo de foco permanecerá sendo o elemento com foco quando o foco retornar.This allows for keyboard focus to be changed between multiple focus scopes but insures that the focused element within the focus scope remains the focused element when focus returns.

Um elemento pode ser transformado em um escopo de foco em XAML (linguagem XAML)Extensible Application Markup Language (XAML) definindo a propriedade anexada FocusManager IsFocusScope como trueou no código, definindo a propriedade anexada usando o método SetIsFocusScope.An element can be turned into a focus scope in XAML (linguagem XAML)Extensible Application Markup Language (XAML) by setting the FocusManager attached property IsFocusScope to true, or in code by setting the attached property by using the SetIsFocusScope method.

O exemplo a seguir torna um StackPanel em um escopo de foco definindo a propriedade IsFocusScope anexada.The following example makes a StackPanel into a focus scope by setting the IsFocusScope attached property.

<StackPanel Name="focusScope1" 
            FocusManager.IsFocusScope="True"
            Height="200" Width="200">
  <Button Name="button1" Height="50" Width="50"/>
  <Button Name="button2" Height="50" Width="50"/>
</StackPanel>
StackPanel focuseScope2 = new StackPanel();
FocusManager.SetIsFocusScope(focuseScope2, true);
Dim focuseScope2 As New StackPanel()
FocusManager.SetIsFocusScope(focuseScope2, True)

As classes em WPFWPF que são escopos de foco por padrão são Window, Menu, ToolBare ContextMenu.Classes in WPFWPF which are focus scopes by default are Window, Menu, ToolBar, and ContextMenu.

Um elemento que tem o foco do teclado também terá foco lógico para o escopo de foco ao qual ele pertence; Portanto, definir o foco em um elemento com o método Focus na classe Keyboard ou nas classes do elemento base tentará dar o foco do teclado do elemento e o foco lógico.An element that has keyboard focus will also have logical focus for the focus scope it belongs to; therefore, setting focus on an element with the Focus method on the Keyboard class or the base element classes will attempt to give the element keyboard focus and logical focus.

Para determinar o elemento focalizado em um escopo de foco, use GetFocusedElement.To determine the focused element in a focus scope, use GetFocusedElement. Para alterar o elemento focalizado para um escopo de foco, use SetFocusedElement.To change the focused element for a focus scope, use SetFocusedElement.

Para obter mais informações sobre o foco lógico, consulte Visão geral do foco.For more information about logical focus, see Focus Overview.

Posição do mouseMouse Position

A API de entrada do WPFWPF fornece informações úteis em relação a espaços de coordenadas.The WPFWPF input API provides helpful information with regard to coordinate spaces. Por exemplo, a coordenada (0,0) é a coordenada superior esquerda, mas trata-se do canto superior esquerdo de qual elemento na árvore?For example, coordinate (0,0) is the upper-left coordinate, but the upper-left of which element in the tree? O elemento que é o destino de entrada?The element that is the input target? O elemento ao qual você anexou o manipulador de eventos?The element you attached your event handler to? Ou alguma outra coisa?Or something else? Para evitar confusão, a API de entrada WPFWPF requer que você especifique o quadro de referência ao trabalhar com coordenadas obtidas pelo mouse.To avoid confusion, the WPFWPF input API requires that you specify your frame of reference when you work with coordinates obtained through the mouse. O método GetPosition retorna a coordenada do ponteiro do mouse em relação ao elemento especificado.The GetPosition method returns the coordinate of the mouse pointer relative to the specified element.

Captura do mouseMouse Capture

Dispositivos de mouse mantêm especificamente uma característica modal conhecida como captura do mouse.Mouse devices specifically hold a modal characteristic known as mouse capture. A captura do mouse é usada para manter um estado de entrada de transição quando uma operação do tipo "arrastar e soltar" é iniciada, de modo que outras operações que envolvem a posição nominal do ponteiro do mouse na tela não necessariamente ocorrem.Mouse capture is used to maintain a transitional input state when a drag-and-drop operation is started, so that other operations involving the nominal on-screen position of the mouse pointer do not necessarily occur. Durante a ação de arrastar, o usuário não poderá clicar sem anular a ação do tipo "arrastar e soltar", o que torna a maioria das indicações mouseover inadequadas; enquanto isso, a captura do mouse é mantida pela origem da ação de arrastar.During the drag, the user cannot click without aborting the drag-and-drop, which makes most mouseover cues inappropriate while the mouse capture is held by the drag origin. O sistema de entrada expõe APIs que podem determinar o estado de captura do mouse, bem como APIs que podem forçar a captura do mouse para um elemento específico ou limpar o estado de captura do mouse.The input system exposes APIs that can determine mouse capture state, as well as APIs that can force mouse capture to a specific element, or clear mouse capture state. Para obter mais informações sobre operações do tipo "arrastar e soltar", consulte Visão geral de arrastar e soltar.For more information on drag-and-drop operations, see Drag and Drop Overview.

CommandsCommands

Os comandos permitem a manipulação de entrada em um nível mais semântico que a entrada do dispositivo.Commands enable input handling at a more semantic level than device input. Os comandos são diretivas simples, como Cut, Copy, Paste ou Open.Commands are simple directives, such as Cut, Copy, Paste, or Open. Os comandos são úteis para centralizar sua lógica de comando.Commands are useful for centralizing your command logic. O mesmo comando pode ser acessado de um Menu, em um ToolBarou por meio de um atalho de teclado.The same command might be accessed from a Menu, on a ToolBar, or through a keyboard shortcut. Os comandos também fornecem um mecanismo para desabilitar os controles quando o comando se torna não disponível.Commands also provide a mechanism for disabling controls when the command becomes unavailable.

RoutedCommand é a implementação WPFWPF do ICommand.RoutedCommand is the WPFWPF implementation of ICommand. Quando um RoutedCommand é executado, um PreviewExecuted e um evento Executed são gerados no destino do comando, que faz o túnel e a bolha através da árvore de elementos, como outras entradas.When a RoutedCommand is executed, a PreviewExecuted and an Executed event are raised on the command target, which tunnel and bubble through the element tree like other input. Se um destino do comando não for definido, o elemento com o foco do teclado será o destino do comando.If a command target is not set, the element with keyboard focus will be the command target. A lógica que executa o comando é anexada a um CommandBinding.The logic that performs the command is attached to a CommandBinding. Quando um evento de Executed atinge uma CommandBinding para esse comando específico, a ExecutedRoutedEventHandler no CommandBinding é chamada.When an Executed event reaches a CommandBinding for that specific command, the ExecutedRoutedEventHandler on the CommandBinding is called. Esse manipulador executa a ação do comando.This handler performs the action of the command.

Para obter mais informações sobre comandos, consulte Visão geral dos comandos.For more information on commanding, see Commanding Overview.

WPFWPF fornece uma biblioteca de comandos comuns que consistem em ApplicationCommands, MediaCommands, ComponentCommands, NavigationCommandse EditingCommands, ou você pode definir seus próprios.provides a library of common commands which consists of ApplicationCommands, MediaCommands, ComponentCommands, NavigationCommands, and EditingCommands, or you can define your own.

O exemplo a seguir mostra como configurar um MenuItem para que, quando ele for clicado, ele invocará o comando Paste no TextBox, supondo que o TextBox tenha o foco do teclado.The following example shows how to set up a MenuItem so that when it is clicked it will invoke the Paste command on the TextBox, assuming the TextBox has keyboard focus.

<StackPanel>
  <Menu>
    <MenuItem Command="ApplicationCommands.Paste" />
  </Menu>
  <TextBox />
</StackPanel>
  // Creating the UI objects
  StackPanel mainStackPanel = new StackPanel();
  TextBox pasteTextBox = new TextBox();
  Menu stackPanelMenu = new Menu();
  MenuItem pasteMenuItem = new MenuItem();
 
  // Adding objects to the panel and the menu
  stackPanelMenu.Items.Add(pasteMenuItem);
  mainStackPanel.Children.Add(stackPanelMenu);
  mainStackPanel.Children.Add(pasteTextBox);

  // Setting the command to the Paste command
  pasteMenuItem.Command = ApplicationCommands.Paste;

  // Setting the command target to the TextBox
  pasteMenuItem.CommandTarget = pasteTextBox;
' Creating the UI objects
Dim mainStackPanel As New StackPanel()
Dim pasteTextBox As New TextBox()
Dim stackPanelMenu As New Menu()
Dim pasteMenuItem As New MenuItem()

' Adding objects to the panel and the menu
stackPanelMenu.Items.Add(pasteMenuItem)
mainStackPanel.Children.Add(stackPanelMenu)
mainStackPanel.Children.Add(pasteTextBox)

' Setting the command to the Paste command
pasteMenuItem.Command = ApplicationCommands.Paste

Para obter mais informações sobre comandos em WPFWPF, consulte Visão geral dos comandos.For more information about commands in WPFWPF, see Commanding Overview.

O sistema de entrada e elementos baseThe Input System and Base Elements

Eventos de entrada, como os eventos anexados definidos pelas classes Mouse, Keyboarde Stylus são gerados pelo sistema de entrada e injetados em uma determinada posição no modelo de objeto com base em testes de clique na árvore visual em tempo de execução.Input events such as the attached events defined by the Mouse, Keyboard, and Stylus classes are raised by the input system and injected into a particular position in the object model based on hit testing the visual tree at run time.

Cada um dos eventos que Mouse, Keyboarde Stylus definir como um evento anexado também é exposto novamente pelas classes de elemento base UIElement e ContentElement como um novo evento roteado.Each of the events that Mouse, Keyboard, and Stylus define as an attached event is also re-exposed by the base element classes UIElement and ContentElement as a new routed event. Os eventos roteados de elemento base são gerados por classes que manipulam o evento anexado original e reutilizam os dados do evento.The base element routed events are generated by classes handling the original attached event and reusing the event data.

Quando o evento de entrada passa a ser associado a um elemento de origem específico por meio da implementação de evento de entrada do seu elemento base, ele pode ser roteado pelo restante de uma rota de evento baseada em uma combinação de objetos de árvore visual e lógicos e pode também ser manipulado pelo código do aplicativo.When the input event becomes associated with a particular source element through its base element input event implementation, it can be routed through the remainder of an event route that is based on a combination of logical and visual tree objects, and be handled by application code. Em geral, é mais conveniente lidar com esses eventos de entrada relacionados ao dispositivo usando os eventos roteados em UIElement e ContentElement, pois você pode usar uma sintaxe de manipulador de eventos mais intuitiva no XAMLXAML e no código.Generally, it is more convenient to handle these device-related input events using the routed events on UIElement and ContentElement, because you can use more intuitive event handler syntax both in XAMLXAML and in code. Em vez disso, você poderia optar por manipular o evento anexado que iniciou o processo, no entanto, você enfrentaria diversos problemas: o evento anexado poderia ser marcado como manipulado pela manipulação de classe do elemento base e, em vez da verdadeira sintaxe de evento, você precisaria usar os métodos acessadores para anexar manipuladores para eventos anexados.You could choose to handle the attached event that initiated the process instead, but you would face several issues: the attached event may be marked handled by the base element class handling, and you need to use accessor methods rather than true event syntax in order to attach handlers for attached events.

O que vem a seguirWhat's Next

Agora você tem várias técnicas para manipular a entrada em WPFWPF.You now have several techniques to handle input in WPFWPF. Você também deve ter uma compreensão melhor dos vários tipos de eventos de entrada e os mecanismos de evento roteado usados pelo WPFWPF.You should also have an improved understanding of the various types of input events and the routed event mechanisms used by WPFWPF.

Há recursos adicionais disponíveis que explicam roteamento de eventos e elementos estruturais do WPFWPF em mais detalhes.Additional resources are available that explain WPFWPF framework elements and event routing in more detail. Consulte as visões gerais a seguir para obter mais informações: Visão geral de comandos, Visão geral do foco, Visão geral de elementos base, Árvores no WPF e Visão geral de eventos roteados.See the following overviews for more information, Commanding Overview, Focus Overview, Base Elements Overview, Trees in WPF, and Routed Events Overview.

Consulte tambémSee also